@freqhole/haruspex 0.0.0

package/dist/protocol/client.test.js

@@ -0,0 +1,282 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { createFriendzClient, } from "./client.js";
+const ALPN = "freqhole-friendz/1";
+/** a minimal async queue backing an in-memory duplex BiStreamLike pair. */
+function createQueue() {
+    const items = [];
+    const waiters = [];
+    let closed = false;
+    return {
+        push(item) {
+            if (closed)
+                return;
+            const waiter = waiters.shift();
+            if (waiter)
+                waiter(item);
+            else
+                items.push(item);
+        },
+        pop() {
+            if (items.length > 0)
+                return Promise.resolve(items.shift());
+            if (closed)
+                return Promise.resolve(null);
+            return new Promise((resolve) => waiters.push(resolve));
+        },
+        close() {
+            closed = true;
+            while (waiters.length > 0)
+                waiters.shift()(null);
+        },
+    };
+}
+/** two BiStreamLike ends wired to each other - no real transport involved. */
+function createDuplexPair(nodeIdA, nodeIdB) {
+    const aToB = createQueue();
+    const bToA = createQueue();
+    const streamA = {
+        peer_node_id: () => nodeIdB,
+        alpn: () => ALPN,
+        write_message: async (data) => {
+            aToB.push(data);
+        },
+        read_message: () => bToA.pop(),
+        close: () => {
+            aToB.close();
+        },
+    };
+    const streamB = {
+        peer_node_id: () => nodeIdA,
+        alpn: () => ALPN,
+        write_message: async (data) => {
+            bToA.push(data);
+        },
+        read_message: () => aToB.pop(),
+        close: () => {
+            bToA.close();
+        },
+    };
+    return { streamA, streamB };
+}
+function flush() {
+    return new Promise((resolve) => setTimeout(resolve, 0));
+}
+let clients = [];
+function track(client) {
+    clients.push(client);
+    return client;
+}
+afterEach(() => {
+    for (const client of clients)
+        client.destroy();
+    clients = [];
+    vi.useRealTimers();
+});
+describe("createFriendzClient", () => {
+    it("delivers a message sent from an opened stream to the accepting side", async () => {
+        const { streamA, streamB } = createDuplexPair("node-a", "node-b");
+        const received = [];
+        const nodeB = track(createFriendzClient({
+            getNode: async () => {
+                throw new Error("node B never opens outbound in this test");
+            },
+            localNodeId: "node-b",
+            localUsername: "bob",
+            onMessage: (message, fromNodeId) => received.push({ message, fromNodeId }),
+        }));
+        nodeB.handleIncomingStream(streamB);
+        const nodeA = track(createFriendzClient({
+            getNode: async () => ({
+                node_id: () => "node-a",
+                open_bi: async () => streamA,
+            }),
+            localNodeId: "node-a",
+            localUsername: "alice",
+        }));
+        await nodeA.sendMessage("node-b", {
+            kind: "core",
+            message: {
+                type: "knock-request",
+                v: 1,
+                knockId: "k1",
+                nodeId: "node-a",
+                message: "hi",
+                scope: { kind: "browse" },
+            },
+        });
+        await flush();
+        expect(received).toHaveLength(1);
+        expect(received[0].fromNodeId).toBe("node-a");
+        expect(received[0].message).toMatchObject({
+            kind: "core",
+            message: { type: "knock-request", knockId: "k1" },
+        });
+    });
+    it("reuses an already-open stream instead of opening a new one", async () => {
+        const { streamA, streamB } = createDuplexPair("node-a", "node-b");
+        const nodeB = track(createFriendzClient({
+            getNode: async () => {
+                throw new Error("unused");
+            },
+            localNodeId: "node-b",
+            localUsername: "bob",
+        }));
+        nodeB.handleIncomingStream(streamB);
+        let opens = 0;
+        const nodeA = track(createFriendzClient({
+            getNode: async () => ({
+                node_id: () => "node-a",
+                open_bi: async () => {
+                    opens += 1;
+                    return streamA;
+                },
+            }),
+            localNodeId: "node-a",
+            localUsername: "alice",
+        }));
+        const msg = {
+            kind: "core",
+            message: { type: "offline-announcement", v: 1, nodeId: "node-a" },
+        };
+        await nodeA.sendMessage("node-b", msg);
+        await nodeA.sendMessage("node-b", msg);
+        expect(opens).toBe(1);
+    });
+    it("marks a peer online on receiving a heartbeat and fires onPeerBecameOnline once", async () => {
+        const { streamA, streamB } = createDuplexPair("node-a", "node-b");
+        const becameOnline = [];
+        const nodeB = track(createFriendzClient({
+            getNode: async () => {
+                throw new Error("unused");
+            },
+            localNodeId: "node-b",
+            localUsername: "bob",
+            onPeerBecameOnline: (nodeId) => becameOnline.push(nodeId),
+        }));
+        nodeB.handleIncomingStream(streamB);
+        const nodeA = track(createFriendzClient({
+            getNode: async () => ({
+                node_id: () => "node-a",
+                open_bi: async () => streamA,
+            }),
+            localNodeId: "node-a",
+            localUsername: "alice",
+        }));
+        expect(nodeB.isOnline("node-a")).toBe(false);
+        await nodeA.sendMessage("node-a", {
+            kind: "core",
+            message: { type: "heartbeat", v: 1, nodeId: "node-a", username: "alice" },
+        });
+        await flush();
+        expect(nodeB.isOnline("node-a")).toBe(true);
+        expect(nodeB.getOnlinePeers()).toEqual(["node-a"]);
+        expect(becameOnline).toEqual(["node-a"]);
+    });
+    it("marks a peer offline on an explicit offline-announcement", async () => {
+        const { streamA, streamB } = createDuplexPair("node-a", "node-b");
+        const wentOffline = [];
+        const nodeB = track(createFriendzClient({
+            getNode: async () => {
+                throw new Error("unused");
+            },
+            localNodeId: "node-b",
+            localUsername: "bob",
+            onPeerWentOffline: (nodeId) => wentOffline.push(nodeId),
+        }));
+        nodeB.handleIncomingStream(streamB);
+        const nodeA = track(createFriendzClient({
+            getNode: async () => ({
+                node_id: () => "node-a",
+                open_bi: async () => streamA,
+            }),
+            localNodeId: "node-a",
+            localUsername: "alice",
+        }));
+        await nodeA.sendMessage("node-a", {
+            kind: "core",
+            message: { type: "heartbeat", v: 1, nodeId: "node-a", username: "alice" },
+        });
+        await flush();
+        expect(nodeB.isOnline("node-a")).toBe(true);
+        await nodeA.sendMessage("node-a", {
+            kind: "core",
+            message: { type: "offline-announcement", v: 1, nodeId: "node-a" },
+        });
+        await flush();
+        expect(nodeB.isOnline("node-a")).toBe(false);
+        expect(wentOffline).toEqual(["node-a"]);
+    });
+    it("calls onDecodeError instead of throwing when a peer sends garbage bytes", async () => {
+        const { streamA, streamB } = createDuplexPair("node-a", "node-b");
+        const errors = [];
+        const nodeB = track(createFriendzClient({
+            getNode: async () => {
+                throw new Error("unused");
+            },
+            localNodeId: "node-b",
+            localUsername: "bob",
+            onDecodeError: (error) => errors.push(error),
+        }));
+        nodeB.handleIncomingStream(streamB);
+        await streamA.write_message(new TextEncoder().encode("not json"));
+        await flush();
+        expect(errors).toHaveLength(1);
+    });
+    it("startHeartbeat sends an immediate heartbeat and stopHeartbeat halts further ticks", async () => {
+        vi.useFakeTimers();
+        const { streamA, streamB } = createDuplexPair("node-a", "node-b");
+        const received = [];
+        const nodeB = track(createFriendzClient({
+            getNode: async () => {
+                throw new Error("unused");
+            },
+            localNodeId: "node-b",
+            localUsername: "bob",
+            onMessage: (message) => received.push(message),
+        }));
+        nodeB.handleIncomingStream(streamB);
+        const nodeA = track(createFriendzClient({
+            getNode: async () => ({
+                node_id: () => "node-a",
+                open_bi: async () => streamA,
+            }),
+            localNodeId: "node-a",
+            localUsername: "alice",
+            heartbeatIntervalMs: 1000,
+        }));
+        nodeA.startHeartbeat(() => ["node-b"]);
+        await vi.advanceTimersByTimeAsync(0);
+        expect(received).toHaveLength(1);
+        nodeA.stopHeartbeat();
+        await vi.advanceTimersByTimeAsync(5000);
+        expect(received).toHaveLength(1);
+    });
+    it("destroy() closes streams and clears online state without throwing", async () => {
+        const { streamA, streamB } = createDuplexPair("node-a", "node-b");
+        const nodeB = createFriendzClient({
+            getNode: async () => {
+                throw new Error("unused");
+            },
+            localNodeId: "node-b",
+            localUsername: "bob",
+        });
+        nodeB.handleIncomingStream(streamB);
+        const nodeA = createFriendzClient({
+            getNode: async () => ({
+                node_id: () => "node-a",
+                open_bi: async () => streamA,
+            }),
+            localNodeId: "node-a",
+            localUsername: "alice",
+        });
+        await nodeA.sendMessage("node-a", {
+            kind: "core",
+            message: { type: "heartbeat", v: 1, nodeId: "node-a", username: "alice" },
+        });
+        await flush();
+        expect(nodeB.isOnline("node-a")).toBe(true);
+        expect(() => nodeA.destroy()).not.toThrow();
+        expect(() => nodeB.destroy()).not.toThrow();
+        expect(nodeB.getOnlinePeers()).toEqual([]);
+    });
+});

