entangled-worlds-orbiters-shared 2.9.0 → 2.10.0

package/src/capabilities/schema.ts

@@ -0,0 +1,164 @@
+/**
+ * Tiny JSON-Schema-subset validator (shared machinery, TypeScript).
+ *
+ * The ONE validator both registries use (supersedes the duplicated
+ * `studio/capabilities/schema.js` + `core/edit/capabilities/schema.ts`). Deliberately NOT a
+ * dependency (no zod/ajv) — the app is bundle-weight sensitive and the house style is
+ * lightweight guard clauses. Each capability carries an `inputSchema` literal in this subset;
+ * the SAME literal is what the future agent layer hands the model as a tool definition, so
+ * there is no second schema language to keep in sync.
+ *
+ * Supported keywords (a pragmatic subset of JSON Schema draft-07):
+ *   type        'object' | 'array' | 'string' | 'number' | 'integer' | 'boolean' | 'null'
+ *               (or an array of those — value matches if it satisfies any)
+ *   properties  per-key subschemas (objects)
+ *   required    array of keys that must be present and not undefined (objects)
+ *   items       subschema applied to every array element
+ *   enum        value must be one of the listed values
+ *   const       value must deep-equal the given value
+ *   nullable    when true, null always passes regardless of type
+ *   minimum / maximum                 numbers
+ *   minLength / maxLength             strings
+ *   minItems / maxItems               arrays
+ *   pattern     string regex source (tested with RegExp)
+ *
+ * A schema with no `type` accepts any value (still honouring enum/const/properties if set).
+ * Unknown keywords are ignored — forward-compatible, never throws on shape it doesn't know.
+ */
+
+import { ValidationError, type SchemaIssue } from './errors.js'
+
+export type JsonType = 'object' | 'array' | 'string' | 'number' | 'integer' | 'boolean' | 'null'
+
+export interface JsonSchema {
+  type?: JsonType | JsonType[]
+  properties?: Record<string, JsonSchema>
+  required?: string[]
+  items?: JsonSchema
+  enum?: unknown[]
+  const?: unknown
+  nullable?: boolean
+  minimum?: number
+  maximum?: number
+  minLength?: number
+  maxLength?: number
+  minItems?: number
+  maxItems?: number
+  pattern?: string
+}
+
+const TYPE_CHECKS: Record<JsonType, (v: unknown) => boolean> = {
+  object: (v) => v !== null && typeof v === 'object' && !Array.isArray(v),
+  array: (v) => Array.isArray(v),
+  string: (v) => typeof v === 'string',
+  number: (v) => typeof v === 'number' && Number.isFinite(v),
+  integer: (v) => typeof v === 'number' && Number.isInteger(v),
+  boolean: (v) => typeof v === 'boolean',
+  null: (v) => v === null,
+}
+
+function deepEqual(a: unknown, b: unknown): boolean {
+  if (a === b) return true
+  if (typeof a !== typeof b || a === null || b === null || typeof a !== 'object') return false
+  const ka = Object.keys(a as object)
+  const kb = Object.keys(b as object)
+  if (ka.length !== kb.length) return false
+  return ka.every((k) => deepEqual((a as Record<string, unknown>)[k], (b as Record<string, unknown>)[k]))
+}
+
+function checkType(schema: JsonSchema, value: unknown): boolean {
+  if (schema.type == null) return true
+  const types = Array.isArray(schema.type) ? schema.type : [schema.type]
+  return types.some((t) => (TYPE_CHECKS[t] ? TYPE_CHECKS[t](value) : true))
+}
+
+function describeType(value: unknown): string {
+  if (value === null) return 'null'
+  if (Array.isArray(value)) return 'array'
+  return typeof value
+}
+
+function validateNode(schema: JsonSchema | undefined, value: unknown, path: string, issues: SchemaIssue[]): void {
+  if (!schema || typeof schema !== 'object') return
+  const at = path || '(root)'
+
+  if (schema.nullable && value === null) return
+
+  if (!checkType(schema, value)) {
+    const want = Array.isArray(schema.type) ? schema.type.join('|') : schema.type
+    issues.push({ path: at, message: `expected type ${want}, got ${describeType(value)}` })
+    return // type is the gate; downstream checks would be noise
+  }
+
+  if ('const' in schema && !deepEqual(value, schema.const)) {
+    issues.push({ path: at, message: `must equal ${JSON.stringify(schema.const)}` })
+  }
+
+  if (Array.isArray(schema.enum) && !schema.enum.some((e) => deepEqual(e, value))) {
+    issues.push({ path: at, message: `must be one of ${JSON.stringify(schema.enum)}` })
+  }
+
+  if (typeof value === 'number') {
+    if (typeof schema.minimum === 'number' && value < schema.minimum) {
+      issues.push({ path: at, message: `must be >= ${schema.minimum}` })
+    }
+    if (typeof schema.maximum === 'number' && value > schema.maximum) {
+      issues.push({ path: at, message: `must be <= ${schema.maximum}` })
+    }
+  }
+
+  if (typeof value === 'string') {
+    if (typeof schema.minLength === 'number' && value.length < schema.minLength) {
+      issues.push({ path: at, message: `must be at least ${schema.minLength} chars` })
+    }
+    if (typeof schema.maxLength === 'number' && value.length > schema.maxLength) {
+      issues.push({ path: at, message: `must be at most ${schema.maxLength} chars` })
+    }
+    if (typeof schema.pattern === 'string' && !new RegExp(schema.pattern).test(value)) {
+      issues.push({ path: at, message: `must match /${schema.pattern}/` })
+    }
+  }
+
+  if (Array.isArray(value)) {
+    if (typeof schema.minItems === 'number' && value.length < schema.minItems) {
+      issues.push({ path: at, message: `must have at least ${schema.minItems} items` })
+    }
+    if (typeof schema.maxItems === 'number' && value.length > schema.maxItems) {
+      issues.push({ path: at, message: `must have at most ${schema.maxItems} items` })
+    }
+    if (schema.items) {
+      value.forEach((el, i) => validateNode(schema.items, el, `${path}[${i}]`, issues))
+    }
+  }
+
+  if (TYPE_CHECKS.object(value)) {
+    const obj = value as Record<string, unknown>
+    if (Array.isArray(schema.required)) {
+      for (const key of schema.required) {
+        if (obj[key] === undefined) issues.push({ path: path ? `${path}.${key}` : key, message: 'is required' })
+      }
+    }
+    if (schema.properties) {
+      for (const [key, sub] of Object.entries(schema.properties)) {
+        if (obj[key] !== undefined) validateNode(sub, obj[key], path ? `${path}.${key}` : key, issues)
+      }
+    }
+  }
+}
+
+/** Returns { ok, issues }. Never throws. */
+export function validate(schema: JsonSchema, value: unknown): { ok: boolean; issues: SchemaIssue[] } {
+  const issues: SchemaIssue[] = []
+  validateNode(schema ?? {}, value, '', issues)
+  return { ok: issues.length === 0, issues }
+}
+
+/** Throws ValidationError when invalid; returns the value otherwise. Used by the registry. */
+export function assertValid<T>(schema: JsonSchema, value: T, capability: string | null = null): T {
+  const { ok, issues } = validate(schema, value)
+  if (!ok) {
+    const summary = issues.map((i) => `${i.path}: ${i.message}`).join('; ')
+    throw new ValidationError(`Invalid input${capability ? ` for "${capability}"` : ''}: ${summary}`, { capability, issues })
+  }
+  return value
+}

