@erclx/canon 5.18.0 → 5.19.0

package/README.md

@@ -68,7 +68,7 @@ Each domain has a canonical source in this repo and a thin install or sync CLI o
 | Standards      | Authoring conventions for commits, branches, plans, tasks, and markdown                                                  | Opened by name, read by name with `canon standards <name>`      |
 | Tooling stacks | Golden configs, seeds, and a reference per framework                                                                     | Laid down by `canon init`, reconciled by `canon tooling sync`   |
 | Design system  | Ships a `DESIGN.md` token format, a skill that drafts one from an existing project or from scratch, and a render command | `canon design render`                                           |
-| Slides         | A `SLIDES.md` source format with a layout catalog                                                                        | `canon slides render` writes PowerPoint                         |
+| Slides         | A `SLIDES.md` source format with a layout catalog, or a folder of HTML slides rebuilt as editable shapes                 | `canon slides render` writes PowerPoint                         |
 | Teach          | Lessons, sources, and a glossary in one workspace, rendered to a small site                                              | `canon teach`                                                   |
 | Canvas         | Pages of HTML frames on a local pan and zoom surface, each frame drawn with the project's tokens                         | `canon canvas serve`                                            |
 | Transcripts    | A YouTube transcript with metadata frontmatter                                                                           | `canon transcripts <url>` writes it into any repo               |

package/claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "canon",
   "description": "Runs your agent's work and keeps its code good, on one setup for every repo.",
-  "version": "5.18.0",
+  "version": "5.19.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

package/docs/agents/commands.md

@@ -129,6 +129,7 @@ Subcommands no other page describes:
 - `claude skills rank` scores either skill corpus's descriptions against a case corpus by TF-IDF cosine similarity, reporting rank-one and top-three (`--cases <path>`).
 - `design regen` rewrites this repository's `canon/DESIGN.md` from `src/design/tokens.ts` and `src/design/base.css` from `src/design/neutral.ts`. `design css` emits the tokens and components as CSS on stdout, with `--no-components` for properties alone, and `design render` declares each vendored face the typography table names under `--embed-fonts`.
 - `slides render` renders a `.claude/SLIDES.md` source into a PowerPoint deck and reports any unrecognized layout name on stderr, and `slides list --json` emits the layout catalog.
+- `slides render --source <folder>` lays out each `.html` file in filename order in Chromium at 1280 by 720 and rebuilds it as editable shapes. Each element drawn as a picture prints one `✗` line on stderr naming the slide, the selector, and the properties that forced it. A link left out, being a `#slide-N` past the deck's end or any target that is neither that nor an absolute URL, prints one too, and the exit stays 0.
 - `canvas`, with its verbs, content format, and write routes, is described in `canvas.md`.
 - `labels scan` fails a pull request or a posted review whose title, body, or review comment carries a phase label, a label a code span quotes, a gitignored record path, a session link, a title word no dictionary holds, or a title breaking `standards/pr.md`'s format, casing, or length rule (`--event`, `--body-file`, `--json`).
 - `repo metadata propose` compares a description, homepage, and topic set computed from the README and `package.json` against what the remote carries, writing nothing, and `repo metadata apply` writes an explicitly supplied set through `gh repo edit` (`--description`, `--homepage`, `--topics`).

package/docs/agents/teach.md

@@ -126,9 +126,15 @@ The link opens the named workspace's contents page, or the root listing when no
 
 The JSON record is one line carrying the `nav` fields, then `served`, the absolute folder, and the server's `host`, `port`, `entry`, `url`, and `entryExists`. A lesson `nav` skips lands in `skipped` and the server still starts, since a partial refresh is still worth viewing. A `nav` refusal starts no server.
 
+While it runs, `up` watches the teach root. A change there, such as a lesson, a workspace, a glossary term, or a reference page added by hand or by another `teach` verb, runs the `nav` pass again, and every open page reloads once that pass changes what is served. Passes run one at a time, so a burst of saves costs one more pass rather than several at once. A pass `nav` refuses, such as one over a workspace deleted while it was served, is reported on stderr, the server keeps running, and no page reloads.
+
+Each refresh is logged to stderr, so stdout stays the one record line. Dotfiles and editor backups ending in `~` start no pass.
+
+The reload script is added to each page as the server sends it and never written to disk, so a page saved from the browser, a promoted lesson, and a committed fixture carry no trace of it. The script listens on `/__live`, which answers only a request naming the server by its loopback address or `localhost`.
+
 Viewing writes. Every page and generated stylesheet `nav` owns is rewritten first, which on a committed fixture shows as a diff. To serve without rewriting anything, `canon teach list <topic>` ends its human output with a `canon serve` line for that workspace, with the teach folder written relative to the cwd, or absolute when it sits outside it. The JSON record of `list` carries no such field.
 
