@worca/app 1.3.0 → 1.4.0

package/ui/public/artifact-picker.mjs

@@ -0,0 +1,189 @@
+// ui/public/artifact-picker.mjs
+// "Run…" on a bench input: pick an md/json artifact of a PAST run and drop its
+// text into the port (W2). Client-only by design (C6): it reads the three
+// existing routes — /api/history, /api/runs/:id/artifacts and
+// /api/runs/:id/artifact?rel= — whose indexed-artifact resolver already owns
+// path safety, so the bench API never learns a second input shape.
+//
+// The picked text is TEXT from then on (W9): a case that referenced a run would
+// break when the run is pruned, and could not travel in a plugin.
+import { h } from './script-forms.mjs';
+
+export const PICKER_EXTENSIONS = { md: ['md'], json: ['json'] };
+export const MAX_INPUT_BYTES = 262144;
+/** BYTES, like the store's own case cap (script-cases.mjs), not characters. */
+const byteLength = (s) => new TextEncoder().encode(String(s)).length;
+
+/** The file's extension against the requested types. Pure. */
+export function artifactMatches(relPath, types) {
+  const base = String(relPath || '').split('/').pop() || '';
+  const dot = base.lastIndexOf('.');
+  if (dot <= 0) return false;
+  const ext = base.slice(dot + 1).toLowerCase();
+  return (types || []).some((t) => (PICKER_EXTENSIONS[t] || [t]).includes(ext));
+}
+
+/** `YYYY-MM-DD HH:MM` in LOCAL time, like every other date in the app. */
+function whenOf(iso) {
+  const t = Date.parse(iso || '');
+  if (!Number.isFinite(t)) return '';
+  const d = new Date(t);
+  const p = (n) => String(n).padStart(2, '0');
+  return `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())} ${p(d.getHours())}:${p(d.getMinutes())}`;
+}
+
+export function runRowLabel(run) {
+  return [run.title || run.id, run.id, whenOf(run.startedAt)].filter(Boolean).join(' · ');
+}
+
+function bytesOf(n) {
+  const b = Number(n) || 0;
+  if (b < 1024) return `${b} B`;
+  if (b < 1024 * 1024) return `${(b / 1024).toFixed(1)} KB`;
+  return `${(b / (1024 * 1024)).toFixed(1)} MB`;
+}
+
+/** Runs grouped by project, in the order /api/history returned them (newest
+ *  first). A workspace row prefers the workspace's own name, as History does. */
+export function renderRunList(pipelines, { doc = globalThis.document } = {}) {
+  const wrap = h(doc, 'div', 'apick');
+  const list = Array.isArray(pipelines) ? pipelines : [];
+  if (!list.length) { wrap.appendChild(h(doc, 'div', 'apick-empty', 'No runs yet.')); return wrap; }
+  const groups = new Map();
+  for (const p of list) {
+    if (!p || !p.id) continue;
+    const key = p.projectKey || '';
+    if (!groups.has(key)) {
+      const name = p.target === 'workspace' ? (p.workspaceName || p.projectName || key) : (p.projectName || key);
+      groups.set(key, { name, runs: [] });
+    }
+    groups.get(key).runs.push(p);
+  }
+  for (const g of groups.values()) {
+    const box = h(doc, 'div', 'apick-project');
+    box.appendChild(h(doc, 'div', 'apick-project-name', g.name));
+    for (const run of g.runs) {
+      const row = h(doc, 'button', 'apick-run');
+      row.type = 'button';
+      row.dataset.runId = run.id;
+      row.append(h(doc, 'span', 'apick-run-title', run.title || run.id),
+        h(doc, 'span', 'apick-run-meta', [run.id, whenOf(run.startedAt)].filter(Boolean).join(' · ')));   // the title is already beside it
+      box.appendChild(row);
+    }
+    wrap.appendChild(box);
+  }
+  return wrap;
+}
+
+export function renderArtifactList(artifacts, { doc = globalThis.document, types = ['md'] } = {}) {
+  const wrap = h(doc, 'div', 'apick');
+  const back = h(doc, 'button', 'btn btn-ghost btn-mini apick-back', 'Runs');
+  back.type = 'button';
+  wrap.appendChild(back);
+  const hits = (Array.isArray(artifacts) ? artifacts : []).filter((a) => a && artifactMatches(a.relPath, types));
+  if (!hits.length) {
+    wrap.appendChild(h(doc, 'div', 'apick-empty', `This run has no ${types.join('/')} artifacts.`));
+    return wrap;
+  }
+  for (const a of hits) {
+    const row = h(doc, 'button', 'apick-art');
+    row.type = 'button';
+    row.dataset.rel = a.relPath;
+    row.append(h(doc, 'span', 'apick-art-name', String(a.relPath).split('/').pop() || a.relPath),
+      h(doc, 'span', 'chip apick-art-kind', a.kind || ''),
+      h(doc, 'span', 'apick-art-bytes', bytesOf(a.bytes)));
+    wrap.appendChild(row);
+  }
+  return wrap;
+}
+
+/**
+ * Open the app's modal shell on the picker. Resolves `{ text, label }` on a pick
+ * and `null` on Cancel — exactly once, whatever order the clicks arrive in.
+ * `modal` is app.js's `{ open: pluginModal, close: closePluginModal }`.
+ */
+export function openArtifactPicker({ doc = globalThis.document, api, types = ['md'], modal } = {}) {
+  return new Promise((resolve) => {
+    let settled = false;
+    const body = h(doc, 'div', 'apick-body');
+    let unhook = null;
+    const done = (value) => {
+      if (settled) return;
+      settled = true;
+      if (unhook) unhook();
+      modal.close();
+      resolve(value);
+    };
+    // The error sits ABOVE whatever is on screen, never in place of it: replacing
+    // the body would take the Runs button with it and strand the picker on a run
+    // whose indexed file has been pruned.
+    const fail = (message) => {
+      const old = body.querySelector('.apick-err');
+      if (old) old.remove();
+      body.prepend(h(doc, 'div', 'apick-err', message));
+    };
+    const failed = (r) => fail((r && r.data && r.data.error) || `HTTP ${r && r.status}`);
+    let runs = [];
+
+    async function showRuns() {
+      const r = await api.history();
+      if (settled) return;
+      if (!r.ok) return failed(r);
+      runs = Array.isArray(r.data.pipelines) ? r.data.pipelines : [];
+      body.replaceChildren(renderRunList(runs, { doc }));
+    }
+
+    async function showArtifacts(runId) {
+      const r = await api.runArtifacts(runId);
+      if (settled) return;
+      if (!r.ok) return failed(r);
+      body.replaceChildren(renderArtifactList(r.data.artifacts, { doc, types }));
+      body.dataset.runId = runId;
+    }
+
+    async function pick(runId, rel) {
+      const r = await api.runArtifact(runId, rel);
+      if (settled) return;
+      if (!r.ok) return failed(r);
+      const text = String(r.data.text ?? '');
+      // The SAME 256 KiB-per-port cap File… enforces (W9). Without it the run would
+      // go out fine and `Save as case` would come back with the store's refusal —
+      // the two ways into one port have to agree.
+      if (byteLength(text) > MAX_INPUT_BYTES) return fail(`"${rel}" is larger than 256 KiB.`);
+      const run = runs.find((p) => p && p.id === runId);
+      done({ text, label: `${(run && run.title) || runId} · ${rel}` });
+    }
+
+    body.addEventListener('click', (e) => {
+      const t = e.target;
+      const run = t.closest ? t.closest('.apick-run') : null;
+      if (run) { void showArtifacts(run.dataset.runId); return; }
+      if (t.closest && t.closest('.apick-back')) { void showRuns(); return; }
+      const art = t.closest ? t.closest('.apick-art') : null;
+      if (art) void pick(body.dataset.runId, art.dataset.rel);
+    });
+
+    // EVERY way out settles the promise once — the shell's own header Close and Escape
+    // included, or the caller awaits for ever and the next open stacks a second body.
+    if (typeof modal.onClose === 'function') unhook = modal.onClose(() => done(null));
+    modal.open('Pick an artifact', body, [['Cancel', 'btn btn-ghost btn-mini', () => done(null)]]);
+    void showRuns();
+  });
+}
+
+/**
+ * "File…": read a local file as text, capped at 256 KiB per port (W9). The cap is
+ * checked on `file.size` BEFORE the read, so a 2 GB file is never pulled into
+ * memory to be rejected.
+ */
+export function readInputFile(file, { maxBytes = MAX_INPUT_BYTES, FileReaderImpl = globalThis.FileReader } = {}) {
+  const name = (file && file.name) || 'file';
+  return new Promise((resolve, reject) => {
+    if (!file) { reject(new Error(`"${name}" could not be read.`)); return; }
+    if (Number(file.size) > maxBytes) { reject(new Error(`"${name}" is larger than 256 KiB.`)); return; }
+    const reader = new FileReaderImpl();
+    reader.onload = () => resolve({ text: String(reader.result ?? ''), label: name });
+    reader.onerror = () => reject(new Error(`"${name}" could not be read.`));
+    try { reader.readAsText(file); } catch { reject(new Error(`"${name}" could not be read.`)); }
+  });
+}

