@erclx/canon 5.27.0 → 5.29.0

package/src/canvas/edit.ts

@@ -17,6 +17,7 @@ import {
   withFileLock,
   writeSelection,
 } from '@/canvas/content'
+import type { ElementState } from '@/canvas/history'
 
 /**
  * The basic set an operator edits by hand. Each is a CSS property written into
@@ -27,6 +28,10 @@ export const STYLE_PROPERTIES = [
   'background-color',
   'font-size',
   'font-weight',
+  'font-family',
+  'line-height',
+  'letter-spacing',
+  'text-align',
   'width',
   'height',
   'padding',
@@ -99,6 +104,11 @@ const DECLARATION_BREAK = /[;{}<>\n\r]/
 
 const BOM = ''
 
+/* The rewriter drops a leading byte order mark, so a read skips it first. */
+function withoutBom(html: string): string {
+  return html.startsWith(BOM) ? html.slice(BOM.length) : html
+}
+
 function refuse(reason: EditRefusal, detail: string): EditRefused {
   return { ok: false, reason, detail }
 }
@@ -133,10 +143,13 @@ function checkChange(change: EditChange): EditRefused | undefined {
   return undefined
 }
 
+const CHARACTER_REFERENCE = /&(?:#\d+|#x[0-9a-f]+|[a-z][a-z0-9]*);/iy
+
 /**
  * Splits a style attribute at each semicolon outside parentheses and quotes,
  * keeping every segment's own spacing so an untouched one is written back as
- * it was.
+ * it was. The rewriter hands the attribute over undecoded and writes a quote
+ * back as `&quot;`, so a character reference's own semicolon never splits.
  */
 function declarations(style: string): string[] {
   const segments: string[] = []
@@ -145,7 +158,10 @@ function declarations(style: string): string[] {
   let start = 0
   for (let at = 0; at < style.length; at += 1) {
     const char = style[at]
-    if (quote) {
+    CHARACTER_REFERENCE.lastIndex = at
+    if (char === '&' && CHARACTER_REFERENCE.test(style)) {
+      at = CHARACTER_REFERENCE.lastIndex - 1
+    } else if (quote) {
       if (char === quote) quote = undefined
     } else if (char === '"' || char === "'") quote = char
     else if (char === '(') depth += 1
@@ -282,11 +298,106 @@ export function applyEdit(
   return { ok: true, html: `${bom}${rewritten}` }
 }
 
+interface ElementRead {
+  readonly tag: string
+  readonly style: string | undefined
+  /** The raw text inside it, entities still encoded, when it holds text alone. */
+  readonly inner: string | undefined
+}
+
+/**
+ * What the element at an index holds, read as the file states it. Each text
+ * chunk the rewriter hands over is the source text, so the inner content keeps
+ * every entity as written.
+ */
+function readElement(html: string, index: number): ElementRead | undefined {
+  let found: { tag: string; style: string | undefined } | undefined
+  let isOpen = false
+  let hasChild = false
+  let inner = ''
+  countElements(new HTMLRewriter(), (element, at) => {
+    if (isOpen) hasChild = true
+    if (at !== index) return undefined
+    found = {
+      tag: element.tagName.toLowerCase(),
+      style: element.getAttribute('style') ?? undefined,
+    }
+    if (!element.canHaveContent || element.selfClosing) return undefined
+    isOpen = true
+    return () => {
+      isOpen = false
+    }
+  })
+    .onDocument({
+      text(chunk) {
+        if (isOpen) inner += chunk.text
+      },
+    })
+    .transform(html)
+  if (!found) return undefined
+  return { ...found, inner: hasChild ? undefined : inner }
+}
+
+function stateOf(read: ElementRead, withInner: boolean): ElementState {
+  return withInner
+    ? { style: read.style, inner: read.inner }
+    : { style: read.style }
+}
+
+function sameState(read: ElementRead, state: ElementState): boolean {
+  if (read.style !== state.style) return false
+  return state.inner === undefined || read.inner === state.inner
+}
+
+/**
+ * Restamps a selection that was fresh before a write, since neither an edit
+ * nor a restore moves an element.
+ */
+function restampSelection(
+  root: string,
+  page: string,
+  frame: string,
+  before: ReturnType<typeof readSelection>,
+  html: string,
+): void {
+  if (
+    before?.page !== page ||
+    before.frame !== frame ||
+    !before.element ||
+    before.element.stale
+  ) {
+    return
+  }
+  writeSelection(root, {
+    page,
+    frame,
+    element: {
+      index: before.element.index,
+      tag: before.element.tag,
+      count: sourceElements(html).length,
+    },
+  })
+}
+
+function writeFrame(path: string, html: string): void {
+  const temp = `${path}.${process.pid}${TEMP_SUFFIX}`
+  writeFileSync(temp, html)
+  renameSync(temp, path)
+}
+
+/** The element's state on each side of an edit, which undo restores. */
+export type EditObserver = (states: {
+  readonly before: ElementState
+  readonly after: ElementState
+}) => void
+
 /**
  * Edits one element of a frame file under the file's lock. An address carrying
  * a hash the file no longer has is refused rather than applied at an index the
  * change may have shifted. A selection that was fresh before the edit is
- * restamped after it, since the edit moves no element.
+ * restamped after it, since the edit moves no element. An observer hears the
+ * element's state before and after a write that landed, apart from the
+ * returned record, which the CLI prints.
  */
 export function editFrame(
   root: string,
@@ -294,6 +405,7 @@ export function editFrame(
   frame: string,
   address: ElementAddress,
   change: EditChange,
+  observe?: EditObserver,
 ): FrameEdit {
   const invalid = checkChange(change)
   if (invalid) return invalid
@@ -314,30 +426,25 @@ export function editFrame(
         `${page}/${frame} changed after this edit was made, so nothing was written`,
       )
     }
-    const before = readSelection(root)
-    const isSelectionFresh =
-      before?.page === page &&
-      before.frame === frame &&
-      before.element !== undefined &&
-      !before.element.stale
-
-    const applied = applyEdit(bytes.toString('utf8'), address, change)
+    const selected = readSelection(root)
+    const source = bytes.toString('utf8')
+
+    const applied = applyEdit(source, address, change)
     if (!applied.ok) return applied
 
-    const temp = `${path}.${process.pid}${TEMP_SUFFIX}`
-    writeFileSync(temp, applied.html)
-    renameSync(temp, path)
-
-    if (isSelectionFresh && before.element) {
-      writeSelection(root, {
-        page,
-        frame,
-        element: {
-          index: before.element.index,
-          tag: before.element.tag,
-          count: sourceElements(applied.html).length,
-        },
-      })
+    writeFrame(path, applied.html)
+    restampSelection(root, page, frame, selected, applied.html)
+
+    if (observe) {
+      const withInner = change.property === 'text'
+      const before = readElement(withoutBom(source), address.index)
+      const after = readElement(withoutBom(applied.html), address.index)
+      if (before && after) {
+        observe({
+          before: stateOf(before, withInner),
+          after: stateOf(after, withInner),
+        })
+      }
     }
     return {
       ok: true,
@@ -349,6 +456,81 @@ export function editFrame(
   })
 }
 
+export type RestoreRefusal = EditRefusal | 'changed'
+
+export type ElementRestore =
+  | { readonly ok: true; readonly hash: string }
+  | {
+      readonly ok: false
+      readonly reason: RestoreRefusal
+      readonly detail: string
+    }
+
+/**
+ * Writes a recorded state back to one element under the file's lock, only
+ * while the file holds as many elements as it did at the edit and the element
+ * at that index still carries the tag and the state the record expects. An
+ * unstyled state matches any unstyled sibling, so the count is what catches
+ * an element inserted or removed ahead of the target. Anything else means the
+ * file moved on since, so the restore refuses as `changed` rather than
+ * overwrite a newer state or land on a neighbor. The state comes from the
+ * server's own record, never a request, since inner content is written back
+ * as markup.
+ */
+export function restoreElement(
+  root: string,
+  page: string,
+  frame: string,
+  target: {
+    readonly index: number
+    readonly tag: string
+    readonly count: number
+  },
+  expected: ElementState,
+  to: ElementState,
+): ElementRestore {
+  const onPage = readPage(root, page)
+  if (!onPage) return refuse('no-page', `page ${page} does not exist`)
+  const found = onPage.frames.find((candidate) => candidate.name === frame)
+  if (!found) {
+    return refuse('no-frame', `frame ${frame} does not exist on ${page}`)
+  }
+
+  const path = join(canvasDir(root), page, found.file)
+  return withFileLock(path, (): ElementRestore => {
+    const source = readFileSync(path, 'utf8')
+    const bom = source.startsWith(BOM) ? BOM : ''
+    const html = source.slice(bom.length)
+    const current = readElement(html, target.index)
+    if (
+      sourceElements(html).length !== target.count ||
+      current?.tag !== target.tag ||
+      !sameState(current, expected)
+    ) {
+      return {
+        ok: false,
+        reason: 'changed',
+        detail: `<${target.tag}> in ${page}/${frame} changed since this edit, so nothing was written`,
+      }
+    }
+    const selected = readSelection(root)
+    const rewritten = countElements(new HTMLRewriter(), (element, at) => {
+      if (at !== target.index) return undefined
+      if (to.style === undefined) element.removeAttribute('style')
+      else element.setAttribute('style', to.style)
+      if (to.inner !== undefined) {
+        element.setInnerContent(to.inner, { html: true })
+      }
+      return undefined
+    }).transform(html)
+    const written = `${bom}${rewritten}`
+
+    writeFrame(path, written)
+    restampSelection(root, page, frame, selected, written)
+    return { ok: true, hash: contentHash(written) }
+  })
+}
+
 /**
  * Edits the element at an index of the file as it stands, for a caller that
  * holds no served frame to take an address from. The address it builds

package/src/canvas/history.ts

@@ -0,0 +1,116 @@
+import type { Box } from '@/canvas/content'
+
+/**
+ * The operator's shell edits, held by one `canon canvas serve` process. Only
+ * the server's write routes record here, so an edit made through a file or a
+ * CLI verb never enters it. An entry carries the state it replaced and the
+ * state it wrote, and applying it checks the second is still there.
+ */
+
+/** What an element entry restores: the raw style attribute, and raw inner content for a text edit. */
+export interface ElementState {
+  readonly style: string | undefined
+  readonly inner?: string
+}
+
+export interface ElementEntry {
+  readonly kind: 'element'
+  readonly page: string
+  readonly frame: string
+  readonly index: number
+  readonly tag: string
+  /** How many elements the file held, which an insert or removal ahead of the target changes. */
+  readonly count: number
+  readonly before: ElementState
+  readonly after: ElementState
+  /** Edits a control posts as one gesture share this, and merge into one entry. */
+  readonly step?: string
+}
+
+export interface BoxEntry {
+  readonly kind: 'box'
+  readonly page: string
+  readonly frame: string
+  /** Undefined when the layout held no box, so the reader placed the frame. */
+  readonly before: Box | undefined
+  readonly after: Box
+}
+
+export type HistoryEntry = ElementEntry | BoxEntry
+
+export type Direction = 'undo' | 'redo'
+
+/**
+ * `dropped` means the target changed since the entry was recorded, so the
+ * entry is discarded unwritten. `busy` leaves it in place to try again.
+ */
+export type ApplyResult = 'applied' | 'dropped' | 'busy'
+
+export type HistoryOutcome = ApplyResult | 'empty'
+
+export interface HistoryFlags {
+  readonly canUndo: boolean
+  readonly canRedo: boolean
+}
+
+export const HISTORY_CAP = 100
+
+function isSameTarget(a: ElementEntry, b: ElementEntry): boolean {
+  return (
+    a.page === b.page &&
+    a.frame === b.frame &&
+    a.index === b.index &&
+    a.tag === b.tag
+  )
+}
+
+export class History {
+  private readonly undone: HistoryEntry[] = []
+  private readonly done: HistoryEntry[] = []
+
+  constructor(private readonly cap = HISTORY_CAP) {}
+
+  record(entry: HistoryEntry): void {
+    this.undone.length = 0
+    const last = this.done.at(-1)
+    if (
+      entry.kind === 'element' &&
+      entry.step !== undefined &&
+      last?.kind === 'element' &&
+      last.step === entry.step &&
+      isSameTarget(last, entry)
+    ) {
+      this.done[this.done.length - 1] = { ...last, after: entry.after }
+      return
+    }
+    this.done.push(entry)
+    if (this.done.length > this.cap) this.done.shift()
+  }
+
+  undo(apply: (entry: HistoryEntry, direction: Direction) => ApplyResult) {
+    return this.move(this.done, this.undone, 'undo', apply)
+  }
+
+  redo(apply: (entry: HistoryEntry, direction: Direction) => ApplyResult) {
+    return this.move(this.undone, this.done, 'redo', apply)
+  }
+
+  flags(): HistoryFlags {
+    return { canUndo: this.done.length > 0, canRedo: this.undone.length > 0 }
+  }
+
+  private move(
+    from: HistoryEntry[],
+    to: HistoryEntry[],
+    direction: Direction,
+    apply: (entry: HistoryEntry, direction: Direction) => ApplyResult,
+  ): HistoryOutcome {
+    const entry = from.at(-1)
+    if (!entry) return 'empty'
+    const result = apply(entry, direction)
+    if (result === 'busy') return result
+    from.pop()
+    if (result === 'applied') to.push(entry)
+    return result
+  }
+}

package/src/canvas/server.ts

@@ -7,6 +7,7 @@ import {
   TOKENS_ATTRIBUTE,
 } from '@/canvas/address'
 import {
+  type BoxObserver,
   type ContentRefused,
   canvasDir,
   contentHash,
@@ -15,11 +16,18 @@ import {
   moveFrame,
   readSelection,
   resizeFrame,
+  restoreBox,
   TEMP_SUFFIX,
   writeSelection,
 } from '@/canvas/content'
-import { type EditRefused, editFrame } from '@/canvas/edit'
+import { type EditRefused, editFrame, restoreElement } from '@/canvas/edit'
 import { readEditing } from '@/canvas/editing'
+import {
+  type ApplyResult,
+  type Direction,
+  History,
+  type HistoryEntry,
+} from '@/canvas/history'
 import {
   resolveFrameTokens,
   type TokenOptions,
@@ -311,6 +319,59 @@ function isLoopbackOrigin(origin: string, port: number): boolean {
   )
 }
 
+/**
+ * Writes one entry back through the writer that recorded it. A busy lock
+ * keeps the entry for another try, and any other refusal means the target
+ * moved on or went, so the entry drops.
+ */
+function applyEntry(
+  root: string,
+  entry: HistoryEntry,
+  direction: Direction,
+): ApplyResult {
+  const isUndo = direction === 'undo'
+  const outcome =
+    entry.kind === 'element'
+      ? restoreElement(
+          root,
+          entry.page,
+          entry.frame,
+          entry,
+          isUndo ? entry.after : entry.before,
+          isUndo ? entry.before : entry.after,
+        )
+      : restoreBox(
+          root,
+          entry.page,
+          entry.frame,
+          isUndo ? entry.after : entry.before,
+          isUndo ? entry.before : entry.after,
+        )
+  if (outcome.ok) return 'applied'
+  return outcome.reason === 'busy' ? 'busy' : 'dropped'
+}
+
+function stepHistory(
+  root: string,
+  history: History,
+  direction: Direction,
+): Response {
+  const apply = (entry: HistoryEntry) => applyEntry(root, entry, direction)
+  const outcome =
+    direction === 'undo' ? history.undo(apply) : history.redo(apply)
+  if (outcome === 'busy') {
+    return json(
+      {
+        ok: false,
+        reason: 'busy',
+        detail: 'the file is being written, try again',
+      },
+      409,
+    )
+  }
+  return json({ ok: true, outcome, history: history.flags() })
+}
+
 function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === 'object' && value !== null
 }
@@ -444,6 +505,16 @@ export function startCanvas(
     embedFonts: true,
   })
   const changes = new ChangeStream(content)
+  /*
+   * Held here and written only by the shell's write routes, so an edit a CLI
+   * verb makes in its own process never enters it.
+   */
+  const history = new History()
+  const recordBox =
+    (page: string, frame: string): BoxObserver =>
+    (before, after) => {
+      history.record({ kind: 'box', page, frame, before, after })
+    }
   const first = options.port ?? CANVAS_PORT
 
   let bound: ReturnType<typeof bindFirstFree>
@@ -487,8 +558,15 @@ export function startCanvas(
               editing: readEditing(root, new Date()).map(
                 ({ page, frame, by, until }) => ({ page, frame, by, until }),
               ),
+              history: history.flags(),
             })
           }),
+          '/api/history/undo': {
+            POST: guarded(mutation(() => stepHistory(root, history, 'undo'))),
+          },
+          '/api/history/redo': {
+            POST: guarded(mutation(() => stepHistory(root, history, 'redo'))),
+          },
           '/api/frames/move': {
             POST: guarded(
               mutation((body) => {
@@ -501,10 +579,14 @@ export function startCanvas(
                 ) {
                   return badBody('send page, frame, x, and y')
                 }
-                const outcome = moveFrame(root, body.page, body.frame, {
-                  x: body.x,
-                  y: body.y,
-                })
+                const { page, frame } = body
+                const outcome = moveFrame(
+                  root,
+                  page,
+                  frame,
+                  { x: body.x, y: body.y },
+                  recordBox(page, frame),
+                )
                 return outcome.ok ? json(outcome) : refusal(outcome)
               }),
             ),
@@ -523,12 +605,19 @@ export function startCanvas(
                 ) {
                   return badBody('send page, frame, x, y, width, and height')
                 }
-                const outcome = resizeFrame(root, body.page, body.frame, {
-                  x: body.x,
-                  y: body.y,
-                  width: body.width,
-                  height: body.height,
-                })
+                const { page, frame } = body
+                const outcome = resizeFrame(
+                  root,
+                  page,
+                  frame,
+                  {
+                    x: body.x,
+                    y: body.y,
+                    width: body.width,
+                    height: body.height,
+                  },
+                  recordBox(page, frame),
+                )
                 return outcome.ok ? json(outcome) : refusal(outcome)
               }),
             ),
