@adea-ai/spatial 0.95.0 → 0.97.0

package/dist/index.d.ts

@@ -8,6 +8,8 @@ export declare const DEFAULT_CHARACTER_ID = "configurable";
 /**
  * Shell-side character param check. The engine validates against its
  * reference/preset catalogs on mount; the shell only needs a plausible
- * non-empty value to thread through.
+ * non-empty value to thread through. A serialized customization
+ * (`character:v1:` and 13 slots, 157 characters by default) is checked by the
+ * bridge's structural parser instead of the short-id length rule.
  */
 export declare function isPlausibleCharacterId(value: string | undefined): value is string;

package/dist/index.js

@@ -1,3 +1,4 @@
+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';
@@ -8,8 +9,12 @@ export const DEFAULT_CHARACTER_ID = configurableCharacterId;
 /**
  * Shell-side character param check. The engine validates against its
  * reference/preset catalogs on mount; the shell only needs a plausible
- * non-empty value to thread through.
+ * non-empty value to thread through. A serialized customization
+ * (`character:v1:` and 13 slots, 157 characters by default) is checked by the
+ * bridge's structural parser instead of the short-id length rule.
  */
 export function isPlausibleCharacterId(value) {
-    return typeof value === 'string' && value.length > 0 && value.length <= 128;
+    if (typeof value !== 'string' || value.length === 0)
+        return false;
+    return value.length <= 128 || isSerializedSimCharacter(value);
 }

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

@@ -1,4 +1,4 @@
-import type { SimFrameMessage } from './messages';
+import type { SimFrameStatusMessage } from './messages';
 import type { SimLaunchGrant } from './launch';
 /**
  * What the host knows about a hosted Agent Sim launch, as a pure state machine. The host shows only
@@ -59,7 +59,7 @@ Readonly<{
 }> | Readonly<{
     type: 'frame';
     attempt: number;
-    message: SimFrameMessage;
+    message: SimFrameStatusMessage;
     now: number;
 }> | Readonly<{
     type: 'timeout';

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

@@ -0,0 +1,17 @@
+/**
+ * The character value the bridge carries in `host.launch` and `frame.character.save`.
+ *
+ * Two forms, both finite and structurally checked. The bridge never learns the private part
+ * catalog: slot contents are bounded opaque ids and the engine keeps validating membership.
+ *
+ * 1. A catalog id, such as `configurable`.
+ * 2. `character:v1:` followed by exactly 13 `|`-separated slots in `SIM_CHARACTER_SLOTS` order.
+ *    An empty slot is `-`, and `body` is required.
+ */
+export declare const SIM_CHARACTER_SLOTS: readonly ['body', 'ears', 'face', 'hair', 'hat', 'top', 'bottom', 'shoes', 'socks', 'glasses', 'gloves', 'accessory', 'costume'];
+export declare const SIM_SERIALIZED_CHARACTER_PREFIX = "character:v1:";
+/** The audited serializer's longest value is 251 characters; this leaves headroom, not slack. */
+export declare const MAX_SIM_SERIALIZED_CHARACTER_LENGTH = 384;
+export declare function isSerializedSimCharacter(value: unknown): value is string;
+/** The value when it is a catalog id or a well-formed serialized character; otherwise null. */
+export declare function parseSimCharacterValue(value: unknown): string | null;

package/dist/sim-bridge/character.js

