@derive-to/artifacts 0.0.0-stage → 0.6.1

package/dist/host/sse.js

@@ -0,0 +1,57 @@
+const MAX_DELAY_MS = 15_000;
+const readFrames = async (body, onData) => {
+    const reader = body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = "";
+    for (;;) {
+        // oxlint-disable-next-line no-await-in-loop -- a stream is consumed one chunk at a time
+        const { value, done } = await reader.read();
+        if (done)
+            return;
+        buffer += decoder.decode(value, { stream: true });
+        const frames = buffer.split("\n\n");
+        buffer = frames.pop() ?? "";
+        for (const frame of frames) {
+            const data = frame
+                .split("\n")
+                .filter((line) => line.startsWith("data:"))
+                .map((line) => line.slice(5).trimStart())
+                .join("\n");
+            if (data)
+                onData(data);
+        }
+    }
+};
+/** Open the stream; the returned function closes it for good. */
+export const openStream = ({ url, init, fetch, onData }) => {
+    const controller = new AbortController();
+    /** One connection; resolves true when it was established (so backoff resets). */
+    const connect = async () => {
+        try {
+            const response = await fetch(url, { ...init, signal: controller.signal });
+            if (!response.ok || !response.body)
+                return false;
+            await readFrames(response.body, onData);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    };
+    let timer;
+    const run = async (attempt) => {
+        if (controller.signal.aborted)
+            return;
+        const established = await connect();
+        if (controller.signal.aborted)
+            return;
+        const next = established ? 0 : attempt + 1;
+        timer = setTimeout(() => void run(next), Math.min(MAX_DELAY_MS, 500 * 2 ** next));
+    };
+    void run(0);
+    return () => {
+        clearTimeout(timer);
+        controller.abort();
+    };
+};
+//# sourceMappingURL=sse.js.map

package/dist/host/sse.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sse.js","sourceRoot":"","sources":["../../src/host/sse.ts"],"names":[],"mappings":"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"}

package/dist/host/view.d.ts

@@ -0,0 +1,60 @@
+import { type McpUiHostContext } from "@modelcontextprotocol/ext-apps/app-bridge";
+import type { Actor, Anchor, ArtifactFeature, Params, TextEdit } from "../protocol/index.js";
+import { type ViewEvents } from "./bridge.js";
+import type { ArtifactClient } from "./client.js";
+import { createEmitter } from "./emitter.js";
+import type { LiveChannel } from "./live.js";
+export interface ArtifactViewOptions {
+    /** The element the artifact frame is appended to. */
+    container: HTMLElement;
+    client: ArtifactClient;
+    live: LiveChannel;
+    artifactId: string;
+    version: number;
+    /** The sandbox page on its own origin, e.g. `https://sandbox.example.com/sandbox.html`. */
+    sandboxUrl: string;
+    actor: Actor | null;
+    /** Defaults to every feature. Leave out "state" for a read-only embed, for example. */
+    features?: ArtifactFeature[];
+    /** Theme, CSS variables, locale: passed to the artifact as MCP Apps host context. */
+    hostContext?: McpUiHostContext;
+    title?: string;
+    /** Return true to handle a link in the host instead of opening a new tab. */
+    onOpenLink?: ((url: string) => boolean | Promise<boolean>) | undefined;
+}
+export interface ArtifactView {
+    readonly iframe: HTMLIFrameElement;
+    /** Resolves when the artifact has loaded and completed the MCP Apps handshake. */
+    readonly ready: Promise<void>;
+    readonly layoutAvailable: boolean;
+    on: ReturnType<typeof createEmitter<ViewEvents>>["on"];
+    setAnchors(anchors: Anchor[]): void;
+    focusAnchor(id: string): void;
+    /** Present a slides artifact one slide at a time from `slide`, or stop. The frame fills its
+     *  container while presenting; put that container in fullscreen yourself. */
+    setPresenting(on: boolean, slide?: number): void;
+    /** Turn text editing on; turning it off resolves with the person's edits (none when
+     *  `discard`), for `client.editText`. */
+    setEditing(on: true, options?: {
+        layout?: boolean;
+        text?: boolean;
+        labels?: Params<"editing">["labels"];
+    }): void;
+    setEditing(on: false, options?: {
+        discard?: boolean;
+    }): Promise<TextEdit[]>;
+    /** The page as it looks now, live data included and scripts removed, for printing. */
+    snapshot(): Promise<string>;
+    /** Collect text and layout in one draft for an atomic save. */
+    finishEditing(options?: {
+        discard?: boolean;
+    }): Promise<Params<"edits">>;
+    /** Mark the host’s currently open link. Null clears the selection. */
+    setSelectedLink(url: string | null): void;
+    setHostContext(context: McpUiHostContext): void;
+    destroy(): void;
+}
+/** Mount an artifact version: sandboxed on its own origin, connected with MCP Apps, and
+ *  collaborative through the artifact extension. */
+export declare const mountArtifact: (options: ArtifactViewOptions) => ArtifactView;
+//# sourceMappingURL=view.d.ts.map

package/dist/host/view.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"view.d.ts","sourceRoot":"","sources":["../../src/host/view.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,gBAAgB,EAEtB,MAAM,2CAA2C,CAAA;AAClD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAA;AAC5F,OAAO,EAAgB,KAAK,UAAU,EAAE,MAAM,aAAa,CAAA;AAC3D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AACjD,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AAC5C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,WAAW,CAAA;AAE5C,MAAM,WAAW,mBAAmB;IAClC,qDAAqD;IACrD,SAAS,EAAE,WAAW,CAAA;IACtB,MAAM,EAAE,cAAc,CAAA;IACtB,IAAI,EAAE,WAAW,CAAA;IACjB,UAAU,EAAE,MAAM,CAAA;IAClB,OAAO,EAAE,MAAM,CAAA;IACf,2FAA2F;IAC3F,UAAU,EAAE,MAAM,CAAA;IAClB,KAAK,EAAE,KAAK,GAAG,IAAI,CAAA;IACnB,uFAAuF;IACvF,QAAQ,CAAC,EAAE,eAAe,EAAE,CAAA;IAC5B,qFAAqF;IACrF,WAAW,CAAC,EAAE,gBAAgB,CAAA;IAC9B,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,6EAA6E;IAC7E,UAAU,CAAC,EAAE,CAAC,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC,GAAG,SAAS,CAAA;CACvE;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAA;IAClC,kFAAkF;IAClF,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC,IAAI,CAAC,CAAA;IAC7B,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAA;IACjC,EAAE,EAAE,UAAU,CAAC,OAAO,aAAa,CAAC,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC,CAAA;IACtD,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,CAAA;IACnC,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAA;IAC7B;iFAC6E;IAC7E,aAAa,CAAC,EAAE,EAAE,OAAO,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAChD;6CACyC;IACzC,UAAU,CACR,EAAE,EAAE,IAAI,EACR,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,OAAO,CAAC;QAAC,IAAI,CAAC,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC,SAAS,CAAC,CAAC,QAAQ,CAAC,CAAA;KAAE,GACnF,IAAI,CAAA;IACP,UAAU,CAAC,EAAE,EAAE,KAAK,EAAE,OAAO,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAA;IAC3E,sFAAsF;IACtF,QAAQ,IAAI,OAAO,CAAC,MAAM,CAAC,CAAA;IAC3B,+DAA+D;IAC/D,aAAa,CAAC,OAAO,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAA;IACxE,sEAAsE;IACtE,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAAA;IACzC,cAAc,CAAC,OAAO,EAAE,gBAAgB,GAAG,IAAI,CAAA;IAC/C,OAAO,IAAI,IAAI,CAAA;CAChB;AAkLD;oDACoD;AACpD,eAAO,MAAM,aAAa,YAAa,mBAAmB,KAAG,YAgF5D,CAAA"}

package/dist/host/view.js

@@ -0,0 +1,218 @@
+import { PostMessageTransport, } from "@modelcontextprotocol/ext-apps/app-bridge";
+import { createBridge } from "./bridge.js";
+import { createEmitter } from "./emitter.js";
+/** Drop absent keys: the SDK's CSP type has no room for explicit `undefined`. */
+const definedOnly = (value) => Object.fromEntries(Object.entries(value).filter(([, entry]) => entry !== undefined));
+const ALL_FEATURES = ["state", "anchors", "presence", "editing", "layout"];
+const createFrame = (title) => {
+    const iframe = document.createElement("iframe");
+    iframe.title = title;
+    iframe.setAttribute("sandbox", "allow-scripts allow-same-origin allow-forms allow-popups allow-popups-to-escape-sandbox");
+    iframe.style.cssText = "display:block;width:100%;height:120px;border:0;background:transparent";
+    return iframe;
+};
+/** Host context changes, held until the bridge is connected and dropped once it closes, so a
+ *  theme change never races the handshake or the teardown. */
+const contextGate = (bridge) => {
+    let state = "waiting";
+    let pending = null;
+    return {
+        open: () => {
+            if (state !== "waiting")
+                return;
+            state = "open";
+            if (pending)
+                bridge.setHostContext(pending);
+        },
+        set: (next) => {
+            if (state === "open")
+                bridge.setHostContext(next);
+            else if (state === "waiting")
+                pending = next;
+        },
+        close: () => {
+            state = "closed";
+        },
+    };
+};
+/** The frame grows with its page, or fills its container while presenting; the page's own
+ *  height waits until after. */
+const frameHeight = (iframe, emitter) => {
+    let filling = false;
+    let pageHeight = 120;
+    const stop = emitter.on("resize", ({ height }) => {
+        if (filling)
+            return;
+        pageHeight = Math.ceil(height);
+        iframe.style.height = `${pageHeight}px`;
+    });
+    return {
+        fill: (on) => {
+            filling = on;
+            iframe.style.height = on ? "100%" : `${pageHeight}px`;
+        },
+        stop,
+    };
+};
+const followSlideScroll = (iframe, emitter) => {
+    return emitter.on("slide", ({ scrollTo }) => {
+        if (scrollTo === undefined)
+            return;
+        requestAnimationFrame(() => {
+            if (!iframe.isConnected)
+                return;
+            // A cross-origin page cannot scroll the host's expanded frame. A zero-height
+            // marker lets the browser scroll every host ancestor without changing layout.
+            const marker = document.createElement("span");
+            marker.style.cssText = `display:block;position:relative;height:0;top:${Math.min(scrollTo, iframe.clientHeight)}px`;
+            iframe.before(marker);
+            marker.scrollIntoView({ block: "start", inline: "nearest" });
+            marker.remove();
+        });
+    });
+};
+const editingGate = (emitter, notify, speaks, pendingEdits) => (how) => {
+    if (!speaks())
+        return Promise.reject(new Error("Artifact is not ready to save. Try again."));
+    const answered = new Promise((resolve, reject) => {
+        const cleanup = () => {
+            clearTimeout(timer);
+            stop();
+            pendingEdits.delete(cancel);
+        };
+        const cancel = () => {
+            cleanup();
+            reject(new Error("Artifact stopped responding. Try again."));
+        };
+        const timer = setTimeout(cancel, 10_000);
+        const stop = emitter.on("edits", (draft) => {
+            cleanup();
+            resolve(draft);
+        });
+        pendingEdits.add(cancel);
+    });
+    notify("editing", { on: false, discard: how?.discard ?? false });
+    return answered;
+};
+/** Ask the view for its page as rendered now. Rejects when it is not ready or does not answer. */
+const snapshotGate = (emitter, notify, speaks) => () => {
+    if (!speaks())
+        return Promise.reject(new Error("Artifact is not ready. Try again."));
+    const answered = new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            stop();
+            reject(new Error("Artifact stopped responding. Try again."));
+        }, 10_000);
+        const stop = emitter.on("page", ({ html }) => {
+            clearTimeout(timer);
+            stop();
+            resolve(html);
+        });
+    });
+    notify("snapshot", {});
+    return answered;
+};
+const editingControl = (notify, finishEditing) => ((on, how) => {
+    if (on)
+        return notify("editing", {
+            on: true,
+            layout: how?.layout ?? false,
+            text: how?.text ?? true,
+            ...(how?.labels ? { labels: how.labels } : {}),
+        });
+    return finishEditing(how).then((draft) => draft.edits);
+});
+const initialization = (bridge, notify, getAnchors) => {
+    const initialized = new Promise((resolve) => {
+        bridge.oninitialized = () => {
+            notify("anchors", { anchors: getAnchors() });
+            resolve();
+        };
+    });
+    const sandboxReady = new Promise((resolve) => {
+        bridge.onsandboxready = () => resolve();
+    });
+    return { initialized, sandboxReady };
+};
+/** Mount an artifact version: sandboxed on its own origin, connected with MCP Apps, and
+ *  collaborative through the artifact extension. */
+export const mountArtifact = (options) => {
+    const { client, live, artifactId } = options;
+    const features = options.features ?? ALL_FEATURES;
+    const emitter = createEmitter();
+    let layoutAvailable = false;
+    emitter.on("layoutReady", ({ available }) => {
+        layoutAvailable = available;
+    });
+    const pendingEdits = new Set();
+    const { bridge, notify, speaks } = createBridge({
+        client,
+        artifactId,
+        actor: options.actor,
+        features,
+        emitter,
+        hostContext: options.hostContext,
+        onOpenLink: options.onOpenLink,
+    });
+    const context = contextGate(bridge);
+    const iframe = createFrame(options.title ?? "Artifact");
+    let anchors = [];
+    const { initialized, sandboxReady } = initialization(bridge, notify, () => anchors);
+    const unsubscribe = live.subscribe((event) => {
+        if (event.type === "state.changed")
+            notify("stateChanged", { key: event.key, snapshot: event.snapshot });
+    });
+    const frame = frameHeight(iframe, emitter);
+    const stopSlideScroll = followSlideScroll(iframe, emitter);
+    const finishEditing = editingGate(emitter, notify, speaks, pendingEdits);
+    const start = async () => {
+        const content = client.content(artifactId, options.version);
+        options.container.append(iframe);
+        const window = iframe.contentWindow;
+        if (!window)
+            throw new Error("The artifact frame has no window.");
+        await bridge.connect(new PostMessageTransport(window, window));
+        context.open();
+        const url = new URL(options.sandboxUrl);
+        const { html, csp } = await content;
+        url.searchParams.set("csp", JSON.stringify(csp));
+        iframe.src = url.href;
+        await sandboxReady;
+        await bridge.sendSandboxResourceReady({ html, csp: definedOnly(csp) });
+        await initialized;
+    };
+    return {
+        iframe,
+        ready: start(),
+        get layoutAvailable() {
+            return layoutAvailable;
+        },
+        on: emitter.on,
+        setAnchors: (next) => {
+            anchors = next;
+            notify("anchors", { anchors });
+        },
+        focusAnchor: (id) => notify("focusAnchor", { id }),
+        setPresenting: (on, slide) => {
+            frame.fill(on);
+            notify("present", slide === undefined ? { on } : { on, slide });
+        },
+        setEditing: editingControl(notify, finishEditing),
+        finishEditing,
+        snapshot: snapshotGate(emitter, notify, speaks),
+        setSelectedLink: (url) => notify("selectedLink", { url }),
+        setHostContext: context.set,
+        destroy: () => {
+            for (const cancel of pendingEdits)
+                cancel();
+            unsubscribe();
+            frame.stop();
+            stopSlideScroll();
+            emitter.clear();
+            context.close();
+            void bridge.close();
+            iframe.remove();
+        },
+    };
+};
+//# sourceMappingURL=view.js.map

