@tio-canvas/canvas 0.0.0-stage → 0.1.1

package/client/menu-position.js

@@ -0,0 +1,36 @@
+const clamp = (value, min, max) => Math.max(min, Math.min(value, max));
+
+// Search the free vertical lanes beside fixed chrome, nearest the field first.
+export function menuPosition({ anchor, width, height, viewport, margin, gap, obstacles, aboveOnly = false }) {
+  const left = margin, right = viewport.width - margin;
+  const top = margin, bottom = viewport.height - margin;
+  width = Math.min(width, right - left);
+  const idealX = anchor.left + (anchor.width - width) / 2;
+  const xs = [idealX, left, right - width];
+  for (const rect of obstacles) xs.push(rect.left - gap - width, rect.right + gap);
+  let best;
+  for (const x of new Set(xs.map(value => clamp(value, left, right - width)))) {
+    let lanes = [[top, bottom]];
+    for (const rect of obstacles) {
+      if (x + width <= rect.left - gap || x >= rect.right + gap) continue;
+      lanes = lanes.flatMap(([start, end]) => {
+        if (rect.bottom + gap <= start || rect.top - gap >= end) return [[start, end]];
+        return [[start, Math.min(end, rect.top - gap)], [Math.max(start, rect.bottom + gap), end]].filter(([a, b]) => b > a);
+      });
+    }
+    for (const side of aboveOnly ? ['above'] : ['below', 'above']) {
+      for (const [start, end] of lanes) {
+        const min = side === 'below' ? Math.max(start, anchor.bottom + gap) : start;
+        const max = side === 'above' ? Math.min(end, anchor.top - gap) : end;
+        const available = max - min;
+        if (available <= 0) continue;
+        const h = Math.min(height, available);
+        const y = side === 'below' ? min : max - h;
+        const idealY = side === 'below' ? anchor.bottom + gap : anchor.top - gap - height;
+        const score = (height - h) * 10000 + Math.abs(x - idealX) + Math.abs(y - idealY) + (side === 'above' && !aboveOnly ? 0.5 : 0);
+        if (!best || score < best.score) best = { x, y, height: h, score };
+      }
+    }
+  }
+  return best;
+}

package/client/onboarding.js