package/ui/public/ask/dom.mjs

@@ -0,0 +1,121 @@
+// ui/public/ask/dom.mjs
+// The DOM primitives every ask-form widget module shares. This file imports
+// nothing and touches no global: the target `document` always arrives as `doc`
+// (the ui/public/script-forms.mjs convention), and every function returns
+// DETACHED nodes. No colour literal ever appears here — style.css owns colour.
+
+/** `<tag class=cls>text</tag>`. `text` goes through textContent, always. */
+export function h(doc, tag, cls, text) {
+  const n = doc.createElement(tag);
+  if (cls) n.className = cls;
+  if (text != null) n.textContent = String(text);
+  return n;
+}
+
+/** Set attributes from a map; null/undefined/false are skipped, true becomes ''. */
+export function attrs(node, map) {
+  for (const [k, v] of Object.entries(map || {})) {
+    if (v == null || v === false) continue;
+    node.setAttribute(k, v === true ? '' : String(v));
+  }
+  return node;
+}
+
+const SVG_NS = 'http://www.w3.org/2000/svg';
+
+/** A stroked 24-grid glyph, `aria-hidden` (the control beside it carries the name). */
+export function icon(doc, d, size = 16) {
+  const svg = doc.createElementNS(SVG_NS, 'svg');
+  svg.setAttribute('width', String(size));
+  svg.setAttribute('height', String(size));
+  svg.setAttribute('viewBox', '0 0 24 24');
+  svg.setAttribute('fill', 'none');
+  svg.setAttribute('stroke', 'currentColor');
+  svg.setAttribute('stroke-width', '2');
+  svg.setAttribute('stroke-linecap', 'round');
+  svg.setAttribute('stroke-linejoin', 'round');
+  svg.setAttribute('aria-hidden', 'true');
+  const path = doc.createElementNS(SVG_NS, 'path');
+  path.setAttribute('d', d);
+  svg.appendChild(path);
+  return svg;
+}
+
+export const ICON_UP = 'M6 15l6-6 6 6';
+export const ICON_DOWN = 'M6 9l6 6 6-6';
+export const ICON_CHECK = 'M5 13l4 4L19 7';
+export const ICON_INFO = 'M12 8v5M12 16.5h.01M12 21a9 9 0 1 0 0-18 9 9 0 0 0 0 18z';
+
+/** The closed tone vocabulary a form may name — `callout.tone`, a `tones` map on
+ *  `select` / `review-list`, a column's `tones` — is the four status families the
+ *  stylesheet already tokens. Anything else is no tone: `data-tone` is set only
+ *  for one of these, so an agent can never name a class the stylesheet lacks. */
+export const TONES = Object.freeze(['info', 'ok', 'warn', 'bad']);
+export const toneOf = (v) => (TONES.includes(v) ? v : '');
+
+/** Human bytes. Mirrors the shape the Artifacts list uses: B / KB / MB. */
+export function fmtBytes(n) {
+  const b = Number(n) || 0;
+  if (b >= 1048576) return `${(b / 1048576).toFixed(1)} MB`;
+  if (b >= 1024) return `${Math.round(b / 1024)} KB`;
+  return `${b} B`;
+}
+
+/** A row's OWN scalar property, or undefined. Every read of agent-named row keys
+ *  (`titleKey`, `captionKey`, `fileKey`, a column `key`, a `labels` map …) goes
+ *  through here: gate 1 admits `"constructor"` as a key name, and a plain `r[k]`
+ *  would print `function Object() { [native code] }`. Objects never become text. */
+export function own(o, k) {
+  if (!o || typeof o !== 'object' || k == null || !Object.hasOwn(o, k)) return undefined;
+  const v = o[k];
+  return v == null || typeof v === 'object' || typeof v === 'function' ? undefined : v;
+}
+
+/** The uppercased extension of a file name, or 'FILE'. */
+export function extOf(name) {
+  const s = String(name == null ? '' : name);
+  const dot = s.lastIndexOf('.');
+  return dot > 0 && dot < s.length - 1 ? s.slice(dot + 1).toUpperCase() : 'FILE';
+}
+
+/**
+ * Is `path` (a DECLARED bind path, e.g. `data.report`) a `type:'file'` field, and
+ * what does it point at? X16: the envelope's `fileRefs` answers this exactly — the
+ * renderer never guesses from the string, so a document body whose whole text is
+ * `README.md` stays a document body and a file field stays a file whatever it holds.
+ * The snapshot entry is then found by REL through ctx.fileFor — never by position:
+ * P2 writes `files[i]` for `fileRefs[i]`, but a preview (P5) ships `fileRefs` with
+ * `files: []`, and nothing here may depend on the two arrays lining up.
+ *   → `{ rel, entry }`       a file with a snapshot: render it
+ *   → `{ rel, entry: null }` a file with no snapshot: draw the .af-nofile tile (X14)
+ *   → `null`                 not a file field: the bound value IS the content
+ */
+export function fileRefAt(path, ctx) {
+  if (typeof path !== 'string' || path === '') return null;
+  const refs = Array.isArray(ctx.ask && ctx.ask.fileRefs) ? ctx.ask.fileRefs : [];
+  const ref = refs.find((r) => r && r.path === path);
+  if (!ref) return null;
+  return { rel: ref.rel, entry: ctx.fileFor(ref.rel) };
+}
+
+/** `fileRefAt` for an item's own `bind`. */
+export function fileRefOfBind(item, ctx) {
+  return fileRefAt(item.bind, ctx);
+}
+
+/**
+ * X14 — the ONE placeholder every file widget falls back to: the file has no
+ * snapshot (P5 renders a declaration's `example`, `files: []`, `fileUrl` → null) or
+ * the manifest simply lacks the rel the agent named. No broken <img>, no <iframe>,
+ * no loadText. The name goes through textContent, like every other agent string.
+ * `.af-nofile` is the pinned class name; P5 reuses it.
+ */
+export function noFileTile(ctx, rel, kind = '') {
+  const box = h(ctx.doc, 'div', 'af-nofile');
+  box.appendChild(h(ctx.doc, 'span', 'af-file-badge', kind || extOf(rel)));
+  box.appendChild(h(ctx.doc, 'span', 'af-file-name', String(rel == null ? '' : rel)));
+  return box;
+}
+
+/** True when this file can actually be addressed on the wire. */
+export const servable = (ctx, entry) => Boolean(entry) && ctx.fileUrl(entry.index) != null;

