@erclx/canon 5.17.0 → 5.19.0

package/src/canvas/server.ts

@@ -15,7 +15,12 @@ import {
   TEMP_SUFFIX,
   writeSelection,
 } from '@/canvas/content'
-import { resolveFrameTokens, type TokenOptions } from '@/canvas/tokens'
+import { type EditRefused, editFrame } from '@/canvas/edit'
+import {
+  resolveFrameTokens,
+  type TokenOptions,
+  tokenGroups,
+} from '@/canvas/tokens'
 import { buildDesignCss } from '@/design/css'
 import {
   bindFirstFree,
@@ -140,7 +145,9 @@ function json(body: unknown, status = 200): Response {
   })
 }
 
-const REFUSAL_STATUS: Record<ContentRefused['reason'], number> = {
+const REFUSAL_STATUS: Record<EditRefused['reason'], number> = {
+  'invalid-edit': 400,
+  'not-text-only': 409,
   'invalid-name': 400,
   'invalid-size': 400,
   'invalid-position': 400,
@@ -154,7 +161,7 @@ const REFUSAL_STATUS: Record<ContentRefused['reason'], number> = {
   'stale-address': 409,
 }
 
-function refusal(refused: ContentRefused): Response {
+function refusal(refused: ContentRefused | EditRefused): Response {
   return json(refused, REFUSAL_STATUS[refused.reason])
 }
 
@@ -351,11 +358,11 @@ export function startCanvas(
           '/': options.shell,
           '/api/pages': guarded(() => {
             const resolved = resolveFrameTokens(root, tokens)
-            const { css: _css, ...source } = resolved
+            const { css, ...source } = resolved
             const selected = readSelection(root)
             return json({
               pages: listPages(root),
-              tokens: source,
+              tokens: { ...source, groups: tokenGroups(css) },
               selection: selected && {
                 page: selected.page,
                 frame: selected.frame,
@@ -389,6 +396,44 @@ export function startCanvas(
               }),
             ),
           },
+          '/api/frames/edit': {
+            POST: guarded(
+              mutation((body) => {
+                if (
+                  !isRecord(body) ||
+                  typeof body.page !== 'string' ||
+                  typeof body.frame !== 'string' ||
+                  typeof body.property !== 'string' ||
+                  typeof body.value !== 'string'
+                ) {
+                  return badBody(
+                    'send page, frame, element, property, and value',
+                  )
+                }
+                const { element } = body
+                /*
+                 * The hash is what keeps an edit off an element the file has
+                 * since moved, so the shell's edit never goes without it.
+                 */
+                if (!isAddressShape(element) || element.hash === undefined) {
+                  return badBody(
+                    'send an element as index, tag, count, and the hash it was served with',
+                  )
+                }
+                const outcome = editFrame(
+                  root,
+                  body.page,
+                  body.frame,
+                  element,
+                  {
+                    property: body.property,
+                    value: body.value,
+                  },
+                )
+                return outcome.ok ? json(outcome) : refusal(outcome)
+              }),
+            ),
+          },
           '/api/selection': {
             POST: guarded(
               mutation((body) => {

package/src/canvas/tokens.ts

@@ -29,6 +29,88 @@ const BASE_FILE = 'base.css'
 
 const NONE_NOTICE = `No token stylesheet, so frames render unstyled. Run canon design install to add ${join(DESIGN_INSTALL_DIR, BASE_FILE)}, put overrides under ${join(DESIGN_INSTALL_DIR, DESIGN_PROJECT_SUBDIR)}/, or link a stylesheet from the frame.`
 
+export type TokenKind =
+  | 'color'
+  | 'spacing'
+  | 'radius'
+  | 'font-family'
+  | 'font-size'
+  | 'other'
+
+export interface Token {
+  readonly name: string
+  readonly value: string
+  /** The literal a `var()` value ends at, where the sheet defines it. */
+  readonly resolved?: string
+}
+
+export interface TokenGroup {
+  readonly kind: TokenKind
+  readonly tokens: readonly Token[]
+}
+
+const KIND_ORDER: readonly TokenKind[] = [
+  'color',
+  'spacing',
+  'radius',
+  'font-family',
+  'font-size',
+  'other',
+]
+
+/** By the naming the toolkit's module and most token sheets share. */
+function kindOf(name: string): TokenKind {
+  if (name.startsWith('--color-')) return 'color'
+  if (/^--(space|spacing)-/.test(name)) return 'spacing'
+  if (name.startsWith('--radius-')) return 'radius'
+  if (/-family$|^--font-family-/.test(name)) return 'font-family'
+  if (/-size$|^--font-size-|^--text-/.test(name)) return 'font-size'
+  return 'other'
+}
+
+const DECLARATION = /(--[A-Za-z0-9_-]+)\s*:\s*([^;}]*)/g
+
+const REFERENCE = /^var\(\s*(--[A-Za-z0-9_-]+)\s*(?:,[^)]*)?\)$/
+
+/**
+ * The custom properties a token sheet defines, grouped by kind. A property
+ * defined twice keeps its first value, which is the dark theme's in this
+ * toolkit's module and the base's in an installed sheet. Empty groups drop.
+ */
+export function tokenGroups(css: string): TokenGroup[] {
+  const values = new Map<string, string>()
+  for (const [, name, value] of css
+    .replace(/\/\*[\s\S]*?\*\//g, '')
+    .matchAll(DECLARATION)) {
+    if (name && value !== undefined && !values.has(name)) {
+      values.set(name, value.trim())
+    }
+  }
+
+  const resolve = (value: string, seen: Set<string>): string | undefined => {
+    const reference = value.match(REFERENCE)?.[1]
+    if (!reference) return value
+    const next = values.get(reference)
+    if (next === undefined || seen.has(reference)) return undefined
+    return resolve(next, new Set([...seen, reference]))
+  }
+
+  const grouped = new Map<TokenKind, Token[]>()
+  for (const [name, value] of values) {
+    const resolved = REFERENCE.test(value)
+      ? resolve(value, new Set([name]))
+      : undefined
+    const token =
+      resolved === undefined ? { name, value } : { name, value, resolved }
+    const kind = kindOf(name)
+    grouped.set(kind, [...(grouped.get(kind) ?? []), token])
+  }
+  return KIND_ORDER.flatMap((kind) => {
+    const tokens = grouped.get(kind)
+    return tokens ? [{ kind, tokens }] : []
+  })
+}
+
 /** The installed files in cascade order: the base first, then each override. */
 function installedFiles(root: string): string[] {
   const files: string[] = []

package/src/claude/cases/misc.ts

@@ -104,6 +104,10 @@ export const MISC_CASES: readonly SkillCase[] = [
   },
   {
     prompt: 'Connect this repo to Cloudflare Pages and set up the deploy.',
-    expect: 'deploy-cloudflare',
+    expect: 'deploy-app',
+  },
+  {
+    prompt: 'Set up a Vercel project for this app and wire up its secrets.',
+    expect: 'deploy-app',
   },
 ]

package/src/commands/canvas.ts

@@ -14,6 +14,11 @@ import {
   renamePage,
 } from '@/canvas/content'
 import { captureCanvas } from '@/canvas/capture'
+import {
+  type EditRefused,
+  editFrameAtIndex,
+  STYLE_PROPERTIES,
+} from '@/canvas/edit'
 import { CANVAS_PORT, startCanvas } from '@/canvas/server'
 import { resolveFrameTokens } from '@/canvas/tokens'
 import { displayPath, parsePort, waitForInterrupt } from '@/serve/report'
@@ -40,6 +45,7 @@ interface Refused {
   readonly ok: false
   readonly reason:
     | ContentRefused['reason']
+    | EditRefused['reason']
     | 'no-root'
     | 'no-server'
     | 'capture-failed'
@@ -102,7 +108,7 @@ export function register(program: Command): void {
     .command('canvas')
     .helpOption('-h, --help', 'Show this help message')
     .description(
-      'Local canvas of pages and HTML frames (serve, list, page, frame, selection, capture)',
+      'Local canvas of pages and HTML frames (serve, list, page, frame, selection, edit, capture)',
     )
     .addHelpText(
       'after',
@@ -118,6 +124,7 @@ export function register(program: Command): void {
         '  canon canvas frame add drafts hero --width 1440 --height 900',
         '  canon canvas frame move drafts hero --x 200 --y 120',
         '  canon canvas selection --json',
+        "  canon canvas edit drafts/hero --element 4 --set 'color=var(--color-accent)'",
         '  canon canvas capture drafts/hero',
         '  canon canvas list --json',
         '',
@@ -366,6 +373,93 @@ export function register(program: Command): void {
       outro()
     })
 
+  withRoot(
+    canvas
+      .command('edit')
+      .description(
+        'Set one property of an element in a frame, the writer the inspector uses',
+      )
+      .argument('<target>', '<page>/<frame>')
+      .requiredOption(
+        '--element <index>',
+        'The element by its index in document order, as canvas selection reports it',
+      )
+      .requiredOption(
+        '--set <property=value>',
+        'The property and its value, where an empty value drops a style property',
+      ),
+  )
+    .addHelpText(
+      'after',
+      [
+        '',
+        `Properties: text, ${STYLE_PROPERTIES.join(', ')}.`,
+        'A style property is written into the element inline style and',
+        'leaves its other properties as they were. text replaces the text of',
+        'an element holding text alone, and refuses one holding elements.',
+        'Every byte outside the element stays as it was.',
+        '',
+      ].join('\n'),
+    )
+    .action(
+      async (
+        target: string,
+        opts: RootOptions & { element: string; set: string },
+      ) => {
+        const emitJson = opts.json ?? false
+        const resolved = await resolveRoot(opts)
+        if (!resolved.ok) {
+          process.exitCode = refuse(resolved, emitJson)
+          return
+        }
+        const { root } = resolved
+        const [pageName, frameName, ...rest] = target.split('/')
+        if (!pageName || !frameName || rest.length > 0) {
+          process.exitCode = refuse(
+            {
+              ok: false,
+              reason: 'invalid-name',
+              detail: `${target} is not <page>/<frame>`,
+            },
+            emitJson,
+          )
+          return
+        }
+        const split = opts.set.indexOf('=')
+        if (split <= 0) {
+          process.exitCode = refuse(
+            {
+              ok: false,
+              reason: 'invalid-edit',
+              detail: `${opts.set} is not <property>=<value>`,
+            },
+            emitJson,
+          )
+          return
+        }
+        const property = opts.set.slice(0, split).trim()
+        const value = opts.set.slice(split + 1)
+        const index =
+          opts.element.trim() === '' ? Number.NaN : Number(opts.element)
+        const outcome = editFrameAtIndex(root, pageName, frameName, index, {
+          property,
+          value,
+        })
+        if (!outcome.ok) {
+          process.exitCode = refuse(outcome, emitJson)
+          return
+        }
+        const path = resolve(canvasDir(root), outcome.page, outcome.file)
+        if (emitJson) writeJson({ ...outcome, property, value, path })
+        intro(BANNER)
+        logAdd(`${outcome.page}/${outcome.file}`)
+        logInfo(
+          `element ${index}: ${property} ${value === '' ? 'dropped' : `= ${value}`}`,
+        )
+        outro()
+      },
+    )
+
   withRoot(
     canvas
       .command('capture')

package/src/commands/context.ts

@@ -24,8 +24,10 @@ import {
   coveredCount,
   isOverCount,
   isOverLength,
+  isOverRisks,
   measureArchitecture,
   missingRevisit,
+  overWords,
   testableCount,
 } from '@/context/architecture'
 import { auditCitations, type CitationReport } from '@/context/citations'
@@ -56,6 +58,12 @@ import {
   resolveFolders,
 } from '@/context/folders'
 import { isGating } from '@/context/gate'
+import {
+  isOverWordCap,
+  measureRequirements,
+  requirementsRel,
+  type RequirementsReport,
+} from '@/context/requirements'
 import { auditIndexes, type FolderDrift } from '@/context/index-drift'
 import {
   measureWireframeFolder,
@@ -96,7 +104,7 @@ export function register(program: Command): void {
   context
     .command('audit')
     .description(
-      'Report required sections, entry length, citations, reference form, catalog tables, provenance, index drift, the architecture record against its own ceiling, its own entry cap, and its word weight, and wireframe states against their evidence folders',
+      'Report required sections, entry length, citations, reference form, catalog tables, provenance, index drift, the architecture record against its own ceiling, entry cap, word cap, and risk cap, the requirements record against its own word cap, and wireframe states against their evidence folders',
     )
     .argument('[path]', 'Project root, defaulting to the current directory')
     .helpOption('-h, --help', 'Show this help message')
@@ -125,8 +133,10 @@ export function register(program: Command): void {
         'measures it. A record stating an entry cap gates the same way when',
         'it holds more decisions than the cap, and a record stating that',
         'every decision closes with a revisit sentence gates when one lacks',
-        'it. A record stating none of the three is reported and never',
-        'gated. --gate widens the gate to the other two',
+        'it. A record stating a word cap a decision or a risk bullet cap',
+        'gates past either, and a requirements record stating a word cap',
+        'gates past it. A record stating none of these is reported and',
+        'never gated. --gate widens the gate to the other two',
         'findings that are facts rather than judgments: a missing required',
         'section and index drift. A context entry requires Overview and',
         'Layout, and a wireframe requires Regions, States, Copy, and Not on',
@@ -658,6 +668,7 @@ async function runAudit(
   // record. A run that never looked and a project with nothing to look at are
   // different answers, and one value for both reports the second as the first.
   const record = gateOnly ? undefined : await measureArchitecture(root)
+  const requirements = gateOnly ? undefined : await measureRequirements(root)
   const wireframes = gateOnly
     ? []
     : (
@@ -681,6 +692,7 @@ async function runAudit(
     reportProvenance(entries, folders)
     reportDrift(drift)
     reportRecord(record, root)
+    reportRequirements(requirements, root)
     reportWireframeStates(wireframes)
     outro()
   }
@@ -719,6 +731,8 @@ async function runAudit(
         // target that never wrote one is entitled to. Absent says the run
         // never looked, which is `--citations-only`.
         architecture: gateOnly ? undefined : (record ?? null),
+        // The same three states for the requirements record.
+        requirements: gateOnly ? undefined : (requirements ?? null),
         // Absent under `--citations-only`, for the same reason as above. An
         // empty array under the ordinary run says the project carries no
         // wireframes folder or no entry carrying a States table, which is a
@@ -744,6 +758,10 @@ async function runAudit(
     recordOverCount: record !== undefined && isOverCount(record),
     recordMissingRevisit:
       record !== undefined && missingRevisit(record).length > 0,
+    recordOverWords: record !== undefined && overWords(record).length > 0,
+    recordOverRisks: record !== undefined && isOverRisks(record),
+    requirementsOverWords:
+      requirements !== undefined && isOverWordCap(requirements),
     sections,
     drift,
     wireframes,
@@ -1152,11 +1170,44 @@ function reportRecord(
   const { allowances } = report
 
   logInfo(
-    `${plural(report.words, 'word')} across ${plural(report.lines, 'line')}, read alongside the weight judgment a session makes by reading the file. This never gates.`,
+    `${plural(report.words, 'word')} across ${plural(report.lines, 'line')}. The whole file's count never gates.`,
   )
   if (report.risksWords !== undefined) {
     logInfo(
-      `\`## Risks / open questions\` holds ${plural(report.risksWords, 'word')}, weighed the same way and read alongside the same judgment.`,
+      `\`## Risks / open questions\` holds ${plural(report.risksWords, 'word')}.`,
+    )
+  }
+
+  const longDecisions = overWords(report)
+  if (report.wordCap === undefined) {
+    logInfo(
+      'No word cap a decision stated, so each decision word count is reported and never gated.',
+    )
+  } else if (longDecisions.length > 0) {
+    for (const entry of longDecisions) {
+      logError(
+        `"${entry.heading}" holds ${entry.words} words against a cap of ${report.wordCap} a decision.`,
+      )
+    }
+  } else {
+    logInfo(
+      `Every decision fits the cap of ${report.wordCap} words a decision.`,
+    )
+  }
+
+  if (report.riskCap === undefined) {
+    logInfo('No risk bullet cap stated, so the Risks section is never gated.')
+  } else if (report.risksBullets === undefined) {
+    logWarn(
+      `The record states a cap of ${report.riskCap} risk bullets and carries no \`## Risks / open questions\` section to count.`,
+    )
+  } else if (isOverRisks(report)) {
+    logError(
+      `${plural(report.risksBullets, 'risk bullet')} against a cap of ${report.riskCap}, nested bullets counted.`,
+    )
+  } else {
+    logInfo(
+      `${plural(report.risksBullets, 'risk bullet')} against a cap of ${report.riskCap}, nested bullets counted.`,
     )
   }
 
@@ -1257,6 +1308,35 @@ function reportRecord(
   )
 }
 
+/** Reports the requirements record against the word cap it states, if any. */
+function reportRequirements(
+  report: RequirementsReport | undefined,
+  root: string,
+): void {
+  logStep('Requirements record')
+
+  if (report === undefined) {
+    logInfo(
+      `Out of scope. The project carries no ${requirementsRel(root)}, so there was no record to measure.`,
+    )
+    return
+  }
+
+  if (report.wordCap === undefined) {
+    logInfo(
+      `${plural(report.words, 'word')} in ${report.rel} and no word cap stated, so the count is reported and never gated.`,
+    )
+  } else if (isOverWordCap(report)) {
+    logError(
+      `${plural(report.words, 'word')} against a cap of ${report.wordCap} in ${report.rel}.`,
+    )
+  } else {
+    logInfo(
+      `${plural(report.words, 'word')} against a cap of ${report.wordCap} in ${report.rel}.`,
+    )
+  }
+}
+
 function reportDrift(drift: readonly FolderDrift[]): void {
   logStep('Index drift')
 

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