Skip to content

feat: add __kosh.page and list published pages in the inventory - #90

Merged
katodea merged 5 commits into
trunkfrom
update/model-page-code
Nov 5, 2026
Merged

katodea merged 5 commits into
trunkfrom
update/model-page-code

Conversation

@katodea

@katodea katodea commented Nov 4, 2026 •

Copy link
Copy Markdown
Collaborator

what

  • collectors/kosh.js
    • new __kosh.page(): scrolls the page so lazy content loads, then returns images, contrast, headings, text (what main shows, cut at 8,000 characters), clipped and overflow in one call
    • contrast rows with the same measurement are grouped, with a count
    • text on a gradient gets a ratioRange worked out from the gradient's stops, over axe's own background stack
    • textColor keeps its transparency (#ffffff at 30%), for placeholders and gradient text
  • collectors/capture.js loads axe for __kosh.page as well as __kosh.contrast
  • scripts/page-capture.js inventory
    • prints published first: the site's published pages the run hasn't loaded or seen a link to, read from Node through ?rest_route=, then ?sitemap=, so it works on plain permalinks and in a subdirectory
    • keeps only http(s) URLs on the site's host, refuses an answer that redirected off it, and returns error instead of an empty list when it can't tell
    • only asks a host the run's browser has loaded
    • prints one line per page and per link, with null share tags collapsed into missingMeta
  • skills/functional-design/SKILL.md
    • each page runs __kosh.page() in place of the scroll loop, __kosh.images() and __kosh.contrast()
    • read text for spelling and grammar
    • don't work out contrast by hand
    • menus never prove a site has nothing else, so read published
  • evals/tests/functional-design.yaml: new cases for gradient ranges, placeholders, icon glyphs, text and published
  • AGENTS.md: __kosh.page loading axe, and how published reads the site
  • tests for all of the above in tests/collectors.test.js and tests/page-capture.test.js

why

the functional-design after runs wrote about as much page code as before the rewrite. it was ~33K characters of browser_evaluate a run, much of it the same each page: scroll loops (16–31 a run), main-text reads and hand-written contrast math (16 calls across six runs), which is how wrong ratios get into reports.

three rounds of runs on a staging site, Opus 5 at xhigh:

  • page() alone halved the code (33.5K → 17.5K mean) and took the contrast math to zero, but the contact page's sentence fragment went from 5/6 to 3/6. the misses never had that sentence in any tool result, so text went into page().
  • with text, the fragment came back 3/3 and code fell further (17.0K → 10.4K). then a published test page with broken gallery images, a high in every earlier run, went from 6/6 to 0/3. Opus 5 had only ever found it through the REST API, and two reports said the menu was the whole site.
  • with published and the skill sentence, the page is back 3/3. all three runs found it with their own REST call before reading inventory, so published is a backstop that no run has needed yet. code 13.9K, output tokens 57K, HTML 23 MB, pages 9.7 (mean). the placeholder is reported at 2.54:1, measured, in every run.

the inventory change came from the first of those runs: it read the pretty-printed output with head -200 and tail, so the middle pages' rows were never read. a one-line-per-row inventory of the same run is 55 lines rather than 685, and both later runs read it whole.

notes

  • published is only shown to the model, so a run that ignores notReached leaves no trace in the report. not built since no run ignored it.
  • the ?rest_route= and ?sitemap= routes were checked on a live site with pretty permalinks and against WordPress core's source. plain permalinks and subdirectory installs were only tested against a stub server.
  • inventory, like check-links.js, follows a redirect before checking its host, so a site can send it to a private address. one shared fix for both is tracked.

co-authored by claude opus 5.5 🧹

@katodea katodea self-assigned this Nov 4, 2026
@katodea katodea changed the title feat: add __kosh.page and contrast ranges for gradient text feat: add __kosh.page and list published pages in the inventory Nov 5, 2026
@katodea
katodea marked this pull request as ready for review November 5, 2026 19:08
@t51eng-poseidon

t51eng-poseidon Bot commented Nov 5, 2026 •

Copy link
Copy Markdown

🔱 Poseidon started reviewing this PR — central run.

Comment thread collectors/kosh.js Resolved
Comment thread collectors/kosh.js Resolved

@t51eng-poseidon t51eng-poseidon Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔱 Poseidon Review

Summary — Adds a single __kosh.page() call for each page (scroll, images, contrast with ranges for gradient text and placeholders, headings, main text, clipped text, overflow) and adds published pages to the inventory. The risk is low: the Node fetch is restricted to the site's host, it fails closed, and the PR already notes the redirect issue. Two measurement edge cases could steer the model wrong.

Walkthrough

  • ✨ New — __kosh.page() collects each page's checks in one call; contrast now has a ratioRange for gradient text and ::placeholder rows; the inventory prints published from ?rest_route=/?sitemap=.
  • ♻️ Refactor — The inventory prints one line per page and per link; null share tags are collapsed into missingMeta.
  • 📝 Docs — The functional-design skill and AGENTS.md now describe page(), published and the contrast rules.
  • 🧪 Tests — Adds jsdom tests over real axe color code, tests for published and the inventory output, and new promptfoo cases.

🟡 Suggestions

  • collectors/kosh.js:L296 — gradientRange (and the placeholder path) ignores the opacity of the text element and its ancestors, so faded text gets a ratioRange that is too high and can be skipped as passing. The test a layer's opacity scales its stops expects 5.32 where the browser renders 1:1. Return no range when an element in the chain has opacity below 1, or fold that opacity into foreground.alpha.
  • collectors/kosh.js:L420 — overflow() counts elements off the left edge (rect.left < -1), such as skip links at left: -9999px. Those never cause horizontal scrolling, so the model may report overflow that isn't there. Count only elements whose rect.right is past the viewport width.

🤖 Prompt for AI agents — fix all findings
Verify each finding against the current code and only fix it if
needed.

Suggestions:
In `collectors/kosh.js`:
- Line 296: In `gradientRange`, the foreground comes from
  `getComputedStyle(node.element).getPropertyValue(
  '-webkit-text-fill-color')`, and the `opacity` of the text element
  and its ancestors is never applied. Only `backgroundsBehind` uses
  opacity, to scale the gradient stops. Faded text therefore gets a
  `ratioRange` that is too high. The skill says to skip a row whose
  `min` clears `threshold`, so failing text can be skipped. Walk from
  `node.element` up to `document.documentElement`. If any computed
  `opacity` is below 1, return null so the row falls back to judging
  by eye. Apply the same check to `field` in `placeholders()` before
  calling `ratioRange`; keep the existing `::placeholder` opacity
  multiplication. Update the test `a layer's opacity scales its
  stops` in tests/collectors.test.js: it expects 5.32 where the
  browser renders 1:1. Have it expect no `ratioRange` instead. Keep
  the try/catch and the `!foreground.alpha` early return.
- Line 420: In `overflow()`, the condition `(rect.right <= width + 1
  && rect.left >= -1)` counts any element whose left edge is below
  -1. Content off the left edge never causes horizontal scrolling.
  Skip links and screen-reader text placed at `left: -9999px` are
  common in themes, and `heldBack` does not exempt them. They show
  up in `overflow.elements` on every page, and the model may report
  a layout bug that does not exist. Change the check so only
  elements whose right edge passes the viewport count, e.g.
  `if (!rect.width || !rect.height || rect.right <= width + 1)
  continue;`. At minimum, skip elements with `rect.right <= 0`. Keep
  the `shown`/`heldBack` filters and the outermost-element logic
  using `past`. Add a case to the `page: overflow ...` test in
  tests/collectors.test.js with an element at left -9999 that must
  not be listed.

ℹ️ Review info
  • Commit: f4c6d95
  • Files reviewed: AGENTS.md, collectors/capture.js, collectors/kosh.js, evals/tests/functional-design.yaml, scripts/page-capture.js, skills/functional-design/SKILL.md, tests/capture.test.js, tests/collectors.test.js, tests/image-resolution-script.test.js, tests/page-capture.test.js
  • Files skipped: none
  • Model: claude-opus-5-5

@t51eng-poseidon t51eng-poseidon Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔱 Poseidon Review

No issues found on this pass. Both fixes since the prior review work as described and have tests.


♻️ Previously flagged

Resolved

  • ✅ collectors/kosh.js:L288 — ratioRange now returns null via faded() when the element or an ancestor has opacity below 1. This covers gradient text and placeholders, and new tests check both.
  • ✅ collectors/kosh.js:L428 — overflow() now counts only elements past the right edge, so a skip link parked off the left is no longer listed. A test case covers it.

ℹ️ Review info
  • Commit: f672054
  • Files reviewed: AGENTS.md, collectors/capture.js, collectors/kosh.js, evals/tests/functional-design.yaml, scripts/page-capture.js, skills/functional-design/SKILL.md, tests/capture.test.js, tests/collectors.test.js, tests/image-resolution-script.test.js, tests/page-capture.test.js
  • Files skipped: none
  • Model: claude-opus-5-5

@katodea
katodea merged commit 0338408 into trunk Nov 5, 2026
3 checks passed
@katodea
katodea deleted the update/model-page-code branch November 5, 2026 20:24
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant