@erclx/canon 5.14.1 → 5.15.0

package/src/canvas/client/surface.tsx

@@ -0,0 +1,213 @@
+/** @jsxImportSource preact */
+import type { JSX, RefObject } from 'preact'
+import { useEffect, useRef } from 'preact/hooks'
+import type { Frame } from '@/canvas/content'
+import {
+  currentPage,
+  fitView,
+  frameKey,
+  frameTheme,
+  frameVersions,
+  panBy,
+  type Theme,
+  toggleFrameTheme,
+  view,
+  zoomAt,
+} from '@/canvas/client/state'
+
+/** One wheel notch or one button press. */
+const ZOOM_STEP = 1.2
+
+export interface SurfaceProps {
+  readonly viewportRef: RefObject<HTMLDivElement | null>
+}
+
+export function frameSrc(page: string, frame: Frame, version: number): string {
+  const path = `/frames/${encodeURIComponent(page)}/${encodeURIComponent(frame.file)}`
+  return version === 0 ? path : `${path}?v=${version}`
+}
+
+/**
+ * Sets the frame document's theme the way the token stylesheet reads it. The
+ * frame shares the shell's origin, so its document is reachable once loaded.
+ */
+function applyFrameTheme(iframe: HTMLIFrameElement | null, value: Theme): void {
+  const root = iframe?.contentDocument?.documentElement
+  if (!root) return
+  root.dataset.theme = value
+  root.style.colorScheme = value
+}
+
+function FrameView({
+  page,
+  frame,
+}: {
+  readonly page: string
+  readonly frame: Frame
+}): JSX.Element {
+  const key = frameKey(page, frame)
+  const version = frameVersions.value.get(key) ?? 0
+  const value = frameTheme(key)
+  const iframe = useRef<HTMLIFrameElement>(null)
+
+  useEffect(() => {
+    applyFrameTheme(iframe.current, value)
+  }, [value])
+
+  const next = value === 'dark' ? 'light' : 'dark'
+  return (
+    <figure
+      class="frame"
+      data-frame={frame.name}
+      style={{
+        left: `${frame.x}px`,
+        top: `${frame.y}px`,
+        width: `${frame.width}px`,
+      }}
+    >
+      <figcaption class="frame-label">
+        <span class="frame-name" title={frame.name}>
+          {frame.name}
+        </span>
+        <span class="frame-size">
+          {frame.width} × {frame.height}
+        </span>
+        <button
+          type="button"
+          class="frame-theme"
+          aria-label={`Show ${frame.name} in ${next} theme`}
+          title={`Show in ${next} theme`}
+          onClick={() => toggleFrameTheme(key)}
+        >
+          {value === 'dark' ? 'Dark' : 'Light'}
+        </button>
+      </figcaption>
+      <iframe
+        ref={iframe}
+        title={frame.name}
+        src={frameSrc(page, frame, version)}
+        width={frame.width}
+        height={frame.height}
+        style={{ height: `${frame.height}px` }}
+        onLoad={() => applyFrameTheme(iframe.current, frameTheme(key))}
+      />
+    </figure>
+  )
+}
+
+function viewportSize(viewport: RefObject<HTMLDivElement | null>): {
+  width: number
+  height: number
+} {
+  const rect = viewport.current?.getBoundingClientRect()
+  return { width: rect?.width ?? 0, height: rect?.height ?? 0 }
+}
+
+function Toolbar({ viewportRef }: SurfaceProps): JSX.Element {
+  const zoomCentered = (factor: number) => {
+    const { width, height } = viewportSize(viewportRef)
+    zoomAt(factor, width / 2, height / 2)
+  }
+  return (
+    <div class="toolbar" role="toolbar" aria-label="Zoom">
+      <button
+        type="button"
+        class="icon-button"
+        aria-label="Zoom out"
+        onClick={() => zoomCentered(1 / ZOOM_STEP)}
+      >
+        −
+      </button>
+      <output class="zoom" aria-live="polite">
+        {Math.round(view.value.zoom * 100)}%
+      </output>
+      <button
+        type="button"
+        class="icon-button"
+        aria-label="Zoom in"
+        onClick={() => zoomCentered(ZOOM_STEP)}
+      >
+        +
+      </button>
+      <button
+        type="button"
+        class="text-button"
+        onClick={() => {
+          const { width, height } = viewportSize(viewportRef)
+          fitView(width, height)
+        }}
+      >
+        Fit
+      </button>
+    </div>
+  )
+}
+
+export function Surface({ viewportRef }: SurfaceProps): JSX.Element {
+  const page = currentPage.value
+  const drag = useRef<{ x: number; y: number } | undefined>(undefined)
+
+  /* Fits a page once when it opens, never on a reload of the same page. */
+  useEffect(() => {
+    const { width, height } = viewportSize(viewportRef)
+    fitView(width, height)
+  }, [page?.name])
+
+  const handleWheel = (event: WheelEvent) => {
+    event.preventDefault()
+    if (event.ctrlKey || event.metaKey) {
+      const rect = viewportRef.current?.getBoundingClientRect()
+      const factor = event.deltaY < 0 ? ZOOM_STEP : 1 / ZOOM_STEP
+      zoomAt(
+        factor,
+        event.clientX - (rect?.left ?? 0),
+        event.clientY - (rect?.top ?? 0),
+      )
+      return
+    }
+    panBy(-event.deltaX, -event.deltaY)
+  }
+
+  const handlePointerDown = (event: PointerEvent) => {
+    const target = event.target as HTMLElement | null
+    if (target?.closest('.frame, .toolbar')) return
+    drag.current = { x: event.clientX, y: event.clientY }
+    viewportRef.current?.setPointerCapture?.(event.pointerId)
+  }
+
+  const handlePointerMove = (event: PointerEvent) => {
+    const start = drag.current
+    if (!start) return
+    panBy(event.clientX - start.x, event.clientY - start.y)
+    drag.current = { x: event.clientX, y: event.clientY }
+  }
+
+  const handlePointerUp = () => {
+    drag.current = undefined
+  }
+
+  const { x, y, zoom } = view.value
+  return (
+    <main class="surface" aria-label="Canvas">
+      <div
+        ref={viewportRef}
+        class="viewport"
+        onWheel={handleWheel}
+        onPointerDown={handlePointerDown}
+        onPointerMove={handlePointerMove}
+        onPointerUp={handlePointerUp}
+        onPointerCancel={handlePointerUp}
+      >
+        <div
+          class="plane"
+          style={{ transform: `translate(${x}px, ${y}px) scale(${zoom})` }}
+        >
+          {page?.frames.map((frame) => (
+            <FrameView key={frame.name} page={page.name} frame={frame} />
+          ))}
+        </div>
+      </div>
+      <Toolbar viewportRef={viewportRef} />
+    </main>
+  )
+}

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>