@nika-js/onlymap 0.6.0 → 0.6.2

package/dist/region-export.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Region 3D export (spec: issue #34 §"Technical Implementation Steps" —
+ * region export; ported from a sibling project's proven implementation
+ * rather than rebuilt from scratch, per direct instruction). Draw a 2D
+ * footprint over loaded 3D Tiles content (BIM/`BIMLayer`, `Tile3DLayer`)
+ * and export exactly the triangles inside it as a portable GLB — or a
+ * b3dm-wrapped GLB for pipelines (Cesium, 3D Tiles tooling) that expect
+ * that container.
+ *
+ * Deliberately simpler than the source implementation in one respect: tile
+ * selection is a plain bbox prefilter (`tileGeoBounds` vs. the ring's own
+ * bbox) rather than the source's mesh-sampling/loose-footprint heuristics —
+ * those exist there to avoid walking every triangle of city-scale national
+ * tilesets before an exact clip; at this library's current single-tileset
+ * (BIM model) scale, bbox-prefilter-then-exact-clip is both simpler and
+ * already correct (a tile outside the ring exact-clips to zero triangles
+ * regardless), and the same geometric pipeline this module already needs
+ * is reused straightforwardly if the heuristic layer becomes worth adding.
+ *
+ * No textures: BIM/IFC materials are flat colors, not textured meshes, so
+ * the UV/image plumbing the source implementation carries is dead weight
+ * here — dropped rather than kept for a case this library doesn't have.
+ * Each triangle's own source color IS carried through, though — baked as
+ * per-vertex `COLOR_0` (see `resolvePrimitiveColor`/`buildGlb`), not left
+ * as an undifferentiated flat gray.
+ *
+ * PURE geometry/binary-writing core (this file) + a thin DOM-touching
+ * driver (`region-export-run.ts`) that resolves the live tileset registry
+ * and triggers the browser download — same split as terrain-sample.ts /
+ * terrain-heightfield.ts.
+ */
+export type LngLatRing = Array<[number, number]>;
+/** Closed (first === last) + CCW — committed draw rings arrive closed, previews open; both normalize the same way. */
+export declare function normalizeRing(ring: LngLatRing): LngLatRing;
+export interface B3dmBatchTable {
+    /** batchLength: number of features encoded in the glb's `_BATCHID`; each property array below must have this length. */
+    batchLength: number;
+    /** Plain-JSON per-feature properties — entry i is feature i's value. Omit for a structurally-valid b3dm with no property data. */
+    properties?: Record<string, unknown[]>;
+}
+export interface RegionExportResult {
+    bytes: Uint8Array;
+    triangleCount: number;
+    format: "glb" | "b3dm";
+}
+/**
+ * Clip every loaded tile's triangles across ALL given tilesets against
+ * `ring`, re-frame the clipped result to a local ENU frame at the ring's
+ * own centroid (portable — most viewers can't display ECEF-scale
+ * coordinates), and pack it as GLB or b3dm. `null` when the ring or the
+ * clip produces nothing (an empty region, or a ring drawn where nothing is
+ * loaded) — the caller reports that distinctly from a thrown error.
+ */
+export declare function computeRegionExport(ring: LngLatRing, tilesets: Map<string, unknown>, options?: {
+    format?: "glb" | "b3dm";
+}): RegionExportResult | null;

package/dist/runtime-core.d.ts

@@ -1,10 +1,30 @@
+import type { PickingInfo } from "@deck.gl/core";
 import { type LightingIR } from "./scene-lighting";
 import { type TerrainIR } from "./terrain";
+import { type ClipBoxIR } from "./clip-box";
+import { type SnapAgent, type SnapConfig } from "./snapping";
 import type { ViewOrigin } from "./external-store";
 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 +45,36 @@ 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;
