@panphora/clayjs 1.13.1 → 1.15.0

package/src/page/recover.js

@@ -0,0 +1,193 @@
+import toast, { toastPersistent, dismissPersistent } from "../ui/toast.js";
+import { state as pmState } from "../vendor/prosemirror.vendor.js";
+
+export const NOTICE_TEXT = "Some text you typed was kept aside when its block moved or was removed.";
+
+const STYLE_ID = "page-recover-style";
+const STYLES = `
+.page-recover { position: fixed; right: 16px; bottom: 16px; z-index: 20; min-height: 36px; padding: 0 14px; font: inherit; font-size: 14px; color: var(--page-ink); background: var(--page-pop-bg); border: 1px solid var(--page-chrome-line-rest); border-radius: 999px; cursor: pointer; }
+.page-recover[hidden], .page-recover-panel[hidden] { display: none; }
+.page-recover-panel { position: fixed; right: 16px; bottom: 64px; z-index: 21; width: min(380px, calc(100vw - 32px)); max-height: 60vh; overflow-y: auto; color: var(--page-ink); background: var(--page-pop-bg); border: 1px solid var(--page-chrome-line-rest); border-radius: var(--page-chrome-radius); padding: 8px; box-sizing: border-box; }
+.page-recover-head { display: flex; align-items: center; justify-content: space-between; gap: 8px; padding: 4px 6px 8px; font-weight: 600; }
+.page-recover-note { margin: 0 6px 8px; font-size: 13px; opacity: .72; }
+.page-recover-row { display: grid; grid-template-columns: 1fr auto; gap: 4px 12px; align-items: center; min-height: 44px; padding: 8px 6px; border-top: 1px solid var(--page-chrome-line-rest); }
+.page-recover-row.is-target { outline: 2px solid var(--page-accent, currentColor); outline-offset: -2px; }
+.page-recover-meta { grid-column: 1; font-size: 12px; opacity: .72; }
+.page-recover-text { grid-column: 1; overflow-wrap: anywhere; }
+.page-recover-text mark { background: var(--page-mark-bg, rgba(255, 214, 102, .45)); color: inherit; border-radius: 2px; }
+.page-recover-row button, .page-recover-head button { grid-column: 2; grid-row: 1 / span 2; min-height: 36px; padding: 0 12px; font: inherit; font-size: 14px; color: inherit; background: transparent; border: 1px solid var(--page-chrome-line-rest); border-radius: var(--page-chrome-radius); cursor: pointer; }
+@media (max-width: 560px) {
+  .page-recover { top: 12px; bottom: auto; min-height: 44px; }
+  .page-recover-panel { left: 0; right: 0; bottom: 0; width: 100%; max-height: 70vh; border-radius: var(--page-chrome-radius) var(--page-chrome-radius) 0 0; }
+  .page-recover-row button, .page-recover-head button { min-height: 44px; }
+}
+`;
+
+const TYPE_LABELS = { heading: "Heading", list_item: "List item", toggle: "Toggle", quote: "Quote", code_block: "Code", callout: "Callout", table: "Table", image: "Image" };
+const PREVIEW_LIMIT = 280;
+
+const el = (doc, tag, className, attrs = {}) => {
+  const node = doc.createElement(tag);
+  if (className) node.className = className;
+  for (const [key, value] of Object.entries(attrs)) node.setAttribute(key, value);
+  return node;
+};
+
+function ensureStyle(doc) {
+  if (doc.getElementById(STYLE_ID)) return;
+  const style = doc.createElement("style");
+  style.id = STYLE_ID;
+  style.textContent = STYLES;
+  doc.head.append(style);
+}
+
+function previewOf(doc, record) {
+  const out = el(doc, "div", "page-recover-text");
+  let used = 0;
+  for (const block of record.blocks) {
+    for (const run of block.runs) {
+      if (run.kind !== "text" || used >= PREVIEW_LIMIT) continue;
+      const text = run.text.slice(0, PREVIEW_LIMIT - used);
+      used += text.length;
+      out.append(run.displaced ? Object.assign(doc.createElement("mark"), { textContent: text }) : doc.createTextNode(text));
+    }
+    if (used < PREVIEW_LIMIT && block !== record.blocks[record.blocks.length - 1]) out.append(doc.createTextNode(" / "));
+  }
+  if (!out.textContent) out.textContent = "(no text)";
+  return out;
+}
+
+function authorsOf(record) {
+  const out = new Set();
+  for (const block of record.blocks) for (const run of block.runs) if (run.displaced) out.add(run.author ?? null);
+  return [...out];
+}
+
+export function focusBlock(view, id) {
+  let at = null;
+  view.state.doc.forEach((node, pos) => { if (at === null && node.attrs.id === id) at = node.isTextblock ? pos + 1 : pos; });
+  if (at === null) return false;
+  view.dispatch(view.state.tr.setSelection(pmState.Selection.near(view.state.doc.resolve(at))).scrollIntoView());
+  view.focus();
+  return true;
+}
+
+export function createRecoverList({ binding, mount, ownTokens = [], onRestored = () => {}, onStale = () => {} }) {
+  const doc = mount.ownerDocument;
+  ensureStyle(doc);
+  const own = new Set(ownTokens.filter(Boolean));
+  const button = el(doc, "button", "page-recover", { type: "button", "aria-haspopup": "dialog", "aria-expanded": "false" });
+  const panel = el(doc, "div", "page-recover-panel", { role: "dialog", "aria-label": "Recover changes" });
+  button.hidden = true;
+  panel.hidden = true;
+  mount.append(button, panel);
+
+  let snapshot = { recoverable: [], notices: [] };
+  let target = null;
+  let noticeSignature = "";
+
+  const who = (tokens) => {
+    if (tokens.some((token) => own.has(token))) return tokens.length > 1 ? "You and others" : "You";
+    return tokens.some((token) => token !== null) ? "Another editor" : "An earlier edit";
+  };
+
+  const close = () => {
+    panel.hidden = true;
+    target = null;
+    button.setAttribute("aria-expanded", "false");
+  };
+
+  const restore = (record) => {
+    let result;
+    try {
+      result = binding.restore(record.source, record.revision);
+    } catch (error) {
+      console.error("[clay] Restore failed:", error);
+      toast("This change could not be restored.", "error");
+      return { status: "failed" };
+    }
+    if (result.status === "restored" || result.status === "resolved") onRestored(result.id);
+    else if (result.status === "stale") onStale(result);
+    return result;
+  };
+
+  const draw = () => {
+    panel.replaceChildren();
+    const head = el(doc, "div", "page-recover-head");
+    head.append(doc.createTextNode("Recover changes"));
+    const done = el(doc, "button", "", { type: "button" });
+    done.textContent = "Close";
+    done.addEventListener("click", () => { close(); button.focus(); });
+    head.append(done);
+    const note = el(doc, "p", "page-recover-note");
+    note.textContent = "Text typed while its block was moved or removed. Restore puts it back as a new block.";
+    panel.append(head, note);
+    for (const record of snapshot.recoverable) {
+      const row = el(doc, "div", "page-recover-row", { "data-source": record.source });
+      if (record.source === target) row.classList.add("is-target");
+      const meta = el(doc, "div", "page-recover-meta");
+      meta.textContent = `${TYPE_LABELS[record.type] ?? "Paragraph"} · ${who(authorsOf(record))}`;
+      const action = el(doc, "button", "", { type: "button" });
+      action.textContent = "Restore";
+      action.addEventListener("click", () => restore(record));
+      row.append(meta, previewOf(doc, record), action);
+      panel.append(row);
+    }
+  };
+
+  const open = (source = null) => {
+    if (!snapshot.recoverable.length) return;
+    target = source;
+    panel.hidden = false;
+    button.setAttribute("aria-expanded", "true");
+    draw();
+    const rows = [...panel.querySelectorAll(".page-recover-row")];
+    const focus = (rows.find((row) => row.dataset.source === source) ?? rows[0])?.querySelector("button");
+    focus?.focus();
+  };
+
+  const showNotices = (notices) => {
+    const signature = notices.map((notice) => `${notice.source}\u0000${notice.revision}`).join("\n");
+    if (signature === noticeSignature) return;
+    noticeSignature = signature;
+    if (!notices.length) { dismissPersistent(NOTICE_TEXT); return; }
+    toastPersistent(NOTICE_TEXT, "warning", {
+      actions: [
+        { label: "Review", onClick: () => open(notices[0].source) },
+        { label: "Dismiss", onClick: () => { for (const notice of notices) binding.dismiss(notice.source, notice.revision); } },
+      ],
+    });
+  };
+
+  const update = (next) => {
+    snapshot = next;
+    const count = next.recoverable.length;
+    button.hidden = count === 0;
+    button.textContent = `Recover changes (${count})`;
+    if (!count) close();
+    else if (!panel.hidden) draw();
+    showNotices(next.notices);
+  };
+
+  button.addEventListener("click", () => (panel.hidden ? open() : close()));
+  panel.addEventListener("keydown", (event) => {
+    if (event.key !== "Escape") return;
+    event.stopPropagation();
+    close();
+    button.focus();
+  });
+  const off = binding.subscribeRecovery(update);
+
+  return {
+    open,
+    close,
+    restore,
+    get count() { return snapshot.recoverable.length; },
+    destroy() {
+      off();
+      dismissPersistent(NOTICE_TEXT);
+      button.remove();
+      panel.remove();
+    },
+  };
+}

