@erclx/canon 5.14.0 → 5.15.0

package/src/canvas/content.ts

@@ -0,0 +1,326 @@
+import {
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  renameSync,
+  statSync,
+  writeFileSync,
+} from 'node:fs'
+import { join } from 'node:path'
+import { recordDir } from '@/record-root'
+
+/**
+ * The content format. A page is a folder under the record root's `canvas/`, a
+ * frame is one `.html` file in it, and `layout.json` beside them holds each
+ * frame's box. The HTML stays a plain file so an agent edits a frame the way it
+ * edits any other file, and the box lives apart from it so moving a frame never
+ * rewrites its markup.
+ */
+export const CANVAS_FOLDER = 'canvas'
+
+export const LAYOUT_FILE = 'layout.json'
+
+const FRAME_EXTENSION = '.html'
+
+/** The size a frame takes when nothing states one. */
+export const DEFAULT_FRAME = { width: 1440, height: 900 } as const
+
+/** Horizontal space between frames placed in a row. */
+export const FRAME_GAP = 80
+
+/**
+ * One path segment with no dot leading it, so a name can neither climb out of
+ * the canvas folder nor hide as a dotfile the listing skips.
+ */
+const NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*$/
+
+export interface Box {
+  readonly x: number
+  readonly y: number
+  readonly width: number
+  readonly height: number
+}
+
+export interface Frame extends Box {
+  readonly name: string
+  /** Relative to the page folder. */
+  readonly file: string
+  /** Whether the layout stated this box, or the reader placed it in a row. */
+  readonly placed: boolean
+}
+
+export interface Page {
+  readonly name: string
+  readonly frames: readonly Frame[]
+  /** Set when `layout.json` exists and does not parse. Frames still list. */
+  readonly layoutIssue?: 'malformed'
+}
+
+export type ContentRefusal =
+  | 'invalid-name'
+  | 'invalid-size'
+  | 'exists'
+  | 'no-page'
+  | 'malformed-layout'
+
+export interface ContentRefused {
+  readonly ok: false
+  readonly reason: ContentRefusal
+  readonly detail: string
+}
+
+export type PageOutcome =
+  | { readonly ok: true; readonly page: string }
+  | ContentRefused
+
+export type FrameOutcome =
+  | {
+      readonly ok: true
+      readonly page: string
+      readonly frame: string
+      readonly file: string
+      readonly box: Box
+    }
+  | ContentRefused
+
+export function canvasDir(root: string): string {
+  return recordDir(root, CANVAS_FOLDER)
+}
+
+function pagePath(root: string, page: string): string {
+  return join(canvasDir(root), page)
+}
+
+function refuse(reason: ContentRefusal, detail: string): ContentRefused {
+  return { ok: false, reason, detail }
+}
+
+function isValidName(name: string): boolean {
+  return NAME_PATTERN.test(name) && !name.includes('..')
+}
+
+function isDirectory(path: string): boolean {
+  return statSync(path, { throwIfNoEntry: false })?.isDirectory() ?? false
+}
+
+function isBox(value: unknown): value is Box {
+  if (typeof value !== 'object' || value === null) return false
+  const box = value as Record<string, unknown>
+  return ['x', 'y', 'width', 'height'].every(
+    (key) => typeof box[key] === 'number' && Number.isFinite(box[key]),
+  )
+}
+
+interface LayoutRead {
+  readonly boxes: ReadonlyMap<string, Box>
+  readonly malformed: boolean
+}
+
+/**
+ * Reads what a layout states and nothing else. An entry with a box that is not
+ * four finite numbers is skipped rather than refused, since one bad entry
+ * should cost that frame its position and not the whole page its frames.
+ */
+function readLayout(dir: string): LayoutRead {
+  const path = join(dir, LAYOUT_FILE)
+  if (!existsSync(path)) return { boxes: new Map(), malformed: false }
+
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(readFileSync(path, 'utf8'))
+  } catch {
+    return { boxes: new Map(), malformed: true }
+  }
+
+  const frames =
+    typeof parsed === 'object' && parsed !== null
+      ? (parsed as { frames?: unknown }).frames
+      : undefined
+  if (typeof frames !== 'object' || frames === null) {
+    return { boxes: new Map(), malformed: true }
+  }
+
+  const boxes = new Map<string, Box>()
+  for (const [name, box] of Object.entries(frames)) {
+    if (isBox(box)) {
+      boxes.set(name, {
+        x: box.x,
+        y: box.y,
+        width: box.width,
+        height: box.height,
+      })
+    }
+  }
+  return { boxes, malformed: false }
+}
+
+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`,
+  )
+}
+
+function frameNames(dir: string): string[] {
+  return readdirSync(dir)
+    .filter((entry) => entry.endsWith(FRAME_EXTENSION))
+    .map((entry) => entry.slice(0, -FRAME_EXTENSION.length))
+    .filter(isValidName)
+    .sort((a, b) => a.localeCompare(b))
+}
+
+/** The x a frame starts at when it joins the row after every box given. */
+function nextX(boxes: Iterable<Box>): number {
+  let right: number | undefined
+  for (const box of boxes) {
+    const edge = box.x + box.width
+    right = right === undefined ? edge : Math.max(right, edge)
+  }
+  return right === undefined ? 0 : right + FRAME_GAP
+}
+
+export function readPage(root: string, page: string): Page | undefined {
+  if (!isValidName(page)) return undefined
+  const dir = pagePath(root, page)
+  if (!isDirectory(dir)) return undefined
+
+  const { boxes, malformed } = readLayout(dir)
+  const names = frameNames(dir)
+
+  const placed = names.filter((name) => boxes.has(name))
+  const frames: Frame[] = []
+  for (const name of placed) {
+    const box = boxes.get(name)
+    if (box) {
+      frames.push({
+        name,
+        file: `${name}${FRAME_EXTENSION}`,
+        ...box,
+        placed: true,
+      })
+    }
+  }
+
+  for (const name of names.filter((candidate) => !boxes.has(candidate))) {
+    frames.push({
+      name,
+      file: `${name}${FRAME_EXTENSION}`,
+      x: nextX(frames),
+      y: 0,
+      ...DEFAULT_FRAME,
+      placed: false,
+    })
+  }
+
+  frames.sort((a, b) => a.name.localeCompare(b.name))
+  return malformed
+    ? { name: page, frames, layoutIssue: 'malformed' }
+    : { name: page, frames }
+}
+
+export function listPages(root: string): Page[] {
+  const dir = canvasDir(root)
+  if (!isDirectory(dir)) return []
+
+  return readdirSync(dir)
+    .filter(isValidName)
+    .filter((name) => isDirectory(join(dir, name)))
+    .sort((a, b) => a.localeCompare(b))
+    .flatMap((name) => readPage(root, name) ?? [])
+}
+
+export function addPage(root: string, page: string): PageOutcome {
+  if (!isValidName(page)) {
+    return refuse('invalid-name', `${page} is not a valid page name`)
+  }
+  const dir = pagePath(root, page)
+  if (existsSync(dir)) return refuse('exists', `page ${page} already exists`)
+
+  mkdirSync(dir, { recursive: true })
+  return { ok: true, page }
+}
+
+export function renamePage(
+  root: string,
+  from: string,
+  to: string,
+): PageOutcome {
+  if (!isValidName(from) || !isValidName(to)) {
+    return refuse(
+      'invalid-name',
+      `${isValidName(from) ? to : from} is not a valid page name`,
+    )
+  }
+  const source = pagePath(root, from)
+  if (!isDirectory(source))
+    return refuse('no-page', `page ${from} does not exist`)
+  const target = pagePath(root, to)
+  if (existsSync(target)) return refuse('exists', `page ${to} already exists`)
+
+  renameSync(source, target)
+  return { ok: true, page: to }
+}
+
+function frameScaffold(name: string): string {
+  return `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <title>${name}</title>
+  </head>
+  <body>
+    <main>
+      <h1>${name}</h1>
+    </main>
+  </body>
+</html>
+`
+}
+
+export interface FrameSize {
+  readonly width: number
+  readonly height: number
+}
+
+export function addFrame(
+  root: string,
+  page: string,
+  frame: string,
+  size: FrameSize,
+): 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`)
+  }
+  const isPositive = (value: number) => Number.isFinite(value) && value > 0
+  if (!isPositive(size.width) || !isPositive(size.height)) {
+    return refuse('invalid-size', 'width and height must be positive 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('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.
+   */
+  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 }
+}

