@ggui-ai/iframe-runtime 0.9.0 → 0.11.0

package/dist/compiled-validators.d.ts

@@ -39,17 +39,26 @@ export declare const EMPTY_COMPILED_VALIDATOR_SET: CompiledValidatorSet;
  */
 export declare function loadCompiledValidators(meta: CompiledContractValidators | undefined, warn?: (message: string, detail: unknown) => void): Promise<CompiledValidatorSet>;
 /**
- * #109 content-addressable variant: fetch the validator-bundle URL,
- * dynamic-import the response, then delegate to
- * {@link loadCompiledValidators}. Returns {@link EMPTY_COMPILED_VALIDATOR_SET}
+ * #109 content-addressable variant: fetch the validator-bundle URL via
+ * ONE dynamic import. Returns {@link EMPTY_COMPILED_VALIDATOR_SET}
  * when `url` is undefined OR the fetch/import fails — sidecar
  * semantics, the server-side `assertActionContract` gate remains
  * authoritative on validator absence.
  *
- * Response shape: an ES module whose `default` export is a
- * {@link CompiledContractValidators} object (produced server-side by
- * `bundleCompiledValidatorsAsModule`). `Cache-Control: immutable` so
- * repeat renders with the same contract hit browser cache with no
+ * Response shape (v2 executable format, ggui#522 slice 2): an ES
+ * module whose `default` export carries the validate FUNCTIONS
+ * themselves (produced server-side by
+ * `bundleValidatorExprsAsExecutableModule`) — the single https import
+ * is the whole load, governed by `script-src` origins alone. No
+ * per-validator `blob:` import remains on this path, which is what
+ * lets a strict-CSP embedder (no `blob:`, no `data:`, no
+ * `'unsafe-eval'`) run client-side outbound validation at all.
+ *
+ * A default export whose leaves are not functions (the retired v1
+ * format carried module SOURCES as strings — reachable only through a
+ * stale CDN copy under a pre-salt URL, which no current slice mints)
+ * degrades to the empty set with a warning. `Cache-Control: immutable`
+ * so repeat renders with the same contract hit browser cache with no
  * round-trip.
  */
 export declare function loadCompiledValidatorsFromUrl(url: string | undefined, warn?: (message: string, detail: unknown) => void): Promise<CompiledValidatorSet>;

package/dist/compiled-validators.js

