openuispec 0.2.13 → 0.2.15

package/README.md

@@ -47,7 +47,8 @@ This scaffolds a spec directory, starter tokens, and **configures the MCP server
 
 - **Tokens** — design values (color, typography, spacing, elevation, motion) with semantic names and constrained ranges
 - **Contracts** — 7 reusable UI component families defined by role, props, interaction states, and accessibility
-- **Screens** — compositions of contracts with data bindings, adaptive layout, and conditional rendering
+- **Components** — reusable compositions of contracts with named slots, states, and variants
+- **Screens** — compositions of contracts and components with data bindings, adaptive layout, and conditional rendering
 - **Flows** — multi-screen navigation journeys, intent-based and platform-agnostic
 - **Actions** — 13 typed action types with composition, error handling, and optimistic updates
 - **Data binding** — reactive state, format expressions, caching, and loading/error/empty states
@@ -76,7 +77,7 @@ openuispec init → configures MCP for your agent → AI calls tools automatical
 
 When you ask your AI to "add a settings page" or "update the home feed," the MCP server provides spec context before generation, feeds authoritative spec contents during generation, validates spec integrity after edits, and returns a spec-derived checklist for the AI to review the generated code against.
 
-15 tools are available as both MCP tools and CLI commands — see the [full reference](./docs/cli.md).
+16 tools are available as both MCP tools and CLI commands — see the [full reference](./docs/cli.md).
 
 **Using without MCP?** You can provide spec context to any AI manually:
 
@@ -98,19 +99,19 @@ Screenshots of the generated apps are in the [artifacts](./artifacts/) directory
 |-----|-------------|
 | [CLI & MCP Tools](./docs/cli.md) | All CLI commands, MCP tools, screenshot params, target workflow |
 | [File Formats & Schemas](./docs/file-formats.md) | File types, JSON schemas, output directories, spec sections |