package/src/canvas/index.html

@@ -0,0 +1,14 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Canvas</title>
+    <link rel="icon" href="data:," />
+    <link rel="stylesheet" href="./client/shell.css" />
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="./client/main.tsx"></script>
+  </body>
+</html>

package/src/canvas/server.ts

@@ -0,0 +1,302 @@
+import { type FSWatcher, mkdirSync, watch } from 'node:fs'
+import { canvasDir, listPages } from '@/canvas/content'
+import { resolveFrameTokens, type TokenOptions } from '@/canvas/tokens'
+import { buildDesignCss } from '@/design/css'
+import {
+  bindFirstFree,
+  PORT_ATTEMPTS,
+  respond,
+  SERVE_HOST,
+  type ServeRefusal,
+} from '@/serve/static'
+
+/** Clear of `canon serve`'s default, so a lesson preview and the canvas both open. */
+export const CANVAS_PORT = 8790
+
+/** The URL prefix a frame and the files beside it are served under. */
+export const FRAMES_PREFIX = '/frames/'
+
+/**
+ * How long a burst of watch events for one file waits before it is sent. One
+ * editor save raises several, and each would otherwise reload the frame again.
+ */
+const SETTLE_MS = 40
+
+export interface CanvasStarted {
+  readonly ok: true
+  readonly root: string
+  readonly content: string
+  readonly host: string
+  readonly port: number
+  readonly url: string
+  readonly stop: () => Promise<void>
+}
+
+export interface CanvasRefused {
+  readonly ok: false
+  readonly reason: Extract<ServeRefusal, 'no-port' | 'bind-failed'>
+  readonly detail: string
+}
+
+export type CanvasOutcome = CanvasStarted | CanvasRefused
+
+export interface CanvasOptions {
+  readonly port?: number
+  /**
+   * What answers `/`. The command passes the HTML import of `index.html`, which
+   * `Bun.serve` bundles on request, and a test passes a plain response, since
+   * the test runner cannot load an HTML module.
+   */
+  readonly shell: Bun.HTMLBundle | Response
+  readonly tokens?: TokenOptions
+}
+
+export interface ChangeEvent {
+  readonly page: string
+  /**
+   * The path under the page folder, or empty when the change is to the
+   * top-level entry itself, being a page folder added, renamed, or removed.
+   * An empty file names no frame, so a reader rereads the page list alone.
+   */
+  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>`
+}
+
+/**
+ * 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.
+ */
+export function injectTokens(html: string, css: string): string {
+  if (css === '') return html
+  const element = styleElement(css)
+  const head = html.match(/<head(?:\s[^>]*)?>/i)
+  if (head?.index === undefined) return `${element}${html}`
+  const at = head.index + head[0].length
+  return `${html.slice(0, at)}${element}${html.slice(at)}`
+}
+
+/**
+ * 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}`
+}
+
+type Handler = (
+  request: Request,
+  server: Bun.Server<undefined>,
+) => Response | Promise<Response>
+
+function guarded(handler: Handler): Handler {
+  return (request, server) =>
+    isLoopbackHost(request.headers.get('host'), server.port ?? 0)
+      ? handler(request, server)
+      : new Response('Forbidden\n', {
+          status: 403,
+          headers: { 'content-type': 'text/plain; charset=utf-8' },
+        })
+}
+
+function json(body: unknown): Response {
+  return new Response(JSON.stringify(body), {
+    headers: {
+      'content-type': 'application/json; charset=utf-8',
+      'cache-control': 'no-store',
+    },
+  })
+}
+
+async function serveFrame(
+  root: string,
+  content: string,
+  request: Request,
+  tokens: TokenOptions,
+): Promise<Response> {
+  const url = new URL(request.url)
+  url.pathname = `/${url.pathname.slice(FRAMES_PREFIX.length)}`
+  const file = await respond(content, new Request(url))
+
+  const type = file.headers.get('content-type') ?? ''
+  if (file.status !== 200 || !type.startsWith('text/html')) return file
+
+  const { css } = resolveFrameTokens(root, tokens)
+  return new Response(injectTokens(await file.text(), css), {
+    headers: { 'content-type': type, 'cache-control': 'no-store' },
+  })
+}
+
+/**
+ * Fans each change under the canvas folder out to every open shell. The first
+ * segment names the page and the rest names the file within it, so a
+ * top-level entry goes out with an empty file. Only an empty path is skipped.
+ */
+class ChangeStream {
+  private readonly clients = new Set<ReadableStreamDefaultController<string>>()
+  private readonly pending = new Map<string, ReturnType<typeof setTimeout>>()
+  private readonly watcher: FSWatcher
+
+  constructor(content: string) {
+    this.watcher = watch(content, { recursive: true }, (_event, filename) => {
+      if (filename) this.queue(filename.toString())
+    })
+  }
+
+  /**
+   * A one-segment path is kept because the recursive watch reports a page
+   * folder appearing, going, or being renamed under its bare name with nothing
+   * beneath it. A stray file beside the pages goes out the same way, which
+   * costs the shell one page-list reread.
+   */
+  private queue(path: string): void {
+    const [page, ...rest] = path.split(/[\\/]/)
+    if (page === undefined || page === '') return
+    clearTimeout(this.pending.get(path))
+    this.pending.set(
+      path,
+      setTimeout(() => {
+        this.pending.delete(path)
+        this.send({ page, file: rest.join('/') })
+      }, SETTLE_MS),
+    )
+  }
+
+  private send(change: ChangeEvent): void {
+    const frame = `data: ${JSON.stringify(change)}\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',
+      },
+    })
+  }
+
+  close(): void {
+    this.watcher.close()
+    for (const timer of this.pending.values()) clearTimeout(timer)
+    for (const client of this.clients) {
+      try {
+        client.close()
+      } catch {
+        /* Already closed by the browser going away. */
+      }
+    }
+    this.clients.clear()
+  }
+}
+
+export function startCanvas(
+  root: string,
+  options: CanvasOptions,
+): CanvasOutcome {
+  const content = canvasDir(root)
+  /* Created up front, since the change stream has to watch something. */
+  mkdirSync(content, { recursive: true })
+
+  const tokens = options.tokens ?? {}
+  /*
+   * Fonts embedded, so the chrome renders in its own face on a machine that
+   * never installed it rather than in whatever the fallback stack finds.
+   */
+  const chromeCss = buildDesignCss(undefined, {
+    components: false,
+    embedFonts: true,
+  })
+  const changes = new ChangeStream(content)
+  const first = options.port ?? CANVAS_PORT
+
+  let bound: ReturnType<typeof bindFirstFree>
+  try {
+    bound = bindFirstFree(first, (port) =>
+      Bun.serve({
+        hostname: SERVE_HOST,
+        port,
+        development: false,
+        /* The change stream stays open for as long as the shell does. */
+        idleTimeout: 0,
+        routes: {
+          /*
+           * The shell and the chunks it bundles carry toolkit code and no
+           * project content, so they are the one route left unguarded.
+           */
+          '/': options.shell,
+          '/api/pages': guarded(() => {
+            const resolved = resolveFrameTokens(root, tokens)
+            const { css: _css, ...source } = resolved
+            return json({ pages: listPages(root), tokens: source })
+          }),
+          '/api/chrome.css': guarded(
+            () =>
+              new Response(chromeCss, {
+                headers: {
+                  'content-type': 'text/css; charset=utf-8',
+                  'cache-control': 'no-store',
+                },
+              }),
+          ),
+          '/api/events': guarded(() => changes.open()),
+        },
+        fetch: guarded((request) => {
+          const { pathname } = new URL(request.url)
+          if (pathname.startsWith(FRAMES_PREFIX)) {
+            return serveFrame(root, content, request, tokens)
+          }
+          return new Response('Not found\n', { status: 404 })
+        }),
+      }),
+    )
+  } catch (error) {
+    changes.close()
+    const code = (error as NodeJS.ErrnoException).code ?? 'unknown'
+    return {
+      ok: false,
+      reason: 'bind-failed',
+      detail: `could not bind ${SERVE_HOST}:${first} (${code})`,
+    }
+  }
+
+  if (!bound) {
+    changes.close()
+    return {
+      ok: false,
+      reason: 'no-port',
+      detail: `no free port between ${first} and ${first + PORT_ATTEMPTS - 1}`,
+    }
+  }
+
+  const { server, port } = bound
+  return {
+    ok: true,
+    root,
+    content,
+    host: SERVE_HOST,
+    port,
+    url: `http://${SERVE_HOST}:${port}/`,
+    stop: async () => {
+      changes.close()
+      await server.stop(true)
+    },
+  }
+}