@@ -0,0 +1,49 @@
+/**
+ * The character value the bridge carries in `host.launch` and `frame.character.save`.
+ *
+ * Two forms, both finite and structurally checked. The bridge never learns the private part
+ * catalog: slot contents are bounded opaque ids and the engine keeps validating membership.
+ *
+ * 1. A catalog id, such as `configurable`.
+ * 2. `character:v1:` followed by exactly 13 `|`-separated slots in `SIM_CHARACTER_SLOTS` order.
+ *    An empty slot is `-`, and `body` is required.
+ */
+export const SIM_CHARACTER_SLOTS = [
+    'body',
+    'ears',
+    'face',
+    'hair',
+    'hat',
+    'top',
+    'bottom',
+    'shoes',
+    'socks',
+    'glasses',
+    'gloves',
+    'accessory',
+    'costume',
+];
+export const SIM_SERIALIZED_CHARACTER_PREFIX = 'character:v1:';
+/** The audited serializer's longest value is 251 characters; this leaves headroom, not slack. */
+export const MAX_SIM_SERIALIZED_CHARACTER_LENGTH = 384;
+const CATALOG_ID = /^[A-Za-z0-9_.:-]{1,64}$/;
+const SLOT_PART_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,47}$/;
+const EMPTY_SLOT = '-';
+export function isSerializedSimCharacter(value) {
+    if (typeof value !== 'string' ||
+        value.length > MAX_SIM_SERIALIZED_CHARACTER_LENGTH ||
+        !value.startsWith(SIM_SERIALIZED_CHARACTER_PREFIX))
+        return false;
+    const slots = value.slice(SIM_SERIALIZED_CHARACTER_PREFIX.length).split('|');
+    if (slots.length !== SIM_CHARACTER_SLOTS.length)
+        return false;
+    return slots.every((slot, index) => (slot === EMPTY_SLOT ? index !== 0 : SLOT_PART_ID.test(slot)));
+}
+/** The value when it is a catalog id or a well-formed serialized character; otherwise null. */
+export function parseSimCharacterValue(value) {
+    if (typeof value !== 'string')
+        return null;
+    if (value.startsWith('character:'))
+        return isSerializedSimCharacter(value) ? value : null;
+    return CATALOG_ID.test(value) ? value : null;
+}

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

@@ -1,6 +1,8 @@
 export * from './availability';
+export * from './character';
 export * from './cookie';
 export * from './launch';
 export * from './messages';
 export * from './origin';
+export * from './save-client';
 export * from './service';

package/dist/sim-bridge/index.js

@@ -1,6 +1,8 @@
 export * from './availability';
+export * from './character';
 export * from './cookie';
 export * from './launch';
 export * from './messages';
 export * from './origin';
+export * from './save-client';
 export * from './service';

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

