openuispec 0.2.10 → 0.2.11

package/README.md

@@ -74,7 +74,7 @@ OpenUISpec includes an **MCP server** that AI assistants call automatically duri
 openuispec init → configures MCP for your agent → AI calls tools automatically
 ```
 
-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, and returns a concrete audit checklist after generation.
+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).
 
@@ -90,6 +90,8 @@ When you ask your AI to "add a settings page" or "update the home feed," the MCP
 | [Todo Orbit](./examples/todo-orbit/openuispec/) | iOS, Android, Web | Bilingual task app with localization, custom contracts |
 | [Social App](./examples/social-app/openuispec/) | Android, Web | Trilingual social app with feeds, messaging, profiles |
 
+Screenshots of the generated apps are in the [artifacts](./artifacts/) directory.
+
 ## Documentation
 
 | Doc | What's in it |

package/cli/index.ts

@@ -332,6 +332,7 @@ async function main(): Promise<void> {
           width: parseInt(getOption(rest, "--width") ?? "1280"),
           height: parseInt(getOption(rest, "--height") ?? "800"),
         },
+        scale: parseFloat(getOption(rest, "--scale") ?? "2"),
         theme: getOption(rest, "--theme") as "light" | "dark" | undefined,
         wait_for: parseInt(getOption(rest, "--wait-for") ?? "1000"),
         full_page: getFlag(rest, "--full-page"),
@@ -382,6 +383,7 @@ async function main(): Promise<void> {
       const result = await takeScreenshotBatch(cwd, {
         captures,
         viewport: config.viewport,
+        scale: parseFloat(getOption(rest, "--scale") ?? config.scale ?? "2"),
         theme: (getOption(rest, "--theme") ?? config.theme) as "light" | "dark" | undefined,
         output_dir: getOption(rest, "--output-dir") ?? config.output_dir ?? undefined,
       });
@@ -459,14 +461,14 @@ Spec access:
   openuispec spec-schema <type>             Get full JSON schema for a spec type
 
 Screenshots (single):
-  openuispec screenshot [--route /path] [--theme light|dark] [--output-dir dir]
+  openuispec screenshot [--route /path] [--width px] [--height px] [--scale n] [--theme light|dark] [--output-dir dir]
   openuispec screenshot-android [--screen name] [--project-dir path] [--module name]
       [--route deeplink] [--nav Step1,Step2] [--theme light|dark] [--output-dir dir]
   openuispec screenshot-ios [--screen name] [--project-dir path] [--scheme name]
       [--bundle-id id] [--device name] [--nav Step1,Step2] [--theme light|dark]
 
 Screenshots (batch — build once, capture many):
-  openuispec screenshot-web-batch --config captures.json [--theme light|dark] [--output-dir dir]
+  openuispec screenshot-web-batch --config captures.json [--scale n] [--theme light|dark] [--output-dir dir]
   openuispec screenshot-android-batch --config captures.json [--project-dir path]
       [--module name] [--theme light|dark] [--output-dir dir]
   openuispec screenshot-ios-batch --config captures.json [--project-dir path]

package/cli/init.ts

@@ -348,21 +348,35 @@ Call these MCP tools directly. They return structured JSON with everything you n
 
 **Pre-generation:**
 1. Call \`openuispec_prepare\` with the target platform — returns spec context, platform config, constraints.
-2. Call \`openuispec_read_specs\` to load spec file contents. Use these as the AUTHORITATIVE source.
+   Use \`include_specs: true\` to embed all spec contents in one call (saves a separate read_specs).
+2. Call \`openuispec_read_specs\` to load spec file contents if not using include_specs.
+   Without paths: returns file listing. With paths: returns contents. Use these as the AUTHORITATIVE source.
 3. If spec changes are needed, update spec files FIRST, then call \`openuispec_check\`.
 4. Generate or update the platform UI code based on the spec contents.
 
 **Post-generation (EVERY TIME after writing UI code):**
-5. Call \`openuispec_check\` to validate spec integrity.
-6. Call \`openuispec_read_specs\` for the screens/contracts you just generated code for.
-7. Audit your generated code against the spec. For each screen, verify:
+5. Call \`openuispec_check\` to validate spec files (schema + semantics) and confirm prepare readiness.
+   Note: this validates the SPEC, not the generated code.
+6. Call \`openuispec_check\` with \`audit: true\` to get a spec-derived checklist, then manually review
+   the generated code against it. For each screen, verify:
    - Every field/action in the spec has a corresponding UI element
    - Token values (colors, spacing, radii) match exactly — no approximations
    - Contract \`must_handle\` states are all implemented (loading, error, empty, etc.)
    - Adaptive breakpoints match the spec's \`size_classes\`
    - Locale keys match \`$t:\` references
    - Navigation targets match flow definitions
-8. Report any real gaps found and fix them before finishing.
+7. Report any real gaps found and fix them before finishing.
+
+**Iterating before baseline:**
+Generated code rarely needs just one pass. Read the spec, audit the generated code against it,
+take screenshots to verify visuals, then fix gaps and repeat.
+Multiple generate → review → fix cycles are expected before the user accepts the result.
+
+**Baseline reminder:**
+After generation, remind the user to review the output and run the baseline when satisfied:
+> When you're happy with the generated output, run: \`openuispec drift --snapshot --target <t>\`
+> This records the spec state so future changes are tracked as incremental drift.
+Do not baseline on your own initiative — only run the snapshot when the user asks.
 
 **Creating new spec files:**
 - Call \`openuispec_spec_types\` to discover available spec types.
@@ -374,7 +388,7 @@ Call these MCP tools directly. They return structured JSON with everything you n
 - \`openuispec_get_contract(name, variant?)\` — single contract, 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, screens?, contracts?)\` — scoped audit for specific screens/contracts
+- \`openuispec_check(target, audit?, screens?, contracts?)\` — validation + optional scoped audit checklist
 
 Use \`read_specs\` for full-project generation; use focused getters when editing one screen or contract.
 
@@ -404,7 +418,7 @@ If MCP tools are not available, use these CLI commands with \`--json\` flag:
 
 ### Other CLI commands
 - \`openuispec init\` — scaffold a new spec project
-- \`openuispec drift --snapshot --target <t>\` — snapshot current state (only after UI code is updated)
+- \`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
 
@@ -448,7 +462,8 @@ Read \`spec/openuispec-v0.1.md\` from the package first, then:
 5. Fill in \`data_model\`, \`api.endpoints\` in \`${specDir}/openuispec.yaml\`
 
 ## Rules
-- Do not snapshot drift unless the UI code has also been updated.
+- Do not baseline on your own initiative — the user decides when generated output is accepted.
+- After generation, always remind the user to review and baseline: \`openuispec drift --snapshot --target <t>\`.
 - Do not modify generated UI without checking whether the spec must change first.
 - Do not use \`configure-target --defaults\` as silent approval — ask the user to confirm.
 - Always read spec format from the installed package, not from cached/memorized content.

package/docs/cli.md

@@ -41,12 +41,12 @@ Or run directly: `openuispec mcp`
 | 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 the full JSON schema for a specific spec type |
-| `openuispec_prepare` | Before UI code generation | Returns spec context, platform config, generation constraints |
-| `openuispec_read_specs` | Before and after generation | Loads spec file contents — the authoritative source |
-| `openuispec_check` | After generation | Schema validation + concrete audit checklist. Optional `screens`/`contracts` params scope the audit |
+| `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 | Detect spec drift since last snapshot, with semantic explanation |
+| `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 |
@@ -55,6 +55,9 @@ Or run directly: `openuispec mcp`
 | `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 |
 
 The server includes **protocol-level instructions** that trigger on UI-related requests independently of CLAUDE.md rules.
 
