@erclx/canon 5.69.0 → 5.70.0

package/scripts/core/design-sync.ts

@@ -0,0 +1,204 @@
+/**
+ * Lands the board's accepted designs in canon/design/: each frame
+ * canon/design/frames.json maps, as its HTML beside a PNG per theme, captured
+ * through Frameboard's own `capture` verb from the design board at the main
+ * worktree's .canon/board, plus a copy of every project asset those frames
+ * load under kit/<project>/assets/. `--check` writes nothing and exits 1
+ * when the folder differs from what a sync would write.
+ *
+ * Ported from Frameboard's own scripts/design-sync.ts. Its frames load a
+ * shared kit and it formats each HTML through oxfmt, while this board's frames
+ * load their project's ../assets/ and the formatter ignores canon/design/, so
+ * the asset handling is the one part that differs. The pure half sits in
+ * `src/design/reference.ts`, where tsc and vitest reach it.
+ *
+ * Frameboard runs through bunx at a pinned version rather than as a
+ * devDependency, since only a session holding the board runs this script.
+ *
+ * Clone-only. This script reads the gitignored board, which neither a
+ * registry install nor CI carries.
+ */
+import {
+  mkdirSync,
+  mkdtempSync,
+  readdirSync,
+  readFileSync,
+  rmdirSync,
+  rmSync,
+  writeFileSync,
+} from 'node:fs'
+import { tmpdir } from 'node:os'
+import { dirname, join, relative } from 'node:path'
+
+import {
+  boardAssets,
+  classifyDrift,
+  MappingError,
+  missingFrames,
+  parseFrameMap,
+  toReference,
+} from '../../src/design/reference'
+
+type Output = Map<string, string | Buffer>
+
+interface Envelope<T> {
+  ok: boolean
+  data?: T
+  error?: { code: string; message: string }
+}
+
+interface Listing {
+  projects: { pages: { frames: { ref: string; path: string }[] }[] }[]
+}
+
+interface Capture {
+  images: { theme: string; path: string }[]
+}
+
+class SyncRefused extends Error {}
+
+const FRAMEBOARD = 'frameboard@0.14.0'
+const ROOT = join(import.meta.dirname, '..', '..')
+const DESIGN = join(ROOT, 'canon', 'design')
+const MAPPING = join(DESIGN, 'frames.json')
+const OWN_FILES = new Set(['index.md', 'frames.json'])
+
+/** The main worktree, which holds the gitignored board every worktree reads. */
+function mainRoot(): string {
+  const run = Bun.spawnSync(['git', 'worktree', 'list', '--porcelain'], {
+    cwd: ROOT,
+  })
+  const line = run.stdout
+    .toString()
+    .split('\n')
+    .find((l) => l.startsWith('worktree '))
+  return line ? line.slice('worktree '.length) : ROOT
+}
+
+function frameboard<T>(args: string[]): T {
+  const run = Bun.spawnSync(['bunx', '-y', FRAMEBOARD, ...args, '--json'])
+  let record: Envelope<T>
+  try {
+    record = JSON.parse(run.stdout.toString()) as Envelope<T>
+  } catch {
+    throw new SyncRefused(`frameboard ${args[0]} printed no record.`)
+  }
+  if (!record.ok || !record.data) {
+    throw new SyncRefused(
+      `frameboard ${args[0]} refused: ${record.error?.message ?? run.stderr.toString()}`,
+    )
+  }
+  return record.data
+}
+
+function trackedFiles(): string[] {
+  return readdirSync(DESIGN, { recursive: true, withFileTypes: true })
+    .filter((entry) => entry.isFile())
+    .map((entry) => relative(DESIGN, join(entry.parentPath, entry.name)))
+    .filter((path) => !OWN_FILES.has(path))
+}
+
+function pruneEmptyDirs(dir: string): void {
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    if (entry.isDirectory()) pruneEmptyDirs(join(dir, entry.name))
+  }
+  if (dir !== DESIGN && readdirSync(dir).length === 0) rmdirSync(dir)
+}
+
+function readAsset(board: string, project: string, asset: string): Buffer {
+  try {
+    return readFileSync(join(board, project, 'assets', asset))
+  } catch {
+    throw new SyncRefused(
+      `No board asset ${project}/assets/${asset}. Nothing written.`,
+    )
+  }
+}
+
+function run(check: boolean): number {
+  const map = parseFrameMap(readFileSync(MAPPING, 'utf8'))
+  const board = join(mainRoot(), '.canon', 'board')
+
+  const listing = frameboard<Listing>(['list', '--root', board])
+  const paths = new Map(
+    listing.projects
+      .flatMap((project) => project.pages)
+      .flatMap((page) => page.frames)
+      .map((frame) => [frame.ref, frame.path]),
+  )
+  const missing = missingFrames(map, new Set(paths.keys()))
+  if (missing.length > 0) {
+    throw new SyncRefused(
+      `No board frame for: ${missing.join(', ')}. Nothing written.`,
+    )
+  }
+
+  const output: Output = new Map()
+  const captures = mkdtempSync(join(tmpdir(), 'design-sync-'))
+  try {
+    for (const [reference, ref] of map) {
+      const [project = ''] = ref.split('/')
+      const html = readFileSync(paths.get(ref) ?? '', 'utf8')
+      output.set(`${reference}.html`, toReference(html, project))
+      for (const asset of boardAssets(html)) {
+        output.set(
+          join('kit', project, 'assets', asset),
+          readAsset(board, project, asset),
+        )
+      }
+      const { images } = frameboard<Capture>([
+        'capture',
+        ref,
+        '--root',
+        board,
+        '--out',
+        captures,
+      ])
+      for (const image of images) {
+        output.set(`${reference}-${image.theme}.png`, readFileSync(image.path))
+      }
+    }
+  } finally {
+    rmSync(captures, { recursive: true, force: true })
+  }
+
+  if (check) {
+    const tracked = new Map<string, string | Buffer>()
+    for (const path of trackedFiles()) {
+      tracked.set(path, readFileSync(join(DESIGN, path)))
+    }
+    const drift = classifyDrift(output, tracked)
+    for (const path of drift.changed) console.error(`Changed: ${path}`)
+    for (const path of drift.missing) console.error(`Missing: ${path}`)
+    for (const path of drift.stray) console.error(`Stray: ${path}`)
+    for (const path of drift.pngDiffers) {
+      console.error(`Warning: PNG bytes differ: ${path}`)
+    }
+    const owed =
+      drift.changed.length + drift.missing.length + drift.stray.length
+    if (owed === 0) console.log('canon/design/ matches the board.')
+    return owed === 0 ? 0 : 1
+  }
+
+  for (const [path, data] of output) {
+    mkdirSync(dirname(join(DESIGN, path)), { recursive: true })
+    writeFileSync(join(DESIGN, path), data)
+  }
+  for (const path of trackedFiles()) {
+    if (!output.has(path)) rmSync(join(DESIGN, path))
+  }
+  pruneEmptyDirs(DESIGN)
+  console.log(`Wrote ${output.size} files to canon/design/.`)
+  return 0
+}
+
+try {
+  process.exitCode = run(process.argv.includes('--check'))
+} catch (error) {
+  console.error(
+    error instanceof SyncRefused || error instanceof MappingError
+      ? error.message
+      : error,
+  )
+  process.exitCode = 1
+}

