@ifc-lite/renderer 2.0.1 → 2.2.0

package/README.md

@@ -108,3 +108,13 @@ See the [Rendering Guide](https://ifclite.dev/docs/guide/rendering/) and [API Re
 ## License
 
 [MPL-2.0](../../LICENSE)
+
+Registered raster references are available through `renderer.getReferenceImages()`; see the [rendering guide](../../docs/guide/rendering.md#registered-raster-references) for identity, coordinates, resource ownership and picking.
+
+### Exact surface tools and clipping
+
+`renderer.hasActiveClipping()` reports whether the last rendered frame applied
+section, terrain or box clipping. It reads the retained render snapshot, so
+mutating a previous options object does not change the answer.
+`raycastScene()` does not clip triangle hits; tools requiring an exact visible
+surface should refuse that operation while this query returns `true`.

package/dist/appearance-batch-cohorts.d.ts

@@ -0,0 +1,33 @@
+import type { MeshData } from '@ifc-lite/geometry';
+import type { AppearanceOwner } from './appearance-preview.js';
+import type { AppearanceBucket } from './scene-appearance-buckets.js';
+interface Cohort {
+    id: number;
+    live: Set<AppearanceBucket>;
+    slots: Set<string>;
+    active: Set<string>;
+    vertexLimit: number;
+    indexLimit: number;
+}
+/** Metadata only: original GPU resources and source arrays are never retained.
+ * Only buckets descended from the same original batch can be rejoined. */
+export declare class AppearanceBatchCohorts {
+    private readonly parts;
+    private sequence;
+    private slots;
+    private buckets;
+    private cohorts;
+    constructor(parts: (id: number) => readonly MeshData[] | undefined);
+    private slot;
+    register(bucket: AppearanceBucket): void;
+    inherit(from: AppearanceBucket, to: AppearanceBucket): void;
+    group(part: MeshData, index: number): Cohort | undefined;
+    assign(bucket: AppearanceBucket, cohort: Cohort | undefined): void;
+    attach(bucket: AppearanceBucket): void;
+    detach(bucket: AppearanceBucket): void;
+    begin(owner: AppearanceOwner): void;
+    finish(owner: AppearanceOwner, rebuild: (old: AppearanceBucket[], parts: MeshData[]) => AppearanceBucket): void;
+    forget(expressId?: number): void;
+}
+export {};
+//# sourceMappingURL=appearance-batch-cohorts.d.ts.map

package/dist/appearance-batch-cohorts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"appearance-batch-cohorts.d.ts","sourceRoot":"","sources":["../src/appearance-batch-cohorts.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAC/D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AAGtE,UAAU,MAAM;IACd,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,GAAG,CAAC,gBAAgB,CAAC,CAAC;IAC5B,KAAK,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACnB,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;CACpB;AAUD;0EAC0E;AAC1E,qBAAa,sBAAsB;IAM/B,OAAO,CAAC,QAAQ,CAAC,KAAK;IALxB,OAAO,CAAC,QAAQ,CAAK;IACrB,OAAO,CAAC,KAAK,CAA6B;IAC1C,OAAO,CAAC,OAAO,CAA2C;IAC1D,OAAO,CAAC,OAAO,CAAqB;gBAEjB,KAAK,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,SAAS,QAAQ,EAAE,GAAG,SAAS;IAGzE,OAAO,CAAC,IAAI;IAMZ,QAAQ,CAAC,MAAM,EAAE,gBAAgB,GAAG,IAAI;IAexC,OAAO,CAAC,IAAI,EAAE,gBAAgB,EAAE,EAAE,EAAE,gBAAgB,GAAG,IAAI;IAI3D,KAAK,CAAC,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAGxD,MAAM,CAAC,MAAM,EAAE,gBAAgB,EAAE,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI;IAGlE,MAAM,CAAC,MAAM,EAAE,gBAAgB,GAAG,IAAI;IAGtC,MAAM,CAAC,MAAM,EAAE,gBAAgB,GAAG,IAAI;IAGtC,KAAK,CAAC,KAAK,EAAE,eAAe,GAAG,IAAI;IAKnC,MAAM,CACJ,KAAK,EAAE,eAAe,EACtB,OAAO,EAAE,CAAC,GAAG,EAAE,gBAAgB,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,KAAK,gBAAgB,GACxE,IAAI;IAkCP,MAAM,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI;CAuBjC"}

package/dist/appearance-batch-cohorts.js

@@ -0,0 +1,126 @@
+import { BATCH_CONSTANTS } from './constants.js';
+const ownerKey = (owner) => `${owner.modelIndex}:${owner.expressId}:`;
+const meshOwner = (part) => ({
+    expressId: part.expressId,
+    modelIndex: part.modelIndex ?? 0,
+});
+const vertexBytes = (part) => (part.positions.length / 3) * BATCH_CONSTANTS.BYTES_PER_VERTEX;
+/** Metadata only: original GPU resources and source arrays are never retained.
+ * Only buckets descended from the same original batch can be rejoined. */
+export class AppearanceBatchCohorts {
+    parts;
+    sequence = 0;
+    slots = new Map();
+    buckets = new WeakMap();
+    cohorts = new Set();
+    constructor(parts) {
+        this.parts = parts;
+    }
+    slot(part) {
+        const index = this.parts(part.expressId)?.indexOf(part) ?? -1;
+        if (index < 0)
+            throw new Error('Appearance batch lost its source part identity');
+        return ownerKey(meshOwner(part)) + index;
+    }
+    register(bucket) {
+        if (this.buckets.has(bucket))
+            return;
+        const slots = bucket.meshData.map((part) => this.slot(part));
+        const cohort = {
+            id: ++this.sequence,
+            live: new Set([bucket]),
+            slots: new Set(slots),
+            active: new Set(),
+            vertexLimit: bucket.meshData.reduce((n, p) => n + vertexBytes(p), 0),
+            indexLimit: bucket.meshData.reduce((n, p) => n + p.indices.byteLength, 0),
+        };
+        for (const slot of slots)
+            this.slots.set(slot, cohort);
+        this.buckets.set(bucket, cohort);
+        this.cohorts.add(cohort);
+    }
+    inherit(from, to) {
+        const cohort = this.buckets.get(from);
+        if (cohort)
+            this.buckets.set(to, cohort);
+    }
+    group(part, index) {
+        return this.slots.get(ownerKey(meshOwner(part)) + index);
+    }
+    assign(bucket, cohort) {
+        if (cohort)
+            this.buckets.set(bucket, cohort);
+    }
+    attach(bucket) {
+        this.buckets.get(bucket)?.live.add(bucket);
+    }
+    detach(bucket) {
+        this.buckets.get(bucket)?.live.delete(bucket);
+    }
+    begin(owner) {
+        const prefix = ownerKey(owner);
+        for (const [slot, cohort] of this.slots)
+            if (slot.startsWith(prefix))
+                cohort.active.add(prefix);
+    }
+    finish(owner, rebuild) {
+        const prefix = ownerKey(owner);
+        const affected = new Set();
+        for (const [slot, cohort] of this.slots)
+            if (slot.startsWith(prefix)) {
+                cohort.active.delete(prefix);
+                affected.add(cohort);
+            }
+        for (const cohort of affected) {
+            if (cohort.active.size || cohort.live.size < 2)
+                continue;
+            // Restore within original allocation bounds; changed colors remain distinct.
+            const colors = new Map();
+            for (const bucket of cohort.live) {
+                const key = bucket.meshData[0].color.join(',');
+                const group = colors.get(key) ?? [];
+                group.push(bucket);
+                colors.set(key, group);
+            }
+            for (const group of colors.values()) {
+                const parts = group.flatMap((bucket) => bucket.meshData);
+                if (group.length < 2 ||
+                    parts.reduce((n, p) => n + vertexBytes(p), 0) > cohort.vertexLimit ||
+                    parts.reduce((n, p) => n + p.indices.byteLength, 0) >
+                        cohort.indexLimit)
+                    continue;
+                const replacement = rebuild(group, parts);
+                for (const old of group)
+                    cohort.live.delete(old);
+                this.buckets.set(replacement, cohort);
+                cohort.live.add(replacement);
+            }
+        }
+    }
+    forget(expressId) {
+        if (expressId === undefined) {
+            this.slots.clear();
+            this.cohorts.clear();
+            this.buckets = new WeakMap();
+            return;
+        }
+        for (const [slot, cohort] of this.slots) {
+            if (Number(slot.split(':')[1]) !== expressId)
+                continue;
+            this.slots.delete(slot);
+            cohort.slots.delete(slot);
+            cohort.active.delete(slot.slice(0, slot.lastIndexOf(':') + 1));
+        }
+        for (const cohort of this.cohorts) {
+            for (const bucket of cohort.live) {
+                if (bucket.meshData.some((part) => part.expressId === expressId)) {
+                    this.buckets.delete(bucket);
+                    cohort.live.delete(bucket);
+                }
+            }
+            if (!cohort.slots.size)
+                this.cohorts.delete(cohort);
+        }
+    }
+}
+//# sourceMappingURL=appearance-batch-cohorts.js.map

package/dist/appearance-batch-cohorts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"appearance-batch-cohorts.js","sourceRoot":"","sources":["../src/appearance-batch-cohorts.ts"],"names":[],"mappings":"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"}

package/dist/appearance-companions.d.ts

@@ -0,0 +1,30 @@
+import type { MeshData } from '@ifc-lite/geometry';
+import type { AppearanceOwner } from './appearance-preview.js';
+/** Companion transitions change presence only, never geometry or appearance. */
+export declare function sameCompanionParts(a: readonly MeshData[], b: readonly MeshData[]): boolean;
+interface CompanionRecord {
+    owner: AppearanceOwner;
+    originals: readonly MeshData[];
+    sources: readonly MeshData[];
+    absent: boolean;
+    hidden: boolean;
+    drafts: number;
+    history: number;
+}
+/** Tombstones prove that missing geometry was removed by this transaction.
+ * They do not authorize restoring an arbitrary unloaded or replaced owner. */
+export declare class AppearanceCompanions {
+    private records;
+    get(owner: AppearanceOwner): CompanionRecord | undefined;
+    capture(owner: AppearanceOwner, expected: readonly MeshData[], current: readonly MeshData[] | undefined, source: (part: MeshData) => MeshData, hidden?: boolean): CompanionRecord;
+    validate(owner: AppearanceOwner, current: readonly MeshData[] | undefined): void;
+    install(owner: AppearanceOwner, parts: readonly MeshData[]): void;
+    finish(owner: AppearanceOwner, expected?: CompanionRecord): void;
+    retain(owner: AppearanceOwner): () => void;
+    private collect;
+    retained(geometry: readonly MeshData[], models: ReadonlySet<number>): Set<number>;
+    forget(id?: number): void;
+    forgetExcept(retained: ReadonlySet<number>): void;
+}
+export {};
+//# sourceMappingURL=appearance-companions.d.ts.map

package/dist/appearance-companions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"appearance-companions.d.ts","sourceRoot":"","sources":["../src/appearance-companions.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAS/D,gFAAgF;AAChF,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,SAAS,QAAQ,EAAE,EAAE,CAAC,EAAE,SAAS,QAAQ,EAAE,GAAG,OAAO,CAa1F;AAQD,UAAU,eAAe;IACvB,KAAK,EAAE,eAAe,CAAC;IACvB,SAAS,EAAE,SAAS,QAAQ,EAAE,CAAC;IAC/B,OAAO,EAAE,SAAS,QAAQ,EAAE,CAAC;IAC7B,MAAM,EAAE,OAAO,CAAC;IAChB,MAAM,EAAE,OAAO,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;8EAC8E;AAC9E,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,OAAO,CAAsC;IACrD,GAAG,CAAC,KAAK,EAAE,eAAe,GAAG,eAAe,GAAG,SAAS;IAKxD,OAAO,CAAC,KAAK,EAAE,eAAe,EAAE,QAAQ,EAAE,SAAS,QAAQ,EAAE,EAAE,OAAO,EAAE,SAAS,QAAQ,EAAE,GAAG,SAAS,EACrG,MAAM,EAAE,CAAC,IAAI,EAAE,QAAQ,KAAK,QAAQ,EAAE,MAAM,UAAQ,GAAG,eAAe;IAmCxE,QAAQ,CAAC,KAAK,EAAE,eAAe,EAAE,OAAO,EAAE,SAAS,QAAQ,EAAE,GAAG,SAAS,GAAG,IAAI;IAMhF,OAAO,CAAC,KAAK,EAAE,eAAe,EAAE,KAAK,EAAE,SAAS,QAAQ,EAAE,GAAG,IAAI;IAMjE,MAAM,CAAC,KAAK,EAAE,eAAe,EAAE,QAAQ,CAAC,EAAE,eAAe,GAAG,IAAI;IAMhE,MAAM,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM,IAAI;IAO1C,OAAO,CAAC,OAAO;IAGf,QAAQ,CAAC,QAAQ,EAAE,SAAS,QAAQ,EAAE,EAAE,MAAM,EAAE,WAAW,CAAC,MAAM,CAAC,GAAG,GAAG,CAAC,MAAM,CAAC;IAMjF,MAAM,CAAC,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI;IACzB,YAAY,CAAC,QAAQ,EAAE,WAAW,CAAC,MAAM,CAAC,GAAG,IAAI;CAClD"}

package/dist/appearance-companions.js

@@ -0,0 +1,138 @@
+function sameNumbers(a, b) {
+    if (a === undefined || b === undefined)
+        return a === b;
+    if (a.length !== b.length)
+        return false;
+    for (let index = 0; index < a.length; index++)
+        if (a[index] !== b[index])
+            return false;
+    return true;
+}
+/** Companion transitions change presence only, never geometry or appearance. */
+export function sameCompanionParts(a, b) {
+    return a.length === b.length && a.every((part, index) => {
+        const other = b[index];
+        return part.expressId === other.expressId && (part.modelIndex ?? 0) === (other.modelIndex ?? 0)
+            && part.geometryItemId === other.geometryItemId && !part.entityIds && !other.entityIds
+            && ['positions', 'normals', 'indices', 'localToWorld', 'shadingColor'].every(key => {
+                return sameNumbers(part[key], other[key]);
+            })
+            && sameNumbers(part.origin ?? [0, 0, 0], other.origin ?? [0, 0, 0])
+            && part.color.every((value, axis) => value === other.color[axis])
+            && part.texture === other.texture
+            && part.textureRef === other.textureRef && part.textureBitmap === other.textureBitmap && part.uvs === other.uvs;
+    });
+}
+function snapshot(part) {
+    return Object.freeze({ ...part, positions: part.positions.slice(), normals: part.normals.slice(), indices: part.indices.slice(),
+        color: [...part.color],
+        ...(part.shadingColor ? { shadingColor: [...part.shadingColor] } : {}),
+        ...(part.origin ? { origin: [...part.origin] } : {}),
+        ...(part.localToWorld ? { localToWorld: [...part.localToWorld] } : {}) });
+}
+/** Tombstones prove that missing geometry was removed by this transaction.
+ * They do not authorize restoring an arbitrary unloaded or replaced owner. */
+export class AppearanceCompanions {
+    records = new Map();
+    get(owner) {
+        const record = this.records.get(owner.expressId);
+        if (record && record.owner.modelIndex !== owner.modelIndex)
+            throw new Error('Companion model ownership changed.');
+        return record;
+    }
+    capture(owner, expected, current, source, hidden = false) {
+        let record = this.get(owner);
+        let vertices = 0, corners = 0;
+        if (expected.length > 10_000)
+            throw new Error('Companion geometry exceeds its snapshot budget.');
+        for (const part of expected) {
+            vertices += part.positions.length / 3;
+            corners += part.indices.length;
+            if (!Number.isSafeInteger(vertices) || vertices > 2_000_000 || corners > 1_500_000
+                || part.positions.length / 3 > 1_000_000)
+                throw new Error('Companion geometry exceeds its snapshot budget.');
+        }
+        if (!expected.length || expected.some(part => part.expressId !== owner.expressId
+            || (part.modelIndex ?? 0) !== owner.modelIndex || !part.geometryItemId || part.entityIds
+            || !part.positions.length || !part.indices.length || part.texture || part.textureRef || part.textureBitmap || part.uvs)) {
+            throw new Error('Companion removal requires original untextured owner geometry.');
+        }
+        if (record) {
+            if (!sameCompanionParts(expected, record.originals)
+                || (record.absent ? !!current?.length : current?.length ? !sameCompanionParts(current, record.originals) : !record.hidden)) {
+                throw new Error('Companion geometry changed since preparation.');
+            }
+        }
+        else {
+            if ((!current?.length && !hidden) || (current?.length && !sameCompanionParts(current, expected)))
+                throw new Error('Companion original geometry is missing or changed.');
+            const resident = current?.length ? current : expected;
+            const originals = resident.map(snapshot);
+            const sources = resident.map((part, index) => {
+                const raw = source(part);
+                return raw === part ? originals[index] : snapshot(raw);
+            });
+            record = { owner: Object.freeze({ ...owner }), originals: Object.freeze(originals),
+                sources: Object.freeze(sources), absent: false, hidden, drafts: 0, history: 0 };
+            this.records.set(owner.expressId, record);
+        }
+        record.hidden = hidden && !current?.length;
+        record.drafts++;
+        return record;
+    }
+    validate(owner, current) {
+        const record = this.get(owner);
+        if (record && (record.absent ? !!current?.length : current?.length ? !sameCompanionParts(current, record.originals) : !record.hidden)) {
+            throw new Error('Companion geometry changed during the appearance transaction.');
+        }
+    }
+    install(owner, parts) {
+        const record = this.get(owner);
+        if (!record)
+            return;
+        if (parts.length && !sameCompanionParts(parts, record.originals))
+            throw new Error('Companion restoration changed its original geometry.');
+        record.absent = !parts.length;
+    }
+    finish(owner, expected) {
+        const record = this.get(owner);
+        if (!record || (expected && record !== expected))
+            return;
+        record.drafts = Math.max(0, record.drafts - 1);
+        this.collect(record);
+    }
+    retain(owner) {
+        const record = this.get(owner);
+        if (!record)
+            return () => { };
+        record.history++;
+        let released = false;
+        return () => { if (!released) {
+            released = true;
+            record.history--;
+            this.collect(record);
+        } };
+    }
+    collect(record) {
+        if (!record.drafts && !record.history && this.records.get(record.owner.expressId) === record)
+            this.records.delete(record.owner.expressId);
+    }
+    retained(geometry, models) {
+        const byOwner = new Map();
+        for (const part of geometry) {
+            const parts = byOwner.get(part.expressId) ?? [];
+            parts.push(part);
+            byOwner.set(part.expressId, parts);
+        }
+        return new Set([...this.records].filter(([id, record]) => record.history > 0 && models.has(record.owner.modelIndex)
+            && (record.absent ? !byOwner.get(id)?.length : sameCompanionParts(byOwner.get(id) ?? [], record.sources))).map(([id]) => id));
+    }
+    forget(id) { if (id === undefined)
+        this.records.clear();
+    else
+        this.records.delete(id); }
+    forgetExcept(retained) { for (const id of this.records.keys())
+        if (!retained.has(id))
+            this.records.delete(id); }
+}
+//# sourceMappingURL=appearance-companions.js.map

package/dist/appearance-companions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"appearance-companions.js","sourceRoot":"","sources":["../src/appearance-companions.ts"],"names":[],"mappings":"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"}

