@net-mesh/browser 0.37.0

package/dist/store/state.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Identity-preserving state application.
+ *
+ * `getState()` promises that "unchanged subtrees retain identity"
+ * (design §4). That is not documentation — it is what lets a Three.js
+ * loop diff by reference instead of walking the scene every frame, and
+ * a naive apply (`JSON.parse` → replace the root) breaks it silently:
+ * every render sees a brand-new root, every selector fires, and the
+ * only symptom is that the demo feels heavy.
+ *
+ * So both write paths funnel through {@link reconcile}:
+ *
+ * - the owner's shallow merge ({@link mergeShallow}), and
+ * - a replica applying a full validated snapshot.
+ *
+ * A validator necessarily returns fresh objects, so validation always
+ * happens *first* and reconciliation restores identity afterwards.
+ * That composition is also what makes an equivalent resynchronization
+ * snapshot a no-op rather than a whole-world change.
+ *
+ * Everything reconcile emits is frozen. New nodes are frozen as they
+ * are built and unchanged nodes were frozen when they were first
+ * built, so the reachable graph is deeply immutable without a separate
+ * deep-freeze pass over unchanged data.
+ */
+/**
+ * The reconciled form of `next`, reusing every part of `previous` that
+ * is structurally equal.
+ *
+ * Returns `previous` itself when the two are equivalent, so
+ * `reconcile(state, validate(raw)) === state` is the test for "this
+ * snapshot told us nothing new".
+ */
+export declare function reconcile<T>(previous: unknown, next: T): T;
+/**
+ * The owner's transaction: a shallow merge at the root, reconciled.
+ *
+ * Returns `current` unchanged when the patch moves nothing, which is
+ * what makes "empty/unchanged updates do not create notifications or
+ * revisions" true at the source instead of at every notify site.
+ */
+export declare function mergeShallow<S extends object>(current: S, patch: Partial<S>): S;

package/dist/store/state.js

