openuispec 0.1.46 → 0.2.0

package/README.md

@@ -115,10 +115,15 @@ Or run directly: `openuispec mcp`
 | `openuispec_spec_schema` | Before creating/editing spec files | Returns the full JSON schema for a specific spec type — exact structure, required fields, allowed values |
 | `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 for tokens, screens, contracts |
-| `openuispec_check` | After generation | Schema validation + concrete audit checklist from your spec |
+| `openuispec_check` | After generation | Schema validation + concrete audit checklist from your spec. Optional `screens`/`contracts` params scope the audit |
 | `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_status` | Anytime | Cross-target summary: baselines, drift, next steps |
+| `openuispec_get_screen` | Incremental edits | Get a single screen spec by name — faster than `read_specs` for targeted work |
+| `openuispec_get_contract` | Incremental edits | Get a single contract spec, optionally filtered to one variant |
+| `openuispec_get_tokens` | Incremental edits | Get tokens for a specific category (color, typography, spacing, etc.) |
+| `openuispec_get_locale` | Incremental edits | Get a single locale file, optionally filtered to specific keys |
+| `openuispec_screenshot` | Visual verification | Take a screenshot of the generated web app at a specific route (requires `puppeteer`) |
 
 The server includes **protocol-level instructions** that trigger on UI-related requests independently of CLAUDE.md rules — so even if CLAUDE.md is buried under other project rules, the MCP enforcement still works.
 
@@ -138,6 +143,7 @@ See the examples for reference:
 
 - [TaskFlow](./examples/taskflow/openuispec/) — compact reference spec covering all 7 contract families
 - [Todo Orbit](./examples/todo-orbit/openuispec/) — bilingual task app with localization, custom contracts, and generated native/web targets
+- [Social App](./examples/social-app/openuispec/) — trilingual social app with feeds, messaging, profiles, and generated Android/web targets
 
 ## Repository structure
 
@@ -175,6 +181,7 @@ openuispec/
 │   │   ├── generated/                   # Generated iOS, Android, and web apps
 │   │   ├── README.md                    # Sample overview and structure
 │   │   └── AGENTS.md / CLAUDE.md        # AI rules generated from the package
+│   ├── social-app/                       # Social app sample (trilingual, Android + Web)
 │   └── todo-orbit/                      # Full showcase sample
 │       ├── openuispec/                  # Source OpenUISpec project
 │       ├── generated/                   # Generated iOS, Android, and web apps
@@ -184,7 +191,8 @@ openuispec/
 │   ├── index.ts                        # Entry point
 │   └── init.ts                         # Project scaffolding + AI rules
 ├── mcp-server/                          # MCP server (openuispec-mcp)
-│   └── index.ts                        # Stdio transport, 8 tools
+│   ├── index.ts                        # Stdio transport, 13 tools
+│   └── screenshot.ts                  # Dev server + headless browser screenshot
 ├── check/                               # Composite validation command
 │   └── index.ts                        # Schema + semantic + readiness
 ├── drift/                               # Drift detection (spec change tracking)
@@ -243,6 +251,8 @@ By default, drift stores state in `generated/<target>/<project>/`. To point targ
 ```yaml
 generation:
   targets: [ios, android, web]
+  extra_rules:
+    - "Generation hint strings may start with [common], [ios], [android], or [web] to indicate scope."
   output_dir:
     web: "../web-ui/"
     android: "../kmp-ui/"
@@ -255,6 +265,8 @@ Paths are relative to `openuispec.yaml`. The `.openuispec-state.json` file is st
 
 If `api.endpoints` are declared, `generation.code_roots.backend` is required. It should point at the backend folder the AI must inspect when generating API clients or wiring request/response behavior.
 
+`generation.extra_rules` can hold project-wide generation conventions for AI and humans. For example, projects may declare that generation hint strings use prefixes such as `[common]`, `[ios]`, `[android]`, and `[web]` to indicate scope.
+
 `openuispec drift --snapshot --target <target>` requires that target output directory to already exist. If it does not, generate the target code first, then snapshot the accepted baseline.
 
 Use the commands like this:
@@ -345,7 +357,7 @@ to see which targets are already up to date and which ones still need to catch u
 
 ## Status
 
-**v0.1 — Draft**. The spec covers all foundational layers. TaskFlow provides a compact reference app, and Todo Orbit extends coverage with localization, recurring-rule flows, custom contracts, and generated native/web targets.
+**v0.1 — Draft**. The spec covers all foundational layers. TaskFlow provides a compact reference app, Todo Orbit extends coverage with localization, recurring-rule flows, custom contracts, and generated native/web targets, and Social App demonstrates a trilingual social feed app with generated Android and web targets.
 
 ### Roadmap
 
@@ -364,7 +376,8 @@ to see which targets are already up to date and which ones still need to catch u
 - [x] CLI tool (`openuispec init` for project scaffolding + AI rules)
 - [x] MCP server for AI tool integration (`openuispec-mcp`)
 - [x] Multi-platform showcase app (`examples/todo-orbit/`)
-- [ ] More example apps (e-commerce, social, dashboard)
+- [x] Social app example (`examples/social-app/`)
+- [ ] More example apps (e-commerce, dashboard)
 
 ## Contributing
 

package/cli/init.ts

@@ -208,6 +208,8 @@ i18n:
 
 generation:
   targets: [${targetList}]
+  # extra_rules:                        # Optional: project-wide AI authoring conventions
+  #   - "Generation hint strings may start with [common], [ios], [android], or [web] to indicate scope."
   # output_dir:                          # Optional: map targets to code directories
   #   ios: "../ios-app/"                  # relative to this file
   #   android: "../android-app/"
