@erclx/canon 5.15.0 → 5.17.0

package/src/canvas/content.ts

@@ -1,13 +1,23 @@
+import { createHash } from 'node:crypto'
 import {
+  closeSync,
   existsSync,
   mkdirSync,
+  openSync,
   readdirSync,
   readFileSync,
   renameSync,
+  rmSync,
   statSync,
+  unlinkSync,
   writeFileSync,
 } from 'node:fs'
 import { join } from 'node:path'
+import {
+  type ElementAddress,
+  resolveAddress,
+  type SourceElement,
+} from '@/canvas/address'
 import { recordDir } from '@/record-root'
 
 /**
@@ -21,6 +31,23 @@ export const CANVAS_FOLDER = 'canvas'
 
 export const LAYOUT_FILE = 'layout.json'
 
+/** The frame or element the operator pointed at, beside the pages it names. */
+export const SELECTION_FILE = 'selection.json'
+
+/** Suffix of the file a write goes through before it replaces its target. */
+export const TEMP_SUFFIX = '.tmp'
+
+/** Suffix of the file a writer holds while it reads, merges, and replaces. */
+export const LOCK_SUFFIX = '.lock'
+
+/** A lock older than this was left by a writer that died holding it. */
+const LOCK_STALE_MS = 10_000
+
+/** How long a writer waits on another's lock before it refuses. */
+const LOCK_WAIT_MS = 2_000
+
+const LOCK_POLL_MS = 5
+
 const FRAME_EXTENSION = '.html'
 
 /** The size a frame takes when nothing states one. */
@@ -62,7 +89,13 @@ export type ContentRefusal =
   | 'invalid-size'
   | 'exists'
   | 'no-page'
+  | 'no-frame'
+  | 'invalid-position'
   | 'malformed-layout'
