@bldrs-ai/conway 1.389.1221 → 1.394.1504

package/compiled/src/core/model_registry.d.ts

@@ -0,0 +1,87 @@
+import { EntityAddress } from "./model_uri.js";
+import { SharedByteBudget } from "./shared_byte_budget.js";
+/**
+ * A model resolved from the registry, paired with the express ID an address
+ * selected within it.
+ */
+export interface ResolvedEntity<H> {
+    model: H;
+    expressID: number;
+}
+/**
+ * The set of open models in one browser session (M5 / design S3).
+ *
+ * Federation is a registry of loader instances keyed by **model URI**, all
+ * sharing one {@link SharedByteBudget} so total resident memory is bounded per
+ * browser rather than per model. An {@link EntityAddress} (`modelURI#expressID`)
+ * resolves through here to the live model handle; a URI with no registered
+ * model is the signal to open a sibling loader (its own sidecar/stream) and
+ * register it.
+ *
+ * The registry is deliberately generic over the model handle `H` — it owns
+ * identity, resolution and the shared budget, not the loader. The streaming
+ * loader registers its model instance; higher layers (the composed skeleton,
+ * the UI link layer) query through the same addresses.
+ */
+export declare class ModelRegistry<H> {
+    private readonly byURI_;
+    private readonly budget_;
+    /**
+     * @param budget The shared per-browser byte budget every registered model
+     * draws from.
+     */
+    constructor(budget: SharedByteBudget);
+    /**
+     * @return {SharedByteBudget} The shared budget all registered models draw
+     * from.
+     */
+    get budget(): SharedByteBudget;
+    /**
+     * @return {number} The number of registered models.
+     */
+    get size(): number;
+    /**
+     * @return {IterableIterator<string>} The URIs of all registered models.
+     */
+    uris(): IterableIterator<string>;
+    /**
+     * @return {IterableIterator<H>} The registered model handles.
+     */
+    models(): IterableIterator<H>;
+    /**
+     * Register (or replace) the model for a URI.
+     *
+     * @param uri The model URI (no `#` fragment).
+     * @param model The model handle.
+     */
+    register(uri: string, model: H): void;
+    /**
+     * Remove a model from the registry.
+     *
+     * @param uri The model URI.
+     * @return {boolean} True if a model was removed.
+     */
+    unregister(uri: string): boolean;
+    /**
+     * @param uri The model URI.
+     * @return {boolean} True if a model is registered for the URI.
+     */
+    has(uri: string): boolean;
+    /**
+     * @param uri The model URI.
+     * @return {H | undefined} The registered model, or undefined.
+     */
+    get(uri: string): H | undefined;
+    /**
+     * Resolve an entity address to its model + express ID. Returns undefined
+     * when the address's model isn't registered — the caller's cue to open and
+     * register it, then resolve again.
+     *
+     * @param address The entity address, as a URI string or a parsed
+     * {@link EntityAddress}.
+     * @return {ResolvedEntity | undefined} The resolved model + express ID, or
+     * undefined if the model isn't registered.
+     */
+    resolve(address: string | EntityAddress): ResolvedEntity<H> | undefined;
+}
+//# sourceMappingURL=model_registry.d.ts.map

package/compiled/src/core/model_registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"model_registry.d.ts","sourceRoot":"","sources":["../../../src/core/model_registry.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAsB,MAAM,aAAa,CAAA;AAC/D,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAA;AAGvD;;;GAGG;AACH,MAAM,WAAW,cAAc,CAAC,CAAC;IAC/B,KAAK,EAAE,CAAC,CAAA;IACR,SAAS,EAAE,MAAM,CAAA;CAClB;AAGD;;;;;;;;;;;;;;GAcG;AACH,qBAAa,aAAa,CAAC,CAAC;IAE1B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAuB;IAE9C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAkB;IAE1C;;;OAGG;gBACU,MAAM,EAAE,gBAAgB;IAIrC;;;OAGG;IACH,IAAW,MAAM,IAAI,gBAAgB,CAEpC;IAED;;OAEG;IACH,IAAW,IAAI,IAAI,MAAM,CAExB;IAED;;OAEG;IACI,IAAI,IAAI,gBAAgB,CAAC,MAAM,CAAC;IAIvC;;OAEG;IACI,MAAM,IAAI,gBAAgB,CAAC,CAAC,CAAC;IAIpC;;;;;OAKG;IACI,QAAQ,CAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,GAAI,IAAI;IAS9C;;;;;OAKG;IACI,UAAU,CAAE,GAAG,EAAE,MAAM,GAAI,OAAO;IAIzC;;;OAGG;IACI,GAAG,CAAE,GAAG,EAAE,MAAM,GAAI,OAAO;IAIlC;;;OAGG;IACI,GAAG,CAAE,GAAG,EAAE,MAAM,GAAI,CAAC,GAAG,SAAS;IAIxC;;;;;;;;;OASG;IACI,OAAO,CAAE,OAAO,EAAE,MAAM,GAAG,aAAa,GAAI,cAAc,CAAC,CAAC,CAAC,GAAG,SAAS;CASjF"}