package/scripts/core/regen-web-favicon.ts

@@ -1,23 +1,30 @@
 /**
- * Writes web/public/favicon.svg from assets/brand/mark.svg and the favicon's
- * own colors in src/design/favicon.ts, apart from the page accent tokens.
+ * Writes web/public/favicon.svg and the README's `mark-color` pair from
+ * assets/brand/mark.svg and the mark's own colors in src/design/favicon.ts,
+ * apart from the page accent tokens.
  *
- * The page is the fourth surface to carry the mark as a favicon and the only
- * one that can answer for itself. `regen-hero.ts` and `src/design/render.ts`
- * each bake a single literal, because both embed the mark as a data URI and a
- * data URI has no CSS context. A file served at its own URL does have one, so
- * this copy carries a `prefers-color-scheme` branch and tracks the reader's
- * theme rather than picking one accent for everybody.
+ * The favicon is served at its own URL, so it has a CSS context and carries a
+ * `prefers-color-scheme` branch over its tile, c, and pip. The README pair is
+ * loaded as an image behind a `<picture>`, which picks the file by theme, so
+ * each copy bakes its fills. Its c takes GitHub's own text color rather than
+ * canon's ink, since GitHub's ground is what it has to clear.
  *
  * `web/public/favicon.svg` was a symlink to the source before this, and the
  * source fills `currentColor`, which resolves to black with no CSS context.
  * That is what painted the tab icon black on every surface the page reaches.
- * The source keeps `currentColor`, since the hero topbar embeds the same file
- * inline and wants it to inherit.
+ * The source keeps `currentColor`, since the nav and the hero topbar inline it
+ * and want it to inherit.
  */
 import { writeFileSync } from 'node:fs'
 
