@nika-js/onlymap 0.6.0 → 0.6.1

package/dist/runtime-core.d.ts

@@ -5,6 +5,23 @@ import type { LayerIR } from "./ir";
 import { type Selection } from "./selection";
 import type { ValidationEntry } from "./validation";
 import type { MapViewport } from "./basemap";
+/**
+ * The tile-level EXT_structural_metadata property-table index, resolved
+ * independently of `FeatureMeshLayer`'s own copy of this same computation.
+ *
+ * `tile.content.featureIdPropertyTableIndex` (which `FeatureMeshLayer`
+ * eventually sets, in its own `renderLayers()`) is NOT readable here: deck.gl's
+ * `Tile3DLayer._onTileLoad` fires the `onTileLoad` prop callback (what feeds
+ * this hook) BEFORE it ever constructs `FeatureMeshLayer` for that tile —
+ * confirmed against `@deck.gl/geo-layers`'s own `_onTileLoad`/`_getSubLayer`
+ * ordering. Reading that field here always saw `undefined`, silently falling
+ * back to property table 0 regardless of which table a tile's feature IDs
+ * actually reference — invisible only because this repo's own IFC converter
+ * never emits more than one table. Recomputing from the tile's raw glTF with
+ * the same pure, already-tested helpers `FeatureMeshLayer` itself uses avoids
+ * depending on that ordering entirely.
+ */
+export declare function resolveTilePropertyTableIndex(gltf: unknown, featureIdProperty: string): number;
 /** Mapbox presets/protocol URLs aren't implemented — kept maplibre-free so validation/runtime can check without loading the chunk. */
 export declare function isMapboxBasemap(raw: string): boolean;
 export interface InitialView {
@@ -25,6 +42,24 @@ export interface CameraOptions {
     /** Arc the move (zoom-out-and-in) instead of easing directly — MapLibre `flyTo` / deck `FlyToInterpolator`. */
     curve?: boolean;
 }
+export { resolveFeatureColor } from "./feature-colors";
+/** One layer's accumulated (per-tile) property tables — see RuntimeCore.featureTables. */
+export interface FeatureTableEntry {
+    source: string;
+    tiles: Map<string, Record<string, unknown>[]>;
+    rows: Record<string, unknown>[];
+    rowsVersion: number;
+    mappingKey?: string;
+    mapping?: import("./feature-colors").FeatureColorMapping | null;
+}
+/**
+ * The accumulator, extracted for direct testing: resets on a SOURCE change
+ * (the loader widget swapping models under one layer id), REPLACES rows for a
+ * re-seen tile key (deck evicts + refetches tiles as new objects — identity
+ * dedup accumulated duplicates), and keeps per-tile row arrays because
+ * feature IDs are tile-local. Returns the (possibly new) entry.
+ */
+export declare function accumulateFeatureRows(tables: Map<string, FeatureTableEntry>, layerId: string, sourceKey: string, tileKey: string, rows: Record<string, unknown>[]): FeatureTableEntry;
 export interface RuntimeCoreCallbacks {
     /**
      * Fired whenever the view state changes (pan/zoom/pitch/bearing) — a
@@ -34,7 +69,14 @@ export interface RuntimeCoreCallbacks {
      * convention, the echo-loop half of two-way store binding.
      */
     onViewportChange?: (origin: ViewOrigin) => void;
-    onSelectionChange?: (selection: Selection | null) => void;
+    /**
+     * `pickType` is the pointer event that produced this pick — REQUIRED even
+     * when `selection` is null (an empty pick), because toSelection discards
+     * empty picks and with them their type. Overlays scoped with
+     * `selection-type` need it: a click on empty space dismisses a
+     * click-anchored popup, a hover over empty space must not.
+     */
+    onSelectionChange?: (selection: Selection | null, pickType: "hover" | "click") => void;
     /** Fired once the map (deck.gl standalone, or the basemap) has finished its async init (spec: Behavior Engine "load" event). */
     onLoad?: () => void;
     /**
@@ -52,6 +94,14 @@ export interface RuntimeCoreCallbacks {
      * deck reports none (e.g. off-globe).
      */
     onMapPoint?: (coordinate: [number, number] | null, kind: "click" | "hover") => void;
+    /**
+     * A `pick-features` layer decoded its EXT_structural_metadata property
+     * table — the whole table, indexed by feature ID. Fires once per layer, on
+     * the first tile that carries one, because every tile in a tileset shares
+     * the same schema. This is what lets a legend enumerate categories without
+     * a hand-built sidecar next to the tileset.
+     */
+    onFeatureTable?: (layerId: string, rows: Record<string, unknown>[]) => void;
     /**
      * A tileset-bearing layer (Tile3DLayer) finished loading its root tileset
      * — the consumer hook for tools that must reach the LIVE deck tileset
@@ -60,6 +110,30 @@ export interface RuntimeCoreCallbacks {
      * @loaders.gl/tiles type dependency in the core).
      */
     onTilesetLoad?: (layerId: string, tileset: unknown) => void;
+    /**
+     * A `carriesGeoreference` layer (BIMLayer) finished loading its source file
+     * and read whatever georeferencing it declares — `hasFullMapConversion`
+     * is true only when the file both resolved a real position
+     * (`IfcMapConversion` into a recognized CRS) AND declared
+     * `OrthogonalHeight`, the two facts absolute elevation needs to mean
+     * anything. Informational for consumers: the library never auto-applies
+     * terrain from it (what-you-write-is-what-you-see) — validation instead
+     * requires the map to author `terrain` explicitly for these layers.
+     *
+     * `approximatePlacement` is a narrower, separate fact: true whenever the
+     * file's position did NOT come from a real `IfcMapConversion` (IfcSite
+     * lat/lon, or no georeference at all) — that source has no rotation data
+     * at all, and is very often an authoring tool's default location rather
+     * than a survey. A plain boolean (not the raw `originSource` string) to
+     * keep this file decoupled from IFC-specific types, same reasoning as
+     * `hasFullMapConversion` already being precomputed rather than passed as
+     * raw parts. The front-end layer surfaces this as a validation warning.
+     */
+    onGeoreference?: (layerId: string, info: {
+        orthogonalHeight?: number;
+        hasFullMapConversion: boolean;
+        approximatePlacement: boolean;
+    }) => void;
     /**
      * Runtime error boundary (spec: "Runtime error boundary") — deck.gl-level
      * failures (a crashing accessor, an incompatible prop) formatted into the
@@ -138,6 +212,40 @@ export declare class RuntimeCore {
     private terrainGeneration;
     /** Rendered deck layer id → authored manifest/controller id (terrain uses fresh renderer ids). */
     private renderedLayerIds;
+    /** The decoded property table for a pick-features layer, or undefined before its first tile. */
+    getFeatureTable(layerId: string): Record<string, unknown>[] | undefined;
+    /**
+     * Decoded property tables per `pick-features` layer, keyed by layer id.
+     * Held here rather than in the element because LAYER props derive from them
+     * too (`feature-color-by`), not only widgets. `rows` accumulates across
+     * every tile that has loaded so far (see `featureTableHook`) — for a
+     * grid-tiled model this means the table is only as complete as whatever
+     * has actually streamed in, same as any real tiled 3D-Tiles viewer.
+     */
+    /**
+     * Per-layer accumulated property tables (spec: BIM feature picking). Rows
+     * are kept PER TILE — feature IDs are tile-local, so a flat concatenation
+     * can never be indexed by feature ID (the multi-tile styling bug). `rows`
+     * is the derived aggregate for legends/`ctx.features()`/global domains;
+     * `tiles` is keyed by a STABLE content key so an evicted-and-refetched tile
+     * REPLACES its rows instead of duplicating them, and `source` is the layer's
+     * source URL string (not the per-parse rows-array identity, which reset the
+     * whole accumulator on every reconcile mid-stream). `mapping` memoizes the
+     * derived colour mapping so animation frames reuse one identity — the
+     * style-texture-rebuild-per-rAF fix.
+     */
+    private featureTables;
+    /** Fallback identity for tiles that expose no content URL — a stable per-object key. */
+    private tileKeyFallback;
+    private tileKeyCounter;
+    /**
+     * The memoized global colour mapping for a layer — rebuilt only when the
+     * accumulated table grows or a colour prop changes, so `applyLayers` calls
+     * from the per-frame channel (patchAnimatedProps runs one per rAF during
+     * story animations) hand every tile the SAME mapping identity and no GPU
+     * style texture is ever rebuilt for an unrelated animation.
+     */
+    private featureColorMappingFor;
     /**
      * The basemap attribute suppressed while terrain is active — a flat
      * MapLibre canvas at sea level visibly desyncs from a raised surface
@@ -259,7 +367,7 @@ export declare class RuntimeCore {
      * behavior dispatch, and the overlay flush are same-path by construction.
      * Available in every mode (a browser-level test may use it too).
      */
-    injectPick(selection: Selection | null): void;
+    injectPick(selection: Selection | null, pickType?: "hover" | "click"): void;
     getViewState(): Readonly<ViewState>;
     /**
      * Sketch capture (spec: "Manual Drawing", D4) — while a draw tool is active,
@@ -305,4 +413,3 @@ export declare class RuntimeCore {
     flyToBounds(bounds: [[number, number], [number, number]], padding?: number, opts?: CameraOptions): void;
     destroy(): void;
 }
-export {};

package/dist/selection.d.ts

@@ -3,6 +3,7 @@
  * Converts a deck.gl PickingInfo into the documented, deck.gl-independent
  * ctx.selection shape (HU2: ctx never leaks deck.gl internals).
  */
+import { type Tile3DPickMetadata } from "./tile3d-metadata";
 export interface Selection {
     layerId: string;
     object: unknown;
@@ -16,6 +17,31 @@ export interface Selection {
     coordinate: [number, number] | null;
     pixel: [number, number];
     type: "hover" | "click";
+    /**
+     * BIM feature-picking epic. Undefined for every pick except a
+     * Tile3DLayer pick that resolved SOME metadata; `class`/`properties`
+     * follow the same "ctx never leaks deck.gl internals" normalization as
+     * the rest of this shape, `rawMetadata` is the deliberate escape hatch.
+     * Two sources, most-specific-wins:
+     * - Phase 1 (tile granularity, always active): 3D-Tiles-native
+     *   tileset/group/tile/content entities, merged with a single-feature
+     *   glTF EXT_structural_metadata property table when the content
+     *   resolves to exactly one feature. See src/tile3d-metadata.ts.
+     * - Phase 2 (per-feature, only when `pick-features` resolved a specific
+     *   vertex-level feature): overrides Phase 1's properties/class/guid
+     *   with the picked feature's own row from the same property table,
+     *   still layered on top of Phase 1's broader tile-level context. See
+     *   src/layers/feature-mesh-layer.ts.
+     */
+    properties?: Record<string, unknown>;
+    class?: string | null;
+    /** Best-effort identity (IFC GlobalId / gml:id / guid), from either Phase 1's tile-granularity merge or Phase 2's per-feature row — see tile3d-metadata.ts's findGuidLike. Undefined when nothing matched. */
+    guid?: string | null;
+    /** The picked vertex-level feature ID — only set by Phase 2's per-vertex picking; undefined for a Phase 1 tile-granularity pick. TILE-LOCAL: each tile's property table indexes 0..n-1, so the same number exists in every tile of a grid-tiled model — use `featureKey` to identify an element across tiles/models. */
+    featureId?: number;
+    /** Stable cross-tile identity for a Phase 2 pick: the element's own guid when the table carries one (IFC GlobalId / gml:id), else `<tile content key>#<featureId>`. Undefined when no per-feature pick resolved. */
+    featureKey?: string;
+    rawMetadata?: Tile3DPickMetadata["rawMetadata"];
 }
 interface PickingInfoLike {
     layer?: {
@@ -26,6 +52,13 @@ interface PickingInfoLike {
     coordinate?: number[];
     x: number;
     y: number;
+    /** Tile3DLayer's own getPickingInfo always sets this (undefined on a miss) — see tile3d-metadata.ts. */
+    sourceTile?: unknown;
+    /** Set by src/layers/feature-mesh-layer.ts's SinglePrimitiveFeatureLayer.getPickingInfo when pick-features resolved a specific vertex-level feature — takes precedence over the tile-granularity fallback below. */
+    featureId?: number;
+    properties?: Record<string, unknown>;
+    class?: string | null;
+    guid?: string | null;
 }
 export declare function toSelection(info: PickingInfoLike, type: "hover" | "click", resolveLayerId?: (renderedId: string) => string): Selection | null;
 export {};

package/dist/site-placement.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Declarative georeferencing — `site-origin` / `site-heading` / `site-scale`.
+ *
+ * An IFC export tells you where it thinks it is, and it is very often wrong:
+ * authoring tools ship a default project location (the Medical-Dental Clinic
+ * sample carries Revit's Boston default; the Duplex carries a Chicago city
+ * centre point), `IfcMapConversion` is absent from most IFC2x3 files, and
+ * `TrueNorth` is routinely left unset. Baking that into the tileset at
+ * conversion time means every correction is a reconversion.
+ *
+ * So placement moves to the layer, where it is an attribute like any other —
+ * inspectable in the markup, settable by the IFC loader from whatever it
+ * managed to extract, and undoable/story-steppable for free.
+ *
+ * Two transports, because the two layers that make up an IFC model are
+ * anchored differently:
+ *
+ *   - The MESH is a 3D Tiles tileset whose root already carries an
+ *     east/north/up frame. deck's `Tile3DLayer` forwards `loadOptions.tileset`
+ *     into the `Tileset3D` constructor, and `Tileset3D` PRE-multiplies its
+ *     `modelMatrix` onto the root transform, so relocating means cancelling
+ *     the baked frame first: `target · Rz · S · baked⁻¹`. That needs the baked
+ *     frame, hence `tilesetBakedFrame` below.
+ *   - The OUTLINES are a `PathLayer` of local east/north/up metres, which
+ *     `METER_OFFSETS` places directly from `coordinateOrigin` — no baked frame
+ *     to cancel, and rotation/scale ride a plain `modelMatrix` uniform, so
+ *     they are free to change per frame.
+ */
+import { Matrix4 } from "@math.gl/core";
+export interface SitePlacement {
+    /** Absent when the author gave only a heading/scale — rotate in place. */
+    origin: [number, number, number] | null;
+    /** Degrees CLOCKWISE from true north, matching how a survey bearing reads. */
+    heading: number;
+    scale: number;
+}
+/**
+ * Reads the three placement props off a resolved layer IR.
+ *
+ * Returns null when none is authored, which is the common case and must stay
+ * free: no prefetch, no matrix, no change to how the layer loads.
+ */
+export declare function parseSitePlacement(props: Record<string, unknown>): SitePlacement | null;
+/**
+ * Short, DOT-FREE token for "has the placement changed?" — appended to a
+ * tileset URL to force deck to reload (see the cache-bust in runtime-core).
+ *
+ * Hashed rather than spelled out because loaders.gl types a tile by
+ * `url.split('?')[0].split('.').pop()`, and a coordinate spelled into the
+ * fragment (`#site=-71.059776,…`) hands that sniffer `059776` instead of
+ * `json`. Tilesets that force `isTileset` would survive it; ones relying on
+ * auto-detection would not, and the failure is the silent kind where nothing
+ * renders. Base-36 of a 32-bit FNV-1a has no dots by construction.
+ */
+export declare function sitePlacementToken(p: SitePlacement): string;
+/**
+ * Local east/north/up frame at a geodetic point, as the column-major matrix
+ * 3D Tiles calls `root.transform`.
+ */
+export declare function enuMatrix(lonDeg: number, latDeg: number, height?: number): Matrix4;
+/**
+ * Rotation + uniform scale about the model's own origin, in its local
+ * east/north/up frame.
+ *
+ * Heading is clockwise from north; ENU is right-handed with +Z up, where a
+ * POSITIVE rotation about Z turns north toward west. So a clockwise bearing is
+ * a negative rotation — the sign here is the whole reason this is a named
+ * function rather than an inline `rotateZ`.
+ */
+export declare function localPlacementMatrix(p: SitePlacement): Matrix4;
+/**
+ * The `Tileset3D.modelMatrix` that moves a tileset anchored at `baked` onto `p`.
+ *
+ * `target · Rz · S · anchor⁻¹`: the inverse undoes the frame the converter
+ * wrote, then the model is re-planted. With no `site-origin` the target IS the
+ * anchor, so the inverse cancels it exactly and only the rotation and scale
+ * survive — `site-heading` on its own spins the model where it stands.
+ *
+ * Both the pivot and the outline overlay's `coordinateOrigin` are the same
+ * ground-level site point, so mesh and outlines rotate together.
+ */
+export declare function tilesetPlacementMatrix(baked: Matrix4, p: SitePlacement): Matrix4;
+export declare function tilesetBakedFrame(url: string, onReady: () => void): Matrix4 | null | undefined;
+/** Test seam — the cache is process-wide and would leak between cases. */
+export declare function resetSitePlacementCache(): void;

package/dist/testing.d.ts

@@ -49,8 +49,12 @@ export interface TestHarness {
      * selection path a real pick takes. Settles before resolving.
      */
     pick(opts: PickOptions): Promise<void>;
-    /** Ends the current selection (a hover-off) — the path that auto-hides tooltips. */
-    clearSelection(): Promise<void>;
+    /**
+     * Ends the current selection with an empty pick. Default kind "hover" — a
+     * hover-off, the path that auto-hides tooltips. Pass "click" for a click on
+     * empty space, which is what dismisses a `selection-type="click"` popup.
+     */
+    clearSelection(kind?: "hover" | "click"): Promise<void>;
     /**
      * Feeds a map coordinate through the same path a real deck click/hover
      * takes — drives the draw controller and fires the `om-map-point` event.

package/dist/tile3d-metadata.d.ts

@@ -0,0 +1,185 @@
+/**
+ * BIM feature-picking epic, Phase 1 (design pending — see
+ * agent-map-library-architecture.md once the design section lands).
+ *
+ * Enriches a Tile3DLayer pick with whatever metadata is CHEAPLY available at
+ * tile granularity — no shader work, no new manifest attribute, no per-tile
+ * caching, no new deck.gl prop injection. Three independent sources merge,
+ * most-content-specific winning when more than one is present:
+ *
+ * 1. glTF `EXT_mesh_features` + `EXT_structural_metadata`, already fully
+ *    decoded by loaders.gl's GLTFLoader by the time a tile is even
+ *    renderable (`Tile3D.content.gltf`, post `postProcessGLTF` — verified
+ *    against node_modules/@loaders.gl/{gltf,3d-tiles} source: primitive
+ *    `.extensions` and the top-level `EXT_structural_metadata` survive the
+ *    postprocess step via object spread, so the same decode this repo's
+ *    Phase-0 spike proved against a real fixture applies here unchanged).
+ *    Only used when the content resolves to exactly ONE feature — Phase 1
+ *    has no per-vertex resolution (that's Phase 2's `pick-features` shader
+ *    work), so a multi-feature content would be misattributing properties
+ *    to whichever vertex the coarse tile-level pick happened to return.
+ * 2. **Legacy 3D Tiles 1.0 batch tables** — b3dm's older per-feature
+ *    mechanism (a JSON `batchTableJson` of `{propertyName: [oneValuePerBatch]}`
+ *    arrays, keyed by a `_BATCHID` vertex attribute never surfaced by this
+ *    layer since Phase 1 doesn't do per-vertex work). Verified directly
+ *    against real production data (NYC DoITT building footprints and Japan's
+ *    PLATEAU CityGML export, both streamed live via Cesium ion): real-world
+ *    3D Tiles datasets overwhelmingly still ship this older mechanism, not
+ *    1.1's `EXT_structural_metadata` — this is the metadata source that
+ *    actually matters for content people can get their hands on today, not
+ *    just synthetic samples. loaders.gl's b3dm parser
+ *    (`parse-3d-tile-tables.js`) sets `tile.featureTableJson.BATCH_LENGTH`
+ *    and `tile.batchTableJson` directly on the SAME parsed-content object
+ *    `.gltf` lives on (confirmed by reading the parser itself — no
+ *    intermediate class wraps it). Same single-feature-only restriction as
+ *    the glTF path, same reasoning: `BATCH_LENGTH === 1` is unambiguous,
+ *    `BATCH_LENGTH > 1` needs per-vertex `_BATCHID` resolution this layer
+ *    doesn't attempt.
+ * 3. 3D Tiles 1.1's OWN (non-glTF) metadata mechanism — tileset/group/tile/
+ *    content-level entities declared directly in tileset.json as plain
+ *    inline JSON (no binary property-table decode needed at this
+ *    granularity, unlike the glTF one — verified against a real tileset.json,
+ *    CesiumGS/3d-tiles-samples 1.1/MetadataGranularities). loaders.gl's
+ *    `Tile3D` retains the raw tile node verbatim on `.header`, and
+ *    `Tileset3D` retains the raw parsed tileset.json on `.tileset`, so this
+ *    reads entirely off already-retained data.
+ */
+interface MetadataEntity {
+    class?: string;
+    properties?: Record<string, unknown>;
+}
+interface GltfPropertyTable {
+    class?: string;
+    count: number;
+    /** Decoded column data. NOT numeric-only — STRING properties decode to `string[]`, which is what most BIM classification fields are. */
+    properties?: Record<string, {
+        data?: ArrayLike<unknown>;
+    }>;
+}
+export interface GltfExtStructuralMetadata {
+    schema?: {
+        classes?: Record<string, {
+            name?: string;
+        }>;
+    };
+    propertyTables?: GltfPropertyTable[];
+}
+interface GltfMeshFeaturesId {
+    attribute?: number;
+    /** Present instead of `attribute` for "feature ID by texture coordinates" sets — see resolvePrimitiveFeatureIdSet. */
+    texture?: {
+        index?: number;
+        texCoord?: number;
+        channels?: number[];
+    };
+    propertyTable?: number;
+    data?: ArrayLike<number>;
+}
+export interface GltfPrimitiveLike {
+    extensions?: {
+        EXT_mesh_features?: {
+            featureIds?: GltfMeshFeaturesId[];
+        };
+    };
+}
+/**
+ * Finds the `EXT_mesh_features` feature-ID set selected by a `_FEATURE_ID_N`
+ * name (the manifest's `feature-id-property`, default `_FEATURE_ID_0`) on one
+ * glTF primitive. Returns null when the primitive carries no usable feature
+ * IDs (a plain, non-BIM mesh — the common case until real IFC-derived content
+ * is loaded).
+ *
+ * `EXT_mesh_features` defines THREE ways to carry feature IDs, and N selects
+ * across all of them:
+ *
+ * - **By vertex** (`attribute: N` -> the `_FEATURE_ID_N` vertex attribute).
+ *   Matched by attribute number first, so an explicitly numbered set always
+ *   wins over its position in the array.
+ * - **By texture** (`texture: {...}`, no `attribute`) — how photogrammetry
+ *   classification datasets carry per-element IDs, since a photogrammetry
+ *   mesh is one triangle soup with the classification painted on. These sets
+ *   have no attribute number to match, so N falls back to selecting the Nth
+ *   entry of the `featureIds` array — the same positional convention the
+ *   extension's own `featureId_N` shader naming uses.
+ * - **By index** (neither field; the vertex's own index is its feature ID).
+ *   loaders.gl leaves `data` empty for these, so they resolve to null here.
+ *
+ * CAVEAT for texture-backed sets: loaders.gl decodes them by sampling the
+ * feature-ID texture once PER VERTEX at that vertex's UV
+ * (`getPrimitiveTextureData`), not per fragment. The resulting IDs are
+ * therefore only as precise as the mesh is dense — a classification boundary
+ * that runs through the middle of a triangle is lost, and that triangle takes
+ * whichever ID its vertices sampled. Good enough to pick an element, not
+ * equivalent to a per-fragment lookup.
+ *
+ * Note both texture and index sets require the glTF to be loaded with
+ * `loadBuffers` (and, for textures, `loadImages`); without them loaders.gl
+ * leaves `data` undefined/empty and this returns null.
+ */
+export declare function resolvePrimitiveFeatureIdSet(primitive: GltfPrimitiveLike | undefined, featureIdProperty: string): {
+    data: ArrayLike<number>;
+    propertyTable?: number;
+    texture?: GltfMeshFeaturesId["texture"];
+    nullFeatureId?: number;
+} | null;
+/**
+ * Reads ONE property of a decoded property table as a column — one entry per
+ * feature ID, indexed by feature ID.
+ *
+ * This is the row-major counterpart to `resolveGltfFeatureRow`: the declarative
+ * `hide-features`/`ghost-features`/`isolate-features` attributes need to test
+ * a single field across EVERY feature at once, and building a full properties
+ * object per row just to read one key would allocate the whole table to answer
+ * a one-column question. Returns null when the table or property is absent.
+ */
+export declare function readPropertyColumn(structuralMetadata: GltfExtStructuralMetadata | undefined, propertyTableIndex: number | undefined, property: string): unknown[] | null;
+/**
+ * The WHOLE property table as row objects, indexed by feature ID.
+ *
+ * Picking resolves one row at a time, which is right for a hover but useless
+ * for anything that needs the set: a legend listing every IfcClass, a category
+ * palette, a model tree. Those previously had to fetch a hand-built sidecar
+ * next to the tileset. This reads the same table the GLB already carries.
+ */
+export declare function extractPropertyTableRows(structuralMetadata: GltfExtStructuralMetadata | undefined, propertyTableIndex: number | undefined): Record<string, unknown>[] | null;
+/**
+ * Resolves one feature's properties out of a specific decoded property
+ * table, by row index — the general case (Phase 2: `rowIndex` is the
+ * per-vertex feature ID; Phase 1's single-feature path below is just this
+ * with `rowIndex = 0` on a `count === 1` table). Returns null for an
+ * out-of-range table/row (defensive — a malformed or partially-loaded tile
+ * should degrade to "no properties," not throw during picking).
+ */
+export declare function resolveGltfFeatureRow(structuralMetadata: GltfExtStructuralMetadata | undefined, propertyTableIndex: number | undefined, rowIndex: number): {
+    properties: Record<string, unknown>;
+    class: string | null;
+} | null;
+export interface Tile3DPickMetadata {
+    /** Merged properties, most-specific source wins: glTF content / legacy batch table > 3D-Tiles content > tile > group > tileset. Empty object if nothing resolved. */
+    properties: Record<string, unknown>;
+    /** The class name of the most specific contributing source, or null if nothing resolved. */
+    class: string | null;
+    /** Best-effort identity (IFC GlobalId / gml:id / guid), or null — see findGuidLike. */
+    guid: string | null;
+    /** Unmerged, per-source view — the escape hatch. Deck.gl/loaders.gl shapes leak here deliberately, unlike `properties`/`class`. */
+    rawMetadata: {
+        tileset?: MetadataEntity;
+        group?: MetadataEntity;
+        tile?: MetadataEntity;
+        content?: MetadataEntity;
+        gltfProperties?: Record<string, unknown>;
+        gltfClass?: string;
+        batchTableProperties?: Record<string, unknown>;
+        batchTableClass?: string;
+    };
+}
+/**
+ * Resolves whatever tile-granularity BIM metadata is available for a
+ * Tile3DLayer pick. `sourceTile` is `PickingInfo.sourceTile` (Tile3DLayer's
+ * own `getPickingInfo` always sets it, undefined for a miss) — callers
+ * should only invoke this once they know the pick landed on a
+ * `carriesTileset` layer. Returns null when nothing resolved (a tileset
+ * with no metadata at all — the common case today, since this is new).
+ */
+export declare function resolveTile3DPickMetadata(sourceTile: unknown): Tile3DPickMetadata | null;
+export {};

package/dist/version.d.ts

@@ -5,4 +5,4 @@
  * the build rootDir, and a `define` would need repeating across vite/vitest/
  * vite-node configs.
  */
-export declare const LIBRARY_VERSION = "0.6.0";
+export declare const LIBRARY_VERSION = "0.6.1";

package/dist/widget-registry.d.ts

@@ -36,6 +36,17 @@ export interface WidgetImpl {
      */
     neverHides?: boolean;
     render(ctx: RuntimeContext, host: WidgetHost): void | Promise<void>;
+    /**
+     * Optional teardown, called by <om-widget> when the element is REMOVED for
+     * real — an author delete, or an SPA unmounting the whole <om-map> — never
+     * on the transient disconnect of a slot/fold/cluster reparent (om-widget
+     * distinguishes the two; see its disconnectedCallback). For releasing
+     * resources the document would otherwise pin past the widget's life: blob
+     * URLs, external listeners, large cached tables held in `host.state`.
+     * May fire again after a re-connect if the widget is removed a second
+     * time, so implementations must tolerate repeat calls.
+     */
+    destroy?(host: WidgetHost): void;
 }
 /** Clusterable (spec: "Widget Layout Manager") — the type is compact AND the author didn't opt out. One predicate for the cluster pass AND the validation lint. */
 export declare function isClusterableWidget(el: Element): boolean;

package/dist/widgets/ifc-clash.d.ts

@@ -0,0 +1,18 @@
+interface ClashItem {
+    id: number;
+    ifcClass: string;
+    name: string;
+    box: number[];
+}
+/** Rows to clash candidates, dropping ignored classes and anything with no real box. */
+export declare function clashCandidates(rows: Record<string, unknown>[]): ClashItem[];
+/**
+ * Axis-aligned overlap, with a tolerance that SHRINKS both boxes.
+ *
+ * The strict comparison matters: two slabs meeting exactly face to face share a
+ * plane, and reporting that would mean every floor clashes with every wall
+ * standing on it. `tolerance` then demands a real interpenetration of that
+ * depth before a pair counts, which is how modelling noise gets tuned out.
+ */
+export declare function boxesOverlap(a: number[], b: number[], tolerance: number): boolean;
+export {};

package/dist/widgets/ifc.d.ts

@@ -0,0 +1,41 @@
+export declare function ensureStyles(root: ShadowRoot): void;
+/** Every `<om-layer pick-features>` on a map — the BIM widgets' shared universe of pickable models. */
+export declare function pickFeatureLayers(map: Element | null | undefined): Element[];
+interface TreeNode {
+    /** Full prefix identifying this node — also its key in the visibility state. */
+    key: string;
+    label: string;
+    count: number;
+    /** Every concrete `spatialPath` value at or below this node. */
+    values: string[];
+    children: Map<string, TreeNode>;
+}
+/**
+ * Distinct spatial paths -> a nested tree, with counts aggregated upward.
+ *
+ * Depth is NOT uniform in real models: the bridge sample mixes 1-level and
+ * 5-level paths in one file, and a model can leave elements with no spatial
+ * container at all (700 of the clinic's 2,626). Both are represented rather
+ * than dropped — an element that vanishes from the tree is an element nobody
+ * can find again.
+ */
+export declare function buildSpatialTree(counts: Map<string, number>): TreeNode;
+/**
+ * Writes an attribute only when it would actually change.
+ *
+ * These widgets re-render on the `layers`/`features` tokens and their writes
+ * mutate layers, so an unconditional write schedules the MutationObserver →
+ * reconcile → full parseManifest pass that produced it — on EVERY render,
+ * even when nothing changed. `setAttribute` notifies observers even when the
+ * value is identical, so equality has to be checked here rather than relied
+ * on.
+ *
+ * It also matters for size: an isolate list or a serialized feature-styles
+ * table spans every element and runs to tens of kilobytes, and re-parsing
+ * that on a loop would be felt.
+ *
+ * Shared with ifc-clash (imported from here — the dependency already flows
+ * that way for ensureStyles/pickFeatureLayers).
+ */
+export declare function setIfChanged(element: Element | null, name: string, value: string | null): void;
+export {};