package/dist/appearance-preview.d.ts

@@ -0,0 +1,93 @@
+import type { MeshData } from '@ifc-lite/geometry';
+/** expressId is already federation-resolved; modelIndex is the renderer model. */
+export interface AppearanceOwner {
+    readonly expressId: number;
+    readonly modelIndex: number;
+}
+export interface AppearanceToken {
+    readonly owner: AppearanceOwner;
+}
+export interface AppearanceChange {
+    readonly owner: AppearanceOwner;
+    readonly before: readonly MeshData[];
+    readonly after: readonly MeshData[];
+    /** Exact original geometry for a companion presence-only transition. */
+    readonly companionOriginals?: readonly MeshData[];
+    readonly beforeInstanced?: true;
+    readonly afterInstanced?: true;
+    /** Explicit occurrence-local representation changes, captured before preview. */
+    readonly geometryItemRemaps?: readonly {
+        readonly from: number;
+        readonly to: number;
+    }[];
+}
+export interface AppearancePreviewOptions extends Pick<AppearanceChange, 'geometryItemRemaps' | 'companionOriginals'> {
+    /** Canonical native originals for an occurrence absent from flat scene geometry. */
+    readonly materializedOriginals?: readonly MeshData[];
+    /** Host proved canonical originals exist but current visibility omits residency. */
+    readonly companionHidden?: true;
+}
+export interface AppearancePreview {
+    /** Requires finalized resident geometry, or canonical materializedOriginals
+     * for one retained GPU occurrence. */
+    begin(owner: AppearanceOwner, options?: AppearancePreviewOptions): AppearanceToken;
+    /** Full part list in source order. Geometry must preserve exact triangle corners.
+     * Mesh arrays are borrowed immutable data, including image pixels and UVs. */
+    update(token: AppearanceToken, parts: readonly MeshData[]): void;
+    /** Current canonical parts, including retained originals when an instance is active. */
+    getParts?(owner: AppearanceOwner): readonly MeshData[] | undefined;
+    /** Retain an original occurrence for one host history command; release on disposal. */
+    retainSource?(owner: AppearanceOwner): () => void;
+    cancel(token: AppearanceToken): void;
+    /** Discard an uncommitted owner draft before replaying its committed history. */
+    commit(token: AppearanceToken): AppearanceChange;
+    /** Validate a whole command before consuming any owner; returned commit is idempotent. */
+    prepareCommit(tokens: readonly AppearanceToken[]): () => AppearanceChange[];
+}
+export interface AppearanceAdapter<Resource> {
+    capture(owner: AppearanceOwner, originals?: readonly MeshData[], companions?: readonly MeshData[], companionHidden?: true): {
+        parts: readonly MeshData[];
+        resources: readonly Resource[];
+        abandon?(): void;
+        companionOriginals?: readonly MeshData[];
+    };
+    validate?(owner: AppearanceOwner): void;
+    instanced?(owner: AppearanceOwner, parts: readonly MeshData[]): boolean;
+    parts?(owner: AppearanceOwner): readonly MeshData[] | undefined;
+    retainSource?(owner: AppearanceOwner): () => void;
+    stage(parts: readonly MeshData[]): readonly Resource[];
+    install(owner: AppearanceOwner, parts: readonly MeshData[], resources: readonly Resource[]): void;
+    release(resources: readonly Resource[]): void;
+    finished?(owner: AppearanceOwner): void;
+    forget?(expressId?: number): void;
+    prepareRebuild?(geometry: readonly MeshData[], models: ReadonlySet<number>): Set<number>;
+    finishRebuild?(retained: ReadonlySet<number>): void;
+    discardedForRebuild?(retained: ReadonlySet<number>): readonly number[];
+}
+/** Owns detached GPU originals until cancellation/commit; never exports GPU handles. */
+export declare class AppearancePreviewController<Resource> implements AppearancePreview {
+    private readonly adapter;
+    private drafts;
+    private issued;
+    constructor(adapter: AppearanceAdapter<Resource>);
+    begin(owner: AppearanceOwner, options?: AppearancePreviewOptions): AppearanceToken;
+    getParts(owner: AppearanceOwner): readonly MeshData[] | undefined;
+    retainSource(owner: AppearanceOwner): () => void;
+    private draft;
+    update(token: AppearanceToken, parts: readonly MeshData[]): void;
+    private installDraft;
+    cancel(token: AppearanceToken): void;
+    commit(token: AppearanceToken): AppearanceChange;
+    prepareCommit(tokens: readonly AppearanceToken[]): () => AppearanceChange[];
+    private finished;
+    owns(expressId: number): boolean;
+    /** End drafts, then validate every surviving history owner before GPU reset. */
+    prepareRebuild(geometry: readonly MeshData[], models: ReadonlySet<number>): Set<number>;
+    finishRebuild(retained: ReadonlySet<number>): void;
+    discardedForRebuild(retained: ReadonlySet<number>): readonly number[];
+    /** Geometry edits supersede an uncommitted appearance draft. */
+    cancelFor(expressId: number): void;
+    /** Scene deletion/teardown invalidates tokens and releases detached originals. */
+    forget(expressId?: number): void;
+}
+//# sourceMappingURL=appearance-preview.d.ts.map

