openuispec 0.2.10 → 0.2.12

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/check/index.ts

@@ -14,10 +14,13 @@ import { existsSync, readFileSync } from "node:fs";
 import { join, resolve } from "node:path";
 import YAML from "yaml";
 import {
+  computeSharedDrift,
   findProjectDir,
+  hasDriftChanges,
   readManifest,
   readProjectName,
   resolveOutputDir,
+  sharedLayersForTarget,
 } from "../drift/index.js";
 import {
   buildAjv,
@@ -153,6 +156,20 @@ function determinePrepare(
     );
   }
 
+  // Check for shared layer drift (only when tracks are configured)
+  const sharedLayers = sharedLayersForTarget(projectDir, target);
+  for (const layer of sharedLayers) {
+    if (layer.tracks.length === 0) continue;
+    const driftResult = computeSharedDrift(projectDir, layer);
+    if (driftResult.state !== null) {
+      if (hasDriftChanges(driftResult.drift)) {
+        warnings.push(
+          `Shared layer "${layer.name}" has spec drift — shared code may need updates before ${target} generation.`
+        );
+      }
+    }
+  }
+
   const ready =
     missing.length === 0 && backendContextReady && !pendingUserConfirmation;
 

package/cli/index.ts

@@ -95,6 +95,19 @@ function checkRulesVersion(): void {
 
 // ── spec helpers (shared with MCP server) ────────────────────────────
 
+function lookupLocaleKey(content: Record<string, unknown>, key: string): { found: boolean; value: unknown } {
+  if (key in content) return { found: true, value: content[key] };
+  const parts = key.split(".");
+  let current: unknown = content;
+  for (const part of parts) {
+    if (current === null || current === undefined || typeof current !== "object" || Array.isArray(current)) {
+      return { found: false, value: undefined };
+    }
+    current = (current as Record<string, unknown>)[part];
+  }
+  return current !== undefined ? { found: true, value: current } : { found: false, value: undefined };
+}
+
 function resolveSpecDir(projectDir: string, manifest: any, key: string): string {
   return resolve(projectDir, manifest.includes?.[key] ?? `./${key}/`);
 }
@@ -293,7 +306,10 @@ async function main(): Promise<void> {
       const content = JSON.parse(readFileSync(filePath, "utf-8"));
       if (keys) {
         const filtered: Record<string, unknown> = {};
-        for (const key of keys) { if (key in content) filtered[key] = content[key]; }
+        for (const key of keys) {
+          const result = lookupLocaleKey(content, key);
+          if (result.found) filtered[key] = result.value;
+        }
         console.log(JSON.stringify(filtered, null, 2));
       } else {
         console.log(JSON.stringify(content, null, 2));
@@ -332,6 +348,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 +399,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 +477,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

@@ -33,6 +33,7 @@ export type InitOptionsResponse = {
     options?: string[];
   }>;
   configure_targets_note: string;
+  shared_layer_note?: string;
 };
 
 export function listInitOptions(): InitOptionsResponse {
@@ -78,9 +79,17 @@ export function listInitOptions(): InitOptionsResponse {
         type: "yes_no",
         default: defaults.configureTargets,
       },
+      {
+        key: "with_shared",
+        prompt: "Does the project share code between platforms (e.g. KMP commonMain)?",
+        type: "yes_no",
+        default: false,
+      },
     ],
     configure_targets_note:
       "If configure_targets is true, use `openuispec configure-target <target> --list-options` for each target after init to present stack choices to the user.",
+    shared_layer_note:
+      "If with_shared is true, add shared layer config to generation.shared in the manifest. Each shared layer needs: name, platforms (subset of targets), language, root (path relative to openuispec.yaml), tracks (spec categories: manifest, contracts, flows, screens, tokens, platform, locales), and scope (what code belongs there). Also add generation.structure entries for each target to define where platform-specific UI code goes and its scope.",
   };
 }
 