@@ -0,0 +1,302 @@
+// First-run tour for the canvas. It watches the page and never drives it: each
+// step ends when the user does the thing the step is about, so there is no
+// Back, and no Next except where there is nothing to do (a tip, or the finish).
+// While it is up, every press and key outside what is highlighted is swallowed.
+const KEY = 'tio-canvas:onboarding';
+const PAD = 6, GAP = 12, MARGIN = 12, RADIUS = 14;
+const $ = selector => document.querySelector(selector);
+const visible = element => !!element && element.checkVisibility();
+
+const inspectorReady = () => visible($('#inspector'));
+const selectScreen = {
+  targets: () => [$('#layers')],
+  title: 'Select one screen',
+  body: 'Click a single screen in this list to edit its size.',
+};
+
+// pan: the target lives on the canvas, so it can end up off screen; the tour pans to it.
+const steps = [
+  {
+    targets: () => [$('#add')],
+    title: 'Add a page',
+    body: 'Click here to open the page list.',
+  },
+  {
+    targets: () => [$('#page-options .page-option')],
+    deny: '.page-checkbox-target', modal: true,
+    title: 'Pick a page',
+    body: 'Click a page to add it to the canvas.',
+  },
+  {
+    // The screen that was just added, clipped to what is on screen.
+    targets: () => [$('.screen[data-selected]') || $('.screen')],
+    clip: true,
+    title: 'Select a screen',
+    body: 'Click a screen to select it. Only the selected screen reacts to your clicks, scrolling and keys.',
+    action: 'Next',
+  },
+  {
+    targets: () => [$('#inspector button.select-field')],
+    ready: inspectorReady, fallback: selectScreen, pan: true,
+    title: 'Change the size',
+    body: 'Open Preset and pick a device. The screen resizes to match.',
+    action: 'Next',
+  },
+  {
+    targets: () => [$('#width')?.closest('label'), $('#height')?.closest('label')],
+    ready: inspectorReady, fallback: selectScreen, pan: true,
+    title: 'Or set your own',
+    body: 'Choose Custom in Preset to type an exact width and height.',
+    action: 'Next',
+  },
+  {
+    targets: () => [$('.screen[data-selected] .screen-fullscreen')],
+    ready: () => visible($('.screen[data-selected] .screen-fullscreen')), fallback: selectScreen, pan: true,
+    title: 'Preview full screen',
+    body: 'Open the screen at its real size, without the canvas around it.',
+  },
+  {
+    // The preview's menu is closed until pressed; then the way back is what is pointed at.
+    targets: () => [$('#fullscreen-back')],
+    ready: () => visible($('#fullscreen-back')),
+    fallback: {
+      targets: () => [$('#fullscreen-toggle')],
+      title: 'Back to canvas',
+      body: 'Open this menu to return to the canvas.',
+      action: 'Finish',
+    },
+    title: 'Back to canvas',
+    body: 'Choose Back to canvas to leave the preview.',
+    action: 'Finish',
+  },
+];
+const LAST = steps.length - 1;
+const PICK = 1, SELECT = 2, PRESET = 3, FULLSCREEN = 5, BACK = 6;
+
+let dim, card, titleEl, bodyEl, dotsEl, skipEl, actionEl;
+let active = false, paused = false, index = 0, shownKey = '', frame = 0, motionTimer = 0, placed = false;
+let countBefore = 0, activeTargets = [], activeDeny = '', offSince = 0, lastPan = 0;
+
+function build() {
+  dim = document.createElement('div');
+  dim.className = 'onboarding-dim';
+  dim.setAttribute('aria-hidden', 'true');
+  dim.popover = 'manual';
+  card = document.createElement('div');
+  card.className = 'onboarding-card';
+  card.popover = 'manual';
+  card.setAttribute('role', 'group');
+  card.setAttribute('aria-label', 'Canvas tour');
+  card.innerHTML = '<div class="onboarding-copy" aria-live="polite"><h2></h2><p></p></div>'
+    + '<div class="onboarding-footer"><div class="onboarding-dots" role="img"></div><div class="onboarding-actions">'
+    + '<button type="button" class="secondary-button" data-tooltip="Skip the tour" data-shortcut="esc">Skip</button>'
+    + '<button type="button" class="primary-button" hidden></button></div></div>';
+  titleEl = card.querySelector('h2');
+  bodyEl = card.querySelector('p');
+  dotsEl = card.querySelector('.onboarding-dots');
+  skipEl = card.querySelector('.secondary-button');
+  actionEl = card.querySelector('.primary-button');
+  for (let n = 0; n < steps.length; n++) dotsEl.append(document.createElement('span'));
+  skipEl.addEventListener('click', end);
+  actionEl.addEventListener('click', () => (index === LAST ? end() : go(index + 1)));
+  document.body.append(dim, card);
+}
+
+function remember() { try { localStorage.setItem(KEY, 'seen'); } catch { /* storage blocked: the tour may show again */ } }
+function seen() { try { return localStorage.getItem(KEY) !== null; } catch { return true; } }
+
+function bounds(elements) {
+  const rects = elements.filter(visible).map(element => element.getBoundingClientRect());
+  if (!rects.length) return null;
+  const left = Math.min(...rects.map(r => r.left)), top = Math.min(...rects.map(r => r.top));
+  const right = Math.max(...rects.map(r => r.right)), bottom = Math.max(...rects.map(r => r.bottom));
+  return { left, top, right, bottom, width: right - left, height: bottom - top };
+}
+
+// A full-screen rectangle with a rounded hole. Every hole has the same path
+// structure, so the browser can interpolate from one step's hole to the next.
+function holePath(r) {
+  const W = innerWidth, H = innerHeight, x = r.left - PAD, y = r.top - PAD, w = r.width + 2 * PAD, h = r.height + 2 * PAD, k = Math.min(RADIUS, w / 2, h / 2);
+  return `path(evenodd, "M0 0H${W}V${H}H0Z M${x + k} ${y}H${x + w - k}A${k} ${k} 0 0 1 ${x + w} ${y + k}V${y + h - k}A${k} ${k} 0 0 1 ${x + w - k} ${y + h}H${x + k}A${k} ${k} 0 0 1 ${x} ${y + h - k}V${y + k}A${k} ${k} 0 0 1 ${x + k} ${y}Z")`;
+}
+
+function render(step, key) {
+  titleEl.textContent = step.title;
+  bodyEl.textContent = step.body;
+  skipEl.hidden = index === LAST;
+  actionEl.hidden = !step.action;
+  actionEl.textContent = step.action || '';
+  [...dotsEl.children].forEach((dot, n) => { dot.dataset.on = String(n === index); });
+  dotsEl.setAttribute('aria-label', `Step ${index + 1} of ${steps.length}`);
+  if (placed) {
+    dim.dataset.motion = ''; card.dataset.motion = '';
+    clearTimeout(motionTimer);
+    motionTimer = setTimeout(() => { delete dim.dataset.motion; delete card.dataset.motion; }, 300);
+  }
+  card.classList.remove('is-swapping'); void card.offsetWidth; card.classList.add('is-swapping');
+  shownKey = key;
+}
+
+// Top-layer elements stack in the order they were shown, so lift the tour above
+// a dialog that opened after it.
+function raise() {
+  for (const element of [dim, card]) { if (element.matches(':popover-open')) element.hidePopover(); element.showPopover(); }
+}
+// A modal dialog makes everything outside its own subtree inert, the card
+// included. Inside the dialog it stays pressable, and Skip stays reachable.
+function dock(modal) {
+  const home = modal ? $('#add-pages') : document.body;
+  if (home && card.parentElement !== home) { home.append(card); raise(); }
+}
+
+// Pan the canvas by the least distance that brings an on-canvas target fully into view.
+function reveal(rect) {
+  const left = visible($('#layers')) ? $('#layers').getBoundingClientRect().right + 16 : 16;
+  const right = innerWidth - 16, top = 150, bottom = innerHeight - 88;
+  let dx = 0, dy = 0;
+  if (rect.left < left) dx = left - rect.left; else if (rect.right > right) dx = right - rect.right;
+  if (rect.bottom > bottom) dy = bottom - rect.bottom; else if (rect.top < top) dy = top - rect.top;
+  if (!dx && !dy) { offSince = 0; return; }
+  const now = performance.now();
+  if (!offSince) offSince = now;
+  // Let any camera move that is already running (a refit after a resize) finish first.
+  if (now - offSince < 300 || now - lastPan < 700) return;
+  lastPan = now;
+  document.dispatchEvent(new CustomEvent('tio-canvas:pan-by', { detail: { dx, dy } }));
+}
+
+function layout() {
+  const step = steps[index];
+  const resolved = step.ready && !step.ready() ? step.fallback : step;
+  const key = `${index}:${resolved === step ? 'main' : 'fallback'}`;
+  dock(!!step.modal && !!$('#add-pages')?.open);
+  if (key !== shownKey) render(resolved, key);
+  activeTargets = resolved.targets();
+  activeDeny = resolved.deny || '';
+  const rect = bounds(activeTargets);
+  if (rect && resolved.clip) {
+    // A screen can be bigger than the window: point at the part that is visible.
+    const left = visible($('#layers')) ? Math.max(0, $('#layers').getBoundingClientRect().right) : 0;
+    rect.left = Math.max(rect.left, left + PAD); rect.top = Math.max(rect.top, PAD);
+    rect.right = Math.min(rect.right, innerWidth - PAD); rect.bottom = Math.min(rect.bottom, innerHeight - PAD);
+    rect.width = rect.right - rect.left; rect.height = rect.bottom - rect.top;
+  }
+  if (!rect) { dim.dataset.on = 'false'; card.dataset.on = 'false'; return; }
+  if (resolved.pan) reveal(rect);
+  dim.dataset.on = 'true'; card.dataset.on = 'true';
+  dim.style.clipPath = holePath(rect);
+  const w = card.offsetWidth, h = card.offsetHeight;
+  const padded = { top: rect.top - PAD, bottom: rect.bottom + PAD, cx: (rect.left + rect.right) / 2 };
+  const above = padded.top - GAP - h >= MARGIN;
+  const x = Math.max(MARGIN, Math.min(padded.cx - w / 2, innerWidth - w - MARGIN));
+  const y = above ? padded.top - GAP - h : Math.min(padded.bottom + GAP, innerHeight - h - MARGIN);
+  card.style.translate = `${x}px ${y}px`;
+  placed = true;
+}
+
+function loop() {
+  frame = 0;
+  if (!active || paused) return;
+  layout();
+  frame = requestAnimationFrame(loop);
+}
+function run() { if (!frame && active && !paused) frame = requestAnimationFrame(loop); }
+
+function hideUi() {
+  cancelAnimationFrame(frame); frame = 0;
+  dim.dataset.on = 'false'; card.dataset.on = 'false';
+  activeTargets = [];
+}
+function go(next) { index = next; shownKey = ''; offSince = 0; run(); }
+function start() {
+  if (!dim) build();
+  active = true; paused = false; placed = false; shownKey = ''; index = 0;
+  dock(false);
+  raise();
+  dim.style.transition = 'none'; card.style.transition = 'none';
+  layout();
+  void dim.offsetWidth;
+  dim.style.transition = ''; card.style.transition = '';
+  run();
+}
+function end() {
+  if (!active) return;
+  active = false; paused = false;
+  hideUi();
+  setTimeout(() => { if (!active) for (const element of [dim, card]) if (element.matches(':popover-open')) element.hidePopover(); }, 250);
+}
+
+function syncDialogs() {
+  if (!active) return;
+  const adding = $('#add-pages')?.open, shortcuts = $('#shortcuts')?.open;
+  if (shortcuts) {
+    if (!paused) { paused = true; hideUi(); }
+    return;
+  }
+  if (adding) {
+    if (index === 0) { countBefore = Number($('#screens-count')?.textContent) || 0; go(PICK); raise(); }
+    else if (index !== 1 && !paused) { paused = true; hideUi(); }
+    return;
+  }
+  paused = false;
+  setTimeout(() => {
+    if (!active) return;
+    if (index === PICK) go((Number($('#screens-count')?.textContent) || 0) > countBefore ? SELECT : 0);
+    else run();
+  }, 0);
+}
+
+// Everything outside what is highlighted is dead while the tour is up.
+const POINTER = ['pointerdown', 'pointerup', 'mousedown', 'mouseup', 'click', 'dblclick', 'auxclick', 'contextmenu', 'wheel', 'dragstart'];
+function blocking() { return active && !paused && dim?.dataset.on === 'true'; }
+function allowed(event) {
+  const target = event.target instanceof Element ? event.target : null;
+  if (!target) return true;
+  if (card.contains(target) || target.closest('.canvas-tooltip, .icon-options:popover-open')) return true;
+  if (activeDeny && target.closest(activeDeny)) return false;
+  return activeTargets.some(element => element?.contains(target));
+}
+function guard(event) {
+  if (!blocking() || allowed(event)) return;
+  event.preventDefault();
+  event.stopImmediatePropagation();
+}
+function guardKey(event) {
+  if (!blocking()) return;
+  if (event.key === 'Escape') {
+    if (document.body.hasAttribute('data-fullscreen')) return;
+    // Dialogs and menus close themselves; otherwise Escape skips the tour.
+    if ($('dialog[open], .icon-options:popover-open, #screen-context:popover-open')) return;
+    event.preventDefault(); event.stopImmediatePropagation(); end();
+    return;
+  }
+  if (event.key === 'Tab' || allowed(event)) return;
+  event.preventDefault();
+  event.stopImmediatePropagation();
+}
+
+function init() {
+  for (const dialog of [$('#add-pages'), $('#shortcuts')]) {
+    if (dialog) new MutationObserver(syncDialogs).observe(dialog, { attributes: true, attributeFilter: ['open'] });
+  }
+  for (const type of POINTER) window.addEventListener(type, guard, { capture: true, passive: false });
+  window.addEventListener('keydown', guardKey, true);
+  document.addEventListener('change', event => { if (active && index === PRESET && event.target.id === 'preset') go(PRESET + 1); }, true);
+  // Entering the preview moves the tour on; leaving it ends the tour.
+  new MutationObserver(() => {
+    if (!active) return;
+    const inPreview = document.body.hasAttribute('data-fullscreen');
+    if (inPreview && index === FULLSCREEN) go(BACK);
+    else if (!inPreview && index === BACK) end();
+  }).observe(document.body, { attributes: true, attributeFilter: ['data-fullscreen'] });
+  $('#onboarding-open')?.addEventListener('click', () => { end(); start(); });
+  addEventListener('resize', run);
+  if (!seen()) {
+    // Not on a phone-sized screen, where the canvas is blocked: the tour waits for a visit that can use it.
+    setTimeout(() => {
+      if (document.documentElement.hasAttribute('data-device-blocked') || !visible($('#add'))) return;
+      remember(); start();
+    }, 900);
+  }
+}
+init();

