@ggui-ai/iframe-runtime 0.14.0 → 0.16.0

package/dist/runtime.d.ts

@@ -25,7 +25,7 @@
  * wrapper, which routes it to the host's `onError` callback.
  */
 import './zod-jitless.js';
-import type { DrainAckPayload, JsonValue, JsonObject, GguiSession } from '@ggui-ai/protocol';
+import type { DrainAckPayload, JsonValue, JsonObject, GguiSession } from '@ggui-ai/protocol/wire';
 import type { WebSocketMessage } from '@ggui-ai/protocol/transport/websocket';
 import { type McpAppAiGguiRenderMeta, type McpAppBootstrapFailedMessage, type McpAppRendererReadyMessage } from '@ggui-ai/protocol/integrations/mcp-apps';
 import type { GguiSessionSeedInput } from './types.js';
@@ -97,36 +97,32 @@ export declare function setCurrentApp(app: App): void;
  * `color-scheme` via `applyDocumentTheme` — nothing in the token
  * pipeline keys off it, so a dark host painted the light ladder
  * (host-fit 46.0 vs 87.7 with the dark ladder, probe `cc728a8eb`).
- * `buildOpts` consumes this ONLY when the slice stamps no `themeMode`:
- * every operator layer (live provider > per-render override > app
- * default > server default) still wins by being stamped; the host
- * fills the gap where no operator had an opinion.
+ * Under ggui#987 §4 the embedding host OWNS runtime mode: when it
+ * announces one, `buildOpts` paints it over every stamped opinion; the
+ * stamped layers decide only when the host is silent. Read live from
+ * the App's pre-merged hostContext, so a `hostcontextchanged` flip
+ * re-resolves on the next `buildOpts`.
  *
  * @internal — exported for unit tests (`setCurrentApp` injects the
  *   App); production caller is `buildOpts` inside `bootSequence`.
  */
 export declare function hostAnnouncedThemeMode(): 'light' | 'dark' | undefined;
 /**
- * Resolve the mount's base-stylesheet color mode from the slice, with
- * the host as the final fallback (ggui#589, completing the ggui#551
- * precedence ruling — "slice wins, host is the fallback, absent ≠
- * light"):
+ * Resolve the mount's color mode (ggui#987 §4 — the embedding host owns
+ * runtime mode; the app theme's `mode` is a DEFAULT, never a pin):
  *
- *   stamped `themeMode`  >  `theme.mode` (the slice theme OBJECT)  >
- *   host-announced theme  >  undefined
+ *   host-announced theme  >  stamped `themeMode`  >  `theme.mode`
+ *   (the app theme's default)  >  undefined
  *
- * The middle leg is the ggui#589 fix: a render envelope carrying a
- * per-app theme (`theme: {mode, cssVariables}`) but no top-level
- * `themeMode` is still a slice-stamped mode opinion — before this,
- * the base token ladder ignored it and painted the LIGHT token set
- * under a dark overlay whenever the host (correctly, per the
- * adapter-boundary doctrine in the native host helpers) announced no
- * `hostContext.theme`: a light skeleton in a dark skin. The theme
- * object's own `mode` already drove `color-scheme`; now it also
- * selects the ladder.
+ * A card that ignored the host's announced mode painted a light
+ * skeleton inside a dark chat — the host's word is what the user
+ * actually sees around the card. The stamped layers (live provider >
+ * per-render override > app default > server default) decide only when
+ * the host is silent, which is the adapter-boundary case (a host
+ * helper that announces no `hostContext.theme`).
  *
  * `undefined` still means "no opinion anywhere" — the renderer's
- * default applies; never coerced to `'light'`.
+ * default applies; never coerced to `'light'` here (ggui#551).
  *
  * @internal — exported for unit tests; production caller is
  *   `buildOpts` inside `bootSequence`.
@@ -134,36 +130,24 @@ export declare function hostAnnouncedThemeMode(): 'light' | 'dark' | undefined;
 export declare function resolveMountThemeMode(meta: {
     readonly themeMode?: 'light' | 'dark';
     readonly theme?: {
-        readonly mode: 'light' | 'dark';
-        readonly cssVariables?: Record<string, string>;
+        readonly mode?: 'light' | 'dark';
     };
 }): 'light' | 'dark' | undefined;
 /**
- * Resolve the mount's base-theme id from the slice (ggui#589 ask 3):
+ * Resolve the mount's compiled-ladder id from the slice (ggui#987 D2):
  *
- *   stamped `themeId`  >  `theme.name` (the slice theme OBJECT's name)
- *   >  undefined (renderer default ladder)
+ *   stamped `themeId`  >  undefined (renderer default ladder)
  *
- * The name leg makes a slice theme whose `name` matches a REGISTERED
- * theme id select that theme as the BASE token ladder — the overlay's
- * cssVariables still apply above it, so the base carries the full
- * brand ramp coverage a sparse overlay cannot (the "only the mapped
- * vars carry brand" store-frame class). An unregistered name is
- * harmless by construction: `getScopedThemeCss` falls back to the
- * default theme, which is byte-identical to the no-themeId path
- * (`getScopedCssTokens` ≡ `getScopedThemeCss(default)`), so a slice
- * naming its theme "My Custom" renders exactly as before.
+ * The app theme's `name` is a LABEL the author's tooling reads back —
+ * it never selects a ladder. An app theme carries its own full
+ * projection (`overlays`, exactly the manifest minus the floor), so
+ * there is no coverage gap for a compiled theme to fill beneath it.
  *
  * @internal — exported for unit tests; production caller is
  *   `buildOpts` inside `bootSequence`.
  */
 export declare function resolveMountThemeId(meta: {
     readonly themeId?: string;
-    readonly theme?: {
-        readonly name?: string;
-        readonly mode?: 'light' | 'dark';
-        readonly cssVariables?: Record<string, string>;
-    };
 }): string | undefined;
 /**
  * The host's announced palette, read from the connected App's
@@ -279,10 +263,12 @@ export interface BootSequenceOptions {
      * entirely (matches the ProtocolError posture; the `<McpAppIframe>`
      * host wrapper decides whether to bind this via its `onObserve`
      * prop). Exception: `relay-incapability` events do NOT flow through
-     * this seam — they originate in module-level gesture-dispatch code
-     * outside the boot graph (it runs independently of any given boot
-     * call) and always ride the postMessage-to-parent default, whether
-     * or not this option is bound.
+     * this seam — by rule they always ride the postMessage-to-parent
+     * default, whether or not this option is bound: most emission sites
+     * are module-level gesture-dispatch code that runs independently of
+     * any given boot call, and the one inside the boot graph (the
+     * `boot-failed` edge, ggui#830) follows the same rule so a host reads
+     * every edge the same way.
      */
     readonly onObserve?: ObservabilityEmitter;
     /**
@@ -704,19 +690,22 @@ export declare function dispatchSubmitAction(args: {
 /**
  * Channel-transport router's `tools/call` invoker (ggui#440) —
  * iframe-polling transport, `tools/call` against the parent MCP host
- * via `app.callServerTool` (spec-canonical) when the App handle is
- * set; falls back to raw postMessage pre-handshake or in tests.
+ * via `app.callServerTool` (spec-canonical); with no App bound the
+ * call answers a code-less error envelope — never a raw postMessage.
  * Direct call (no LLM consent loop). Returns the tool's
  * structuredContent (or `content[0]` if that's where the payload
  * landed) as a `JsonValue`. On RPC error we throw — the router
  * catches and silently retries on the next tick.
  *
- * Once a REAL gesture has confirmed this host can't relay (the latch
- * above — set only after {@link dispatchSubmitAction} actually tried
- * and failed on a host with no `serverTools` advertised, with
- * capabilities already captured, AND the failure was relay-shaped —
- * not a well-formed `{ok:false}` result; see `isRelayShapedFailure`),
- * every subsequent poll will fail identically.
+ * Once this document has confirmed it cannot relay (the latch above —
+ * set through the ONE writer on exactly three paths: a REAL gesture
+ * that failed relay-shaped on a host that never advertised
+ * `serverTools`, with capabilities already captured (`advert-silent`);
+ * a declared refusal code answered under a positive advertisement
+ * (`confirmed-refusal`); or the host's own failure of the mandatory
+ * `ui/initialize` handshake, before any gesture (`boot-failed`,
+ * ggui#830) — never a well-formed `{ok:false}` result; see
+ * `isRelayShapedFailure`), every subsequent poll will fail identically.
  *
  * This guard does NOT stop the router's poll loop, and nothing here
  * should ever be written so that it could (ggui#443). It does two
@@ -742,10 +731,13 @@ export declare function dispatchSubmitAction(args: {
  * (ggui's own embed host pre-Task-2 is exactly this case) — silently
  * killing working channel polls forever. That is "absence of a
  * capability blocks an attempt", which the fail-safe constraint
- * forbids. The latch implies `!hostCanRelayToolCalls()` (it only
- * ever sets inside that guard), so testing it alone is sufficient —
- * a host that never fails a real gesture never latches, and its
- * channels keep working.
+ * forbids. The latch is set only by a CONFIRMED OUTCOME — a failed
+ * real gesture (the advert-silent leg, or a confirmed refusal under a
+ * positive advertisement, ggui#599 cycle-2) or a failed handshake
+ * (ggui#830), never by an advertisement's absence — so testing the
+ * latch alone is sufficient: a host that answers its handshake and
+ * never fails a real gesture never latches, and its channels keep
+ * working.
  *
  * Extracted to a named export (rather than an inline closure inside
  * `bootProduction`) so unit tests can drive it directly through the