@@ -0,0 +1,165 @@
+/**
+ * Identity-preserving state application.
+ *
+ * `getState()` promises that "unchanged subtrees retain identity"
+ * (design §4). That is not documentation — it is what lets a Three.js
+ * loop diff by reference instead of walking the scene every frame, and
+ * a naive apply (`JSON.parse` → replace the root) breaks it silently:
+ * every render sees a brand-new root, every selector fires, and the
+ * only symptom is that the demo feels heavy.
+ *
+ * So both write paths funnel through {@link reconcile}:
+ *
+ * - the owner's shallow merge ({@link mergeShallow}), and
+ * - a replica applying a full validated snapshot.
+ *
+ * A validator necessarily returns fresh objects, so validation always
+ * happens *first* and reconciliation restores identity afterwards.
+ * That composition is also what makes an equivalent resynchronization
+ * snapshot a no-op rather than a whole-world change.
+ *
+ * Everything reconcile emits is frozen. New nodes are frozen as they
+ * are built and unchanged nodes were frozen when they were first
+ * built, so the reachable graph is deeply immutable without a separate
+ * deep-freeze pass over unchanged data.
+ */
+/**
+ * The reconciled form of `next`, reusing every part of `previous` that
+ * is structurally equal.
+ *
+ * Returns `previous` itself when the two are equivalent, so
+ * `reconcile(state, validate(raw)) === state` is the test for "this
+ * snapshot told us nothing new".
+ */
+export function reconcile(previous, next) {
+    if (Object.is(previous, next))
+        return next;
+    if (Array.isArray(next)) {
+        const source = next;
+        if (!Array.isArray(previous))
+            return freezeArray(source, undefined);
+        const merged = freezeArray(source, previous);
+        // Same length and every element reused ⇒ the old array still
+        // describes the world, so keep its identity.
+        if (previous.length === source.length && sameElements(previous, merged)) {
+            return previous;
+        }
+        return merged;
+    }
+    if (isPlainObject(next)) {
+        if (!isPlainObject(previous))
+            return freezeRecord(next, undefined);
+        const merged = freezeRecord(next, previous);
+        const nextKeys = Object.keys(next);
+        // Own keys only, and the same SET of them — not merely the same
+        // count. Reading `previous[key]` would answer for an inherited
+        // member: `previous['__proto__']` is `Object.prototype` on any
+        // ordinary object, so a `next` carrying that as an own data key
+        // compared equal to a prototype it never came from, and
+        // reconciliation concluded the update changed nothing. Equal
+        // cardinality with different keys hid it further: `{a:1}` against
+        // an own `{__proto__:{}}` is one key each.
+        if (nextKeys.length === Object.keys(previous).length &&
+            nextKeys.every(key => hasOwn(previous, key) && Object.is(previous[key], merged[key]))) {
+            return previous;
+        }
+        return merged;
+    }
+    // Primitive, function, class instance or null: nothing to share.
+    return next;
+}
+/**
+ * The owner's transaction: a shallow merge at the root, reconciled.
+ *
+ * Returns `current` unchanged when the patch moves nothing, which is
+ * what makes "empty/unchanged updates do not create notifications or
+ * revisions" true at the source instead of at every notify site.
+ */
+export function mergeShallow(current, patch) {
+    const keys = Object.keys(patch);
+    if (keys.length === 0)
+        return current;
+    let changed = false;
+    const draft = { ...current };
+    for (const key of keys) {
+        // The prior subtree is an OWN property or it is absent. Reading
+        // through the prototype made `__proto__` look like an existing
+        // subtree equal to the incoming one, so the merge reported no
+        // change and the owner's update vanished: no new root, no
+        // revision, no notification.
+        const before = ownValue(current, key);
+        const incoming = reconcile(before, patch[key]);
+        if (!Object.is(before, incoming)) {
+            // `defineProperty` for the reason `freezeRecord` uses it: a
+            // plain assignment of `__proto__` replaces this object's
+            // prototype rather than storing the caller's data. The spread
+            // above is already safe (it defines rather than assigns); this
+            // was the one that was not.
+            Object.defineProperty(draft, key, {
+                value: incoming,
+                enumerable: true,
+                writable: true,
+                configurable: true,
+            });
+            changed = true;
+        }
+    }
+    if (!changed)
+        return current;
+    return Object.freeze(draft);
+}
+function isPlainObject(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return false;
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+}
+function sameElements(previous, merged) {
+    for (let i = 0; i < merged.length; i += 1) {
+        if (!Object.is(previous[i], merged[i]))
+            return false;
+    }
+    return true;
+}
+function freezeArray(next, previous) {
+    const out = new Array(next.length);
+    for (let i = 0; i < next.length; i += 1) {
+        out[i] = reconcile(previous?.[i], next[i]);
+    }
+    return Object.freeze(out);
+}
+/** Whether a record carries this key itself. */
+function hasOwn(record, key) {
+    return Object.prototype.hasOwnProperty.call(record, key);
+}
+/** A record's own value for a key, or `undefined` when it has none. */
+function ownValue(record, key) {
+    if (record === undefined)
+        return undefined;
+    return hasOwn(record, key) ? record[key] : undefined;
+}
+function freezeRecord(next, previous) {
+    const out = {};
+    for (const key of Object.keys(next)) {
+        // `defineProperty`, never `out[key] = …`.
+        //
+        // A plain assignment of the key `__proto__` goes through
+        // `Object.prototype`'s legacy setter: it REPLACES this object's
+        // prototype instead of storing a property. A patch whose
+        // replacement *value* is the ordinary JSON data
+        // `{"__proto__":{…}}` — no forbidden path segment anywhere — then
+        // came out of a successful, validated reconciliation as `{}` whose
+        // prototype carried the data, so the published state both lost the
+        // key and answered `true` for a field it does not own. The
+        // null-prototype parser and the null-prototype patch draft do not
+        // help here: this is the last step, after validation, and it built
+        // an ordinary object.
+        Object.defineProperty(out, key, {
+            value: reconcile(ownValue(previous, key), next[key]),
+            enumerable: true,
+            writable: false,
+            configurable: false,
+        });
+    }
+    return Object.freeze(out);
+}