@@ -272,10 +274,15 @@ When the openuispec MCP server is configured, AI assistants should use these too
 | \`openuispec_spec_schema\` | Get the full JSON schema for a specific spec type — exact structure, required fields, allowed values. |
 | \`openuispec_prepare\` | **Before any UI code generation.** Returns spec context, platform config, and constraints. |
 | \`openuispec_read_specs\` | Load spec file contents — the authoritative source for tokens, screens, contracts. |
-| \`openuispec_check\` | After editing spec files. Validates schema + semantics + readiness. |
+| \`openuispec_check\` | After editing spec files. Validates schema + semantics + readiness. Optional \`screens\`/\`contracts\` params scope the audit. |
 | \`openuispec_validate\` | Schema-only validation, optionally by group. |
 | \`openuispec_drift\` | Detect spec changes since last snapshot. |
 | \`openuispec_status\` | To understand cross-target state (baselines, drift, next steps). |
+| \`openuispec_get_screen\` | Get a single screen spec by name — faster than \`read_specs\` for targeted edits. |
+| \`openuispec_get_contract\` | Get a single contract spec, optionally filtered to one variant. |
+| \`openuispec_get_tokens\` | Get tokens for a specific category (color, typography, spacing, etc.). |
+| \`openuispec_get_locale\` | Get a single locale file, optionally filtered to specific keys. |
+| \`openuispec_screenshot\` | Take a screenshot of the generated web app at a route (requires \`puppeteer\`). |
 
 ## CLI commands
 
@@ -345,6 +352,15 @@ Call these MCP tools directly. They return structured JSON with everything you n
 - Call \`openuispec_spec_schema\` with the specific type to get the full JSON schema.
 - Write the spec file following the schema exactly.
 
+**Focused getters (prefer these for incremental edits over \`read_specs\`):**
+- \`openuispec_get_screen(name)\` — single screen spec
+- \`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
+
+Use \`read_specs\` for full-project generation; use focused getters when editing one screen or contract.
+
 **Other tools:**
 - \`openuispec_status\` — cross-target summary, good starting point
 - \`openuispec_drift\` with \`explain: true\` — property-level spec changes

package/examples/social-app/AGENTS.md

@@ -1,5 +1,5 @@
 <!-- openuispec-rules-start -->
-<!-- openuispec-rules-version: 0.1.45 -->
+<!-- openuispec-rules-version: 0.1.47 -->
 # OpenUISpec — AI Assistant Rules
 # ================================
 # This project uses OpenUISpec to define UI as a semantic spec.
@@ -38,6 +38,15 @@ Call these MCP tools directly. They return structured JSON with everything you n
 - Call `openuispec_spec_schema` with the specific type to get the full JSON schema.
 - Write the spec file following the schema exactly.
 
+**Focused getters (prefer these for incremental edits over `read_specs`):**
+- `openuispec_get_screen(name)` — single screen spec
+- `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
+
+Use `read_specs` for full-project generation; use focused getters when editing one screen or contract.
+
 **Other tools:**
 - `openuispec_status` — cross-target summary, good starting point
 - `openuispec_drift` with `explain: true` — property-level spec changes

package/examples/social-app/CLAUDE.md

@@ -1,5 +1,5 @@
 <!-- openuispec-rules-start -->
-<!-- openuispec-rules-version: 0.1.45 -->
+<!-- openuispec-rules-version: 0.1.47 -->
 # OpenUISpec — AI Assistant Rules
 # ================================
 # This project uses OpenUISpec to define UI as a semantic spec.
@@ -38,6 +38,15 @@ Call these MCP tools directly. They return structured JSON with everything you n
 - Call `openuispec_spec_schema` with the specific type to get the full JSON schema.
 - Write the spec file following the schema exactly.
 
