@unoverse-platform/studio 0.1.0

package/src/universes.ts

@@ -0,0 +1,210 @@
+/**
+ * The universes this developer can publish to.
+ *
+ * A UNIVERSE NAMES ITS OWN IDENTITY PROVIDER. Studio hardcodes no issuer and no vendor:
+ * it asks a universe at `/.well-known/unoverse-universe` and follows the answer, so
+ * Auth0, Okta, Entra and Keycloak all work with no change here. That is the whole reason
+ * login lives in Studio (a browser, where OIDC is a redirect) rather than in the CLI.
+ *
+ * THERE IS NO CENTRAL DIRECTORY, and there cannot be. Every universe is independent with
+ * its own database and its own IdP (docs/AUTH_TOKEN_FLOW.md: "OIDC-provider-agnostic").
+ * Nothing sits above them to enumerate. So "the universes I can deploy to" means the ones
+ * this developer has connected to, held here on their machine. That is the honest answer,
+ * not a placeholder for a registry.
+ *
+ * NO TOKEN IS EVER WRITTEN HERE. Only the URL, a label, and the public config. The access
+ * token stays wherever the OIDC library keeps it for the session. Local Studio already
+ * holds this line for credentials (`local/keys.ts`: "Studio therefore never WRITES a
+ * secret") and connecting to a universe must not be the thing that breaks it.
+ *
+ * See docs/architecture/LOCAL_STUDIO.md.
+ */
+
+/** What a universe publishes about itself. Mirrors `getPublicAuthConfig()` on the server. */
+export interface UniverseConfig {
+  /** False means the universe is not gated at all: do not send anyone to log in. */
+  authEnabled: boolean;
+  issuer: string | null;
+  clientId: string | null;
+  audience: string | null;
+  /** The permission a token needs before this universe accepts a publish. */
+  publishPermission: string;
+}
+
+export interface Universe {
+  /** Origin, normalised. The identity of the entry: one row per universe. */
+  url: string;
+  /** What the developer calls it. Defaults to the host. */
+  label: string;
+  config: UniverseConfig;
+  /** When it was last reachable, ISO. Purely informational. */
+  connectedAt?: string;
+}
+
+const STORAGE_KEY = "studio:universes";
+
+/** The path a universe serves its public config on. */
+export const DISCOVERY_PATH = "/.well-known/unoverse-universe";
+
+/**
+ * Turn whatever a developer typed into an origin.
+ *
+ * People type `localhost:4105`, `example.com/`, and `https://example.com/canvas`. All
+ * three mean one universe, and storing them as three entries would let the same universe
+ * hold three different logins. So this is the identity function for the list.
+ *
+ * Bare hosts default to https, EXCEPT localhost and 127.0.0.1, which are overwhelmingly
+ * a developer's own machine over http and would otherwise fail confusingly.
+ */
+export function normaliseUrl(input: string): string {
+  const trimmed = (input ?? "").trim();
+  if (!trimmed) throw new Error("Enter a universe address");
+
+  const isLocal = /^(https?:\/\/)?(localhost|127\.0\.0\.1)(:|\/|$)/i.test(trimmed);
+  const withScheme = /^https?:\/\//i.test(trimmed) ? trimmed : `${isLocal ? "http" : "https"}://${trimmed}`;
+
+  let parsed: URL;
+  try {
+    parsed = new URL(withScheme);
+  } catch {
+    throw new Error(`"${input}" is not a valid address`);
+  }
+  return parsed.origin;
+}
+
+/** A readable default name: the host, without the port for a real domain. */
+export function defaultLabel(url: string): string {
+  try {
+    return new URL(url).host;
+  } catch {
+    return url;
+  }
+}
+
+/**
+ * Ask a universe how to log in.
+ *
+ * Failure here is the common case, not the exception: wrong address, universe down, a
+ * plain website that is not a universe at all. Each gets a message a developer can act
+ * on, because "Failed to fetch" tells them nothing about which of the three it was.
+ */
+export async function discover(
+  url: string,
+  fetchImpl: typeof fetch = fetch,
+): Promise<UniverseConfig> {
+  let response: Response;
+  try {
+    response = await fetchImpl(`${url}${DISCOVERY_PATH}`, { headers: { accept: "application/json" } });
+  } catch {
+    throw new Error(`Could not reach ${url}. Check the address, and that the universe is running.`);
+  }
+
+  if (response.status === 404) {
+    throw new Error(`Something answered at ${url}, but it is not a universe.`);
+  }
+  if (!response.ok) {
+    throw new Error(`${url} answered with an error (${response.status}).`);
+  }
+
+  let body: unknown;
+  try {
+    body = await response.json();
+  } catch {
+    throw new Error(`${url} answered, but not like a universe. If it is one, it may need restarting.`);
+  }
+
+  const cfg = body as Partial<UniverseConfig>;
+  // authEnabled is the field that decides whether we send someone to log in, so its
+  // absence is a broken response rather than a default worth guessing at.
+  if (typeof cfg?.authEnabled !== "boolean") {
+    throw new Error(`${url} answered, but not like a universe. If it is one, it may need restarting.`);
+  }
+
+  return {
+    authEnabled: cfg.authEnabled,
+    issuer: cfg.issuer ?? null,
+    clientId: cfg.clientId ?? null,
+    audience: cfg.audience ?? null,
+    publishPermission: cfg.publishPermission ?? "marketplace:publish",
+  };
+}
+
+/**
+ * Can this universe actually be logged into?
+ *
+ * A universe can say `authEnabled: true` and still be missing an issuer or a client id,
+ * which is a misconfigured universe rather than a Studio problem. Saying so beats
+ * redirecting the browser to `undefined`.
+ */
+export function loginReady(config: UniverseConfig): { ok: true } | { ok: false; reason: string } {
+  if (!config.authEnabled) return { ok: false, reason: "This universe has authentication switched off." };
+  if (!config.issuer) return { ok: false, reason: "This universe has no identity provider configured." };
+  if (!config.clientId) return { ok: false, reason: "This universe has no client id configured for sign-in." };
+  return { ok: true };
+}
+
+/**
+ * Does this token allow publishing here?
+ *
+ * Checked so Studio can say "signed in, but not allowed to publish" up front, instead of
+ * letting someone build for an hour and fail on the push. Namespace-aware for the same
+ * reason the server is: an IdP may emit `permissions` under a namespaced claim, and a
+ * plain read silently returns nothing (docs/AUTH_TOKEN_FLOW.md).
+ */
+export function canPublish(claims: Record<string, unknown> | null | undefined, config: UniverseConfig): boolean {
+  if (!claims) return false;
+  const direct = claims.permissions;
+  const namespacedKey = Object.keys(claims).find(
+    (k) => k.endsWith("/permissions") || k.endsWith("/claims/permissions"),
+  );
+  const list = Array.isArray(direct) ? direct : namespacedKey && Array.isArray(claims[namespacedKey]) ? (claims[namespacedKey] as unknown[]) : [];
+
+  // TRIMMED, because a permission is typed into an identity provider by a person and a
+  // stray space is invisible everywhere it is displayed. One arrived as " marketplace:publish"
+  // and cost a long debugging session: the Auth0 screen showed it assigned, the token
+  // carried it, the label printed it, and the comparison correctly said no. Nothing about
+  // surrounding whitespace is ever meaningful in a permission name.
+  const wanted = String(config.publishPermission).trim();
+  return list.some((p) => String(p).trim() === wanted);
+}
+
+// ── The stored list ───────────────────────────────────────────────────────
+
+type Store = Pick<Storage, "getItem" | "setItem">;
+
+function store(): Store | null {
+  try {
+    return typeof localStorage === "undefined" ? null : localStorage;
+  } catch {
+    return null; // storage blocked (private mode, embedded contexts)
+  }
+}
+
+/** Every universe this developer has connected to. Never throws: a corrupt entry is
+ *  dropped rather than taking the whole list, and the app down with it. */
+export function loadUniverses(storage: Store | null = store()): Universe[] {
+  const raw = storage?.getItem(STORAGE_KEY);
+  if (!raw) return [];
+  try {
+    const parsed = JSON.parse(raw);
+    if (!Array.isArray(parsed)) return [];
+    return parsed.filter((u): u is Universe => typeof u?.url === "string" && typeof u?.config?.authEnabled === "boolean");
+  } catch {
+    return [];
+  }
+}
+
+/** Add or update one, keyed on url so reconnecting refreshes rather than duplicates. */
+export function saveUniverse(universe: Universe, storage: Store | null = store()): Universe[] {
+  const next = [...loadUniverses(storage).filter((u) => u.url !== universe.url), universe].sort((a, b) =>
+    a.label.localeCompare(b.label),
+  );
+  storage?.setItem(STORAGE_KEY, JSON.stringify(next));
+  return next;
+}
+
+export function removeUniverse(url: string, storage: Store | null = store()): Universe[] {
+  const next = loadUniverses(storage).filter((u) => u.url !== url);
+  storage?.setItem(STORAGE_KEY, JSON.stringify(next));
+  return next;
+}