@@ -171,7 +180,12 @@ function getPackageVersion(): string {
 function manifestTemplate(
   name: string,
   targets: string[],
-  options: { withApi: boolean; backendPath: string | null }
+  options: {
+    withApi: boolean;
+    backendPath: string | null;
+    sharedLayers: SharedLayerAnswers[];
+    structures: StructureAnswers[];
+  }
 ): string {
   const targetList = targets.join(", ");
   const outputLines = targets
@@ -186,6 +200,38 @@ function manifestTemplate(
     })
     .join("\n");
 
+  function yamlPathsBlock(paths: Record<string, string>): string {
+    const entries = Object.entries(paths);
+    return entries.length > 0
+      ? `\n      paths:\n${entries.map(([k, v]) => `        ${k}: "${v}"`).join("\n")}`
+      : "";
+  }
+
+  let sharedBlock = "";
+  if (options.sharedLayers.length > 0) {
+    const layers = options.sharedLayers.map((layer) => {
+      const tracksLine = layer.tracks.length > 0
+        ? `\n      tracks: [${layer.tracks.join(", ")}]`
+        : "";
+      return `    ${layer.name}:
+      platforms: [${layer.platforms.join(", ")}]
+      language: ${layer.language}
+      root: "${layer.root}"
+      scope: "${layer.scope}"${tracksLine}${yamlPathsBlock(layer.paths)}`;
+    }).join("\n");
+    sharedBlock = `  shared:\n${layers}\n`;
+  }
+
+  let structureBlock = "";
+  if (options.structures.length > 0) {
+    const entries = options.structures.map((s) => {
+      const scopeLine = s.scope ? `\n      scope: "${s.scope}"` : "";
+      return `    ${s.target}:
+      root: "${s.root}"${scopeLine}${yamlPathsBlock(s.paths)}`;
+    }).join("\n");
+    structureBlock = `  structure:\n${entries}\n`;
+  }
+
   return `# ${name} — OpenUISpec v0.1
 spec_version: "0.1"
 
@@ -218,7 +264,7 @@ ${options.withApi ? `  code_roots:
     backend: "${options.backendPath}"                # Required when api.endpoints are declared
 ` : ""}  output_format:
 ${outputLines}
-
+${sharedBlock}${structureBlock}
 data_model: {}
 
 api:
@@ -348,21 +394,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 +434,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 +464,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 +508,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.
@@ -664,6 +725,23 @@ export function extractRulesVersion(filePath: string): string | null {
 
 export { getPackageVersion };
 
+interface SharedLayerAnswers {
+  name: string;
+  platforms: string[];
+  language: string;
+  root: string;
+  tracks: string[];
+  scope: string;
+  paths: Record<string, string>;
+}
+
+interface StructureAnswers {
+  target: string;
+  root: string;
+  scope: string;
+  paths: Record<string, string>;
+}
+
 interface InitOptions {
   defaults: boolean;
   quiet: boolean;
@@ -673,6 +751,7 @@ interface InitOptions {
   withApi?: boolean;
   backendPath?: string;
   configureTargets?: boolean;
+  withShared?: boolean;
 }
 
 interface InitAnswers {
@@ -682,6 +761,8 @@ interface InitAnswers {
   withApi: boolean;
   backendPath: string | null;
   configureTargets: boolean;
+  sharedLayers: SharedLayerAnswers[];
+  structures: StructureAnswers[];
 }
 
 function parseTargetsValue(raw: string): string[] {
@@ -737,6 +818,12 @@ function parseInitArgs(argv: string[]): InitOptions {
       case "--no-configure-targets":
         options.configureTargets = false;
         break;
+      case "--with-shared":
+        options.withShared = true;
+        break;
+      case "--no-shared":
+        options.withShared = false;
+        break;
       default:
         if (arg.startsWith("--")) {
           console.error(`Error: Unknown init option: ${arg}`);
@@ -758,9 +845,127 @@ function collectDefaults(): InitAnswers {
     withApi: true,
     backendPath: "../backend/",
     configureTargets: true,
+    sharedLayers: [],
+    structures: [],
   };
 }
 
+const SHARED_LAYER_DEFAULTS: Record<string, {
+  language: string;
+  root: string;
+  tracks: string[];
+  scope: string;
+  paths: Record<string, string>;
+  structureScope: Record<string, string>;
+}> = {
+  kmp: {
+    language: "kotlin",
+    root: "../shared",
+    tracks: [],
+    scope: "Business logic, data models, repositories, API clients, view models/stores. No UI rendering.",
+    paths: { domain: "commonMain/domain/", features: "commonMain/features/" },
+    structureScope: {
+      ios: "Pure SwiftUI views and navigation. All business logic comes from the shared layer.",
+      android: "Pure Compose UI and navigation. All business logic comes from the shared layer.",
+    },
+  },
+};
+
+function defaultSharedConfig(targets: string[]): {
+  sharedLayers: SharedLayerAnswers[];
+  structures: StructureAnswers[];
+} {
+  const mobilePlatforms = targets.filter((t) => t === "ios" || t === "android");
+  if (mobilePlatforms.length < 2) {
+    return { sharedLayers: [], structures: [] };
+  }
+
+  const preset = SHARED_LAYER_DEFAULTS.kmp;
+  const sharedLayers: SharedLayerAnswers[] = [{
+    name: "mobile_common",
+    platforms: mobilePlatforms,
+    language: preset.language,
+    root: preset.root,
+    tracks: preset.tracks,
+    scope: preset.scope,
+    paths: preset.paths,
+  }];
+
+  const structures: StructureAnswers[] = mobilePlatforms.map((t) => ({
+    target: t,
+    root: preset.root,
+    scope: preset.structureScope[t] ?? `Pure ${t} UI. Business logic comes from the shared layer.`,
+    paths: { ui: `${t}App/ui/` },
+  }));
+
+  return { sharedLayers, structures };
+}
+
+async function collectSharedLayerAnswers(
+  rl: ReturnType<typeof createInterface>,
+  targets: string[],
+): Promise<{ sharedLayers: SharedLayerAnswers[]; structures: StructureAnswers[] }> {
+  const withShared = await askYesNo(rl, "\nShare code between platforms (e.g. KMP commonMain)?", false);
+  if (!withShared) return { sharedLayers: [], structures: [] };
+
+  const defaults = defaultSharedConfig(targets);
+  const defaultLayer = defaults.sharedLayers[0];
+  if (!defaultLayer) return { sharedLayers: [], structures: [] };
+
+  console.log("\n  Shared layer defaults (KMP):");
+  console.log(`    platforms: ${defaultLayer.platforms.join(", ")}`);
+  console.log(`    language: ${defaultLayer.language}`);
+  console.log(`    root: ${defaultLayer.root}`);
+  console.log(`    scope: ${defaultLayer.scope}`);
+
+  const useDefaults = await askYesNo(rl, "  Use these defaults?", true);
+  if (useDefaults) return defaults;
+
+  const layerName = await ask(rl, "  Shared layer name", defaultLayer.name);
+  const platformsRaw = await askList(rl, "  Platforms", targets, defaultLayer.platforms);
+  const language = await ask(rl, "  Language", defaultLayer.language);
+  const root = await ask(rl, "  Root path (relative to openuispec.yaml)", defaultLayer.root);
+  const scope = await ask(rl, "  Scope (what code belongs here)", defaultLayer.scope);
+  const wantTracks = await askYesNo(rl, "  Enable hash-based drift tracking for this layer?", false);
+  const tracksRaw = wantTracks
+    ? await askList(
+        rl,
+        "  Tracked spec categories",
+        ["manifest", "tokens", "contracts", "screens", "flows", "platform", "locales"],
+        ["manifest", "contracts", "flows"]
+      )
+    : [];
+
+  const sharedLayers: SharedLayerAnswers[] = [{
+    name: layerName,
+    platforms: platformsRaw,
+    language,
+    root,
+    tracks: tracksRaw,
+    scope,
+    paths: defaultLayer.paths,
+  }];
+
+  const structures: StructureAnswers[] = [];
+  for (const t of platformsRaw) {
+    const defaultStructure = defaults.structures.find((s) => s.target === t);
+    const structRoot = await ask(rl, `  ${t} structure root`, defaultStructure?.root ?? root);
+    const structScope = await ask(
+      rl,
+      `  ${t} scope (what code belongs in the ${t} target)`,
+      defaultStructure?.scope ?? `Pure ${t} UI rendering.`
+    );
+    structures.push({
+      target: t,
+      root: structRoot,
+      scope: structScope,
+      paths: defaultStructure?.paths ?? { ui: `${t}App/ui/` },
+    });
+  }
+
+  return { sharedLayers, structures };
+}
+
 async function collectInteractiveAnswers(rl: ReturnType<typeof createInterface>): Promise<InitAnswers> {
   const defaults = collectDefaults();
   const name = await ask(rl, "Project name", defaults.name);
@@ -777,6 +982,7 @@ async function collectInteractiveAnswers(rl: ReturnType<typeof createInterface>)
     ? await ask(rl, "Backend folder path relative to openuispec.yaml", defaults.backendPath ?? "../backend/")
     : null;
   const configureTargets = await askYesNo(rl, "Configure target stacks now?", defaults.configureTargets);
+  const { sharedLayers, structures } = await collectSharedLayerAnswers(rl, targets);
 
   return {
     name,
@@ -785,6 +991,8 @@ async function collectInteractiveAnswers(rl: ReturnType<typeof createInterface>)
     withApi,
     backendPath,
     configureTargets,
+    sharedLayers,
+    structures,
   };
 }
 
@@ -808,6 +1016,8 @@ function collectNonInteractiveAnswers(argv: string[]): InitAnswers {
 
   const withApi = parsed.withApi ?? defaults.withApi;
   const backendPath = withApi ? parsed.backendPath ?? defaults.backendPath : null;
+  const withShared = parsed.withShared ?? false;
+  const { sharedLayers, structures } = withShared ? defaultSharedConfig(targets) : { sharedLayers: [], structures: [] };
 
   return {
     name: parsed.name ?? defaults.name,
@@ -816,6 +1026,8 @@ function collectNonInteractiveAnswers(argv: string[]): InitAnswers {
     withApi,
     backendPath,
     configureTargets: parsed.configureTargets ?? defaults.configureTargets,
+    sharedLayers,
+    structures,
   };
 }
 
@@ -864,6 +1076,8 @@ export async function init(argv: string[] = []): Promise<void> {
       manifestTemplate(answers.name, answers.targets, {
         withApi: answers.withApi,
         backendPath: answers.backendPath,
+        sharedLayers: answers.sharedLayers,
+        structures: answers.structures,
       }),
       quiet
     );

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/docs/file-formats.md

@@ -64,6 +64,42 @@ Paths are relative to `openuispec.yaml`. The `.openuispec-state.json` file recor
 - `generation.extra_rules` can hold project-wide generation conventions
 - `drift --snapshot` requires that target output directory to already exist
 
+## Shared code layers
+
+Projects that share business logic between platforms (e.g. KMP `commonMain`) can declare `generation.shared` to tell AI what code belongs in the shared layer vs platform-specific targets:
+
+```yaml
+generation:
+  targets: [ios, android, web]
+  shared:
+    mobile_common:
+      platforms: [ios, android]
+      language: kotlin
+      root: "../shared"
+      scope: "Business logic, data models, repositories, API clients, view models. No UI rendering."
+      # tracks: [manifest, contracts]   # optional — enables hash-based drift detection for this layer
+      paths:
+        domain: "commonMain/domain/"
+        features: "commonMain/features/"
+  structure:
+    ios:
+      root: "../shared"
+      scope: "Pure SwiftUI views and navigation. All business logic comes from the shared layer."
+      paths:
+        ui: "iosApp/ui/"
+    android:
+      root: "../shared"
+      scope: "Pure Compose UI and navigation. All business logic comes from the shared layer."
+      paths:
+        ui: "androidApp/ui/"
+```
+
+- **`scope`** (required on shared, optional on structure) — tells AI what code belongs where. This is the primary mechanism for routing generation work between shared and platform layers.
+- **`tracks`** (optional) — when set, enables hash-based drift detection scoped to specific spec categories (`manifest`, `tokens`, `contracts`, `screens`, `flows`, `platform`, `locales`). When omitted, the shared layer relies on `scope` alone.
+- **`structure`** — when present, overrides the heuristic code root discovery for a target. Paths are relative to `root`.
+- Shared layers are not targets — they are tracked alongside targets in `prepare` and `status` output.
+- `openuispec init --with-shared` scaffolds KMP defaults when both ios and android targets are selected.
+
 ## Spec sections overview
 
 | Section | What it defines |

package/docs/implementation-notes.md

@@ -87,6 +87,13 @@
   - backend generation context
     - if the manifest declares `api.endpoints`, `generation.code_roots.backend` is required
     - `prepare` should surface the resolved backend root so AI can inspect backend code when generating API clients
+- Shared code layers (`generation.shared`):
+  - when configured, `prepare` includes `shared_layers` in its output with per-layer `scope`, `already_generated`, and `guidance`
+  - `scope` tells AI what code belongs in the shared layer vs the platform target — this is the primary routing mechanism
+  - optional `tracks` enables hash-based drift detection scoped to specific spec categories
+  - `generation.structure` overrides heuristic code root discovery when present, and its `scope` field tells AI what goes in the platform-specific target
+  - `suggestCodeRoots` includes shared layer roots and structure paths alongside target output directories
+  - generation rules include shared layer and target scope descriptions
 - Important positioning:
   - `prepare` does not generate code
   - `prepare` does not verify code correctness