+**Focused getters (prefer these for incremental edits over `read_specs`):**
+- `openuispec_get_screen(name)` — single screen spec
+- `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
+
+Use `read_specs` for full-project generation; use focused getters when editing one screen or contract.
+
 **Other tools:**
 - `openuispec_status` — cross-target summary, good starting point
 - `openuispec_drift` with `explain: true` — property-level spec changes

package/examples/social-app/generated/android/social-app/app/src/main/java/com/social/app/ui/screens/SettingsScreen.kt

@@ -133,19 +133,21 @@ fun SettingsScreen(
             )
 
             ContractSectionHeader(stringResource(R.string.settings_account))
-            ActionTriggerButton(
-                text = stringResource(R.string.settings_edit_profile),
-                onClick = onEditProfileClick,
-                variant = ActionTriggerVariant.Secondary,
-                fullWidth = true,
-                icon = { Icon(Icons.Default.Edit, contentDescription = null) },
-            )
-            ActionTriggerButton(
-                text = stringResource(R.string.settings_logout),
-                onClick = { showLogoutDialog = true },
-                variant = ActionTriggerVariant.Destructive,
-                fullWidth = true,
-            )
+            Column(verticalArrangement = Arrangement.spacedBy(Spacing.SM)) {
+                ActionTriggerButton(
+                    text = stringResource(R.string.settings_edit_profile),
+                    onClick = onEditProfileClick,
+                    variant = ActionTriggerVariant.Secondary,
+                    fullWidth = false,
+                    icon = { Icon(Icons.Default.Edit, contentDescription = null) },
+                )
+                ActionTriggerButton(
+                    text = stringResource(R.string.settings_logout),
+                    onClick = { showLogoutDialog = true },
+                    variant = ActionTriggerVariant.Destructive,
+                    fullWidth = false,
+                )
+            }
         }
     }
 

package/examples/social-app/generated/web/social-app/src/components/Shell.tsx

@@ -5,12 +5,11 @@ import { Icon } from "../lib/icons";
 import type { SizeClass } from "../lib/tokens";
 import { cn, useSizeClass } from "../lib/utils";
 import { selectUnreadNotifications, useAppStore } from "../state/store";
-import { ActionButton } from "./ui";
+import { ActionButton, ActionGroup } from "./ui";
 
 const primaryRoutes = [
   { to: "/home", icon: "home" as const, labelKey: "nav.home" },
   { to: "/discover", icon: "discover" as const, labelKey: "nav.discover" },
-  { to: "/create", icon: "create_post" as const, labelKey: "nav.create" },
   { to: "/notifications", icon: "notifications" as const, labelKey: "nav.notifications" },
   { to: "/profile", icon: "profile" as const, labelKey: "nav.profile" },
 ];
@@ -91,6 +90,19 @@ export function AppShell() {
         </main>
 
         {sizeClass !== "expanded" ? <BottomTabBar unreadCount={unreadCount} /> : null}
+
+        {location.pathname.startsWith("/home") || location.pathname === "/" ? (
+          <Link
+            to="/create"
+            className={cn(
+              "interactive-press fixed z-30 flex h-14 w-14 items-center justify-center rounded-cap-primary bg-[var(--color-brand-primary)] text-white shadow-md",
+              sizeClass === "expanded" ? "bottom-8 right-8" : "bottom-20 right-4",
+            )}
+            aria-label={t("nav.create")}
+          >
+            <Icon name="create_post" className="h-6 w-6" />
+          </Link>
+        ) : null}
       </div>
 
       {toast ? (
@@ -106,7 +118,7 @@ export function AppShell() {
           <div className="w-full max-w-md rounded-surface border border-[var(--color-border-default)] bg-[var(--color-surface-primary)] p-6 shadow-lg">
             <h2 className="text-xl font-semibold">{dialog.title}</h2>
             <p className="mt-2 text-sm leading-6 text-[var(--color-text-secondary)]">{dialog.message}</p>
-            <div className="mt-6 flex flex-col gap-3 sm:flex-row sm:justify-end">
+            <ActionGroup className="mt-6 sm:flex-row sm:items-center sm:justify-end">
               {dialog.actions.map((action) => (
                 <ActionButton
                   key={action.label}
@@ -119,7 +131,7 @@ export function AppShell() {
                   {action.label}
                 </ActionButton>
               ))}
-            </div>
+            </ActionGroup>
           </div>
         </div>
       ) : null}
@@ -131,7 +143,7 @@ function BottomTabBar({ unreadCount }: { unreadCount: number }) {
   const { t } = useI18n();
   return (
     <nav className="fixed inset-x-0 bottom-0 z-30 border-t border-[var(--color-border-default)] bg-[color:rgba(250,248,245,0.94)] px-2 py-2 backdrop-blur-xl">
-      <div className="mx-auto grid max-w-xl grid-cols-5 gap-1">
+      <div className="mx-auto grid max-w-xl grid-cols-4 gap-1">
         {primaryRoutes.map((route) => (
           <NavLink
             key={route.to}

package/examples/social-app/generated/web/social-app/src/components/ui.tsx

@@ -40,8 +40,17 @@ export function Surface({
   return <div className={cn("rounded-surface border border-[var(--color-border-default)] bg-[var(--color-surface-secondary)] shadow-sm", className)}>{children}</div>;
 }
 
+export function ActionGroup({
+  children,
+  className,
+}: PropsWithChildren<{
+  className?: string;
+}>) {
+  return <div className={cn("flex flex-col items-start gap-3", className)}>{children}</div>;
+}
+
 type ActionButtonProps = ButtonHTMLAttributes<HTMLButtonElement> & {
-  variant?: "primary" | "secondary" | "chip" | "destructive";
+  variant?: "primary" | "secondary" | "chip" | "destructive" | "fab";
   icon?: Parameters<typeof Icon>[0]["name"];
   fullWidth?: boolean;
   selected?: boolean;
@@ -65,6 +74,8 @@ export function ActionButton({
         ? "rounded-cap-alternate border-[var(--color-border-strong)] bg-transparent text-[var(--color-text-primary)]"
         : variant === "destructive"
           ? "rounded-cap-primary border-transparent bg-[var(--color-semantic-danger)] text-white"
+          : variant === "fab"
+            ? "rounded-cap-primary border-transparent bg-[var(--color-brand-primary)] text-[var(--color-brand-primary-on)] shadow-md"
           : selected
             ? "rounded-cap-primary border-transparent bg-[var(--color-brand-accent)] text-[var(--color-brand-accent-on)]"
             : "rounded-cap-primary border-[var(--color-border-default)] bg-transparent text-[var(--color-text-primary)]";
@@ -72,7 +83,8 @@ export function ActionButton({
   return (
     <button
       className={cn(
-        "interactive-press inline-flex min-h-11 items-center justify-center gap-2 border px-4 py-3 text-sm font-semibold transition",
+        "interactive-press inline-flex min-h-11 shrink-0 items-center justify-center gap-2 whitespace-nowrap align-middle border px-4 py-3 text-sm font-semibold transition",
+        variant === "fab" && "h-14 w-14 gap-0 px-0 py-0",
         fullWidth && "w-full",
         variantClass,
         className,
@@ -80,7 +92,7 @@ export function ActionButton({
       {...props}
     >
       {icon ? <Icon name={icon} className="h-5 w-5" /> : null}
-      <span>{children}</span>
+      {variant === "fab" ? (children ? <span className="sr-only">{children}</span> : null) : <span>{children}</span>}
       {trailing}
     </button>
   );

package/examples/social-app/generated/web/social-app/src/screens/HomeFeedScreen.tsx

@@ -2,7 +2,7 @@ import { useMemo, useState, startTransition } from "react";
 import { useNavigate } from "react-router";
 import { useI18n } from "../i18n";
 import { selectFeed, selectStories, selectUserById, useAppStore } from "../state/store";
-import { CreatorCard, PostCard, StoryCard } from "../components/cards";
+import { PostCard, StoryCard } from "../components/cards";
 import { ActionButton, EmptyState, ErrorState, ScreenScaffold, SectionTitle, SkeletonList } from "../components/ui";
 import { useSimulatedLoading, useUiScenario } from "../lib/utils";
 
@@ -56,15 +56,7 @@ export function HomeFeedScreen() {
       </section>
 
       <section className="space-y-4">
-        <SectionTitle
-          action={
-            <ActionButton variant="primary" icon="create_post" onClick={() => navigate("/create")}>
-              {t("nav.create")}
-            </ActionButton>
-          }
-        >
-          Feed
-        </SectionTitle>
+        <SectionTitle>Feed</SectionTitle>
 
         {scenario === "error" ? (
           <ErrorState title="Feed unavailable" description="The mock feed request failed. Remove `?ui=error` to restore the normal state." />
@@ -97,17 +89,15 @@ export function HomeFeedScreen() {
         )}
       </section>
 
-      <section className="space-y-4 xl:hidden">
-        <SectionTitle>Suggested Creators</SectionTitle>
-        <div className="no-scrollbar flex snap-x gap-3 overflow-x-auto pb-1">
-          {state.users
-            .filter((user) => user.id !== state.currentUserId)
-            .slice(0, 3)
-            .map((user) => (
-              <CreatorCard key={user.id} user={user} to={`/u/${user.id}`} />
-            ))}
-        </div>
-      </section>
+      <ActionButton
+        variant="fab"
+        icon="create_post"
+        aria-label={t("nav.create")}
+        className="fixed bottom-20 right-4 z-30 lg:bottom-8 lg:right-8"
+        onClick={() => navigate("/create")}
+      >
+        {t("nav.create")}
+      </ActionButton>
     </ScreenScaffold>
   );
 }

package/examples/social-app/generated/web/social-app/src/screens/SettingsScreen.tsx

@@ -1,6 +1,6 @@
 import { useNavigate } from "react-router";
 import { useI18n } from "../i18n";
-import { ActionButton, ScreenScaffold, SectionTitle, SelectField, ToggleField } from "../components/ui";
+import { ActionButton, ActionGroup, ScreenScaffold, SectionTitle, SelectField, ToggleField } from "../components/ui";
 import { useAppStore } from "../state/store";
 
 export function SettingsScreen() {
@@ -49,28 +49,30 @@ export function SettingsScreen() {
 
       <section className="space-y-4">
         <SectionTitle>{t("settings.account")}</SectionTitle>
-        <ActionButton variant="secondary" icon="edit" onClick={() => navigate("/profile/edit")}>
-          {t("settings.edit_profile")}
-        </ActionButton>
-        <ActionButton
-          variant="destructive"
-          onClick={() =>
-            state.openDialog({
-              title: t("settings.logout"),
-              message: t("settings.logout_confirm"),
-              actions: [
-                { label: t("common.cancel"), variant: "secondary", onPress: () => undefined },
-                {
-                  label: t("settings.logout"),
-                  variant: "destructive",
-                  onPress: () => state.logout(),
-                },
-              ],
-            })
-          }
-        >
-          {t("settings.logout")}
-        </ActionButton>
+        <ActionGroup className="gap-2">
+          <ActionButton variant="secondary" icon="edit" onClick={() => navigate("/profile/edit")}>
+            {t("settings.edit_profile")}
+          </ActionButton>
+          <ActionButton
+            variant="destructive"
+            onClick={() =>
+              state.openDialog({
+                title: t("settings.logout"),
+                message: t("settings.logout_confirm"),
+                actions: [
+                  { label: t("common.cancel"), variant: "secondary", onPress: () => undefined },
+                  {
+                    label: t("settings.logout"),
+                    variant: "destructive",
+                    onPress: () => state.logout(),
+                  },
+                ],
+              })
+            }
+          >
+            {t("settings.logout")}
+          </ActionButton>
+        </ActionGroup>
       </section>
     </ScreenScaffold>
   );

package/examples/social-app/openuispec/contracts/action_trigger.yaml

@@ -21,11 +21,13 @@ action_trigger:
         web: { style: "border-radius: 2px 24px 2px 24px" }
       generation:
         must_handle:
-          - "Rounded cap primary: TR and BL corners ~24px, TL and BR corners 2px"
-          - "Dark fill background with high-contrast white text"
-          - "Press state: scale down slightly with spring animation"
+          - "[common] Rounded cap primary: TR and BL corners ~24px, TL and BR corners 2px"
+          - "[common] Dark fill background with high-contrast white text"
+          - "[common] Press state: scale down slightly with spring animation"
+          - "[web] When action triggers are adjacent siblings, place them in an explicit group/container layout instead of raw inline text flow."
+          - "[web] Mixed icon-bearing and text-only actions keep consistent cross-axis alignment."
         should_handle:
-          - "Haptic feedback on press (iOS)"
+          - "[ios] Haptic feedback on press"
 
     secondary:
       semantic: "Secondary action — bordered, rounded cap alternate diagonal (mirrors primary)"
@@ -40,8 +42,10 @@ action_trigger:
         web: { style: "border-radius: 24px 2px 24px 2px" }
       generation:
         must_handle:
-          - "Rounded cap alternate: TL and BR corners ~24px, TR and BL corners 2px"
-          - "Visible border, no fill. Mirrors primary for visual rhythm."
+          - "[common] Rounded cap alternate: TL and BR corners ~24px, TR and BL corners 2px"
+          - "[common] Visible border, no fill. Mirrors primary for visual rhythm."
+          - "[web] When action triggers are adjacent siblings, place them in an explicit group/container layout instead of raw inline text flow."
+          - "[web] Mixed icon-bearing and text-only actions keep consistent cross-axis alignment."
 
     chip:
       semantic: "Chip / tag — rounded cap primary diagonal, accent fill when selected"
@@ -58,8 +62,8 @@ action_trigger:
         web: { style: "border-radius: 2px 24px 2px 24px" }
       generation:
         must_handle:
-          - "Same diagonal as primary, radius scales to chip height (~16-20px for 32-40px tall chips)"
-          - "Toggle between default (bordered) and selected (accent fill) states"
+          - "[common] Same diagonal as primary, radius scales to chip height (~16-20px for 32-40px tall chips)"
+          - "[common] Toggle between default (bordered) and selected (accent fill) states"
 
     destructive:
       semantic: "Destructive action — danger color, rounded cap primary diagonal"
@@ -71,3 +75,30 @@ action_trigger:
         ios: { shape: "RoundedCapShape(diagonal: .primary)", role: "destructive" }
         android: { shape: "RoundedCapShape(diagonal = Primary)" }
         web: { style: "border-radius: 2px 24px 2px 24px" }
+      generation:
+        must_handle:
+          - "[common] Danger color background with high-contrast on-color text."
+          - "[web] When action triggers are adjacent siblings, place them in an explicit group/container layout instead of raw inline text flow."
+          - "[web] Mixed icon-bearing and text-only actions keep consistent cross-axis alignment."
+
+    fab:
+      semantic: "Floating action button — elevated icon-only primary trigger"
+      tokens:
+        background: "color.brand.primary"
+        icon_color: "color.brand.primary.on_color"
+        shape: "2px 24px 2px 24px"
+        size: 56
+        icon_size: 24
+        elevation: "elevation.md"
+      platform_mapping:
+        ios: { shape: "RoundedCapShape(diagonal: .primary)", size: 56 }
+        android: { shape: "RoundedCapShape(diagonal = Primary)", size: "56.dp" }
+        web: { style: "border-radius: 2px 24px 2px 24px; width: 56px; height: 56px" }
+      generation:
+        must_handle:
+          - "[common] Rounded cap primary shape, icon-only centered layout"
+          - "[common] Brand primary background with white icon"
+          - "[common] Elevation shadow (md level)"
+          - "[common] Press state: scale down slightly with spring animation"
+        should_handle:
+          - "[ios] Haptic feedback on press"

package/examples/social-app/openuispec/screens/home_feed.yaml

@@ -35,10 +35,6 @@ home_feed:
           label: "$t:nav.discover"
           icon: "discover"
           destination: "screens/discover"
-        - id: "create"
-          label: "$t:nav.create"
-          icon: "create_post"
-          destination: "flows/create_post"
         - id: "notifications"
           label: "$t:nav.notifications"
           icon: "notifications"
@@ -121,3 +117,22 @@ home_feed:
         pagination:
           type: infinite_scroll
           cursor_field: "cursor"
+
+      - id: create_fab
+        contract: action_trigger
+        variant: fab
+        position: "floating"
+        props:
+          icon: "create_post"
+          label: "$t:nav.create"
+          aria_label: "$t:nav.create"
+        action:
+          type: navigate
+          destination: "flows/create_post"
+        adaptive:
+          compact:
+            position: "bottom-right"
+            inset: { bottom: 80, right: 16 }
+          expanded:
+            position: "bottom-right"
+            inset: { bottom: 32, right: 32 }

package/examples/social-app/openuispec/screens/settings.yaml

@@ -64,9 +64,13 @@ settings:
 
       - id: account
         header: "$t:settings.account"
+        layout:
+          type: stack
+          spacing: "sm"
         children:
           - contract: action_trigger
             variant: secondary
+            full_width: false
             props:
               label: "$t:settings.edit_profile"
               icon: "edit"
@@ -76,6 +80,7 @@ settings:
 
           - contract: action_trigger
             variant: destructive
+            full_width: false
             props:
               label: "$t:settings.logout"
             action:

package/examples/taskflow/openuispec/openuispec.yaml

@@ -31,6 +31,8 @@ i18n:
 
 generation:
   targets: [ios, android, web]
+  extra_rules:
+    - "Generation hint strings may start with [common], [ios], [android], or [web] to indicate scope."
   code_roots:
     backend: "../backend/"
   output_format:

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

@@ -25,6 +25,8 @@ i18n:
 
 generation:
   targets: [ios, android, web]
+  extra_rules:
+    - "Generation hint strings may start with [common], [ios], [android], or [web] to indicate scope."
   # output_dir:                          # Optional: map targets to code directories
   #   ios: "../ios-app/"                  # relative to this file
   #   android: "../android-app/"

package/mcp-server/index.ts

@@ -25,6 +25,7 @@ import { loadTargetDrift } from "../drift/index.js";
 import { readFileSync as fsReadFileSync, existsSync, readdirSync } from "node:fs";
 import { relative, resolve } from "node:path";
 import YAML from "yaml";
+import { takeScreenshot } from "./screenshot.js";
 
 // ── resolve project cwd ──────────────────────────────────────────────
 
@@ -42,6 +43,12 @@ function getPackageVersion(): string {
   }
 }
 
+// ── spec directory resolver ─────────────────────────────────────────
+
+function resolveSpecDir(projectDir: string, manifest: any, key: string): string {
+  return resolve(projectDir, manifest.includes?.[key] ?? `./${key}/`);
+}
+
 // ── shared tool helpers ──────────────────────────────────────────────
 
 const targetSchema = z.enum(SUPPORTED_TARGETS).describe("Target platform");
@@ -60,7 +67,7 @@ function toolError(err: unknown): { content: [{ type: "text"; text: string }]; i
 
 // ── create server ────────────────────────────────────────────────────
 
-const server = new McpServer(
+export const server = new McpServer(
   {
     name: "openuispec",
     version: getPackageVersion(),
@@ -97,6 +104,19 @@ When you need to create or edit spec files and are unsure of the format:
 2. Call openuispec_spec_schema with the specific type to get the full JSON schema.
 3. Write the spec file following the schema exactly.
 
+FOCUSED GETTERS (prefer these for incremental edits over read_specs):
+- openuispec_get_screen(name) — single screen spec
+- 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
+Use read_specs for full-project generation; use focused getters when editing one screen or contract.
+
+VISUAL VERIFICATION:
+- openuispec_screenshot(route, viewport?, theme?) — screenshot the generated web app at a route.
+  Starts the dev server automatically. Use after generation to visually verify UI matches the spec.
+  Requires puppeteer (npm install -g puppeteer).
+
 Skip these tools ONLY when the request is purely non-UI (API logic, database, infrastructure, etc.)
 or explicitly platform-specific polish that doesn't affect shared UI semantics.`,
   }