package/dist/host/view.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"view.js","sourceRoot":"","sources":["../../src/host/view.ts"],"names":[],"mappings":"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"}

package/dist/protocol/access.d.ts

@@ -0,0 +1,39 @@
+import * as z from "zod/mini";
+import type { Actor } from "./extension.js";
+/**
+ * What a host answers for a principal on an artifact, as a ladder: each verb includes every
+ * verb before it. `interact` is writing shared state from inside the artifact (a vote, a
+ * checklist tick); `comment` adds threads; `edit` publishes versions; `manage` renames,
+ * deletes and shares. The kit has no roles of its own.
+ */
+export declare const verbSchema: z.ZodMiniEnum<{
+    comment: "comment";
+    edit: "edit";
+    interact: "interact";
+    manage: "manage";
+    view: "view";
+}>;
+export type Verb = z.infer<typeof verbSchema>;
+export declare const VERBS: readonly Verb[];
+/** Does holding `held` include `needed`? */
+export declare const verbIncludes: (held: Verb, needed: Verb) => boolean;
+/**
+ * The verbs a principal holds, from the host's answer for each verb on its own: the longest
+ * run from the bottom of the ladder that the host allows. A host that grants `edit` but
+ * forgets `view` grants nothing past the gap, so a verb is never held without every verb
+ * below it.
+ */
+export declare const heldVerbs: (allows: (verb: Verb) => boolean) => Verb[];
+/**
+ * Who a request runs as: the signed-in actor, if any, and the share link it arrived by, if
+ * any. Either, both or neither may be present. A link never invents an actor: an anonymous
+ * reader through a link has `actor: null`.
+ */
+export interface Principal {
+    actor: Actor | null;
+    link: string | null;
+}
+export declare const anonymous: Principal;
+/** The principal for a signed-in actor with no link. */
+export declare const signedIn: (actor: Actor) => Principal;
+//# sourceMappingURL=access.d.ts.map

