@erclx/canon 5.15.0 → 5.16.0

package/src/canvas/client/state.ts

@@ -1,9 +1,12 @@
 import { computed, signal } from '@preact/signals'
+import type { ElementAddress } from '@/canvas/address'
 import type { Frame, Page } from '@/canvas/content'
 
 /**
  * Everything the panels read. Type imports only from outside `client/`, since
  * this runs in the browser and a Node or Bun module would not bundle there.
+ * `@/canvas/address` is the one exception the client imports for values, since
+ * it imports nothing itself.
  */
 
 export type Theme = 'light' | 'dark'
@@ -14,9 +17,27 @@ export interface TokenSource {
   readonly notice?: string
 }
 
+export interface FrameRef {
+  readonly page: string
+  readonly frame: string
+}
+
+export interface ElementRef {
+  readonly index: number
+  readonly tag: string
+  /** Set by the server once the frame file changed since the pick. */
+  readonly stale?: boolean
+}
+
+export interface SelectionRef extends FrameRef {
+  readonly element?: ElementRef
+}
+
 export interface PagesRecord {
   readonly pages: readonly Page[]
   readonly tokens: TokenSource
+  /** Absent when nothing is selected or the selected frame is gone. */
+  readonly selection?: SelectionRef | null
 }
 
 export interface ChangeEvent {
@@ -54,11 +75,51 @@ export const frameVersions = signal<ReadonlyMap<string, number>>(new Map())
 
 export const view = signal<View>({ x: 0, y: 0, zoom: 0.5 })
 
+/**
+ * The one frame, or element in it, the operator pointed at, which Claude reads
+ * as "this one".
+ */
+export const selection = signal<SelectionRef | undefined>(undefined)
+
+/** Each loaded frame's document by frame key, replaced on every reload. */
+export const frameDocuments = signal<ReadonlyMap<string, Document>>(new Map())
+
+/** The element under the pointer, in a frame or in the layers tree. */
+export const hoveredElement = signal<
+  { readonly key: string; readonly index: number } | undefined
+>(undefined)
+
+/** Frame keys whose layers are open in the pages panel. */
+export const expandedFrames = signal<ReadonlySet<string>>(new Set())
+
+/** Set while a frame follows the pointer, so the surface can style it. */
+export const draggingFrame = signal<string | undefined>(undefined)
+
+/** Why the last write to the canvas failed, until the next one succeeds. */
+export const writeError = signal<string | undefined>(undefined)
+
 export const currentPage = computed<Page | undefined>(() => {
   const all = pages.value
   return all.find((page) => page.name === selectedPage.value) ?? all[0]
 })
 
+/** The selected frame when it is on the page being shown. */
+export const selectedFrame = computed<Frame | undefined>(() => {
+  const page = currentPage.value
+  const chosen = selection.value
+  if (!page || chosen?.page !== page.name) return undefined
+  return page.frames.find((frame) => frame.name === chosen.frame)
+})
+
+/** The selected element when its frame is on the page being shown. */
+export const selectedElement = computed<
+  { readonly frame: Frame; readonly element: ElementRef } | undefined
+>(() => {
+  const frame = selectedFrame.value
+  const element = selection.value?.element
+  return frame && element ? { frame, element } : undefined
+})
+
 export function frameKey(page: string, frame: Pick<Frame, 'file'>): string {
   return `${page}/${frame.file}`
 }
@@ -77,9 +138,22 @@ export function toggleFrameTheme(key: string): void {
   frameThemes.value = next
 }
 
+export function registerFrameDocument(key: string, doc: Document): void {
+  const next = new Map(frameDocuments.value)
+  next.set(key, doc)
+  frameDocuments.value = next
+}
+
+export function toggleLayers(key: string): void {
+  const next = new Set(expandedFrames.value)
+  if (!next.delete(key)) next.add(key)
+  expandedFrames.value = next
+}
+
 export function applyRecord(record: PagesRecord): void {
   pages.value = record.pages
   tokens.value = record.tokens
+  selection.value = record.selection ?? undefined
   loadError.value = undefined
   isLoaded.value = true
 }
@@ -115,6 +189,112 @@ export async function applyChange(
   await loadPages(fetchImpl)
 }
 
+/** What a refused element pick tells the operator, by the server's reason. */
+const PICK_NOTICES: Readonly<Record<string, string | undefined>> = {
+  'address-mismatch':
+    'Could not select that element, since the browser and the file count the elements of this frame differently, as when the browser builds an element the file does not state.',
+  'stale-address':
+    'Could not select that element, since the frame changed before the pick arrived. Pick it again once the frame reloads.',
+}
+
+async function refusalReason(response: Response): Promise<string | undefined> {
+  try {
+    const body: unknown = await response.json()
+    return typeof body === 'object' && body !== null && 'reason' in body
+      ? String(body.reason)
+      : undefined
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * Posts one write and reports a refusal in the panel rather than failing
+ * silently. A refusal also rereads the page list, so a position the server
+ * would not take does not stay on the surface.
+ */
+async function write(
+  path: string,
+  body: unknown,
+  fetchImpl: typeof fetch,
+): Promise<void> {
+  try {
+    const response = await fetchImpl(path, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify(body),
+    })
+    if (!response.ok) {
+      const reason = await refusalReason(response)
+      writeError.value =
+        (reason && PICK_NOTICES[reason]) ??
+        `Could not save (status ${response.status}). Check canon canvas serve is still running.`
+      await loadPages(fetchImpl)
+      return
+    }
+    writeError.value = undefined
+  } catch (error) {
+    writeError.value = `Could not save (${error instanceof Error ? error.message : 'unknown'}). Check canon canvas serve is still running.`
+    await loadPages(fetchImpl)
+  }
+}
+
+/** Selects a frame here at once and records it where Claude reads it. */
+export async function selectFrame(
+  ref: FrameRef | undefined,
+  fetchImpl: typeof fetch = fetch,
+): Promise<void> {
+  selection.value = ref
+  await write('/api/selection', ref ?? {}, fetchImpl)
+}
+
+/**
+ * Selects one element of a frame, opens that frame's layers so the tree shows
+ * the pick, and records it where Claude reads it. The server checks the
+ * address against the file and refuses one it cannot match.
+ */
+export async function selectElement(
+  ref: FrameRef,
+  key: string,
+  address: ElementAddress,
+  fetchImpl: typeof fetch = fetch,
+): Promise<void> {
+  selection.value = {
+    ...ref,
+    element: { index: address.index, tag: address.tag },
+  }
+  if (!expandedFrames.value.has(key)) toggleLayers(key)
+  await write('/api/selection', { ...ref, element: address }, fetchImpl)
+}
+
+/**
+ * Moves a frame on the surface without writing, which a drag calls on every
+ * pointer move. The next reread replaces it with what the layout holds.
+ */
+export function previewMove(ref: FrameRef, x: number, y: number): void {
+  pages.value = pages.value.map((candidate) =>
+    candidate.name === ref.page
+      ? {
+          ...candidate,
+          frames: candidate.frames.map((frame) =>
+            frame.name === ref.frame ? { ...frame, x, y, placed: true } : frame,
+          ),
+        }
+      : candidate,
+  )
+}
+
+/** Shows the move and writes it through the server's shared layout writer. */
+export async function moveFrameTo(
+  ref: FrameRef,
+  x: number,
+  y: number,
+  fetchImpl: typeof fetch = fetch,
+): Promise<void> {
+  previewMove(ref, x, y)
+  await write('/api/frames/move', { ...ref, x, y }, fetchImpl)
+}
+
 export function clampZoom(zoom: number): number {
   return Math.min(MAX_ZOOM, Math.max(MIN_ZOOM, zoom))
 }
@@ -183,4 +363,10 @@ export function resetState(): void {
   frameThemes.value = new Map()
   frameVersions.value = new Map()
   view.value = { x: 0, y: 0, zoom: 0.5 }
+  selection.value = undefined
+  frameDocuments.value = new Map()
+  hoveredElement.value = undefined
+  expandedFrames.value = new Set()
+  draggingFrame.value = undefined
+  writeError.value = undefined
 }

package/src/canvas/client/surface.tsx

@@ -1,14 +1,25 @@
 /** @jsxImportSource preact */
 import type { JSX, RefObject } from 'preact'
-import { useEffect, useRef } from 'preact/hooks'
+import { useEffect, useRef, useState } from 'preact/hooks'
+import { addressOf, documentElements, elementAt } from '@/canvas/address'
 import type { Frame } from '@/canvas/content'
 import {
   currentPage,
+  draggingFrame,
   fitView,
+  type FrameRef,
+  frameDocuments,
   frameKey,
   frameTheme,
   frameVersions,
+  hoveredElement,
+  moveFrameTo,
   panBy,
+  previewMove,
+  registerFrameDocument,
+  selectElement,
+  selectFrame,
+  selection,
   type Theme,
   toggleFrameTheme,
   view,
@@ -18,10 +29,76 @@ import {
 /** One wheel notch or one button press. */
 const ZOOM_STEP = 1.2
 
+/** Screen pixels a press travels before it reads as a drag and not a click. */
+const DRAG_THRESHOLD = 3
+
+/** Surface units one arrow press moves a frame, and one with Shift held. */
+const NUDGE = 10
+const NUDGE_LARGE = 50
+
+const ARROWS: Readonly<Record<string, { x: number; y: number } | undefined>> = {
+  ArrowLeft: { x: -1, y: 0 },
+  ArrowRight: { x: 1, y: 0 },
+  ArrowUp: { x: 0, y: -1 },
+  ArrowDown: { x: 0, y: 1 },
+}
+
+interface Gesture {
+  readonly startX: number
+  readonly startY: number
+  readonly originX: number
+  readonly originY: number
+  x: number
+  y: number
+  moved: boolean
+}
+
 export interface SurfaceProps {
   readonly viewportRef: RefObject<HTMLDivElement | null>
 }
 
+/** A wheel turn in shell coordinates, wherever the pointer sat. */
+interface WheelTurn {
+  readonly deltaX: number
+  readonly deltaY: number
+  readonly isZoom: boolean
+  readonly clientX: number
+  readonly clientY: number
+}
+
+/**
+ * The frame's own document is a separate window, so an element in it fails an
+ * `instanceof Element` against the shell's window. The node type is the test
+ * that holds across both.
+ */
+function asElement(target: EventTarget | null): Element | undefined {
+  const node = target as Node | null
+  return node?.nodeType === 1 ? (node as Element) : undefined
+}
+
+function ElementOutline({
+  element,
+  kind,
+}: {
+  readonly element: Element
+  readonly kind: 'hover' | 'selected'
+}): JSX.Element {
+  const rect = element.getBoundingClientRect()
+  return (
+    <div
+      class="element-outline"
+      data-outline={kind}
+      aria-hidden="true"
+      style={{
+        left: `${rect.left}px`,
+        top: `${rect.top}px`,
+        width: `${rect.width}px`,
+        height: `${rect.height}px`,
+      }}
+    />
+  )
+}
+
 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}`
@@ -41,31 +118,179 @@ function applyFrameTheme(iframe: HTMLIFrameElement | null, value: Theme): void {
 function FrameView({
   page,
   frame,
+  onWheelTurn,
 }: {
   readonly page: string
   readonly frame: Frame
+  readonly onWheelTurn: (turn: WheelTurn) => void
 }): JSX.Element {
   const key = frameKey(page, frame)
   const version = frameVersions.value.get(key) ?? 0
   const value = frameTheme(key)
   const iframe = useRef<HTMLIFrameElement>(null)
+  const gesture = useRef<Gesture | undefined>(undefined)
+  const ref: FrameRef = { page, frame: frame.name }
+  const isSelected =
+    selection.value?.page === page && selection.value.frame === frame.name
+  /* Bumped when the frame document scrolls, so the outlines follow it. */
+  const [, setScrolled] = useState(0)
+  const doc = frameDocuments.value.get(key)
 
   useEffect(() => {
     applyFrameTheme(iframe.current, value)
   }, [value])
 
+  /*
+   * The frame shares the shell's origin, so its document takes listeners
+   * directly. A click selects the element under it and goes no further, so a
+   * link or a submit button in a draft never navigates the frame away.
+   */
+  const handleLoad = () => {
+    const element = iframe.current
+    const loaded = element?.contentDocument
+    applyFrameTheme(element, frameTheme(key))
+    if (!element || !loaded) return
+    registerFrameDocument(key, loaded)
+
+    loaded.addEventListener('click', (event) => {
+      event.preventDefault()
+      event.stopPropagation()
+      const target = asElement(event.target)
+      const address = target && addressOf(loaded, target)
+      if (address) void selectElement(ref, key, address)
+    })
+    loaded.addEventListener('submit', (event) => event.preventDefault())
+    loaded.addEventListener('mouseover', (event) => {
+      const target = asElement(event.target)
+      const index = target ? documentElements(loaded).indexOf(target) : -1
+      hoveredElement.value = index === -1 ? undefined : { key, index }
+    })
+    loaded.addEventListener('mouseleave', () => {
+      if (hoveredElement.value?.key === key) hoveredElement.value = undefined
+    })
+    loaded.addEventListener('scroll', () => setScrolled((n) => n + 1))
+    loaded.addEventListener(
+      'wheel',
+      (event) => {
+        event.preventDefault()
+        const rect = element.getBoundingClientRect()
+        const { zoom } = view.value
+        onWheelTurn({
+          deltaX: event.deltaX,
+          deltaY: event.deltaY,
+          isZoom: event.ctrlKey || event.metaKey,
+          clientX: rect.left + event.clientX * zoom,
+          clientY: rect.top + event.clientY * zoom,
+        })
+      },
+      { passive: false },
+    )
+  }
+
+  const picked =
+    isSelected && doc && selection.value?.element
+      ? selection.value.element
+      : undefined
+  const selectedNode =
+    doc && picked && !picked.stale ? elementAt(doc, picked) : undefined
+  const hovered = hoveredElement.value
+  const hoveredNode =
+    doc && hovered?.key === key
+      ? documentElements(doc)[hovered.index]
+      : undefined
+
+  /* The label means the frame itself, so it also drops a picked element. */
+  const select = () => {
+    if (!isSelected || selection.value?.element) void selectFrame(ref)
+  }
+
+  const handlePointerDown = (event: PointerEvent) => {
+    if (event.button !== 0) return
+    if ((event.target as HTMLElement | null)?.closest('.frame-theme')) return
+    gesture.current = {
+      startX: event.clientX,
+      startY: event.clientY,
+      originX: frame.x,
+      originY: frame.y,
+      x: frame.x,
+      y: frame.y,
+      moved: false,
+    }
+    ;(event.currentTarget as HTMLElement).setPointerCapture?.(event.pointerId)
+    select()
+  }
+
+  const handlePointerMove = (event: PointerEvent) => {
+    const current = gesture.current
+    if (!current) return
+    const dx = event.clientX - current.startX
+    const dy = event.clientY - current.startY
+    if (!current.moved && Math.hypot(dx, dy) < DRAG_THRESHOLD) return
+    const { zoom } = view.value
+    current.moved = true
+    current.x = Math.round(current.originX + dx / zoom)
+    current.y = Math.round(current.originY + dy / zoom)
+    draggingFrame.value = frame.name
+    previewMove(ref, current.x, current.y)
+  }
+
+  const handlePointerUp = () => {
+    const current = gesture.current
+    gesture.current = undefined
+    draggingFrame.value = undefined
+    if (current?.moved) void moveFrameTo(ref, current.x, current.y)
+  }
+
+  const handlePointerCancel = () => {
+    const current = gesture.current
+    gesture.current = undefined
+    draggingFrame.value = undefined
+    if (current?.moved) previewMove(ref, current.originX, current.originY)
+  }
+
+  /*
+   * The keyboard path for a drag, since a pointer gesture alone leaves a
+   * frame unmovable without a mouse.
+   */
+  const handleKeyDown = (event: KeyboardEvent) => {
+    if (event.target !== event.currentTarget) return
+    if (event.key === 'Enter' || event.key === ' ') {
+      event.preventDefault()
+      select()
+      return
+    }
+    const step = event.shiftKey ? NUDGE_LARGE : NUDGE
+    const delta = ARROWS[event.key]
+    if (!delta || !isSelected) return
+    event.preventDefault()
+    void moveFrameTo(ref, frame.x + delta.x * step, frame.y + delta.y * step)
+  }
+
   const next = value === 'dark' ? 'light' : 'dark'
   return (
     <figure
       class="frame"
       data-frame={frame.name}
+      data-selected={isSelected ? 'true' : undefined}
+      data-dragging={draggingFrame.value === frame.name ? 'true' : undefined}
+      tabIndex={0}
+      aria-label={`${frame.name}, ${frame.width} by ${frame.height}`}
+      aria-current={isSelected ? 'true' : undefined}
+      onKeyDown={handleKeyDown}
       style={{
         left: `${frame.x}px`,
         top: `${frame.y}px`,
         width: `${frame.width}px`,
       }}
     >
-      <figcaption class="frame-label">
+      {/* The frame's handle, since a press inside the frame picks an element. */}
+      <figcaption
+        class="frame-label"
+        onPointerDown={handlePointerDown}
+        onPointerMove={handlePointerMove}
+        onPointerUp={handlePointerUp}
+        onPointerCancel={handlePointerCancel}
+      >
         <span class="frame-name" title={frame.name}>
           {frame.name}
         </span>
@@ -82,15 +307,23 @@ function FrameView({
           {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))}
-      />
+      <div class="frame-body">
+        <iframe
+          ref={iframe}
+          title={frame.name}
+          src={frameSrc(page, frame, version)}
+          width={frame.width}
+          height={frame.height}
+          style={{ height: `${frame.height}px` }}
+          onLoad={handleLoad}
+        />
+        {hoveredNode && hoveredNode !== selectedNode ? (
+          <ElementOutline element={hoveredNode} kind="hover" />
+        ) : null}
+        {selectedNode ? (
+          <ElementOutline element={selectedNode} kind="selected" />
+        ) : null}
+      </div>
     </figure>
   )
 }
@@ -153,19 +386,29 @@ export function Surface({ viewportRef }: SurfaceProps): JSX.Element {
     fitView(width, height)
   }, [page?.name])
 
-  const handleWheel = (event: WheelEvent) => {
-    event.preventDefault()
-    if (event.ctrlKey || event.metaKey) {
+  const handleWheelTurn = (turn: WheelTurn) => {
+    if (turn.isZoom) {
       const rect = viewportRef.current?.getBoundingClientRect()
-      const factor = event.deltaY < 0 ? ZOOM_STEP : 1 / ZOOM_STEP
+      const factor = turn.deltaY < 0 ? ZOOM_STEP : 1 / ZOOM_STEP
       zoomAt(
         factor,
-        event.clientX - (rect?.left ?? 0),
-        event.clientY - (rect?.top ?? 0),
+        turn.clientX - (rect?.left ?? 0),
+        turn.clientY - (rect?.top ?? 0),
       )
       return
     }
-    panBy(-event.deltaX, -event.deltaY)
+    panBy(-turn.deltaX, -turn.deltaY)
+  }
+
+  const handleWheel = (event: WheelEvent) => {
+    event.preventDefault()
+    handleWheelTurn({
+      deltaX: event.deltaX,
+      deltaY: event.deltaY,
+      isZoom: event.ctrlKey || event.metaKey,
+      clientX: event.clientX,
+      clientY: event.clientY,
+    })
   }
 
   const handlePointerDown = (event: PointerEvent) => {
@@ -200,10 +443,19 @@ export function Surface({ viewportRef }: SurfaceProps): JSX.Element {
       >
         <div
           class="plane"
-          style={{ transform: `translate(${x}px, ${y}px) scale(${zoom})` }}
+          style={{
+            transform: `translate(${x}px, ${y}px) scale(${zoom})`,
+            /* Lets an outline inside the plane hold its screen weight at any zoom. */
+            '--outline-scale': String(1 / zoom),
+          }}
         >
           {page?.frames.map((frame) => (
-            <FrameView key={frame.name} page={page.name} frame={frame} />
+            <FrameView
+              key={frame.name}
+              page={page.name}
+              frame={frame}
+              onWheelTurn={handleWheelTurn}
+            />
           ))}
         </div>
       </div>