@synapse-sdk/client 0.3.6 → 0.3.8

package/dist/index.d.ts

@@ -4,7 +4,7 @@ export { defaultReconnectPolicy, exponentialPolicy, fixedPolicy, withMaxAttempts
 export { isTasksRefusal } from "./tasks.ts";
 export { setMoqDebug } from "./moq_log.ts";
 export type * from "./types.ts";
-export { brokerCertHelperUrl, discoverBrokerCertSha256, ensureWebTransport } from "./session.ts";
+export { brokerCertHelperUrl, discoverBrokerCertSha256, ensureWebTransport, namesRoot } from "./session.ts";
 export { replaceEqualDeep, shallowEqual } from "./util.ts";
 export { orderAfter, orderBefore, orderBetween, ulid } from "./scene.ts";
 export { derivedFrameKey, derivedFrameName, materializeFrames, materializeHardpoints, validateDerivedFrame, type MaterializeReport } from "./scene_frames.ts";

package/dist/index.js

@@ -4,7 +4,7 @@ export { Synapse, FIRST_CONNECT_GIVE_UP_MS } from "./synapse.js";
 export { defaultReconnectPolicy, exponentialPolicy, fixedPolicy, withMaxAttempts } from "./node.js";
 export { isTasksRefusal } from "./tasks.js";
 export { setMoqDebug } from "./moq_log.js";
-export { brokerCertHelperUrl, discoverBrokerCertSha256, ensureWebTransport } from "./session.js";
+export { brokerCertHelperUrl, discoverBrokerCertSha256, ensureWebTransport, namesRoot } from "./session.js";
 export { replaceEqualDeep, shallowEqual } from "./util.js";
 export { orderAfter, orderBefore, orderBetween, ulid } from "./scene.js";
 export { derivedFrameKey, derivedFrameName, materializeFrames, materializeHardpoints, validateDerivedFrame } from "./scene_frames.js";

package/dist/keyserver.d.ts

@@ -0,0 +1,37 @@
+import { SynapseError } from "@synapse-sdk/core";
+import type { Discovery, DiscoveryState, FetchToken } from "./types.ts";
+import type { Cell } from "./util.ts";
+/** The key server a node asks when `setAuth` names none. */
+export declare const DEFAULT_AUTH_URL = "https://e9e413af.synapse.build";
+/** The discovery value with no credential set, or just after `setAuth` (a new object each time: a change). */
+export declare const idleDiscovery: () => DiscoveryState;
+/** The refusal when no credential is set or the sign-in gives none. */
+export declare const notSignedIn: () => SynapseError;
+/** `GET /discover`'s body as the `Discovery` value; `undefined` when it does not have that shape. */
+export declare function discoveryOf(body: unknown): Discovery | undefined;
+/**
+ * One `setAuth(fetchToken, { authUrl })` of one node: the key server's client and the caches it fills. A new one at every
+ * `setAuth` (the old one's caches go with it). It writes the node's `discovery` value only while it is the node's
+ * current one (`current`), so an answer arriving after a `setAuth` changes nothing.
+ */
+export declare class Auth {
+    #private;
+    private readonly fetchToken;
+    private readonly discovery;
+    private readonly current;
+    constructor(fetchToken: FetchToken, authUrl: string, discovery: Cell<DiscoveryState>, current: (a: Auth) => boolean);
+    /** `GET /discover`, setting the value (`pending`, then `success` or `error`, the last data kept); one at a time: a call while one is out joins it. */
+    discover(): Promise<Discovery>;
+    /** The discover answer: the value's when it is `success` (`cached`), else fetched now. */
+    known(): Promise<{
+        discovery: Discovery;
+        cached: boolean;
+    }>;
+    /** The token for cluster `id`: the kept one while it does not expire within `FRESH_FOR_S` (`cached`), else `POST /clusters/{id}/token`, kept. */
+    clusterToken(id: string): Promise<{
+        token: string;
+        cached: boolean;
+    }>;
+    /** Forgets the token of cluster `id` (the relay refused it). */
+    dropToken(id: string): void;
+}

package/dist/keyserver.js

@@ -0,0 +1,146 @@
+// The key server for a signed-in person (PLAN v0.38 §3.3): what a node set with `setAuth` asks it, `GET /discover`
+// (the relay and the person's clusters with their runtimes) and `POST /clusters/{id}/token` (a cluster token), with
+// the person's credential fetched at each request and sent only in the `Authorization` header. Both answers are kept
+// in memory, per node, until the next `setAuth`: the discover answer as the node's `discovery` state value, the cluster
+// tokens by cluster id while fresh (`FRESH_FOR_S`). Nothing is written anywhere else; no token is ever put in a URL, an
+// error or a log line.
+import { SynapseError } from "@synapse-sdk/core";
+import { describeError } from "./session.js";
+import { FRESH_FOR_S, knownOfListed, label } from "./target.js";
+/** The key server a node asks when `setAuth` names none. */
+export const DEFAULT_AUTH_URL = "https://e9e413af.synapse.build";
+/** The discovery value with no credential set, or just after `setAuth` (a new object each time: a change). */
+export const idleDiscovery = () => ({ status: "idle" });
+/** The refusal when no credential is set or the sign-in gives none. */
+export const notSignedIn = () => new SynapseError("unauthorized", { message: "not signed in: sign in first", source: "sdk" });
+const isTable = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+/** An answer that is not what the key server says it sends: `connection_lost` (retried; never a caller's mistake). */
+const unreadable = (what) => new SynapseError("connection_lost", { message: `the key server's answer to ${what} could not be read`, source: "sdk" });
+/** `GET /discover`'s body as the `Discovery` value; `undefined` when it does not have that shape. */
+export function discoveryOf(body) {
+    if (!isTable(body) || typeof body.relay !== "string" || typeof body.user_id !== "string" || !Array.isArray(body.clusters))
+        return undefined;
+    const clusters = [];
+    for (const c of body.clusters) {
+        if (!isTable(c) || typeof c.id !== "string" || typeof c.name !== "string" || !isTable(c.owner) || !isTable(c.runtimes))
+            return undefined;
+        const o = c.owner;
+        if (typeof o.kind !== "string" || typeof o.id !== "string" || (o.slug !== undefined && o.slug !== null && typeof o.slug !== "string"))
+            return undefined;
+        const owner = typeof o.slug === "string" ? { kind: o.kind, id: o.id, slug: o.slug } : { kind: o.kind, id: o.id };
+        const runtimes = {};
+        for (const [name, id] of Object.entries(c.runtimes)) {
+            if (typeof id !== "string")
+                return undefined;
+            runtimes[name] = id;
+        }
+        const listed = { id: c.id, name: c.name, owner };
+        clusters.push({ ...listed, label: label(knownOfListed(listed)), runtimes });
+    }
+    return { relay: body.relay, userId: body.user_id, clusters };
+}
+/**
+ * One `setAuth(fetchToken, { authUrl })` of one node: the key server's client and the caches it fills. A new one at every
+ * `setAuth` (the old one's caches go with it). It writes the node's `discovery` value only while it is the node's
+ * current one (`current`), so an answer arriving after a `setAuth` changes nothing.
+ */
+export class Auth {
+    fetchToken;
+    discovery;
+    current;
+    #tokens = new Map();
+    #pending;
+    #authUrl;
+    constructor(fetchToken, authUrl, discovery, current) {
+        this.fetchToken = fetchToken;
+        this.discovery = discovery;
+        this.current = current;
+        this.#authUrl = authUrl.replace(/\/+$/, "");
+    }
+    #set(f) { if (this.current(this))
+        this.discovery.set(f(this.discovery.get())); }
+    /** `GET /discover`, setting the value (`pending`, then `success` or `error`, the last data kept); one at a time: a call while one is out joins it. */
+    discover() {
+        return this.#pending ??= (async () => {
+            this.#set(p => (p.data ? { status: "pending", data: p.data } : { status: "pending" }));
+            try {
+                const d = discoveryOf(await this.#request("GET", "/discover"));
+                if (!d)
+                    throw unreadable("discover");
+                this.#set(() => ({ status: "success", data: d }));
+                return d;
+            }
+            catch (e) {
+                const err = e instanceof SynapseError ? e : new SynapseError("internal", { message: describeError(e), source: "sdk" });
+                this.#set(p => (p.data ? { status: "error", data: p.data, error: err } : { status: "error", error: err }));
+                throw err;
+            }
+            finally {
+                this.#pending = undefined;
+            }
+        })();
+    }
+    /** The discover answer: the value's when it is `success` (`cached`), else fetched now. */
+    async known() {
+        const v = this.discovery.get();
+        if (this.current(this) && v.status === "success" && v.data)
+            return { discovery: v.data, cached: true };
+        return { discovery: await this.discover(), cached: false };
+    }
+    /** The token for cluster `id`: the kept one while it does not expire within `FRESH_FOR_S` (`cached`), else `POST /clusters/{id}/token`, kept. */
+    async clusterToken(id) {
+        const kept = this.#tokens.get(id);
+        if (kept && kept.exp > Math.floor(Date.now() / 1000) + FRESH_FOR_S)
+            return { token: kept.token, cached: true };
+        const body = await this.#request("POST", `/clusters/${encodeURIComponent(id)}/token`);
+        const exp = isTable(body) && typeof body.expires_at === "string" ? Date.parse(body.expires_at) : NaN;
+        if (!isTable(body) || typeof body.token !== "string" || body.token === "" || Number.isNaN(exp))
+            throw unreadable("a cluster token request");
+        this.#tokens.set(id, { token: body.token, exp: Math.floor(exp / 1000) });
+        return { token: body.token, cached: false };
+    }
+    /** Forgets the token of cluster `id` (the relay refused it). */
+    dropToken(id) { this.#tokens.delete(id); }
+    /**
+     * One request with the credential fetched now. The key server's answers (PLAN v0.38 §3.3.5): `401` `unauthorized`
+     * (and every cache dropped), `400`/`403`/`404` `invalid_input`, anything else not 2xx, or no answer, `connection_lost`;
+     * each with the key server's own sentence when it sent one.
+     */
+    async #request(method, path) {
+        let credential;
+        try {
+            credential = await this.fetchToken();
+        }
+        catch (e) {
+            throw new SynapseError("connection_lost", { message: `signing in gave no credential: ${describeError(e)}`, source: "sdk" });
+        }
+        if (!credential)
+            throw notSignedIn();
+        let res;
+        try {
+            res = await globalThis.fetch(`${this.#authUrl}${path}`, { method, headers: { Authorization: `Bearer ${credential}` } });
+        }
+        catch (e) {
+            throw new SynapseError("connection_lost", { message: `the key server could not be reached: ${describeError(e)}`, source: "transport" });
+        }
+        let body;
+        try {
+            body = JSON.parse(await res.text());
+        }
+        catch {
+            body = undefined;
+        }
+        if (res.ok)
+            return body;
+        const sentence = isTable(body) && typeof body.error === "string" && body.error !== "" ? body.error : `the key server answered ${res.status}`;
+        if (res.status === 401) {
+            const err = new SynapseError("unauthorized", { message: sentence, source: "sdk" });
+            this.#tokens.clear();
+            this.#set(p => (p.status === "success" ? { status: "error", data: p.data, error: err } : p));
+            throw err;
+        }
+        if (res.status === 400 || res.status === 403 || res.status === 404)
+            throw new SynapseError("invalid_input", { message: sentence, source: "sdk" });
+        throw new SynapseError("connection_lost", { message: sentence, source: "sdk" });
+    }
+}