package/client/page-picker.js

@@ -0,0 +1,76 @@
+import { createRangeSelection } from './range-selection.js';
+
+// Pages are grouped by `kind` in an accordion; `groups` is [{id,label}] in display order.
+export function createPagePicker({dialog,trigger,sources,groups,count,onOpen,onAdd}) {
+  const list=dialog.querySelector('#page-options'),submit=dialog.querySelector('#add-pages-submit'),error=dialog.querySelector('#page-picker-error');
+  let selection=new Set();
+  // Display order, so a shift-range follows what is on screen rather than the registry.
+  const ordered=groups.flatMap(group=>sources.filter(source=>source.kind===group.id));
+  const closedGroups=new Set();
+  function update(ids){
+    selection=new Set(ids);
+    for(const row of list.querySelectorAll('.page-option')){
+      row.dataset.checked=String(selection.has(row.dataset.rangeId));
+      row.querySelector('[role="checkbox"]').setAttribute('aria-checked',row.dataset.checked);
+    }
+    dialog.querySelector('footer').hidden=!selection.size;
+    submit.hidden=!selection.size;submit.disabled=!selection.size;submit.textContent=selection.size?`Add ${selection.size} ${selection.size===1?'page':'pages'}`:'Add pages';
+    dialog.querySelector('#add-pages-select-all').disabled=selection.size===sources.length;
+    dialog.querySelector('#add-pages-unselect-all').disabled=!selection.size;
+  }
+  const ranges=createRangeSelection({root:list,items:()=>ordered.map(source=>source.id),selected:()=>[...selection],onChange:update,toggleClick:true,toggleDrag:true,startTarget:'.page-checkbox-target'});
+  function close(){ranges.reset();dialog.close();}
+  function add(ids){
+    if(onAdd(ids)!==false)close();
+    else error.textContent='Cannot add these pages. The canvas is full. Remove screens or select fewer pages.';
+  }
+  trigger.addEventListener('click',()=>{
+    onOpen();ranges.reset();list.replaceChildren();error.textContent='';
+    for(const group of groups){
+      const members=ordered.filter(source=>source.kind===group.id);
+      if(!members.length)continue;
+      const section=document.createElement('section');section.className='picker-group';
+      const toggle=document.createElement('button');toggle.type='button';toggle.className='picker-group-toggle';
+      const panelId=`picker-group-${group.id}`;toggle.setAttribute('aria-controls',panelId);
+      toggle.innerHTML='<span class="picker-group-label"></span><span class="picker-group-count"></span><svg class="chevron" viewBox="0 0 12 12" aria-hidden="true"><path d="m3 4.5 3 3 3-3"/></svg>';
+      toggle.querySelector('.picker-group-label').textContent=group.label;
+      toggle.querySelector('.picker-group-count').textContent=String(members.length);
+      const panel=document.createElement('div');panel.className='picker-group-panel';panel.id=panelId;
+      const items=document.createElement('div');items.className='picker-group-list';panel.append(items);
+      const setOpen=open=>{section.dataset.open=String(open);toggle.setAttribute('aria-expanded',String(open));panel.inert=!open;};
+      setOpen(!closedGroups.has(group.id));
+      toggle.addEventListener('click',()=>{const open=section.dataset.open!=='true';if(open)closedGroups.delete(group.id);else closedGroups.add(group.id);setOpen(open);});
+      section.append(toggle,panel);list.append(section);
+      for(const source of members)items.append(buildRow(source));
+    }
+    update([]);dialog.showModal();
+  });
+  function buildRow(source){
+      const row=document.createElement('div');row.className='page-option';row.dataset.rangeId=source.id;
+      const checkbox=document.createElement('button');checkbox.type='button';checkbox.className='page-checkbox-target';checkbox.setAttribute('role','checkbox');checkbox.setAttribute('aria-label',`Select ${source.title}`);
+      const mark=document.createElement('span');mark.className='page-checkbox';mark.setAttribute('aria-hidden','true');checkbox.append(mark);
+      const action=document.createElement('button');action.type='button';action.className='page-option-add';action.setAttribute('aria-label',`Add ${source.title}`);
+      row.addEventListener('click',event=>{if(!event.target.closest('.page-checkbox-target'))add([source.id]);});
+      const thumbnail=document.createElement('span');thumbnail.className='page-thumbnail';thumbnail.setAttribute('aria-hidden','true');
+      const image=document.createElement('img');image.src=`/canvas/thumbnails/${encodeURIComponent(source.id)}.webp`;image.alt='';image.loading='lazy';image.decoding='async';image.draggable=false;
+      image.addEventListener('error',()=>image.remove(),{once:true});thumbnail.append(image);
+      const label=document.createElement('span');label.className='page-option-label';label.textContent=source.title;
+      const description=document.createElement('small');description.textContent=source.description;label.append(description);action.append(thumbnail,label);row.append(checkbox,action);
+      const number=count(source.id);
+      if(number){const pill=document.createElement('span');pill.className='page-pill';pill.textContent=`${number} on canvas`;action.append(pill);}
+      return row;
+  }
+  dialog.querySelector('#add-pages-close').onclick=close;
+  dialog.querySelector('#add-pages-select-all').onclick=()=>{ranges.reset();update(sources.map(source=>source.id));};
+  dialog.querySelector('#add-pages-unselect-all').onclick=()=>{ranges.reset();update([]);};
+  dialog.addEventListener('close',()=>{ranges.reset();trigger.focus({preventScroll:true});});
+  dialog.addEventListener('click',event=>{
+    if(event.target!==dialog)return;
+    const rect=dialog.getBoundingClientRect();
+    if(event.clientX<rect.left||event.clientX>rect.right||event.clientY<rect.top||event.clientY>rect.bottom)close();
+  });
+  submit.addEventListener('click',()=>{
+    if(!selection.size)return;
+    add([...selection]);
+  });
+}

