@erclx/canon 5.53.0 → 5.55.0

package/claude/skills/canvas-board/REQUIREMENT.md

@@ -1,35 +0,0 @@
----
-name: canvas-board
-description: Scope boundary for driving the local design canvas, and the line between a drafted frame and the design it feeds
----
-
-# Canvas board requirement
-
-## Gap
-
-Without this skill, a session asked to draw on the canvas writes frames nothing is serving and reports them drawn. It trusts a passing capture, though a blank shell passes every capture while the operator sees an empty tab. From a linked worktree it writes a copy the canvas never serves, and it captures after every edit.
-
-It reads "this one" from the conversation rather than the operator's selection, or acts on a stale element pick and edits the wrong element. It restyles through a class while the operator's inspector edit sits inline, so the change never shows. A picked frame stays on the canvas as the only record, and the project's design record never learns it.
-
-## Must
-
-- The canvas is serving and its live shell loads at the address the server reported before any frame is written, and a refusal or a blank shell is reported rather than drawn into
-- Pages and frames go through the verbs, so the session and the operator's drags share one writer, and a frame from a linked worktree takes the main-root route
-- The operator's selection decides what "this one" means, and a stale element pick reads as unknown
-- A frame's inline styles are read before a restyle, the run names which operator edits it kept and dropped, and capture runs once per finished frame or page
-- A picked frame is handed to `design-record` by page and frame, while a picked layout stays on the canvas for the plan that builds it
-
-## Must not
-
-- Present the canvas as the project's source of truth for design, or promise it survives a lost checkout
-- Write frames when `canon` or its canvas command is missing
-- Name any third-party design tool, or the canvas's predecessor surface
-- Be reached only by the author typing its name, since a request to draw, select, or capture on the canvas should reach it by description
-
-## Out of scope
-
-- Drafting candidates for a taste decision and taking the pick, which `pick-by-eye` owns
-- What the canvas verbs do internally, which the CLI's own contract owns
-- The content format a frame and a layout take, which the canvas standard owns
-- Landing a pick in the reference folder and carrying its values into the design document, which `design-record` owns
-- Tracing reference images into design values and backing up the canvas folder, which no skill owns

package/claude/skills/canvas-board/SKILL.md

