@seatlayer/core 0.96.0 → 0.98.0

package/dist/view3d/index.d.cts

@@ -1,6 +1,7 @@
-import { C as ChartDoc } from '../types-BbqhOJ5L.cjs';
+import { P as Point, C as ChartDoc } from '../types-BbqhOJ5L.cjs';
 import { E as EventConfigurationProductionElementKind, a as EventConfigurationOcclusion, b as EventConfigurationVersion } from '../eventConfigurations-BE0rFmbQ.cjs';
 import { E as ExpandedSeat } from '../renderer-DEnthjgs.cjs';
+import { S as StageKind } from '../stage-CKb7aNoH.cjs';
 import { SeatView } from './crossfade/panorama.cjs';
 
 /**
@@ -47,6 +48,55 @@ declare const STRUCTURE: {
     readonly tableWall: RGB;
 };
 
+/**
+ * Pure geometry primitives for the view3d scene — no OGL, no DOM, so the whole
+ * scene-model builder is unit-testable in a plain runtime.
+ *
+ * Coordinate convention: chart units (x, y) map to world metres as
+ *   worldX = x * METRES_PER_CHART_UNIT
+ *   worldZ = y * METRES_PER_CHART_UNIT
+ *   worldY = up (height in metres)
+ * i.e. the chart's audience-depth (+y) becomes world +Z, and Y is the vertical.
+ */
+
+interface MeshData {
+    /** Non-indexed triangle soup: 3 floats per vertex. */
+    position: Float32Array;
+    normal: Float32Array;
+    /** Baked vertex colour incl. AO, 3 floats per vertex. */
+    color: Float32Array;
+    /**
+     * Owning floor index per vertex.
+     *
+     * Lets one merged mesh be dimmed per floor without splitting it into a draw
+     * call per floor. A multi-floor chart (the opera house has three) draws every
+     * floor at once, so the balcony sits over the parterre and hides it; isolating
+     * one is the only way to look at the level you are actually booking.
+     */
+    floor: Float32Array;
+    /**
+     * Small renderer material class per vertex:
+     * 0 = ordinary structure, 1 = authored powered display,
+     * 2 = row riser, 3 = row tread, 4 = football turf, 5 = generated concrete.
+     */
+    material: Float32Array;
+    /** Vertex count (position.length / 3). */
+    count: number;
+}
+
+interface SharedAisleCandidate {
+    sections: [string, string];
+    /** Block IDs are local to each section, paired in the same endpoint order. */
+    blocks?: [number, number];
+    floorIndex: number;
+    ends: [Point, Point];
+    /** Same-level clear width after reserving furniture space at both ends. */
+    clearWidthM: number;
+    heightM: number;
+    /** Chart-space footprint; a proposal, not an authored circulation route. */
+    outline: Point[];
+}
+
 /**
  * Resolve a chart's authored theme into the 3D scene's colours.
  *
@@ -124,46 +174,16 @@ interface SceneLabel {
     anchor: [number, number, number];
     /** Authored colour (`#rrggbb`), when the object carries one. */
     color?: string;
+    /** Physical chair width, used to reveal numbers only at readable scale. */
+    seatWidthM?: number;
     /** Authored rotation in degrees, for annotations that specify one. */
     rotation?: number;
     /** Owning physical level, so a focused floor never keeps another level's text. */
     floorIndex?: number;