package/dist/protocol/access.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"access.d.ts","sourceRoot":"","sources":["../../src/protocol/access.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,UAAU,CAAA;AAC7B,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAA;AAE3C;;;;;GAKG;AACH,eAAO,MAAM,UAAU;;;;;;EAA4D,CAAA;AACnF,MAAM,MAAM,IAAI,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAA;AAC7C,eAAO,MAAM,KAAK,EAAE,SAAS,IAAI,EAAuB,CAAA;AAExD,4CAA4C;AAC5C,eAAO,MAAM,YAAY,SAAU,IAAI,UAAU,IAAI,KAAG,OACV,CAAA;AAE9C;;;;;GAKG;AACH,eAAO,MAAM,SAAS,WAAY,CAAC,IAAI,EAAE,IAAI,KAAK,OAAO,KAAG,IAAI,EAO/D,CAAA;AAED;;;;GAIG;AACH,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,KAAK,GAAG,IAAI,CAAA;IACnB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;CACpB;AAED,eAAO,MAAM,SAAS,EAAE,SAAuC,CAAA;AAE/D,wDAAwD;AACxD,eAAO,MAAM,QAAQ,UAAW,KAAK,KAAG,SAAoC,CAAA"}

package/dist/protocol/access.js

@@ -0,0 +1,30 @@
+import * as z from "zod/mini";
+/**
+ * What a host answers for a principal on an artifact, as a ladder: each verb includes every
+ * verb before it. `interact` is writing shared state from inside the artifact (a vote, a
+ * checklist tick); `comment` adds threads; `edit` publishes versions; `manage` renames,
+ * deletes and shares. The kit has no roles of its own.
+ */
+export const verbSchema = z.enum(["view", "interact", "comment", "edit", "manage"]);
+export const VERBS = verbSchema.options;
+/** Does holding `held` include `needed`? */
+export const verbIncludes = (held, needed) => VERBS.indexOf(held) >= VERBS.indexOf(needed);
+/**
+ * The verbs a principal holds, from the host's answer for each verb on its own: the longest
+ * run from the bottom of the ladder that the host allows. A host that grants `edit` but
+ * forgets `view` grants nothing past the gap, so a verb is never held without every verb
+ * below it.
+ */
+export const heldVerbs = (allows) => {
+    const held = [];
+    for (const verb of VERBS) {
+        if (!allows(verb))
+            break;
+        held.push(verb);
+    }
+    return held;
+};
+export const anonymous = { actor: null, link: null };
+/** The principal for a signed-in actor with no link. */
+export const signedIn = (actor) => ({ actor, link: null });
+//# sourceMappingURL=access.js.map