package/dist/store/types.d.ts

@@ -0,0 +1,200 @@
+/**
+ * The store's public type contract.
+ *
+ * These are the declarations from
+ * `docs/internal/plans/BROWSER_GAME_STORE_API_DESIGN.md` §2, moved into
+ * the package so they are compiled rather than merely written down — but
+ * compiled is all that binds them: the shipped handles are
+ * `HostedStoreHandle` (`host.ts`) and `JoinedStoreHandle` (`join.ts`), and
+ * `OperationOptions`, `StoreLimits`, `HostedStore` and `JoinedStore` below
+ * have no implementor (`HostedStoreHandle.setState(next)` full-replaces;
+ * `joinStore` returns `JoinedStoreHandle` synchronously with
+ * `act(name, input)` / `input(name, value)`, no options).
+ *
+ * Two of them encode a review disposition and must not be "simplified":
+ *
+ * - {@link HostedStore} has `setState`; {@link JoinedStore} does **not**.
+ *   A replica cannot write, and that is a type-level fact, not a runtime
+ *   check a caller can be talked out of.
+ * - The projection callback on the host returns a validated `S`, never a
+ *   `Partial<S>`. Visibility is expressed **in the schema** — collections
+ *   omit invisible entities, individually hidden fields are explicit
+ *   `null` or a tagged value, and `empty()` means absence. A zero must
+ *   never be readable as "you cannot see this".
+ */
+import type { StoreError } from './errors.js';
+import type { Visibility } from './visibility.js';
+/** Deeply-readonly view of validated plain state. */
+export type ReadonlyState<T> = T extends readonly (infer V)[] ? readonly ReadonlyState<V>[] : T extends object ? {
+    readonly [K in keyof T]: ReadonlyState<T[K]>;
+} : T;
+/**
+ * A validator: total on accepted input, throwing otherwise.
+ *
+ * Deliberately the shape of `schema.parse` so Zod/Valibot/hand-written
+ * checks are all usable without the store depending on any of them.
+ */
+export type Parse<T> = (value: unknown) => T;
+/** A subscription disposer. Calling it more than once is harmless. */
+export type Cancel = () => void;
+/** Declared actions: acknowledged, validated request/response pairs. */
+export type ActionSpec = Record<string, {
+    input: unknown;
+    output: unknown;
+}>;
+/** Declared latest-value inputs: coalesced intent, no per-call promise. */
+export type InputSpec = Record<string, unknown>;
+/** A reusable typed description of a store. Carries no state or connection. */
+export interface StoreDefinition<S extends object, A extends ActionSpec, I extends InputSpec> {
+    readonly id: string;
+    readonly version: number;
+    readonly state: Parse<S>;
+    /**
+     * The value that represents **absence** — no visible entities, no
+     * visible fields. Not a plausible set of game values: a reader that
+     * cannot see the ship must not receive a ship pointing north.
+     */
+    readonly empty: () => S;
+    readonly actions: {
+        readonly [K in keyof A]: {
+            readonly input: Parse<A[K]['input']>;
+            readonly output: Parse<A[K]['output']>;
+        };
+    };
+    readonly inputs: {
+        readonly [K in keyof I]: Parse<I[K]>;
+    };
+    /**
+     * What each player may see, declared: `'open'`, a preset, or path →
+     * rule. Enforced by the host after any hand-written projection. See
+     * `visibility.ts`.
+     */
+    readonly visibility?: Visibility;
+    /**
+     * Interest management: for each top-level entity map, the key an
+     * entity is found under — a grid cell, a room, any string (`null`:
+     * always delivered). A replica that declares an interest set receives
+     * only the entities whose key is in it. Used by the host; a joiner may
+     * omit it.
+     */
+    readonly interest?: {
+        readonly [collection: string]: (entity: never, id: string) => string | null;
+    };
+    /**
+     * Per-entity validators, for the top-level entity maps whose validity is
+     * **per entity**: collection name → a parser for ONE entity.
+     *
+     * What makes {@link HostedStoreHandle.setEntities} cheap. An entity
+     * write validates only the entities it changes, and it commits without
+     * running {@link StoreDefinition.state} over the untouched world. That
+     * is the whole-document validator, which costs O(world) on every commit.
+     *
+     * **A contract, not a hint.** Declaring a collection here says that
+     * `state`'s rule for that key is exactly "a record of entities, each
+     * passing this parser", with no cross-entity or cross-collection
+     * invariant. `setEntities` trusts that, so an invariant that `state`
+     * enforces across entities is not enforced on this path. Keep such
+     * invariants in actions, or write through `setState`.
+     */
+    readonly entities?: {
+        readonly [collection: string]: Parse<unknown>;
+    };
+}
+/** The top-level keys of `S` whose values are entity maps. */
+export type EntityCollection<S extends object> = {
+    [K in keyof S & string]: S[K] extends Readonly<Record<string, unknown>> ? K : never;
+}[keyof S & string];
+/** One entity of collection `C` of `S`. */
+export type EntityOf<S extends object, C extends keyof S> = S[C] extends Readonly<Record<string, infer E>> ? E : never;
+/** Where a handle is in its lifecycle. Kept out of game state. */
+export type StorePhase = 'connecting' | 'syncing' | 'ready' | 'reconnecting' | 'failed' | 'closed';
+/** Readiness, separate from the state itself. */
+export interface StoreStatus {
+    readonly phase: StorePhase;
+    /** Retained state is no longer known-current. Not "empty world". */
+    readonly stale: boolean;
+    readonly error: StoreError | null;
+}
+/** Equality and delivery options for a selector subscription. */
+export interface SelectorOptions<T> {
+    readonly equality?: (a: T, b: T) => boolean;
+    readonly fireImmediately?: boolean;
+}
+/** The read surface both the owner and a replica expose. */
+export interface StoreReader<S extends object> {
+    getState(): ReadonlyState<S>;
+    subscribe(listener: (state: ReadonlyState<S>, previous: ReadonlyState<S>) => void): Cancel;
+    subscribe<T>(selector: (state: ReadonlyState<S>) => T, listener: (selected: T, previous: T) => void, options?: SelectorOptions<T>): Cancel;
+    getStatus(): StoreStatus;
+    subscribeStatus(listener: (status: StoreStatus, previous: StoreStatus) => void): Cancel;
+}
+/** Per-call deadline and cancellation. */
+export interface OperationOptions {
+    readonly timeoutMs?: number;
+    readonly signal?: AbortSignal;
+}
+/** What happened to a latest-value input locally. Not remote acceptance. */
+export type InputDisposition = {
+    readonly type: 'queued' | 'replaced';
+} | {
+    readonly type: 'dropped';
+    readonly reason: 'not-ready' | 'capacity';
+};
+/** An owner state update: a shallow patch, or a function producing one. */
+export type StateUpdate<S extends object> = Partial<S> | ((state: ReadonlyState<S>) => Partial<S>);
+/**
+ * The handle a handler gets for the duration of **one synchronous
+ * transaction**. Valid only during that transaction: returning,
+ * throwing or handing back a thenable invalidates it, so a retained
+ * context cannot write from a later microtask.
+ */
+export interface ActionContext<S extends object> {
+    /** The authenticated caller's 16-lowercase-hex mesh node id. */
+    readonly peer: string;
+    getState(): ReadonlyState<S>;
+    setState(update: StateUpdate<S>): void;
+}
+/** What the owner's `authorize` is asked to rule on. */
+export type AccessRequest<A extends ActionSpec, I extends InputSpec> = {
+    readonly type: 'read';
+    readonly peer: string;
+    readonly audience: readonly string[];
+} | {
+    [K in keyof A]: {
+        readonly type: 'action';
+        readonly peer: string;
+        readonly name: K;
+        readonly input: A[K]['input'];
+    };
+}[keyof A] | {
+    [K in keyof I]: {
+        readonly type: 'input';
+        readonly peer: string;
+        readonly name: K;
+        readonly input: I[K];
+    };
+}[keyof I];
+/** Declared bounds. The host enforces its own; callers cannot raise them. */
+export interface StoreLimits {
+    readonly maxSnapshotBytes?: number;
+    readonly maxMessageBytes?: number;
+    readonly maxPendingActions?: number;
+    readonly maxAudiences?: number;
+}
+/** The authoritative instance. The only handle with `setState`. */
+export interface HostedStore<S extends object> extends StoreReader<S> {
+    readonly authority: string;
+    setState(update: StateUpdate<S>): void;
+    close(): Promise<void>;
+}
+/** A subscribed replica. Writes go through `actions` / `inputs`, never `setState`. */
+export interface JoinedStore<S extends object, A extends ActionSpec, I extends InputSpec> extends StoreReader<S> {
+    readonly actions: {
+        readonly [K in keyof A]: (input: A[K]['input'], options?: OperationOptions) => Promise<A[K]['output']>;
+    };
+    readonly inputs: {
+        readonly [K in keyof I]: (input: I[K]) => InputDisposition;
+    };
+    setAudience(names: readonly string[], options?: OperationOptions): Promise<void>;
+    close(): Promise<void>;
+}