-`canon serve` itself stays general, since nothing about serving a directory is specific to a learning workspace and the same verb carries a slide render and a design preview. What `up` adds in front of it is the refresh, which is teach-specific, and it serves through the same server rather than a second one.
+`canon serve` itself stays general, since nothing about serving a directory is specific to a learning workspace and the same verb carries a slide render and a design preview. What `up` adds in front of it is the refresh and the watch that repeats it, both teach-specific, and it serves through the same server rather than a second one.
 
 Read `url` off the record rather than building one from the port that was asked for. The verb walks forward past a port already in use, which is routine when a second workspace is already open, and the port it took is the one thing a composed URL gets wrong.
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/canon",
   "type": "module",
-  "version": "5.18.0",
+  "version": "5.19.0",
   "description": "Runs your agent's work and keeps its code good, on one setup for every repo.",
   "license": "MIT",
   "bin": {
@@ -56,6 +56,7 @@
     "commander": "^13.1.0",
     "execa": "^9.5.2",
     "highlight.js": "^11.12.0",
+    "jszip": "^3.10.1",
     "playwright-core": "1.59.1",
     "pptxgenjs": "^4.0.1",
     "preact": "^11.0.0"

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

package/src/commands/teach.ts

@@ -1,12 +1,16 @@
-import { isAbsolute, relative, resolve, sep } from 'node:path'
+import { readdirSync, statSync } from 'node:fs'
+import { isAbsolute, join, relative, resolve, sep } from 'node:path'
 import type { Command } from 'commander'
+import { LiveStream } from '@/serve/live'
 import {
   logServing,
   parsePort,
   serveFields,
   waitForInterrupt,
 } from '@/serve/report'
-import { DEFAULT_PORT, startServer } from '@/serve/static'
+import { DEFAULT_PORT, LIVE_EVENTS_PATH, startServer } from '@/serve/static'
+import { compileScript } from '@/teach/browser/compile'
+import { reload } from '@/teach/browser/reload'
 import { type LessonOutcome, planLesson } from '@/teach/lesson'
 import { type NavGenerated, type NavOutcome, generateNav } from '@/teach/nav'
 import type { RenderOutcome } from '@/teach/render'
@@ -942,8 +946,17 @@ async function runUp(
       ? 'index.html'
       : relative(dir, resolve(root, contents)).split(sep).join('/')
 
-  const served = startServer(dir, { port, entry })
+  const stream = refreshOnChange(root, dir, topic, emitJson)
+  const served = startServer(dir, {
+    port,
+    entry,
+    live: {
+      stream,
+      script: compileScript(reload, [LIVE_EVENTS_PATH]),
+    },
+  })
   if (!served.ok) {
+    stream.close()
     // A serve refusal carries a reason the teach refusals do not list, so it
     // is written here in the teach record's shape rather than through one.
     if (emitJson) {
@@ -970,10 +983,105 @@ async function runUp(
     logServing(served)
   }
 
-  await waitForInterrupt(served.stop)
+  await waitForInterrupt(async () => {
+    stream.close()
+    await served.stop()
+  })
   return 0
 }
 
+/**
+ * An editor's swap or backup file, or anything under a dot folder. It changes
+ * nothing a page shows, so it neither starts a pass nor counts as served.
+ */
+function isScratch(path: string): boolean {
+  return path
+    .split(/[\\/]/)
+    .some((segment) => segment.startsWith('.') || segment.endsWith('~'))
+}
+
+/**
+ * What the served folder holds, as each file's path, size, and mtime. A pass
+ * whose `nav` wrote nothing leaves it unchanged, which is how the echo of a
+ * pass's own writes settles without a second reload.
+ */
+function servedState(dir: string): string {
+  return readdirSync(dir, { recursive: true, withFileTypes: true })
+    .filter((entry) => entry.isFile())
+    .map((entry) => relative(dir, join(entry.parentPath, entry.name)))
+    .filter((path) => !isScratch(path))
+    .sort()
+    .map((path) => {
+      const stat = statSync(join(dir, path), { throwIfNoEntry: false })
+      return `${path}:${stat?.size}:${stat?.mtimeMs}`
+    })
+    .join('\n')
+}
+
+/**
+ * Re-runs `nav` on each settled change under the teach folder and tells every
+ * open page to reload once a pass changed what is served. Passes run one at a
+ * time, since `nav` is not reentrant over the files it rewrites, and a change
+ * arriving mid-pass is coalesced into exactly one more. A refused or failed
+ * pass sends no reload, so a page never reloads onto a half-written state.
+ */
+function refreshOnChange(
+  root: string,
+  dir: string,
+  topic: string | undefined,
+  emitJson: boolean,
+): LiveStream<string> {
+  let isRunning = false
+  let isDirty = false
+  let state = servedState(dir)
+
+  const report = (message: string, isWarning: boolean) => {
+    if (emitJson) process.stderr.write(`${message}\n`)
+    else if (isWarning) logWarn(message)
+    else logInfo(message)
+  }
+
+  const pass = async (): Promise<void> => {
+    const nav = await generateNav(root, topic)
+    if (!nav.ok) {
+      report(`Refresh refused: ${nav.message}`, true)
+      return
+    }
+    const next = servedState(dir)
+    if (next === state) return
+    state = next
+    stream.send({ reload: true })
+    report(`Refreshed ${nav.lessons} lessons, reloading open pages`, false)
+  }
+
+  const schedule = async (): Promise<void> => {
+    if (isRunning) {
+      isDirty = true
+      return
+    }
+    isRunning = true
+    do {
+      isDirty = false
+      // A throw, such as the teach folder removed mid-pass, is reported and
+      // the loop carries on, since a rejection left here would end the
+      // process and a stuck flag would end every later refresh.
+      try {
+        await pass()
+      } catch (error) {
+        const code = (error as NodeJS.ErrnoException).code ?? String(error)
+        report(`Refresh failed: ${code}`, true)
+      }
+    } while (isDirty)
+    isRunning = false
+  }
+
+  const stream = new LiveStream<string>(dir, {
+    map: (path) => (isScratch(path) ? undefined : path),
+    onChange: () => void schedule(),
+  })
+  return stream
+}
+
 function reportRefusal(
   title: string,
   refused: TeachRefused,

package/src/serve/live.ts

@@ -0,0 +1,113 @@
+import { type FSWatcher, watch } from 'node:fs'
+import { SERVE_HOST } from '@/serve/static'
+
+/**
+ * How long a burst of watch events for one path waits before it is sent. One
+ * editor save raises several, and each would otherwise reach a reader again.
+ */
+const SETTLE_MS = 40
+
+export interface LiveOptions<T> {
+  /**
+   * Turns a changed path, relative to the watched directory, into what a change
+   * carries, or into undefined to drop it, such as a write's staging file.
+   */
+  readonly map: (path: string) => T | undefined
+  /**
+   * Takes each settled change in place of the clients. A caller that has work
+   * to do before a reader may look, such as regenerating pages, sends its own
+   * payload through `send` once that work lands.
+   */
+  readonly onChange?: (payload: T) => void
+}
+
+/**
+ * Whether a request names this server by a loopback name and its own port.
+ * The bind keeps other machines out, and this keeps out a page the operator
+ * visits whose domain was rebound to 127.0.0.1, which reaches the socket with
+ * its own name in the Host header.
+ */
+export function isLoopbackHost(host: string | null, port: number): boolean {
+  return host === `${SERVE_HOST}:${port}` || host === `localhost:${port}`
+}
+
+/**
+ * Watches a directory and fans each settled change out as a server-sent event
+ * to every open client, or to `onChange` when the caller takes changes itself.
+ */
+export class LiveStream<T> {
+  private readonly clients = new Set<ReadableStreamDefaultController<string>>()
+  private readonly pending = new Map<string, ReturnType<typeof setTimeout>>()
+  private readonly watcher: FSWatcher
+
+  constructor(
+    dir: string,
+    private readonly options: LiveOptions<T>,
+  ) {
+    this.watcher = watch(dir, { recursive: true }, (_event, filename) => {
+      if (filename) this.queue(filename.toString())
+    })
+  }
+
+  private queue(path: string): void {
+    const payload = this.options.map(path)
+    if (payload === undefined) return
+    clearTimeout(this.pending.get(path))
+    this.pending.set(
+      path,
+      setTimeout(() => {
+        this.pending.delete(path)
+        if (this.options.onChange) this.options.onChange(payload)
+        else this.send(payload)
+      }, SETTLE_MS),
+    )
+  }
+
+  send(payload: unknown): void {
+    const frame = `data: ${JSON.stringify(payload)}\n\n`
+    for (const client of this.clients) client.enqueue(frame)
+  }
+
+  open(): Response {
+    let self: ReadableStreamDefaultController<string> | undefined
+    const stream = new ReadableStream<string>({
+      start: (controller) => {
+        self = controller
+        this.clients.add(controller)
+        controller.enqueue(': open\n\n')
+      },
+      cancel: () => {
+        if (self) this.clients.delete(self)
+      },
+    })
+    return new Response(stream, {
+      headers: {
+        'content-type': 'text/event-stream',
+        'cache-control': 'no-store',
+      },
+    })
+  }
+
+  /** Opens a stream for a request naming this server, and refuses any other. */
+  answer(request: Request, port: number): Response {
+    if (isLoopbackHost(request.headers.get('host'), port)) return this.open()
+    return new Response('Forbidden\n', {
+      status: 403,
+      headers: { 'content-type': 'text/plain; charset=utf-8' },
+    })
+  }
+
+  close(): void {
+    this.watcher.close()
+    for (const timer of this.pending.values()) clearTimeout(timer)
+    this.pending.clear()
+    for (const client of this.clients) {
+      try {
+        client.close()
+      } catch {
+        /* Already closed by the browser going away. */
+      }
+    }
+    this.clients.clear()
+  }
+}

package/src/serve/static.ts

@@ -1,5 +1,6 @@
 import { existsSync, readdirSync, realpathSync, statSync } from 'node:fs'
 import { join, resolve, sep } from 'node:path'
+import type { LiveStream } from '@/serve/live'
 
 /**
  * The loopback interface, never a wildcard bind. A preview serves whatever
@@ -78,11 +79,25 @@ export interface ServeStarted {
 
 export type ServeOutcome = ServeStarted | ServeRefused
 
+/** The route a live page's script opens its event stream on. */
+export const LIVE_EVENTS_PATH = '/__live'
+
+export interface LiveServe {
+  readonly stream: Pick<LiveStream<unknown>, 'answer'>
+  /**
+   * The `<script>` element spliced into every page served, built by the caller
+   * so this module stays free of what a reload means to any one surface.
+   */
+  readonly script: string
+}
+
 export interface ServeOptions {
   readonly port?: number
   readonly entry?: string
   /** Answers a directory request with no index page by listing it. Off by default. */
   readonly index?: boolean
+  /** Answers the events route and splices a script into each page. Off by default. */
+  readonly live?: LiveServe
 }
 
 function escapeHtml(text: string): string {
@@ -253,16 +268,59 @@ export function bindFirstFree(
   return undefined
 }
 
+/**
+ * Splices the script in before the last closing body tag of a page. A page
+ * carrying none goes out as the bytes on disk, since guessing a place for it
+ * risks breaking markup the author wrote. The splice happens per response and
+ * never on disk, so a page the reader saves or commits carries no hook.
+ */
+export async function injectLive(
+  response: Response,
+  script: string,
+): Promise<Response> {
+  const type = response.headers.get('content-type') ?? ''
+  if (response.status !== 200 || !type.startsWith('text/html')) return response
+
+  const bytes = new Uint8Array(await response.arrayBuffer())
+  const html = new TextDecoder().decode(bytes)
+  /*
+   * Searched in the original rather than a lowercased copy, since lowercasing
+   * changes the length of some characters, such as İ, and an index read off
+   * the copy would cut the original inside the tag.
+   */
+  const at = [...html.matchAll(/<\/body>/gi)].at(-1)?.index
+  const init = { status: response.status, headers: response.headers }
+  if (at === undefined) return new Response(bytes, init)
+  return new Response(`${html.slice(0, at)}${script}${html.slice(at)}`, init)
+}
+
 function listen(
   root: string,
   first: number,
   index: boolean,
+  live: LiveServe | undefined,
 ): { server: BoundServer; port: number } | undefined {
+  if (!live) {
+    return bindFirstFree(first, (port) =>
+      Bun.serve({
+        hostname: SERVE_HOST,
+        port,
+        fetch: (request) => respond(root, request, index),
+      }),
+    )
+  }
   return bindFirstFree(first, (port) =>
     Bun.serve({
       hostname: SERVE_HOST,
       port,
-      fetch: (request) => respond(root, request, index),
+      /* The event stream stays open for as long as the page does. */
+      idleTimeout: 0,
+      fetch: async (request, server) => {
+        if (new URL(request.url).pathname === LIVE_EVENTS_PATH) {
+          return live.stream.answer(request, server.port ?? 0)
+        }
+        return injectLive(await respond(root, request, index), live.script)
+      },
     }),
   )
 }
@@ -378,7 +436,7 @@ export function startServer(
    */
   let bound: ReturnType<typeof listen>
   try {
-    bound = listen(root, first, options.index ?? false)
+    bound = listen(root, first, options.index ?? false, options.live)
   } catch (error) {
     const code = (error as NodeJS.ErrnoException).code ?? 'unknown'
     return refuse(