@tio-canvas/canvas 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tio Putra
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,107 @@
-# Temporary Holding Version
+# @tio-canvas/canvas
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A private exploration canvas for a web project. Pages of the project are laid out
+as real, live documents (same-origin iframes) on a finite board that you can pan,
+zoom, arrange, resize to device presets, rename, annotate with arrows and text,
+and preview full screen. It is a development tool: it adds nothing to what a
+visitor of the project downloads unless the project chooses to publish `/canvas`.
+
+Plain HTML, CSS and JavaScript. No framework, no bundler for the canvas itself.
+The only dependencies (`interface-kit`, `react`, `react-dom`, `esbuild`) exist to
+build the optional development-only Interface Kit overlay and are never sent to
+a browser except by the dev server, as one script, inside a framed screen.
+
+The behaviour of the canvas is described in [`docs/exploration-canvas.md`](docs/exploration-canvas.md).
+
+## Install
+
+```bash
+pnpm add -D @tio-canvas/canvas     # or: npm i -D @tio-canvas/canvas
+```
+
+## Use it in a project
+
+### 1. List your screens
+
+Create `dev/canvas/screens.js` (any path works; pass it as `config`). It is a
+standalone ES module that the **browser loads as it stands**, so it must not
+import anything.
+
+```js
+export const storageKey = 'my-project:canvas:v1'; // where the browser keeps the saved layout
+export const screens = [
+  { id: 'home', kind: 'production', title: 'Home', description: 'The live homepage.',
+    src: '/', x: 160, y: 160, width: 1440, height: 900, preset: 'laptop' },
+];
+```
+
+- `id` is stable: saved layouts refer to it. `kind` is `production` or `prototype`.
+  `description` is required. Both are checked and a mistake throws.
+- `preset` is a key of the device presets (`laptop`, `iphone-16`, `ipad-air`, …; see `client/registry.js`).
+- `storageKey` is optional. Two projects served from one origin (for example
+  `localhost:4321`) must not share a key, or they overwrite each other's layout.
+
+Page thumbnails live in `dev/canvas/thumbnails/<id>.webp` (see `tio-canvas thumbnails`).
+
+### 2. Serve it from your dev server
+
+The package does not own a server. Your dev server asks it where things are:
+
+```js
+import { createCanvasHost } from '@tio-canvas/canvas/server';
+const canvas = createCanvasHost({ root, config: 'dev/canvas/screens.js' });
+
+// For a request under /canvas:
+const { directory, localPath, project } = canvas.locate(pathname);   // which file to read
+//   if (project) send `await canvas.projectModule()` as text/javascript instead of the file
+// For an HTML page in development:
+const { bridge, tools } = canvas.pageScripts(url, request.headers); // scripts to add before </body>
+// For GET /__dev/interface-kit.js:
+const script = await canvas.interfaceKitBundle();
+// Reload the workspace when any of these change:
+for (const dir of canvas.watchTargets()) watch(dir, { recursive: true }, notify);
+```
+
+`tio-web`'s `build/serve.mjs` is the reference integration.
+
+### 3. Publish it with your site (optional)
+
+```js
+import { copyCanvas } from '@tio-canvas/canvas/build';
+const screens = await copyCanvas({ root, config: 'dev/canvas/screens.js', target: 'dist/canvas' });
+```
+
+This writes the canvas, your screens as `project.js`, only the thumbnails of
+screens that exist, and a `noindex` tag. Do not link to it from a public page.
+
+### 4. Thumbnails
+
+With the dev server running:
+
+```bash
+npx tio-canvas thumbnails http://localhost:4321 --missing
+npx tio-canvas thumbnails --check          # fails when a screen has no thumbnail
+```
+
+Options: `--config <file>`, `--out <dir>`. It uses a Chromium from the Playwright
+cache (`~/Library/Caches/ms-playwright`) or `CHROME_BIN`.
+
+## Updating
+
+Releases follow semver. A project updates with `pnpm update @tio-canvas/canvas`.
+Nothing else needs to change as long as the major version stays the same.
+
+## Development
+
+```bash
+pnpm install
+pnpm test        # unit tests and a smoke test of the server and build helpers
+```
+
+`client/` is served at `/canvas/`. Its files are the canvas exactly as it ran
+inside `tio-web` (the commit it was extracted from is in the first commit
+message), with two changes: `screens.js` now reads `project.js` and
+`registry.js`, and `canvas.js` takes its storage key from the project.
+
+Publishing: `npm login`, then `npm publish` (the scope is public through
+`publishConfig`). Bump the version first and tag it `vX.Y.Z`.

package/bin/tio-canvas.mjs

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+const [command, ...rest] = process.argv.slice(2);
+const commands = {
+  thumbnails: () => import("../src/thumbnails.js")
+};
+if (!commands[command]) {
+  console.error(`Usage: tio-canvas thumbnails [base-url] [--missing|--check] [--config <file>] [--out <dir>]`);
+  process.exit(command ? 1 : 0);
+}
+process.argv.splice(2, 1, ...rest);
+process.argv.length = 2 + rest.length;
+await commands[command]();

