@divlet/web 0.0.0-stage → 0.0.1

package/dist/lib/chat.js

@@ -0,0 +1,156 @@
+// The conversation with Pi: your requests and its answers, oldest first, in the Agent pane. Changes made to the
+// project (by anyone) are the History pane's business, not this one's.
+import { $, el, icon, ago, button } from './util.js';
+import { store, toast, descriptor, selectArtboards, selectNodes, loadModel, cachedModel } from './store.js';
+import { reveal } from './canvas.js';
+import * as sidebar from './sidebar.js';
+
+const CHAT = new Set(['ask', 'reply']);
+export const isChat = change => CHAT.has(change.kind);
+
+export const list = el('div', 'chat-list');
+list.setAttribute('role', 'log');
+list.setAttribute('aria-label', 'Conversation with Pi');
+const expanded = new Set();
+const unreadBadge = $('#agent-count');
+let unread = 0;
+let focusSeq = null;
+let followLatest = true;
+// An explicitly focused message stays in view through the layout changes that follow (the pane finishing its open/resize,
+// the composer settling) until the reader scrolls it away; it is the one place `scrollTop` is re-applied after a resize.
+let pinnedSeq = null, pinnedTop = 0;
+let readWidth = 0, readHeight = 0;
+const atBottom = () => list.scrollHeight - list.scrollTop - list.clientHeight < 40;
+const scrollToLatest = () => { if (followLatest && list.clientHeight) list.scrollTop = list.scrollHeight; };
+const revealPinned = () => {
+  const target = pinnedSeq === null ? null : [...list.querySelectorAll('[data-seq]')].find(node => node.dataset.seq === String(pinnedSeq));
+  if (!target || !list.clientHeight) return false;
+  followLatest = false;
+  target.scrollIntoView({ block: 'nearest' });
+  followLatest = atBottom();
+  pinnedTop = list.scrollTop;
+  return true;
+};
+list.addEventListener('scroll', () => {
+  // A queued scroll from the old layout is not a reader leaving the bottom after the composer/status resizes.
+  if (list.clientHeight && list.clientWidth === readWidth && list.clientHeight === readHeight) {
+    followLatest = atBottom();
+    if (pinnedSeq !== null && Math.abs(list.scrollTop - pinnedTop) > 1) pinnedSeq = null;
+  }
+}, { passive: true });
+new ResizeObserver(() => {
+  readWidth = list.clientWidth; readHeight = list.clientHeight;
+  if (pinnedSeq !== null && revealPinned()) return;
+  scrollToLatest();
+}).observe(list);
+
+/** Plain text with `code`, **bold** and line breaks, built as DOM (never as HTML). */
+function richText(text) {
+  const box = el('div', 'rich');
+  for (const [index, line] of text.split('\n').entries()) {
+    if (index) box.append(document.createElement('br'));
+    for (const part of line.split(/(`[^`\n]+`|\*\*[^*\n]+\*\*)/)) {
+      if (!part) continue;
+      if (part.startsWith('`') && part.endsWith('`') && part.length > 2) box.append(el('code', '', part.slice(1, -1)));
+      else if (part.startsWith('**') && part.endsWith('**') && part.length > 4) box.append(el('b', '', part.slice(2, -2)));
+      else box.append(document.createTextNode(part));
+    }
+  }
+  return box;
+}
+
+function contextLabel(context) {
+  if (!context) return '';
+  if (context.nodes) {
+    const doc = descriptor(context.nodes.documentId);
+    return `${doc?.name || context.nodes.documentId} › ${context.nodes.ids.slice(0, 2).map(id => `#${id}`).join(', ')}${context.nodes.ids.length > 2 ? ` +${context.nodes.ids.length - 2}` : ''}`;
+  }
+  if (context.documents?.length) return context.documents.length === 1 ? context.documents[0].name : `${context.documents.length} artboards`;
+  return 'whole project';
+}
+
+async function focusContext(context) {
+  const ids = (context.documents || []).map(doc => doc.id).filter(id => descriptor(id));
+  if (!ids.length) return;
+  if (context.nodes && descriptor(context.nodes.documentId)) {
+    const model = cachedModel(context.nodes.documentId) || await loadModel(context.nodes.documentId).catch(() => null);
+    const alive = context.nodes.ids.filter(id => model?.nodes[id]);
+    if (alive.length) { selectNodes(context.nodes.documentId, alive, { reveal: true }); reveal(context.nodes.documentId); return; }
+  }
+  selectArtboards(ids);
+  reveal(ids[0]);
+}
+
+function bubble(change) {
+  const mine = change.kind === 'ask';
+  const line = el('div', `bubble ${mine ? 'from-user' : 'from-agent'}`);
+  line.dataset.seq = String(change.seq);
+  const head = el('div', 'bubble-head');
+  head.append(icon(mine ? 'user' : 'sparkle'), el('b', '', mine ? 'You' : 'Pi'));
+  if (mine && change.context) {
+    const label = contextLabel(change.context);
+    const about = el('button', 'bubble-about', label);
+    about.type = 'button';
+    // One line in the panel (it ellipsizes when the sidebar is narrow); the whole label is on hover.
+    about.title = label;
+    about.dataset.tip = `Select what this request was about · ${label}`;
+    about.disabled = !(change.context.documents || []).some(doc => descriptor(doc.id));
+    about.addEventListener('click', () => focusContext(change.context));
+    head.append(about);
+  }
+  const when = el('time', 'when', ago(change.at));
+  when.dateTime = change.at;
+  when.title = new Date(change.at).toLocaleString();
+  head.append(el('span', 'grow'), when);
+  if (!mine) {
+    const copy = button('copy', 'Copy this reply', async () => {
+      try { await navigator.clipboard.writeText(change.message || change.summary || ''); toast('Reply copied'); }
+      catch { toast('The clipboard is not available here'); }
+    }, 'mini bubble-copy');
+    head.append(copy);
+  }
+  const body = richText(change.message || change.summary || '');
+  const long = (change.message || '').length > 280 || (change.message || '').split('\n').length > 6;
+  const open = expanded.has(change.seq);
+  body.classList.toggle('clamped', long && !open);
+  line.append(head, body);
+  if (long) {
+    const more = el('button', 'link-button more', open ? 'Show less' : 'Show more');
+    more.type = 'button';
+    more.addEventListener('click', () => { if (expanded.has(change.seq)) expanded.delete(change.seq); else expanded.add(change.seq); render(); });
+    line.append(more);
+  }
+  return line;
+}
+
+function paintUnread() {
+  unreadBadge.hidden = !unread;
+  unreadBadge.textContent = String(Math.min(unread, 99));
+}
+
+/** A new request or answer arrived: unseen answers are counted on the Agent tab until it is opened. */
+export function note(change) {
+  if (!isChat(change)) return;
+  if (change.kind === 'ask') { followLatest = true; pinnedSeq = null; }
+  if (change.kind === 'reply' && !sidebar.isOpen('agent')) { unread++; paintUnread(); }
+  render();
+}
+
+export function render() {
+  const top = list.scrollTop;
+  const messages = store.recent.filter(isChat);
+  list.replaceChildren(...(messages.length ? messages.map(bubble) : [el('div', 'quiet', 'No conversation yet. Ask the agent to change the layout below; its answers appear here, and every edit it makes is in History.')]));
+  if (sidebar.isOpen('agent')) { unread = 0; paintUnread(); }
+  if (focusSeq !== null) {
+    const target = [...list.querySelectorAll('[data-seq]')].find(node => node.dataset.seq === String(focusSeq));
+    focusSeq = null;
+    if (target) { pinnedSeq = Number(target.dataset.seq); revealPinned(); target.classList.add('flash'); setTimeout(() => target.classList.remove('flash'), 1200); return; }
+  }
+  if (followLatest) scrollToLatest();
+  else if (list.clientHeight) list.scrollTop = top;
+}
+
+/** Scroll to one message once the pane shows it. */
+export function focus(seq) { focusSeq = seq; render(); }
+
+setInterval(() => { if (sidebar.isOpen('agent')) for (const node of list.querySelectorAll('time.when')) node.textContent = ago(node.dateTime); }, 15000);

package/dist/lib/clip.js

@@ -0,0 +1,231 @@
+import { store, documents, descriptor, edit, toast, cachedModel, loadModel, selectNodes, parentOf, canContain, apiUrl, request } from './store.js';
+import * as canvas from './canvas.js';
+import { duplicateArtboards } from './artboards.js';
+
+/* Copy, cut and paste of elements and artboards, plus images from the clipboard or a drop.
+   The system clipboard receives clean HTML; the board keeps a lossless copy (names, metadata,
+   IDs as hints) and uses it whenever the clipboard still holds what the board put there. */
+
+const STRUCTURE = new Set('div section main article header footer nav aside form figure fieldset details dialog ul ol menu dl table tbody thead tfoot tr hgroup search blockquote'.split(' '));
+const VOID = new Set('area br col hr img input source track wbr'.split(' '));
+const INLINE = new Set('a abbr b bdi bdo br cite code data dfn em i img input kbd label mark q s samp small span strong sub sup time u var wbr'.split(' '));
+let clip = null;
+
+export const hasClip = () => !!clip;
+export const clipKind = () => clip?.kind ?? null;
+
+const escapeText = value => value.replaceAll('&', '&amp;').replaceAll('<', '&lt;').replaceAll('>', '&gt;');
+const escapeAttribute = value => escapeText(value).replaceAll('"', '&quot;');
+
+/** A node and its subtree as an insert spec that keeps names, classes, styles and metadata. */
+export function toSpec(model, id, top = true) {
+  const node = model.nodes[id];
+  if (node.type === 'text') return top ? { tag: 'span', text: node.content } : node.content;
+  const spec = { tag: node.tag, id: node.id };
+  if (node.className) spec.className = node.className;
+  for (const key of ['attrs', 'style', 'metadata']) if (Object.keys(node[key] || {}).length) spec[key] = structuredClone(node[key]);
+  if (node.children.length) spec.children = node.children.map(child => toSpec(model, child, false));
+  return spec;
+}
+
+/** Readable HTML of nodes without divlet bookkeeping (what other apps receive). */
+export function htmlOf(model, ids) {
+  const open = node => {
+    const attrs = Object.entries(node.attrs).map(([key, value]) => `${key}="${escapeAttribute(value)}"`);
+    if (node.className) attrs.push(`class="${escapeAttribute(node.className)}"`);
+    const style = Object.entries(node.style).map(([key, value]) => `${key}: ${value}`).join('; ');
+    if (style) attrs.push(`style="${escapeAttribute(style)}"`);
+    return `<${node.tag}${attrs.length ? ' ' + attrs.join(' ') : ''}>`;
+  };
+  const inline = id => {
+    const node = model.nodes[id];
+    if (node.type === 'text') return escapeText(node.content);
+    if (VOID.has(node.tag)) return open(node);
+    return `${open(node)}${node.children.map(inline).join('')}</${node.tag}>`;
+  };
+  const block = (id, depth) => {
+    const node = model.nodes[id];
+    const pad = '  '.repeat(depth);
+    if (node.type === 'text') return node.content.trim() ? pad + escapeText(node.content) : '';
+    const inlineOnly = node.children.every(child => model.nodes[child].type === 'text' || INLINE.has(model.nodes[child].tag));
+    if (VOID.has(node.tag) || !node.children.length || inlineOnly) return pad + inline(id);
+    return `${pad}${open(node)}\n${node.children.map(child => block(child, depth + 1)).filter(Boolean).join('\n')}\n${pad}</${node.tag}>`;
+  };
+  return ids.map(id => block(id, 0)).join('\n') + '\n';
+}
+
+/** Selected node IDs without the root and without nodes whose ancestor is also selected, in tree order. */
+function topLevel(model, ids) {
+  const chosen = new Set(ids.filter(id => model.nodes[id] && id !== model.rootId));
+  const parents = new Map();
+  for (const node of Object.values(model.nodes)) if (node.type === 'element') for (const child of node.children) parents.set(child, node.id);
+  const order = [];
+  const walk = id => { order.push(id); const node = model.nodes[id]; if (node.type === 'element') node.children.forEach(walk); };
+  walk(model.rootId);
+  return order.filter(id => {
+    if (!chosen.has(id)) return false;
+    for (let p = parents.get(id); p; p = parents.get(p)) if (chosen.has(p)) return false;
+    return true;
+  });
+}
+
+async function writeSystem(text, event) {
+  if (event?.clipboardData) {
+    event.clipboardData.setData('text/plain', text);
+    event.clipboardData.setData('text/html', text);
+    event.preventDefault();
+    return true;
+  }
+  try {
+    // A key forwarded from a preview frame leaves the board document unfocused.
+    if (!document.hasFocus()) document.querySelector('#viewport')?.focus({ preventScroll: true });
+    await navigator.clipboard.writeText(text);
+    return true;
+  } catch { return false; }
+}
+
+/**
+ * Copy (or cut) the selection. With a DOM copy/cut `event` the clipboard is written synchronously
+ * when the model is cached; returns false when there is nothing to copy so the browser default runs.
+ */
+export function copySelection({ event, cut = false } = {}) {
+  const node = store.node?.nodeIds.length ? store.node : null;
+  if (node) {
+    const model = cachedModel(node.documentId);
+    if (!model) {
+      // The newest model is still on its way (e.g. right after a paste): finish once it is here.
+      event?.preventDefault();
+      loadModel(node.documentId).then(() => copySelection({ cut })).catch(error => toast(error.message));
+      return true;
+    }
+    const ids = topLevel(model, node.nodeIds);
+    if (!ids.length) { toast('The page root cannot be copied. Copy the artboard instead.'); event?.preventDefault(); return true; }
+    const text = htmlOf(model, ids);
+    clip = { kind: 'nodes', documentId: node.documentId, specs: ids.map(id => toSpec(model, id)), text, count: ids.length, preferInternal: false };
+    const current = clip;
+    const declared = (store.state?.project?.resources?.length ?? 0) > 0;
+    if (declared) { event?.preventDefault(); current.preferInternal = true; }
+    const written = declared ? request(`api/export/${encodeURIComponent(node.documentId)}?${ids.map(id => `nodes=${encodeURIComponent(id)}`).join('&')}&version=${model.version}&projectVersion=${store.state.project.version}`).then(async result => {
+      if (clip !== current) return false;
+      current.text = result.html;
+      return writeSystem(result.html);
+    }) : writeSystem(text, event);
+    Promise.resolve(written).then(ok => { if (clip === current) current.preferInternal = !ok; }).catch(error => toast(error.message));
+    const what = ids.length === 1 ? `<${model.nodes[ids[0]].tag ?? 'text'}>` : `${ids.length} elements`;
+    if (cut) {
+      const expectedRender = descriptor(node.documentId)?.render;
+      const remove = () => {
+        if (clip !== current) return;
+        edit(node.documentId, declared ? latest => {
+          if (latest.version !== model.version) throw new Error('The copied frame changed. Copy it again before cutting.');
+          return { type: 'remove', ids };
+        } : { type: 'remove', ids }, { label: `cut ${what}`, ...(declared ? { expectedRender } : {}) }).then(() => {
+          selectNodes(node.documentId, []);
+          toast(`Cut ${what} — paste with ${navigator.platform.includes('Mac') ? '⌘' : 'Ctrl'} V`);
+        }).catch(() => {});
+      };
+      if (declared) Promise.resolve(written).then(remove).catch(() => {});
+      else remove();
+    } else toast(`Copied ${what}`);
+    return true;
+  }
+  if (store.selected.size) {
+    const ids = [...store.selected];
+    clip = { kind: 'artboards', ids, text: null, count: ids.length, preferInternal: true };
+    event?.preventDefault();
+    toast(ids.length === 1 ? `Copied “${descriptor(ids[0])?.name || ids[0]}”` : `Copied ${ids.length} artboards`);
+    return true;
+  }
+  return false;
+}
+
+/** Where pasted content goes: inside a selected container, after a selected element, or at the end of the page. */
+async function target() {
+  const node = store.node?.nodeIds.length ? store.node : null;
+  const documentId = node?.documentId ?? (store.selected.size === 1 ? [...store.selected][0] : null);
+  if (!documentId) return null;
+  const model = cachedModel(documentId) || await loadModel(documentId);
+  let anchor = node ? model.nodes[node.nodeIds.at(-1)] : null;
+  if (anchor?.type === 'text') anchor = parentOf(model, anchor.id);
+  if (!anchor || anchor.id === model.rootId) return { documentId, place: { parentId: model.rootId } };
+  if (canContain(anchor) && STRUCTURE.has(anchor.tag)) return { documentId, place: { parentId: anchor.id } };
+  return { documentId, place: { after: anchor.id } };
+}
+
+const looksLikeHtml = text => /^\s*<([a-z][\w-]*)[\s>/][\s\S]*>\s*$/i.test(text) && /<\/[a-z][\w-]*\s*>|\/>\s*$|<(img|br|hr|input)\b/i.test(text);
+
+async function insert(op, label, group) {
+  const spot = await target();
+  if (!spot) { toast('Select an artboard or an element to paste into'); return null; }
+  const result = await edit(spot.documentId, { type: 'insert', ...spot.place, ...op }, { label, group }).catch(() => null);
+  if (!result?.ids?.length) return null;
+  if (store.mode !== 'select') canvas.setMode('select');
+  selectNodes(spot.documentId, result.ids, { reveal: true });
+  canvas.flashNodes(spot.documentId, result.render, result.ids);
+  return result;
+}
+
+/**
+ * Paste. `text` comes from a paste event (or is undefined for a key forwarded by a preview frame,
+ * where only the board's own clipboard is available). `files` may carry images.
+ */
+export async function paste({ text, files } = {}) {
+  const images = [...(files || [])].filter(file => file.type.startsWith('image/'));
+  if (images.length) return addImages(images);
+  const normalize = value => value?.replace(/\r\n?/g, '\n');
+  const own = clip && (clip.preferInternal || text === undefined || normalize(text) === normalize(clip.text));
+  if (own && clip.kind === 'artboards') {
+    const alive = clip.ids.filter(id => descriptor(id));
+    if (!alive.length) { toast('The copied artboards no longer exist'); return null; }
+    return duplicateArtboards(alive);
+  }
+  if (own && clip.kind === 'nodes') return insert({ spec: clip.specs }, clip.count > 1 ? `paste ${clip.count} elements` : 'paste element');
+  const value = (text ?? '').trim();
+  if (!value) { toast('The clipboard is empty — copy elements with Ctrl C first'); return null; }
+  if (looksLikeHtml(value)) return insert({ html: value }, 'paste HTML');
+  const paragraphs = value.split(/\n\s*\n/).map(part => part.trim()).filter(Boolean).slice(0, 50);
+  return insert({ spec: paragraphs.map(content => ({ preset: 'text', text: content })) }, paragraphs.length > 1 ? `paste ${paragraphs.length} paragraphs` : 'paste text');
+}
+
+/* ---- images --------------------------------------------------------------- */
+async function upload(file, documentId, group) {
+  const name = file.name && /\.[a-z0-9]+$/i.test(file.name) ? file.name : `pasted.${(file.type.split('/')[1] || 'png').replace('svg+xml', 'svg').replace('jpeg', 'jpg')}`;
+  const response = await fetch(apiUrl(`api/assets?name=${encodeURIComponent(name)}&documentId=${encodeURIComponent(documentId)}&group=${encodeURIComponent(group)}`), { method: 'POST', headers: { 'Content-Type': file.type || 'image/png' }, body: file });
+  const body = await response.json().catch(() => ({}));
+  if (!response.ok) throw new Error(body.message || `Upload failed (${response.status})`);
+  return { ...body, alt: name.replace(/\.[a-z0-9]+$/i, '').replace(/[-_]+/g, ' ') };
+}
+
+/** Store images in the project and add an <img> for each at the paste/drop target. */
+export async function addImages(files, documentId) {
+  if (documentId && !(store.selected.size === 1 && store.selected.has(documentId))) {
+    const { selectArtboards } = await import('./store.js');
+    selectArtboards([documentId]);
+  }
+  const spot = await target();
+  if (!spot) { toast('Select an artboard first, or drop the image onto one'); return null; }
+  try {
+    const saved = [], group = `images:${crypto.randomUUID()}`;
+    for (const file of files.slice(0, 12)) saved.push(await upload(file, spot.documentId, group));
+    toast(saved.length === 1 ? `Added ${saved[0].file}` : `Added ${saved.length} project images`);
+    return insert({ spec: saved.map(item => ({ tag: 'img', className: 'block max-w-full h-auto', attrs: { src: item.path, alt: item.alt } })) }, saved.length > 1 ? `add ${saved.length} images` : 'add image', group);
+  } catch (error) { toast(error.message); return null; }
+}
+
+/** Text selected where the shortcut happens (e.g. in History) keeps the browser's own copy. */
+const copiesText = event => {
+  const selection = getSelection();
+  if (!selection || selection.isCollapsed || !selection.toString()) return false;
+  const anchor = selection.anchorNode instanceof Element ? selection.anchorNode : selection.anchorNode?.parentElement;
+  return !!anchor && event.target instanceof Node && event.target.contains(anchor) && event.target !== document.querySelector('#viewport');
+};
+
+export const isEditable = target => target instanceof HTMLInputElement || target instanceof HTMLTextAreaElement || target instanceof HTMLSelectElement || !!target?.isContentEditable;
+
+document.addEventListener('copy', event => { if (!isEditable(event.target) && !store.expanded && !copiesText(event)) copySelection({ event }); });
+document.addEventListener('cut', event => { if (!isEditable(event.target) && !store.expanded && !copiesText(event)) copySelection({ event, cut: true }); });
+document.addEventListener('paste', event => {
+  if (isEditable(event.target) || store.expanded || !documents().length) return;
+  event.preventDefault();
+  paste({ text: event.clipboardData?.getData('text/plain') ?? '', files: event.clipboardData?.files });
+});

package/dist/lib/crumbbar.js

@@ -0,0 +1,56 @@
+// The path of the selection, always bottom centre between the left column and the toolbar. When that span is narrow the path
+// wraps onto more lines; on a phone the sidebars simply sit on top of it.
+import { $, el, uiScale } from './util.js';
+import { store, on } from './store.js';
+import { pathInto, pathKey } from './crumbs.js';
+
+const bar = $('#crumbs');
+const track = el('div', 'crumbs-track');
+bar.append(track);
+const tabs = $('#side-tabs');
+const dock = $('#dock');
+const MIN_WIDTH = 90;
+let shown = '';
+
+function context() {
+  const ids = [...store.selected];
+  if (!ids.length) return null;
+  const node = store.node;
+  if (node?.nodeIds.length && ids.length === 1 && node.documentId === ids[0]) return { ids, nodes: { documentId: node.documentId, nodeIds: [...node.nodeIds] } };
+  return { ids };
+}
+
+/** Fit the bar between the tabs and the toolbar; with no room at all it hides rather than overlap them. */
+function place() {
+  if (bar.hidden) return;
+  // The tabs live in the sidebar footer; compare viewport rectangles, not offsets from different parents.
+  const a = tabs.getBoundingClientRect(), b = dock.getBoundingClientRect(), scale = uiScale();
+  const sameRow = Math.abs(a.bottom - b.bottom) / scale < 24;
+  const left = (sameRow ? a.right / scale : 0) + 10;
+  const width = b.left / scale - 10 - left;
+  bar.style.left = `${left}px`;
+  bar.style.width = `${Math.max(0, width)}px`;
+  const minimum = track.querySelector('.root-entry') ? track.scrollWidth + 2 : MIN_WIDTH;
+  bar.classList.toggle('cramped', width < minimum);
+}
+
+function paint() {
+  const ctx = store.expanded ? null : context();
+  if (!ctx) { bar.hidden = true; shown = ''; track.replaceChildren(); return; }
+  const key = pathKey(ctx);
+  bar.hidden = false;
+  if (key !== shown || !track.childElementCount) {
+    shown = key;
+    const focused = track.contains(document.activeElement);
+    track.replaceChildren();
+    pathInto(track, ctx, { all: true, repaint: () => { shown = ''; paint(); } });
+    if (focused) (track.querySelector('.crumb.current') ?? track.querySelector('.crumb'))?.focus({ preventScroll: true });
+  }
+  place();
+}
+
+for (const name of ['selection', 'model', 'state', 'expanded', 'sidebar']) on(name, paint);
+addEventListener('resize', place);
+new ResizeObserver(place).observe(dock);
+new ResizeObserver(place).observe(tabs);
+paint();

package/dist/lib/crumbs.js

@@ -0,0 +1,63 @@
+// The path of what is selected — artboard › container › … › element — as buttons that re-point the
+// selection. Shown in the bottom-centre bar (crumbbar.js); the Agent composer states its own one-line scope.
+import { el, icon } from './util.js';
+import { cachedModel, loadModel, descriptor, ancestorsOf, selectNodes, selectArtboards } from './store.js';
+import { openMenu } from './menu.js';
+import { selectRoot } from './actions.js';
+
+/**
+ * Fill the bottom path for `ctx` ({ ids, nodes? }). A selected artboard collapses to its root-entry icon;
+ * selecting that root opens the path. Container crumbs select ancestors; the artboard crumb folds it again.
+ * `after()` runs after activation; `repaint()` is called when element data arrives late.
+ */
+export function pathInto(container, ctx, { after, repaint, all = false } = {}) {
+  const model = ctx.nodes ? cachedModel(ctx.nodes.documentId) : null;
+  if (ctx.nodes && !model) loadModel(ctx.nodes.documentId).then(() => repaint?.()).catch(() => {});
+  const crumb = (label, run, tip, className = '') => {
+    const item = el('button', `crumb ${className}`.trim(), label);
+    item.type = 'button';
+    if (tip) item.dataset.tip = tip;
+    item.addEventListener('click', () => { run(); after?.(); });
+    return item;
+  };
+  const sep = () => el('i', 'crumb-sep');
+  if (!ctx.nodes) {
+    if (ctx.ids.length === 1) {
+      const root = crumb('', () => selectRoot(ctx.ids[0]), `Select root element · ${descriptor(ctx.ids[0])?.name || ctx.ids[0]}`, 'root-entry');
+      root.setAttribute('aria-label', 'Select root element');
+      root.append(icon('inspect'));
+      container.append(root);
+    } else container.append(crumb(`${ctx.ids.length} artboards`, () => {}, 'These artboards', 'current'));
+    return;
+  }
+  const { documentId, nodeIds } = ctx.nodes;
+  const home = crumb('', () => selectArtboards([documentId]), 'Select the whole artboard', 'home');
+  home.append(icon('artboard'), el('span', '', descriptor(documentId)?.name || documentId));
+  container.append(home);
+  const first = nodeIds[0];
+  const path = model ? ancestorsOf(model, first) : [];
+  const labelOf = (id, last) => {
+    const node = model?.nodes[id];
+    if (!node) return `#${id}`;
+    const tag = node.type === 'text' ? 'text' : node.type === 'ref' ? 'instance' : node.tag;
+    return last ? `${tag}#${id}` : (node.metadata?.name || tag);
+  };
+  // A long path keeps the artboard, an ellipsis that lists the rest, and the last three — unless the bar scrolls (`all`).
+  const shown = !all && path.length > 3 ? path.slice(-3) : path;
+  if (!all && path.length > 3) {
+    const hidden = path.slice(0, -3);
+    const more = crumb('…', () => openMenu(hidden.map(id => ({ label: labelOf(id), run: () => selectNodes(documentId, [id], { reveal: true }) })), { anchor: more, label: 'Containers' }), hidden.map(id => labelOf(id)).join(' › '));
+    container.append(sep(), more);
+  }
+  for (const id of shown) container.append(sep(), crumb(labelOf(id), () => selectNodes(documentId, [id], { reveal: true }), `Select this container · #${id}`));
+  container.append(sep(), crumb(labelOf(first, true), () => {}, 'The selected element', 'current'));
+  if (nodeIds.length > 1) container.append(el('span', 'ask-more', `+${nodeIds.length - 1}`));
+}
+
+/** What the path is made from, so a bar only repaints when it would look different. */
+export function pathKey(ctx) {
+  if (!ctx) return '';
+  const model = ctx.nodes ? cachedModel(ctx.nodes.documentId) : null;
+  const names = ctx.nodes && model ? [...ctx.nodes.nodeIds, ...ancestorsOf(model, ctx.nodes.nodeIds[0])].map(id => model.nodes[id]?.metadata?.name ?? model.nodes[id]?.tag) : null;
+  return JSON.stringify([ctx, !!model, names, (ctx.nodes ? [ctx.nodes.documentId] : ctx.ids).map(id => descriptor(id)?.name)]);
+}