openuispec 0.2.11 → 0.2.13

package/schema/openuispec.schema.json

@@ -38,22 +38,28 @@
       "description": "Paths to spec component directories",
       "properties": {
         "tokens": {
-          "type": "string"
+          "type": "string",
+          "description": "Visual design tokens — colors, typography, spacing, elevation, motion. Affects UI rendering only, not business logic."
         },
         "contracts": {
-          "type": "string"
+          "type": "string",
+          "description": "Reusable UI component definitions — buttons, inputs, lists, surfaces. Each contract specifies visual props, UI interaction states (pressed, disabled, loading), and accessibility. These are UI rendering specifications, not business logic or domain state machines."
         },
         "screens": {
-          "type": "string"
+          "type": "string",
+          "description": "Screen layouts composed from contracts — defines what UI components appear on each screen, their data bindings, and visual arrangement."
         },
         "flows": {
-          "type": "string"
+          "type": "string",
+          "description": "Multi-screen navigation journeys — defines screen sequences, transitions, and navigation triggers. UI navigation structure, not business workflow logic."
         },
         "platform": {
-          "type": "string"
+          "type": "string",
+          "description": "Per-target platform overrides — native UI behavior, framework-specific generation config. One file per target (ios.yaml, android.yaml, web.yaml)."
         },
         "locales": {
-          "type": "string"
+          "type": "string",
+          "description": "Localization string files — one JSON file per supported locale containing translated UI text."
         }
       },
       "required": [
@@ -152,6 +158,65 @@
             },
             "additionalProperties": true
           }