package/dist/protocol/access.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"access.js","sourceRoot":"","sources":["../../src/protocol/access.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,UAAU,CAAA;AAG7B;;;;;GAKG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAA;AAEnF,MAAM,CAAC,MAAM,KAAK,GAAoB,UAAU,CAAC,OAAO,CAAA;AAExD,4CAA4C;AAC5C,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,IAAU,EAAE,MAAY,EAAW,EAAE,CAChE,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,CAAA;AAE9C;;;;;GAKG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,MAA+B,EAAU,EAAE;IACnE,MAAM,IAAI,GAAW,EAAE,CAAA;IACvB,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC;YAAE,MAAK;QACxB,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IACjB,CAAC;IACD,OAAO,IAAI,CAAA;AACb,CAAC,CAAA;AAYD,MAAM,CAAC,MAAM,SAAS,GAAc,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,CAAA;AAE/D,wDAAwD;AACxD,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC,KAAY,EAAa,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAA"}

package/dist/protocol/anchors.d.ts

@@ -0,0 +1,61 @@
+import * as z from "zod/mini";
+/** A text-quote selector (W3C Web Annotation shape): the exact text plus a little context
+ *  on each side, so a repeated phrase resolves to the right occurrence and survives edits
+ *  elsewhere in the page. */
+export declare const quoteSchema: z.ZodMiniObject<{
+    exact: z.ZodMiniString<string>;
+    prefix: z.ZodMiniString<string>;
+    suffix: z.ZodMiniString<string>;
+    element: z.ZodMiniOptional<z.ZodMiniString<string>>;
+    sourceSelector: z.ZodMiniOptional<z.ZodMiniString<string>>;
+}, z.core.$strip>;
+export type Quote = z.infer<typeof quoteSchema>;
+/** A rectangle in the artifact document's coordinates (CSS pixels from the top-left). */
+export declare const rectSchema: z.ZodMiniObject<{
+    top: z.ZodMiniNumber<number>;
+    left: z.ZodMiniNumber<number>;
+    width: z.ZodMiniNumber<number>;
+    height: z.ZodMiniNumber<number>;
+}, z.core.$strip>;
+export type Rect = z.infer<typeof rectSchema>;
+export declare const anchorSchema: z.ZodMiniObject<{
+    id: z.ZodMiniString<string>;
+    quote: z.ZodMiniObject<{
+        exact: z.ZodMiniString<string>;
+        prefix: z.ZodMiniString<string>;
+        suffix: z.ZodMiniString<string>;
+        element: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        sourceSelector: z.ZodMiniOptional<z.ZodMiniString<string>>;
+    }, z.core.$strip>;
+    quiet: z.ZodMiniBoolean<boolean>;
+}, z.core.$strip>;
+export type Anchor = z.infer<typeof anchorSchema>;
+export declare const anchorPositionSchema: z.ZodMiniObject<{
+    id: z.ZodMiniString<string>;
+    rect: z.ZodMiniObject<{
+        top: z.ZodMiniNumber<number>;
+        left: z.ZodMiniNumber<number>;
+        width: z.ZodMiniNumber<number>;
+        height: z.ZodMiniNumber<number>;
+    }, z.core.$strip>;
+    slide: z.ZodMiniOptional<z.ZodMiniInt>;
+}, z.core.$strip>;
+export type AnchorPosition = z.infer<typeof anchorPositionSchema>;
+export declare const pointSchema: z.ZodMiniObject<{
+    x: z.ZodMiniNumber<number>;
+    y: z.ZodMiniNumber<number>;
+}, z.core.$strip>;
+export type Point = z.infer<typeof pointSchema>;
+/** One change to an artifact's text: the quoted words, and what they become. */
+export declare const textEditSchema: z.ZodMiniObject<{
+    quote: z.ZodMiniObject<{
+        exact: z.ZodMiniString<string>;
+        prefix: z.ZodMiniString<string>;
+        suffix: z.ZodMiniString<string>;
+        element: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        sourceSelector: z.ZodMiniOptional<z.ZodMiniString<string>>;
+    }, z.core.$strip>;
+    text: z.ZodMiniString<string>;
+}, z.core.$strip>;
+export type TextEdit = z.infer<typeof textEditSchema>;
+//# sourceMappingURL=anchors.d.ts.map