@@ -93,12 +96,12 @@ openuispec spec-schema <type>                 # Get JSON schema for a spec type
 
 ```bash
 # Single captures
-openuispec screenshot --route /home [--theme dark] [--output-dir dir]
+openuispec screenshot --route /home [--width 1280] [--height 800] [--scale 2] [--theme dark] [--output-dir dir]
 openuispec screenshot-android [--project-dir path] [--screen name] [--module name] [--route deeplink]
 openuispec screenshot-ios [--project-dir path] [--screen name] [--scheme name] [--bundle-id id]
 
 # Batch — build once, capture many
-openuispec screenshot-web-batch --config captures.json [--theme dark] [--output-dir dir]
+openuispec screenshot-web-batch --config captures.json [--scale 2] [--theme dark] [--output-dir dir]
 openuispec screenshot-android-batch --config captures.json [--project-dir path] [--module name]
 openuispec screenshot-ios-batch --config captures.json [--project-dir path] [--scheme name] [--bundle-id id]
 ```
@@ -113,6 +116,7 @@ Screenshot tools work with **any** project — use `--project-dir` to skip manif
 | `--bundle-id` | -- | yes | Override bundle ID (default: auto-detect) |
 | `--route` | yes | -- | Deep link URI for navigation |
 | `--nav` | yes | yes | UI tap steps, comma-separated |
