openuispec 0.1.18 → 0.1.20

package/README.md

@@ -4,6 +4,8 @@
 
 OpenUISpec is a **semantic UI specification format** that replaces cross-platform frameworks with a declarative design language. Instead of sharing runtime code across platforms, you share the *spec* — and AI generates native SwiftUI, Jetpack Compose, and React code from it.
 
+OpenUISpec is a shared UI sync language for native products, optimized for solo developers but equally usable by teams. It is not a pixel-perfect design format like Figma and it is not a shared runtime like Flutter or React Native. Its job is to keep product intent, interaction contracts, flows, tokens, and platform outputs aligned while still allowing bounded native variation on iOS, Android, and web.
+
 ## Why
 
 Cross-platform frameworks (Flutter, React Native, KMP/CMP) solve code duplication by sharing a runtime. OpenUISpec solves it by sharing **intent**:
@@ -13,7 +15,7 @@ Cross-platform frameworks (Flutter, React Native, KMP/CMP) solve code duplicatio
 | Cross-platform framework | Runtime code | Abstraction layer |
 | **OpenUISpec** | **Semantic spec** | **Native per platform** |
 
-The result: each platform feels native, but every app stays consistent because it's generated from the same source of truth.
+The result: each platform feels native, but every app stays semantically consistent because it's generated from the same source of truth.
 
 ## How it works
 
@@ -56,7 +58,18 @@ Then hand your spec to any AI code generator:
 
 > Generate a native iOS app from this OpenUISpec. Follow all contract state machines, apply token ranges for iOS, and implement navigation flows as defined. Use `platform/ios.yaml` for SwiftUI-specific overrides.
 
-See the [TaskFlow example](./examples/taskflow/) for a complete spec covering all 7 contract families.
+Before platform code generation, the AI should refresh its understanding of the current target toolchain and platform conventions instead of relying on stale memory. This matters most for project formats, resource wiring, navigation APIs, packaging rules, and other implementation details that change across toolchain versions.
+
+For platform generation, treat these as hard output constraints:
+
+- Generate a valid native project or target that actually bundles every required runtime resource. Converting spec inputs into platform-native resource files is insufficient unless those files are attached to the final app target and resolve at runtime.
+- Do not ship unresolved resource identifiers in the UI. Raw localization keys, token references, asset names, or placeholder paths mean the generated output is incomplete.
+- Do not use a container or navigation primitive without defining its behavior for every supported size class and form factor. Master-detail patterns must provide a non-empty compact fallback instead of assuming large-screen behavior.
+
+See the examples for concrete reference projects:
+
+- [TaskFlow](./examples/taskflow/) for a compact spec covering all 7 contract families
+- [Todo Orbit](./examples/todo-orbit/openuispec/) for a bilingual task app with generated iOS, Android, and web targets under `examples/todo-orbit/generated/`
 
 ## Repository structure
 
@@ -89,37 +102,41 @@ openuispec/
 │   │   └── validation.schema.json     # Validation rule definitions
 │   └── validate.ts                     # Validation script (npm run validate)
 ├── examples/
