openuispec 0.1.19 → 0.1.21

package/README.md

@@ -96,7 +96,7 @@ openuispec/
 │   │   └── icons.schema.json          # Icon token schema
 │   ├── defs/
 │   │   ├── common.schema.json          # Shared types (icons, badges, etc.)
-│   │   ├── action.schema.json          # 13 action types (discriminated union)
+│   │   ├── action.schema.json          # 14 action types (discriminated union)
 │   │   ├── data-binding.schema.json    # Data sources, state, params
 │   │   ├── adaptive.schema.json        # Adaptive override pattern
 │   │   └── validation.schema.json     # Validation rule definitions
@@ -210,7 +210,7 @@ Paths are relative to `openuispec.yaml`. The `.openuispec-state.json` file is st
 | 6. Navigation flows | Multi-screen journeys with transitions and progress |
 | 7. Platform adaptation | Per-target overrides for iOS, Android, Web |
 | 8. AI generation contract | Compliance levels (MUST/SHOULD/MAY), validation, drift detection |
-| 9. Action system | 13 action types, composition, optimistic updates |
+| 9. Action system | 14 action types, composition, optimistic updates |
 | 10. Data binding & state | Sources, paths, format expressions, reactivity, caching |
 | 11. Internationalization | Locale files, `$t:` references, ICU MessageFormat, RTL, platform mapping |
 | 12. Custom contract extensions | `x_` prefixed domain-specific contracts, registration, dependencies |

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/examples/todo-orbit/CLAUDE.md

@@ -4,26 +4,47 @@
 # Spec files are the single source of truth for all UI across platforms.
 # Targets: "ios", "android", "web"
 
+## 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: `openuispec/`
 - Manifest: `openuispec/openuispec.yaml` — always read this first.
-- Tokens: `openuispec/tokens/` — colors, typography, spacing, motion, icons, themes
-- Screens: `openuispec/screens/` — one YAML file per screen
-- Flows: `openuispec/flows/` — multi-step navigation journeys
-- Contracts: `openuispec/contracts/` — UI component definitions
-- Platform: `openuispec/platform/` — per-target overrides (iOS, Android, Web)
-- Locales: `openuispec/locales/` — i18n strings (JSON, ICU MessageFormat)
+- Tokens: `openuispec/tokens/`
+- Screens: `openuispec/screens/`
+- Flows: `openuispec/flows/`
+- Contracts: `openuispec/contracts/`
+- Platform: `openuispec/platform/`
+- Locales: `openuispec/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 `openuispec/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 `openuispec/screens/<name>.yaml` with:
    ```yaml
    screen_name:
      semantic: "Brief description of what this screen does"
@@ -31,14 +52,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 `openuispec/tokens/`.
-4. **Update the manifest** — fill in `data_model` and `api.endpoints` in `openuispec/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 `openuispec/tokens/`.
+5. **Update the manifest** — fill in `data_model` and `api.endpoints` in `openuispec/openuispec.yaml`.
 
 ## Making UI changes
 1. Read the relevant spec files before modifying any UI code.
@@ -52,73 +67,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/x_*.yaml` | `custom-contract.schema.json` | `contract` |
-| `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/examples/todo-orbit/openuispec/screens/analytics.yaml

@@ -1,5 +1,6 @@
 analytics:
   semantic: "Analytics dashboard for productivity trends, weekly completion, and overdue task review"
+  title: "$t:nav.analytics"
   status: ready
 
   data:

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

@@ -1,5 +1,6 @@
 home:
   semantic: "Main todo list with search, filters, completion toggles, and a quick-create action"
+  title: "$t:nav.tasks"
   status: ready
 
   data:

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

@@ -1,5 +1,6 @@
 settings:
   semantic: "Preferences screen for application language and theme"
+  title: "$t:nav.settings"
   status: ready
 
   data:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openuispec",