package/vendor/sdk/appEngine.tsx

@@ -0,0 +1,219 @@
+/**
+ * The native app ENGINE (§6d) — surface-agnostic. It:
+ *   - reads its OWN workflow binding from its manifest (§4b: "App supplies workflow, trigger"),
+ *   - opens the SDK's native connection (`/stream` register_session → store),
+ *   - fires the workflow DIRECTLY via `conn.sendMessage` → REST `{apiUrl}/api/workflows/:id/execute`
+ *     with the USER's token (§5a: "direct channel → Gravity backend — never brokered").
+ *
+ * The server tool only LOADS this app; it never fires or brokers a token. Uses the LOCAL
+ * vendored SDK (./lib), not the npm package.
+ */
+import { useEffect, useMemo, useRef, useState } from "react";
+import {
+  UnoverseClient,
+  ComponentStore,
+  StreamedUnoverseTemplate,
+  useUnoverseConnection,
+  useUnoverseTheme,
+  computeAppWidth,
+  resolveActiveLayout,
+  type UseVoiceServiceConfig,
+} from "./lib";
+
+export interface AppConfig {
+  serverUrl: string;
+  apiUrl?: string;
+  templateId: string;
+  getAccessToken?: () => Promise<string | null> | string | null;
+  userId?: string;
+  conversationId: string;
+}
+
+export function AppEngine(cfg: AppConfig) {
+  const { serverUrl, apiUrl, templateId, getAccessToken, userId, conversationId } = cfg;
+
+  const store = useMemo(() => new ComponentStore(), []);
+  const client = useMemo(
+    () => new UnoverseClient(`${serverUrl}/mcp`, { getAccessToken: getAccessToken as any }),
+    [serverUrl],
+  );
+  const [binding, setBinding] = useState<{ workflow?: string; trigger?: string; service?: string }>({});
+  // STATE-OWNED WIDTH (rx data): the layout root's `appWidth` = the core surface's
+  // constant width; an occupied panel slot's `appWidth` adds to it (computeAppWidth).
+  // No declared width → the host keeps its own default. There is no other path.
+  const [def, setDef] = useState<{ root?: unknown; org?: string; layouts?: Record<string, unknown>; defaultLayout?: string } | null>(null);
+  const lastWidthRef = useRef<string | undefined>(undefined);
+  // Named app sizes resolve via the served theme (theme.appSize), like every token.
+  const theme = useUnoverseTheme(client, def ? (def.org ? `${def.org}/light` : "light") : null);
+
+  // The app owns which workflow it runs — read it from its manifest (§4b), not from config.
+  useEffect(() => {
+    let alive = true;
+    client
+      .connect()
+      .then(() => (client as any).client.readResource({ uri: `unoverse://apps/${templateId.toLowerCase()}` }))
+      .then((res: any) => {
+        const parsed = res?.contents?.[0]?.text ? JSON.parse(res.contents[0].text) : null;
+        const m = parsed?.manifest ?? parsed ?? {};
+        const b = m.binding ?? {};
+        // `service` (e.g. "voice") is the app's own declaration — it selects whether the
+        // renderer runs a native service. Read it here, next to the binding, and forward it.
+        if (alive) setBinding({ workflow: b.workflow, trigger: b.trigger, service: m.service });
+      })
+      .catch((e) => console.error("[app] manifest read failed:", e));
+    // The width lives in the template DATA (root/slot `appWidth`), so read the
+    // definition too — same resource the renderer loads.
+    client
+      .connect()
+      .then(() => client.readDefinition(`unoverse://templates/${templateId}`))
+      .then((d) => {
+        const t = d as { root?: unknown; org?: string; layouts?: Record<string, unknown>; defaultLayout?: string } | null;
+        if (alive) setDef(t ? { root: t.root, org: t.org, layouts: t.layouts, defaultLayout: t.defaultLayout } : null);
+      })
+      .catch((e) => console.error("[app] template read failed:", e));
+    return () => {
+      alive = false;
+    };
+  }, [client, templateId]);
+
+  // Report the app's width UP to the embedding host (iframe boundary → the twin of the
+  // inbound `unoverse:config` channel), re-reporting whenever a panel surface opens or
+  // closes: the app grows by the panel's declared width, then shrinks back. The host
+  // animates the resize. Only posts on an ACTUAL width change (guard).
+  useEffect(() => {
+    const report = () => {
+      // NAME-SYNC: width is computed off the ACTIVE layout (multi-layout templates
+      // swap whole arrangements); single-layout defs resolve to their root.
+      const w = computeAppWidth(resolveActiveLayout(def as never, store), store, theme?.appSize);
+      if (w && w !== lastWidthRef.current) {
+        lastWidthRef.current = w;
+        window.parent?.postMessage({ type: "unoverse:size", width: w }, "*");
+      }
+    };
+    report();
+    return store.subscribe(report);
+  }, [store, def, theme]);
+
+  // SDK's native connection: opens /stream, register_session, feeds the store. Outbound
+  // sendMessage fires the workflow DIRECTLY (REST, user token) — no server broker.
+  const conn = useUnoverseConnection(
+    { apiUrl: apiUrl ?? serverUrl, streamUrl: serverUrl, getAccessToken: getAccessToken as any },
+    {
+      workflowId: binding.workflow ?? "",
+      targetTriggerNode: binding.trigger ?? "",
+      userId: userId ?? "",
+      conversationId,
+      chatId: conversationId,
+    },
+    store,
+    // Open only once BOTH are ready: the user identity AND the manifest binding (read async).
+    // Avoids the transient "connection missing workflowId/userId/conversationId" warning.
+    { enabled: !!userId && !!binding.workflow },
+  );
+
+  // VOICE (§2e-1): a `service: "voice"` app runs the native voice service — which now lives
+  // in the shared renderer (StreamedUnoverseTemplate), identical to Studio. The host only
+  // supplies the connection identity it already holds; startCall/endCall/toggleMute are
+  // answered inside the renderer, so this host wires NO voice buttons. Absent → inert.
+  const voiceConfig = useMemo<UseVoiceServiceConfig | undefined>(
+    () =>
+      binding.service === "voice" && binding.workflow
+        ? {
+            // START_CALL REST triggers the workflow on the gateway (user token). The audio
+            // WS lane is derived by the SDK from the client's server origin (see the renderer)
+            // — the host passes NO wsUrl (its srcdoc `location.origin` is "null").
+            apiUrl: apiUrl ?? serverUrl,
+            getAccessToken: getAccessToken as UseVoiceServiceConfig["getAccessToken"],
+            session: {
+              userId: userId ?? "",
+              conversationId,
+              chatId: conversationId,
+              workflowId: binding.workflow,
+              targetTriggerNode: binding.trigger ?? "",
+            },
+            // Producer: writes callState/isMuted into TEMPLATE STATE so the voice states switch.
+            store,
+          }
+        : undefined,
+    [binding.service, binding.workflow, binding.trigger, apiUrl, serverUrl, getAccessToken, userId, conversationId, store],
+  );
+
+  return (
+    <StreamedUnoverseTemplate
+      client={client}
+      store={store}
+      uri={`unoverse://templates/${templateId}`}
+      voice={voiceConfig}
+      onAction={(action, data, meta) => {
+        const t = typeof action === "string" ? action : (action as any)?.type;
+        if (t === "close") {
+          // The app owns its close chrome (its own top-right X). Tell the embedding host to
+          // dismiss the surface (twin of `unoverse:config`/`unoverse:size`). The host decides
+          // what "close" means for its frame (slide the drawer shut); we don't assume.
+          window.parent?.postMessage({ type: "unoverse:close" }, "*");
+          return;
+        }
+        if (t === "sendMessage") {
+          // A suggestion that NAMES AN APP launches it instead of sending its text: read
+          // that app's manifest (the binding lives there — §4b, never in template data)
+          // and fire its trigger. The `text` field stays as the fallback for channels
+          // without launch support. Same-workflow apps only for now: the connection
+          // posts to the BOUND workflow id, so a foreign-workflow app logs and falls
+          // through to its trigger on the bound workflow.
+          const app = typeof (data as any)?.app === "string" ? (data as any).app : "";
+          if (app) {
+            (client as any).client
+              .readResource({ uri: `unoverse://apps/${app.toLowerCase()}` })
+              .then((res: any) => {
+                const parsed = res?.contents?.[0]?.text ? JSON.parse(res.contents[0].text) : null;
+                const b = parsed?.manifest?.binding ?? parsed?.binding ?? {};
+                if (!b.trigger) return console.error("[app] launch failed: no binding on", app);
+                if (b.workflow && binding.workflow && b.workflow !== binding.workflow)
+                  console.warn("[app] launch:", app, "binds a different workflow — firing its trigger on the bound workflow");
+                // LOADING STATE: write the app's declared defaultState (open NAME; `mode` =
+                // pre-rename alias) into template state NOW — e.g. a "focus" app pre-opens
+                // the focus surface, whose slot shows its fallback (skeleton) until the
+                // workflow streams the component in. Same template-state key the node's
+                // TEMPLATE_DATA emit writes; no new vocabulary. "template" apps ARE the
+                // surface — nothing to write.
+                const declared = parsed?.manifest?.defaultState ?? parsed?.manifest?.mode ?? parsed?.defaultState ?? parsed?.mode;
+                if (declared && declared !== "template") store.mergeTemplateState({ defaultState: declared });
+                conn.trigger({ app, metadata: { targetTriggerNode: b.trigger } });
+              })
+              .catch((e: any) => console.error("[app] launch failed:", e));
+            return;
+          }
+          // Composer submit is generic: Enter carries `text`; a send BUTTON carries none,
+          // so fall back to the shared draft the store already holds (same as Studio).
+          const text = (typeof (data as any)?.text === "string" && (data as any).text) || store.getDraft();
+          if (text.trim()) {
+            conn.sendMessage(text);
+            store.setDraft(""); // clear the composer after sending (the Input binds `draft`)
+          }
+          return;
+        }
+        // Controlled composer: the Input emits "input" on every keystroke → the shared
+        // draft (local, never a server round-trip). A send button / Enter emits "sendMessage".
+        if (t === "input") {
+          store.setDraft(typeof (data as any)?.text === "string" ? (data as any).text : "");
+          return;
+        }
+        // Any other named server action (submit, selectCourse…): if the server is
+        // ELICITING on this session (the native §3.3 path — an app tool call is
+        // waiting), the submitted state ANSWERS the elicitation; one accept then
+        // completes the waiting node AND the held tool call server-side. Otherwise
+        // fall back to the data-plane `user_action` submit (waiter transport).
+        if (!t) return;
+        const state = (meta?.state ?? data) as Record<string, unknown>;
+        if (conn.resolveElicitation(state)) return;
+        conn.sendAction(t, {
+          componentNodeId: meta?.nodeId,
+          // The component's OWN chatId is the TURN id — the waiting node execution is
+          // keyed `<turn>:<nodeId>`, not the conversation-level chatId.
+          componentChatId: meta?.chatId,
+          componentState: state,
+        });
+      }}
+    />
+  );
+}

