@erclx/canon 5.14.1 → 5.16.0

package/docs/workflow/skill-map.md

@@ -50,6 +50,7 @@ This page is the corpus the coverage claim is measured against: every name `cano
 | `canon:deprecation-migration` | When deleting or replacing code something may still call, to migrate its callers and prove none remain     |
 | `canon:code-craft`            | Before writing a function, class, or module, to pick the shape the next change needs                       |
 | `canon:review-craft`          | When reviewing a change, for what to look for and how much evidence a finding needs                        |
+| `canon:search-craft`          | Before searching outside the project, to derive where the field's authorities publish and search there too |
 | `canon:systematic-debugging`  | When a test fails or a bug surfaces, to force root cause first                                             |
 | `canon:design-taste`          | When drafting or judging an interface, or when output reads generic, to settle which decision comes first  |
 | `canon:ui-checklist`          | After a UI change, to write what to look at and name what ships untested                                   |
@@ -134,7 +135,7 @@ This page is the corpus the coverage claim is measured against: every name `cano
 | `canon:ci-workflow`       | For a GitHub Actions workflow file                                                                                |
 | `canon:draft-slides`      | For a deck, drafted as `.claude/SLIDES.md` and rendered to PowerPoint                                             |
 | `canon:draft-screencast`  | For a recording script with beats and defaults already seeded                                                     |
-| `canon:record-screencast` | For compiling and running a screencast draft into a recording and a still                                         |
+| `canon:record-screencast` | For recording a screencast draft, then composing the take into a finished mp4 when the draft asks for a wrap      |
 | `canon:draft-identity`    | For a project's logo mark and its social card, drafted through `draft-and-pick`'s pick loop                       |
 
 ## Answer a question at any point

package/governance/renames.toml

@@ -6,10 +6,13 @@
 # An entry declares one-to-one identity and nothing else. A fold of several
 # rules into one, or a split of one into several, is a retirement plus an
 # addition and takes no entry here. Add the entry in the same change as the
-# rename or renumber, and never prune one: a target can sit any number of
-# releases behind, and a chain A to B to C resolves A only while both links
-# stay. A key must name no live rule and every chain must end on one, which
-# `src/gov/renames.test.ts` checks against this file.
+# rename or renumber. Prune an entry only once its target rule is retired and
+# the retire path covers it, since a chain ending on a rule nothing ships
+# resolves to nothing and a sync deletes the held file instead. Otherwise leave
+# it: a target can sit any number of releases behind, and a chain A to B to C
+# resolves A only while both links stay. A key must name no live rule and every
+# chain must end on one, which `src/gov/renames.test.ts` checks against this
+# file.
 [renamed]
 "005-behavior" = "565-behavior"
 "015-output" = "566-output"
@@ -25,7 +28,6 @@
 "520-wireframes" = "620-wireframes"
 "530-requirements" = "630-requirements"
 "540-architecture" = "640-architecture"
-"545-decisions" = "645-decisions"
 "550-design" = "650-design"
 "555-tasks" = "655-tasks"
 "556-groundwork" = "656-groundwork"

package/governance/rules/canon/630-requirements.md

@@ -9,4 +9,4 @@ paths:
 
 ## Authority
 
-- Follow the requirements standard for what belongs in the problem, goals, non-goals, MVP features, tech stack, and constraints. It is the single source. Read it with `canon standards requirements`.
+- Follow the requirements standard for what belongs in the problem, goals, non-goals, MVP features, and constraints. It is the single source. Read it with `canon standards requirements`.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/canon",
   "type": "module",
