openuispec 0.2.13 → 0.2.15

package/examples/todo-orbit/README.md

@@ -10,13 +10,14 @@ Todo Orbit is a multi-platform sample project for OpenUISpec. It combines a sour
 - Create and edit task flows
 - Recurring-rule creation with conditional fields and validation
 - Bilingual localization with English and Russian
-- Custom contracts for schedule preview and task trend charts
+- Components for reusable composed UI (task trend chart)
+- Custom contracts for schedule preview
 
 ## Project layout
 
 | Path | Purpose |
 |------|---------|
-| [`openuispec/`](./openuispec/) | Source OpenUISpec project: manifest, tokens, screens, flows, contracts, locales |
+| [`openuispec/`](./openuispec/) | Source OpenUISpec project: manifest, tokens, screens, flows, contracts, components, locales |
 | [`generated/web/Todo Orbit/`](./generated/web/Todo%20Orbit/) | Generated React + Vite web app |
 | [`generated/ios/Todo Orbit/`](./generated/ios/Todo%20Orbit/) | Generated SwiftUI iOS target |
 | [`generated/android/Todo Orbit/`](./generated/android/Todo%20Orbit/) | Generated Jetpack Compose Android target |

package/examples/todo-orbit/openuispec/README.md

@@ -12,6 +12,7 @@ This directory contains the **OpenUISpec** semantic UI specification for **todo-
 | `screens/` | Screen definitions — one YAML file per screen |
 | `flows/` | Navigation flows — multi-step user journeys |
 | `contracts/` | Component contracts — standard extensions and custom (`x_` prefixed) |
+| `components/` | Reusable compositions — contract slot compositions with states and variants |
 | `platform/` | Platform overrides — per-target (iOS, Android, Web) behaviors |
 | `locales/` | Localization — i18n strings (JSON, ICU MessageFormat) |
 
@@ -28,7 +29,7 @@ Do NOT guess the file format — skipping this step will produce invalid YAML th
 
 **Reference files inside the package (read in this order):**
 1. `README.md` — schema tables, file format reference, root wrapper keys
-2. `spec/openuispec-v0.1.md` — full specification (contracts, layout, expressions, etc.)
+2. `spec/openuispec-v0.2.md` — full specification (contracts, layout, expressions, etc.)
 3. `examples/taskflow/openuispec/` — complete working example with all file types
 4. `schema/` — JSON Schemas for validation
 

package/examples/todo-orbit/openuispec/components/task_trend_chart.yaml

@@ -0,0 +1,85 @@
+# ============================================================
+# Component: task_trend_chart
+# ============================================================
+# Visualizes task creation and completion trends as a composed
+# component with chart area, legend, and period selector slots.
+# ============================================================
+
+task_trend_chart:
+  semantic: "Visualizes task creation and completion trends over time for productivity analysis"
+
+  props:
+    metric:
+      type: enum
+      values: [completed, created, completion_rate]
+      required: true
+    period:
+      type: enum
+      values: [week, month, quarter]
+      required: true
+    show_legend: { type: bool, default: true }
+
+  slots:
+    chart_area:
+      contract: data_display
+      variant: card
+      props: { title: "$t:analytics.trend_chart" }
+    period_selector:
+      contract: input_field
+      input_type: select
+      props: { label: "$t:analytics.period", options: [week, month, quarter] }
+      hideable: true
+    legend:
+      contract: data_display
+      variant: inline
+      props: { title: "$t:analytics.legend" }
+      hideable: true
+
+  layout:
+    type: stack
+    spacing: "spacing.sm"
+    sections:
+      - slot: period_selector
+      - slot: chart_area
+      - slot: legend
+
+  states:
+    idle: { semantic: "Chart has not loaded data yet" }
+    loading:
+      semantic: "Trend data is loading"
+      hide_slots: [legend]
+    ready:
+      semantic: "Trend data is available and rendered"
+    empty:
+      semantic: "No trend points available"
+      hide_slots: [legend]
+    error:
+      semantic: "Trend data failed to load"
+      hide_slots: [legend]
+
+  variants:
+    compact:
+      semantic: "Compact chart for dashboard cards"
+      hide_slots: [period_selector]
+      tokens:
+        background: "color.surface.secondary"
+        radius: "spacing.sm"
+
+  tokens:
+    background: "color.surface.primary"
+    radius: "spacing.sm"
+    padding: "spacing.md"
+
+  a11y:
+    role: "img"
+    label: "Analytics trend chart"
+
+  platform_mapping:
+    ios: { component: "Chart", framework: "Swift Charts" }
+    android: { component: "Canvas chart composable" }
+    web: { component: "SVG chart component" }
+
+  generation:
+    must_handle:
+      - "Render chart area with completed and created series"
+      - "Handle loading, empty, and error states"