package/ui/public/ask/form-preview.mjs

@@ -0,0 +1,55 @@
+// ui/public/ask/form-preview.mjs
+// The Agents view previews a DECLARATION, not a run: it has a form def and the
+// def's mandatory `example`, and it wants the picture a run would draw. This
+// module builds the exact envelope the engine emits for a form ask (P2), so the
+// preview goes through renderAskForm unchanged — one renderer, one truth about
+// what a form looks like.
+//
+// Pure by the ui/public module convention: plain objects in, one plain object
+// out. No `doc`, no fetch, no listeners. P1 is imported at depth 3 from
+// ui/public/ask/, never copied (test/shared-graph-single-source.test.mjs).
+
+import { resolveAnswerSchema } from '../../../src/shared/forms/schema.mjs';
+import { fileRefs } from '../../../src/shared/forms/answer.mjs';
+
+/**
+ * The P2-shaped ask envelope (ruling X1) a form's own `example` stands for.
+ * @param {string} id   the form id (the KEY of ask.forms)
+ * @param {object} def  { version, title, surface?, data, answer, layout, example }
+ * @returns {object} the same shape `_ask({ kind: 'form', … })` emits
+ */
+export function previewAskFromDef(id, def) {
+  const d = def && typeof def === 'object' && !Array.isArray(def) ? def : {};
+  const data = d.example && typeof d.example === 'object' ? d.example : {};
+  return {
+    // A preview is not a run: there is no question to answer and no ask to serve
+    // files from, so `id` and `askId` are inert markers and `files` is EMPTY
+    // (ruling X14). The renderer's fileFor() then answers null for every file
+    // value in the data and draws the `.af-nofile` tile with its name.
+    // `fileRefs` IS built (ruling X16): it is the only thing that tells the
+    // renderer a bound value is a file at all. Without it a file-typed example
+    // value renders as plain text.
+    id: `preview:${id}`,
+    askId: `preview:${id}`,
+    kind: 'form',
+    agent: null,
+    nodeId: null,
+    executionId: null,
+    form: id,
+    version: Number.isInteger(d.version) && d.version > 0 ? d.version : 1,
+    title: (typeof d.title === 'string' && d.title.trim()) ? d.title : id,
+    surface: d.surface === 'web' ? 'web' : 'any',
+    data,
+    layout: Array.isArray(d.layout) ? d.layout : [],
+    answerSchema: resolveAnswerSchema(d.answer || {}, data),
+    fileRefs: fileRefs(d.data || {}, data).map(({ path, rel }) => ({ path, rel })),
+    files: [],
+  };
+}
+
+/** The preview's `fileUrl`. Always null: nothing was snapshotted, so the
+ *  renderer draws a neutral placeholder tile with the file name instead of a
+ *  resource that would 404 in the author's face. */
+export function previewFileUrl() {
+  return null;
+}

