stylegallery 0.1.6 → 0.1.7

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "stylegallery",
-  "version": "0.1.6",
-  "description": "A governed gallery of portable interface knowledge with deterministic CLIs and read-only MCP servers.",
+  "version": "0.1.7",
+  "description": "A governed gallery of portable interface knowledge with knowledge CLIs, website compilation, and MCP servers.",
   "type": "module",
+  "license": "MIT",
   "homepage": "https://github.com/changeroa/StyleGallery#readme",
   "bugs": {
     "url": "https://github.com/changeroa/StyleGallery/issues"
@@ -28,6 +29,9 @@
     "DOMAINS.md",
     "GOVERNANCE.md",
     "GUIDE.md",
+    "LICENSE",
+    "LICENSE-DOCS",
+    "NOTICE",
     "README.md",
     "consumer-reference/agent-native/README.md",
     "consumer-reference/agent-native/registry.json",
@@ -52,17 +56,44 @@
     "design-engineering/decision-tree.md",
     "design-engineering/index.md",
     "design-engineering/interface-craft.md",
+    "design-engineering/loading-and-feedback.md",
+    "design-engineering/native-interaction-contracts.md",
     "design-engineering/reference-profiles/governed-local/editorial/profile.json",
     "design-engineering/reference-profiles/governed-local/index.md",
     "design-engineering/reference-profiles/index.md",
+    "design-engineering/state-management/decision-tree.md",
+    "design-engineering/state-management/index.md",
+    "design-engineering/state-management/patterns/derived-state.md",
+    "design-engineering/state-management/patterns/draft-and-baseline.md",
+    "design-engineering/state-management/patterns/id-selection.md",
+    "design-engineering/state-management/patterns/identity-reset.md",
+    "design-engineering/state-management/patterns/latest-request-wins.md",
+    "design-engineering/state-management/patterns/optimistic-overlay.md",
+    "design-engineering/state-management/patterns/single-flight.md",
+    "design-engineering/state-management/patterns/single-owner.md",
+    "design-engineering/state-management/patterns/submitted-snapshot.md",
+    "design-engineering/state-management/patterns/unsaved-navigation.md",
+    "design-engineering/state-management/patterns/url-state.md",
+    "design-engineering/state-management/patterns/versioned-restore.md",
+    "design-engineering/state-management/recipes/delete-undo.md",
+    "design-engineering/state-management/recipes/index.md",
+    "design-engineering/state-management/recipes/multi-step-form.md",
+    "design-engineering/state-management/recipes/search-detail.md",
+    "design-engineering/state-management/recipes/settings-save.md",
+    "design-engineering/state-management/state-brief.md",
+    "design-engineering/state-management/verification.md",
+    "design-engineering/text-input-and-internationalization.md",
     "design-engineering/worked-examples.md",
     "design-terminology/comparison-workflow.md",
     "design-terminology/concept-families.md",
     "design-terminology/conflict-cases.md",
     "design-terminology/index.md",
+    "design-terminology/interaction-semantics.md",
     "design-terminology/relation-types.md",
     "design-terminology/source-kinds.md",
     "design-terminology/source-vocabularies.md",
+    "design-terminology/token-semantics.md",
+    "design-terminology/typography-semantics.md",
     "game-ui/classification.md",
     "game-ui/decision-tree.md",
     "game-ui/index.md",
@@ -83,11 +114,15 @@
     "index.md",
     "layout/index.md",
     "log.md",
+    "motion/accessible-motion.md",
     "motion/decision-tree.md",
     "motion/index.md",
     "motion/interaction-recipes.md",
+    "motion/interruption-and-retargeting.md",
     "motion/motion-brief.md",
+    "motion/observed-choreography.md",
     "motion/practice-reference.md",
+    "motion/rendering-and-performance.md",
     "motion/review-workflow.md",
     "motion/vocabulary.md",
     "patterns/centering/center.md",
@@ -147,10 +182,13 @@
     "patterns/viewport-shell/sticky-footer.md",
     "patterns/viewport-shell/sticky-header.md",
     "platform-guides/adaptation-workflow.md",
+    "platform-guides/adaptive-navigation.md",
     "platform-guides/android-interaction.md",
     "platform-guides/apple-interaction.md",
     "platform-guides/compatibility-matrix.md",
     "platform-guides/index.md",
+    "platform-guides/input-and-focus.md",
+    "platform-guides/preferences-and-accessibility.md",
     "platform-guides/windows-interaction.md",
     "quality/claim-records/design-terminology-domain-scope.md",
     "quality/claim-records/index.md",
@@ -214,19 +252,26 @@
     "scripts/agent-native/v2/material-operation-registry.mjs",
     "scripts/agent-native/v2/material-queries.mjs",
     "scripts/agent-native/v2/material-registry.mjs",
+    "scripts/compiler/README.md",
+    "scripts/compiler/cli.mjs",
+    "scripts/compiler/mcp.mjs",
+    "scripts/compiler/operations.mjs",
+    "scripts/compiler/runtime.mjs",
+    "scripts/sg-entry.mjs",
     "scripts/sg-material-mcp.mjs",
     "scripts/sg-material.mjs",
     "scripts/sg-mcp.mjs",
+    "scripts/sg-server.mjs",
     "scripts/sg.mjs",
     "scripts/strict-json.mjs"
   ],
   "bin": {
-    "sg": "scripts/sg.mjs",
+    "sg": "scripts/sg-entry.mjs",
     "sg-material": "scripts/sg-material.mjs",
-    "stylegallery": "scripts/sg.mjs",
+    "stylegallery": "scripts/sg-entry.mjs",
     "stylegallery-material": "scripts/sg-material.mjs",
     "stylegallery-material-mcp": "scripts/sg-material-mcp.mjs",
-    "stylegallery-mcp": "scripts/sg-mcp.mjs"
+    "stylegallery-mcp": "scripts/sg-server.mjs"
   },
   "publishConfig": {
     "access": "public"
@@ -251,13 +296,17 @@
     "test:material": "node scripts/agent-native/v2/test-material-admission.mjs && node scripts/agent-native/v2/test-material-registry.mjs && node scripts/agent-native/v2/test-material-query.mjs && node scripts/agent-native/v2/test-material-context.mjs && node scripts/agent-native/v2/test-sg-material-cli.mjs && node scripts/agent-native/v2/test-material-mcp.mjs && node scripts/agent-native/v2/test-material-mcp-stdio.mjs && node scripts/agent-native/v2/test-sg-material-package.mjs",
     "test:lifecycle-dispositions": "node scripts/test-lifecycle-disposition.mjs",
     "validate:lifecycle-dispositions": "node scripts/validate-lifecycle-disposition.mjs --json",
-    "sg": "node scripts/sg.mjs",
+    "sg": "node scripts/sg-entry.mjs",
     "sg:material": "node scripts/sg-material.mjs",
     "sg:material:mcp": "node scripts/sg-material-mcp.mjs",
-    "sg:mcp": "node scripts/sg-mcp.mjs",
+    "sg:mcp": "node scripts/sg-server.mjs",
     "test:agent-native": "node scripts/test-agent-knowledge-kernel.mjs --json && node scripts/test-agent-execution-kernel.mjs --json && node scripts/test-agent-execution-safety.mjs --json && node scripts/test-agent-events.mjs --json && node scripts/test-agent-learning.mjs --json && node scripts/test-agent-native-schemas.mjs --json && node scripts/test-sg-cli.mjs --json && node scripts/test-agent-conformance-receipt.mjs --json && node scripts/test-agent-mcp.mjs --json && node scripts/test-agent-registry-mcp-integrity.mjs --json && node scripts/test-agent-registry-mutations.mjs --json && node scripts/test-agent-adapter-conformance.mjs --json && node scripts/agent-native/v2/test-agent-extension-boundary.mjs && node scripts/test-agent-projections.mjs --json && node scripts/agent-native/v2/test-agent-v1-compatibility.mjs",
     "validate": "node scripts/validate-reference-artifacts.mjs --manifest consumer-reference/generated/manifest.json --json",
-    "validate:component-state": "node scripts/validate-component-state.mjs --json && node scripts/generate-consumer-reference-evidence.mjs --check --json"
+    "validate:component-state": "node scripts/validate-component-state.mjs --json && node scripts/generate-consumer-reference-evidence.mjs --check --json",
+    "test:state-management": "node --test scripts/test-state-management-examples.mjs",
+    "test:compiler": "node --test scripts/test-sg-compiler.mjs",
+    "sg:v1": "node scripts/sg.mjs",
+    "sg:mcp:v1": "node scripts/sg-mcp.mjs"
   },
   "devDependencies": {
     "@axe-core/playwright": "4.12.1",
@@ -270,5 +319,8 @@
     "@modelcontextprotocol/sdk": "1.29.0",
     "style-dictionary": "5.5.0",
     "zod": "4.4.3"
+  },
+  "overrides": {
+    "brace-expansion": "5.0.9"
   }
 }

