@erclx/canon 5.14.0 → 5.15.0

package/scripts/core/install-check.sh

@@ -22,7 +22,7 @@ Usage: scripts/core/install-check.sh [--keep]
 
 Verifies the published install path end to end:
   1. Packs this repo into a tarball at .canon/tmp/install-check/pack
-  2. Extracts it and asserts scripts/sandbox is absent from the tree
+  2. Extracts it and asserts sandbox is absent from the tree
   3. Runs bun install --production in the extracted tree
   4. Runs the CLI with --help from the extracted tree to confirm it resolves
   5. Scaffolds a fresh project in .canon/tmp/install-check/target
@@ -51,6 +51,15 @@ mkdir -p "$PACK_DIR" "$EXTRACT_DIR"
 
 open_timeline "Install verification"
 
+# An absence check over a path the source tree no longer holds passes on
+# nothing, so the excluded tree has to exist here before its absence below can
+# mean the publish left it out.
+log_step "Assert excluded path exists in source"
+if [ ! -f "$PROJECT_ROOT/sandbox/run.sh" ]; then
+  log_error "sandbox/run.sh is missing from the source tree, so the absence check below would pass on nothing"
+fi
+log_info "Present: sandbox/run.sh"
+
 log_step "Pack"
 TARBALL_PATH="$(cd "$PROJECT_ROOT" && bun pm pack --quiet --ignore-scripts --destination "$PACK_DIR" | tail -n 1)"
 log_info "Packed to $TARBALL_PATH"
@@ -60,10 +69,10 @@ tar -xzf "$TARBALL_PATH" -C "$EXTRACT_DIR" --strip-components=1
 log_info "Extracted to $EXTRACT_DIR"
 
 log_step "Assert excluded path is absent"
-if [ -e "$EXTRACT_DIR/scripts/sandbox" ]; then
-  log_error "scripts/sandbox shipped in the tarball, and the files field in package.json excludes it"
+if [ -e "$EXTRACT_DIR/sandbox" ]; then
+  log_error "sandbox shipped in the tarball, and the files field in package.json leaves it out"
 fi
-log_info "Absent: scripts/sandbox"
+log_info "Absent: sandbox"
 
 log_step "Install dependencies (production)"
 (cd "$EXTRACT_DIR" && bun install --production --ignore-scripts --silent 2>&1 | pipe_output) || log_error "bun install --production failed"

package/scripts/lib/sandbox-dispatch.sh

@@ -9,7 +9,7 @@
 # them, so the escape watch reported clean throughout and was right to. The run
 # spent real cost until a person found it, and `SIGTERM` alone did not end it.
 #
-# Three mechanisms sit here rather than in `scripts/sandbox/run.sh`, which is the
+# Three mechanisms sit here rather than in `sandbox/run.sh`, which is the
 # only caller. Each is reachable from a test that never launches a session:
 # `src/sandbox-dispatch.test.ts` drives the shim against a stub binary and the
 # reap against a `sleep`, where proving either through `run.sh` would mean

package/scripts/lib/sandbox-fixtures.sh

@@ -6,7 +6,7 @@
 FIXTURE_SUFFIX=".fixture"
 
 # The tree mirrors the scenario path, so `category` and `scenario` together match