-  "version": "0.1.19",
+  "version": "0.1.21",
   "license": "MIT",
   "type": "module",
   "description": "A semantic UI specification format for AI-native, platform-native app development",

package/schema/defs/action.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://openuispec.org/schema/defs/action.schema.json",
   "title": "OpenUISpec Action",
-  "description": "Discriminated union of the 13 action types in OpenUISpec",
+  "description": "Discriminated union of the 14 action types in OpenUISpec",
 
   "type": "object",
   "required": ["type"],

package/schema/screen.schema.json

@@ -17,6 +17,10 @@
         "semantic": {
           "type": "string"
         },
+        "title": {
+          "type": "string",
+          "description": "Optional screen title for navigation bars and headers. When omitted, inferred from the first data_display title in the layout or the nav item label."
+        },
         "status": {
           "type": "string",
           "enum": [
@@ -182,6 +186,11 @@
         "input_type": {
           "type": "string"
         },
+        "render_hint": {
+          "type": "string",
+          "enum": ["dropdown", "segmented", "radio_group", "bottom_sheet"],
+          "description": "Optional hint for how an input_field with input_type select should render. When omitted, the platform default is used (e.g., Picker on iOS, ExposedDropdownMenuBox on Android, select on Web)."
+        },
         "size": {
           "type": "string"
         },

package/spec/openuispec-v0.1.md

@@ -835,6 +835,12 @@ input_field:
     suffix: { type: string, required: false }
     icon: { type: icon_ref, required: false, position: [leading, trailing] }
     clearable: { type: bool, default: false }
+    render_hint:
+      type: enum
+      values: [dropdown, segmented, radio_group, bottom_sheet]
+      required: false
+      condition: "input_type == select"
+      description: "Overrides the default platform widget for select fields. When omitted, the platform default is used."
 
   states:
     empty:
@@ -909,6 +915,7 @@ input_field:
       text: { widget: "TextField" }
       multiline: { widget: "TextEditor" }
       select: { widget: "Picker" }
+      select[segmented]: { widget: "Picker(style: .segmented)" }
       toggle: { widget: "Toggle" }
       slider: { widget: "Slider" }
       date: { widget: "DatePicker" }
@@ -916,6 +923,7 @@ input_field:
       text: { composable: "OutlinedTextField" }
       multiline: { composable: "OutlinedTextField(singleLine=false)" }
       select: { composable: "ExposedDropdownMenuBox" }
+      select[segmented]: { composable: "SegmentedButton / SingleChoiceSegmentedButtonRow" }
       toggle: { composable: "Switch" }
       slider: { composable: "Slider" }
       date: { composable: "DatePicker" }
@@ -923,6 +931,7 @@ input_field:
       text: { element: "input", type: "text" }
       multiline: { element: "textarea" }
       select: { element: "select" }
+      select[segmented]: { element: "fieldset > input[type=radio]", styled: "segmented control" }
       toggle: { element: "input", type: "checkbox", role: "switch" }
       slider: { element: "input", type: "range" }
       date: { element: "input", type: "date" }
@@ -1484,7 +1493,8 @@ Screens compose contracts into layouts. A screen never references platform widge
 # Example: screens/order_detail.yaml
 order_detail:
   semantic: "Displays detailed information about a single order"
-  
+  title: "$t:order_detail.title"   # Optional — shown in nav bar / browser tab
+
   params:
     order_id: { type: string, required: true }
   
@@ -1561,7 +1571,19 @@ order_detail:
 
 ### 5.1 Screen-level keys
 
-Beyond contract props and layout primitives, screen files use several keys that modify how sections and contract instances behave. These keys are available on any section or contract instance within a screen's `sections:` array.
+Screen definitions support the following top-level keys alongside `semantic`, `layout`, `data`, `state`, `params`, `navigation`, and `surfaces`:
+
+#### `title`
+
+Optional display title for the screen, shown in navigation bars, browser tabs, and back-button labels. When omitted, generators should infer the title from the first `data_display` title in the layout, or from the corresponding `nav_container` item label.
+
+```yaml
+settings:
+  semantic: "Preferences screen for language and theme"
+  title: "$t:settings.title"   # "Preferences"
+```
+
+Beyond these, screen files use several keys that modify how sections and contract instances behave. These keys are available on any section or contract instance within a screen's `sections:` array.
 
 #### `tokens_override`
 
@@ -2648,8 +2670,9 @@ Format expressions transform values for display. They appear inside `{}` delimit
 ```
 interpolation  := '{' (piped_expr | computed_expr) '}'
 piped_expr     := data_path ('|' pipe)*
-pipe           := operation ':' argument
+pipe           := operation ':' argument ('.' option)?
 operation      := 'format' | 'map' | 'default'
+option         := identifier   # e.g., abbreviated, narrow
 computed_expr  := data_path comparator value '?' literal ':' literal
 comparator     := '==' | '!=' | '>' | '<' | '>=' | '<='
 locale_ref     := '$t:' locale_key
@@ -2705,18 +2728,18 @@ subtitle: "{item.quantity} × {item.unit_price | format:currency}"
 
 **Built-in formatters:**
 
-| Formatter | Input | Output | Locale-aware |
-|-----------|-------|--------|-------------|
-| `currency` | number | "$1,234.56" | Yes |
-| `date` | date/datetime | "Mar 13, 2026" | Yes |
-| `date_relative` | date/datetime | "2 hours ago", "yesterday" | Yes |
-| `date_short` | date/datetime | "Mar 13" | Yes |
-| `time` | datetime | "3:45 PM" | Yes |
-| `number` | number | "1,234" | Yes |
-| `percentage` | number (0-1) | "45%" | No |
-| `status_label` | enum string | "In Progress" (title case) | No |
-| `pluralize` | number | "1 task" / "3 tasks" | Yes |
-| `file_size` | number (bytes) | "2.4 MB" | No |
+| Formatter | Input | Output | Locale-aware | Options |
+|-----------|-------|--------|-------------|---------|
+| `currency` | number | "$1,234.56" | Yes | — |
+| `date` | date/datetime | "Mar 13, 2026" | Yes | — |
+| `date_relative` | date/datetime | "2 hours ago", "yesterday" | Yes | `style`: full (default), abbreviated, narrow |
+| `date_short` | date/datetime | "Mar 13" | Yes | — |
+| `time` | datetime | "3:45 PM" | Yes | — |
+| `number` | number | "1,234" | Yes | — |
+| `percentage` | number (0-1) | "45%" | No | — |
+| `status_label` | enum string | "In Progress" (title case) | No | — |
+| `pluralize` | number | "1 task" / "3 tasks" | Yes | — |
+| `file_size` | number (bytes) | "2.4 MB" | No | — |
 
 **Built-in mappers:**
 
@@ -2726,6 +2749,21 @@ subtitle: "{item.quantity} × {item.unit_price | format:currency}"
 | `priority_to_severity` | priority enum → severity enum (e.g., "urgent" → "error") |
 | `bool_to_label` | true/false → "Yes"/"No" (or custom mapping) |
 
+**Formatter options** — some built-in formatters accept an `options` parameter, passed with a dot suffix:
+
+```yaml
+# Default style (full): "in 2 days", "3 hours ago"
+subtitle: "{task.due_date | format:date_relative}"
+
+# Abbreviated: "in 2d", "3h ago"
+subtitle: "{task.due_date | format:date_relative.abbreviated}"
+
+# Narrow: "2d", "3h"
+subtitle: "{task.due_date | format:date_relative.narrow}"
+```
+
+When no option is provided, the default style is used. Generators must respect the option across all platforms to ensure consistent output.
+
 **Custom formatters and mappers** can be defined in the project manifest:
 
 ```yaml