@@ -121,7 +141,7 @@ server.registerTool(
 
 // ── tool: openuispec_check ───────────────────────────────────────────
 
-function buildAuditChecklist(projectDir: string, target: string): string {
+function buildAuditChecklist(projectDir: string, target: string, screenFilter?: string[], contractFilter?: string[]): string {
   const lines: string[] = [
     "POST-GENERATION AUDIT — verify your code against these concrete spec requirements:",
     "",
@@ -133,7 +153,7 @@ function buildAuditChecklist(projectDir: string, target: string): string {
 
   // Extract must_handle from contracts
   const manifest = YAML.parse(fsReadFileSync(join(projectDir, "openuispec.yaml"), "utf-8"));
-  const contractsDir = resolve(projectDir, manifest.includes?.contracts ?? "./contracts/");
+  const contractsDir = resolveSpecDir(projectDir, manifest, "contracts");
 
   if (existsSync(contractsDir)) {
     lines.push("## Contract must_handle requirements");
@@ -141,6 +161,7 @@ function buildAuditChecklist(projectDir: string, target: string): string {
       try {
         const content = YAML.parse(fsReadFileSync(join(contractsDir, file), "utf-8"));
         const contractName = Object.keys(content)[0];
+        if (contractFilter && !contractFilter.includes(contractName)) continue;
         const contract = content[contractName];
         if (!contract?.variants) continue;
 
@@ -168,13 +189,14 @@ function buildAuditChecklist(projectDir: string, target: string): string {
   }
 
   // Extract screens and their sections
-  const screensDir = resolve(projectDir, manifest.includes?.screens ?? "./screens/");
+  const screensDir = resolveSpecDir(projectDir, manifest, "screens");
   if (existsSync(screensDir)) {
     lines.push("## Screens — verify all sections exist in generated code");
     for (const file of readdirSync(screensDir).filter(f => f.endsWith(".yaml")).sort()) {
       try {
         const content = YAML.parse(fsReadFileSync(join(screensDir, file), "utf-8"));
         const screenName = Object.keys(content)[0];
+        if (screenFilter && !screenFilter.includes(screenName)) continue;
         const screen = content[screenName];
         if (screen?.status === "stub") continue;
 
@@ -212,7 +234,7 @@ function buildAuditChecklist(projectDir: string, target: string): string {
   }
 
   // Locale keys count
-  const localesDir = resolve(projectDir, manifest.includes?.locales ?? "./locales/");
+  const localesDir = resolveSpecDir(projectDir, manifest, "locales");
   if (existsSync(localesDir)) {
     const localeFiles = readdirSync(localesDir).filter(f => f.endsWith(".json"));
     if (localeFiles.length > 0) {
@@ -228,7 +250,7 @@ function buildAuditChecklist(projectDir: string, target: string): string {
   }
 
   // Platform-specific checks
-  const platformDir = resolve(projectDir, manifest.includes?.platform ?? "./platform/");
+  const platformDir = resolveSpecDir(projectDir, manifest, "platform");
   const platformPath = join(platformDir, `${target}.yaml`);
   if (existsSync(platformPath)) {
     try {
@@ -254,14 +276,20 @@ function buildAuditChecklist(projectDir: string, target: string): string {
 server.registerTool(
   "openuispec_check",
   {
-    description: "Run composite validation + post-generation audit. Returns schema validation results AND a concrete audit checklist derived from your spec files — listing every contract must_handle item, every screen section, and every locale file that must exist in your generated code. Verify each item.",
-    inputSchema: { target: targetSchema },
+    description: "Run composite validation + post-generation audit. Returns schema validation results AND a concrete audit checklist derived from your spec files — listing every contract must_handle item, every screen section, and every locale file that must exist in your generated code. Verify each item. Use optional screens/contracts params to scope the audit to specific items (validation still runs on all files).",
+    inputSchema: {
+      target: targetSchema,
+      screens: z.array(z.string()).optional().describe("Screen names to audit (e.g. ['home_feed', 'settings']). If omitted, audits all screens."),
+      contracts: z.array(z.string()).optional().describe("Contract names to audit (e.g. ['action_trigger']). If omitted, audits all contracts."),
+    },
   },
-  async ({ target }) => {
+  async ({ target, screens, contracts }) => {
     try {
       const result = buildCheckResult(target, projectCwd);
       const projectDir = findProjectDir(projectCwd);
-      const audit = buildAuditChecklist(projectDir, target);
+      const screenFilter = screens && screens.length > 0 ? screens : undefined;
+      const contractFilter = contracts && contracts.length > 0 ? contracts : undefined;
+      const audit = buildAuditChecklist(projectDir, target, screenFilter, contractFilter);
       return {
         content: [
           { type: "text" as const, text: JSON.stringify(result, null, 2) },
@@ -432,6 +460,208 @@ server.registerTool(
   }
 );
 
+// ── tool: openuispec_get_screen ──────────────────────────────────────
+
+server.registerTool(
+  "openuispec_get_screen",
+  {
+    description: "Get the parsed content of a single screen spec file. Faster than read_specs when you only need one screen.",
+    inputSchema: {
+      name: z.string().describe("Screen name, e.g. 'home_feed' (matches filename without .yaml)"),
+    },
+  },
+  async ({ name }) => {
+    try {
+      const projectDir = findProjectDir(projectCwd);
+      const manifest = YAML.parse(fsReadFileSync(join(projectDir, "openuispec.yaml"), "utf-8"));
+      const screensDir = resolveSpecDir(projectDir, manifest, "screens");
+      const filePath = join(screensDir, `${name}.yaml`);
+      if (!existsSync(filePath)) {
+        return toolError(`Screen "${name}" not found. Expected file: ${filePath}`);
+      }
+      const content = fsReadFileSync(filePath, "utf-8");
+      return toolResult({ name, path: relative(projectDir, filePath), content });
+    } catch (err) {
+      return toolError(err);
+    }
+  }
+);
+
+// ── tool: openuispec_get_contract ───────────────────────────────────
+
+server.registerTool(
+  "openuispec_get_contract",
+  {
+    description: "Get a single contract spec, optionally filtered to one variant. Faster than read_specs when you only need one contract.",
+    inputSchema: {
+      name: z.string().describe("Contract name, e.g. 'action_trigger'"),
+      variant: z.string().optional().describe("Optional variant name, e.g. 'fab'. If given, returns only that variant's definition."),
+    },
+  },
+  async ({ name, variant }) => {
+    try {
+      const projectDir = findProjectDir(projectCwd);
+      const manifest = YAML.parse(fsReadFileSync(join(projectDir, "openuispec.yaml"), "utf-8"));
+      const contractsDir = resolveSpecDir(projectDir, manifest, "contracts");
+
+      if (!existsSync(contractsDir)) {
+        return toolError(`Contracts directory not found: ${contractsDir}`);
+      }
+
+      // Scan contract files for the matching contract key
+      for (const file of readdirSync(contractsDir).filter(f => f.endsWith(".yaml")).sort()) {
+        const filePath = join(contractsDir, file);
+        const raw = fsReadFileSync(filePath, "utf-8");
+        const content = YAML.parse(raw);
+        const contractName = Object.keys(content)[0];
+        if (contractName !== name) continue;
+
+        if (variant) {
+          const contract = content[contractName];
+          const variantDef = contract?.variants?.[variant];
+          if (!variantDef) {
+            return toolError(`Variant "${variant}" not found in contract "${name}". Available variants: ${Object.keys(contract?.variants ?? {}).join(", ")}`);
+          }
+          return toolResult({ name, variant, definition: variantDef });
+        }
+
+        return toolResult({ name, path: relative(projectDir, filePath), content: raw });
+      }
+
+      return toolError(`Contract "${name}" not found in ${contractsDir}`);
+    } catch (err) {
+      return toolError(err);
+    }
+  }
+);
+
+// ── tool: openuispec_get_tokens ─────────────────────────────────────
+
+server.registerTool(
+  "openuispec_get_tokens",
+  {
+    description: "Get tokens for a specific category (color, typography, spacing, elevation, motion, layout, themes, icons). Faster than read_specs when you only need one token file.",
+    inputSchema: {
+      category: z.string().describe("Token category, e.g. 'color', 'typography', 'spacing', 'elevation', 'motion', 'layout', 'themes', 'icons'"),
+    },
+  },
+  async ({ category }) => {
+    try {
+      const projectDir = findProjectDir(projectCwd);
+      const manifest = YAML.parse(fsReadFileSync(join(projectDir, "openuispec.yaml"), "utf-8"));
+      const tokensDir = resolveSpecDir(projectDir, manifest, "tokens");
+
+      if (!existsSync(tokensDir)) {
+        return toolError(`Tokens directory not found: ${tokensDir}`);
+      }
+
+      // Try exact match first, then scan for files containing the category name
+      const candidates = [
+        `${category}.yaml`,
+        `${category}.yml`,
+      ];
+
+      for (const candidate of candidates) {
+        const filePath = join(tokensDir, candidate);
+        if (existsSync(filePath)) {
+          const content = fsReadFileSync(filePath, "utf-8");
+          return toolResult({ category, path: relative(projectDir, filePath), content });
+        }
+      }
+
+      // List available token files for helpful error
+      const available = readdirSync(tokensDir)
+        .filter(f => f.endsWith(".yaml") || f.endsWith(".yml"))
+        .map(f => f.replace(/\.ya?ml$/, ""));
+      return toolError(`Token category "${category}" not found. Available: ${available.join(", ")}`);
+    } catch (err) {
+      return toolError(err);
+    }
+  }
+);
+
+// ── tool: openuispec_get_locale ─────────────────────────────────────
+
+server.registerTool(
+  "openuispec_get_locale",
+  {
+    description: "Get a single locale file, optionally filtered to specific keys. Faster than read_specs when you only need one locale or specific translation keys.",
+    inputSchema: {
+      locale: z.string().describe("Locale code, e.g. 'en', 'ru'"),
+      keys: z.array(z.string()).optional().describe("Optional list of keys to filter to, e.g. ['nav.home', 'nav.create']. If omitted, returns the full locale file."),
+    },
+  },
+  async ({ locale, keys }) => {
+    try {
+      const projectDir = findProjectDir(projectCwd);
+      const manifest = YAML.parse(fsReadFileSync(join(projectDir, "openuispec.yaml"), "utf-8"));
+      const localesDir = resolveSpecDir(projectDir, manifest, "locales");
+      const filePath = join(localesDir, `${locale}.json`);
+
+      if (!existsSync(filePath)) {
+        if (existsSync(localesDir)) {
+          const available = readdirSync(localesDir)
+            .filter(f => f.endsWith(".json"))
+            .map(f => f.replace(/\.json$/, ""));
+          return toolError(`Locale "${locale}" not found. Available: ${available.join(", ")}`);
+        }
+        return toolError(`Locales directory not found: ${localesDir}`);
+      }
+
+      const raw = fsReadFileSync(filePath, "utf-8");
+      const content = JSON.parse(raw);
+
+      if (keys && keys.length > 0) {
+        const filtered: Record<string, unknown> = {};
+        for (const key of keys) {
+          if (key in content) {
+            filtered[key] = content[key];
+          }
+        }
+        return toolResult({ locale, path: relative(projectDir, filePath), content: filtered });
+      }
+
+      return toolResult({ locale, path: relative(projectDir, filePath), content });
+    } catch (err) {
+      return toolError(err);
+    }
+  }
+);
+
+// ── tool: openuispec_screenshot ──────────────────────────────────────
+
+server.registerTool(
+  "openuispec_screenshot",
+  {
+    description: "Take a screenshot of the generated web app at a specific route. Starts the Vite dev server automatically if needed (first call may take longer). Returns a PNG image for visual verification of generated UI. Requires puppeteer to be installed (npm install -g puppeteer).",
+    inputSchema: {
+      route: z.string().default("/").describe("Route path to navigate to, e.g. '/home', '/settings', '/posts/123'"),
+      viewport: z.object({
+        width: z.number().default(1280),
+        height: z.number().default(800),
+      }).optional().describe("Viewport dimensions. Defaults to 1280x800. Use {width: 375, height: 812} for mobile."),
+      theme: z.enum(["light", "dark"]).optional().describe("Force a color scheme via prefers-color-scheme emulation"),
+      wait_for: z.number().optional().default(1000).describe("Milliseconds to wait after page load before screenshotting (default 1000)"),
+      full_page: z.boolean().optional().default(false).describe("Capture the full scrollable page instead of just the viewport"),
+      selector: z.string().optional().describe("CSS selector to screenshot a specific element instead of the full page"),
+    },
+  },
+  async ({ route, viewport, theme, wait_for, full_page, selector }) => {
+    try {
+      return await takeScreenshot(projectCwd, {
+        route,
+        viewport,
+        theme,
+        wait_for,
+        full_page,
+        selector,
+      });
+    } catch (err) {
+      return toolError(err);
+    }
+  }
+);
+
 // ── start server ─────────────────────────────────────────────────────
 
 export async function startMcpServer() {

package/mcp-server/screenshot.ts

@@ -0,0 +1,262 @@
+/**
+ * Screenshot tool — launches dev server + headless browser, captures pages.
+ *
+ * Both the Vite dev server and the Puppeteer browser are kept alive between
+ * calls and torn down when the MCP server process exits.
+ */
+
+import { spawn, type ChildProcess, execSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { createServer, type AddressInfo } from "node:net";
+import YAML from "yaml";
+import { findProjectDir } from "../drift/index.js";
+
+// ── types ───────────────────────────────────────────────────────────
+
+export interface ScreenshotOptions {
+  route: string;
+  viewport?: { width: number; height: number };
+  theme?: "light" | "dark";
+  wait_for?: number;
+  full_page?: boolean;
+  selector?: string;
+}
+
+export interface ScreenshotResult {
+  content: Array<{ type: "text"; text: string } | { type: "image"; data: string; mimeType: string }>;
+  isError?: true;
+}
+
+// ── free port finder ────────────────────────────────────────────────
+
+function findFreePort(): Promise<number> {
+  return new Promise((resolve, reject) => {
+    const srv = createServer();
+    srv.listen(0, () => {
+      const port = (srv.address() as AddressInfo).port;
+      srv.close(() => resolve(port));
+    });
+    srv.on("error", reject);
+  });
+}
+
+// ── web app directory discovery ─────────────────────────────────────
+
+export function findWebAppDir(projectCwd: string): string {
+  const projectDir = findProjectDir(projectCwd);
+  const manifestPath = join(projectDir, "openuispec.yaml");
+  const manifest = YAML.parse(readFileSync(manifestPath, "utf-8"));
+  const projectName = manifest.project?.name ?? "app";
+
+  // Check custom output_dir first
+  const customDir = manifest.generation?.output_dir?.web;
+  if (customDir) {
+    const resolved = resolve(projectDir, customDir);
+    if (existsSync(join(resolved, "package.json"))) return resolved;
+  }
+
+  // Default: generated/web/<project-name>/
+  // Try from the project root (parent of openuispec/)
+  const projectRoot = resolve(projectDir, "..");
+  const defaultDir = join(projectRoot, "generated", "web", projectName);
+  if (existsSync(join(defaultDir, "package.json"))) return defaultDir;
+
+  throw new Error(
+    `Web app not found. Checked:\n` +
+    (customDir ? `  - ${resolve(projectDir, customDir)}\n` : "") +
+    `  - ${defaultDir}\n` +
+    `Generate the web target first, then try again.`,
+  );
+}
+
+// ── dev server manager ──────────────────────────────────────────────
+
+interface ServerInstance {
+  process: ChildProcess;
+  port: number;
+  url: string;
+}
+
+const servers = new Map<string, ServerInstance>();
+
+function ensureDepsInstalled(webDir: string): void {
+  if (existsSync(join(webDir, "node_modules"))) return;
+  try {
+    execSync("npm install", { cwd: webDir, stdio: "pipe", timeout: 90_000 });
+  } catch (err) {
+    throw new Error(`Failed to install web app dependencies in ${webDir}: ${err instanceof Error ? err.message : err}`);
+  }
+}
+
+async function startDevServer(webDir: string): Promise<ServerInstance> {
+  const existing = servers.get(webDir);
+  if (existing) {
+    // Verify still running
+    if (existing.process.exitCode === null) return existing;
+    servers.delete(webDir);
+  }
+
+  ensureDepsInstalled(webDir);
+  const port = await findFreePort();
+
+  const child = spawn("npx", ["vite", "--port", String(port), "--strictPort"], {
+    cwd: webDir,
+    stdio: ["ignore", "pipe", "pipe"],
+    env: { ...process.env, FORCE_COLOR: "0", BROWSER: "none" },
+  });
+
+  // Wait for "Local:" line from Vite
+  const stripAnsi = (s: string) => s.replace(/\x1b\[[0-9;]*m/g, "");
+
+  const url = await new Promise<string>((resolveUrl, reject) => {
+    const timeout = setTimeout(() => {
+      child.kill();
+      reject(new Error("Vite dev server failed to start within 30s"));
+    }, 30_000);
+
+    let output = "";
+    const onData = (chunk: Buffer) => {
+      output += chunk.toString();
+      const clean = stripAnsi(output);
+      const match = clean.match(/Local:\s+(https?:\/\/[^\s]+)/);
+      if (match) {
+        clearTimeout(timeout);
+        child.stdout?.off("data", onData);
+        child.stderr?.off("data", onData);
+        resolveUrl(match[1]);
+      }
+    };
+    child.stdout?.on("data", onData);
+    child.stderr?.on("data", onData);
+    child.on("error", (err) => { clearTimeout(timeout); reject(err); });
+    child.on("exit", (code) => {
+      clearTimeout(timeout);
+      if (!output.includes("Local:")) {
+        reject(new Error(`Vite exited with code ${code} before ready. Output:\n${output.slice(-500)}`));
+      }
+    });
+  });
+
+  const instance: ServerInstance = { process: child, port, url };
+  servers.set(webDir, instance);
+  return instance;
+}
+
+// ── browser manager ─────────────────────────────────────────────────
+
+let browserInstance: any = null;
+
+async function getBrowser(): Promise<any> {
+  if (browserInstance?.connected) return browserInstance;
+
+  let puppeteer: any;
+  try {
+    puppeteer = await import("puppeteer");
+  } catch {
+    throw new Error(
+      "puppeteer is not installed. Run:\n  npm install -g puppeteer\n" +
+      "or add it to your project's devDependencies.",
+    );
+  }
+
+  browserInstance = await puppeteer.launch({
+    headless: true,
+    args: ["--no-sandbox", "--disable-setuid-sandbox"],
+  });
+  return browserInstance;
+}
+
+// ── screenshot capture ──────────────────────────────────────────────
+
+export async function takeScreenshot(
+  projectCwd: string,
+  options: ScreenshotOptions,
+): Promise<ScreenshotResult> {
+  const {
+    route = "/",
+    viewport = { width: 1280, height: 800 },
+    theme,
+    wait_for = 1000,
+    full_page = false,
+    selector,
+  } = options;
+
+  // 1. Find and start
+  const webDir = findWebAppDir(projectCwd);
+  const server = await startDevServer(webDir);
+  const browser = await getBrowser();
+
+  // 2. Navigate
+  const page = await browser.newPage();
+  try {
+    await page.setViewport({ width: viewport.width, height: viewport.height });
+
+    if (theme) {
+      await page.emulateMediaFeatures([
+        { name: "prefers-color-scheme", value: theme },
+      ]);
+    }
+
+    const base = server.url.replace(/\/+$/, "");
+    const targetUrl = `${base}${route.startsWith("/") ? "" : "/"}${route}`;
+    await page.goto(targetUrl, { waitUntil: "networkidle2", timeout: 30_000 });
+
+    if (wait_for > 0) {
+      await new Promise((r) => setTimeout(r, wait_for));
+    }
+
+    // 3. Screenshot
+    let buffer: Buffer;
+    if (selector) {
+      const element = await page.$(selector);
+      if (!element) {
+        return {
+          content: [{ type: "text", text: `Error: Element not found for selector: ${selector}` }],
+          isError: true,
+        };
+      }
+      buffer = await element.screenshot({ type: "png" });
+    } else {
+      buffer = await page.screenshot({ type: "png", fullPage: full_page });
+    }
+
+    const base64 = buffer.toString("base64");
+
+    return {
+      content: [
+        { type: "image" as const, data: base64, mimeType: "image/png" },
+        {
+          type: "text" as const,
+          text: JSON.stringify({
+            route,
+            url: targetUrl,
+            viewport,
+            theme: theme ?? "default",
+            full_page,
+            selector: selector ?? null,
+          }, null, 2),
+        },
+      ],
+    };
+  } finally {
+    await page.close();
+  }
+}
+
+// ── cleanup ─────────────────────────────────────────────────────────
+
+export function shutdownAll() {
+  for (const [, instance] of servers) {
+    try { instance.process.kill(); } catch { /* already dead */ }
+  }
+  servers.clear();
+  if (browserInstance) {
+    try { browserInstance.close(); } catch { /* ignore */ }
+    browserInstance = null;
+  }
+}
+
+process.on("exit", shutdownAll);
+process.on("SIGINT", () => { shutdownAll(); process.exit(0); });
+process.on("SIGTERM", () => { shutdownAll(); process.exit(0); });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openuispec",
-  "version": "0.1.46",
+  "version": "0.2.0",
   "license": "MIT",
   "type": "module",
   "description": "A semantic UI specification format for AI-native, platform-native app development",
@@ -49,6 +49,9 @@
     "tsx": "^4.19.4",
     "yaml": "^2.7.1"
   },
+  "optionalDependencies": {
+    "puppeteer": "^24.39.1"
+  },
   "devDependencies": {
     "@types/node": "^25.5.0",
     "typescript": "^5.8.3"

package/schema/openuispec.schema.json

@@ -104,6 +104,13 @@
             "type": "string"
           }
         },
+        "extra_rules": {
+          "type": "array",
+          "description": "Project-wide authoring and generation conventions for AI, including optional scoped hint labels such as [common], [ios], [android], and [web].",
+          "items": {
+            "type": "string"
+          }
+        },
         "output_dir": {
           "type": "object",
           "description": "Per-target output directory (relative to openuispec.yaml). Defaults to generated/<target>/<project_name> if not set.",

package/spec/openuispec-v0.1.md

@@ -83,6 +83,8 @@ includes:
 
 generation:
   targets: [ios, android, web]
+  extra_rules:
+    - "Generation hint strings may start with [common], [ios], [android], or [web] to indicate scope."
   ai_model: "any"                    # no model lock-in
   output_format:
     ios: { language: swift, framework: swiftui }
@@ -3248,6 +3250,17 @@ ios:
 - Generate test code based on `test_cases`
 - Add platform-specific enhancements beyond what the contract specifies
 
+### Scoped generation hint labels
+
+Projects may declare authoring conventions in `generation.extra_rules` inside `openuispec.yaml`. One supported convention is prefixing generation hint strings with scope labels such as `[common]`, `[ios]`, `[android]`, and `[web]`. These labels are advisory authoring metadata for humans and AI; they do not change schema semantics unless downstream tooling chooses to interpret them.
+
+```yaml
+generation:
+  targets: [ios, android, web]
+  extra_rules:
+    - "Generation hint strings may start with [common], [ios], [android], or [web] to indicate scope."
+```
+
 ### 12.8 Extending standard contracts
 
 The 7 built-in contract families (Section 4) can be extended per-project using `contracts/<name>.yaml` files. Extensions add project-specific **variants**, **token overrides**, **platform mapping**, and **generation hints** without redefining the base contract. The base definition (props, states, a11y) remains authoritative from the spec.