package/dist/store/types.js

@@ -0,0 +1,25 @@
+/**
+ * The store's public type contract.
+ *
+ * These are the declarations from
+ * `docs/internal/plans/BROWSER_GAME_STORE_API_DESIGN.md` §2, moved into
+ * the package so they are compiled rather than merely written down — but
+ * compiled is all that binds them: the shipped handles are
+ * `HostedStoreHandle` (`host.ts`) and `JoinedStoreHandle` (`join.ts`), and
+ * `OperationOptions`, `StoreLimits`, `HostedStore` and `JoinedStore` below
+ * have no implementor (`HostedStoreHandle.setState(next)` full-replaces;
+ * `joinStore` returns `JoinedStoreHandle` synchronously with
+ * `act(name, input)` / `input(name, value)`, no options).
+ *
+ * Two of them encode a review disposition and must not be "simplified":
+ *
+ * - {@link HostedStore} has `setState`; {@link JoinedStore} does **not**.
+ *   A replica cannot write, and that is a type-level fact, not a runtime
+ *   check a caller can be talked out of.
+ * - The projection callback on the host returns a validated `S`, never a
+ *   `Partial<S>`. Visibility is expressed **in the schema** — collections
+ *   omit invisible entities, individually hidden fields are explicit
+ *   `null` or a tagged value, and `empty()` means absence. A zero must
+ *   never be readable as "you cannot see this".
+ */
+export {};