package/compiled/src/core/model_registry.js

@@ -0,0 +1,101 @@
+import { parseEntityAddress } from "./model_uri.js";
+/**
+ * The set of open models in one browser session (M5 / design S3).
+ *
+ * Federation is a registry of loader instances keyed by **model URI**, all
+ * sharing one {@link SharedByteBudget} so total resident memory is bounded per
+ * browser rather than per model. An {@link EntityAddress} (`modelURI#expressID`)
+ * resolves through here to the live model handle; a URI with no registered
+ * model is the signal to open a sibling loader (its own sidecar/stream) and
+ * register it.
+ *
+ * The registry is deliberately generic over the model handle `H` — it owns
+ * identity, resolution and the shared budget, not the loader. The streaming
+ * loader registers its model instance; higher layers (the composed skeleton,
+ * the UI link layer) query through the same addresses.
+ */
+export class ModelRegistry {
+    /**
+     * @param budget The shared per-browser byte budget every registered model
+     * draws from.
+     */
+    constructor(budget) {
+        this.byURI_ = new Map();
+        this.budget_ = budget;
+    }
+    /**
+     * @return {SharedByteBudget} The shared budget all registered models draw
+     * from.
+     */
+    get budget() {
+        return this.budget_;
+    }
+    /**
+     * @return {number} The number of registered models.
+     */
+    get size() {
+        return this.byURI_.size;
+    }
+    /**
+     * @return {IterableIterator<string>} The URIs of all registered models.
+     */
+    uris() {
+        return this.byURI_.keys();
+    }
+    /**
+     * @return {IterableIterator<H>} The registered model handles.
+     */
+    models() {
+        return this.byURI_.values();
+    }
+    /**
+     * Register (or replace) the model for a URI.
+     *
+     * @param uri The model URI (no `#` fragment).
+     * @param model The model handle.
+     */
+    register(uri, model) {
+        if (uri.includes("#")) {
+            throw new Error(`Model URI must not contain '#': ${uri}`);
+        }
+        this.byURI_.set(uri, model);
+    }
+    /**
+     * Remove a model from the registry.
+     *
+     * @param uri The model URI.
+     * @return {boolean} True if a model was removed.
+     */
+    unregister(uri) {
+        return this.byURI_.delete(uri);
+    }
+    /**
+     * @param uri The model URI.
+     * @return {boolean} True if a model is registered for the URI.
+     */
+    has(uri) {
+        return this.byURI_.has(uri);
+    }
+    /**
+     * @param uri The model URI.
+     * @return {H | undefined} The registered model, or undefined.
+     */
+    get(uri) {
+        return this.byURI_.get(uri);
+    }
+    /**
+     * Resolve an entity address to its model + express ID. Returns undefined
+     * when the address's model isn't registered — the caller's cue to open and
+     * register it, then resolve again.
+     *
+     * @param address The entity address, as a URI string or a parsed
+     * {@link EntityAddress}.
+     * @return {ResolvedEntity | undefined} The resolved model + express ID, or
+     * undefined if the model isn't registered.
+     */
+    resolve(address) {
+        const { modelURI, expressID } = typeof address === "string" ? parseEntityAddress(address) : address;
+        const model = this.byURI_.get(modelURI);
+        return model === void 0 ? void 0 : { model, expressID };
+    }
+}

package/compiled/src/core/model_registry.test.d.ts

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

package/compiled/src/core/model_registry.test.d.ts.map

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

package/compiled/src/core/model_registry.test.js