package/dist/protocol/codec.d.ts

@@ -0,0 +1,45 @@
+import { type CoreMessage } from "./messages.js";
+import { type AppExtensionMessage } from "./extensions.js";
+/**
+ * the full friendz protocol message set, decoded: every core (unified)
+ * message, tagged as such, or a namespaced app-extension passthrough this
+ * package never inspects the shape of.
+ */
+export type FriendzMessage = {
+    kind: "core";
+    message: CoreMessage;
+} | ({
+    kind: "app-extension";
+} & AppExtensionMessage);
+/** the wire `type` discriminant of a decoded message, for logging/dispatch. */
+export declare function friendzMessageType(msg: FriendzMessage): string;
+/**
+ * validate + decode a raw json value (already parsed, not yet bytes) into
+ * a FriendzMessage. a `type` containing `:` is routed to the app-extension
+ * passthrough without inspecting its payload shape further; anything else
+ * is validated against the core message union and is a real protocol
+ * error (thrown) if it matches no core variant.
+ */
+export declare function decodeFriendzMessage(raw: unknown): FriendzMessage;
+/** flatten a FriendzMessage back to the plain json object the wire sends. */
+export declare function encodeFriendzMessageToJson(msg: FriendzMessage): Record<string, unknown>;
+/** encode a message to its utf-8 json wire bytes, unframed. */
+export declare function encodeMessage(msg: FriendzMessage): Uint8Array;
+/** parse utf-8 json wire bytes into a validated, decoded FriendzMessage. */
+export declare function decodeMessage(bytes: Uint8Array): FriendzMessage;
+/** encode a message as one length-delimited frame: a 4-byte be length + payload. */
+export declare function frameMessage(msg: FriendzMessage): Uint8Array;
+/**
+ * accumulates bytes fed via push() and yields fully-framed messages as
+ * they complete - handles a message arriving split across multiple reads
+ * (typical for a raw byte stream) or several messages arriving in one
+ * chunk.
+ */
+export declare class FrameReader {
+    private buffer;
+    /** feed newly received bytes in; returns every message that completed. */
+    push(chunk: Uint8Array): FriendzMessage[];
+    /** bytes buffered so far that don't yet form a complete frame. */
+    pendingByteLength(): number;
+}
+//# sourceMappingURL=codec.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"codec.d.ts","sourceRoot":"","sources":["../../src/protocol/codec.ts"],"names":[],"mappings":"AAUA,OAAO,EAAwC,KAAK,WAAW,EAAE,MAAM,eAAe,CAAC;AACvF,OAAO,EAAsB,KAAK,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAE/E;;;;GAIG;AACH,MAAM,MAAM,cAAc,GACtB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,WAAW,CAAA;CAAE,GACtC,CAAC;IAAE,IAAI,EAAE,eAAe,CAAA;CAAE,GAAG,mBAAmB,CAAC,CAAC;AAEtD,+EAA+E;AAC/E,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,cAAc,GAAG,MAAM,CAE9D;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,OAAO,GAAG,cAAc,CAoBjE;AAED,6EAA6E;AAC7E,wBAAgB,0BAA0B,CAAC,GAAG,EAAE,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAEvF;AAKD,+DAA+D;AAC/D,wBAAgB,aAAa,CAAC,GAAG,EAAE,cAAc,GAAG,UAAU,CAE7D;AAED,4EAA4E;AAC5E,wBAAgB,aAAa,CAAC,KAAK,EAAE,UAAU,GAAG,cAAc,CAS/D;AAYD,oFAAoF;AACpF,wBAAgB,YAAY,CAAC,GAAG,EAAE,cAAc,GAAG,UAAU,CAM5D;AAED;;;;;GAKG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,MAAM,CAAqB;IAEnC,0EAA0E;IAC1E,IAAI,CAAC,KAAK,EAAE,UAAU,GAAG,cAAc,EAAE;IAkBzC,kEAAkE;IAClE,iBAAiB,IAAI,MAAM;CAG5B"}