package/dist/node.d.ts

@@ -1,6 +1,7 @@
 import { SynapseError, type ClientType, type ErrorBody, type Identity, type TimeDomain } from "@synapse-sdk/core";
+import { Auth } from "./keyserver.ts";
 import { Session, type Dial, type SessionKnobs } from "./session.ts";
-import type { ConnectOptions, ConnectTarget, ConnectionState, Notice, ReconnectPolicy } from "./types.ts";
+import type { ConnectOptions, ConnectTarget, ConnectionState, DiscoveryState, FetchToken, Notice, ReconnectPolicy } from "./types.ts";
 import { Cell, type Deferred } from "./util.ts";
 /** `initial × 2^(attempt−1)` capped at `max`, times an equal jitter U(0.5, 1); never gives up. */
 export declare function exponentialPolicy(initialMs: number, maxMs: number): ReconnectPolicy;
@@ -108,6 +109,13 @@ export declare class Node {
     readonly projectNotices: Set<(n: Notice) => void>;
     /** Resolves once the node has ended for good: `close()`, and nothing else. */
     readonly ended: Deferred<void>;
+    /**
+     * The signed-in person's key server (`setAuth`), asked when a target named by name is dialed (PLAN v0.38 §3.2);
+     * `undefined`: nobody is signed in. Read at each attempt, never by a live session: signing out ends no session.
+     */
+    auth: Auth | undefined;
+    /** The key server's answer about the signed-in person, kept by `auth` (`node.discovery`). */
+    readonly discovery: Cell<DiscoveryState>;
     epochs: number;
     reconnects: number;
     callsSent: number;
@@ -118,6 +126,8 @@ export declare class Node {
         finalDom?: Promise<TimeDomain>;
     });
     get isEnded(): boolean;
