Skip to content

Tier 4: support canvases rendered by a JS framework (phase 1) - #9

Merged
chorta merged 2 commits into
mainfrom
claude/tier4-framework-canvas
Oct 2, 2026
Merged

chorta merged 2 commits into
mainfrom
claude/tier4-framework-canvas

Conversation

@chorta

@chorta chorta commented Oct 2, 2026 •

Copy link
Copy Markdown
Contributor

Why

In a Vue 3 + Vite port of a Decorator deck, npm run build && npx ucsd-decorator-kit verify reported 3 × chrome/styling/script in dist/assets/index-*.js, and --accept refused because of them. Tiers 1–3 were fine. There were three causes:

  1. The built canvas is an empty <div id="deck-app">, so deriveProtectedTokens protected 59 tokens. That included shared Bootstrap words the app really uses at runtime (.row, .glyphicon, .sr-only, …). Canvas-scoped CSS such as main#main-content .deck-card .glyphicon was flagged.
  2. The JS gate worked per file and matched token names as bare words, string contents included. Slide prose ("Navbar, drawer & both search forms") tripped it.
  3. Once a file was gated, every .id = in it was flagged, including Vue's scheduler setting job.id = uid on objects that aren't DOM elements.

What changed

A. Canvas-anchored selectors are exempt (no config). A selector is not flagged for a protected token when its leftmost compound is the canvas root (canvas in decorator-kit.json, default main#main-content) and every combinator after it is a descendant or child combinator. These are still flagged:

  • a sibling combinator after the anchor (main#main-content ~ footer)
  • an anchor that isn't leftmost (.navbar main#main-content .row, body main#main-content …)
  • a leading combinator

Page-ground and canvas-components/ strict checks are unchanged.

B. The JS gate works per function. An id mutation is flagged only when its nearest named enclosing function, or a function lexically enclosing it (module scope included), references a protected token in a string literal in code position. Three kinds of literal count:

  • an argument to a DOM selector API (querySelector(All), closest, matches, getElementById, getElementsByClassName, $/jQuery, .find)
  • a selector-shaped string
  • an id value (el.id = "search", setAttribute("id", "search"))

Prose, comments, identifiers like location.search, and [href='#…'] contents don't count. The two-view stripJsNoise approach is kept. The trade-off is in checks/README.md: an element fetched in one function and mutated in an unrelated one is not flagged. The closure shape (fetched at module scope or in an outer function, mutated in a nested handler) still is.

C. thirdParty in decorator-kit.json. This is an optional list of globs or paths for built third-party JS that the script scan skips. CSS is never skipped. Each pattern must start with a literal path segment, so **/*.js is refused.

  • verify prints the tier-4 scope on every run, e.g. tier 4 scanned 2 CSS files and 5 JS files; skipped …. It also notes any pattern that matched nothing.
  • --explain lists the patterns.
  • sync keeps the list.
  • The schema is updated.
  • The CI workflow template warns on each added pattern.
  • checks/README.md and rules/00-canvas.md say agents must not add entries to make a finding go away.

D. decorator-kit.json is guarded like the chrome *.local.json files. Its canvas decides what tier 4 protects and what counts as canvas-anchored, so "canvas": "body" would empty most of the check in one line, and nothing flagged that before. Two changes:

  • templates/claude-settings.json now denies Edit/Write on the file. init, add and sync still write it, because they go through Node, not those tools.
  • The CI workflow template now warns when canvas changes, alongside the thirdParty warning. A new manifest with the default canvas doesn't trigger it.

Compiled CLAUDE.md is 24,770 chars, under the 25,000 budget.

Verification

  • npm test: 152 pass.
  • New tests cover each case: A (anchored, sibling, non-anchored, non-leftmost); B (Vue scheduler shape with prose, the real-incident replays, functions that query #search/.navmenu, closures, prose/comments/identifiers); C (declared JS skipped and reported, undeclared flagged, declared CSS still scanned, glob validation, sync preserves the list, scope line printed).
  • Checked in decorator-kit-deck-vue by running node <worktree>/checks/chrome-contract.mjs --check:
    • Tier 4 reports 0 findings with no thirdParty entry.
    • Temporarily reverting the .deck-card-icon workaround back to main#main-content .deck-card .glyphicon also passes; main flags it twice. The project's files were restored byte-for-byte afterward.
    • The 6 remaining findings there are tier 2 "no golden recorded yet". A human has to run --accept for those.

🤖 Generated with Claude Code

chorta and others added 2 commits October 2, 2026 11:49
A Vue 3 + Vite build ships an empty canvas mount point, so the derived
protected token set swells with shared Bootstrap words the app uses at
runtime, and the file-level script gate tripped on slide prose and then
flagged Vue's scheduler setting .id on job objects.

- CSS: a selector whose leftmost compound is the canvas root, followed
  only by descendant/child combinators, is not flagged for naming a
  protected token. Sibling combinators and non-leftmost anchors still are;
  page-ground and canvas-components/ global checks are unchanged.
- JS: gate id mutations per nearest named function (plus lexically
  enclosing scopes), counting only string literals in code position:
  selector-API arguments, selector-shaped strings, and id values.
- decorator-kit.json gains an optional, human-owned `thirdParty` list of
  built third-party JS the script scan skips (CSS is never skipped).
  verify prints the tier 4 scope every run; the CI template warns on added
  patterns; sync preserves the list; rules tell agents not to add to it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Its canvas selector decides what tier 4 protects and what counts as
canvas-anchored, so "canvas": "body" would empty most of the check in one
line, and nothing flagged it.

- templates/claude-settings.json denies Edit/Write on decorator-kit.json.
  init/add/sync still write it through Node.
- The CI workflow template now warns when canvas changes, alongside the
  existing thirdParty warning.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@chorta
chorta merged commit cebb975 into main Oct 2, 2026
1 check passed
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