package/dist/protocol/codec.js

@@ -0,0 +1,111 @@
+// friendz message codec: json wire encode/decode plus a length-delimited
+// framing layer for transports that give raw bytes with no message
+// boundaries of their own.
+//
+// the 20 rust fixture files (haruspex/rust/fixtures/protocol/) are the
+// pre-framing json payload shape - not length-delimited bytes - so
+// decodeMessage/encodeMessage below operate on that same json shape, and
+// framing is a separate, optional layer on top for callers whose
+// transport needs it.
+import { CoreMessageSchema, isCoreMessageType } from "./messages.js";
+import { isAppExtensionType } from "./extensions.js";
+/** the wire `type` discriminant of a decoded message, for logging/dispatch. */
+export function friendzMessageType(msg) {
+    return msg.kind === "core" ? msg.message.type : msg.messageType;
+}
+/**
+ * validate + decode a raw json value (already parsed, not yet bytes) into
+ * a FriendzMessage. a `type` containing `:` is routed to the app-extension
+ * passthrough without inspecting its payload shape further; anything else
+ * is validated against the core message union and is a real protocol
+ * error (thrown) if it matches no core variant.
+ */
+export function decodeFriendzMessage(raw) {
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+        throw new Error("friendz message must be a json object");
+    }
+    const obj = raw;
+    const type = obj["type"];
+    if (typeof type !== "string" || type.length === 0) {
+        throw new Error("friendz message is missing a string 'type' field");
+    }
+    if (isAppExtensionType(type)) {
+        return { kind: "app-extension", messageType: type, payload: obj };
+    }
+    if (!isCoreMessageType(type)) {
+        throw new Error(`unknown friendz message type "${type}"`);
+    }
+    const message = CoreMessageSchema.parse(obj);
+    return { kind: "core", message };
+}
+/** flatten a FriendzMessage back to the plain json object the wire sends. */
+export function encodeFriendzMessageToJson(msg) {
+    return msg.kind === "core" ? msg.message : msg.payload;
+}
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+/** encode a message to its utf-8 json wire bytes, unframed. */
+export function encodeMessage(msg) {
+    return encoder.encode(JSON.stringify(encodeFriendzMessageToJson(msg)));
+}
+/** parse utf-8 json wire bytes into a validated, decoded FriendzMessage. */
+export function decodeMessage(bytes) {
+    const text = decoder.decode(bytes);
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch {
+        throw new Error("friendz message bytes are not valid json");
+    }
+    return decodeFriendzMessage(raw);
+}
+// ---------------------------------------------------------------------------
+// length-delimited framing
+//
+// for a transport that hands over raw bytes with no message-boundary
+// framing of its own (unlike a midden BiStream, whose write_message/
+// read_message already frame each call - see client.ts). a 4-byte
+// big-endian u32 length prefix precedes each encoded message, matching
+// this workspace's existing length-delimited wire convention.
+// ---------------------------------------------------------------------------
+/** encode a message as one length-delimited frame: a 4-byte be length + payload. */
+export function frameMessage(msg) {
+    const payload = encodeMessage(msg);
+    const frame = new Uint8Array(4 + payload.byteLength);
+    new DataView(frame.buffer).setUint32(0, payload.byteLength, false);
+    frame.set(payload, 4);
+    return frame;
+}
+/**
+ * accumulates bytes fed via push() and yields fully-framed messages as
+ * they complete - handles a message arriving split across multiple reads
+ * (typical for a raw byte stream) or several messages arriving in one
+ * chunk.
+ */
+export class FrameReader {
+    buffer = new Uint8Array(0);
+    /** feed newly received bytes in; returns every message that completed. */
+    push(chunk) {
+        const merged = new Uint8Array(this.buffer.byteLength + chunk.byteLength);
+        merged.set(this.buffer, 0);
+        merged.set(chunk, this.buffer.byteLength);
+        this.buffer = merged;
+        const messages = [];
+        for (;;) {
+            if (this.buffer.byteLength < 4)
+                break;
+            const length = new DataView(this.buffer.buffer, this.buffer.byteOffset).getUint32(0, false);
+            if (this.buffer.byteLength < 4 + length)
+                break;
+            const payload = this.buffer.subarray(4, 4 + length);
+            messages.push(decodeMessage(payload));
+            this.buffer = this.buffer.subarray(4 + length);
+        }
+        return messages;
+    }
+    /** bytes buffered so far that don't yet form a complete frame. */
+    pendingByteLength() {
+        return this.buffer.byteLength;
+    }
+}