package/ui/public/ask/form-renderer.mjs

@@ -0,0 +1,250 @@
+// ui/public/ask/form-renderer.mjs
+// The host renderer for a `kind:'form'` ask (ask-forms design §6). It owns the
+// ANSWER state, `when` visibility, the error slots and disposal; the widget
+// tables own the drawing. Module convention (ui/public/script-forms.mjs): `doc`
+// arrives via opts, the tree is detached, nothing fetches and no listener is
+// added outside the returned tree.
+//
+// Depth 3 from ui/public/: `../../../src/shared/forms/<file>.mjs` is the URL the
+// /src/shared mount serves AND the disk path — test/shared-graph-purity.test.mjs
+// pins that equality. Never copy a shared function here.
+import { ASK_CATALOG_VERSION } from '../../../src/shared/forms/catalog.mjs';
+import { effectiveItem, whenOk, visibleFields } from '../../../src/shared/forms/layout.mjs';
+import { collectAnswer } from '../../../src/shared/forms/answer.mjs';
+import { h } from './dom.mjs';
+import { INPUT_WIDGETS_TABLE, EMPTY } from './widgets-input.mjs';
+import { DISPLAY_WIDGETS_TABLE } from './widgets-display.mjs';
+import { LAYOUT_WIDGETS_TABLE } from './widgets-layout.mjs';
+
+// Every mount gets its own id prefix: the run card and the run detail hold a
+// panel for the SAME ask at once, and duplicate ids would cross-wire their labels.
+let mountSeq = 0;
+
+// `gallery` lives in both tables and is the SAME function (widgetClass pins
+// "input iff item.field"); the input table is applied last so its entries win
+// for any other name that ever collides.
+const WIDGETS = Object.assign(Object.create(null),
+  DISPLAY_WIDGETS_TABLE, LAYOUT_WIDGETS_TABLE, INPUT_WIDGETS_TABLE);
+
+const clone = (v) => (v === undefined ? undefined : JSON.parse(JSON.stringify(v)));
+
+function seedDefaults(props) {
+  const out = Object.create(null);           // `__proto__` as a field name must not set a prototype
+  for (const [k, s] of Object.entries(props || {})) {
+    if (s && s.default !== undefined) out[k] = clone(s.default);
+  }
+  return out;
+}
+
+/**
+ * @param {object} ask  the P2 envelope: { layout, answerSchema, data, files, … }
+ * @param {object} opts
+ *   doc            target document (required in practice)
+ *   fileUrl        (index) => string  — GET …/ask-files/:askId/:index
+ *   readonly       History renders the stored answer, disabled
+ *   values         pre-set values (History, or a re-render)
+ *   onChange       ({ values, errors }) => void, after every edit
+ *   loadText       (index) => Promise<string> — the HOST's fetch seam (W5)
+ *   markdown       (text) => { kind: 'md', frag } | { kind: 'plain' }
+ *   highlight      (el) => Promise<void>
+ *   catalogVersion host askCatalog version for `requires` / `fallback`
+ */
+export function renderAskForm(ask, {
+  doc = globalThis.document,
+  fileUrl = null, readonly = false, values = null, onChange = null,
+  loadText = null, markdown = null, highlight = null,
+  catalogVersion = ASK_CATALOG_VERSION,
+} = {}) {
+  const schema = (ask && ask.answerSchema) || { type: 'object', properties: {} };
+  const props = schema.properties || {};
+  const required = Array.isArray(schema.required) ? schema.required : [];
+  const layout = Array.isArray(ask && ask.layout) ? ask.layout : [];
+  const files = Array.isArray(ask && ask.files) ? ask.files : [];
+  const base = `af${(mountSeq += 1)}-`;
+  const ro = Boolean(readonly);
+
+  // A null-prototype object: a field named `constructor` or `__proto__` (agent
+  // vocabulary gate 1 admits as an own answer property) must neither read an
+  // inherited function back into a control nor rewrite the prototype on write.
+  const state = Object.assign(Object.create(null),
+    values && typeof values === 'object' ? clone(values) : seedDefaults(props));
+  const conds = [];          // { el, when }
+  const slots = new Map();   // field -> role=alert element
+  const mdBoxes = [];        // { el, text }
+  const disposers = [];
+  let disposed = false;
+
+  function clearError(field) {
+    const slot = slots.get(field);
+    if (!slot) return;
+    slot.textContent = '';
+    slot.hidden = true;
+    const fld = slot.parentNode;
+    if (fld && fld.classList) fld.classList.remove('af-bad');
+  }
+
+  function setValue(field, v) {
+    if (ro || disposed) return;
+    if (EMPTY(v)) delete state[field]; else state[field] = v;
+    clearError(field);
+    refresh();
+  }
+
+  const ctx = {
+    doc,
+    ask: ask || {},
+    data: (ask && ask.data) || {},
+    base,
+    readonly: ro,
+    catalogVersion,
+    props,
+    required,
+    values: state,
+    // The field's OWN answer schema, or {} — never an inherited `constructor`.
+    schemaOf: (field) => (Object.hasOwn(props, field) ? props[field] : {}),
+    idFor: (suffix) => `${base}${String(suffix).replace(/[^A-Za-z0-9_-]/g, '_')}`,
+    get: (field) => state[field],
+    set: setValue,
+    isRequired: (field) => required.includes(field),
+    errSlot(field) {
+      const el = h(doc, 'div', 'af-err');
+      el.setAttribute('role', 'alert');
+      el.hidden = true;
+      slots.set(field, el);
+      return el;
+    },
+    // X14: BOTH may come back empty. `files` is [] in P5's Agents-view preview (an
+    // `example` was never snapshotted), and agent data can name a rel the manifest
+    // lacks. A file widget draws its .af-nofile tile rather than a broken <img>.
+    fileFor: (rel) => files.find((f) => f && f.rel === rel) || null,
+    fileUrl: (index) => {
+      if (typeof fileUrl !== 'function') return null;
+      const u = fileUrl(index);
+      return typeof u === 'string' && u !== '' ? u : null;
+    },
+    // W5: the module declares WHAT it needs; the host decides HOW to get it. The
+    // host is called SYNCHRONOUSLY (a widget asks at mount, and the tests assert the
+    // ask before they await); whatever it returns or throws becomes a promise.
+    loadText: typeof loadText === 'function'
+      ? (index) => { try { return Promise.resolve(loadText(index)); } catch (e) { return Promise.reject(e); } }
+      : null,
+    markdown: typeof markdown === 'function' ? markdown : null,
+    highlight: typeof highlight === 'function' ? highlight : null,
+    own(fn) { if (typeof fn === 'function' && !disposed) disposers.push(fn); },
+    isDisposed: () => disposed,
+    // The ONE markdown painter (W4): plain text now, the host pipeline as soon as it
+    // can render — immediately when it already can, else when paintMarkdown() runs.
+    // Tracked by node, so a file-bound box is re-tracked when its text arrives.
+    trackMarkdown(el, text) {
+      let box = mdBoxes.find((b) => b.el === el);
+      if (!box) { box = { el, text: '', done: false }; mdBoxes.push(box); }
+      box.text = String(text == null ? '' : text);
+      box.done = false;
+      el.classList.remove('artifact-markdown');
+      el.textContent = box.text;
+      paintBox(box);
+    },
+    render: renderItems,
+  };
+
+  /** Draw a list of layout items. W10: an item with no effective widget draws NOTHING. */
+  function renderItems(items) {
+    const out = [];
+    for (const raw of Array.isArray(items) ? items : []) {
+      const item = effectiveItem(raw, catalogVersion);
+      if (!item || !item.widget) continue;
+      const make = WIDGETS[item.widget];
+      if (typeof make !== 'function') continue;
+      const el = make(item, ctx);
+      if (!el) continue;
+      if (item.when) {
+        conds.push({ el, when: item.when });
+        el.hidden = !whenOk(item.when, state);
+      }
+      out.push(el);
+    }
+    return out;
+  }
+
+  function collect() {
+    // CR1 (satisfied): collectAnswer reads only `.layout` off its first argument,
+    // so the ask ENVELOPE is a legal carrier — it has `layout` and `answerSchema`
+    // but no `answer` / `data` / `example`. It strips unknown keys, settles `when`
+    // to a fixpoint and narrows `required` to the visible set (P1 C6).
+    return collectAnswer(ask || { layout }, schema, state);
+  }
+
+  function progress() {
+    const vis = new Set(visibleFields(layout, state));
+    const req = required.filter((f) => vis.has(f));
+    const done = req.filter((f) => {
+      const v = state[f];
+      return !EMPTY(v) && !(Array.isArray(v) && v.length === 0);
+    }).length;
+    return { done, total: req.length };
+  }
+
+  function refresh() {
+    // Toggle `hidden` on the EXISTING node: a remount would blow away focus and
+    // every half-typed value in the subtree.
+    for (const c of conds) c.el.hidden = !whenOk(c.when, state);
+    if (typeof onChange === 'function') {
+      try { onChange(collect()); } catch { /* a host callback never breaks the form */ }
+    }
+  }
+
+  function setErrors(errors) {
+    for (const field of slots.keys()) clearError(field);
+    for (const e of Array.isArray(errors) ? errors : []) {
+      const field = String((e && e.path) || '').split(/[.[]/)[0];
+      const slot = slots.get(field);
+      if (!slot) continue;
+      slot.textContent = String((e && e.message) || (e && e.code) || 'Invalid.');
+      slot.hidden = false;
+      const fld = slot.parentNode;
+      if (fld && fld.classList) fld.classList.add('af-bad');
+    }
+  }
+
+  /** Render one tracked box through the host pipeline. False while it cannot
+   *  (no pipeline yet, or it answered `plain`); a box is painted at most once per text. */
+  function paintBox(box) {
+    if (disposed || box.done || typeof ctx.markdown !== 'function') return false;
+    let out = null;
+    try { out = ctx.markdown(box.text); } catch { out = null; }
+    if (!out || out.kind !== 'md') return false;
+    box.el.replaceChildren(out.frag);
+    box.el.classList.add('artifact-markdown');
+    box.done = true;
+    if (ctx.highlight) { try { void ctx.highlight(box.el); } catch { /* highlighting is cosmetic */ } }
+    return true;
+  }
+
+  function paintMarkdown() {
+    for (const box of mdBoxes) paintBox(box);
+  }
+
+  function dispose() {
+    if (disposed) return;
+    disposed = true;
+    for (const fn of disposers.splice(0)) { try { fn(); } catch { /* never block a repaint */ } }
+    conds.length = 0;
+    mdBoxes.length = 0;
+    slots.clear();
+  }
+
+  const el = h(doc, 'div', ro ? 'af-form af-readonly' : 'af-form');
+  for (const node of renderItems(layout)) el.appendChild(node);
+
+  return {
+    el,
+    collect,
+    setErrors,
+    dispose,
+    progress,
+    paintMarkdown,
+    setValue,
+    own: ctx.own,
+    snapshot: () => clone(state),
+  };
+}

package/ui/public/ask/registry.mjs

@@ -0,0 +1,53 @@
+// ui/public/ask/registry.mjs
+// The ask-panel renderer registry (agent-ask-forms design §6, D6). `renderQpanel`
+// used to be an if/else ladder on `pq.kind`; it is now a lookup in this table and
+// the five kinds — clarify, gate, recovery, workflow, form — are its registrants.
+// Pure: no DOM, no imports. A renderer is registered by the module that owns its
+// body (app.js for the four legacy bodies, app.js again for `form`), so this file
+// never grows a dependency on any of them.
+
+const RENDERERS = new Map();
+
+const NOOP_COLLECT = () => null;
+const NOOP_ERRORS = () => {};
+const NOOP_TITLE = () => '';
+const NOOP_COUNT = () => null;
+
+/**
+ * Register (or replace) the renderer for one question kind.
+ * @param {string} kind
+ * @param {{ render: Function, collect?: Function, setErrors?: Function,
+ *           title?: Function, count?: Function }} renderer
+ */
+export function registerAskRenderer(kind, renderer) {
+  if (typeof kind !== 'string' || kind === '') return;
+  if (!renderer || typeof renderer.render !== 'function') return;
+  RENDERERS.set(kind, Object.freeze({
+    render: renderer.render,
+    collect: typeof renderer.collect === 'function' ? renderer.collect : NOOP_COLLECT,
+    setErrors: typeof renderer.setErrors === 'function' ? renderer.setErrors : NOOP_ERRORS,
+    title: typeof renderer.title === 'function' ? renderer.title : NOOP_TITLE,
+    count: typeof renderer.count === 'function' ? renderer.count : NOOP_COUNT,
+  }));
+}
+
+/** The renderer for a kind, or null. */
+export function askRendererFor(kind) {
+  return RENDERERS.get(kind) || null;
+}
+
+/**
+ * Which registrant draws this pending question. This IS the pre-registry ladder
+ * from renderQpanel, precedence and all: workflow, then recovery, then form, then
+ * gate — where `gate` still accepts a payload that only carries an `issues` array
+ * (older servers never set kind:'gate') — and clarify as the catch-all, which is
+ * also what `kind:'questions'` lands on.
+ */
+export function askKindOf(pq) {
+  if (!pq) return null;
+  if (pq.kind === 'workflow') return 'workflow';
+  if (pq.kind === 'recovery') return 'recovery';
+  if (pq.kind === 'form') return 'form';
+  if (pq.kind === 'gate' || Array.isArray(pq.issues)) return 'gate';
+  return 'clarify';
+}