mockpit 0.0.0-stage → 1.1.0

package/dist/server/parts.js

@@ -0,0 +1,338 @@
+// The parts an agent marked in its html (`data-part`, optional `data-part-label`
+// and `data-part-key`). Read server-side from the markup string with a regex —
+// geometry is the bridge's job, identity is declared, so no DOM is needed.
+const TAG_RE = /<[A-Za-z][\w:-]*(\s[^<>]*)?>/g;
+const ATTR_RE = /\sdata-part(-label|-key)?\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'=<>`]+))/g;
+const MAX_PARTS = 200;
+const decode = (s) => s
+    .replace(/&quot;/g, '"')
+    .replace(/&#39;|&apos;/g, "'")
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .replace(/&amp;/g, "&")
+    .trim();
+export function partsInHtml(html) {
+    const byName = new Map();
+    for (const tag of html.matchAll(TAG_RE)) {
+        const attrs = tag[1];
+        if (!attrs || !attrs.includes("data-part"))
+            continue;
+        let name;
+        let label;
+        let key;
+        for (const a of attrs.matchAll(ATTR_RE)) {
+            const value = decode(a[2] ?? a[3] ?? a[4] ?? "").slice(0, 200);
+            if (a[1] === "-label")
+                label = value;
+            else if (a[1] === "-key")
+                key = value;
+            else
+                name = value;
+        }
+        if (!name)
+            continue;
+        let part = byName.get(name);
+        if (!part) {
+            if (byName.size >= MAX_PARTS)
+                break;
+            part = { name };
+            byName.set(name, part);
+        }
+        if (label && !part.label)
+            part.label = label;
+        if (key) {
+            part.keys ??= [];
+            if (!part.keys.includes(key))
+                part.keys.push(key);
+        }
+    }
+    return [...byName.values()];
+}
+export function partsInSurfaces(surfaces) {
+    return mergeParts(surfaces.flatMap((s) => (s.kind === "html" ? [partsInHtml(s.html)] : [])));
+}
+// Union several part lists by name, first occurrence first.
+export function mergeParts(lists) {
+    const byName = new Map();
+    for (const list of lists) {
+        for (const p of list) {
+            const have = byName.get(p.name);
+            if (!have) {
+                byName.set(p.name, { ...p, ...(p.keys ? { keys: [...p.keys] } : {}) });
+                continue;
+            }
+            if (p.label && !have.label)
+                have.label = p.label;
+            for (const k of p.keys ?? []) {
+                have.keys ??= [];
+                if (!have.keys.includes(k))
+                    have.keys.push(k);
+            }
+        }
+    }
+    return [...byName.values()];
+}
+// What happened to the previous version's parts. A part that disappeared but
+// whose key or label reappears under a new name was renamed — comments anchored
+// on it re-anchor by key, so the agent should know which name it now answers to.
+export function diffParts(before, after) {
+    const afterNames = new Set(after.map((p) => p.name));
+    const beforeNames = new Set(before.map((p) => p.name));
+    const added = after.filter((p) => !beforeNames.has(p.name));
+    const vanished = [];
+    const renamed = [];
+    const taken = new Set();
+    for (const old of before) {
+        if (afterNames.has(old.name))
+            continue;
+        const match = added.find((p) => !taken.has(p.name) &&
+            ((old.keys ?? []).some((k) => (p.keys ?? []).includes(k)) ||
+                (!!old.label && old.label === p.label)));
+        if (match) {
+            taken.add(match.name);
+            renamed.push({ from: old.name, to: match.name });
+        }
+        else
+            vanished.push(old.name);
+    }
+    return { vanished, renamed };
+}
+// --- part-scoped revisions ---
+// A revision that touches one part should cost that part, not the whole
+// document: the agent sends new outer html for `data-part="name"` and the
+// server splices it into the current html. Located with a small tokenizer
+// rather than the regex above, because a splice must know where the element
+// ENDS, and a `>` in a quoted attribute, a comment or script text must not
+// fool it.
+const VOID_TAGS = new Set([
+    "area",
+    "base",
+    "br",
+    "col",
+    "embed",
+    "hr",
+    "img",
+    "input",
+    "keygen",
+    "link",
+    "meta",
+    "param",
+    "source",
+    "track",
+    "wbr",
+]);
+// Their content is text up to the matching close tag, so tags inside are not tags.
+const RAW_TEXT_TAGS = new Set(["script", "style", "textarea", "title", "xmp"]);
+const NAME_RE = /[A-Za-z][\w:.-]*/y;
+// Where the close tag of a raw-text element starts, or the end of the string.
+function rawTextEnd(html, name, from) {
+    const close = new RegExp(`</${name}[\\s/>]`, "ig");
+    close.lastIndex = from;
+    return close.exec(html)?.index ?? html.length;
+}
+function* tags(html) {
+    let i = 0;
+    while (i < html.length) {
+        const lt = html.indexOf("<", i);
+        if (lt < 0)
+            return;
+        if (html.startsWith("<!--", lt)) {
+            const close = html.indexOf("-->", lt + 4);
+            if (close < 0)
+                return;
+            i = close + 3;
+            continue;
+        }
+        if (html[lt + 1] === "!" || html[lt + 1] === "?") {
+            const close = html.indexOf(">", lt + 2);
+            if (close < 0)
+                return;
+            i = close + 1;
+            continue;
+        }
+        const isClose = html[lt + 1] === "/";
+        NAME_RE.lastIndex = lt + (isClose ? 2 : 1);
+        const m = NAME_RE.exec(html);
+        if (!m) {
+            i = lt + 1;
+            continue;
+        }
+        const name = m[0].toLowerCase();
+        const nameEnd = lt + (isClose ? 2 : 1) + m[0].length;
+        const end = tagEnd(html, nameEnd);
+        if (end < 0)
+            return;
+        if (isClose) {
+            yield { type: "close", name, start: lt, end, attrs: "", selfClosing: false };
+            i = end;
+            continue;
+        }
+        const attrs = html.slice(nameEnd, end - 1);
+        const selfClosing = /\/\s*$/.test(attrs);
+        yield { type: "open", name, start: lt, end, attrs, selfClosing };
+        i = RAW_TEXT_TAGS.has(name) && !selfClosing ? rawTextEnd(html, name, end) : end;
+    }
+}
+// Index just past the `>` that ends a tag, skipping quoted attribute values.
+function tagEnd(html, from) {
+    let i = from;
+    while (i < html.length) {
+        const ch = html[i];
+        if (ch === ">")
+            return i + 1;
+        i++;
+        if (ch !== "=")
+            continue;
+        while (i < html.length && /\s/.test(html[i]))
+            i++;
+        const q = html[i];
+        if (q !== '"' && q !== "'")
+            continue;
+        const close = html.indexOf(q, i + 1);
+        if (close < 0)
+            return -1;
+        i = close + 1;
+    }
+    return -1;
+}
+function partElements(html) {
+    const out = [];
+    for (const tag of tags(html)) {
+        if (tag.type !== "open" || !tag.attrs.includes("data-part"))
+            continue;
+        let name;
+        let key;
+        for (const a of ` ${tag.attrs}`.matchAll(ATTR_RE)) {
+            const value = decode(a[2] ?? a[3] ?? a[4] ?? "");
+            if (a[1] === "-key")
+                key = value;
+            else if (!a[1])
+                name = value;
+        }
+        if (name)
+            out.push({ name, key, open: tag });
+    }
+    return out;
+}
+const label = (el) => (el.key ? `${el.name}#${el.key}` : el.name);
+// The outer-html range of one part element: from its open tag to the close
+// tag that balances it, counting only tags of the same name so unrelated
+// sloppy markup inside does not matter.
+function elementRange(html, el) {
+    const { open } = el;
+    if (open.selfClosing || VOID_TAGS.has(open.name))
+        return { start: open.start, end: open.end };
+    const unclosed = {
+        error: `part "${label(el)}": <${open.name}> is never closed; balance the markup or revise the whole html`,
+    };
+    if (RAW_TEXT_TAGS.has(open.name)) {
+        const at = rawTextEnd(html, open.name, open.end);
+        const end = at < html.length ? html.indexOf(">", at) : -1;
+        return end < 0 ? unclosed : { start: open.start, end: end + 1 };
+    }
+    let depth = 1;
+    for (const tag of tags(html.slice(open.end))) {
+        if (tag.name !== open.name)
+            continue;
+        if (tag.type === "open") {
+            if (!tag.selfClosing)
+                depth++;
+        }
+        else if (--depth === 0) {
+            return { start: open.start, end: open.end + tag.end };
+        }
+    }
+    return unclosed;
+}
+// "name" or "name#key".
+function parseTarget(target) {
+    const hash = target.lastIndexOf("#");
+    if (hash <= 0)
+        return { name: target };
+    return { name: target.slice(0, hash), key: target.slice(hash + 1) };
+}
+function present(elements) {
+    const names = [...new Set(elements.map((e) => e.name))];
+    return names.length ? names.join(", ") : "none (mark parts with data-part)";
+}
+function matches(elements, target) {
+    const { name, key } = parseTarget(target);
+    const found = elements.filter((e) => e.name === name && (key === undefined || e.key === key));
+    // A part name may itself contain "#".
+    if (key !== undefined && found.length === 0)
+        return elements.filter((e) => e.name === target);
+    return found;
+}
+function resolve(html, elements, target) {
+    const found = matches(elements, target);
+    if (found.length === 0) {
+        const { name, key } = parseTarget(target);
+        const instances = elements.filter((e) => e.name === name);
+        if (key !== undefined && instances.length) {
+            return {
+                error: `part "${name}" has no key "${key}"; instances: ${instances.map(label).join(", ")}`,
+            };
+        }
+        return { error: `no part "${target}"; parts present: ${present(elements)}` };
+    }
+    if (found.length > 1) {
+        return {
+            error: found.every((e) => e.key !== undefined)
+                ? `part "${target}" has ${found.length} instances; target one: ${found.map(label).join(", ")}`
+                : `part "${target}" has ${found.length} instances without data-part-key; key them or revise the whole html`,
+        };
+    }
+    return elementRange(html, found[0]);
+}
+// Replace the outer html of one part. `target` is "name" or "name#key".
+export function splicePart(html, target, replacement) {
+    const range = resolve(html, partElements(html), target);
+    if ("error" in range)
+        return range;
+    return { html: html.slice(0, range.start) + replacement + html.slice(range.end) };
+}
+// Apply several part edits to a version's html surfaces. Every target is
+// located in the ORIGINAL markup, so the result does not depend on the order
+// the edits were listed in; overlapping targets are refused rather than guessed.
+export function spliceParts(surfaces, edits) {
+    const docs = surfaces.flatMap((s, i) => (s.kind === "html" ? [{ i, surface: s }] : []));
+    if (docs.length === 0) {
+        return { ok: false, error: "parts needs an html surface; this variant has none" };
+    }
+    const elements = docs.map((d) => partElements(d.surface.html));
+    const ranges = new Map();
+    for (const target of Object.keys(edits)) {
+        const where = elements.flatMap((els, n) => (matches(els, target).length ? [n] : []));
+        if (where.length > 1) {
+            return {
+                ok: false,
+                error: `part "${target}" is in several html surfaces (${where.map((n) => docs[n].i).join(", ")}); edit one with edit_surface`,
+            };
+        }
+        // With no match, the surface that has the bare name explains the bad key.
+        const { name } = parseTarget(target);
+        const n = where[0] ?? elements.findIndex((els) => els.some((e) => e.name === name));
+        const range = n < 0
+            ? { error: `no part "${target}"; parts present: ${present(elements.flat())}` }
+            : resolve(docs[n].surface.html, elements[n], target);
+        if ("error" in range)
+            return { ok: false, error: range.error };
+        const list = ranges.get(n) ?? [];
+        const overlap = list.find((r) => r.start < range.end && range.start < r.end);
+        if (overlap) {
+            return { ok: false, error: `parts "${overlap.target}" and "${target}" overlap; send one` };
+        }
+        list.push({ ...range, target });
+        ranges.set(n, list);
+    }
+    const next = [...surfaces];
+    for (const [n, list] of ranges) {
+        const { i, surface } = docs[n];
+        let html = surface.html;
+        for (const r of list.toSorted((a, b) => b.start - a.start)) {
+            html = html.slice(0, r.start) + edits[r.target] + html.slice(r.end);
+        }
+        next[i] = { ...surface, html };
+    }
+    return { ok: true, surfaces: next, applied: Object.keys(edits) };
+}

package/dist/server/postMarkdown.d.ts

@@ -0,0 +1,10 @@
+import type { Post, Surface } from "./types.ts";
+export interface PostMarkdownOptions {
+    postUrl?: string;
+    assetBase?: string;
+}
+export type MarkdownablePost = Pick<Post, "title" | "surfaces"> & Partial<Pick<Post, "version" | "updatedAt">>;
+export declare function stripAnsi(text: string): string;
+export declare function surfaceToMarkdown(surface: Surface, index: number, opts?: PostMarkdownOptions): string;
+export declare function postToMarkdown(post: MarkdownablePost, opts?: PostMarkdownOptions): string;
+export declare function unifiedDiff(filename: string, before: string, after: string): string;

package/dist/server/postMarkdown.js

@@ -0,0 +1,271 @@
+// Fence long enough to survive backticks in the content: markdown needs the
+// opening fence to be longer than any backtick run inside it.
+function fence(body, info) {
+    const longest = [...body.matchAll(/`+/g)].reduce((max, m) => Math.max(max, m[0].length), 0);
+    const ticks = "`".repeat(Math.max(3, longest + 1));
+    return `${ticks}${info}\n${body.replace(/\n+$/, "")}\n${ticks}`;
+}
+// ANSI escapes carry no meaning in a markdown code block — strip SGR and the
+// rest of the CSI/OSC family so pasted terminal output reads as plain text.
+// oxlint-disable no-control-regex -- matching the escapes is the whole point
+export function stripAnsi(text) {
+    return text
+        .replace(/\u001b\][^\u0007\u001b]*(?:\u0007|\u001b\\)/g, "") // OSC (titles, hyperlinks)
+        .replace(/\u001b\[[0-9;?]*[ -/]*[@-~]/g, "") // CSI (SGR colors, cursor moves)
+        .replace(/\u001b[@-Z\\-_]/g, ""); // two-character escapes
+}
+// oxlint-enable no-control-regex
+// UTC to the minute. A copied document outlives "2 minutes ago", so the stamp
+// has to be absolute — but seconds are noise for a human reading a paste.
+function stamp(iso) {
+    const at = new Date(iso);
+    if (Number.isNaN(at.getTime()))
+        return null;
+    return `${at.toISOString().slice(0, 16).replace("T", " ")} UTC`;
+}
+function surfaceUrl(opts, index) {
+    if (!opts.postUrl)
+        return null;
+    return `${opts.postUrl}?surface=${index}`;
+}
+const KIND_LABELS = {
+    html: "Html surface",
+};
+// Kinds with no markdown form (html) point back at the surface instead. Also the forward-compat path: a kind this build
+// doesn't know still produces a working link rather than nothing.
+function linkFallback(surface, index, opts) {
+    const label = KIND_LABELS[surface.kind] ?? `${surface.kind} surface`;
+    const url = surfaceUrl(opts, index);
+    return url ? `[${label} — open in mockpit](${url})` : `_${label} ${index + 1}_`;
+}
+function codeBlock(surface) {
+    const body = surface.code ?? "";
+    const heading = codeHeading(surface, body);
+    return `${heading}${fence(body, surface.language ?? "text")}`;
+}
+// A code surface's title (usually a filename) becomes a bold line above the
+// block; an excerpt with `lineStart` says which lines it is, so the pasted block
+// keeps the context the viewer shows in its gutter.
+function codeHeading(surface, body) {
+    if (!surface.title && surface.lineStart === undefined)
+        return "";
+    const name = surface.title ? `\`${surface.title}\`` : "Excerpt";
+    const start = surface.lineStart;
+    if (start === undefined)
+        return `**${name}**\n\n`;
+    // splitLines, not a raw split: a body ending in a newline is not one line longer.
+    const end = start + Math.max(1, splitLines(body).length) - 1;
+    return `**${name}** (lines ${start}–${end})\n\n`;
+}
+function imageBlock(surface, opts) {
+    const alt = surface.alt ?? surface.caption ?? "image";
+    const caption = surface.caption ? `\n\n_${surface.caption}_` : "";
+    if (!opts.assetBase)
+        return `_${alt}_`;
+    return `![${alt}](${opts.assetBase}/a/${surface.assetId})${caption}`;
+}
+function diffBlock(surface) {
+    if (surface.patch)
+        return fence(surface.patch, "diff");
+    if (!surface.files?.length)
+        return null;
+    const patch = surface.files.map((f) => unifiedDiff(f.filename, f.before, f.after)).join("");
+    return patch ? fence(patch, "diff") : null;
+}
+function terminalBlock(surface) {
+    const heading = surface.title ? `**${surface.title}**\n\n` : "";
+    return `${heading}${fence(stripAnsi(surface.text ?? ""), "console")}`;
+}
+function jsonBlock(surface) {
+    let body;
+    try {
+        body = JSON.stringify(surface.data, null, 2) ?? "null";
+    }
+    catch {
+        // A cycle can't reach a stored surface (it arrived as JSON), but the store
+        // is not the only caller — degrade instead of throwing out the whole post.
+        body = String(surface.data);
+    }
+    return fence(body, "json");
+}
+export function surfaceToMarkdown(surface, index, opts = {}) {
+    switch (surface.kind) {
+        case "markdown":
+            return surface.markdown?.trim() ?? "";
+        case "code":
+            return codeBlock(surface);
+        case "diff":
+            return diffBlock(surface) ?? linkFallback(surface, index, opts);
+        case "terminal":
+            return terminalBlock(surface);
+        case "json":
+            return jsonBlock(surface);
+        case "mermaid":
+            // A ```mermaid fence renders as a diagram on GitHub and in most markdown
+            // viewers, so the diagram survives the paste rather than becoming source.
+            return fence(surface.mermaid ?? "", "mermaid");
+        case "image":
+            return imageBlock(surface, opts);
+        default:
+            return linkFallback(surface, index, opts);
+    }
+}
+export function postToMarkdown(post, opts = {}) {
+    const meta = [
+        opts.postUrl ? `[View in mockpit](${opts.postUrl})` : null,
+        post.version && post.version > 1 ? `v${post.version}` : null,
+        post.updatedAt ? stamp(post.updatedAt) : null,
+    ].filter(Boolean);
+    const blocks = [
+        `## ${post.title}`,
+        meta.length ? meta.join(" · ") : null,
+        ...post.surfaces.map((surface, i) => surfaceToMarkdown(surface, i, opts).trim()),
+    ].filter((block) => !!block);
+    return blocks.join("\n\n") + "\n";
+}
+// --- unified diff, for a diff surface sent as before/after file pairs --------
+// The `files` form is the documented fallback for agents without a patch, so
+// this is the fallback's fallback: enough of a unified diff to paste and read —
+// and to apply. `git apply` is unforgiving, so the end-of-file newline is
+// tracked as carefully as the lines themselves. Deliberately small and
+// dependency-free: @pierre/diffs renders the real view in the viewer, and
+// pulling its SSR path in here would drag a highlighter into a text transform.
+const DIFF_CONTEXT = 3;
+// Above this many changed lines on either side, the middle is emitted as one
+// wholesale replacement instead of a line-matched diff. Keeps the O(n·m) matrix
+// off the heap for large files; a huge rewrite reads the same either way.
+const DIFF_MAX_MATRIX = 1500;
+const NO_EOF_MARKER = "\";
+function splitLines(text) {
+    if (text === "")
+        return [];
+    const lines = text.split("\n");
+    if (lines[lines.length - 1] === "")
+        lines.pop();
+    return lines;
+}
+function entries(text) {
+    const lines = splitLines(text);
+    const noEof = lines.length > 0 && !text.endsWith("\n");
+    return lines.map((line, i) => ({ line, noEof: noEof && i === lines.length - 1 }));
+}
+const sameEntry = (a, b) => a.line === b.line && a.noEof === b.noEof;
+const op = (tag, entry) => ({ tag, line: entry.line, noEof: entry.noEof });
+function diffOps(before, after) {
+    let head = 0;
+    while (head < before.length && head < after.length && sameEntry(before[head], after[head]))
+        head++;
+    let tail = 0;
+    while (tail < before.length - head &&
+        tail < after.length - head &&
+        sameEntry(before[before.length - 1 - tail], after[after.length - 1 - tail]))
+        tail++;
+    const midBefore = before.slice(head, before.length - tail);
+    const midAfter = after.slice(head, after.length - tail);
+    const ops = before.slice(0, head).map((entry) => op(" ", entry));
+    if (midBefore.length > DIFF_MAX_MATRIX || midAfter.length > DIFF_MAX_MATRIX) {
+        ops.push(...midBefore.map((entry) => op("-", entry)));
+        ops.push(...midAfter.map((entry) => op("+", entry)));
+    }
+    else {
+        ops.push(...lcsOps(midBefore, midAfter));
+    }
+    ops.push(...before.slice(before.length - tail).map((entry) => op(" ", entry)));
+    return ops;
+}
+function lcsOps(before, after) {
+    const n = before.length;
+    const m = after.length;
+    // lcs[i][j] = length of the longest common subsequence of before[i..], after[j..].
+    // Int32Array rows: the matrix is the one allocation here worth being careful
+    // about (DIFF_MAX_MATRIX bounds it, but that is still up to ~2.25M cells).
+    const lcs = Array.from({ length: n + 1 }, () => new Int32Array(m + 1));
+    for (let i = n - 1; i >= 0; i--) {
+        for (let j = m - 1; j >= 0; j--) {
+            lcs[i][j] = sameEntry(before[i], after[j])
+                ? lcs[i + 1][j + 1] + 1
+                : Math.max(lcs[i + 1][j], lcs[i][j + 1]);
+        }
+    }
+    const ops = [];
+    let i = 0;
+    let j = 0;
+    while (i < n && j < m) {
+        if (sameEntry(before[i], after[j])) {
+            ops.push(op(" ", before[i]));
+            i++;
+            j++;
+        }
+        else if (lcs[i + 1][j] >= lcs[i][j + 1]) {
+            ops.push(op("-", before[i]));
+            i++;
+        }
+        else {
+            ops.push(op("+", after[j]));
+            j++;
+        }
+    }
+    while (i < n)
+        ops.push(op("-", before[i++]));
+    while (j < m)
+        ops.push(op("+", after[j++]));
+    return ops;
+}
+// A side that contributes no lines to a hunk is numbered from the line it comes
+// AFTER, so a pure insertion into an empty file is `-0,0` — not `-1,0`.
+const hunkRange = (start, count) => `${count === 0 ? start - 1 : start},${count}`;
+export function unifiedDiff(filename, before, after) {
+    if (before === after)
+        return "";
+    const ops = diffOps(entries(before), entries(after));
+    const hunks = [];
+    let beforeLine = 1;
+    let afterLine = 1;
+    let cursor = 0;
+    while (cursor < ops.length) {
+        if (ops[cursor].tag === " ") {
+            beforeLine++;
+            afterLine++;
+            cursor++;
+            continue;
+        }
+        // Walk to the end of this run of changes, absorbing short stretches of
+        // context so two nearby edits land in one hunk rather than two.
+        let end = cursor;
+        for (let i = cursor; i < ops.length; i++) {
+            if (ops[i].tag !== " ")
+                end = i;
+            else if (i - end > DIFF_CONTEXT * 2)
+                break;
+        }
+        const start = Math.max(0, cursor - DIFF_CONTEXT);
+        const stop = Math.min(ops.length, end + DIFF_CONTEXT + 1);
+        const beforeStart = beforeLine - (cursor - start);
+        const afterStart = afterLine - (cursor - start);
+        const body = [];
+        let beforeCount = 0;
+        let afterCount = 0;
+        for (let i = start; i < stop; i++) {
+            const o = ops[i];
+            body.push(o.tag + o.line);
+            // The marker annotates the line above it and counts toward neither side.
+            if (o.noEof)
+                body.push(NO_EOF_MARKER);
+            if (o.tag !== "+")
+                beforeCount++;
+            if (o.tag !== "-")
+                afterCount++;
+        }
+        hunks.push(`@@ -${hunkRange(beforeStart, beforeCount)} +${hunkRange(afterStart, afterCount)} @@\n${body.join("\n")}\n`);
+        for (let i = cursor; i < stop; i++) {
+            if (ops[i].tag !== "+")
+                beforeLine++;
+            if (ops[i].tag !== "-")
+                afterLine++;
+        }
+        cursor = stop;
+    }
+    if (!hunks.length)
+        return "";
+    return `--- a/${filename}\n+++ b/${filename}\n${hunks.join("")}`;
+}

package/dist/server/postSurfaces.d.ts

@@ -0,0 +1,40 @@
+import { type Surface } from "./types.ts";
+/** Holds parsed surfaces and any validation issues found at the HTTP/MCP boundary. */
+export interface SurfaceParseResult {
+    surfaces: Surface[];
+    parts: Surface[];
+    errors: SurfaceValidationIssue[];
+}
+/** Identifies a rejected surface field and, for Mermaid syntax, how the agent can recover. */
+export type SurfaceValidationIssue = {
+    code: "invalid_surface";
+    requestPath: string;
+    message: string;
+} | {
+    code: "invalid_mermaid_syntax";
+    requestPath: string;
+    message: string;
+    diagramType: string | null;
+    parserMessage: string;
+    nextSteps: string[];
+};
+/** Describes a failed surface validation without losing machine-readable issue details. */
+export interface SurfaceValidationFailure {
+    ok: false;
+    error: string;
+    code: "surface_validation_failed";
+    issues: SurfaceValidationIssue[];
+}
+/** Returns either validated surfaces or a typed surface validation failure. */
+export type SurfaceValidationResult = {
+    ok: true;
+    surfaces: Surface[];
+    parts: Surface[];
+} | SurfaceValidationFailure;
+/** The project kit ids a write may name on top of the bundled ones. */
+export interface SurfaceKitScope {
+    projectKits?: readonly string[];
+}
+export declare const coerceSurfaces: (raw: unknown, scope?: SurfaceKitScope) => Promise<Surface[]>;
+/** Strictly validates surfaces before a native API write reaches persistence. */
+export declare function validateSurfaces(raw: unknown, scope?: SurfaceKitScope): Promise<SurfaceValidationResult>;