@cyberart-io/engine 0.0.10 → 0.0.11

package/CHANGELOG.md

@@ -4,6 +4,16 @@ All notable changes to `@cyberart-io/engine`. Each entry links the guide in `doc
 
 ## Unreleased
 
+## 0.0.11 — 2026-09-06
+
+Production-scenario overlap precedence and transactional reload. Additive: existing exports keep their signatures.
+
+### Added
+
+- **Transactional production-scenario reload** — `reload` preflights the sidecar envelope, optional `host.validateRestoreState`, projected input surface, and every present module sidecar before mutation. Apply is one transaction with rollback on failure; invalid sidecars localize at subsystem boundaries (`invalid-visual-sidecar`, `invalid-semantic-sidecar`, `invalid-binding-sidecar`, `invalid-sequence-sidecar`, `invalid-audio-sidecar`, `invalid-host-sidecar`). Legacy envelopes omitting sidecar keys remain compatible. [docs/production-scenario.md](docs/production-scenario.md) · [#60](https://github.com/cyberart-io/cyberart.io/pull/60)
+
+- **Overlap precedence on production input surface** — `ProductionScenarioControl.priority` resolves intersecting regions deterministically in browser and headless. Equal or missing priority on an overlapping pair still fails closed at boundary `input` (`ambiguous-geometry`). Coordinate clicks record `observation.inputHitTest` (selected and rejected control ids). [docs/production-scenario.md](docs/production-scenario.md) · [#59](https://github.com/cyberart-io/cyberart.io/pull/59)
+
 ## 0.0.10 — 2026-09-06
 
 Production-scenario follow-ups after the 0.0.9 Animation Framework cut. Additive: existing exports keep their signatures.

package/dist/headless.d.ts

@@ -4015,7 +4015,7 @@ declare const PRODUCTION_SCENARIO_SCHEMA_VERSION: 1;
 declare const PRODUCTION_SCENARIO_SNAPSHOT_SCHEMA_VERSION: 1;
 declare const PRODUCTION_SCENARIO_BOUNDARIES: readonly ["input", "reducer", "routing", "binding", "cue", "pixels", "caption", "audio", "save-replay"];
 type ProductionScenarioBoundary = (typeof PRODUCTION_SCENARIO_BOUNDARIES)[number];
-declare const PRODUCTION_SCENARIO_ERROR_CODES: readonly ["invalid-scenario", "invalid-schema", "unknown-field", "missing-field", "callbacks-forbidden", "missing-participant", "missing-layer", "destroyed", "assertion-failed", "invalid-host-audio", "invalid-audio-sidecar", "unsupported-preference", "invalid-geometry", "ambiguous-geometry", "stale-geometry"];
+declare const PRODUCTION_SCENARIO_ERROR_CODES: readonly ["invalid-scenario", "invalid-schema", "unknown-field", "missing-field", "callbacks-forbidden", "missing-participant", "missing-layer", "destroyed", "assertion-failed", "invalid-host-audio", "invalid-audio-sidecar", "invalid-visual-sidecar", "invalid-semantic-sidecar", "invalid-binding-sidecar", "invalid-sequence-sidecar", "invalid-host-sidecar", "unsupported-preference", "invalid-geometry", "ambiguous-geometry", "stale-geometry"];
 type ProductionScenarioErrorCode = (typeof PRODUCTION_SCENARIO_ERROR_CODES)[number];
 declare const HOST_OWNED_AUDIO_EVENT_KINDS: readonly ["invoked", "completed", "failed", "skipped", "fallback"];
 type HostOwnedAudioEventKind = (typeof HOST_OWNED_AUDIO_EVENT_KINDS)[number];
@@ -4115,6 +4115,14 @@ type ProductionScenarioControl = {
     id: string;
     name?: string;
     role?: string;
+    /** Higher priority wins normalized overlap hit-tests when regions intersect. */
+    priority?: number;
+};
+type ProductionScenarioInputHitTest = {
+    x: number;
+    y: number;
+    selectedControlId: string;
+    rejectedControlIds: readonly string[];
 };
 type ProductionScenarioInputSurface = {
     controls: readonly ProductionScenarioControl[];
@@ -4131,6 +4139,16 @@ type ProductionScenarioHost = {
      * geometry and controls.
      */
     projectInputSurface?(state: JsonObject): ProductionScenarioInputSurface;
+    /**
+     * Optional pre-reload validator for host JSON from a saved sidecar. When
+     * supplied, reload rejects invalid host state before any live mutation.
+     */
+    validateRestoreState?(state: JsonObject): {
+        ok: true;
+    } | {
+        ok: false;
+        detail: string;
+    };
 };
 type HostOwnedAudioEvent = {
     kind: HostOwnedAudioEventKind;
@@ -4206,6 +4224,7 @@ type ProductionScenarioObservation = {
     reducedMotion?: boolean;
     reducedMotionPropagation?: ReducedMotionPropagation | null;
     activeControlIds: string[];
+    inputHitTest?: ProductionScenarioInputHitTest;
 };
 type ProductionScenarioExpectation = {
     inputDispatched?: boolean;
@@ -4328,6 +4347,7 @@ type ProductionScenarioRunner = {
         reducedMotionPropagation: ReducedMotionPropagation | null;
         inputSurface: {
             controlIds: string[];
+            controls: readonly ProductionScenarioControl[];
             geometry: GeometryDocument | null;
         };
     };
@@ -4360,4 +4380,4 @@ type WriteComposedFrameResult = ComposedFrame & {
  */
 declare function writeComposedFrame(compositor: Compositor, path?: string): Promise<WriteComposedFrameResult>;
 
-export { AUDIO_CUE_SNAPSHOT_SCHEMA_VERSION, type AudioCueDiagnostic, type BoundReplaySession, CONTENT_REVISION_ACTIVATED_EVENT, CONTENT_REVISION_SNAPSHOT_SCHEMA_VERSION, type CausationTreeNode, type ContentRevisionActivator, type ContentRevisionBundle, type ContentRevisionInspect, type ContentRevisionSnapshot, type CreateHeadlessHarnessOptions, type CreateHeadlessMultiCartHarnessOptions, type CreateProductionScenarioRunnerOptions, type CreateReplayInspectorOptions, type CreateSelectionTraceOptions, DEFAULT_HEADLESS_HEIGHT, DEFAULT_HEADLESS_WIDTH, DEFAULT_MAX_SELECTION_RECORDS, DEFAULT_PRODUCTION_SCENARIO_VIEWPORTS, type FrameBenchmarkOptions, type FrameBenchmarkResult, type GlyphAtlas, HEADLESS_PNG_DATA_URL, HOST_OWNED_AUDIO_EVENT_KINDS, type HeadlessAudioAdapter, type HeadlessAudioAdapterSnapshot, type HeadlessCanvas2DSettings, type HeadlessFrameError, type HeadlessHarness, type HeadlessImageFixture, type HeadlessInspect, type HeadlessJobWorker, type HeadlessMultiCartHarness, HeadlessUnsupportedOperationError, type HostGrantSet, type HostOwnedAudioEvent, type HostOwnedAudioEventKind, type HostOwnedAudioObserver, type HostOwnedAudioSnapshot, type InspectorRecord, type InstallHeadlessCanvasOptions, type JobCoordinator, type JobCoordinatorSnapshot, type JobInspect, PRESENTATION_BINDING_APPLIED_EVENT, PRESENTATION_BINDING_SNAPSHOT_SCHEMA_VERSION, PRODUCTION_SCENARIO_BOUNDARIES, PRODUCTION_SCENARIO_SCHEMA_VERSION, PRODUCTION_SCENARIO_SNAPSHOT_SCHEMA_VERSION, type PortalInspect, type PortalLifecycle, type PortalLifecycleSnapshot, type PresentationBindingInspect, type PresentationBindingManifest, type PresentationBindingRuntime, type PresentationBindingSnapshot, type PresentationSequenceDefinition, type PresentationSequenceInspect, type PresentationSequencePlayer, type PresentationSequenceSnapshot, type ProductionScenarioControl, type ProductionScenarioDefinition, type ProductionScenarioEvidenceBundle, type ProductionScenarioExpectation, type ProductionScenarioHost, type ProductionScenarioInputSurface, type ProductionScenarioLocalization, type ProductionScenarioObservation, type ProductionScenarioRunner, REDUCED_MOTION_ACTIVE_SEQUENCE_POLICY, REDUCED_MOTION_PARTICIPANT_IDS, type ReducedMotionActiveSequencePolicy, type ReducedMotionParticipantId, type ReducedMotionParticipantReport, type ReducedMotionPropagation, type RemoteCartInspect, type RemoteCartSandbox, type ReplayCompareResult, type ReplayInspector, type ReplayInspectorExport, type ReplayInspectorReport, type ReplayParticipantSummary, type ReplayTapeAction, type ReplayTraceFilter, type RestoreAudioCueResult, SELECTION_DECISION_KINDS, SELECTION_REASON_CODES, SELECTION_TRACE_SCHEMA_VERSION, SELECTION_TRACE_SENSITIVE_KEYS, type SelectionAssetResolution, type SelectionBindingEvaluation, type SelectionContentIdentity, type SelectionDecisionInput, type SelectionDecisionKind, type SelectionDecisionRecord, type SelectionPresentationDecision, type SelectionReasonCode, type SelectionSequenceDecision, type SelectionSnapshotProvenance, type SelectionStagingOutcome, type SelectionStagingResult, type SelectionTrace, type SelectionTraceExport, type SelectionTraceFilter, type SelectionTraceReport, type SemanticLayerController, type SemanticPublishedRegion, type SemanticRegionInspect, UPDATE_GOLDEN_ENV, type VisualArtifactPaths, type VisualArtifacts, type VisualCompareOptions, type VisualCompareResult, type VisualLayerCapture, type VisualLayerController, type VisualLayerInspect, WORLD_PATCH_ACCEPTED_EVENT, WORLD_PATCH_SNAPSHOT_SCHEMA_VERSION, type WorldGraph, type WorldGraphInspect, type WorldGraphProjection, type WorldGraphSnapshot, type WorldPatchApplier, type WorldPatchInspect, type WorldPatchSnapshot, type WorldPersistenceAdapter, type WriteComposedFrameResult, assertPixelsEqual, assertPngDataUrlsEqual, attachHeadlessCanvas2D, attachSelectionTrace, benchmarkCartFrames, cabinetPortal, captureVisualLayers, compareImageData, compareReplayTraces, contentRevisionEventContracts, createContentRevisionActivator, createDefaultGlyphAtlas, createHeadlessAudioAdapter, createHeadlessHarness, createHeadlessJobWorker, createHeadlessMultiCartHarness, createHostGrantSet, createImageFixture, createJobCoordinator, createMemoryJobPersistence, createMemoryWorldPersistence, createPortalLifecycle, createPresentationBindingRuntime, createPresentationSequencePlayer, createProductionScenarioRunner, createRemoteCartSandbox, createRemoteContentAdapter, createReplayInspector, createSelectionTrace, createSemanticLayerController, createStaticContentAdapter, createVisualLayerController, createWorldGraph, createWorldPatchApplier, decodePng, definePresentationBindings, definePresentationSequence, defineProductionScenario, encodePng, encodePngDataUrl, evaluatePresentationBindings, fnv1aHex, formatFrameBenchmarkResult, getHeadlessSurface, imageDataFromPngDataUrl, installHeadlessCanvas, isHostOwnedAudioEventKind, isSelectionDecisionKind, isSelectionReasonCode, jobEventContracts, localizeProductionScenarioFailure, makeImageData, paintingPortal, parseAudioCueSnapshot, presentationBindingEventContracts, presentationSequenceEventContracts, productionScenarioEventContracts, recordSelectionDecision, replayExportedTrace, setDefaultGlyphAtlas, shouldUpdateGolden, worldGraphEventContracts, worldPatchEventContracts, writeComposedFrame, writeVisualArtifacts };
+export { AUDIO_CUE_SNAPSHOT_SCHEMA_VERSION, type AudioCueDiagnostic, type BoundReplaySession, CONTENT_REVISION_ACTIVATED_EVENT, CONTENT_REVISION_SNAPSHOT_SCHEMA_VERSION, type CausationTreeNode, type ContentRevisionActivator, type ContentRevisionBundle, type ContentRevisionInspect, type ContentRevisionSnapshot, type CreateHeadlessHarnessOptions, type CreateHeadlessMultiCartHarnessOptions, type CreateProductionScenarioRunnerOptions, type CreateReplayInspectorOptions, type CreateSelectionTraceOptions, DEFAULT_HEADLESS_HEIGHT, DEFAULT_HEADLESS_WIDTH, DEFAULT_MAX_SELECTION_RECORDS, DEFAULT_PRODUCTION_SCENARIO_VIEWPORTS, type FrameBenchmarkOptions, type FrameBenchmarkResult, type GlyphAtlas, HEADLESS_PNG_DATA_URL, HOST_OWNED_AUDIO_EVENT_KINDS, type HeadlessAudioAdapter, type HeadlessAudioAdapterSnapshot, type HeadlessCanvas2DSettings, type HeadlessFrameError, type HeadlessHarness, type HeadlessImageFixture, type HeadlessInspect, type HeadlessJobWorker, type HeadlessMultiCartHarness, HeadlessUnsupportedOperationError, type HostGrantSet, type HostOwnedAudioEvent, type HostOwnedAudioEventKind, type HostOwnedAudioObserver, type HostOwnedAudioSnapshot, type InspectorRecord, type InstallHeadlessCanvasOptions, type JobCoordinator, type JobCoordinatorSnapshot, type JobInspect, PRESENTATION_BINDING_APPLIED_EVENT, PRESENTATION_BINDING_SNAPSHOT_SCHEMA_VERSION, PRODUCTION_SCENARIO_BOUNDARIES, PRODUCTION_SCENARIO_SCHEMA_VERSION, PRODUCTION_SCENARIO_SNAPSHOT_SCHEMA_VERSION, type PortalInspect, type PortalLifecycle, type PortalLifecycleSnapshot, type PresentationBindingInspect, type PresentationBindingManifest, type PresentationBindingRuntime, type PresentationBindingSnapshot, type PresentationSequenceDefinition, type PresentationSequenceInspect, type PresentationSequencePlayer, type PresentationSequenceSnapshot, type ProductionScenarioControl, type ProductionScenarioDefinition, type ProductionScenarioEvidenceBundle, type ProductionScenarioExpectation, type ProductionScenarioHost, type ProductionScenarioInputHitTest, type ProductionScenarioInputSurface, type ProductionScenarioLocalization, type ProductionScenarioObservation, type ProductionScenarioRunner, REDUCED_MOTION_ACTIVE_SEQUENCE_POLICY, REDUCED_MOTION_PARTICIPANT_IDS, type ReducedMotionActiveSequencePolicy, type ReducedMotionParticipantId, type ReducedMotionParticipantReport, type ReducedMotionPropagation, type RemoteCartInspect, type RemoteCartSandbox, type ReplayCompareResult, type ReplayInspector, type ReplayInspectorExport, type ReplayInspectorReport, type ReplayParticipantSummary, type ReplayTapeAction, type ReplayTraceFilter, type RestoreAudioCueResult, SELECTION_DECISION_KINDS, SELECTION_REASON_CODES, SELECTION_TRACE_SCHEMA_VERSION, SELECTION_TRACE_SENSITIVE_KEYS, type SelectionAssetResolution, type SelectionBindingEvaluation, type SelectionContentIdentity, type SelectionDecisionInput, type SelectionDecisionKind, type SelectionDecisionRecord, type SelectionPresentationDecision, type SelectionReasonCode, type SelectionSequenceDecision, type SelectionSnapshotProvenance, type SelectionStagingOutcome, type SelectionStagingResult, type SelectionTrace, type SelectionTraceExport, type SelectionTraceFilter, type SelectionTraceReport, type SemanticLayerController, type SemanticPublishedRegion, type SemanticRegionInspect, UPDATE_GOLDEN_ENV, type VisualArtifactPaths, type VisualArtifacts, type VisualCompareOptions, type VisualCompareResult, type VisualLayerCapture, type VisualLayerController, type VisualLayerInspect, WORLD_PATCH_ACCEPTED_EVENT, WORLD_PATCH_SNAPSHOT_SCHEMA_VERSION, type WorldGraph, type WorldGraphInspect, type WorldGraphProjection, type WorldGraphSnapshot, type WorldPatchApplier, type WorldPatchInspect, type WorldPatchSnapshot, type WorldPersistenceAdapter, type WriteComposedFrameResult, assertPixelsEqual, assertPngDataUrlsEqual, attachHeadlessCanvas2D, attachSelectionTrace, benchmarkCartFrames, cabinetPortal, captureVisualLayers, compareImageData, compareReplayTraces, contentRevisionEventContracts, createContentRevisionActivator, createDefaultGlyphAtlas, createHeadlessAudioAdapter, createHeadlessHarness, createHeadlessJobWorker, createHeadlessMultiCartHarness, createHostGrantSet, createImageFixture, createJobCoordinator, createMemoryJobPersistence, createMemoryWorldPersistence, createPortalLifecycle, createPresentationBindingRuntime, createPresentationSequencePlayer, createProductionScenarioRunner, createRemoteCartSandbox, createRemoteContentAdapter, createReplayInspector, createSelectionTrace, createSemanticLayerController, createStaticContentAdapter, createVisualLayerController, createWorldGraph, createWorldPatchApplier, decodePng, definePresentationBindings, definePresentationSequence, defineProductionScenario, encodePng, encodePngDataUrl, evaluatePresentationBindings, fnv1aHex, formatFrameBenchmarkResult, getHeadlessSurface, imageDataFromPngDataUrl, installHeadlessCanvas, isHostOwnedAudioEventKind, isSelectionDecisionKind, isSelectionReasonCode, jobEventContracts, localizeProductionScenarioFailure, makeImageData, paintingPortal, parseAudioCueSnapshot, presentationBindingEventContracts, presentationSequenceEventContracts, productionScenarioEventContracts, recordSelectionDecision, replayExportedTrace, setDefaultGlyphAtlas, shouldUpdateGolden, worldGraphEventContracts, worldPatchEventContracts, writeComposedFrame, writeVisualArtifacts };