@erclx/canon 5.52.0 → 5.54.0

package/src/canvas/address.ts

@@ -1,227 +0,0 @@
-/**
- * The element address: a frame plus the element's index in document order.
- * The shell counts it over the frame's parsed DOM and the server counts it over
- * the file through `HTMLRewriter`, so the two have to count the same elements.
- * This module imports nothing, which keeps it bundling into the shell, and the
- * server half reaches `HTMLRewriter` as a Bun global only when called.
- */
-
-/** Marks the token stylesheet the server injects, which the file never holds. */
-export const TOKENS_ATTRIBUTE = 'data-canvas-tokens'
-
-/**
- * Marks a document wrapper the server writes because the file leaves it to the
- * browser to imply, so the shell counts only what the file states.
- */
-export const IMPLIED_ATTRIBUTE = 'data-canvas-implied'
-
-/** On that same element, the hash of the file the frame was served from. */
-export const HASH_ATTRIBUTE = 'data-canvas-hash'
-
-const EXCERPT_LENGTH = 80
-
-/** Elements whose content is raw text, which a browser never parses as markup. */
-const RAW_TEXT = new Set(['script', 'style', 'template', 'textarea', 'title'])
-
-export interface ElementAddress {
-  readonly index: number
-  readonly tag: string
-  /**
-   * Every element the shell counted. A browser implies elements the file never
-   * states, such as a `tbody`, and each one shifts the count, so a total that
-   * differs from the server's is what exposes it. The server marks an implied
-   * document wrapper itself, so only the marked ones leave the count.
-   */
-  readonly count: number
-  /**
-   * The served file's hash, so the server can refuse a pick made against a
-   * version of the frame the file has since moved past.
-   */
-  readonly hash?: string
-}
-
-export interface SourceElement {
-  readonly tag: string
-  readonly classes: readonly string[]
-  readonly text: string
-}
-
-export type AddressCheck =
-  | { readonly ok: true; readonly element: SourceElement }
-  | {
-      readonly ok: false
-      readonly reason: 'address-mismatch'
-      readonly detail: string
-    }
-
-export function excerpt(text: string): string {
-  return text.replace(/\s+/g, ' ').trim().slice(0, EXCERPT_LENGTH)
-}
-
-export function documentElements(doc: Document): Element[] {
-  return [...doc.querySelectorAll('*')].filter(
-    (element) =>
-      !element.hasAttribute(TOKENS_ATTRIBUTE) &&
-      !element.hasAttribute(IMPLIED_ATTRIBUTE),
-  )
-}
-
-export function addressOf(
-  doc: Document,
-  element: Element,
-): ElementAddress | undefined {
-  const all = documentElements(doc)
-  const index = all.indexOf(element)
-  if (index === -1) return undefined
-  const address = {
-    index,
-    tag: element.tagName.toLowerCase(),
-    count: all.length,
-  }
-  const hash = doc
-    .querySelector(`[${TOKENS_ATTRIBUTE}]`)
-    ?.getAttribute(HASH_ATTRIBUTE)
-  return hash ? { ...address, hash } : address
-}
-
-/** The element an address names, or nothing once the tag there differs. */
-export function elementAt(
-  doc: Document,
-  address: Pick<ElementAddress, 'index' | 'tag'>,
-): Element | undefined {
-  const element = documentElements(doc)[address.index]
-  return element?.tagName.toLowerCase() === address.tag ? element : undefined
-}
-
-interface Collected {
-  readonly tag: string
-  readonly classes: readonly string[]
-  text: string
-}
-
-/**
- * Called on each element the address counts, with its index. What it returns
- * runs at the element's end tag, since a second `onEndTag` on one element
- * replaces the first rather than adding to it.
- */
-export type ElementVisitor = (
-  element: HTMLRewriterTypes.Element,
-  index: number,
-) => (() => void) | undefined
-
-/**
- * Registers the one counting rule both the reader and the edit writer follow,
- * so an index means the same element to each.
- */
-export function countElements(
-  rewriter: HTMLRewriter,
-  visit: ElementVisitor,
-): HTMLRewriter {
-  let count = 0
-  /* A template's content is a fragment `querySelectorAll` never reaches. */
-  let templateDepth = 0
-
-  return rewriter.on('*', {
-    element(element) {
-      const tag = element.tagName.toLowerCase()
-      if (templateDepth > 0) {
-        if (tag === 'template') {
-          templateDepth += 1
-          element.onEndTag(() => {
-            templateDepth -= 1
-          })
-        }
-        return
-      }
-      const end = visit(element, count)
-      count += 1
-      if (!element.canHaveContent || element.selfClosing) return
-      const isTemplate = tag === 'template'
-      if (isTemplate) templateDepth += 1
-      element.onEndTag(() => {
-        if (isTemplate) templateDepth -= 1
-        end?.()
-      })
-    },
-  })
-}
-
-/** Whether an element's content is raw text rather than parsed markup. */
-export function isRawText(tag: string): boolean {
-  return RAW_TEXT.has(tag)
-}
-
-/**
- * Every element the file states, in document order. Text is gathered into
- * each open element, which an element closed only by implication keeps open to
- * the end, so its excerpt can run past where a browser would end it.
- */
-export function sourceElements(html: string): SourceElement[] {
-  const elements: Collected[] = []
-  const open: number[] = []
-  let rawDepth = 0
-
-  const appendText = (text: string) => {
-    for (const index of open) {
-      const element = elements[index]
-      if (element && element.text.length < EXCERPT_LENGTH * 4) {
-        element.text += text
-      }
-    }
-  }
-
-  countElements(new HTMLRewriter(), (element, index) => {
-    const tag = element.tagName.toLowerCase()
-    /* A tag boundary separates words the way a rendered block would. */
-    appendText(' ')
-    elements.push({
-      tag,
-      classes: (element.getAttribute('class') ?? '')
-        .split(/\s+/)
-        .filter(Boolean),
-      text: '',
-    })
-    if (!element.canHaveContent || element.selfClosing) return undefined
-    const isRaw = isRawText(tag)
-    open.push(index)
-    if (isRaw) rawDepth += 1
-    return () => {
-      const at = open.lastIndexOf(index)
-      if (at !== -1) open.splice(at, 1)
-      if (isRaw) rawDepth -= 1
-      appendText(' ')
-    }
-  })
-    .onDocument({
-      text(chunk) {
-        if (rawDepth === 0) appendText(chunk.text)
-      },
-    })
-    .transform(html)
-
-  return elements.map(({ tag, classes, text }) => ({
-    tag,
-    classes,
-    text: excerpt(text),
-  }))
-}
-
-/**
- * Finds the element the shell addressed in the file, and refuses when the two
- * counts disagree rather than naming whatever sits at that index on disk.
- */
-export function resolveAddress(
-  html: string,
-  address: ElementAddress,
-): AddressCheck {
-  const elements = sourceElements(html)
-  const element = elements[address.index]
-  if (elements.length !== address.count || element?.tag !== address.tag) {
-    return {
-      ok: false,
-      reason: 'address-mismatch',
-      detail: `the browser counted ${address.count} elements and the file states ${elements.length}, so element ${address.index} cannot be matched`,
-    }
-  }
-  return { ok: true, element }
-}

