@almadar/shell-web 0.0.0-stage → 1.0.0

package/dist/useUISlots-CiobNFGb.d.ts

@@ -0,0 +1,211 @@
+import React__default from 'react';
+import { UISlot, RenderItemLambda, EventPayloadValue, RowSetMarker } from '@almadar/core';
+
+/**
+ * useUISlots Hook
+ *
+ * Core hook for managing UI slot rendering in the trait-driven architecture.
+ * Traits use render_ui effects to dynamically render content into slots.
+ *
+ * Slots:
+ * - main: Primary content area
+ * - sidebar: Left/right sidebar
+ * - modal: Modal overlay
+ * - drawer: Slide-in drawer
+ * - overlay: Full-screen overlay
+ * - center: Centered popup
+ * - toast: Toast notifications
+ * - hud-top: Game HUD top bar
+ * - hud-bottom: Game HUD bottom bar
+ * - floating: Draggable floating panel
+ *
+ * Multi-source model (2026-04-24):
+ * A slot can receive renders from multiple source traits across independent
+ * batches (e.g. in the playground, ProbeCreate renders "main" on INIT, then
+ * later ProbePersistor cascades a render into "main" too). Prior code stored
+ * a single SlotContent per slot and last-writer-wins silently dropped
+ * earlier traits' frames. Internally the manager now holds a
+ * `Record<UISlot, Record<sourceKey, SlotContent>>` map and consumers see an
+ * aggregated view: a single SlotContent for single-source slots, or a
+ * synthetic `stack` wrapper when 2+ sources are active simultaneously.
+ * This mirrors the compiled-path page layout's VStack-of-trait-views.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Render-prop callback after fn-form-lambda conversion or
+ * `wrapCallbackForEvent` wrapping. Pattern components consume these as
+ * `renderItem` / `onTabChange` / `onClick` / etc. The arg list is
+ * contravariant (`never[]` accepts any caller shape — event handlers,
+ * 2-arg `(item, index)` render-props, etc.); the return is the union of
+ * shapes seen at this layer. Pattern-level prop types narrow the
+ * signature for each consumer downstream.
+ */
+type SlotCallback = (...args: never[]) => void | React__default.ReactNode | EventPayloadValue;
+/**
+ * Render-ui prop value: any leaf flowing from a `(render-ui slot {...})`
+ * effect into a React pattern component. The union enumerates every
+ * shape the renderer can receive — no `unknown` escape hatch.
+ *
+ * - JSON primitives (`string`, `number`, `boolean`, `Date`, `null`,
+ *   `undefined`) come through `BindingResolver`.
+ * - `RenderItemLambda` is the unconverted tuple form `["fn", arg, body]`;
+ *   `SlotCallback` is the post-conversion callable form.
+ * - `React.ReactNode` covers substituted `<TraitFrame>` elements.
+ * - The recursive array + object branches mirror the `EventPayloadValue`
+ *   shape but with `SlotPropValue` leaves so functions and React nodes
+ *   can appear at any depth (e.g. `tabs[].content: "@trait.X"` surviving
+ *   substitution into a `ReactElement`).
+ */
+type SlotPropValue = string | number | boolean | Date | null | undefined | RenderItemLambda | SlotCallback | React__default.ReactElement | RowSetMarker | ReadonlyArray<SlotPropValue> | {
+    readonly [key: string]: SlotPropValue;
+};
+/**
+ * Pattern-specific props carried by a rendered slot. The slot manager
+ * routes these from `(render-ui slot {...})` effects to React pattern
+ * components without coercion.
+ */
+type SlotProps = Record<string, SlotPropValue>;
+/**
+ * Content rendered in a slot
+ */
+interface SlotContent {
+    /** Unique ID for this content */
+    id: string;
+    /** Pattern/component type to render */
+    pattern: string;
+    /** Props to pass to the pattern component. A bare string is a whole-slot
+     * trait-embed reference (`(render-ui main "@trait.X")`) — the renderer lifts
+     * it to a TraitFrame. */
+    props: SlotProps | string;
+    /** Priority for conflict resolution (higher wins) */
+    priority: number;
+    /** Auto-dismiss timestamp (for toasts) */
+    autoDismissAt?: number;
+    /** Callback when dismissed */
+    onDismiss?: () => void;
+    /** Source trait that rendered this content */
+    sourceTrait?: string;
+    /** Stable node ID from the schema pattern tree (for edit mode overlay targeting) */
+    nodeId?: string;
+    /** Slot this content was rendered into (= SlotRenderConfig.target) — contextual-edit address. */
+    slot?: string;
+    /** Transition event key that produced this render (raw, as fired). */
+    transitionEvent?: string;
+    /** State the trait was in when this render fired (the from-state). */
+    fromState?: string;
+    /** linkedEntity of the source trait — contextual-edit address. */
+    entity?: string;
+}
+/**
+ * Configuration for render_ui effect
+ */
+interface SlotRenderConfig {
+    /** Target slot */
+    target: UISlot;
+    /** Pattern/component to render */
+    pattern: string;
+    /** Props for the pattern — or a bare `@trait.X` embed string */
+    props?: SlotProps | string;
+    /** Priority (default: 0) */
+    priority?: number;
+    /** Auto-dismiss after ms (for toasts) */
+    autoDismissMs?: number;
+    /** Callback on dismiss */
+    onDismiss?: () => void;
+    /** Source trait name */
+    sourceTrait?: string;
+    /** Transition event key that produced this render (raw, as fired). */
+    transitionEvent?: string;
+    /** State the trait was in when this render fired (the from-state). */
+    fromState?: string;
+    /** linkedEntity of the source trait. */
+    entity?: string;
+}
+/**
+ * Callback for slot changes
+ */
+type SlotChangeCallback = (slot: UISlot, content: SlotContent | null) => void;
+/**
+ * Fires when a specific trait's current render-ui output changes.
+ * Used by `<TraitFrame>` to subscribe only to the trait it embeds,
+ * avoiding wide re-renders when unrelated slots update.
+ *
+ * Per-trait index stores exactly one entry per trait (the most recent
+ * render), so the callback signature carries just the new content —
+ * no per-slot disambiguation needed.
+ */
+type TraitChangeCallback = (content: SlotContent | null) => void;
+/**
+ * UI Slot Manager interface
+ */
+interface UISlotManager {
+    /**
+     * Current aggregate content for each slot. Single-source slots hold
+     * that source's SlotContent; multi-source slots hold a synthetic
+     * `stack` wrapper whose `children` prop is the list of per-source
+     * pattern configs in insertion order. Single consumers can continue
+     * to read `slots[slot]` without knowing the slot is multi-source.
+     */
+    slots: Partial<Record<UISlot, SlotContent | null>>;
+    /** Render content to a slot */
+    render: (config: SlotRenderConfig) => string;
+    /** Clear all source entries from a slot */
+    clear: (slot: UISlot) => void;
+    /** Clear a single source's contribution from a slot, keeping others */
+    clearBySource: (slot: UISlot, sourceTrait: string) => void;
+    /** Clear content by ID */
+    clearById: (id: string) => void;
+    /** Clear all slots */
+    clearAll: () => void;
+    /** Subscribe to slot changes */
+    subscribe: (callback: SlotChangeCallback) => () => void;
+    /** Check if a slot has content */
+    hasContent: (slot: UISlot) => boolean;
+    /** Get aggregated content for a slot (single or synthetic stack) */
+    getContent: (slot: UISlot) => SlotContent | null;
+    /**
+     * Look up the most recent `render-ui` output a given trait produced,
+     * keyed by `SlotContent.sourceTrait`. Returns `null` when the trait
+     * hasn't rendered yet.
+     *
+     * Backs the `@trait.X` binding's client-side resolution via
+     * `<TraitFrame>`. See `docs/Almadar_Std_Gaps.md` §3.8. The binding is
+     * single-segment — there's intentionally no slot disambiguation.
+     */
+    getTraitContent: (traitName: string) => SlotContent | null;
+    /**
+     * Subscribe to changes in a specific trait's render output. Returns
+     * an unsubscribe function.
+     *
+     * Scoped per-trait so `<TraitFrame>` components only re-render when
+     * the trait they embed actually changes — not on every slot update.
+     */
+    subscribeTrait: (traitName: string, callback: TraitChangeCallback) => () => void;
+    /**
+     * Update only the per-trait sidecar without writing to any slot.
+     *
+     * Used for embed-aware slot routing: when a trait is referenced via
+     * `@trait.X` by a sibling layout's render-ui, its render output should
+     * not stack into the same slot the layout writes — the layout owns the
+     * slot and embeds the trait's frame via `<TraitFrame>`. This method
+     * keeps the per-trait sidecar (`traitIndexRef`) up-to-date so
+     * `<TraitFrame>` re-renders, while leaving `slots[target]` untouched.
+     *
+     * Mirrors what the compiled-path codegen does structurally — atoms
+     * inlined as JSX inside the layout's pattern, not writing slots.
+     */
+    updateTraitContent: (traitName: string, content: Omit<SlotContent, 'id' | 'sourceTrait'>) => string;
+}
+declare const DEFAULT_SLOTS: Partial<Record<UISlot, SlotContent | null>>;
+/**
+ * Create a UI Slot Manager instance.
+ *
+ * This is the internal hook that creates the manager.
+ * Use `useUISlots()` from context in components.
+ */
+declare function useUISlotManager(): UISlotManager;
+
+export { DEFAULT_SLOTS as D, useUISlotManager as u };
+export type { SlotChangeCallback as S, UISlotManager as U, SlotContent as a, SlotRenderConfig as b, SlotPropValue as c };

