@erclx/canon 5.28.0 → 5.30.0

package/claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "canon",
   "description": "Runs your agent's work and keeps its code good, on one setup for every repo.",
-  "version": "5.28.0",
+  "version": "5.30.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

package/claude/skills/review-ui/references/post.md

@@ -25,11 +25,11 @@ Write it to `.canon/tmp/pr/review-ui/body-<number>-<short-sha>.md` at the main w
 
 P passed, F failed, E need eyes, N not driven. Drove <address> at <short-sha>, rendered by <renderer>.
 
-| Box                                | Verdict    | Evidence                                      |
-| ---------------------------------- | ---------- | --------------------------------------------- |
-| 1. <the box as written, shortened> | fail       | <the value read against what the box expects> |
-| 2. <box>                           | needs eyes | <what the frame showed, in words>             |
-| 3. <box>                           | pass       | Evidence `<stem>` <what it showed, in words>  |
+| Box                                          | Evidence                                      |
+| -------------------------------------------- | --------------------------------------------- |
+| **Fail.** 1. <the box as written, shortened> | <the value read against what the box expects> |
+| **Needs eyes.** 2. <box>                     | <what the frame showed, in words>             |
+| **Pass.** 3. <box>                           | Evidence `<stem>` <what it showed, in words>  |
 
 **Frames**
 