package/dist/protocol/codec.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=codec.test.d.ts.map

package/dist/protocol/codec.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codec.test.d.ts","sourceRoot":"","sources":["../../src/protocol/codec.test.ts"],"names":[],"mappings":""}

package/dist/protocol/codec.test.js

@@ -0,0 +1,93 @@
+import { describe, expect, it } from "vitest";
+import { FrameReader, decodeFriendzMessage, decodeMessage, encodeFriendzMessageToJson, encodeMessage, frameMessage, friendzMessageType, } from "./codec.js";
+const heartbeat = {
+    kind: "core",
+    message: { type: "heartbeat", v: 1, nodeId: "node-abc", username: "alice" },
+};
+const extension = {
+    kind: "app-extension",
+    messageType: "skein:canvas-invite",
+    payload: { v: 1, type: "skein:canvas-invite", inviteId: "inv-1" },
+};
+describe("decodeFriendzMessage", () => {
+    it("throws on a non-object value", () => {
+        expect(() => decodeFriendzMessage("nope")).toThrow(/json object/);
+        expect(() => decodeFriendzMessage(null)).toThrow();
+        expect(() => decodeFriendzMessage([1, 2])).toThrow();
+    });
+    it("throws when 'type' is missing or not a string", () => {
+        expect(() => decodeFriendzMessage({})).toThrow(/type/);
+        expect(() => decodeFriendzMessage({ type: 5 })).toThrow();
+    });
+    it("throws on an unrecognized non-namespaced type", () => {
+        expect(() => decodeFriendzMessage({ type: "not-a-real-type" })).toThrow(/unknown/);
+    });
+    it("routes a namespaced type to the app-extension passthrough", () => {
+        const message = decodeFriendzMessage({ type: "skein:canvas-invite", foo: "bar" });
+        expect(message).toEqual({
+            kind: "app-extension",
+            messageType: "skein:canvas-invite",
+            payload: { type: "skein:canvas-invite", foo: "bar" },
+        });
+    });
+});
+describe("friendzMessageType", () => {
+    it("returns the core message's type", () => {
+        expect(friendzMessageType(heartbeat)).toBe("heartbeat");
+    });
+    it("returns the app-extension's messageType", () => {
+        expect(friendzMessageType(extension)).toBe("skein:canvas-invite");
+    });
+});
+describe("encodeFriendzMessageToJson", () => {
+    it("flattens a core message back to its plain wire shape", () => {
+        expect(encodeFriendzMessageToJson(heartbeat)).toEqual(heartbeat.message);
+    });
+    it("flattens an app-extension message back to its raw payload", () => {
+        expect(encodeFriendzMessageToJson(extension)).toEqual(extension.payload);
+    });
+});
+describe("encodeMessage / decodeMessage", () => {
+    it("round-trips a core message through utf-8 json bytes", () => {
+        const bytes = encodeMessage(heartbeat);
+        expect(decodeMessage(bytes)).toEqual(heartbeat);
+    });
+    it("round-trips an app-extension message through utf-8 json bytes", () => {
+        const bytes = encodeMessage(extension);
+        expect(decodeMessage(bytes)).toEqual(extension);
+    });
+    it("throws decodeMessage on non-json bytes", () => {
+        const bytes = new TextEncoder().encode("not json at all {");
+        expect(() => decodeMessage(bytes)).toThrow(/not valid json/);
+    });
+});
+describe("frameMessage / FrameReader", () => {
+    it("decodes a single complete frame delivered whole", () => {
+        const reader = new FrameReader();
+        const frame = frameMessage(heartbeat);
+        expect(reader.push(frame)).toEqual([heartbeat]);
+        expect(reader.pendingByteLength()).toBe(0);
+    });
+    it("decodes a frame split across multiple chunks", () => {
+        const reader = new FrameReader();
+        const frame = frameMessage(heartbeat);
+        const mid = Math.floor(frame.byteLength / 2);
+        expect(reader.push(frame.subarray(0, mid))).toEqual([]);
+        expect(reader.pendingByteLength()).toBe(mid);
+        expect(reader.push(frame.subarray(mid))).toEqual([heartbeat]);
+    });
+    it("decodes multiple frames delivered in one chunk", () => {
+        const reader = new FrameReader();
+        const a = frameMessage(heartbeat);
+        const b = frameMessage(extension);
+        const combined = new Uint8Array(a.byteLength + b.byteLength);
+        combined.set(a, 0);
+        combined.set(b, a.byteLength);
+        expect(reader.push(combined)).toEqual([heartbeat, extension]);
+    });
+    it("waits for the length prefix itself to arrive before decoding anything", () => {
+        const reader = new FrameReader();
+        expect(reader.push(new Uint8Array([0, 0]))).toEqual([]);
+        expect(reader.pendingByteLength()).toBe(2);
+    });
+});