-import { FAVICON_COLORS, renderFavicon } from '../../src/design/favicon'
+import {
+  FAVICON_COLORS,
+  renderFavicon,
+  renderMark,
+} from '../../src/design/favicon'
+
+/** GitHub's default foreground on its dark and light grounds. */
+const GITHUB_TEXT = { light: '#1f2328', dark: '#f0f6fc' }
 
 const root = new URL('../..', import.meta.url).pathname
 
@@ -31,6 +38,14 @@ writeFileSync(
   `${root}web/public/favicon.svg`,
   renderFavicon(mark, FAVICON_COLORS),
 )
+writeFileSync(
+  `${root}assets/brand/mark-color.svg`,
+  renderMark(mark, { c: GITHUB_TEXT.dark, pip: FAVICON_COLORS.pip.dark }),
+)
+writeFileSync(
+  `${root}assets/brand/mark-color-light.svg`,
+  renderMark(mark, { c: GITHUB_TEXT.light, pip: FAVICON_COLORS.pip.light }),
+)
 console.log(
-  `regen-web-favicon: wrote web/public/favicon.svg (${FAVICON_COLORS.light} / ${FAVICON_COLORS.dark})`,
+  `regen-web-favicon: wrote web/public/favicon.svg and assets/brand/mark-color{,-light}.svg (pip ${FAVICON_COLORS.pip.dark} / ${FAVICON_COLORS.pip.light})`,
 )

package/scripts/core/regen-web-previews.ts

@@ -8,6 +8,7 @@
  * `<main>`.
  */
 import { readFileSync } from 'node:fs'
+import { FAVICON_COLORS, renderFavicon } from '@/design/favicon'
 import { DESIGN_DOCUMENT } from '@/design/regen'
 import { renderDesignDoc } from '@/design/render'
 
@@ -16,7 +17,13 @@ const root = new URL('../..', import.meta.url).pathname
 const { cssPath } = renderDesignDoc(
   `${root}${DESIGN_DOCUMENT}`,
   `${root}web/public/previews/design-tokens`,
-  { embedFonts: true },
+  {
+    embedFonts: true,
+    favicon: renderFavicon(
+      readFileSync(`${root}assets/brand/mark.svg`, 'utf8'),
+      FAVICON_COLORS,
+    ),
+  },
 )
 
 const css = readFileSync(cssPath, 'utf8')

package/scripts/core/render-film.ts