-│   └── taskflow/                        # Complete example app
-│       ├── openuispec.yaml              # Root manifest + data model + API endpoints
-│       ├── tokens/
-│       │   ├── color.yaml               # Brand + semantic + status colors
-│       │   ├── typography.yaml          # Font family + 8-step type scale
-│       │   ├── spacing.yaml             # 4px base unit, 9-step scale
-│       │   ├── elevation.yaml           # 4-level elevation (none/sm/md/lg)
-│       │   ├── motion.yaml              # Durations, easings, patterns
-│       │   ├── layout.yaml              # Size classes, primitives, reflow rules
-│       │   ├── themes.yaml              # Light, dark, warm variants
-│       │   └── icons.yaml              # Icon registry with platform mappings
-│       ├── contracts/                   # Standard contract extensions + custom contracts
-│       │   ├── input_field.yaml       # Standard contract with cut_corner variant
-│       │   └── x_media_player.yaml    # Custom media player contract (Section 12)
-│       ├── screens/
-│       │   ├── home.yaml                # Task list with search, filters, FAB, adaptive nav
-│       │   ├── task_detail.yaml         # Full task view with actions + assignee sheet
-│       │   ├── projects.yaml            # Project grid + new project dialog
-│       │   ├── project_detail.yaml      # Single project with task list (stub)
-│       │   ├── settings.yaml            # Preferences, toggles, account management
-│       │   ├── profile_edit.yaml        # Edit profile form (stub)
-│       │   └── calendar.yaml            # Calendar view (stub)
-│       ├── flows/
-│       │   ├── create_task.yaml         # Task creation form (sheet presentation)
-│       │   └── edit_task.yaml           # Task editing flow
-│       ├── locales/
-│       │   └── en.json                  # English locale (ICU MessageFormat)
-│       └── platform/
-│           ├── ios.yaml                 # SwiftUI overrides + behaviors
-│           ├── android.yaml             # Compose overrides + behaviors
-│           └── web.yaml                 # React overrides + responsive rules
+│   ├── taskflow/                        # Compact reference spec
+│   │   ├── openuispec.yaml              # Root manifest + data model + API endpoints
+│   │   ├── tokens/
+│   │   │   ├── color.yaml               # Brand + semantic + status colors
+│   │   │   ├── typography.yaml          # Font family + 8-step type scale
+│   │   │   ├── spacing.yaml             # 4px base unit, 9-step scale
+│   │   │   ├── elevation.yaml           # 4-level elevation (none/sm/md/lg)
+│   │   │   ├── motion.yaml              # Durations, easings, patterns
+│   │   │   ├── layout.yaml              # Size classes, primitives, reflow rules
+│   │   │   ├── themes.yaml              # Light, dark, warm variants
+│   │   │   └── icons.yaml               # Icon registry with platform mappings
+│   │   ├── contracts/                   # Standard contract extensions + custom contracts
+│   │   │   ├── input_field.yaml         # Standard contract with cut_corner variant
+│   │   │   └── x_media_player.yaml      # Custom media player contract (Section 12)
+│   │   ├── screens/
+│   │   │   ├── home.yaml                # Task list with search, filters, FAB, adaptive nav
+│   │   │   ├── task_detail.yaml         # Full task view with actions + assignee sheet
+│   │   │   ├── projects.yaml            # Project grid + new project dialog
+│   │   │   ├── project_detail.yaml      # Single project with task list (stub)
+│   │   │   ├── settings.yaml            # Preferences, toggles, account management
+│   │   │   ├── profile_edit.yaml        # Edit profile form (stub)
+│   │   │   └── calendar.yaml            # Calendar view (stub)
+│   │   ├── flows/
+│   │   │   ├── create_task.yaml         # Task creation form (sheet presentation)
+│   │   │   └── edit_task.yaml           # Task editing flow
+│   │   ├── locales/
+│   │   │   └── en.json                  # English locale (ICU MessageFormat)
+│   │   └── platform/
+│   │       ├── ios.yaml                 # SwiftUI overrides + behaviors
+│   │       ├── android.yaml             # Compose overrides + behaviors
+│   │       └── web.yaml                 # React overrides + responsive rules
+│   └── todo-orbit/                      # Full showcase app with generated targets
+│       ├── openuispec/                  # Source OpenUISpec project
+│       ├── generated/                   # Generated iOS, Android, and web apps
+│       └── artifacts/                   # Screenshots and supporting outputs
 ├── cli/                                 # CLI tool (openuispec init, drift, validate)
 │   ├── index.ts                        # Entry point
 │   └── init.ts                         # Project scaffolding + AI rules
@@ -214,7 +231,7 @@ Paths are relative to `openuispec.yaml`. The `.openuispec-state.json` file is st
 
 ## Status
 
-**v0.1 — Draft**. The spec covers all foundational layers. One complete example app (TaskFlow) demonstrates full coverage.
+**v0.1 — Draft**. The spec covers all foundational layers. TaskFlow provides a compact reference app, and Todo Orbit extends coverage with localization, recurring-rule flows, custom contracts, and generated native/web targets.
 
 ### Roadmap
 
@@ -231,6 +248,7 @@ Paths are relative to `openuispec.yaml`. The `.openuispec-state.json` file is st
 - [x] Form system (validation rules, field dependencies)
 - [x] Drift detection (spec change tracking per platform)
 - [x] CLI tool (`openuispec init` for project scaffolding + AI rules)
