@ggui-ai/iframe-runtime 0.10.0 → 0.12.0

package/dist/mcp-app-iframe-host.js

@@ -77,8 +77,13 @@ export function mountMcpAppIframe(container, opts) {
     iframe.style.maxWidth = dims.maxWidth !== undefined ? `${dims.maxWidth}px` : '100%';
     if (dims.maxHeight !== undefined)
         iframe.style.maxHeight = `${dims.maxHeight}px`;
-    iframe.style.border = '1px solid #e5e5e5';
-    iframe.style.borderRadius = '8px';
+    // Round-6 doctrine (ggui#589 @6e15724a1, kit C1 grade): the helper
+    // paints CONTAINMENT ONLY — silhouette (border/radius) belongs to
+    // the embedding host's own chrome, tokens to the theme. The former
+    // 1px #e5e5e5 / radius-8 here was the same ungoverned-chrome class
+    // the RN helper shipped, surfaced by the host-helper catalog's
+    // first-party run (ggui#600 OPEN FINDING, closed here).
+    iframe.style.border = 'none';
     iframe.style.display = 'block';
     container.appendChild(iframe);
     // Cache contentWindow — on detach, `iframe.contentWindow` is null

package/dist/react-renderer.d.ts

@@ -62,17 +62,59 @@ export interface ReactRootMountOptions {
      */
     readonly themeMode?: 'light' | 'dark';
     /**
-     * Per-app theme overlay applied at the iframe's `:root` AFTER the base
-     * token block, so the operator-supplied `--ggui-*` values win the
-     * cascade (a partial set — unset vars keep their token defaults). A
-     * structural subset of protocol's `AppTheme` (`name` is display-only,
-     * not needed at render). `mode` drives `color-scheme` so native
-     * controls / scrollbars / canvas pick up dark vs light.
+     * Per-app theme overlay — a partial set of `--ggui-*` values; unset
+     * vars keep their token defaults. Merged INTO the scoped in-body
+     * token block after the base block (and after `hostPalette`), which
+     * is the only placement that can recolor tree content: a `:root`-only
+     * append is cascade-dead for components — the scoped block sits later
+     * in document order and re-specifies every token (browser-verified,
+     * see the scoped-merge comment in `renderTree`). The `:root` append
+     * still happens, but for body chrome only. A structural subset of
+     * protocol's `AppTheme` (`name` is display-only, not needed at
+     * render). `mode` drives `color-scheme` so native controls /
+     * scrollbars / canvas pick up dark vs light.
+     *
+     * Precedence (ggui#573 ruling): base tokens < `hostPalette` <
+     * `appTheme` < `cssOverrides` — the slice's stamped theme always
+     * wins; the host palette is the fallback layer beneath it.
      */
     readonly appTheme?: {
         readonly mode: 'light' | 'dark';
         readonly cssVariables: Record<string, string>;
+        /**
+         * The REGISTERED base ladder, delivered over the wire (ggui#598-C
+         * runtime theme registration — see protocol's `appThemeSchema`).
+         * BOTH modes' resolved variable sets ride the envelope; when
+         * present, the mode-selected set REPLACES the compiled ladder
+         * block (`getScopedThemeCss`/`getScopedCssTokens`) at the base
+         * position of the #573 precedence above — delivery changes WHERE
+         * the ladder's bytes come from, never WHICH layer wins. Mode
+         * selection reuses the mount's already-resolved `themeMode` (one
+         * projection — no second mode resolution here), and a mode switch
+         * re-paints from the retained other set with no network activity.
+         * Values are injection-safe by the wire schema — never
+         * re-validated here; serialization is key-sorted for byte-stable
+         * output. `documentHash` is the registration's identity (joins a
+         * painted ladder to its registration record); the renderer
+         * carries it but exposes no observability surface for it today.
+         */
+        readonly base?: {
+            readonly documentHash: string;
+            readonly light: Readonly<Record<string, string>>;
+            readonly dark: Readonly<Record<string, string>>;
+        };
     };
+    /**
+     * Host-announced palette, already translated onto `--ggui-*` tokens
+     * (see `host-palette-bridge.ts` — the spec `--color-*` vocabulary
+     * never reaches this layer). Merged into the scoped token block
+     * after the base block and BEFORE `appTheme`, so it repaints only
+     * the slots no operator theme re-specifies (ggui#572; precedence
+     * per the ggui#573 ruling above). Values are sanitized by the
+     * bridge before they get here — host input never reaches this
+     * string-join raw.
+     */
+    readonly hostPalette?: Readonly<Record<string, string>>;
     readonly cssOverrides?: string;
     readonly onError?: (error: Error) => void;
     /**

package/dist/react-renderer.js

@@ -31,7 +31,7 @@
  */
 import React, { Component, createElement, Fragment, } from 'react';
 import { createRoot } from 'react-dom/client';
-import { stripMarkers, rewriteImports, getScopedThemeCss, getScopedCssTokens, getThemeCss, getCssTokens, } from '@ggui-ai/design/rendering';
+import { stripMarkers, rewriteImports, getScopedThemeCss, getScopedCssTokens, assembleDeliveredThemeCss, getThemeCss, getCssTokens, } from '@ggui-ai/design/rendering';
 import { hoistImports, loadModule, loadModuleInline, probeUrlModuleLoad, } from '@ggui-ai/design/module-loader';
 /**
  * Document-lifetime verdict: URL-scheme module loading (`blob:` main
@@ -59,6 +59,18 @@ function makeScopeClass() {
     scopeCounter += 1;
     return `ggui-rcr-${scopeCounter}`;
 }
+/**
+ * Join a custom-property record into CSS declarations. Values were
+ * validated injection-safe upstream (appTheme: write-side
+ * `appThemeSchema` + the wire parser; hostPalette: the host-palette
+ * bridge's sanitizer), so the string-join is safe — do NOT
+ * re-sanitize here.
+ */
+function toCssDecls(vars) {
+    return Object.entries(vars)
+        .map(([k, v]) => `${k}: ${v};`)
+        .join('');
+}
 // =============================================================================
 // Error boundary — port of RCR's internal ErrorBoundary (L68–203).
 // =============================================================================
@@ -302,13 +314,35 @@ export async function mountReactRoot(container, opts) {
         }
     }
     function renderTree(opts) {
-        let themeCss = opts.themeId
-            ? getScopedThemeCss(opts.themeId, scopeClass, opts.themeMode)
-            : getScopedCssTokens(scopeClass, opts.themeMode);
+        // Delivered base ladder (ggui#598-C): when the slice theme carries
+        // `base`, the mode-selected set REPLACES the compiled ladder block
+        // at the base position — same precedence slot, different byte
+        // source. Mode selection reuses the already-resolved `themeMode`
+        // (one projection; absent means light — the same default
+        // `getScopedThemeCss` applies). Both sets stay retained on the
+        // options, so a mode-switch re-render picks the other ladder from
+        // memory — never the network.
+        const deliveredBase = opts.appTheme?.base;
+        let themeCss = deliveredBase !== undefined
+            ? // Design-package assembler (ggui#598-C, injection-review flag 1):
+                // the delivered ladder gets the SAME scaffolding the compiled
+                // ladder gets — base inherits, derived gradient/effect tokens
+                // (color-mix fallback split), box-sizing, font-inherit — from
+                // ONE shared builder, so the two paths cannot drift.
+                assembleDeliveredThemeCss(scopeClass, opts.themeMode === 'dark' ? deliveredBase.dark : deliveredBase.light)
+            : opts.themeId
+                ? getScopedThemeCss(opts.themeId, scopeClass, opts.themeMode)
+                : getScopedCssTokens(scopeClass, opts.themeMode);
+        if (opts.hostPalette) {
+            // Host palette = the fallback layer (ggui#572, #573 ruling):
+            // after the base scoped block so it can repaint at all (the base
+            // re-specifies every token), BEFORE the appTheme overlay so the
+            // slice's stamped theme wins by document order. Keys + values
+            // arrive pre-sanitized from the host-palette bridge.
+            themeCss += `.${scopeClass}{${toCssDecls(opts.hostPalette)}}`;
+        }
         if (opts.appTheme) {
-            const decls = Object.entries(opts.appTheme.cssVariables)
-                .map(([k, v]) => `${k}: ${v};`)
-                .join('');
+            const decls = toCssDecls(opts.appTheme.cssVariables);
             // The overlay must be merged HERE, into the scoped style that
             // mounts INSIDE the scope div — the `:root` append below is
             // cascade-dead for tree content: the in-scope block sits later
@@ -316,9 +350,11 @@ export async function mountReactRoot(container, opts) {
             // specificity the base scoped tokens always win over a head-level
             // override (browser-verified in rnd/gen-ui/beauty/experiments/001,
             // the probe sequence that found this). Appended AFTER the base
-            // block and BEFORE `cssOverrides`, so: base < operator overlay <
-            // explicit overrides. Values validated injection-safe upstream
-            // (same guarantee the `:root` append cites).
+            // block + host palette and BEFORE `cssOverrides`, so: base <
+            // host palette < operator overlay < explicit overrides
+            // (ggui#573: slice wins, host fallback). Values validated
+            // injection-safe upstream (same guarantee the `:root` append
+            // cites).
             themeCss += `.${scopeClass}{${decls}}`;
         }
         // Also inject theme CSS at `:root` on `document.head`. The scoped
@@ -334,10 +370,15 @@ export async function mountReactRoot(container, opts) {
             let rootCss = opts.themeId
                 ? getThemeCss(opts.themeId, opts.themeMode)
                 : getCssTokens(opts.themeMode);
+            if (opts.hostPalette) {
+                // BODY-CHROME ONLY, same as the appTheme `:root` append below —
+                // and beneath it, mirroring the scoped-block order (#573:
+                // slice wins, host fallback). Keeps the embedding shell's
+                // body font/color/background coherent with the tree.
+                rootCss += `:root{${toCssDecls(opts.hostPalette)}}`;
+            }
             if (opts.appTheme) {
-                const decls = Object.entries(opts.appTheme.cssVariables)
-                    .map(([k, v]) => `${k}: ${v};`)
-                    .join('');
+                const decls = toCssDecls(opts.appTheme.cssVariables);
                 // BODY-CHROME ONLY. This `:root` append themes the embedding
                 // shell's body styles (font/color/background outside the scope
                 // div). It does NOT reach tree content — the scoped in-body

package/dist/render-item.d.ts

@@ -51,11 +51,28 @@ export interface RenderItemOptions {
      * so the renderer injects the `--ggui-*` overrides + `color-scheme` at
      * `:root`. Sourced from the bootstrap's `_meta["ai.ggui/render"].theme`.
      * A structural subset of protocol's `AppTheme` (`name` is display-only).
+     * `base` is the delivered registered ladder (ggui#598-C) — forwarded
+     * verbatim; the renderer injects the mode-selected set in place of
+     * the compiled ladder block (see
+     * {@link ReactRootMountOptions.appTheme}).
      */
     readonly appTheme?: {
         readonly mode: 'light' | 'dark';
         readonly cssVariables: Record<string, string>;
+        readonly base?: {
+            readonly documentHash: string;
+            readonly light: Readonly<Record<string, string>>;
+            readonly dark: Readonly<Record<string, string>>;
+        };
     };
+    /**
+     * Host-announced palette, pre-mapped onto `--ggui-*` tokens by the
+     * host-palette bridge. Forwarded to
+     * {@link ReactRootMountOptions.hostPalette}: the fallback layer
+     * beneath `appTheme` in the scoped token block (ggui#572, merge
+     * order per the ggui#573 ruling — slice wins, host fallback).
+     */
+    readonly hostPalette?: Readonly<Record<string, string>>;
     readonly cssOverrides?: string;
     readonly onError?: (err: Error) => void;
     /**

package/dist/render-item.js

@@ -177,6 +177,9 @@ export async function mountRender(container, opts) {
             ...(currentOpts.themeId !== undefined ? { themeId: currentOpts.themeId } : {}),
             ...(currentOpts.themeMode !== undefined ? { themeMode: currentOpts.themeMode } : {}),
             ...(currentOpts.appTheme !== undefined ? { appTheme: currentOpts.appTheme } : {}),
+            ...(currentOpts.hostPalette !== undefined
+                ? { hostPalette: currentOpts.hostPalette }
+                : {}),
             ...(currentOpts.cssOverrides !== undefined
                 ? { cssOverrides: currentOpts.cssOverrides }
                 : {}),
@@ -244,6 +247,7 @@ export async function mountRender(container, opts) {
                     ...(next.themeId !== undefined ? { themeId: next.themeId } : {}),
                     ...(next.themeMode !== undefined ? { themeMode: next.themeMode } : {}),
                     ...(next.appTheme !== undefined ? { appTheme: next.appTheme } : {}),
+                    ...(next.hostPalette !== undefined ? { hostPalette: next.hostPalette } : {}),
                     ...(next.cssOverrides !== undefined ? { cssOverrides: next.cssOverrides } : {}),
                     ...(next.onError !== undefined ? { onError: next.onError } : {}),
                     renderWrapper: wrapInScopedProvider,

package/dist/runtime.d.ts

@@ -97,6 +97,87 @@ export declare function setCurrentApp(app: App): void;
  *   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"):
+ *
+ *   stamped `themeMode`  >  `theme.mode` (the slice theme OBJECT)  >
+ *   host-announced theme  >  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.
+ *
+ * `undefined` still means "no opinion anywhere" — the renderer's
+ * default applies; never coerced to `'light'`.
+ *
+ * @internal — exported for unit tests; production caller is
+ *   `buildOpts` inside `bootSequence`.
+ */
+export declare function resolveMountThemeMode(meta: {
+    readonly themeMode?: 'light' | 'dark';
+    readonly theme?: {
+        readonly mode: 'light' | 'dark';
+        readonly cssVariables?: Record<string, string>;
+    };
+}): 'light' | 'dark' | undefined;
+/**
+ * Resolve the mount's base-theme id from the slice (ggui#589 ask 3):
+ *
+ *   stamped `themeId`  >  `theme.name` (the slice theme OBJECT's name)
+ *   >  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.
+ *
+ * @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
+ * pre-merged hostContext and translated onto `--ggui-*` tokens by the
+ * host-palette bridge. `undefined` when no App is connected, the host
+ * sent no `styles.variables`, or nothing in it maps/survives
+ * sanitization — callers spread-skip the option, exactly like
+ * {@link hostAnnouncedThemeMode}.
+ *
+ * This is the palette input leg of host-theme adaptation (ggui#572,
+ * the color analog of #551's mode leg above): the spec `--color-*`
+ * variables land as inline custom properties on `<html>` via the
+ * canonical ext-apps helper, but nothing ggui renders consumes that
+ * vocabulary, and the scoped token block shadows root inheritance
+ * anyway — so without this mapping a host palette repaints nothing.
+ * `buildOpts` threads it onto the mount options; the renderer merges
+ * it as the fallback layer BENEATH the slice's own theme (ggui#573
+ * ruling: slice wins, host fallback).
+ *
+ * @internal — exported for unit tests (`setCurrentApp` injects the
+ *   App); production caller is `buildOpts` inside `bootSequence`.
+ */
+export declare function hostAnnouncedPalette(): Readonly<Record<string, string>> | undefined;
 /**
  * @internal — exported for unit tests to reset module state between
  * scenarios.
@@ -733,7 +814,7 @@ export declare function requestDisplayModeInParent(args: {
  * or honor an upstream `defaultPrevented` from a higher-priority
  * handler.
  *
- * Idempotent: re-mounts (via `installPostMountListener`) call this
+ * Idempotent: re-mounts (via `installPersistentToolResultListener`) call this
  * helper again; the {@link anchorClickInterceptInstalled} guard makes
  * subsequent calls a no-op.
  */