package/client/arrange.js

@@ -0,0 +1,41 @@
+import { bounds, pixelRect } from './geometry.js';
+import { groupSpacing } from './spacing.js';
+
+const alignments = {
+  left: ['x', 'width', 0], 'horizontal-center': ['x', 'width', .5], right: ['x', 'width', 1],
+  top: ['y', 'height', 0], 'vertical-center': ['y', 'height', .5], bottom: ['y', 'height', 1],
+};
+const alignmentKeys = { KeyA: 'left', KeyH: 'horizontal-center', KeyD: 'right', KeyW: 'top', KeyV: 'vertical-center', KeyS: 'bottom' };
+
+export function arrangeShortcut(event) {
+  if (!event.altKey || event.metaKey || event.shiftKey) return null;
+  // Option changes event.key on macOS; physical codes keep these shortcuts usable.
+  if (event.ctrlKey) return event.code === 'KeyH' ? 'distribute-x' : event.code === 'KeyV' ? 'distribute-y' : null;
+  return Object.hasOwn(alignmentKeys, event.code) ? alignmentKeys[event.code] : null;
+}
+
+// Arrange within the selection's existing bounds, never resize or reorder screens.
+// Distribution shares the gap fields' bands, so grid columns/rows stay together.
+export function arrangeScreens(rectangles, action) {
+  if (rectangles.length < 2) return null;
+  const result = rectangles.map(pixelRect), box = bounds(result);
+  const alignment = Object.hasOwn(alignments, action) ? alignments[action] : null;
+  if (alignment) {
+    const [axis, size, anchor] = alignment;
+    for (const rect of result) rect[axis] = Math.round(box[axis] + (box[size] - rect[size]) * anchor);
+    return result;
+  }
+  const axis = action === 'distribute-x' ? 'x' : action === 'distribute-y' ? 'y' : null;
+  if (!axis) return null;
+  const spacing = groupSpacing(result, { width: 20000, height: 11250 }, axis);
+  if (!spacing || spacing.bands.length < 3) return null;
+  const total = spacing.bands.reduce((sum, band) => sum + band.size, 0);
+  const gap = (box[spacing.size] - total) / (spacing.bands.length - 1);
+  let position = box[axis];
+  for (const band of spacing.bands) {
+    // Rounding cumulative positions spreads fractional pixels instead of drifting.
+    for (const { index } of band.items) result[index][axis] = Math.round(Math.max(box[axis], Math.min(position, box[axis] + box[spacing.size] - band.size)));
+    position += band.size + gap;
+  }
+  return result;
+}

package/client/arrow-geometry.js

@@ -0,0 +1,56 @@
+const clamp = (value, min, max) => Math.min(max, Math.max(min, value));
+export const SIDES = ['top', 'right', 'bottom', 'left'];
+export const ARROW_GAP = 8;
+
+// Bindings use object IDs and a fraction along an edge, not screen-specific data.
+export function boundPoint(binding, objects) {
+  const object = objects.find(item => item.id === binding.objectId);
+  if (!object) return null;
+  const { x, y, width, height } = object, t = binding.t;
+  if (binding.side === 'top') return { x: x + width * t, y: y - ARROW_GAP };
+  if (binding.side === 'bottom') return { x: x + width * t, y: y + height + ARROW_GAP };
+  if (binding.side === 'left') return { x: x - ARROW_GAP, y: y + height * t };
+  return { x: x + width + ARROW_GAP, y: y + height * t };
+}
+export function resolvePoint(point, objects) {
+  return point.binding ? boundPoint(point.binding, objects) ?? point : point;
+}
+export function snapArrow(point, objects, scale) {
+  let center = null, edge = null;
+  for (const object of objects) for (const side of SIDES) {
+    const binding = { objectId: object.id, side, t: .5 };
+    const middle = boundPoint(binding, objects);
+    const distance = Math.hypot(point.x - middle.x, point.y - middle.y) * scale;
+    if (distance <= 20 && (!center || distance < center.distance)) center = { ...middle, binding: { ...binding }, distance };
+    const horizontal = side === 'top' || side === 'bottom';
+    binding.t = clamp((point[horizontal ? 'x' : 'y'] - object[horizontal ? 'x' : 'y']) / object[horizontal ? 'width' : 'height'], 0, 1);
+    const projected = boundPoint(binding, objects);
+    const edgeDistance = Math.hypot(point.x - projected.x, point.y - projected.y) * scale;
+    if (edgeDistance <= 12 && (!edge || edgeDistance < edge.distance)) edge = { ...projected, binding: { ...binding }, distance: edgeDistance };
+  }
+  const result = center ?? edge;
+  return result ? { x: result.x, y: result.y, binding: result.binding } : { x: point.x, y: point.y };
+}
+export function arrowGeometry(arrow, objects) {
+  const start = resolvePoint(arrow.start, objects), end = resolvePoint(arrow.end, objects);
+  const dx = end.x - start.x, dy = end.y - start.y, length = Math.hypot(dx, dy);
+  const normal = length ? { x: -dy / length, y: dx / length } : { x: 0, y: 1 };
+  const midpoint = { x: (start.x + end.x) / 2, y: (start.y + end.y) / 2 };
+  const middle = { x: midpoint.x + normal.x * arrow.bend, y: midpoint.y + normal.y * arrow.bend };
+  const h = Math.abs(arrow.bend);
+  const radius = h ? length * length / (8 * h) + h / 2 : 0;
+  const path = h > .01 && length > .01
+    ? `M ${start.x} ${start.y} A ${radius} ${radius} 0 ${h > length / 2 ? 1 : 0} ${arrow.bend > 0 ? 0 : 1} ${end.x} ${end.y}`
+    : `M ${start.x} ${start.y} L ${end.x} ${end.y}`;
+  return { start, end, middle, midpoint, normal, length, path };
+}
+export function readArrows(value) {
+  if (!Array.isArray(value)) return [];
+  const number = n => Number.isFinite(n) && Math.abs(n) <= 40000;
+  const point = p => p && number(p.x) && number(p.y) && (!p.binding || (typeof p.binding.objectId === 'string' && SIDES.includes(p.binding.side) && Number.isFinite(p.binding.t) && p.binding.t >= 0 && p.binding.t <= 1));
+  const ids = new Set();
+  return value.slice(0, 1000).filter(a => {
+    if (!a || typeof a.id !== 'string' || a.id.length > 100 || ids.has(a.id) || !point(a.start) || !point(a.end) || !number(a.bend) || !['arrow', 'line'].includes(a.startStyle) || !['arrow', 'line'].includes(a.endStyle) || !Number.isFinite(a.width) || a.width < 1 || a.width > 16 || !['solid', 'dashed', 'dotted'].includes(a.pattern)) return false;
+    ids.add(a.id);return true;
+  }).map(a => ({ ...structuredClone(a), width: Math.max(2, Math.min(10, Math.round(a.width / 2) * 2)) }));
+}