@@ -0,0 +1,179 @@
+/**
+ * Renders the launch film in assets/film/ once per theme and writes the
+ * README loops to assets/loops/launch.gif and launch-light.gif, and beside
+ * them the landing page's web MP4 and poster PNG per theme.
+ *
+ * Each theme renders to an MP4 at the canvas size under assets/film/renders/,
+ * which git ignores, and the GIF comes from that MP4 through the ffmpeg pass
+ * `assets/film/SPEC.md` gives, since no render preset scales below the canvas.
+ * Every output is written to the renders folder first and copied into
+ * assets/loops/ only once both themes exist, so a failed theme leaves the
+ * committed set as it was rather than a half set.
+ *
+ * The web MP4 drops every audio stream with `-an` whatever the source
+ * carries, since the repository is public and no music track's terms are
+ * cleared for use outside the tool that made it.
+ *
+ * Run by hand, not by the gate. The film shows one merged change, so no
+ * catalog edit makes it stale, and a render costs minutes of chromium.
+ *
+ * Clone-only. This script reads assets/film/, which a registry install does
+ * not carry.
+ */
+import { copyFileSync, mkdirSync } from 'node:fs'
+import { join } from 'node:path'
+
+const HYPERFRAMES = 'hyperframes@0.8.206'
+
+/** The README pass from SPEC.md: 960x600 at 12 fps with a 64-color palette. */
+const GIF_FILTER =
+  'fps=12,scale=960:600:flags=lanczos,split[a][b];[a]palettegen=max_colors=64:stats_mode=diff[p];[b][p]paletteuse=dither=none:diff_mode=rectangle'
+
+/** The landing page pass: 1280 wide, silent, and playable before it finishes downloading. */
+const WEB_ARGS = [
+  '-an',
+  '-vf',
+  'scale=1280:-2:flags=lanczos',
+  '-c:v',
+  'libx264',
+  '-pix_fmt',
+  'yuv420p',
+  '-crf',
+  '24',
+  '-preset',
+  'slow',
+  '-movflags',
+  '+faststart',
+]
+
+/** The poster frame: the mark centered before its pip leaves. */
+const POSTER_AT = '0.6'
+
+const THEMES = [
+  {
+    theme: 'dark',
+    loop: 'launch.gif',
+    web: 'launch.mp4',
+    poster: 'launch-poster.png',
+  },
+  {
+    theme: 'light',
+    loop: 'launch-light.gif',
+    web: 'launch-light.mp4',
+    poster: 'launch-poster-light.png',
+  },
+] as const
+
+const root = new URL('../..', import.meta.url).pathname
+const filmDir = join(root, 'assets', 'film')
+const renderDir = join(filmDir, 'renders')
+const loopDir = join(root, 'assets', 'loops')
+
+function fail(message: string): never {
+  console.error(`render-film: ${message}`)
+  process.exit(1)
+}
+
+function run(cmd: string[], cwd: string): void {
+  const result = Bun.spawnSync(cmd, {
+    cwd,
+    stdout: 'inherit',
+    stderr: 'inherit',
+  })
+  if (result.exitCode !== 0) {
+    fail(`${cmd.slice(0, 3).join(' ')} exited ${result.exitCode}`)
+  }
+}
+
+if (process.argv.length > 2) {
+  fail(`unknown argument ${process.argv[2]}`)
+}
+
+const ffmpeg = Bun.which('ffmpeg')
+if (!ffmpeg) {
+  fail(
+    'ffmpeg is not on PATH, and each GIF is derived with it. Install ffmpeg and re-run.',
+  )
+}
+
+mkdirSync(renderDir, { recursive: true })
+
+for (const { theme } of THEMES) {
+  const mp4 = join(renderDir, `launch-${theme}.mp4`)
+  const gif = join(renderDir, `readme-${theme}.gif`)
+  console.log(`render-film: rendering ${theme}`)
+  run(
+    [
+      'bunx',
+      '-y',
+      HYPERFRAMES,
+      'render',
+      '--variables-file',
+      `themes/${theme}.json`,
+      '--strict-variables',
+      '--quiet',
+      '--output',
+      mp4,
+    ],
+    filmDir,
+  )
+  run(
+    [
+      ffmpeg,
+      '-y',
+      '-loglevel',
+      'error',
+      '-i',
+      mp4,
+      '-vf',
+      GIF_FILTER,
+      '-loop',
+      '0',
+      gif,
+    ],
+    filmDir,
+  )
+  run(
+    [
+      ffmpeg,
+      '-y',
+      '-loglevel',
+      'error',
+      '-i',
+      mp4,
+      ...WEB_ARGS,
+      join(renderDir, `web-${theme}.mp4`),
+    ],
+    filmDir,
+  )
+  run(
+    [
+      ffmpeg,
+      '-y',
+      '-loglevel',
+      'error',
+      '-ss',
+      POSTER_AT,
+      '-i',
+      mp4,
+      '-frames:v',
+      '1',
+      '-vf',
+      'scale=1280:-2:flags=lanczos',
+      join(renderDir, `poster-${theme}.png`),
+    ],
+    filmDir,
+  )
+}
+
+mkdirSync(loopDir, { recursive: true })
+const written: string[] = []
+for (const { theme, loop, web, poster } of THEMES) {
+  copyFileSync(join(renderDir, `readme-${theme}.gif`), join(loopDir, loop))
+  copyFileSync(join(renderDir, `web-${theme}.mp4`), join(loopDir, web))
+  copyFileSync(join(renderDir, `poster-${theme}.png`), join(loopDir, poster))
+  written.push(loop, web, poster)
+}
+console.log(
+  `render-film: wrote assets/loops/${written.join(', assets/loops/')}`,
+)

package/src/capture/frame-values.ts

@@ -1,3 +1,4 @@
+import { FAVICON_COLORS, renderFavicon } from '@/design/favicon'
 import type { GovCatalog } from '@/gov/list'
 import type { StackSummary } from '@/tooling/list'
 