@@ -0,0 +1,60 @@
+/* eslint-disable no-magic-numbers */
+// M5: the registry keys open models by URI, resolves universal addresses to
+// the live model, and hands every model the one shared budget.
+import { describe, expect, test } from "@jest/globals";
+import { ModelRegistry } from "./model_registry.js";
+import { SharedByteBudget } from "./shared_byte_budget.js";
+describe("ModelRegistry", () => {
+    /**
+     * A registry with two registered fake models.
+     *
+     * @return {ModelRegistry} The populated registry.
+     */
+    function twoModels() {
+        const registry = new ModelRegistry(new SharedByteBudget(1000));
+        registry.register("https://ex.com/a.ifc", { uri: "a" });
+        registry.register("https://ex.com/b.ifc", { uri: "b" });
+        return registry;
+    }
+    test("registers, looks up and counts models", () => {
+        const registry = twoModels();
+        expect(registry.size).toBe(2);
+        expect(registry.has("https://ex.com/a.ifc")).toBe(true);
+        expect(registry.get("https://ex.com/b.ifc")?.uri).toBe("b");
+        expect([...registry.uris()].sort()).toEqual(["https://ex.com/a.ifc", "https://ex.com/b.ifc"]);
+    });
+    test("resolves an address string to the model and express ID", () => {
+        const registry = twoModels();
+        const resolved = registry.resolve("https://ex.com/b.ifc#42");
+        expect(resolved?.model.uri).toBe("b");
+        expect(resolved?.expressID).toBe(42);
+    });
+    test("resolves a pre-parsed address object too", () => {
+        const registry = twoModels();
+        const resolved = registry.resolve({ modelURI: "https://ex.com/a.ifc", expressID: 7 });
+        expect(resolved?.model.uri).toBe("a");
+        expect(resolved?.expressID).toBe(7);
+    });
+    test("returns undefined for an unregistered model (open-then-retry cue)", () => {
+        const registry = twoModels();
+        expect(registry.resolve("https://ex.com/missing.ifc#1"))
+            .toBeUndefined();
+    });
+    test("unregister removes a model", () => {
+        const registry = twoModels();
+        expect(registry.unregister("https://ex.com/a.ifc")).toBe(true);
+        expect(registry.has("https://ex.com/a.ifc")).toBe(false);
+        expect(registry.size).toBe(1);
+    });
+    test("rejects registering a URI with a fragment", () => {
+        const registry = new ModelRegistry(new SharedByteBudget(10));
+        expect(() => registry.register("a.ifc#1", { uri: "a" })).toThrow(/#/);
+    });
+    test("exposes the one shared budget every model draws from", () => {
+        const budget = new SharedByteBudget(1000);
+        const registry = new ModelRegistry(budget);
+        expect(registry.budget).toBe(budget);
+        registry.budget.reserve(400);
+        expect(registry.budget.available).toBe(600);
+    });
+});

package/compiled/src/core/model_uri.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Cross-model entity addressing (M5 / design S3).
+ *
+ * Federation turns "thousands of cross-referenced files" from a loader problem
+ * into an addressing problem: every entity has a **universal address** of a
+ * model URI plus an express ID — `https://…/part-B.ifc#4022`. The engine never
+ * holds all the files; it holds a registry of models keyed by URI (see
+ * {@link ModelRegistry}) and resolves an address to a (model, expressID) pair
+ * on demand, opening a sibling loader for a URI it hasn't seen.
+ *
+ * The URI is opaque to the engine except for its `#expressID` fragment: the
+ * scheme, host, path and any version identity live entirely in the model URI,
+ * so "many versions side by side" is expressible without an engine change.
+ */
+/**
+ * A universal entity address: which model, and which express ID within it.
+ */
+export interface EntityAddress {
+    /** The model's URI (everything left of the `#expressID` fragment). */
+    modelURI: string;
+    /** The entity's express ID within that model. */
+    expressID: number;
+}
+/**
+ * Format a model URI + express ID as a single entity address URI.
+ *
+ * @param modelURI The model URI (must not itself contain a `#`).
+ * @param expressID The express ID (a non-negative integer).
+ * @return {string} The `modelURI#expressID` address.
+ */
+export declare function formatEntityAddress(modelURI: string, expressID: number): string;
+/**
+ * Parse an entity address URI into its model URI and express ID.
+ *
+ * The split is on the **last** `#`, so a fragment is required; the model URI
+ * is everything before it. A missing or non-integer fragment is an error —
+ * an address without an express ID isn't an entity address.
+ *
+ * @param uri The `modelURI#expressID` address.
+ * @return {EntityAddress} The parsed address.
+ */
+export declare function parseEntityAddress(uri: string): EntityAddress;
+/**
+ * Resolve a (possibly relative) reference URI against a base model URI, so an
+ * `IfcExternalReference.Location` like `../shared/grid.ifc` becomes an absolute
+ * model URI addressable in the registry. Absolute references (with a scheme,
+ * or protocol-relative) pass through unchanged.
+ *
+ * Uses the standard URL resolver when the base is absolute; falls back to a
+ * plain path join when the base has no scheme (e.g. a bare filename in tests).
+ *
+ * @param base The base model URI the reference was found in.
+ * @param reference The reference URI (absolute or relative).
+ * @return {string} The resolved absolute reference URI.
+ */
+export declare function resolveReference(base: string, reference: string): string;
+//# sourceMappingURL=model_uri.d.ts.map

package/compiled/src/core/model_uri.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"model_uri.d.ts","sourceRoot":"","sources":["../../../src/core/model_uri.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH;;GAEG;AACH,MAAM,WAAW,aAAa;IAE5B,sEAAsE;IACtE,QAAQ,EAAE,MAAM,CAAA;IAEhB,iDAAiD;IACjD,SAAS,EAAE,MAAM,CAAA;CAClB;AAOD;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAI,MAAM,CAWjF;AAGD;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAE,GAAG,EAAE,MAAM,GAAI,aAAa,CAgB/D;AAGD;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAI,MAAM,CAgB1E"}

package/compiled/src/core/model_uri.js

@@ -0,0 +1,101 @@
+/**
+ * Cross-model entity addressing (M5 / design S3).
+ *
+ * Federation turns "thousands of cross-referenced files" from a loader problem
+ * into an addressing problem: every entity has a **universal address** of a
+ * model URI plus an express ID — `https://…/part-B.ifc#4022`. The engine never
+ * holds all the files; it holds a registry of models keyed by URI (see
+ * {@link ModelRegistry}) and resolves an address to a (model, expressID) pair
+ * on demand, opening a sibling loader for a URI it hasn't seen.
+ *
+ * The URI is opaque to the engine except for its `#expressID` fragment: the
+ * scheme, host, path and any version identity live entirely in the model URI,
+ * so "many versions side by side" is expressible without an engine change.
+ */
+const FRAGMENT = '#';
+const RADIX = 10;
+/**
+ * Format a model URI + express ID as a single entity address URI.
+ *
+ * @param modelURI The model URI (must not itself contain a `#`).
+ * @param expressID The express ID (a non-negative integer).
+ * @return {string} The `modelURI#expressID` address.
+ */
+export function formatEntityAddress(modelURI, expressID) {
+    if (modelURI.includes(FRAGMENT)) {
+        throw new Error(`Model URI must not contain '#': ${modelURI}`);
+    }
+    if (!Number.isInteger(expressID) || expressID < 0) {
+        throw new Error(`Invalid express ID ${expressID}`);
+    }
+    return `${modelURI}${FRAGMENT}${expressID}`;
+}
+/**
+ * Parse an entity address URI into its model URI and express ID.
+ *
+ * The split is on the **last** `#`, so a fragment is required; the model URI
+ * is everything before it. A missing or non-integer fragment is an error —
+ * an address without an express ID isn't an entity address.
+ *
+ * @param uri The `modelURI#expressID` address.
+ * @return {EntityAddress} The parsed address.
+ */
+export function parseEntityAddress(uri) {
+    const hash = uri.lastIndexOf(FRAGMENT);
+    if (hash < 0) {
+        throw new Error(`Entity address has no '#expressID' fragment: ${uri}`);
+    }
+    const modelURI = uri.slice(0, hash);
+    const fragment = uri.slice(hash + 1);
+    if (fragment.length === 0 || !/^\d+$/.test(fragment)) {
+        throw new Error(`Entity address fragment is not an express ID: ${uri}`);
+    }
+    return { modelURI, expressID: parseInt(fragment, RADIX) };
+}
+/**
+ * Resolve a (possibly relative) reference URI against a base model URI, so an
+ * `IfcExternalReference.Location` like `../shared/grid.ifc` becomes an absolute
+ * model URI addressable in the registry. Absolute references (with a scheme,
+ * or protocol-relative) pass through unchanged.
+ *
+ * Uses the standard URL resolver when the base is absolute; falls back to a
+ * plain path join when the base has no scheme (e.g. a bare filename in tests).
+ *
+ * @param base The base model URI the reference was found in.
+ * @param reference The reference URI (absolute or relative).
+ * @return {string} The resolved absolute reference URI.
+ */
+export function resolveReference(base, reference) {
+    // Already absolute (has a scheme like `https:` or is protocol-relative).
+    if (/^[a-z][a-z0-9+.-]*:/i.test(reference) || reference.startsWith('//')) {
+        return reference;
+    }
+    try {
+        return new URL(reference, base).toString();
+    }
+    catch {
+        // Base isn't a valid absolute URL (bare filename): join paths manually.
+        const slash = base.lastIndexOf('/');
+        const dir = slash < 0 ? '' : base.slice(0, slash + 1);
+        return normalizePath(dir + reference);
+    }
+}
+/**
+ * Collapse `.` / `..` segments in a slash-joined path (used only for the
+ * scheme-less fallback in {@link resolveReference}).
+ *
+ * @param path The path to normalise.
+ * @return {string} The normalised path.
+ */
+function normalizePath(path) {
+    const out = [];
+    for (const segment of path.split('/')) {
+        if (segment === '..') {
+            out.pop();
+        }
+        else if (segment !== '.') {
+            out.push(segment);
+        }
+    }
+    return out.join('/');
+}

package/compiled/src/core/model_uri.test.d.ts

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

package/compiled/src/core/model_uri.test.d.ts.map

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

package/compiled/src/core/model_uri.test.js

@@ -0,0 +1,49 @@
+/* eslint-disable no-magic-numbers */
+// M5: universal entity addressing — a model URI plus an express-ID fragment —
+// must round-trip and resolve relative references the way IFC external-ref
+// locations demand.
+import { describe, expect, test } from "@jest/globals";
+import { formatEntityAddress, parseEntityAddress, resolveReference, } from "./model_uri.js";
+describe("model URI addressing", () => {
+    test("formats and parses an entity address round-trip", () => {
+        const uri = formatEntityAddress("https://ex.com/part-B.ifc", 4022);
+        expect(uri).toBe("https://ex.com/part-B.ifc#4022");
+        const parsed = parseEntityAddress(uri);
+        expect(parsed.modelURI).toBe("https://ex.com/part-B.ifc");
+        expect(parsed.expressID).toBe(4022);
+    });
+    test("splits on the last # so the model URI keeps earlier structure", () => {
+        // (Model URIs shouldn't carry a '#', but parsing must be unambiguous.)
+        const parsed = parseEntityAddress("scheme://h/a#b#42");
+        expect(parsed.modelURI).toBe("scheme://h/a#b");
+        expect(parsed.expressID).toBe(42);
+    });
+    test("rejects formatting a model URI that contains #", () => {
+        expect(() => formatEntityAddress("a#b", 1)).toThrow(/#/);
+    });
+    test("rejects formatting a non-integer or negative express ID", () => {
+        expect(() => formatEntityAddress("a", 1.5)).toThrow();
+        expect(() => formatEntityAddress("a", -1)).toThrow();
+    });
+    test("rejects an address with no fragment or a non-numeric fragment", () => {
+        expect(() => parseEntityAddress("a.ifc")).toThrow(/fragment/);
+        expect(() => parseEntityAddress("a.ifc#")).toThrow(/express ID/);
+        expect(() => parseEntityAddress("a.ifc#x")).toThrow(/express ID/);
+    });
+    test("resolves a relative reference against an absolute base URI", () => {
+        expect(resolveReference("https://ex.com/site/plan.ifc", "../shared/grid.ifc"))
+            .toBe("https://ex.com/shared/grid.ifc");
+        expect(resolveReference("https://ex.com/site/plan.ifc", "wing-A.ifc"))
+            .toBe("https://ex.com/site/wing-A.ifc");
+    });
+    test("passes an already-absolute reference through unchanged", () => {
+        expect(resolveReference("https://ex.com/a.ifc", "https://other.org/b.ifc"))
+            .toBe("https://other.org/b.ifc");
+    });
+    test("resolves relative references against a scheme-less base", () => {
+        expect(resolveReference("project/plan.ifc", "wing-A.ifc"))
+            .toBe("project/wing-A.ifc");
+        expect(resolveReference("project/site/plan.ifc", "../grid.ifc"))
+            .toBe("project/grid.ifc");
+    });
+});

package/compiled/src/core/progress.d.ts

@@ -27,6 +27,8 @@ export interface ProgressEvent {
     readonly elapsedMs: number;
     /** Coarse used-JS-heap sample in MB, when the environment exposes one. */
     readonly memoryMb?: number;
+    /** Windowed source bytes currently resident, in MB (Geometry phase). */
+    readonly residentSourceMb?: number;
 }
 export type ProgressCallback = (event: ProgressEvent) => void;
 /**
@@ -42,7 +44,14 @@ export declare const DEFAULT_PROGRESS_INTERVAL_MS = 100;
  * repaint progress UI and timers (e.g. stall watchdogs) can fire. Used by the
  * *Async load variants between progress ticks.
  *
- * @return {Promise<void>} A promise resolved on the next timer turn.
+ * Not timer-based where avoidable: background tabs clamp setTimeout to >=1s,
+ * which would collapse a cooperative parse to a ~5% duty cycle the moment
+ * the tab loses focus. scheduler.yield() (and the MessageChannel fallback)
+ * post ordinary tasks, which are not clamped — loads keep their CPU in
+ * backgrounded tabs. setTimeout remains as the last-resort fallback for
+ * environments without either (where throttling doesn't apply anyway).
+ *
+ * @return {Promise<void>} A promise resolved on the next event-loop task.
  */
 export declare function yieldToEventLoop(): Promise<void>;
 /**
@@ -61,6 +70,7 @@ export declare class ProgressTracker {
     private phase_;
     private unit_;
     private total_;
+    private extras_;
     /**
      * Construct this with the callback progress events are forwarded to.
      *
@@ -93,8 +103,11 @@ export declare class ProgressTracker {
      * Report progress within the current phase; throttled.
      *
      * @param completed Units completed so far.
+     * @param extras Optional extras (window residency) merged into the event.
      */
-    update(completed: number): void;
+    update(completed: number, extras?: {
+        residentSourceMb?: number;
+    }): void;
     /**
      * End the current phase, emitting an unthrottled final event with
      * completed === total when a total is known.
@@ -107,6 +120,7 @@ export declare class ProgressTracker {
      *
      * @param completed Units completed so far.
      * @param now Current time in ms (defaults to Date.now()).
+     * @param extras Optional extras merged into the event.
      */
     private emit;
 }

package/compiled/src/core/progress.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"progress.d.ts","sourceRoot":"","sources":["../../../src/core/progress.ts"],"names":[],"mappings":"AAGA;;;;;;;;;GASG;AACH,MAAM,MAAM,aAAa,GACvB,aAAa,GAAG,WAAW,GAAG,UAAU,GAAG,YAAY,GAAG,WAAW,CAAA;AAEvE,MAAM,MAAM,YAAY,GAAG,OAAO,GAAG,UAAU,GAAG,UAAU,GAAG,QAAQ,GAAG,QAAQ,CAAA;AAElF;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAA;IAC7B,yEAAyE;IACzE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,kEAAkE;IAClE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAA;IAC3B,8DAA8D;IAC9D,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,0EAA0E;IAC1E,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAC3B;AAED,MAAM,MAAM,gBAAgB,GAAG,CAAE,KAAK,EAAE,aAAa,KAAM,IAAI,CAAA;AAE/D;;;;GAIG;AACH,MAAM,MAAM,qBAAqB,GAAG,CAAE,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAM,IAAI,CAAA;AAEhF,oEAAoE;AACpE,eAAO,MAAM,4BAA4B,MAAM,CAAA;AAE/C;;;;;;GAMG;AACH,wBAAgB,gBAAgB,IAAI,OAAO,CAAC,IAAI,CAAC,CAIhD;AAED;;;;;;;GAOG;AACH,qBAAa,eAAe;IAexB,OAAO,CAAC,QAAQ,CAAC,UAAU;IAC3B,OAAO,CAAC,QAAQ,CAAC,aAAa;IAdhC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAqB;IAC/C,OAAO,CAAC,YAAY,CAAY;IAChC,OAAO,CAAC,MAAM,CAA2B;IACzC,OAAO,CAAC,KAAK,CAA2B;IACxC,OAAO,CAAC,MAAM,CAAoB;IAElC;;;;;OAKG;gBAEgB,UAAU,EAAE,gBAAgB,EAC5B,aAAa,GAAE,MAAqC;IAEvE;;;;OAIG;IACH,IAAW,KAAK,IAAI,aAAa,GAAG,SAAS,CAE5C;IAED;;;;;;OAMG;IACI,UAAU,CAAE,KAAK,EAAE,aAAa,EAAE,IAAI,EAAE,YAAY,EAAE,KAAK,CAAC,EAAE,MAAM,GAAI,IAAI;IAQnF;;;;;OAKG;IACI,aAAa,CAAE,KAAK,EAAE,MAAM,GAAI,IAAI;IAI3C;;;;OAIG;IACI,MAAM,CAAE,SAAS,EAAE,MAAM,GAAI,IAAI;IAUxC;;;;;OAKG;IACI,QAAQ,CAAE,SAAS,CAAC,EAAE,MAAM,GAAI,IAAI;IAK3C;;;;;OAKG;IACH,OAAO,CAAC,IAAI;CAkBb"}
+{"version":3,"file":"progress.d.ts","sourceRoot":"","sources":["../../../src/core/progress.ts"],"names":[],"mappings":"AAGA;;;;;;;;;GASG;AACH,MAAM,MAAM,aAAa,GACvB,aAAa,GAAG,WAAW,GAAG,UAAU,GAAG,YAAY,GAAG,WAAW,CAAA;AAEvE,MAAM,MAAM,YAAY,GAAG,OAAO,GAAG,UAAU,GAAG,UAAU,GAAG,QAAQ,GAAG,QAAQ,CAAA;AAElF;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAA;IAC7B,yEAAyE;IACzE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,kEAAkE;IAClE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAA;IAC3B,8DAA8D;IAC9D,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,0EAA0E;IAC1E,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;IAC1B,wEAAwE;IACxE,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAA;CACnC;AAED,MAAM,MAAM,gBAAgB,GAAG,CAAE,KAAK,EAAE,aAAa,KAAM,IAAI,CAAA;AAE/D;;;;GAIG;AACH,MAAM,MAAM,qBAAqB,GAAG,CAAE,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAM,IAAI,CAAA;AAEhF,oEAAoE;AACpE,eAAO,MAAM,4BAA4B,MAAM,CAAA;AAE/C;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gBAAgB,IAAI,OAAO,CAAC,IAAI,CAAC,CAuBhD;AAED;;;;;;;GAOG;AACH,qBAAa,eAAe;IAgBxB,OAAO,CAAC,QAAQ,CAAC,UAAU;IAC3B,OAAO,CAAC,QAAQ,CAAC,aAAa;IAfhC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAqB;IAC/C,OAAO,CAAC,YAAY,CAAY;IAChC,OAAO,CAAC,MAAM,CAA2B;IACzC,OAAO,CAAC,KAAK,CAA2B;IACxC,OAAO,CAAC,MAAM,CAAoB;IAClC,OAAO,CAAC,OAAO,CAA2C;IAE1D;;;;;OAKG;gBAEgB,UAAU,EAAE,gBAAgB,EAC5B,aAAa,GAAE,MAAqC;IAEvE;;;;OAIG;IACH,IAAW,KAAK,IAAI,aAAa,GAAG,SAAS,CAE5C;IAED;;;;;;OAMG;IACI,UAAU,CAAE,KAAK,EAAE,aAAa,EAAE,IAAI,EAAE,YAAY,EAAE,KAAK,CAAC,EAAE,MAAM,GAAI,IAAI;IAQnF;;;;;OAKG;IACI,aAAa,CAAE,KAAK,EAAE,MAAM,GAAI,IAAI;IAI3C;;;;;OAKG;IACI,MAAM,CACT,SAAS,EAAE,MAAM,EACjB,MAAM,CAAC,EAAE;QAAE,gBAAgB,CAAC,EAAE,MAAM,CAAA;KAAE,GAAI,IAAI;IAWlD;;;;;OAKG;IACI,QAAQ,CAAE,SAAS,CAAC,EAAE,MAAM,GAAI,IAAI;IAM3C;;;;;;OAMG;IACH,OAAO,CAAC,IAAI;CAsBb"}

