@seatlayer/core 0.28.4 → 0.30.0

package/dist/view3d/index.d.cts

@@ -0,0 +1,385 @@
+import { C as ChartDoc, E as ExpandedSeat } from '../types-CG2pEDoI.cjs';
+
+/**
+ * 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;
+}
+
+/**
+ * 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';
+type RGB = [number, number, number];
+/** Structure palette — cool desaturated greys + one warm stage accent. */
+declare const STRUCTURE: {
+    readonly ground: RGB;
+    readonly tierTop: RGB;
+    readonly tierWall: RGB;
+    readonly stageTop: RGB;
+    readonly stageWall: RGB;
+    readonly decorTop: RGB;
+    readonly decorWall: RGB;
+    readonly gaTop: RGB;
+    readonly gaWall: RGB;
+    /** Exhibition / trade-show booth stand. */
+    readonly boothTop: RGB;
+    readonly boothWall: RGB;
+    /** Banquet table top — warmer, so a laid table reads apart from structure. */
+    readonly tableTop: RGB;
+    readonly tableWall: RGB;
+};
+
+/**
+ * Resolve a chart's authored theme into the 3D scene's colours.
+ *
+ * Every chart already carries a `ChartTheme` — background, brand accent, seat
+ * scale — and the 2D renderer and the picker chrome honour it. The 3D view did
+ * not: `palette.ts` was a fixed set of constants, so a white-labelled event
+ * rendered in SeatLayer's own dark grey whatever the organizer had branded. That
+ * is a visible gap in a paid feature, and it is the kind of thing a customer
+ * notices immediately when they switch from the 2D map to the 3D view.
+ *
+ * The palette in `palette.ts` stays the DEFAULT and the reference. This module
+ * only rebases it, so an unthemed chart is byte-for-byte what it was.
+ *
+ * ## How structure is rebased
+ *
+ * Structure colours are not replaced by the brand colour — a venue rendered in
+ * flat brand paint reads as a diagram, not a building, and the look brief is
+ * deliberately "desaturated greys for structure, saturated colour only on
+ * seats". Instead each structure colour is blended a little way toward the
+ * authored background, so the whole venue picks up the brand's cast and sits in
+ * its own light, while keeping the tonal relationships (tier above wall, stage
+ * warmer than tier) that make the geometry readable.
+ */
+
+interface Theme3D {
+    background: {
+        top: RGB;
+        bottom: RGB;
+    };
+    structure: typeof STRUCTURE;
+    seatStates: Record<SeatState3D, RGB>;
+    /** Multiplier on the seat dot's world radius. */
+    seatScale: number;
+}
+
+/**
+ * Venue labels — anchors, level-of-detail, and world→screen projection.
+ *
+ * ## Why labels are DOM, not geometry
+ *
+ * The renderer is deliberately texture-free at three draw calls. Drawing text on
+ * the GPU means a signed-distance font atlas: a texture, another shader, a build
+ * asset, and a resolution ceiling — a lot of machinery for the few dozen labels a
+ * venue actually needs. Projecting anchors and positioning DOM elements costs
+ * nothing when a chart has no labels, and buys properties the GPU path cannot:
+ *
+ *  - **Real text.** A screen reader can read the venue's structure. That is the
+ *    accessibility gap in 3D, not just a rendering convenience.
+ *  - Crisp at any device pixel ratio and any zoom, with no atlas to outgrow.
+ *  - `ChartTheme.fontFamily`, i18n and RTL come from the browser.
+ *
+ * This module is the pure half — what to label, where its anchor sits, and when
+ * it should show. The overlay that positions elements lives in `index.ts`.
+ *
+ * ## Why the rungs mirror 2D
+ *
+ * 2D melts through zones → sections → seats. Labels follow the same idea for the
+ * same reason: at a distance a buyer needs to know which part of the venue they
+ * are looking at, and up close they need to know which block and which door. A
+ * label set that does not thin out with distance turns a 51-section arena into
+ * unreadable confetti.
+ */
+
+type LabelKind = 'zone' | 'section' | 'annotation' | 'booth';
+interface SceneLabel {
+    id: string;
+    kind: LabelKind;
+    text: string;
+    /** World-metre anchor the label is pinned to. */
+    anchor: [number, number, number];
+    /** Authored colour (`#rrggbb`), when the object carries one. */
+    color?: string;
+    /** Authored rotation in degrees, for annotations that specify one. */
+    rotation?: 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;
+    /** 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;
+    /**
+     * float per instance: the largest world radius this dot may take, metres.
+     *
+     * The shader enforces `uMinPixels` by GROWING a dot's world radius with depth,
+     * which is what merges rows into a solid mass at range — measured mean seat
+     * spacing is 0.53–0.58 m against a 0.44 m dot diameter, so there is very little
+     * slack to spend before neighbours touch. A global cap cannot fix it: spacing
+     * is a property of the chart, and varies between sections of the same venue
+     * (measured min 0.21 m on the amphitheatre against a 0.58 m mean).
+     *
+     * So the ceiling travels per seat, derived from that seat's own nearest
+     * neighbour. A dot grows to hold its minimum pixel size and then STOPS,
+     * whatever the distance. Past that point holding legibility is the LOD ladder's
+     * job (fade toward the tier tint), not the dot's.
+     */
+    iMaxRadius: Float32Array;
+    /**
+     * vec3 per instance: accommodation ring colour, or (0,0,0) for none.
+     *
+     * 2D draws a coloured ring around every seat with an accessibility type, and
+     * 3D drew nothing at all — so a wheelchair space, a companion seat or a
+     * lift-armrest seat was indistinguishable from any other the moment a buyer
+     * switched to the 3D view. A ring mirrors the 2D treatment exactly, needs no
+     * texture, and costs one instanced attribute rather than a draw call.
+     */
+    iRing: Float32Array;
+    /** float per instance: owning floor index, for per-floor isolation. */
+    iFloor: Float32Array;
+    /** seatId → instance index (drives targeted availability updates). */
+    idToIndex: Map<string, number>;
+}
+
+/**
+ * A navigable zone — the venue's own top-level grouping (Orchestra, Lower Bowl,
+ * Hall A), resolved for camera framing and for the section/zone LOD rung.
+ *
+ * Every shipped chart authors zones and gives every section one, and the 2D
+ * renderer uses them as its farthest LOD rung. 3D ignored them entirely, so the
+ * one structure a buyer navigates by ("take me to the Grand Circle") had no
+ * representation at all in the 3D view.
+ */
+interface SceneZone {
+    id: string;
+    label: string;
+    /** Authored zone colour, or null when the chart leaves it to the category mix. */
+    color: RGB | null;
+    /** Section object ids belonging to this zone. */
+    sectionIds: string[];
+    /** Seats resolved into this zone. */
+    seatCount: number;
+    /** World-metre centre of the zone's seats (camera target). */
+    center: [number, number, number];
+    /** Half-diagonal of its footprint, world metres (camera fit). */
+    radius: number;
+    /** What this zone faces — its authored focal, else the venue's. */
+    focalWorld: [number, number, number];
+}
+/** A navigable floor — a logical level of the venue. */
+interface SceneFloor {
+    index: number;
+    id: string;
+    label: string;
+    seatCount: number;
+    center: [number, number, number];
+    radius: 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[];
+    /** Resolved colours for this chart's authored theme (background, seat scale). */
+    theme: Theme3D;
+    seatCount: number;
+    /** Venue focal point in world metres (cinematic look-at target). */
+    focalWorld: [number, number, number];
+    /** The venue's zones, in authored order. Empty when the chart has none. */
+    zones: SceneZone[];
+    /**
+     * The venue's floors, in authored order. A single-floor chart reports one.
+     *
+     * Every shipped multi-floor template puts all its floors at baseHeightM 0 and
+     * takes height from the sections instead, so floors are a logical grouping,
+     * not a physical stack. What they need is ISOLATION: draw all three of an
+     * opera house at once and the balcony sits over the parterre.
+     */
+    floors: SceneFloor[];
+    /**
+     * Everything worth naming, with a world anchor: zones, sections, authored
+     * wayfinding text, and booths. Rendered as a DOM overlay — see `labels.ts` for
+     * why text is not geometry here.
+     */
+    labels: SceneLabel[];
+}
+interface SceneModelInput {
+    doc: ChartDoc;
+    seats: ExpandedSeat[];
+    /** Optional initial per-seat state (default all available). */
+    initialState?: (seat: ExpandedSeat) => SeatState3D;
+}
+declare function buildSceneModel(input: SceneModelInput): SceneModel;
+
+/**
+ * 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 — 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;
+    /** The venue's zones (id, label, colour, seat count) in authored order. */
+    zones(): SceneZone[];
+    /**
+     * Frame a zone: the camera moves to sit over that zone looking at what the
+     * zone faces. Returns false for an unknown or empty zone.
+     *
+     * This is the navigation the venue's own structure implies — a buyer picks
+     * "Grand Circle", not a set of coordinates — and it is what the 2D renderer's
+     * farthest LOD rung already offers. Approaching from the zone's focal side
+     * means the seats face the camera rather than presenting their backs.
+     */
+    focusZone(zoneId: string): boolean;
+    /** The venue's floors (id, name, seat count) in authored order. */
+    floors(): SceneFloor[];
+    /**
+     * Isolate one floor, or pass null to show the whole venue.
+     *
+     * Every shipped multi-floor chart puts its floors at the same base height and
+     * takes relief from the sections, so all three of an opera house draw at once
+     * and the balcony sits over the parterre. Unfocused floors are DIMMED rather
+     * than hidden, so the buyer keeps the venue as context while looking at the
+     * level they are booking. Returns false for an unknown index.
+     */
+    focusFloor(index: number | null): boolean;
+}
+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 };