package/src/page/rich/cell.js

@@ -0,0 +1,16 @@
+const ATOM = "\uFFFC";
+const BREAK = '@{"type":"hard_break"}';
+
+export function cellText(value) {
+  if (typeof value === "string") return value;
+  if (typeof value === "number" || typeof value === "boolean") return String(value);
+  if (value === null || typeof value !== "object" || typeof value.c !== "string") return "";
+  const keys = [];
+  for (const run of Array.isArray(value.m) ? value.m : []) {
+    if (!Array.isArray(run)) keys.push(run);
+    else for (let i = 0; i < run[0] && keys.length < value.c.length; i++) keys.push(run[1]);
+  }
+  let out = "";
+  for (let i = 0; i < value.c.length; i++) out += value.c[i] === ATOM && keys[i] === BREAK ? "\n" : value.c[i];
+  return out;
+}

package/src/page/rich/chart.js

@@ -0,0 +1,104 @@
+import { parseDecimal } from "./csv.js";
+import { cellText } from "./cell.js";
+
+const esc = (value) => String(value ?? "").replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
+const fmt = (value) => Number(value.toFixed(2)).toString();
+
+function ticks(min, max, count) {
+  if (min === max) { min -= Math.max(Math.abs(min) * .05, 1); max += Math.max(Math.abs(max) * .05, 1); }
+  const target = (max - min) / (count - 1);
+  const power = 10 ** Math.floor(Math.log10(target));
+  const steps = [1, 2, 5, 10].map((n) => n * power);
+  let step = steps.find((n) => Math.floor(max / n) - Math.ceil(min / n) + 1 <= count) ?? steps.at(-1);
+  while (Math.floor(max / step) - Math.ceil(min / step) + 1 > count) step *= 2;
+  const out = [];
+  for (let n = Math.ceil(min / step); n <= Math.floor(max / step); n++) out.push(Number((n * step).toPrecision(12)));
+  return out.length ? out : [Number(min.toFixed(2)), Number(max.toFixed(2))];
+}
+
+export function chartModel(chart, table) {
+  if (!table) return { state: "missing", reason: "table" };
+  const cols = table.cols ?? [];
+  const rows = table.rows ?? [];
+  const x = cols.find((col) => col.id === chart.x);
+  if (!x || !chart.series?.length || chart.series.some((id) => !cols.some((col) => col.id === id))) return { state: "missing", reason: "column" };
+  const series = chart.series.map((id, index) => {
+    const col = cols.find((item) => item.id === id);
+    const points = rows.map((row, rowIndex) => ({
+      id: `${chart.id}:${row.id}:${id}`, rowId: row.id, colId: id, rowIndex,
+      xLabel: cellText(row.cells?.[chart.x]), value: parseDecimal(cellText(row.cells?.[id])),
+      highlight: row.id === chart.highlight,
+    }));
+    return { id, name: col.name, color: `var(--chart-${index % 6 + 1})`, points };
+  });
+  const points = series.flatMap((item) => item.points);
+  const values = points.map((point) => point.value).filter((value) => value !== null);
+  let min = values.length ? values.reduce((current, value) => Math.min(current, value), Infinity) : 0;
+  let max = values.length ? values.reduce((current, value) => Math.max(current, value), -Infinity) : 1;
+  if (chart.type === "bar") { min = Math.min(min, 0); max = Math.max(max, 0); }
+  else { const pad = (max - min || Math.max(Math.abs(max), 1)) * .05; min -= pad; max += pad; }
+  if (min === max) max = min + 1;
+  return {
+    state: "ok", type: chart.type, title: chart.title ?? "", series, points,
+    xLabels: rows.map((row) => cellText(row.cells?.[chart.x])),
+    yTicks: ticks(min, max, 6), narrowTicks: ticks(min, max, 3), domain: [min, max],
+  };
+}
+
+export function renderChartSvg(model, { width = 640, height = 320, narrow = false } = {}) {
+  if (model.state === "missing") return `<svg xmlns="http://www.w3.org/2000/svg" role="img" width="${width}" height="80" viewBox="0 0 ${width} 80"><title>Chart source missing</title><text x="12" y="44">Chart source missing</text></svg>`;
+  const margin = { left: 52, right: 72, top: 28, bottom: 48 };
+  const plotW = Math.max(1, width - margin.left - margin.right);
+  const plotH = Math.max(1, height - margin.top - margin.bottom);
+  const [min, max] = model.domain;
+  const y = (value) => margin.top + (max - value) / (max - min) * plotH;
+  const n = model.xLabels.length;
+  const x = (index) => margin.left + (n <= 1 ? plotW / 2 : index * plotW / (n - 1));
+  const parts = [`<svg xmlns="http://www.w3.org/2000/svg" role="img" width="${width}" height="${height}" viewBox="0 0 ${width} ${height}">`, `<title>${esc(model.title)}</title>`];
+  const caption = model.series.map((item) => {
+    const valid = item.points.filter((point) => point.value !== null);
+    return `${item.name}: ${valid.length ? `${fmt(valid[0].value)} to ${fmt(valid.at(-1).value)}` : "no values"}`;
+  }).join("; ");
+  parts.push(`<desc>${esc(caption)}</desc>`);
+  for (const tick of narrow ? model.narrowTicks : model.yTicks) {
+    const yy = fmt(y(tick));
+    parts.push(`<line x1="${margin.left}" y1="${yy}" x2="${fmt(margin.left + plotW)}" y2="${yy}" stroke="currentColor" opacity="0.15"/><text x="${margin.left - 8}" y="${fmt(y(tick) + 4)}" text-anchor="end">${fmt(tick)}</text>`);
+  }
+  if (model.type === "bar") {
+    const groupW = plotW / Math.max(n, 1);
+    const barW = Math.max(1, Math.min(32, groupW * .7 / model.series.length));
+    const base = y(0);
+    model.series.forEach((item, seriesIndex) => {
+      item.points.forEach((point) => {
+        if (point.value === null) return;
+        const xx = margin.left + (point.rowIndex + .5) * groupW - model.series.length * barW / 2 + seriesIndex * barW;
+        const yy = y(point.value);
+        parts.push(`<rect data-point="${esc(point.id)}"${point.highlight ? ' data-highlight="true"' : ""} x="${fmt(xx)}" y="${fmt(Math.min(yy, base))}" width="${fmt(barW)}" height="${fmt(Math.abs(base - yy))}" fill="${item.color}"/>`);
+      });
+      const last = [...item.points].reverse().find((point) => point.value !== null);
+      if (last) {
+        const xx = margin.left + (last.rowIndex + .5) * groupW - model.series.length * barW / 2 + seriesIndex * barW;
+        parts.push(`<text x="${fmt(xx + barW / 2)}" y="${fmt(Math.min(y(last.value), base) - 7)}" text-anchor="middle">${esc(item.name)}</text>`);
+      }
+    });
+  } else {
+    model.series.forEach((item) => {
+      let segment = [];
+      const flush = () => { if (segment.length > 1) parts.push(`<polyline points="${segment.join(" ")}" fill="none" stroke="${item.color}" stroke-width="2"/>`); segment = []; };
+      item.points.forEach((point) => {
+        if (point.value === null) { flush(); return; }
+        segment.push(`${fmt(x(point.rowIndex))},${fmt(y(point.value))}`);
+        parts.push(`<circle data-point="${esc(point.id)}"${point.highlight ? ' data-highlight="true"' : ""} cx="${fmt(x(point.rowIndex))}" cy="${fmt(y(point.value))}" r="3" fill="${item.color}"/>`);
+      });
+      flush();
+      const last = [...item.points].reverse().find((point) => point.value !== null);
+      if (last) parts.push(`<text x="${fmt(x(last.rowIndex) + 7)}" y="${fmt(y(last.value) - 5)}">${esc(item.name)}</text>`);
+    });
+  }
+  model.xLabels.forEach((label, i) => {
+    const xx = model.type === "bar" ? margin.left + (i + .5) * plotW / Math.max(n, 1) : x(i);
+    parts.push(`<text x="${fmt(xx)}" y="${fmt(height - 14)}" text-anchor="middle">${esc(label)}</text>`);
+  });
+  parts.push("</svg>");
+  return parts.join("");
+}