package/client/arrow-selection.js

@@ -0,0 +1,68 @@
+import { arrowGeometry } from './arrow-geometry.js';
+
+function arc(arrow, objects) {
+  const g = arrowGeometry(arrow, objects);
+  if (Math.abs(arrow.bend) < .01 || g.length < .01) return { ...g, curved: false };
+  const radius = g.length ** 2 / (8 * Math.abs(arrow.bend)) + Math.abs(arrow.bend) / 2;
+  const signedRadius = Math.sign(arrow.bend) * radius;
+  const center = { x: g.midpoint.x + g.normal.x * (arrow.bend - signedRadius), y: g.midpoint.y + g.normal.y * (arrow.bend - signedRadius) };
+  const startAngle = Math.atan2(g.start.y - center.y, g.start.x - center.x);
+  const endAngle = Math.atan2(g.end.y - center.y, g.end.x - center.x);
+  const direction = arrow.bend > 0 ? -1 : 1;
+  const distance = angle => ((angle - startAngle) * direction % (2 * Math.PI) + 2 * Math.PI) % (2 * Math.PI);
+  const sweep = distance(endAngle);
+  return { ...g, curved: true, radius, center, contains: point => distance(Math.atan2(point.y - center.y, point.x - center.x)) <= sweep + 1e-8 };
+}
+export function arrowBounds(arrows, objects) {
+  const points = [];
+  for (const arrow of arrows) {
+    const g = arc(arrow, objects);points.push(g.start, g.end);
+    if (g.curved) for (const [dx, dy] of [[1, 0], [0, 1], [-1, 0], [0, -1]]) {
+      const point = { x: g.center.x + dx * g.radius, y: g.center.y + dy * g.radius };
+      if (g.contains(point)) points.push(point);
+    }
+  }
+  if (!points.length) return null;
+  const x = Math.min(...points.map(p => p.x)), y = Math.min(...points.map(p => p.y));
+  return { x, y, width: Math.max(...points.map(p => p.x)) - x, height: Math.max(...points.map(p => p.y)) - y };
+}
+export function arrowIntersects(arrow, box, objects) {
+  if (box.width <= 0 || box.height <= 0) return false;
+  const g = arc(arrow, objects), right = box.x + box.width, bottom = box.y + box.height;
+  const inside = p => p.x >= box.x && p.x <= right && p.y >= box.y && p.y <= bottom;
+  if (inside(g.start) || inside(g.end)) return true;
+  if (!g.curved) {
+    // Slab intersection rejects empty parts of a diagonal's bounding box.
+    let low = 0, high = 1;
+    for (const [axis, min, max] of [['x', box.x, right], ['y', box.y, bottom]]) {
+      const d = g.end[axis] - g.start[axis];
+      if (!d) { if (g.start[axis] < min || g.start[axis] > max) return false;continue; }
+      const a = (min - g.start[axis]) / d, b = (max - g.start[axis]) / d;
+      low = Math.max(low, Math.min(a, b));high = Math.min(high, Math.max(a, b));
+    }
+    return low <= high;
+  }
+  for (const x of [box.x, right]) {
+    const squared = g.radius ** 2 - (x - g.center.x) ** 2;
+    if (squared < 0) continue;
+    for (const y of [g.center.y - Math.sqrt(squared), g.center.y + Math.sqrt(squared)]) if (y >= box.y && y <= bottom && g.contains({ x, y })) return true;
+  }
+  for (const y of [box.y, bottom]) {
+    const squared = g.radius ** 2 - (y - g.center.y) ** 2;
+    if (squared < 0) continue;
+    for (const x of [g.center.x - Math.sqrt(squared), g.center.x + Math.sqrt(squared)]) if (x >= box.x && x <= right && g.contains({ x, y })) return true;
+  }
+  return false;
+}
+export function resizeArrows(originals, box, corner, point, origin) {
+  if (originals.some(a => a.start.binding || a.end.binding)) return null;
+  const anchor = { x: box.x + (corner.includes('w') ? box.width : 0), y: box.y + (corner.includes('n') ? box.height : 0) };
+  const vector = { x: origin.x - anchor.x, y: origin.y - anchor.y };
+  const length = vector.x ** 2 + vector.y ** 2;
+  const scale = Math.max(.01, length ? ((point.x - anchor.x) * vector.x + (point.y - anchor.y) * vector.y) / length : 1);
+  return originals.map(arrow => {
+    const next = structuredClone(arrow);
+    for (const name of ['start', 'end']) next[name] = { x: anchor.x + (arrow[name].x - anchor.x) * scale, y: anchor.y + (arrow[name].y - anchor.y) * scale };
+    next.bend *= scale;return next;
+  });
+}