package/examples/todo-orbit/openuispec/locales/en.json

@@ -26,6 +26,9 @@
   "analytics.completion_rate": "Completion rate",
   "analytics.overdue_section": "Overdue review",
   "analytics.overdue_subtitle": "Tasks that need attention first.",
+  "analytics.trend_chart": "Trend chart",
+  "analytics.period": "Period",
+  "analytics.legend": "Legend",
   "analytics.trend_subtitle": "Completion trend",
   "analytics.legend_completed": "Completed",
   "analytics.legend_created": "Created",

package/examples/todo-orbit/openuispec/locales/ru.json

@@ -26,6 +26,9 @@
   "analytics.completion_rate": "Процент выполнения",
   "analytics.overdue_section": "Просроченные задачи",
   "analytics.overdue_subtitle": "Задачи, которым нужно уделить внимание в первую очередь.",
+  "analytics.trend_chart": "График тренда",
+  "analytics.period": "Период",
+  "analytics.legend": "Легенда",
   "analytics.trend_subtitle": "Динамика выполнения",
   "analytics.legend_completed": "Выполнено",
   "analytics.legend_created": "Создано",

package/examples/todo-orbit/openuispec/mock/analytics.yaml

@@ -0,0 +1,26 @@
+# Mock data for the analytics screen
+data:
+  overview:
+    completed_today: 3
+    open_tasks: 8
+    overdue_tasks: 2
+    completion_rate: 67
+
+  trend:
+    - { label: "Mon", completed: 4, created: 2 }
+    - { label: "Tue", completed: 3, created: 5 }
+    - { label: "Wed", completed: 6, created: 3 }
+    - { label: "Thu", completed: 2, created: 4 }
+    - { label: "Fri", completed: 5, created: 1 }
+    - { label: "Sat", completed: 1, created: 0 }
+    - { label: "Sun", completed: 0, created: 2 }
+
+  overdue:
+    - id: "t6"
+      title: "Submit tax forms"
+      priority: high
+      due_date: "2026-03-15"
+    - id: "t7"
+      title: "Renew gym membership"
+      priority: low
+      due_date: "2026-03-14"

package/examples/todo-orbit/openuispec/mock/home.yaml

@@ -0,0 +1,33 @@
+# Mock data for the home screen
+data:
+  tasks:
+    - id: "t1"
+      title: "Buy groceries"
+      due_date: "2026-03-18"
+      status: open
+      priority: high
+    - id: "t2"
+      title: "Finish project proposal"
+      due_date: "2026-03-19"
+      status: open
+      priority: medium
+    - id: "t3"
+      title: "Call dentist"
+      due_date: "2026-03-20"
+      status: done
+      priority: low
+    - id: "t4"
+      title: "Review pull request"
+      due_date: "2026-03-18"
+      status: open
+      priority: high
+    - id: "t5"
+      title: "Clean apartment"
+      due_date: "2026-03-21"
+      status: open
+      priority: medium
+
+  task_counts:
+    all: 12
+    open: 8
+    done: 4

package/examples/todo-orbit/openuispec/mock/settings.yaml

@@ -0,0 +1,7 @@
+# Mock data for the settings screen
+data:
+  preferences:
+    locale: "en"
+    theme: "light"
+    reminders_enabled: true
+    daily_summary_enabled: false

package/examples/todo-orbit/openuispec/mock/task_detail.yaml