+    /** `setAuth`: a new key-server client for `fetchToken` (none: signed out); what the previous one kept is forgotten and `discovery` is `idle` again. */
+    setAuth(fetchToken: FetchToken | undefined, authUrl: string): void;
     get isConnected(): boolean;
     /** Whether the node rests `failed` on target `generation` (a `failed` of an older target, not yet replaced by the loop, is not this target's). */
     failedOn(generation: number): boolean;
@@ -161,6 +171,13 @@ export declare class Node {
     /** Starts the loop (once the time domain is final). `first` is a `connect()` call's reply. `signals`: close on SIGINT/SIGTERM (Bun/Node). */
     run(stand: Stand, first: Reply | undefined, signals: boolean): void;
 }
+/**
+ * Dials `dial`, a target named as the CLI names it, through the key server of `auth` (`resolveViaKeyserver`), with `open`.
+ * When the relay refuses (`unauthorized`) a cluster token that came from the cache, that token is dropped, one is asked
+ * again and dialed once more within this attempt (a token the relay stopped taking before its expiry costs one request,
+ * not a `failed`); a second refusal is the attempt's. A token given as such is dialed as it is.
+ */
+export declare function dialByName<T>(dial: Dial, auth: Auth, open: (at: Dial) => Promise<T>): Promise<T>;
 /** Resolves the identity a node declares (`resolve_identity`): a missing name is minted, a `web`/`hmi` node without a `user_id` mints one. */
 export declare function resolveIdentity(o: {
     type: ClientType;
@@ -168,7 +185,12 @@ export declare function resolveIdentity(o: {
     userId?: string;
     credential?: string;
 }): Identity;
-/** Resolves a `ConnectTarget` against the node's current identity (fields left out are kept). */
+/**
+ * Resolves a `ConnectTarget` against the node's current identity (fields left out are kept). A url that is not a URL is a
+ * target as the CLI names it (`infra-1@devel`): its grammar is checked now, and it is resolved at every attempt (through
+ * the key server when a person is signed in, else from the CLI's files); with neither (a browser, nobody signed in) it is
+ * refused at once.
+ */
 export declare function resolveTarget(node: Node, t: ConnectTarget): Dial;
 /** A given broker url that is not a URL is the caller's mistake: `invalid_input`. */
 export declare function checkUrl(url: string): void;

package/dist/node.js

@@ -8,6 +8,8 @@
 // the handles replay when told.
 import { ClockSync, SynapseError, calibrateMonotonicClock, defaultDomId, isValidClientName, mintName, mintUserId, nowUs } from "@synapse-sdk/core";
 import { closeOnSignals, forgetOnSignals } from "./signals.js";
+import { BROWSER_REFUSAL, canReadFiles, isUrl, parseTargetStrict, resolveStr, resolveViaKeyserver } from "./target.js";
+import { Auth, idleDiscovery } from "./keyserver.js";
 import { Session, closeError, defaultMaxDatagram, discoverBrokerCertSha256, makeDial, openSession, urlOrEndpoint } from "./session.js";
 import { startOn } from "./calls.js";
 import { AsyncQueue, Cell, deferred } from "./util.js";
@@ -84,6 +86,13 @@ export class Node {
     /** The loop's mailbox: unbounded, so no `close()` or target change is ever dropped. */
     #commands = new AsyncQueue(Infinity);
     #monitors = new Set();
+    /**
+     * The signed-in person's key server (`setAuth`), asked when a target named by name is dialed (PLAN v0.38 §3.2);
+     * `undefined`: nobody is signed in. Read at each attempt, never by a live session: signing out ends no session.
+     */
+    auth;
+    /** The key server's answer about the signed-in person, kept by `auth` (`node.discovery`). */
+    discovery = new Cell(idleDiscovery());
     epochs = 0;
     reconnects = 0;
     callsSent = 0;
@@ -98,6 +107,11 @@ export class Node {
         this.prepared = opts.finalDom ? opts.finalDom.then(d => { this.dom = d; }) : Promise.resolve();
     }
     get isEnded() { return this.#endedFlag; }
+    /** `setAuth`: a new key-server client for `fetchToken` (none: signed out); what the previous one kept is forgotten and `discovery` is `idle` again. */
+    setAuth(fetchToken, authUrl) {
+        this.auth = fetchToken ? new Auth(fetchToken, authUrl, this.discovery, a => this.auth === a) : undefined;
+        this.discovery.set(idleDiscovery());
+    }
     get isConnected() { return this.link.get().status === "connected"; }
     /** Whether the node rests `failed` on target `generation` (a `failed` of an older target, not yet replaced by the loop, is not this target's). */
     failedOn(generation) { const l = this.link.get(); return l.status === "failed" && l.generation === generation; }
@@ -328,9 +342,19 @@ async function runLoop(node, commands, stand, first) {
                 if (ac.signal.aborted)
                     return { kind: "opened", result: new SynapseError("canceled", "superseded") };
                 try {
-                    // The pin: given, else discovered per attempt (a restarted dev broker has a fresh certificate), else unpinned.
-                    const cert = dial.cert ?? await discoverBrokerCertSha256(dial.url, { signal: ac.signal });
-                    return { kind: "opened", result: await openSession(node.knobs, { ...dial, cert }, node.dom.id, ac.signal) };
+                    const open = async (at) => {
+                        // The pin: given, else discovered per attempt (a restarted dev broker has a fresh certificate), else unpinned.
+                        const cert = at.cert ?? await discoverBrokerCertSha256(at.url, { signal: ac.signal });
+                        return openSession(node.knobs, { ...at, cert }, node.dom.id, ac.signal);
+                    };
+                    // A URL is dialed as it is. A target named as the CLI names it is resolved now, by one source chosen per attempt
+                    // (PLAN v0.38 §3.2): the key server when a person is signed in (`setAuth`), else the CLI's files (a token the
+                    // CLI refreshed since the last attempt is this attempt's). A token given as such wins.
+                    const auth = node.auth;
+                    const session = isUrl(dial.url) ? await open(dial)
+                        : auth ? await dialByName(dial, auth, open)
+                            : await resolveStr(dial.url).then(r => open({ ...dial, url: r.url, token: dial.token ?? r.token }));
+                    return { kind: "opened", result: session };
                 }
                 catch (e) {
                     return { kind: "opened", result: e instanceof SynapseError ? e : new SynapseError("connection_lost", { message: String(e), cause: e }) };
@@ -476,6 +500,26 @@ async function runLoop(node, commands, stand, first) {
         }
     }
 }
+/**
+ * Dials `dial`, a target named as the CLI names it, through the key server of `auth` (`resolveViaKeyserver`), with `open`.
+ * When the relay refuses (`unauthorized`) a cluster token that came from the cache, that token is dropped, one is asked
+ * again and dialed once more within this attempt (a token the relay stopped taking before its expiry costs one request,
+ * not a `failed`); a second refusal is the attempt's. A token given as such is dialed as it is.
+ */
+export async function dialByName(dial, auth, open) {
+    const r = await resolveViaKeyserver(dial.url, auth);
+    const at = { ...dial, url: r.url, token: dial.token ?? r.token };
+    try {
+        return await open(at);
+    }
+    catch (e) {
+        if (!(e instanceof SynapseError) || e.code !== "unauthorized" || dial.token !== undefined || !r.cached || r.cluster === undefined)
+            throw e;
+        auth.dropToken(r.cluster);
+        const { token } = await auth.clusterToken(r.cluster);
+        return open({ ...at, token });
+    }
+}
 /** Ends session `s`: the node stops naming it (handles are told, the status is true from that instant), then the session is torn down (calls failed, tasks awaited, close sent). */
 async function teardown(node, s, next) {
     node.setLink(next);
@@ -495,9 +539,25 @@ export function resolveIdentity(o) {
         id.credential = o.credential;
     return id;
 }
-/** Resolves a `ConnectTarget` against the node's current identity (fields left out are kept). */
+/**
+ * Resolves a `ConnectTarget` against the node's current identity (fields left out are kept). A url that is not a URL is a
+ * target as the CLI names it (`infra-1@devel`): its grammar is checked now, and it is resolved at every attempt (through
+ * the key server when a person is signed in, else from the CLI's files); with neither (a browser, nobody signed in) it is
+ * refused at once.
+ */
 export function resolveTarget(node, t) {
-    checkUrl(t.url);
+    if (isUrl(t.url))
+        checkUrl(t.url);
+    else {
+        if (!node.auth && !canReadFiles())
+            throw new SynapseError("invalid_input", { message: BROWSER_REFUSAL, source: "sdk" });
+        try {
+            parseTargetStrict(t.url);
+        }
+        catch (e) {
+            throw new SynapseError("invalid_input", { message: `${e instanceof Error ? e.message : String(e)}, or a URL`, source: "sdk" });
+        }
+    }
     const cur = node.target.get().identity;
     if (t.name !== undefined && !isValidClientName(t.name))
         throw new SynapseError("invalid_input", `name ${JSON.stringify(t.name)} is not [a-z0-9_-]{1,64}`);

package/dist/scene.d.ts

@@ -3,7 +3,7 @@ import { SynapseError, type ErrorBody, type ProjectSnapshot } from "@synapse-sdk
 import type { Node } from "./node.ts";
 import { StreamWriter, type Session } from "./session.ts";
 import type { Warn } from "./topics.ts";
-import type { LiveJoints, LivePose, LiveRemoved, LiveState, Quat, SceneAuthored, SceneDiffOp, SceneEntity, SceneEntityLive, SceneEntityRef, SceneEntityView, SceneHandle, SceneKind, SceneLive, SceneOp, ScenePlace, SceneSpawnOptions, SceneState, SceneStatus, SceneTree, SceneTxn, SceneView, Vec3 } from "./types.ts";
+import type { LiveJoints, LivePose, LiveRemoved, LiveState, Quat, SceneAuthored, SceneDiffOp, SceneEntity, SceneEntityLive, SceneEntityRef, SceneEntityView, SceneHandle, SceneKind, SceneLive, SceneOp, SceneSpawnOptions, SceneState, SceneStatus, SceneTree, SceneTxn, SceneView, Vec3 } from "./types.ts";
 import { AsyncQueue, type Deferred, type StateValue } from "./util.ts";
 /** How many batches a feed may fall behind before it is ended (the store's `STORE_FEED_CAP`). */
 export declare const SCENE_FEED_CAP = 256;
@@ -12,6 +12,9 @@ export declare const PATCH_PROTECTED: readonly string[];
 type Entities = Map<string, SceneEntity>;
 /** An entity named by its id or by a view of it (the id the view names now). */
 type EntityArg = string | SceneEntityView;
+/** A patch's `set` and `reparent`'s options, as the public interfaces take them. */
+type PatchSet = Parameters<SceneTxn["patch"]>[1];
+type ReparentOptions = NonNullable<Parameters<SceneTxn["reparent"]>[2]>;
 /**
  * A fresh entity id: a ULID (26 Crockford base-32 characters) made from a UUIDv7 (48-bit ms, version,
  * 74 random bits, variant), so ids sort by the time they were minted; within one millisecond the
@@ -30,6 +33,14 @@ export declare function orderBetween(left: string | null | undefined, right: str
  * prototype's rule). A cycle cannot come from the runtime; were one there, it is cut where it closes.
  */
 export declare function treeOf(entities: Readonly<Record<string, SceneEntity>>): SceneTree;
+/**
+ * The runtime's patch merge (`merge_set`): merges one level deep; a null deletes the key it names. A top-level null
+ * removes the component; an object merges into an object component key by key, a null sub-key removing that sub-key;
+ * an object given for a component that is absent or not an object replaces it without its null sub-keys, and nulls
+ * alone leave no component (an explicitly given `{}` is kept); any other value replaces. `undefined` is not given (the
+ * encoder skips it).
+ */
+export declare function mergeSet(into: Record<string, unknown>, set: Record<string, unknown>): Record<string, unknown>;
 /**
  * One authoring batch being built (`txn`): the ops it sends as one atomic `apply`. Ops on an entity
  * spawned in the same batch fold into its spawn: a patch (of keys a patch may set) or a rename merges
@@ -41,11 +52,15 @@ export declare class Txn implements SceneTxn {
     get ops(): readonly SceneOp[];
     /** Spawns an entity of `kind` under `opts.parent` (default the world root) with the components given (`layer` `authored` when not given, else `calibration`; a live entity is not spawned here, it comes from `scene.live.upsert`); its id is minted here (or `opts.id`, a known one) and returned. No `order` is sent: the runtime appends it after its siblings. */
     spawn(kind: SceneKind, opts: SceneSpawnOptions): string;
-    /** Sets components of the entity (one level deep: an object merges into an object). */
-    patch(entity: EntityArg, set: Partial<SceneEntity>): void;
+    /** Sets components of the entity: merges one level deep; a null deletes the key it names. */
+    patch(entity: EntityArg, set: PatchSet): void;
     rename(entity: EntityArg, name: string): void;
-    /** Moves the entity under `parent` (`null`: the world root), before or after a sibling (default: after the last). */
-    reparent(entity: EntityArg, parent: EntityArg | null, place?: ScenePlace): void;
+    /**
+     * Moves the entity under `parent` (`null`: the world root), `before` or `after` a sibling (default: after the last).
+     * By default it keeps its world pose (the runtime's default: nothing sent); `preserveWorld: false` sends
+     * `preserve_world: false`, and it keeps its local xform.
+     */
+    reparent(entity: EntityArg, parent: EntityArg | null, opts?: ReparentOptions): void;
     /** Despawns the entity (`cascade`: with its subtree). One spawned in this batch is cancelled instead, unless it has children spawned in the batch and `cascade` is off (then the runtime decides). */
     despawn(entity: EntityArg, opts?: {
         cascade?: boolean;

package/dist/scene.js

@@ -231,14 +231,45 @@ export function treeOf(entities) {
     return build(null);
 }
 // -------------------------------------------------------------------------------------------- txn
-/** One level of the runtime's patch merge: an object merges into an object key by key; anything else replaces. */
-function mergeSet(into, set) {
+/**
+ * The runtime's patch merge (`merge_set`): merges one level deep; a null deletes the key it names. A top-level null
+ * removes the component; an object merges into an object component key by key, a null sub-key removing that sub-key;
+ * an object given for a component that is absent or not an object replaces it without its null sub-keys, and nulls
+ * alone leave no component (an explicitly given `{}` is kept); any other value replaces. `undefined` is not given (the
+ * encoder skips it).
+ */
+export function mergeSet(into, set) {
     const out = { ...into };
     for (const [k, v] of Object.entries(set)) {
         if (v === undefined)
             continue;
+        if (v === null) {
+            delete out[k];
+            continue;
+        }
+        if (!isObject(v)) {
+            out[k] = v;
+            continue;
+        }
+        const given = Object.entries(v).filter(([, s]) => s !== undefined);
         const old = out[k];
-        out[k] = isObject(old) && isObject(v) ? { ...old, ...v } : v;
+        if (isObject(old)) {
+            const next = { ...old };
+            for (const [s, sv] of given) {
+                if (sv === null)
+                    delete next[s];
+                else
+                    next[s] = sv;
+            }
+            out[k] = next;
+        }
+        else {
+            const kept = given.filter(([, s]) => s !== null);
+            if (kept.length === 0 && given.length > 0)
+                delete out[k];
+            else
+                out[k] = Object.fromEntries(kept);
+        }
     }
     return out;
 }
@@ -264,7 +295,7 @@ export class Txn {
         this.#ops.push({ op: "spawn", entity });
         return id;
     }
-    /** Sets components of the entity (one level deep: an object merges into an object). */
+    /** Sets components of the entity: merges one level deep; a null deletes the key it names. */
     patch(entity, set) {
         const id = idOf(entity);
         // A protected key is the runtime's to refuse: such a patch is sent as it is.
@@ -287,13 +318,19 @@ export class Txn {
         }
         this.#ops.push({ op: "rename", id, name });
     }
-    /** Moves the entity under `parent` (`null`: the world root), before or after a sibling (default: after the last). */
-    reparent(entity, parent, place) {
+    /**
+     * Moves the entity under `parent` (`null`: the world root), `before` or `after` a sibling (default: after the last).
+     * By default it keeps its world pose (the runtime's default: nothing sent); `preserveWorld: false` sends
+     * `preserve_world: false`, and it keeps its local xform.
+     */
+    reparent(entity, parent, opts = {}) {
         const op = { op: "reparent", id: idOf(entity), parent: parent === null ? null : idOf(parent, "parent") };
-        if (place && "before" in place)
-            op.before = idOf(place.before, "before");
-        else if (place && "after" in place)
-            op.after = idOf(place.after, "after");
+        if (opts.before !== undefined)
+            op.before = idOf(opts.before, "before");
+        else if (opts.after !== undefined)
+            op.after = idOf(opts.after, "after");
+        if (opts.preserveWorld === false)
+            op.preserve_world = false;
         this.#ops.push(op);
     }
     /** Despawns the entity (`cascade`: with its subtree). One spawned in this batch is cancelled instead, unless it has children spawned in the batch and `cascade` is off (then the runtime decides). */
@@ -1972,7 +2009,7 @@ export class SceneHandleImpl {
             patch: (entity, set) => this.#txn(t => t.patch(entity, set)),
             upsert: (kind, opts) => this.#upsert(kind, opts),
             rename: (entity, name) => this.#txn(t => t.rename(entity, name)),
-            reparent: (entity, parent, place) => this.#txn(t => t.reparent(entity, parent, place)),
+            reparent: (entity, parent, opts) => this.#txn(t => t.reparent(entity, parent, opts)),
             despawn: (entity, opts) => this.#txn(t => t.despawn(entity, opts)),
             setLocked: (entity, locked) => this.#txn(t => t.setLocked(entity, locked)),
         });

package/dist/session.d.ts

@@ -89,14 +89,24 @@ export declare function describeError(e: unknown): string;
  * GOAWAY looks like one).
  */
 export declare function closeError(err: Error | null): SynapseError;
-/** `https://host:port/<root>` → `http://host:port/certificate.sha256`, the broker's plain-HTTP helper. */
+/**
+ * `https://host[:port]` → `http://host:port/certificate.sha256`, the runtime's plain-HTTP helper on the
+ * runtime's own port (443 when the URL names none, as the Rust SDK). Before 2026-10-17 the default
+ * port was lost and a relay URL was asked on port 80, which no relay answers: a 2 s stall per attempt.
+ */
 export declare function brokerCertHelperUrl(brokerUrl: string): string;
+/** Whether `url` names a root (`/runtimes/<id>`, `/cluster/<c>/runtimes/<id>`): a relay, a deployment with a real certificate, never asked for a pin (`withRoot` makes the same split). */
+export declare function namesRoot(url: string): boolean;
 /**
  * The runtime's URL when the caller gave none: `SYNAPSE_ENDPOINT` (Bun/Node; the runtime sets it for every task it starts).
  * A browser has no environment: there, as with neither, `invalid_input`.
  */
 export declare function urlOrEndpoint(url: string | undefined): string;
-/** The certificate pin when the caller gave none (SDK §13): `SYNAPSE_BROKER_CERT_SHA256` (Bun/Node), then the helper, then `undefined` = unpinned. Per attempt. */
+/**
+ * The certificate pin when the caller gave none (SDK §13): `SYNAPSE_BROKER_CERT_SHA256` (Bun/Node); else, for a
+ * runtime URL (no path: a self-signed certificate, pinned), its helper; a URL that names a root (a relay) is
+ * never asked and connects unpinned, against the system's roots. `undefined` = unpinned. Per attempt.
+ */
 export declare function discoverBrokerCertSha256(brokerUrl: string, opts?: {
     timeoutMs?: number;
     signal?: AbortSignal;

package/dist/session.js

@@ -332,8 +332,20 @@ export function closeError(err) {
         return new SynapseError("unauthorized", { message: text.trim(), source: "broker", cause: err });
     return new SynapseError("connection_lost", { message: text.trim() || err.name, source: "transport", cause: err });
 }
-/** `https://host:port/<root>` → `http://host:port/certificate.sha256`, the broker's plain-HTTP helper. */
-export function brokerCertHelperUrl(brokerUrl) { const u = new URL(brokerUrl); return `http://${u.host}/certificate.sha256`; }
+/**
+ * `https://host[:port]` → `http://host:port/certificate.sha256`, the runtime's plain-HTTP helper on the
+ * runtime's own port (443 when the URL names none, as the Rust SDK). Before 2026-10-17 the default
+ * port was lost and a relay URL was asked on port 80, which no relay answers: a 2 s stall per attempt.
+ */
+export function brokerCertHelperUrl(brokerUrl) { const u = new URL(brokerUrl); return `http://${u.hostname}:${u.port || (u.protocol === "http:" ? "80" : "443")}/certificate.sha256`; }
+/** Whether `url` names a root (`/runtimes/<id>`, `/cluster/<c>/runtimes/<id>`): a relay, a deployment with a real certificate, never asked for a pin (`withRoot` makes the same split). */
+export function namesRoot(url) { try {
+    const p = new URL(url).pathname;
+    return p !== "" && p !== "/";
+}
+catch {
+    return false;
+} }
 /**
  * The runtime's URL when the caller gave none: `SYNAPSE_ENDPOINT` (Bun/Node; the runtime sets it for every task it starts).
  * A browser has no environment: there, as with neither, `invalid_input`.
@@ -347,22 +359,35 @@ export function urlOrEndpoint(url) {
     throw new SynapseError("invalid_input", { message: "no url given and SYNAPSE_ENDPOINT is not set", source: "sdk" });
 }
 const SHA256_HEX = /^[0-9a-f]{64}$/i;
-/** The certificate pin when the caller gave none (SDK §13): `SYNAPSE_BROKER_CERT_SHA256` (Bun/Node), then the helper, then `undefined` = unpinned. Per attempt. */
+/**
+ * The certificate pin when the caller gave none (SDK §13): `SYNAPSE_BROKER_CERT_SHA256` (Bun/Node); else, for a
+ * runtime URL (no path: a self-signed certificate, pinned), its helper; a URL that names a root (a relay) is
+ * never asked and connects unpinned, against the system's roots. `undefined` = unpinned. Per attempt.
+ */
 export async function discoverBrokerCertSha256(brokerUrl, opts = {}) {
     const env = globalThis.process?.env?.SYNAPSE_BROKER_CERT_SHA256?.trim();
     if (env)
         return env;
-    const signal = opts.signal ? AbortSignal.any([opts.signal, AbortSignal.timeout(opts.timeoutMs ?? 2000)]) : AbortSignal.timeout(opts.timeoutMs ?? 2000);
-    try {
-        const res = await fetch(brokerCertHelperUrl(brokerUrl), { signal });
-        if (!res.ok)
-            return undefined;
-        const text = (await res.text()).trim();
-        return SHA256_HEX.test(text) ? text : undefined;
-    }
-    catch {
+    if (namesRoot(brokerUrl))
         return undefined;
-    }
+    const timeoutMs = opts.timeoutMs ?? 2000;
+    const signal = opts.signal ? AbortSignal.any([opts.signal, AbortSignal.timeout(timeoutMs)]) : AbortSignal.timeout(timeoutMs);
+    const fetched = (async () => {
+        try {
+            const res = await fetch(brokerCertHelperUrl(brokerUrl), { signal });
+            if (!res.ok)
+                return undefined;
+            const text = (await res.text()).trim();
+            return SHA256_HEX.test(text) ? text : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    })();
+    // Bun does not abort a connect that gets no answer (measured 2026-10-17: a filtered port hung the dial for
+    // good); the race bounds the wait whatever the runtime does with the signal.
+    const r = await withTimeout(fetched, timeoutMs);
+    return r === TIMEOUT ? undefined : r;
 }
 /**
  * `token_from_url`: `url` without its `jwt=` query parameters, and the last non-empty one (as the relays