@erclx/canon 5.53.0 → 5.54.0

package/src/canvas/server.ts

@@ -1,766 +0,0 @@
-import { type FSWatcher, mkdirSync, watch } from 'node:fs'
-import {
-  countElements,
-  type ElementAddress,
-  HASH_ATTRIBUTE,
-  IMPLIED_ATTRIBUTE,
-  TOKENS_ATTRIBUTE,
-} from '@/canvas/address'
-import {
-  type BoxObserver,
-  type ContentRefused,
-  canvasDir,
-  contentHash,
-  listPages,
-  LOCK_SUFFIX,
-  moveFrame,
-  readSelection,
-  resizeFrame,
-  restoreBox,
-  TEMP_SUFFIX,
-  writeSelection,
-} from '@/canvas/content'
-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,
-  tokenGroups,
-} from '@/canvas/tokens'
-import { buildDesignCss } from '@/design/css'
-import { brandFavicon } from '@/design/brand-favicon'
-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. 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>`
-}
-
-/** The wrappers a browser builds whether or not the file states them. */
-const WRAPPERS = new Set(['html', 'head', 'body'])
-
-/** Which of the document wrappers the file states, counted as the address counts. */
-function statedWrappers(html: string): Set<string> {
-  const stated = new Set<string>()
-  countElements(new HTMLRewriter(), (element) => {
-    const tag = element.tagName.toLowerCase()
-    if (WRAPPERS.has(tag)) stated.add(tag)
-    return undefined
-  }).transform(html)
-  return stated
-}
-
-/** Prepends markup inside the first element a selector matches. */
-function prependFirst(html: string, selector: string, markup: string): string {
-  let isDone = false
-  return new HTMLRewriter()
-    .on(selector, {
-      element(element) {
-        if (isDone) return
-        isDone = true
-        element.prepend(markup, { html: true })
-      },
-    })
-    .transform(html)
-}
-
-/**
- * What a browser parses into the head it builds ahead of a fragment's first
- * content. A comment or whitespace among them stays in that head too.
- */
-const HEAD_CONTENT = new Set([
-  'base',
-  'link',
-  'meta',
-  'noscript',
-  'script',
-  'style',
-  'template',
-  'title',
-])
-
-/**
- * Opens a marked body where the browser would build its own: ahead of the
- * first element or text outside the head content a file leads with, or at the
- * end when the file holds nothing else.
- */
-function openBodyBeforeContent(html: string, marker: string): string {
-  let isOpen = false
-  let headDepth = 0
-  const open = (target: HTMLRewriterTypes.Element | HTMLRewriterTypes.Text) => {
-    isOpen = true
-    target.before(marker, { html: true })
-  }
-  return new HTMLRewriter()
-    .on('*', {
-      element(element) {
-        if (isOpen || headDepth > 0) return
-        const tag = element.tagName.toLowerCase()
-        if (tag === 'html') return
-        if (!HEAD_CONTENT.has(tag)) {
-          open(element)
-          return
-        }
-        if (!element.canHaveContent || element.selfClosing) return
-        headDepth += 1
-        element.onEndTag(() => {
-          headDepth -= 1
-        })
-      },
-    })
-    .onDocument({
-      text(chunk) {
-        if (!isOpen && headDepth === 0 && chunk.text.trim() !== '') open(chunk)
-      },
-      end(end) {
-        if (!isOpen) end.append(marker, { html: true })
-      },
-    })
-    .transform(html)
-}
-
-/**
- * Puts the tokens first in the head, so a stylesheet the frame links itself
- * still wins the cascade. A hash stamps the element even when no tokens
- * resolve, since the shell sends it back with an element pick.
- *
- * A wrapper the file leaves out is written in marked, since the browser would
- * build it anyway and the shell's count would run past the file's. An `html`
- * goes right after the doctype, which keeps the frame out of quirks mode. A
- * marked `head` is left open, so the head content a fragment leads with parses
- * into it the way it would into the head a browser builds, and a file stating
- * neither `head` nor `body` gets a marked body opened where that content ends.
- * A file stating a `head` but no `body` is left to the browser.
- */
-export function injectTokens(html: string, css: string, hash?: string): string {
-  if (css === '' && hash === undefined) return html
-  const style = styleElement(css, hash)
-  const stated = statedWrappers(html)
-  const isHeadStated = stated.has('head')
-  const withBody =
-    isHeadStated || stated.has('body')
-      ? html
-      : openBodyBeforeContent(html, `<body ${IMPLIED_ATTRIBUTE}>`)
-  if (isHeadStated) {
-    const withHead = prependFirst(withBody, 'head', style)
-    return stated.has('html') ? withHead : markedHtml(withHead, '')
-  }
-  const head = `<head ${IMPLIED_ATTRIBUTE}>${style}`
-  return stated.has('html')
-    ? prependFirst(withBody, 'html', head)
-    : markedHtml(withBody, head)
-}
-
-/** Writes a marked `html` and what follows it right after the doctype. */
-function markedHtml(html: string, lead: string): string {
-  const doctype = html.match(/^\s*<!doctype[^>]*>/i)?.[0] ?? ''
-  return `${doctype}<html ${IMPLIED_ATTRIBUTE}>${lead}${html.slice(doctype.length)}`
-}
-
-/**
- * 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, status = 200): Response {
-  return new Response(JSON.stringify(body), {
-    status,
-    headers: {
-      'content-type': 'application/json; charset=utf-8',
-      'cache-control': 'no-store',
-    },
-  })
-}
-
-const REFUSAL_STATUS: Record<EditRefused['reason'], number> = {
-  'invalid-edit': 400,
-  'not-text-only': 409,
-  '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 | EditRefused): 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}`
-  )
-}
-
-/**
- * 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
-}
-
-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,
-  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)
-  /*
-   * 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' },
-  })
-}
-
-/**
- * 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
-    /* 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,
-      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)
-  /*
-   * 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>
-  try {
-    bound = bindFirstFree(first, (port) =>
-      Bun.serve({
-        hostname: SERVE_HOST,
-        port,
-        development: false,
-        /*
-         * Production mode turns port reuse on, so a second canvas would bind
-         * beside one already listening rather than walk past it.
-         */
-        reusePort: 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, ...source } = resolved
-            const selected = readSelection(root)
-            return json({
-              pages: listPages(root),
-              tokens: { ...source, groups: tokenGroups(css) },
-              selection: selected && {
-                page: selected.page,
-                frame: selected.frame,
-                ...(selected.element && {
-                  element: {
-                    index: selected.element.index,
-                    tag: selected.element.tag,
-                    stale: selected.element.stale,
-                  },
-                }),
-              },
-              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) => {
-                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 { 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)
-              }),
-            ),
-          },
-          '/api/frames/resize': {
-            POST: guarded(
-              mutation((body) => {
-                if (
-                  !isRecord(body) ||
-                  typeof body.page !== 'string' ||
-                  typeof body.frame !== 'string' ||
-                  typeof body.x !== 'number' ||
-                  typeof body.y !== 'number' ||
-                  typeof body.width !== 'number' ||
-                  typeof body.height !== 'number'
-                ) {
-                  return badBody('send page, frame, x, y, width, and 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)
-              }),
-            ),
-          },
-          '/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 { 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,
-                  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)
-              }),
-            ),
-          },
-          '/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, {
-                headers: {
-                  'content-type': 'text/css; charset=utf-8',
-                  'cache-control': 'no-store',
-                },
-              }),
-          ),
-          '/api/icon.svg': guarded(
-            () =>
-              new Response(brandFavicon(), {
-                headers: { 'content-type': 'image/svg+xml' },
-              }),
-          ),
-          '/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)
-    },
-  }
-}