@@ -1,143 +0,0 @@
----
-name: canvas-board
-description: Drives the local design canvas, where pages hold HTML frames the operator sees, drags, selects, and edits in the browser. Starts the canvas when it is not running, confirms the live shell loads, makes pages and frames, edits a frame through its file, reads what the operator selected or restyled, captures finished frames, and hands a picked frame to `design-record`. Use when asked to "open the canvas", "put this on the canvas", "draw a frame for X", "change the one I selected", "what did I pick", "capture this frame", or "move that frame on the canvas". Do NOT use to draft candidates for a taste decision, which is `pick-by-eye`.
-metadata:
-  family: decide
----
-
-# Canvas board
-
-Drive the canvas the operator is looking at. A page is a folder of HTML frames and a frame is one file, so a session draws by writing files and the operator sees each write land in the browser. The content format is fixed by `${CLAUDE_SKILL_DIR}/references/canvas.md`. Read it before writing a frame.
-
-Every verb below is `canon canvas`. Run `canon canvas --help` for the verbs and their refusals, and read `${CLAUDE_SKILL_DIR}/references/canvas.md` for the content format.
-
-## Guards
-
-- If `canon` is not on PATH, stop: `❌ canon CLI not found.`
-- If `canon canvas --help` reports no such command, stop: `❌ The installed canon carries no canvas command. Update the CLI and re-run.`
-- Write no frame before the canvas is serving and the shell has loaded. A frame nobody can see is a draft reported as delivered.
-- Never present a frame as the project's design. The canvas is a drafting surface and the project's design record holds what was decided.
-- Never promise the canvas survives a lost checkout. Its folder is gitignored and nothing backs it up.
-
-## Step 1: start the canvas and confirm the shell
-
-Read the pages first, which also proves the verb resolves:
-
-```bash
-canon canvas list --json
-```
-
-The record carries `content`, the folder every page lives in. It sits at the main worktree root whichever worktree the session runs in, so write through that path rather than one composed from the current directory.
-
-Start the server in the background unless the operator named an address that already answers, since it runs until interrupted. No verb reports a running server, and a second one is harmless, since it walks to the next free port and serves the same folder:
-
-```bash
-canon canvas serve --json
-```
-
-Read `url` off the record rather than composing one, since the server walks past a port already in use. Report the refusal and its `reason` when `ok` is false, and stop there.
-
-### Check the shell
-
-Fetch the printed address and check the shell itself, not a capture, since every capture goes through the frame route alone and passes on a blank shell.
-
-- The body is non-empty and carries a `<script` tag. An empty `200` means the shell failed to build, usually a missing dependency, so report a blank shell and stop.
-- `<url>/api/pages` answers with JSON listing the pages.
-
-Hand the operator the address as a markdown link carrying the URL as its text and its target.
-
-## Step 2: make pages and frames
-
-- Add a page for each decision being drafted: `canon canvas page add <page> --json`.
-- Follow the house style in `${CLAUDE_SKILL_DIR}/references/canvas.md` before drafting an explanation frame.
-- Add each frame with `canon canvas frame add <page> <frame> --width <px> --height <px> --json`, which writes the file and its box in one locked step
-
-Give each frame the width it should render at, since a capture and the canvas both render at it. The verb places the frame after the last one, and a position the operator asks for goes through `frame move`.
-
-### Layout and naming
-
-Lay frames out through the verbs rather than by hand, since the operator's drags write the same `layout.json` under a lock.
-
-- Move a frame with `canon canvas frame move <page> <frame> --x <px> --y <px> --json`
-- Name pages and frames for what they hold, such as `pricing` and `pricing-dense`, so the operator can say which one by name.
-- After an insert or a resize, re-lay the page with `canon canvas arrange <page> --json`. It keeps dragged rows, sets the standard gap, and drops entries whose file is gone.
-- Run `arrange --check` to report without writing
-
-## Step 3: edit a frame through its file
-
-Write the frame's whole document to the `path` the add verb reported. The open canvas reloads the frame when its file changes.
-
-- From a linked worktree, `Edit` and `Write` refuse a main-root path. Write the whole file through one plain `Bash` heredoc, the route `session-worktree` states, never a worktree copy.
-- Change one property with `canon canvas edit <page>/<frame> --element <index> --set <property>=<value> --json` when its set covers the change, since it leaves every other byte as it was
-- Use the project's custom properties for every value the token stylesheet defines. The `serve` record names the source under `tokens`, and `none` means frames render unstyled, so say so.
-
-### Fit the box
-
-Fit the box to the content once the write lands, with `canon canvas fit <page>/<frame> --json`, and read each row's `wide` and `font`.
-
-- A `wide` frame needs its box widened, which fit never does
-- A `font` frame names a family the canvas does not serve, so set its text to a served face and fit again
-- A fit that grew a frame leaves the rows below overlapped until `canvas arrange` runs
-
-### Mark the frame
-
-Mark the frame before the first write, so the operator sees which frame is being worked on before anything lands, and clear the mark once the edits to it are done:
-
-```bash
-canon canvas editing <page>/<frame> --json
-canon canvas editing <page>/<frame> --done --json
-```
-
-- A mark lapses after five minutes, so mark the frame again during a longer edit.
-- Clear it on every exit from the edit, including one that stopped on a refusal. Clearing a frame that holds no mark succeeds.
-- On `unknown command 'editing'`, the CLI predates the mark, so go on without it. Never run `canvas edit` in its place, since that verb writes the frame.
-
-## Step 4: read what the operator pointed at
-
-Read the selection when the operator says "this one", "the selected frame", or "that button":
-
-```bash
-canon canvas selection --json
-```
-
-- `selection: null` means nothing is selected or the selected frame is gone. Ask which one rather than guessing.
-- An `element` carrying `stale: true` was picked against an earlier file, so its `index` may land elsewhere. Ask the operator to pick again rather than matching its `tag` and `text` by eye.
-- A fresh `element` gives the `index` that `canvas edit` takes.
-
-## Step 5: respect the operator's inspector edits
-
-The operator restyles elements from the inspector, and each edit lands as inline `style` on the element. Inline style beats a class, so a class change made afterwards does not show.
-
-- Read the frame's inline `style` attributes before restyling anything in it.
-- Keep an inline property the operator set unless the change replaces it, and drop it, through `canvas edit` with an empty value or by rewriting the file, when it does.
-- Say which operator edits were kept and which were dropped.
-
-## Step 6: capture finished work
-
-Capture once per finished frame or page, not after every edit. The live canvas is the working view, and a capture is the record handed on.
-
-- Capture a frame with `canon canvas capture <page>/<frame> --json`. Each PNG is the whole document, so its height follows the content rather than the box.
-- Capture a page with `canon canvas capture <page> --composite --json`, which shows each frame clipped to its box at its layout position
-- Read each `path` off the record rather than composing one.
-
-A capture refused because a font is not installed names the family it read off the frame's text. Set that text's `font-family` to a named family the machine has, never a generic keyword such as `sans-serif`, and capture again rather than reporting the frame as captured.
-
-## Step 7: hand a picked frame on
-
-When the operator picks a frame, the decision leaves the canvas. Hand it to `canon:design-record`, which lands the frame in the project's reference folder and carries its values into the design document. Report it rather than proceeding silently when that skill does not resolve.
-
-- Name the page and frame the decision came from in the handoff and the reply, and leave the frame on the canvas until the operator clears it
-- Name the frame in the plan that builds a picked layout, since the layout reaches code through that plan
-- Never cite a frame path from a tracked file. The folder is gitignored, so the citation resolves on this machine alone.
-
-## Output
-
-```plaintext
-✅ Canvas: <url the serve verb reported>
-Page:     <page>, <n> frames
-Selected: <page>/<frame>, element <index>, or none, or stale
-Capture:  <path of each capture written>
-Handed:   <the frame handed to design-record, the plan that cites it, or not yet>
-```
-
-Write the canvas line's URL as a markdown link. Omit the capture line when nothing was captured and the handed line when no frame was picked. Emit every path from the project root.

