@myzonerocks/gosslens 0.12.0 → 0.13.0

package/dist/src/index.js

@@ -6,6 +6,14 @@
 // everything else (the frame graph, all six beauty effects, mirror and
 // rotation) straight to the engine.
 export const GOSS_OK = 0;
+/// The session's scope does not carry the verb an op needs. A host can grant this
+/// one; GOSS_UNSUPPORTED it cannot.
+export const GOSS_OUT_OF_SCOPE = 9;
+/// The mask for a set of verbs, which is what setScope takes.
+export function gossVerbMask(verbs) {
+    return verbs.reduce((mask, verb) => mask | (1 << verb), 0);
+}
+export const GOSS_AGAIN = 7;
 const FRAME_FLAG_MIRROR = 0x1;
 const FRAME_ROTATION_SHIFT = 8;
 const LENS_SIGNALS_BYTES = 232;
@@ -164,6 +172,25 @@ export class Gosslens {
         // use fit a number, and a number is what every caller masks against.
         return Number(this.mod.ccall("goss_capabilities", "number", [], []));
     }
+    /// The rails a lens declares that this build lacks, as GOSS_CAP_ bits; zero means
+    /// every one it asked for is here. A catalogue filters on this rather than
+    /// activating a lens to find out.
+    lensCapabilitiesMissing(manifestJson) {
+        const bytes = new TextEncoder().encode(manifestJson);
+        const ptr = this.mod.ccall("goss_alloc", "number", ["number"], [bytes.length]);
+        const out = this.mod.ccall("goss_alloc", "number", ["number"], [8]);
+        try {
+            this.mod.HEAPU8.set(bytes, ptr);
+            const status = this.mod.ccall("goss_lens_capabilities_missing", "number", ["number", "number", "number"], [ptr, bytes.length, out]);
+            if (status !== GOSS_OK)
+                return 0;
+            return this.mod.HEAPU32[out >> 2];
+        }
+        finally {
+            this.mod.ccall("goss_free", null, ["number", "number"], [out, 8]);
+            this.mod.ccall("goss_free", null, ["number", "number"], [ptr, bytes.length]);
+        }
+    }
     /// Loads gosslens_web.js and checks its ABI major version. A
     /// dynamic import, not static: bun's bundler would otherwise inline
     /// this file, breaking Emscripten's own import.meta.url-relative