-  "version": "5.14.1",
+  "version": "5.16.0",
   "description": "Runs your agent's work and keeps its code good, on one setup for every repo.",
   "license": "MIT",
   "bin": {
@@ -52,11 +52,13 @@
     "web:e2e": "cd web && playwright test"
   },
   "dependencies": {
+    "@preact/signals": "^2.11.3",
     "commander": "^13.1.0",
     "execa": "^9.5.2",
     "highlight.js": "^11.12.0",
     "playwright-core": "1.59.1",
-    "pptxgenjs": "^4.0.1"
+    "pptxgenjs": "^4.0.1",
+    "preact": "^11.0.0"
   },
   "devDependencies": {
     "@astrojs/check": "^0.9.8",
@@ -70,6 +72,7 @@
     "@types/micromatch": "^4.0.10",
     "astro": "^6.1.9",
     "cspell": "^8.17.1",
+    "happy-dom": "^20.14.5",
     "husky": "^9.1.7",
     "micromatch": "^4.0.8",
     "prettier": "^3.8.1",

package/scripts/lib/sandbox-git.sh

@@ -43,7 +43,7 @@ resolve_sandbox_git_identity() {
   SANDBOX_GIT_NAME="${SANDBOX_GIT_NAME:-$(git config --global user.name 2>/dev/null || true)}"
   SANDBOX_GIT_EMAIL="${SANDBOX_GIT_EMAIL:-$(git config --global user.email 2>/dev/null || true)}"
 
-  : "${SANDBOX_GIT_NAME:=aitk-sandbox}"
+  : "${SANDBOX_GIT_NAME:=canon-sandbox}"
   : "${SANDBOX_GIT_EMAIL:=sandbox@example.com}"
 
   export SANDBOX_GIT_NAME SANDBOX_GIT_EMAIL
@@ -57,7 +57,7 @@ configure_sandbox_git_identity() {
 
 # Every scenario that needs a remote points at the same throwaway repository, so
 # the name lives here rather than in each one.
-SANDBOX_ANCHOR_REPO="aitk-sandbox"
+SANDBOX_ANCHOR_REPO="canon-sandbox"
 
 # A scenario calls this from its own use_anchor hook rather than this file
 # defining the hook. manage-sandbox.sh keys off `type -t use_anchor`, so

package/src/canvas/address.ts

@@ -0,0 +1,184 @@
+/**
+ * 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'
+
+/** 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` or the document wrapper, and each one shifts the
+   * count, so a total that differs from the server's is what exposes it.
+   */
+  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),
+  )
+}
+
+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
+}
+
+/**
+ * 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
+  /* A template's content is a fragment `querySelectorAll` never reaches. */
+  let templateDepth = 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
+      }
+    }
+  }
+
+  new HTMLRewriter()
+    .on('*', {
+      element(element) {
+        const tag = element.tagName.toLowerCase()
+        if (templateDepth > 0) {
+          if (tag === 'template') {
+            templateDepth += 1
+            element.onEndTag(() => {
+              templateDepth -= 1
+            })
+          }
+          return
+        }
+        const index = elements.length
+        /* 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
+        const isRaw = RAW_TEXT.has(tag)
+        const isTemplate = tag === 'template'
+        open.push(index)
+        if (isRaw) rawDepth += 1
+        if (isTemplate) templateDepth += 1
+        element.onEndTag(() => {
+          const at = open.lastIndexOf(index)
+          if (at !== -1) open.splice(at, 1)
+          if (isRaw) rawDepth -= 1
+          if (isTemplate) templateDepth -= 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 }
+}

package/src/canvas/capture.ts

@@ -0,0 +1,172 @@
+import { join } from 'node:path'
+import type { CaptureResult } from '@/capture/render'
+import { type ContentRefused, type Frame, readPage } from '@/canvas/content'
+import {
+  type CanvasOptions,
+  type CanvasOutcome,
+  FRAMES_PREFIX,
+  startCanvas,
+} from '@/canvas/server'
+import { recordDir } from '@/record-root'
+
+/**
+ * The element a frame is captured by. The document rather than its body, so a
+ * frame that paints its background on the root is not cropped to the body's
+ * box.
+ */
+export const CAPTURE_SELECTOR = 'html'
+
+export interface CaptureTarget {
+  readonly page: string
+  readonly frame: string
+  /** The served address, which is what carries the injected tokens. */
+  readonly url: string
+  /** The viewport width, so a media query resolves at the frame's own width. */
+  readonly width: number
+  readonly pngPath: string
+}
+
+export type TargetsOutcome =
+  | { readonly ok: true; readonly targets: readonly CaptureTarget[] }
+  | ContentRefused
+
+function refuse(
+  reason: ContentRefused['reason'],
+  detail: string,
+): ContentRefused {
+  return { ok: false, reason, detail }
+}
+
+function frameUrl(base: string, page: string, frame: Frame): string {
+  return `${base}${FRAMES_PREFIX.slice(1)}${encodeURIComponent(page)}/${encodeURIComponent(frame.file)}`
+}
+
+/**
+ * Turns `<page>` or `<page>/<frame>` into what to capture. Every target is a
+ * served address, never the file on disk, so a capture can only show what the
+ * canvas shows. The width comes from the layout and not from the window, so a
+ * frame narrower than its own breakpoint renders its narrow layout.
+ *
+ * `out` is the PNG for a frame and a folder for a page, the way a URL source
+ * reads `--out` in `canon capture`.
+ */
+export function resolveCaptureTargets(
+  root: string,
+  spec: string,
+  base: string,
+  out?: string,
+): TargetsOutcome {
+  const [pageName, frameName, ...extra] = spec.split('/')
+  if (!pageName || extra.length > 0 || frameName === '') {
+    return refuse('invalid-name', `${spec} is not <page> or <page>/<frame>`)
+  }
+
+  const page = readPage(root, pageName)
+  if (!page) return refuse('no-page', `page ${pageName} does not exist`)
+
+  const frames =
+    frameName === undefined
+      ? page.frames
+      : page.frames.filter((frame) => frame.name === frameName)
+  if (frames.length === 0) {
+    return frameName === undefined
+      ? refuse('no-frame', `page ${pageName} has no frames`)
+      : refuse('no-frame', `frame ${frameName} does not exist on ${pageName}`)
+  }
+
+  const scratch = recordDir(root, 'tmp', 'canvas-capture', pageName)
+  return {
+    ok: true,
+    targets: frames.map((frame) => ({
+      page: pageName,
+      frame: frame.name,
+      url: frameUrl(base, pageName, frame),
+      width: frame.width,
+      pngPath:
+        frameName !== undefined && out !== undefined
+          ? out
+          : join(out ?? scratch, `${frame.name}.png`),
+    })),
+  }
+}
+
+export type CaptureOutcome =
+  | {
+      readonly ok: true
+      readonly captures: readonly {
+        readonly target: CaptureTarget
+        readonly result: CaptureResult
+      }[]
+    }
+  | ContentRefused
+  | {
+      readonly ok: false
+      readonly reason: 'no-server' | 'capture-failed'
+      readonly detail: string
+    }
+
+type CaptureEngine = (typeof import('@/capture/render'))['captureSources']
+
+/** What a test stands in for, which the command never passes. */
+export interface CaptureDeps {
+  readonly start?: (root: string, options: CanvasOptions) => CanvasOutcome
+  readonly capture?: CaptureEngine
+}
+
+/**
+ * Serves the canvas for the length of the call and captures through it, so the
+ * run needs no `canon canvas serve` and still never reads the raw file. The
+ * port is whatever is free, which keeps it clear of a canvas already running.
+ * An error the engine throws, such as a browser that will not launch, comes
+ * back as `capture-failed` rather than escaping, so a caller reading the record
+ * can tell it from a root that is wrong.
+ */
+export async function captureCanvas(
+  root: string,
+  spec: string,
+  out?: string,
+  deps: CaptureDeps = {},
+): Promise<CaptureOutcome> {
+  /*
+   * Refused before the server starts, since starting it creates the canvas
+   * folder and a refused capture should leave the project as it found it.
+   */
+  const early = resolveCaptureTargets(root, spec, '')
+  if (!early.ok) return early
+
+  const start = deps.start ?? startCanvas
+  const server = start(root, { port: 0, shell: new Response('') })
+  if (!server.ok) {
+    return {
+      ok: false,
+      reason: 'no-server',
+      detail: `${server.detail}, so run canon canvas serve and capture again`,
+    }
+  }
+
+  try {
+    const resolved = resolveCaptureTargets(root, spec, server.url, out)
+    if (!resolved.ok) return resolved
+
+    const capture =
+      deps.capture ?? (await import('@/capture/render')).captureSources
+    const captures: { target: CaptureTarget; result: CaptureResult }[] = []
+    for (const target of resolved.targets) {
+      const [result] = await capture(target.url, {
+        selector: CAPTURE_SELECTOR,
+        width: target.width,
+        outDir: target.pngPath,
+      })
+      if (result) captures.push({ target, result })
+    }
+    return { ok: true, captures }
+  } catch (error) {
+    return {
+      ok: false,
+      reason: 'capture-failed',
+      detail: error instanceof Error ? error.message : String(error),
+    }
+  } finally {
+    await server.stop()
+  }
+}

package/src/canvas/client/app.tsx

@@ -0,0 +1,87 @@
+/** @jsxImportSource preact */
+import type { JSX } from 'preact'
+import { useRef } from 'preact/hooks'
+import { Inspector } from '@/canvas/client/inspector'
+import { PagesPanel } from '@/canvas/client/pages-panel'
+import { currentPage, focusFrame, tokens } from '@/canvas/client/state'
+import { Surface } from '@/canvas/client/surface'
+
+const SOURCE_LABEL = {
+  toolkit: 'This toolkit',
+  installed: 'Installed design',
+  none: 'None',
+} as const
+
+function TokenDetails(): JSX.Element | null {
+  const value = tokens.value
+  if (!value) return null
+  return (
+    <section aria-labelledby="tokens-heading">
+      <h2 id="tokens-heading" class="section-label">
+        Tokens
+      </h2>
+      <p class="detail">{SOURCE_LABEL[value.source]}</p>
+      {value.files && value.files.length > 0 ? (
+        <ul class="files">
+          {value.files.map((file) => (
+            <li key={file} title={file}>
+              <code>{file}</code>
+            </li>
+          ))}
+        </ul>
+      ) : null}
+      {value.notice ? <p class="notice">{value.notice}</p> : null}
+    </section>
+  )
+}
+
+function PageDetails(): JSX.Element | null {
+  const page = currentPage.value
+  if (!page) return null
+  const unplaced = page.frames.filter((frame) => !frame.placed).length
+  return (
+    <section aria-labelledby="page-heading">
+      <h2 id="page-heading" class="section-label">
+        Page
+      </h2>
+      <p class="detail" title={page.name}>
+        {page.name}
+      </p>
+      <p class="detail-meta">
+        {page.frames.length} {page.frames.length === 1 ? 'frame' : 'frames'}
+      </p>
+      {unplaced > 0 ? (
+        <p class="notice">
+          {unplaced} {unplaced === 1 ? 'frame has' : 'frames have'} no box in
+          layout.json and sit in a default row.
+        </p>
+      ) : null}
+      {page.layoutIssue === 'malformed' ? (
+        <p class="notice" role="alert">
+          layout.json does not parse, so every frame sits in a default row. Fix
+          the file to restore their places.
+        </p>
+      ) : null}
+    </section>
+  )
+}
+
+export function App(): JSX.Element {
+  const viewportRef = useRef<HTMLDivElement>(null)
+  return (
+    <div class="shell">
+      <PagesPanel
+        onFocusFrame={(frame) => {
+          const rect = viewportRef.current?.getBoundingClientRect()
+          focusFrame(frame, rect?.width ?? 0, rect?.height ?? 0)
+        }}
+      />
+      <Surface viewportRef={viewportRef} />
+      <aside class="panel panel-right" aria-label="Details">
+        <Inspector />
+        <PageDetails />
+        <TokenDetails />
+      </aside>
+    </div>
+  )
+}

package/src/canvas/client/inspector.tsx

@@ -0,0 +1,121 @@
+/** @jsxImportSource preact */
+import type { JSX } from 'preact'
+import { elementAt } from '@/canvas/address'
+import {
+  currentPage,
+  frameDocuments,
+  frameKey,
+  selectedElement,
+  selectedFrame,
+  writeError,
+} from '@/canvas/client/state'
+
+const FIELDS = ['x', 'y', 'width', 'height'] as const
+
+interface Row {
+  readonly name: string
+  readonly value: string
+}
+
+/**
+ * The computed values the browser settled on, which is what the operator sees
+ * rather than what any one stylesheet states.
+ */
+function styleRows(element: Element): Row[] {
+  const rect = element.getBoundingClientRect()
+  const view = element.ownerDocument.defaultView
+  const style = view?.getComputedStyle(element)
+  const rows: Row[] = [
+    { name: 'x', value: String(Math.round(rect.left)) },
+    { name: 'y', value: String(Math.round(rect.top)) },
+    { name: 'width', value: String(Math.round(rect.width)) },
+    { name: 'height', value: String(Math.round(rect.height)) },
+  ]
+  if (!style) return rows
+  return [
+    ...rows,
+    { name: 'color', value: style.color },
+    { name: 'background', value: style.backgroundColor },
+    { name: 'font', value: style.fontFamily },
+    { name: 'size', value: style.fontSize },
+    { name: 'weight', value: style.fontWeight },
+  ]
+}
+
+function elementName(element: Element): string {
+  const tag = element.tagName.toLowerCase()
+  return [tag, ...element.classList].join('.')
+}
+
+/** Read-only in this slice, since editing an element is the edit slice's work. */
+function ElementDetails(): JSX.Element | null {
+  const picked = selectedElement.value
+  const page = currentPage.value
+  if (!picked || !page) return null
+  const { frame, element } = picked
+  const doc = frameDocuments.value.get(frameKey(page.name, frame))
+  const node = doc && !element.stale ? elementAt(doc, element) : undefined
+
+  return (
+    <section aria-label="Element">
+      <h2 class="section-label">Element</h2>
+      {element.stale ? (
+        <p class="notice">
+          The frame changed since this element was picked, so its index may name
+          another element now. Pick it again.
+        </p>
+      ) : node ? (
+        <>
+          <p class="detail" title={elementName(node)}>
+            {elementName(node)}
+          </p>
+          <dl class="box styles">
+            {styleRows(node).map((row) => (
+              <div key={row.name} class="box-row">
+                <dt>{row.name}</dt>
+                <dd title={row.value}>{row.value}</dd>
+              </div>
+            ))}
+          </dl>
+        </>
+      ) : (
+        <p class="empty">Loading the frame to read this element</p>
+      )}
+    </section>
+  )
+}
+
+/** Read-only in this slice, since editing a box is the edit slice's work. */
+export function Inspector(): JSX.Element {
+  const frame = selectedFrame.value
+  return (
+    <>
+      <section aria-label="Frame">
+        <h2 class="section-label">Frame</h2>
+        {frame ? (
+          <>
+            <p class="detail" title={frame.name}>
+              {frame.name}
+            </p>
+            <dl class="box">
+              {FIELDS.map((field) => (
+                <div key={field} class="box-row">
+                  <dt>{field}</dt>
+                  <dd>{frame[field]}</dd>
+                </div>
+              ))}
+            </dl>
+          </>
+        ) : (
+          <p class="empty">Select a frame to see its box</p>
+        )}
+        {writeError.value ? (
+          <p class="notice" role="alert">
+            {writeError.value}
+          </p>
+        ) : null}
+      </section>
+      <ElementDetails />
+    </>
+  )
+}