+/**
+ * The subset of deck.gl's MjolnirGestureEvent a gizmo drag-claim needs (spec:
+ * "Cut/fill volume measurement"). `stopPropagation()` sets the underlying
+ * event's `handled` flag, which `Controller.isPointInBounds` checks before
+ * starting a camera pan — calling it from `onGizmoDragStart` when the gizmo
+ * is the picked layer is what lets a LEFT-button drag on the gizmo win over
+ * the map's own drag-to-pan (deck dispatches its root onDragStart before the
+ * controller's own pan handling for the same gesture, so this is in time).
+ */
+export interface GizmoDragEvent {
+    stopPropagation(): void;
+}
 export interface RuntimeCoreCallbacks {
     /**
      * Fired whenever the view state changes (pan/zoom/pitch/bearing) — a
@@ -34,7 +84,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;
     /**
@@ -44,6 +101,17 @@ export interface RuntimeCoreCallbacks {
      * re-render on every drag-move.
      */
     onDragPick?: (selection: Selection) => void;
+    /**
+     * Raw deck.gl drag lifecycle (spec: "Cut/fill volume measurement"),
+     * forwarded verbatim alongside `onDragPick` — for a controller that owns a
+     * pickable internal layer (the volume tool's height gizmo) and needs the
+     * real `x`/`y`/`viewport`, not a resolved `Selection`. `onDragPick` stays
+     * the mechanism for declarative `on="drag"` behaviors; this is the
+     * mechanism for a controller driving its own layer via patchAnimatedProps.
+     */
+    onGizmoDragStart?: (info: PickingInfo, event: GizmoDragEvent) => void;
+    onGizmoDrag?: (info: PickingInfo) => void;
+    onGizmoDragEnd?: (info: PickingInfo) => void;
     /**
      * Every click/hover's map coordinate (spec: "Manual Drawing"), fired
      * ALONGSIDE onSelectionChange but INCLUDING empty-map events — which
@@ -52,6 +120,31 @@ export interface RuntimeCoreCallbacks {
      * deck reports none (e.g. off-globe).
      */
     onMapPoint?: (coordinate: [number, number] | null, kind: "click" | "hover") => void;
+    /**
+     * XY snapping (spec: issue #34 Part A) — fires ALONGSIDE onMapPoint on
+     * every click/hover, `null` whenever that point ISN'T a snap (no config,
+     * no candidate within tolerance, an opted-out/unsupported layer) — the
+     * snap-tip UI's entire "show only while actually snapped" contract reads
+     * off this being null vs. set, not off onMapPoint's own coordinate.
+     * Carries `position` itself (not just agent/layer) so a consumer never
+     * has to correlate this against a SEPARATE onMapPoint firing in the same
+     * tick to know where to anchor a tip — both already come from the one
+     * `resolveMapPoint` call.
+     */
+    onSnapPoint?: (result: {
+        position: [number, number];
+        agent: SnapAgent;
+        layerId: string;
+        elevation?: number;
+    } | null) => 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 +153,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
@@ -103,6 +220,10 @@ export declare class RuntimeCore {
     private mode;
     /** Layers reconciled while the basemap chunk is still loading — applied on adapter arrival. */
     private pendingLayers?;
+    /** setDrawCapture's last value — composed with dragPanSuppressed by standaloneControllerOverrides. */
+    private drawCaptureActive;
+    /** setDragPan's last value, inverted — see standaloneControllerOverrides. */
+    private dragPanSuppressed;
     /** Retained descriptors — what the per-frame channel re-applies against. */
     private lastIRs;
     /** layerId → effect-driven plain-prop patches (the per-frame channel). */
@@ -136,8 +257,65 @@ export declare class RuntimeCore {
      */
     private terrain;
     private terrainGeneration;
+    /**
+     * Clip box (spec: issue #34 §"Cutting / Clipping") — the retained box IR.
+     * Non-null patches every opted-in layer with `ClipBoxExtension` in
+     * buildLayers (see `applyClipBox`'s own doc comment for the default-
+     * applied, `clip="off"`-to-exclude posture). `clipBoxGeneration` bumps on
+     * every active-state flip, same reason and same fix as terrain's own
+     * generation counter: extension sets must be BIRTH-stable (verified
+     * empirically — a box present from the first render works, toggling one
+     * onto an already-mounted DataFilterExtension-carrying layer silently
+     * blanks it), so patched layers get `#c<generation>`-based deck ids.
+     */
+    private clipBox;
+    private clipBoxGeneration;
+    /** XY snapping (spec: issue #34 Part A) — `null` is the free/common case (no pickingRadius change, resolveMapPoint short-circuits to the plain pick). */
+    private snapConfig;
+    /** See resolveMapPoint's memo comment — the last picked object's derived snap geometry. */
+    private snapGeometryMemo;
+    /** See pickForSnap's memo comment — the non-terrain layer-id list, keyed by the deck layer array's own identity. */
+    private snapLayerIdsMemo;
+    /** Spacebar-held suppression (spec: issue #34 Part A) — deliberately leaves `pickingRadius`/`snapConfig` untouched, only gates `resolveMapPoint`'s refinement step, since the underlying pick tolerance isn't what a user means by "hold to disable snapping momentarily." */
+    private snapSuppressed;
+    /** Per-BIMLayer lonLat/heading/scale, captured off `onGeoreference` (see `BimGeoreferenceInfo`) — `resolveMapPoint`'s only way to convert a picked EdgeRow's raw local vertices back to real `[lng, lat]` for snapping, since that georeference otherwise lives entirely inside BIMLayer's own async load state. */
+    private bimGeoreference;
     /** 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
@@ -192,6 +370,72 @@ export declare class RuntimeCore {
      */
     setTerrain(ir: TerrainIR | null): void;
     getTerrainInternal(): TerrainIR | null;
+    /** Clip box on/off/extent change (spec: issue #34) — no basemap-replacement dance like terrain's (a clip box never changes render mode), just a straight re-apply. Bumps the generation on an active-state flip (fresh deck ids — see the `clipBoxGeneration` field doc). */
+    setClipBox(ir: ClipBoxIR | null): void;
+    getClipBoxInternal(): ClipBoxIR | null;
+    /**
+     * XY snapping on/off + tolerance change (spec: issue #34 Part A). Unlike
+     * clip box/terrain, this never touches the layer list — only deck's
+     * `pickingRadius` (0 by default and never otherwise set in this
+     * codebase; without it a cursor has to land EXACTLY on rendered pixels
+     * to pick anything, which defeats snapping's own point of "near enough
+     * counts") and `resolveMapPoint`'s own read of `this.snapConfig` on the
+     * next pick — no `applyLayers()` needed.
+     */
+    /** Spacebar held/released (spec: issue #34 Part A) — no-op when snapping isn't configured at all. */
+    setSnapSuppressed(suppressed: boolean): void;
+    /**
+     * Whether a snap resolver is actually configured — the ONLY condition under
+     * which om-map's window-level keydown listener may `preventDefault()` the
+     * spacebar. Without this gate, every page embedding an `<om-map>` lost
+     * space-to-scroll and space-to-activate-a-focused-button, snapping
+     * configured or not (`setSnapSuppressed` no-ops in that case, but
+     * `preventDefault` does not).
+     */
+    hasSnapConfig(): boolean;
+    setSnapConfig(config: SnapConfig | null): void;
+    /**
+     * `coordOf` plus snap refinement — the two-stage resolver (see
+     * src/snapping.ts's own header comment): a pick (stage 1) tells us which
+     * feature + viewport are under the cursor; `resolveSnap` (stage 2)
+     * refines that to the nearest vertex/edge/midpoint. Falls back to the
+     * plain pick on no config, no layer/viewport (an empty-map pick), a
+     * `snap="off"` layer, or no candidate within tolerance — `resolveSnap`'s
+     * own `null` covers the last case AND "geometry shape this module
+     * doesn't understand" (e.g. a raw meter-offsets PathLayer row)
+     * identically, which is the right behavior either way: nothing to add,
+     * use the raw pick.
+     *
+     * Stage 1 does NOT simply reuse `info` (deck's own top-level pick that
+     * already drove `onMapPoint`/`onSelectionChange`) whenever terrain is
+     * active — confirmed live, terrain wins deck's pick-buffer resolution
+     * against ANY co-located pickable content, vector or BIM mesh alike,
+     * even where that content visibly, correctly renders on top of it (the
+     * SAME finding already documented on this session's z-tooltip work, one
+     * layer up: there it was worked around with an unscoped hover behavior;
+     * here, where snapping specifically needs to know WHICH non-terrain
+     * feature is under the cursor, that workaround doesn't apply). Instead,
+     * re-picks explicitly via `deck.pickObject`, `layerIds`-restricted to
+     * everything EXCEPT the terrain layer — deliberately narrow (standalone
+     * mode only, terrain's own required mode) rather than a general-purpose
+     * picking API this codebase otherwise avoids.
+     */
+    private resolveMapPoint;
+    /**
+     * See `resolveMapPoint`'s own doc comment for why this re-picks rather than
+     * reusing deck's own top-level `info`. `radius` mirrors the configured
+     * tolerance — a vertex sitting outside the tolerance couldn't win anyway,
+     * and this keeps the explicit re-pick's own search window consistent with
+     * the resolver's.
+     *
+     * The `layerIds` list is memoized against the layer ARRAY's identity: this
+     * runs on every pointer move while snapping is on, and deck only hands out
+     * a new array when the layer set actually changes, so the filter+map runs
+     * per layer-set change instead of per mousemove. (The `pickObject` call
+     * itself is a synchronous GPU readback and remains the real cost here —
+     * this just stops adding avoidable per-move allocation on top of it.)
+     */
+    private pickForSnap;
     private drainSnapshotCaptures;
     /** Settle queued snapshot promises when the renderer they were waiting on goes away (mode flip / destroy) — never leave a caller hanging. */
     private cancelSnapshotCaptures;
@@ -259,7 +503,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,
@@ -269,6 +513,20 @@ export declare class RuntimeCore {
      * fight drag-pan, so pan stays live.
      */
     setDrawCapture(active: boolean): void;
+    /**
+     * Suspend/restore drag-to-pan while a gizmo is grabbed — otherwise a drag
+     * on the gizmo also pans the camera underneath it. Originally standalone-
+     * only (the volume tool's own height gizmo requires terrain, which always
+     * forces standalone mode — see setTerrain — so it never hit basemap mode
+     * in practice); the clip-box face-handle gizmo (issue #34) has no such
+     * precondition and runs fine with a plain basemap, which surfaced the gap
+     * for real (reported: dragging a handle panned the map underneath it and
+     * the two fighting over every mousemove read as the whole page hanging).
+     * `basemap.setInteractive` is the SAME mechanism setDrawCapture already
+     * uses for doubleClickZoom, just a different MapLibre gesture handler.
+     */
+    setDragPan(active: boolean): void;
+    private standaloneControllerOverrides;
     /**
      * Used by the built-in `zoom-controls` widget's emitted zoom-in/zoom-out
      * intents. Programmatic, so — unlike a user drag/scroll — standalone mode
@@ -305,4 +563,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;
@@ -13,9 +14,44 @@ export interface Selection {
      * onSelectionChange), so downstream consumers still always see an object.
      */
     index: number;
-    coordinate: [number, number] | null;
+    /**
+     * `[lng, lat]`, or `[lng, lat, z]` when deck actually ran the depth-pick
+     * pass for this pick (some pickable layer in the scene has `pickable:
+     * '3d'` — see terrain.ts and BIMLayer's own hover picking). Without that
+     * pass deck's `info.coordinate` is the ray∩z=0-plane intersection, not a
+     * real surface point, so a 2-length coordinate here is not "z=0 at this
+     * point" — it's "no z was ever computed," and callers (the hover-tooltip
+     * z field, this session's own concrete use) must treat it as absent, not
+     * zero.
+     */
+    coordinate: [number, number] | [number, 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 +62,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,107 @@
+/**
+ * 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;
+/**
+ * Companion to `localPlacementMatrix` + `coordinateOrigin` (the outline
+ * overlay's own placement, see this file's header comment) — converts ONE
+ * RAW local vertex (an `EdgeRow.path` point, in the model's own pre-
+ * transform local frame — the exact same value `getPath` hands the
+ * PathLayer) to real `[lng, lat]`, the SAME two steps deck.gl itself
+ * applies to render that vertex on screen: `localPlacementMatrix`'s
+ * `scale * Rz(-heading)` first, THEN interpret the result as an east/north
+ * metre offset from `coordinateOrigin`. Needed for XY snapping (spec:
+ * issue #34 Part A) against the BIM edges overlay specifically: its picked
+ * rows carry this raw local form, not GeoJSON, so `snapping.ts`'s
+ * resolver — which only understands `[lng, lat]` — cannot search them
+ * directly without this.
+ *
+ * The metres-to-degrees step is the standard small-area linear
+ * approximation (matches `getDistanceScales` inside
+ * `@math.gl/web-mercator`, which is what ACTUALLY renders this exact
+ * vertex on screen today — deliberately consistent with that real
+ * projection rather than a more "correct" ellipsoidal model that would
+ * silently disagree with it).
+ */
+export declare function localOffsetToLngLat(local: readonly [number, number], origin: readonly [number, number], heading: number, scale: number): [number, number];
+/**
+ * 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;