+- [x] Multi-platform showcase app (`examples/todo-orbit/`)
 - [ ] More example apps (e-commerce, social, dashboard)
 
 ## Contributing

package/cli/index.ts

@@ -43,7 +43,7 @@ Usage:
   openuispec drift --snapshot --target <t>  Snapshot current state
   openuispec validate [group...]            Validate spec files
 
-Validate groups: manifest, tokens, screens, flows, platform, locales, custom_contracts
+Validate groups: manifest, tokens, screens, flows, platform, locales, contracts
 
 Docs: https://openuispec.rsteam.uz
 `);

package/cli/init.ts

@@ -128,7 +128,7 @@ function specReadmeTemplate(name: string, targets: string[]): string {
 
 This directory contains the **OpenUISpec** semantic UI specification for **${name}**.
 
-OpenUISpec is a YAML-based format that describes your app's UI semantically — tokens, screens, flows, and platform overrides. AI reads the spec and generates native code (SwiftUI, Compose, React). The spec is the single source of truth across all platforms.
+**Start here:** read \`openuispec.yaml\` — it defines the project structure, data model, API endpoints, and generation targets (**${targetList}**).
 
 ## Directory structure
 
@@ -137,113 +137,26 @@ OpenUISpec is a YAML-based format that describes your app's UI semantically —
 | \`tokens/\` | Design tokens — colors, typography, spacing, elevation, motion, icons, themes |
 | \`screens/\` | Screen definitions — one YAML file per screen |
 | \`flows/\` | Navigation flows — multi-step user journeys |
-| \`contracts/\` | Component contracts — standard extensions (variants, tokens) and custom (\`x_\` prefixed) |
+| \`contracts/\` | Component contracts — standard extensions and custom (\`x_\` prefixed) |
 | \`platform/\` | Platform overrides — per-target (iOS, Android, Web) behaviors |
 | \`locales/\` | Localization — i18n strings (JSON, ICU MessageFormat) |
 
-All directory paths are configured in \`openuispec.yaml\` under \`includes:\` and support relative paths. For example, to share locales across projects:
-\`\`\`yaml
-includes:
-  locales: "../../shared/locales"   # resolved relative to openuispec.yaml
-\`\`\`
-
-## Getting started
-
-**Start here:** read \`openuispec.yaml\` — it's the root manifest that defines the project structure, data model, API endpoints, and generation targets.
-
-### New project (no existing UI code)
-
-1. Define your data model and API endpoints in \`openuispec.yaml\`
-2. Create token files in \`tokens/\` (colors, typography, spacing)
-3. Create screen specs in \`screens/\` (one YAML per screen)
-4. Create navigation flows in \`flows/\`
-5. Ask AI to generate native code from the spec
-
-### Existing project (adopting OpenUISpec)
-
-1. Scan the codebase for existing UI screens
-2. Create a stub for each screen in \`screens/\`:
-   \`\`\`yaml
-   screen_name:
-     semantic: "Brief description of what this screen does"
-     status: stub
-     layout:
-       type: scroll_vertical
-   \`\`\`
-3. Extract design tokens (colors, fonts, spacing) into \`tokens/\`
-4. Fill in \`data_model\` and \`api.endpoints\` in \`openuispec.yaml\`
-5. Spec screens incrementally: \`stub\` → \`draft\` → \`ready\`
-
-## Screen and flow status
-
-- \`stub\` — placeholder, not yet specced. Drift detection skips these.
-- \`draft\` — actively being specced. Tracked by drift.
-- \`ready\` — fully specified (default if omitted). Tracked by drift.
-
-## Learning OpenUISpec — where to find the docs
-
-All documentation is included in the installed \`openuispec\` package. Search for it in this order:
-1. **Local:** \`node_modules/openuispec/\` (if installed as a project dependency)
-2. **Global:** run \`npm root -g\` to find the global prefix, then look in \`<prefix>/openuispec/\`
-3. **Online fallback:** if the package is not installed at all, fetch from:
-   - \`https://openuispec.rsteam.uz/llms-full.txt\` — complete spec + all JSON schemas in one file
-   - \`https://openuispec.rsteam.uz/llms.txt\` — concise summary with links
-
-Inside the package:
-- **Full specification:** \`spec/openuispec-v0.1.md\`
-- **Example app:** \`examples/taskflow/\`
-- **JSON Schemas:** \`schema/\`
-
-## Token file structure — root wrapper key required
-
-Every token file must have a single root key matching the token type. Do NOT put properties at the top level.
-
-\`\`\`yaml
-# ✅ Correct — tokens/typography.yaml
-typography:
-  font_family: ...
-  scale: ...
-
-# ❌ Wrong — missing root wrapper key
-font_family: ...
-scale: ...
-\`\`\`
-
-Root keys: \`color\`, \`typography\`, \`spacing\`, \`elevation\`, \`motion\`, \`layout\`, \`themes\`, \`icons\`.
-
-## File formats and schemas
-
-**IMPORTANT:** Before creating or editing any spec file, read the corresponding JSON Schema to understand the valid structure. Do not guess the file format.
-
-| File | Schema | Root key |
-|------|--------|----------|
-| \`openuispec.yaml\` | \`openuispec.schema.json\` | \`spec_version\` |
-| \`screens/*.yaml\` | \`screen.schema.json\` | \`<screen_id>\` |
-| \`flows/*.yaml\` | \`flow.schema.json\` | \`<flow_id>\` |
-| \`platform/*.yaml\` | \`platform.schema.json\` | \`platform\` |
-| \`locales/*.json\` | \`locale.schema.json\` | (object) |
-| \`contracts/<name>.yaml\` | \`contract.schema.json\` | \`<contract_name>\` |
-| \`contracts/x_*.yaml\` | \`custom-contract.schema.json\` | \`<x_name>\` |
-| \`tokens/color.yaml\` | \`tokens/color.schema.json\` | \`color\` |
-| \`tokens/typography.yaml\` | \`tokens/typography.schema.json\` | \`typography\` |
-| \`tokens/spacing.yaml\` | \`tokens/spacing.schema.json\` | \`spacing\` |
-| \`tokens/elevation.yaml\` | \`tokens/elevation.schema.json\` | \`elevation\` |
-| \`tokens/motion.yaml\` | \`tokens/motion.schema.json\` | \`motion\` |
-| \`tokens/layout.yaml\` | \`tokens/layout.schema.json\` | \`layout\` |
-| \`tokens/themes.yaml\` | \`tokens/themes.schema.json\` | \`themes\` |
-| \`tokens/icons.yaml\` | \`tokens/icons.schema.json\` | \`icons\` |
-
-All schemas are in \`schema/\` inside the installed package. Shared type definitions (actions, data-binding, adaptive, validation, common) are in \`schema/defs/\`.
+## IMPORTANT — Read the specification before working with spec files
 
-**Workflow:** read the schema → read an example from \`examples/taskflow/\` → create the YAML → run \`openuispec validate\`.
+The spec format, file schemas, and generation rules are defined in the installed \`openuispec\` package.
+You MUST read these reference files before creating, editing, or generating from any spec file.
+Do NOT guess the file format — skipping this step will produce invalid YAML that fails validation.
 
-## Spec format quick reference
+**Find the package in this order:**
+1. \`node_modules/openuispec/\` (project dependency)
+2. Run \`npm root -g\` → \`<prefix>/openuispec/\` (global install)
+3. Online: \`https://openuispec.rsteam.uz/llms-full.txt\` (if not installed)
 
-- **7 contract families:** nav_container, surface, action_trigger, input_field, data_display, collection, feedback
-- **Custom contracts:** prefixed with \`x_\` (e.g., \`x_media_player\`)
-- **Data binding:** \`$data:\`, \`$state:\`, \`$param:\`, \`$t:\` prefixes
-- **Actions:** typed objects — navigate, api_call, set_state, confirm, sequence, feedback, etc.
-- **Adaptive layout:** size classes (compact, regular, expanded) with per-section overrides
+**Reference files inside the package (read in this order):**
+1. \`README.md\` — schema tables, file format reference, root keys
+2. \`spec/openuispec-v0.1.md\` — full specification (contracts, layout, expressions, etc.)
+3. \`examples/taskflow/\` — complete working example with all file types
+4. \`schema/\` — JSON Schemas for validation
 
 ## CLI commands
 
@@ -252,34 +165,11 @@ openuispec validate             # Validate spec files against schemas
 openuispec validate screens     # Validate only screens
 openuispec drift --target ${targets[0]}    # Check for spec drift
 openuispec drift --snapshot --target ${targets[0]}  # Snapshot current state
-openuispec drift --all          # Include stubs in drift check
-\`\`\`
-
-## Targets and output directories
-
-This project generates native code for: **${targetList}**
-
-By default, drift stores state in \`generated/<target>/<project>/\`. To point targets to your actual code directories, add \`output_dir\` to \`openuispec.yaml\`:
-
-\`\`\`yaml
-generation:
-  targets: [ios, android, web]
-  output_dir:
-    web: "../web-ui/"
-    android: "../kmp-ui/"
-    ios: "../kmp-ui/iosApp/"
 \`\`\`
 
-Paths are relative to \`openuispec.yaml\`.
-
 ## Learn more
 
-All docs and examples are in the installed \`openuispec\` package — check \`node_modules/openuispec/\` or run \`npm root -g\` for the global install path.
-
-- Full spec: \`spec/openuispec-v0.1.md\`
-- Example app: \`examples/taskflow/\`
-- JSON Schemas: \`schema/\`
-- Online reference: \`https://openuispec.rsteam.uz/llms-full.txt\`
+Docs: https://openuispec.rsteam.uz
 `;
 }
 
