@erclx/canon 5.15.0 → 5.17.0

package/src/canvas/address.ts

@@ -0,0 +1,184 @@
+/**
+ * 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'
+
+/** 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` or the document wrapper, and each one shifts the
+   * count, so a total that differs from the server's is what exposes it.
+   */
+  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),
+  )
+}
+
+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
+}
+
+/**
+ * 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
+  /* A template's content is a fragment `querySelectorAll` never reaches. */
+  let templateDepth = 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
+      }
+    }
+  }
+
+  new HTMLRewriter()
+    .on('*', {
+      element(element) {
+        const tag = element.tagName.toLowerCase()
+        if (templateDepth > 0) {
+          if (tag === 'template') {
+            templateDepth += 1
+            element.onEndTag(() => {
+              templateDepth -= 1
+            })
+          }
+          return
+        }
+        const index = elements.length
+        /* 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
+        const isRaw = RAW_TEXT.has(tag)
+        const isTemplate = tag === 'template'
+        open.push(index)
+        if (isRaw) rawDepth += 1
+        if (isTemplate) templateDepth += 1
+        element.onEndTag(() => {
+          const at = open.lastIndexOf(index)
+          if (at !== -1) open.splice(at, 1)
+          if (isRaw) rawDepth -= 1
+          if (isTemplate) templateDepth -= 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/capture.ts

@@ -0,0 +1,172 @@
+import { join } from 'node:path'
+import type { CaptureResult } from '@/capture/render'
+import { type ContentRefused, type Frame, readPage } from '@/canvas/content'
+import {
+  type CanvasOptions,
+  type CanvasOutcome,
+  FRAMES_PREFIX,
+  startCanvas,
+} from '@/canvas/server'
+import { recordDir } from '@/record-root'
+
+/**
+ * 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
+
+  const start = deps.start ?? 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 capture again`,
+    }
+  }
+
+  try {
+    const resolved = resolveCaptureTargets(root, spec, server.url, out)
+    if (!resolved.ok) return resolved
+
+    const capture =
+      deps.capture ?? (await import('@/capture/render')).captureSources
+    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 }
+  } catch (error) {
+    return {
+      ok: false,
+      reason: 'capture-failed',
+      detail: error instanceof Error ? error.message : String(error),
+    }
+  } finally {
+    await server.stop()
+  }
+}

package/src/canvas/client/app.tsx

@@ -1,6 +1,7 @@
 /** @jsxImportSource preact */
 import type { JSX } from 'preact'
 import { useRef } from 'preact/hooks'
+import { Inspector } from '@/canvas/client/inspector'
 import { PagesPanel } from '@/canvas/client/pages-panel'
 import { currentPage, focusFrame, tokens } from '@/canvas/client/state'
 import { Surface } from '@/canvas/client/surface'
@@ -77,6 +78,7 @@ export function App(): JSX.Element {
       />
       <Surface viewportRef={viewportRef} />
       <aside class="panel panel-right" aria-label="Details">
+        <Inspector />
         <PageDetails />
         <TokenDetails />
       </aside>

package/src/canvas/client/inspector.tsx

@@ -0,0 +1,121 @@
+/** @jsxImportSource preact */
+import type { JSX } from 'preact'
+import { elementAt } from '@/canvas/address'
+import {
+  currentPage,
+  frameDocuments,
+  frameKey,
+  selectedElement,
+  selectedFrame,
+  writeError,
+} from '@/canvas/client/state'
+
+const FIELDS = ['x', 'y', 'width', 'height'] as const
+
+interface Row {
+  readonly name: string
+  readonly value: string
+}
+
+/**
+ * The computed values the browser settled on, which is what the operator sees
+ * rather than what any one stylesheet states.
+ */
+function styleRows(element: Element): Row[] {
+  const rect = element.getBoundingClientRect()
+  const view = element.ownerDocument.defaultView
+  const style = view?.getComputedStyle(element)
+  const rows: Row[] = [
+    { name: 'x', value: String(Math.round(rect.left)) },
+    { name: 'y', value: String(Math.round(rect.top)) },
+    { name: 'width', value: String(Math.round(rect.width)) },
+    { name: 'height', value: String(Math.round(rect.height)) },
+  ]
+  if (!style) return rows
+  return [
+    ...rows,
+    { name: 'color', value: style.color },
+    { name: 'background', value: style.backgroundColor },
+    { name: 'font', value: style.fontFamily },
+    { name: 'size', value: style.fontSize },
+    { name: 'weight', value: style.fontWeight },
+  ]
+}
+
+function elementName(element: Element): string {
+  const tag = element.tagName.toLowerCase()
+  return [tag, ...element.classList].join('.')
+}
+
+/** Read-only in this slice, since editing an element is the edit slice's work. */
+function ElementDetails(): JSX.Element | null {
+  const picked = selectedElement.value
+  const page = currentPage.value
+  if (!picked || !page) return null
+  const { frame, element } = picked
+  const doc = frameDocuments.value.get(frameKey(page.name, frame))
+  const node = doc && !element.stale ? elementAt(doc, element) : undefined
+
+  return (
+    <section aria-label="Element">
+      <h2 class="section-label">Element</h2>
+      {element.stale ? (
+        <p class="notice">
+          The frame changed since this element was picked, so its index may name
+          another element now. Pick it again.
+        </p>
+      ) : node ? (
+        <>
+          <p class="detail" title={elementName(node)}>
+            {elementName(node)}
+          </p>
+          <dl class="box styles">
+            {styleRows(node).map((row) => (
+              <div key={row.name} class="box-row">
+                <dt>{row.name}</dt>
+                <dd title={row.value}>{row.value}</dd>
+              </div>
+            ))}
+          </dl>
+        </>
+      ) : (
+        <p class="empty">Loading the frame to read this element</p>
+      )}
+    </section>
+  )
+}
+
+/** Read-only in this slice, since editing a box is the edit slice's work. */
+export function Inspector(): JSX.Element {
+  const frame = selectedFrame.value
+  return (
+    <>
+      <section aria-label="Frame">
+        <h2 class="section-label">Frame</h2>
+        {frame ? (
+          <>
+            <p class="detail" title={frame.name}>
+              {frame.name}
+            </p>
+            <dl class="box">
+              {FIELDS.map((field) => (
+                <div key={field} class="box-row">
+                  <dt>{field}</dt>
+                  <dd>{frame[field]}</dd>
+                </div>
+              ))}
+            </dl>
+          </>
+        ) : (
+          <p class="empty">Select a frame to see its box</p>
+        )}
+        {writeError.value ? (
+          <p class="notice" role="alert">
+            {writeError.value}
+          </p>
+        ) : null}
+      </section>
+      <ElementDetails />
+    </>
+  )
+}

package/src/canvas/client/layers.tsx

@@ -0,0 +1,118 @@
+/** @jsxImportSource preact */
+import type { JSX } from 'preact'
+import { addressOf, documentElements, excerpt } from '@/canvas/address'
+import {
+  type FrameRef,
+  frameDocuments,
+  hoveredElement,
+  selectElement,
+  selection,
+} from '@/canvas/client/state'
+
+/** Elements that never render, so a layer for one points at nothing. */
+const HIDDEN = new Set(['script', 'style', 'template', 'noscript'])
+
+const LABEL_TEXT = 24
+
+export interface LayersProps {
+  readonly frame: FrameRef
+  /** The frame's key, which its loaded document is registered under. */
+  readonly frameKey: string
+}
+
+/** `tag.first-class`, then a short excerpt of a leaf's own text. */
+function layerLabel(element: Element): { name: string; text: string } {
+  const tag = element.tagName.toLowerCase()
+  const first = element.classList[0]
+  const text =
+    element.children.length === 0
+      ? excerpt(element.textContent ?? '').slice(0, LABEL_TEXT)
+      : ''
+  return { name: first ? `${tag}.${first}` : tag, text }
+}
+
+function LayerNode({
+  doc,
+  element,
+  indexes,
+  props,
+}: {
+  readonly doc: Document
+  readonly element: Element
+  readonly indexes: ReadonlyMap<Element, number>
+  readonly props: LayersProps
+}): JSX.Element {
+  const index = indexes.get(element) ?? -1
+  const chosen = selection.value
+  const isCurrent =
+    chosen?.page === props.frame.page &&
+    chosen.frame === props.frame.frame &&
+    chosen.element?.index === index &&
+    !chosen.element.stale
+  const { name, text } = layerLabel(element)
+  const children = [...element.children].filter(
+    (child) => !HIDDEN.has(child.tagName.toLowerCase()),
+  )
+
+  return (
+    <li>
+      <button
+        type="button"
+        class="row layer"
+        title={text ? `${name} ${text}` : name}
+        aria-current={isCurrent ? 'true' : undefined}
+        onClick={() => {
+          const address = addressOf(doc, element)
+          if (address) void selectElement(props.frame, props.frameKey, address)
+        }}
+        onMouseEnter={() => {
+          hoveredElement.value = { key: props.frameKey, index }
+        }}
+        onMouseLeave={() => {
+          hoveredElement.value = undefined
+        }}
+      >
+        <span class="row-label">{name}</span>
+        {text ? <span class="row-meta layer-text">{text}</span> : null}
+      </button>
+      {children.length > 0 ? (
+        <ul class="layers">
+          {children.map((child, at) => (
+            <LayerNode
+              key={at}
+              doc={doc}
+              element={child}
+              indexes={indexes}
+              props={props}
+            />
+          ))}
+        </ul>
+      ) : null}
+    </li>
+  )
+}
+
+/**
+ * The element tree of one frame, read from its loaded document, so it shows
+ * what the browser built rather than what the file states. Each row selects by
+ * the same address a click on the surface records.
+ */
+export function Layers(props: LayersProps): JSX.Element {
+  const doc = frameDocuments.value.get(props.frameKey)
+  const label = `Layers of ${props.frame.frame}`
+  if (!doc?.body) {
+    return (
+      <p class="empty" aria-label={label}>
+        Loading layers
+      </p>
+    )
+  }
+  const indexes = new Map(
+    documentElements(doc).map((element, index) => [element, index]),
+  )
+  return (
+    <ul class="layers layers-root" aria-label={label}>
+      <LayerNode doc={doc} element={doc.body} indexes={indexes} props={props} />
+    </ul>
+  )
+}

package/src/canvas/client/pages-panel.tsx

@@ -1,13 +1,19 @@
 /** @jsxImportSource preact */
 import type { JSX } from 'preact'
+import { Layers } from '@/canvas/client/layers'
 import type { Frame } from '@/canvas/content'
 import {
   currentPage,
+  expandedFrames,
+  frameKey,
   isLoaded,
   loadError,
   pages,
+  selectedFrame,
   selectedPage,
+  selectFrame,
   theme,
+  toggleLayers,
   toggleTheme,
 } from '@/canvas/client/state'
 
@@ -76,19 +82,47 @@ function FrameList({ onFocusFrame }: PagesPanelProps): JSX.Element | null {
   }
   return (
     <ul class="list" aria-label="Frames">
-      {page.frames.map((frame) => (
-        <li key={frame.name}>
-          <button
-            type="button"
-            class="row"
-            title={frame.name}
-            onClick={() => onFocusFrame(frame)}
-          >
-            <span class="row-label">{frame.name}</span>
-            <span class="row-meta">{frame.width}</span>
-          </button>
-        </li>
-      ))}
+      {page.frames.map((frame) => {
+        const key = frameKey(page.name, frame)
+        const isOpen = expandedFrames.value.has(key)
+        return (
+          <li key={frame.name}>
+            <div class="frame-row">
+              <button
+                type="button"
+                class="disclosure"
+                aria-expanded={isOpen}
+                aria-label={`${isOpen ? 'Hide' : 'Show'} layers of ${frame.name}`}
+                title={`${isOpen ? 'Hide' : 'Show'} layers`}
+                onClick={() => toggleLayers(key)}
+              >
+                <span aria-hidden="true">{isOpen ? '▾' : '▸'}</span>
+              </button>
+              <button
+                type="button"
+                class="row"
+                title={frame.name}
+                aria-current={
+                  frame.name === selectedFrame.value?.name ? 'true' : undefined
+                }
+                onClick={() => {
+                  onFocusFrame(frame)
+                  void selectFrame({ page: page.name, frame: frame.name })
+                }}
+              >
+                <span class="row-label">{frame.name}</span>
+                <span class="row-meta">{frame.width}</span>
+              </button>
+            </div>
+            {isOpen ? (
+              <Layers
+                frame={{ page: page.name, frame: frame.name }}
+                frameKey={key}
+              />
+            ) : null}
+          </li>
+        )
+      })}
     </ul>
   )
 }