package/claude/skills/canvas-board/references/canvas.md

@@ -1,170 +0,0 @@
----
-title: Canvas reference
-description: Page folders, frame files, the layout.json shape, token resolution, and what a frame must not assume on a local design canvas
----
-
-# Canvas reference
-
-Applies to the canvas content under `.canon/canvas/`, where each page is a folder of HTML frames and a layout file placing them. A frame is a draft drawn to be looked at and picked from, so it changes whenever someone tries a direction, and the operator clears it once the direction lands where the project keeps its design.
-
-The folder is gitignored, so nothing in a repository checks its shape and nothing backs it up by default.
-
-## Contents
-
-- [Scope](#scope)
-- [What a working canvas looks like](#what-a-working-canvas-looks-like)
-- [Pages](#pages)
-- [Frames](#frames)
-- [House style](#house-style)
-- [Layout](#layout)
-- [Tokens](#tokens)
-- [What a frame must not assume](#what-a-frame-must-not-assume)
-- [Template](#template)
-
-## Scope
-
-Governs the canvas content under `.canon/canvas/`: page folder names, frame files, the `layout.json` shape, how tokens reach a frame, and what a frame must not assume about where it renders.
-
-- Also governs the house style of an explanation frame, being a diagram, a board of notes, or a comparison
-- A mockup of the project's own interface is not an explanation frame, and follows the project's design document for type, color, and layout
-
-Does not govern:
-
-- The design decisions a mockup frame is drafting, such as type, color, and layout taste: the project's own design document
-- The project's design document and the token module it renders from, which a picked direction is carried into: `design.md`
-- The procedure that starts the canvas, reads the operator's selection, and carries a pick back, which belongs to the surface driving the canvas
-- Voice, rhythm, and sentence construction in any text a frame shows: the `write-human` skill
-
-## What a working canvas looks like
-
-A canvas works when the operator and a session can point at the same thing and see the same thing:
-
-- Which pages exist, and which frames sit on each?
-- Where does each frame sit on its page, and at what width does it render?
-- Does each frame show the project's own tokens rather than values copied into it?
-- Does a frame render the same in the live canvas as in a capture?
-
-A canvas failing these is non-conforming even when it satisfies every shape rule below.
-
-## Pages
-
-- Make one folder per page directly under `.canon/canvas/`. A page groups the frames compared side by side, such as the candidates for one decision.
-- Name a page as one path segment of letters, digits, dots, dashes, and underscores, starting with a letter or a digit. A name opening with a dot is hidden from every listing.
-- Never write a folder whose name opens with a dot. Those names are reserved for files the canvas generates and removes itself.
-- Rename a page rather than copying it under a new name, so its layout and frames stay together.
-
-## Frames
-
-- Write one frame as one `.html` file inside its page folder. The filename without its extension is the frame's name, and the name follows the page naming rule.
-- Write a frame as a whole document or as a fragment. The server writes in the `html`, `head`, and `body` a fragment leaves out, marked so a pick still matches the file.
-- State a `body` whenever the frame states a `head`. The browser builds one the file leaves out, and an address the operator picks inside the frame can no longer be matched to the file.
-- Write every table with its `tbody` stated, for the same reason. A browser adds one the file leaves out.
-
-### Content and edits
-
-A frame is the only copy of its markup, so it carries everything it needs.
-
-- Keep a frame self-contained. Inline its own styles and scripts, or link a file inside the same page folder, since a frame is served from its page and nothing outside the canvas resolves.
-- Use the project's custom properties, `var(--<name>)`, for every value the token stylesheet defines. A literal copied from it shows the right color today and the wrong one after the next token change.
-- Edit a frame by rewriting its file. The file is the frame, and nothing else holds a copy of its markup.
-
-## House style
-
-Applies to an explanation frame only. A mockup of the project's interface renders at the app's own sizes and follows the project's design document instead.
-
-- Write text in sentence case. Use no all-caps text and no `text-transform: uppercase`.
-- Keep lines short, one fact a line.
-- Set body text at 20px or larger and headings at 44px or larger. Set nothing under 16px.
-- Render an explanation frame about 1100px wide.
-
-### Colors, faces, and fit
-
-Take colors from the project's custom properties. A frame defining colors of its own sets the dark values on `:root` and the light ones under `[data-theme="light"]`, since the shell sets `data-theme` on each frame's root.
-
-- Name only the faces the canvas serves into every frame, being `Geist Variable` for text, `Noto Sans Mono` for code, and `Excalifont` for a hand-drawn look
-- Those render the same in a capture and in any browser, so a height fitted against them holds
-- Make each box tall enough to show all its content, with no scrollbar and no clipped line
-- Run `canon canvas fit <page>/<frame>` rather than estimating, since it measures the content in the capture browser and sets the height
-- Read frames left to right in reading order. Let `frame add` place each frame after the last with the standard gap, and move one only when the operator asks for a position.
-
-## Layout
-
-- Keep one `layout.json` per page, beside its frames. It holds each frame's box and nothing else, so moving a frame never rewrites its markup.
-- Key each box by the frame's name, under one top-level `frames` object.
-- Give every box four finite numbers in pixels: `x` and `y` for its top-left corner on the page, `width` for the width the frame renders at, and `height` for the height it shows on the canvas.
-
-### Missing boxes and writes
-
-The layout file is shared state, so a write never discards a box another writer or reader holds.
-
-- Leave a frame out of the layout only when its position does not matter yet. A reader places an unnamed frame in a row after the others, at the default size of 1440 by 900.
-- Never write the file while a writer holds its lock, which is the same name with `.lock` appended. Two writers each replacing the whole file lose one of the two edits.
-- Treat a layout that does not parse as a defect to repair, never as an empty one to overwrite. Writing over it erases every box it held.
-
-The keys below are the ones a reader parses. The frame names are placeholders.
-
-```json
-{
-  "frames": {
-    "hero-a": { "x": 0, "y": 0, "width": 1440, "height": 900 },
-    "hero-b": { "x": 1520, "y": 0, "width": 1440, "height": 900 }
-  }
-}
-```
-
-## Tokens
-
-- Expect the token stylesheet first in every frame's `head` when it is served, ahead of anything the frame links. A stylesheet the frame links itself still wins the cascade.
-- Read the tokens from the canvas tool's own module inside its own checkout, else the project's installed base stylesheet plus its project override folder, else none
-- A canvas with no token source renders unstyled and says so
-- Never paste the token stylesheet into a frame. The injected copy follows the project, and a pasted one stops following it the moment it is written.
-
-## What a frame must not assume
-
-- Do not assume a viewport. A frame renders at its layout width on the canvas and in a capture alike, so size it with media queries against that width rather than against the operator's window.
-- Do not assume the theme. The canvas theme toggle is the operator's own state, and a capture shows each frame in its default theme.
-- Do not assume a network. Name a served face, or ship the font beside the frame, since a capture refuses a frame naming a font it cannot find.
-
-### Font, source, and checkout
-
-Do not assume a default font. Set `font-family` with a served face first on an element the frame's text inherits from, since a capture checks the first family of the text it renders and the browser's default serif is absent from many machines.
-
-- A frame naming a machine family such as `DejaVu Sans` renders at another height in another browser, which `canon canvas fit` reports
-- Do not assume the frame is the source. A picked direction is carried into the project's design document or a plan, and the operator clears the frame once it has been carried.
-- Do not assume the canvas survives the checkout. The folder is gitignored, so a lost checkout loses every page in it.
-
-## Template
-
-A new frame starts from this skeleton. The names in it are placeholders.
-
-```html
-<!doctype html>
-<html lang="en">
-  <head>
-    <meta charset="utf-8" />
-    <title>frame-name</title>
-    <style>
-      html {
-        font-family: installed-family, sans-serif;
-      }
-      main {
-        padding: var(--space-lg);
-        color: var(--color-text);
-        background: var(--color-background);
-      }
-      /* only a color the frame defines itself: dark on :root, light here */
-      :root {
-        --frame-accent: #7aa2ff;
-      }
-      [data-theme='light'] {
-        --frame-accent: #1f4fd8;
-      }
-    </style>
-  </head>
-  <body>
-    <main>
-      <h1>frame-name</h1>
-    </main>
-  </body>
-</html>
-```

package/governance/rules/ui/canvas.md

@@ -1,13 +0,0 @@
----
-description: Route edits to canvas frames under .canon/canvas/ to the canvas-board skill for the house style, and keep frame text and box height readable
-paths:
-  - '.canon/canvas/**'
----
-
-# Canvas standards
-
-## Frames
-
-- Load the `canon:canvas-board` skill before drawing or editing a frame. It carries the house style for an explanation frame and the content format. Report it rather than proceeding silently when the skill does not resolve.
-- Write explanation frame text in sentence case. A mockup of the project's interface follows its design document instead.
-- Size each explanation frame's box to show all its content with no scrollbar.

package/scripts/core/check-color-source.sh

@@ -1,51 +0,0 @@
-#!/usr/bin/env bash
-set -e
-set -o pipefail
-
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-PROJECT_ROOT="${PROJECT_ROOT:-$(cd "$SCRIPT_DIR/../.." && pwd)}"
-
-SCRIPTS_ROOT="$PROJECT_ROOT/scripts"
-SANDBOX_ROOT="$PROJECT_ROOT/sandbox"
-PALETTE_SOURCE="$SCRIPTS_ROOT/lib/ui.sh"
-
-# `find` writes to stderr and returns non-zero for a missing root, inside a
-# process substitution whose status nothing reads. Without this the walk covers
-# nothing and the check reports the tree clean having never measured it.
-if [ ! -f "$PALETTE_SOURCE" ]; then
-  echo "No palette source at ${PALETTE_SOURCE#"$PROJECT_ROOT/"}, color sourcing unverifiable." >&2
-  exit 1
-fi
-
-# The same silence follows a root that moved, so a walked root that is gone
-# fails here rather than shrinking the corpus with no message.
-for root in "$SCRIPTS_ROOT" "$SANDBOX_ROOT"; do
-  if [ ! -d "$root" ]; then
-    echo "No shell root at ${root#"$PROJECT_ROOT/"}, color sourcing unverifiable." >&2
-    exit 1
-  fi
-done
-
-# Any SGR sequence in either spelling. The cursor and erase sequences an
-# interactive prompt writes end in a letter instead, and they run only where a
-# terminal already exists, so they are not what this measures.
-SGR='\\(033|e|x1b)\[[0-9;]*m'
-
-# Sixteen copies of one decision is what made color impossible to turn off on
-# the TypeScript side. A rule nothing enforces rebuilds them the next time a
-# script wants grey, so the escape lives in the shared library and every other
-# script reads the palette that library derives for its stream.
-offenders=""
-while IFS= read -r file; do
-  [ "$file" = "$PALETTE_SOURCE" ] && continue
-  if grep -qE "$SGR" "$file"; then
-    offenders="$offenders  ${file#"$PROJECT_ROOT/"}"$'\n'
-  fi
-done < <(find "$SCRIPTS_ROOT" "$SANDBOX_ROOT" -type f -name '*.sh')
-
-if [ -n "$offenders" ]; then
-  echo "A color escape is defined outside the shared library:" >&2
-  printf '%s' "$offenders" >&2
-  echo "Source scripts/lib/ui.sh and read its palette, so one answer covers every writer." >&2
-  exit 1
-fi

package/src/canvas/address.ts

@@ -1,227 +0,0 @@
-/**
- * The element address: a frame plus the element's index in document order.
- * The shell counts it over the frame's parsed DOM and the server counts it over
- * the file through `HTMLRewriter`, so the two have to count the same elements.
- * This module imports nothing, which keeps it bundling into the shell, and the
- * server half reaches `HTMLRewriter` as a Bun global only when called.
- */
-
-/** Marks the token stylesheet the server injects, which the file never holds. */
-export const TOKENS_ATTRIBUTE = 'data-canvas-tokens'
-
-/**
- * Marks a document wrapper the server writes because the file leaves it to the
- * browser to imply, so the shell counts only what the file states.
- */
-export const IMPLIED_ATTRIBUTE = 'data-canvas-implied'
-
-/** On that same element, the hash of the file the frame was served from. */
-export const HASH_ATTRIBUTE = 'data-canvas-hash'
-
-const EXCERPT_LENGTH = 80
-
-/** Elements whose content is raw text, which a browser never parses as markup. */
-const RAW_TEXT = new Set(['script', 'style', 'template', 'textarea', 'title'])
-
-export interface ElementAddress {
-  readonly index: number
-  readonly tag: string
-  /**
-   * Every element the shell counted. A browser implies elements the file never
-   * states, such as a `tbody`, and each one shifts the count, so a total that
-   * differs from the server's is what exposes it. The server marks an implied
-   * document wrapper itself, so only the marked ones leave the count.
-   */
-  readonly count: number
-  /**
-   * The served file's hash, so the server can refuse a pick made against a
-   * version of the frame the file has since moved past.
-   */
-  readonly hash?: string
-}
-
-export interface SourceElement {
-  readonly tag: string
-  readonly classes: readonly string[]
-  readonly text: string
-}
-
-export type AddressCheck =
-  | { readonly ok: true; readonly element: SourceElement }
-  | {
-      readonly ok: false
-      readonly reason: 'address-mismatch'
-      readonly detail: string
-    }
-
-export function excerpt(text: string): string {
-  return text.replace(/\s+/g, ' ').trim().slice(0, EXCERPT_LENGTH)
-}
-
-export function documentElements(doc: Document): Element[] {
-  return [...doc.querySelectorAll('*')].filter(
-    (element) =>
-      !element.hasAttribute(TOKENS_ATTRIBUTE) &&
-      !element.hasAttribute(IMPLIED_ATTRIBUTE),
-  )
-}
-
-export function addressOf(
-  doc: Document,
-  element: Element,
-): ElementAddress | undefined {
-  const all = documentElements(doc)
-  const index = all.indexOf(element)
-  if (index === -1) return undefined
-  const address = {
-    index,
-    tag: element.tagName.toLowerCase(),
-    count: all.length,
-  }
-  const hash = doc
-    .querySelector(`[${TOKENS_ATTRIBUTE}]`)
-    ?.getAttribute(HASH_ATTRIBUTE)
-  return hash ? { ...address, hash } : address
-}
-
-/** The element an address names, or nothing once the tag there differs. */
-export function elementAt(
-  doc: Document,
-  address: Pick<ElementAddress, 'index' | 'tag'>,
-): Element | undefined {
-  const element = documentElements(doc)[address.index]
-  return element?.tagName.toLowerCase() === address.tag ? element : undefined
-}
-
-interface Collected {
-  readonly tag: string
-  readonly classes: readonly string[]
-  text: string
-}
-
-/**
- * Called on each element the address counts, with its index. What it returns
- * runs at the element's end tag, since a second `onEndTag` on one element
- * replaces the first rather than adding to it.
- */
-export type ElementVisitor = (
-  element: HTMLRewriterTypes.Element,
-  index: number,
-) => (() => void) | undefined
-
-/**
- * Registers the one counting rule both the reader and the edit writer follow,
- * so an index means the same element to each.
- */
-export function countElements(
-  rewriter: HTMLRewriter,
-  visit: ElementVisitor,
-): HTMLRewriter {
-  let count = 0
-  /* A template's content is a fragment `querySelectorAll` never reaches. */
-  let templateDepth = 0
-
-  return rewriter.on('*', {
-    element(element) {
-      const tag = element.tagName.toLowerCase()
-      if (templateDepth > 0) {
-        if (tag === 'template') {
-          templateDepth += 1
-          element.onEndTag(() => {
-            templateDepth -= 1
-          })
-        }
-        return
-      }
-      const end = visit(element, count)
-      count += 1
-      if (!element.canHaveContent || element.selfClosing) return
-      const isTemplate = tag === 'template'
-      if (isTemplate) templateDepth += 1
-      element.onEndTag(() => {
-        if (isTemplate) templateDepth -= 1
-        end?.()
-      })
-    },
-  })
-}
-
-/** Whether an element's content is raw text rather than parsed markup. */
-export function isRawText(tag: string): boolean {
-  return RAW_TEXT.has(tag)
-}
-
-/**
- * Every element the file states, in document order. Text is gathered into
- * each open element, which an element closed only by implication keeps open to
- * the end, so its excerpt can run past where a browser would end it.
- */
-export function sourceElements(html: string): SourceElement[] {
-  const elements: Collected[] = []
-  const open: number[] = []
-  let rawDepth = 0
-
-  const appendText = (text: string) => {
-    for (const index of open) {
-      const element = elements[index]
-      if (element && element.text.length < EXCERPT_LENGTH * 4) {
-        element.text += text
-      }
-    }
-  }
-
-  countElements(new HTMLRewriter(), (element, index) => {
-    const tag = element.tagName.toLowerCase()
-    /* A tag boundary separates words the way a rendered block would. */
-    appendText(' ')
-    elements.push({
-      tag,
-      classes: (element.getAttribute('class') ?? '')
-        .split(/\s+/)
-        .filter(Boolean),
-      text: '',
-    })
-    if (!element.canHaveContent || element.selfClosing) return undefined
-    const isRaw = isRawText(tag)
-    open.push(index)
-    if (isRaw) rawDepth += 1
-    return () => {
-      const at = open.lastIndexOf(index)
-      if (at !== -1) open.splice(at, 1)
-      if (isRaw) rawDepth -= 1
-      appendText(' ')
-    }
-  })
-    .onDocument({
-      text(chunk) {
-        if (rawDepth === 0) appendText(chunk.text)
-      },
-    })
-    .transform(html)
-
-  return elements.map(({ tag, classes, text }) => ({
-    tag,
-    classes,
-    text: excerpt(text),
-  }))
-}
-
-/**
- * Finds the element the shell addressed in the file, and refuses when the two
- * counts disagree rather than naming whatever sits at that index on disk.
- */
-export function resolveAddress(
-  html: string,
-  address: ElementAddress,
-): AddressCheck {
-  const elements = sourceElements(html)
-  const element = elements[address.index]
-  if (elements.length !== address.count || element?.tag !== address.tag) {
-    return {
-      ok: false,
-      reason: 'address-mismatch',
-      detail: `the browser counted ${address.count} elements and the file states ${elements.length}, so element ${address.index} cannot be matched`,
-    }
-  }
-  return { ok: true, element }
-}