@divlet/web 0.0.0-stage → 0.0.2

package/dist/lib/ask.js

@@ -0,0 +1,350 @@
+import { $, el, icon, button, keys } from './util.js';
+import { openMenu } from './menu.js';
+import { store, on, emit, post, toast, descriptor } from './store.js';
+import * as sidebar from './sidebar.js';
+import * as chat from './chat.js';
+
+/* The Agent tab: the conversation with Pi and the box to write to it. A request goes to the running Pi
+   session together with what is selected; the status line shows what Pi is doing and can stop it; Pi's
+   answers land in the conversation and its edits in History. */
+
+const panel = $('#agent');
+const RECENT_KEY = 'divlet:asks';
+let sending = false;
+let recall = -1;
+let draft = '';
+let watchdog = 0;
+let returnFocus = null;
+
+export const available = () => !!store.state?.agent?.connected;
+export const isOpen = () => sidebar.isOpen('agent');
+const agent = () => store.state?.agent || {};
+
+const recent = () => { try { const list = JSON.parse(localStorage.getItem(RECENT_KEY) || '[]'); return Array.isArray(list) ? list.filter(item => typeof item === 'string') : []; } catch { return []; } };
+const remember = text => { try { localStorage.setItem(RECENT_KEY, JSON.stringify([text, ...recent().filter(item => item !== text)].slice(0, 20))); } catch {} };
+
+/* ---- composer ------------------------------------------------------------- */
+const input = el('textarea', 'ask-input');
+input.rows = 1;
+input.placeholder = 'Ask the agent to change the layout…';
+input.spellcheck = true;
+input.dataset.key = 'ask';
+input.setAttribute('aria-label', 'Request for the agent');
+const hint = el('span', 'ask-hint');
+const stopButton = button('stop', 'Stop the agent', () => stop(), 'mini ask-stop');
+const send = el('button', 'cta ask-send');
+send.type = 'button';
+send.id = 'ask-send';
+send.append(el('span', '', 'Send'), icon('send'));
+send.addEventListener('click', () => submit());
+const status = el('div', 'agent-status');
+status.setAttribute('role', 'status');
+status.hidden = true;
+const statusText = el('span', 'agent-status-text');
+const statusTime = el('time', 'agent-status-time');
+status.append(el('span', 'spinner'), statusText, statusTime, stopButton);
+const foot = el('div', 'ask-foot');
+/* Two chips, no labels: the session that answers this board — model and thinking level — when the host can change them. An MCP
+   client can only answer prompts, so there the chips are simply absent; nothing here is guessed or stored in the project. */
+const sessionChips = el('div', 'agent-session');
+const settingsError = el('div', 'agent-settings-error');
+settingsError.hidden = true;
+const post_ = (path, body) => post(path, body).catch(error => {
+  // A refused change is reported where it was made, never as a silent no-op.
+  settingsError.hidden = false;
+  settingsError.textContent = error?.message || 'That setting could not be applied.';
+  setTimeout(() => { settingsError.hidden = true; }, 6000);
+  paintSession();
+  return null;
+});
+const chip = (label, tip, options, current, choose) => {
+  const node = el('button', 'agent-chip', label);
+  node.type = 'button';
+  node.dataset.tip = tip;
+  node.setAttribute('aria-label', tip);
+  node.addEventListener('click', () => {
+    openMenu(options.map(option => ({
+      label: option.label,
+      icon: option.id === current ? 'check' : undefined,
+      run: () => { if (option.id !== current) choose(option); },
+    })), { anchor: node, label: tip, className: 'menu-agent' });
+  });
+  return node;
+};
+function paintSession() {
+  const controls = agent().controls;
+  const chips = [];
+  if (controls?.model?.options?.length) {
+    const current = controls.model.value;
+    const option = controls.model.options.find(item => item.id === current);
+    chips.push(chip(option?.label || current, `Model · ${current}`, controls.model.options, current, item => post_('api/agent/settings', { model: item.id })));
+  }
+  if (controls?.thinking?.options?.length) {
+    const current = controls.thinking.value;
+    chips.push(chip(current, `Thinking level · ${current}`, controls.thinking.options.map(level => ({ id: level, label: level })), current, item => post_('api/agent/settings', { thinking: item.id })));
+  }
+  sessionChips.replaceChildren(...chips);
+  // The selectors replace the key hints rather than stacking under them; Send keeps the trailing bottom corner if they wrap.
+  sessionChips.hidden = chips.length === 0;
+  hint.hidden = chips.length > 0;
+}
+// One slot, two occupants: a host that can change the session shows the two selectors where the key hints would be; a host that
+// cannot (MCP) shows the hints. Pi users are assumed to know the shortcuts; the selectors carry their own tips.
+foot.append(sessionChips, hint, send);
+const scope = el('div', 'ask-scope');
+scope.id = 'ask-context';
+input.setAttribute('aria-describedby', scope.id);
+const suggest = el('div', 'ask-suggest');
+const composer = el('div', 'agent-composer');
+// Order is the reading order: what the request is about, the box, then send — with the session selectors in its footer.
+composer.append(scope, input, foot, settingsError);
+panel.append(chat.list, suggest, status, composer);
+
+const grow = () => { input.style.height = 'auto'; input.style.height = `${Math.min(input.scrollHeight + 2, 220)}px`; };
+
+function context() {
+  if (!store.selected.size) return null;
+  const ids = [...store.selected];
+  const nodes = store.node?.nodeIds.length && ids.length === 1 && store.node.documentId === ids[0] ? { documentId: ids[0], nodeIds: [...store.node.nodeIds] } : undefined;
+  return { ids, nodes };
+}
+
+/** What the agent will see with the next request, so nobody has to guess what "this" means. */
+function paintScope() {
+  const ids = [...store.selected];
+  const names = ids.map(id => descriptor(id)?.name || id);
+  const nodes = store.node?.documentId === ids[0] && ids.length === 1 ? store.node.nodeIds : [];
+  const value = el('span', 'ask-scope-v');
+  if (!ids.length) value.append(el('span', '', 'the whole board (nothing selected)'));
+  else if (ids.length > 1) value.append(el('span', '', `${ids.length} artboards`));
+  else {
+    // Only the frame name is truncated: it can be surprisingly long and the sidebar is narrow, while the selector after it
+    // tells the user what the request is about and must stay whole. The whole name stays available as a tooltip.
+    const frame = el('span', 'ask-scope-frame', names[0]);
+    frame.dataset.tip = names[0];
+    frame.title = names[0];
+    value.append(frame);
+    if (nodes.length) {
+      value.append(el('span', 'ask-scope-sep', '›'));
+      value.append(el('span', 'ask-scope-tail', nodes.length === 1 ? `#${nodes[0]}` : `${nodes.length} elements`));
+    }
+  }
+  scope.replaceChildren(el('span', 'ask-scope-k', 'About'), ' ', value);
+  scope.dataset.tip = 'Your next request goes to the agent together with this selection';
+}
+
+/** A few starting points while the conversation is empty; a click only fills the box, nothing is sent. */
+function paintSuggest() {
+  const empty = !store.recent.some(chat.isChat);
+  suggest.hidden = !empty || !available();
+  if (suggest.hidden) { suggest.replaceChildren(); return; }
+  const ids = [...store.selected];
+  const nodes = store.node?.documentId === ids[0] && ids.length === 1 ? store.node.nodeIds : [];
+  const ideas = nodes.length ? ['Tighten the spacing', 'Make it responsive', 'Improve contrast and readability']
+    : ids.length ? ['Make this page work on a phone', 'Add a footer', 'Describe what this page does']
+    : ['Create a landing page for ', 'Add a pricing section', 'Review the whole board for consistency'];
+  suggest.replaceChildren(...ideas.map(text => {
+    const chip = el('button', 'ask-idea', text.trim());
+    chip.type = 'button';
+    chip.addEventListener('click', () => { input.value = text; grow(); paintStatus(); input.focus(); input.setSelectionRange(input.value.length, input.value.length); });
+    return chip;
+  }));
+}
+
+function paintStatus() {
+  paintScope();
+  paintSuggest();
+  paintSession();
+  const state = agent();
+  send.querySelector('span').textContent = state.busy ? 'Queue' : 'Send';
+  send.dataset.tip = state.busy ? `The agent is working — this runs right after · ${keys('Enter')}` : `Send to the agent · ${keys('Enter')}`;
+  send.disabled = sending || !available() || !input.value.trim();
+  input.disabled = !available();
+  // The sidebar can be dragged narrow, so the texts follow its own width (sidebar.js measures it).
+  const tight = (document.documentElement.dataset.sidebar ?? 'wide') !== 'wide';
+  input.placeholder = !available() ? (tight ? 'Open from Pi (/divlet)' : 'Open this board from Pi (/divlet) to talk to it')
+    : tight ? 'Ask the agent…' : 'Ask the agent to change the layout…';
+  const keysHint = tight ? [`${keys('Enter')} send`] : [`${keys('Enter')} send`, `${keys('Shift+Enter')} new line`, '↑ previous'];
+  // Each key with its meaning is one unit: a narrow composer wraps between units, never inside one.
+  if (!available()) {
+    // Not connected: say so, and offer the exact command that connects this project in Pi.
+    const file = store.state?.project?.file;
+    const copy = button('copy', 'Copy the command that opens this project in Pi', async () => {
+      const command = `/divlet ${file || ''}`.trim();
+      try { await navigator.clipboard.writeText(command); toast(`Copied ${command} · paste it in the Pi terminal`); }
+      catch { toast(`Run ${command} in the Pi terminal`); }
+    }, 'mini ask-copy');
+    hint.replaceChildren(el('span', '', 'No agent is connected to this board'), copy);
+  } else hint.replaceChildren(...keysHint.map(text => el('span', 'hint-unit', text)));
+  // The plaque above the box already says what the agent is doing; the hint keeps the keys so nothing moves or repeats it.
+  hint.classList.toggle('busy', false);
+}
+
+/* Opened by a key typed in a preview frame: that frame keeps focus until typing pauses, so every
+   character arrives through one ordered channel (keys forwarded by the frame) and none is reordered. */
+let handOff = 0;
+function focusInput() {
+  clearTimeout(handOff);
+  handOff = 0;
+  if (!isOpen()) return;
+  input.focus();
+  input.setSelectionRange(input.value.length, input.value.length);
+}
+
+export function toggle(open = !isOpen(), { text, fromFrame = false } = {}) {
+  if (open && !available()) {
+    toast('No agent is connected to this board. Open it from Pi with /divlet, or connect an MCP client (divlet-mcp).');
+    return false;
+  }
+  if (open === isOpen()) { if (open) { if (text !== undefined) { input.value = text; grow(); } input.focus(); } return open; }
+  if (open) {
+    returnFocus = document.activeElement instanceof HTMLElement && !panel.contains(document.activeElement) ? document.activeElement : null;
+    if (text !== undefined) input.value = text;
+    sidebar.show('agent');
+    if (fromFrame) handOff = setTimeout(focusInput, 220);
+    else focusInput();
+  } else {
+    clearTimeout(handOff);
+    handOff = 0;
+    sidebar.close();
+    recall = -1;
+    if (returnFocus?.isConnected) returnFocus.focus({ preventScroll: true });
+    else $('#viewport').focus({ preventScroll: true });
+  }
+  return open;
+}
+
+/** The pane was shown or folded, by this module or by its tab. */
+on('sidebar', ({ open, tab }) => {
+  placeStatus();
+  const now = open && tab === 'agent';
+  if (now) { paintStatus(); grow(); chat.render(); }
+  emit('ask-open', now);
+});
+
+// A narrow sidebar changes what fits: the placeholder and the key hints are re-chosen, and the textarea re-fits its value.
+on('sidebar-width', () => { paintStatus(); grow(); });
+
+function armWatchdog(delay = 9000, waits = 6) {
+  clearTimeout(watchdog);
+  watchdog = setTimeout(() => {
+    if (agent().busy || !available()) return;
+    // A notice the user can still act on (Undo after a delete) keeps its window: this one waits its turn instead of replacing it.
+    if (waits > 0 && document.querySelector('#toast:not([hidden]) .toast-action')) { armWatchdog(2000, waits - 1); return; }
+    toast('Pi has not started yet. Check the Pi terminal — it needs a model and an API key.');
+  }, delay);
+}
+
+/** Keys typed in a preview frame while focus is still moving to the field: keep them as text. */
+export function typeAhead(key) {
+  if (!isOpen()) return false;
+  if (key === 'Backspace') input.value = input.value.slice(0, -1);
+  else input.value += key;
+  if (handOff) { clearTimeout(handOff); handOff = setTimeout(focusInput, 220); }
+  else focusInput();
+  grow();
+  paintStatus();
+  return true;
+}
+
+export async function submit(text = input.value) {
+  const request = text.trim();
+  if (!request || sending) return null;
+  sending = true;
+  paintStatus();
+  const ctx = context();
+  try {
+    const result = await post('api/ask', { text: request, ids: ctx?.ids ?? [], nodes: ctx?.nodes });
+    remember(request);
+    if (input.value.trim() === request) input.value = '';
+    draft = '';
+    grow();
+    if (result.queued) toast('Queued — Pi takes it right after the current task');
+    if (!result.queued) armWatchdog();
+    return result;
+  } catch (error) {
+    toast(error.message);
+    return null;
+  } finally {
+    sending = false;
+    paintStatus();
+  }
+}
+
+let stopping = false;
+export function stop() {
+  stopping = true;
+  paintChip();
+  paintStatus();
+  return post('api/agent/stop', {}).catch(error => { stopping = false; paintChip(); paintStatus(); toast(error.message); });
+}
+
+input.addEventListener('input', () => { grow(); paintStatus(); recall = -1; });
+input.addEventListener('keydown', event => {
+  event.stopPropagation();
+  if (event.key === 'Escape') { event.preventDefault(); toggle(false); }
+  else if (event.key === 'Enter' && !event.shiftKey && !event.isComposing) { event.preventDefault(); submit(); }
+  else if ((event.key === 'ArrowUp' || event.key === 'ArrowDown') && !event.shiftKey) {
+    const list = recent();
+    const atStart = input.selectionStart === 0 && input.selectionEnd === 0;
+    // Like a shell: ↑ on an empty or untouched field (or while already recalling) walks back through requests.
+    if (event.key === 'ArrowUp' && (atStart || !input.value || recall >= 0) && recall < list.length - 1) {
+      event.preventDefault();
+      if (recall < 0) draft = input.value;
+      recall++;
+      input.value = list[recall];
+    } else if (event.key === 'ArrowDown' && recall >= 0) {
+      event.preventDefault();
+      recall--;
+      input.value = recall < 0 ? draft : list[recall];
+    } else return;
+    grow();
+    paintStatus();
+  }
+});
+panel.addEventListener('keydown', event => { if (event.key === 'Escape') { event.stopPropagation(); toggle(false); } });
+
+/* ---- one activity plaque: above the composer, or above the tabs when the sidebar folds ---- */
+function placeStatus() {
+  const floating = !!agent().busy && !sidebar.isOpen();
+  const parent = floating ? $('#agent-status-dock') : panel;
+  if (status.parentElement === parent) return;
+  const focused = status.contains(document.activeElement) ? document.activeElement : null;
+  parent.insertBefore(status, floating ? null : composer);
+  if (focused instanceof HTMLElement && (floating || isOpen())) focused.focus({ preventScroll: true });
+}
+function elapsed() {
+  const since = agent().since ? Date.parse(agent().since) : NaN;
+  if (!Number.isFinite(since)) return '';
+  const seconds = Math.max(0, Math.round((Date.now() - since) / 1000));
+  return seconds < 60 ? `${seconds}s` : `${Math.floor(seconds / 60)}:${String(seconds % 60).padStart(2, '0')}`;
+}
+
+function paintChip() {
+  const state = agent();
+  if (!state.busy) stopping = false;
+  status.hidden = !state.busy;
+  stopButton.hidden = !state.busy;
+  placeStatus();
+  status.classList.toggle('stopping', stopping);
+  document.body.classList.toggle('agent-busy', !!state.busy);
+  $('#open-agent').setAttribute('aria-busy', String(!!state.busy));
+  if (!state.busy) return;
+  statusText.textContent = stopping ? 'Agent · stopping…' : `Agent · ${state.activity || 'working'}${state.queued ? ` · ${state.queued} queued` : ''}`;
+  statusTime.textContent = elapsed();
+}
+setInterval(() => { if (!status.hidden) statusTime.textContent = elapsed(); }, 1000);
+
+on('selection', () => { if (isOpen()) { paintScope(); paintSuggest(); } });
+on('change', () => { if (isOpen()) paintSuggest(); });
+on('state', () => {
+  if (agent().busy) clearTimeout(watchdog);
+  paintChip();
+  if (isOpen()) paintStatus();
+  emit('agent', agent());
+});
+on('change', change => {
+  if (change.kind !== 'reply') return;
+  if (sidebar.isOpen('agent')) return;
+  toast(`Pi: ${String(change.summary || '').replace(/\*\*|`/g, '')}`, { label: 'Read', run: () => { sidebar.show('agent'); chat.focus(change.seq); } });
+});

package/dist/lib/attrs.js

@@ -0,0 +1,144 @@
+// Attributes of an element: what it has, the important ones it lacks (one click to add), and
+// suggestions for names and values that fit its tag.
+import { el, icon } from './util.js';
+import { attachSuggest, filterLocal } from './suggest.js';
+
+const COMMON = [
+  ['id', 'name for links (#id) and labels'], ['title', 'tooltip text'], ['aria-label', 'name read by screen readers'],
+  ['role', 'what it is for assistive tech'], ['aria-hidden', 'hide from screen readers'], ['tabindex', 'keyboard focus order'],
+  ['hidden', 'not shown'], ['lang', 'language of the content'], ['dir', 'text direction'],
+];
+const BY_TAG = {
+  a: [['href', 'where the link goes'], ['target', '_blank opens a new tab'], ['rel', 'noopener for new tabs'], ['download', 'download instead of opening']],
+  img: [['src', 'image file, e.g. assets/photo.png'], ['alt', 'what the image shows'], ['loading', 'lazy: load when visible'], ['width', 'intrinsic width'], ['height', 'intrinsic height'], ['decoding', 'async decoding']],
+  button: [['type', 'button, submit or reset'], ['disabled', 'not clickable'], ['name', 'form field name'], ['value', 'value sent with the form']],
+  input: [['type', 'text, email, checkbox…'], ['name', 'form field name'], ['placeholder', 'hint inside the field'], ['value', 'initial value'], ['required', 'must be filled'], ['disabled', 'not editable'], ['autocomplete', 'browser autofill'], ['min', 'smallest value'], ['max', 'largest value']],
+  textarea: [['name', 'form field name'], ['placeholder', 'hint inside the field'], ['rows', 'visible lines'], ['required', 'must be filled']],
+  select: [['name', 'form field name'], ['required', 'must be chosen'], ['multiple', 'several choices']],
+  option: [['value', 'value sent with the form'], ['selected', 'chosen at start']],
+  label: [['for', 'id of its field']],
+  form: [['action', 'where it is sent'], ['method', 'get or post']],
+  video: [['src', 'video file'], ['controls', 'show player controls'], ['autoplay', 'start at once'], ['muted', 'no sound'], ['loop', 'repeat'], ['poster', 'image before playing'], ['playsinline', 'play inline on phones']],
+  audio: [['src', 'audio file'], ['controls', 'show player controls'], ['loop', 'repeat']],
+  time: [['datetime', 'machine-readable date']],
+  ol: [['start', 'first number'], ['reversed', 'count down']],
+  td: [['colspan', 'columns it spans'], ['rowspan', 'rows it spans']],
+  th: [['scope', 'col or row'], ['colspan', 'columns it spans']],
+  details: [['open', 'expanded at start']],
+  nav: [['aria-label', 'name of this navigation']],
+  section: [['aria-label', 'name of this region']],
+};
+const IMPORTANT = { a: ['href', 'target'], img: ['src', 'alt'], button: ['type', 'aria-label'], input: ['type', 'name', 'placeholder'], textarea: ['name', 'placeholder'], label: ['for'], form: ['action', 'method'], video: ['src', 'controls'], audio: ['src', 'controls'], nav: ['aria-label'], section: ['aria-label'] };
+const BOOLEAN = new Set(['hidden', 'disabled', 'required', 'multiple', 'selected', 'controls', 'autoplay', 'muted', 'loop', 'reversed', 'open', 'download', 'playsinline', 'checked', 'readonly']);
+const VALUES = {
+  target: ['_blank', '_self'], rel: ['noopener noreferrer', 'nofollow', 'me'], loading: ['lazy', 'eager'], decoding: ['async', 'sync', 'auto'],
+  method: ['get', 'post'], 'aria-hidden': ['true', 'false'], dir: ['ltr', 'rtl', 'auto'], scope: ['col', 'row'],
+  autocomplete: ['on', 'off', 'name', 'email', 'tel', 'current-password', 'new-password', 'street-address'],
+  role: ['button', 'link', 'navigation', 'banner', 'main', 'contentinfo', 'region', 'list', 'listitem', 'img', 'presentation', 'dialog', 'tab', 'tablist', 'tabpanel', 'status', 'alert'],
+};
+const TYPES = { button: ['button', 'submit', 'reset'], input: ['text', 'email', 'password', 'number', 'search', 'tel', 'url', 'checkbox', 'radio', 'date', 'time', 'file', 'range', 'color', 'hidden'] };
+
+const namesFor = tag => [...(BY_TAG[tag] || []), ...COMMON].filter(([name], index, all) => all.findIndex(([other]) => other === name) === index);
+const valuesFor = (tag, name) => (name === 'type' ? TYPES[tag] || [] : VALUES[name] || []);
+
+/**
+ * `node` is the element; `save(patch, label)` commits `{ attrs: { name: value | null } }`.
+ * Each row edits one attribute; the last row adds one (name, then value).
+ */
+export function attributesEditor(node, save) {
+  const box = el('div', 'rows attrs');
+  const attrs = node.attrs || {};
+  const known = new Map(namesFor(node.tag));
+  for (const [name, value] of Object.entries(attrs)) {
+    const line = el('div', 'kv');
+    const key = el('span', 'k', name);
+    key.dataset.tip = known.get(name) ? `${name} · ${known.get(name)}` : name;
+    const input = el('input', 'field mono');
+    input.type = 'text';
+    input.value = value;
+    input.spellcheck = false;
+    input.dataset.key = `attr:${name}`;
+    input.placeholder = BOOLEAN.has(name) ? 'on' : '';
+    input.setAttribute('aria-label', `${name} value`);
+    const commit = () => { if (input.value !== value) save({ [name]: input.value }, `${name}="${input.value.slice(0, 24)}"`); };
+    const choices = valuesFor(node.tag, name);
+    if (choices.length) attachSuggest(input, { empty: true, fetch: word => filterLocal(choices.map(item => ({ name: item })), choices.includes(word) ? '' : word), onAccept: commit });
+    input.addEventListener('keydown', event => {
+      event.stopPropagation();
+      if (event.key === 'Enter') { event.preventDefault(); input.blur(); }
+      else if (event.key === 'Escape') { input.value = value; input.blur(); }
+    });
+    input.addEventListener('change', commit);
+    const remove = el('button', 'tool mini');
+    remove.type = 'button';
+    remove.dataset.tip = `Remove ${name}`;
+    remove.setAttribute('aria-label', `Remove ${name}`);
+    remove.append(icon('close'));
+    remove.addEventListener('click', () => save({ [name]: null }, `remove ${name}`));
+    line.append(el('span', 'swatch none'), key, input, remove);
+    box.append(line);
+  }
+
+  // Add: a name with suggestions for this tag, then its value.
+  const add = el('div', 'kv add');
+  const nameInput = el('input', 'field mono');
+  nameInput.type = 'text';
+  nameInput.placeholder = 'attribute';
+  nameInput.spellcheck = false;
+  nameInput.dataset.key = 'attr-new-key';
+  nameInput.setAttribute('aria-label', 'New attribute name');
+  const valueInput = el('input', 'field mono');
+  valueInput.type = 'text';
+  valueInput.placeholder = 'value';
+  valueInput.spellcheck = false;
+  valueInput.dataset.key = 'attr-new-value';
+  valueInput.setAttribute('aria-label', 'New attribute value');
+  const missing = () => namesFor(node.tag).filter(([name]) => !Object.hasOwn(attrs, name)).map(([name, hint]) => ({ name, hint }));
+  const submit = () => {
+    const name = nameInput.value.trim();
+    if (!name) return false;
+    if (!/^[A-Za-z_:][A-Za-z0-9_.:-]*$/.test(name)) { nameInput.focus(); return false; }
+    if (!valueInput.value && !BOOLEAN.has(name)) return false;
+    save({ [name]: valueInput.value }, `${name}="${valueInput.value.slice(0, 24)}"`);
+    nameInput.value = '';
+    valueInput.value = '';
+    return true;
+  };
+  const toValue = () => {
+    const name = nameInput.value.trim();
+    if (!name) return;
+    if (BOOLEAN.has(name)) { submit(); return; }
+    valueInput.placeholder = valuesFor(node.tag, name)[0] ?? known.get(name) ?? 'value';
+    valueInput.focus();
+  };
+  attachSuggest(nameInput, { fetch: word => filterLocal(missing(), word), onAccept: toValue });
+  attachSuggest(valueInput, { empty: true, fetch: word => { const choices = valuesFor(node.tag, nameInput.value.trim()); return filterLocal(choices.map(item => ({ name: item })), choices.includes(word) ? '' : word); }, onAccept: () => submit() });
+  nameInput.addEventListener('keydown', event => {
+    event.stopPropagation();
+    if (event.key === 'Enter') { event.preventDefault(); toValue(); }
+    else if (event.key === 'Escape') { nameInput.value = ''; nameInput.blur(); }
+  });
+  valueInput.addEventListener('keydown', event => {
+    event.stopPropagation();
+    if (event.key === 'Enter') { event.preventDefault(); if (submit()) nameInput.focus(); }
+    else if (event.key === 'Escape') { valueInput.value = ''; valueInput.blur(); }
+  });
+  valueInput.addEventListener('change', () => { if (nameInput.value.trim() && valueInput.value) submit(); });
+  add.append(nameInput, valueInput);
+  box.append(add);
+
+  // One click for the attributes this kind of element usually needs.
+  const wanted = (IMPORTANT[node.tag] || []).filter(name => !Object.hasOwn(attrs, name));
+  if (wanted.length) {
+    const quick = el('div', 'chips quick-attrs');
+    for (const name of wanted) {
+      const chip = el('button', 'chip', `+ ${name}`);
+      chip.type = 'button';
+      chip.dataset.tip = known.get(name) ?? name;
+      chip.addEventListener('click', () => { nameInput.value = name; toValue(); });
+      quick.append(chip);
+    }
+    box.append(quick);
+  }
+  return box;
+}

package/dist/lib/board-host.d.ts

@@ -0,0 +1,14 @@
+/** A history reader need not have authority to restore project state. Payload admission remains with the consumer. */
+export interface BoardHistoryService {
+    readonly readRecent: () => Promise<unknown>;
+    readonly navigate?: (target: {
+        pointId: string;
+        expectedPoint: string;
+    }) => Promise<unknown>;
+}
+/** Native source-update workflow, including the actions offered by its notification. Absent in static compositions. */
+export interface BoardSourceUpdates {
+    readonly readStatus: () => Promise<unknown>;
+    readonly reimport: () => Promise<unknown>;
+    readonly openProject: (path: string) => Promise<unknown>;
+}

package/dist/lib/board-host.js

@@ -0,0 +1,2 @@
+/* Owns: optional host services for history and native source updates. Excludes: read-session authority and I/O implementation. */
+export {};

package/dist/lib/board-session.d.ts

@@ -0,0 +1,53 @@
+export type BoardReadEvent = {
+    type: 'connection';
+    status: 'connected' | 'offline';
+} | {
+    type: 'state';
+    value: unknown;
+} | {
+    type: 'change';
+    value: unknown;
+} | {
+    type: 'invalid-state';
+};
+/** Payloads are opaque transport data; existing consumers/admission own their model and state checks. */
+export interface BoardReadSession {
+    readonly readState: () => Promise<unknown>;
+    readonly readFrame: (id: string) => Promise<unknown>;
+    /** Each subscription owns its cleanup. After cleanup, it delivers no further events. */
+    readonly subscribe: (listener: (event: BoardReadEvent) => void) => () => void;
+}
+/** Optional host capability for sharing ephemeral view selection, not committing project content. Replies are opaque board state. */
+export interface BoardSelection {
+    readonly ids: readonly string[];
+    readonly nodes?: {
+        readonly documentId: string;
+        readonly nodeIds: readonly string[];
+    };
+}
+export type BoardSelectionPublisher = (selection: BoardSelection) => Promise<unknown>;
+/** Frame measurements already bounded by the preview receiver. `version` and `render` both name the shown render revision. */
+export interface BoardObservation {
+    readonly documentId: string;
+    readonly version: number;
+    readonly render: number;
+    readonly nodes: readonly {
+        readonly id: string;
+        readonly rect: {
+            readonly x: number;
+            readonly y: number;
+            readonly width: number;
+            readonly height: number;
+        };
+        readonly overflowX?: boolean;
+        readonly overflowY?: boolean;
+    }[];
+    readonly contentHeight?: number;
+    readonly scrollHeight?: number;
+}
+export type BoardObservationPublisher = (report: BoardObservation) => Promise<unknown>;
+/** A host-created snapshot; the caller owns project admission and public-data curation. Not an upload parser. */
+export declare function createSnapshotReadSession({ state, frames }: {
+    state: unknown;
+    frames: ReadonlyMap<string, unknown>;
+}): BoardReadSession;

package/dist/lib/board-session.js

@@ -0,0 +1,24 @@
+/** A host-created snapshot; the caller owns project admission and public-data curation. Not an upload parser. */
+export function createSnapshotReadSession({ state, frames }) {
+    const snapshot = structuredClone(state);
+    const models = new Map([...frames].map(([id, model]) => [id, structuredClone(model)]));
+    return Object.freeze({
+        readState: async () => structuredClone(snapshot),
+        readFrame: async (id) => {
+            if (!models.has(id))
+                throw Object.assign(new Error(`Unknown frame: ${id}`), { code: 'NOT_FOUND' });
+            return structuredClone(models.get(id));
+        },
+        subscribe(listener) {
+            let active = true;
+            queueMicrotask(() => {
+                if (!active)
+                    return;
+                listener({ type: 'connection', status: 'connected' });
+                if (active)
+                    listener({ type: 'state', value: structuredClone(snapshot) });
+            });
+            return () => { active = false; };
+        },
+    });
+}