-}
-
-/**
- * Pure geometry primitives for the view3d scene — no OGL, no DOM, so the whole
- * scene-model builder is unit-testable in a plain runtime.
- *
- * Coordinate convention: chart units (x, y) map to world metres as
- *   worldX = x * METRES_PER_CHART_UNIT
- *   worldZ = y * METRES_PER_CHART_UNIT
- *   worldY = up (height in metres)
- * i.e. the chart's audience-depth (+y) becomes world +Z, and Y is the vertical.
- */
-
-interface MeshData {
-    /** Non-indexed triangle soup: 3 floats per vertex. */
-    position: Float32Array;
-    normal: Float32Array;
-    /** Baked vertex colour incl. AO, 3 floats per vertex. */
-    color: Float32Array;
-    /**
-     * Owning floor index per vertex.
-     *
-     * Lets one merged mesh be dimmed per floor without splitting it into a draw
-     * call per floor. A multi-floor chart (the opera house has three) draws every
-     * floor at once, so the balcony sits over the parterre and hides it; isolating
-     * one is the only way to look at the level you are actually booking.
-     */
-    floor: Float32Array;
-    /**
-     * Small renderer material class per vertex:
-     * 0 = ordinary structure, 1 = authored powered display,
-     * 2 = row riser, 3 = row tread.
-     */
-    material: Float32Array;
-    /** Vertex count (position.length / 3). */
-    count: number;
+    /** A picked seat's pin base (scene/seatPin): its tag rides the pin's stem. */
+    pinBase?: [number, number, number];
+    /** A seat label's row, so the row under the pointer can show its numbers. */
+    rowId?: string;
 }
 
 /**
@@ -216,6 +236,8 @@ interface SeatInstanceData {
     iRing: Float32Array;
     /** float per instance: owning floor index, for per-floor isolation. */
     iFloor: Float32Array;
+    /** float per instance: owning section's index in SceneModel.sections, -1 = none. */
+    iSection: Float32Array;
     /**
      * float per instance: facing yaw in radians, for the near-field chair mesh.
      *
@@ -313,6 +335,11 @@ interface SceneSection {
     center: [number, number, number];
     /** Half-diagonal of its seat footprint, world metres (camera fit). */
     radius: number;
+    /** Seat envelope including furniture height, used for projected camera fitting. */
+    box?: {
+        min: [number, number, number];
+        max: [number, number, number];
+    };
     /** What this section faces — the camera approaches from this side. */
     focalWorld: [number, number, number];
 }
