stylegallery 0.1.4 → 0.1.7

package/motion/observed-choreography.md

@@ -0,0 +1,73 @@
+---
+type: Domain Guide
+title: Observed Choreography Transcription
+description: Transcribe an observed scroll choreography into Scene Composition Contract vocabulary without copying assets or claiming implementation knowledge.
+domain: motion
+lifecycle: experimental
+provenance_kind: local
+---
+
+# Observed Choreography Transcription
+
+Primary role: observed scroll-choreography transcription workflow.
+
+## Repository Boundary
+
+This workflow turns an externally observed scroll-driven presentation into a transcription record written in the [Scroll-Driven Story](interaction-recipes.md#scroll-driven-story) vocabulary: `start`, `distance`, `scene_ranges`, progress-derived state, and static path. It exists so that a reimplementation study, a review, or an automated capture pipeline can hand a builder one document instead of raw pixels.
+
+It does not authorize copying an observed site's assets, copy, code, or brand into this repository or into a study; it does not add motion or decorative properties to reusable Layout pattern CSS; and a transcription record is an observation of an unaffiliated external artifact, not evidence about this repository's own examples. The consuming study owns its own imagery, copy, and visual values.
+
+## Reusable Method
+
+### Capture Protocol
+
+Record the capture identity before transcribing: URL, capture date, viewport, tool, wait strategy, and total scroll height. Capture in two passes:
+
+1. A coarse scene pass segments the page into scene y-ranges using layout landmarks (full-width blocks) and per-scene representative frames.
+2. A dense timeline pass scrubs at a fixed step (small enough that at least three frames land inside the shortest choreography of interest) and records a frame-difference score between consecutive frames.
+
+Difference-score plateaus near zero indicate static regions; sustained non-zero runs indicate scrubbed choreography; isolated spikes indicate discrete swaps. Keep every frame file; the transcription must cite frames by file name.
+
+### Transcription Record
+
+For each observed scene, write:
+
+- **Scene identity**: name, document y-range, one-sentence job.
+- **Pin observation**: whether a stage visually holds position while the document advances (`start` and `distance` in document pixels), or the scene scrolls through normally (`distance` not applicable).
+- **Scene ranges**: sub-segments as fractions of scene progress, each with the observed state it presents.
+- **Keyframe observations**: for each boundary between sub-segments, the property-level change observed across adjacent frames — content swap, translation, scale, opacity, counter/number roll, media frame advance — stated as direction and rough magnitude, not invented exact values.
+- **Transition profile**: for each sub-segment boundary, how the states mix — `cut` (adjacent frames show only completed states), `blend` (a mid-transition frame shows both states partially visible; record the observed blend width in scroll pixels, bounded below by the capture step), or `slide` (a mid-transition frame shows a state displaced along an axis; record the direction). A consumer without a profile defaults to whatever its own contract prefers, so an omitted profile is a gap worth naming.
+- **Static path**: what a non-animated reading order of the same content would present, so the consumer can build the reduced-motion and no-script alternative required by the [Scroll-Driven Story](interaction-recipes.md#scroll-driven-story) contract.
+- **Asset inventory**: the kind of media carrying the effect (photograph, video, rendered UI, image sequence) and its role. Kinds only; the record never embeds or links a copy of the asset for reuse.
+- **Frame evidence**: the frame files supporting each claim.
+
+Mark anything the captured frames cannot establish as `not observable in captured frames` instead of interpolating a guess. A claim without a citable frame is a gap, not a fact.
+
+### Handoff
+
+A transcription record travels with the capture manifest and difference curve. A consumer maps scene ranges onto the [Scene Composition Contract](interaction-recipes.md#scene-composition-contract): document scroll and sticky geometry stay with Layout responsibilities, progress mapping and teardown with Motion, and all visual values with the consuming product.
+
+## Opinionated Guidance
+
+Transcribe jobs and relationships, not pixel values; a reimplementation that inherits observed exact timings inherits unverified choices. Derive every described state from scene progress so reversal and mid-entry stay well defined in the eventual build. Sampling density bounds what a record may claim: a 500px step cannot support statements about effects shorter than 500px of scroll.
+
+## Platform-Specific Guidance
+
+Record the capture browser, OS, headless mode, and device scale separately from the observed site's behavior; headless rendering, missing fonts, and disabled video autoplay can all change what frames show. For client-rendered pages, note that DOM text accumulates as sections mount, so per-scene text dumps overstate what is visible; treat frames as the primary evidence for visibility.
+
+## Unsupported Absolutes
+
+A transcription proves what frames show at sampled positions, never how the original is implemented — no easing curve, frame rate, library, or performance claim survives from frame differences alone. There is no universal scrub step, difference threshold, or scene count; each capture declares its own. Frame similarity in one direction does not prove reversibility. A transition profile is bounded by sampling: a capture step wider than a transition can prove `blend` only when a mid-transition frame happens to land inside it, and can never prove `cut`.
+
+## Verification Contract
+
+A transcription record is usable when every scene declares a y-range and pin observation, every motion claim cites frame files, every scene has a static path, and every unknown is marked `not observable in captured frames`. Reversibility claims require frames captured in both scroll directions; otherwise mark reversal untested. The record is stale when the source site changes; re-verification means a fresh capture compared against the recorded capture date, never editing old observations in place.
+
+## Source, License, And Attribution
+
+Locally authored workflow, generalized from an internal capture-and-reimplementation study of an external homepage on 2026-09-10. Transcription records describe unaffiliated external sites; they carry the capture identity for provenance and reproduce no external assets, copy, or code.
+
+## IA Navigation
+
+Parent: [Motion](index.md).
+Next: [Scroll-Driven Story](interaction-recipes.md#scroll-driven-story).

package/motion/rendering-and-performance.md

@@ -0,0 +1,89 @@
+---
+type: Domain Guide
+title: Motion Rendering And Performance
+description: Diagnose animation cost and choose native transition mechanisms with measurable behavior and complete fallbacks.
+domain: motion
+lifecycle: experimental
+provenance_kind: local
+reviewed_on: 2026-09-21
+---
+
+# Motion Rendering And Performance
+
+Primary role: source-backed rendering diagnosis and mechanism selection.
+
+## Repository Boundary
+
+This guide owns questions about the delivery of product motion. It does not grant reusable Layout CSS animation properties, establish universal frame budgets, or treat a trace from one machine as proof for every device. Use the existing [Practice Reference](practice-reference.md) for the boundary between mechanics and taste.
+
+## Reusable Method
+
+Describe the visible failure before choosing a faster-looking API: input responds late, geometry jumps, frames arrive irregularly, content is blank during decoding, or the wrong state appears. Record the target browser/device, surface size, concurrent work, and source revision. Select evidence that distinguishes these failures.
+
+### Source Findings
+
+| Source | What it supports | What it does not establish |
+| --- | --- | --- |
+| [web.dev animation guide](https://web.dev/articles/animations-guide) | Rendering work depends on the properties and effects involved; inspect paint and compositing behavior. | That a property or library always runs on a GPU. |
+| [Layout thrashing](https://web.dev/articles/avoid-large-complex-layouts-and-layout-thrashing) | Interleaved style writes and geometry reads can force synchronous layout; batching can avoid repeated work. | That every geometry read is a defect. |
+| [Chrome runtime performance](https://developer.chrome.com/docs/devtools/performance) | Recorded frames and main-thread work can locate a runtime bottleneck. | Hardware equivalence between throttling and an actual device. |
+| [View Transitions Level 1](https://www.w3.org/TR/css-view-transitions-1/) | Same-document transitions wrap a DOM update and expose distinct update, readiness, and finish promises. | Route state, data consistency, or a universal cross-document contract. |
+| [Scroll-driven Animations](https://www.w3.org/TR/scroll-animations-1/) | Scroll progress and view progress are distinct timeline models. | That a visually scrubbed sequence has correct reading order or accessibility. |
+| [CSS Transitions Level 2](https://www.w3.org/TR/css-transitions-2/#defining-before-change-style) | `@starting-style` supplies entry styling for relevant newly rendered elements. | Correct exit teardown, focus handling, or support in an unspecified runtime. |
+
+These are dated source readings, not a compatibility table. The linked standards-track documents include work in progress; check the selected browser and feature combination before making a shipping claim.
+
+### Match The Mechanism To The Responsibility
+
+| Responsibility | Candidate | First failure probe |
+| --- | --- | --- |
+| Animate one local state difference | CSS transition with a static endpoint | Disable transitions; the endpoint must still be correct. |
+| Control an effect's playback lifecycle | Web Animations | Interrupt and dispose it; verify cleanup and promise handling. |
+| Visually connect a replaced DOM state | Same-document View Transition | Skip the transition; the DOM update must still occur once. |
+| Bind presentation to a scroll interval | Native scroll/view timeline where supported | Remove support; content must remain readable in order. |
+| Coordinate media decoding with chapters | Consumer-owned controller | Delay or fail a frame decode; preserve a readable fallback. |
+
+This selection table is a local reasoning aid. It does not rank CSS, JavaScript, or native APIs by universal speed.
+
+### A Diagnostic Sequence
+
+1. Reproduce the failure with representative content and a repeatable input sequence. Save the initial state, not just the final screenshot.
+2. Inspect the slow interval: input queueing, script execution, style/layout, paint, compositing, and media work where the tooling exposes them.
+3. Change one suspected cost while retaining the same task and information. For a suspected layout loop, batch the same reads before writes rather than removing the interaction.
+4. Compare trace intervals and final behavior. Report both improvements and regressions; averaging the entire page can hide the bad interval.
+5. Repeat on a declared target device when the claim concerns that device. Keep emulation and real-device observations separate.
+
+For continuous motion, inspect frame delivery during the effect. For input responsiveness, use [Loading And Feedback](../design-engineering/loading-and-feedback.md) and its distinction between next paint and completed work. A responsive first frame can precede an unsuccessful operation.
+
+### View Transition Failure Contract
+
+Treat the DOM update as the essential operation. `updateCallbackDone` reports that update's result; `ready` can reject when an animation cannot start; visual skipping can still lead to successful completion. Handle the promises relevant to the selected API version and keep route/focus error handling independent of decoration. The [specification interface](https://www.w3.org/TR/css-view-transitions-1/#viewtransition) is the source for these distinctions.
+
+Local probes: request a second navigation before the first effect ends, remove a named element, use a duplicate transition name, fail the update callback, and resize during capture. Determine which failures skip only the effect and which prevent the destination update. Do not infer business success from the existence of a transition object.
+
+## Opinionated Guidance
+
+Choose the smallest effect that explains the state change. Promote an element or retain a large snapshot only when the measured benefit justifies its lifetime and resource cost. Reducing the work is often easier to explain than adding coordination machinery, but retain evidence for the actual tradeoff.
+
+## Platform-Specific Guidance
+
+DevTools UI and event names change; record tool/browser versions and retain raw traces. A native timeline needs a source-bound fallback, especially for media chapters with independent decoding. Follow [Scroll-driven Story](interaction-recipes.md#scroll-driven-story) for reading, scroll ownership, and runnable examples.
+
+## Unsupported Absolutes
+
+An average FPS value cannot prove every frame arrived on time. Smooth video playback of a capture cannot establish input latency. A compositor-friendly effect does not remove image decode, memory, script, or accessibility costs.
+
+## Verification Contract
+
+Report the initial failure, task-preserving comparison, target environment, raw artifact locator, observed difference, and remaining limitations. Keep source-derived expectations separate from measured timings. Test the static path, rapid input, cold and warm media/cache conditions, and reduced motion when relevant.
+
+The sequence above is a proposed diagnostic protocol; this documentation change captures no runtime performance evidence. Re-review when the effect, content scale, browser feature, or target hardware changes.
+
+## Source, License, And Attribution
+
+Locally authored synthesis. The linked official browser guidance and specifications were inspected 2026-09-21; no source code, figures, or tables are reproduced. `consumer_reference: not_applicable` because no consumer implementation or performance record is selected.
+
+## IA Navigation
+
+Parent: [Motion](index.md).
+Next: [Motion Review Workflow](review-workflow.md).

package/motion/review-workflow.md

@@ -72,6 +72,14 @@ Do not automatically block `ease-in`, a particular scale value, motion longer th
 
 Exercise the actual interaction in its default, repeated, interrupted, reversed, and reduced-motion states. Record the exact environment and observable. Source review may establish declared code paths; rendered and human outcomes require corresponding evidence families.
 
+## Scroll Story Evidence
+
+For [scroll-driven stories](interaction-recipes.md#scroll-driven-story), add boundary samples immediately before and after each scene transition, forward/reverse comparison, large jumps, direct middle entry, reload/history restoration, narrow and short viewports, long copy, and delayed font/image changes. Deliberately fail or delay a media request and verify stale completion cannot replace current presentation.
+
+Record JavaScript update cost separately from animation-frame intervals: neither alone measures compositor frame delivery. Count idle updates to catch observer/decode feedback loops. Record media dimensions, bounded cache entries, and estimated decoded bytes separately from measured process/GPU memory. Set product-local budgets and keep real-device, touch, assistive-technology, and comfort outcomes `not_run` when unobserved.
+
+The [Scroll Story verification](../examples/scroll-story/verification.md) records the two worked implementations and the limits of the local run.
+
 ## Source, License, And Attribution
 
 - Upstream inspiration: [review-animations/SKILL.md](https://github.com/emilkowalski/skills/blob/220e8607c90b17337d210125777b7b695f26c221/skills/review-animations/SKILL.md)

package/motion/vocabulary.md

@@ -51,7 +51,7 @@ The terms are implementation-neutral. A framework, operating-system behavior, or
 
 ## Opinionated Guidance
 
-The family ordering favors what a reader can observe before implementation details. It is useful for retrieval, but it is not a complete ontology. Add a term only after a reader task demonstrates that existing terms and aliases cannot express the distinction.
+The family ordering favors what a reader can observe before implementation details. It is useful for retrieval, but it is not a complete ontology. Add a term only when contrastive repository cases show that existing terms and aliases cannot express the distinction.
 
 ## Platform-Specific Guidance
 
@@ -66,7 +66,7 @@ Names tied to iOS, macOS, a browser API, Motion, Framer Motion, React, or a comp
 
 ## Verification Contract
 
-A vocabulary lookup should exercise exact, ambiguous, and unknown cases. Pass requires one justified term, an ordered candidate set with a stated distinction, or `unknown`; invented winners fail. A new term also requires a findability task showing the current route cannot reach an adequate term within two hops.
+A vocabulary lookup should exercise exact, ambiguous, and unknown cases. Pass requires one justified term, an ordered candidate set with a stated distinction, or `unknown`; invented winners fail. A new term also requires contrastive exact, ambiguous, and unknown cases showing that the current vocabulary cannot express the distinction.
 
 ## Source, License, And Attribution
 

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "stylegallery",
-  "version": "0.1.4",
-  "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",
@@ -47,27 +51,61 @@
     "consumer-reference/agent-native/v2/schema/material-record.schema.json",
     "consumer-reference/contract.md",
     "consumer-reference/index.md",
+    "design-engineering/component-contract.md",
     "design-engineering/consumer-migration-readiness.md",
+    "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",
     "game-ui/reference-record.md",
     "game-ui/screen-hierarchy.md",
+    "game-ui/screen-recipes.md",
     "game-ui/unity/architecture.md",
     "game-ui/unity/cli-loop.md",
     "game-ui/unity/org-wiki.md",
     "game-ui/unity/repository-map.md",
     "game-ui/unity/ui-systems.md",
+    "game-ui/verification-workflow.md",
     "guides/decision-tree.md",
     "guides/documentation-mode-taxonomy.md",
     "guides/layout-brief.md",
@@ -76,8 +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",
@@ -136,8 +181,15 @@
     "patterns/viewport-shell/scroll-body-shell.md",
     "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",
     "quality/claim-records/samples.md",
@@ -200,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"
@@ -237,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",
@@ -256,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/adaptation-workflow.md

@@ -0,0 +1,76 @@
+---
+type: Domain Guide
+title: Platform Adaptation Workflow
+description: Compare a native convention with a target implementation through source, capability, fallback, and evidence records.
+domain: platform-guides
+lifecycle: experimental
+provenance_kind: local
+---
+
+# Platform Adaptation Workflow
+
+Primary role: platform comparison planning and handoff.
+
+## Repository Boundary
+
+Use a platform convention as a sourced comparison for a named task. The native platform owns its convention; the target's standards and actual runtime determine the adaptation. This workflow does not make a visual imitation equivalent to native behavior.
+
+## Reusable Method
+
+1. Name the task and target: native application, browser, embedded web view, or game engine.
+2. Select [Apple](apple-interaction.md), [Android](android-interaction.md), or [Windows](windows-interaction.md) by source platform.
+3. Record an official source, exact page section, version or dated reading, and re-review trigger.
+4. Separate the observed/native fact from the transferable interaction question.
+5. Choose an adaptation and an explicit fallback using the [Compatibility Matrix](compatibility-matrix.md).
+6. Execute the target-specific acceptance cases and record what was not tested.
+
+## Adaptation Record
+
+| Field | Required content |
+| --- | --- |
+| Task | The user action, intended outcome, and affected state |
+| Source context | Platform, OS/API or documentation version, source URL/section, review date |
+| Source claim | The precise native fact supported by that source |
+| Target context | Browser/OS/framework/device/input and relevant versions |
+| Transferable question | What problem the convention helps investigate |
+| Target decision | Implement, adapt, omit, or defer with a reason |
+| Capability gap | Missing API, different input model, permission, or semantic difference |
+| Fallback | A complete task path when the preferred capability is absent |
+| Verification | Actions, expected and actual behavior, artifacts, source/build identity |
+| Freshness | Source/API change or failed observation that triggers re-review |
+| Handoff | `consumer_reference` record or `not_applicable` with a reason |
+
+## Worked Comparison: Returning From Detail
+
+Native source: Android's [predictive Back documentation](https://developer.android.com/guide/navigation/custom-back/predictive-back-gesture), reviewed 2026-09-08, describes gesture preview and cancellation. Transferable question: can a person understand and cancel a return before committing it?
+
+Web decision: use the application's documented list/detail route and normal browser history. Restore the list's selection and relevant search state on return. Provide a visible return link where the task needs it. Do not intercept browser/system gestures merely to reproduce a preview.
+
+Fallback: direct entry to a detail URL has no assumed prior list history; its visible parent link goes to the known collection route. Verification cases: navigate from a filtered list, return with browser Back, enter detail directly, cancel a local dialog before leaving, and return after the selected item is removed.
+
+Actual result: `not_run`; this is a fictional adaptation proposal. `consumer_reference: not_applicable` because no consumer record is selected. The comparison claims neither native gesture support nor tested browser history restoration.
+
+## Opinionated Guidance
+
+Preserve the task and recovery path before reproducing the native effect. When a capability is absent, document an intentional complete alternative rather than a partially functioning control.
+
+## Platform-Specific Guidance
+
+The source platform and target platform are separate fields even when both run on the same device. A browser on Android does not expose every Android application API. A web view's embedding host may own navigation and permissions.
+
+## Unsupported Absolutes
+
+An official source establishes its own guidance, not target conformance. Similar appearance, shared vocabulary, or a matching API name is insufficient evidence of equivalent behavior.
+
+## Verification Contract
+
+A completed adaptation distinguishes source fact, local inference, target implementation, and actual observation. Verify unavailable capabilities, interrupted navigation, relevant preferences, and all claimed inputs. Re-review on a source change, target API change, or failed acceptance case; a review date alone is not proof of continuing support.
+
+## Source, License, And Attribution
+
+Locally authored comparison method and fictional example. The linked Android source was rechecked on 2026-09-08; prose and examples are independently written. Source access does not establish device execution.
+
+## IA Navigation
+
+Parent: [Platform Guides](index.md).
+Next: [Platform Compatibility Matrix](compatibility-matrix.md).

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/android-interaction.md

@@ -0,0 +1,74 @@
+---
+type: Domain Guide
+title: Android Interaction As A Comparative Reference
+description: Source-bounded Android Back and adaptive-window guidance with explicit web translation and failure cases.
+domain: platform-guides
+lifecycle: experimental
+provenance_kind: local
+platform: Android applications
+platform_version: dated official documentation; target OS and AndroidX versions required
+reviewed_on: 2026-09-08
+---
+
+# Android Interaction As A Comparative Reference
+
+Primary role: Android platform comparison guide.
+
+## Repository Boundary
+
+This guide compares Android application behavior with a consumer's target. It does not equate Android APIs with browser APIs or prescribe Material visual treatment. Record the actual OS, AndroidX/UI stack, and target device before implementation.
+
+## Reusable Method
+
+Use the [Adaptation Workflow](adaptation-workflow.md). Choose a specific native concern below, inspect its source, then write the target behavior and fallback independently of native visuals.
+
+## Source-Bounded Conventions
+
+| Concern | Official source and bounded fact | Transferable question |
+| --- | --- | --- |
+| Back preview | [Predictive Back](https://developer.android.com/guide/navigation/custom-back/predictive-back-gesture) describes previewing a destination and cancelling a gesture; custom handling depends on the application stack | Is the destination understandable, and does cancelling preserve the current state? |
+| Back ownership | The same source describes enabled callbacks and one recipient for a Back gesture | Which active layer consumes Back, and when does control return to the outer navigation owner? |
+| Window adaptation | [Window size classes](https://developer.android.com/develop/adaptive-apps/guides/use-window-size-classes) classify available application window space for adaptive decisions | Does the screen adapt to its available space while preserving selection and task state? |
+| Navigation transformation | [Responsive navigation](https://developer.android.com/develop/ui/views/layout/build-responsive-navigation) discusses changing navigation presentation with window conditions | Can the user reach the same destinations after presentation changes? |
+
+These pages were read on 2026-09-08. They are a dated documentation set, not a pin of every Android release or package. Verify the implementation details for the selected runtime.
+
+## Worked Adaptation: Compact List And Expanded Detail
+
+Task: inspect a collection on a resizable surface. Native comparison: available window space can change the presentation. Target web decision: compose [List Detail](../recipes/list-detail.md), retain selected identity in application state, and let the Layout owner choose the fit constraint. Android's native units and class boundaries are not CSS breakpoints.
+
+On a tight surface, the detail route can replace the list visually while preserving the query and selection. On a roomy surface, both can be visible. Returning must resolve a missing selected item explicitly. Changing presentation must not duplicate the current route or save unrelated navigation history entries.
+
+| Action | Expected target behavior |
+| --- | --- |
+| Resize with item B selected | B remains the selected detail |
+| Return to the list | Previous query remains available |
+| Cancel an inner dialog | Dialog closes once; outer route stays put |
+| Open detail directly | Parent navigation works without assuming prior history |
+
+This is an unexecuted web proposal, not evidence of an Android build.
+
+## Opinionated Guidance
+
+Map Back, Up/parent navigation, dialog dismissal, and operation cancellation separately. They may share an icon or button position while changing different state.
+
+## Platform-Specific Guidance
+
+Android gesture progress, callback dispatch, activities, and AndroidX navigation belong to native or embedding-host code. A browser adaptation should use its supported navigation semantics. Record any web-view host integration as a separate implementation dependency.
+
+## Unsupported Absolutes
+
+Android window classes are not universal web breakpoints. A browser Back action is not necessarily an application's parent destination. A cancel animation does not prove the underlying operation was cancelled.
+
+## Verification Contract
+
+Test gesture completion/cancellation on the declared native device when claiming native behavior. For a web adaptation, test actual browser history, direct links, resizes, input modes, and dialog focus independently. Review when any cited convention or target navigation implementation changes.
+
+## Source, License, And Attribution
+
+Locally authored synthesis of the official Android pages linked above, rechecked 2026-09-08. No source code, tables, or native visual assets are reproduced. `consumer_reference: not_applicable` because this reference guide selects no consumer implementation record.
+
+## IA Navigation
+
+Parent: [Platform Guides](index.md).
+Next: [Platform Compatibility Matrix](compatibility-matrix.md).