@@ -130,8 +131,9 @@ const indentTokens = (css: string): string =>
     .join('\n')
 
 /**
- * The frames a README serves in both themes. The hero is a landing-page frame
- * no README shows, so it stays dark.
+ * The frames rendered in both themes. No README shows the install pair now,
+ * and it stays for the landing page redesign to pick from. The hero is a
+ * landing-page frame, so it stays dark.
  */
 const LIGHT_TEMPLATES = new Set(['install.html.tmpl'])
 
@@ -156,18 +158,15 @@ function lightTokens(tokenCss: string): string {
   ].join('\n')
 }
 
-function faviconUri(markSvg: string, tokenCss: string): string {
-  const accent = tokenCss.match(/--color-accent:\s*(#[0-9a-fA-F]{3,8})/)
-  if (!accent) {
+/** The favicon the web page serves, so the hero's tab matches it rather than the accent. */
+function faviconUri(markSvg: string): string {
+  try {
+    return `data:image/svg+xml,${encodeURIComponent(renderFavicon(markSvg, FAVICON_COLORS))}`
+  } catch (error) {
     throw new FrameError(
-      'token css carries no --color-accent value, refusing to write a colorless favicon',
+      `assets/brand/mark.svg cannot be drawn as a favicon: ${error instanceof Error ? error.message : String(error)}`,
     )
   }
-  const svg = markSvg
-    .replace(/<!--[\s\S]*?-->/, '')
-    .trim()
-    .replaceAll('currentColor', accent[1])
-  return `data:image/svg+xml,${encodeURIComponent(svg)}`
 }
 
 /**
@@ -278,7 +277,8 @@ export function buildFrameValues(catalogs: FrameCatalogs): FrameValues {
     TOOLING_STACK_COUNT: String(toolingStacks.length),
     COMMAND_COUNT: String(catalogs.commandCount),
     MARK_SVG: markSvg,
-    FAVICON: faviconUri(markSvg, tokenCss),
+    MARK_PIP: FAVICON_COLORS.pip.dark,
+    FAVICON: faviconUri(markSvg),
     SKILL_ENTRIES: markup(featured(skills, FEATURED_SKILLS)),
     RULE_ENTRIES: markup(sample(deliveredRules)),
     SKILL_MORE: remaining(skills),

package/src/commands/records.ts

@@ -110,8 +110,9 @@ export function register(program: Command): void {
         '',
         'Structure, under `structure` and never in the exit:',
         "  S1 to S5 from the plan standard, read on plans, a track's README and",
-        '  numbered files, and intake clusters, plus intake-spill for content under',
-        '  a field. A record written before the criteria misses S1, so it reports alone.',
+        "  numbered files, intake clusters, and an intake folder's",
+        '  evidence/drive-log.md, plus intake-spill for content under a field.',
+        '  A record written before the criteria misses S1, so it reports alone.',
         '',
         'Refusals, read off `reason`:',
         "  no-folder     none of the kind's directories exist at either record root",

package/src/commands/sandbox.ts

@@ -25,7 +25,7 @@ import {
   type RunEnvelope,
   type Verdict,
 } from '@/sandbox/expect'
-import { runHeadless } from '@/sandbox/headless/run'
+import { runHeadless, runSettings } from '@/sandbox/headless/run'
 import { runSandbox } from '@/sandbox/provision'
 import {
   EXPECTED_FILE,
@@ -120,7 +120,12 @@ function showProvisionHelp(): void {
 }
 
 /** A run that reported nothing counts as clean, so only real signals fail. */
-const CLEAN_ENVELOPE: RunEnvelope = { isError: false, turns: 0, denials: 0 }
+const CLEAN_ENVELOPE: RunEnvelope = {
+  isError: false,
+  isTruncated: false,
+  turns: 0,
+  denials: 0,
+}
 
 interface CheckOptions {
   readonly envelope?: string
@@ -190,6 +195,8 @@ function readEnvelope(path: string | undefined): RunEnvelope | undefined {
 
     return {
       isError: parsed.is_error === true,
+      isTruncated: parsed.subtype === 'error_max_turns',
+      turnCap: Number(runSettings(process.env).maxTurns),
       turns: typeof parsed.num_turns === 'number' ? parsed.num_turns : 0,
       denials: Array.isArray(denials) ? denials.length : 0,
       reply: typeof parsed.result === 'string' ? parsed.result : undefined,