package/client/arrows.js

@@ -0,0 +1,205 @@
+import { SIDES, boundPoint, resolvePoint, snapArrow, arrowGeometry, readArrows } from './arrow-geometry.js';
+import { arrowBounds, arrowIntersects, resizeArrows } from './arrow-selection.js';
+import { setupArrowFields } from './select-field.js';
+
+const NS = 'http://www.w3.org/2000/svg';
+const svgElement = (tag, attributes = {}) => {
+  const node = document.createElementNS(NS, tag);
+  for (const [name, value] of Object.entries(attributes)) node.setAttribute(name, value);
+  return node;
+};
+export function createArrows({ viewport, world, camera, objects, saved, checkpoint, commit, clearScreens, screenSelectionCount, rank, schedule, stopCanvas }) {
+  let arrows = readArrows(saved), tool = 'cursor', drag = null, hover = null;
+  const chosen = new Set();
+  const layer = document.createElement('div');layer.id = 'arrow-layer';world.append(layer);
+  const dots = document.createElement('div');dots.id = 'arrow-snaps';
+  const nodes = document.createElement('div');nodes.id = 'arrow-nodes';viewport.append(dots, nodes);
+  const toolbar = document.querySelector('#arrow-inspector'), fields = setupArrowFields(toolbar);
+  const cursorButton = document.querySelector('#tool-cursor'), arrowButton = document.querySelector('#tool-arrow'), textButton = document.querySelector('#tool-text');
+  const pointAt = event => ({ x: (event.clientX - camera.x) / camera.scale, y: (event.clientY - camera.y) / camera.scale });
+  const screenPoint = point => ({ x: camera.x + point.x * camera.scale, y: camera.y + point.y * camera.scale });
+  const selected = () => arrows.filter(a => chosen.has(a.id));
+  function choose(arrow, toggle = false) {
+    if (!toggle) { chosen.clear();if (arrow) clearScreens(); }
+    if (arrow) { if (toggle && chosen.has(arrow.id)) chosen.delete(arrow.id);else chosen.add(arrow.id); }
+    schedule();
+  }
+  function setTool(value) {
+    cancel();stopCanvas();fields.close();tool = value;
+    document.body.dataset.canvasTool = tool;
+    cursorButton.setAttribute('aria-pressed', String(tool === 'cursor'));arrowButton.setAttribute('aria-pressed', String(tool === 'arrow'));textButton.setAttribute('aria-pressed', String(tool === 'text'));
+    if (tool === 'arrow' || tool === 'text') { clearScreens();chosen.clear(); }
+    document.dispatchEvent(new CustomEvent('tio-canvas:tool', { detail: tool }));
+    schedule();
+  }
+  cursorButton.onclick = () => setTool('cursor');arrowButton.onclick = () => setTool('arrow');
+  function begin(event, arrow, part, before = checkpoint()) {
+    if (drag || event.button !== 0) return;
+    stopCanvas();fields.close();event.preventDefault();event.stopPropagation();viewport.focus({ preventScroll: true });
+    if (arrow && !chosen.has(arrow.id)) choose(arrow);
+    drag = { id: event.pointerId, arrow, part, before, origin: pointAt(event), originals: structuredClone(selected()), created: part === 'create', box: arrowBounds(selected(), objects()) };
+    document.body.dataset.arrowDrag = '';viewport.setPointerCapture(event.pointerId);schedule();
+  }
+  viewport.addEventListener('pointerdown', event => {
+    if (document.body.hasAttribute('data-fullscreen') || document.body.hasAttribute('data-space') || event.button !== 0 || event.target.closest('#arrow-inspector')) return;
+    const corner = event.target.closest('[data-arrow-corner]');
+    if (corner) { begin(event, null, corner.dataset.arrowCorner);return; }
+    const handle = event.target.closest('[data-arrow-node]');
+    if (handle && selected().length === 1) { begin(event, selected()[0], handle.dataset.arrowNode);return; }
+    const hit = event.target.closest('[data-arrow-id]');
+    if (tool === 'cursor' && hit) {
+      const arrow = arrows.find(a => a.id === hit.dataset.arrowId);
+      if (event.shiftKey) { event.preventDefault();event.stopPropagation();choose(arrow, true);return; }
+      if (arrow) begin(event, arrow, 'move');return;
+    }
+    if (tool !== 'arrow') return;
+    if (arrows.length >= 1000) { event.preventDefault();event.stopPropagation();document.querySelector('#canvas-status').textContent = 'The canvas supports up to 1,000 arrows.';return; }
+    const before = checkpoint(), start = snapArrow(pointAt(event), objects(), camera.scale);
+    const arrow = { id: crypto.randomUUID(), start, end: structuredClone(start), bend: 0, startStyle: 'line', endStyle: 'arrow', width: 4, pattern: 'solid' };
+    arrows.push(arrow);choose(arrow);begin(event, arrow, 'create', before);
+  }, true);
+  function move(event) {
+    if (!drag) { if (tool === 'arrow') { hover = pointAt(event);schedule(); }return; }
+    if (event.pointerId !== drag.id) return;
+    const { arrow, part, originals, origin } = drag, point = pointAt(event);
+    if (!drag.moved && part !== 'create' && Math.hypot(point.x - origin.x, point.y - origin.y) * camera.scale < 3) return;
+    drag.moved = true;
+    if (['nw', 'ne', 'sw', 'se'].includes(part)) {
+      const next = resizeArrows(originals, drag.box, part, point, origin);
+      if (next) for (const model of next) Object.assign(arrows.find(a => a.id === model.id), model);
+    } else if (part === 'middle') {
+      const geometry = arrowGeometry(arrow, objects());
+      arrow.bend = (point.x - geometry.midpoint.x) * geometry.normal.x + (point.y - geometry.midpoint.y) * geometry.normal.y;
+      if (Math.abs(arrow.bend) * camera.scale < 3) arrow.bend = 0;
+    } else if (part === 'move') {
+      // A bound multi-selection is config-only; moving it would break its bindings.
+      if (originals.length > 1 && originals.some(a => a.start.binding || a.end.binding)) return;
+      for (const original of originals) for (const name of ['start', 'end']) {
+        const base = resolvePoint(original[name], objects()), target = arrows.find(a => a.id === original.id);
+        const nextPoint = { x: base.x + point.x - origin.x, y: base.y + point.y - origin.y };
+        target[name] = originals.length > 1 ? nextPoint : snapArrow(nextPoint, objects(), camera.scale);
+      }
+    } else arrow[part === 'create' ? 'end' : part] = snapArrow(point, objects(), camera.scale);
+    hover = point;schedule();
+  }
+  function finish(event) {
+    if (!drag || event.pointerId !== drag.id) return;
+    move(event);const previous = drag;drag = null;
+    if (viewport.hasPointerCapture(previous.id)) viewport.releasePointerCapture(previous.id);
+    delete document.body.dataset.arrowDrag;
+    if (previous.created && arrowGeometry(previous.arrow, objects()).length * camera.scale < 4) { arrows.splice(arrows.indexOf(previous.arrow), 1);chosen.clear(); }
+    else if (previous.created) setTool('cursor');
+    commit(previous.before);schedule();
+  }
+  function cancel() {
+    if (!drag) return false;
+    const previous = drag;drag = null;
+    if (viewport.hasPointerCapture(previous.id)) viewport.releasePointerCapture(previous.id);
+    if (previous.created) { arrows.splice(arrows.indexOf(previous.arrow), 1);chosen.clear(); }
+    else for (const original of previous.originals) Object.assign(arrows.find(a => a.id === original.id), original);
+    delete document.body.dataset.arrowDrag;schedule();return true;
+  }
+  window.addEventListener('pointermove', move);window.addEventListener('pointerup', finish);window.addEventListener('pointercancel', cancel);window.addEventListener('blur', cancel);
+  window.addEventListener('keydown', event => {
+    if (document.body.hasAttribute('data-fullscreen') || document.querySelector('dialog[open]') || event.target.closest?.('input,textarea,select,[contenteditable],.icon-options')) return;
+    if (event.key === 'Escape') { cancel();choose(null);setTool('cursor'); }
+    if (event.metaKey || event.ctrlKey || event.altKey) return;
+    if (event.key.toLowerCase() === 'v') setTool('cursor');if (event.key.toLowerCase() === 'a') setTool('arrow');
+    if (chosen.size && ['Delete', 'Backspace'].includes(event.key) && !event.defaultPrevented) { event.preventDefault();const before = checkpoint();removeSelected();commit(before); }
+  });
+  function removeSelected() { arrows = arrows.filter(a => !chosen.has(a.id));choose(null); }
+  toolbar.addEventListener('submit', event => event.preventDefault());
+  toolbar.addEventListener('change', event => {
+    if (!chosen.size) return;
+    const field = event.target.dataset.arrowField;if (!field) return;
+    const value = field === 'width' ? Number(event.target.value) : event.target.value;
+    if ((field === 'width' && ![2, 4, 6, 8, 10].includes(value)) || (['startStyle', 'endStyle'].includes(field) && !['line', 'arrow'].includes(value)) || (field === 'pattern' && !['solid', 'dashed'].includes(value))) return;
+    const before = checkpoint();for (const arrow of selected()) arrow[field] = value;commit(before);schedule();
+  });
+  document.querySelector('#arrow-straight').onclick = () => { if (!chosen.size) return;const before = checkpoint();for (const arrow of selected()) arrow.bend = 0;commit(before);schedule(); };
+  function render() {
+    const all = objects(), targets = selected();
+    for (const arrow of arrows) for (const name of ['start', 'end']) {
+      const point = arrow[name];if (!point.binding) continue;
+      const resolved = boundPoint(point.binding, all);if (resolved) Object.assign(point, resolved);else delete point.binding;
+    }
+    const focusedId = document.activeElement?.dataset?.arrowId, focusedNode = document.activeElement?.dataset?.arrowNode;
+    const contents = [];
+    for (const arrow of arrows) {
+      const geometry = arrowGeometry(arrow, all), active = chosen.has(arrow.id);
+      const svg = svgElement('svg', { class: 'arrow-object', 'data-object-id': arrow.id, width: 20000, height: 11250 });svg.style.zIndex = rank(arrow.id);
+      const defs = svgElement('defs'), length = 6 + arrow.width * 2, headSize = length + arrow.width * 2;
+      for (const end of ['start', 'end']) {
+        const marker = svgElement('marker', { id: `arrow-${arrow.id}-${end}`, viewBox: `${-length - arrow.width} ${-headSize / 2} ${headSize} ${headSize}`, markerWidth: headSize, markerHeight: headSize, refX: 0, refY: 0, orient: 'auto-start-reverse', markerUnits: 'userSpaceOnUse', overflow: 'visible' });
+        marker.append(svgElement('path', { d: `M ${-length} ${-length / 2} L 0 0 L ${-length} ${length / 2}`, fill: 'none', stroke: 'context-stroke', 'stroke-width': arrow.width, 'stroke-linecap': 'round', 'stroke-linejoin': 'round' }));defs.append(marker);
+      }
+      const path = svgElement('path', { d: geometry.path, class: 'arrow-line', 'stroke-width': arrow.width });
+      if (arrow.pattern !== 'solid') path.setAttribute('stroke-dasharray', `${arrow.width * 2} ${arrow.width * 3}`);
+      for (const end of ['start', 'end']) if (arrow[`${end}Style`] === 'arrow') path.setAttribute(`marker-${end}`, `url(#arrow-${arrow.id}-${end})`);
+      svg.append(defs, path);
+      if (active) {
+        const highlight = svgElement('path', { d: geometry.path, class: 'arrow-highlight', 'stroke-width': 1, 'vector-effect': 'non-scaling-stroke' });
+        if (arrow.pattern !== 'solid') highlight.setAttribute('stroke-dasharray', `${arrow.width * 2 * camera.scale} ${arrow.width * 3 * camera.scale}`);
+        svg.append(highlight);
+      }
+      const hit = svgElement('path', { d: geometry.path, class: 'arrow-hit', 'data-arrow-id': arrow.id, 'stroke-width': Math.max(16 / camera.scale, arrow.width + 8), tabindex: 0, role: 'button', 'aria-label': 'Select arrow', 'aria-pressed': String(active) });
+      hit.addEventListener('focus', () => { if (!chosen.has(arrow.id)) choose(arrow); });
+      hit.addEventListener('keydown', event => { if (['Enter', ' '].includes(event.key)) { event.preventDefault();choose(arrow, event.shiftKey); } });
+      svg.append(hit);contents.push(svg);
+    }
+    layer.replaceChildren(...contents);
+    if (focusedId) [...layer.querySelectorAll('[data-arrow-id]')].find(node => node.dataset.arrowId === focusedId)?.focus({ preventScroll: true });
+    dots.replaceChildren();
+    if (tool === 'arrow' || (drag && ['start', 'end', 'create'].includes(drag.part))) for (const object of all) {
+      const near = !hover || (hover.x >= object.x - 60 / camera.scale && hover.x <= object.x + object.width + 60 / camera.scale && hover.y >= object.y - 60 / camera.scale && hover.y <= object.y + object.height + 60 / camera.scale);
+      if (!near) continue;
+      for (const side of SIDES) {
+        const binding = { objectId: object.id, side, t: .5 }, p = screenPoint(boundPoint(binding, all));
+        const dot = document.createElement('span');dot.className = 'arrow-snap';dot.dataset.side = side;
+        if (drag && ['start', 'end', 'create'].includes(drag.part)) { const active = drag.arrow[drag.part === 'create' ? 'end' : drag.part].binding;dot.toggleAttribute('data-active', active?.objectId === object.id && active.side === side && active.t === .5); }
+        dot.style.left = `${p.x}px`;dot.style.top = `${p.y}px`;dots.append(dot);
+      }
+    }
+    nodes.replaceChildren();toolbar.hidden = !targets.length || !!drag;
+    if (toolbar.hidden) fields.close();
+    if (!targets.length) return;
+    if (targets.length === 1 && !screenSelectionCount()) {
+      const arrow = targets[0], geometry = arrowGeometry(arrow, all);
+      for (const name of ['start', 'middle', 'end']) {
+        const p = screenPoint(geometry[name]), button = document.createElement('button');button.type = 'button';button.className = 'smart-handle arrow-node';button.dataset.arrowNode = name;
+        button.setAttribute('aria-label', name === 'middle' ? 'Bend arrow symmetrically' : `Move arrow ${name}`);button.style.left = `${p.x}px`;button.style.top = `${p.y}px`;
+        nodes.append(button);
+      }
+    } else if (targets.length > 1 && !screenSelectionCount()) {
+      const box = arrowBounds(targets, all), p = screenPoint(box), frame = document.createElement('div');frame.className = 'arrow-group-box';
+      Object.assign(frame.style, { left: `${p.x}px`, top: `${p.y}px`, width: `${box.width * camera.scale}px`, height: `${box.height * camera.scale}px` });nodes.append(frame);
+      const locked = targets.some(a => a.start.binding || a.end.binding);frame.dataset.locked = String(locked);
+      if (!locked) for (const [corner, x, y] of [['nw', 0, 0], ['ne', 100, 0], ['se', 100, 100], ['sw', 0, 100]]) {
+        const button = document.createElement('button');button.type = 'button';button.className = 'handle';button.dataset.arrowCorner = corner;button.setAttribute('aria-label', `Resize arrows ${corner}`);
+        button.style.cssText = `left:${x}%;top:${y}%;cursor:${corner}-resize`;frame.append(button);
+      }
+    }
+    if (focusedNode && !drag) nodes.querySelector(`[data-arrow-node="${focusedNode}"]`)?.focus({ preventScroll: true });
+    for (const field of toolbar.querySelectorAll('[data-arrow-field]')) {
+      const values = targets.map(a => a[field.dataset.arrowField]), same = values.every(value => value === values[0]);
+      if (document.activeElement !== field) field.value = same ? String(values[0]) : '';
+    }
+    fields.update();
+    for (const element of toolbar.querySelectorAll('[data-curved-only]')) element.hidden = targets.every(a => Math.abs(a.bend) < .01);
+    const main = document.querySelector('#edit-tools').getBoundingClientRect(), inset = parseFloat(getComputedStyle(toolbar).getPropertyValue('--canvas-panel-inset'));
+    const center = Math.max(inset + toolbar.offsetWidth / 2, Math.min(innerWidth - inset - toolbar.offsetWidth / 2, main.left + main.width / 2));
+    toolbar.style.left = `${center}px`;toolbar.style.bottom = `${innerHeight - main.top + inset}px`;
+  }
+  return {
+    render,
+    capture: () => structuredClone(arrows),
+    restore(value, ids) { cancel();arrows = readArrows(value);chosen.clear();for (const id of Array.isArray(ids) ? ids : [ids]) if (arrows.some(a => a.id === id)) chosen.add(id);schedule(); },
+    get ids() { return arrows.map(a => a.id); },
+    get selectedIds() { return [...chosen]; },
+    clearSelection() { choose(null); },
+    selectRect(box, initial = []) { chosen.clear();for (const id of initial) if (arrows.some(a => a.id === id)) chosen.add(id);if (box) for (const arrow of arrows) if (arrowIntersects(arrow, box, objects())) chosen.add(arrow.id);schedule(); },
+    removeSelected,
+    cancel,
+    setTool,
+  };
+}