@@ -0,0 +1,14 @@
+# Mock data for the task_detail screen
+data:
+  task:
+    id: "t1"
+    title: "Buy groceries"
+    status: open
+    priority: high
+    due_date: "2026-03-18"
+    notes: "Get milk, eggs, bread, and vegetables. Check the weekly deals at the store."
+    created_at: "2026-03-10"
+    updated_at: "2026-03-17"
+
+params:
+  task_id: "t1"

package/examples/todo-orbit/openuispec/openuispec.yaml

@@ -1,5 +1,5 @@
-# openuispec-sample — OpenUISpec v0.1
-spec_version: "0.1"
+# openuispec-sample — OpenUISpec v0.2
+spec_version: "0.2"
 
 project:
   name: "Todo Orbit"
@@ -9,13 +9,13 @@ project:
 includes:
   tokens: "./tokens/"
   contracts: "./contracts/"
+  components: "./components/"
   screens: "./screens/"
   flows: "./flows/"
   platform: "./platform/"
   locales: "./locales/"
 
 custom_contracts:
-  - "./contracts/x_task_trend_chart.yaml"
   - "./contracts/x_schedule_preview.yaml"
 
 i18n:

package/examples/todo-orbit/openuispec/platform/android.yaml

@@ -4,9 +4,6 @@ android:
   min_sdk: 26
 
   overrides:
-    x_task_trend_chart:
-      compact: { uses_canvas_rendering: true }
-      detail: { uses_canvas_rendering: true, supports_pointer_highlight: true }
     x_schedule_preview:
       compact: { uses_lazy_column: true }
       detail: { uses_lazy_column: true, supports_animated_content: true }

package/examples/todo-orbit/openuispec/platform/ios.yaml

@@ -3,9 +3,6 @@ ios:
   min_version: "17.0"
 
   overrides:
-    x_task_trend_chart:
-      compact: { uses_native_chart_framework: true }
-      detail: { uses_native_chart_framework: true, supports_rule_mark: true }
     x_schedule_preview:
       compact: { uses_timeline_view: true }
       detail: { uses_timeline_view: true, supports_content_transition: true }

package/examples/todo-orbit/openuispec/platform/web.yaml

@@ -3,9 +3,6 @@ web:
   language: typescript
 
   overrides:
-    x_task_trend_chart:
-      compact: { implementation: "svg", responsive: true }
-      detail: { implementation: "svg", responsive: true, supports_tooltip: true }
     x_schedule_preview:
       compact: { implementation: "semantic_list", responsive: true }
       detail: { implementation: "semantic_list", responsive: true, supports_staggered_updates: true }

package/examples/todo-orbit/openuispec/screens/analytics.yaml

@@ -102,14 +102,11 @@ analytics:
 
       - id: trend_chart
         margin_top: "spacing.lg"
-        contract: x_task_trend_chart
-        variant: detail
+        component: task_trend_chart
         props:
-          series: "trend"
           metric: completed
           period: "state.period"
           show_legend: true
-          empty_message: "$t:analytics.empty_trend"
 
       - id: overdue_header
         margin_top: "spacing.xl"

package/mcp-server/index.ts

@@ -25,6 +25,7 @@ import YAML from "yaml";
 import { takeScreenshot, takeScreenshotBatch } from "./screenshot.js";
 import { takeAndroidScreenshot, takeAndroidScreenshotBatch } from "./screenshot-android.js";
 import { takeIOSScreenshot, takeIOSScreenshotBatch } from "./screenshot-ios.js";
+import { renderPreview } from "./preview.js";
 
 // ── resolve project cwd ──────────────────────────────────────────────
 
@@ -121,8 +122,9 @@ WORKFLOW — each tool response includes a next_tool hint, follow it:
 5. Remind the user to baseline when satisfied: openuispec drift --snapshot --target <t>
    Do not baseline on your own initiative — the user decides when output is accepted.
 
-FOCUSED GETTERS (prefer for incremental edits): get_screen, get_contract, get_tokens, get_locale
+FOCUSED GETTERS (prefer for incremental edits): get_screen, get_contract, get_component, get_tokens, get_locale
 SPEC AUTHORING: spec_types → spec_schema(type, summary?) → write YAML