@@ -292,26 +182,47 @@ function aiRulesBlock(specDir: string, targets: string[]): string {
 # Spec files are the single source of truth for all UI across platforms.
 # Targets: ${targetList}
 
+## IMPORTANT — Read the specification before working with spec files
+
+The spec format, file schemas, and generation rules are defined in the installed \`openuispec\` package.
+You MUST read the reference files listed below before creating, editing, or generating from any spec file.
+Do NOT guess the file format — skipping this step will produce invalid YAML that fails validation.
+
+**Find the package in this order:**
+1. \`node_modules/openuispec/\` (project dependency)
+2. Run \`npm root -g\` → \`<prefix>/openuispec/\` (global install)
+3. Online: \`https://openuispec.rsteam.uz/llms-full.txt\` (if not installed)
+
+**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, adaptive, etc.)
+3. \`examples/taskflow/\` — complete working example with all file types
+4. \`schema/\` — JSON Schemas for every file type
+
+These files are updated with each package version. Always read from the installed package,
+not from cached or memorized content, to ensure you use the latest spec.
+
 ## What is OpenUISpec
 OpenUISpec is a YAML-based spec format that describes an app's UI semantically — tokens, screens, flows, and platform overrides. AI reads the spec and generates native code (SwiftUI, Compose, React). AI reads native code and updates the spec. The spec is the sync layer between platforms.
 
 ## Spec location
 - Spec root: \`${specDir}/\`
 - Manifest: \`${specDir}/openuispec.yaml\` — always read this first.
-- Tokens: \`${specDir}/tokens/\` — colors, typography, spacing, motion, icons, themes
-- Screens: \`${specDir}/screens/\` — one YAML file per screen
-- Flows: \`${specDir}/flows/\` — multi-step navigation journeys
-- Contracts: \`${specDir}/contracts/\` — standard extensions (variants, tokens) and custom (\`x_\` prefixed)
-- Platform: \`${specDir}/platform/\` — per-target overrides (iOS, Android, Web)
-- Locales: \`${specDir}/locales/\` — i18n strings (JSON, ICU MessageFormat)
+- Tokens: \`${specDir}/tokens/\`
+- Screens: \`${specDir}/screens/\`
+- Flows: \`${specDir}/flows/\`
+- Contracts: \`${specDir}/contracts/\`
+- Platform: \`${specDir}/platform/\`
+- Locales: \`${specDir}/locales/\`
 
-**Note:** These are the default paths. Actual paths are in \`includes:\` in \`openuispec.yaml\` and may use relative paths (e.g. \`../../shared/locales\`). Always read \`openuispec.yaml\` to find the real directories.
+**Note:** These are the default paths. Actual paths are in \`includes:\` in \`openuispec.yaml\` and may use relative paths. Always read \`openuispec.yaml\` to find the real directories.
 
 ## If spec directories are empty (first-time setup)
 This means the project has existing UI code but hasn't been specced yet. Your job:
 
-1. **Find existing screens** — scan the codebase for UI screen files (SwiftUI views, Compose screens, React components/pages).
-2. **Create stubs** — for each screen, create \`${specDir}/screens/<name>.yaml\` with:
+1. **Read the spec first** — find and read \`spec/openuispec-v0.1.md\` from the installed package.
+2. **Find existing screens** — scan the codebase for UI screen files.
+3. **Create stubs** — for each screen, create \`${specDir}/screens/<name>.yaml\` with:
    \`\`\`yaml
    screen_name:
      semantic: "Brief description of what this screen does"
@@ -319,14 +230,8 @@ This means the project has existing UI code but hasn't been specced yet. Your jo
      layout:
        type: scroll_vertical
    \`\`\`
-3. **Extract tokens** — scan the codebase for colors, fonts, spacing values and create token files in \`${specDir}/tokens/\`.
-4. **Update the manifest** — fill in \`data_model\` and \`api.endpoints\` in \`${specDir}/openuispec.yaml\` based on the existing code.
-5. **Spec screens on demand** — when the user asks to spec a screen, read the native code, create a full spec, and change \`status: draft\` → \`ready\`.
-
-## Screen and flow status
-- \`stub\` — placeholder, not yet specced. Drift detection skips these.
-- \`draft\` — actively being specced. Tracked by drift.
-- \`ready\` — fully specified (default if omitted). Tracked by drift.
+4. **Extract tokens** — scan for colors, fonts, spacing and create files in \`${specDir}/tokens/\`.
+5. **Update the manifest** — fill in \`data_model\` and \`api.endpoints\` in \`${specDir}/openuispec.yaml\`.
 
 ## Making UI changes
 1. Read the relevant spec files before modifying any UI code.
@@ -340,74 +245,6 @@ This means the project has existing UI code but hasn't been specced yet. Your jo
 2. Run \`openuispec drift --snapshot --target <target>\` for each affected platform.
 3. Run \`openuispec drift\` to verify no untracked drift remains.
 
-## Learning OpenUISpec — where to find the docs
-All documentation is in the installed \`openuispec\` package. Search in this order:
-1. **Local:** \`node_modules/openuispec/\` (project dependency)
-2. **Global:** run \`npm root -g\` to get the global prefix, then look in \`<prefix>/openuispec/\`
-3. **Online fallback:** if not installed, fetch from:
-   - \`https://openuispec.rsteam.uz/llms-full.txt\` — complete spec + all JSON schemas
-   - \`https://openuispec.rsteam.uz/llms.txt\` — concise summary with links
-
-Inside the package:
-1. **Full specification:** \`spec/openuispec-v0.1.md\` — the complete spec (read this to understand the format)
-2. **Example app:** \`examples/taskflow/\` — a complete working app with all file types
-3. **JSON Schemas:** \`schema/\` — validation schemas that define the exact structure of every file type
-
-## Token file structure — root wrapper key required
-Every token file must have a single root key matching the token type. Do NOT put properties at the top level.
-- \`tokens/color.yaml\` → root key: \`color\`
-- \`tokens/typography.yaml\` → root key: \`typography\`
-- \`tokens/spacing.yaml\` → root key: \`spacing\`
-- \`tokens/elevation.yaml\` → root key: \`elevation\`
-- \`tokens/motion.yaml\` → root key: \`motion\`
-- \`tokens/layout.yaml\` → root key: \`layout\`
-- \`tokens/themes.yaml\` → root key: \`themes\`
-- \`tokens/icons.yaml\` → root key: \`icons\`
-
-## File formats and schemas — read before creating spec files
-Before creating or editing any spec file, read the corresponding JSON Schema. Do not guess the file format.
-
-| File | Schema (in \`schema/\` inside the installed package) | Root key |
-|------|--------|----------|
-| \`openuispec.yaml\` | \`openuispec.schema.json\` | \`spec_version\` |
-| \`screens/*.yaml\` | \`screen.schema.json\` | \`<screen_id>\` |
-| \`flows/*.yaml\` | \`flow.schema.json\` | \`<flow_id>\` |
-| \`platform/*.yaml\` | \`platform.schema.json\` | \`platform\` |
-| \`locales/*.json\` | \`locale.schema.json\` | (object) |
-| \`contracts/<name>.yaml\` | \`contract.schema.json\` | \`<contract_name>\` |
-| \`contracts/x_*.yaml\` | \`custom-contract.schema.json\` | \`<x_name>\` |
-| \`tokens/color.yaml\` | \`tokens/color.schema.json\` | \`color\` |
-| \`tokens/typography.yaml\` | \`tokens/typography.schema.json\` | \`typography\` |
-| \`tokens/spacing.yaml\` | \`tokens/spacing.schema.json\` | \`spacing\` |
-| \`tokens/elevation.yaml\` | \`tokens/elevation.schema.json\` | \`elevation\` |
-| \`tokens/motion.yaml\` | \`tokens/motion.schema.json\` | \`motion\` |
-| \`tokens/layout.yaml\` | \`tokens/layout.schema.json\` | \`layout\` |
-| \`tokens/themes.yaml\` | \`tokens/themes.schema.json\` | \`themes\` |
-| \`tokens/icons.yaml\` | \`tokens/icons.schema.json\` | \`icons\` |
-
-Shared type definitions (actions, data-binding, adaptive, validation, common) are in \`schema/defs/\`.
-
-Workflow: read the schema → read an example from \`examples/taskflow/\` → create the YAML → run \`openuispec validate\`.
-
-## Spec format reference
-- 7 contract families: nav_container, surface, action_trigger, input_field, data_display, collection, feedback
-- Custom contracts: prefixed with \`x_\` (e.g., \`x_media_player\`)
-- Data binding: \`$data:\`, \`$state:\`, \`$param:\`, \`$t:\` prefixes
-- Actions: typed objects (navigate, api_call, set_state, confirm, sequence, feedback, etc.)
-- Adaptive layout: size classes (compact, regular, expanded) with per-section overrides
-
-## Output directories
-Drift tracks spec changes per target. By default state is stored in \`generated/<target>/<project>/\`.
-To map targets to actual code directories, set \`generation.output_dir\` in \`openuispec.yaml\`:
-\`\`\`yaml
-generation:
-  output_dir:
-    web: "../web-ui/"
-    android: "../kmp-ui/"
-    ios: "../kmp-ui/iosApp/"
-\`\`\`
-Paths are relative to \`openuispec.yaml\`. The \`.openuispec-state.json\` file is stored inside each output directory.
-
 ## CLI commands
 - \`openuispec init\` — scaffold a new spec project
 - \`openuispec validate [group...]\` — validate spec files against schemas

package/docs/stress-test-maturity-report.md

@@ -0,0 +1,97 @@
+# OpenUISpec Stress Test & Maturity Assessment
+
+Date: 2026-03-14
+
+## Scope
+This assessment stress-tested the project at four layers:
+
+1. **Schema correctness pressure** across both reference specs (`taskflow`, `todo-orbit`).
+2. **Type safety and implementation consistency** in the TypeScript toolchain.
+3. **Change-tracking workflow resilience** using drift snapshot/check across all declared targets.
+4. **Generated output comparison** to verify functional parity across platform outputs without requiring pixel-perfect identity.
+
+## Commands executed
+
+```bash
+npm ci
+npm run validate                                # from examples/taskflow (workspace script)
+npx tsx ../../../schema/validate.ts            # from examples/todo-orbit/openuispec
+npx tsc --noEmit
+for t in ios android web; do
+  npx tsx ../../../drift/index.ts --snapshot --target "$t"
+  npx tsx ../../../drift/index.ts --target "$t"
+done
+python - <<'PY'
+from pathlib import Path
+roots={
+  'web':Path('examples/todo-orbit/generated/web/Todo Orbit/src'),
+  'ios':Path('examples/todo-orbit/generated/ios/Todo Orbit/Sources/TodoOrbit'),
+  'android':Path('examples/todo-orbit/generated/android/Todo Orbit/app/src/main/java/uz/rsteam/todoorbit')
+}
+for k,r in roots.items():
+  code=[p for p in r.rglob('*') if p.is_file() and p.suffix in ['.tsx','.ts','.swift','.kt','.css']]
+  loc=sum(sum(1 for _ in p.open('r',encoding='utf-8')) for p in code)
+  print(f"{k}: files={len(code)} loc={loc}")
+PY
+rg --files "examples/todo-orbit/artifacts/screenshots"
+```
+
+## Results summary
+
+- **Validation stress**: Passed for both example projects (all manifests, tokens, screens, flows, platform files, locales, and contracts).
+- **Compiler stress**: `tsc --noEmit` passed.
+- **Workflow stress (drift)**:
+  - Initial condition required snapshots (expected for first run).
+  - After snapshot creation, all three targets (`ios`, `android`, `web`) reported **0 changed / 0 added / 0 removed**.
+
+## Generated output comparison (functional parity, not pixel parity)
+
+The repository already frames Todo Orbit as a showcase with generated outputs for web, iOS, and Android. In this model, differences in structure/styling between generators or AI agents are expected.
+
+### Comparison policy used
+
+- **Do compare**: coverage of screens/flows/features, data model usage, localization support, and contract intent.
+- **Do not require**: identical widget trees, identical naming, exact spacing/typography values, or 1:1 rendered pixels.
+
+### Observed output differences (expected)
+
+- Web output is centralized in a small React surface (`src/App.tsx`, `src/main.tsx`, `src/styles.css`), while iOS/Android split into screen/component/flow files in platform-native patterns.
+- Code volume differs by target (`web: 3 files / 3013 LOC`, `ios: 11 files / 1516 LOC`, `android: 11 files / 1992 LOC`), which is normal because generated architecture choices vary by platform and template style.
+
+### Observed output alignment (good)
+
+- All targets include the same core feature set represented in spec: home/tasks, analytics, settings, task editor flow, and recurring-rule flow.
+- Localization assets exist for EN/RU in generated native outputs and in web runtime messages.
+- Reference screenshots exist for corresponding web and Android screens (`home`, `analytics`, `settings`), indicating practical parity at user-flow level rather than pixel-level equivalence.
+
+## Maturity score (0–5)
+
+- **Specification maturity: 4.0 / 5**
+  - Strong: clear schema decomposition, contract model, and examples.
+  - Gap: project still explicitly marked **v0.1 Draft**.
+
+- **Implementation maturity: 3.9 / 5**
+  - Strong: deterministic validators, lint-like contract usage checks, drift hashing, and multi-target generated examples.
+  - Gap: limited automated unit/integration test coverage in root scripts.
+
+- **Operational readiness: 3.7 / 5**
+  - Strong: practical CLI workflows for init/validate/drift and documented generated project layout.
+  - Gap: baseline onboarding friction for generated app dependency installation can be high in constrained environments.
+
+**Overall maturity estimate: 3.9 / 5 (promising, near early-production for spec tooling, with remaining work in generator conformance automation).**
+
+## What this says about idea–implementation fit
+
+- **Idea fit is high**: the repository architecture matches the thesis (“share semantic intent, generate native apps”).
+- **Implementation fit is good**: current tooling already enforces many promised invariants (schema + contract usage + drift).
+- **Cross-generator variance is acceptable**: output can differ by coding agent/LLM as long as contract behavior and user flows remain faithful to spec intent.
+- **Main risk is ecosystem hardening, not concept validity**: next maturity gains likely come from deeper automated tests, generator conformance tests, and CI reproducibility across generated targets.
+
+## Recommended next stress tests
+
+1. Add a `test` script with unit tests for validator edge-cases (especially custom contracts and malformed wrappers).
+2. Add golden-file conformance tests for drift output and schema error formatting.
+3. Add CI matrix that validates both examples + executes drift check for all targets.
+4. Add conformance checks that compare generated outputs on **feature parity** (screens, flows, actions, i18n keys), not snapshot pixel identity.
+5. Add “break tests” (intentionally invalid fixtures) to ensure failure messages stay actionable.
+6. Add benchmark scripts for validator runtime and drift checks on scaled synthetic specs.