package/client/platform.js

@@ -0,0 +1,16 @@
+// Which keyboard the shortcut labels are written for. It follows the visitor's
+// system until they choose, and the choice is remembered on this device.
+const KEY = 'tio-canvas:shortcut-platform';
+const detected = () => /Mac|iPhone|iPad/.test(navigator.userAgentData?.platform || navigator.platform || '') ? 'mac' : 'win';
+let current;
+try { current = localStorage.getItem(KEY); } catch { /* storage blocked: the system's keyboard is used */ }
+if (current !== 'mac' && current !== 'win') current = detected();
+
+export const platform = () => current;
+export function setPlatform(value) {
+  if (value !== 'mac' && value !== 'win') return;
+  try { localStorage.setItem(KEY, value); } catch { /* not remembered */ }
+  if (value === current) return;
+  current = value;
+  window.dispatchEvent(new CustomEvent('tio-canvas:platform'));
+}

package/client/range-selection.js

@@ -0,0 +1,54 @@
+// Shared range selection for page rows and the Layers drawer. The caller owns
+// selection state; this helper owns only the pointer gesture and its anchor.
+export function createRangeSelection({root,items,selected,onChange,toggleClick=false,shiftRange=true,toggleModifiers=false,toggleDrag=false,startTarget=null}) {
+  let anchor=null,gesture=null,frame=0;
+  function range(first,last){const ids=items(),a=ids.indexOf(first),b=ids.indexOf(last);return a<0||b<0?[]:ids.slice(Math.min(a,b),Math.max(a,b)+1);}
+  function apply(id){
+    const ids=range(gesture.start,id),next=new Set(gesture.base);
+    for(const value of ids){if(gesture.remove)next.delete(value);else next.add(value);}
+    onChange([...next]);
+  }
+  function scroll(){
+    if(!gesture)return;
+    const rect=root.getBoundingClientRect(),delta=gesture.y<rect.top+24?-10:gesture.y>rect.bottom-24?10:0;
+    if(delta && gesture.moved){root.scrollTop+=delta;hit();}
+    frame=requestAnimationFrame(scroll);
+  }
+  function hit(){
+    const rect=root.getBoundingClientRect();
+    const row=document.elementFromPoint(Math.max(rect.left+1,Math.min(rect.right-1,gesture.x)),Math.max(rect.top+1,Math.min(rect.bottom-1,gesture.y)))?.closest('[data-range-id]');
+    if(row && root.contains(row))apply(row.dataset.rangeId);
+  }
+  function cancel(){const old=gesture;gesture=null;cancelAnimationFrame(frame);if(old && root.hasPointerCapture(old.pointer))root.releasePointerCapture(old.pointer);}
+  function select(id,event){
+    if(event.shiftKey&&shiftRange&&anchor){
+      onChange([...new Set([...selected(),...range(anchor,id)])]);
+    }else{
+      anchor=id;
+      const toggling=toggleClick||(toggleModifiers&&(event.metaKey||event.ctrlKey))||(!shiftRange&&event.shiftKey);
+      const next=new Set(toggling?selected():[]);
+      if(toggling&&next.has(id))next.delete(id);else next.add(id);
+      onChange([...next]);
+    }
+  }
+  root.addEventListener('pointerdown',event=>{
+    const row=event.target.closest('[data-range-id]');
+    if(event.button!==0 || !row || (startTarget&&!event.target.closest(startTarget)) || event.target.closest('[contenteditable],svg,[data-reorder]'))return;
+    event.preventDefault();const id=row.dataset.rangeId,base=toggleDrag||event.shiftKey||(toggleModifiers&&(event.metaKey||event.ctrlKey))?selected():[];
+    const start=event.shiftKey&&shiftRange&&anchor?anchor:id;
+    const remove=toggleDrag&&base.includes(id)&&!(event.shiftKey&&shiftRange&&anchor);
+    select(id,event);
+    gesture={moved:false,pointer:event.pointerId,start,base,remove,x:event.clientX,y:event.clientY};
+    (startTarget?row.querySelector(startTarget):row).focus({preventScroll:true});frame=requestAnimationFrame(scroll);
+  });
+  root.addEventListener('pointermove',event=>{if(gesture && gesture.pointer===event.pointerId){if(!gesture.moved && Math.hypot(event.clientX-gesture.x,event.clientY-gesture.y)<4)return;gesture.moved=true;root.setPointerCapture(event.pointerId);gesture.x=event.clientX;gesture.y=event.clientY;hit();}});
+  root.addEventListener('pointerup',()=>{cancel();});root.addEventListener('pointercancel',cancel);root.addEventListener('lostpointercapture',cancel);
+  window.addEventListener('keydown',event=>{if(event.key==='Escape')cancel();});
+  window.addEventListener('blur',cancel);document.addEventListener('visibilitychange',()=>{if(document.hidden)cancel();});
+  root.addEventListener('click',event=>{
+    const row=event.target.closest('[data-range-id]');if(!row || event.detail!==0 || (startTarget&&!event.target.closest(startTarget)))return;
+    const id=row.dataset.rangeId;
+    select(id,event);
+  });
+  return {cancel,select,reset(){cancel();anchor=null;}};
+}