package/src/loaders/cubeMapLoader.js

@@ -56,25 +56,47 @@ function detectExtension(faceKeys) {
   return 'ktx2'; // default assumption
 }
 
+// How many faces may be in flight at once. Not six: the KTX2 worker pool three.js gives us holds
+// four transcoder workers, each carrying its own copy of the basis wasm, and that same pool also
+// serves body textures and GLBs. Asking for all six together spawned every worker and queued the
+// other loaders behind the whole sky; measured on cold fetches it was no faster than three.
+const FACES_IN_FLIGHT = 3;
+
 // Load KTX2 faces and create skybox mesh
 async function loadFacesKTX2(faceKeys, renderer) {
   const loader = getKTX2LoaderForRenderer(renderer);
+  const anisotropy = Math.min(8, renderer.capabilities.getMaxAnisotropy());
+
+  const loadFace = async face => {
+    const tex = await loader.loadAsync(faceKeys[face]);
+    tex.flipY = false;
+    tex.wrapS = THREE.ClampToEdgeWrapping;
+    tex.wrapT = THREE.ClampToEdgeWrapping;
+    tex.anisotropy = anisotropy;
+    return { face, tex };
+  };
+
+  // Faces overlap instead of chaining. Awaiting each one in turn made every face wait on the
+  // previous face's download *and* its transcode, so the sky arrived six round trips deep.
+  const settled = [];
+  for (let i = 0; i < FACE_ORDER.length; i += FACES_IN_FLIGHT) {
+    const wave = FACE_ORDER.slice(i, i + FACES_IN_FLIGHT).map(face => loadFace(face));
+    settled.push(...await Promise.allSettled(wave));
+  }
+
+  // allSettled, not all: a bare Promise.all rejects on the first failure and leaks the faces that
+  // land after it. Settle every face first, then dispose everything that arrived before rethrowing.
   const loaded = [];
-  
-  for (const face of FACE_ORDER) {
-    const url = faceKeys[face];
-    try {
-      const tex = await loader.loadAsync(url);
-      tex.flipY = false;
-      tex.wrapS = THREE.ClampToEdgeWrapping;
-      tex.wrapT = THREE.ClampToEdgeWrapping;
-      tex.anisotropy = Math.min(8, renderer.capabilities.getMaxAnisotropy());
-      loaded.push({ face, tex });
-    } catch (e) {
-      // Dispose already loaded textures on failure
-      loaded.forEach(f => f.tex.dispose?.());
-      throw e;
-    }
+  let failure = null;
+  for (const result of settled) {
+    if (result.status === 'fulfilled') loaded.push(result.value);
+    else if (!failure) failure = result.reason;
+  }
+
+  if (failure) {
+    // Dispose already loaded textures on failure
+    loaded.forEach(f => f.tex.dispose?.());
+    throw failure;
   }
   
   const size = 500;

package/src/studio/autosaveSession.ts

@@ -0,0 +1,186 @@
+// AutosaveSession — the single owner of a studio's autosave state slice.
+//
+// Owns STATE TRANSITIONS only: the debounce timer and the
+// dirty/inFlight/queued/lastSavedDraftKey/pendingHost* transitions. The real I/O (building the
+// draft, the API call, the host postMessage, toasts, analytics) stays in the app's host bridge,
+// which drives this session through methods and never writes the slice directly. No DOM: the
+// header save-status dot is rendered through the injected `setHeaderStatus` callback.
+//
+// Convention: a `*Session` owns a mutable state slice (no DOM); `createX(holder, deps)`.
+
+export type AutosaveTone = 'default' | 'busy' | 'warn' | 'ok' | 'error'
+
+export interface AutosaveState {
+  ready: boolean
+  timer: ReturnType<typeof setTimeout> | null
+  dirty: boolean
+  inFlight: boolean
+  queued: boolean
+  lastSavedDraftKey: string
+  pendingHostDraftKey: string
+  pendingHostDraftManual: boolean
+}
+
+export interface AutosaveCtrl {
+  autosave: AutosaveState
+}
+
+export interface AutosaveDeps {
+  // Persist the draft now — the debounce timer's trigger. Late-bound: it may close over a host
+  // bridge built after the session, since it only ever runs inside setTimeout.
+  flushAutosave?: () => unknown
+  // Render the header save-status chip ({ tone } to show, null to clear). The session never
+  // touches the DOM/shell directly — this is the one presentation seam.
+  setHeaderStatus?: (arg: { tone: AutosaveTone } | null) => void
+  // Return true while a save would be rejected (e.g. a server-side lock is held) — the timer
+  // reschedules instead of flushing until it clears.
+  shouldDefer?: () => boolean
+}
+
+export interface AutosaveSession {
+  markDirty(): void
+  schedule(opts?: { delayMs?: number }): void
+  clearTimer(): void
+  syncStatus(): void
+  setStatus(text?: string, tone?: AutosaveTone): void
+  arm(baselineKey: string): void
+  // Save round-trip (driven by the app's host bridge save). Split in two so a blocked autosave
+  // tick (not-ready / not-dirty / inFlight) returns before the descriptor is ever built.
+  tryBegin(opts: { manual: boolean }): boolean
+  checkDedupAndBegin(opts: { manual: boolean; currentDraftKey: string }): { proceed: boolean; result: boolean }
+  markSaved(draftKey: string): void
+  beginHostAck(opts: { manual: boolean; currentDraftKey: string }): void
+  settleAfterApi(opts: { manual: boolean }): void
+  // Host-ack is two calls so the caller can interleave its status/toast/
+  // analytics between the state resolution and the final settle — preserving the exact order
+  // of the original handler (where the transient 'Save failed' header is then re-synced).
+  resolveHostAck(opts: { ok: boolean }): { wasManual: boolean }
+  settleHostAck(): void
+}
+
+export function createAutosaveSession(ctrl: AutosaveCtrl, deps: AutosaveDeps = {}): AutosaveSession {
+  ctrl.autosave = {
+    ready: false,
+    timer: null,
+    dirty: false,
+    inFlight: false,
+    queued: false,
+    lastSavedDraftKey: '',
+    pendingHostDraftKey: '',
+    pendingHostDraftManual: false,
+  }
+  const state = ctrl.autosave
+
+  const api: AutosaveSession = {
+    setStatus(text = '', tone = 'default') {
+      deps.setHeaderStatus?.(text ? { tone } : null)
+    },
+
+    syncStatus() {
+      if (state.inFlight) { api.setStatus('Saving...', 'busy'); return }
+      if (state.dirty) { api.setStatus('Unsaved changes', 'warn'); return }
+      if (state.lastSavedDraftKey) { api.setStatus('All changes saved', 'ok'); return }
+      api.setStatus('')
+    },
+
+    clearTimer() {
+      if (!state.timer) return
+      clearTimeout(state.timer)
+      state.timer = null
+    },
+
+    schedule({ delayMs = 2000 } = {}) {
+      if (!state.ready) return
+      api.clearTimer()
+      if (!state.dirty) { api.syncStatus(); return }
+      api.syncStatus()
+      state.timer = setTimeout(() => {
+        state.timer = null
+        // Reschedule (don't flush) while the app says a save would be rejected.
+        if (deps.shouldDefer?.()) {
+          api.schedule({ delayMs: 2000 })
+          return
+        }
+        void deps.flushAutosave?.()
+      }, delayMs)
+    },
+
+    markDirty() {
+      if (!state.ready) return
+      state.dirty = true
+      if (state.inFlight) {
+        state.queued = true
+        api.syncStatus()
+        return
+      }
+      api.schedule()
+    },
+
+    arm(baselineKey: string) {
+      state.lastSavedDraftKey = baselineKey
+      state.ready = true
+    },
+
+    tryBegin({ manual }) {
+      api.clearTimer()
+      if (!manual && (!state.ready || !state.dirty)) return false
+      if (state.inFlight) {
+        state.queued = true
+        api.syncStatus()
+        return false
+      }
+      return true
+    },
+
+    checkDedupAndBegin({ manual, currentDraftKey }) {
+      if (!manual && currentDraftKey && currentDraftKey === state.lastSavedDraftKey) {
+        state.dirty = false
+        api.syncStatus()
+        return { proceed: false, result: true }
+      }
+      state.inFlight = true
+      api.syncStatus()
+      return { proceed: true, result: false }
+    },
+
+    markSaved(draftKey: string) {
+      // An edit that landed while this save was in flight is queued and NOT in what was saved —
+      // stay dirty so the queued reschedule writes it.
+      state.dirty = state.queued
+      state.lastSavedDraftKey = draftKey
+    },
+
+    beginHostAck({ manual, currentDraftKey }) {
+      state.pendingHostDraftKey = currentDraftKey
+      state.pendingHostDraftManual = manual === true
+    },
+
+    settleAfterApi({ manual }) {
+      state.inFlight = false
+      api.syncStatus()
+      if (state.queued) {
+        state.queued = false
+        api.schedule({ delayMs: manual ? 300 : 1200 })
+      }
+    },
+
+    resolveHostAck({ ok }) {
+      const wasManual = state.pendingHostDraftManual === true
+      if (ok) api.markSaved(state.pendingHostDraftKey || state.lastSavedDraftKey)
+      return { wasManual }
+    },
+
+    settleHostAck() {
+      state.pendingHostDraftKey = ''
+      state.pendingHostDraftManual = false
+      state.inFlight = false
+      api.syncStatus()
+      if (state.queued) {
+        state.queued = false
+        api.schedule({ delayMs: 1200 })
+      }
+    },
+  }
+
+  return api
+}

package/src/studio/headerBroadcast.ts

@@ -0,0 +1,52 @@
+// Header-protocol broadcast (the "header sink" seam).
+//
+// A studio controller drives its header imperatively (`shell.setUndoRedoState(...)`,
+// `shell.setHeaderStatus(...)`, …). When a React header mounts over the stage it must show the
+// SAME state, driven by the SAME controller logic — no duplicated per-step rules, one source of
+// truth.
+//
+// `makeHeaderBroadcast` wraps the shell so every listed header setter ALSO fans out to a sink
+// (read live through `getSink`, so a late registration is picked up) and retains its last value,
+// so a sink that registers after the shell was driven can be replayed race-free via `replayInto`.
+// Every other member of the shell passes through untouched.
+
+type Setter = (arg: never) => void
+
+/** A header sink implements any subset of the setters. */
+export type HeaderSinkOf<K extends string> = Partial<Record<K, Setter>>
+
+export type HeaderBroadcast<Shell extends object, K extends string> = Shell & {
+  /** Push the last value of every header setter into a freshly registered sink. */
+  replayInto(sink: HeaderSinkOf<K> | null | undefined): void
+}
+
+export function makeHeaderBroadcast<Shell extends object, K extends string>(
+  shell: Shell,
+  getSink: () => HeaderSinkOf<K> | null | undefined,
+  setters: readonly K[],
+): HeaderBroadcast<Shell, K> {
+  // One slot per setter (all single-arg, last write wins) is the full retained header model.
+  const lastArg = new Map<K, unknown>()
+  const call = (fn: unknown, self: unknown, arg: unknown) => {
+    if (typeof fn === 'function') fn.call(self, arg)
+  }
+
+  // Spread carries the shell's own members (data props and non-header methods). Shell methods
+  // are expected to be closures (no `this`), so copying the references is safe.
+  const wrapper = { ...shell } as Record<string, unknown>
+  for (const key of setters) {
+    const original = (shell as Record<string, unknown>)[key]
+    wrapper[key] = (arg: unknown) => {
+      call(original, shell, arg)
+      lastArg.set(key, arg)
+      call(getSink()?.[key], undefined, arg)
+    }
+  }
+
+  wrapper.replayInto = (sink: HeaderSinkOf<K> | null | undefined) => {
+    if (!sink) return
+    for (const [key, arg] of lastArg) call(sink[key], undefined, arg)
+  }
+
+  return wrapper as HeaderBroadcast<Shell, K>
+}

package/src/studio/history.ts

@@ -0,0 +1,91 @@
+// Snapshot-based undo/redo for a studio.
+//
+// The history knows nothing about what it stores: the app injects `snapshot()` (capture the
+// editable state, deep-cloned) and `restore(s)` (put a snapshot back). `onChange` fires after every
+// push/undo/redo/clear so the app can mark its draft dirty, rebuild derived views, and refresh the
+// header's undo/redo buttons. The stacks can be supplied by the caller so an existing controller
+// that already exposes `history.undo` / `history.redo` arrays keeps reading the same arrays.
+
+export interface HistoryStacks<S> {
+  undo: S[]
+  redo: S[]
+}
+
+export type HistoryAction = 'push' | 'undo' | 'redo' | 'clear'
+
+export interface HistoryState {
+  canUndo: boolean
+  canRedo: boolean
+}
+
+export interface HistoryDeps<S> {
+  /** Capture the current editable state. Must return a detached copy (deep clone). */
+  snapshot: () => S
+  /** Put a previously captured snapshot back as the current state. */
+  restore: (snapshot: S) => void
+  /** Return false to skip a push (e.g. nothing is loaded yet). */
+  canPush?: () => boolean
+  /** Oldest entries drop off beyond this many undo steps. */
+  maxHistory?: number
+  /** Reuse existing stacks instead of fresh ones. */
+  stacks?: HistoryStacks<S>
+  /** Fires after every change of the stacks, with the action that caused it. */
+  onChange?: (state: HistoryState, action: HistoryAction) => void
+}
+
+export interface StudioHistory<S> {
+  readonly stacks: HistoryStacks<S>
+  /** Record the current state as an undo step. Call BEFORE applying a reversible edit. */
+  push(): void
+  undo(): boolean
+  redo(): boolean
+  clear(): void
+  canUndo(): boolean
+  canRedo(): boolean
+  getState(): HistoryState
+}
+
+export function createHistory<S>(deps: HistoryDeps<S>): StudioHistory<S> {
+  const { snapshot, restore, canPush, maxHistory = 60, onChange } = deps
+  const stacks: HistoryStacks<S> = deps.stacks ?? { undo: [], redo: [] }
+
+  const getState = (): HistoryState => ({
+    canUndo: stacks.undo.length > 0,
+    canRedo: stacks.redo.length > 0,
+  })
+  const notify = (action: HistoryAction) => onChange?.(getState(), action)
+
+  function step(from: S[], to: S[], action: 'undo' | 'redo'): boolean {
+    if (!from.length) return false
+    to.push(snapshot())
+    restore(from.pop() as S)
+    notify(action)
+    return true
+  }
+
+  return {
+    stacks,
+    push() {
+      if (canPush && !canPush()) return
+      stacks.undo.push(snapshot())
+      if (stacks.undo.length > maxHistory) stacks.undo.shift()
+      stacks.redo.length = 0
+      notify('push')
+    },
+    undo: () => step(stacks.undo, stacks.redo, 'undo'),
+    redo: () => step(stacks.redo, stacks.undo, 'redo'),
+    clear() {
+      stacks.undo.length = 0
+      stacks.redo.length = 0
+      notify('clear')
+    },
+    canUndo: () => stacks.undo.length > 0,
+    canRedo: () => stacks.redo.length > 0,
+    getState,
+  }
+}
+
+/** Deep clone for JSON-shaped studio state — the usual `snapshot()` building block. */
+export function cloneJson<T>(value: T): T {
+  return value == null ? value : (JSON.parse(JSON.stringify(value)) as T)
+}

package/src/studio/hostTransport.ts

@@ -0,0 +1,70 @@
+// The generic half of a studio's host bridge: who may act as the host, and how to talk to it.
+//
+// A studio runs embedded in an iframe of the platform dashboard (or a local dev server). Drafts
+// and captured media are posted back to whichever origin claims the host role, so an arbitrary
+// embedding page must never pass the trust gate, and nothing is ever broadcast to '*' except the
+// initial "ready" ping (which carries no payload).
+//
+// The app-specific half — what a draft looks like, which API saves it, which message types exist
+// — stays in each app and drives an AutosaveSession.
+
+interface WindowLike {
+  location: { origin: string }
+  parent: WindowLike | null
+  postMessage(message: unknown, targetOrigin: string, transfer?: Transferable[]): void
+}
+
+const TRUSTED_DEV_HOSTNAMES = new Set(['localhost', '127.0.0.1'])
+const TRUSTED_DOMAIN = 'plantasia.space'
+
+const currentWindow = (): WindowLike | null =>
+  typeof window === 'undefined' ? null : (window as unknown as WindowLike)
+
+/**
+ * True for the studio's own origin, a local dev host, or an https plantasia.space origin
+ * (apex or any subdomain).
+ */
+export function isTrustedHostOrigin(origin: string | null | undefined, win = currentWindow()): boolean {
+  if (!origin || origin === 'null') return false
+  let url: URL
+  try {
+    url = new URL(origin)
+  } catch {
+    return false
+  }
+  if (win && url.origin === win.location.origin) return true
+  const hostname = url.hostname.toLowerCase()
+  if (TRUSTED_DEV_HOSTNAMES.has(hostname)) return true
+  return url.protocol === 'https:' && (hostname === TRUSTED_DOMAIN || hostname.endsWith(`.${TRUSTED_DOMAIN}`))
+}
+
+/** True when running inside a parent frame. */
+export function isEmbedded(win = currentWindow()): boolean {
+  try {
+    return Boolean(win?.parent && win.parent !== win)
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Post to the parent frame. Returns false (and sends nothing) when there is no recorded host
+ * origin or no parent — never falls back to a '*' broadcast for payloads.
+ */
+export function postToHost(
+  message: unknown,
+  targetOrigin: string | null | undefined,
+  transfer: Transferable[] = [],
+  win = currentWindow(),
+): boolean {
+  try {
+    if (!targetOrigin || !win) return false
+    if (isEmbedded(win)) {
+      ;(win.parent as WindowLike).postMessage(message, targetOrigin, transfer)
+      return true
+    }
+  } catch (err) {
+    console.warn('[Studio] postMessage to host failed', err)
+  }
+  return false
+}

package/src/studio/index.ts

@@ -0,0 +1,30 @@
+// Studio session machinery shared by the Entangled World and Orbiter studios: undo/redo, the
+// autosave state machine, the header mirror (patch store + broadcast/replay), the status line
+// seam, and the host-frame transport. Framework-free: no React, no DOM beyond postMessage.
+
+export {
+  createHistory,
+  cloneJson,
+  type StudioHistory,
+  type HistoryDeps,
+  type HistoryStacks,
+  type HistoryState,
+  type HistoryAction,
+} from './history.js'
+export {
+  createAutosaveSession,
+  type AutosaveSession,
+  type AutosaveState,
+  type AutosaveCtrl,
+  type AutosaveDeps,
+  type AutosaveTone,
+} from './autosaveSession.js'
+export { createPatchStore, type PatchStore } from './patchStore.js'
+export { makeHeaderBroadcast, type HeaderBroadcast, type HeaderSinkOf } from './headerBroadcast.js'
+export {
+  createStatusChannel,
+  type StatusChannel,
+  type StatusSink,
+  type StatusShowOptions,
+} from './statusChannel.js'
+export { isTrustedHostOrigin, isEmbedded, postToHost } from './hostTransport.js'