+  | 'busy'
+  | 'invalid-address'
+  | 'address-mismatch'
+  | 'stale-address'
 
 export interface ContentRefused {
   readonly ok: false
@@ -155,12 +188,55 @@ function readLayout(dir: string): LayoutRead {
   return { boxes, malformed: false }
 }
 
+function sleep(ms: number): void {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms)
+}
+
+/**
+ * Holds an exclusive lock file for the length of a read, merge, and write. The
+ * server and a CLI verb are two processes, so a synchronous step inside either
+ * does not keep them from reading the same layout and each replacing it with
+ * its own edit, which loses the other's. A refused call leaves the file as it
+ * found it.
+ */
+function withLayoutLock(dir: string, run: () => FrameOutcome): FrameOutcome {
+  const lock = join(dir, `${LAYOUT_FILE}${LOCK_SUFFIX}`)
+  const deadline = Date.now() + LOCK_WAIT_MS
+  for (;;) {
+    try {
+      closeSync(openSync(lock, 'wx'))
+      break
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== 'EEXIST') throw error
+      const modified = statSync(lock, { throwIfNoEntry: false })?.mtimeMs
+      if (modified !== undefined && Date.now() - modified > LOCK_STALE_MS) {
+        rmSync(lock, { force: true })
+        continue
+      }
+      if (Date.now() >= deadline) {
+        return refuse('busy', `${LAYOUT_FILE} is being written, try again`)
+      }
+      sleep(LOCK_POLL_MS)
+    }
+  }
+  try {
+    return run()
+  } finally {
+    rmSync(lock, { force: true })
+  }
+}
+
+/**
+ * Replaces the file in one rename, so the shell reading while a CLI verb writes
+ * never sees half a layout and reports it as malformed. The caller holds
+ * `withLayoutLock`, which is what keeps two writers from losing each other.
+ */
 function writeLayout(dir: string, boxes: ReadonlyMap<string, Box>): void {
   const frames = Object.fromEntries(boxes)
-  writeFileSync(
-    join(dir, LAYOUT_FILE),
-    `${JSON.stringify({ frames }, null, 2)}\n`,
-  )
+  const target = join(dir, LAYOUT_FILE)
+  const temp = `${target}.${process.pid}${TEMP_SUFFIX}`
+  writeFileSync(temp, `${JSON.stringify({ frames }, null, 2)}\n`)
+  renameSync(temp, target)
 }
 
 function frameNames(dir: string): string[] {
@@ -308,19 +384,234 @@ export function addFrame(
     return refuse('exists', `frame ${frame} already exists on ${page}`)
   }
 
-  /*
-   * Placed against the boxes a reader would draw, unplaced frames included, so
-   * a new frame never lands under one the layout has yet to name.
+  return withLayoutLock(dir, () => {
+    /*
+     * Placed against the boxes a reader would draw, unplaced frames included,
+     * so a new frame never lands under one the layout has yet to name.
+     */
+    const current = readPage(root, page)?.frames ?? []
+    const { boxes, malformed } = readLayout(dir)
+    /* Writing over a layout that does not parse would erase every box in it. */
+    if (malformed) {
+      return refuse('malformed-layout', `${page}/${LAYOUT_FILE} does not parse`)
+    }
+    const box: Box = { x: nextX(current), y: 0, ...size }
+
+    writeFileSync(join(dir, file), frameScaffold(frame))
+    writeLayout(dir, new Map([...boxes, [frame, box]]))
+    return { ok: true, page, frame, file, box }
+  })
+}
+
+export interface Position {
+  readonly x: number
+  readonly y: number
+}
+
+/**
+ * Moves one frame and keeps its size. A frame the layout never named takes the
+ * default size it was already drawn at, so the move does not resize it.
+ */
+export function moveFrame(
+  root: string,
+  page: string,
+  frame: string,
+  to: Position,
+): FrameOutcome {
+  if (!isValidName(page)) {
+    return refuse('invalid-name', `${page} is not a valid page name`)
+  }
+  if (!isValidName(frame)) {
+    return refuse('invalid-name', `${frame} is not a valid frame name`)
+  }
+  if (!Number.isFinite(to.x) || !Number.isFinite(to.y)) {
+    return refuse('invalid-position', 'x and y must be numbers')
+  }
+
+  const dir = pagePath(root, page)
+  if (!isDirectory(dir)) return refuse('no-page', `page ${page} does not exist`)
+  const file = `${frame}${FRAME_EXTENSION}`
+  if (!existsSync(join(dir, file))) {
+    return refuse('no-frame', `frame ${frame} does not exist on ${page}`)
+  }
+
+  return withLayoutLock(dir, () => {
+    const { boxes, malformed } = readLayout(dir)
+    if (malformed) {
+      return refuse('malformed-layout', `${page}/${LAYOUT_FILE} does not parse`)
+    }
+    const size = boxes.get(frame) ?? DEFAULT_FRAME
+    const box: Box = {
+      x: to.x,
+      y: to.y,
+      width: size.width,
+      height: size.height,
+    }
+
+    writeLayout(dir, new Map([...boxes, [frame, box]]))
+    return { ok: true, page, frame, file, box }
+  })
+}
+
+export interface Selection {
+  readonly page: string
+  readonly frame: string
+  readonly element?: ElementAddress
+}
+
+export interface SelectedElement extends SourceElement {
+  readonly index: number
+  /**
+   * Whether the frame file changed since the element was picked. The address
+   * is an index, so an edit can shift it onto another element, and the fields
+   * here are what was picked rather than what sits at the index now.
    */
-  const current = readPage(root, page)?.frames ?? []
-  const { boxes, malformed } = readLayout(dir)
-  /* Writing over a layout that does not parse would erase every box in it. */
-  if (malformed) {
-    return refuse('malformed-layout', `${page}/${LAYOUT_FILE} does not parse`)
+  readonly stale: boolean
+}
+
+export interface SelectedFrame {
+  readonly page: string
+  readonly frame: string
+  readonly file: string
+  readonly box: Box
+  readonly element?: SelectedElement
+}
+
+export type SelectionOutcome = { readonly ok: true } | ContentRefused
+
+interface StoredElement extends SourceElement {
+  readonly index: number
+  readonly hash: string
+}
+
+function selectionPath(root: string): string {
+  return join(canvasDir(root), SELECTION_FILE)
+}
+
+export function contentHash(html: string | Uint8Array): string {
+  return createHash('sha256').update(html).digest('hex')
+}
+
+function isAddress(value: ElementAddress): boolean {
+  return (
+    Number.isInteger(value.index) &&
+    Number.isInteger(value.count) &&
+    value.index >= 0 &&
+    value.index < value.count &&
+    typeof value.tag === 'string' &&
+    value.tag !== ''
+  )
+}
+
+/**
+ * Records which frame, or which element in it, "this one" means, or clears it.
+ * Only a frame on disk can be recorded, and only an element the file holds at
+ * the address given, so the file never names something a reader would have to
+ * guess about.
+ */
+export function writeSelection(
+  root: string,
+  selection: Selection | undefined,
+): SelectionOutcome {
+  if (selection === undefined) {
+    if (existsSync(selectionPath(root))) unlinkSync(selectionPath(root))
+    return { ok: true }
   }
-  const box: Box = { x: nextX(current), y: 0, ...size }
 
-  writeFileSync(join(dir, file), frameScaffold(frame))
-  writeLayout(dir, new Map([...boxes, [frame, box]]))
-  return { ok: true, page, frame, file, box }
+  const { page, frame, element } = selection
+  if (!isValidName(page) || !isValidName(frame)) {
+    return refuse('invalid-name', `${page}/${frame} is not a valid frame`)
+  }
+  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}`)
+  }
+
+  let stored: StoredElement | undefined
+  if (element !== undefined) {
+    if (!isAddress(element)) {
+      return refuse(
+        'invalid-address',
+        'an element address needs a whole index below its count and a tag',
+      )
+    }
+    const bytes = readFileSync(join(pagePath(root, page), found.file))
+    const hash = contentHash(bytes)
+    const html = bytes.toString('utf8')
+    if (element.hash !== undefined && element.hash !== hash) {
+      return refuse(
+        'stale-address',
+        `${page}/${frame} changed after the pick was made, so pick it again`,
+      )
+    }
+    const check = resolveAddress(html, element)
+    if (!check.ok) return refuse(check.reason, check.detail)
+    stored = { index: element.index, ...check.element, hash }
+  }
+
+  const target = selectionPath(root)
+  const temp = `${target}.${process.pid}${TEMP_SUFFIX}`
+  const record = stored ? { page, frame, element: stored } : { page, frame }
+  writeFileSync(temp, `${JSON.stringify(record)}\n`)
+  renameSync(temp, target)
+  return { ok: true }
+}
+
+function readStoredElement(value: unknown): StoredElement | undefined {
+  if (typeof value !== 'object' || value === null) return undefined
+  const { index, tag, classes, text, hash } = value as Record<string, unknown>
+  if (
+    typeof index !== 'number' ||
+    typeof tag !== 'string' ||
+    !Array.isArray(classes) ||
+    !classes.every((name) => typeof name === 'string') ||
+    typeof text !== 'string' ||
+    typeof hash !== 'string'
+  ) {
+    return undefined
+  }
+  return { index, tag, classes, text, hash }
+}
+
+/**
+ * The selected frame with its box, or undefined when nothing is selected, the
+ * file does not parse, or the frame it names has since been removed, so a
+ * reader never gets a stale name back. An element is reported as picked, with
+ * `stale` set once the frame file no longer matches what was picked from.
+ */
+export function readSelection(root: string): SelectedFrame | undefined {
+  const path = selectionPath(root)
+  if (!existsSync(path)) return undefined
+
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(readFileSync(path, 'utf8'))
+  } catch {
+    return undefined
+  }
+  if (typeof parsed !== 'object' || parsed === null) return undefined
+  const { page, frame, element } = parsed as Record<string, unknown>
+  if (typeof page !== 'string' || typeof frame !== 'string') return undefined
+
+  const found = readPage(root, page)?.frames.find(
+    (candidate) => candidate.name === frame,
+  )
+  if (!found) return undefined
+  const { x, y, width, height } = found
+  const selected = {
+    page,
+    frame,
+    file: found.file,
+    box: { x, y, width, height },
+  }
+
+  const stored = readStoredElement(element)
+  if (!stored) return selected
+  const { hash, ...picked } = stored
+  const current = contentHash(
+    readFileSync(join(pagePath(root, page), found.file)),
+  )
+  return { ...selected, element: { ...picked, stale: current !== hash } }
 }

package/src/canvas/server.ts

@@ -1,5 +1,20 @@
 import { type FSWatcher, mkdirSync, watch } from 'node:fs'
-import { canvasDir, listPages } from '@/canvas/content'
+import {
+  type ElementAddress,
+  HASH_ATTRIBUTE,
+  TOKENS_ATTRIBUTE,
+} from '@/canvas/address'
+import {
+  type ContentRefused,
+  canvasDir,
+  contentHash,
+  listPages,
+  LOCK_SUFFIX,
+  moveFrame,
+  readSelection,
+  TEMP_SUFFIX,
+  writeSelection,
+} from '@/canvas/content'
 import { resolveFrameTokens, type TokenOptions } from '@/canvas/tokens'
 import { buildDesignCss } from '@/design/css'
 import {
@@ -61,21 +76,31 @@ export interface ChangeEvent {
   readonly file: string
 }
 
-/** Escapes the one sequence that would end the injected element early. */
-function styleElement(css: string): string {
-  return `<style data-canvas-tokens>${css.replaceAll('</style', '<\\/style')}</style>`
+/**
+ * Escapes the one sequence that would end the injected element early. The
+ * hash is hex, so it needs no escaping inside the attribute.
+ */
+function styleElement(css: string, hash: string | undefined): string {
+  const stamp = hash === undefined ? '' : ` ${HASH_ATTRIBUTE}="${hash}"`
+  return `<style ${TOKENS_ATTRIBUTE}${stamp}>${css.replaceAll('</style', '<\\/style')}</style>`
 }
 
 /**
  * Puts the tokens first in the head, so a stylesheet the frame links itself
- * still wins the cascade. A frame with no head gets the element ahead of
- * everything, which a browser hoists into the head it builds.
+ * still wins the cascade. A frame with no head gets the element right after
+ * its doctype, which a browser hoists into the head it builds. A hash stamps
+ * the element even when no tokens resolve, since the shell sends it back with
+ * an element pick.
  */
-export function injectTokens(html: string, css: string): string {
-  if (css === '') return html
-  const element = styleElement(css)
+export function injectTokens(html: string, css: string, hash?: string): string {
+  if (css === '' && hash === undefined) return html
+  const element = styleElement(css, hash)
   const head = html.match(/<head(?:\s[^>]*)?>/i)
-  if (head?.index === undefined) return `${element}${html}`
+  if (head?.index === undefined) {
+    /* Ahead of a doctype the element would drop the frame into quirks mode. */
+    const doctype = html.match(/^\s*<!doctype[^>]*>/i)?.[0] ?? ''
+    return `${doctype}${element}${html.slice(doctype.length)}`
+  }
   const at = head.index + head[0].length
   return `${html.slice(0, at)}${element}${html.slice(at)}`
 }
@@ -105,8 +130,9 @@ function guarded(handler: Handler): Handler {
         })
 }
 
-function json(body: unknown): Response {
+function json(body: unknown, status = 200): Response {
   return new Response(JSON.stringify(body), {
+    status,
     headers: {
       'content-type': 'application/json; charset=utf-8',
       'cache-control': 'no-store',
@@ -114,6 +140,79 @@ function json(body: unknown): Response {
   })
 }
 
+const REFUSAL_STATUS: Record<ContentRefused['reason'], number> = {
+  'invalid-name': 400,
+  'invalid-size': 400,
+  'invalid-position': 400,
+  'no-page': 404,
+  'no-frame': 404,
+  exists: 409,
+  'malformed-layout': 409,
+  busy: 409,
+  'invalid-address': 400,
+  'address-mismatch': 409,
+  'stale-address': 409,
+}
+
+function refusal(refused: ContentRefused): Response {
+  return json(refused, REFUSAL_STATUS[refused.reason])
+}
+
+function badBody(detail: string): Response {
+  return json({ ok: false, reason: 'invalid-body', detail }, 400)
+}
+
+/**
+ * The Host guard cannot tell the shell from a page on another origin that
+ * reaches this socket, since a browser sends the loopback Host either way. A
+ * write also carries an Origin when a page sent it, so one naming any other
+ * origin is refused, and a JSON content type forces that page through a
+ * preflight this server never answers.
+ */
+function mutation(handler: (body: unknown) => Response): Handler {
+  return async (request, server) => {
+    const origin = request.headers.get('origin')
+    if (origin !== null && !isLoopbackOrigin(origin, server.port ?? 0)) {
+      return new Response('Forbidden\n', { status: 403 })
+    }
+    const type = request.headers.get('content-type') ?? ''
+    if (!type.startsWith('application/json')) {
+      return json(
+        { ok: false, reason: 'invalid-body', detail: 'send application/json' },
+        415,
+      )
+    }
+    let body: unknown
+    try {
+      body = await request.json()
+    } catch {
+      return badBody('the body is not JSON')
+    }
+    return handler(body)
+  }
+}
+
+function isLoopbackOrigin(origin: string, port: number): boolean {
+  return (
+    origin === `http://${SERVE_HOST}:${port}` ||
+    origin === `http://localhost:${port}`
+  )
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null
+}
+
+function isAddressShape(value: unknown): value is ElementAddress {
+  return (
+    isRecord(value) &&
+    typeof value.index === 'number' &&
+    typeof value.tag === 'string' &&
+    typeof value.count === 'number' &&
+    (value.hash === undefined || typeof value.hash === 'string')
+  )
+}
+
 async function serveFrame(
   root: string,
   content: string,
@@ -128,7 +227,13 @@ async function serveFrame(
   if (file.status !== 200 || !type.startsWith('text/html')) return file
 
   const { css } = resolveFrameTokens(root, tokens)
-  return new Response(injectTokens(await file.text(), css), {
+  /*
+   * Hashed over the bytes on disk, the same input `writeSelection` reads,
+   * since decoding to text drops a byte order mark the file still holds.
+   */
+  const bytes = new Uint8Array(await file.arrayBuffer())
+  const html = new TextDecoder().decode(bytes)
+  return new Response(injectTokens(html, css, contentHash(bytes)), {
     headers: { 'content-type': type, 'cache-control': 'no-store' },
   })
 }
@@ -158,6 +263,8 @@ class ChangeStream {
   private queue(path: string): void {
     const [page, ...rest] = path.split(/[\\/]/)
     if (page === undefined || page === '') return
+    /* A write's staging or lock file, gone a moment later. */
+    if (path.endsWith(TEMP_SUFFIX) || path.endsWith(LOCK_SUFFIX)) return
     clearTimeout(this.pending.get(path))
     this.pending.set(
       path,
@@ -245,8 +352,70 @@ export function startCanvas(
           '/api/pages': guarded(() => {
             const resolved = resolveFrameTokens(root, tokens)
             const { css: _css, ...source } = resolved
-            return json({ pages: listPages(root), tokens: source })
+            const selected = readSelection(root)
+            return json({
+              pages: listPages(root),
+              tokens: source,
+              selection: selected && {
+                page: selected.page,
+                frame: selected.frame,
+                ...(selected.element && {
+                  element: {
+                    index: selected.element.index,
+                    tag: selected.element.tag,
+                    stale: selected.element.stale,
+                  },
+                }),
+              },
+            })
           }),
+          '/api/frames/move': {
+            POST: guarded(
+              mutation((body) => {
+                if (
+                  !isRecord(body) ||
+                  typeof body.page !== 'string' ||
+                  typeof body.frame !== 'string' ||
+                  typeof body.x !== 'number' ||
+                  typeof body.y !== 'number'
+                ) {
+                  return badBody('send page, frame, x, and y')
+                }
+                const outcome = moveFrame(root, body.page, body.frame, {
+                  x: body.x,
+                  y: body.y,
+                })
+                return outcome.ok ? json(outcome) : refusal(outcome)
+              }),
+            ),
+          },
+          '/api/selection': {
+            POST: guarded(
+              mutation((body) => {
+                if (!isRecord(body)) return badBody('send a frame or {}')
+                const { page, frame } = body
+                const target =
+                  typeof page === 'string' && typeof frame === 'string'
+                    ? { page, frame }
+                    : undefined
+                if (target === undefined && (page != null || frame != null)) {
+                  return badBody('send both page and frame, or neither')
+                }
+                const { element } = body
+                if (element != null && target === undefined) {
+                  return badBody('send an element with its page and frame')
+                }
+                if (element != null && !isAddressShape(element)) {
+                  return badBody('send an element as index, tag, and count')
+                }
+                const outcome = writeSelection(
+                  root,
+                  target && element != null ? { ...target, element } : target,
+                )
+                return outcome.ok ? json(outcome) : refusal(outcome)
+              }),
+            ),
+          },
           '/api/chrome.css': guarded(
             () =>
               new Response(chromeCss, {

package/src/claude/cases/misc.ts

@@ -79,6 +79,11 @@ export const MISC_CASES: readonly SkillCase[] = [
       'The same discount rule sits in two files and I need a third variant. Should I extract it, or add a strategy class for the two cases?',
     expect: 'code-craft',
   },
+  {
+    prompt:
+      'Find me the strongest evidence on whether rent control reduces housing supply. Where should I look?',
+    expect: 'search-craft',
+  },
   {
     prompt:
       "I've got the plan approved and it touches the parser, the command, and the docs. How should I build it so I don't end up with one giant diff?",