-# `scripts/sandbox/<category>/<scenario>.sh`. Both segments are load-bearing:
+# `sandbox/<category>/<scenario>.sh`. Both segments are load-bearing:
 # four scenario basenames repeat across categories (`claude`, `docs`, `review`,
 # `sync`), and `docs` is also a category of its own.
 fixture_stage_dir() {
@@ -14,7 +14,7 @@ fixture_stage_dir() {
   local scenario="$2"
   local arm="$3"
   local stage="$4"
-  echo "$PROJECT_ROOT/scripts/sandbox/fixtures/$category/$scenario/$arm/$stage"
+  echo "$PROJECT_ROOT/sandbox/fixtures/$category/$scenario/$arm/$stage"
 }
 
 list_fixture_files() {

package/scripts/lib/sandbox-path.sh

@@ -1,6 +1,6 @@
 #!/usr/bin/env bash
 
-# The sandbox tree lives outside the toolkit worktree. `scripts/sandbox/run.sh`
+# The sandbox tree lives outside the toolkit worktree. `sandbox/run.sh`
 # sets cwd to it for `claude -p`, and every `CLAUDE.md` between that cwd and the
 # filesystem root loads into the session. Under the repository the toolkit's own
 # instructions join that chain beside the seeded copy the scenario installed,

package/scripts/manage-sandbox.sh

@@ -40,7 +40,7 @@ show_help() {
   exit 0
 }
 
-ANCHOR_FIXTURE_DIR="$PROJECT_ROOT/scripts/sandbox/fixtures/anchor/create"
+ANCHOR_FIXTURE_DIR="$PROJECT_ROOT/sandbox/fixtures/anchor/create"
 
 # Where an anchor scenario's tree comes from and where its remote points are two
 # concerns, and only the remote needs a network. Taking the tree from a fixture
@@ -438,7 +438,7 @@ main() {
   fi
 
   SANDBOX="$(resolve_sandbox_dir)"
-  SANDBOX_DIR="$PROJECT_ROOT/scripts/sandbox"
+  SANDBOX_DIR="$PROJECT_ROOT/sandbox"
 
   local unsafe
   if ! unsafe="$(assert_sandbox_dir_safe "$SANDBOX" "$PROJECT_ROOT")"; then

package/src/canvas/client/app.tsx

@@ -0,0 +1,85 @@
+/** @jsxImportSource preact */
+import type { JSX } from 'preact'
+import { useRef } from 'preact/hooks'
+import { PagesPanel } from '@/canvas/client/pages-panel'
+import { currentPage, focusFrame, 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>
+  )
+}
+
+export function App(): JSX.Element {
+  const viewportRef = useRef<HTMLDivElement>(null)
+  return (
+    <div class="shell">
+      <PagesPanel
+        onFocusFrame={(frame) => {
+          const rect = viewportRef.current?.getBoundingClientRect()
+          focusFrame(frame, rect?.width ?? 0, rect?.height ?? 0)
+        }}
+      />
+      <Surface viewportRef={viewportRef} />
+      <aside class="panel panel-right" aria-label="Details">
+        <PageDetails />
+        <TokenDetails />
+      </aside>
+    </div>
+  )
+}

package/src/canvas/client/main.tsx

@@ -0,0 +1,62 @@
+/** @jsxImportSource preact */
+import { effect } from '@preact/signals'
+import { render } from 'preact'
+import { App } from '@/canvas/client/app'
+import {
+  applyChange,
+  type ChangeEvent,
+  loadPages,
+  systemTheme,
+  theme,
+  themeChoice,
+  type Theme,
+} from '@/canvas/client/state'
+
+const THEME_KEY = 'canon-canvas-theme'
+
+function readStoredTheme(): Theme | undefined {
+  try {
+    const stored = localStorage.getItem(THEME_KEY)
+    return stored === 'light' || stored === 'dark' ? stored : undefined
+  } catch {
+    return undefined
+  }
+}
+
+function storeTheme(value: Theme | undefined): void {
+  try {
+    if (value === undefined) localStorage.removeItem(THEME_KEY)
+    else localStorage.setItem(THEME_KEY, value)
+  } catch {
+    /* A blocked store costs the remembered pick, nothing else. */
+  }
+}
+
+const darkQuery = matchMedia('(prefers-color-scheme: dark)')
+systemTheme.value = darkQuery.matches ? 'dark' : 'light'
+darkQuery.addEventListener('change', (event) => {
+  systemTheme.value = event.matches ? 'dark' : 'light'
+})
+themeChoice.value = readStoredTheme()
+
+effect(() => {
+  document.documentElement.dataset.theme = theme.value
+  document.documentElement.style.colorScheme = theme.value
+})
+effect(() => storeTheme(themeChoice.value))
+
+/* The chrome reads this toolkit's own tokens, served beside the shell. */
+const chrome = document.createElement('link')
+chrome.rel = 'stylesheet'
+chrome.href = '/api/chrome.css'
+document.head.prepend(chrome)
+
+const events = new EventSource('/api/events')
+events.addEventListener('message', (message) => {
+  void applyChange(JSON.parse(message.data) as ChangeEvent)
+})
+
+void loadPages()
+
+const mount = document.getElementById('app')
+if (mount) render(<App />, mount)

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

@@ -0,0 +1,123 @@
+/** @jsxImportSource preact */
+import type { JSX } from 'preact'
+import type { Frame } from '@/canvas/content'
+import {
+  currentPage,
+  isLoaded,
+  loadError,
+  pages,
+  selectedPage,
+  theme,
+  toggleTheme,
+} from '@/canvas/client/state'
+
+export interface PagesPanelProps {
+  /** Brings a frame into view on the surface. */
+  readonly onFocusFrame: (frame: Frame) => void
+}
+
+function ThemeToggle(): JSX.Element {
+  const next = theme.value === 'dark' ? 'light' : 'dark'
+  return (
+    <button
+      type="button"
+      class="icon-button"
+      aria-label={`Switch to ${next} theme`}
+      title={`Switch to ${next} theme`}
+      onClick={toggleTheme}
+    >
+      <span aria-hidden="true">{theme.value === 'dark' ? '☾' : '☀'}</span>
+    </button>
+  )
+}
+
+function PageList(): JSX.Element {
+  if (pages.value.length === 0) {
+    return (
+      <p class="empty">
+        No pages yet. Run <code>canon canvas page add &lt;name&gt;</code> to add
+        one.
+      </p>
+    )
+  }
+  const current = currentPage.value?.name
+  return (
+    <ul class="list" aria-label="Pages">
+      {pages.value.map((page) => (
+        <li key={page.name}>
+          <button
+            type="button"
+            class="row"
+            aria-current={page.name === current ? 'page' : undefined}
+            title={page.name}
+            onClick={() => {
+              selectedPage.value = page.name
+            }}
+          >
+            <span class="row-label">{page.name}</span>
+            <span class="row-meta">{page.frames.length}</span>
+          </button>
+        </li>
+      ))}
+    </ul>
+  )
+}
+
+function FrameList({ onFocusFrame }: PagesPanelProps): JSX.Element | null {
+  const page = currentPage.value
+  if (!page) return null
+  if (page.frames.length === 0) {
+    return (
+      <p class="empty">
+        No frames on this page. Run{' '}
+        <code>canon canvas frame add {page.name} &lt;name&gt;</code> to add one.
+      </p>
+    )
+  }
+  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>
+      ))}
+    </ul>
+  )
+}
+
+export function PagesPanel(props: PagesPanelProps): JSX.Element {
+  return (
+    <nav class="panel panel-left" aria-label="Pages and frames">
+      <header class="panel-head">
+        <span class="brand">Canvas</span>
+        <ThemeToggle />
+      </header>
+      {loadError.value ? (
+        <p class="empty" role="alert">
+          {loadError.value}
+        </p>
+      ) : !isLoaded.value ? (
+        <p class="empty">Loading</p>
+      ) : (
+        <>
+          <h2 class="section-label">Pages</h2>
+          <PageList />
+          {currentPage.value ? (
+            <>
+              <h2 class="section-label">Frames</h2>
+              <FrameList {...props} />
+            </>
+          ) : null}
+        </>
+      )}
+    </nav>
+  )
+}