package/vendor/sdk/lib/UnoverseComponent.tsx

@@ -0,0 +1,120 @@
+/**
+ * <UnoverseComponent> — reads a definition by URI from the Unoverse MCP server
+ * (via ./core) and renders it natively with the given data.
+ */
+import { useEffect, useMemo, useState, type CSSProperties } from "react";
+import type { ResolvedTheme, UnoverseClient, UnoverseDefinition } from "./core";
+import { renderNode, keyframesCss, type ActionHandler } from "./render";
+import { useUnoverseTheme, ensureFontStylesheets } from "./theme";
+import { IsolatedRoot } from "./isolate";
+
+export interface UnoverseComponentProps {
+  client: UnoverseClient;
+  /** e.g. "unoverse://components/Card" */
+  uri: string;
+  /** instance data bound into the definition (the streamed props) */
+  data?: Record<string, unknown>;
+  onAction?: ActionHandler;
+  /**
+   * Resolved theme. Optional — if omitted, the SDK FETCHES it from the server
+   * (`unoverse://theme/light`). The SDK bundles no tokens. Pass one to override
+   * (e.g. the workbench's light/dark toggle); swap it to restyle, zero def changes.
+   */
+  theme?: ResolvedTheme;
+  /**
+   * Render inside a Shadow DOM for full CSS isolation (default true). The SDK owns the
+   * isolation boundary so every consumer is protected identically; the canvas/channel no
+   * longer wrap it themselves. Set false only for a host that manages its own isolation.
+   */
+  isolate?: boolean;
+  /**
+   * A SURFACE'S SINGLE OCCUPANT FILLS THE SURFACE (docs/design/05): set by a limit-1
+   * reaction surface so the instance wrapper takes the frame's full height. The
+   * component still owns its face — this only gives its `height: "full"` a definite
+   * container. Flow/rail instances stay content-sized (never set there).
+   */
+  fill?: boolean;
+}
+
+export function UnoverseComponent({ client, uri, data, onAction, theme, isolate = true, fill = false }: UnoverseComponentProps) {
+  const [def, setDef] = useState<UnoverseDefinition | null>(null);
+  const [error, setError] = useState<string | null>(null);
+  // No theme passed → fetch it from the server (the SDK owns zero token values). The
+  // theme REF comes from the definition itself: a template's `org` names its client's
+  // theme (`<org>/light`); a universal component previews under the default set
+  // ("light" — channels pass their org's theme explicitly). Wait for the def before
+  // fetching (null = no fetch) so the wrong theme never flashes.
+  const fetched = useUnoverseTheme(client, theme ? null : def ? (def.org ? `${def.org}/light` : "light") : null);
+  const activeTheme = theme ?? fetched;
+  // Register the theme's webfonts (served DATA) at document level — see ensureFontStylesheets.
+  useEffect(() => ensureFontStylesheets(activeTheme), [activeTheme]);
+
+  useEffect(() => {
+    let alive = true;
+    setDef(null);
+    setError(null);
+    client
+      .readDefinition(uri)
+      .then((d) => alive && setDef(d))
+      .catch((e) => alive && setError(String(e?.message ?? e)));
+    return () => {
+      alive = false;
+    };
+  }, [client, uri]);
+
+  // Fill props the instance didn't provide from the definition's defaults; instance `data`
+  // overrides. This is what lets a partially-emitted component still render its declared
+  // baseline — e.g. StreamingText's `progressText` default ("Thinking…") shows while the node
+  // streams and hasn't emitted a progress line. IMPORTANT: a def `default` must therefore be
+  // a sensible RUNTIME fallback, NOT a demo placeholder — a demo-y default (e.g. a markdown
+  // showcase on `text`) would mask an empty stream. Keep demo content out of prop defaults.
+  // Memoized on the def — a streaming component re-renders per chunk; the defaults don't move.
+  const propDefaults = useMemo(
+    () =>
+      Object.fromEntries(
+        Object.entries((def?.props ?? {}) as Record<string, { default?: unknown }>).map(([k, v]) => [k, v?.default]),
+      ),
+    [def],
+  );
+
+  // Loading/error hints carry NO styling — the SDK owns zero styles (tokens or hints).
+  if (error) return <div>Unoverse error: {error}</div>;
+  if (!def || !activeTheme) return <div>Loading {uri}…</div>;
+  // Internal state initial values (def.state) sit beneath the live slice — the
+  // microapp's own keys (step/phase/…) start at their authored values and move only
+  // when its actions write them. Props stay the EXTERNAL contract.
+  const merged = { ...propDefaults, ...(def?.state ?? {}), ...(data ?? {}) };
+  // Inject the served keyframes + apply the SERVED base render-root (theme.root — DS typography
+  // + font-smoothing). When ISOLATED, theme.root is applied to the shadow-root container inside
+  // IsolatedRoot (a REAL box — reliable font cascade in the shadow tree). When NOT isolated the
+  // host owns isolation, so apply it here on a `display:contents` wrapper (out of layout while
+  // its inherited props cascade) — the design-system baseline either way.
+  const keyframes = <style>{keyframesCss(activeTheme)}</style>;
+  const tree = renderNode(def.root, merged, onAction, activeTheme);
+  // The isolation container MIRRORS the component root's declared sizing intent (§4a:
+  // the component owns its size; the host responds). A root that declares
+  // `height: "full"` needs a definite chain — the container passes the host's height
+  // through (100%). Any other root keeps an auto container → fit-to-content, the §5a
+  // default (a card in a timeline must NOT fill). Without this, a full-height
+  // component's 100% resolves against an auto box and silently collapses.
+  const fillsHost = fill || ((def.root as { style?: Record<string, unknown> })?.style?.height ?? null) === "full";
+  const isolatedRootStyle = {
+    ...(activeTheme.root as CSSProperties),
+    ...(fillsHost ? { height: "100%" } : {}),
+    ...(fill ? { flex: "1 1 auto", minHeight: 0 } : {}),
+  };
+  if (isolate) {
+    return (
+      <IsolatedRoot rootStyle={isolatedRootStyle}>
+        {keyframes}
+        {tree}
+      </IsolatedRoot>
+    );
+  }
+  return (
+    <>
+      {keyframes}
+      <div style={{ display: "contents", ...(activeTheme.root as CSSProperties) }}>{tree}</div>
+    </>
+  );
+}