package/dist/protocol/anchors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"anchors.d.ts","sourceRoot":"","sources":["../../src/protocol/anchors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,UAAU,CAAA;AAE7B;;6BAE6B;AAC7B,eAAO,MAAM,WAAW;;;;;;iBAUtB,CAAA;AACF,MAAM,MAAM,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAA;AAE/C,yFAAyF;AACzF,eAAO,MAAM,UAAU;;;;;iBAKrB,CAAA;AACF,MAAM,MAAM,IAAI,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAA;AAE7C,eAAO,MAAM,YAAY;;;;;;;;;;iBAKvB,CAAA;AACF,MAAM,MAAM,MAAM,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAA;AAEjD,eAAO,MAAM,oBAAoB;;;;;;;;;iBAK/B,CAAA;AACF,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAA;AAEjE,eAAO,MAAM,WAAW;;;iBAA6C,CAAA;AACrE,MAAM,MAAM,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAA;AAE/C,gFAAgF;AAChF,eAAO,MAAM,cAAc;;;;;;;;;iBAGzB,CAAA;AACF,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAA"}

package/dist/protocol/anchors.js

@@ -0,0 +1,41 @@
+import * as z from "zod/mini";
+/** A text-quote selector (W3C Web Annotation shape): the exact text plus a little context
+ *  on each side, so a repeated phrase resolves to the right occurrence and survives edits
+ *  elsewhere in the page. */
+export const quoteSchema = z.object({
+    exact: z.string().check(z.minLength(1), z.maxLength(2_000)),
+    prefix: z.string().check(z.maxLength(64)),
+    suffix: z.string().check(z.maxLength(64)),
+    /** Anchored to an element the author marked `data-anchor="…"` (a chart, an image, a
+     *  row) rather than to text; `exact` is then its label, for the rail. */
+    element: z.optional(z.string().check(z.minLength(1), z.maxLength(128))),
+    /** Original saved selector JSON, including snapshots and stable slide identities.
+     *  Hosts validate and resolve it. The quote remains a fallback for other readers. */
+    sourceSelector: z.optional(z.string().check(z.maxLength(16_000))),
+});
+/** A rectangle in the artifact document's coordinates (CSS pixels from the top-left). */
+export const rectSchema = z.object({
+    top: z.number(),
+    left: z.number(),
+    width: z.number().check(z.nonnegative()),
+    height: z.number().check(z.nonnegative()),
+});
+export const anchorSchema = z.object({
+    id: z.string().check(z.minLength(1), z.maxLength(128)),
+    quote: quoteSchema,
+    /** Resolved threads still resolve (for jump-to) but are not highlighted. */
+    quiet: z.boolean(),
+});
+export const anchorPositionSchema = z.object({
+    id: z.string(),
+    rect: rectSchema,
+    /** The 0-based slide holding the anchor, in a slides artifact. */
+    slide: z.optional(z.int().check(z.nonnegative())),
+});
+export const pointSchema = z.object({ x: z.number(), y: z.number() });
+/** One change to an artifact's text: the quoted words, and what they become. */
+export const textEditSchema = z.object({
+    quote: quoteSchema,
+    text: z.string().check(z.maxLength(10_000)),
+});
+//# sourceMappingURL=anchors.js.map

