@vgai/engine 0.2.0 → 0.3.0

package/dist/scene/schema/ui.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ui.d.ts","sourceRoot":"","sources":["../../../src/scene/schema/ui.ts"],"names":[],"mappings":"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"}

package/dist/scene/schema/ui.js

@@ -0,0 +1,506 @@
+import { z } from 'zod';
+/**
+ * UI scene-graph schema — React game UI represented AS scene-graph data.
+ *
+ * This is the engine-side (framework-agnostic, data-only) source of truth for the
+ * `.vscn.json` `ui` field and `.uitheme.json` theme assets. The React runtime
+ * renderer (editor-side, `packages/editor/src/ui-runtime/`) and the editor's
+ * UI-authoring layer both read/write THIS data — the engine never imports React.
+ *
+ * Design follows the cross-engine UI model distilled from Godot Control nodes,
+ * Unity uGUI/UI Toolkit, and Unreal UMG (see docs/UI-VISUAL-EDIT-MAXIMAL-SPEC.json
+ * groups A/D/E/F/G): a nested node tree (root canvas -> containers -> controls) with
+ * an anchor+offset layout model on top of a flexbox auto-layout engine, a reusable
+ * theme/token resource with per-element overrides and per-state styling, declarative
+ * data bindings (one-/two-way), data-bound list templates, and reusable component
+ * references. Every field is `.describe()`d to power JSON Schema generation.
+ */
+// ---------------------------------------------------------------------------
+// Primitives
+// ---------------------------------------------------------------------------
+/** A 2-tuple [x, y] in 0..1 fraction or px depending on the field. */
+const UIVec2Schema = z.tuple([z.number(), z.number()]);
+/**
+ * A length: a number (logical px) or a CSS-like string token ('auto', '50%',
+ * '1fr', 'min-content'). Strings let containers express fractional/intrinsic
+ * sizing (Godot size flags / Unity flexible size / UMG Fill) without inventing a
+ * parallel unit system — the flex runtime maps them to CSS directly.
+ */
+const UILengthSchema = z.union([z.number(), z.string()]);
+/**
+ * A style value: a literal string/number, OR a theme-token reference of the form
+ * "$tokenName" resolved against the active theme (F1). Kept as a permissive
+ * union so the schema-driven inspector round-trips both forms.
+ */
+const UIStyleValueSchema = z.union([z.string(), z.number()]);
+// ---------------------------------------------------------------------------
+// Data binding (G1/G2/G4)
+// ---------------------------------------------------------------------------
+/**
+ * A declarative binding to the game's reactive data source. The runtime resolves
+ * `source` (a dotted path, e.g. "player.health") against the UIDataSource the
+ * game provides; `mode` controls write-back for input controls (two-way / MVVM).
+ */
+export const UIBindingSchema = z
+    .object({
+    source: z
+        .string()
+        .describe('Dotted path into the game data source, e.g. "player.health" or "settings.volume"'),
+    mode: z
+        .enum(['one-way', 'two-way'])
+        .optional()
+        .describe('one-way: source -> UI (default). two-way: input controls also write back (MVVM)'),
+    transform: z
+        .string()
+        .optional()
+        .describe('Optional named transform/formatter applied to the value before display'),
+    fallback: UIStyleValueSchema.optional().describe('Value used when the source path is undefined at runtime'),
+})
+    .describe('A data binding from the game data source to a UI property');
+/**
+ * A prop value is either a literal (scalar / scalar array) or a binding wrapper
+ * `{ $bind: {...} }` (G4 — bindings are first-class and distinguishable from
+ * literals, mirroring visual-edit's literal-vs-dynamic guard but editable).
+ */
+const UIBoundValueSchema = z
+    .object({ $bind: UIBindingSchema })
+    .describe('A bound value: { $bind: { source, mode, ... } }');
+const UIPropValueSchema = z.union([
+    z.string(),
+    z.number(),
+    z.boolean(),
+    z.array(z.string()),
+    z.array(z.number()),
+    UIBoundValueSchema,
+]);
+// ---------------------------------------------------------------------------
+// Layout & anchoring (D1/D2/D3) + containers (E1-E4)
+// ---------------------------------------------------------------------------
+/** Anchor fractions (0..1) of each edge against the parent rect (D1). */
+const UIAnchorSchema = z
+    .object({
+    left: z.number().describe('Left-edge anchor as a fraction of parent width (0=left, 1=right)'),
+    top: z.number().describe('Top-edge anchor as a fraction of parent height (0=top, 1=bottom)'),
+    right: z.number().describe('Right-edge anchor as a fraction of parent width'),
+    bottom: z.number().describe('Bottom-edge anchor as a fraction of parent height'),
+})
+    .describe('Anchor preset (fractions of parent). Equal L/R or T/B = fixed size; split = stretch');
+/** Pixel offsets of each edge from its anchor (D1). */
+const UIOffsetSchema = z
+    .object({
+    left: z.number().describe('Left offset in px from the left anchor'),
+    top: z.number().describe('Top offset in px from the top anchor'),
+    right: z.number().describe('Right offset in px from the right anchor'),
+    bottom: z.number().describe('Bottom offset in px from the bottom anchor'),
+})
+    .describe('Pixel offsets from the anchors');
+export const UILayoutSchema = z
+    .object({
+    position: z
+        .enum(['flow', 'absolute'])
+        .optional()
+        .describe('flow: laid out by the parent container (flex). absolute: anchored free placement'),
+    anchor: UIAnchorSchema.optional().describe('Anchor fractions (absolute/anchored nodes) (D1)'),
+    offset: UIOffsetSchema.optional().describe('Pixel offsets from anchors (absolute/anchored) (D1)'),
+    pivot: UIVec2Schema.optional().describe('Pivot/alignment point (0..1 each axis) for rotation/scale/position origin (D3)'),
+    width: UILengthSchema.optional().describe('Width: px number or token ("auto","50%","1fr")'),
+    height: UILengthSchema.optional().describe('Height: px number or token'),
+    minWidth: UILengthSchema.optional().describe('Minimum width'),
+    maxWidth: UILengthSchema.optional().describe('Maximum width'),
+    minHeight: UILengthSchema.optional().describe('Minimum height'),
+    maxHeight: UILengthSchema.optional().describe('Maximum height'),
+    aspectRatio: z
+        .number()
+        .optional()
+        .describe('Locked width/height ratio (AspectRatio container)'),
+    // --- container (parent) flex props (E1/E4) ---
+    direction: z
+        .enum(['row', 'column', 'row-reverse', 'column-reverse'])
+        .optional()
+        .describe('Flex main-axis direction for box containers (E1)'),
+    justify: z
+        .enum(['start', 'center', 'end', 'space-between', 'space-around', 'space-evenly'])
+        .optional()
+        .describe('Main-axis alignment of children'),
+    align: z
+        .enum(['start', 'center', 'end', 'stretch', 'baseline'])
+        .optional()
+        .describe('Cross-axis alignment of children'),
+    wrap: z
+        .boolean()
+        .optional()
+        .describe('Wrap children to the next line (Wrap/Flow container) (E3)'),
+    gap: z.number().optional().describe('Gap (px) between children'),
+    columns: z.number().optional().describe('Column count for grid containers (E2)'),
+    // --- child (item) flex props (Godot size flags / Unity flexible / UMG Fill) ---
+    grow: z.number().optional().describe('Flex grow factor (expand to fill / stretch ratio)'),
+    shrink: z.number().optional().describe('Flex shrink factor'),
+    basis: UILengthSchema.optional().describe('Flex basis (initial main-axis size)'),
+    alignSelf: z
+        .enum(['auto', 'start', 'center', 'end', 'stretch', 'baseline'])
+        .optional()
+        .describe('Per-child cross-axis alignment override'),
+    // --- spacing & layering ---
+    padding: z
+        .array(z.number())
+        .optional()
+        .describe('Padding [top,right,bottom,left] in px (MarginContainer / slot padding)'),
+    margin: z.array(z.number()).optional().describe('Margin [top,right,bottom,left] in px'),
+    zIndex: z
+        .number()
+        .optional()
+        .describe('Stacking order within the parent (Overlay/Canvas z) (E3)'),
+    overflow: z
+        .enum(['visible', 'hidden', 'scroll', 'auto'])
+        .optional()
+        .describe('Overflow behaviour (Scroll container = scroll/auto) (E3)'),
+})
+    .describe('Layout: anchor+offset model over a flexbox auto-layout engine (D/E)');
+// ---------------------------------------------------------------------------
+// Styling & theming (F1-F6)
+// ---------------------------------------------------------------------------
+/**
+ * A flat style bag. Values are literal CSS-ish values OR theme-token refs
+ * ("$accent"). Kept open (record) for forward-compat, with the common authored
+ * properties documented. Numbers are treated as px where a length is expected.
+ */
+export const UIStyleSchema = z
+    .object({
+    backgroundColor: UIStyleValueSchema.optional().describe('Background color (hex/rgb/"$token")'),
+    backgroundImage: z.string().optional().describe('Background image asset ref or url (A5)'),
+    backgroundSize: z.string().optional().describe('Background sizing (e.g. "cover","9-slice")'),
+    color: UIStyleValueSchema.optional().describe('Text/foreground color'),
+    fontSize: UIStyleValueSchema.optional().describe('Font size (px or "$token")'),
+    fontFamily: z.string().optional().describe('Font family or font asset ref (A5)'),
+    fontWeight: UIStyleValueSchema.optional().describe('Font weight (e.g. 400/700/"bold")'),
+    fontStyle: z.string().optional().describe('Font style (normal/italic)'),
+    textAlign: z.enum(['left', 'center', 'right', 'justify']).optional().describe('Text alignment'),
+    lineHeight: UIStyleValueSchema.optional().describe('Line height'),
+    letterSpacing: UIStyleValueSchema.optional().describe('Letter spacing'),
+    opacity: z.number().optional().describe('Opacity 0..1'),
+    borderRadius: UIStyleValueSchema.optional().describe('Corner radius (px or "$token")'),
+    borderWidth: UIStyleValueSchema.optional().describe('Border width (px)'),
+    borderColor: UIStyleValueSchema.optional().describe('Border color'),
+    borderStyle: z.enum(['solid', 'dashed', 'dotted', 'none']).optional().describe('Border style'),
+    boxShadow: z.string().optional().describe('Box shadow CSS value'),
+    // 9-slice / scalable box image (F4): border image inset for non-distorting scale
+    sliceInset: z
+        .array(z.number())
+        .optional()
+        .describe('9-slice inset [top,right,bottom,left] px for backgroundImage scaling (F4)'),
+    cursor: z.string().optional().describe('Cursor over this element (e.g. "pointer")'),
+    // transition (F6): animated state changes
+    transition: z.string().optional().describe('CSS-like transition for state changes (F6)'),
+})
+    .describe('Style bag. Values may reference theme tokens via "$tokenName" (F1/F2)');
+/** Per-state style overrides (F3): normal is the base style; these layer on top. */
+export const UIStateStylesSchema = z
+    .object({
+    hover: UIStyleSchema.optional().describe('Style applied on pointer hover'),
+    pressed: UIStyleSchema.optional().describe('Style applied while pressed/active'),
+    disabled: UIStyleSchema.optional().describe('Style applied when disabled'),
+    focus: UIStyleSchema.optional().describe('Style applied when focused (keyboard/gamepad)'),
+})
+    .describe('Per-state styling overrides (F3)');
+/**
+ * A reusable theme/style resource (F1). `tokens` is a flat map of token name ->
+ * value referenced by style props as "$name". `variants` are named style
+ * variations of a base look (F4 / Godot type variations). Authored inline on a
+ * UI root OR as a standalone `.uitheme.json` referenced by `themeRef`.
+ */
+export const UIThemeSchema = z
+    .object({
+    name: z.string().describe('Theme name'),
+    tokens: z
+        .record(z.string(), UIStyleValueSchema)
+        .describe('Design tokens: tokenName -> value, referenced in styles as "$tokenName" (F1)'),
+    variants: z
+        .record(z.string(), UIStyleSchema)
+        .optional()
+        .describe('Named style variations of a base type (F4 / type variations)'),
+})
+    .describe('Reusable theme resource (F1). Inline on a UI root or a .uitheme.json asset');
+/** Standalone theme asset file (.uitheme.json) — the chosen theme file boundary. */
+export const UIThemeFileSchema = z
+    .object({
+    version: z.number().describe('Theme file format version'),
+    theme: UIThemeSchema.describe('The theme resource'),
+})
+    .describe('UI theme asset file (.uitheme.json)');
+// ---------------------------------------------------------------------------
+// UI node tree (A2) + controls (J1) + lists (G3) + components (H)
+// ---------------------------------------------------------------------------
+/**
+ * Node kinds. Containers (canvas/box/grid/stack/scroll/panel/tab/center/wrap/
+ * aspect/sizebox) arrange children; controls (text/richtext/button/image/input/
+ * toggle/slider/dropdown/progress) are leaves; `component` references a reusable
+ * React component or a saved UI prefab.
+ */
+export const UINodeKindSchema = z
+    .enum([
+    // containers (E1-E4)
+    'canvas',
+    'box',
+    'grid',
+    'stack', // z-layered overlay
+    'scroll',
+    'panel', // styled background container
+    'center',
+    'wrap',
+    'aspect',
+    'sizebox',
+    'tab', // shows one child at a time (WidgetSwitcher)
+    // controls (J1) + text (F4 rich text)
+    'text',
+    'richtext',
+    'button',
+    'image',
+    'input',
+    'toggle',
+    'slider',
+    'dropdown',
+    'progress',
+    // reuse (H) — a referenced React component or saved UI prefab
+    'component',
+])
+    .describe('UI node kind (container / control / component)');
+/** A data-bound list template descriptor (G3). */
+const UIRepeatSchema = z
+    .object({
+    items: UIBindingSchema.describe('Binding to the collection to repeat over (G3)'),
+    as: z
+        .string()
+        .describe('Alias name each item is exposed under inside the template (e.g. "item")'),
+    keyPath: z
+        .string()
+        .optional()
+        .describe('Per-item key path for stable per-instance ids/selection (overcomes shared-OID) (G3)'),
+})
+    .describe('Repeat this node as a template over a bound collection (data-bound list) (G3)');
+// ---------------------------------------------------------------------------
+// Keyframe / timeline animation (S1 — FLOOR per the union rule: Godot
+// AnimationPlayer, Unity Timeline, Unreal UMG Animations all author multi-keyframe
+// multi-property UI animation on a dope-sheet/timeline).
+// ---------------------------------------------------------------------------
+/** Easing applied to the segment LEAVING a keyframe toward the next. */
+export const UIEasingSchema = z
+    .enum(['linear', 'ease-in', 'ease-out', 'ease-in-out', 'step'])
+    .describe('Interpolation easing for the segment after this keyframe (S1)');
+/**
+ * The animatable properties. Curated so each maps to a GPU-friendly CSS output
+ * (transform/opacity/color/size) — animating these does not reflow per frame.
+ */
+export const UIAnimatablePropertySchema = z
+    .enum([
+    'opacity',
+    'translateX',
+    'translateY',
+    'rotate',
+    'scale',
+    'backgroundColor',
+    'color',
+    'width',
+    'height',
+])
+    .describe('A property a keyframe track can animate (S1)');
+/** A single keyframe: a value at a time (seconds), with the easing leaving it. */
+export const UIKeyframeSchema = z
+    .object({
+    time: z.number().describe('Keyframe time in seconds from the clip start (S1)'),
+    value: z.union([z.number(), z.string()]).describe('Value at this time (number, px, or color)'),
+    easing: UIEasingSchema.optional().describe('Easing of the segment after this keyframe'),
+})
+    .describe('A keyframe (time + value) on a track (S1)');
+/** A track animates ONE property via an ordered list of keyframes (S1). */
+export const UITrackSchema = z
+    .object({
+    property: UIAnimatablePropertySchema.describe('Property this track animates'),
+    keyframes: z.array(UIKeyframeSchema).describe('Ordered keyframes (by time)'),
+})
+    .describe('A keyframe track for one animatable property (dope-sheet row) (S1)');
+/** A named animation clip: multiple tracks (multi-property), duration, loop (S1). */
+const UIAnimationBase = z.object({
+    name: z.string().describe('Clip name'),
+    duration: z.number().describe('Clip duration in seconds'),
+    loop: z.boolean().optional().describe('Whether the clip loops'),
+    autoplay: z.boolean().optional().describe('Play automatically on mount'),
+    playOnEvent: z
+        .string()
+        .optional()
+        .describe('Trigger id that plays this clip (e.g. onClick). REJECTED at parse (T4.1): declared but ' +
+        'has no runtime reader — authoring this field throws. Do not author.'),
+    tracks: z.array(UITrackSchema).describe('Tracks (one per animated property)'),
+});
+export const UIAnimationSchema = UIAnimationBase
+    // T4.1: `playOnEvent` is authored/typed but has no runtime reader — the UI
+    // runtime (`packages/editor/src/ui-runtime/mount.tsx`) only ever looks up
+    // `autoplay` clips; `SceneUI.tsx`'s event firing (`fire('onClick')`) never
+    // cross-references a clip's `playOnEvent` id. Authoring it silently does
+    // nothing today, so it's a loud load error until a reader exists — see
+    // docs/BACKBONE-TASKS.md T4.1.
+    .superRefine((clip, ctx) => {
+    if (clip.playOnEvent !== undefined) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: `UI animation clip "${clip.name}": \`playOnEvent\` is authored but not implemented — ` +
+                'no runtime reader consumes it (only `autoplay` clips are played). See T4.1.',
+            path: ['playOnEvent'],
+        });
+    }
+})
+    .describe('A keyframe/timeline animation clip on a UI node (S1)');
+const UISharedNodeFields = {
+    id: z.string().optional().describe('Stable unique node id. Auto-generated if omitted'),
+    name: z.string().describe('Human-readable node name (shown in the UI hierarchy)'),
+    kind: UINodeKindSchema.describe('Node kind'),
+    visible: z.boolean().optional().describe('Whether the node renders'),
+    locked: z
+        .boolean()
+        .optional()
+        .describe('Prevent selection/editing in the editor. REJECTED at parse (T4.1): declared but has no ' +
+        'runtime reader — authoring this field throws. Do not author.'),
+    tags: z
+        .array(z.string())
+        .optional()
+        .describe('Arbitrary tags for runtime queries. REJECTED at parse (T4.1): declared but has no runtime ' +
+        'reader — authoring this field throws. Do not author.'),
+    layout: UILayoutSchema.optional().describe('Layout/anchor/flex properties (D/E)'),
+    style: UIStyleSchema.optional().describe('Base style (F1/F2)'),
+    states: UIStateStylesSchema.optional().describe('Per-state style overrides (F3)'),
+    variant: z.string().optional().describe('Named theme variant to apply (F4)'),
+    props: z
+        .record(z.string(), UIPropValueSchema)
+        .optional()
+        .describe('Control/component props (text, value, placeholder, min/max, …). May be bound (G)'),
+    bindings: z
+        .record(z.string(), UIBindingSchema)
+        .optional()
+        .describe('Explicit prop/style bindings keyed by target path (G1/G2)'),
+    events: z
+        .record(z.string(), z.string())
+        .optional()
+        .describe('Event wiring: eventName ("onClick") -> game handler/action id (J2)'),
+    component: z
+        .string()
+        .optional()
+        .describe('For kind:"component" — referenced React component name or saved UI prefab path (H)'),
+    repeat: UIRepeatSchema.optional().describe('Make this node a data-bound list template (G3)'),
+    animations: z
+        .array(UIAnimationSchema)
+        .optional()
+        .describe('Keyframe/timeline animation clips on this node (S1)'),
+};
+/**
+ * T4.1: `locked`/`tags` (UISharedNodeFields — shared by every UI node AND the
+ * root) are authored/typed but have no runtime reader anywhere. Unlike their
+ * 3D `SceneEntity` namesakes (editor-store.ts locking, scene-query.ts tag
+ * queries), the UI-authoring side only wires `locked` as far as
+ * `ui-authoring-adapter.ts`'s `EditorNode.flags.locked` — which nothing
+ * downstream reads (that adapter isn't wired into the live editor shell yet;
+ * see its file doc comment) — and `tags` isn't touched at all. Loud load
+ * error until real readers exist — see T4.1.
+ */
+function checkDeadSharedNodeFields(node, ctx) {
+    if (node.locked !== undefined) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: `UI node "${node.name}": \`locked\` is authored but not implemented — no runtime reader ` +
+                'gates selection/editing on it (the UI-authoring adapter sets it but nothing downstream ' +
+                'reads it yet). See T4.1.',
+            path: ['locked'],
+        });
+    }
+    if (node.tags !== undefined) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: `UI node "${node.name}": \`tags\` is authored but not implemented — no runtime query ` +
+                'reader consumes it (no UI equivalent of scene-query.ts exists yet). See T4.1.',
+            path: ['tags'],
+        });
+    }
+}
+const UINodeBase = z.object(UISharedNodeFields);
+export const UINodeSchema = z.lazy(() => UINodeBase.extend({
+    children: z.array(UINodeSchema).optional().describe('Child UI nodes (A2)'),
+}).superRefine(checkDeadSharedNodeFields));
+// ---------------------------------------------------------------------------
+// UI root / canvas (A1/A3, I1-I3)
+// ---------------------------------------------------------------------------
+/** Responsive scaling config for a UI root (I1/I2). */
+const UIScalingSchema = z
+    .object({
+    referenceWidth: z.number().describe('Design/reference resolution width (I1)'),
+    referenceHeight: z.number().describe('Design/reference resolution height (I1)'),
+    mode: z
+        .enum(['scale-with-size', 'constant-pixel', 'constant-physical'])
+        .optional()
+        .describe('Global scaling mode (Unity CanvasScaler analog) (I1)'),
+    aspect: z
+        .enum(['expand', 'keep', 'keep-width', 'keep-height'])
+        .optional()
+        .describe('Aspect-ratio policy (Godot stretch aspect / Unity match mode) (I2)'),
+    match: z
+        .number()
+        .optional()
+        .describe('0..1 width/height match factor for scale-with-size mode'),
+})
+    .describe('Responsive resolution/DPI scaling for the UI root (I1/I2)');
+/**
+ * A UI root — a canvas placed screen-space or screen-tracked to a 3D entity (A3).
+ * Carries the responsive scaling config and an optional inline theme / theme ref.
+ */
+export const UIRootSchema = z.lazy(() => z
+    .object({
+    ...UISharedNodeFields,
+    kind: z.literal('canvas').describe('A UI root is always a canvas'),
+    space: z
+        .enum(['screen', 'world-tracked'])
+        .optional()
+        .describe('screen: overlay. world-tracked: billboarded to trackEntity screen pos (A3)'),
+    trackEntity: z
+        .string()
+        .optional()
+        .describe('Entity id this canvas is screen-tracked to (world-tracked space) (A3)'),
+    scaling: UIScalingSchema.optional().describe('Responsive scaling config (I1/I2)'),
+    theme: UIThemeSchema.optional().describe('Inline theme resource (F1)'),
+    themeRef: z
+        .string()
+        .optional()
+        .describe('Path to a shared .uitheme.json theme asset (F1). REJECTED at parse (T4.1): declared ' +
+        'but has no runtime reader — authoring this field throws. Do not author.'),
+    locale: z.string().optional().describe('Active locale for localized text (G5)'),
+    children: z.array(UINodeSchema).optional().describe('Child UI nodes (A2)'),
+})
+    // T4.1: `themeRef` is authored/typed but has no runtime reader anywhere —
+    // only the inline `theme` field is ever read (`SceneUI.tsx` passes
+    // `root.theme` into render context; nothing fetches/resolves a
+    // `.uitheme.json` by path). Authoring it silently does nothing today, so
+    // it's a loud load error until a resolver exists — see T4.1.
+    .superRefine((root, ctx) => {
+    checkDeadSharedNodeFields(root, ctx);
+    if (root.themeRef !== undefined) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: '`themeRef` is authored but not implemented — no runtime reader resolves a shared ' +
+                '.uitheme.json asset (only inline `theme` is read). See T4.1.',
+            path: ['themeRef'],
+        });
+    }
+})
+    .describe('A UI root canvas attached to the scene graph (A1/A3)'));
+/**
+ * A saved reusable UI prefab/component (H1). Mirrors PrefabFile but for a UI
+ * subtree, with declared exposed props/slots (H3).
+ */
+export const UIPrefabFileSchema = z
+    .object({
+    version: z.number().describe('UI prefab file format version'),
+    name: z.string().describe('UI prefab display name'),
+    root: UINodeSchema.describe('Root UI node of the prefab (H1)'),
+    exposedProps: z
+        .array(z.string())
+        .optional()
+        .describe('Prop names exposed for per-instance override (H3)'),
+    slots: z.array(z.string()).optional().describe('Named content slots for injection (H3)'),
+})
+    .describe('UI prefab file (.uiprefab.json) — a reusable UI subtree (H1/H3)');