@@ -17,7 +17,13 @@ export declare const SIM_FRAME_STATES: readonly ['loading', 'running', 'unavaila
 export type SimFrameState = (typeof SIM_FRAME_STATES)[number];
 export declare const SIM_FRAME_ERRORS: readonly ['launch_rejected', 'asset_unavailable', 'engine_failed', 'bridge_incompatible'];
 export type SimFrameError = (typeof SIM_FRAME_ERRORS)[number];
-export type SimFrameMessage = Readonly<{
+/** Where HQ may send the host: the designers only. A designer returns with `frame.close`. */
+export declare const SIM_NAVIGATE_TARGETS: readonly ['room-designer', 'character-designer'];
+export type SimNavigateTarget = (typeof SIM_NAVIGATE_TARGETS)[number];
+export declare const SIM_SAVE_FAILURES: readonly ['refused', 'failed', 'timeout'];
+export type SimSaveFailure = (typeof SIM_SAVE_FAILURES)[number];
+/** What the frame reports about its own launch; the pure launch reducer consumes only these. */
+export type SimFrameStatusMessage = Readonly<{
     type: 'frame.ready';
     payload: Readonly<Record<string, never>>;
 }> | Readonly<{
@@ -35,6 +41,21 @@ export type SimFrameMessage = Readonly<{
         code: SimFrameError;
     }>;
 }>;
+/** Closed requests the frame may make of the host. Each is answered or ends the attempt. */
+export type SimFrameRequestMessage = Readonly<{
+    type: 'frame.navigate';
+    payload: Readonly<{
+        requestId: string;
+        target: SimNavigateTarget;
+    }>;
+}> | Readonly<{
+    type: 'frame.character.save';
+    payload: Readonly<{
+        requestId: string;
+        character: string;
+    }>;
+}>;
+export type SimFrameMessage = SimFrameStatusMessage | SimFrameRequestMessage;
 export type SimHostMessage = Readonly<{
     type: 'host.launch';
     payload: Readonly<{
@@ -47,6 +68,13 @@ export type SimHostMessage = Readonly<{
 }> | Readonly<{
     type: 'host.dispose';
     payload: Readonly<Record<string, never>>;
+}> | Readonly<{
+    type: 'host.character.save.result';
+    payload: Readonly<{
+        requestId: string;
+        saved: boolean;
+        reason?: SimSaveFailure;
+    }>;
 }>;
 export type SimBridgeFailure = 'origin_refused' | 'source_mismatch' | 'not_a_bridge_message' | 'version_unsupported' | 'bridge_mismatch' | 'unknown_type' | 'invalid_payload' | 'too_large';
 export type SimBridgeResult<T> = Readonly<{

package/dist/sim-bridge/messages.js

@@ -1,5 +1,6 @@
 import { boundedString, isPlainRecord, strictRecord } from './record';
 import { SIM_SURFACES } from './launch';
+import { parseSimCharacterValue } from './character';
 import { SIM_UNAVAILABLE_REASONS } from './availability';
 /**
  * Versioned message schema between the Adea host window and the hosted Agent Sim frame.
@@ -15,7 +16,7 @@ export const SIM_BRIDGE_VERSION = 1;
 export const MAX_SIM_MESSAGE_BYTES = 2048;
 const BRIDGE_ID = /^[A-Za-z0-9_-]{16,64}$/;
 const LAUNCH_CODE = /^[A-Za-z0-9_-]{32,128}$/;
-const CHARACTER_ID = /^[A-Za-z0-9_.:-]{1,64}$/;
+const REQUEST_ID = /^[A-Za-z0-9_-]{1,32}$/;
 export const SIM_FRAME_STATES = ['loading', 'running', 'unavailable', 'offline'];
 export const SIM_FRAME_ERRORS = [
     'launch_rejected',
@@ -23,6 +24,9 @@ export const SIM_FRAME_ERRORS = [
     'engine_failed',
     'bridge_incompatible',
 ];
+/** Where HQ may send the host: the designers only. A designer returns with `frame.close`. */
+export const SIM_NAVIGATE_TARGETS = ['room-designer', 'character-designer'];
+export const SIM_SAVE_FAILURES = ['refused', 'failed', 'timeout'];
 const ENVELOPE_KEYS = ['channel', 'version', 'bridgeId', 'type', 'payload'];
 function envelope(event, bridgeId) {
     const data = strictRecord(event.data, ENVELOPE_KEYS);
@@ -122,6 +126,22 @@ export function parseFrameMessage(event, context) {
             const code = SIM_FRAME_ERRORS.find((item) => item === body?.code);
             return code ? { ok: true, message: { type, payload: { code } } } : fail('invalid_payload');
         }
+        case 'frame.navigate': {
+            const body = strictRecord(payload, ['requestId', 'target']);
+            const requestId = boundedString(body?.requestId, REQUEST_ID);
+            const target = SIM_NAVIGATE_TARGETS.find((item) => item === body?.target);
+            return requestId && target
+                ? { ok: true, message: { type, payload: { requestId, target } } }
+                : fail('invalid_payload');
+        }
+        case 'frame.character.save': {
+            const body = strictRecord(payload, ['requestId', 'character']);
+            const requestId = boundedString(body?.requestId, REQUEST_ID);
+            const character = parseSimCharacterValue(body?.character);
+            return requestId && character
+                ? { ok: true, message: { type, payload: { requestId, character } } }
+                : fail('invalid_payload');
+        }
         default:
             return fail('unknown_type');
     }
@@ -148,7 +168,7 @@ export function parseHostMessage(event, context) {
             const code = boundedString(body?.code, LAUNCH_CODE);
             const surface = SIM_SURFACES.find((item) => item === body?.surface);
             const expiresAt = body?.expiresAt;
-            const character = body && 'character' in body ? boundedString(body.character, CHARACTER_ID) : undefined;
+            const character = body && 'character' in body ? parseSimCharacterValue(body.character) : undefined;
             if (!body ||
                 !code ||
                 !surface ||
@@ -164,6 +184,23 @@ export function parseHostMessage(event, context) {
                 },
             };
         }
+        case 'host.character.save.result': {
+            const body = strictRecord(payload, ['requestId', 'saved'], ['reason']);
+            const requestId = boundedString(body?.requestId, REQUEST_ID);
+            if (!body || !requestId || typeof body.saved !== 'boolean')
+                return fail('invalid_payload');
+            const reason = SIM_SAVE_FAILURES.find((item) => item === body.reason);
+            // A failure names its reason; a success has none.
+            if (body.saved ? 'reason' in body : !reason)
+                return fail('invalid_payload');
+            return {
+                ok: true,
+                message: {
+                    type,
+                    payload: reason ? { requestId, saved: false, reason } : { requestId, saved: true },
+                },
+            };
+        }
         default:
             return fail('unknown_type');
     }

package/dist/sim-bridge/save-client.d.ts

@@ -0,0 +1,25 @@
+import type { SimFrameRequestMessage, SimHostMessage } from './messages';
+/**
+ * Frame side of the acknowledged character save.
+ *
+ * `save` resolves `true` only when the host answers the very request it sent with
+ * `saved: true`. A refusal, a failure, a timeout, a host dispose, `dispose()`, a second save while
+ * one is open, an invalid value, a post that throws, and a late or mismatched answer all resolve
+ * `false`, so the engine never shows a saved value the host did not commit.
+ */
+export type CharacterSaveClient = Readonly<{
+    save(character: string): Promise<boolean>;
+    /** Feed every parsed host message in; unrelated ones are ignored. */
+    receive(message: SimHostMessage): void;
+    /** Fails any open save. Call when the frame is torn down. */
+    dispose(): void;
+}>;
+export type CharacterSaveClientOptions = Readonly<{
+    post(message: SimFrameRequestMessage): void;
+    /** Longer than the host's own timeout so the host's answer normally arrives first. */
+    timeoutMs?: number;
+    mintRequestId?: () => string;
+    schedule?: (run: () => void, ms: number) => () => void;
+}>;
+export declare const DEFAULT_SAVE_CLIENT_TIMEOUT_MS = 8000;
+export declare function createCharacterSaveClient(options: CharacterSaveClientOptions): CharacterSaveClient;

package/dist/sim-bridge/save-client.js

@@ -0,0 +1,55 @@
+import { parseSimCharacterValue } from './character';
+export const DEFAULT_SAVE_CLIENT_TIMEOUT_MS = 8_000;
+export function createCharacterSaveClient(options) {
+    const timeoutMs = options.timeoutMs ?? DEFAULT_SAVE_CLIENT_TIMEOUT_MS;
+    const schedule = options.schedule ??
+        ((run, ms) => {
+            const id = setTimeout(run, ms);
+            return () => clearTimeout(id);
+        });
+    let counter = 0;
+    const mint = options.mintRequestId ?? (() => `save${++counter}`);
+    let open = null;
+    let disposed = false;
+    function failOpen() {
+        open?.settle(false);
+    }
+    return {
+        save(character) {
+            if (disposed || open || parseSimCharacterValue(character) === null)
+                return Promise.resolve(false);
+            const requestId = mint();
+            return new Promise((resolve) => {
+                const cancel = schedule(() => failOpen(), timeoutMs);
+                const entry = {
+                    requestId,
+                    settle(saved) {
+                        if (open !== entry)
+                            return;
+                        open = null;
+                        cancel();
+                        resolve(saved);
+                    },
+                };
+                open = entry;
+                try {
+                    options.post({ type: 'frame.character.save', payload: { requestId, character } });
+                }
+                catch {
+                    entry.settle(false);
+                }
+            });
+        },
+        receive(message) {
+            if (message.type === 'host.dispose')
+                failOpen();
+            else if (message.type === 'host.character.save.result' &&
+                open?.requestId === message.payload.requestId)
+                open.settle(message.payload.saved);
+        },
+        dispose() {
+            disposed = true;
+            failOpen();
+        },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adea-ai/spatial",
-  "version": "0.95.0",
+  "version": "0.97.0",
   "description": "Scene and asset manifest contracts plus the shell-to-engine spatial protocol for Adea workspaces: scene mount manifests, spawn URL helpers, and scene telemetry schemas. Pure types — no rendering, no binaries.",
   "keywords": [
     "assets",
@@ -44,6 +44,6 @@
     "build": "tsc -p tsconfig.json",
     "dev": "tsc -p tsconfig.json --watch --preserveWatchOutput",
     "test": "bun test test/*.test.ts",
-    "typecheck": "tsc -p tsconfig.json --noEmit"
+    "typecheck": "bun check -p tsconfig.json"
   }
 }

package/src/index.ts

@@ -1,3 +1,5 @@
+import { isSerializedSimCharacter } from './sim-bridge/character'
+
 export * from './asset-manifests'
 export {
   agentSimEngineManifestUrl,
@@ -35,8 +37,11 @@ export const DEFAULT_CHARACTER_ID = configurableCharacterId
 /**
  * Shell-side character param check. The engine validates against its
  * reference/preset catalogs on mount; the shell only needs a plausible
- * non-empty value to thread through.
+ * non-empty value to thread through. A serialized customization
+ * (`character:v1:` and 13 slots, 157 characters by default) is checked by the
+ * bridge's structural parser instead of the short-id length rule.
  */
 export function isPlausibleCharacterId(value: string | undefined): value is string {
-  return typeof value === 'string' && value.length > 0 && value.length <= 128
+  if (typeof value !== 'string' || value.length === 0) return false
+  return value.length <= 128 || isSerializedSimCharacter(value)
 }

package/src/sim-bridge/availability.ts

@@ -1,4 +1,4 @@
-import type { SimFrameMessage } from './messages'
+import type { SimFrameStatusMessage } from './messages'
 import type { SimLaunchGrant } from './launch'
 
 /**
@@ -47,7 +47,7 @@ export type SimLaunchEvent =
   | Readonly<{ type: 'start'; online?: boolean }>
   /** The backend's parsed reply for `attempt`; `null` is a reply that failed validation. */
   | Readonly<{ type: 'grant'; attempt: number; grant: SimLaunchGrant | null }>
-  | Readonly<{ type: 'frame'; attempt: number; message: SimFrameMessage; now: number }>
+  | Readonly<{ type: 'frame'; attempt: number; message: SimFrameStatusMessage; now: number }>
   | Readonly<{ type: 'timeout'; attempt: number }>
   | Readonly<{ type: 'offline' }>
   | Readonly<{ type: 'dispose' }>
@@ -76,7 +76,11 @@ function unavailable(attempt: number, reason: SimUnavailableReason): SimLaunchSt
   return { state: { phase: 'unavailable', attempt, reason } }
 }
 
-function reduceFrame(state: SimLaunchState, message: SimFrameMessage, now: number): SimLaunchStep {
+function reduceFrame(
+  state: SimLaunchState,
+  message: SimFrameStatusMessage,
+  now: number
+): SimLaunchStep {
   const { attempt } = state
   switch (message.type) {
     case 'frame.ready': {

package/src/sim-bridge/character.ts

@@ -0,0 +1,53 @@
+/**
+ * The character value the bridge carries in `host.launch` and `frame.character.save`.
+ *
+ * Two forms, both finite and structurally checked. The bridge never learns the private part
+ * catalog: slot contents are bounded opaque ids and the engine keeps validating membership.
+ *
+ * 1. A catalog id, such as `configurable`.
+ * 2. `character:v1:` followed by exactly 13 `|`-separated slots in `SIM_CHARACTER_SLOTS` order.
+ *    An empty slot is `-`, and `body` is required.
+ */
+
+export const SIM_CHARACTER_SLOTS = [
+  'body',
+  'ears',
+  'face',
+  'hair',
+  'hat',
+  'top',
+  'bottom',
+  'shoes',
+  'socks',
+  'glasses',
+  'gloves',
+  'accessory',
+  'costume',
+] as const
+
+export const SIM_SERIALIZED_CHARACTER_PREFIX = 'character:v1:'
+/** The audited serializer's longest value is 251 characters; this leaves headroom, not slack. */
+export const MAX_SIM_SERIALIZED_CHARACTER_LENGTH = 384
+
+const CATALOG_ID = /^[A-Za-z0-9_.:-]{1,64}$/
+const SLOT_PART_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,47}$/
+const EMPTY_SLOT = '-'
+
+export function isSerializedSimCharacter(value: unknown): value is string {
+  if (
+    typeof value !== 'string' ||
+    value.length > MAX_SIM_SERIALIZED_CHARACTER_LENGTH ||
+    !value.startsWith(SIM_SERIALIZED_CHARACTER_PREFIX)
+  )
+    return false
+  const slots = value.slice(SIM_SERIALIZED_CHARACTER_PREFIX.length).split('|')
+  if (slots.length !== SIM_CHARACTER_SLOTS.length) return false
+  return slots.every((slot, index) => (slot === EMPTY_SLOT ? index !== 0 : SLOT_PART_ID.test(slot)))
+}
+
+/** The value when it is a catalog id or a well-formed serialized character; otherwise null. */
+export function parseSimCharacterValue(value: unknown): string | null {
+  if (typeof value !== 'string') return null
+  if (value.startsWith('character:')) return isSerializedSimCharacter(value) ? value : null
+  return CATALOG_ID.test(value) ? value : null
+}

package/src/sim-bridge/index.ts

@@ -1,6 +1,8 @@
 export * from './availability'
+export * from './character'
 export * from './cookie'
 export * from './launch'
 export * from './messages'
 export * from './origin'
+export * from './save-client'
 export * from './service'

package/src/sim-bridge/messages.ts

@@ -1,6 +1,7 @@
 import { boundedString, isPlainRecord, strictRecord } from './record'
 import type { OriginAllowlist } from './origin'
 import { SIM_SURFACES, type SimSurface } from './launch'
+import { parseSimCharacterValue } from './character'
 import { SIM_UNAVAILABLE_REASONS, type SimUnavailableReason } from './availability'
 
 /**
@@ -19,7 +20,7 @@ export const MAX_SIM_MESSAGE_BYTES = 2048
 
 const BRIDGE_ID = /^[A-Za-z0-9_-]{16,64}$/
 const LAUNCH_CODE = /^[A-Za-z0-9_-]{32,128}$/
-const CHARACTER_ID = /^[A-Za-z0-9_.:-]{1,64}$/
+const REQUEST_ID = /^[A-Za-z0-9_-]{1,32}$/
 
 export const SIM_FRAME_STATES = ['loading', 'running', 'unavailable', 'offline'] as const
 export type SimFrameState = (typeof SIM_FRAME_STATES)[number]
@@ -31,7 +32,14 @@ export const SIM_FRAME_ERRORS = [
 ] as const
 export type SimFrameError = (typeof SIM_FRAME_ERRORS)[number]
 
-export type SimFrameMessage =
+/** Where HQ may send the host: the designers only. A designer returns with `frame.close`. */
+export const SIM_NAVIGATE_TARGETS = ['room-designer', 'character-designer'] as const
+export type SimNavigateTarget = (typeof SIM_NAVIGATE_TARGETS)[number]
+export const SIM_SAVE_FAILURES = ['refused', 'failed', 'timeout'] as const
+export type SimSaveFailure = (typeof SIM_SAVE_FAILURES)[number]
+
+/** What the frame reports about its own launch; the pure launch reducer consumes only these. */
+export type SimFrameStatusMessage =
   | Readonly<{ type: 'frame.ready'; payload: Readonly<Record<string, never>> }>
   | Readonly<{
       type: 'frame.state'
@@ -40,6 +48,19 @@ export type SimFrameMessage =
   | Readonly<{ type: 'frame.close'; payload: Readonly<Record<string, never>> }>
   | Readonly<{ type: 'frame.error'; payload: Readonly<{ code: SimFrameError }> }>
 
+/** Closed requests the frame may make of the host. Each is answered or ends the attempt. */
+export type SimFrameRequestMessage =
+  | Readonly<{
+      type: 'frame.navigate'
+      payload: Readonly<{ requestId: string; target: SimNavigateTarget }>
+    }>
+  | Readonly<{
+      type: 'frame.character.save'
+      payload: Readonly<{ requestId: string; character: string }>
+    }>
+
+export type SimFrameMessage = SimFrameStatusMessage | SimFrameRequestMessage
+
 export type SimHostMessage =
   | Readonly<{
       type: 'host.launch'
@@ -52,6 +73,10 @@ export type SimHostMessage =
       }>
     }>
   | Readonly<{ type: 'host.dispose'; payload: Readonly<Record<string, never>> }>
+  | Readonly<{
+      type: 'host.character.save.result'
+      payload: Readonly<{ requestId: string; saved: boolean; reason?: SimSaveFailure }>
+    }>
 
 export type SimBridgeFailure =
   | 'origin_refused'
@@ -168,6 +193,22 @@ export function parseFrameMessage(
       const code = SIM_FRAME_ERRORS.find((item) => item === body?.code)
       return code ? { ok: true, message: { type, payload: { code } } } : fail('invalid_payload')
     }
+    case 'frame.navigate': {
+      const body = strictRecord(payload, ['requestId', 'target'])
+      const requestId = boundedString(body?.requestId, REQUEST_ID)
+      const target = SIM_NAVIGATE_TARGETS.find((item) => item === body?.target)
+      return requestId && target
+        ? { ok: true, message: { type, payload: { requestId, target } } }
+        : fail('invalid_payload')
+    }
+    case 'frame.character.save': {
+      const body = strictRecord(payload, ['requestId', 'character'])
+      const requestId = boundedString(body?.requestId, REQUEST_ID)
+      const character = parseSimCharacterValue(body?.character)
+      return requestId && character
+        ? { ok: true, message: { type, payload: { requestId, character } } }
+        : fail('invalid_payload')
+    }
     default:
       return fail('unknown_type')
   }
@@ -203,7 +244,7 @@ export function parseHostMessage(
       const surface = SIM_SURFACES.find((item) => item === body?.surface)
       const expiresAt = body?.expiresAt
       const character =
-        body && 'character' in body ? boundedString(body.character, CHARACTER_ID) : undefined
+        body && 'character' in body ? parseSimCharacterValue(body.character) : undefined
       if (
         !body ||
         !code ||
@@ -221,6 +262,21 @@ export function parseHostMessage(
         },
       }
     }
+    case 'host.character.save.result': {
+      const body = strictRecord(payload, ['requestId', 'saved'], ['reason'])
+      const requestId = boundedString(body?.requestId, REQUEST_ID)
+      if (!body || !requestId || typeof body.saved !== 'boolean') return fail('invalid_payload')
+      const reason = SIM_SAVE_FAILURES.find((item) => item === body.reason)
+      // A failure names its reason; a success has none.
+      if (body.saved ? 'reason' in body : !reason) return fail('invalid_payload')
+      return {
+        ok: true,
+        message: {
+          type,
+          payload: reason ? { requestId, saved: false, reason } : { requestId, saved: true },
+        },
+      }
+    }
     default:
       return fail('unknown_type')
   }

package/src/sim-bridge/save-client.ts

@@ -0,0 +1,87 @@
+import { parseSimCharacterValue } from './character'
+import type { SimFrameRequestMessage, SimHostMessage } from './messages'
+
+/**
+ * Frame side of the acknowledged character save.
+ *
+ * `save` resolves `true` only when the host answers the very request it sent with
+ * `saved: true`. A refusal, a failure, a timeout, a host dispose, `dispose()`, a second save while
+ * one is open, an invalid value, a post that throws, and a late or mismatched answer all resolve
+ * `false`, so the engine never shows a saved value the host did not commit.
+ */
+
+export type CharacterSaveClient = Readonly<{
+  save(character: string): Promise<boolean>
+  /** Feed every parsed host message in; unrelated ones are ignored. */
+  receive(message: SimHostMessage): void
+  /** Fails any open save. Call when the frame is torn down. */
+  dispose(): void
+}>
+
+export type CharacterSaveClientOptions = Readonly<{
+  post(message: SimFrameRequestMessage): void
+  /** Longer than the host's own timeout so the host's answer normally arrives first. */
+  timeoutMs?: number
+  mintRequestId?: () => string
+  schedule?: (run: () => void, ms: number) => () => void
+}>
+
+export const DEFAULT_SAVE_CLIENT_TIMEOUT_MS = 8_000
+
+export function createCharacterSaveClient(
+  options: CharacterSaveClientOptions
+): CharacterSaveClient {
+  const timeoutMs = options.timeoutMs ?? DEFAULT_SAVE_CLIENT_TIMEOUT_MS
+  const schedule =
+    options.schedule ??
+    ((run, ms) => {
+      const id = setTimeout(run, ms)
+      return () => clearTimeout(id)
+    })
+  let counter = 0
+  const mint = options.mintRequestId ?? (() => `save${++counter}`)
+  let open: { requestId: string; settle(saved: boolean): void } | null = null
+  let disposed = false
+
+  function failOpen() {
+    open?.settle(false)
+  }
+
+  return {
+    save(character) {
+      if (disposed || open || parseSimCharacterValue(character) === null)
+        return Promise.resolve(false)
+      const requestId = mint()
+      return new Promise<boolean>((resolve) => {
+        const cancel = schedule(() => failOpen(), timeoutMs)
+        const entry = {
+          requestId,
+          settle(saved: boolean) {
+            if (open !== entry) return
+            open = null
+            cancel()
+            resolve(saved)
+          },
+        }
+        open = entry
+        try {
+          options.post({ type: 'frame.character.save', payload: { requestId, character } })
+        } catch {
+          entry.settle(false)
+        }
+      })
+    },
+    receive(message) {
+      if (message.type === 'host.dispose') failOpen()
+      else if (
+        message.type === 'host.character.save.result' &&
+        open?.requestId === message.payload.requestId
+      )
+        open.settle(message.payload.saved)
+    },
+    dispose() {
+      disposed = true
+      failOpen()
+    },
+  }
+}