@@ -50,6 +50,8 @@ P passed, F failed, E need eyes, N not driven. Drove <address> at <short-sha>, r
 <!-- review-ui: head=<head> -->
 ```
 
+The table has two columns and each Box cell opens on its verdict in bold with a period: `**Pass.**`, `**Fail.**`, `**Needs eyes.**`, or `**Not driven.**`. A column holding only those short words loses its width beside two long ones and GitHub breaks its header mid-word, so the verdict rides in the Box cell instead.
+
 An Evidence cell resting on a frame holds words only, so the table's text columns keep the body's width. A frame Step 5 pushed goes in the Frames block below the table, one `Box <n>, <verdict>` label then the `![](<link>)` embed for each framed box, with the link exactly as `canon pr frames` returned it. It names the frame's path on the frames branch, which stays put while other pull requests' frames are dropped and carries this pass's stamp, so a later pass never changes the image.
 
 The row still says what the frame showed, so it reads without the image. A state the worker's evidence already shows names the evidence stem in backticks and embeds nothing, since the evidence comment carries that image. A push that refused leaves the words alone and names the reason. Omit the Frames block when no box pushed a frame. Never cite the local frame path, since a path under `.canon/` is a board identifier the label scan rejects.

package/docs/agents/canvas.md

@@ -53,6 +53,14 @@ Inline style beats a class, so an operator's edit masks a class change Claude ma
 
 The Theme tab in the shell lists what the token stylesheet defines, grouped as color, spacing, radius, font family, font size, and other. The page record at `/api/pages` carries the same list as `tokens.groups`.
 
+## Undo in the shell
+
+The operator undoes and redoes their own shell edits, frame moves, and frame resizes from Ctrl or Cmd with Z, Shift with it or Ctrl with Y, or the tool strip's buttons. The history lives in the `canvas serve` process and covers shell edits alone, so a `canvas edit`, `canvas frame move`, or `canvas frame resize` never enters it, and their `--json` records are unchanged. A restart clears it.
+
+An undo writes the recorded state back only while the element or frame still holds what the operator's edit left. When Claude has since rewritten what that edit changed, being the element's inline style or, for a text edit, its text, or has added or removed an element in that frame, the operator's entry is dropped and nothing is written, and the shell says so. A write that changes another element's style or text, or another part of the same element, leaves the entry live. The page record at `/api/pages` carries `history` as `{ canUndo, canRedo }`.
+
+The tool strip also holds a toggle, bound to backslash, that hides both side panels to show the whole surface, and each panel resizes from a handle on its inner edge. Both are remembered in the browser and write nothing to the project.
+
 ## Mark a frame being edited
 
 `canvas editing <page>/<frame>` marks a frame as being edited, so an open canvas shows who is working on it before the write lands. The shell draws the mark as `<by> editing` on that frame's label with a dashed outline around it, and drops it on the reread after `--done` or at the mark's `until` with no reread. Run it before writing a frame and again with `--done` once the edits are written. A bare `canvas editing` lists the live marks, and `--json` emits `{ ok, editing }` after each of the three, with each mark carrying `page`, `frame`, `by`, `since`, and `until`.

package/docs/agents/pr-evidence.md

@@ -42,7 +42,7 @@ directory under the `evidence/` segment, and within a state by filename stem,
 so a `before/hero.png` and an `after/hero.png` naming the same case group as
 one entry, not two files. Each entry carries whether it existed at the base
 commit, so the comment shows a base image or marks it new. All-new states drop
-the Base column and each image is an `<img width="1000">`.
+the Base column and each `<img>` takes its PNG width, at most 1000.
 
 `reason` on the record is what a caller branches on, not the exit code:
 
@@ -85,9 +85,10 @@ unreadable thread refuses as `gh-failed` on both reasons rather than
 reporting the fields absent.
 
 `ok` also carries `states`, the comparison the body renders as data: each
-state's name and its items, each with its `path`, `stem`, and whether it was
-`added`. `review-ui` matches a frame against it so it publishes no image the
+state's items with `path`, `stem`, `added`, and `width` and `baseWidth` when
+read. `review-ui` matches a frame against it so it publishes no image the
 worker's evidence already shows. `canon docs pr-frames` covers that store.
+`widthUnread` lists a failed read as `head:<path>` or `base:<path>`.
 
 ## What `[number]` selects, and what it does not
 
@@ -243,12 +244,11 @@ or `--checklist` with it refuses as `check-writes` before any `gh` call, since
 those ask a read to write.
 
 The thread cannot separate a skipped preview step from a failed one. A pull
-request whose deploy run failed or timed out reads as owing a preview, and the
+request whose deploy failed or timed out reads as owing a preview, and the
 session that ran it holds the cause. A checklist-only branch posts a marked
 comment, so it reads as owing a preview once that comment exists and a deploy
-workflow resolves. The deploy
-workflow is read from the checkout rather than the pull request's head, so a
-pull request that adds or removes its own deploy workflow reads against trunk's.
+workflow resolves. The deploy workflow is read from the checkout rather than
+the pull request's head, so one adding or removing its own reads trunk's.
 
 An unreadable thread refuses as `gh-failed` rather than reporting `settled` off
 a thread it never read. The check skips the merge base read, which only the

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/canon",
   "type": "module",
-  "version": "5.28.0",
+  "version": "5.30.0",
   "description": "Runs your agent's work and keeps its code good, on one setup for every repo.",
   "license": "MIT",
   "bin": {

package/src/canvas/client/app.tsx

@@ -1,9 +1,20 @@
 /** @jsxImportSource preact */
+import { effect } from '@preact/signals'
 import type { JSX } from 'preact'
-import { useRef } from 'preact/hooks'
+import { useLayoutEffect, 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 { 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 = {
@@ -66,22 +77,112 @@ function PageDetails(): JSX.Element | null {
   )
 }
 
+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="shell">
+    <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 class="panel panel-right" aria-label="Details">
+      <aside id="details-panel" class="panel panel-right" aria-label="Details">
         <Inspector />
         <PageDetails />
         <TokenDetails />
       </aside>
+      <PanelHandle side="right" controls="details-panel" />
     </div>
   )
 }

package/src/canvas/client/inspector.tsx

@@ -34,6 +34,7 @@ import {
   frameDocuments,
   frameKey,
   frameVersions,
+  newStep,
   pendingEdit,
   savedEdit,
   selectedElement,
@@ -240,17 +241,25 @@ function ElementFields({
   }
   /*
    * The writer takes one property an edit, so a control setting two posts
-   * them in turn and stops at the first refusal. Each carries the hash the
-   * last answered with in its own address, since a frame reloading between
-   * the two clears the stored one.
+   * them in turn and stops at the first refusal, under one step so they undo
+   * as one. Each carries the hash the last answered with in its own address,
+   * since a frame reloading between the two clears the stored one.
    */
   const commitAll = async (
     changes: readonly (readonly [string, string])[],
   ): Promise<void> => {
+    const step = newStep()
     let current = address
     for (const [property, value] of changes) {
       if (!current) return
-      const written = await editElement(frameRef, key, current, property, value)
+      const written = await editElement(
+        frameRef,
+        key,
+        current,
+        property,
+        value,
+        step,
+      )
       if (!written) return
       if (written.hash) current = { ...current, hash: written.hash }
     }

package/src/canvas/client/keys.ts

@@ -12,6 +12,9 @@ export type SurfaceAction =
   | 'zoom-fit'
   | 'pan-hold'
   | 'pan-release'
+  | 'undo'
+  | 'redo'
+  | 'panels-toggle'
 
 /** The fields of a `KeyboardEvent` the map reads, so a test needs no DOM. */
 export interface KeyInput {
@@ -34,21 +37,35 @@ const PLAIN_KEYS: Readonly<Record<string, SurfaceAction | undefined>> = {
 }
 
 /**
- * Cmd, Ctrl, and Alt combinations are the browser's or the system's, so any
- * of them held on a press returns nothing. Space coming up releases whatever
- * is held with it, or a modifier pressed mid-pan would leave the pan stuck.
- * Shift and the 1 key fits by `code`, since the character Shift gives on that
- * key differs by layout.
+ * Undo and redo are the one exception to the browser owning a modifier: Ctrl
+ * or Cmd with Z, with Shift to redo, and Ctrl with Y. Any other Cmd, Ctrl, or
+ * Alt combination is the browser's or the system's, so it returns nothing.
+ */
+function historyAction(event: KeyInput): SurfaceAction | undefined {
+  if (event.altKey) return undefined
+  const key = event.key.toLowerCase()
+  if (key === 'z') return event.shiftKey ? 'redo' : 'undo'
+  if (key === 'y' && event.ctrlKey && !event.shiftKey) return 'redo'
+  return undefined
+}
+
+/**
+ * Space coming up releases whatever is held with it, or a modifier pressed
+ * mid-pan would leave the pan stuck. Shift and the 1 key fits, and the
+ * backslash key toggles the panels, by `code`, since the character each
+ * gives differs by layout.
  */
 export function surfaceAction(event: KeyInput): SurfaceAction | undefined {
   if (event.type === 'keyup') {
     return event.key === ' ' ? 'pan-release' : undefined
   }
   if (event.type !== 'keydown') return undefined
-  if (event.ctrlKey || event.metaKey || event.altKey) return undefined
+  if (event.ctrlKey || event.metaKey) return historyAction(event)
+  if (event.altKey) return undefined
   if (event.shiftKey) {
     if (event.code === 'Digit1') return 'zoom-fit'
     return event.key === '+' ? 'zoom-in' : undefined
   }
+  if (event.code === 'Backslash') return 'panels-toggle'
   return PLAIN_KEYS[event.key.toLowerCase()]
 }

package/src/canvas/client/main.tsx

@@ -51,6 +51,15 @@ chrome.rel = 'stylesheet'
 chrome.href = '/api/chrome.css'
 document.head.prepend(chrome)
 
+/*
+ * The page declares an empty icon so the browser never asks for /favicon.ico,
+ * since the bundler cannot resolve a route the server answers, and this points
+ * it at the brand icon once the shell loads.
+ */
+document
+  .querySelector('link[rel="icon"]')
+  ?.setAttribute('href', '/api/icon.svg')
+
 const events = new EventSource('/api/events')
 events.addEventListener('message', (message) => {
   void applyChange(JSON.parse(message.data) as ChangeEvent)

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

@@ -174,7 +174,11 @@ function Tabs(): JSX.Element {
 
 export function PagesPanel(props: PagesPanelProps): JSX.Element {
   return (
-    <nav class="panel panel-left" aria-label="Pages and frames">
+    <nav
+      id="pages-panel"
+      class="panel panel-left"
+      aria-label="Pages and frames"
+    >
       <header class="panel-head">
         <span class="brand">Canvas</span>
         <ThemeToggle />

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

@@ -0,0 +1,90 @@
+/** @jsxImportSource preact */
+import type { JSX } from 'preact'
+import { useRef } from 'preact/hooks'
+import {
+  clampPanelWidth,
+  MAX_PANEL_WIDTH,
+  MIN_PANEL_WIDTH,
+  type PanelSide,
+  panelWidths,
+  setPanelWidth,
+} from '@/canvas/client/state'
+
+const KEY_STEP = 16
+const SHIFT_STEP = 64
+
+const NAMES: Readonly<Record<PanelSide, string>> = {
+  left: 'Resize pages panel',
+  right: 'Resize details panel',
+}
+
+/**
+ * The drag handle on a panel's inner edge, a focusable separator the arrow
+ * keys move as well. It sits outside the surface, so a drag on it never pans,
+ * moves a frame, or reaches the undo history.
+ */
+export function PanelHandle({
+  side,
+  controls,
+}: {
+  readonly side: PanelSide
+  readonly controls: string
+}): JSX.Element {
+  const drag = useRef<{ x: number; width: number } | undefined>(undefined)
+  const width = panelWidths.value[side]
+  /* Dragging right widens the left panel and narrows the right one. */
+  const sign = side === 'left' ? 1 : -1
+
+  const handlePointerDown = (event: PointerEvent) => {
+    event.preventDefault()
+    drag.current = { x: event.clientX, width }
+    ;(event.currentTarget as HTMLElement).setPointerCapture?.(event.pointerId)
+  }
+
+  const handlePointerMove = (event: PointerEvent) => {
+    const start = drag.current
+    if (!start) return
+    setPanelWidth(
+      side,
+      start.width + sign * (event.clientX - start.x),
+      window.innerWidth,
+    )
+  }
+
+  const handlePointerUp = () => {
+    drag.current = undefined
+  }
+
+  const handleKeyDown = (event: KeyboardEvent) => {
+    const step = event.shiftKey ? SHIFT_STEP : KEY_STEP
+    const next: Record<string, number | undefined> = {
+      ArrowRight: width + sign * step,
+      ArrowLeft: width - sign * step,
+      Home: MIN_PANEL_WIDTH,
+      End: MAX_PANEL_WIDTH,
+    }
+    const wanted = next[event.key]
+    if (wanted === undefined) return
+    event.preventDefault()
+    setPanelWidth(side, wanted, window.innerWidth)
+  }
+
+  return (
+    <div
+      class={`panel-handle panel-handle-${side}`}
+      role="separator"
+      aria-orientation="vertical"
+      aria-label={NAMES[side]}
+      aria-controls={controls}
+      aria-valuenow={width}
+      aria-valuemin={MIN_PANEL_WIDTH}
+      aria-valuemax={clampPanelWidth(side, MAX_PANEL_WIDTH, window.innerWidth)}
+      tabIndex={0}
+      onPointerDown={handlePointerDown}
+      onPointerMove={handlePointerMove}
+      onPointerUp={handlePointerUp}
+      onPointerCancel={handlePointerUp}
+      onKeyDown={handleKeyDown}
+    />
+  )
+}

package/src/canvas/client/shell.css

@@ -38,11 +38,58 @@ code {
 }
 
 .shell {
+  position: relative;
   display: grid;
-  grid-template-columns: 15rem minmax(0, 1fr) 16rem;
+  grid-template-columns: var(--panel-left, 15rem) minmax(0, 1fr) var(
+      --panel-right,
+      16rem
+    );
   height: 100%;
 }
 
+/*
+ * Centered on the edge, so a 24 pixel circle around it stays inside the
+ * panel's padding on one side and short of the tool strip on the other, with
+ * a line drawn at the edge itself.
+ */
+.panel-handle {
+  position: absolute;
+  top: 0;
+  bottom: 0;
+  z-index: 2;
+  width: 12px;
+  cursor: col-resize;
+  touch-action: none;
+}
+
+.panel-handle-left {
+  left: calc(var(--panel-left, 15rem) - 6px);
+}
+
+.panel-handle-right {
+  right: calc(var(--panel-right, 16rem) - 6px);
+}
+
+.panel-handle::after {
+  content: '';
+  position: absolute;
+  top: 0;
+  bottom: 0;
+  left: 5px;
+  width: 2px;
+  background: transparent;
+}
+
+.panel-handle:hover::after,
+.panel-handle:active::after,
+.panel-handle:focus-visible::after {
+  background: var(--color-accent);
+}
+
+.shell.panels-hidden > .panel-handle {
+  display: none;
+}
+
 .panel {
   overflow-y: auto;
   padding: var(--space-md);
@@ -531,6 +578,32 @@ code {
   background: var(--color-border);
 }
 
+.tool-button:disabled {
+  opacity: 0.4;
+  background: transparent;
+  cursor: not-allowed;
+}
+
+.tools-divider {
+  height: 1px;
+  margin: 2px var(--space-xs);
+  background: var(--color-border);
+}
+
+.history-notice {
+  position: absolute;
+  top: var(--space-md);
+  left: 50%;
+  max-width: min(28rem, calc(100% - 8rem));
+  margin: 0;
+  padding: var(--space-xs) var(--space-sm);
+  border: 1px solid var(--color-border);
+  border-radius: var(--radius-panel);
+  background: var(--color-chrome);
+  color: var(--color-text);
+  transform: translateX(-50%);
+}
+
 .zoom {
   min-width: 3.5rem;
   text-align: center;
@@ -543,7 +616,8 @@ code {
     grid-template-columns: 12rem minmax(0, 1fr);
   }
 
-  .panel-right {
+  .panel-right,
+  .panel-handle {
     display: none;
   }
 }
@@ -561,6 +635,16 @@ code {
   }
 }
 
+/* Two classes outrank every width's own columns, so hiding holds at each. */
+.shell.panels-hidden {
+  grid-template-columns: minmax(0, 1fr);
+  grid-template-rows: minmax(0, 1fr);
+}
+
+.shell.panels-hidden > .panel {
+  display: none;
+}
+
 .frame-row {
   display: flex;
   align-items: center;