-| [Full Specification](./spec/openuispec-v0.1.md) | Complete v0.1 spec (14 sections) |
+| [Full Specification](./spec/openuispec-v0.2.md) | Complete v0.2 spec (15 sections) |
 | [llms-full.txt](https://openuispec.rsteam.uz/llms-full.txt) | Spec + all schemas in one file (for AI consumption) |
 
 ## Status
 
-**v0.1 — Draft**. The spec covers all foundational layers with three example apps demonstrating generation across iOS, Android, and Web.
+**v0.2 — Draft**. The spec covers all foundational layers — including component composition — with three example apps demonstrating generation across iOS, Android, and Web.
 
 ### Roadmap
 
 - [x] Token system, 7 contract families, adaptive layout, action system
 - [x] Data binding, i18n, form validation, custom contract extensions
 - [x] JSON Schema validation, CLI tool, MCP server
-- [x] Drift detection, visual verification (screenshots)
+- [x] Drift detection, visual verification (screenshots, preview)
 - [x] Example apps: TaskFlow, Todo Orbit, Social App
 - [ ] More example apps (e-commerce, dashboard)
 

package/cli/index.ts

@@ -18,6 +18,7 @@
  *   openuispec read-specs [paths...]          Read spec file contents
  *   openuispec get-screen <name>              Get a single screen spec
  *   openuispec get-contract <name> [--variant v] Get a contract spec
+ *   openuispec get-component <name> [--variant v] Get a component spec
  *   openuispec get-tokens <category>          Get tokens for a category
  *   openuispec get-locale <locale> [--keys k1,k2] Get a locale file
  *   openuispec spec-types                     List available spec types
@@ -119,6 +120,7 @@ const SCHEMA_CATALOG: Record<string, { file: string; title: string; description:
   platform:         { file: "platform.schema.json",              title: "Platform",         description: "Platform-specific generation config" },
   contract:         { file: "contract.schema.json",              title: "Contract",         description: "Built-in UI contract definitions" },
   "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" },
   locale:           { file: "locale.schema.json",                title: "Locale",           description: "Locale translation files" },
   "tokens/color":       { file: "tokens/color.schema.json",       title: "Color Tokens",       description: "Color tokens" },
   "tokens/typography":  { file: "tokens/typography.schema.json",   title: "Typography Tokens",  description: "Typography tokens" },
@@ -225,31 +227,34 @@ async function main(): Promise<void> {
       break;
     }
 
-    case "get-contract": {
+    case "get-contract":
+    case "get-component": {
+      const specType = command === "get-contract" ? "contract" : "component";
+      const specDir = specType === "contract" ? "contracts" : "components";
       const name = rest[0];
-      if (!name) { console.error("Usage: openuispec get-contract <name> [--variant v]"); process.exit(1); }
+      if (!name) { console.error(`Usage: openuispec get-${specType} <name> [--variant v]`); process.exit(1); }
       const variant = getOption(rest, "--variant");
       const { findProjectDir } = await import("../drift/index.js");
       const YAML = (await import("yaml")).default;
       const projectDir = findProjectDir(cwd);
       const manifest = YAML.parse(readFileSync(join(projectDir, "openuispec.yaml"), "utf-8"));
-      const contractsDir = resolveSpecDir(projectDir, manifest, "contracts");
+      const dir = resolveSpecDir(projectDir, manifest, specDir);
 
-      if (!existsSync(contractsDir)) { console.error(`Contracts directory not found: ${contractsDir}`); process.exit(1); }
+      if (!existsSync(dir)) { console.error(`${specDir} directory not found: ${dir}`); process.exit(1); }
 
       let found = false;
-      for (const file of readdirSync(contractsDir).filter(f => f.endsWith(".yaml")).sort()) {
-        const filePath = join(contractsDir, file);
+      for (const file of readdirSync(dir).filter(f => f.endsWith(".yaml")).sort()) {
+        const filePath = join(dir, file);
         const raw = readFileSync(filePath, "utf-8");
         const content = YAML.parse(raw);
-        const contractName = Object.keys(content)[0];
-        if (contractName !== name) continue;
+        const rootKey = Object.keys(content)[0];
+        if (rootKey !== name) continue;
         found = true;
 
         if (variant) {
-          const variantDef = content[contractName]?.variants?.[variant];
+          const variantDef = content[rootKey]?.variants?.[variant];
           if (!variantDef) {
-            const available = Object.keys(content[contractName]?.variants ?? {}).join(", ");
+            const available = Object.keys(content[rootKey]?.variants ?? {}).join(", ");
             console.error(`Variant "${variant}" not found. Available: ${available}`);
             process.exit(1);
           }
@@ -259,7 +264,7 @@ async function main(): Promise<void> {
         }
         break;
       }
-      if (!found) { console.error(`Contract "${name}" not found in ${contractsDir}`); process.exit(1); }
+      if (!found) { console.error(`${specType} "${name}" not found in ${dir}`); process.exit(1); }
       break;
     }
 
@@ -471,6 +476,7 @@ Spec access:
   openuispec read-specs [paths...]          Read spec file contents as JSON
   openuispec get-screen <name>              Get a single screen spec (YAML)
   openuispec get-contract <name> [--variant v]  Get a contract spec
+  openuispec get-component <name> [--variant v] Get a component spec
   openuispec get-tokens <category>          Get tokens for a category (YAML)
   openuispec get-locale <locale> [--keys k1,k2] Get a locale file (JSON)
   openuispec spec-types                     List available spec types
@@ -493,7 +499,7 @@ Screenshots (batch — build once, capture many):
 Server:
   openuispec mcp                            Start MCP server (stdio transport)
 
-Validate groups: manifest, tokens, screens, flows, platform, locales, contracts, semantic
+Validate groups: manifest, tokens, screens, flows, platform, locales, contracts, components, semantic
 Exit codes: 0 = success, 1 = missing config/usage error, 2 = validation failure
 Docs: https://openuispec.rsteam.uz
 `);

package/cli/init.ts

@@ -232,8 +232,8 @@ function manifestTemplate(
     structureBlock = `  structure:\n${entries}\n`;
   }
 
-  return `# ${name} — OpenUISpec v0.1
-spec_version: "0.1"
+  return `# ${name} — OpenUISpec v0.2
+spec_version: "0.2"
 
 project:
   name: "${name}"
@@ -242,6 +242,7 @@ project:
 includes:
   tokens: "./tokens/"
   contracts: "./contracts/"
+  components: "./components/"
   screens: "./screens/"
   flows: "./flows/"
   platform: "./platform/"
@@ -290,6 +291,7 @@ This directory contains the **OpenUISpec** semantic UI specification for **${nam
 | \`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 component compositions — contract slot compositions with states and variants |
 | \`platform/\` | Platform overrides — per-target (iOS, Android, Web) behaviors |
 | \`locales/\` | Localization — i18n strings (JSON, ICU MessageFormat) |
 
@@ -306,7 +308,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
 
@@ -432,6 +434,7 @@ Do not baseline on your own initiative — only run the snapshot when the user a
 **Focused getters (prefer these for incremental edits over \`read_specs\`):**
 - \`openuispec_get_screen(name)\` — single screen spec
 - \`openuispec_get_contract(name, variant?)\` — single contract, optionally one variant
+- \`openuispec_get_component(name, variant?)\` — single component, optionally one variant
 - \`openuispec_get_tokens(category)\` — single token category (color, typography, spacing, etc.)
 - \`openuispec_get_locale(locale, keys?)\` — single locale file, optionally filtered keys
 - \`openuispec_check(target, audit?, screens?, contracts?)\` — validation + optional scoped audit checklist
@@ -446,27 +449,37 @@ Use \`read_specs\` for full-project generation; use focused getters when editing
 ### CLI fallback (when MCP is not available)
 
 If MCP tools are not available, use these CLI commands with \`--json\` flag:
-- \`openuispec prepare --target <t> --json\` — build AI-ready work bundle
-- \`openuispec check --target <t> --json\` — composite validation
+
+**Status & discovery:**
 - \`openuispec status --json\` — cross-target status
-- \`openuispec drift --target <t> --explain --json\` — semantic drift
-- \`openuispec validate [group...] --json\` — schema validation
+- \`openuispec spec-types\` — list available spec types
+- \`openuispec spec-schema <type>\` — get JSON schema for a spec type
+
+**Spec access:**
 - \`openuispec read-specs [paths...]\` — read spec file contents
 - \`openuispec get-screen <name>\` — get a single screen spec
 - \`openuispec get-contract <name> [--variant v]\` — get a contract spec
+- \`openuispec get-component <name> [--variant v]\` — get a component spec
 - \`openuispec get-tokens <category>\` — get tokens for a category
 - \`openuispec get-locale <locale> [--keys k1,k2]\` — get a locale file
-- \`openuispec spec-types\` — list available spec types
-- \`openuispec spec-schema <type>\` — get JSON schema for a spec type
+
+**Validation & generation workflow:**
+- \`openuispec validate [group...] --json\` — validate spec files against JSON Schemas
+- \`openuispec check --target <t> --json\` — validate spec files + check target generation readiness
+- \`openuispec prepare --target <t> --json\` — build AI-ready work bundle
+- \`openuispec drift --target <t> --explain --json\` — semantic drift
+
+**Visual verification:**
 - \`openuispec screenshot --route /path\` — screenshot the web app
+- \`openuispec screenshot --route /path --init-script "..."\` — inject auth/role before rendering (web only; app must implement \`__ous_init\` bootstrapper)
 - \`openuispec screenshot-android [--project-dir path]\` — screenshot Android app
 - \`openuispec screenshot-ios [--project-dir path]\` — screenshot iOS app
 
 ### Other CLI commands
 - \`openuispec init\` — scaffold a new spec project
-- \`openuispec drift --snapshot --target <t>\` — snapshot current state (user-initiated, after reviewing generated output)
 - \`openuispec configure-target <t>\` — configure target platform stack
 - \`openuispec update-rules\` — update AI rules to match installed package version
+- \`openuispec drift --snapshot --target <t>\` — snapshot current state (user-initiated, after reviewing generated output)
 
 ## Spec format reference
 
@@ -478,13 +491,13 @@ You MUST read the reference files before creating or editing spec files — do N
 
 **Reference files (read in order):**
 1. \`README.md\` — schema tables, file format, root wrapper keys
-2. \`spec/openuispec-v0.1.md\` — full specification
+2. \`spec/openuispec-v0.2.md\` — full specification
 3. \`examples/taskflow/openuispec/\` — complete working example
 4. \`schema/\` — JSON Schemas for every file type
 
 ## Spec location
 - Spec root: \`${specDir}/\` — read \`${specDir}/openuispec.yaml\` first for actual paths.
-- Default dirs: tokens/, screens/, flows/, contracts/, platform/, locales/
+- Default dirs: tokens/, screens/, flows/, contracts/, components/, platform/, locales/
 
 ## When to start from spec vs platform code
 
@@ -500,7 +513,7 @@ You MUST read the reference files before creating or editing spec files — do N
 
 ## If spec directories are empty (first-time setup)
 
-Read \`spec/openuispec-v0.1.md\` from the package first, then:
+Read \`spec/openuispec-v0.2.md\` from the package first, then:
 1. Scan codebase for UI screens → create \`${specDir}/screens/<name>.yaml\` as \`status: stub\`
 2. Extract tokens (colors, fonts, spacing) → \`${specDir}/tokens/\`
 3. Create contract extensions → \`${specDir}/contracts/\`
@@ -590,10 +603,62 @@ export function updateRules(): void {
     console.log(`\nAI rules updated to v${version}`);
   }
 
+  // Migrate old spec doc version references to current
+  migrateDocVersionRefs(cwd, specDir);
+
   // Ensure MCP server is configured
   configureMcp(cwd, true);
 }
 
+// ── spec doc version migration ──────────────────────────────────────
+
+function getCurrentSpecDocVersion(): string | null {
+  const pkgDir = dirname(fileURLToPath(import.meta.url));
+  const specDir = join(pkgDir, "..", "spec");
+  try {
+    const files = readdirSync(specDir);
+    const match = files
+      .map((f) => f.match(/^openuispec-v(.+)\.md$/))
+      .filter(Boolean)
+      .sort()
+      .pop();
+    return match ? match[1] : null;
+  } catch {
+    return null;
+  }
+}
+
+function migrateDocVersionRefs(cwd: string, specDir: string): void {
+  const currentVersion = getCurrentSpecDocVersion();
+  if (!currentVersion) return;
+
+  const currentRef = `openuispec-v${currentVersion}`;
+  const pattern = /openuispec-v(\d+\.\d+)/g;
+
+  const filesToCheck = [
+    join(cwd, specDir, "README.md"),
+    join(cwd, "CLAUDE.md"),
+    join(cwd, "AGENTS.md"),
+  ];
+
+  for (const filePath of filesToCheck) {
+    if (!existsSync(filePath)) continue;
+
+    const content = readFileSync(filePath, "utf-8");
+    const oldRefs = [...content.matchAll(pattern)]
+      .filter((m) => m[1] !== currentVersion);
+    if (oldRefs.length === 0) continue;
+
+    const migrated = content.replace(pattern, (_match, ver) =>
+      ver === currentVersion ? _match : currentRef
+    );
+    writeFileSync(filePath, migrated);
+    const relPath = relative(cwd, filePath);
+    const oldVersions = [...new Set(oldRefs.map((m) => m[1]))].join(", ");
+    console.log(`  updated ${relPath} (migrated v${oldVersions} → v${currentVersion} doc references)`);
+  }
+}
+
 // ── shared MCP config ───────────────────────────────────────────────
 
 const EXPECTED_MCP_CONFIG = {
@@ -1058,6 +1123,7 @@ export async function init(argv: string[] = []): Promise<void> {
     const dirs = [
       "tokens",
       "contracts",
+      "components",
       "screens",
       "flows",
       "platform",

package/docs/cli.md

@@ -38,32 +38,51 @@ Or run directly: `openuispec mcp`
 
 ## MCP Tools
 
-| Tool | When | What it does |
-|------|------|-------------|
-| `openuispec_spec_types` | Before creating spec files | Lists all available spec types with descriptions |
-| `openuispec_spec_schema` | Before creating/editing spec files | Returns JSON schema for a spec type. Optional `summary` for top-level overview |
-| `openuispec_prepare` | Before UI code generation | Returns spec context, platform config, constraints. Optional `include_specs` embeds all spec contents |
-| `openuispec_read_specs` | Before and after generation | Without `paths`: returns file listing. With `paths`: loads spec contents |
-| `openuispec_check` | After spec edits or generation | Spec validation (schema + semantic) + prepare readiness. `audit=true` returns a spec-derived checklist for manual code review |
-| `openuispec_validate` | After spec edits | Schema-only validation, optionally filtered by group |
-| `openuispec_drift` | Before updates / after generation | Detect drift, or `snapshot=true` to create/update baseline |
-| `openuispec_status` | Anytime | Cross-target summary: baselines, drift, next steps |
-| `openuispec_get_screen` | Incremental edits | Get a single screen spec by name |
-| `openuispec_get_contract` | Incremental edits | Get a single contract spec, optionally filtered to one variant |
-| `openuispec_get_tokens` | Incremental edits | Get tokens for a specific category |
-| `openuispec_get_locale` | Incremental edits | Get a single locale file, optionally filtered to specific keys |
-| `openuispec_screenshot` | Visual verification | Screenshot the web app at a route via headless browser |
-| `openuispec_screenshot_android` | Visual verification | Screenshot Android app on emulator. Works with any project via `project_dir` |
-| `openuispec_screenshot_ios` | Visual verification | Screenshot iOS app on Simulator via XCUITest. Works with any project via `project_dir` |
-| `openuispec_screenshot_web_batch` | Visual verification | Multiple web screenshots in one server session |
-| `openuispec_screenshot_android_batch` | Visual verification | Multiple Android screenshots in one build+install cycle |
-| `openuispec_screenshot_ios_batch` | Visual verification | Multiple iOS screenshots in one build+install cycle |
+### Status & discovery
+
+| Tool | What it does |
+|------|-------------|
+| `openuispec_status` | Cross-target summary: baselines, drift, next steps |
+| `openuispec_spec_types` | Lists all available spec types with descriptions |
+| `openuispec_spec_schema` | Returns JSON schema for a spec type. Optional `summary` for top-level overview |
+
+### Spec access
+
+| Tool | What it does |
+|------|-------------|
+| `openuispec_read_specs` | Without `paths`: returns file listing. With `paths`: loads spec contents |
+| `openuispec_get_screen` | Get a single screen spec by name |
+| `openuispec_get_contract` | Get a single contract spec, optionally filtered to one variant |
+| `openuispec_get_component` | Get a single component spec, optionally filtered to one variant |
+| `openuispec_get_tokens` | Get tokens for a specific category |
+| `openuispec_get_locale` | Get a single locale file, optionally filtered to specific keys |
+
+### Validation & generation workflow
+
+| Tool | What it does |
+|------|-------------|
+| `openuispec_validate` | Validate spec files against JSON Schemas, optionally filtered by group |
+| `openuispec_check` | Validate spec files (schema + semantic) and check target generation readiness. `audit=true` returns a spec-derived review checklist |
+| `openuispec_prepare` | Returns spec context, platform config, constraints. Optional `include_specs` embeds all spec contents |
+| `openuispec_drift` | Detect drift, or `snapshot=true` to create/update baseline |
+
+### Visual verification
+
+| Tool | What it does |
+|------|-------------|
+| `openuispec_preview` | Render a screen spec as HTML with mock data and return a screenshot — no app build needed. **Experimental**: visual approximation, not pixel-accurate |
+| `openuispec_screenshot` | Screenshot the web app at a route via headless browser |
+| `openuispec_screenshot_android` | Screenshot Android app on emulator. Works with any project via `project_dir` |
+| `openuispec_screenshot_ios` | Screenshot iOS app on Simulator via XCUITest. Works with any project via `project_dir` |
+| `openuispec_screenshot_web_batch` | Multiple web screenshots in one server session |
+| `openuispec_screenshot_android_batch` | Multiple Android screenshots in one build+install cycle |
+| `openuispec_screenshot_ios_batch` | Multiple iOS screenshots in one build+install cycle |
 
 The server includes **protocol-level instructions** that trigger on UI-related requests independently of CLAUDE.md rules.
 
 ## CLI Commands
 
-### Workflow
+### Project setup
 
 ```bash
 openuispec init                            # Scaffold a new spec project
@@ -71,25 +90,36 @@ openuispec init --defaults                 # Non-interactive with unconfirmed de
 openuispec init --no-configure-targets     # Skip target stack setup
 openuispec update-rules                    # Update AI rules to match installed version
 openuispec configure-target <t> [--defaults]  # Configure target stack
-openuispec validate [group...] [--json]    # Validate spec files
-openuispec validate semantic               # Semantic cross-reference linting
+```
+
+### Validation
+
+```bash
+openuispec validate [group...] [--json]    # Validate spec files against JSON Schemas
+openuispec validate semantic               # Lint cross-references (locale keys, icons, contracts, tokens)
+openuispec check --target <t> [--json]     # Validate spec files + check target generation readiness
+```
+
+### Status & generation workflow
+
+```bash
 openuispec status [--json]                 # Cross-target baseline/drift status
-openuispec drift --target <t> --explain    # Explain semantic spec drift
 openuispec prepare --target <t> [--json]   # Build the target work bundle
-openuispec check --target <t> [--json]     # Composite validation + prepare readiness
+openuispec drift --target <t> --explain    # Explain semantic spec drift
 openuispec drift --snapshot --target <t>   # Snapshot current state + git baseline
 ```
 
 ### Spec access
 
 ```bash
+openuispec spec-types                         # List available spec types
+openuispec spec-schema <type>                 # Get JSON schema for a spec type
 openuispec read-specs [paths...]              # Read spec file contents as JSON
 openuispec get-screen <name>                  # Get a single screen spec (YAML)
 openuispec get-contract <name> [--variant v]  # Get a contract spec
+openuispec get-component <name> [--variant v] # Get a component spec
 openuispec get-tokens <category>              # Get tokens for a category (YAML)
 openuispec get-locale <locale> [--keys k1,k2] # Get a locale file (JSON)
-openuispec spec-types                         # List available spec types
-openuispec spec-schema <type>                 # Get JSON schema for a spec type
 ```
 
 ### Screenshots
@@ -145,6 +175,83 @@ Each capture supports:
 - `wait_for`: per-capture wait time in ms
 - `selector`: CSS selector to screenshot a specific element (web only)
 - `full_page`: capture full scrollable page (web only)
+- `init_script`: JavaScript to execute before the page renders (web only — see below)
+
+### `init_script` — app-level initialization
+
+`init_script` lets you inject auth, switch roles, or set up session state before a screenshot is taken — without Puppeteer executing JS directly. The tool base64-encodes the script and appends it as a `?__ous_init=<encoded>` query param. The generated app's bootstrapper reads and runs it before rendering.
+
+**Why app-level instead of `evaluateOnNewDocument`:** the app can `await` login APIs, set framework state, or call any async init — Puppeteer's `evaluateOnNewDocument` is sync-only and has no access to app internals.
+
+**Single capture (MCP):**
+
+```json
+{
+  "route": "/dashboard",
+  "init_script": "window.__auth = { token: 'test-token', role: 'admin' };"
+}
+```
+
+**Batch capture (MCP):**
+
+```json
+{
+  "output_dir": "screenshots",
+  "init_script": "window.__auth = { token: 'test-token', role: 'viewer' };",
+  "captures": [
+    { "screen": "dashboard", "route": "/dashboard" },
+    { "screen": "admin_panel", "route": "/admin",
+      "init_script": "window.__auth = { token: 'test-token', role: 'admin' };" }
+  ]
+}
+```
+
+Per-capture `init_script` overrides the shared one. If neither is set, no param is appended and the app renders normally.
+
+**Bootstrapper contract** — the generated app must include a bootstrapper that:
+
+1. Checks for `__ous_init` in the URL query string on load
+2. Base64-decodes it (`atob`) and `eval`s it (or parses it as structured data)
+3. Runs **before** rendering authenticated content (can be async — app awaits it)
+4. Strips the param from URL/history after processing (`history.replaceState`)
+
+Example bootstrapper (framework-agnostic):
+
+```js
+const param = new URLSearchParams(location.search).get('__ous_init');
+if (param) {
+  try { eval(atob(param)); } catch (e) { console.warn('[ous] init_script error', e); }
+  const url = new URL(location.href);
+  url.searchParams.delete('__ous_init');
+  history.replaceState(null, '', url.toString());
+}
+```
+
+This is a **contract between the tool and generated code** — the tool appends the param; the app consumes it.
+
+### Preview (experimental)
+
+> **Note:** The preview renderer produces a _visual approximation_ of the spec — it maps contracts to semantic HTML+CSS and applies token values, but does not match the fidelity of a real generated app. Intended for **human inspection only** — AI agents should not use this tool for UI verification and should use `openuispec_screenshot` (or the batch/platform variants) against the real built app instead.
+
+```bash
+# MCP tool (intended for human review, not AI verification)
+openuispec_preview screen=home size_class=compact theme=light
+
+# No CLI equivalent yet — preview is MCP-only.
+```
+
+Parameters:
+
+| Param | Default | Purpose |
+|-------|---------|---------|
+| `screen` | (required) | Screen name matching `screens/<name>.yaml` |
+| `size_class` | `compact` | Adaptive breakpoint: `compact`, `regular`, `expanded` |
+| `theme` | `light` | Color theme: `light` or `dark` |
+| `locale` | `en` | Locale code for i18n string resolution |
+| `viewport` | auto | Custom `{width, height}` — overrides `size_class` defaults |
+| `include_html` | `false` | Also return the rendered HTML string |
+
+Preview reads mock data from `openuispec/mock/<screen>.yaml` — see [File Formats](./file-formats.md) for the mock data convention.
 
 ## Target Update Workflow
 

package/docs/file-formats.md

@@ -12,7 +12,8 @@ Every file type has a corresponding JSON Schema in `schema/`. **Read the schema
 | `platform/*.yaml` | `platform.schema.json` | `platform` | [ios.yaml](../examples/taskflow/openuispec/platform/ios.yaml) |
 | `locales/*.json` | `locale.schema.json` | (object) | [en.json](../examples/taskflow/openuispec/locales/en.json) |
 | `contracts/<name>.yaml` | `contract.schema.json` | `<contract_name>` | [input_field.yaml](../examples/taskflow/openuispec/contracts/input_field.yaml) |
-| `contracts/x_*.yaml` | `custom-contract.schema.json` | `<x_name>` | [x_media_player.yaml](../examples/taskflow/openuispec/contracts/x_media_player.yaml) |
+| `contracts/x_*.yaml` | `custom-contract.schema.json` | `<x_name>` | [x_schedule_preview.yaml](../examples/todo-orbit/openuispec/contracts/x_schedule_preview.yaml) |
+| `components/*.yaml` | `component.schema.json` | `<component_name>` | [media_player.yaml](../examples/taskflow/openuispec/components/media_player.yaml) |
 | `tokens/color.yaml` | `tokens/color.schema.json` | `color` | [color.yaml](../examples/taskflow/openuispec/tokens/color.yaml) |
 | `tokens/typography.yaml` | `tokens/typography.schema.json` | `typography` | [typography.yaml](../examples/taskflow/openuispec/tokens/typography.yaml) |
 | `tokens/spacing.yaml` | `tokens/spacing.schema.json` | `spacing` | [spacing.yaml](../examples/taskflow/openuispec/tokens/spacing.yaml) |
@@ -21,6 +22,7 @@ Every file type has a corresponding JSON Schema in `schema/`. **Read the schema
 | `tokens/layout.yaml` | `tokens/layout.schema.json` | `layout` | [layout.yaml](../examples/taskflow/openuispec/tokens/layout.yaml) |
 | `tokens/themes.yaml` | `tokens/themes.schema.json` | `themes` | [themes.yaml](../examples/taskflow/openuispec/tokens/themes.yaml) |
 | `tokens/icons.yaml` | `tokens/icons.schema.json` | `icons` | [icons.yaml](../examples/taskflow/openuispec/tokens/icons.yaml) |
+| `mock/<screen>.yaml` | — | `data` / `params` | [analytics.yaml](../examples/todo-orbit/openuispec/mock/analytics.yaml) |
 
 Every token file **must** have a single root wrapper key matching its type:
 
@@ -35,6 +37,40 @@ brand:
   primary: ...
 ```
 
+## Components
+
+Components are **reusable compositions of contracts with named slots**. They fill the gap between atomic contracts and full-page screens — use them for complex UI blocks like media players, wizards, conversation timelines, and maps.
+
+```
+Tokens → Contracts → Components → Screens → Flows
+         (atomic)    (composed)    (full page)
+```
+
+Each component file lives in `components/*.yaml` with a single root key (the component name). Components define:
+
+- **slots** — named contract instances (e.g. `play_button: { contract: action_trigger }`)
+- **layout** — how slots are arranged (stack, row, nested)
+- **states** — composite states that hide slots or override slot props (e.g. `playing`, `loading`)
+- **variants** — named presets that change layout, hide slots, or override tokens (e.g. `mini`, `fullscreen`)
+
+Screens reference components with `component:` instead of `contract:` and can override individual slots:
+
+```yaml
+- component: media_player
+  variant: mini
+  props:
+    source: "{task.attachment.url}"
+  slots:
+    volume_control: { hidden: true }
+    play_button:
+      variant: branded
+      tokens_override: { background: "color.brand.primary" }
+```
+
+**Resolution order:** slot default → variant override → state override → screen-level override. Most specific wins.
+
+Simple custom contracts (`x_entity_status_badge`, etc.) stay as `x_` prefixed contracts — components are for composed UI that has internal layout and state.
+
 ## Shared interactive state roles
 
 Interactive contracts may optionally express state-specific visual roles inside their token maps with a nested `states:` object. This lets generators use explicit roles for `default`, `active`, `selected`, `pressed`, `focused`, `disabled`, `loading`, and `error` states.
@@ -100,6 +136,20 @@ generation:
 - Shared layers are not targets — they are tracked alongside targets in `prepare` and `status` output.
 - `openuispec init --with-shared` scaffolds KMP defaults when both ios and android targets are selected.
 
+## Mock data (preview)
+
+The preview renderer reads mock data from `openuispec/mock/<screen>.yaml`. Each file has two optional top-level keys:
+
+```yaml
+data:
+  tasks: [...]          # binds to $data.tasks in the screen spec
+  user: { name: "..." } # binds to $data.user
+params:
+  id: "task-1"          # binds to $params.id
+```
+
+Mock files are not validated by `openuispec validate` and are excluded from drift detection. They exist solely to feed the preview renderer with realistic placeholder data. Preview is intended for **human inspection only** — AI agents should not use it for UI verification.
+
 ## Spec sections overview
 
 | Section | What it defines |

package/drift/index.ts

@@ -189,6 +189,9 @@ export function discoverSpecFiles(projectDir: string): string[] {
   if (includes.contracts) {
     files.push(...listFiles(resolve(projectDir, includes.contracts), ".yaml"));
   }
+  if (includes.components) {
+    files.push(...listFiles(resolve(projectDir, includes.components), ".yaml"));
+  }
 
   return files;
 }
@@ -203,6 +206,7 @@ export function specCategory(relPath: string): string {
   if (dir === "platform") return "platform";
   if (dir === "locales") return "locales";
   if (dir === "contracts") return "contracts";
+  if (dir === "components") return "components";
   return "other";
 }
 
@@ -662,7 +666,7 @@ export function createSharedSnapshot(
   const { entries, stubs: stubCount } = buildFileEntries(projectDir, files);
 
   const state: SharedLayerState = {
-    spec_version: manifest.spec_version ?? "0.1",
+    spec_version: manifest.spec_version ?? "0.2",
     snapshot_at: new Date().toISOString(),
     layer_name: layerName,
     generated_by_target: generatedByTarget,
@@ -770,7 +774,7 @@ export function createSnapshot(cwd: string, target: string): SnapshotResult {
   const { entries, stubs: stubCount } = buildFileEntries(projectDir, files);
 
   const state: StateFile = {
-    spec_version: manifest.spec_version ?? "0.1",
+    spec_version: manifest.spec_version ?? "0.2",
     snapshot_at: new Date().toISOString(),
     target,
     baseline,
@@ -1033,6 +1037,7 @@ function printReport(projectDir: string, result: CheckResult): void {
     "Platform",
     "Locales",
     "Contracts",
+    "Components",
     "Other",
   ];
 

package/examples/social-app/openuispec/README.md

@@ -12,6 +12,7 @@ This directory contains the **OpenUISpec** semantic UI specification for **socia
 | `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