package/dist/protocol/anchors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"anchors.js","sourceRoot":"","sources":["../../src/protocol/anchors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,UAAU,CAAA;AAE7B;;6BAE6B;AAC7B,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,CAAC,MAAM,CAAC;IAClC,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IAC3D,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC;IACzC,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC;IACzC;6EACyE;IACzE,OAAO,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC;IACvE;yFACqF;IACrF,cAAc,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC;CAClE,CAAC,CAAA;AAGF,yFAAyF;AACzF,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,CAAC,MAAM,CAAC;IACjC,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE;IACf,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;IAChB,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC;IACxC,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC;CAC1C,CAAC,CAAA;AAGF,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,CAAC,MAAM,CAAC;IACnC,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;IACtD,KAAK,EAAE,WAAW;IAClB,4EAA4E;IAC5E,KAAK,EAAE,CAAC,CAAC,OAAO,EAAE;CACnB,CAAC,CAAA;AAGF,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC3C,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE;IACd,IAAI,EAAE,UAAU;IAChB,kEAAkE;IAClE,KAAK,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC;CAClD,CAAC,CAAA;AAGF,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,EAAE,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAA;AAGrE,gFAAgF;AAChF,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,CAAC,MAAM,CAAC;IACrC,KAAK,EAAE,WAAW;IAClB,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;CAC5C,CAAC,CAAA"}