+        },
+        "shared": {
+          "type": "object",
+          "description": "Named shared code layers that span multiple targets (e.g. KMP common modules)",
+          "additionalProperties": {
+            "type": "object",
+            "properties": {
+              "platforms": {
+                "type": "array",
+                "items": { "type": "string" }
+              },
+              "language": {
+                "type": "string"
+              },
+              "root": {
+                "type": "string"
+              },
+              "paths": {
+                "type": "object",
+                "additionalProperties": { "type": "string" }
+              },
+              "tracks": {
+                "type": "array",
+                "description": "Spec categories this shared layer tracks for hash-based drift detection. Optional — when omitted, the layer relies on scope alone. Categories: manifest (project config, data models, API endpoints), tokens (visual design tokens — UI only), contracts (reusable UI component definitions — UI only, not business logic), screens (screen layouts — UI only), flows (navigation journeys — UI only), platform (per-target overrides — UI only), locales (translated UI strings).",
+                "items": {
+                  "type": "string",
+                  "enum": ["manifest", "tokens", "contracts", "screens", "flows", "platform", "locales"]
+                }
+              },
+              "scope": {
+                "type": "string",
+                "description": "What code belongs in this shared layer (e.g. 'Business logic, data models, repositories, API clients, view models. No UI rendering.')"
+              }
+            },
+            "required": ["platforms", "language", "root", "scope"],
+            "additionalProperties": false
+          }
+        },
+        "structure": {
+          "type": "object",
+          "description": "Per-target output directory structure (overrides heuristic code root discovery)",
+          "additionalProperties": {
+            "type": "object",
+            "properties": {
+              "root": {
+                "type": "string"
+              },
+              "paths": {
+                "type": "object",
+                "additionalProperties": { "type": "string" }
+              },
+              "scope": {
+                "type": "string",
+                "description": "What code belongs in this target directory (e.g. 'Pure SwiftUI views and navigation. All business logic comes from the shared layer.')"
+              }
+            },
+            "required": ["root"],
+            "additionalProperties": false
+          }
         }
       },
       "required": [

package/schema/semantic-lint.ts

@@ -5,6 +5,23 @@ import { listFiles, readManifest } from "../drift/index.js";
 
 type UnknownRecord = Record<string, unknown>;
 
+/** Collect all locale keys from a JSON object, supporting both flat dotted keys and nested objects. */
+function collectLocaleKeys(data: unknown, prefix = ""): string[] {
+  if (!data || typeof data !== "object" || Array.isArray(data)) return [];
+  const keys: string[] = [];
+  for (const [key, value] of Object.entries(data as UnknownRecord)) {
+    if (key.startsWith("$")) continue; // skip $locale, $direction
+    const fullKey = prefix ? `${prefix}.${key}` : key;
+    if (typeof value === "string") {
+      keys.push(fullKey);
+    } else if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+      // Nested object — recurse to flatten
+      keys.push(...collectLocaleKeys(value, fullKey));
+    }
+  }
+  return keys;
+}
+
 export interface Includes {
   tokens: string;
   contracts: string;
@@ -212,7 +229,14 @@ function buildContext(projectDir: string, includes: Includes, manifest: UnknownR
   for (const filePath of listFiles(localeDir, ".json")) {
     const localeName = basename(filePath, ".json");
     const data = loadJson(filePath);
-    localeFiles.set(localeName, new Set(Object.keys(data)));
+    // Support both flat dotted keys ("nav.home": "Home") and nested objects ({ nav: { home: "Home" } })
+    const flatKeys = Object.keys(data as object).filter(k => !k.startsWith("$"));
+    const hasNestedObjects = flatKeys.some(k => {
+      const v = (data as UnknownRecord)[k];
+      return typeof v === "object" && v !== null && !Array.isArray(v);
+    });
+    const allKeys = hasNestedObjects ? collectLocaleKeys(data) : flatKeys;
+    localeFiles.set(localeName, new Set(allKeys));
   }
 
   const formatterNames = new Set<string>([

package/spec/openuispec-v0.1.md

@@ -19,7 +19,7 @@ OpenUISpec is a shared UI sync language for native products, optimized for solo
 
 1. **Semantic over visual.** The spec defines behavioral intent, not pixel layouts. A "primary action trigger" maps to `Button` in SwiftUI, `Button` in Compose, and `<button>` in HTML — the spec never says "button."
 2. **Constrained freedom.** Tokens use ranges, not exact values. Close enough to be recognizably the same brand; loose enough for each platform to feel native.
-3. **Contract-driven.** Every component is a behavioral contract with typed props, a state machine, and accessibility requirements. If a state exists in the spec, the generated code must handle it.
+3. **Contract-driven.** Every UI component is a reusable contract with typed props, UI interaction states (pressed, disabled, loading, error — not business logic states), and accessibility requirements. If a UI state exists in the spec, the generated code must handle it.
 4. **AI-first authoring.** The spec is structured for machine consumption: strongly typed, validatable, with generation hints that tell AI what it must, should, and may produce.
 5. **Platform respect.** iOS should feel like iOS. Android should feel like Android. Web should feel like the web. The spec preserves platform identity; it does not erase it.
 
@@ -90,6 +90,19 @@ generation:
     ios: { language: swift, framework: swiftui }
     android: { language: kotlin, framework: compose }
     web: { language: typescript, framework: react }
+  # shared:                          # optional: cross-platform shared code layers
+  #   mobile_common:
+  #     platforms: [ios, android]
+  #     language: kotlin
+  #     root: "../shared"
+  #     scope: "Business logic, data models, repositories, view models. No UI."
+  #     paths:
+  #       domain: "commonMain/domain/"
+  # structure:                       # optional: per-target directory structure (overrides heuristics)
+  #   ios:
+  #     root: "../shared"
+  #     scope: "Pure SwiftUI views and navigation."
+  #     paths: { ui: "iosApp/ui/" }
 ```
 
 ---
@@ -542,7 +555,7 @@ The `custom` section follows the same shape as `registry` categories. App-specif
 
 ## 4. Component contracts
 
-Each contract defines a **behavioral family** — a category of UI elements that share the same role, props shape, state machine, and accessibility pattern. The AI maps each contract to the most appropriate native widget per platform.
+Each contract defines a **reusable UI component family** — a category of UI elements that share the same role, props shape, UI interaction states, and accessibility pattern. The AI maps each contract to the most appropriate native widget per platform. Contracts describe how components look and respond to user interaction — they are UI rendering specifications, not business logic or domain state machines.
 
 ### Contract anatomy
 
@@ -552,7 +565,7 @@ Every contract contains:
 |---------|---------|----------|
 | `semantic` | Human-readable description of what this family does | Yes |
 | `props` | Typed inputs the component accepts | Yes |
-| `states` | Finite state machine with valid transitions | Yes |
+| `states` | UI interaction states (e.g. idle, pressed, disabled, loading, error) with valid transitions | Yes |
 | `a11y` | Accessibility role, label pattern, focus behavior | Yes |
 | `tokens` | Visual token bindings per variant | Yes |
 | `platform_mapping` | Default native widget per platform | Yes |
@@ -1752,7 +1765,7 @@ When omitted, the item contract's default variant is used.
 
 #### `state_binding`
 
-Binds a contract's state machine states to data paths. This allows screen-level data to drive contract states declaratively, without requiring an explicit action.
+Binds a contract's UI interaction states to data paths. This allows screen-level data to drive contract states declaratively, without requiring an explicit action.
 
 ```yaml
 - contract: action_trigger
@@ -1770,7 +1783,7 @@ Binds a contract's state machine states to data paths. This allows screen-level
 - Values must be data paths that resolve to `bool`
 - When the bound value is `true`, the contract transitions to that state
 - When the bound value returns to `false`, the contract transitions back to `default`
-- If multiple state bindings are `true` simultaneously, priority follows the contract's state machine (e.g., `loading` takes precedence over `disabled`)
+- If multiple state bindings are `true` simultaneously, priority follows the contract's state priority order (e.g., `loading` takes precedence over `disabled`)
 
 ---
 
@@ -2953,7 +2966,7 @@ props:
 condition: "tasks.$empty"
 ```
 
-Collection contracts handle `$loading`, `$error`, and `$empty` automatically via their state machines (see Section 4.7). For non-collection data, screens can use `condition:` to show appropriate UI.
+Collection contracts handle `$loading`, `$error`, and `$empty` automatically via their built-in UI states (see Section 4.7). For non-collection data, screens can use `condition:` to show appropriate UI.
 
 ### 10.9 AI generation requirements
 
@@ -3148,7 +3161,7 @@ Custom contracts allow spec authors to define domain-specific component families
 Use a custom contract when the component:
 
 - Has domain-specific behavior that doesn't map cleanly to any built-in family
-- Requires a dedicated state machine (e.g., play/pause/seek for media)
+- Requires dedicated UI interaction states (e.g., play/pause/seek for media)
 - Needs platform-specific libraries or frameworks not covered by core contracts
 - Would clutter the core spec if included as a built-in
 
@@ -3314,7 +3327,7 @@ ios:
 
 **MUST:**
 - Read and parse all registered custom contract definitions before generating code
-- Handle every declared state in the state machine
+- Handle every declared UI interaction state
 - Apply `platform_mapping` to select the correct native component
 - Include all `dependencies` in the generated project configuration (Package.swift, build.gradle, package.json)
 - Implement all items listed in `generation.must_handle`
@@ -3809,7 +3822,7 @@ A drift detector compares:
 - **Spec → Code**: Does the generated code match what the spec describes? (e.g., a button's action type, a screen's data sources, a flow's step order)
 - **Code → Spec**: Does the current platform code contain UI decisions not reflected in the spec? (e.g., a new field added to a form, a navigation path changed)
 
-Drift detection is scoped to the semantic layer — it compares behavioral intent (contracts, props, state machines, data bindings), not visual details (padding values, animation curves). Platform-specific polish is expected to diverge from the spec; behavioral contracts are not.
+Drift detection is scoped to the semantic layer — it compares behavioral intent (contracts, props, UI interaction states, data bindings), not visual details (padding values, animation curves). Platform-specific polish is expected to diverge from the spec; behavioral contracts are not.
 
 Resolution strategies:
 - **Update spec** — The code change is intentional; update the spec to match

package/status/index.ts

@@ -10,14 +10,19 @@
 import { existsSync } from "node:fs";
 import {
   computeDrift,
+  computeSharedDrift,
   discoverTargets,
   explainDrift,
   findProjectDir,
   formatBaseline,
+  hasDriftChanges,
   readOutputDirs,
   readProjectName,
+  readSharedLayers,
+  readSharedLayerState,
   resolveOutputDir,
   stateFilePath,
+  type SharedLayerConfig,
   type StateFile,
 } from "../drift/index.js";
 
@@ -45,9 +50,21 @@ interface TargetStatus {
   note?: string;
 }
 
+interface SharedLayerStatus {
+  name: string;
+  platforms: string[];
+  root: string;
+  snapshot: boolean;
+  snapshot_at: string | null;
+  generated_by_target: string | null;
+  has_drift: boolean;
+  status: "up to date" | "behind" | "needs generation";
+}
+
 export interface StatusResult {
   project: string;
   targets: TargetStatus[];
+  shared_layers?: SharedLayerStatus[];
 }
 
 function configuredTargets(projectDir: string): string[] {
@@ -141,6 +158,38 @@ function buildTargetStatus(cwd: string, projectDir: string, projectName: string,
   };
 }
 
+function buildSharedLayerStatus(projectDir: string, layer: SharedLayerConfig): SharedLayerStatus {
+  const state = readSharedLayerState(layer);
+  if (!state) {
+    return {
+      name: layer.name,
+      platforms: layer.platforms,
+      root: layer.root,
+      snapshot: false,
+      snapshot_at: null,
+      generated_by_target: null,
+      has_drift: false,
+      status: "needs generation",
+    };
+  }
+
+  let hasDrift = false;
+  if (layer.tracks.length > 0) {
+    hasDrift = hasDriftChanges(computeSharedDrift(projectDir, layer).drift);
+  }
+
+  return {
+    name: layer.name,
+    platforms: layer.platforms,
+    root: layer.root,
+    snapshot: true,
+    snapshot_at: state.snapshot_at,
+    generated_by_target: state.generated_by_target,
+    has_drift: hasDrift,
+    status: hasDrift ? "behind" : "up to date",
+  };
+}
+
 export function buildStatusResult(cwd: string = process.cwd()): StatusResult {
   const projectDir = findProjectDir(cwd);
   const projectName = readProjectName(projectDir);
@@ -148,9 +197,15 @@ export function buildStatusResult(cwd: string = process.cwd()): StatusResult {
     buildTargetStatus(cwd, projectDir, projectName, target)
   );
 
+  const sharedLayers = readSharedLayers(projectDir);
+  const sharedLayerStatuses = sharedLayers.length > 0
+    ? sharedLayers.map((layer) => buildSharedLayerStatus(projectDir, layer))
+    : undefined;
+
   return {
     project: projectName,
     targets,
+    ...(sharedLayerStatuses ? { shared_layers: sharedLayerStatuses } : {}),
   };
 }
 
@@ -182,6 +237,21 @@ function printReport(result: StatusResult): void {
     console.log(`  next: ${target.recommended_next_step}`);
     console.log("");
   }
+
+  if (result.shared_layers && result.shared_layers.length > 0) {
+    console.log("Shared Layers");
+    console.log("─────────────");
+    for (const layer of result.shared_layers) {
+      console.log(`${layer.name} (${layer.platforms.join(", ")})`);
+      console.log(`  root: ${layer.root}`);
+      console.log(`  snapshot: ${layer.snapshot ? layer.snapshot_at : "missing"}`);
+      if (layer.generated_by_target) {
+        console.log(`  generated by: ${layer.generated_by_target}`);
+      }
+      console.log(`  status: ${layer.status}`);
+      console.log("");
+    }
+  }
 }
 
 export function runStatus(argv: string[]): void {