+| `--scale` | web | -- | Device pixel ratio for sharper screenshots (default: 2) |
 | `--theme` | yes | yes | Force light or dark mode |
 | `--device` | -- | yes | Simulator device name |
 | `--output-dir` | yes | yes | Save screenshot to directory |
@@ -125,6 +129,7 @@ All batch commands accept `--config captures.json`. The JSON file has the same s
 {
   "project_dir": "path/to/project",
   "output_dir": "screenshots",
+  "scale": 2,
   "theme": "light",
   "captures": [
     { "screen": "home", "route": "/home", "wait_for": 3000 },
@@ -156,5 +161,5 @@ openuispec drift --snapshot --target ios
 ```
 
 - `prepare` runs in `bootstrap` mode for first-time generation and `update` mode after a snapshot exists
-- `drift --snapshot` is bookkeeping — it does not prove code matches the spec, and requires the output directory to exist
+- `drift --snapshot` is bookkeeping — it does not prove code matches the spec, and requires the output directory to exist. Only run it after reviewing the generated output.
 - Run `openuispec status` between targets to see what still needs updating

package/drift/index.ts

@@ -538,19 +538,28 @@ function normalizeEntry(value: string | FileEntry): FileEntry {
 
 // ── snapshot ──────────────────────────────────────────────────────────
 
-function snapshot(cwd: string, projectDir: string, target: string): void {
+export interface SnapshotResult {
+  target: string;
+  snapshot_at: string;
+  files_hashed: number;
+  stubs: number;
+  state_path: string;
+  baseline: string | null;
+}
+
+export function createSnapshot(cwd: string, target: string): SnapshotResult {
+  const projectDir = findProjectDir(cwd);
   const projectName = readProjectName(projectDir);
   const outDir = resolveOutputDir(projectDir, projectName, target);
   if (!existsSync(outDir)) {
-    console.error(
-      `Error: Output directory not found: ${relative(cwd, outDir)}\n` +
+    throw new Error(
+      `Output directory not found: ${relative(cwd, outDir)}\n` +
         `Run code generation for "${target}" first.`
     );
-    process.exit(1);
   }
 
+  const manifest = readManifest(projectDir);
   const files = discoverSpecFiles(projectDir);
-  const doc = YAML.parse(readFileSync(join(projectDir, "openuispec.yaml"), "utf-8"));
   const baseline = captureBaseline(projectDir, files);
 
   const entries: Record<string, FileEntry> = {};
@@ -564,7 +573,7 @@ function snapshot(cwd: string, projectDir: string, target: string): void {
   }
 
   const state: StateFile = {
-    spec_version: doc.spec_version ?? "0.1",
+    spec_version: manifest.spec_version ?? "0.1",
     snapshot_at: new Date().toISOString(),
     target,
     baseline,
@@ -573,15 +582,32 @@ function snapshot(cwd: string, projectDir: string, target: string): void {
 
   const outPath = stateFilePath(projectDir, projectName, target);
   writeFileSync(outPath, JSON.stringify(state, null, 2) + "\n");
-  console.log(`Snapshot saved: ${relative(cwd, outPath)}`);
-  console.log(`  ${Object.keys(entries).length} files hashed`);
-  if (stubCount > 0) {
-    console.log(`  ${stubCount} stubs (not tracked for drift)`);
-  }
-  console.log(`  target: ${target}`);
-  const baselineLabel = formatBaseline(baseline);
-  if (baselineLabel) {
-    console.log(`  baseline: ${baselineLabel}`);
+
+  return {
+    target,
+    snapshot_at: state.snapshot_at,
+    files_hashed: Object.keys(entries).length,
+    stubs: stubCount,
+    state_path: relative(cwd, outPath),
+    baseline: formatBaseline(baseline),
+  };
+}
+
+function snapshot(cwd: string, projectDir: string, target: string): void {
+  try {
+    const result = createSnapshot(cwd, target);
+    console.log(`Snapshot saved: ${result.state_path}`);
+    console.log(`  ${result.files_hashed} files hashed`);
+    if (result.stubs > 0) {
+      console.log(`  ${result.stubs} stubs (not tracked for drift)`);
+    }
+    console.log(`  target: ${result.target}`);
+    if (result.baseline) {
+      console.log(`  baseline: ${result.baseline}`);
+    }
+  } catch (err) {
+    console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
+    process.exit(1);
   }
 }