@seatlayer/core 0.28.4 → 0.29.0

package/dist/view3d/index.d.ts

@@ -0,0 +1,176 @@
+import { C as ChartDoc, E as ExpandedSeat } from '../types-B-tpUFqz.js';
+
+/**
+ * Dirty-flag render loop. A frame is drawn only while the camera is moving /
+ * damping or an availability update arrived; when idle, no rAF is scheduled at
+ * all (zero CPU/GPU when parked). Tracks an FPS EMA over frames actually
+ * rendered — it reads as "idle" when nothing is scheduled.
+ */
+interface RenderLoopStats {
+    fps: number;
+    rendered: number;
+    idle: boolean;
+}
+
+/**
+ * Slice 3 hand-off — the DOM panorama overlay the fly-to-seat cinematic
+ * dissolves into. Decoupled by design: the CALLER supplies the equirectangular
+ * image (via mountVenue3D's getSeatView), so view3d never imports the app's
+ * panorama generator and the chunk stays lean.
+ *
+ * Technique (mirrors SeatPicker.openSeatView, reimplemented small): an equirect
+ * image panned with `repeat-x`; the initial horizontal offset is set so the
+ * panorama's bearing matches the final camera yaw — the dissolve reads as the
+ * same view sharpening, not a cut. CSS opacity fade is compositor-only.
+ */
+interface SeatView {
+    url: string;
+    /** Bearing (deg, 0 = facing the focal/stage) the panorama should open centred
+     * on, to match the camera's final yaw. Default 0 (both face the stage). */
+    initialBearingDeg?: number;
+}
+
+/**
+ * view3d analytics — a tiny, decoupled event emitter for the venue view. The
+ * caller (app/harness) supplies `onAnalytics`; this class owns the per-mount
+ * state (first-orbit latch, panorama dwell timing) and, crucially, wraps EVERY
+ * callback invocation in try/catch so a throwing analytics sink can never break
+ * rendering. No DOM, no GL — unit-testable in isolation.
+ */
+type Analytics3DCallback = (event: string, props?: Record<string, unknown>) => void;
+
+/**
+ * view3d palette + seat-state model — the single source of colour truth for the
+ * OGL venue view. Pure data (no GPU, no DOM) so the scene builder and the unit
+ * tests share one definition. Colours are linear-ish RGB triplets in 0..1.
+ *
+ * Look brief (docs/3d-usp-strategy §3): desaturated cool greys for structure,
+ * one warm accent for the stage, availability colours only on seats.
+ */
+type SeatState3D = 'available' | 'held' | 'sold' | 'selected' | 'dimmed';
+
+/**
+ * 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;
+    /** Vertex count (position.length / 3). */
+    count: number;
+}
+
+/**
+ * Pure builder for the instanced seat cloud. Produces the per-instance arrays a
+ * single OGL InstancedMesh consumes (one draw call for every seat), plus the
+ * seatId → instanceIndex map that `setAvailability` uses to patch only the seats
+ * that actually changed via a sub-range `bufferSubData` upload.
+ */
+
+interface SeatInstanceData {
+    count: number;
+    /** vec3 per instance: world (x, y, z) in metres. */
+    iPosition: Float32Array;
+    /** float per instance: index into the seat-state colour LUT. */
+    iState: Float32Array;
+    /** seatId → instance index (drives targeted availability updates). */
+    idToIndex: Map<string, number>;
+}
+
+interface SceneModel {
+    /** Every non-seat surface merged into one triangle soup (1 draw call). */
+    solids: MeshData;
+    seats: SeatInstanceData;
+    bounds: {
+        /** World-metre venue centre (camera target). */
+        center: [number, number, number];
+        /** Half-diagonal of the horizontal footprint, metres (camera fit). */
+        radius: number;
+        groundY: number;
+    };
+    /** 5 × vec3 flat LUT for the seat fragment shader. */
+    stateColorLUT: number[];
+    seatCount: number;
+    /** Venue focal point in world metres (cinematic look-at target). */
+    focalWorld: [number, number, number];
+}
+interface SceneModelInput {
+    doc: ChartDoc;
+    seats: ExpandedSeat[];
+    /** Optional initial per-seat state (default all available). */
+    initialState?: (seat: ExpandedSeat) => SeatState3D;
+}
+declare function buildSceneModel(input: SceneModelInput): SceneModel;
+
+/**
+ * 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.
+ */
+
+interface Venue3DInput {
+    doc: ChartDoc;
+    /** Expanded seats (from `expandChart`) — carry x/y + resolved eyeHeightM. */
+    seats: ExpandedSeat[];
+    /** Optional initial per-seat state (default all available). */
+    initialState?: (seat: ExpandedSeat) => SeatState3D;
+}
+interface Venue3DOptions {
+    /** Fired on a tap that hits a seat (GPU color-pick). Not fired on empty taps. */
+    onSeatPick?: (seatId: string) => void;
+    /**
+     * Supplies the view-from-seat panorama for the cinematic hand-off. Decoupled:
+     * the caller (app/harness) owns panorama generation; view3d never imports it.
+     * Called at PICK time to pre-render, so flyToSeat has zero wait on landing.
+     */
+    getSeatView?: (seatId: string) => SeatView | Promise<SeatView>;
+    /**
+     * Decoupled analytics sink. Emits the venue-view journey: `3d_opened`,
+     * `3d_orbit_engaged` (first user gesture), `3d_seat_picked`,
+     * `3d_cinematic_played`/`_skipped`/`_cancelled`, `3d_panorama_opened`/`_closed`.
+     * Every invocation is wrapped in try/catch — a throwing sink never breaks
+     * rendering. Absent = no events emitted.
+     */
+    onAnalytics?: Analytics3DCallback;
+}
+interface Venue3DStats extends RenderLoopStats {
+    drawCalls: number;
+    seatCount: number;
+}
+interface Venue3DHandle {
+    dispose(): void;
+    setAvailability(updates: {
+        seatId: string;
+        state: SeatState3D;
+    }[]): void;
+    setSelection(seatIds: string[]): void;
+    /** Fly the camera from the overview into `seatId` and dissolve into its
+     * view-from-seat panorama. Resolves at flight end; a drag cancels it, a second
+     * call retargets, dispose resolves early. Reduced-motion → a short fade. */
+    flyToSeat(seatId: string): Promise<void>;
+    resize(): void;
+    stats(): Venue3DStats;
+    loseContextForTest(): void;
+    /** Test hook: force (or clear) the reduced-motion path. */
+    setReducedMotionForTest(value: boolean | null): void;
+}
+declare function mountVenue3D(container: HTMLElement, input: Venue3DInput, opts?: Venue3DOptions): Venue3DHandle;
+
+export { type Analytics3DCallback, type SeatState3D, type SeatView, type Venue3DHandle, type Venue3DInput, type Venue3DOptions, type Venue3DStats, buildSceneModel, mountVenue3D };