package/dist/appearance-preview.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"appearance-preview.d.ts","sourceRoot":"","sources":["../src/appearance-preview.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAInD,kFAAkF;AAClF,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AACD,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,KAAK,EAAE,eAAe,CAAC;CACjC;AACD,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,KAAK,EAAE,eAAe,CAAC;IAChC,QAAQ,CAAC,MAAM,EAAE,SAAS,QAAQ,EAAE,CAAC;IACrC,QAAQ,CAAC,KAAK,EAAE,SAAS,QAAQ,EAAE,CAAC;IACpC,wEAAwE;IACxE,QAAQ,CAAC,kBAAkB,CAAC,EAAE,SAAS,QAAQ,EAAE,CAAC;IAClD,QAAQ,CAAC,eAAe,CAAC,EAAE,IAAI,CAAC;IAChC,QAAQ,CAAC,cAAc,CAAC,EAAE,IAAI,CAAC;IAC/B,iFAAiF;IACjF,QAAQ,CAAC,kBAAkB,CAAC,EAAE,SAAS;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CACzF;AACD,MAAM,WAAW,wBAAyB,SAAQ,IAAI,CAAC,gBAAgB,EAAE,oBAAoB,GAAG,oBAAoB,CAAC;IACnH,oFAAoF;IACpF,QAAQ,CAAC,qBAAqB,CAAC,EAAE,SAAS,QAAQ,EAAE,CAAC;IACrD,oFAAoF;IACpF,QAAQ,CAAC,eAAe,CAAC,EAAE,IAAI,CAAC;CACjC;AACD,MAAM,WAAW,iBAAiB;IAChC;0CACsC;IACtC,KAAK,CAAC,KAAK,EAAE,eAAe,EAAE,OAAO,CAAC,EAAE,wBAAwB,GAAG,eAAe,CAAC;IACnF;kFAC8E;IAC9E,MAAM,CAAC,KAAK,EAAE,eAAe,EAAE,KAAK,EAAE,SAAS,QAAQ,EAAE,GAAG,IAAI,CAAC;IACjE,wFAAwF;IACxF,QAAQ,CAAC,CAAC,KAAK,EAAE,eAAe,GAAG,SAAS,QAAQ,EAAE,GAAG,SAAS,CAAC;IACnE,uFAAuF;IACvF,YAAY,CAAC,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM,IAAI,CAAC;IAClD,MAAM,CAAC,KAAK,EAAE,eAAe,GAAG,IAAI,CAAC;IACrC,iFAAiF;IACjF,MAAM,CAAC,KAAK,EAAE,eAAe,GAAG,gBAAgB,CAAC;IACjD,0FAA0F;IAC1F,aAAa,CAAC,MAAM,EAAE,SAAS,eAAe,EAAE,GAAG,MAAM,gBAAgB,EAAE,CAAC;CAC7E;AACD,MAAM,WAAW,iBAAiB,CAAC,QAAQ;IACzC,OAAO,CAAC,KAAK,EAAE,eAAe,EAAE,SAAS,CAAC,EAAE,SAAS,QAAQ,EAAE,EAAE,UAAU,CAAC,EAAE,SAAS,QAAQ,EAAE,EAAE,eAAe,CAAC,EAAE,IAAI,GAAG;QAC1H,KAAK,EAAE,SAAS,QAAQ,EAAE,CAAC;QAC3B,SAAS,EAAE,SAAS,QAAQ,EAAE,CAAC;QAC/B,OAAO,CAAC,IAAI,IAAI,CAAC;QACjB,kBAAkB,CAAC,EAAE,SAAS,QAAQ,EAAE,CAAC;KAC1C,CAAC;IACF,QAAQ,CAAC,CAAC,KAAK,EAAE,eAAe,GAAG,IAAI,CAAC;IACxC,SAAS,CAAC,CAAC,KAAK,EAAE,eAAe,EAAE,KAAK,EAAE,SAAS,QAAQ,EAAE,GAAG,OAAO,CAAC;IACxE,KAAK,CAAC,CAAC,KAAK,EAAE,eAAe,GAAG,SAAS,QAAQ,EAAE,GAAG,SAAS,CAAC;IAChE,YAAY,CAAC,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM,IAAI,CAAC;IAClD,KAAK,CAAC,KAAK,EAAE,SAAS,QAAQ,EAAE,GAAG,SAAS,QAAQ,EAAE,CAAC;IACvD,OAAO,CACL,KAAK,EAAE,eAAe,EACtB,KAAK,EAAE,SAAS,QAAQ,EAAE,EAC1B,SAAS,EAAE,SAAS,QAAQ,EAAE,GAC7B,IAAI,CAAC;IACR,OAAO,CAAC,SAAS,EAAE,SAAS,QAAQ,EAAE,GAAG,IAAI,CAAC;IAC9C,QAAQ,CAAC,CAAC,KAAK,EAAE,eAAe,GAAG,IAAI,CAAC;IACxC,MAAM,CAAC,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,cAAc,CAAC,CAAC,QAAQ,EAAE,SAAS,QAAQ,EAAE,EAAE,MAAM,EAAE,WAAW,CAAC,MAAM,CAAC,GAAG,GAAG,CAAC,MAAM,CAAC,CAAC;IACzF,aAAa,CAAC,CAAC,QAAQ,EAAE,WAAW,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC;IACpD,mBAAmB,CAAC,CAAC,QAAQ,EAAE,WAAW,CAAC,MAAM,CAAC,GAAG,SAAS,MAAM,EAAE,CAAC;CACxE;AAWD,wFAAwF;AACxF,qBAAa,2BAA2B,CAAC,QAAQ,CAC/C,YAAW,iBAAiB;IAIhB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAFpC,OAAO,CAAC,MAAM,CAAsC;IACpD,OAAO,CAAC,MAAM,CAAkC;gBACnB,OAAO,EAAE,iBAAiB,CAAC,QAAQ,CAAC;IAEjE,KAAK,CAAC,KAAK,EAAE,eAAe,EAAE,OAAO,CAAC,EAAE,wBAAwB,GAAG,eAAe;IAyClF,QAAQ,CAAC,KAAK,EAAE,eAAe,GAAG,SAAS,QAAQ,EAAE,GAAG,SAAS;IACjE,YAAY,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM,IAAI;IAEhD,OAAO,CAAC,KAAK;IAOb,MAAM,CAAC,KAAK,EAAE,eAAe,EAAE,KAAK,EAAE,SAAS,QAAQ,EAAE,GAAG,IAAI;IA6EhE,OAAO,CAAC,YAAY;IAcpB,MAAM,CAAC,KAAK,EAAE,eAAe,GAAG,IAAI;IAYpC,MAAM,CAAC,KAAK,EAAE,eAAe,GAAG,gBAAgB;IAIhD,aAAa,CAAC,MAAM,EAAE,SAAS,eAAe,EAAE,GAAG,MAAM,gBAAgB,EAAE;IAsD3E,OAAO,CAAC,QAAQ;IAWhB,IAAI,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO;IAIhC,gFAAgF;IAChF,cAAc,CAAC,QAAQ,EAAE,SAAS,QAAQ,EAAE,EAAE,MAAM,EAAE,WAAW,CAAC,MAAM,CAAC,GAAG,GAAG,CAAC,MAAM,CAAC;IAIvF,aAAa,CAAC,QAAQ,EAAE,WAAW,CAAC,MAAM,CAAC,GAAG,IAAI;IAClD,mBAAmB,CAAC,QAAQ,EAAE,WAAW,CAAC,MAAM,CAAC,GAAG,SAAS,MAAM,EAAE;IAErE,gEAAgE;IAChE,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAKlC,kFAAkF;IAClF,MAAM,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI;CASjC"}