package/dist/protocol/extensions.d.ts

@@ -0,0 +1,33 @@
+import type { z } from "zod";
+/** a namespaced app-extension message: the raw payload, unparsed. */
+export interface AppExtensionMessage {
+    /** the wire `type` string, e.g. "skein:canvas-invite". */
+    messageType: string;
+    /** the full received json object, including `type` and `v`. */
+    payload: Record<string, unknown>;
+}
+/** does `type` look like an app-extension message (has a `:` in it)? */
+export declare function isAppExtensionType(type: string): boolean;
+/**
+ * a registry of zod schemas for app-extension message types, keyed by the
+ * exact wire `type` string. lets a consuming app parse its own extension
+ * payloads with real types instead of a raw `Record<string, unknown>`.
+ */
+export interface AppExtensionRegistry {
+    /** register a schema for one exact message type (e.g. "skein:canvas-invite"). */
+    register<T>(messageType: string, schema: z.ZodType<T>): void;
+    /** remove a previously registered schema. */
+    unregister(messageType: string): void;
+    /** is a schema registered for this message type? */
+    isRegistered(messageType: string): boolean;
+    /**
+     * parse an app-extension message's payload against its registered
+     * schema. throws if no schema is registered, or if the payload doesn't
+     * match - use `isRegistered` first to fall back to the raw payload
+     * instead of throwing.
+     */
+    parse<T = unknown>(message: AppExtensionMessage): T;
+}
+/** create a fresh, empty app-extension registry. */
+export declare function createAppExtensionRegistry(): AppExtensionRegistry;
+//# sourceMappingURL=extensions.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"extensions.d.ts","sourceRoot":"","sources":["../../src/protocol/extensions.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAE7B,qEAAqE;AACrE,MAAM,WAAW,mBAAmB;IAClC,0DAA0D;IAC1D,WAAW,EAAE,MAAM,CAAC;IACpB,+DAA+D;IAC/D,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAED,wEAAwE;AACxE,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAExD;AAED;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACnC,iFAAiF;IACjF,QAAQ,CAAC,CAAC,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IAC7D,6CAA6C;IAC7C,UAAU,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IACtC,oDAAoD;IACpD,YAAY,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC;IAC3C;;;;;OAKG;IACH,KAAK,CAAC,CAAC,GAAG,OAAO,EAAE,OAAO,EAAE,mBAAmB,GAAG,CAAC,CAAC;CACrD;AAED,oDAAoD;AACpD,wBAAgB,0BAA0B,IAAI,oBAAoB,CAqBjE"}