package/src/canvas/client/shell.css

@@ -0,0 +1,319 @@
+/*
+ * The canvas chrome. Every value reads a custom property from this toolkit's
+ * own token module, served at /api/chrome.css, which maps dark onto :root and
+ * light onto [data-theme='light']. A frame reads the project's tokens inside
+ * its own iframe, so the two sets of names never meet.
+ */
+
+* {
+  box-sizing: border-box;
+}
+
+html,
+body {
+  height: 100%;
+  margin: 0;
+}
+
+body {
+  background: var(--color-background);
+  color: var(--color-text);
+  font-family: var(--type-body-family);
+  font-size: var(--type-label-size);
+  line-height: var(--type-label-lh);
+}
+
+#app {
+  height: 100%;
+}
+
+:focus-visible {
+  outline: 2px solid var(--color-accent);
+  outline-offset: 2px;
+}
+
+code {
+  font-family: var(--type-code-family);
+  font-size: var(--type-code-size);
+}
+
+.shell {
+  display: grid;
+  grid-template-columns: 15rem minmax(0, 1fr) 13rem;
+  height: 100%;
+}
+
+.panel {
+  overflow-y: auto;
+  padding: var(--space-md);
+  background: var(--color-chrome);
+  min-width: 0;
+}
+
+.panel-left {
+  border-right: 1px solid var(--color-border);
+}
+
+.panel-right {
+  border-left: 1px solid var(--color-border);
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-lg);
+}
+
+.panel-head {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  margin-bottom: var(--space-md);
+}
+
+.brand {
+  font-weight: 600;
+  color: var(--color-text);
+}
+
+.section-label {
+  margin: var(--space-md) 0 var(--space-xs);
+  font-size: var(--type-label-size);
+  font-weight: 500;
+  color: var(--color-text-secondary);
+}
+
+.panel-right .section-label {
+  margin-top: 0;
+}
+
+.list {
+  list-style: none;
+  margin: 0;
+  padding: 2px;
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+}
+
+.row {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--space-sm);
+  width: 100%;
+  min-height: 28px;
+  padding: var(--space-xs) var(--space-sm);
+  border: 0;
+  border-radius: var(--radius-action);
+  background: transparent;
+  color: var(--color-text-body);
+  font: inherit;
+  text-align: left;
+  cursor: pointer;
+}
+
+.row:hover {
+  background: var(--color-surface);
+  color: var(--color-text);
+}
+
+.row:active {
+  background: var(--color-border);
+}
+
+.row[aria-current='page'] {
+  background: var(--color-surface);
+  color: var(--color-text);
+  box-shadow: inset 2px 0 0 var(--color-accent);
+}
+
+.row-label {
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.row-meta {
+  flex-shrink: 0;
+  color: var(--color-muted);
+  font-variant-numeric: tabular-nums;
+}
+
+.empty,
+.notice {
+  margin: var(--space-xs) 0;
+  color: var(--color-text-secondary);
+}
+
+.notice {
+  border-left: 2px solid var(--color-accent);
+  padding-left: var(--space-sm);
+}
+
+.detail {
+  margin: 0;
+  color: var(--color-text);
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.detail-meta {
+  margin: 0;
+  color: var(--color-muted);
+}
+
+.files {
+  list-style: none;
+  margin: var(--space-xs) 0 0;
+  padding: 0;
+}
+
+.files li {
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  color: var(--color-text-body);
+}
+
+.icon-button,
+.text-button {
+  min-width: 28px;
+  min-height: 28px;
+  padding: 0 var(--space-sm);
+  border: 1px solid var(--color-border);
+  border-radius: var(--radius-action);
+  background: var(--color-surface);
+  color: var(--color-text);
+  font: inherit;
+  cursor: pointer;
+}
+
+.icon-button:hover,
+.text-button:hover {
+  border-color: var(--color-text-secondary);
+}
+
+.icon-button:active,
+.text-button:active {
+  background: var(--color-border);
+}
+
+.surface {
+  position: relative;
+  min-width: 0;
+  overflow: hidden;
+  background: var(--color-background);
+}
+
+.viewport {
+  position: absolute;
+  inset: 0;
+  overflow: hidden;
+  cursor: grab;
+  touch-action: none;
+}
+
+.viewport:active {
+  cursor: grabbing;
+}
+
+.plane {
+  position: absolute;
+  top: 0;
+  left: 0;
+  transform-origin: 0 0;
+}
+
+.frame {
+  position: absolute;
+  margin: 0;
+  cursor: default;
+}
+
+.frame-label {
+  position: absolute;
+  bottom: 100%;
+  left: 0;
+  right: 0;
+  display: flex;
+  align-items: center;
+  gap: var(--space-sm);
+  padding-bottom: var(--space-sm);
+  font-size: 1.5rem;
+  color: var(--color-text-secondary);
+  white-space: nowrap;
+}
+
+.frame-name {
+  overflow: hidden;
+  text-overflow: ellipsis;
+  color: var(--color-text);
+}
+
+.frame-size {
+  color: var(--color-muted);
+  font-variant-numeric: tabular-nums;
+}
+
+.frame-theme {
+  margin-left: auto;
+  padding: 2px var(--space-sm);
+  border: 1px solid var(--color-border);
+  border-radius: var(--radius-pill);
+  background: var(--color-surface);
+  color: var(--color-text-secondary);
+  font: inherit;
+  cursor: pointer;
+}
+
+.frame-theme:hover {
+  color: var(--color-text);
+}
+
+.frame iframe {
+  display: block;
+  border: 1px solid var(--color-border);
+  border-radius: 2px;
+}
+
+.toolbar {
+  position: absolute;
+  right: var(--space-md);
+  bottom: var(--space-md);
+  display: flex;
+  align-items: center;
+  gap: var(--space-xs);
+  padding: var(--space-xs);
+  border: 1px solid var(--color-border);
+  border-radius: var(--radius-panel);
+  background: var(--color-chrome);
+}
+
+.zoom {
+  min-width: 3.5rem;
+  text-align: center;
+  font-variant-numeric: tabular-nums;
+  color: var(--color-text-secondary);
+}
+
+@media (max-width: 900px) {
+  .shell {
+    grid-template-columns: 12rem minmax(0, 1fr);
+  }
+
+  .panel-right {
+    display: none;
+  }
+}
+
+@media (max-width: 600px) {
+  .shell {
+    grid-template-columns: minmax(0, 1fr);
+    grid-template-rows: auto minmax(0, 1fr);
+  }
+
+  .panel-left {
+    max-height: 40vh;
+    border-right: 0;
+    border-bottom: 1px solid var(--color-border);
+  }
+}