package/client/bridge.js

@@ -0,0 +1,74 @@
+import { arrangeShortcut } from './arrange.js';
+import { layerShortcut } from './layer-order.js';
+import { historyShortcut } from './history.js';
+import { createTouchPreview } from './touch-preview.js';
+// Dev-only host communication. Does not replace handlers or alter preview controls.
+const send = data => parent.postMessage(data, location.origin);
+let space = false, panning = false, active = false, fullscreen = false, canArrange = false;
+const typing = target => target.closest?.('input,textarea,select,[contenteditable]:not([contenteditable="false"])');
+window.addEventListener('pointerdown', event => {
+  if(fullscreen){send({type:'tio-canvas:preview-pointer'});return;}
+  if(event.button===0 && event.altKey && !space){event.preventDefault();event.stopImmediatePropagation();panning=true;send({type:'tio-canvas:alt-drag',screenX:event.screenX,screenY:event.screenY,shiftKey:event.shiftKey});return;}
+  if(event.button===0 && !space){if(!event.shiftKey)active=true;send({type:'tio-canvas:select',shift:event.shiftKey});}
+  if(event.button===1 || (event.button===0 && space)) {
+    event.preventDefault();panning=true;
+    send({type:'tio-canvas:pan',screenX:event.screenX,screenY:event.screenY});
+  }
+},true);
+window.addEventListener('pointermove',event=>{if(panning)send({type:'tio-canvas:move',screenX:event.screenX,screenY:event.screenY,shiftKey:event.shiftKey,altKey:event.altKey,metaKey:event.metaKey,ctrlKey:event.ctrlKey});});
+const stop=()=>{const active=panning||space;panning=false;space=false;if(active)send({type:'tio-canvas:stop'});};
+window.addEventListener('pointerup',()=>{if(panning)stop();});window.addEventListener('pointercancel',stop);window.addEventListener('blur',stop);
+window.addEventListener('contextmenu',event=>{if(fullscreen || typing(event.target))return;event.preventDefault();send({type:'tio-canvas:context',x:event.clientX,y:event.clientY});});
+window.addEventListener('auxclick',event=>{if(!fullscreen && event.button===1)event.preventDefault();});
+window.addEventListener('keydown',event=>{
+  if(fullscreen){if(event.key==='Escape')send({type:'tio-canvas:preview-escape'});return;}
+  if(event.shiftKey && event.code==='Digit1' && !event.metaKey && !event.ctrlKey && !event.altKey && !typing(event.target)){event.preventDefault();if(!event.repeat)send({type:'tio-canvas:fit-all'});}
+  if(event.shiftKey && event.code==='Digit2' && !event.metaKey && !event.ctrlKey && !event.altKey && !typing(event.target)){event.preventDefault();if(!event.repeat)send({type:'tio-canvas:fit-selection'});}
+  const arrangeAction=arrangeShortcut(event);
+  if(arrangeAction && canArrange && !typing(event.target)){event.preventDefault();if(!event.repeat)send({type:'tio-canvas:arrange',action:arrangeAction});return;}
+  const layerAction=layerShortcut(event);
+  if(layerAction && !typing(event.target)){event.preventDefault();send({type:'tio-canvas:layer',action:layerAction});}
+  const direction=historyShortcut(event);
+  if(direction && !typing(event.target)){event.preventDefault();send({type:'tio-canvas:history',direction});}
+  if(event.code==='Space' && !typing(event.target)){event.preventDefault();space=true;send({type:'tio-canvas:space',down:true});}
+  if((event.metaKey || event.ctrlKey) && !event.altKey && event.key.toLowerCase()==='d' && !typing(event.target)) {
+    event.preventDefault();if(!event.repeat)send({type:'tio-canvas:duplicate'});
+  }
+  if(['Backspace','Delete'].includes(event.key) && !typing(event.target)) {
+    event.preventDefault();if(!event.repeat)send({type:'tio-canvas:delete'});
+  }
+});
+window.addEventListener('keyup',event=>{if(fullscreen)return;if(event.code==='Space'){space=false;send({type:'tio-canvas:space',down:false});}});
+const touchPreview=createTouchPreview(()=>active && !space && !panning,contact=>send({type:'tio-canvas:contact',...contact}));
+window.addEventListener('message',event=>{
+  if(event.source!==parent || event.origin!==location.origin)return;
+  if(event.data?.type==='tio-canvas:input'){
+    fullscreen=event.data.fullscreen===true;
+    canArrange=event.data.canArrange===true;
+    if(fullscreen){space=false;panning=false;}
+    active=event.data.active===true;touchPreview.configure(!fullscreen && event.data.touch===true,active);return;
+  }
+  if(event.data?.type!=='tio-canvas:visibility')return;
+  const visible=event.data.visible===true;
+  document.documentElement.dataset.canvasVisible=String(visible);
+  window.dispatchEvent(new CustomEvent('canvasvisibilitychange',{detail:{visible}}));
+});
+
+// A single active screen keeps native wheel scrolling. Inactive screens pan
+// the workspace; modified wheel gestures (including trackpad pinch) always zoom.
+window.addEventListener('wheel',event=>{
+  if(fullscreen || (active && !event.metaKey && !event.ctrlKey && !space))return;
+  event.preventDefault();
+  // Embedded pages can scroll in their own wheel listeners even after the
+  // browser's default is cancelled. Canvas gestures must not reach them.
+  event.stopImmediatePropagation();
+  if(event.metaKey || event.ctrlKey)send({type:'tio-canvas:zoom',x:event.clientX,y:event.clientY,delta:event.deltaY,mode:event.deltaMode,ctrlKey:event.ctrlKey && !event.metaKey});
+  else send({type:'tio-canvas:wheel-pan',dx:event.deltaX,dy:event.deltaY,mode:event.deltaMode});
+},{passive:false,capture:true});
+
+// Report usable document readiness without waiting for images or weather.
+async function reportReady(){
+  document.documentElement.getBoundingClientRect();await document.fonts.ready;
+  send({type:'tio-canvas:ready'});
+}
+if(document.readyState==='loading')document.addEventListener('DOMContentLoaded',reportReady,{once:true});else void reportReady();