@seatlayer/core 0.68.1 → 0.70.0

package/dist/view3d/index.d.cts

@@ -1,6 +1,6 @@
-import { C as ChartDoc } from '../types-BjTzKc2D.cjs';
-import { p as EventConfigurationProductionElementKind, j as EventConfigurationOcclusion, a as EventConfigurationVersion } from '../eventConfigurations-C_dst7Ro.cjs';
-import { E as ExpandedSeat } from '../renderer-BHInJ52w.cjs';
+import { C as ChartDoc } from '../types-DNztpn7q.cjs';
+import { p as EventConfigurationProductionElementKind, j as EventConfigurationOcclusion, a as EventConfigurationVersion } from '../eventConfigurations-Csdxe89O.cjs';
+import { E as ExpandedSeat } from '../renderer-DmG3C8vD.cjs';
 import { SeatView } from './crossfade/panorama.cjs';
 
 /**
@@ -504,6 +504,45 @@ interface RenderLoopStats {
     idle: boolean;
 }
 
+/**
+ * What a buyer must actually SEE from their seat, and the ladder of poses they
+ * can pull back through.
+ *
+ * `seatViewPose` answers "where is the buyer's eye" truthfully. That is not the
+ * same question as "what does the arrival frame show". On a phone the seat-eye
+ * pose was landing with a fixed 65°/90° FOV pointed at a focal point that could
+ * be a metre of stage lip filling a hundredth of the frame — or, from a pit or
+ * front-stalls seat whose eye sits BELOW the stage deck, nothing but the stage's
+ * front wall and the backdrop above it. The frame was truthful and useless.
+ *
+ * This module is the framing guarantee, and it is pure: given the seat eye, the
+ * stage box and the viewport aspect it returns the pose and FOV to arrive at.
+ *
+ *   1. Aim at the stage — the box centre, at performer height above its deck.
+ *   2. Clear the deck. An eye at or below `stage.max[1]` sees the stage's face,
+ *      not its surface, so lift to just above the lip and step back along the
+ *      seat→stage axis so the lift reads as a view rather than a nosedive.
+ *   3. Choose the WIDEST field of view in [45°, 80°] that leaves the stage box
+ *      covering at least a quarter of the frame's WIDTH, and the PERFORMANCE
+ *      VOLUME — the deck plus a performer's height, which is what the buyer
+ *      came to see — covering at least an eighth of its HEIGHT. Wide is the honest
+ *      seat feeling (you see your neighbours); the width floor stops "wide"
+ *      from turning the stage into a speck, and the height floor stops it
+ *      turning the stage into a line at the horizon. Where the two conflict,
+ *      width wins, because the height floor is never worth a step off the
+ *      buyer's own seat.
+ *   4. If the box still overflows the frame, keep stepping back along the same
+ *      axis until it fits. That also resolves the degenerate cases — an eye
+ *      inside or level with the stage box — where corners fall behind the eye.
+ *
+ * The stops (`buildSeatViewStops`) are the same axis, further out: your seat →
+ * your row → your section → the venue. Every stop is a pose, so pulling back
+ * and pinching in are the same reversible gesture; nothing hands the camera
+ * away irrecoverably.
+ */
+
+type SeatViewStopName = 'seat' | 'row' | 'section' | 'venue';
+
 declare const VENUE3D_QUALITY_REPORT_VERSION = 1;
 interface Venue3DLabelEvidence {
     id: string;
@@ -562,6 +601,19 @@ interface Venue3DQualityEvidence {
     labels: Venue3DLabelEvidence[];
     /** Measured for review; promotion thresholds remain an owner decision. */
     framing?: Venue3DFramingEvidence;
+    /**
+     * The seat view's LIVE state, when the buyer is sitting in a seat.
+     *
+     * `camera.verticalFovDeg` above is the ORBIT rig's field of view, which the
+     * seat-view controller does not own: pulling back through the named stops
+     * animates the camera's own fov, and reading the orbit value there reports a
+     * framing nobody is looking through. Verification needs the number that is
+     * actually on the glass, next to the stop it belongs to.
+     */
+    seatView?: {
+        fovDeg: number;
+        stop: SeatViewStopName | null;
+    };
 }
 type Venue3DQualityFindingCode = 'webgl2-unavailable' | 'context-lost' | 'frame-not-stable' | 'viewport-empty' | 'camera-invalid' | 'authored-relief-not-visible' | 'hierarchy-label-missing' | 'hierarchy-label-undersized' | 'hierarchy-label-contrast-low' | 'hierarchy-label-collision';
 interface Venue3DQualityFinding {
@@ -649,9 +701,26 @@ interface Venue3DOptions {
     /** Buyer-facing action for entering the supplied seat view. The caller knows
      * whether that source is live geometry or an authored panorama. */
     seatViewActionLabel?: (seatId: string) => string;
+    /**
+     * The caption naming where the camera has landed, e.g.
+     * "Stalls D · Row C · Seat 6 · view from your seat". The engine ships an
+     * English default; hosts that translate their chrome supply the localized
+     * string here rather than having the engine carry a second copy of i18n.
+     */
+    seatViewCaption?: (seatId: string) => string;
     /** Land at the modeled seated-eye pose instead of the elevated inspection
      * anchor. Useful when live geometry is the primary buyer view. */
     arriveAtSeatEye?: boolean;
+    /**
+     * Give a seat-eye arrival the named pull-back stops — your seat, your row,
+     * your section, the venue — reachable by pinch/wheel, with drag looking
+     * around from the seat. Default true; pass false for the old pinned pose.
+     * Ignored unless `arriveAtSeatEye` is set.
+     */
+    seatViewStops?: boolean;
+    /** Fired when the seat view settles on (or nears) a different stop, and with
+     * null when the seat view ends. Lets host chrome caption where the buyer is. */
+    onSeatViewStopChange?: (stop: SeatViewStopName | null) => void;
     /**
      * Decoupled analytics sink. Emits the venue-view journey: `3d_opened`,
      * `3d_orbit_engaged` (first user gesture), `3d_seat_picked`,
@@ -671,6 +740,7 @@ interface Venue3DOptions {
      * Intended for deterministic rendered review and screenshot capture. */
     skipInitialOverviewAnimation?: boolean;
 }
+
 interface Venue3DStats extends RenderLoopStats {
     drawCalls: number;
     seatCount: number;
@@ -695,6 +765,18 @@ interface Venue3DHandle {
     flyToSeat(seatId: string): Promise<void>;
     /** Cancel a seat flight/panorama and fit the active floor or complete venue. */
     focusOverview(): void;
+    /**
+     * Which named stop the seat view is at — 'seat', 'row', 'section', 'venue' —
+     * or null when the buyer is not in a seat view. Host chrome captions this;
+     * it is read-only because the stops belong to the gesture, not the host.
+     */
+    seatViewStop(): SeatViewStopName | null;
+    /**
+     * Turn the seat view's aim back to the stage without leaving the seat — the
+     * recover action for a buyer who has looked away. False when the buyer is
+     * not in a seat view (nothing to recentre).
+     */
+    recentreSeatView(): boolean;
     resize(): void;
     stats(): Venue3DStats;
     /** Machine-readable evidence from the exact parked WebGL frame and DOM labels. */
@@ -761,4 +843,4 @@ interface Venue3DHandle {
 
 declare function mountVenue3D(container: HTMLElement, input: Venue3DInput, opts?: Venue3DOptions): Venue3DHandle;
 
-export { type Analytics3DCallback, type Scene3DPrepSource, type SeatState3D, SeatView, VENUE3D_QUALITY_REPORT_VERSION, type Venue3DHandle, type Venue3DInput, type Venue3DOptions, type Venue3DQualityEvidence, type Venue3DQualityReport, type Venue3DStats, buildSceneModel, inspectVenue3DQualityEvidence, mountVenue3D, prepareVenue3D };
+export { type Analytics3DCallback, 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 };

package/dist/view3d/index.d.ts

@@ -1,6 +1,6 @@
-import { C as ChartDoc } from '../types-BjTzKc2D.js';
-import { p as EventConfigurationProductionElementKind, j as EventConfigurationOcclusion, a as EventConfigurationVersion } from '../eventConfigurations-kZpADDdx.js';
-import { E as ExpandedSeat } from '../renderer-BGmZn_bq.js';
+import { C as ChartDoc } from '../types-DNztpn7q.js';
+import { p as EventConfigurationProductionElementKind, j as EventConfigurationOcclusion, a as EventConfigurationVersion } from '../eventConfigurations-CA2XhDig.js';
+import { E as ExpandedSeat } from '../renderer-DIcDImOu.js';
 import { SeatView } from './crossfade/panorama.js';
 
 /**
@@ -504,6 +504,45 @@ interface RenderLoopStats {
     idle: boolean;
 }
 
+/**
+ * What a buyer must actually SEE from their seat, and the ladder of poses they
+ * can pull back through.
+ *
+ * `seatViewPose` answers "where is the buyer's eye" truthfully. That is not the
+ * same question as "what does the arrival frame show". On a phone the seat-eye
+ * pose was landing with a fixed 65°/90° FOV pointed at a focal point that could
+ * be a metre of stage lip filling a hundredth of the frame — or, from a pit or
+ * front-stalls seat whose eye sits BELOW the stage deck, nothing but the stage's
+ * front wall and the backdrop above it. The frame was truthful and useless.
+ *
+ * This module is the framing guarantee, and it is pure: given the seat eye, the
+ * stage box and the viewport aspect it returns the pose and FOV to arrive at.
+ *
+ *   1. Aim at the stage — the box centre, at performer height above its deck.
+ *   2. Clear the deck. An eye at or below `stage.max[1]` sees the stage's face,
+ *      not its surface, so lift to just above the lip and step back along the
+ *      seat→stage axis so the lift reads as a view rather than a nosedive.
+ *   3. Choose the WIDEST field of view in [45°, 80°] that leaves the stage box
+ *      covering at least a quarter of the frame's WIDTH, and the PERFORMANCE
+ *      VOLUME — the deck plus a performer's height, which is what the buyer
+ *      came to see — covering at least an eighth of its HEIGHT. Wide is the honest
+ *      seat feeling (you see your neighbours); the width floor stops "wide"
+ *      from turning the stage into a speck, and the height floor stops it
+ *      turning the stage into a line at the horizon. Where the two conflict,
+ *      width wins, because the height floor is never worth a step off the
+ *      buyer's own seat.
+ *   4. If the box still overflows the frame, keep stepping back along the same
+ *      axis until it fits. That also resolves the degenerate cases — an eye
+ *      inside or level with the stage box — where corners fall behind the eye.
+ *
+ * The stops (`buildSeatViewStops`) are the same axis, further out: your seat →
+ * your row → your section → the venue. Every stop is a pose, so pulling back
+ * and pinching in are the same reversible gesture; nothing hands the camera
+ * away irrecoverably.
+ */
+
+type SeatViewStopName = 'seat' | 'row' | 'section' | 'venue';
+
 declare const VENUE3D_QUALITY_REPORT_VERSION = 1;
 interface Venue3DLabelEvidence {
     id: string;
@@ -562,6 +601,19 @@ interface Venue3DQualityEvidence {
     labels: Venue3DLabelEvidence[];
     /** Measured for review; promotion thresholds remain an owner decision. */
     framing?: Venue3DFramingEvidence;
+    /**
+     * The seat view's LIVE state, when the buyer is sitting in a seat.
+     *
+     * `camera.verticalFovDeg` above is the ORBIT rig's field of view, which the
+     * seat-view controller does not own: pulling back through the named stops
+     * animates the camera's own fov, and reading the orbit value there reports a
+     * framing nobody is looking through. Verification needs the number that is
+     * actually on the glass, next to the stop it belongs to.
+     */
+    seatView?: {
+        fovDeg: number;
+        stop: SeatViewStopName | null;
+    };
 }
 type Venue3DQualityFindingCode = 'webgl2-unavailable' | 'context-lost' | 'frame-not-stable' | 'viewport-empty' | 'camera-invalid' | 'authored-relief-not-visible' | 'hierarchy-label-missing' | 'hierarchy-label-undersized' | 'hierarchy-label-contrast-low' | 'hierarchy-label-collision';
 interface Venue3DQualityFinding {
@@ -649,9 +701,26 @@ interface Venue3DOptions {
     /** Buyer-facing action for entering the supplied seat view. The caller knows
      * whether that source is live geometry or an authored panorama. */
     seatViewActionLabel?: (seatId: string) => string;
+    /**
+     * The caption naming where the camera has landed, e.g.
+     * "Stalls D · Row C · Seat 6 · view from your seat". The engine ships an
+     * English default; hosts that translate their chrome supply the localized
+     * string here rather than having the engine carry a second copy of i18n.
+     */
+    seatViewCaption?: (seatId: string) => string;
     /** Land at the modeled seated-eye pose instead of the elevated inspection
      * anchor. Useful when live geometry is the primary buyer view. */
     arriveAtSeatEye?: boolean;
+    /**
+     * Give a seat-eye arrival the named pull-back stops — your seat, your row,
+     * your section, the venue — reachable by pinch/wheel, with drag looking
+     * around from the seat. Default true; pass false for the old pinned pose.
+     * Ignored unless `arriveAtSeatEye` is set.
+     */
+    seatViewStops?: boolean;
+    /** Fired when the seat view settles on (or nears) a different stop, and with
+     * null when the seat view ends. Lets host chrome caption where the buyer is. */
+    onSeatViewStopChange?: (stop: SeatViewStopName | null) => void;
     /**
      * Decoupled analytics sink. Emits the venue-view journey: `3d_opened`,
      * `3d_orbit_engaged` (first user gesture), `3d_seat_picked`,
@@ -671,6 +740,7 @@ interface Venue3DOptions {
      * Intended for deterministic rendered review and screenshot capture. */
     skipInitialOverviewAnimation?: boolean;
 }
+
 interface Venue3DStats extends RenderLoopStats {
     drawCalls: number;
     seatCount: number;
@@ -695,6 +765,18 @@ interface Venue3DHandle {
     flyToSeat(seatId: string): Promise<void>;
     /** Cancel a seat flight/panorama and fit the active floor or complete venue. */
     focusOverview(): void;
+    /**
+     * Which named stop the seat view is at — 'seat', 'row', 'section', 'venue' —
+     * or null when the buyer is not in a seat view. Host chrome captions this;
+     * it is read-only because the stops belong to the gesture, not the host.
+     */
+    seatViewStop(): SeatViewStopName | null;
+    /**
+     * Turn the seat view's aim back to the stage without leaving the seat — the
+     * recover action for a buyer who has looked away. False when the buyer is
+     * not in a seat view (nothing to recentre).
+     */
+    recentreSeatView(): boolean;
     resize(): void;
     stats(): Venue3DStats;
     /** Machine-readable evidence from the exact parked WebGL frame and DOM labels. */
@@ -761,4 +843,4 @@ interface Venue3DHandle {
 
 declare function mountVenue3D(container: HTMLElement, input: Venue3DInput, opts?: Venue3DOptions): Venue3DHandle;
 
-export { type Analytics3DCallback, type Scene3DPrepSource, type SeatState3D, SeatView, VENUE3D_QUALITY_REPORT_VERSION, type Venue3DHandle, type Venue3DInput, type Venue3DOptions, type Venue3DQualityEvidence, type Venue3DQualityReport, type Venue3DStats, buildSceneModel, inspectVenue3DQualityEvidence, mountVenue3D, prepareVenue3D };
+export { type Analytics3DCallback, 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 };