@@ -73,17 +73,26 @@ export async function loadCompiledValidators(meta, warn) {
     };
 }
 /**
- * #109 content-addressable variant: fetch the validator-bundle URL,
- * dynamic-import the response, then delegate to
- * {@link loadCompiledValidators}. Returns {@link EMPTY_COMPILED_VALIDATOR_SET}
+ * #109 content-addressable variant: fetch the validator-bundle URL via
+ * ONE dynamic import. Returns {@link EMPTY_COMPILED_VALIDATOR_SET}
  * when `url` is undefined OR the fetch/import fails — sidecar
  * semantics, the server-side `assertActionContract` gate remains
  * authoritative on validator absence.
  *
- * Response shape: an ES module whose `default` export is a
- * {@link CompiledContractValidators} object (produced server-side by
- * `bundleCompiledValidatorsAsModule`). `Cache-Control: immutable` so
- * repeat renders with the same contract hit browser cache with no
+ * Response shape (v2 executable format, ggui#522 slice 2): an ES
+ * module whose `default` export carries the validate FUNCTIONS
+ * themselves (produced server-side by
+ * `bundleValidatorExprsAsExecutableModule`) — the single https import
+ * is the whole load, governed by `script-src` origins alone. No
+ * per-validator `blob:` import remains on this path, which is what
+ * lets a strict-CSP embedder (no `blob:`, no `data:`, no
+ * `'unsafe-eval'`) run client-side outbound validation at all.
+ *
+ * A default export whose leaves are not functions (the retired v1
+ * format carried module SOURCES as strings — reachable only through a
+ * stale CDN copy under a pre-salt URL, which no current slice mints)
+ * degrades to the empty set with a warning. `Cache-Control: immutable`
+ * so repeat renders with the same contract hit browser cache with no
  * round-trip.
  */
 export async function loadCompiledValidatorsFromUrl(url, warn) {
@@ -96,7 +105,31 @@ export async function loadCompiledValidatorsFromUrl(url, warn) {
             warn?.('[ggui:validators] contract bundle: default export is not an object', compiled);
             return EMPTY_COMPILED_VALIDATOR_SET;
         }
-        return loadCompiledValidators(compiled, warn);
+        const groups = compiled;
+        const pickGroup = (group, kind) => {
+            const map = new Map();
+            if (group === undefined)
+                return map;
+            for (const [name, fn] of Object.entries(group)) {
+                if (isValidateFunction(fn)) {
+                    map.set(name, fn);
+                }
+                else {
+                    warn?.(`[ggui:validators] ${kind}.${name}: bundle entry is not a function (stale v1-format bundle?)`, typeof fn);
+                }
+            }
+            return map;
+        };
+        const props = isValidateFunction(groups.props) ? groups.props : undefined;
+        if (groups.props !== undefined && props === undefined) {
+            warn?.('[ggui:validators] props: bundle entry is not a function (stale v1-format bundle?)', typeof groups.props);
+        }
+        return {
+            ...(props !== undefined ? { props } : {}),
+            actions: pickGroup(groups.actions, 'action'),
+            streams: pickGroup(groups.streams, 'stream'),
+            context: pickGroup(groups.context, 'context'),
+        };
     }
     catch (err) {
         warn?.(`[ggui:validators] contract bundle: failed to load ${url}`, err);

package/dist/host-palette-bridge.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Spec→ggui token bridge (ggui#572).
+ *
+ * MCP Apps hosts announce their palette as spec `--color-*` custom
+ * properties in `hostContext.styles.variables`. The canonical
+ * `@modelcontextprotocol/ext-apps` helper applies them as inline
+ * custom properties on the iframe `<html>` — which is correct spec
+ * behavior but repaints nothing ggui renders: generated UI, the
+ * design system, and the shell chrome consume exclusively `--ggui-*`
+ * tokens, and the renderer's scoped in-body token block shadows
+ * root-level inheritance for every token it defines anyway.
+ *
+ * This module translates the spec vocabulary onto the ggui token
+ * ladder so the renderer can merge the host's palette INTO the scoped
+ * block — as the fallback layer beneath the app's own theme (#573
+ * ruling: the slice's stamped theme wins; the host palette fills the
+ * slots no operator repainted).
+ *
+ * Coverage is deliberately PARTIAL in both directions:
+ *
+ *   - Spec keys with no faithful ggui counterpart (ghost/disabled/
+ *     inverse variants, ring colors, fonts, radii, shadows) are
+ *     dropped — they keep applying via the ext-apps inline-DOM path
+ *     for any non-ggui content, and inventing a mapping would repaint
+ *     tokens with the WRONG semantic role.
+ *   - ggui tokens the spec doesn't express (the primary accent scale,
+ *     containers beyond error, the neutral ladder) keep their
+ *     mode-resolved base values — the host-announced color MODE
+ *     (ggui#551) already selects the coherent light/dark ladder these
+ *     slots resolve from.
+ */
+/**
+ * Map a host-announced `styles.variables` record onto `--ggui-*`
+ * declarations ready for the renderer's scoped token block.
+ *
+ * Unknown keys and unsafe/blank values are dropped silently (the same
+ * tolerant posture as the rest of host-context handling — a partial
+ * palette is a partial repaint, never an error). Returns `undefined`
+ * when nothing survives so callers can spread-skip the option.
+ *
+ * @public
+ */
+export declare function mapHostPaletteToGguiVars(variables: Readonly<Record<string, string | undefined>> | undefined): Readonly<Record<string, string>> | undefined;

package/dist/host-palette-bridge.js

@@ -0,0 +1,107 @@
+/**
+ * Spec→ggui token bridge (ggui#572).
+ *
+ * MCP Apps hosts announce their palette as spec `--color-*` custom
+ * properties in `hostContext.styles.variables`. The canonical
+ * `@modelcontextprotocol/ext-apps` helper applies them as inline
+ * custom properties on the iframe `<html>` — which is correct spec
+ * behavior but repaints nothing ggui renders: generated UI, the
+ * design system, and the shell chrome consume exclusively `--ggui-*`
+ * tokens, and the renderer's scoped in-body token block shadows
+ * root-level inheritance for every token it defines anyway.
+ *
+ * This module translates the spec vocabulary onto the ggui token
+ * ladder so the renderer can merge the host's palette INTO the scoped
+ * block — as the fallback layer beneath the app's own theme (#573
+ * ruling: the slice's stamped theme wins; the host palette fills the
+ * slots no operator repainted).
+ *
+ * Coverage is deliberately PARTIAL in both directions:
+ *
+ *   - Spec keys with no faithful ggui counterpart (ghost/disabled/
+ *     inverse variants, ring colors, fonts, radii, shadows) are
+ *     dropped — they keep applying via the ext-apps inline-DOM path
+ *     for any non-ggui content, and inventing a mapping would repaint
+ *     tokens with the WRONG semantic role.
+ *   - ggui tokens the spec doesn't express (the primary accent scale,
+ *     containers beyond error, the neutral ladder) keep their
+ *     mode-resolved base values — the host-announced color MODE
+ *     (ggui#551) already selects the coherent light/dark ladder these
+ *     slots resolve from.
+ */
+/**
+ * Spec `--color-*` key → ggui token, one entry per slot whose semantic
+ * role matches 1:1. Semantic status text maps to the ladder's `-500`
+ * stop — the "live" stop tone slots and Alert actually read; a flat
+ * `--ggui-color-error` target would repaint nothing (no theme emits
+ * flat semantic tokens).
+ */
+const SPEC_TO_GGUI = {
+    '--color-background-primary': '--ggui-color-surface',
+    '--color-background-secondary': '--ggui-color-surfaceVariant',
+    '--color-background-tertiary': '--ggui-color-container',
+    '--color-background-danger': '--ggui-color-errorContainer',
+    '--color-text-primary': '--ggui-color-onSurface',
+    '--color-text-secondary': '--ggui-color-onSurfaceVariant',
+    '--color-text-tertiary': '--ggui-color-neutral-500',
+    '--color-text-danger': '--ggui-color-error-500',
+    '--color-text-success': '--ggui-color-success-500',
+    '--color-text-warning': '--ggui-color-warning-500',
+    '--color-text-info': '--ggui-color-info-500',
+    '--color-border-primary': '--ggui-color-outline',
+    '--color-border-secondary': '--ggui-color-outlineVariant',
+};
+/**
+ * Host palette values arrive over postMessage and are string-joined
+ * into a `<style>` element by the renderer — unlike the app's own
+ * theme overlay they are NOT pre-validated by the wire parser, so
+ * this is the sanitization gate. Conservative deny-list: anything
+ * that could close the declaration (`;`), the rule (`{`/`}`), or the
+ * style element (`<`/`>`), smuggle strings/escapes, comment out the
+ * rest of the sheet (`/*`), or trigger a fetch (`url(`) drops the
+ * value. Plain color syntax — hex, rgb()/hsl()/oklch()/color-mix(),
+ * named colors — passes untouched.
+ */
+function isSafeCssValue(value) {
+    if (value.length === 0 || value.length > 256)
+        return false;
+    if (/[;{}<>"'`\\]/.test(value))
+        return false;
+    if (/\/\*/.test(value))
+        return false;
+    if (/url\s*\(/i.test(value))
+        return false;
+    // Control characters (incl. newlines) have no place in a color value.
+    // eslint-disable-next-line no-control-regex
+    if (/[\u0000-\u001f\u007f]/.test(value))
+        return false;
+    return true;
+}
+/**
+ * Map a host-announced `styles.variables` record onto `--ggui-*`
+ * declarations ready for the renderer's scoped token block.
+ *
+ * Unknown keys and unsafe/blank values are dropped silently (the same
+ * tolerant posture as the rest of host-context handling — a partial
+ * palette is a partial repaint, never an error). Returns `undefined`
+ * when nothing survives so callers can spread-skip the option.
+ *
+ * @public
+ */
+export function mapHostPaletteToGguiVars(variables) {
+    if (variables === undefined)
+        return undefined;
+    const mapped = {};
+    let count = 0;
+    for (const [specKey, gguiKey] of Object.entries(SPEC_TO_GGUI)) {
+        const raw = variables[specKey];
+        if (typeof raw !== 'string')
+            continue;
+        const value = raw.trim();
+        if (!isSafeCssValue(value))
+            continue;
+        mapped[gguiKey] = value;
+        count += 1;
+    }
+    return count > 0 ? mapped : undefined;
+}