package/dist/verification-C5pTeMJv.d.ts

@@ -0,0 +1,66 @@
+import { OrbitalVerificationAPI, EventPayload, BusEvent } from '@almadar/core';
+
+/**
+ * Renderer-agnostic `window.__orbitalVerification` bridge.
+ *
+ * The single observation point Playwright-based verifiers
+ * (`runtime-verify`, `orbital-verify`, `@almadar-io/verify`) use to read
+ * state out of a live app and drive events into it. The wire types live
+ * in `@almadar/core` (see `types/verification.ts`); this module owns only
+ * the minimal exposure plumbing so any UI library — React, Web
+ * Components, or a future renderer — can populate the same contract
+ * without duplicating it.
+ *
+ * Framework-specific state (transition traces, reducer snapshots, bridge
+ * health) is left empty by default; a renderer that tracks them can
+ * override the readers after {@link ensureVerificationApi} runs. The two
+ * bindings every renderer must provide are {@link bindEventBus} (so
+ * automation can `sendEvent`) and {@link bindTraitStateGetter} (so
+ * automation can `getTraitState`).
+ *
+ * @packageDocumentation
+ */
+
+declare global {
+    interface Window {
+        __orbitalVerification?: OrbitalVerificationAPI;
+    }
+}
+/**
+ * Minimal structural surface a renderer's event bus must satisfy to be
+ * driven by automation. Matches the runtime `EventBus` (`emit` +
+ * optional `onAny`) without forcing a concrete class, so any UI
+ * library's bus — including `@almadar/runtime`'s own — plugs in.
+ */
+interface VerificationBus {
+    emit: (type: string, payload?: EventPayload) => void;
+    onAny?: (listener: (event: BusEvent) => void) => () => void;
+}
+/**
+ * Ensure `window.__orbitalVerification` exists with the required
+ * readers, then return it. Returns `undefined` outside a DOM (SSR /
+ * tests without a window). Idempotent: an existing object is returned
+ * untouched so a renderer that already registered readers keeps them.
+ */
+declare function ensureVerificationApi(): OrbitalVerificationAPI | undefined;
+/** Read the current bridge, if any. SSR-safe. */
+declare function getOrbitalVerification(): OrbitalVerificationAPI | undefined;
+/**
+ * Bind the renderer's event bus so automation can send events and read
+ * a rolling emission log.
+ *
+ * `sendEvent(event, payload, traitScope)` mirrors the React bridge:
+ * when `traitScope` is provided the event is emitted on the qualified
+ * key `UI:${traitScope}.${event}` (matching codegen-emitted
+ * subscription keys); otherwise the legacy bare form `UI:${event}` is
+ * used. An already-`UI:`-prefixed event is emitted verbatim.
+ */
+declare function bindEventBus(eventBus: VerificationBus): void;
+/**
+ * Bind a trait-state getter so automation can query a trait's current
+ * state machine state by name.
+ */
+declare function bindTraitStateGetter(getter: (traitName: string) => string | undefined): void;
+
+export { bindTraitStateGetter as a, bindEventBus as b, ensureVerificationApi as e, getOrbitalVerification as g };
+export type { VerificationBus as V };