+PREVIEW: openuispec_preview(screen) → render spec as HTML with mock data, returns screenshot (no app needed)
 SCREENSHOTS: screenshot (web), screenshot_android, screenshot_ios — single + batch variants
 
 Skip only for purely non-UI requests.`,
@@ -387,10 +389,10 @@ server.registerTool(
 server.registerTool(
   "openuispec_validate",
   {
-    description: "Validate spec files against JSON schemas. Returns validation errors grouped by type (manifest, tokens, screens, flows, platform, locales, contracts, semantic).",
+    description: "Validate spec files against JSON schemas. Returns validation errors grouped by type (manifest, tokens, screens, flows, platform, locales, contracts, components, semantic).",
     inputSchema: {
       groups: z
-        .array(z.enum(["manifest", "tokens", "screens", "flows", "platform", "locales", "contracts", "semantic"]))
+        .array(z.enum(["manifest", "tokens", "screens", "flows", "platform", "locales", "contracts", "components", "semantic"]))
         .optional()
         .describe("Specific groups to validate. If omitted, validates all groups."),
     },
@@ -491,6 +493,7 @@ const SCHEMA_CATALOG: Record<string, { file: string; title: string; description:
   platform:         { file: "platform.schema.json",              title: "Platform",         description: "Platform-specific generation config: architecture, naming, CSS framework, component mapping" },
   contract:         { file: "contract.schema.json",              title: "Contract",         description: "Built-in UI contract definitions: variants, props, must_handle states, generation hints" },
   "custom-contract":{ file: "custom-contract.schema.json",       title: "Custom Contract",  description: "User-defined UI contract definitions (x_ prefixed)" },
+  component:        { file: "component.schema.json",             title: "Component",        description: "Reusable composition of contracts with named slots, states, variants, and layout" },
   locale:           { file: "locale.schema.json",                title: "Locale",           description: "Locale translation files: flat key-value string maps" },
   "tokens/color":       { file: "tokens/color.schema.json",       title: "Color Tokens",       description: "Color tokens: brand, surface, text, semantic, border groups with HSL ranges and contrast" },
   "tokens/typography":  { file: "tokens/typography.schema.json",   title: "Typography Tokens",  description: "Typography tokens: font families, sizes, weights, line heights, letter spacing" },
@@ -634,6 +637,53 @@ server.registerTool(
   }
 );
 
+// ── tool: openuispec_get_component ──────────────────────────────────
+
+server.registerTool(
+  "openuispec_get_component",
+  {
+    description: "Get a single component spec. Components are reusable compositions of contracts with named slots.",
+    inputSchema: {
+      name: z.string().describe("Component name, e.g. 'media_player'"),
+      variant: z.string().optional().describe("Optional variant name. If given, returns only that variant's definition."),
+    },
+  },
+  async ({ name, variant }) => {
+    try {
+      const projectDir = findProjectDir(projectCwd);
+      const manifest = YAML.parse(readFileSync(join(projectDir, "openuispec.yaml"), "utf-8"));
+      const componentsDir = resolveSpecDir(projectDir, manifest, "components");
+
+      if (!existsSync(componentsDir)) {
+        return toolError(`Components directory not found: ${componentsDir}`);
+      }
+
+      for (const file of readdirSync(componentsDir).filter(f => f.endsWith(".yaml")).sort()) {
+        const filePath = join(componentsDir, file);
+        const raw = readFileSync(filePath, "utf-8");
+        const content = YAML.parse(raw);
+        const componentName = Object.keys(content)[0];
+        if (componentName !== name) continue;
+
+        if (variant) {
+          const component = content[componentName];
+          const variantDef = component?.variants?.[variant];
+          if (!variantDef) {
+            return toolError(`Variant "${variant}" not found in component "${name}". Available variants: ${Object.keys(component?.variants ?? {}).join(", ")}`);
+          }
+          return toolResult({ name, variant, definition: variantDef });
+        }
+
+        return toolResult({ name, path: relative(projectDir, filePath), content: raw });
+      }
+
+      return toolError(`Component "${name}" not found in ${componentsDir}`);
+    } catch (err) {
+      return toolError(err);
+    }
+  }
+);
+
 // ── tool: openuispec_get_tokens ─────────────────────────────────────
 
 server.registerTool(
@@ -763,9 +813,10 @@ server.registerTool(
       full_page: z.boolean().optional().default(false).describe("Capture the full scrollable page instead of just the viewport"),
       selector: z.string().optional().describe("CSS selector to screenshot a specific element instead of the full page"),
       output_dir: z.string().optional().describe("Directory to save the screenshot PNG (relative to web app root). E.g. 'screenshots'. If omitted, only returns base64 in response."),
+      init_script: z.string().optional().describe("JavaScript to run before the page renders. Passed to the app via ?__ous_init=<base64> query param. The app's bootstrapper decodes and executes it — use for auth injection, role switching, or session setup."),
     },
   },
-  async ({ route, viewport, scale, theme, wait_for, full_page, selector, output_dir }) => {
+  async ({ route, viewport, scale, theme, wait_for, full_page, selector, output_dir, init_script }) => {
     try {
       return await takeScreenshot(projectCwd, {
         route,
@@ -776,6 +827,7 @@ server.registerTool(
         full_page,
         selector,
         output_dir,
+        init_script,
       });
     } catch (err) {
       return toolError(err);
@@ -844,6 +896,7 @@ const webBatchCaptureSchema = z.object({
   selector: z.string().optional().describe("CSS selector to screenshot a specific element"),
   full_page: z.boolean().optional().describe("Capture full scrollable page"),
   wait_for: z.number().optional().describe("Per-capture wait time in ms"),
+  init_script: z.string().optional().describe("Per-capture init script (overrides shared init_script for this capture)"),
 });
 
 server.registerTool(
@@ -856,11 +909,12 @@ server.registerTool(
       scale: z.number().optional().default(2).describe("Device pixel ratio for all captures (default 2)"),
       theme: z.enum(["light", "dark"]).optional().describe("Force color scheme for all captures"),
       output_dir: z.string().optional().describe("Directory to save all PNGs (relative to web app root)"),
+      init_script: z.string().optional().describe("Shared init script for all captures. Passed via ?__ous_init=<base64>. Per-capture init_script overrides this."),
     },
   },
-  async ({ captures, viewport, scale, theme, output_dir }) => {
+  async ({ captures, viewport, scale, theme, output_dir, init_script }) => {
     try {
-      return await takeScreenshotBatch(projectCwd, { captures, viewport, scale, theme, output_dir });
+      return await takeScreenshotBatch(projectCwd, { captures, viewport, scale, theme, output_dir, init_script });
     } catch (err) {
       return toolError(err);
     }
@@ -928,6 +982,33 @@ server.registerTool(
   }
 );
 
+// ── tool: openuispec_preview ────────────────────────────────────────────
+
+server.registerTool(
+  "openuispec_preview",
+  {
+    description: "Render a screen spec as an HTML preview with mock data and return a screenshot. Uses token values, locale strings, and contract-to-HTML mapping to produce a visual approximation without generating a full app. Mock data should be placed in openuispec/mock/<screen>.yaml.",
+    inputSchema: {
+      screen: z.string().describe("Screen name (e.g. 'home', 'settings', 'task_detail')"),
+      size_class: z.enum(["compact", "regular", "expanded"]).optional().default("compact").describe("Adaptive size class — compact (phone), regular (tablet), expanded (desktop)"),
+      theme: z.enum(["light", "dark"]).optional().default("light").describe("Color theme"),
+      locale: z.string().optional().default("en").describe("Locale code for i18n strings"),
+      viewport: z.object({
+        width: z.number(),
+        height: z.number(),
+      }).optional().describe("Custom viewport size (overrides size_class default)"),
+      include_html: z.boolean().optional().default(false).describe("Also return the rendered HTML string in the response"),
+    },
+  },
+  async ({ screen, size_class, theme, locale, viewport, include_html }) => {
+    try {
+      return await renderPreview(projectCwd, { screen, size_class, theme, locale, viewport, include_html });
+    } catch (err) {
+      return toolError(err);
+    }
+  }
+);
+
 // ── start server ─────────────────────────────────────────────────────
 
 export async function startMcpServer() {