package/compiled/src/core/progress.js

@@ -6,9 +6,30 @@ export const DEFAULT_PROGRESS_INTERVAL_MS = 100;
  * repaint progress UI and timers (e.g. stall watchdogs) can fire. Used by the
  * *Async load variants between progress ticks.
  *
- * @return {Promise<void>} A promise resolved on the next timer turn.
+ * Not timer-based where avoidable: background tabs clamp setTimeout to >=1s,
+ * which would collapse a cooperative parse to a ~5% duty cycle the moment
+ * the tab loses focus. scheduler.yield() (and the MessageChannel fallback)
+ * post ordinary tasks, which are not clamped — loads keep their CPU in
+ * backgrounded tabs. setTimeout remains as the last-resort fallback for
+ * environments without either (where throttling doesn't apply anyway).
+ *
+ * @return {Promise<void>} A promise resolved on the next event-loop task.
  */
 export function yieldToEventLoop() {
+    const scheduler = globalThis.scheduler;
+    if (typeof scheduler?.yield === "function") {
+        return scheduler.yield();
+    }
+    if (typeof MessageChannel === "function") {
+        return new Promise((resolve) => {
+            const channel = new MessageChannel();
+            channel.port1.onmessage = () => {
+                channel.port1.close();
+                resolve();
+            };
+            channel.port2.postMessage(null);
+        });
+    }
     return new Promise((resolve) => {
         setTimeout(resolve, 0);
     });
@@ -69,13 +90,15 @@ export class ProgressTracker {
      * Report progress within the current phase; throttled.
      *
      * @param completed Units completed so far.
+     * @param extras Optional extras (window residency) merged into the event.
      */
-    update(completed) {
+    update(completed, extras) {
+        this.extras_ = extras;
         const now = Date.now();
         if (now - this.lastEmitTime < this.minIntervalMs) {
             return;
         }
-        this.emit(completed, now);
+        this.emit(completed, now, extras);
     }
     /**
      * End the current phase, emitting an unthrottled final event with
@@ -84,16 +107,18 @@ export class ProgressTracker {
      * @param completed Final completed units (defaults to the phase total).
      */
     endPhase(completed) {
-        this.emit(completed ?? this.total_ ?? 0);
+        this.emit(completed ?? this.total_ ?? 0, Date.now(), this.extras_);
         this.phase_ = void 0;
+        this.extras_ = void 0;
     }
     /**
      * Materialize and forward an event now, bypassing the throttle.
      *
      * @param completed Units completed so far.
      * @param now Current time in ms (defaults to Date.now()).
+     * @param extras Optional extras merged into the event.
      */
-    emit(completed, now = Date.now()) {
+    emit(completed, now = Date.now(), extras) {
         if (this.phase_ === void 0) {
             return;
         }
@@ -106,6 +131,7 @@ export class ProgressTracker {
             unit: this.unit_,
             elapsedMs: now - this.startTime,
             memoryMb: Memory.usedHeapMb(),
+            residentSourceMb: extras?.residentSourceMb,
         });
     }
 }

package/compiled/src/core/progress.test.js

@@ -54,12 +54,21 @@ describe("ProgressTracker", () => {
     });
 });
 describe("yieldToEventLoop", () => {
-    test("lets queued macrotasks run", async () => {
+    test("does not starve queued timers", async () => {
+        // The yield posts an ordinary task (scheduler.yield / MessageChannel —
+        // deliberately NOT a timer, so background tabs' >=1s setTimeout clamp
+        // cannot collapse a cooperative parse). Message tasks can be serviced
+        // ahead of the timer queue, so a due timer is not guaranteed to run
+        // within ONE yield — the contract is that repeated yielding lets due
+        // timers fire promptly (stall watchdogs stay live during a parse).
         let timerRan = false;
         setTimeout(() => {
             timerRan = true;
         }, 0);
-        await yieldToEventLoop();
+        const MAX_YIELDS = 50;
+        for (let where = 0; where < MAX_YIELDS && !timerRan; ++where) {
+            await yieldToEventLoop();
+        }
         expect(timerRan).toBe(true);
     });
 });

package/compiled/src/core/progress_log.d.ts

@@ -38,6 +38,7 @@ export interface ProgressEventLike {
     total?: number;
     elapsedMs: number;
     memoryMb?: number;
+    residentSourceMb?: number;
 }
 /**
  * Display label for a phase, merging headerParse+dataParse into 'Parsing'.