@@ -557,15 +646,32 @@ export function startCanvas(
                     'send an element as index, tag, count, and the hash it was served with',
                   )
                 }
+                const { page, frame, step } = body
+                if (step !== undefined && typeof step !== 'string') {
+                  return badBody('send step as a string, or leave it out')
+                }
                 const outcome = editFrame(
                   root,
-                  body.page,
-                  body.frame,
+                  page,
+                  frame,
                   element,
                   {
                     property: body.property,
                     value: body.value,
                   },
+                  ({ before, after }) => {
+                    history.record({
+                      kind: 'element',
+                      page,
+                      frame,
+                      index: element.index,
+                      tag: element.tag,
+                      count: element.count,
+                      before,
+                      after,
+                      ...(step !== undefined && { step }),
+                    })
+                  },
                 )
                 return outcome.ok ? json(outcome) : refusal(outcome)
               }),

package/src/canvas/tokens.ts

@@ -13,7 +13,7 @@ import {
   namedFamilies,
   projectSheets,
 } from '@/design/project-fonts'
-import { isOwnCheckout } from '@/project-root'
+import { isOwnCheckout } from '@/roots/project'
 
 /**
  * The stylesheet injected into every frame, so a frame drawn with

package/src/claude/seeds.ts

@@ -2,9 +2,9 @@ import { existsSync } from 'node:fs'
 import { chmod, mkdir, readFile, writeFile } from 'node:fs/promises'
 import { dirname, join, relative } from 'node:path'
 import { copyPreservingMode } from '@/sync/copy'
-import { creationRel, isRecordEntry } from '@/record-root'
+import { creationRel, isRecordEntry } from '@/roots/record'
 import { rewritesOnInstall, stripSeedMarker } from '@/tooling/seed-marker'
-import { SURFACE_ENTRIES, surfaceDir } from '@/surface-root'
+import { SURFACE_ENTRIES, surfaceDir } from '@/roots/surface'
 
 const SEEDS_DIR = join('tooling', 'claude', 'seeds')
 const CLAUDE_DIR = '.claude'

package/src/claude/skills-reach.ts

@@ -1,7 +1,7 @@
 import { existsSync, readFileSync } from 'node:fs'
 import { join } from 'node:path'
 import { resolveSkillsCorpus } from '@/claude/skills-list'
-import { SURFACE_ROOTS } from '@/surface-root'
+import { SURFACE_ROOTS } from '@/roots/surface'
 
 /**
  * The authoring roots this repository owns and no install channel delivers.

package/src/{exec.ts → cli/exec.ts}

@@ -1,7 +1,7 @@
 import { join } from 'node:path'
 import { execa } from 'execa'
-import { checkoutMismatchWarning, PROJECT_ROOT } from '@/project-root'
-import { logWarn } from '@/ui'
+import { checkoutMismatchWarning, PROJECT_ROOT } from '@/roots/project'
+import { logWarn } from '@/cli/ui'
 
 export async function execScript(
   script: string,

package/src/{help.ts → cli/help.ts}

@@ -1,4 +1,4 @@
-import { palette } from '@/ui'
+import { palette } from '@/cli/ui'
 
 const HELP_WIDTH = 80
 const SIGNATURE_WIDTH = 19

package/src/cli.ts

@@ -44,7 +44,7 @@ import { register as census } from '@/commands/census'
 import { register as targets } from '@/commands/targets'
 import { register as upgrade } from '@/commands/upgrade'
 import { readInstalled, UNKNOWN_LABEL } from '@/version/installed'
-import { renderHelp } from '@/help'
+import { renderHelp } from '@/cli/help'
 
 function showHelp(): void {
   console.log(renderHelp(process.stdout))

package/src/commands/audits.ts

@@ -20,7 +20,15 @@ import {
   summarize,
 } from '@/audits/run'
 import { gitEnv } from '@/git/env'
-import { intro, logError, logInfo, logStep, logWarn, outro, plural } from '@/ui'
+import {
+  intro,
+  logError,
+  logInfo,
+  logStep,
+  logWarn,
+  outro,
+  plural,
+} from '@/cli/ui'
 import { currentWorktreeRoot } from '@/git/worktree'
 
 interface RunCommandOptions {