package/client/registry.js

@@ -0,0 +1,31 @@
+// What the canvas knows about screens, whatever project it runs in. The project
+// owns the list of screens (project.js, served from its own config file); this
+// file owns the shape a screen must have and the device presets.
+// The page picker groups by kind and shows the description under each title, so
+// every page, production or prototype, must carry both. Fail loudly when one does not.
+export const screenKinds = { production: 'Production', prototype: 'Prototypes' };
+export function validateScreens(screens) {
+  for (const screen of screens) {
+    if (!Object.hasOwn(screenKinds, screen.kind)) throw new Error(`Canvas screen "${screen.id}" needs kind: "production" or "prototype".`);
+    if (typeof screen.description !== 'string' || !screen.description.trim()) throw new Error(`Canvas screen "${screen.id}" needs a short description.`);
+  }
+}
+export const presets = {
+  custom: { label: 'Custom' },
+  laptop: { label: 'Laptop', group: 'Desktop', device: 'laptop', width: 1440, height: 900 },
+  'macbook-air-13': { label: 'MacBook Air 13-inch', group: 'Desktop', device: 'laptop', width: 1470, height: 956 },
+  'macbook-pro-14': { label: 'MacBook Pro 14-inch', group: 'Desktop', device: 'laptop', width: 1512, height: 982 },
+  desktop: { label: 'Desktop', group: 'Desktop', device: 'desktop', width: 1920, height: 1080 },
+  'desktop-qhd': { label: 'Desktop QHD', group: 'Desktop', device: 'desktop', width: 2560, height: 1440 },
+  'iphone-se': { label: 'iPhone SE', group: 'Mobile', device: 'phone', touch: true, width: 375, height: 667 },
+  'iphone-16': { label: 'iPhone 16', group: 'Mobile', device: 'phone', touch: true, width: 393, height: 852 },
+  'iphone-16-pro-max': { label: 'iPhone 16 Pro Max', group: 'Mobile', device: 'phone', touch: true, width: 440, height: 956 },
+  'pixel-9': { label: 'Pixel 9', group: 'Mobile', device: 'phone', touch: true, width: 412, height: 915 },
+  'galaxy-s24': { label: 'Galaxy S24', group: 'Mobile', device: 'phone', touch: true, width: 360, height: 780 },
+  'ipad-mini': { label: 'iPad mini', group: 'Tablet', device: 'tablet', touch: true, width: 744, height: 1133 },
+  'ipad-air': { label: 'iPad Air', group: 'Tablet', device: 'tablet', touch: true, width: 820, height: 1180 },
+  'ipad-pro-11': { label: 'iPad Pro 11-inch', group: 'Tablet', device: 'tablet', touch: true, width: 834, height: 1194 },
+  'ipad-pro-13': { label: 'iPad Pro 13-inch', group: 'Tablet', device: 'tablet', touch: true, width: 1032, height: 1376 },
+  'galaxy-z-fold-6-cover': { label: 'Galaxy Z Fold 6 (cover)', group: 'Foldable', device: 'phone', touch: true, width: 344, height: 748 },
+  'galaxy-z-fold-6-open': { label: 'Galaxy Z Fold 6 (open)', group: 'Foldable', device: 'phone', touch: true, width: 673, height: 841 },
+};