package/dist/protocol/extensions.js

@@ -0,0 +1,36 @@
+// the app-extension mechanism: an unknown `type` string containing a `:`
+// (e.g. "skein:canvas-invite", "playlistz:list-playlists") is a namespaced
+// message this package never inspects the shape of - only the framing and
+// the `:`-prefixed routing convention belong to it. a `type` with no `:`
+// that doesn't match any core message is a real protocol error instead
+// (see codec.ts's decodeFriendzMessage).
+//
+// an app registers a zod schema for its own extension message types here,
+// so it can parse a received app-extension payload with its own shape
+// without forking this package.
+/** does `type` look like an app-extension message (has a `:` in it)? */
+export function isAppExtensionType(type) {
+    return type.includes(":");
+}
+/** create a fresh, empty app-extension registry. */
+export function createAppExtensionRegistry() {
+    const schemas = new Map();
+    return {
+        register(messageType, schema) {
+            schemas.set(messageType, schema);
+        },
+        unregister(messageType) {
+            schemas.delete(messageType);
+        },
+        isRegistered(messageType) {
+            return schemas.has(messageType);
+        },
+        parse(message) {
+            const schema = schemas.get(message.messageType);
+            if (!schema) {
+                throw new Error(`no schema registered for app-extension type "${message.messageType}"`);
+            }
+            return schema.parse(message.payload);
+        },
+    };
+}

package/dist/protocol/extensions.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=extensions.test.d.ts.map

package/dist/protocol/extensions.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extensions.test.d.ts","sourceRoot":"","sources":["../../src/protocol/extensions.test.ts"],"names":[],"mappings":""}