@erclx/canon 5.21.0 → 5.22.0

package/scripts/manage-sandbox.sh

@@ -190,10 +190,10 @@ provision_sandbox() {
   (cd "$SANDBOX" && configure_sandbox_git_credentials)
 }
 
-# Runs the real installer rather than copying the source tree. The two copies
-# these replaced each reimplemented an installer's selection rules, so a change
-# to what install produces left the sandbox provisioning the old shape and no
-# scenario could observe the difference.
+# Runs the real installer rather than copying the source tree. The copies these
+# replaced, for gov rules and for seeds, each reimplemented an installer's
+# selection rules, so a change to what install produces left the sandbox
+# provisioning the old shape and no scenario could observe the difference.
 run_sandbox_install() {
   local label="$1"
   shift
@@ -223,10 +223,9 @@ inject_gov_rules() {
 }
 
 inject_seeds() {
-  local seeds_source="$PROJECT_ROOT/tooling/claude/seeds"
-  if [ -d "$seeds_source" ]; then
-    cp -r "$seeds_source/." "$SANDBOX/"
-  fi
+  [ ! -d "$PROJECT_ROOT/tooling/claude/seeds" ] && return
+
+  run_sandbox_install "seeds" claude init "$SANDBOX"
 }
 
 commit_environment_setup() {

package/src/claude/cases/authoring.ts

@@ -31,7 +31,7 @@ export const AUTHORING_CASES: readonly SkillCase[] = [
   {
     prompt:
       'Write a brand-new docs page for the capture command, nothing under docs/ covers it yet.',
-    expect: 'draft-docs',
+    expect: 'draft-doc',
   },
   {
     prompt:
@@ -40,22 +40,22 @@ export const AUTHORING_CASES: readonly SkillCase[] = [
   },
   {
     prompt: 'This project has no README.md at all, write one from scratch.',
-    expect: 'draft-readme',
+    expect: 'draft-doc',
   },
   {
     prompt:
       'Write a context entry for the payments domain, there is no canon/context page for it yet.',
-    expect: 'draft-context',
+    expect: 'draft-doc',
   },
   {
     prompt:
       'Draft a wireframe for the settings panel, nothing under canon/wireframes covers that surface yet.',
-    expect: 'draft-wireframes',
+    expect: 'draft-doc',
   },
   {
     prompt:
       'Write a wiki reference page for Claude Code output styles, no page covers that subject yet.',
-    expect: 'draft-wiki',
+    expect: 'draft-doc',
   },
   {
     prompt: 'Say what that dense answer actually means in plain terms.',

package/src/commands/slides.ts

@@ -119,10 +119,10 @@ 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, a refused link or chart,
- * or a token the master fell back on 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. A malformed `deck.json` refuses before any slide is laid
+ * jszip, or the token module at startup. A fallback, a refused link, chart, or
+ * effect, or a token the master fell back on 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. A malformed `deck.json` refuses before any slide is laid
  * out and exits 1.
  */
 async function renderHtmlFolder(
@@ -163,6 +163,16 @@ async function renderHtmlFolder(
       `${GREY}│${NC} ${RED}✗${NC} slide ${slide} ${selector} chart left out: ${message}\n`,
     )
   }
+  for (const { slide, message } of result.refusedMotion) {
+    process.stderr.write(
+      `${GREY}│${NC} ${RED}✗${NC} slide ${slide} motion left out: ${message}\n`,
+    )
+  }
+  for (const { path, message } of result.refusedFonts) {
+    process.stderr.write(
+      `${GREY}│${NC} ${RED}✗${NC} font ${path} not embedded: ${message}\n`,
+    )
+  }
   for (const notice of result.notices) {
     process.stderr.write(`${GREY}│${NC} ${RED}✗${NC} ${notice}\n`)
   }

package/src/commands/sync.ts

@@ -168,6 +168,16 @@ function renderCheck(report: CheckReport): void {
     logInfo('Move the content yourself. No sync command touches these.')
   }
 
+  if (report.unmovedSurfaces.length > 0) {
+    logStep('Surfaces at the old .claude/ root')
+    for (const entry of report.unmovedSurfaces) {
+      logWarn(`${entry.rel} (moves to ${entry.movesTo})`)
+    }
+    logInfo(
+      'Rules glob the canon/ spelling only. Run `canon migrate surface-roots` to move these.',
+    )
+  }
+
   renderSeeds(report)
 
   if (report.superseded.length > 0) {

package/src/gov/citations.ts

@@ -266,8 +266,7 @@ export function collectCitations(text: string): RawCitation[] {
  *
  * A rule spelling a whole path there is declaring that exact artifact, and a
  * body line naming it again is naming what the rule governs rather than
- * pointing a reader somewhere. `governance/rules/standards/diagrams.md` tells
- * its reader to convert a `.claude/DIAGRAMS.md` left by an older install, which
+ * pointing a reader somewhere. Such a path names a file a target holds, so it
  * is correctly absent from this tree and correctly named in the rule.
  */
 function governedPaths(text: string): string[] {

package/src/migrate/skill-names.ts

@@ -33,6 +33,13 @@ import { defineRenameRules, type RenameRules } from '@/migrate/rename'
  * its name collided with `docs-sync`, which owns `docs/`. `claude-docs` is
  * retargeted onto `context-fold` for the same reason `claude-ui-test` was.
  *
+ * Five rows merge skills rather than rename one. `draft-docs`,
+ * `draft-context`, `draft-wireframes`, `draft-readme`, and `draft-wiki` ran
+ * one procedure five times over, differing only in the standard each read and
+ * the catalog each checked, so they became `draft-doc`, which picks the kind
+ * from where the document lands. Every retired name lands on the one skill, so
+ * a target citing any of them resolves after a single sweep.
+ *
  * Every name takes two words. Ten of these would have landed as a bare single
  * word under a plain strip, and a bare word such as `review` or `docs` is a
  * substring of ordinary prose with no token left for a later sweep to find.
@@ -79,6 +86,11 @@ export const SKILL_NAME_MAP: Readonly<Record<string, string>> = {
   'canon-slides-draft': 'draft-slides',
   'canon-record': 'record-screencast',
   'canon-frames-read': 'read-frames',
+  'draft-docs': 'draft-doc',
+  'draft-context': 'draft-doc',
+  'draft-wireframes': 'draft-doc',
+  'draft-readme': 'draft-doc',
+  'draft-wiki': 'draft-doc',
 }
 
 /**

package/src/slides/convert/deck.ts

@@ -1,5 +1,5 @@
-import { existsSync, readFileSync, statSync } from 'node:fs'
-import { basename, join } from 'node:path'
+import { existsSync, readFileSync, realpathSync, statSync } from 'node:fs'
+import { basename, isAbsolute, join, relative, resolve } from 'node:path'
 
 /**
  * What belongs to the deck rather than to one slide, read from `deck.json`
@@ -27,6 +27,18 @@ export interface DeckConfig {
   readonly slideNumbers: boolean
   /** Absolute, resolved against the deck folder. */
   readonly mark?: string
+  /** The faces the package step embeds, in the order the deck lists them. */
+  readonly fonts: readonly DeckFont[]
+}
+
+export interface DeckFont {
+  readonly family: string
+  readonly weight: number
+  readonly style: 'normal' | 'italic'
+  /** Absolute, resolved against the deck folder and kept inside it. */
+  readonly path: string
+  /** The path as `deck.json` wrote it, which a refusal names. */
+  readonly source: string
 }
 
 export type DeckRead =
@@ -43,8 +55,10 @@ const DECK_FIELDS = new Set([
   'footer',
   'slideNumbers',
   'mark',
+  'fonts',
 ])
 const BAND_FIELDS = new Set<string>(['show', ...BAND_SLOTS])
+const FONT_FIELDS = new Set(['family', 'weight', 'style', 'path'])
 
 class FieldError extends Error {
   constructor(
@@ -133,7 +147,73 @@ function parse(raw: unknown, folder: string): DeckConfig {
       throw new FieldError('mark', `mark ${mark} does not exist`)
     }
   }
-  return { title, header, footer, slideNumbers, mark }
+  const fonts = fontList(raw.fonts, folder)
+  return { title, header, footer, slideNumbers, mark, fonts }
+}
+
+function isWithin(folder: string, path: string): boolean {
+  const inside = relative(folder, path)
+  return inside !== '' && !inside.startsWith('..') && !isAbsolute(inside)
+}
+
+/**
+ * A face is read from the deck folder only, so a `deck.json` cannot point the
+ * export at a file elsewhere on the machine and carry it out inside the deck.
+ */
+function fontList(value: unknown, folder: string): DeckFont[] {
+  if (value === undefined) return []
+  if (!Array.isArray(value)) {
+    throw new FieldError('fonts', 'fonts must be a list')
+  }
+  return value.map((entry: unknown, index): DeckFont => {
+    const field = `fonts[${index}]`
+    if (!isRecord(entry)) {
+      throw new FieldError(field, `${field} must be an object`)
+    }
+    rejectUnknown(entry, FONT_FIELDS, `${field}.`)
+    const family = stringField(entry.family, `${field}.family`)
+    if (!family) {
+      throw new FieldError(`${field}.family`, `${field}.family is required`)
+    }
+    const weight = entry.weight ?? 400
+    if (
+      typeof weight !== 'number' ||
+      !Number.isInteger(weight) ||
+      weight < 1 ||
+      weight > 1000
+    ) {
+      throw new FieldError(
+        `${field}.weight`,
+        `${field}.weight must be a whole number from 1 to 1000`,
+      )
+    }
+    const style = entry.style ?? 'normal'
+    if (style !== 'normal' && style !== 'italic') {
+      throw new FieldError(
+        `${field}.style`,
+        `${field}.style must be normal or italic`,
+      )
+    }
+    const source = stringField(entry.path, `${field}.path`)
+    if (!source) {
+      throw new FieldError(`${field}.path`, `${field}.path is required`)
+    }
+    const path = resolve(folder, source)
+    const outside = new FieldError(
+      `${field}.path`,
+      `${field}.path ${source} lies outside the deck folder`,
+    )
+    if (!isWithin(folder, path)) throw outside
+    if (!existsSync(path) || !statSync(path).isFile()) {
+      throw new FieldError(
+        `${field}.path`,
+        `${field}.path ${path} does not exist`,
+      )
+    }
+    // A link inside the folder can still lead out of it.
+    if (!isWithin(realpathSync(folder), realpathSync(path))) throw outside
+    return { family, weight, style, path, source }
+  })
 }
 
 export function readDeck(folder: string): DeckRead {

package/src/slides/convert/export.ts

@@ -42,13 +42,23 @@ import {
   type WalkedSlide,
   walkSlide,
 } from '@/slides/convert/walk'
+import { embedFonts, type FontNotice } from '@/slides/package/fonts'
+import {
+  type EntranceSpec,
+  entranceShapes,
+  type MotionNotice,
+  type SlideMotionEdit,
+  writeMotion,
+} from '@/slides/package/motion'
 
 /**
  * Turns a folder of HTML slides into one editable deck. Chromium lays each
  * slide out at 1280 by 720 in the project's tokens, `walkSlide` reads what it
  * placed, `planSlide` maps the records onto shapes, and an element whose CSS has
  * no mapping lands as a screenshot of itself. The first slide's computed tokens
- * build the masters, and `deck.json` sets the bands they carry.
+ * build the masters, and `deck.json` sets the bands they carry. Once pptxgenjs
+ * has written the package, `src/slides/package/` adds the transitions,
+ * entrances, and embedded faces it declares nothing for.
  *
  * Every browser reference this feature adds lives here, and the command reaches
  * it through a dynamic import so no other command resolves the engine.
@@ -94,6 +104,10 @@ export type ExportResult =
       readonly fallbacks: readonly SlideFallback[]
       readonly refusedLinks: readonly SlideRefusedLink[]
       readonly refusedCharts: readonly RefusedChart[]
+      /** Transitions and entrances left out, each with the reason. */
+      readonly refusedMotion: readonly MotionNotice[]
+      /** Faces `deck.json` lists that the deck does not carry, with the reason. */
+      readonly refusedFonts: readonly FontNotice[]
       /** What the deck master could not take from the project's tokens. */
       readonly notices: readonly string[]
     }
@@ -172,6 +186,7 @@ export async function exportHtmlDeck(
   const refusedLinks: SlideRefusedLink[] = []
   const refusedCharts: RefusedChart[] = []
   const patches: Patch[] = []
+  const motions: SlideMotionEdit[] = []
   const notices: string[] = []
 
   try {
@@ -227,9 +242,8 @@ export async function exportHtmlDeck(
         slide.background = { color: walked.background.hex }
       }
       if (walked.meta.isHidden) slide.hidden = true
-      for (const [opIndex, op] of plan.ops.entries()) {
-        const name = `canon-${slideNumber}-${opIndex + 1}`
-        await draw(page, slide, { slide: slideNumber, name }, op, patches)
+      for (const op of plan.ops) {
+        await draw(page, slide, slideNumber, op, patches)
       }
       for (const record of walked.charts) {
         const chart = planChart(record, chartTheme)
@@ -241,6 +255,24 @@ export async function exportHtmlDeck(
       }
       drawOverrides(slide, deck, theme, walked.meta)
       if (walked.meta.notes) slide.addNotes(walked.meta.notes)
+      const { transition } = walked.meta
+      const roots = new Set(
+        walked.entrances.flatMap(({ record }) =>
+          record === null ? [] : [record],
+        ),
+      )
+      const entrances = walked.entrances.map(
+        ({ record, ...spec }): EntranceSpec => ({
+          ...spec,
+          shapes: entranceShapes(record, walked.records, plan.names, roots),
+        }),
+      )
+      if (transition || entrances.length > 0) {
+        motions.push({
+          slide: slideNumber,
+          motion: { ...(transition ? { transition } : {}), entrances },
+        })
+      }
     }
     if (drifted.length > 0) {
       const noun = drifted.length === 1 ? 'slide' : 'slides'
@@ -262,12 +294,32 @@ export async function exportHtmlDeck(
   if (!(written instanceof Uint8Array)) {
     return refused('export-failed', 'pptxgenjs returned no buffer')
   }
-  const patched = await applyPatches(written, patches)
+  // A deck needing no edit keeps the bytes pptxgenjs wrote.
+  let packaged: Uint8Array = written
+  const refusedMotion: MotionNotice[] = []
+  const refusedFonts: FontNotice[] = []
+  if (patches.length > 0 || motions.length > 0 || deck.fonts.length > 0) {
+    const zip = await JSZip.loadAsync(written)
+    await applyPatches(zip, patches)
+    refusedMotion.push(...(await writeMotion(zip, motions)))
+    const faces = deck.fonts.map((font) => ({
+      family: font.family,
+      weight: font.weight,
+      style: font.style,
+      path: font.source,
+      bytes: readFileSync(font.path),
+    }))
+    refusedFonts.push(...(await embedFonts(zip, faces)))
+    packaged = await zip.generateAsync({
+      type: 'nodebuffer',
+      compression: 'DEFLATE',
+    })
+  }
 
   mkdirSync(outDir, { recursive: true })
   const fileName = `${basename(sourceDir)}.pptx`
   const pptxPath = join(outDir, fileName)
-  writeFileSync(pptxPath, patched)
+  writeFileSync(pptxPath, packaged)
 
   let mirrorPath: string | undefined
   if (options.mirror) {
@@ -284,6 +336,8 @@ export async function exportHtmlDeck(
     fallbacks,
     refusedLinks,
     refusedCharts,
+    refusedMotion,
+    refusedFonts,
     notices,
   }
 }
@@ -437,10 +491,11 @@ const base64 = (bytes: Buffer | string): string =>
 async function draw(
   page: Page,
   slide: PptxGenJS.Slide,
-  target: { readonly slide: number; readonly name: string },
+  slideNumber: number,
   op: DrawOp,
   patches: Patch[],
 ): Promise<void> {
+  const target = { slide: slideNumber, name: op.options.objectName ?? '' }
   if (op.kind === 'shape') {
     slide.addShape(op.shape, op.options)
   } else if (op.kind === 'text') {
@@ -448,18 +503,13 @@ async function draw(
   } else if (op.kind === 'table') {
     slide.addTable(op.rows, op.options)
   } else if (op.kind === 'image') {
-    slide.addImage({
-      ...op.options,
-      ...imageSource(op.src),
-      objectName: target.name,
-    })
+    slide.addImage({ ...op.options, ...imageSource(op.src) })
     if (op.radius > 0) patches.push({ ...target, radius: op.radius })
     if (op.frame) slide.addShape(op.radius > 0 ? 'roundRect' : 'rect', op.frame)
   } else if (op.kind === 'svg') {
     slide.addImage({
       ...op.options,
       data: `image/svg+xml;base64,${base64(op.markup)}`,
-      objectName: target.name,
     })
     patches.push({ ...target, png: await screenshot(page, op.id) })
   } else {
@@ -472,14 +522,13 @@ async function draw(
  * Two things pptxgenjs cannot write, fixed in the package it wrote. An SVG's
  * PNG fallback comes out as the SVG's own bytes under a `.png` name in Node, so
  * a viewer that cannot draw SVG gets a broken image, and a picture takes no
- * corner radius. Each patched picture is found by the object name `draw` gave
- * it, which is the only handle the written XML keeps.
+ * corner radius. Each patched picture is found by the object name `planSlide`
+ * gave it, which is the only handle the written XML keeps.
  */
 async function applyPatches(
-  deck: Uint8Array,
+  zip: JSZip,
   patches: readonly Patch[],
-): Promise<Buffer> {
-  const zip = await JSZip.loadAsync(deck)
+): Promise<void> {
   const bySlide = Map.groupBy(patches, (patch) => patch.slide)
   for (const [slideNumber, slidePatches] of bySlide) {
     const slidePath = `ppt/slides/slide${slideNumber}.xml`
@@ -504,7 +553,6 @@ async function applyPatches(
     }
     zip.file(slidePath, xml)
   }
-  return zip.generateAsync({ type: 'nodebuffer', compression: 'DEFLATE' })
 }
 
 function pictureXml(xml: string, name: string): string | undefined {

package/src/slides/convert/shapes.ts

@@ -521,10 +521,44 @@ export interface Fallback {
   readonly properties: readonly UnmappedProperty[]
 }
 
+/** A shape the slide will hold, by the record that produced it. */
+export interface NamedShape {
+  readonly record: number
+  readonly name: string
+}
+
 export interface SlidePlan {
   readonly ops: readonly DrawOp[]
   readonly fallbacks: readonly Fallback[]
   readonly refusedLinks: readonly RefusedLink[]
+  /** Every object name the ops carry, in the order they are drawn. */
+  readonly names: readonly NamedShape[]
+}
+
+/**
+ * pptxgenjs numbers shape ids itself, so the object name is the only handle a
+ * later pass over the written XML can find a shape by.
+ */
+export const objectNameOf = (record: number): string => `canon-${record}`
+
+/** An image's border is a second shape over it, named after the picture. */
+function named<T extends DrawOp>(op: T, record: number): T {
+  const name = objectNameOf(record)
+  const options = { ...op.options, objectName: name }
+  if (op.kind === 'image' && op.frame) {
+    return {
+      ...op,
+      options,
+      frame: { ...op.frame, objectName: `${name}-frame` },
+    }
+  }
+  return { ...op, options }
+}
+
+function namesOf(record: number, op: DrawOp): NamedShape[] {
+  const names = [op.options.objectName]
+  if (op.kind === 'image') names.push(op.frame?.objectName)
+  return names.flatMap((name) => (name ? [{ record, name }] : []))
 }
 
 function boxOp(record: ElementRecord): DrawOp | undefined {
@@ -729,7 +763,13 @@ export function planSlide(
   const ops: DrawOp[] = []
   const fallbacks: Fallback[] = []
   const refusedLinks: RefusedLink[] = []
+  const names: NamedShape[] = []
   const dropped = new Set<number>()
+  const add = (record: number, op: DrawOp): void => {
+    const withName = named(op, record)
+    ops.push(withName)
+    names.push(...namesOf(record, withName))
+  }
 
   for (const record of records) {
     if (record.parent !== null && dropped.has(record.parent)) {
@@ -740,7 +780,7 @@ export function planSlide(
     if (properties.length > 0) {
       dropped.add(record.id)
       fallbacks.push({ id: record.id, selector: record.selector, properties })
-      ops.push({
+      add(record.id, {
         kind: 'fallback',
         id: record.id,
         options: { ...position(record.bounds), altText: record.text },
@@ -757,8 +797,8 @@ export function planSlide(
             : record.kind === 'svg'
               ? svgOp(record)
               : tableOp(record, context, refusedLinks)
-    if (op) ops.push(op)
+    if (op) add(record.id, op)
   }
 
-  return { ops, fallbacks, refusedLinks }
+  return { ops, fallbacks, refusedLinks, names }
 }

package/src/slides/convert/walk.ts

@@ -1,5 +1,6 @@
 import type { ChartRecord } from '@/slides/convert/chart'
 import type { ThemeReading } from '@/slides/convert/master'
+import type { TransitionSpec } from '@/slides/package/motion'
 import type {
   BoxStyle,
   ElementRecord,
@@ -31,6 +32,20 @@ export interface SlideMeta {
   readonly footer: BandOverride
   /** The `--color-text` the slide's `<body>` computes, as hex. */
   readonly textToken?: string
+  /** `data-transition` and `data-transition-duration` on `<body>`. */
+  readonly transition?: TransitionSpec
+}
+
+/**
+ * An element's `data-enter`, with the record it was walked as, or null when it
+ * was folded into another record's text or never drawn.
+ */
+export interface EntranceRecord {
+  readonly record: number | null
+  readonly selector: string
+  readonly effect: string
+  readonly order?: string
+  readonly duration?: string
 }
 
 /** What one laid-out slide hands back across `page.evaluate`. */
@@ -38,6 +53,7 @@ export interface WalkedSlide {
   readonly background: Rgba
   readonly records: ElementRecord[]
   readonly charts: ChartRecord[]
+  readonly entrances: EntranceRecord[]
   readonly meta: SlideMeta
 }
 
@@ -532,6 +548,10 @@ export function walkSlide(idAttribute: string): WalkedSlide {
       : { kind: 'master' }
   }
   const section = body.getAttribute('data-section')?.trim()
+  const attribute = (element: Element, name: string): string | undefined =>
+    element.getAttribute(name)?.trim() || undefined
+  const transitionEffect = attribute(body, 'data-transition')
+  const transitionDuration = attribute(body, 'data-transition-duration')
   const textValue = getComputedStyle(body)
     .getPropertyValue('--color-text')
     .trim()
@@ -544,9 +564,31 @@ export function walkSlide(idAttribute: string): WalkedSlide {
       body.getAttribute('data-hidden') !== 'false',
     header: band('header'),
     footer: band('footer'),
+    ...(transitionEffect
+      ? {
+          transition: {
+            effect: transitionEffect,
+            ...(transitionDuration ? { duration: transitionDuration } : {}),
+          },
+        }
+      : {}),
   }
 
-  return { background, records, charts, meta }
+  const entrances: EntranceRecord[] = Array.from(
+    body.querySelectorAll('[data-enter]'),
+  ).map((element) => {
+    const order = attribute(element, 'data-enter-order')
+    const duration = attribute(element, 'data-enter-duration')
+    return {
+      record: ids.get(element) ?? null,
+      selector: describe(element),
+      effect: attribute(element, 'data-enter') ?? '',
+      ...(order ? { order } : {}),
+      ...(duration ? { duration } : {}),
+    }
+  })
+
+  return { background, records, charts, entrances, meta }
 }
 
 /**