package/src/page/rich/csv.js

@@ -0,0 +1,118 @@
+import { keysBetween } from "../model.js";
+
+export class CsvError extends Error {
+  constructor(code, line) {
+    super(`CSV ${code} at line ${line}`);
+    this.name = "CsvError";
+    this.code = code;
+    this.line = line;
+  }
+}
+
+function detectedDelimiter(text) {
+  const counts = new Map([[",", 0], [";", 0], ["\t", 0]]);
+  let quoted = false;
+  for (let i = 0; i < text.length; i++) {
+    const ch = text[i];
+    if (ch === '"') {
+      if (quoted && text[i + 1] === '"') i++;
+      else quoted = !quoted;
+    } else if (!quoted && (ch === "\r" || ch === "\n")) break;
+    else if (!quoted && counts.has(ch)) counts.set(ch, counts.get(ch) + 1);
+  }
+  return [...counts].sort((a, b) => b[1] - a[1])[0][0];
+}
+
+export function parseCsv(text, { delimiter } = {}) {
+  text = String(text).replace(/^\uFEFF/, "");
+  delimiter ??= detectedDelimiter(text);
+  if (typeof delimiter !== "string" || delimiter.length !== 1 || /["\r\n]/.test(delimiter)) throw new TypeError("CSV delimiter must be one non-newline character");
+  const records = [];
+  let row = [], field = "", quoted = false, line = 1, startLine = 1;
+  for (let i = 0; i < text.length; i++) {
+    const ch = text[i];
+    if (quoted) {
+      if (ch === '"') {
+        if (text[i + 1] === '"') { field += '"'; i++; }
+        else quoted = false;
+      } else if (ch === "\r" || ch === "\n") {
+        field += ch;
+        if (ch === "\r" && text[i + 1] === "\n") field += text[++i];
+        line++;
+      } else field += ch;
+    } else if (ch === '"' && field === "") {
+      quoted = true;
+      startLine = line;
+    } else if (ch === delimiter) {
+      row.push(field);
+      field = "";
+    } else if (ch === "\r" || ch === "\n") {
+      row.push(field);
+      records.push(row);
+      row = [];
+      field = "";
+      if (ch === "\r" && text[i + 1] === "\n") i++;
+      line++;
+    } else field += ch;
+  }
+  if (quoted) throw new CsvError("unterminated-quote", startLine);
+  if (row.length || field !== "" || (text && !/[\r\n]$/.test(text))) records.push([...row, field]);
+  if (!records.length) return { header: [], rows: [] };
+  const [header, ...rows] = records;
+  const width = Math.max(header.length, ...rows.map((r) => r.length));
+  header.length = width;
+  for (let i = 0; i < width; i++) header[i] ??= "";
+  for (const r of rows) for (let i = r.length; i < width; i++) r.push("");
+  return { header, rows };
+}
+
+export function parseDecimal(value) {
+  if (typeof value !== "string" || !/^[+-]?(?:0|[1-9]\d*)(?:[.,]\d+)?$/.test(value)) return null;
+  const number = Number(value.replace(",", "."));
+  return Number.isFinite(number) ? number : null;
+}
+
+export function inferKinds(header, rows) {
+  return header.map((_, col) => {
+    const values = rows.map((row) => row[col] ?? "").filter((value) => value.trim() !== "");
+    if (!values.length) return "text";
+    const separators = new Set(values.map((value) => value.includes(",") ? "," : value.includes(".") ? "." : null).filter(Boolean));
+    if (separators.size <= 1 && values.every((value) => parseDecimal(value) !== null)) return "number";
+    if (values.every((value) => {
+      if (!/^\d{4}-\d{2}-\d{2}$/.test(value)) return false;
+      const date = new Date(`${value}T00:00:00Z`);
+      return !Number.isNaN(date.getTime()) && date.toISOString().slice(0, 10) === value;
+    })) return "date";
+    return "text";
+  });
+}
+
+export const COLUMN_KINDS = Object.freeze(["text", "number", "date"]);
+
+export function effectiveKind(stored, values) {
+  return COLUMN_KINDS.includes(stored) ? stored : inferKinds([""], values.map((value) => [value]))[0];
+}
+
+export function tableFromCsv({ header, rows: inputRows }, { maxBytes = Infinity, newId } = {}) {
+  if (typeof newId !== "function") throw new TypeError("tableFromCsv needs newId");
+  const kinds = inferKinds(header, inputRows);
+  const cols = {};
+  const ids = header.map(() => newId());
+  const colPositions = keysBetween(null, null, header.length);
+  header.forEach((name, i) => { cols[ids[i]] = { pos: colPositions[i], name, kind: kinds[i] }; });
+  const rows = {};
+  const positions = keysBetween(null, null, inputRows.length);
+  const encoder = new TextEncoder();
+  let size = encoder.encode(JSON.stringify({ cols, rows })).length;
+  let kept = 0;
+  for (let i = 0; i < inputRows.length; i++) {
+    const id = newId();
+    const row = { pos: positions[i], cells: Object.fromEntries(ids.map((col, j) => [col, inputRows[i][j] ?? ""])) };
+    const increment = encoder.encode(`${kept ? "," : ""}${JSON.stringify(id)}:${JSON.stringify(row)}`).length;
+    if (size + increment > maxBytes) break;
+    rows[id] = row;
+    size += increment;
+    kept++;
+  }
+  return { cols, rows, truncated: kept === inputRows.length ? null : { kept, total: inputRows.length } };
+}

package/src/page/rich/page-tool.js

@@ -0,0 +1,86 @@
+import { cloneJson } from "../../live/ops.js";
+import { validateArtifact, validateState } from "./tool-runtime.js";
+
+const CONTEXT_LIMIT = 16384;
+const bytes = (value) => new TextEncoder().encode(JSON.stringify(value)).length;
+
+/** @typedef {{protocol: 'page-tool/1', requestId: string, prompt: string, context: {title: string, outline: unknown[], tables: unknown[]}, target: null | {toolId: string, rev: string}}} ToolRequest */
+/** @typedef {{requestId: string, artifact: object, state: unknown}} ToolResult */
+/** @typedef {{requestId: string, code: string, message: string}} ToolFailure */
+
+export class ToolRequestError extends Error {
+  constructor(code, message = code) {
+    super(message);
+    this.name = "ToolRequestError";
+    this.code = code;
+  }
+}
+
+function trimmedContext(context) {
+  const copy = cloneJson(context);
+  if (!Array.isArray(copy.tables)) copy.tables = [];
+  if (!Array.isArray(copy.outline)) copy.outline = [];
+  while (bytes(copy) > CONTEXT_LIMIT) {
+    const table = [...copy.tables].reverse().find((item) => Array.isArray(item.rows) && item.rows.length);
+    if (table) table.rows.pop();
+    else if (copy.outline.length) copy.outline.pop();
+    else break;
+  }
+  if (bytes(copy) > CONTEXT_LIMIT) throw new ToolRequestError("context-too-large");
+  return copy;
+}
+
+export function capabilityAdvertised(meta) {
+  return Array.isArray(meta?.extensions) && meta.extensions.includes("page-tool/1");
+}
+
+export function createToolClient({ transport, newId }) {
+  let active = null;
+  const discard = (candidate) => {
+    if (!candidate || candidate.discarded || candidate.done) return;
+    candidate.discarded = true;
+    if (active === candidate) active = null;
+    transport.cancel(candidate.requestId);
+    candidate.resolve({ requestId: candidate.requestId, code: "discarded", message: "Candidate discarded" });
+  };
+  return {
+    request(prompt, context, target = null) {
+      const trimmed = trimmedContext(context);
+      if (active) discard(active);
+      const requestId = newId();
+      const candidate = { requestId, discarded: false, done: false };
+      candidate.promise = new Promise((resolve) => { candidate.resolve = resolve; });
+      active = candidate;
+      const request = { protocol: "page-tool/1", requestId, prompt, context: trimmed, target };
+      candidate.request = request;
+      const finish = (reply) => {
+        if (candidate.discarded || candidate.done || reply?.requestId !== requestId) return;
+        candidate.done = true;
+        if (active === candidate) active = null;
+        if (reply?.artifact !== undefined) {
+          const artifact = validateArtifact(reply.artifact);
+          const state = validateState(reply.state);
+          const invalid = !artifact.ok ? artifact : !state.ok ? state : null;
+          candidate.resolve(invalid ? { requestId, code: invalid.code, message: invalid.code } : reply);
+        } else candidate.resolve(typeof reply?.code === "string" ? reply : { requestId, code: "invalid-result", message: "invalid-result" });
+      };
+      try {
+        Promise.resolve(transport.request(request)).then(finish, (error) => finish({ requestId, code: "transport-error", message: String(error?.message ?? error) }));
+      } catch (error) {
+        finish({ requestId, code: "transport-error", message: String(error?.message ?? error) });
+      }
+      return candidate;
+    },
+    discard,
+    async wait(candidate, { signal } = {}) {
+      if (signal?.aborted) throw new DOMException("Aborted", "AbortError");
+      let abort;
+      const outcome = await (signal ? Promise.race([
+        candidate.promise,
+        new Promise((_, reject) => { abort = () => reject(new DOMException("Aborted", "AbortError")); signal.addEventListener("abort", abort, { once: true }); }),
+      ]).finally(() => signal.removeEventListener("abort", abort)) : candidate.promise);
+      if (outcome?.code) throw new ToolRequestError(outcome.code, outcome.message);
+      return outcome;
+    },
+  };
+}