package/dist/protocol/collection.d.ts

@@ -0,0 +1,33 @@
+import type { Mutation, Snapshot, StateItem } from "./state.js";
+export { isStateKey, STATE_KEY_PATTERN, STATE_LIMITS } from "./state-limits.js";
+export interface CollectionDialect {
+    actorField: string;
+    slotField: string;
+    incrementKey: string;
+    /** Keep existing host contracts that refuse invalid or duplicate supplied ids. */
+    strictIds: boolean;
+}
+export declare const DEFAULT_COLLECTION_DIALECT: Readonly<CollectionDialect>;
+export interface CollectionError {
+    error: string;
+    code: "invalid" | "reserved" | "missing" | "items" | "bytes" | "owned";
+}
+export interface CollectionChange {
+    items: StateItem[];
+    itemId: string;
+    changed: boolean;
+}
+export interface CollectionRules {
+    read(value: unknown, options: {
+        mintId?: (() => string) | undefined;
+        stored?: boolean;
+    }): StateItem[] | CollectionError;
+    apply(items: StateItem[], mutation: Mutation, actorId: string, newItemId: string): CollectionChange | CollectionError;
+    /** Is this write allowed under `interact` (adding, your own values, a ±1 nudge)? Anything
+     *  else rewrites shared items and needs `edit`. */
+    withinInteract(mutation: Mutation): boolean;
+    snapshot(items: StateItem[] | null, version: number, actorId: string | null): Snapshot;
+}
+/** Shared collection behavior, with host-owned persisted field names. No stored ids or ownership fields need rewriting. */
+export declare const createCollectionRules: (profile: Readonly<CollectionDialect>) => CollectionRules;
+//# sourceMappingURL=collection.d.ts.map