package/platform-guides/adaptive-navigation.md

@@ -0,0 +1,85 @@
+---
+type: Domain Guide
+title: Adaptive Navigation Across Platforms
+description: Compare window adaptation, modal presentation, and Back ownership while preserving task identity across native and web surfaces.
+domain: platform-guides
+lifecycle: experimental
+provenance_kind: local
+platform: Apple applications, Android applications, Windows applications, and web adaptations
+platform_version: dated official documentation; consumer OS, SDK, and browser versions required
+reviewed_on: 2026-09-21
+---
+
+# Adaptive Navigation Across Platforms
+
+Primary role: comparative navigation and adaptation guide.
+
+## Repository Boundary
+
+This page compares named platform conventions. It owns no CSS breakpoints, product visuals, or shared navigation implementation. Layout remains responsible for spatial constraints; [State Management](../design-engineering/state-management/index.md) owns route identity, drafts, and persistence.
+
+## Reusable Method
+
+Describe the current task independently of presentation: selected object, query, draft, parent destination, and active blocking surface. Then name which of those facts must survive a window change. Choose the target presentation and its navigation contract from available space and task needs, rather than from a device label.
+
+### Dated Source Comparison
+
+| Platform source | Bounded observation | Web adaptation question |
+| --- | --- | --- |
+| [Apple HIG layout](https://developer.apple.com/design/human-interface-guidelines/layout) | The guidance covers changing windows/displays, system safe areas, and text-size changes. | Does the task survive a changed content area and larger text? |
+| [Apple HIG modality](https://developer.apple.com/design/human-interface-guidelines/modality) | Modal presentation is a scoped change of interaction context with dismissal obligations. | Which part of the workflow intentionally suspends background interaction? |
+| [Apple HIG popovers](https://developer.apple.com/design/human-interface-guidelines/popovers) | Popover guidance is platform-specific and recommends a different presentation in compact iOS/iPadOS views. | Can the presentation change while preserving the same edit and explicit close policy? |
+| [Android window size classes](https://developer.android.com/develop/ui/compose/layouts/adaptive/use-window-size-classes) | Width and height are classified separately from available app space. The reviewed page includes compact, medium, expanded, large, and extra-large width classes. | Does the decision consider usable height as well as width? |
+| [Android predictive Back](https://developer.android.com/guide/navigation/custom-back/predictive-back-gesture) | Enabled callbacks have scoped Back responsibilities; gesture handling and observation are distinct concerns. | Which active layer consumes Back, and does observation accidentally change navigation? |
+| [Windows responsive techniques](https://learn.microsoft.com/en-us/windows/apps/design/layout/responsive-design) | Adaptation can change composition and presentation of controls as available space changes. | Does every required destination remain available after the transformation? |
+
+Read on 2026-09-21. These are live documentation snapshots, not SDK pins. Android's reviewed window guidance was updated 2026-08-04 and predictive Back guidance 2026-09-18. Apple page bodies were inspected through their official documentation JSON because the HTML reader exposed a JavaScript shell. Native implementation claims require a named OS/API and an actual native run.
+
+### Navigation Actions Are Different Operations
+
+| Action | State it should address | Failure from conflation |
+| --- | --- | --- |
+| Browser/native Back | Navigation history according to the host contract | Closing a dialog and leaving the route in one action. |
+| Parent/Up navigation | A defined parent destination | Assuming a direct-link visitor has a matching history entry. |
+| Surface dismissal | Visibility and ownership of a temporary surface | Discarding a draft because a surface resized or changed form. |
+| Operation cancellation | The actual pending operation and its acknowledgement | A closing animation falsely reports that a write was cancelled. |
+| Selection change | Identity of the item being inspected | Selecting another item silently overwrites unsaved work. |
+
+This table is a local comparison framework, not a common native dispatch algorithm. Each host retains its own semantics.
+
+### Worked Adaptation: Detail Pane Becomes A Route
+
+A document browser shows list and detail together when both fit. With less room, the selected document occupies the primary view. Record the selection once and derive presentation from it. Preserve the list query and any draft; do not create a second editor instance solely because a presentation boundary changed.
+
+If a selection is encoded in the URL, decide whether presenting the same selection in a second pane creates a navigation event. A resize itself should not invent a new task history entry under this proposal. Direct links, browser refresh, and a missing selected document need explicit outcomes.
+
+When a popover becomes a modal editor, re-evaluate focus containment and dismissal. A stored boolean such as `isPopoverOpen` does not describe whether the current surface is modal, what it edits, or which host receives Back. Represent the task and presentation separately.
+
+## Opinionated Guidance
+
+Prefer task-preserving transformations: keep identity and editable data stable while rearranging presentation. Define navigation with state transitions that a reviewer can inspect. Avoid copying a platform's numeric size boundaries into CSS without a separate content-fit rationale.
+
+## Platform-Specific Guidance
+
+Android density-independent units, Apple points/safe areas, Windows effective sizing, and browser CSS pixels belong to different target contracts. A visual resemblance does not establish unit equivalence. On the web, use [Layout's existing routes](../layout/index.md) to choose the spatial composition and verify it at the actual parent constraints.
+
+Predictive Back progress and cancellation are native host behavior. A browser animation cannot by itself claim equivalent integration. For keyboard and focus adaptation, continue to [Input And Focus](input-and-focus.md).
+
+## Unsupported Absolutes
+
+A wide window does not identify a desktop device. A compact surface does not require a particular native component. A native Back callback is not interchangeable with browser history. A successful resize screenshot does not prove state continuity.
+
+## Verification Contract
+
+Proposed cases: resize while editing; open a direct detail link; navigate Back with an inner dialog open; cancel a native Back gesture; rotate with an onscreen keyboard present; enlarge text until a two-pane arrangement no longer fits; remove the selected item remotely.
+
+For each case, record route/history, selected identity, draft value, active surface, and focused element before and after. Native claims need native execution; browser cases establish only the browser adaptation. No native or web execution is claimed here. Re-review when a cited convention, SDK, or navigation owner changes.
+
+## Source, License, And Attribution
+
+Locally authored synthesis of the linked Apple, Google, and Microsoft documentation, inspected 2026-09-21. No platform artwork, code, or distinctive source examples are reproduced. `consumer_reference: not_applicable` because no consumer navigation record is selected.
+
+## IA Navigation
+
+Parent: [Platform Guides](index.md).
+Next: [Preferences And Accessibility](preferences-and-accessibility.md).

package/platform-guides/index.md

@@ -27,6 +27,12 @@ These workflows and worked cases are usable experimental guidance. Expected-resu
 
 A platform guide names the platform, source authority, version or review date, web-adaptation boundary, and local verification protocol. Similar appearance or behavior does not establish affiliation or correctness.
 
+## Source-Backed Deep Dives
+
+- [Adaptive Navigation Across Platforms](adaptive-navigation.md). Preserve task state across window and navigation transformations.
+- [Preferences And Accessibility Across Platforms](preferences-and-accessibility.md). Compare text scaling, contrast, motion, and transparency independently.
+- [Input And Focus Across Platforms](input-and-focus.md). Compare keyboard, pointer, drag alternatives, and focus contracts.
+
 ## Domain Contract
 
 See [StyleGallery Domains](../DOMAINS.md) for lifecycle, provenance, page membership, and staleness rules.

package/platform-guides/input-and-focus.md

@@ -0,0 +1,91 @@
+---
+type: Domain Guide
+title: Input And Focus Across Platforms
+description: Compare keyboard, pointing, dragging, focus, and target conventions using named native and web contracts.
+domain: platform-guides
+lifecycle: experimental
+provenance_kind: local
+platform: Apple applications, Android Compose, Windows applications, and web adaptations
+platform_version: dated official documentation; consumer OS, input device, and browser versions required
+reviewed_on: 2026-09-21
+---
+
+# Input And Focus Across Platforms
+
+Primary role: comparative input and focus guide.
+
+## Repository Boundary
+
+This page compares platform interaction contracts. It does not make one platform's shortcuts, target dimensions, or focus model universal. Layout owns logical spatial order; Design Engineering owns the [component behavior](../design-engineering/native-interaction-contracts.md); shared quality owns accessibility evidence.
+
+## Reusable Method
+
+For each task, identify the action, focused or selected object, available input paths, and owner of cancellation. Distinguish moving focus, moving selection, changing a value, and invoking a command. Then compare the target platform's expected behavior with the proposed adaptation.
+
+### Platform And Web Sources
+
+| Source | Bounded finding | Adaptation question |
+| --- | --- | --- |
+| [Apple HIG keyboards](https://developer.apple.com/design/human-interface-guidelines/keyboards) | Keyboard guidance includes text entry and discoverable, platform-appropriate shortcuts. | Which commands remain discoverable without knowing a shortcut? |
+| [Apple HIG pointing devices](https://developer.apple.com/design/human-interface-guidelines/pointing-devices) | Pointer interaction is a named platform concern alongside other input. | Does pointer feedback preserve the same task as touch or keyboard input? |
+| [Android Compose keyboard actions](https://developer.android.com/develop/ui/compose/touch-input/keyboard-input/commands) | Editing components have default key behavior; key handlers can consume or propagate events. | Does a parent handler steal a key from an editor or child control? |
+| [Windows keyboard interactions](https://learn.microsoft.com/en-us/windows/apps/develop/input/keyboard-interactions) | The guidance distinguishes navigation, commands, and visible focus for keyboard use. | Are command invocation and focus navigation separate and predictable? |
+| [APG keyboard interface](https://www.w3.org/WAI/ARIA/apg/practices/keyboard-interface/) | Composite widgets have internal navigation conventions; focus and selection are distinct. | Is the chosen widget model actually implemented, including entry and exit? |
+| [Pointer Events Level 3](https://www.w3.org/TR/pointerevents3/) | Pointer events model multiple pointing inputs, capture, and cancellation. | Does cancellation leave a coherent drag state and release ownership? |
+
+Read on 2026-09-21. Apple source bodies were inspected through the official documentation JSON. APG is informative guidance; Pointer Events is a standards-track source. Actual input behavior requires a named OS/browser/device combination.
+
+### Web Accessibility Conditions To Keep Separate
+
+| Source | Bounded condition | Local probe |
+| --- | --- | --- |
+| [Keyboard, SC 2.1.1](https://www.w3.org/WAI/WCAG22/Understanding/keyboard.html) | Functionality needs keyboard operability, with the criterion's scoped exception. | Complete the task without a pointing device. |
+| [Dragging Movements, SC 2.5.7](https://www.w3.org/WAI/WCAG22/Understanding/dragging-movements.html) | Dragging functionality needs a single-pointer alternative without dragging, subject to exceptions. | Try a click/tap alternative as well as keyboard operation. |
+| [Target Size Minimum, SC 2.5.8](https://www.w3.org/WAI/WCAG22/Understanding/target-size-minimum.html) | The AA criterion specifies 24 by 24 CSS pixels or its stated exceptions, including a defined spacing alternative. | Evaluate the actual hit region and nearby targets, not only the icon. |
+| [Hover Or Focus Content, SC 1.4.13](https://www.w3.org/WAI/WCAG22/Understanding/content-on-hover-or-focus.html) | Additional content has dismissibility, hoverability, and persistence conditions with scoped exceptions. | Move onto the revealed content and dismiss it without losing the task. |
+| [Focus Order, SC 2.4.3](https://www.w3.org/WAI/WCAG22/Understanding/focus-order.html) | Sequential focus order must preserve meaning and operation where order matters. | Follow focus through the actual rendered structure. |
+| [Focus Not Obscured Minimum, SC 2.4.11](https://www.w3.org/WAI/WCAG22/Understanding/focus-not-obscured-minimum.html) | At AA, an author-created surface must not entirely hide the focused component. | Open sticky and overlay surfaces while moving focus. |
+
+These Understanding documents explain normative WCAG requirements. The minimum target criterion is not a universal product target size; native units and platform recommendations need their own rationale. Keyboard access and a no-drag single-pointer alternative answer different conditions.
+
+### Worked Adaptation: Reorder An Item
+
+The product offers a drag handle and chooses a Move action with explicit destinations as its alternative. All paths call the same reorder operation with stable item identity. Focus stays on the moved item or on a documented successor, and the result is exposed without relying solely on movement.
+
+| Path | Ownership decision | Failure to catch |
+| --- | --- | --- |
+| Pointer drag | Capture, drop eligibility, and cancelled-drag outcome | A cancelled pointer stream leaves the item detached. |
+| Click/tap Move | Destination choice and confirmation | The alternative still requires a hidden drag gesture. |
+| Keyboard | Widget navigation and command activation | Arrow keys move the page and item simultaneously. |
+| Assistive technology | Name, action, current position, and resulting state | The visual reorder is absent from the semantic order. |
+
+This is a local proposal. It does not prescribe one keyboard shortcut or say that every list must be a composite ARIA widget.
+
+## Opinionated Guidance
+
+Use shortcuts to accelerate visible actions. Scope listeners to the intended surface, and let text editing and composition retain their own keys. Give each cancellation action one clearly documented owner before allowing it to propagate outward.
+
+## Platform-Specific Guidance
+
+Primary pointer and hover media features describe capabilities, not an exclusive device category; hybrid input requires an actual interaction matrix. System/browser shortcuts and assistive-technology commands may already own a key combination. Record the platform conflict check instead of translating Control to Command mechanically.
+
+For IME-sensitive keys, follow [Text Input And Internationalization](../design-engineering/text-input-and-internationalization.md). For drag presentation after cancellation, follow [Interruption And Retargeting](../motion/interruption-and-retargeting.md).
+
+## Unsupported Absolutes
+
+Keyboard support alone does not satisfy the no-drag pointer condition. Visible focus does not prove focus order. A large icon does not prove a large hit region. A touch-capable device does not imply that hover or keyboard input is absent.
+
+## Verification Contract
+
+Use actual task sequences with keyboard, pointer, touch where supported, and relevant assistive technology. Record input mode changes mid-task, cancelled drag, focus after item removal, nested Escape, hover-to-content movement, and overlays covering the focus target.
+
+These cases are unexecuted. Synthetic events can validate handlers but do not establish physical input or assistive-technology integration. Re-review when command scope, component roles, or target input support changes.
+
+## Source, License, And Attribution
+
+Locally authored synthesis of the linked first-party sources, inspected 2026-09-21. No native interaction artwork, source examples, or code are copied. `consumer_reference: not_applicable` because no consumer input record is selected.
+
+## IA Navigation
+
+Parent: [Platform Guides](index.md).
+Next: [Platform Compatibility Matrix](compatibility-matrix.md).

package/platform-guides/preferences-and-accessibility.md

@@ -0,0 +1,90 @@
+---
+type: Domain Guide
+title: Preferences And Accessibility Across Platforms
+description: Compare text scaling, motion, contrast, transparency, and accessibility semantics without collapsing distinct user preferences.
+domain: platform-guides
+lifecycle: experimental
+provenance_kind: local
+platform: Apple applications, Android Compose, Windows applications, and web adaptations
+platform_version: dated official documentation; consumer OS, framework, and browser versions required
+reviewed_on: 2026-09-21
+---
+
+# Preferences And Accessibility Across Platforms
+
+Primary role: comparative preference and accessibility adaptation guide.
+
+## Repository Boundary
+
+This guide compares what named platforms expose and the questions a consumer must answer. Shared [accessibility evidence](../quality/evidence/accessibility.md) governs conformance. Product color, typography, transparency, and motion remain consumer-owned; this page supplies no visual defaults to Layout.
+
+## Reusable Method
+
+Inventory each preference as a separate input. Name its source, application override policy, affected components, and update behavior. Specify a usable base presentation for targets that do not expose a particular signal. Then test meaningful combinations rather than treating “accessibility mode” as one boolean.
+
+### Source Findings
+
+| Source | Bounded finding | Transfer boundary |
+| --- | --- | --- |
+| [Apple HIG accessibility](https://developer.apple.com/design/human-interface-guidelines/accessibility) | The guidance addresses larger text, VoiceOver descriptions, multiple information channels, and response to Reduce Motion. | Native support depends on the implementation; a web font choice does not implement Dynamic Type. |
+| [Apple HIG materials](https://developer.apple.com/design/human-interface-guidelines/materials) | Material behavior can respond to appearance and accessibility settings, including transparency and contrast. | A CSS blur copied from a screenshot does not inherit native material behavior. |
+| [Android Compose accessibility](https://developer.android.com/develop/ui/compose/accessibility) | Compose exposes semantics and accessibility support that custom components must preserve. | A drawn label is not by itself an accessibility semantic node. |
+| [Windows contrast themes](https://learn.microsoft.com/en-us/windows/apps/design/accessibility/high-contrast-themes) | Contrast themes use system color roles and can change while an app runs. | A single hard-coded dark palette is not the Windows contrast-theme contract. |
+| [Media Queries Level 5](https://www.w3.org/TR/mediaqueries-5/#mf-user-preferences) | Color scheme, reduced motion, contrast, and reduced transparency are separate preference features. | Support must be checked per feature and target; one query does not imply another. |
+| [CSS Color Adjustment](https://www.w3.org/TR/css-color-adjust-1/#forced-colors-mode) | Forced colors can replace author colors with a user-selected palette and adjust effects. | Preserve meaningful distinctions when author decoration changes or disappears. |
+
+Read on 2026-09-21. Apple documentation bodies were inspected through the official documentation JSON. These living platform pages and standards-track publications are dated readings, not proof that all named features exist in a selected OS/browser release.
+
+### Preference Resolution
+
+Record “follow system” separately from an explicit in-product selection. Define which setting currently determines the presentation and how users return to system behavior. Do not use one persisted theme name to infer motion, contrast, or text-size preferences.
+
+For web forced colors, verify semantic system-color pairings and visible boundaries rather than preserving brand appearance at any cost. Any local exception to automatic color adjustment needs a stated reason and target evidence. For reduced transparency without a supported media feature, the base surface still needs to make its content legible.
+
+### Text Scaling Is A Behavior Change
+
+[Reflow](https://www.w3.org/WAI/WCAG22/Understanding/reflow.html) concerns preserving information and function when content is presented in a narrow equivalent viewport, with scoped exceptions. [Text Spacing](https://www.w3.org/WAI/WCAG22/Understanding/text-spacing.html) concerns loss of content or function when users override specified spacing. Neither criterion means that every interface must have the same default type scale.
+
+Local proposal: treat text scaling as a reason to reconsider composition, not merely multiply font sizes. A toolbar can need wrapping or a different command presentation; a dialog may need a scrollable reading area; a short title can become several lines. Those spatial choices go to Layout, while label priorities and command availability stay in the product.
+
+### Combination Matrix
+
+| Combination | Failure to probe | Observable result to retain |
+| --- | --- | --- |
+| Dark appearance with forced colors | The app assumes its dark palette remains authoritative. | Text, selection, links, and focus remain distinguishable. |
+| Larger text with compact window | Fixed control bounds clip names or actions. | Full task remains possible without losing required information. |
+| Reduced motion during pending work | The indicator disappears without an equivalent waiting state. | Pending and completed states remain understandable. |
+| Reduced transparency over rich content | A custom surface depends on blur alone for separation. | Foreground content remains legible with the chosen fallback. |
+| Screen reader with changing result set | Decorative text changes lack meaningful semantics. | The selected task and concise result status are exposed correctly. |
+| Runtime preference change | Only newly mounted components update. | Existing dialogs, portals, and embedded surfaces follow their declared policy. |
+
+These are proposed probes, not a statement that all combinations are exposed by every OS. Record unavailable combinations as not applicable with a reason.
+
+## Opinionated Guidance
+
+Make preference ownership explicit and keep the base experience usable. Avoid adding a single “accessible theme” that quietly overrides unrelated preferences. Use product settings to provide clear user control where platform signals are absent or insufficient.
+
+## Platform-Specific Guidance
+
+Native text scaling, browser zoom, author font settings, and OS display scaling can affect different layers. Name which mechanism was changed in a test. Likewise, simulated CSS media features establish a code path, while an actual OS setting additionally exercises host integration.
+
+Use [Accessible Motion](../motion/accessible-motion.md) for motion replacement and [Typography Semantics](../design-terminology/typography-semantics.md) for source-specific type-style meanings.
+
+## Unsupported Absolutes
+
+Dark mode is not forced colors. A contrast preference is not a contrast measurement. Removing blur does not guarantee legibility. Passing one text-size case does not prove all localization and scaling combinations.
+
+## Verification Contract
+
+Record the actual system setting, application override, media/API observation, and effective component state. Test before load and while a dialog or asynchronous operation is active. Compare semantic and visual evidence for the same state; do not substitute an accessibility-tree snapshot for an announcement test.
+
+This documentation defines unexecuted cases. It makes no native accessibility or browser conformance claim. Re-review when a source, preference-resolution rule, or target platform changes.
+
+## Source, License, And Attribution
+
+Locally authored synthesis of the linked first-party sources, inspected 2026-09-21. No platform values or assets are imported. `consumer_reference: not_applicable` because no consumer preference or profile record is selected.
+
+## IA Navigation
+
+Parent: [Platform Guides](index.md).
+Next: [Input And Focus](input-and-focus.md).

package/scripts/compiler/README.md

@@ -0,0 +1,112 @@
+---
+type: Interface Guide
+title: SG Website Compilation
+description: Run a separately installed website compiler through the SG CLI and MCP server.
+---
+
+# SG Website Compilation
+
+Primary role: compiler setup and execution reference.
+
+Use `sg compile`, `sg timeline`, and the other commands below directly. The `stylegallery-mcp` server exposes the same names alongside `discover`, `resolve`, `claims`, `context`, `ops`, and `retrieve`. Compiler operations can write files, open websites, and invoke a model; each tool declares those effects. The original [v1 knowledge interface](../../consumer-reference/agent-native/README.md) remains available separately.
+
+## Setup
+
+Install StyleGallery with Node.js 22 or newer using `npm install --global stylegallery`. For an unreleased StyleGallery checkout, run commands from that checkout as `npm run sg -- <command>` instead. If another program already owns the `sg` command, use the equivalent `stylegallery` executable or the npm script. The compiler is a [separate private repository](https://github.com/changeroa/site-compiler); an account with access must install it once:
+
+```sh
+gh repo clone changeroa/site-compiler /absolute/path/to/site-compiler
+cd /absolute/path/to/site-compiler
+npm ci --ignore-scripts --no-audit --no-fund
+npx playwright install chromium
+export SG_COMPILER_ROOT=/absolute/path/to/site-compiler
+sg discover --format json
+```
+
+Set `SG_COMPILER_ROOT` in your shell profile for CLI use and in your MCP server environment for MCP use. A CLI invocation can override it with `--compiler-root /absolute/path/to/site-compiler`. `discover` preserves the knowledge response and adds a top-level `compiler` object containing installation status, the actual Git revision, tracked changes, and available operations. Missing compiler setup leaves knowledge queries usable.
+
+The verified upstream revision is declared in [scripts/compiler/operations.mjs](operations.mjs). `matches_verified_revision` is true only for that revision without tracked modifications; a mismatch is reported but does not block execution. Use that revision when reproducing the verified workflow. To use a newer upstream version, update your compiler checkout with `git pull --ff-only` and `npm ci`, then inspect `sg discover` and `sg workflow`; SG does not fetch or upgrade code during a tool call. The compiler source, browser binaries, captured frames, and private pack data are not included in the StyleGallery npm package.
+
+## CLI
+
+Run these from the consumer project's working directory:
+
+```sh
+sg workflow
+sg workflow --document readme
+sg compile --url https://example.com --out ./captures/example
+sg timeline --url https://example.com --out ./captures/example --step 500 --grow
+sg transcribe --in ./captures --only example
+sg sale --in ./captures/example --out ./captures/example/sale
+sg gate --in ./captures/example --sale ./captures/example/sale --json ./captures/example/qa-report.json
+sg build --packs ./captures --out ./builds --only example
+sg shots --builds ./builds --slug example
+```
+
+`compile` captures scenes and frames; it does not produce a SceneBook by itself. A SceneBook describes scene geometry and content; its Timeline companion describes observed scroll behavior. `transcribe` produces these documents. Transcription and the optional sale-preview builder require an installed, authenticated `claude` CLI and can incur model usage. Their input roots contain one subdirectory per pack. Supply `--stylegallery` only when a different SG corpus should be used; the installed StyleGallery package is the default.
+
+Read `sg workflow` before selecting stages. Its installed compiler document owns the task policy: faithful reconstruction, adaptation for a new design, or sale-package production. These are task purposes, not CLI flags. Reconstruction uses available source media and direct observation to fill document gaps; the current implementation agent remains the builder. A media record carries source URLs, responsive variants, reuse or replacement decisions, and playback checks separately from the observation document.
+
+`sale` replaces observed copy with structural descriptors. `build` consumes only those sale editions and intentionally restricts original-page and external-media access. It is a package preview, not the faithful-reconstruction route. Use sale, build, and release operations when that package purpose is requested. A document-only evaluation is an explicit experiment, not the default website workflow. The SG skill only retrieves this workflow; it does not duplicate these policies.
+
+By default, `sale` writes its private audit to `copy-audit.private.json` in the parent of `--out`. Override this with `--audit`; it must remain outside the sale directory. The resolved destination is returned in `result.paths.audit`.
+
+| Command | Input and output |
+| --- | --- |
+| `compile` | `--url`, `--out`; writes `scenes.json` and `frames/` |
+| `timeline` | `--url`, `--out`; writes `timeline-curve.json` and `dense/` |
+| `transcribe` | `--in` pack root; writes documents and `transcribe.json` |
+| `sale` | `--in`, `--out`; writes sale documents and a private audit outside `out` |
+| `gate` | `--in`; optionally `--sale`, `--json`; returns failure when the upstream gate fails |
+| `build` | `--packs`, `--out`; writes sale-edition previews and `build.json` |
+| `shots` | `--builds`, `--slug`; writes screenshots and a report under each build |
+| `probe` | `--url`; logs scroll geometry; optional `--chrome` |
+| `batch-triage` | `--candidates`, `--out`; captures candidate curves and writes `runs.json` |
+| `triage` | `--in`; writes heuristic rankings |
+| `batch-capture` | `--candidates`, `--out`; captures scenes/timelines and writes `capture.json` |
+| `pack-status` | `--candidates`, `--in`; generates sale editions, runs gates, and updates status |
+| `pack-release` | `--products`; uses the compiler checkout's `out/packs` and `out/builds`, replacing matching files in `out/release` |
+| `workflow` | Reads the installed `SKILL.md`, or `README.md` with `--document readme` |
+
+All CLI results are one JSON envelope on stdout, including failures. Child logs are returned in `result.stdout` and `result.stderr`, with a 64 KiB tail per stream and truncation flags. Relative path options resolve from the caller's working directory; upstream scripts execute from the compiler checkout. `pack-release` is the upstream exception with fixed checkout-relative directories, and produces local archives without publishing them.
+
+Use `sg discover` or `sg ops` for the full input schemas. CLI options use hyphens (`--max-height`); MCP inputs use underscores (`max_height`). Unknown options, repeated CLI options, missing required paths, and invalid numeric values fail before execution. `--format json` is optional. `--runner-timeout-ms` bounds the entire process tree, defaults to 30 minutes, and accepts up to six hours; `--timeout-ms` on model operations instead controls upstream per-job timeouts. Interrupting the CLI or cancelling an MCP request terminates its running process tree.
+
+`ok` reports process success. Batch scripts can exit zero with failed individual jobs: use the returned ledger path to inspect each pack. A gate pass is an upstream consistency check, not SG conformance, accessibility proof, or rights clearance. Each result records the compiler revision, tracked-change status, executed script hash, and normalized arguments. Captures and generated documents remain consumer-owned outputs and are not admitted to the governed material registry.
+
+## MCP
+
+```json
+{
+  "mcpServers": {
+    "stylegallery": {
+      "command": "npx",
+      "args": ["--yes", "--package", "stylegallery", "stylegallery-mcp"],
+      "env": { "SG_COMPILER_ROOT": "/absolute/path/to/site-compiler" }
+    }
+  }
+}
+```
+
+Call `compile` with `{"url":"https://example.com","out":"/absolute/path/to/captures/example"}` or `gate` with `{"in":"/absolute/path/to/captures/example"}`. Prefer absolute paths because the MCP client's launch directory may differ from your terminal. Long captures require a client request timeout longer than the capture; the runner's timeout does not change client settings. `workflow` and the knowledge tools are read-only; execution tools are marked as potentially destructive and non-idempotent because existing artifacts may be replaced.
+
+From the StyleGallery checkout, use `npm run sg -- compile ...` and `npm run sg:mcp` for local development. To connect an MCP client to that unreleased checkout, use `"command": "node"` and `"args": ["/absolute/path/to/StyleGallery/scripts/sg-server.mjs"]` with the same environment settings. The frozen six-tool v1 server is `npm run sg:mcp:v1`, and its CLI is `npm run sg:v1 -- ...`.
+
+## Contracts And Verification
+
+The adapter follows the handoff fields in [Component Contract](../../design-engineering/component-contract.md): explicit inputs, outputs, process ownership, cancellation, and observable failure. Motion transcription remains governed by [Observed Choreography](../../motion/observed-choreography.md). These are routes into the existing domains; the transport creates no new domain or reusable Layout styling.
+
+From the StyleGallery checkout, run `npm run test:compiler` for subprocess, argument, cancellation, JSON, and MCP transport checks. With a compiler installation and Chromium available, run `SG_COMPILER_INTEGRATION_ROOT=/absolute/path/to/site-compiler npm run test:compiler` to also capture a local fixture with the real upstream scripts. Model transcription, model builds, and product release packaging are separate upstream operations and are not exercised by that smoke test.
+
+Implementation handoff:
+
+```text
+Consumer reference: declared
+Consumer reference record: consumer-reference/agent-native/registry.json
+consumer_reference: consumer-reference/agent-native/registry.json
+```
+
+## Navigation
+
+Parent: [StyleGallery](../../README.md).
+Next: [Component Contract](../../design-engineering/component-contract.md).

package/scripts/compiler/cli.mjs

@@ -0,0 +1,51 @@
+import { runCli } from "../agent-native/cli-adapter.mjs";
+import { compilerOperations, compilerToolDefinitions } from "./operations.mjs";
+import { compilerDiscovery, executeCompiler, failure } from "./runtime.mjs";
+
+export function withCompilerDiscovery(report, config = {}) {
+  if (!report.ok || !["discover", "ops"].includes(report.operation)) return report;
+  return { ...report, compiler: compilerDiscovery(config) };
+}
+
+export async function runSgCli(argv, config = {}) {
+  const args = [...argv];
+  const options = { ...config };
+  let report;
+  const rootIndex = args.indexOf("--compiler-root");
+  if (rootIndex >= 0) {
+    const root = args[rootIndex + 1];
+    if (!root || root.startsWith("--") || args.lastIndexOf("--compiler-root") !== rootIndex) {
+      report = failure(null, "argument_invalid", "--compiler-root requires one checkout path.");
+    } else { options.compilerRoot = root; args.splice(rootIndex, 2); }
+  }
+  const command = args[0];
+  if (!report && !Object.hasOwn(compilerOperations, command) && command !== "workflow") {
+    report = withCompilerDiscovery(runCli(args).report, options);
+  } else if (!report) {
+    const definition = compilerToolDefinitions().find(({ name }) => name === command);
+    const properties = definition.inputSchema.properties;
+    const input = {};
+    const seen = new Set();
+    for (let i = 1; i < args.length; i += 1) {
+      const flag = args[i];
+      const key = flag.startsWith("--") ? flag.slice(2).replaceAll("-", "_") : "";
+      if ((!Object.hasOwn(properties, key) && key !== "format") || seen.has(key)) {
+        report = failure(command, "argument_invalid", `Unknown or repeated argument: ${flag}`);
+        break;
+      }
+      seen.add(key);
+      const type = key === "format" ? "string" : properties[key].type;
+      if (type === "boolean") { input[key] = true; continue; }
+      const value = args[++i];
+      if (value === undefined || value.startsWith("--")) {
+        report = failure(command, "argument_value_required", `${flag} requires a value.`);
+        break;
+      }
+      if (key === "format") {
+        if (value !== "json") { report = failure(command, "format_unsupported", "Only --format json is supported."); break; }
+      } else input[key] = ["number", "integer"].includes(type) ? Number(value) : value;
+    }
+    report ??= await executeCompiler(command, input, options);
+  }
+  return { report, exitCode: report.ok ? 0 : 1, output: `${JSON.stringify(report, null, 2)}\n` };
+}