fauna-api 0.0.0-stage → 1.0.679

package/dist/src/extensions/web/session.js

@@ -0,0 +1,470 @@
+import { connectRoom } from "../../parrot/room.js";
+import { openRoom } from "../../parrot/share.js";
+import { Marmot } from "../../marmot/index.js";
+import { connectWebRoom, DomRecorder, DomReplayer, toHtml, collectAllAssetUrls, rewriteMediaUrls, extractAssetCodes, materializeAssetUrls, fetchMediaBytes, absoluteUrl, WEB_ASSET_SCHEME, uploadBootstrap, downloadBootstrap, uploadAsset, downloadAsset, weightedProgress, } from "../../marmot/web.js";
+import { attachHostTools, createHostPageToolHandler, pageTools } from "./tools.js";
+/** Public join URL for a web-room access code (chat joins via ensure, not the URL). */
+export function shareUrl(code, origin = "https://app.faunakit.com") {
+    // Trailing slash is required: without it Vite (and many static hosts) serve
+    // the app root `index.html` instead of `extensions/web/index.html`.
+    return `${origin.replace(/\/$/, "")}/extensions/web/?access-code=${encodeURIComponent(code)}`;
+}
+/**
+ * A paired live session: one `WebRoom` (live page DOM) + one `ChatRoom`.
+ * Share links carry only the web access code; chat uses ensure + Parrot code.
+ */
+export class ExtensionWebSession {
+    constructor(parts) {
+        Object.defineProperty(this, "web", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "chat", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "webSelf", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "chatSelf", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        /** Bare web access code used in the share URL. */
+        Object.defineProperty(this, "code", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "recorder", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
+        Object.defineProperty(this, "replayer", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
+        Object.defineProperty(this, "detachTools", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
+        this.web = parts.web;
+        this.chat = parts.chat;
+        this.webSelf = parts.webSelf;
+        this.chatSelf = parts.chatSelf;
+        this.code = parts.code;
+    }
+    shareCode() {
+        return this.code;
+    }
+    /** Page tools routed through the web room (host executes). */
+    pageTools() {
+        return pageTools((name, params) => this.web.invokeTool(name, params));
+    }
+    /**
+     * Begin hosting: upload HTML + assets, bind ids, stream mutations.
+     * Prefer `startWebShare` from the extension for progress UX.
+     */
+    async startHosting(root = document.documentElement, onProgress) {
+        // Host target is the connected room's server authorization.
+        await publishPageBootstrap(this.web, this.web.getAuthorization(), root, onProgress);
+        this.recorder = new DomRecorder(root);
+        this.recorder.bindIds();
+        this.detachTools = attachHostTools(this.web, createHostPageToolHandler(root));
+        let mutationChain = Promise.resolve();
+        this.recorder.start((mutation) => {
+            mutationChain = mutationChain.then(async () => {
+                const next = await maybeRewriteMutationAsset(this.web, this.web.getAuthorization(), mutation);
+                this.web.publishMutation(next);
+            }).catch((err) => {
+                console.error("[extensions/web] mutation publish failed:", err);
+            });
+        });
+    }
+    stopHosting() {
+        this.recorder?.stop();
+        this.recorder = null;
+        this.detachTools?.();
+        this.detachTools = null;
+    }
+    async startViewing(mount, onProgress) {
+        this.replayer = new DomReplayer(mount);
+        const meta = this.web.getBootstrap();
+        if (meta) {
+            await loadAndApplyBootstrap(this.web, this.web.getAuthorization(), this.replayer, meta, onProgress);
+        }
+        else if (this.web.getSnapshot()) {
+            this.replayer.apply(this.web.getSnapshot());
+        }
+    }
+    renderSnapshot(snapshot) {
+        this.replayer?.apply(snapshot);
+    }
+    renderMutation(mutation) {
+        void this.renderMutationAsync(mutation);
+    }
+    async renderMutationAsync(mutation) {
+        if (!this.replayer)
+            return;
+        const next = await materializeMutationAssets(this.web.getAuthorization(), mutation);
+        this.replayer.mutate(next);
+    }
+    close() {
+        try {
+            this.web.publishClosed();
+        }
+        catch { /* noop */ }
+        this.stopHosting();
+        this.replayer = null;
+        try {
+            this.web.disconnect();
+        }
+        catch { /* noop */ }
+        try {
+            this.chat.disconnect();
+        }
+        catch { /* noop */ }
+    }
+}
+function wireViewerHooks(hooks, getSession, getReplayer) {
+    return {
+        ...hooks,
+        onBootstrap(room, bootstrap) {
+            hooks?.onBootstrap?.(room, bootstrap);
+            const replayer = getReplayer();
+            if (replayer) {
+                void loadAndApplyBootstrap(room, room.getAuthorization(), replayer, bootstrap);
+            }
+        },
+        onSnapshot(room, snapshot) {
+            hooks?.onSnapshot?.(room, snapshot);
+            getSession()?.renderSnapshot(snapshot);
+        },
+        onMutation(room, mutation) {
+            hooks?.onMutation?.(room, mutation);
+            const session = getSession();
+            if (session)
+                session.renderMutation(mutation);
+            else {
+                const replayer = getReplayer();
+                if (replayer) {
+                    void materializeMutationAssets(room.getAuthorization(), mutation).then((m) => replayer.mutate(m));
+                }
+            }
+        },
+        onClosed(room) {
+            const session = getSession();
+            if (session)
+                session.replayer = null;
+            hooks?.onClosed?.(room);
+        },
+    };
+}
+/**
+ * Open (or return) a shared Parrot chat room for this tab. Lives until the host
+ * leaves the page — panel close must not destroy it. Does not connect a socket
+ * here; call `connectRoom` from the chat UI with `code`.
+ */
+export async function ensureChatRoom(authorization, cached) {
+    if (cached?.code)
+        return cached;
+    const opened = await openRoom(authorization, { share: true });
+    return {
+        reference: opened.reference,
+        roomId: opened.roomId,
+        code: opened.code ?? "",
+    };
+}
+/**
+ * Bind (host) or open the Parrot room paired with a web room. The host binds a
+ * room it opened (`room` is its reference). Always returns a fresh Parrot access
+ * code for `connectRoom({ code })`.
+ */
+export async function ensureChatFromWebAccess(authorization, scope, opts) {
+    const headers = {
+        "Content-Type": "application/json",
+        Authorization: "email" in authorization ? `Token ${authorization.token}` : `ApiKey ${authorization.id}`,
+    };
+    if ("accessCode" in scope)
+        headers["Access-Code"] = scope.accessCode;
+    else
+        headers["Server"] = scope.reference;
+    const response = await fetch(`${Marmot.getURL()}/extensions/web/chat/ensure`, {
+        method: "POST",
+        headers,
+        body: JSON.stringify(opts?.room ? { room: opts.room } : {}),
+    });
+    if (!response.ok)
+        throw new Error(await response.text());
+    const json = await response.json();
+    if (!json.room || !json.code)
+        throw new Error("Invalid web chat ensure response.");
+    return { room: json.room, code: json.code };
+}
+/**
+ * Start the web room only (chat room must already exist). Uploads HTML + assets
+ * with progress, publishes bootstrap meta, starts mutation streaming + tools.
+ * Pairs the chat room with the web room so guests can ensure a Parrot code later.
+ */
+export async function startWebShare(authorization, chat, options = {}) {
+    const reference = `web:${crypto.randomUUID()}`;
+    const root = options.root ?? document.documentElement;
+    let recorder = null;
+    let detachTools = null;
+    const { room: web, self: webSelf } = await connectWebRoom(authorization, { reference }, options.hooks ?? {});
+    const webCode = await web.generateAccessCode();
+    // Durable web → chat pairing (not encoded in the share URL).
+    await ensureChatFromWebAccess(authorization, { reference }, { room: chat.reference });
+    await publishPageBootstrap(web, authorization, root, options.onProgress, { reference });
+    recorder = new DomRecorder(root);
+    recorder.bindIds();
+    detachTools = attachHostTools(web, createHostPageToolHandler(root));
+    let mutationChain = Promise.resolve();
+    recorder.start((mutation) => {
+        mutationChain = mutationChain.then(async () => {
+            const next = await maybeRewriteMutationAsset(web, authorization, mutation, { reference });
+            web.publishMutation(next);
+        }).catch((err) => {
+            console.error("[extensions/web] mutation publish failed:", err);
+        });
+    });
+    return {
+        web,
+        webSelf,
+        room: chat.reference,
+        webCode,
+        reference,
+        shareCode: () => webCode,
+        close() {
+            // Order matters on tab close: announce before tearing the socket down
+            // so guests (and the edge broadcast) see web-closed when possible.
+            try {
+                web.publishClosed();
+            }
+            catch { /* noop */ }
+            recorder?.stop();
+            recorder = null;
+            detachTools?.();
+            detachTools = null;
+            try {
+                web.disconnect();
+            }
+            catch { /* noop */ }
+        },
+    };
+}
+export async function openSession(authorization, hooks = {}) {
+    let session;
+    let replayer = null;
+    const openedChat = await openRoom(authorization, { share: true });
+    const chatCode = openedChat.code ?? "";
+    const webHooks = wireViewerHooks(hooks.web, () => session, () => replayer);
+    const reference = `web:${crypto.randomUUID()}`;
+    const { room: web, self: webSelf } = await connectWebRoom(authorization, { reference }, webHooks);
+    const webCode = await web.generateAccessCode();
+    await ensureChatFromWebAccess(authorization, { reference }, { room: openedChat.reference });
+    const { room: chat, self: chatSelf } = await connectRoom(authorization, { code: chatCode }, hooks.chat ?? {});
+    session = new ExtensionWebSession({
+        web, chat, webSelf, chatSelf,
+        code: webCode,
+    });
+    return session;
+}
+export async function joinRoom(authorization, webCode, hooks = {}) {
+    let session;
+    let replayer = null;
+    const { room: web, self: webSelf } = await connectWebRoom(authorization, { code: webCode }, wireViewerHooks(hooks.web, () => session, () => replayer));
+    const ensured = await ensureChatFromWebAccess(authorization, { accessCode: webCode });
+    const { room: chat, self: chatSelf } = await connectRoom(authorization, { code: ensured.code }, hooks.chat ?? {});
+    session = new ExtensionWebSession({ web, chat, webSelf, chatSelf, code: webCode });
+    const original = session.startViewing.bind(session);
+    session.startViewing = async (mount, onProgress) => {
+        await original(mount, onProgress);
+        replayer = session?.replayer ?? null;
+    };
+    return session;
+}
+export async function invite(authorization, email, joinUrl, scope) {
+    const headers = {
+        "Content-Type": "application/json",
+        Authorization: "email" in authorization
+            ? `Token ${authorization.token}`
+            : `ApiKey ${authorization.id}`,
+    };
+    if ("accessCode" in scope)
+        headers["Access-Code"] = scope.accessCode;
+    else
+        headers["Server"] = scope.reference;
+    const response = await fetch(`${Marmot.getURL()}/extensions/web/invite`, {
+        method: "POST",
+        headers,
+        body: JSON.stringify({ email, joinUrl }),
+    });
+    if (!response.ok)
+        throw new Error(await response.text());
+    return await response.json();
+}
+// ── Bootstrap helpers ────────────────────────────────────────────────────────
+async function publishPageBootstrap(web, authorization, root, onProgress, targetOverride) {
+    const target = targetOverride
+        ? { reference: targetOverride.reference }
+        : webTargetFromRoom(web);
+    const prepared = toHtml(root);
+    const urls = collectAllAssetUrls(prepared.clone, prepared.cssUrls);
+    const rewrite = new Map();
+    let uploadedCount = 0;
+    let skippedCount = 0;
+    const stages = [];
+    for (const url of urls) {
+        stages.push({
+            weight: 1,
+            run: async (p) => {
+                try {
+                    const abs = absoluteUrl(url);
+                    const fetched = await fetchMediaBytes(abs);
+                    if (!fetched) {
+                        skippedCount++;
+                        p(1);
+                        return;
+                    }
+                    const uploaded = await uploadAsset(authorization, target, fetched.data, fetched.contentType.split(";")[0]?.trim() || "application/octet-stream", { onProgress: p });
+                    rewrite.set(url, uploaded.accessCode);
+                    if (abs !== url)
+                        rewrite.set(abs, uploaded.accessCode);
+                    uploadedCount++;
+                }
+                catch (err) {
+                    // One bad image must not abort the whole page share.
+                    skippedCount++;
+                    console.warn("[extensions/web] asset upload skipped:", url, err);
+                    p(1);
+                }
+            },
+        });
+    }
+    stages.push({
+        weight: Math.max(2, urls.length),
+        run: async (p) => {
+            rewriteMediaUrls(prepared.clone, rewrite);
+            const html = prepared.clone.outerHTML;
+            await uploadBootstrap(authorization, target, html, {
+                version: 1,
+                viewport: prepared.viewport,
+                onProgress: p,
+            });
+        },
+    });
+    await weightedProgress(stages, onProgress);
+    console.info(`[extensions/web] bootstrap assets: ${uploadedCount} uploaded, ${skippedCount} skipped, ${urls.length} total`);
+    const meta = {
+        version: 1,
+        viewport: prepared.viewport,
+        contentType: "text/html; charset=utf-8",
+    };
+    web.publishBootstrap(meta);
+    return meta;
+}
+async function loadAndApplyBootstrap(web, authorization, replayer, meta, onProgress) {
+    const target = webTargetFromRoom(web);
+    const { html } = await downloadBootstrap(authorization, target, (p) => onProgress?.(p * 0.35));
+    const codes = extractAssetCodes(html);
+    const blobs = new Map();
+    let i = 0;
+    for (const code of codes) {
+        const { data, contentType } = await downloadAsset(authorization, code, (p) => {
+            const base = 0.35 + (i / Math.max(codes.length, 1)) * 0.55;
+            const span = 0.55 / Math.max(codes.length, 1);
+            onProgress?.(base + p * span);
+        });
+        const blob = new Blob([new Uint8Array(data)], { type: contentType });
+        blobs.set(code, URL.createObjectURL(blob));
+        i++;
+    }
+    const materialized = materializeAssetUrls(html, blobs);
+    await replayer.applyHtml(materialized, meta.viewport);
+    onProgress?.(1);
+}
+function webTargetFromRoom(web) {
+    const packed = web.authorization;
+    if ("accessCode" in packed)
+        return { code: packed.accessCode };
+    return { reference: packed.server };
+}
+async function maybeRewriteMutationAsset(web, authorization, mutation, targetOverride) {
+    if (mutation.kind !== "attribute")
+        return mutation;
+    if (mutation.name !== "src" && mutation.name !== "poster" && mutation.name !== "href" && mutation.name !== "srcset") {
+        return mutation;
+    }
+    if (!mutation.value || mutation.value.startsWith(WEB_ASSET_SCHEME))
+        return mutation;
+    const target = targetOverride
+        ? { reference: targetOverride.reference }
+        : webTargetFromRoom(web);
+    if (mutation.name === "srcset") {
+        const parts = mutation.value.split(",").map((part) => part.trim());
+        const out = [];
+        for (const part of parts) {
+            const bits = part.split(/\s+/);
+            const url = bits[0] ?? "";
+            const fetched = await fetchMediaBytes(absoluteUrl(url));
+            if (!fetched) {
+                out.push(part);
+                continue;
+            }
+            const uploaded = await uploadAsset(authorization, target, fetched.data, fetched.contentType);
+            out.push([`${WEB_ASSET_SCHEME}${uploaded.accessCode}`, ...bits.slice(1)].join(" "));
+        }
+        return { ...mutation, value: out.join(", ") };
+    }
+    const fetched = await fetchMediaBytes(absoluteUrl(mutation.value));
+    if (!fetched)
+        return mutation;
+    const uploaded = await uploadAsset(authorization, target, fetched.data, fetched.contentType);
+    return { ...mutation, value: `${WEB_ASSET_SCHEME}${uploaded.accessCode}` };
+}
+async function materializeMutationAssets(authorization, mutation) {
+    if (mutation.kind !== "attribute" || !mutation.value)
+        return mutation;
+    if (mutation.name === "srcset" && mutation.value.includes(WEB_ASSET_SCHEME)) {
+        const parts = mutation.value.split(",").map((part) => part.trim());
+        const out = [];
+        for (const part of parts) {
+            const bits = part.split(/\s+/);
+            const url = bits[0] ?? "";
+            if (!url.startsWith(WEB_ASSET_SCHEME)) {
+                out.push(part);
+                continue;
+            }
+            const code = url.slice(WEB_ASSET_SCHEME.length);
+            const { data, contentType } = await downloadAsset(authorization, code);
+            const blobUrl = URL.createObjectURL(new Blob([new Uint8Array(data)], { type: contentType }));
+            out.push([blobUrl, ...bits.slice(1)].join(" "));
+        }
+        return { ...mutation, value: out.join(", ") };
+    }
+    if ((mutation.name === "src" || mutation.name === "poster" || mutation.name === "href")
+        && mutation.value.startsWith(WEB_ASSET_SCHEME)) {
+        const code = mutation.value.slice(WEB_ASSET_SCHEME.length);
+        const { data, contentType } = await downloadAsset(authorization, code);
+        const blobUrl = URL.createObjectURL(new Blob([new Uint8Array(data)], { type: contentType }));
+        return { ...mutation, value: blobUrl };
+    }
+    return mutation;
+}

package/dist/src/extensions/web/tools.d.ts

@@ -0,0 +1,13 @@
+import type { Tool } from "../../parrot/generative.js";
+import type { WebRoom } from "../../marmot/web.js";
+export type PageToolName = "read_page_html" | "read_page_text" | "read_selection";
+export type PageToolHandler = (name: PageToolName, params: Record<string, unknown>) => Promise<string>;
+/**
+ * Host-side executors against the live document. Not ChatRoom-native — the web
+ * room (or content script) owns fulfillment.
+ */
+export declare function createHostPageToolHandler(root?: Node): PageToolHandler;
+/** Parrot `Tool[]` wired through a web-room invoke (or local host handler). */
+export declare function pageTools(invoke: (name: PageToolName, params: Record<string, unknown>) => Promise<string>): Tool[];
+/** Bind host tool fulfillment on a connected WebRoom. */
+export declare function attachHostTools(room: WebRoom, handler: PageToolHandler): () => void;

package/dist/src/extensions/web/tools.js

@@ -0,0 +1,72 @@
+import { toHtml } from "../../marmot/web.js";
+const MAX_HTML = 200000;
+const MAX_TEXT = 80000;
+/**
+ * Host-side executors against the live document. Not ChatRoom-native — the web
+ * room (or content script) owns fulfillment.
+ */
+export function createHostPageToolHandler(root = document.documentElement) {
+    return async (name, params) => {
+        switch (name) {
+            case "read_page_html": {
+                const { html } = toHtml(root);
+                const clipped = html.length > MAX_HTML ? html.slice(0, MAX_HTML) + "\n<!-- truncated -->" : html;
+                return clipped;
+            }
+            case "read_page_text": {
+                const el = root.nodeType === Node.ELEMENT_NODE
+                    ? root
+                    : document.body;
+                const text = (el.textContent ?? "").replace(/\s+/g, " ").trim();
+                return text.length > MAX_TEXT ? text.slice(0, MAX_TEXT) + "…" : text;
+            }
+            case "read_selection": {
+                const sel = typeof window !== "undefined" ? window.getSelection()?.toString() ?? "" : "";
+                const max = typeof params.max === "number" ? params.max : MAX_TEXT;
+                return sel.slice(0, max) || "(no selection)";
+            }
+            default:
+                return `Unknown page tool: ${name}`;
+        }
+    };
+}
+/** Parrot `Tool[]` wired through a web-room invoke (or local host handler). */
+export function pageTools(invoke) {
+    return [
+        {
+            function: {
+                name: "read_page_html",
+                description: "Read the cleaned HTML of the currently shared page.",
+                parameters: { type: "OBJECT", properties: {} },
+            },
+            evaluate: async () => invoke("read_page_html", {}),
+        },
+        {
+            function: {
+                name: "read_page_text",
+                description: "Read the visible text of the currently shared page.",
+                parameters: { type: "OBJECT", properties: {} },
+            },
+            evaluate: async () => invoke("read_page_text", {}),
+        },
+        {
+            function: {
+                name: "read_selection",
+                description: "Read the host's current text selection on the shared page.",
+                parameters: {
+                    type: "OBJECT",
+                    properties: {
+                        max: { type: "INTEGER", description: "Max characters to return." },
+                    },
+                },
+            },
+            evaluate: async (params) => invoke("read_selection", params ?? {}),
+        },
+    ];
+}
+/** Bind host tool fulfillment on a connected WebRoom. */
+export function attachHostTools(room, handler) {
+    return room.setToolHandler(async (name, params) => {
+        return handler(name, params ?? {});
+    });
+}

package/dist/src/friends.d.ts

@@ -0,0 +1,39 @@
+import { ApiKey, Credentials, Profile } from "./authentification.js";
+import { ChatSummary } from "./parrot/chat.js";
+/** Someone you have people only chats with. Open a chat with `UI.Chat.Chat` and its id. */
+export type Friend = {
+    id: string;
+    person: Profile;
+    /** Under Hidden: they started at no trust while you hide strangers, and you haven't replied or shown them. */
+    hidden: boolean;
+    chats: ChatSummary[];
+    created: Date;
+};
+export type Settings = {
+    /** Keep chats from people you have no trust in under Hidden until you reply or show them. On by default. */
+    hideStrangers: boolean;
+};
+/** How much you trust someone or a group (`credentials:{id}`, `group:{id}`), in [0, 1). */
+export type TrustEdge = {
+    target: string;
+    weight: number;
+};
+/** Your friends, each with your chats together and what you haven't read. An API key reads them too. */
+export declare function list(authorization: Credentials | ApiKey): Promise<Friend[]>;
+/** Start a chat with someone by their Fauna email. The first chat makes you friends. */
+export declare function startChat(credentials: Credentials, email: string, name?: string): Promise<{
+    friend: Friend;
+    chat: string;
+}>;
+/** Another chat with a friend. Resolves to its id. */
+export declare function createChat(credentials: Credentials, friend: string, name?: string): Promise<string>;
+/** Delete a chat with a friend, for both of you. */
+export declare function deleteChat(credentials: Credentials, friend: string, chat: string): Promise<void>;
+/** Bring a hidden friend out of Hidden. */
+export declare function show(credentials: Credentials, friend: string): Promise<Friend>;
+/** End a friendship. Its chats and their files go with it, for both of you. */
+export declare function end(credentials: Credentials, friend: string): Promise<void>;
+export declare function settings(credentials: Credentials): Promise<Settings>;
+export declare function updateSettings(credentials: Credentials, update: Partial<Settings>): Promise<Settings>;
+/** Your own trust edges, strongest first. Nobody else can read them; your API keys can. */
+export declare function trust(authorization: Credentials | ApiKey): Promise<TrustEdge[]>;