package/src/canvas/arrange.ts

@@ -1,66 +0,0 @@
-import { type Box, FRAME_GAP, type Frame } from '@/canvas/content'
-
-export interface Placement {
-  readonly name: string
-  readonly from: Box
-  readonly to: Box
-}
-
-function boxOf(frame: Frame): Box {
-  return {
-    x: frame.x,
-    y: frame.y,
-    width: frame.width,
-    height: frame.height,
-  }
-}
-
-/**
- * Boxes whose vertical spans overlap share a row, so a row the operator dragged
- * stays a row. Reading by overlap rather than by an equal `y` lets a frame a
- * few pixels off its neighbor still join it.
- */
-function rowsOf(frames: readonly Frame[]): Frame[][] {
-  const sorted = [...frames].sort((a, b) => a.y - b.y || a.x - b.x)
-  const rows: Frame[][] = []
-  let bottom = Number.NEGATIVE_INFINITY
-  for (const frame of sorted) {
-    const row = rows.at(-1)
-    if (row && frame.y < bottom) {
-      row.push(frame)
-      bottom = Math.max(bottom, frame.y + frame.height)
-    } else {
-      rows.push([frame])
-      bottom = frame.y + frame.height
-    }
-  }
-  return rows.map((row) =>
-    row.sort((a, b) => a.x - b.x || a.name.localeCompare(b.name)),
-  )
-}
-
-/**
- * Re-lays a page's frames: each row left to right on `FRAME_GAP` from the
- * page's leftmost edge, rows stacked on their tallest box plus the gap from
- * the page's top edge. Returns only the frames whose position changes.
- */
-export function planArrange(frames: readonly Frame[]): Placement[] {
-  if (frames.length === 0) return []
-  const left = Math.min(...frames.map((frame) => frame.x))
-  let top = Math.min(...frames.map((frame) => frame.y))
-
-  const moves: Placement[] = []
-  for (const row of rowsOf(frames)) {
-    let x = left
-    for (const frame of row) {
-      const from = boxOf(frame)
-      const to: Box = { ...from, x, y: top }
-      if (from.x !== to.x || from.y !== to.y) {
-        moves.push({ name: frame.name, from, to })
-      }
-      x += frame.width + FRAME_GAP
-    }
-    top += Math.max(...row.map((frame) => frame.height)) + FRAME_GAP
-  }
-  return moves
-}

