@adea-ai/spatial 0.111.0 → 0.113.0

package/README.md

@@ -12,8 +12,6 @@ package.
   `SceneStartPosition`, assigned-props manifests, static-field asset URLs.
 - `manifests.ts`: `hqHomeManifest` / `hqWorkManifest` mount constants (mirrors
   the engine's room layout; the engine is source of truth).
-- `engine.ts`: agent-sim engine manifest discovery and validation
-  (`parseAgentSimEngineManifest`, official web hosts).
 - `scene-spawn.ts`: cross-app spawn encode/parse and portal URL helpers.
 - `telemetry.ts`: `ScenePerformanceReport` schema, validation, envelope, and
   navigation instrumentation.
@@ -23,9 +21,7 @@ package.
   engine's `scenes/sim/assets/`; staged into the web public dir by
   `scripts/sync-assets.mjs`.
 
-The engine manifest validator requires a nonempty version and a same-origin
-JavaScript entry URL. Its version is diagnostic; it does not enforce API or
-version-range compatibility or verify entry bytes. Tracked scene data is a
+Tracked scene data is a
 public mirror, not proof that every file matches a particular private source
 revision or distributed pack. Manifest and payload acceptance need separate
 checks against the intended pack.
@@ -81,6 +77,11 @@ own: callers pass `MessageEvent`-shaped values in and post through `postToFrame`
   frame says so, and
   `describeSimAvailability` gives truthful copy that states Chat and Dev are not affected.
 
+- **Scene channel** (`scene.ts`): feeds the running engine the workspace scene Virtual view draws,
+  as a full snapshot and then diffs against the last revision the engine acknowledged, one revision in
+  flight, with `frame.scene.ack` / `nack` / `perf` back. `createSimSceneFeed` is the host side and
+  `parseHostSceneMessage` the engine's validator. Spec: `docs/specs/sim-bridge-scene.md`.
+
 Not part of this package: the hosted entry, the backend endpoints, the private backing
 origin that authorizes assets before serving cached responses, and any credentials or
 deployment. Those are separate work.

package/dist/index.d.ts

@@ -1,5 +1,4 @@
 export * from './asset-manifests';
-export { agentSimEngineManifestUrl, isLocalDevHost, isOfficialAgentSimWebOrigin, parseAgentSimEngineManifest, OFFICIAL_AGENT_SIM_WEB_HOSTS, type AgentSimEngineManifest, type AgentSimEngineSurface, } from './engine';
 export { hqHomeManifest, hqWorkManifest } from './manifests';
 export { appRouteHref, encodeSceneStartPosition, portalNavigationHref, readSceneStartPosition, type PortalNavigation, type SceneApp, } from './scene-spawn';
 export { createSceneTelemetryEnvelope, MAX_SCENE_TELEMETRY_BYTES, onRouterTransitionStart, parseScenePerformanceReport, recordNavigation, SCENE_TELEMETRY_LOG_PREFIX, type SceneNavigationType, type ScenePerformanceReport, type SceneRuntimeStats, type SceneTelemetryEnvelope, } from './telemetry';

package/dist/index.js

@@ -1,6 +1,5 @@
 import { isSerializedSimCharacter } from './sim-bridge/character';
 export * from './asset-manifests';
-export { agentSimEngineManifestUrl, isLocalDevHost, isOfficialAgentSimWebOrigin, parseAgentSimEngineManifest, OFFICIAL_AGENT_SIM_WEB_HOSTS, } from './engine';
 export { hqHomeManifest, hqWorkManifest } from './manifests';
 export { appRouteHref, encodeSceneStartPosition, portalNavigationHref, readSceneStartPosition, } from './scene-spawn';
 export { createSceneTelemetryEnvelope, MAX_SCENE_TELEMETRY_BYTES, onRouterTransitionStart, parseScenePerformanceReport, recordNavigation, SCENE_TELEMETRY_LOG_PREFIX, } from './telemetry';

package/dist/sim-bridge/index.d.ts

@@ -6,3 +6,4 @@ export * from './messages';
 export * from './origin';
 export * from './save-client';
 export * from './service';
+export * from './scene';

package/dist/sim-bridge/index.js

@@ -6,3 +6,4 @@ export * from './messages';
 export * from './origin';
 export * from './save-client';
 export * from './service';
+export * from './scene';

package/dist/sim-bridge/messages.d.ts

@@ -1,6 +1,7 @@
 import type { OriginAllowlist } from './origin';
 import { type SimSurface } from './launch';
 import { type SimUnavailableReason } from './availability';
+import { type SimFrameSceneMessage } from './scene';
 /**
  * Versioned message schema between the Adea host window and the hosted Agent Sim frame.
  *
@@ -55,7 +56,8 @@ export type SimFrameRequestMessage = Readonly<{
         character: string;
     }>;
 }>;
-export type SimFrameMessage = SimFrameStatusMessage | SimFrameRequestMessage;
+/** The scene channel's acknowledgements, refusals and measurements (see `scene.ts`). */
+export type SimFrameMessage = SimFrameStatusMessage | SimFrameRequestMessage | SimFrameSceneMessage;
 export type SimHostMessage = Readonly<{
     type: 'host.launch';
     payload: Readonly<{

package/dist/sim-bridge/messages.js

@@ -2,6 +2,7 @@ import { boundedString, isPlainRecord, strictRecord } from './record';
 import { SIM_SURFACES } from './launch';
 import { parseSimCharacterValue } from './character';
 import { SIM_UNAVAILABLE_REASONS } from './availability';
+import { parseFrameScenePayload } from './scene';
 /**
  * Versioned message schema between the Adea host window and the hosted Agent Sim frame.
  *
@@ -142,6 +143,12 @@ export function parseFrameMessage(event, context) {
                 ? { ok: true, message: { type, payload: { requestId, character } } }
                 : fail('invalid_payload');
         }
+        case 'frame.scene.ack':
+        case 'frame.scene.nack':
+        case 'frame.scene.perf': {
+            const message = parseFrameScenePayload(type, payload);
+            return message ? { ok: true, message } : fail('invalid_payload');
+        }
         default:
             return fail('unknown_type');
     }

package/dist/sim-bridge/scene.d.ts

@@ -0,0 +1,191 @@
+import type { OriginAllowlist } from './origin';
+import { type SimMessageEventLike } from './messages';
+/**
+ * The workspace scene channel of the Agent Sim bridge (M26, #24, #25, #489, #27). The host feeds
+ * the engine the workspace scene that Virtual view already draws: areas, agents, lead turn and
+ * child-job markers, and lead routes, as a full snapshot and then as diffs against the last
+ * revision the engine acknowledged. The engine renders it and never writes it back: there is no
+ * scene message from the frame other than an acknowledgement, a refusal and a measurement.
+ *
+ * Spec: docs/specs/sim-bridge-scene.md. Rules the code holds:
+ * - Scene messages share the bridge envelope (channel, version, per-mount bridgeId) and its
+ *   origin/source checks, with their own size budget (`MAX_SCENE_MESSAGE_BYTES`).
+ * - One revision is in flight at a time. While it is unacknowledged, newer scene states coalesce:
+ *   the next diff is computed from the acknowledged state to the newest one.
+ * - A diff names the revision it applies to. The engine refuses a diff whose base is not its
+ *   current revision (`revision_gap`), and the host answers with a full snapshot.
+ * - An ack that names any revision other than the one in flight is ignored.
+ * - No ack within `ackTimeoutMs`, an `invalid` or `too_large` refusal, or a gap, resends a full
+ *   snapshot, backing off; `busy` waits `retryAfterMs` (bounded) and resends; `version_unsupported`
+ *   stops the feed.
+ */
+export declare const SIM_SCENE_VERSION = 1;
+/** A scene message, JSON-encoded, may not exceed this. Snapshots are split into parts. */
+export declare const MAX_SCENE_MESSAGE_BYTES: number;
+export declare const MAX_SCENE_ENTITIES_PER_MESSAGE = 200;
+/** The largest scene the host transmits or records as acknowledged. */
+export declare const MAX_SCENE_ENTITIES = 5000;
+export declare const SIM_SCENE_KINDS: readonly ['workspace', 'area', 'agent', 'turn', 'child_job', 'route'];
+export type SimSceneKind = (typeof SIM_SCENE_KINDS)[number];
+export declare const SIM_SCENE_STATUSES: readonly ['error', 'awaiting_input', 'working', 'queued', 'offline', 'unavailable', 'idle', 'completed', 'cancelled', 'archived'];
+export type SimSceneStatus = (typeof SIM_SCENE_STATUSES)[number];
+export declare const SIM_SCENE_ANIMATIONS: readonly ['rest', 'work', 'wait', 'alert', 'celebrate', 'sleep'];
+export type SimSceneAnimation = (typeof SIM_SCENE_ANIMATIONS)[number];
+export declare const SIM_SCENE_TONES: readonly ['neutral', 'active', 'attention', 'danger', 'success', 'muted'];
+export type SimSceneTone = (typeof SIM_SCENE_TONES)[number];
+/**
+ * One scene entity on the wire. Ids are the scene graph's stable ids (`agent:<id>`,
+ * `conversation:<id>`, `turn:<intentId>`, ...; a route is `route:<turn id>`), so the same backend
+ * object is the same engine object across reloads. Coordinates are map units: the engine places
+ * its world from them and may scale, but keeps relative placement.
+ */
+export type SimSceneEntity = Readonly<{
+    id: string;
+    kind: SimSceneKind;
+    /** The containing entity; absent only for the workspace. */
+    parentId?: string;
+    label: string;
+    status: SimSceneStatus;
+    animation: SimSceneAnimation;
+    tone: SimSceneTone;
+    /** Areas and the workspace commons. */
+    rect?: Readonly<{
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    }>;
+    /** Agents, turns and child jobs. */
+    at?: Readonly<{
+        x: number;
+        y: number;
+    }>;
+    /** Agents. */
+    role?: 'lead' | 'agent';
+    characterRef?: string;
+    /** No character reference: the engine shows its explicit default character. */
+    fallback?: boolean;
+    /** Routes: from an agent to a turn marker. */
+    from?: string;
+    to?: string;
+    lead?: boolean;
+}>;
+export type SimHostSceneMessage = Readonly<{
+    type: 'host.scene.snapshot';
+    payload: Readonly<{
+        sceneVersion: typeof SIM_SCENE_VERSION;
+        workspaceId: string;
+        revision: number;
+        /** 1-based part of `parts`. The engine applies the snapshot once every part arrived. */
+        part: number;
+        parts: number;
+        entities: readonly SimSceneEntity[];
+    }>;
+}> | Readonly<{
+    type: 'host.scene.diff';
+    payload: Readonly<{
+        sceneVersion: typeof SIM_SCENE_VERSION;
+        workspaceId: string;
+        baseRevision: number;
+        revision: number;
+        upserts: readonly SimSceneEntity[];
+        removes: readonly string[];
+    }>;
+}>;
+export declare const SIM_SCENE_REFUSALS: readonly ['revision_gap', 'invalid', 'too_large', 'version_unsupported', 'busy'];
+export type SimSceneRefusal = (typeof SIM_SCENE_REFUSALS)[number];
+/** What the engine measured for the scene, for #27's budgets. Durations in ms, memory in bytes. */
+export type SimScenePerf = Readonly<{
+    revision: number;
+    sampleWindowMs: number;
+    frames: number;
+    frameP50Ms: number;
+    frameP95Ms: number;
+    frameMaxMs: number;
+    /** Frames over 50 ms in the window. */
+    longFrames: number;
+    /** From the first snapshot part to the first frame drawn with it. */
+    loadMs: number;
+    /** How long the last applied revision took to apply. */
+    applyMs: number;
+    entities: number;
+    /** `performance.memory.usedJSHeapSize` where the browser exposes it. */
+    heapBytes?: number;
+    /** The renderer's own estimate of GPU memory (geometries + textures), when it keeps one. */
+    gpuBytes?: number;
+}>;
+export type SimFrameSceneMessage = Readonly<{
+    type: 'frame.scene.ack';
+    payload: Readonly<{
+        revision: number;
+    }>;
+}> | Readonly<{
+    type: 'frame.scene.nack';
+    payload: Readonly<{
+        revision: number;
+        code: SimSceneRefusal;
+        retryAfterMs?: number;
+    }>;
+}> | Readonly<{
+    type: 'frame.scene.perf';
+    payload: SimScenePerf;
+}>;
+/** Reads the payload of a `frame.scene.*` message; null when it is not exactly that shape. */
+export declare function parseFrameScenePayload(type: string, payload: unknown): SimFrameSceneMessage | null;
+type PostTarget = Readonly<{
+    postMessage(message: unknown, targetOrigin: string): void;
+}>;
+/** Host to frame, for scene messages. Same origin rule as `postToFrame`, and a size bound. */
+export declare function postSceneToFrame(frameWindow: PostTarget, frameOrigin: string, origins: OriginAllowlist, bridgeId: string, message: SimHostSceneMessage): void;
+export type SimSceneParseFailure = 'origin_refused' | 'source_mismatch' | 'not_a_scene_message' | 'bridge_mismatch' | 'version_unsupported' | 'too_large' | 'invalid';
+/**
+ * Engine side: accepts a host scene message only from the embedding window at its exact origin,
+ * on this mount's bridge id, in a supported scene version, within budget and with every entity in
+ * shape. The engine answers `invalid`, `too_large` or `version_unsupported` with a `nack`.
+ */
+export declare function parseHostSceneMessage(event: SimMessageEventLike, context: Readonly<{
+    parentOrigin: string;
+    parentWindow: unknown;
+    bridgeId: string;
+}>): Readonly<{
+    ok: true;
+    message: SimHostSceneMessage;
+}> | Readonly<{
+    ok: false;
+    reason: SimSceneParseFailure;
+}>;
+export type SimSceneFeedState = 'idle' | 'sending' | 'synced' | 'backing_off' | 'stopped' | 'disposed';
+export type SimSceneFeedStats = Readonly<{
+    state: SimSceneFeedState;
+    /** The revision the engine last acknowledged; 0 before the first. */
+    ackedRevision: number;
+    snapshots: number;
+    diffs: number;
+    timeouts: number;
+    refusals: number;
+    /** Acks naming a revision that was not in flight. */
+    ignoredAcks: number;
+    lastPerf: SimScenePerf | null;
+}>;
+export type SimSceneFeedOptions = Readonly<{
+    workspaceId: string;
+    send(message: SimHostSceneMessage): void;
+    onPerf?(perf: SimScenePerf): void;
+    ackTimeoutMs?: number;
+    /** Schedules `run` after `ms` and returns a canceller. */
+    schedule?: (run: () => void, ms: number) => () => void;
+}>;
+export type SimSceneFeed = Readonly<{
+    /** The newest scene. It is sent now, or coalesced into the next send after the pending ack. */
+    update(entities: readonly SimSceneEntity[]): void;
+    /** A validated `frame.scene.*` message from the current frame. */
+    receive(message: SimFrameSceneMessage): void;
+    stats(): SimSceneFeedStats;
+    dispose(): void;
+}>;
+/**
+ * The host side of the scene channel: keeps what the engine acknowledged, sends one revision at a
+ * time, and recovers from refusals, gaps and silence by resending a full snapshot with backoff.
+ */
+export declare function createSimSceneFeed(options: SimSceneFeedOptions): SimSceneFeed;
+export {};