@erclx/canon 5.18.0 → 5.20.0

package/src/canvas/capture.ts

@@ -1,6 +1,12 @@
-import { join } from 'node:path'
+import { mkdirSync, rmSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
 import type { CaptureResult } from '@/capture/render'
-import { type ContentRefused, type Frame, readPage } from '@/canvas/content'
+import {
+  type ContentRefused,
+  canvasDir,
+  type Frame,
+  readPage,
+} from '@/canvas/content'
 import {
   type CanvasOptions,
   type CanvasOutcome,
@@ -134,6 +140,34 @@ export async function captureCanvas(
   const early = resolveCaptureTargets(root, spec, '')
   if (!early.ok) return early
 
+  return serveFor(root, deps, async (base, capture) => {
+    const resolved = resolveCaptureTargets(root, spec, base, out)
+    if (!resolved.ok) return resolved
+
+    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 }
+  })
+}
+
+type ServeRefused = {
+  readonly ok: false
+  readonly reason: 'no-server' | 'capture-failed'
+  readonly detail: string
+}
+
+async function serveFor<T>(
+  root: string,
+  deps: CaptureDeps,
+  run: (base: string, capture: CaptureEngine) => Promise<T>,
+): Promise<T | ServeRefused> {
   const start = deps.start ?? startCanvas
   const server = start(root, { port: 0, shell: new Response('') })
   if (!server.ok) {
@@ -145,21 +179,9 @@ export async function captureCanvas(
   }
 
   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 }
+    return await run(server.url, capture)
   } catch (error) {
     return {
       ok: false,
@@ -170,3 +192,194 @@ export async function captureCanvas(
     await server.stop()
   }
 }
+
+/** The element a composite is captured by, holding every frame and no chrome. */
+export const COMPOSITE_SELECTOR = '#canvas-composite'
+
+/**
+ * The container holds no text, so its family exists only for the engine's
+ * font probe, which rejects a family the machine lacks. The browser default is
+ * Times New Roman, which a Linux runner often lacks, and `system-ui` is the one
+ * every platform maps. Each frame keeps its own fonts inside its iframe.
+ */
+const COMPOSITE_FONT = 'system-ui'
+
+export interface Placement {
+  readonly frame: string
+  readonly url: string
+  readonly left: number
+  readonly top: number
+  readonly width: number
+  readonly height: number
+}
+
+export interface Composite {
+  readonly placements: readonly Placement[]
+  readonly width: number
+  readonly height: number
+  readonly html: string
+}
+
+/**
+ * One document showing every frame of a page at its layout position. Offsets
+ * run from the top left of the union of the boxes, so a negative coordinate
+ * never clips and a lone frame fills the container exactly. Each iframe takes
+ * its box, so a document taller than its frame clips as it does on the board,
+ * and frames paint in the order given, which is the board's.
+ */
+export function buildComposite(
+  page: string,
+  frames: readonly Frame[],
+  base: string,
+): Composite {
+  const left = Math.min(...frames.map((frame) => frame.x))
+  const top = Math.min(...frames.map((frame) => frame.y))
+  const right = Math.max(...frames.map((frame) => frame.x + frame.width))
+  const bottom = Math.max(...frames.map((frame) => frame.y + frame.height))
+  const width = right - left
+  const height = bottom - top
+
+  const placements = frames.map((frame) => ({
+    frame: frame.name,
+    url: frameUrl(base, page, frame),
+    left: frame.x - left,
+    top: frame.y - top,
+    width: frame.width,
+    height: frame.height,
+  }))
+
+  const iframes = placements.map(
+    (p) =>
+      `<iframe title="${escapeAttribute(p.frame)}" src="${escapeAttribute(p.url)}" style="left:${p.left}px;top:${p.top}px;width:${p.width}px;height:${p.height}px"></iframe>`,
+  )
+  const html = [
+    '<!doctype html>',
+    '<html><head><meta charset="utf-8">',
+    `<style>html,body{margin:0;background:transparent}#canvas-composite{position:relative;font-family:${COMPOSITE_FONT}}#canvas-composite iframe{position:absolute;display:block;border:0;background:transparent}</style>`,
+    '</head><body>',
+    `<div id="canvas-composite" style="width:${width}px;height:${height}px">`,
+    ...iframes,
+    '</div></body></html>',
+    '',
+  ].join('\n')
+
+  return { placements, width, height, html }
+}
+
+function escapeAttribute(value: string): string {
+  return value.replaceAll('&', '&amp;').replaceAll('"', '&quot;')
+}
+
+/**
+ * Where the generated document is served from, inside the canvas folder so it
+ * shares the frames' origin. Chromium skips painting a cross-origin iframe
+ * outside the viewport, and the engine's viewport is 720 pixels tall, so a
+ * document on another origin captured every frame below that line blank. A dot
+ * folder is no page name, so the board never lists it.
+ */
+const COMPOSITE_FOLDER = '.composite'
+
+export interface CompositeTarget {
+  readonly page: string
+  readonly composite: Composite
+  readonly htmlPath: string
+  /** The served address of the document at `htmlPath`. */
+  readonly url: string
+  readonly pngPath: string
+}
+
+export type CompositeTargetOutcome =
+  | { readonly ok: true; readonly target: CompositeTarget }
+  | ContentRefused
+
+/**
+ * Turns `<page>` into one composite. `out` is the PNG, and without it the PNG
+ * lands at `<page>.png` beside the per-frame folder of the same name, so the
+ * two captures of one page never collide.
+ */
+export function resolveCompositeTarget(
+  root: string,
+  spec: string,
+  base: string,
+  out?: string,
+): CompositeTargetOutcome {
+  if (spec.includes('/')) {
+    return refuse(
+      'invalid-name',
+      `--composite takes a page, not ${spec}, so capture <page> or drop the flag`,
+    )
+  }
+
+  const page = readPage(root, spec)
+  if (!page) return refuse('no-page', `page ${spec} does not exist`)
+  if (page.frames.length === 0) {
+    return refuse('no-frame', `page ${spec} has no frames`)
+  }
+
+  const file = `${spec}.html`
+  return {
+    ok: true,
+    target: {
+      page: spec,
+      composite: buildComposite(spec, page.frames, base),
+      htmlPath: join(canvasDir(root), COMPOSITE_FOLDER, file),
+      url: `${base}${FRAMES_PREFIX.slice(1)}${COMPOSITE_FOLDER}/${encodeURIComponent(file)}`,
+      pngPath:
+        out ?? join(recordDir(root, 'tmp', 'canvas-capture'), `${spec}.png`),
+    },
+  }
+}
+
+export type CompositeOutcome =
+  | {
+      readonly ok: true
+      readonly composite: {
+        readonly target: CompositeTarget
+        readonly result: CaptureResult
+      }
+    }
+  | ContentRefused
+  | ServeRefused
+
+/**
+ * Captures a page as one PNG through the served canvas, the way `captureCanvas`
+ * captures each frame. The viewport is the container's width, so no frame's
+ * media query resolves against a window narrower than the frame itself. The
+ * page load the engine waits on waits on every iframe.
+ */
+export async function captureComposite(
+  root: string,
+  spec: string,
+  out?: string,
+  deps: CaptureDeps = {},
+): Promise<CompositeOutcome> {
+  const early = resolveCompositeTarget(root, spec, '')
+  if (!early.ok) return early
+
+  return serveFor(root, deps, async (base, capture) => {
+    const resolved = resolveCompositeTarget(root, spec, base, out)
+    if (!resolved.ok) return resolved
+
+    const { target } = resolved
+    mkdirSync(dirname(target.htmlPath), { recursive: true })
+    writeFileSync(target.htmlPath, target.composite.html)
+    let result: CaptureResult | undefined
+    try {
+      ;[result] = await capture(target.url, {
+        selector: COMPOSITE_SELECTOR,
+        width: target.composite.width,
+        outDir: target.pngPath,
+      })
+    } finally {
+      rmSync(target.htmlPath, { force: true })
+    }
+    if (!result) {
+      return {
+        ok: false,
+        reason: 'capture-failed',
+        detail: `the engine rendered nothing for ${spec}`,
+      }
+    }
+    return { ok: true, composite: { target, result } }
+  })
+}

package/src/claude/cases/misc.ts

@@ -84,6 +84,11 @@ export const MISC_CASES: readonly SkillCase[] = [
       'Find me the strongest evidence on whether rent control reduces housing supply. Where should I look?',
     expect: 'search-craft',
   },
+  {
+    prompt:
+      'The composed demo video looks generic and the zoom drags. What should the captions say, and how fast should the push-in be?',
+    expect: 'video-craft',
+  },
   {
     prompt:
       "I've got the plan approved and it touches the parser, the command, and the docs. How should I build it so I don't end up with one giant diff?",

package/src/claude/routing.ts

@@ -196,7 +196,7 @@ function frontmatter(text: string): string {
  *
  * A glob opening `**` reaches every folder in the tree, so it answers that a
  * file type is governed and never that a named path is. Counting one would
- * report every markdown path covered by `801-markdown` and leave the column
+ * report every markdown path covered by the markdown rule and leave the column
  * saying nothing a reader could act on.
  */
 function isAnchored(glob: string): boolean {

package/src/commands/canvas.ts

@@ -13,7 +13,7 @@ import {
   readSelection,
   renamePage,
 } from '@/canvas/content'
-import { captureCanvas } from '@/canvas/capture'
+import { captureCanvas, captureComposite } from '@/canvas/capture'
 import {
   type EditRefused,
   editFrameAtIndex,
@@ -468,6 +468,10 @@ export function register(program: Command): void {
       .option(
         '-o, --out <path>',
         'The PNG for a frame, or the folder for a page; defaults to session scratch',
+      )
+      .option(
+        '--composite',
+        'Capture a page as one PNG with every frame at its layout position; --out is then the PNG',
       ),
   )
     .addHelpText(
@@ -478,18 +482,25 @@ export function register(program: Command): void {
         'the injected tokens are in the PNG and each frame renders at its own',
         'width. The raw file on disk is never captured.',
         '',
+        'With --composite, each frame is clipped to its box as on the board and',
+        'shows in its default theme, with no captions or selection outline.',
+        '',
         'Exit codes:',
         '  0  every frame rendered',
         '  1  refused or a frame failed, with the reason on stderr or in the JSON record',
         '',
       ].join('\n'),
     )
-    .action(async (target: string, opts: RootOptions & { out?: string }) => {
+    .action(async (target: string, opts: CaptureOptions) => {
       const resolved = await resolveRoot(opts)
       if (!resolved.ok) {
         process.exitCode = refuse(resolved, opts.json ?? false)
         return
       }
+      if (opts.composite) {
+        process.exitCode = await runComposite(resolved.root, target, opts)
+        return
+      }
       let outcome: Awaited<ReturnType<typeof captureCanvas>>
       try {
         outcome = await captureCanvas(
@@ -543,6 +554,69 @@ export function register(program: Command): void {
     })
 }
 
+interface CaptureOptions extends RootOptions {
+  readonly out?: string
+  readonly composite?: boolean
+}
+
+async function runComposite(
+  root: string,
+  target: string,
+  opts: CaptureOptions,
+): Promise<number> {
+  const emitJson = opts.json ?? false
+  let outcome: Awaited<ReturnType<typeof captureComposite>>
+  try {
+    outcome = await captureComposite(
+      root,
+      target,
+      opts.out ? resolve(process.cwd(), opts.out) : undefined,
+    )
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error)
+    return refuse({ ok: false, reason: 'capture-failed', detail }, emitJson)
+  }
+  if (!outcome.ok) return refuse(outcome, emitJson)
+
+  const { target: item, result } = outcome.composite
+  if (result.status === 'failed') {
+    if (emitJson) {
+      writeJson({
+        ok: false,
+        composite: {
+          page: item.page,
+          status: result.status,
+          reason: result.reason,
+        },
+      })
+    }
+    intro(BANNER)
+    logError(`${item.page}: ${result.reason}`)
+    outro()
+    return 1
+  }
+
+  if (emitJson) {
+    writeJson({
+      ok: true,
+      composite: {
+        page: item.page,
+        status: result.status,
+        path: result.pngPath,
+        width: result.width,
+        height: result.height,
+      },
+    })
+  }
+  intro(BANNER)
+  logAdd(
+    `${item.page} composite of ${plural(item.composite.placements.length, 'frame')}`,
+  )
+  logInfo(`${displayPath(result.pngPath)} ${result.width}x${result.height}`)
+  outro()
+  return 0
+}
+
 /** NaN for a value that is not a number, which the content module refuses. */
 function parsePosition(raw: string | undefined, fallback: number): number {
   if (raw === undefined) return fallback

package/src/commands/gov.ts

@@ -12,6 +12,7 @@ import { checkoutMismatchWarning, PROJECT_ROOT } from '@/project-root'
 import { creationRel, SCRATCH } from '@/record-root'
 import { createGovAdapter } from '@/gov/adapter'
 import { regenConsumedRules } from '@/gov/consumed'
+import { regenStandardRules } from '@/gov/standard-rules'
 import { installRules, lookupRules } from '@/gov/install'
 import { buildGovCatalog, describeRule, describeStack } from '@/gov/list'
 import { buildRulesPayload, listRuleFiles } from '@/gov/payload'
@@ -190,15 +191,19 @@ export function register(program: Command): void {
 
   gov
     .command('regen')
-    .description("Rebuild a repository's own .claude/rules/ from its record")
+    .description(
+      "Rebuild the standard-pointer rules and a repository's own .claude/rules/",
+    )
     .helpOption('-h, --help', 'Show this help message')
     .option('--root <path>', 'Repository root to regenerate', PROJECT_ROOT)
     .addHelpText(
       'after',
       [
         '',
-        'Reads internal/governance.toml and installs the stack it names, plus',
-        'any rules under internal/rules/. Unlike install and sync, this runs',
+        'First writes governance/rules/standards/ from the paths: and rule:',
+        'fields in each standard under standards/. Then reads',
+        'internal/governance.toml and installs the stack it names, plus any',
+        'rules under internal/rules/. Unlike install and sync, this runs',
         'against the toolkit root, whose .claude/rules/ is produced output.',
         '',
       ].join('\n'),
@@ -1114,7 +1119,17 @@ async function runRegen(
     if (mismatch !== undefined) logWarn(mismatch)
   }
 
-  const result = await regenConsumedRules(resolve(opts.root ?? PROJECT_ROOT))
+  const root = resolve(opts.root ?? PROJECT_ROOT)
+
+  // The consumed copy installs from `governance/rules/`, so the band this
+  // writes has to be fresh before that copy is built from it.
+  const generated = await regenStandardRules(root)
+  if (!generated.ok) {
+    process.stderr.write(`Standard-rules regen failed: ${generated.reason}\n`)
+    return 1
+  }
+
+  const result = await regenConsumedRules(root)
 
   if (!result.ok) {
     process.stderr.write(`Consumed-rules regen failed: ${result.reason}\n`)

package/src/commands/sandbox.ts

@@ -346,6 +346,7 @@ function runCoverage(options: CoverageOptions): void {
 interface EquivalenceOptions {
   readonly base: string
   readonly includeAnchor?: boolean
+  readonly stubRemote?: boolean
   readonly out?: string
   readonly masks: boolean
   readonly json?: boolean
@@ -372,6 +373,7 @@ async function runEquivalence(
       targets,
       base: options.base,
       includeAnchor: options.includeAnchor === true,
+      stubRemote: options.stubRemote === true,
       useMasks: options.masks,
       out: options.out,
     })
@@ -568,6 +570,10 @@ export function register(program: Command): void {
       '--include-anchor',
       'Also run the arms that push to the shared GitHub anchor, one at a time (attended)',
     )
+    .option(
+      '--stub-remote',
+      'Run the anchor arms against a local bare repository and a stub gh, writing nothing to the shared anchor',
+    )
     .option('--out <dir>', 'Keep the provisioned trees and logs in this folder')
     .option(
       '--no-masks',
@@ -583,6 +589,7 @@ export function register(program: Command): void {
         '  canon sandbox equivalence claude:plan-feature --base origin/main',
         '',
         'Provisions offline only and never runs sandbox/run.sh or a claude binary.',
+        '--stub-remote also runs the anchor arms, and wins over --include-anchor.',
         'Exit codes: 0 when every compared arm is identical or red the same way',
         'on both sides, 1 on any difference, exit mismatch, or enumeration error.',
       ].join('\n'),

package/src/commands/slides.ts

@@ -1,6 +1,7 @@
-import { existsSync } from 'node:fs'
+import { existsSync, statSync } from 'node:fs'
 import { resolve } from 'node:path'
 import type { Command } from 'commander'
+import { INSTALL_BROWSER } from '@/browser/engine'
 import { creationRel, SCRATCH } from '@/record-root'
 import { LAYOUTS } from '@/slides/layouts'
 import { openDeck } from '@/slides/open'
@@ -17,8 +18,14 @@ export function register(program: Command): void {
   slides
     .command('render')
     .helpOption('-h, --help', 'Show this help message')
-    .description('Render a SLIDES.md source into a PowerPoint deck')
-    .option('-s, --source <path>', 'Source SLIDES.md path', '.claude/SLIDES.md')
+    .description(
+      'Render a SLIDES.md source, or a folder of HTML slides, into a PowerPoint deck',
+    )
+    .option(
+      '-s, --source <path>',
+      'Source SLIDES.md file, or a folder of .html slides read in filename order',
+      '.claude/SLIDES.md',
+    )
     .option(
       '-o, --out <path>',
       'Output directory',
@@ -44,8 +51,15 @@ export function register(program: Command): void {
           if (!existsSync(sourcePath)) {
             fail(`${opts.source} not found`)
           }
-          const variant = parseVariant(opts.variant)
           const mirror = resolveMirror(opts.mirror)
+          if (statSync(sourcePath).isDirectory()) {
+            if (opts.variant !== undefined) {
+              fail('--variant applies to a SLIDES.md source, not a folder')
+            }
+            await renderHtmlFolder(sourcePath, outDir, mirror, opts.open)
+            return
+          }
+          const variant = parseVariant(opts.variant)
           const { GREEN, GREY, NC, RED } = palette(process.stderr)
           intro('Render slides')
           const result = await renderSlidesDoc(sourcePath, outDir, {
@@ -103,6 +117,61 @@ export function register(program: Command): void {
     })
 }
 
+/**
+ * The converter loads on demand, so no other command resolves pptxgenjs,
+ * jszip, or the token module at startup. A fallback or a refused link reports
+ * one line each and keeps the exit at 0, as an unrecognized layout does on the
+ * markdown path, since the deck is written either way.
+ */
+async function renderHtmlFolder(
+  sourceDir: string,
+  outDir: string,
+  mirror: string | undefined,
+  shouldOpen: boolean | undefined,
+): Promise<void> {
+  const { exportHtmlDeck } = await import('@/slides/convert/export')
+  const { GREEN, GREY, NC, RED } = palette(process.stderr)
+  const result = await exportHtmlDeck(sourceDir, outDir, {
+    root: process.cwd(),
+    mirror,
+  })
+  if (result.status === 'refused') {
+    fail(
+      result.reason === 'browser-missing'
+        ? `Chromium is not installed. Run ${INSTALL_BROWSER}`
+        : result.message,
+    )
+  }
+  intro('Render slides')
+  process.stderr.write(
+    `${GREY}│${NC} ${GREEN}✓${NC} ${result.slideCount} slides\n${GREY}│${NC} ${GREEN}✓${NC} ${result.pptxPath}\n`,
+  )
+  for (const { slide, selector, properties } of result.fallbacks) {
+    process.stderr.write(
+      `${GREY}│${NC} ${RED}✗${NC} slide ${slide} ${selector} drawn as a picture for ${properties.join(', ')}\n`,
+    )
+  }
+  for (const { slide, selector, href, reason } of result.refusedLinks) {
+    process.stderr.write(
+      `${GREY}│${NC} ${RED}✗${NC} slide ${slide} ${selector} link "${href}" left out: ${reason}\n`,
+    )
+  }
+  if (result.mirrorPath) {
+    process.stderr.write(
+      `${GREY}│${NC} ${GREEN}✓${NC} mirrored to ${result.mirrorPath}\n`,
+    )
+  }
+  if (shouldOpen) {
+    const target = result.mirrorPath ?? result.pptxPath
+    const opened = await openDeck(target)
+    const mark = opened ? `${GREEN}✓${NC}` : `${RED}✗${NC}`
+    process.stderr.write(
+      `${GREY}│${NC} ${mark} ${opened ? 'opened' : 'could not open'} ${target}\n`,
+    )
+  }
+  outro()
+}
+
 function parseVariant(value: string | undefined): Variant | undefined {
   if (value === undefined) return undefined
   if (value === 'light' || value === 'dark') return value