@@ -350,6 +377,8 @@ interface SectionSolidRange {
     count: number;
 }
 interface SceneModel {
+    /** Geometric proposals only; not verified routes or rendered architecture. */
+    sharedAisles?: SharedAisleCandidate[];
     /** Every non-seat surface merged into one triangle soup (1 draw call). */
     solids: MeshData;
     /**
@@ -362,6 +391,8 @@ interface SceneModel {
      */
     sectionSolidRanges: SectionSolidRange[];
     seats: SeatInstanceData;
+    /** Physical section ownership in input-seat order; absent on older prepared models. */
+    seatSectionIds?: Array<string | null>;
     bounds: {
         /** World-metre venue centre (camera target). */
         center: [number, number, number];
@@ -385,6 +416,12 @@ interface SceneModel {
         center: [number, number, number];
         radius: number;
     };
+    /** Everything drawn, including the site around the venue: camera clipping
+     * only. Absent on models built before the site existed. */
+    clipBounds?: {
+        center: [number, number, number];
+        radius: number;
+    };
     /** 5 × vec3 flat LUT for the seat fragment shader. */
     stateColorLUT: number[];
     /** Resolved colours for this chart's authored theme (background, seat scale). */
@@ -438,33 +475,6 @@ interface SceneModelInput {
     initialState?: (seat: ExpandedSeat) => SeatState3D;
 }
 
-/**
- * The JS-side source of truth for the 3D scene — a pure, GPU-free description
- * built once from the chart's existing height contract. Everything the renderer
- * uploads (merged solid geometry, the instanced seat cloud, camera-framing
- * bounds, the seat-state colour LUT) is derived here, so it survives a WebGL
- * context loss: on `webglcontextrestored` the renderer simply re-uploads from
- * this model without recomputing anything.
- *
- * Feeds 100% from `sectionGeometry` / `Floor.baseHeightM` / `ExpandedSeat`
- * (docs/3d-program-workorder §Architecture) — no new chart data is invented.
- *
- * This module is the ORCHESTRATOR and the public face of `scene/model/`: it
- * sequences the passes and re-exports every type and helper the rest of the
- * codebase, the tests and the SDK import from `scene/sceneModel`. The passes
- * themselves live in `scene/model/` — see `docs/architecture` for the layering:
- *
- *   types            the shapes everything below is described in
- *   paint            AO + how an authored colour becomes an architectural tone
- *   footprints       configuration filtering, floor units, plan-space polygons
- *   shapeArchitecture décor vocabulary → architecture, and coplanar claims
- *   objectBuilders   one prism per booth / table / shape / décor / GA area
- *   tiers            per-section decks and the per-floor bowl
- *   labels           zones, sections, rows and everything worth naming
- *   floors           per-level boxes, and the per-seat floor attribute
- *   bounds           chart footprint, ground datum, render + overview volumes
- */
-
 declare function buildSceneModel(input: SceneModelInput): SceneModel;
 
 /**
@@ -487,12 +497,77 @@ type Analytics3DCallback = (event: string, props?: Record<string, unknown>) => v
  */
 type Scene3DPrepSource = 'worker' | 'main' | 'inline';
 
+interface AutoVenueSection {
+    id: string;
+    /** Owning floor on a multi-floor chart. */
+    floorId?: string;
+    /** Surface the estimate implies: stepped rows, or a level deck. */
+    surfaceKind: 'flat' | 'rakedRows';
+    height: number;
+    rake: number;
+    /** Section this one continues from, when it stands behind another. */
+    stackedOn?: string;
+}
+interface AutoVenueReport {
+    /** Shape id treated as the stage and whether that was inferred; `deck`
+     * when an unmarked shape was given the stage role. */
+    stage?: {
+        id: string;
+        inferred: boolean;
+        floorId?: string;
+        deck?: boolean;
+        field?: StageKind;
+    };
+    focalInferred: boolean;
+    /** The facing point each floor was given, where it was moved to the stage. */
+    focal?: {
+        floorId?: string;
+        point: Point;
+    }[];
+    /**
+     * The estimate knows what the audience looks at: a stage (drawn or found)
+     * or a focal point the organizer placed. Without either, heights are a
+     * guess and buyers keep the flat venue.
+     */
+    confident: boolean;
+    sections: AutoVenueSection[];
+    /** Free-standing row blocks given a hidden section in the 3D copy only. */
+    looseRowBlocks?: number;
+    /** The chart's drawn walls enclose its seating: tiers were raked as a hall's. */
+    indoor?: boolean;
+    /** Plain shapes given the role their label names (a Bar, the WC, a Screen). */
+    roles?: {
+        id: string;
+        floorId?: string;
+        role: string;
+    }[];
+}
+/** Derive a 3D-ready copy of `doc`; see the module comment for the rules. */
+declare function autoVenue3d(doc: ChartDoc, defaultFocal?: Point): {
+    doc: ChartDoc;
+    report: AutoVenueReport;
+};
+
+interface EstimatedVenue3D {
+    doc: ChartDoc;
+    report: AutoVenueReport;
+    /** Per seat, in input order: eye height (NaN = unset). */
+    eyeHeightM: Float64Array;
+    /** Per seat, in input order: facing point x, y (NaN = unset). */
+    focal: Float64Array;
+}
+/** The estimate to render for `doc`, or null to render the chart as saved. */
+declare function estimateVenue3D(doc: ChartDoc, seats: readonly ExpandedSeat[]): EstimatedVenue3D | null;
+
 interface PreparedVenue3D {
     model: SceneModel;
     buildMs: number;
     /** Reported on `3d_opened` as `prepSource`. `inline` is not reachable here —
      * it is what `mountVenue3D` reports when no prepared scene was handed in. */
     source: Exclude<Scene3DPrepSource, 'inline'>;
+    /** The estimated venue the model was built from; `mountVenue3D` mounts it
+     * in place of the saved chart, with each seat's eye height and facing point. */
+    estimate?: EstimatedVenue3D;
 }
 interface PrepareVenue3DInput {
     doc: ChartDoc;
@@ -501,6 +576,8 @@ interface PrepareVenue3DInput {
     /** Exact content delivered only with the lazy 3D request. */
     eventConfiguration?: EventConfigurationVersion;
     registeredShellGlb?: ArrayBuffer;
+    /** False renders the chart exactly as saved, with no estimated heights. */
+    estimate?: boolean;
 }
 type PrepareVenue3DFromChartInput = Omit<PrepareVenue3DInput, 'seats'>;
 /** Designer-friendly result: expansion and scene compilation both happened
@@ -706,6 +783,9 @@ interface Venue3DInput {
     initialState?: (seat: ExpandedSeat) => SeatState3D;
     /** CPU scene prepared by `prepareVenue3D`; avoids rebuilding on mount. */
     prepared?: PreparedVenue3D;
+    /** False renders the chart exactly as saved, with no estimated heights.
+     * Ignored with `prepared`, which already made that choice. */
+    estimate?: boolean;
 }
 interface Venue3DOptions {
     /** Fired on a tap that hits a seat (GPU color-pick). Not fired on empty taps. */
@@ -795,6 +875,8 @@ interface Venue3DOptions {
      * contain framing; validated for the buyer across `/dev/3d` fixtures.
      */
     portraitOverviewCrop?: boolean;
+    /** Optional authored presentation angle; stage-derived orientation otherwise wins. */
+    overviewAzimuthDeg?: number;
     /** Start on the final overview pose without the decorative stand-up intro.
      * Intended for deterministic rendered review and screenshot capture. */
     skipInitialOverviewAnimation?: boolean;
@@ -824,6 +906,8 @@ interface Venue3DOptions {
 
 interface Venue3DStats extends RenderLoopStats {
     drawCalls: number;
+    /** Submitted fallback triangles, including collapsed bays; excludes near chairs. */
+    fallbackTriangles?: number;
     seatCount: number;
 }
 interface Venue3DHandle {
@@ -861,6 +945,9 @@ interface Venue3DHandle {
     resize(): void;
     stats(): Venue3DStats;
     /** Machine-readable evidence from the exact parked WebGL frame and DOM labels. */
+    /** The current view as a JPEG data URL, longest edge at most `maxEdge` px
+     *  (default 1280); null when the GPU context is gone. */
+    captureImage(maxEdge?: number): string | null;
     getQualityEvidence(): Venue3DQualityEvidence;
     getQualityReport(): Venue3DQualityReport;
     loseContextForTest(): void;
@@ -909,19 +996,6 @@ interface Venue3DHandle {
     focusFloor(index: number | null): boolean;
 }
 
-/**
- * view3d — the sole dynamic-import boundary for the lazy OGL venue-view chunk.
- *
- *   const { mountVenue3D } = await import('../view3d');
- *   const handle = mountVenue3D(container, { doc, seats }, { onSeatPick, getSeatView });
- *   await handle.flyToSeat(seatId);
- *
- * Read-only 3D of any chart, fed entirely from the existing height contract.
- * Slice 1: orbit camera, extruded tiers/stage/GA, instanced seat dots, sub-range
- * availability, dispose + context-loss survival. Slice 2: GPU color-pick. Slice
- * 3: the fly-to-seat cinematic that dissolves into the view-from-seat panorama.
- */
-
 declare function mountVenue3D(container: HTMLElement, input: Venue3DInput, opts?: Venue3DOptions): Venue3DHandle;
 
-export { type Analytics3DCallback, type PreparedVenue3D, type PreparedVenue3DFromChart, type Scene3DPrepSource, type SeatState3D, SeatView, type SeatViewStopName, VENUE3D_QUALITY_REPORT_VERSION, type Venue3DHandle, type Venue3DInput, type Venue3DOptions, type Venue3DQualityEvidence, type Venue3DQualityReport, type Venue3DStats, buildSceneModel, inspectVenue3DQualityEvidence, mountVenue3D, prepareVenue3D, prepareVenue3DFromChart };
+export { type Analytics3DCallback, type AutoVenueReport, type PreparedVenue3D, type PreparedVenue3DFromChart, type Scene3DPrepSource, type SeatState3D, SeatView, type SeatViewStopName, VENUE3D_QUALITY_REPORT_VERSION, type Venue3DHandle, type Venue3DInput, type Venue3DOptions, type Venue3DQualityEvidence, type Venue3DQualityReport, type Venue3DStats, autoVenue3d, buildSceneModel, estimateVenue3D, inspectVenue3DQualityEvidence, mountVenue3D, prepareVenue3D, prepareVenue3DFromChart };

package/dist/view3d/index.d.ts

@@ -1,6 +1,7 @@
-import { C as ChartDoc } from '../types-BbqhOJ5L.js';
+import { P as Point, C as ChartDoc } from '../types-BbqhOJ5L.js';
 import { E as EventConfigurationProductionElementKind, a as EventConfigurationOcclusion, b as EventConfigurationVersion } from '../eventConfigurations-BEyHDxBT.js';
 import { E as ExpandedSeat } from '../renderer-CuXYGgR3.js';
+import { S as StageKind } from '../stage-CKb7aNoH.js';
 import { SeatView } from './crossfade/panorama.js';
 
 /**
@@ -47,6 +48,55 @@ declare const STRUCTURE: {
     readonly tableWall: RGB;
 };
 
+/**
+ * Pure geometry primitives for the view3d scene — no OGL, no DOM, so the whole
+ * scene-model builder is unit-testable in a plain runtime.
+ *
+ * Coordinate convention: chart units (x, y) map to world metres as
+ *   worldX = x * METRES_PER_CHART_UNIT
+ *   worldZ = y * METRES_PER_CHART_UNIT
+ *   worldY = up (height in metres)
+ * i.e. the chart's audience-depth (+y) becomes world +Z, and Y is the vertical.
+ */
+
+interface MeshData {
+    /** Non-indexed triangle soup: 3 floats per vertex. */
+    position: Float32Array;
+    normal: Float32Array;
+    /** Baked vertex colour incl. AO, 3 floats per vertex. */
+    color: Float32Array;
+    /**
+     * Owning floor index per vertex.
+     *
+     * Lets one merged mesh be dimmed per floor without splitting it into a draw
+     * call per floor. A multi-floor chart (the opera house has three) draws every
+     * floor at once, so the balcony sits over the parterre and hides it; isolating
+     * one is the only way to look at the level you are actually booking.
+     */
+    floor: Float32Array;
+    /**
+     * Small renderer material class per vertex:
+     * 0 = ordinary structure, 1 = authored powered display,
+     * 2 = row riser, 3 = row tread, 4 = football turf, 5 = generated concrete.
+     */
+    material: Float32Array;
+    /** Vertex count (position.length / 3). */
+    count: number;
+}
+
+interface SharedAisleCandidate {
+    sections: [string, string];
+    /** Block IDs are local to each section, paired in the same endpoint order. */
+    blocks?: [number, number];
+    floorIndex: number;
+    ends: [Point, Point];
+    /** Same-level clear width after reserving furniture space at both ends. */
+    clearWidthM: number;
+    heightM: number;
+    /** Chart-space footprint; a proposal, not an authored circulation route. */
+    outline: Point[];
+}
+
 /**
  * Resolve a chart's authored theme into the 3D scene's colours.
  *
@@ -124,46 +174,16 @@ interface SceneLabel {
     anchor: [number, number, number];
     /** Authored colour (`#rrggbb`), when the object carries one. */
     color?: string;
+    /** Physical chair width, used to reveal numbers only at readable scale. */
+    seatWidthM?: number;
     /** Authored rotation in degrees, for annotations that specify one. */
     rotation?: number;
     /** Owning physical level, so a focused floor never keeps another level's text. */
     floorIndex?: number;
-}
-
-/**
- * Pure geometry primitives for the view3d scene — no OGL, no DOM, so the whole
- * scene-model builder is unit-testable in a plain runtime.
- *
- * Coordinate convention: chart units (x, y) map to world metres as
- *   worldX = x * METRES_PER_CHART_UNIT
- *   worldZ = y * METRES_PER_CHART_UNIT
- *   worldY = up (height in metres)
- * i.e. the chart's audience-depth (+y) becomes world +Z, and Y is the vertical.
- */
-
-interface MeshData {
-    /** Non-indexed triangle soup: 3 floats per vertex. */
-    position: Float32Array;
-    normal: Float32Array;
-    /** Baked vertex colour incl. AO, 3 floats per vertex. */
-    color: Float32Array;
-    /**
-     * Owning floor index per vertex.
-     *
-     * Lets one merged mesh be dimmed per floor without splitting it into a draw
-     * call per floor. A multi-floor chart (the opera house has three) draws every
-     * floor at once, so the balcony sits over the parterre and hides it; isolating
-     * one is the only way to look at the level you are actually booking.
-     */
-    floor: Float32Array;
-    /**
-     * Small renderer material class per vertex:
-     * 0 = ordinary structure, 1 = authored powered display,
-     * 2 = row riser, 3 = row tread.
-     */
-    material: Float32Array;
-    /** Vertex count (position.length / 3). */
-    count: number;
+    /** A picked seat's pin base (scene/seatPin): its tag rides the pin's stem. */
+    pinBase?: [number, number, number];
+    /** A seat label's row, so the row under the pointer can show its numbers. */
+    rowId?: string;
 }
 
 /**
@@ -216,6 +236,8 @@ interface SeatInstanceData {
     iRing: Float32Array;
     /** float per instance: owning floor index, for per-floor isolation. */
     iFloor: Float32Array;
+    /** float per instance: owning section's index in SceneModel.sections, -1 = none. */
+    iSection: Float32Array;
     /**
      * float per instance: facing yaw in radians, for the near-field chair mesh.
      *
@@ -313,6 +335,11 @@ interface SceneSection {
     center: [number, number, number];
     /** Half-diagonal of its seat footprint, world metres (camera fit). */
     radius: number;
+    /** Seat envelope including furniture height, used for projected camera fitting. */
+    box?: {
+        min: [number, number, number];
+        max: [number, number, number];
+    };
     /** What this section faces — the camera approaches from this side. */
     focalWorld: [number, number, number];
 }
@@ -350,6 +377,8 @@ interface SectionSolidRange {
     count: number;
 }
 interface SceneModel {
+    /** Geometric proposals only; not verified routes or rendered architecture. */
+    sharedAisles?: SharedAisleCandidate[];
     /** Every non-seat surface merged into one triangle soup (1 draw call). */
     solids: MeshData;
     /**
@@ -362,6 +391,8 @@ interface SceneModel {
      */
     sectionSolidRanges: SectionSolidRange[];
     seats: SeatInstanceData;
+    /** Physical section ownership in input-seat order; absent on older prepared models. */
+    seatSectionIds?: Array<string | null>;
     bounds: {
         /** World-metre venue centre (camera target). */
         center: [number, number, number];
@@ -385,6 +416,12 @@ interface SceneModel {
         center: [number, number, number];
         radius: number;
     };
+    /** Everything drawn, including the site around the venue: camera clipping
+     * only. Absent on models built before the site existed. */
+    clipBounds?: {
+        center: [number, number, number];
+        radius: number;
+    };
     /** 5 × vec3 flat LUT for the seat fragment shader. */
     stateColorLUT: number[];
     /** Resolved colours for this chart's authored theme (background, seat scale). */
@@ -438,33 +475,6 @@ interface SceneModelInput {
     initialState?: (seat: ExpandedSeat) => SeatState3D;
 }
 
-/**
- * The JS-side source of truth for the 3D scene — a pure, GPU-free description
- * built once from the chart's existing height contract. Everything the renderer
- * uploads (merged solid geometry, the instanced seat cloud, camera-framing
- * bounds, the seat-state colour LUT) is derived here, so it survives a WebGL
- * context loss: on `webglcontextrestored` the renderer simply re-uploads from
- * this model without recomputing anything.
- *
- * Feeds 100% from `sectionGeometry` / `Floor.baseHeightM` / `ExpandedSeat`
- * (docs/3d-program-workorder §Architecture) — no new chart data is invented.
- *
- * This module is the ORCHESTRATOR and the public face of `scene/model/`: it
- * sequences the passes and re-exports every type and helper the rest of the
- * codebase, the tests and the SDK import from `scene/sceneModel`. The passes
- * themselves live in `scene/model/` — see `docs/architecture` for the layering:
- *
- *   types            the shapes everything below is described in
- *   paint            AO + how an authored colour becomes an architectural tone
- *   footprints       configuration filtering, floor units, plan-space polygons
- *   shapeArchitecture décor vocabulary → architecture, and coplanar claims
- *   objectBuilders   one prism per booth / table / shape / décor / GA area
- *   tiers            per-section decks and the per-floor bowl
- *   labels           zones, sections, rows and everything worth naming
- *   floors           per-level boxes, and the per-seat floor attribute
- *   bounds           chart footprint, ground datum, render + overview volumes
- */
-
 declare function buildSceneModel(input: SceneModelInput): SceneModel;
 
 /**
@@ -487,12 +497,77 @@ type Analytics3DCallback = (event: string, props?: Record<string, unknown>) => v
  */
 type Scene3DPrepSource = 'worker' | 'main' | 'inline';
 
+interface AutoVenueSection {
+    id: string;
+    /** Owning floor on a multi-floor chart. */
+    floorId?: string;
+    /** Surface the estimate implies: stepped rows, or a level deck. */
+    surfaceKind: 'flat' | 'rakedRows';
+    height: number;
+    rake: number;
+    /** Section this one continues from, when it stands behind another. */
+    stackedOn?: string;
+}
+interface AutoVenueReport {
+    /** Shape id treated as the stage and whether that was inferred; `deck`
+     * when an unmarked shape was given the stage role. */
+    stage?: {
+        id: string;
+        inferred: boolean;
+        floorId?: string;
+        deck?: boolean;
+        field?: StageKind;
+    };
+    focalInferred: boolean;
+    /** The facing point each floor was given, where it was moved to the stage. */
+    focal?: {
+        floorId?: string;
+        point: Point;
+    }[];
+    /**
+     * The estimate knows what the audience looks at: a stage (drawn or found)
+     * or a focal point the organizer placed. Without either, heights are a
+     * guess and buyers keep the flat venue.
+     */
+    confident: boolean;
+    sections: AutoVenueSection[];
+    /** Free-standing row blocks given a hidden section in the 3D copy only. */
+    looseRowBlocks?: number;
+    /** The chart's drawn walls enclose its seating: tiers were raked as a hall's. */
+    indoor?: boolean;
+    /** Plain shapes given the role their label names (a Bar, the WC, a Screen). */
+    roles?: {
+        id: string;
+        floorId?: string;
+        role: string;
+    }[];
+}
+/** Derive a 3D-ready copy of `doc`; see the module comment for the rules. */
+declare function autoVenue3d(doc: ChartDoc, defaultFocal?: Point): {
+    doc: ChartDoc;
+    report: AutoVenueReport;
+};
+
+interface EstimatedVenue3D {
+    doc: ChartDoc;
+    report: AutoVenueReport;
+    /** Per seat, in input order: eye height (NaN = unset). */
+    eyeHeightM: Float64Array;
+    /** Per seat, in input order: facing point x, y (NaN = unset). */
+    focal: Float64Array;
+}
+/** The estimate to render for `doc`, or null to render the chart as saved. */
+declare function estimateVenue3D(doc: ChartDoc, seats: readonly ExpandedSeat[]): EstimatedVenue3D | null;
+
 interface PreparedVenue3D {
     model: SceneModel;
     buildMs: number;
     /** Reported on `3d_opened` as `prepSource`. `inline` is not reachable here —
      * it is what `mountVenue3D` reports when no prepared scene was handed in. */
     source: Exclude<Scene3DPrepSource, 'inline'>;
+    /** The estimated venue the model was built from; `mountVenue3D` mounts it
+     * in place of the saved chart, with each seat's eye height and facing point. */
+    estimate?: EstimatedVenue3D;
 }
 interface PrepareVenue3DInput {
     doc: ChartDoc;
@@ -501,6 +576,8 @@ interface PrepareVenue3DInput {
     /** Exact content delivered only with the lazy 3D request. */
     eventConfiguration?: EventConfigurationVersion;
     registeredShellGlb?: ArrayBuffer;
+    /** False renders the chart exactly as saved, with no estimated heights. */
+    estimate?: boolean;
 }
 type PrepareVenue3DFromChartInput = Omit<PrepareVenue3DInput, 'seats'>;
 /** Designer-friendly result: expansion and scene compilation both happened
@@ -706,6 +783,9 @@ interface Venue3DInput {
     initialState?: (seat: ExpandedSeat) => SeatState3D;
     /** CPU scene prepared by `prepareVenue3D`; avoids rebuilding on mount. */
     prepared?: PreparedVenue3D;
+    /** False renders the chart exactly as saved, with no estimated heights.
+     * Ignored with `prepared`, which already made that choice. */
+    estimate?: boolean;
 }
 interface Venue3DOptions {
     /** Fired on a tap that hits a seat (GPU color-pick). Not fired on empty taps. */
@@ -795,6 +875,8 @@ interface Venue3DOptions {
      * contain framing; validated for the buyer across `/dev/3d` fixtures.
      */
     portraitOverviewCrop?: boolean;
+    /** Optional authored presentation angle; stage-derived orientation otherwise wins. */
+    overviewAzimuthDeg?: number;
     /** Start on the final overview pose without the decorative stand-up intro.
      * Intended for deterministic rendered review and screenshot capture. */
     skipInitialOverviewAnimation?: boolean;
@@ -824,6 +906,8 @@ interface Venue3DOptions {
 
 interface Venue3DStats extends RenderLoopStats {
     drawCalls: number;
+    /** Submitted fallback triangles, including collapsed bays; excludes near chairs. */
+    fallbackTriangles?: number;
     seatCount: number;
 }
 interface Venue3DHandle {
@@ -861,6 +945,9 @@ interface Venue3DHandle {
     resize(): void;
     stats(): Venue3DStats;
     /** Machine-readable evidence from the exact parked WebGL frame and DOM labels. */
+    /** The current view as a JPEG data URL, longest edge at most `maxEdge` px
+     *  (default 1280); null when the GPU context is gone. */
+    captureImage(maxEdge?: number): string | null;
     getQualityEvidence(): Venue3DQualityEvidence;
     getQualityReport(): Venue3DQualityReport;
     loseContextForTest(): void;
@@ -909,19 +996,6 @@ interface Venue3DHandle {
     focusFloor(index: number | null): boolean;
 }
 
-/**
- * view3d — the sole dynamic-import boundary for the lazy OGL venue-view chunk.
- *
- *   const { mountVenue3D } = await import('../view3d');
- *   const handle = mountVenue3D(container, { doc, seats }, { onSeatPick, getSeatView });
- *   await handle.flyToSeat(seatId);
- *
- * Read-only 3D of any chart, fed entirely from the existing height contract.
- * Slice 1: orbit camera, extruded tiers/stage/GA, instanced seat dots, sub-range
- * availability, dispose + context-loss survival. Slice 2: GPU color-pick. Slice
- * 3: the fly-to-seat cinematic that dissolves into the view-from-seat panorama.
- */
-
 declare function mountVenue3D(container: HTMLElement, input: Venue3DInput, opts?: Venue3DOptions): Venue3DHandle;
 
-export { type Analytics3DCallback, type PreparedVenue3D, type PreparedVenue3DFromChart, type Scene3DPrepSource, type SeatState3D, SeatView, type SeatViewStopName, VENUE3D_QUALITY_REPORT_VERSION, type Venue3DHandle, type Venue3DInput, type Venue3DOptions, type Venue3DQualityEvidence, type Venue3DQualityReport, type Venue3DStats, buildSceneModel, inspectVenue3DQualityEvidence, mountVenue3D, prepareVenue3D, prepareVenue3DFromChart };
+export { type Analytics3DCallback, type AutoVenueReport, type PreparedVenue3D, type PreparedVenue3DFromChart, type Scene3DPrepSource, type SeatState3D, SeatView, type SeatViewStopName, VENUE3D_QUALITY_REPORT_VERSION, type Venue3DHandle, type Venue3DInput, type Venue3DOptions, type Venue3DQualityEvidence, type Venue3DQualityReport, type Venue3DStats, autoVenue3d, buildSceneModel, estimateVenue3D, inspectVenue3DQualityEvidence, mountVenue3D, prepareVenue3D, prepareVenue3DFromChart };