package/dist/verificationRegistry-CVrcxG1s.d.ts

@@ -0,0 +1,122 @@
+import { D as DrawableNode } from './paintDispatch-CuJLsr9Y.js';
+import { OrbitalVerificationAPI, TraitStateSnapshot, EventPayload, BusEvent, VerificationCheck, BridgeHealth, VerificationSnapshot, VerificationSummary, TransitionTrace, EventRequest, EventResponse, ServerResponseTrace, EffectTrace, CheckStatus, ServerEffectResult, AssetLoadStatus } from '@almadar/core';
+import { EventTransport } from '@almadar/shell-runtime/client/EventTransport';
+import './verification-C5pTeMJv.js';
+
+/**
+ * Verification Registry - Tracks runtime verification checks and transition traces
+ *
+ * Provides:
+ * 1. A checklist of pass/fail checks (INIT has fetch, bridge connected, etc.)
+ * 2. A full transition timeline with effect execution results
+ * 3. ServerBridge health snapshot
+ * 4. window.__orbitalVerification for Playwright/automation
+ *
+ * @packageDocumentation
+ */
+
+type ChangeListener = () => void;
+/**
+ * Per-trait snapshot getter. Each generated trait logic hook (or
+ * `useTraitStateMachine` trait binding) registers one on mount so the
+ * verifier can read the live reducer state for that trait.
+ */
+type TraitSnapshotGetter = () => TraitStateSnapshot;
+declare function registerCheck(id: string, label: string, status?: CheckStatus, details?: string): void;
+declare function updateCheck(id: string, status: CheckStatus, details?: string): void;
+declare function getAllChecks(): VerificationCheck[];
+declare function recordTransition(trace: Omit<TransitionTrace, "id">): void;
+declare function getTransitions(): TransitionTrace[];
+declare function getTransitionsForTrait(traitName: string): TransitionTrace[];
+/**
+ * Record a server response as a timeline entry.
+ * Creates a synthetic transition entry with type "server-response" to show
+ * what the server returned (clientEffects, data counts, emitted events).
+ *
+ * `effectResults` — the server's persist/set/call-service outcomes, already
+ * mapped to `EffectTrace` by the caller — populate `entry.effects` so a
+ * denied or failed persist is visible on this synthetic entry too. Before
+ * this it was always `[]`: the ONLY entry the driver's per-event
+ * `server:<orbital>` lookup (`default-snapshot.ts`'s `lastEffectResultsFor`)
+ * can find carried nothing.
+ */
+declare function recordServerResponse(orbitalName: string, event: string, response: Omit<ServerResponseTrace, "orbitalName" | "timestamp"> & {
+    effectResults?: EffectTrace[];
+}): void;
+/** A server response's `effectResults` as timeline traces, carrying each persist's real outcome (entity, action, resulting id, denied). */
+declare function serverEffectTraces(results: readonly ServerEffectResult[] | undefined): EffectTrace[];
+/** Record one answered server leg on the timeline as a `server:<orbital>` trace. */
+declare function recordOrbitalResponse(orbitalName: string, request: EventRequest, response: EventResponse): void;
+/** `transport` with every answered post recorded on the verification timeline; the one place the circuit client's server responses are captured. */
+declare function recordingTransport(transport: EventTransport): EventTransport;
+declare function updateBridgeHealth(health: BridgeHealth): void;
+declare function getBridgeHealth(): BridgeHealth | null;
+declare function getSummary(): VerificationSummary;
+declare function getSnapshot(): VerificationSnapshot;
+/**
+ * Per-trait snapshot for the verifier.
+ *
+ * Iterates every registered trait getter and collects the live reducer
+ * state. Empty until at least one trait hook calls `registerTraitSnapshot`.
+ * A getter that throws is logged and skipped — one broken trait must not
+ * poison the rest of the snapshot.
+ */
+declare function getTraitSnapshots(): TraitStateSnapshot[];
+declare function subscribeToVerification(listener: ChangeListener): () => void;
+declare global {
+    interface Window {
+        __orbitalVerification?: OrbitalVerificationAPI;
+    }
+}
+/** Whether a verifier is driving this page: the `__ALMADAR_VERIFY__` window flag it sets before the bundle runs. */
+declare function verifierAttached(): boolean;
+/**
+ * Wait for a transition matching the given event to appear.
+ * Returns the trace or null on timeout.
+ */
+declare function waitForTransition(event: string, timeoutMs?: number): Promise<TransitionTrace | null>;
+/**
+ * Bind the EventBus so automation can send events and log emissions.
+ * Call this during app initialization.
+ */
+declare function bindEventBus(eventBus: {
+    emit: (type: string, payload?: EventPayload) => void;
+    onAny?: (listener: (event: BusEvent) => void) => () => void;
+}): void;
+declare function bindConfigApplier(applyConfig: NonNullable<OrbitalVerificationAPI['applyConfig']>): () => void;
+/**
+ * Bind a trait state getter so automation can query current states.
+ */
+declare function bindTraitStateGetter(getter: (traitName: string) => string | undefined): void;
+/**
+ * Register a per-trait snapshot provider. The generated trait logic hook
+ * (or `useTraitStateMachine`) calls this once on mount, passing a getter
+ * that reads the current reducer state via a ref. Returns an unregister
+ * function for cleanup on unmount.
+ *
+ * Calling this twice for the same `traitName` replaces the previous
+ * getter (e.g. page navigation remounts the trait; the new registration
+ * wins).
+ */
+declare function registerTraitSnapshot(traitName: string, getter: TraitSnapshotGetter): () => void;
+/**
+ * Register a canvas frame capture function.
+ * Called by game organisms (IsometricCanvas, PlatformerCanvas)
+ * so the verifier can snapshot canvas content at checkpoints.
+ */
+declare function bindCanvasCapture(captureFn: () => string | null): void;
+/**
+ * Bind a reader for the last drawables list received by a canvas host.
+ * Lets verification scripts inspect exactly which neutral descriptors reached
+ * the painter without re-deriving them from state.
+ */
+declare function bindLastDrawables(getDrawables: () => DrawableNode[] | null): void;
+/**
+ * Update asset load status for canvas verification.
+ * Game organisms call this when images load or fail.
+ */
+declare function updateAssetStatus(url: string, status: AssetLoadStatus): void;
+declare function clearVerification(): void;
+
+export { bindConfigApplier as a, bindCanvasCapture as b, bindEventBus as c, bindLastDrawables as d, bindTraitStateGetter as e, clearVerification as f, getAllChecks as g, getBridgeHealth as h, getSnapshot as i, getSummary as j, getTraitSnapshots as k, getTransitions as l, getTransitionsForTrait as m, recordServerResponse as n, recordTransition as o, recordingTransport as p, registerCheck as q, recordOrbitalResponse as r, registerTraitSnapshot as s, serverEffectTraces as t, subscribeToVerification as u, updateAssetStatus as v, updateBridgeHealth as w, updateCheck as x, verifierAttached as y, waitForTransition as z };
+export type { TraitSnapshotGetter as T };

