@honua/app-platform 0.0.20-alpha.0 → 0.1.1-beta.0

package/scene-workspace/state-sync.d.ts

@@ -0,0 +1,147 @@
+import type { FeatureSelectionTarget, FilterClause } from "../exploration/index.js";
+import type { SceneCameraState, SceneDetailState, SceneTimelineState } from "./types.js";
+export declare const SCENE_STATE_SYNC_KIND: "honua.scene-state-sync";
+export declare const SCENE_STATE_SYNC_VERSION: "1.0";
+export declare const SCENE_STATE_SYNC_SLICES: readonly ["camera", "selection", "filters", "time", "detail", "attribution", "realtime"];
+export type SceneStateSyncSlice = (typeof SCENE_STATE_SYNC_SLICES)[number];
+export type SceneStateSyncRenderer = "maplibre" | "cesium" | "custom";
+export type SceneStateSyncFidelity = "exact" | "equivalent" | "unsupported";
+export interface SceneStateSyncIdentity {
+    readonly sourceId: string;
+    readonly schemaVersion?: string;
+    readonly sourceVersion?: string;
+    readonly planId?: string;
+    readonly planFingerprint?: `sha256:${string}`;
+}
+export interface SceneStateSyncOrigin {
+    readonly applicationId: string;
+    readonly portId: string;
+    readonly renderer: SceneStateSyncRenderer;
+}
+export interface SceneStateSyncMapping {
+    readonly inbound: SceneStateSyncFidelity;
+    readonly outbound: SceneStateSyncFidelity;
+    readonly code: string;
+    readonly message: string;
+}
+export type SceneStateSyncMappings = Readonly<Record<SceneStateSyncSlice, SceneStateSyncMapping>>;
+export interface SceneStateSyncRealtimeValue {
+    readonly status: "idle" | "connecting" | "connected" | "reconnecting" | "disconnected" | "error";
+    readonly freshness: "fresh" | "stale" | "unknown";
+    readonly observedAt?: string;
+    readonly cursorPresent: boolean;
+    readonly lagMs?: number;
+}
+export interface SceneStateSyncAttributionValue {
+    /** Stable attribution identifiers; raw HTML, URLs, and credentials are excluded. */
+    readonly ids: readonly string[];
+}
+export interface SceneStateSyncValueMap {
+    readonly camera: SceneCameraState | undefined;
+    readonly selection: readonly FeatureSelectionTarget[];
+    readonly filters: Readonly<Record<string, FilterClause>>;
+    readonly time: SceneTimelineState;
+    readonly detail: SceneDetailState;
+    readonly attribution: SceneStateSyncAttributionValue;
+    readonly realtime: SceneStateSyncRealtimeValue;
+}
+export type SceneStateSyncInput = {
+    readonly [Slice in SceneStateSyncSlice]: {
+        readonly kind: typeof SCENE_STATE_SYNC_KIND;
+        readonly version: typeof SCENE_STATE_SYNC_VERSION;
+        readonly sequence: number;
+        readonly emittedAt: string;
+        readonly slice: Slice;
+        readonly value: SceneStateSyncValueMap[Slice];
+        readonly identity: SceneStateSyncIdentity;
+        /** Revision being acknowledged after a renderer applied a delivery. */
+        readonly causeRevision?: number;
+    };
+}[SceneStateSyncSlice];
+export type SceneStateSyncEnvelope = {
+    readonly [Slice in SceneStateSyncSlice]: {
+        readonly kind: typeof SCENE_STATE_SYNC_KIND;
+        readonly version: typeof SCENE_STATE_SYNC_VERSION;
+        readonly revision: number;
+        readonly acceptedAt: string;
+        readonly emittedAt: string;
+        readonly slice: Slice;
+        readonly value: SceneStateSyncValueMap[Slice];
+        readonly identity: SceneStateSyncIdentity;
+        readonly origin: SceneStateSyncOrigin;
+        readonly fidelity: SceneStateSyncMapping;
+    };
+}[SceneStateSyncSlice];
+export interface SceneStateSyncDelivery {
+    readonly envelope: SceneStateSyncEnvelope;
+    readonly target: SceneStateSyncOrigin;
+    readonly fidelity: SceneStateSyncMapping;
+}
+export interface SceneStateSyncPort {
+    readonly id: string;
+    readonly renderer: SceneStateSyncRenderer;
+    readonly mappings: SceneStateSyncMappings;
+    subscribe(listener: (event: SceneStateSyncInput) => void, signal: AbortSignal): () => void;
+    apply(delivery: SceneStateSyncDelivery, signal: AbortSignal): void | Promise<void>;
+}
+export type SceneStateSyncDiagnosticCode = "clock-failed" | "stale-update" | "loop-suppressed" | "duplicate-suppressed" | "coalesced" | "unsupported-origin" | "unsupported-target" | "apply-failed" | "port-detached";
+export interface SceneStateSyncDiagnostic {
+    readonly code: SceneStateSyncDiagnosticCode;
+    readonly at: string;
+    readonly applicationId: string;
+    readonly portId: string;
+    readonly slice?: SceneStateSyncSlice;
+    readonly revision?: number;
+    readonly message: string;
+}
+export interface SceneStateSyncSnapshot {
+    readonly kind: typeof SCENE_STATE_SYNC_KIND;
+    readonly version: typeof SCENE_STATE_SYNC_VERSION;
+    readonly applicationId: string;
+    readonly revision: number;
+    readonly values: Readonly<Partial<{
+        readonly [Slice in SceneStateSyncSlice]: SceneStateSyncEnvelope;
+    }>>;
+    readonly diagnostics: readonly SceneStateSyncDiagnostic[];
+}
+export type SceneStateSyncEvent = {
+    readonly type: "state";
+    readonly envelope: SceneStateSyncEnvelope;
+    readonly snapshot: SceneStateSyncSnapshot;
+} | {
+    readonly type: "diagnostic";
+    readonly diagnostic: SceneStateSyncDiagnostic;
+};
+export type SceneStateSyncErrorCode = "invalid-input" | "duplicate-port" | "unknown-port" | "attach-failed" | "disposed" | "dispose-failed";
+export declare class HonuaSceneStateSyncError extends Error {
+    readonly code: SceneStateSyncErrorCode;
+    constructor(code: SceneStateSyncErrorCode, message: string, options?: {
+        readonly cause?: unknown;
+    });
+}
+export interface CreateSceneStateSynchronizerOptions {
+    readonly applicationId: string;
+    readonly ports?: readonly SceneStateSyncPort[];
+    /** Camera/time coalescing window. Defaults to 16 ms; zero uses a microtask. */
+    readonly coalesceMs?: number;
+    readonly maxPorts?: number;
+    readonly maxDiagnostics?: number;
+    readonly now?: () => string;
+    readonly signal?: AbortSignal;
+}
+export interface SceneStateSynchronizer {
+    readonly disposed: boolean;
+    readonly portIds: readonly string[];
+    readonly snapshot: SceneStateSyncSnapshot;
+    attach(port: SceneStateSyncPort): void;
+    attachAll(ports: readonly SceneStateSyncPort[]): void;
+    detach(portId: string): void;
+    subscribe(listener: (event: SceneStateSyncEvent) => void): () => void;
+    flush(): Promise<void>;
+    dispose(): void;
+}
+/** Create one isolated renderer-neutral state synchronization lifecycle. */
+export declare function createSceneStateSynchronizer(options: CreateSceneStateSynchronizerOptions): SceneStateSynchronizer;
+/** Explicit default mapping truth for a renderer; callers may narrow any slice. */
+export declare function defaultSceneStateSyncMappings(renderer: SceneStateSyncRenderer): SceneStateSyncMappings;
+//# sourceMappingURL=state-sync.d.ts.map

package/scene-workspace/state-sync.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-sync.d.ts","sourceRoot":"","sources":["../../../src/scene-workspace/state-sync.ts"],"names":[],"mappings":"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"}