package/src/canvas/capture.ts

@@ -1,391 +0,0 @@
-import { mkdirSync, rmSync, writeFileSync } from 'node:fs'
-import { dirname, join } from 'node:path'
-import type { CaptureResult } from '@/capture/render'
-import {
-  type ContentRefused,
-  canvasDir,
-  type Frame,
-  readPage,
-} from '@/canvas/content'
-import {
-  type CanvasOptions,
-  type CanvasOutcome,
-  FRAMES_PREFIX,
-  startCanvas,
-} from '@/canvas/server'
-import { recordDir } from '@/roots/record'
-
-/**
- * The element a frame is captured by. The document rather than its body, so a
- * frame that paints its background on the root is not cropped to the body's
- * box.
- */
-export const CAPTURE_SELECTOR = 'html'
-
-export interface CaptureTarget {
-  readonly page: string
-  readonly frame: string
-  /** The served address, which is what carries the injected tokens. */
-  readonly url: string
-  /** The viewport width, so a media query resolves at the frame's own width. */
-  readonly width: number
-  readonly pngPath: string
-}
-
-export type TargetsOutcome =
-  | { readonly ok: true; readonly targets: readonly CaptureTarget[] }
-  | ContentRefused
-
-function refuse(
-  reason: ContentRefused['reason'],
-  detail: string,
-): ContentRefused {
-  return { ok: false, reason, detail }
-}
-
-function frameUrl(base: string, page: string, frame: Frame): string {
-  return `${base}${FRAMES_PREFIX.slice(1)}${encodeURIComponent(page)}/${encodeURIComponent(frame.file)}`
-}
-
-/**
- * Turns `<page>` or `<page>/<frame>` into what to capture. Every target is a
- * served address, never the file on disk, so a capture can only show what the
- * canvas shows. The width comes from the layout and not from the window, so a
- * frame narrower than its own breakpoint renders its narrow layout.
- *
- * `out` is the PNG for a frame and a folder for a page, the way a URL source
- * reads `--out` in `canon capture`.
- */
-export function resolveCaptureTargets(
-  root: string,
-  spec: string,
-  base: string,
-  out?: string,
-): TargetsOutcome {
-  const [pageName, frameName, ...extra] = spec.split('/')
-  if (!pageName || extra.length > 0 || frameName === '') {
-    return refuse('invalid-name', `${spec} is not <page> or <page>/<frame>`)
-  }
-
-  const page = readPage(root, pageName)
-  if (!page) return refuse('no-page', `page ${pageName} does not exist`)
-
-  const frames =
-    frameName === undefined
-      ? page.frames
-      : page.frames.filter((frame) => frame.name === frameName)
-  if (frames.length === 0) {
-    return frameName === undefined
-      ? refuse('no-frame', `page ${pageName} has no frames`)
-      : refuse('no-frame', `frame ${frameName} does not exist on ${pageName}`)
-  }
-
-  const scratch = recordDir(root, 'tmp', 'canvas-capture', pageName)
-  return {
-    ok: true,
-    targets: frames.map((frame) => ({
-      page: pageName,
-      frame: frame.name,
-      url: frameUrl(base, pageName, frame),
-      width: frame.width,
-      pngPath:
-        frameName !== undefined && out !== undefined
-          ? out
-          : join(out ?? scratch, `${frame.name}.png`),
-    })),
-  }
-}
-
-export type CaptureOutcome =
-  | {
-      readonly ok: true
-      readonly captures: readonly {
-        readonly target: CaptureTarget
-        readonly result: CaptureResult
-      }[]
-    }
-  | ContentRefused
-  | {
-      readonly ok: false
-      readonly reason: 'no-server' | 'capture-failed'
-      readonly detail: string
-    }
-
-type CaptureEngine = (typeof import('@/capture/render'))['captureSources']
-
-/** What a test stands in for, which the command never passes. */
-export interface CaptureDeps {
-  readonly start?: (root: string, options: CanvasOptions) => CanvasOutcome
-  readonly capture?: CaptureEngine
-}
-
-/**
- * Serves the canvas for the length of the call and captures through it, so the
- * run needs no `canon canvas serve` and still never reads the raw file. The
- * port is whatever is free, which keeps it clear of a canvas already running.
- * An error the engine throws, such as a browser that will not launch, comes
- * back as `capture-failed` rather than escaping, so a caller reading the record
- * can tell it from a root that is wrong.
- */
-export async function captureCanvas(
-  root: string,
-  spec: string,
-  out?: string,
-  deps: CaptureDeps = {},
-): Promise<CaptureOutcome> {
-  /*
-   * Refused before the server starts, since starting it creates the canvas
-   * folder and a refused capture should leave the project as it found it.
-   */
-  const early = resolveCaptureTargets(root, spec, '')
-  if (!early.ok) return early
-
-  return serveFor(root, deps, async (base, capture) => {
-    const resolved = resolveCaptureTargets(root, spec, base, out)
-    if (!resolved.ok) return resolved
-
-    const captures: { target: CaptureTarget; result: CaptureResult }[] = []
-    for (const target of resolved.targets) {
-      const [result] = await capture(target.url, {
-        selector: CAPTURE_SELECTOR,
-        width: target.width,
-        outDir: target.pngPath,
-      })
-      if (result) captures.push({ target, result })
-    }
-    return { ok: true, captures }
-  })
-}
-
-export type ServeRefused = {
-  readonly ok: false
-  readonly reason: 'no-server' | 'capture-failed'
-  readonly detail: string
-}
-
-async function serveFor<T>(
-  root: string,
-  deps: CaptureDeps,
-  run: (base: string, capture: CaptureEngine) => Promise<T>,
-): Promise<T | ServeRefused> {
-  return serveCanvas(root, deps.start, async (base) => {
-    const capture =
-      deps.capture ?? (await import('@/capture/render')).captureSources
-    return run(base, capture)
-  })
-}
-
-/**
- * Runs a call against a canvas served on a free port for its length, so a verb
- * that renders frames reads the same address the board shows.
- */
-export async function serveCanvas<T>(
-  root: string,
-  startOverride: CaptureDeps['start'],
-  run: (base: string) => Promise<T>,
-): Promise<T | ServeRefused> {
-  const start = startOverride ?? startCanvas
-  const server = start(root, { port: 0, shell: new Response('') })
-  if (!server.ok) {
-    return {
-      ok: false,
-      reason: 'no-server',
-      detail: `${server.detail}, so run canon canvas serve and try again`,
-    }
-  }
-
-  try {
-    return await run(server.url)
-  } catch (error) {
-    return {
-      ok: false,
-      reason: 'capture-failed',
-      detail: error instanceof Error ? error.message : String(error),
-    }
-  } finally {
-    await server.stop()
-  }
-}
-
-/** The element a composite is captured by, holding every frame and no chrome. */
-export const COMPOSITE_SELECTOR = '#canvas-composite'
-
-export interface Placement {
-  readonly frame: string
-  readonly url: string
-  readonly left: number
-  readonly top: number
-  readonly width: number
-  readonly height: number
-}
-
-export interface Composite {
-  readonly placements: readonly Placement[]
-  readonly width: number
-  readonly height: number
-  readonly html: string
-}
-
-/**
- * One document showing every frame of a page at its layout position. Offsets
- * run from the top left of the union of the boxes, so a negative coordinate
- * never clips and a lone frame fills the container exactly. Each iframe takes
- * its box, so a document taller than its frame clips as it does on the board,
- * and frames paint in the order given, which is the board's.
- */
-export function buildComposite(
-  page: string,
-  frames: readonly Frame[],
-  base: string,
-): Composite {
-  const left = Math.min(...frames.map((frame) => frame.x))
-  const top = Math.min(...frames.map((frame) => frame.y))
-  const right = Math.max(...frames.map((frame) => frame.x + frame.width))
-  const bottom = Math.max(...frames.map((frame) => frame.y + frame.height))
-  const width = right - left
-  const height = bottom - top
-
-  const placements = frames.map((frame) => ({
-    frame: frame.name,
-    url: frameUrl(base, page, frame),
-    left: frame.x - left,
-    top: frame.y - top,
-    width: frame.width,
-    height: frame.height,
-  }))
-
-  const iframes = placements.map(
-    (p) =>
-      `<iframe title="${escapeAttribute(p.frame)}" src="${escapeAttribute(p.url)}" style="left:${p.left}px;top:${p.top}px;width:${p.width}px;height:${p.height}px"></iframe>`,
-  )
-  const html = [
-    '<!doctype html>',
-    '<html><head><meta charset="utf-8">',
-    `<style>html,body{margin:0;background:transparent}#canvas-composite{position:relative}#canvas-composite iframe{position:absolute;display:block;border:0;background:transparent}</style>`,
-    '</head><body>',
-    `<div id="canvas-composite" style="width:${width}px;height:${height}px">`,
-    ...iframes,
-    '</div></body></html>',
-    '',
-  ].join('\n')
-
-  return { placements, width, height, html }
-}
-
-function escapeAttribute(value: string): string {
-  return value.replaceAll('&', '&amp;').replaceAll('"', '&quot;')
-}
-
-/**
- * Where the generated document is served from, inside the canvas folder so it
- * shares the frames' origin. Chromium skips painting a cross-origin iframe
- * outside the viewport, and the engine's viewport is 720 pixels tall, so a
- * document on another origin captured every frame below that line blank. A dot
- * folder is no page name, so the board never lists it.
- */
-const COMPOSITE_FOLDER = '.composite'
-
-export interface CompositeTarget {
-  readonly page: string
-  readonly composite: Composite
-  readonly htmlPath: string
-  /** The served address of the document at `htmlPath`. */
-  readonly url: string
-  readonly pngPath: string
-}
-
-export type CompositeTargetOutcome =
-  | { readonly ok: true; readonly target: CompositeTarget }
-  | ContentRefused
-
-/**
- * Turns `<page>` into one composite. `out` is the PNG, and without it the PNG
- * lands at `<page>.png` beside the per-frame folder of the same name, so the
- * two captures of one page never collide.
- */
-export function resolveCompositeTarget(
-  root: string,
-  spec: string,
-  base: string,
-  out?: string,
-): CompositeTargetOutcome {
-  if (spec.includes('/')) {
-    return refuse(
-      'invalid-name',
-      `--composite takes a page, not ${spec}, so capture <page> or drop the flag`,
-    )
-  }
-
-  const page = readPage(root, spec)
-  if (!page) return refuse('no-page', `page ${spec} does not exist`)
-  if (page.frames.length === 0) {
-    return refuse('no-frame', `page ${spec} has no frames`)
-  }
-
-  const file = `${spec}.html`
-  return {
-    ok: true,
-    target: {
-      page: spec,
-      composite: buildComposite(spec, page.frames, base),
-      htmlPath: join(canvasDir(root), COMPOSITE_FOLDER, file),
-      url: `${base}${FRAMES_PREFIX.slice(1)}${COMPOSITE_FOLDER}/${encodeURIComponent(file)}`,
-      pngPath:
-        out ?? join(recordDir(root, 'tmp', 'canvas-capture'), `${spec}.png`),
-    },
-  }
-}
-
-export type CompositeOutcome =
-  | {
-      readonly ok: true
-      readonly composite: {
-        readonly target: CompositeTarget
-        readonly result: CaptureResult
-      }
-    }
-  | ContentRefused
-  | ServeRefused
-
-/**
- * Captures a page as one PNG through the served canvas, the way `captureCanvas`
- * captures each frame. The viewport is the container's width, so no frame's
- * media query resolves against a window narrower than the frame itself. The
- * page load the engine waits on waits on every iframe.
- */
-export async function captureComposite(
-  root: string,
-  spec: string,
-  out?: string,
-  deps: CaptureDeps = {},
-): Promise<CompositeOutcome> {
-  const early = resolveCompositeTarget(root, spec, '')
-  if (!early.ok) return early
-
-  return serveFor(root, deps, async (base, capture) => {
-    const resolved = resolveCompositeTarget(root, spec, base, out)
-    if (!resolved.ok) return resolved
-
-    const { target } = resolved
-    mkdirSync(dirname(target.htmlPath), { recursive: true })
-    writeFileSync(target.htmlPath, target.composite.html)
-    let result: CaptureResult | undefined
-    try {
-      ;[result] = await capture(target.url, {
-        selector: COMPOSITE_SELECTOR,
-        width: target.composite.width,
-        outDir: target.pngPath,
-      })
-    } finally {
-      rmSync(target.htmlPath, { force: true })
-    }
-    if (!result) {
-      return {
-        ok: false,
-        reason: 'capture-failed',
-        detail: `the engine rendered nothing for ${spec}`,
-      }
-    }
-    return { ok: true, composite: { target, result } }
-  })
-}