@@ -171,9 +198,12 @@ export class Gosslens {
     static async load(canvas, wasmJsUrl) {
         const imported = (await import(/* @vite-ignore */ String(wasmJsUrl)));
         const mod = await imported.default({ canvas });
+        // The engine decides, rather than this file comparing against a literal major
+        // that would go stale the day the major moves.
         const version = mod.ccall("goss_abi_version", "number", [], []) >>> 0;
-        if (version >> 16 !== 0)
+        if (mod.ccall("goss_abi_check", "number", ["number"], [GOSS_ABI_MAJOR << 16]) !== GOSS_OK) {
             throw new Error(`gosslens abi major mismatch: ${version >> 16}`);
+        }
         return new Gosslens(mod, version);
     }
     /// The YCbCr to RGB conversion for a standard and range as one
@@ -788,6 +818,137 @@ export class GossEngine {
             sum += value;
         return sum;
     }
+    /// What the engine is doing now, as against what it was asked for. Every
+    /// field is measured. The u64 fields are read as their low word, which holds
+    /// the whole count at any rate this engine reaches.
+    /// What this build's media backend declares it encodes, as bit sets over the
+    /// codec and container enums, so a page asks rather than assuming.
+    mediaCapabilities() {
+        const bytes = 8 * 4;
+        const ptr = this.mod.ccall("goss_alloc", "number", ["number"], [bytes]);
+        try {
+            if (this.mod.ccall("goss_engine_media_capabilities", "number", ["number", "number"], [this.handle, ptr]) !== GOSS_OK)
+                return null;
+            const w = (offset) => this.mod.HEAPU32[(ptr + offset) >> 2];
+            return {
+                videoCodecs: w(0),
+                audioCodecs: w(4),
+                containers: w(8),
+                maxWidth: w(12),
+                maxHeight: w(16),
+                maxBitDepth: w(20),
+                hdr: w(24) !== 0,
+                zeroCopy: w(28) !== 0,
+            };
+        }
+        finally {
+            this.mod.ccall("goss_free", null, ["number", "number"], [ptr, bytes]);
+        }
+    }
+    /// Everything capturable. Empty where permission has not been granted, so
+    /// prompt rather than treating it as an error.
+    screens() {
+        const countPtr = this.mod.ccall("goss_alloc", "number", ["number"], [4]);
+        const entryPtr = this.mod.ccall("goss_alloc", "number", ["number"], [40]);
+        const lenPtr = this.mod.ccall("goss_alloc", "number", ["number"], [8]);
+        const out = [];
+        try {
+            if (this.mod.ccall("goss_engine_screen_count", "number", ["number", "number"], [this.handle, countPtr]) !== GOSS_OK)
+                return out;
+            const count = this.mod.HEAPU32[countPtr >> 2];
+            for (let i = 0; i < count; i += 1) {
+                if (this.mod.ccall("goss_engine_screen_at", "number", ["number", "number", "number"], [this.handle, i, entryPtr]) !== GOSS_OK)
+                    continue;
+                const f = (off) => this.mod.HEAPF32[(entryPtr + off) >> 2];
+                const u = (off) => this.mod.HEAPU32[(entryPtr + off) >> 2];
+                this.mod.ccall("goss_engine_screen_title", "number", ["number", "number", "number", "number", "number"], [this.handle, i, 0, 0, lenPtr]);
+                const needed = this.mod.HEAPU32[lenPtr >> 2];
+                let title = "";
+                if (needed > 0) {
+                    const titlePtr = this.mod.ccall("goss_alloc", "number", ["number"], [needed]);
+                    try {
+                        if (this.mod.ccall("goss_engine_screen_title", "number", ["number", "number", "number", "number", "number"], [this.handle, i, titlePtr, needed, lenPtr]) === GOSS_OK) {
+                            title = new TextDecoder().decode(this.mod.HEAPU8.subarray(titlePtr, titlePtr + needed));
+                        }
+                    }
+                    finally {
+                        this.mod.ccall("goss_free", null, ["number", "number"], [titlePtr, needed]);
+                    }
+                }
+                out.push({ id: u(0), kind: u(8), title, logicalWidth: f(12), logicalHeight: f(16), originX: f(20), originY: f(24), scale: f(28) });
+            }
+            return out;
+        }
+        finally {
+            this.mod.ccall("goss_free", null, ["number", "number"], [countPtr, 4]);
+            this.mod.ccall("goss_free", null, ["number", "number"], [entryPtr, 40]);
+            this.mod.ccall("goss_free", null, ["number", "number"], [lenPtr, 8]);
+        }
+    }
+    /// The operators a model needs that this build does not implement. An empty
+    /// list means the model runs; anything in it names exactly what is missing.
+    mlOpSupport(model) {
+        const modelPtr = this.mod.ccall("goss_alloc", "number", ["number"], [model.length]);
+        const lenPtr = this.mod.ccall("goss_alloc", "number", ["number"], [8]);
+        this.mod.HEAPU8.set(model, modelPtr);
+        let capacity = 256;
+        try {
+            while (capacity <= 1 << 16) {
+                const outPtr = this.mod.ccall("goss_alloc", "number", ["number"], [capacity]);
+                try {
+                    const status = this.mod.ccall("goss_ml_op_support", "number", ["number", "number", "number", "number", "number"], [modelPtr, model.length, outPtr, capacity, lenPtr]);
+                    if (status !== GOSS_OK && status !== GOSS_AGAIN)
+                        return [];
+                    const needed = this.mod.HEAPU32[lenPtr >> 2];
+                    if (needed <= capacity) {
+                        const text = new TextDecoder().decode(this.mod.HEAPU8.subarray(outPtr, outPtr + needed));
+                        return text.split("\n").filter((line) => line.length !== 0);
+                    }
+                    capacity = needed;
+                }
+                finally {
+                    this.mod.ccall("goss_free", null, ["number", "number"], [outPtr, capacity]);
+                }
+            }
+            return [];
+        }
+        finally {
+            this.mod.ccall("goss_free", null, ["number", "number"], [modelPtr, model.length]);
+            this.mod.ccall("goss_free", null, ["number", "number"], [lenPtr, 8]);
+        }
+    }
+    engineReport() {
+        const bytes = ENGINE_REPORT_BYTES;
+        const ptr = this.mod.ccall("goss_alloc", "number", ["number"], [bytes]);
+        try {
+            if (this.mod.ccall("goss_engine_read_report", "number", ["number", "number"], [this.handle, ptr]) !== 0)
+                return null;
+            // The low word of each u64 is the whole count at any size this engine
+            // reaches, and reading it avoids a BigInt in the hot read.
+            const w = (offset) => this.mod.HEAPU32[(ptr + offset) >> 2];
+            return {
+                rendererBackend: w(0),
+                zeroCopyImport: w(4) !== 0,
+                texturePoolCapacity: w(8),
+                texturePoolLive: w(12),
+                texturePoolPeak: w(16),
+                texturePoolExhausted: w(20),
+                stagingPoolCapacity: w(24),
+                stagingPoolLive: w(28),
+                stagingPoolPeak: w(32),
+                stagingPoolExhausted: w(36),
+                texturePoolBins: w(40),
+                texturePoolBinsRefused: w(44),
+                stagingPoolBins: w(48),
+                bgfxLiveBytes: w(56),
+                bgfxAllocCallsLastFrame: w(64),
+                bgfxBytesLastFrame: w(72),
+            };
+        }
+        finally {
+            this.mod.ccall("goss_free", null, ["number", "number"], [ptr, bytes]);
+        }
+    }
     destroy() {
         this.mod.ccall("goss_engine_destroy", null, ["number"], [this.handle]);
         // The renderer is gone now, so bgfx no longer references the selector.
@@ -797,10 +958,35 @@ export class GossEngine {
         this.selectorCapacity = 0;
     }
 }
-/// Per-preview runtime: frame submission, beauty, tracking, lens. Owns
-/// its own scratch allocations (frame descriptor, pixel buffer,
-/// landmarks) rather than one shared per-engine pool - matches every
-/// other SDK's own per-session confinement.
+/// The ABI major these bindings were generated against: handing the engine its own
+/// version back would always match and test nothing. The major, not the whole version,
+/// because only the major decides compatibility. Held to the header by the abi gate.
+const GOSS_ABI_MAJOR = 0;
+/// What a report struct measures, checked against the engine's own layout.
+const ENGINE_REPORT_BYTES = 80;
+const SESSION_REPORT_BYTES = 88;
+/// What a lens node is doing, as against what its manifest asked for.
+export var GossNodeState;
+(function (GossNodeState) {
+    GossNodeState[GossNodeState["Ready"] = 0] = "Ready";
+    GossNodeState[GossNodeState["Degraded"] = 1] = "Degraded";
+    GossNodeState[GossNodeState["Failed"] = 2] = "Failed";
+})(GossNodeState || (GossNodeState = {}));
+/// Why a node is not ready.
+export var GossNodeReason;
+(function (GossNodeReason) {
+    GossNodeReason[GossNodeReason["None"] = 0] = "None";
+    GossNodeReason[GossNodeReason["OutOfMemory"] = 1] = "OutOfMemory";
+    GossNodeReason[GossNodeReason["AssetMissing"] = 2] = "AssetMissing";
+    GossNodeReason[GossNodeReason["AssetMalformed"] = 3] = "AssetMalformed";
+    GossNodeReason[GossNodeReason["AssetTooLarge"] = 4] = "AssetTooLarge";
+    GossNodeReason[GossNodeReason["ShaderMissing"] = 5] = "ShaderMissing";
+    GossNodeReason[GossNodeReason["ShaderLinkFailed"] = 6] = "ShaderLinkFailed";
+    GossNodeReason[GossNodeReason["ModelRejected"] = 7] = "ModelRejected";
+    GossNodeReason[GossNodeReason["ModelUnsupported"] = 8] = "ModelUnsupported";
+    GossNodeReason[GossNodeReason["CapabilityUnavailable"] = 9] = "CapabilityUnavailable";
+    GossNodeReason[GossNodeReason["ConstraintFailed"] = 10] = "ConstraintFailed";
+})(GossNodeReason || (GossNodeReason = {}));
 export class GossSession {
     mod;
     handle;
@@ -834,6 +1020,7 @@ export class GossSession {
     /// freed in destroy() - no per-call wasm heap churn.
     scratchPtr = 0;
     scratchCapacity = 0;
+    lensChangeInFlight = false;
     constructor(mod, handle) {
         this.mod = mod;
         this.handle = handle;
@@ -905,15 +1092,40 @@ export class GossSession {
     /// A lens built entirely from beauty.* nodes (beauty-baseline, say)
     /// activates and runs for real regardless, since those go through
     /// applyWebBeautyChain's own embedded shaders, not a per-lens one.
-    activateLens(manifestJson) {
+    /// Activates a lens, resolving false when it is live but a node the manifest did
+    /// not mark optional could not do what it asked; nodeReports says which and why.
+    /// On the WebGPU build this suspends and creates work that reaches Dawn, so not
+    /// awaiting left the module suspended and the next render reentered it.
+    async activateLens(manifestJson) {
         const bytes = new TextEncoder().encode(manifestJson);
         const ptr = this.mod.ccall("goss_alloc", "number", ["number"], [bytes.length]);
         this.mod.HEAPU8.set(bytes, ptr);
-        this.mod.ccall("goss_session_activate_lens", "number", ["number", "number", "number"], [this.handle, ptr, bytes.length]);
-        this.mod.ccall("goss_free", null, ["number", "number"], [ptr, bytes.length]);
+        this.lensChangeInFlight = true;
+        try {
+            const status = (await this.mod.ccall("goss_session_activate_lens", "number", ["number", "number", "number"], [this.handle, ptr, bytes.length], { async: true }));
+            return status === GOSS_OK;
+        }
+        finally {
+            this.lensChangeInFlight = false;
+            this.mod.ccall("goss_free", null, ["number", "number"], [ptr, bytes.length]);
+        }
     }
-    deactivateLens() {
-        this.mod.ccall("goss_session_deactivate_lens", null, ["number"], [this.handle]);
+    /// Deactivation destroys the same resources, so it suspends for the same
+    /// reason and is awaited for the same reason.
+    async deactivateLens() {
+        this.lensChangeInFlight = true;
+        try {
+            await this.mod.ccall("goss_session_deactivate_lens", null, ["number"], [this.handle], { async: true });
+        }
+        finally {
+            this.lensChangeInFlight = false;
+        }
+    }
+    /// True while an activation or deactivation is unwound. A render during that
+    /// window reenters a suspended module, which Asyncify cannot do, so a caller
+    /// driving its own frame loop skips the frame rather than calling in.
+    get isLensChangeInFlight() {
+        return this.lensChangeInFlight;
     }
     /// Advances the active lens's triggers/param ramps by dtUs, evaluating
     /// them against signals - omitted fields read as false/zero, so a bare
@@ -975,6 +1187,234 @@ export class GossSession {
     /// Casts a world-space ray against the submitted world mesh, returning the
     /// nearest surface hit `{ point, distance }`, or null when no mesh is
     /// submitted or the ray misses. A tap-to-place lens anchors content there.
+    /// Decodes a PNG to packed RGBA8 through the decoder the engine already carries,
+    /// for a caller holding an encoded image and none of its own.
+    decodePng(bytes) {
+        const inPtr = this.mod.ccall("goss_alloc", "number", ["number"], [bytes.length]);
+        const wPtr = this.mod.ccall("goss_alloc", "number", ["number"], [4]);
+        const hPtr = this.mod.ccall("goss_alloc", "number", ["number"], [4]);
+        const lenPtr = this.mod.ccall("goss_alloc", "number", ["number"], [8]);
+        let outPtr = 0;
+        let needed = 0;
+        try {
+            this.mod.HEAPU8.set(bytes, inPtr);
+            const args = ["number", "number", "number", "number", "number", "number", "number"];
+            this.mod.ccall("goss_engine_decode_png", "number", args, [inPtr, bytes.length, 0, 0, wPtr, hPtr, lenPtr]);
+            needed = this.mod.HEAPU32[lenPtr >> 2];
+            if (needed === 0)
+                return null;
+            outPtr = this.mod.ccall("goss_alloc", "number", ["number"], [needed]);
+            if (this.mod.ccall("goss_engine_decode_png", "number", args, [inPtr, bytes.length, outPtr, needed, wPtr, hPtr, lenPtr]) !== GOSS_OK)
+                return null;
+            return {
+                rgba: this.mod.HEAPU8.slice(outPtr, outPtr + needed),
+                width: this.mod.HEAPU32[wPtr >> 2],
+                height: this.mod.HEAPU32[hPtr >> 2],
+            };
+        }
+        finally {
+            this.mod.ccall("goss_free", null, ["number", "number"], [inPtr, bytes.length]);
+            if (outPtr !== 0)
+                this.mod.ccall("goss_free", null, ["number", "number"], [outPtr, needed]);
+            for (const [ptr, size] of [[wPtr, 4], [hPtr, 4], [lenPtr, 8]]) {
+                this.mod.ccall("goss_free", null, ["number", "number"], [ptr, size]);
+            }
+        }
+    }
+    /// A walkable route over the submitted world mesh, so an agent walks content
+    /// across real scanned ground. Null when no mesh is submitted or no route exists.
+    pathAcrossWorld(start, goal) {
+        const capacity = 256;
+        const aPtr = this.mod.ccall("goss_alloc", "number", ["number"], [12]);
+        const bPtr = this.mod.ccall("goss_alloc", "number", ["number"], [12]);
+        const outBytes = capacity * 12;
+        const outPtr = this.mod.ccall("goss_alloc", "number", ["number"], [outBytes]);
+        const countPtr = this.mod.ccall("goss_alloc", "number", ["number"], [8]);
+        try {
+            this.mod.HEAPF32.set(start, aPtr / 4);
+            this.mod.HEAPF32.set(goal, bPtr / 4);
+            const args = ["number", "number", "number", "number", "number", "number"];
+            if (this.mod.ccall("goss_session_path_across_world", "number", args, [this.handle, aPtr, bPtr, outPtr, capacity, countPtr]) !== GOSS_OK)
+                return null;
+            const found = Math.min(this.mod.HEAPU32[countPtr >> 2], capacity);
+            const out = [];
+            for (let i = 0; i < found; i += 1) {
+                const w = (outPtr >> 2) + i * 3;
+                out.push([this.mod.HEAPF32[w], this.mod.HEAPF32[w + 1], this.mod.HEAPF32[w + 2]]);
+            }
+            return out;
+        }
+        finally {
+            for (const [ptr, bytes] of [[aPtr, 12], [bPtr, 12], [outPtr, outBytes], [countPtr, 8]]) {
+                this.mod.ccall("goss_free", null, ["number", "number"], [ptr, bytes]);
+            }
+        }
+    }
+    /// What a submitted plane is, as a named kind rather than the platform's own
+    /// number, and whether a thing can rest on it.
+    planeKind(planeId) {
+        const kindPtr = this.mod.ccall("goss_alloc", "number", ["number"], [4]);
+        const bearingPtr = this.mod.ccall("goss_alloc", "number", ["number"], [4]);
+        try {
+            const args = ["number", "number", "number", "number"];
+            if (this.mod.ccall("goss_session_plane_kind", "number", args, [this.handle, planeId, kindPtr, bearingPtr]) !== GOSS_OK)
+                return null;
+            return { kind: this.mod.HEAPU32[kindPtr >> 2], bearing: this.mod.HEAPU32[bearingPtr >> 2] === 1 };
+        }
+        finally {
+            this.mod.ccall("goss_free", null, ["number", "number"], [kindPtr, 4]);
+            this.mod.ccall("goss_free", null, ["number", "number"], [bearingPtr, 4]);
+        }
+    }
+    /// The plane this session would call the floor: the lowest bearing surface it
+    /// has been shown, or null when it has been shown none.
+    floorPlaneId() {
+        const ptr = this.mod.ccall("goss_alloc", "number", ["number"], [8]);
+        try {
+            if (this.mod.ccall("goss_session_floor_plane", "number", ["number", "number"], [this.handle, ptr]) !== GOSS_OK)
+                return null;
+            return this.mod.HEAPU32[ptr >> 2];
+        }
+        finally {
+            this.mod.ccall("goss_free", null, ["number", "number"], [ptr, 8]);
+        }
+    }
+    /// Where a footprint fits, best surface first: the bearing plane with the most
+    /// room left afterwards. An empty array is an answer.
+    placeOn(item, occupants = []) {
+        const itemPtr = this.mod.ccall("goss_alloc", "number", ["number"], [12]);
+        const occupantBytes = occupants.length * 24;
+        const occupantPtr = occupants.length === 0 ? 0 : this.mod.ccall("goss_alloc", "number", ["number"], [occupantBytes]);
+        const capacity = 32;
+        const outBytes = capacity * 24;
+        const outPtr = this.mod.ccall("goss_alloc", "number", ["number"], [outBytes]);
+        const countPtr = this.mod.ccall("goss_alloc", "number", ["number"], [8]);
+        try {
+            this.mod.HEAPF32.set([item.width, item.depth, item.height ?? 0], itemPtr / 4);
+            // Each occupant is a u64 id then four floats: the id is written as two words
+            // because the heap view is 32-bit and an id past 2^32 is not a plane id any
+            // platform hands out.
+            occupants.forEach((o, i) => {
+                const base = occupantPtr + i * 24;
+                this.mod.HEAPU32[base >> 2] = o.planeId;
+                this.mod.HEAPU32[(base >> 2) + 1] = 0;
+                this.mod.HEAPF32.set([o.x, o.z, o.width, o.depth], (base + 8) / 4);
+            });
+            const args = ["number", "number", "number", "number", "number", "number", "number"];
+            const status = this.mod.ccall("goss_session_place_on", "number", args, [this.handle, itemPtr, occupantPtr, occupants.length, outPtr, capacity, countPtr]);
+            if (status !== GOSS_OK && status !== GOSS_AGAIN)
+                return [];
+            const found = Math.min(this.mod.HEAPU32[countPtr >> 2], capacity);
+            const out = [];
+            for (let i = 0; i < found; i += 1) {
+                const base = outPtr + i * 24;
+                const floats = (base + 8) / 4;
+                out.push({
+                    planeId: this.mod.HEAPU32[base >> 2],
+                    position: [this.mod.HEAPF32[floats], this.mod.HEAPF32[floats + 1], this.mod.HEAPF32[floats + 2]],
+                    freeFraction: this.mod.HEAPF32[floats + 3],
+                });
+            }
+            return out;
+        }
+        finally {
+            this.mod.ccall("goss_free", null, ["number", "number"], [itemPtr, 12]);
+            if (occupantPtr !== 0)
+                this.mod.ccall("goss_free", null, ["number", "number"], [occupantPtr, occupantBytes]);
+            this.mod.ccall("goss_free", null, ["number", "number"], [outPtr, outBytes]);
+            this.mod.ccall("goss_free", null, ["number", "number"], [countPtr, 8]);
+        }
+    }
+    /// Point to point in metres with its uncertainty. `known` is false when either
+    /// end vouched for no accuracy, so a sigma of zero is never read as certainty.
+    measureBetween(from, to, fromAccuracyM = 0, toAccuracyM = 0) {
+        const aPtr = this.mod.ccall("goss_alloc", "number", ["number"], [12]);
+        const bPtr = this.mod.ccall("goss_alloc", "number", ["number"], [12]);
+        const valuePtr = this.mod.ccall("goss_alloc", "number", ["number"], [4]);
+        const sigmaPtr = this.mod.ccall("goss_alloc", "number", ["number"], [4]);
+        const knownPtr = this.mod.ccall("goss_alloc", "number", ["number"], [4]);
+        try {
+            this.mod.HEAPF32.set(from, aPtr / 4);
+            this.mod.HEAPF32.set(to, bPtr / 4);
+            const args = ["number", "number", "number", "number", "number", "number", "number", "number"];
+            const status = this.mod.ccall("goss_session_measure_between", "number", args, [this.handle, aPtr, fromAccuracyM, bPtr, toAccuracyM, valuePtr, sigmaPtr, knownPtr]);
+            if (status !== GOSS_OK)
+                return null;
+            return {
+                metres: this.mod.HEAPF32[valuePtr >> 2],
+                sigma: this.mod.HEAPF32[sigmaPtr >> 2],
+                known: this.mod.HEAPU32[knownPtr >> 2] === 1,
+            };
+        }
+        finally {
+            for (const [ptr, bytes] of [[aPtr, 12], [bPtr, 12], [valuePtr, 4], [sigmaPtr, 4], [knownPtr, 4]]) {
+                this.mod.ccall("goss_free", null, ["number", "number"], [ptr, bytes]);
+            }
+        }
+    }
+    /// What this device can offer another: one landmark per world anchor it holds,
+    /// in its own frame. A pose never crosses.
+    sharedLandmarks() {
+        const capacity = 32;
+        const bytes = capacity * 24;
+        const outPtr = this.mod.ccall("goss_alloc", "number", ["number"], [bytes]);
+        const countPtr = this.mod.ccall("goss_alloc", "number", ["number"], [8]);
+        try {
+            const args = ["number", "number", "number", "number"];
+            const status = this.mod.ccall("goss_session_shared_landmarks", "number", args, [this.handle, outPtr, capacity, countPtr]);
+            if (status !== GOSS_OK && status !== GOSS_AGAIN)
+                return [];
+            const found = Math.min(this.mod.HEAPU32[countPtr >> 2], capacity);
+            const out = [];
+            for (let i = 0; i < found; i += 1) {
+                const base = outPtr + i * 24;
+                const floats = (base + 8) / 4;
+                out.push({
+                    id: this.mod.HEAPU32[base >> 2],
+                    position: [this.mod.HEAPF32[floats], this.mod.HEAPF32[floats + 1], this.mod.HEAPF32[floats + 2]],
+                    confidence: this.mod.HEAPF32[floats + 3],
+                });
+            }
+            return out;
+        }
+        finally {
+            this.mod.ccall("goss_free", null, ["number", "number"], [outPtr, bytes]);
+            this.mod.ccall("goss_free", null, ["number", "number"], [countPtr, 8]);
+        }
+    }
+    /// The transform from the sender's origin into this one, column-major, with the
+    /// fit it achieved. Null when fewer than three landmarks matched, which cannot
+    /// fix a rigid transform.
+    alignShared(theirs) {
+        const bytes = Math.max(theirs.length, 1) * 24;
+        const listPtr = this.mod.ccall("goss_alloc", "number", ["number"], [bytes]);
+        const transformPtr = this.mod.ccall("goss_alloc", "number", ["number"], [64]);
+        const rmsPtr = this.mod.ccall("goss_alloc", "number", ["number"], [4]);
+        const matchedPtr = this.mod.ccall("goss_alloc", "number", ["number"], [4]);
+        try {
+            theirs.forEach((l, i) => {
+                const base = listPtr + i * 24;
+                this.mod.HEAPU32[base >> 2] = l.id;
+                this.mod.HEAPU32[(base >> 2) + 1] = 0;
+                this.mod.HEAPF32.set([l.position[0], l.position[1], l.position[2], l.confidence ?? 1], (base + 8) / 4);
+            });
+            const args = ["number", "number", "number", "number", "number", "number"];
+            const status = this.mod.ccall("goss_session_align_shared", "number", args, [this.handle, listPtr, theirs.length, transformPtr, rmsPtr, matchedPtr]);
+            if (status !== GOSS_OK)
+                return null;
+            return {
+                transform: this.mod.HEAPF32.slice(transformPtr >> 2, (transformPtr >> 2) + 16),
+                rmsError: this.mod.HEAPF32[rmsPtr >> 2],
+                matched: this.mod.HEAPU32[matchedPtr >> 2],
+            };
+        }
+        finally {
+            this.mod.ccall("goss_free", null, ["number", "number"], [listPtr, bytes]);
+            this.mod.ccall("goss_free", null, ["number", "number"], [transformPtr, 64]);
+            this.mod.ccall("goss_free", null, ["number", "number"], [rmsPtr, 4]);
+            this.mod.ccall("goss_free", null, ["number", "number"], [matchedPtr, 4]);
+        }
+    }
     raycastWorldMesh(origin, direction) {
         const oPtr = this.mod.ccall("goss_alloc", "number", ["number"], [12]);
         this.mod.HEAPF32.set(origin, oPtr / 4);
@@ -2366,6 +2806,621 @@ export class GossSession {
         this.mod.ccall("goss_session_write_reconstruction", "number", ["number", "number", "number"], [this.handle, ptr, gaussians.length / 14]);
         this.mod.ccall("goss_free", null, ["number", "number"], [ptr, bytes]);
     }
+    /// Every section this build writes, asked of the engine rather than assumed: a
+    /// hand-written mask excluded the embedding section the day it was added.
+    selectAll() {
+        return this.mod.ccall("goss_perception_select_all", "number", [], []);
+    }
+    /// How many verbs this engine build knows, asked of the engine rather than taken
+    /// from the enum, so a newer engine behind this wrapper is not misread.
+    verbCount() {
+        return this.mod.ccall("goss_scope_verb_count", "number", [], []);
+    }
+    /// The engine's own name for a verb, so a refusal reads as a sentence and a
+    /// permission prompt reads as words rather than a bitmask.
+    verbName(verb) {
+        const lenPtr = this.mod.ccall("goss_alloc", "number", ["number"], [8]);
+        let outPtr = 0;
+        let needed = 0;
+        try {
+            const args = ["number", "number", "number", "number"];
+            this.mod.ccall("goss_scope_verb_name", "number", args, [verb, 0, 0, lenPtr]);
+            needed = this.mod.HEAPU32[lenPtr >> 2];
+            if (needed === 0)
+                return null;
+            outPtr = this.mod.ccall("goss_alloc", "number", ["number"], [needed]);
+            if (this.mod.ccall("goss_scope_verb_name", "number", args, [verb, outPtr, needed, lenPtr]) !== GOSS_OK)
+                return null;
+            return new TextDecoder().decode(this.mod.HEAPU8.subarray(outPtr, outPtr + needed));
+        }
+        finally {
+            this.mod.ccall("goss_free", null, ["number", "number"], [lenPtr, 8]);
+            if (outPtr !== 0)
+                this.mod.ccall("goss_free", null, ["number", "number"], [outPtr, needed]);
+        }
+    }
+    /// One versioned record of what the engine currently sees. Every section
+    /// carries its own tag, version and byte length, so a consumer built against an
+    /// older schema steps over what it does not know. Sized in one retry.
+    perceptionSnapshot(select = this.selectAll()) {
+        const lenPtr = this.mod.ccall("goss_alloc", "number", ["number"], [4]);
+        try {
+            this.mod.ccall("goss_session_perception_snapshot", "number", ["number", "number", "number", "number", "number"], [this.handle, select, 0, 0, lenPtr]);
+            const needed = this.mod.HEAPU32[lenPtr >> 2];
+            if (needed === 0)
+                return null;
+            const ptr = this.mod.ccall("goss_alloc", "number", ["number"], [needed]);
+            try {
+                const status = this.mod.ccall("goss_session_perception_snapshot", "number", ["number", "number", "number", "number", "number"], [this.handle, select, ptr, needed, lenPtr]);
+                if (status !== GOSS_OK)
+                    return null;
+                const written = this.mod.HEAPU32[lenPtr >> 2];
+                return this.mod.HEAPU8.slice(ptr, ptr + written);
+            }
+            finally {
+                this.mod.ccall("goss_free", null, ["number", "number"], [ptr, needed]);
+            }
+        }
+        finally {
+            this.mod.ccall("goss_free", null, ["number", "number"], [lenPtr, 4]);
+        }
+    }
+    /// The same record as compact JSON, for a gateway that speaks it.
+    perceptionJson(select = this.selectAll()) {
+        const lenPtr = this.mod.ccall("goss_alloc", "number", ["number"], [4]);
+        try {
+            this.mod.ccall("goss_session_perception_json", "number", ["number", "number", "number", "number", "number"], [this.handle, select, 0, 0, lenPtr]);
+            const needed = this.mod.HEAPU32[lenPtr >> 2];
+            if (needed === 0)
+                return null;
+            const ptr = this.mod.ccall("goss_alloc", "number", ["number"], [needed]);
+            try {
+                const status = this.mod.ccall("goss_session_perception_json", "number", ["number", "number", "number", "number", "number"], [this.handle, select, ptr, needed, lenPtr]);
+                if (status !== GOSS_OK)
+                    return null;
+                const written = this.mod.HEAPU32[lenPtr >> 2];
+                return new TextDecoder().decode(this.mod.HEAPU8.slice(ptr, ptr + written));
+            }
+            finally {
+                this.mod.ccall("goss_free", null, ["number", "number"], [ptr, needed]);
+            }
+        }
+        finally {
+            this.mod.ccall("goss_free", null, ["number", "number"], [lenPtr, 4]);
+        }
+    }
+    /// Opens a screen as a source. A scale of zero takes the surface's own.
+    openScreen(surfaceId, scale = 0) {
+        const ptr = this.mod.ccall("goss_alloc", "number", ["number"], [4]);
+        try {
+            if (this.mod.ccall("goss_session_open_screen", "number", ["number", "number", "number", "number"], [this.handle, surfaceId, scale, ptr]) !== GOSS_OK)
+                return null;
+            return this.mod.HEAPU32[ptr >> 2];
+        }
+        finally {
+            this.mod.ccall("goss_free", null, ["number", "number"], [ptr, 4]);
+        }
+    }
+    closeScreen(screen) {
+        return this.mod.ccall("goss_session_close_screen", "number", ["number", "number"], [this.handle, screen]) === GOSS_OK;
+    }
+    /// Submits the newest frame. False when the screen has not changed, so a still
+    /// desktop costs nothing.
+    stepScreen(screen, source = "") {
+        const bytes = new TextEncoder().encode(source);
+        const ptr = bytes.length === 0 ? 0 : this.mod.ccall("goss_alloc", "number", ["number"], [bytes.length]);
+        try {
+            if (ptr !== 0)
+                this.mod.HEAPU8.set(bytes, ptr);
+            return this.mod.ccall("goss_session_step_screen", "number", ["number", "number", "number", "number"], [this.handle, screen, ptr, bytes.length]) === GOSS_OK;
+        }
+        finally {
+            if (ptr !== 0)
+                this.mod.ccall("goss_free", null, ["number", "number"], [ptr, bytes.length]);
+        }
+    }
+    /// Where a normalized point lands: logical points, backing pixels, desktop.
+    screenPoint(screen, x, y) {
+        const ptr = this.mod.ccall("goss_alloc", "number", ["number"], [24]);
+        try {
+            if (this.mod.ccall("goss_session_screen_point", "number", ["number", "number", "number", "number", "number", "number", "number"], [this.handle, screen, x, y, ptr, ptr + 8, ptr + 16]) !== GOSS_OK)
+                return null;
+            const f = (off) => this.mod.HEAPF32[(ptr + off) >> 2];
+            return { logical: [f(0), f(4)], pixel: [f(8), f(12)], desktop: [f(16), f(20)] };
+        }
+        finally {
+            this.mod.ccall("goss_free", null, ["number", "number"], [ptr, 24]);
+        }
+    }
+    /// Narrows what this session answers. A session opens fully permissive; a read
+    /// out of scope is dropped from the record rather than failing, and a verb out
+    /// of scope is refused.
+    setScope(sections, verbs) {
+        return this.mod.ccall("goss_session_set_scope", "number", ["number", "number", "number"], [this.handle, sections, verbs]) === GOSS_OK;
+    }
+    scope() {
+        const sectionsPtr = this.mod.ccall("goss_alloc", "number", ["number"], [4]);
+        const verbsPtr = this.mod.ccall("goss_alloc", "number", ["number"], [4]);
+        try {
+            if (this.mod.ccall("goss_session_scope", "number", ["number", "number", "number"], [this.handle, sectionsPtr, verbsPtr]) !== GOSS_OK)
+                return { sections: 0, verbs: 0 };
+            return { sections: this.mod.HEAPU32[sectionsPtr >> 2], verbs: this.mod.HEAPU32[verbsPtr >> 2] };
+        }
+        finally {
+            this.mod.ccall("goss_free", null, ["number", "number"], [sectionsPtr, 4]);
+            this.mod.ccall("goss_free", null, ["number", "number"], [verbsPtr, 4]);
+        }
+    }
+    /// Opens the memory plane. Nothing is remembered until this is called, and
+    /// the bound is yours, so the memory you were promised is the memory you get.
+    memoryOpen(dim, maxEntries = 4096) {
+        return this.mod.ccall("goss_session_memory_open", "number", ["number", "number", "number"], [this.handle, dim, maxEntries]) === GOSS_OK;
+    }
+    memoryClose() {
+        return this.mod.ccall("goss_session_memory_close", "number", ["number"], [this.handle]) === GOSS_OK;
+    }
+    /// Remembers one embedding; the same id replaces rather than duplicating.
+    remember(id, embedding) {
+        const bytes = embedding.length * 4;
+        const ptr = this.mod.ccall("goss_alloc", "number", ["number"], [bytes]);
+        try {
+            this.mod.HEAPF32.set(embedding, ptr >> 2);
+            return this.mod.ccall("goss_session_memory_remember", "number", ["number", "number", "number", "number"], [this.handle, id, ptr, embedding.length]) === GOSS_OK;
+        }
+        finally {
+            this.mod.ccall("goss_free", null, ["number", "number"], [ptr, bytes]);
+        }
+    }
+    forget(id) {
+        return this.mod.ccall("goss_session_memory_forget", "number", ["number", "number"], [this.handle, id]) === GOSS_OK;
+    }
+    /// The nearest remembered embeddings, fewer than k on a smaller memory rather
+    /// than padded with nothing.
+    memorySearch(query, k = 8) {
+        const queryBytes = query.length * 4;
+        const queryPtr = this.mod.ccall("goss_alloc", "number", ["number"], [queryBytes]);
+        const idsPtr = this.mod.ccall("goss_alloc", "number", ["number"], [k * 8]);
+        const scoresPtr = this.mod.ccall("goss_alloc", "number", ["number"], [k * 4]);
+        const countPtr = this.mod.ccall("goss_alloc", "number", ["number"], [4]);
+        try {
+            this.mod.HEAPF32.set(query, queryPtr >> 2);
+            if (this.mod.ccall("goss_session_memory_search", "number", ["number", "number", "number", "number", "number", "number", "number"], [this.handle, queryPtr, query.length, k, idsPtr, scoresPtr, countPtr]) !== GOSS_OK)
+                return [];
+            const count = this.mod.HEAPU32[countPtr >> 2];
+            const out = [];
+            for (let i = 0; i < count; i += 1) {
+                // The low word of the id is the whole value at any count this engine
+                // reaches, and reading it avoids a BigInt in the hot read.
+                out.push({ id: this.mod.HEAPU32[(idsPtr + i * 8) >> 2], score: this.mod.HEAPF32[(scoresPtr + i * 4) >> 2] });
+            }
+            return out;
+        }
+        finally {
+            this.mod.ccall("goss_free", null, ["number", "number"], [queryPtr, queryBytes]);
+            this.mod.ccall("goss_free", null, ["number", "number"], [idsPtr, k * 8]);
+            this.mod.ccall("goss_free", null, ["number", "number"], [scoresPtr, k * 4]);
+            this.mod.ccall("goss_free", null, ["number", "number"], [countPtr, 4]);
+        }
+    }
+    memoryStats() {
+        const countPtr = this.mod.ccall("goss_alloc", "number", ["number"], [4]);
+        const bytesPtr = this.mod.ccall("goss_alloc", "number", ["number"], [8]);
+        try {
+            if (this.mod.ccall("goss_session_memory_stats", "number", ["number", "number", "number"], [this.handle, countPtr, bytesPtr]) !== GOSS_OK)
+                return { count: 0, bytes: 0 };
+            return { count: this.mod.HEAPU32[countPtr >> 2], bytes: this.mod.HEAPU32[bytesPtr >> 2] };
+        }
+        finally {
+            this.mod.ccall("goss_free", null, ["number", "number"], [countPtr, 4]);
+            this.mod.ccall("goss_free", null, ["number", "number"], [bytesPtr, 8]);
+        }
+    }
+    /// The whole memory as bytes, so a cold start is instant.
+    memorySave() {
+        const lenPtr = this.mod.ccall("goss_alloc", "number", ["number"], [8]);
+        try {
+            this.mod.ccall("goss_session_memory_save", "number", ["number", "number", "number", "number"], [this.handle, 0, 0, lenPtr]);
+            const needed = this.mod.HEAPU32[lenPtr >> 2];
+            if (needed === 0)
+                return new Uint8Array(0);
+            const ptr = this.mod.ccall("goss_alloc", "number", ["number"], [needed]);
+            try {
+                if (this.mod.ccall("goss_session_memory_save", "number", ["number", "number", "number", "number"], [this.handle, ptr, needed, lenPtr]) !== GOSS_OK)
+                    return new Uint8Array(0);
+                return new Uint8Array(this.mod.HEAPU8.subarray(ptr, ptr + needed));
+            }
+            finally {
+                this.mod.ccall("goss_free", null, ["number", "number"], [ptr, needed]);
+            }
+        }
+        finally {
+            this.mod.ccall("goss_free", null, ["number", "number"], [lenPtr, 8]);
+        }
+    }
+    /// The memory sealed under a host key. The nonce is yours: reusing one under
+    /// the same key breaks the cipher.
+    memorySaveSealed(key, nonce) {
+        const keyPtr = this.mod.ccall("goss_alloc", "number", ["number"], [key.length]);
+        const noncePtr = this.mod.ccall("goss_alloc", "number", ["number"], [nonce.length]);
+        const lenPtr = this.mod.ccall("goss_alloc", "number", ["number"], [8]);
+        try {
+            this.mod.HEAPU8.set(key, keyPtr);
+            this.mod.HEAPU8.set(nonce, noncePtr);
+            this.mod.ccall("goss_session_memory_save_sealed", "number", ["number", "number", "number", "number", "number", "number"], [this.handle, keyPtr, noncePtr, 0, 0, lenPtr]);
+            const needed = this.mod.HEAPU32[lenPtr >> 2];
+            if (needed === 0)
+                return new Uint8Array(0);
+            const ptr = this.mod.ccall("goss_alloc", "number", ["number"], [needed]);
+            try {
+                if (this.mod.ccall("goss_session_memory_save_sealed", "number", ["number", "number", "number", "number", "number", "number"], [this.handle, keyPtr, noncePtr, ptr, needed, lenPtr]) !== GOSS_OK)
+                    return new Uint8Array(0);
+                return new Uint8Array(this.mod.HEAPU8.subarray(ptr, ptr + needed));
+            }
+            finally {
+                this.mod.ccall("goss_free", null, ["number", "number"], [ptr, needed]);
+            }
+        }
+        finally {
+            this.mod.ccall("goss_free", null, ["number", "number"], [keyPtr, key.length]);
+            this.mod.ccall("goss_free", null, ["number", "number"], [noncePtr, nonce.length]);
+            this.mod.ccall("goss_free", null, ["number", "number"], [lenPtr, 8]);
+        }
+    }
+    memoryLoadSealed(key, bytes) {
+        const keyPtr = this.mod.ccall("goss_alloc", "number", ["number"], [key.length]);
+        const ptr = this.mod.ccall("goss_alloc", "number", ["number"], [bytes.length]);
+        try {
+            this.mod.HEAPU8.set(key, keyPtr);
+            this.mod.HEAPU8.set(bytes, ptr);
+            return this.mod.ccall("goss_session_memory_load_sealed", "number", ["number", "number", "number", "number"], [this.handle, keyPtr, ptr, bytes.length]) === GOSS_OK;
+        }
+        finally {
+            this.mod.ccall("goss_free", null, ["number", "number"], [keyPtr, key.length]);
+            this.mod.ccall("goss_free", null, ["number", "number"], [ptr, bytes.length]);
+        }
+    }
+    memoryLoad(bytes) {
+        const ptr = this.mod.ccall("goss_alloc", "number", ["number"], [bytes.length]);
+        try {
+            this.mod.HEAPU8.set(bytes, ptr);
+            return this.mod.ccall("goss_session_memory_load", "number", ["number", "number", "number"], [this.handle, ptr, bytes.length]) === GOSS_OK;
+        }
+        finally {
+            this.mod.ccall("goss_free", null, ["number", "number"], [ptr, bytes.length]);
+        }
+    }
+    /// Turns on the text rail. A detector alone finds where the text is, which
+    /// is what a redaction or a rectified crop needs; pass a recogniser and its
+    /// dictionary to get strings back.
+    enableText(detector, recognizer, dictionary, detectSide = 320) {
+        const rec = recognizer ?? new Uint8Array(0);
+        const dict = dictionary ?? new Uint8Array(0);
+        const detPtr = this.mod.ccall("goss_alloc", "number", ["number"], [detector.length]);
+        const recPtr = rec.length === 0 ? 0 : this.mod.ccall("goss_alloc", "number", ["number"], [rec.length]);
+        const dictPtr = dict.length === 0 ? 0 : this.mod.ccall("goss_alloc", "number", ["number"], [dict.length]);
+        try {
+            this.mod.HEAPU8.set(detector, detPtr);
+            if (recPtr !== 0)
+                this.mod.HEAPU8.set(rec, recPtr);
+            if (dictPtr !== 0)
+                this.mod.HEAPU8.set(dict, dictPtr);
+            return this.mod.ccall("goss_session_enable_text", "number", ["number", "number", "number", "number", "number", "number", "number", "number"], [this.handle, detPtr, detector.length, recPtr, rec.length, dictPtr, dict.length, detectSide]) === GOSS_OK;
+        }
+        finally {
+            this.mod.ccall("goss_free", null, ["number", "number"], [detPtr, detector.length]);
+            if (recPtr !== 0)
+                this.mod.ccall("goss_free", null, ["number", "number"], [recPtr, rec.length]);
+            if (dictPtr !== 0)
+                this.mod.ccall("goss_free", null, ["number", "number"], [dictPtr, dict.length]);
+        }
+    }
+    disableText() {
+        return this.mod.ccall("goss_session_disable_text", "number", ["number"], [this.handle]) === GOSS_OK;
+    }
+    /// How many readings the frame holds and how many the bound turned away.
+    textCount() {
+        const countPtr = this.mod.ccall("goss_alloc", "number", ["number"], [4]);
+        const refusedPtr = this.mod.ccall("goss_alloc", "number", ["number"], [8]);
+        try {
+            if (this.mod.ccall("goss_session_text_count", "number", ["number", "number", "number"], [this.handle, countPtr, refusedPtr]) !== GOSS_OK) {
+                return { live: 0, refused: 0 };
+            }
+            return { live: this.mod.HEAPU32[countPtr >> 2], refused: this.mod.HEAPU32[refusedPtr >> 2] };
+        }
+        finally {
+            this.mod.ccall("goss_free", null, ["number", "number"], [countPtr, 4]);
+            this.mod.ccall("goss_free", null, ["number", "number"], [refusedPtr, 8]);
+        }
+    }
+    /// Everything the frame says, each reading with its quadrilateral and string.
+    readings() {
+        const { live } = this.textCount();
+        const entryBytes = 64;
+        const entryPtr = this.mod.ccall("goss_alloc", "number", ["number"], [entryBytes]);
+        const lenPtr = this.mod.ccall("goss_alloc", "number", ["number"], [8]);
+        const out = [];
+        try {
+            for (let i = 0; i < live; i += 1) {
+                if (this.mod.ccall("goss_session_text_at", "number", ["number", "number", "number"], [this.handle, i, entryPtr]) !== GOSS_OK)
+                    continue;
+                const f32 = (off) => this.mod.HEAPF32[(entryPtr + off) >> 2];
+                const u32 = (off) => this.mod.HEAPU32[(entryPtr + off) >> 2];
+                this.mod.ccall("goss_session_text_string", "number", ["number", "number", "number", "number", "number"], [this.handle, i, 0, 0, lenPtr]);
+                const needed = this.mod.HEAPU32[lenPtr >> 2];
+                let text = "";
+                if (needed > 0) {
+                    const textPtr = this.mod.ccall("goss_alloc", "number", ["number"], [needed]);
+                    try {
+                        if (this.mod.ccall("goss_session_text_string", "number", ["number", "number", "number", "number", "number"], [this.handle, i, textPtr, needed, lenPtr]) === GOSS_OK) {
+                            text = new TextDecoder().decode(this.mod.HEAPU8.subarray(textPtr, textPtr + needed));
+                        }
+                    }
+                    finally {
+                        this.mod.ccall("goss_free", null, ["number", "number"], [textPtr, needed]);
+                    }
+                }
+                out.push({
+                    text,
+                    quad: [f32(0), f32(4), f32(8), f32(12), f32(16), f32(20), f32(24), f32(28)],
+                    confidence: f32(32),
+                    origin: u32(36),
+                    script: u32(40),
+                    direction: u32(44),
+                    trackId: u32(48),
+                    line: u32(52),
+                    paragraph: u32(56),
+                });
+            }
+            return out;
+        }
+        finally {
+            this.mod.ccall("goss_free", null, ["number", "number"], [entryPtr, entryBytes]);
+            this.mod.ccall("goss_free", null, ["number", "number"], [lenPtr, 8]);
+        }
+    }
+    /// Adds or updates one annotation. The same id replaces rather than
+    /// duplicating, so moving one box every frame leaks no entry per frame.
+    annotate(a, text = "") {
+        const bytes = 64;
+        const ptr = this.mod.ccall("goss_alloc", "number", ["number"], [bytes]);
+        const encoded = new TextEncoder().encode(text);
+        const textPtr = encoded.length === 0 ? 0 : this.mod.ccall("goss_alloc", "number", ["number"], [encoded.length]);
+        try {
+            const u32 = (off, v) => { this.mod.HEAPU32[(ptr + off) >> 2] = v; };
+            const f32 = (off, v) => { this.mod.HEAPF32[(ptr + off) >> 2] = v; };
+            u32(0, a.id);
+            u32(4, a.kind);
+            u32(8, a.space ?? 0);
+            for (let i = 0; i < 4; i += 1)
+                f32(12 + i * 4, a.rect?.[i] ?? 0);
+            u32(28, a.trackId ?? 0);
+            this.mod.HEAPU8[ptr + 32] = a.colour?.[0] ?? 255;
+            this.mod.HEAPU8[ptr + 33] = a.colour?.[1] ?? 255;
+            this.mod.HEAPU8[ptr + 34] = a.colour?.[2] ?? 255;
+            this.mod.HEAPU8[ptr + 35] = a.colour?.[3] ?? 255;
+            this.mod.HEAP32[(ptr + 36) >> 2] = a.z ?? 0;
+            f32(40, a.opacity ?? 1);
+            u32(44, a.lifetimeKind ?? 0);
+            u32(48, a.lifetimeValue ?? 0);
+            u32(52, 0);
+            u32(56, a.onLost ?? 0);
+            f32(60, a.value ?? 0);
+            if (textPtr !== 0)
+                this.mod.HEAPU8.set(encoded, textPtr);
+            return this.mod.ccall("goss_session_annotate", "number", ["number", "number", "number", "number"], [this.handle, ptr, textPtr, encoded.length]) === GOSS_OK;
+        }
+        finally {
+            this.mod.ccall("goss_free", null, ["number", "number"], [ptr, bytes]);
+            if (textPtr !== 0)
+                this.mod.ccall("goss_free", null, ["number", "number"], [textPtr, encoded.length]);
+        }
+    }
+    annotationRemove(id) {
+        return this.mod.ccall("goss_session_annotation_remove", "number", ["number", "number"], [this.handle, id]) === GOSS_OK;
+    }
+    annotationClear() {
+        return this.mod.ccall("goss_session_annotation_clear", "number", ["number"], [this.handle]) === GOSS_OK;
+    }
+    /// Live count and how many adds the bound turned away.
+    annotationCount() {
+        const countPtr = this.mod.ccall("goss_alloc", "number", ["number"], [4]);
+        const refusedPtr = this.mod.ccall("goss_alloc", "number", ["number"], [8]);
+        try {
+            if (this.mod.ccall("goss_session_annotation_count", "number", ["number", "number", "number"], [this.handle, countPtr, refusedPtr]) !== GOSS_OK) {
+                return { live: 0, refused: 0 };
+            }
+            return { live: this.mod.HEAPU32[countPtr >> 2], refused: this.mod.HEAPU32[refusedPtr >> 2] };
+        }
+        finally {
+            this.mod.ccall("goss_free", null, ["number", "number"], [countPtr, 4]);
+            this.mod.ccall("goss_free", null, ["number", "number"], [refusedPtr, 8]);
+        }
+    }
+    /// Installs the egress policy: what the brain sees and what it costs.
+    egressConfigure(config) {
+        const bytes = 48;
+        const ptr = this.mod.ccall("goss_alloc", "number", ["number"], [bytes]);
+        try {
+            const u32 = (off, v) => { this.mod.HEAPU32[(ptr + off) >> 2] = v; };
+            u32(0, config.targetLongEdge ?? 0);
+            u32(4, config.format ?? 0);
+            u32(8, config.quality ?? 80);
+            u32(12, config.maxFps ?? 0);
+            u32(16, config.maxBytesPerSecond ?? 0);
+            u32(20, 0);
+            u32(24, config.source ?? 0);
+            u32(28, config.trigger ?? 0b1010);
+            this.mod.HEAPF32[(ptr + 32) >> 2] = config.changeThreshold ?? 0.02;
+            u32(40, config.keyframeIntervalUs ?? 5_000_000);
+            u32(44, 0);
+            return this.mod.ccall("goss_session_egress_configure", "number", ["number", "number"], [this.handle, ptr]) === GOSS_OK;
+        }
+        finally {
+            this.mod.ccall("goss_free", null, ["number", "number"], [ptr, bytes]);
+        }
+    }
+    /// One frame, whatever the change score says.
+    egressRequest() {
+        return this.mod.ccall("goss_session_egress_request", "number", ["number"], [this.handle]) === GOSS_OK;
+    }
+    /// Whether this frame is worth sending and why. Null when there are no pixels
+    /// to score, which is not a failure.
+    egressDecide() {
+        const bytes = 40;
+        const ptr = this.mod.ccall("goss_alloc", "number", ["number"], [bytes]);
+        try {
+            if (this.mod.ccall("goss_session_egress_decide", "number", ["number", "number"], [this.handle, ptr]) !== GOSS_OK)
+                return null;
+            const w = (off) => this.mod.HEAPU32[(ptr + off) >> 2];
+            return {
+                send: w(0) !== 0,
+                reason: w(4),
+                changeScore: this.mod.HEAPF32[(ptr + 8) >> 2],
+                sinceLastUs: w(16),
+                sentTotal: w(24),
+                heldTotal: w(32),
+            };
+        }
+        finally {
+            this.mod.ccall("goss_free", null, ["number", "number"], [ptr, bytes]);
+        }
+    }
+    /// The session's events as an async iterable, which is how a page wants them:
+    /// `for await (const e of session.eventStream())`. Polls on an interval because
+    /// the ring is drained by the caller and there is nothing to await on the
+    /// engine side. A drop is yielded as an event of its own rather than swallowed.
+    async *eventStream(pollMs = 16, batch = 64) {
+        for (;;) {
+            const drained = this.pollEvents(batch);
+            for (const event of drained.events)
+                yield event;
+            if (drained.dropped > 0) {
+                yield { kind: 0, sequence: 0, timestampUs: 0, a: drained.dropped, b: 0, value: 0 };
+            }
+            await new Promise((resolve) => setTimeout(resolve, pollMs));
+        }
+    }
+    /// Drains the session's event ring in order. `dropped` says whether anything
+    /// was missed since the last drain, and is cleared by the read.
+    pollEvents(capacity = 64) {
+        // kind u32 at 0, sequence u64 at 8, timestamp i64 at 16, a u32 at 24,
+        // b u32 at 28, value f32 at 32; forty bytes with the tail padding.
+        const stride = 40;
+        const ptr = this.mod.ccall("goss_alloc", "number", ["number"], [capacity * stride]);
+        const countPtr = this.mod.ccall("goss_alloc", "number", ["number"], [4]);
+        const droppedPtr = this.mod.ccall("goss_alloc", "number", ["number"], [8]);
+        try {
+            if (this.mod.ccall("goss_session_poll_events", "number", ["number", "number", "number", "number", "number"], [this.handle, ptr, capacity, countPtr, droppedPtr]) !== GOSS_OK) {
+                return { events: [], dropped: 0 };
+            }
+            const n = this.mod.HEAPU32[countPtr >> 2];
+            const events = [];
+            for (let i = 0; i < n; i += 1) {
+                const base = ptr + i * stride;
+                events.push({
+                    kind: this.mod.HEAPU32[base >> 2],
+                    // The low word of the sequence is the whole count at any rate a session
+                    // reaches, and reading it avoids a BigInt in the hot drain.
+                    sequence: this.mod.HEAPU32[(base + 8) >> 2],
+                    timestampUs: this.mod.HEAPU32[(base + 16) >> 2],
+                    a: this.mod.HEAPU32[(base + 24) >> 2],
+                    b: this.mod.HEAPU32[(base + 28) >> 2],
+                    value: this.mod.HEAPF32[(base + 32) >> 2],
+                });
+            }
+            return { events, dropped: this.mod.HEAPU32[droppedPtr >> 2] };
+        }
+        finally {
+            this.mod.ccall("goss_free", null, ["number", "number"], [ptr, capacity * stride]);
+            this.mod.ccall("goss_free", null, ["number", "number"], [countPtr, 4]);
+            this.mod.ccall("goss_free", null, ["number", "number"], [droppedPtr, 8]);
+        }
+    }
+    /// A break the page saw and the engine cannot: the camera track ended, the
+    /// tab was hidden. Declared so the gap it leaves is the break rather than
+    /// drift counted against the engine.
+    reportInterruption(kind) {
+        return this.mod.ccall("goss_session_report_interruption", "number", ["number", "number"], [this.handle, kind]) === GOSS_OK;
+    }
+    /// This session's counters: frames in and out, the rung and how often it
+    /// moved, the analysis each modality ran, the nodes that are not ready.
+    sessionReport() {
+        const bytes = SESSION_REPORT_BYTES;
+        const ptr = this.mod.ccall("goss_alloc", "number", ["number"], [bytes]);
+        try {
+            if (this.mod.ccall("goss_session_read_report", "number", ["number", "number"], [this.handle, ptr]) !== 0)
+                return null;
+            // The low word of each u64 is the whole count at any rate this engine
+            // reaches, and reading it avoids a BigInt in the hot read.
+            const low = (offset) => this.mod.HEAPU32[(ptr + offset) >> 2];
+            return {
+                framesSubmitted: low(0),
+                framesRendered: low(8),
+                degradeLevel: low(16),
+                degradeTransitions: low(20),
+                faceAnalysis: low(24),
+                handAnalysis: low(32),
+                poseAnalysis: low(40),
+                segmentationAnalysis: low(48),
+                mlAnalysis: low(56),
+                nodesDegraded: low(64),
+                nodeReportsLost: low(68),
+                scriptFaults: low(72),
+                mlPlanGrowths: low(76),
+                mlPlanBytes: low(80),
+            };
+        }
+        finally {
+            this.mod.ccall("goss_free", null, ["number", "number"], [ptr, bytes]);
+        }
+    }
+    /// Every node of the active lens that is not doing what its manifest asked,
+    /// beside how many diagnostics could not be recorded at all. An empty list
+    /// with a non-zero lost count means the lens degraded in ways the session
+    /// could not write down, which is not the same as a lens that is fine.
+    nodeReports() {
+        const scratch = this.mod.ccall("goss_alloc", "number", ["number"], [8]);
+        let count = 0;
+        let lost = 0;
+        try {
+            const status = this.mod.ccall("goss_session_node_report_count", "number", ["number", "number", "number"], [this.handle, scratch, scratch + 4]);
+            if (status !== 0)
+                return { reports: [], lost: 0 };
+            count = this.mod.HEAPU32[scratch >> 2];
+            lost = this.mod.HEAPU32[(scratch + 4) >> 2];
+        }
+        finally {
+            this.mod.ccall("goss_free", null, ["number", "number"], [scratch, 8]);
+        }
+        const reports = [];
+        // One report is three u32; the id buffer is sized for a manifest node id.
+        const record = this.mod.ccall("goss_alloc", "number", ["number"], [12]);
+        const idBytes = 256;
+        const idPtr = this.mod.ccall("goss_alloc", "number", ["number"], [idBytes + 4]);
+        try {
+            for (let at = 0; at < count; at += 1) {
+                if (this.mod.ccall("goss_session_node_report_at", "number", ["number", "number", "number"], [this.handle, at, record]) !== 0)
+                    break;
+                const nodeIndex = this.mod.HEAPU32[record >> 2];
+                const state = this.mod.HEAPU32[(record + 4) >> 2];
+                const reason = this.mod.HEAPU32[(record + 8) >> 2];
+                let id = "";
+                const lenPtr = idPtr + idBytes;
+                if (this.mod.ccall("goss_session_node_report_id", "number", ["number", "number", "number", "number", "number"], [this.handle, at, idPtr, idBytes, lenPtr]) === 0) {
+                    const len = this.mod.HEAPU32[lenPtr >> 2];
+                    if (len > 0 && len <= idBytes) {
+                        id = new TextDecoder().decode(this.mod.HEAPU8.subarray(idPtr, idPtr + len));
+                    }
+                }
+                reports.push({ id, nodeIndex, state: state, reason: reason });
+            }
+        }
+        finally {
+            this.mod.ccall("goss_free", null, ["number", "number"], [record, 12]);
+            this.mod.ccall("goss_free", null, ["number", "number"], [idPtr, idBytes + 4]);
+        }
+        return { reports, lost };
+    }
     /// Submits a bare camera pose and projection, for a host driving a scan with
     /// no platform world session behind it: a selfie scan on the front camera,
     /// where the depth comes from a lens's own net rather than a sensor. Both
@@ -2437,7 +3492,10 @@ export class GossSession {
     /// Reports one finished frame: measured whole-pipeline time plus
     /// thermal pressure (nominal by default - no browser API surfaces
     /// device thermal state). Returns the degradation level in effect
-    /// for the next frame.
+    /// for the next frame. A page that never calls this still degrades:
+    /// the engine derives the frame period from the camera timestamps it
+    /// is handed. Calling it lets the page account for its own work
+    /// outside the engine as well.
     reportFrame(frameTimeUs, thermal = 0 /* GossThermal.Nominal */) {
         return this.mod.ccall("goss_session_report_frame", "number", ["number", "number", "number"], [this.handle, frameTimeUs, thermal]);
     }
@@ -2542,11 +3600,18 @@ export class GossPreviewSession {
     setBlush(amount) {
         this.session.setBlush(amount);
     }
+    /// Awaited, because activation suspends on the WebGPU build. A caller that
+    /// fires and forgets leaves the module unwound and the next render reenters
+    /// it.
     activateLens(manifestJson) {
-        this.session.activateLens(manifestJson);
+        return this.session.activateLens(manifestJson);
     }
     deactivateLens() {
-        this.session.deactivateLens();
+        return this.session.deactivateLens();
+    }
+    /// True while a lens change is unwound; a frame loop skips its render.
+    get isLensChangeInFlight() {
+        return this.session.isLensChangeInFlight;
     }
     tickLens(dtUs, signals = {}) {
         this.session.tickLens(dtUs, signals);
@@ -2668,4 +3733,5 @@ export { GossVideoTexture } from "./video-texture.js";
 // The trackers the tracking module runs, so a page reaches them through the one package entry
 // the way the Swift and Kotlin SDKs carry theirs.
 export { GossFaceTracker, GossHandTracker, GossPoseTracker, GossSegmenter, GOSS_FACE_BLENDSHAPE_COUNT, GOSS_MAX_HANDS } from "./tracking.js";
+export { shareScreen } from "./screen-capture.js";
 //# sourceMappingURL=index.js.map