package/dist/wrapCallbackForEvent-B9QLbhxX.d.ts

@@ -0,0 +1,19 @@
+import { PatternCallbackArg } from '@almadar/core/patterns';
+import { EventPayload, EventPayloadValue } from '@almadar/core';
+
+/**
+ * Build the runtime wrapper that turns a string-typed callback prop
+ * (e.g. `onTabChange: "TAB_CHANGED"`) into a function the component can
+ * invoke. The wrapper consumes the component's positional callback args
+ * by name and dispatches an OBJECT payload `{ argName: value, ... }` so
+ * the bus carries the trait's declared event payload, not a raw
+ * positional spread. Mirrors the codegen wrapper in
+ * `orbital-shell-typescript/src/codegen/pattern.rs` (C2 compiled path).
+ *
+ * Single-sourcing this logic across runtime and codegen (shared shape,
+ * not shared code — codegen emits string source) is what keeps the two
+ * paths from silently diverging on payload shape.
+ */
+declare function wrapCallbackForEvent(qualifiedEvent: string, callbackArgs: PatternCallbackArg[] | undefined, emit: (eventKey: string, payload?: EventPayload) => void): (...args: EventPayloadValue[]) => void;
+
+export { wrapCallbackForEvent as w };

package/index.css

@@ -0,0 +1,199 @@
+/**
+ * Design System Styles
+ */
+
+/* Load Plus Jakarta Sans from Google Fonts (Track A: preferred UI font) */
+@import url('https://fonts.googleapis.com/css2?family=Plus+Jakarta+Sans:wght@400;500;600;700&display=swap');
+
+/* React Flow's base styles (the canvas's node layering); ui's overrides below load after them. */
+@import '@xyflow/react/dist/style.css';
+
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+
+/**
+ * Default fallback theme (minimalist-light — UI/UX improved per Track A eval)
+ * Applied when no data-theme attribute is set.
+ */
+:root:not([data-theme]) {
+    --shadow-main: 0 1px 3px rgba(0, 0, 0, 0.08), 0 1px 2px rgba(0, 0, 0, 0.06);
+    --shadow-sm: 0 1px 2px rgba(0, 0, 0, 0.04);
+    --shadow-lg: 0 10px 25px -5px rgba(0, 0, 0, 0.1), 0 8px 10px -6px rgba(0, 0, 0, 0.1);
+    --shadow-inner: inset 0 1px 2px rgba(0, 0, 0, 0.05);
+    --shadow-none: none;
+    /* Track A: more pronounced hover lift for interactive cards */
+    --shadow-hover: 0 8px 30px -8px rgba(0, 0, 0, 0.18), 0 2px 6px rgba(0, 0, 0, 0.08);
+    --shadow-active: 0 1px 2px rgba(0, 0, 0, 0.05);
+
+    --radius-none: 0px;
+    --radius-sm: 6px;
+    /* Track A: bump radii from 8/12 → 10/14 for a more modern feel */
+    --radius-md: 10px;
+    --radius-lg: 14px;
+    --radius-xl: 18px;
+    --radius-full: 9999px;
+
+    --border-width: 1px;
+    --border-width-thin: 1px;
+    --border-width-thick: 2px;
+
+    --color-primary: #18181b;
+    --color-primary-hover: #27272a;
+    --color-primary-foreground: #fafafa;
+    --color-secondary: #fafafa;
+    --color-secondary-hover: #f4f4f5;
+    --color-secondary-foreground: #18181b;
+    --color-accent: #18181b;
+    --color-accent-foreground: #fafafa;
+    --color-muted: #f1f5f9;
+    /* Track A: slightly darker muted-foreground for legibility */
+    --color-muted-foreground: #64748b;
+    /* Track A: background ≠ card → natural surface elevation */
+    --color-background: #f8fafc;
+    --color-foreground: #0f172a;
+    --color-card: #ffffff;
+    --color-card-foreground: #0f172a;
+    --color-surface: #f1f5f9;
+    /* Track A: soften border — semi-transparent instead of solid gray */
+    --color-border: rgba(0, 0, 0, 0.08);
+    --color-input: #e2e8f0;
+    --color-ring: #18181b;
+
+    --color-error: #dc2626;
+    --color-error-foreground: #ffffff;
+    --color-success: #16a34a;
+    --color-success-foreground: #ffffff;
+    --color-warning: #ca8a04;
+    --color-warning-foreground: #000000;
+    --color-info: #2563eb;
+    --color-info-foreground: #ffffff;
+
+    /* Track A: Plus Jakarta Sans as first preference, Inter as fallback */
+    --font-family:
+        "Plus Jakarta Sans", "Inter", -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+    --font-weight-normal: 400;
+    --font-weight-medium: 500;
+    --font-weight-bold: 600;
+    --letter-spacing: -0.015em;
+    --line-height: 1.6;
+
+    --icon-stroke-width: 1.5;
+    --icon-color: currentColor;
+
+    --transition-fast: 150ms;
+    --transition-normal: 250ms;
+    --transition-slow: 400ms;
+    --transition-timing: cubic-bezier(0.4, 0, 0.2, 1);
+
+    --hover-scale: 1.01;
+    --hover-translate-y: -2px;
+    --hover-translate-x: 0;
+    --active-scale: 0.99;
+    --active-translate-y: 0;
+
+    --focus-ring-width: 2px;
+    --focus-ring-offset: 2px;
+    --focus-ring-color: #18181b;
+}
+
+html {
+    font-family: var(--font-family);
+    line-height: var(--line-height);
+    letter-spacing: var(--letter-spacing);
+    font-weight: var(--font-weight-normal);
+    color-scheme: light dark;
+    font-synthesis: none;
+    text-rendering: optimizeLegibility;
+    -webkit-font-smoothing: antialiased;
+    -moz-osx-font-smoothing: grayscale;
+}
+
+body {
+    margin: 0;
+    min-height: 100vh;
+    background-color: var(--color-background);
+    color: var(--color-foreground);
+}
+
+#root {
+    min-height: 100vh;
+}
+
+::-webkit-scrollbar {
+    width: 8px;
+    height: 8px;
+}
+
+::-webkit-scrollbar-track {
+    background: var(--color-muted);
+}
+
+::-webkit-scrollbar-thumb {
+    background: var(--color-muted-foreground);
+    border-radius: var(--radius-sm);
+}
+
+::-webkit-scrollbar-thumb:hover {
+    background: var(--color-foreground);
+}
+
+/**
+ * ReactFlow (@xyflow/react) Controls — theme overrides for FlowCanvas zoom buttons
+ *
+ * Without these, the bottom-left zoom in/out/fit buttons render as plain white
+ * squares from ReactFlow's default stylesheet, ignoring the active theme.
+ * Targets: .react-flow__controls + .react-flow__controls-button
+ */
+.react-flow__controls {
+    background: var(--color-card) !important;
+    border: 1px solid var(--color-border) !important;
+    border-radius: var(--radius-md) !important;
+    box-shadow: var(--shadow-main) !important;
+    overflow: hidden;
+}
+
+.react-flow__controls-button {
+    background: transparent !important;
+    border: none !important;
+    border-bottom: 1px solid var(--color-border) !important;
+    color: var(--color-foreground) !important;
+    fill: var(--color-foreground) !important;
+    width: 28px;
+    height: 28px;
+    transition: background var(--transition-fast) var(--transition-timing);
+}
+
+.react-flow__controls-button:last-child {
+    border-bottom: none !important;
+}
+
+.react-flow__controls-button:hover {
+    background: var(--color-muted) !important;
+}
+
+.react-flow__controls-button svg {
+    fill: var(--color-foreground) !important;
+    width: 14px;
+    height: 14px;
+}
+
+@layer utilities {
+    .shadow-theme { box-shadow: var(--shadow-main); }
+    .shadow-theme-sm { box-shadow: var(--shadow-sm); }
+    .shadow-theme-lg { box-shadow: var(--shadow-lg); }
+    .rounded-theme { border-radius: var(--radius-md); }
+    .rounded-theme-sm { border-radius: var(--radius-sm); }
+    .rounded-theme-lg { border-radius: var(--radius-lg); }
+    .border-theme { border-width: var(--border-width); border-color: var(--color-border); }
+    .bg-theme-primary { background-color: var(--color-primary); }
+    .bg-theme-secondary { background-color: var(--color-secondary); }
+    .bg-theme-background { background-color: var(--color-background); }
+    .bg-theme-card { background-color: var(--color-card); }
+    .text-theme-foreground { color: var(--color-foreground); }
+    .text-theme-muted { color: var(--color-muted-foreground); }
+    .text-theme-primary { color: var(--color-primary); }
+    .font-theme-normal { font-weight: var(--font-weight-normal); }
+    .font-theme-medium { font-weight: var(--font-weight-medium); }
+    .font-theme-bold { font-weight: var(--font-weight-bold); }
+}