package/client/screen-loader.js

@@ -0,0 +1,67 @@
+// Iframe lifecycle. Document readiness excludes images and
+// other nonessential requests; the old painted screen survives refresh failure.
+// The development server adds the bridge to the pages it serves. A production
+// page is served untouched, so the canvas adds the bridge itself. These are
+// same-origin documents, which is what makes that possible.
+function injectBridge(frame) {
+  const doc=frame.contentDocument;
+  if(!doc?.body || [...doc.scripts].some(script=>script.src.endsWith('/canvas/bridge.js')))return;
+  const script=doc.createElement('script');script.type='module';script.src='/canvas/bridge.js';doc.body.append(script);
+}
+export function createScreenLoader({onReady,onError,timeout=15000}) {
+  const documents=new WeakMap();
+  function forget(frame) { if(frame?.contentWindow)documents.delete(frame.contentWindow); }
+  function cancel(entry) {
+    clearTimeout(entry.refreshTimer);
+    if(entry.pending){forget(entry.pending);entry.pending.remove();entry.pending=null;}
+    entry.refresh.disabled=false;entry.element.removeAttribute('aria-busy');
+  }
+  function dispose(entry) { cancel(entry);forget(entry.iframe); }
+  async function finish(record) {
+    const {entry,frame}=record;
+    if(record.settling || !frame.isConnected)return;
+    record.settling=true;
+    try {
+      // Layout requests the fonts actually used by this document. Unlike load,
+      // fonts.ready does not wait for an image or an unrelated fetch to finish.
+      frame.contentDocument?.documentElement.getBoundingClientRect();
+      await frame.contentDocument?.fonts?.ready;
+      await new Promise(resolve=>requestAnimationFrame(()=>requestAnimationFrame(resolve)));
+      if(!frame.isConnected || !entry.element.isConnected)return;
+      if(entry.pending===frame){
+        const previous=entry.iframe,focused=document.activeElement===previous;
+        clearTimeout(entry.refreshTimer);entry.pending=null;entry.iframe=frame;
+        forget(previous);previous?.remove();
+        delete frame.dataset.refreshPending;frame.inert=false;frame.removeAttribute('aria-hidden');frame.title=entry.model.title;
+        entry.refresh.disabled=false;entry.element.removeAttribute('aria-busy');
+        if(focused)frame.focus({preventScroll:true});
+      }
+      if(entry.iframe===frame)onReady(entry);
+    }finally{record.settling=false;}
+  }
+  function mount(entry,replacing=false) {
+    if(entry.pending)return;
+    const frame=document.createElement('iframe'),url=new URL(entry.model.src,location.origin);
+    if(url.origin!==location.origin)throw new Error('Canvas screens must use local pages.');
+    url.searchParams.set('canvasScreen','1');frame.title=entry.model.title;
+    // Native lazy loading keeps host loading independent from embedded media.
+    // An invisible refresh replacement must load eagerly, not wait to be seen.
+    frame.loading=replacing?'eager':'lazy';
+    if(replacing && entry.iframe){
+      entry.pending=frame;frame.dataset.refreshPending='';frame.inert=true;frame.setAttribute('aria-hidden','true');
+      entry.refresh.disabled=true;entry.element.setAttribute('aria-busy','true');
+      entry.refreshTimer=setTimeout(()=>{
+        if(entry.pending!==frame)return;
+        cancel(entry);onError(entry,'Refresh timed out. The previous screen is still shown. Try again.');
+      },timeout);
+    }else entry.iframe=frame;
+    const record={entry,frame,settling:false};
+    // Fallback for a document that cannot run the bridge. A working bridge
+    // signals readiness earlier, at DOMContentLoaded plus font readiness.
+    frame.addEventListener('load',()=>{injectBridge(frame);void finish(record);});
+    frame.src=url.href;entry.element.append(frame);
+    documents.set(frame.contentWindow,record);
+  }
+  function ready(source) { const record=documents.get(source);if(record)void finish(record); }
+  return {mount,ready,dispose};
+}

package/client/screens.js

@@ -0,0 +1,7 @@
+// The canvas reads its screens from here. `project.js` is not a file of the
+// package: the development server serves the project's own config in its place
+// (and a build writes it), so the list of pages always belongs to the project.
+import { screens, storageKey } from './project.js';
+import { screenKinds, presets, validateScreens } from './registry.js';
+validateScreens(screens);
+export { screens, screenKinds, presets, storageKey };