package/dist/store/visibility.d.ts

@@ -0,0 +1,118 @@
+/**
+ * Declarative visibility: say which parts of the state are secret, and
+ * the host removes them from every player's view before anything is
+ * sent.
+ *
+ * ```ts
+ * defineStore({
+ *   …,
+ *   visibility: {
+ *     'players.*.hand': 'owner',     // only the player whose id is that key
+ *     'deck':           'nobody',    // the host only
+ *     'deck.length':    'everyone',  // …but everyone may count it
+ *     'waypoint':       ['command'], // players reading the `command` audience
+ *   },
+ * });
+ * ```
+ *
+ * Why this exists: a hand-written `project` fails SILENTLY — the game
+ * works and the secret is readable in the browser. Rules declared here
+ * are enforced by the SDK, after any hand-written projection, so code
+ * can narrow what a rule allows but never widen it.
+ *
+ * **The rules.**
+ *
+ * - A path is dot-separated keys; `*` matches any key of an object (or
+ *   index of an array). `deck.length` — a path ending in `.length` —
+ *   reveals only the length of an array its parent rule hides.
+ * - `'everyone'`, `'nobody'` (the host only), `'owner'` (the player
+ *   whose peer id is the key matched by the path's FIRST `*` — the
+ *   `ships[context.peer]` pattern needs no setup), or a list of
+ *   audiences (any one of them suffices).
+ * - Unlisted paths are visible, as without rules. A rule covers
+ *   everything beneath its path, and a deeper rule cannot re-open what
+ *   a shallower one hid (except `.length`).
+ *
+ * **What hidden looks like.** An entry of a collection (a path ending
+ * in `*`) is removed. A field becomes the {@link HIDDEN} marker — never
+ * `0`, `""` or `null`, which a game would read as real values — so the
+ * state validator must accept it there: wrap that field's parser with
+ * {@link hiddenOr}. A counted array becomes an array of markers of the
+ * same length.
+ *
+ * **Presets**, for the common shapes: `'open'` (everyone sees
+ * everything — an explicit decision rather than an accident) and
+ * `'card-game'` (`players.*.hand` owner, `deck` nobody, `deck.length`
+ * everyone). A preset takes overrides: `{ preset: 'card-game',
+ * 'players.*.score': 'nobody' }`.
+ *
+ * **What it cannot do.** The host itself holds everything: a player who
+ * hosts can read every secret in their own tab. Games with real stakes
+ * need a host that is not a player.
+ */
+import type { Viewer } from './owner.js';
+/** Who may see a path. */
+export type VisibilityRule = 'everyone' | 'nobody' | 'owner' | readonly string[];
+/** The presets. */
+export type VisibilityPreset = 'card-game';
+/** Path → rule. */
+export type VisibilityRules = {
+    readonly [path: string]: VisibilityRule;
+};
+/** What `defineStore({ visibility })` accepts. */
+export type Visibility = 'open' | VisibilityPreset | VisibilityRules | ({
+    readonly preset: VisibilityPreset;
+} & {
+    readonly [path: string]: VisibilityRule | VisibilityPreset;
+});
+/** The marker a hidden field carries in a player's view. */
+export interface Hidden {
+    readonly $hidden: true;
+}
+/** The one hidden value. Plain JSON, so it survives the wire. */
+export declare const HIDDEN: Hidden;
+/** Whether a value is the hidden marker (the original, or one parsed off the wire). */
+export declare function isHidden(value: unknown): value is Hidden;
+/** Wrap a field's parser so the field may also be {@link HIDDEN}. */
+export declare function hiddenOr<T>(parse: (value: unknown) => T): (value: unknown) => T | Hidden;
+interface CompiledRule {
+    readonly path: string;
+    readonly segments: readonly string[];
+    readonly rule: VisibilityRule;
+    /** A `.length` rule: reveals the count of what its parent hides. */
+    readonly counts: boolean;
+}
+/** Rules ready to apply. `'open'` compiles to no rules. */
+export interface CompiledVisibility {
+    readonly rules: readonly CompiledRule[];
+    /** Whether any rule depends on who is looking — projections are then per player. */
+    readonly perPlayer: boolean;
+}
+/**
+ * Check and compile a visibility declaration. Throws `invalid-data` for
+ * anything that could not be enforced as written — at definition time,
+ * not at the first projection.
+ */
+export declare function compileVisibility(visibility: Visibility): CompiledVisibility;
+/**
+ * Apply compiled rules for one viewer (`null`: nobody in particular —
+ * sees only what `'everyone'` may).
+ */
+export declare function applyVisibility<S>(compiled: CompiledVisibility, state: S, viewer: Viewer | null): S;
+/**
+ * The view a viewer would receive under a definition's declared rules,
+ * for tests and tools. (A host also applies its hand-written `project`
+ * / `projectFor` first; this is the rules alone.)
+ */
+export declare function projectVisible<S>(definition: {
+    readonly visibility?: Visibility;
+}, state: S, viewer: Viewer | null): S;
+/**
+ * Throw if `viewer` could read any of `paths` (concrete dot paths, e.g.
+ * `players.bob.hand`) under the definition's rules. Absent, or the
+ * hidden marker, is hidden; anything else is a leak.
+ */
+export declare function assertHidden<S>(definition: {
+    readonly visibility?: Visibility;
+}, state: S, viewer: Viewer | null, paths: readonly string[]): void;
+export {};