@erclx/canon 5.53.0 → 5.54.0

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 } }
-  })
-}

package/src/canvas/client/app.tsx

@@ -1,188 +0,0 @@
-/** @jsxImportSource preact */
-import { effect } from '@preact/signals'
-import type { JSX } from 'preact'
-import { useLayoutEffect, useRef } from 'preact/hooks'
-import { Inspector } from '@/canvas/client/inspector'
-import { PagesPanel } from '@/canvas/client/pages-panel'
-import { PanelHandle } from '@/canvas/client/panel-handle'
-import {
-  clampPanelWidth,
-  currentPage,
-  DEFAULT_PANEL_WIDTHS,
-  focusFrame,
-  type PanelWidths,
-  panelsHidden,
-  panelWidths,
-  tokens,
-} from '@/canvas/client/state'
-import { Surface } from '@/canvas/client/surface'
-
-const SOURCE_LABEL = {
-  toolkit: 'This toolkit',
-  installed: 'Installed design',
-  none: 'None',
-} as const
-
-function TokenDetails(): JSX.Element | null {
-  const value = tokens.value
-  if (!value) return null
-  return (
-    <section aria-labelledby="tokens-heading">
-      <h2 id="tokens-heading" class="section-label">
-        Tokens
-      </h2>
-      <p class="detail">{SOURCE_LABEL[value.source]}</p>
-      {value.files && value.files.length > 0 ? (
-        <ul class="files">
-          {value.files.map((file) => (
-            <li key={file} title={file}>
-              <code>{file}</code>
-            </li>
-          ))}
-        </ul>
-      ) : null}
-      {value.notice ? <p class="notice">{value.notice}</p> : null}
-    </section>
-  )
-}
-
-function PageDetails(): JSX.Element | null {
-  const page = currentPage.value
-  if (!page) return null
-  const unplaced = page.frames.filter((frame) => !frame.placed).length
-  return (
-    <section aria-labelledby="page-heading">
-      <h2 id="page-heading" class="section-label">
-        Page
-      </h2>
-      <p class="detail" title={page.name}>
-        {page.name}
-      </p>
-      <p class="detail-meta">
-        {page.frames.length} {page.frames.length === 1 ? 'frame' : 'frames'}
-      </p>
-      {unplaced > 0 ? (
-        <p class="notice">
-          {unplaced} {unplaced === 1 ? 'frame has' : 'frames have'} no box in
-          layout.json and sit in a default row.
-        </p>
-      ) : null}
-      {page.layoutIssue === 'malformed' ? (
-        <p class="notice" role="alert">
-          layout.json does not parse, so every frame sits in a default row. Fix
-          the file to restore their places.
-        </p>
-      ) : null}
-    </section>
-  )
-}
-
-const PANELS_KEY = 'canon-canvas-panels'
-
-interface StoredPanels extends PanelWidths {
-  readonly hidden: boolean
-}
-
-function storedWidth(value: unknown, fallback: number): number {
-  return typeof value === 'number' && Number.isFinite(value) ? value : fallback
-}
-
-/** What the last visit left, with anything unreadable read as the default. */
-function readStoredPanels(): StoredPanels {
-  const fallback = { hidden: false, ...DEFAULT_PANEL_WIDTHS }
-  try {
-    const parsed: unknown = JSON.parse(localStorage.getItem(PANELS_KEY) ?? '{}')
-    if (typeof parsed !== 'object' || parsed === null) return fallback
-    const record = parsed as Record<string, unknown>
-    return {
-      hidden: record.hidden === true,
-      left: storedWidth(record.left, fallback.left),
-      right: storedWidth(record.right, fallback.right),
-    }
-  } catch {
-    return fallback
-  }
-}
-
-function storePanels(panels: StoredPanels): void {
-  try {
-    localStorage.setItem(PANELS_KEY, JSON.stringify(panels))
-  } catch {
-    /* A blocked store costs the remembered layout, nothing else. */
-  }
-}
-
-/**
- * Holds both widths inside this window, the details panel giving way first,
- * since long layer names are what the pages panel widens for.
- */
-function fitWidths(widths: PanelWidths): PanelWidths {
-  const right = clampPanelWidth(
-    'right',
-    widths.right,
-    window.innerWidth,
-    widths,
-  )
-  const left = clampPanelWidth('left', widths.left, window.innerWidth, {
-    ...widths,
-    right,
-  })
-  return { left, right }
-}
-
-/**
- * Restores the panels the last visit left and stores each change, the way the
- * theme pick is kept. The read lands before the first paint, so a hidden
- * layout never flashes open. The widths are clamped on that read and on every
- * window resize, since a width kept from a wider window could squeeze the
- * surface out.
- */
-function usePanelPreference(): void {
-  useLayoutEffect(() => {
-    const stored = readStoredPanels()
-    panelsHidden.value = stored.hidden
-    panelWidths.value = fitWidths(stored)
-    const handleResize = () => {
-      const fitted = fitWidths(panelWidths.value)
-      const { left, right } = panelWidths.value
-      if (fitted.left !== left || fitted.right !== right) {
-        panelWidths.value = fitted
-      }
-    }
-    window.addEventListener('resize', handleResize)
-    const stopStoring = effect(() =>
-      storePanels({ hidden: panelsHidden.value, ...panelWidths.value }),
-    )
-    return () => {
-      window.removeEventListener('resize', handleResize)
-      stopStoring()
-    }
-  }, [])
-}
-
-export function App(): JSX.Element {
-  const viewportRef = useRef<HTMLDivElement>(null)
-  usePanelPreference()
-  const { left, right } = panelWidths.value
-  return (
-    <div
-      class={panelsHidden.value ? 'shell panels-hidden' : 'shell'}
-      style={{ '--panel-left': `${left}px`, '--panel-right': `${right}px` }}
-    >
-      <PagesPanel
-        onFocusFrame={(frame) => {
-          const rect = viewportRef.current?.getBoundingClientRect()
-          focusFrame(frame, rect?.width ?? 0, rect?.height ?? 0)
-        }}
-      />
-      <PanelHandle side="left" controls="pages-panel" />
-      <Surface viewportRef={viewportRef} />
-      <aside id="details-panel" class="panel panel-right" aria-label="Details">
-        <Inspector />
-        <PageDetails />
-        <TokenDetails />
-      </aside>
-      <PanelHandle side="right" controls="details-panel" />
-    </div>
-  )
-}