package/src/canvas/tokens.ts

@@ -0,0 +1,71 @@
+import { existsSync, readdirSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { DESIGN_INSTALL_DIR, DESIGN_PROJECT_SUBDIR } from '@/design/adapter'
+import { buildDesignCss } from '@/design/css'
+import { isOwnCheckout } from '@/project-root'
+
+/**
+ * The stylesheet injected into every frame, so a frame drawn with
+ * `var(--color-*)` shows the project's own values. Parsing a `DESIGN.md` into
+ * custom properties is left out, since no such mapping exists, and a frame can
+ * always link a stylesheet of its own.
+ */
+export type FrameTokens =
+  | { readonly source: 'toolkit'; readonly css: string }
+  | {
+      readonly source: 'installed'
+      readonly css: string
+      /** Relative to the root, in the order the stylesheet concatenates them. */
+      readonly files: readonly string[]
+    }
+  | { readonly source: 'none'; readonly css: ''; readonly notice: string }
+
+export interface TokenOptions {
+  /** Overrides the checkout test, which reads this package's own name. */
+  readonly isOwnCheckout?: boolean
+}
+
+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.`
+
+/** The installed files in cascade order: the base first, then each override. */
+function installedFiles(root: string): string[] {
+  const files: string[] = []
+  const base = join(DESIGN_INSTALL_DIR, BASE_FILE)
+  if (existsSync(join(root, base))) files.push(base)
+
+  const projectDir = join(DESIGN_INSTALL_DIR, DESIGN_PROJECT_SUBDIR)
+  if (existsSync(join(root, projectDir))) {
+    const overrides = readdirSync(join(root, projectDir))
+      .filter((name) => name.endsWith('.css'))
+      .sort((a, b) => a.localeCompare(b))
+      .map((name) => join(projectDir, name))
+    files.push(...overrides)
+  }
+  return files
+}
+
+/**
+ * The toolkit's own module where the root is this checkout, else the installed
+ * base plus its project overrides, else nothing with a notice naming where
+ * tokens would come from.
+ */
+export function resolveFrameTokens(
+  root: string,
+  options: TokenOptions = {},
+): FrameTokens {
+  if (options.isOwnCheckout ?? isOwnCheckout(root)) {
+    return { source: 'toolkit', css: buildDesignCss() }
+  }
+
+  const files = installedFiles(root)
+  if (files.length > 0) {
+    const css = files
+      .map((file) => `/* ${file} */\n${readFileSync(join(root, file), 'utf8')}`)
+      .join('\n')
+    return { source: 'installed', css, files }
+  }
+
+  return { source: 'none', css: '', notice: NONE_NOTICE }
+}