package/dist/protocol/collection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"collection.d.ts","sourceRoot":"","sources":["../../src/protocol/collection.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AAG/D,OAAO,EAAE,UAAU,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAE/E,MAAM,WAAW,iBAAiB;IAChC,UAAU,EAAE,MAAM,CAAA;IAClB,SAAS,EAAE,MAAM,CAAA;IACjB,YAAY,EAAE,MAAM,CAAA;IACpB,kFAAkF;IAClF,SAAS,EAAE,OAAO,CAAA;CACnB;AACD,eAAO,MAAM,0BAA0B,EAAE,QAAQ,CAAC,iBAAiB,CAKlE,CAAA;AACD,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,EAAE,SAAS,GAAG,UAAU,GAAG,SAAS,GAAG,OAAO,GAAG,OAAO,GAAG,OAAO,CAAA;CACvE;AACD,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,SAAS,EAAE,CAAA;IAClB,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,EAAE,OAAO,CAAA;CACjB;AACD,MAAM,WAAW,eAAe;IAC9B,IAAI,CACF,KAAK,EAAE,OAAO,EACd,OAAO,EAAE;QAAE,MAAM,CAAC,EAAE,CAAC,MAAM,MAAM,CAAC,GAAG,SAAS,CAAC;QAAC,MAAM,CAAC,EAAE,OAAO,CAAA;KAAE,GACjE,SAAS,EAAE,GAAG,eAAe,CAAA;IAChC,KAAK,CACH,KAAK,EAAE,SAAS,EAAE,EAClB,QAAQ,EAAE,QAAQ,EAClB,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,GAChB,gBAAgB,GAAG,eAAe,CAAA;IACrC;uDACmD;IACnD,cAAc,CAAC,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAA;IAC3C,QAAQ,CAAC,KAAK,EAAE,SAAS,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,GAAG,QAAQ,CAAA;CACvF;AAiLD,2HAA2H;AAC3H,eAAO,MAAM,qBAAqB,YAAa,QAAQ,CAAC,iBAAiB,CAAC,KAAG,eAoC5E,CAAA"}