@peers-app/peers-sdk 0.26.6 → 0.27.1

package/dist/serial-json.test.js

@@ -62,6 +62,321 @@ describe("serial-json", () => {
             expect(deserialized.bufferData).toEqual(originalBuffer);
         });
     });
+    // Signatures sign toJSON output (`canonicalJSONString` in keys.ts), so these strings are frozen.
+    describe("encoded form (pinned)", () => {
+        it("encodes each extended type as a sentinel string", () => {
+            const value = {
+                d: new Date("2023-01-01T00:00:00.000Z"),
+                u8: new Uint8Array([1, 2, 3]),
+                buf: Buffer.from([1, 2, 3]),
+                u: undefined,
+                nan: NaN,
+                inf: Infinity,
+                re: /a+b/gi,
+                n: null,
+                t: true,
+                s: "x",
+                num: 1.5,
+            };
+            const encoded = (0, serial_json_1.toJSONString)(value);
+            expect(encoded).toBe('{"d":"__DATE 2023-01-01T00:00:00.000Z","u8":"__UINT8ARRAY AQID","buf":"__BUFFER AQID",' +
+                '"u":"__UNDEFINED","nan":"__NAN","inf":"__INFINITY","re":"__REGEXP /a+b/gi","n":null,' +
+                '"t":true,"s":"x","num":1.5}');
+            const decoded = (0, serial_json_1.fromJSONString)(encoded);
+            expect(decoded.d).toEqual(value.d);
+            expect(decoded.u8).toBeInstanceOf(Uint8Array);
+            expect(Buffer.isBuffer(decoded.u8)).toBe(false);
+            expect(Buffer.isBuffer(decoded.buf)).toBe(true);
+            expect("u" in decoded).toBe(true);
+            expect(decoded.u).toBeUndefined();
+            expect(decoded.nan).toBeNaN();
+            expect(decoded.inf).toBe(Infinity);
+            expect(decoded.re).toEqual(/a+b/gi);
+            expect(decoded).toMatchObject({ n: null, t: true, s: "x", num: 1.5 });
+        });
+        it("encodes an Error as its stack and a function as one-way source text", () => {
+            const encoded = (0, serial_json_1.toJSON)({
+                e: new Error("boom"),
+                f: function named() {
+                    return 1;
+                },
+            });
+            expect(encoded.e).toMatch(/^__ERROR Error: boom\n/);
+            expect(encoded.f).toMatch(/^__FUNCTION function named\(\)/);
+            const decoded = (0, serial_json_1.fromJSON)(encoded);
+            expect(decoded.e).toBeInstanceOf(Error);
+            expect(decoded.e.stack).toBe(encoded.e.substring(8));
+            expect(decoded.f).toBe(encoded.f);
+        });
+        it("tags the first copy of a shared object and points the others at it", () => {
+            const shared = { s: 1 };
+            const encoded = (0, serial_json_1.toJSONString)({ a: shared, b: shared, c: [shared] });
+            expect(encoded).toBe('{"a":{"s":1,"__this_ref":"__duplicate_ref_obj_2"},"b":"__duplicate_ref_obj_2",' +
+                '"c":["__duplicate_ref_obj_2"]}');
+            const decoded = (0, serial_json_1.fromJSONString)(encoded);
+            expect(decoded.a).toEqual({ s: 1 });
+            expect(decoded.b).toBe(decoded.a);
+            expect(decoded.c[0]).toBe(decoded.a);
+        });
+        it("tags a shared array with an extra first element", () => {
+            const shared = ["a", "b"];
+            const encoded = (0, serial_json_1.toJSONString)({ x: shared, y: shared });
+            expect(encoded).toBe('{"x":["__this_ref:__duplicate_ref_ary_2","a","b"],"y":"__duplicate_ref_ary_2"}');
+            const decoded = (0, serial_json_1.fromJSONString)(encoded);
+            expect(decoded.x).toEqual(["a", "b"]);
+            expect(decoded.y).toBe(decoded.x);
+        });
+        it("encodes cycles, placing the tag wherever the copy has got to", () => {
+            const obj = { n: 1 };
+            obj.self = obj;
+            const list = [1];
+            list.push(list);
+            const root = { child: { grand: {} } };
+            root.child.grand.up = root;
+            expect((0, serial_json_1.toJSONString)(obj)).toBe('{"n":1,"__this_ref":"__duplicate_ref_obj_1","self":"__duplicate_ref_obj_1"}');
+            expect((0, serial_json_1.toJSONString)(list)).toBe('["__this_ref:__duplicate_ref_ary_1",1,"__duplicate_ref_ary_1"]');
+            expect((0, serial_json_1.toJSONString)(root)).toBe('{"__this_ref":"__duplicate_ref_obj_1","child":{"grand":{"up":"__duplicate_ref_obj_1"}}}');
+            const decodedObj = (0, serial_json_1.fromJSONString)((0, serial_json_1.toJSONString)(obj));
+            expect(decodedObj.self).toBe(decodedObj);
+            expect(decodedObj.n).toBe(1);
+            const decodedList = (0, serial_json_1.fromJSONString)((0, serial_json_1.toJSONString)(list));
+            expect(decodedList).toHaveLength(2);
+            expect(decodedList[1]).toBe(decodedList);
+            const decodedRoot = (0, serial_json_1.fromJSONString)((0, serial_json_1.toJSONString)(root));
+            expect(decodedRoot.child.grand.up).toBe(decodedRoot);
+        });
+        it("resolves a reference that appears before its target", () => {
+            const decoded = (0, serial_json_1.fromJSONString)('{"b":"__duplicate_ref_obj_2","a":{"k":1,"__this_ref":"__duplicate_ref_obj_2"}}');
+            expect(decoded.a).toEqual({ k: 1 });
+            expect(decoded.b).toBe(decoded.a);
+        });
+        it("escapes keys that start with $", () => {
+            const encoded = (0, serial_json_1.toJSONString)({ $a: 1, $: 2, plain: { $nested: 3 } });
+            expect(encoded).toBe('{"__DOLLAR_a":1,"__DOLLAR_":2,"plain":{"__DOLLAR_nested":3}}');
+            expect((0, serial_json_1.fromJSONString)(encoded)).toEqual({ $a: 1, $: 2, plain: { $nested: 3 } });
+        });
+        it("leaves top-level primitives alone", () => {
+            expect((0, serial_json_1.toJSON)(NaN)).toBeNaN();
+            expect((0, serial_json_1.toJSONString)(NaN)).toBe("null");
+            expect((0, serial_json_1.toJSON)(undefined)).toBeUndefined();
+            expect((0, serial_json_1.toJSONString)(undefined)).toBeUndefined();
+            expect((0, serial_json_1.toJSON)("__UNDEFINED")).toBe("__UNDEFINED");
+            expect((0, serial_json_1.toJSON)(5)).toBe(5);
+            expect((0, serial_json_1.toJSON)(new Date(0))).toBe("__DATE 1970-01-01T00:00:00.000Z");
+            expect((0, serial_json_1.fromJSON)("__DATE 1970-01-01T00:00:00.000Z")).toEqual(new Date(0));
+        });
+    });
+    // Behavior that is wrong or lossy today. Each test changes when its gap is fixed.
+    describe("known gaps (pinned until fixed)", () => {
+        it("decodes ordinary strings that look like markers as the marked value", () => {
+            // The orphan marker warns; restore so the spy doesn't leak into later tests.
+            const warn = jest.spyOn(console, "warn").mockImplementation(() => undefined);
+            const decoded = (0, serial_json_1.fromJSON)((0, serial_json_1.toJSON)({
+                u: "__UNDEFINED",
+                n: "__NAN",
+                d: "__DATE tomorrow",
+                e: "__ERROR oops",
+                r: "__duplicate_ref_obj_9",
+            }));
+            warn.mockRestore();
+            expect(decoded.u).toBeUndefined();
+            expect(decoded.n).toBeNaN();
+            expect(decoded.d).toBeInstanceOf(Date);
+            expect(decoded.d.getTime()).toBeNaN();
+            expect(decoded.e).toBeInstanceOf(Error);
+            expect(decoded.r).toEqual({});
+        });
+        it("turns a __DOLLAR_ key into a $ key", () => {
+            expect((0, serial_json_1.fromJSONString)((0, serial_json_1.toJSONString)({ __DOLLAR_b: 2 }))).toEqual({ $b: 2 });
+        });
+        it("treats a __this_ref key as a shared-reference tag unless its value is falsy", () => {
+            expect((0, serial_json_1.fromJSONString)((0, serial_json_1.toJSONString)({ __this_ref: "mine", a: 1 }))).toEqual({ a: 1 });
+            expect((0, serial_json_1.fromJSONString)((0, serial_json_1.toJSONString)({ __this_ref: "", a: 1 }))).toEqual({
+                __this_ref: "",
+                a: 1,
+            });
+        });
+        it("loses -Infinity and -0 in JSON text", () => {
+            expect((0, serial_json_1.toJSONString)({ a: -Infinity, z: -0 })).toBe('{"a":null,"z":0}');
+        });
+        it("stores Map, Set and class instances as plain objects", () => {
+            class Point {
+                x = 1;
+            }
+            const encoded = (0, serial_json_1.toJSONString)({ m: new Map([[1, 2]]), s: new Set([1]), p: new Point() });
+            expect(encoded).toBe('{"m":{},"s":{},"p":{"x":1}}');
+            expect(Object.getPrototypeOf((0, serial_json_1.fromJSONString)(encoded).p)).toBe(Object.prototype);
+        });
+        it("drops symbols and throws on BigInt and invalid dates", () => {
+            expect((0, serial_json_1.toJSONString)({ s: Symbol("x"), a: [Symbol("y")] })).toBe('{"a":[null]}');
+            expect(() => (0, serial_json_1.toJSONString)({ b: BigInt(1) })).toThrow(TypeError);
+            expect(() => (0, serial_json_1.toJSONString)({ d: new Date(Number.NaN) })).toThrow(RangeError);
+        });
+        it("throws SyntaxError on a malformed regular expression", () => {
+            // working/tools/foreman/test/host.test.mjs relies on this error.
+            expect(() => (0, serial_json_1.fromJSON)("__REGEXP /[/")).toThrow(SyntaxError);
+        });
+    });
+    // Intended differences from the frozen oracle (serial-json.compat.test.ts covers the rest).
+    describe("decoding changes since the oracle", () => {
+        let warn;
+        beforeEach(() => {
+            warn = jest.spyOn(console, "warn").mockImplementation(() => undefined);
+        });
+        afterEach(() => {
+            warn.mockRestore();
+        });
+        it("returns values that are already decoded as they are", () => {
+            const value = {
+                bytes: new Uint8Array([1, 2]),
+                buffer: Buffer.from([3]),
+                error: new Error("boom"),
+                pattern: /x/g,
+                when: new Date(0),
+            };
+            const decoded = (0, serial_json_1.fromJSON)({ ...value, encoded: "__DATE 1970-01-01T00:00:00.000Z" });
+            for (const key of Object.keys(value)) {
+                expect(decoded[key]).toBe(value[key]);
+            }
+            expect(decoded.encoded).toEqual(new Date(0));
+        });
+        it("builds new arrays and objects and leaves the input untouched", () => {
+            const input = Object.freeze({
+                list: Object.freeze(["__this_ref:__duplicate_ref_ary_2", 1]),
+                tagged: Object.freeze({ __this_ref: "__duplicate_ref_obj_3", $: Object.freeze({}) }),
+                again: "__duplicate_ref_ary_2",
+            });
+            const decoded = (0, serial_json_1.fromJSON)(input);
+            expect(decoded).toEqual({ list: [1], tagged: { $: {} }, again: [1] });
+            expect(decoded.again).toBe(decoded.list);
+            expect(decoded.list).not.toBe(input.list);
+            expect(decoded.tagged).not.toBe(input.tagged);
+            expect(decoded.tagged.$).not.toBe(input.tagged.$);
+        });
+        it("copies untagged nested values instead of sharing live change values", () => {
+            const input = { nested: { list: [{ value: 1 }] } };
+            const decoded = (0, serial_json_1.fromJSON)(input);
+            decoded.nested.list[0].value = 2;
+            decoded.nested.list.push({});
+            expect(input).toEqual({ nested: { list: [{ value: 1 }] } });
+        });
+        it("does not let an object fill an array target, or an array an object target", () => {
+            // The oracle shared them, so `{"length":4e9}` under an array marker decoded to a huge
+            // array that hung whatever re-encoded or cloned it, and `{"length":-1}` threw.
+            const decoded = (0, serial_json_1.fromJSONString)('["__duplicate_ref_ary_1",{"__this_ref":"__duplicate_ref_ary_1","length":4000000000,"a":1},' +
+                '["__this_ref:__duplicate_ref_ary_1","last"],["__this_ref:__duplicate_ref_obj_1",1],' +
+                '{"__this_ref":"__duplicate_ref_obj_1","b":2}]');
+            expect(decoded[0]).toBe(decoded[2]);
+            expect(decoded[0]).toEqual(["last"]);
+            expect(decoded[1]).toEqual({ length: 4000000000, a: 1 });
+            expect(decoded[3]).toEqual([1]);
+            expect(decoded[4]).toEqual({ b: 2 });
+            expect(warn).not.toHaveBeenCalled();
+            expect((0, serial_json_1.fromJSONString)('["__duplicate_ref_ary_2",{"__this_ref":"__duplicate_ref_ary_2","length":-1}]')).toEqual([[], { length: -1 }]);
+            expect(warn).toHaveBeenCalledTimes(1);
+            expect(warn).toHaveBeenCalledWith(expect.stringContaining("__duplicate_ref_ary_2"));
+        });
+        it("warns about an object marker with only a rejected array tag", () => {
+            const marker = "__duplicate_ref_obj_rejected_array";
+            expect((0, serial_json_1.fromJSON)([marker, [`__this_ref:${marker}`, 1]])).toEqual([{}, [1]]);
+            (0, serial_json_1.fromJSON)([marker, [`__this_ref:${marker}`, 2]]);
+            expect(warn).toHaveBeenCalledTimes(1);
+            expect(warn).toHaveBeenCalledWith(expect.stringContaining(marker));
+        });
+        it("accepts a later matching tag after rejecting a conflicting tag", () => {
+            const marker = "__duplicate_ref_obj_later_target";
+            const decoded = (0, serial_json_1.fromJSON)([
+                marker,
+                [`__this_ref:${marker}`, 1],
+                { __this_ref: marker, value: 2 },
+            ]);
+            expect(decoded).toEqual([{ value: 2 }, [1], { value: 2 }]);
+            expect(decoded[0]).toBe(decoded[2]);
+            expect(warn).not.toHaveBeenCalled();
+        });
+        it("leaves the browser-only __HTML and __WINDOW sentinels as strings", () => {
+            expect((0, serial_json_1.fromJSON)({ html: "__HTML <b>x</b>", win: "__WINDOW" })).toEqual({
+                html: "__HTML <b>x</b>",
+                win: "__WINDOW",
+            });
+        });
+        it("warns once, in one string, about a marker with no target", () => {
+            const marker = "__duplicate_ref_obj_9001";
+            expect((0, serial_json_1.fromJSON)({ a: marker, b: { __this_ref: "__duplicate_ref_obj_9002" } })).toEqual({
+                a: {},
+                b: {},
+            });
+            (0, serial_json_1.fromJSON)({ again: marker });
+            expect(warn).toHaveBeenCalledTimes(1);
+            expect(warn.mock.calls[0]).toHaveLength(1);
+            expect(warn.mock.calls[0][0]).toContain(marker);
+            expect(warn.mock.calls[0][0]).not.toContain("9002");
+        });
+        it("does not warn about a marker whose target comes later", () => {
+            (0, serial_json_1.fromJSON)({ b: "__duplicate_ref_obj_9003", a: { __this_ref: "__duplicate_ref_obj_9003" } });
+            expect(warn).not.toHaveBeenCalled();
+        });
+        it("caps warnings at 100 distinct markers across calls", () => {
+            jest.isolateModules(() => {
+                const isolated = require("./serial-json");
+                for (let i = 0; i < 110; i++) {
+                    const marker = `__duplicate_ref_obj_cap_${i}`;
+                    isolated.fromJSON([marker, marker]);
+                    isolated.fromJSON(marker);
+                }
+                expect(warn).toHaveBeenCalledTimes(100);
+                expect(warn.mock.calls.every((args) => args.length === 1 && typeof args[0] === "string")).toBe(true);
+            });
+        });
+        it("can decode its warning through the log pipeline without warning again", () => {
+            warn.mockImplementation((message) => {
+                expect((0, serial_json_1.fromJSONString)((0, serial_json_1.toJSONString)({ message }))).toEqual({ message });
+            });
+            (0, serial_json_1.fromJSON)("__duplicate_ref_obj_log_pipeline");
+            expect(warn).toHaveBeenCalledTimes(1);
+        });
+    });
+    describe("untrusted input", () => {
+        afterEach(() => {
+            // A failing case must not leak a polluted prototype into later tests.
+            delete Object.prototype.polluted;
+            delete Object.prototype[0];
+            delete Object.polluted;
+        });
+        it("does not resolve an object's shared-reference tag to Object.prototype", () => {
+            const decoded = (0, serial_json_1.fromJSONString)('{"__this_ref":"__proto__","polluted":"yes"}');
+            expect({}.polluted).toBeUndefined();
+            expect(decoded).toEqual({ polluted: "yes" });
+        });
+        it("does not resolve an array's shared-reference tag to Object.prototype", () => {
+            const decoded = (0, serial_json_1.fromJSONString)('["__this_ref:__proto__","yes"]');
+            expect({}[0]).toBeUndefined();
+            expect(decoded).toEqual(["yes"]);
+        });
+        it("does not resolve a shared-reference tag to the Object constructor", () => {
+            const decoded = (0, serial_json_1.fromJSONString)('{"__this_ref":"constructor","polluted":"yes"}');
+            expect(Object.polluted).toBeUndefined();
+            expect(decoded).toEqual({ polluted: "yes" });
+        });
+        it("keeps constructor and prototype properties local to the decoded value", () => {
+            const decoded = (0, serial_json_1.fromJSONString)('{"constructor":{"prototype":{"polluted":"yes"}},"prototype":{"polluted":"yes"}}');
+            expect({}.polluted).toBeUndefined();
+            expect(Object.polluted).toBeUndefined();
+            expect(decoded.constructor.prototype.polluted).toBe("yes");
+        });
+        it("ignores a shared-reference tag that is an object instead of coercing it", () => {
+            const decoded = (0, serial_json_1.fromJSONString)('{"a":{"__this_ref":{"toString":"x"},"k":1},"b":{"__this_ref":{},"k":2}}');
+            expect(decoded).toEqual({ a: { k: 1 }, b: { k: 2 } });
+            expect(decoded.a).not.toBe(decoded.b);
+        });
+        it("drops __proto__ keys instead of setting the decoded object's prototype", () => {
+            const decoded = (0, serial_json_1.fromJSONString)('{"__proto__":{"polluted":"yes"},"b":{"__proto__":[]}}');
+            expect(Object.getPrototypeOf(decoded)).toBe(Object.prototype);
+            expect(Object.getPrototypeOf(decoded.b)).toBe(Object.prototype);
+            expect(decoded.polluted).toBeUndefined();
+            expect(Object.keys(decoded)).toEqual(["b"]);
+        });
+    });
     describe("existing functionality", () => {
         it("should still handle other special types", () => {
             const testObj = {

package/dist/testing/index.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Test helpers for package UIs: `@peers-app/peers-sdk/testing`. Not for UI or provider bundles.
+ */
+export { type IMockHostCall, type IMockHostContract, type IMockHostContractOptions, type IMockHostTable, mockHostContract, } from "./mock-host-contract";

package/dist/testing/index.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mockHostContract = void 0;
+/**
+ * Test helpers for package UIs: `@peers-app/peers-sdk/testing`. Not for UI or provider bundles.
+ */
+var mock_host_contract_1 = require("./mock-host-contract");
+Object.defineProperty(exports, "mockHostContract", { enumerable: true, get: function () { return mock_host_contract_1.mockHostContract; } });

package/dist/testing/mock-host-contract.d.ts

@@ -0,0 +1,123 @@
+import type { ContractEventPayloadsOf, ContractObservableValuesOf, ContractTableRowsOf } from "../define/contract-ref";
+import { type IContractDeclaration } from "../define/declare-contract";
+import { type IContractMembers, type IPackageContract } from "../define/define-package";
+import type { IPackageTableHandle } from "../define/table";
+import type { IPackageToolDeclaration } from "../define/tool";
+import { type Observable } from "../observable";
+type AnyContract = IPackageContract<any, any, any, any, any, any> | IContractDeclaration<any, any, any, any, any, any>;
+/** A contract's members: the contract itself, or a declaration's. */
+type MembersOf<C> = C extends {
+    readonly declaration: infer D;
+} ? D : C;
+type Row = Record<string, any>;
+/** A fake for one tool: it gets the input as the tool's schema parses it. */
+type ToolFake<T> = T extends IPackageToolDeclaration<any, infer O, any, infer P> ? (input: P) => O | Promise<O> : never;
+type ToolFakes<C> = MembersOf<C> extends IContractMembers<any, any, any, infer Tools, any, any> ? {
+    readonly [T in Tools[number] as T["definition"]["name"]]?: ToolFake<T>;
+} : never;
+/** One call a UI made to the mock host, as `onCall` sees it. */
+export interface IMockHostCall {
+    /** Which kind of member the call is for. */
+    readonly member: "tool" | "table" | "event" | "observable";
+    /** The member's name. */
+    readonly name: string;
+    /** `run` for a tool; the method for a table (`list`, `save`, ...); `subscribe` and the rest. */
+    readonly operation: string;
+    /** The call's arguments. */
+    readonly args: readonly unknown[];
+}
+/** What {@link mockHostContract} starts with. */
+export interface IMockHostContractOptions<C> {
+    /**
+     * Fakes for the contract's tools, by name. Each gets the input parsed with the tool's schema,
+     * as the host does. Calling a tool without a fake fails, and so does calling a private one.
+     */
+    readonly tools?: ToolFakes<C>;
+    /** Starting complete rows, validated against the manifest's fields, without package defaults. */
+    readonly tables?: {
+        readonly [K in keyof ContractTableRowsOf<MembersOf<C>>]?: readonly ContractTableRowsOf<MembersOf<C>>[K][];
+    };
+    /**
+     * Starting values for the contract's observables, by name. Others start as the host serves
+     * them: a stored observable's default, or the value an in-memory one's source holds now.
+     */
+    readonly observables?: {
+        readonly [K in keyof ContractObservableValuesOf<MembersOf<C>>]?: ContractObservableValuesOf<MembersOf<C>>[K];
+    };
+    /** The data context the UI's calls are scoped to. Defaults to a new id. */
+    readonly dataContextId?: string;
+    /**
+     * Runs before the host answers each call (subscriptions included). Return a promise to delay
+     * the answer, or throw to fail the call.
+     */
+    readonly onCall?: (call: IMockHostCall) => void | Promise<void>;
+}
+/** The host's side of one table: its rows, and writes that reach subscribed UIs. */
+export interface IMockHostTable<R extends Row> extends IPackageTableHandle<R> {
+    /** A copy of the rows, in the order they were added. */
+    readonly rows: R[];
+}
+/** A running mock host. Call `dispose()` when the test ends. */
+export interface IMockHostContract<C> {
+    /** The host's tables: change rows as the provider would, and read what the UI saved. */
+    readonly tables: {
+        readonly [K in keyof ContractTableRowsOf<MembersOf<C>>]: IMockHostTable<ContractTableRowsOf<MembersOf<C>>[K]>;
+    };
+    /**
+     * The host's observables: set one to push a value (as the provider, unchecked), or read what
+     * the UI wrote. UI writes must fit the manifest's value type, then any declared schema.
+     */
+    readonly observables: {
+        readonly [K in keyof ContractObservableValuesOf<MembersOf<C>>]: Observable<ContractObservableValuesOf<MembersOf<C>>[K] | undefined>;
+    };
+    /** The contract's events: emit one to subscribed UIs. */
+    readonly events: {
+        readonly [K in keyof ContractEventPayloadsOf<MembersOf<C>>]: {
+            emit(payload: ContractEventPayloadsOf<MembersOf<C>>[K]): Promise<void>;
+        };
+    };
+    /**
+     * Disconnect the host and restore the default data context. Calls still waiting for an answer
+     * reject. Idempotent.
+     */
+    dispose(): void;
+}
+/**
+ * Stand in for the local host in a UI test: `hostContract` clients for this contract (including
+ * a package's shared `news`-style client) connect to it, with no signed-in user and no
+ * provider. Tables hold rows in memory and send `dataChanged`; tools answer with fakes.
+ *
+ * ```ts
+ * const host = mockHostContract(News, {
+ *   tables: { Headlines: [{ headlineId: newid(), title: "Hello", ... }] },
+ *   tools: { refresh: async () => ({ errors: [] }) },
+ * });
+ * // render the UI; it reads and writes through `news` as usual
+ * await host.tables.Headlines.save(nextHeadline); // the UI sees the change
+ * host.dispose();
+ * ```
+ *
+ * A UI's table calls go through the table's class (`PackageTable` or the package's subclass),
+ * as on the host, with a test context: its `callOwnedTable` reaches the mock's rows, and its
+ * other calls fail. So a save runs the class's overrides and the schema, defaults included,
+ * and each change reaches subscribers through the class's `dataChanged`. Writes through
+ * `host.tables` are storage writes, with no class or schema in between; the class still
+ * filters the changes they send.
+ *
+ * Table filters are equality (`{ feedId }`) and `$in` (`{ status: { $in: ["a", "b"] } }`); a
+ * filter with other operators (`$or`, `$matchWords`, ...) or a text search fails; test those
+ * reads against a real host.
+ * `onCall` can delay or fail calls, but cannot replace their answers. Paging and `sortBy` work.
+ * Stored rows validate the manifest's fields, as host storage does. UI
+ * writes to an observable must fit its manifest value type, then any declared schema. Tool
+ * access levels aren't checked (UI calls act as the signed-in user); private tools refuse UI
+ * calls, as on the host. Disposing rejects calls still waiting for an answer. One mock host
+ * runs at a time.
+ *
+ * @param contract - The contract value from `defineContract` (tests can import it; UI code
+ *   imports only its type), or a declaration from `declareContract`, whose observables start
+ *   empty unless `observables` gives them values.
+ * @param options - Tool fakes, starting rows and values, data context, and a call hook.
+ */
+export declare function mockHostContract<C extends AnyContract>(contract: C, options?: IMockHostContractOptions<C>): IMockHostContract<C>;
+export {};