stylegallery 0.1.6 → 0.1.7

package/design-terminology/typography-semantics.md

@@ -0,0 +1,86 @@
+---
+type: Domain Guide
+title: Typography Roles, Styles, And Representations
+description: Compare named type roles, native scaling behavior, composite token records, and CSS output without inventing universal size mappings.
+domain: design-terminology
+lifecycle: experimental
+provenance_kind: local
+reviewed_on: 2026-09-21
+---
+
+# Typography Roles, Styles, And Representations
+
+Primary role: typography vocabulary comparison.
+
+## Repository Boundary
+
+This guide compares source-specific meanings. It defines no StyleGallery type scale, font choice, size, density, or visual token. Product typography belongs to its consumer; Layout owns spatial behavior. [Term Cases](conflict-cases.md) is the canonical record for the term identifiers and relations used here.
+
+## Reusable Method
+
+Identify whether “style” means a semantic role, a bundle of values, a collection of role slots, a native scaling behavior, or a runtime declaration. Compare sources at that level. Then record what information is lost when the result is serialized or rendered elsewhere.
+
+### Source Findings
+
+| Source | Bounded meaning | Boundary to retain |
+| --- | --- | --- |
+| [Apple HIG typography](https://developer.apple.com/design/human-interface-guidelines/typography) | Text styles combine typographic attributes into a hierarchy and participate in system text-size adaptation. | A single exported size does not encode the complete native scaling behavior. |
+| [Fluent 2 typography](https://fluent2.microsoft.design/typography) | The type ramp supplies named styles and roles for a selected target platform. | A role label does not specify one universal font or numeric size across platforms. |
+| [Material 3 in Compose](https://developer.android.com/develop/ui/compose/designsystems/material3#typography) | The `Typography` class models the Material 3 type scale using named style slots. | This is the system's Compose implementation surface, not an interchange specification. |
+| [DTCG typography type](https://www.designtokens.org/tr/2025.10/format/#typography) | The composite record includes family, size, weight, letter spacing, and line height. | The record does not itself implement platform text scaling. |
+| [CSS font shorthand](https://www.w3.org/TR/css-fonts-4/#font-prop) | `font` is a runtime shorthand over defined font properties and line height. | It does not encode every typographic property or the original role metadata. |
+
+Read on 2026-09-21. Apple content was inspected through the official documentation JSON. Material and Fluent references are dated product documentation. DTCG Format 2025.10 is a Community Group report; CSS Fonts Level 4 is a standards-track publication. Actual font availability and rendering require target evidence.
+
+### Comparing A Style With A Record
+
+`apple.text-style` and `dtcg.typography` have `partial_overlap` for exchanging typographic attributes. Some attributes can be represented in both. Apple's style is also connected to native text-size behavior, while an interchange record can describe styles outside Apple's system. An exporter must explain the scope of a match.
+
+`css.font` → `dtcg.typography` is an `implementation_representation` relation scoped to partial typography output. A consumer must emit additional properties such as letter spacing separately when needed and retain provenance outside the shorthand. This relation does not promise a reversible conversion.
+
+### Comparing Role Collections
+
+`material3.typography` and `fluent.type-ramp` have `partial_overlap` for named typography roles. Both help organize hierarchy, but the role inventories, defaults, and implementation surfaces differ. Matching two names containing “body” does not prove equivalent intended use or visual results.
+
+A collection of styles and one style are different abstraction levels. Before declaring `broader_than`, demonstrate proper set containment with comparable instances; a class that contains fields is not automatically a broader semantic concept than those fields.
+
+### Worked Handoff: Dense Review Surface
+
+A consumer wants more records visible while retaining readable annotations and controls. Separate the density decision from typography translation. Density might change spacing, optional detail, or command presentation; it need not mean scaling every font down.
+
+| Decision | Evidence to request | Translation failure |
+| --- | --- | --- |
+| Role mapping | Task purpose and named source roles | Similar labels map headings to ordinary labels. |
+| Value representation | Output properties and units | A composite style loses a required property. |
+| Scaling | Target user setting and the resulting style behavior | A static export ignores larger-text settings. |
+| Font fallback | Actual fonts and representative scripts | A role looks acceptable only with a locally installed font. |
+| Reading hierarchy | Long and localized content on the target surface | Compact labels obscure the main task. |
+
+This is a proposed consumer investigation, not evidence that a particular type scale improves reading speed. For product adaptation, use [Preferences And Accessibility](../platform-guides/preferences-and-accessibility.md); for editing behavior, use [Text Input And Internationalization](../design-engineering/text-input-and-internationalization.md).
+
+## Opinionated Guidance
+
+Preserve semantic roles even when two styles currently share values. Judge a translation by the declared task, retained attributes, and target scaling behavior. Treat a visual match at one size as a narrow observation.
+
+## Platform-Specific Guidance
+
+Points, CSS pixels, and scale-aware native units must be interpreted by the selected runtime. Native text-style names do not become CSS breakpoints or shared Layout tokens. Font fallback and script shaping require actual rendering; a vocabulary comparison cannot establish them.
+
+## Unsupported Absolutes
+
+A type ramp is not a universal accessibility standard. A typography token is not a complete native text-style behavior. CSS `font` is not a lossless export of all typography information. More visible rows do not prove higher task efficiency.
+
+## Verification Contract
+
+Record source roles, relation scope, output representation, scaling inputs, and any omitted information. Probe default and enlarged text, missing fonts, long labels, multiple scripts, and the actual target's line metrics. Keep file validation separate from visual and user-task evidence.
+
+These probes are unexecuted. Source meaning was reviewed; runtime rendering and reading performance were not measured. Re-review when role definitions, format versions, platform scaling, or adapter behavior changes.
+
+## Source, License, And Attribution
+
+Locally authored synthesis without imported type values or source examples. Terminology reliance: `apple.text-style`, `fluent.type-ramp`, `material3.typography`, `dtcg.typography`, and `css.font`; relation types: `partial_overlap` and `implementation_representation`. Named sources were rechecked 2026-09-21; this is author review, not independent semantic approval. `consumer_reference: not_applicable` because no consumer typography record is selected.
+
+## IA Navigation
+
+Parent: [Design Terminology](index.md).
+Next: [Token Semantics And Resolution](token-semantics.md).

package/log.md

@@ -1,5 +1,34 @@
 # StyleGallery Log
 
+## 2026-09-22
+
+- Prepared `stylegallery@0.1.7` with direct website capture, transcription, and workflow commands in the SG CLI and MCP. The compiler remains a separately installed checkout; frozen v1 knowledge entrypoints remain available.
+- Routed faithful reconstruction, adaptation, and sale-package work through the compiler's task-aware workflow. Reconstruction prioritizes usable original media, additional observation, explicit replacement decisions, and visual QA. The automatic sale-edition builder is labeled as a package preview.
+- Added compiler transport, cancellation, packaged-install, and local real-capture checks. These verify the integration; they do not establish an improvement in clone quality.
+
+Implementation handoff: `consumer_reference: consumer-reference/agent-native/registry.json`.
+
+Consumer reference: declared
+Consumer reference record: consumer-reference/agent-native/registry.json
+
+## 2026-09-21
+
+Understood as: substantially enrich Motion, Design Engineering, Platform Guides, and Design Terminology with primary-source research integrated into governed local documents. The user excluded Layout and Game UI from this work.
+
+- Added twelve local research guides: motion accessibility/interruption/rendering; native interaction contracts, multilingual input, and asynchronous feedback; platform adaptation/preferences/input; and token, interaction, and typography semantics. Each separates source-backed findings, local proposals, failure cases, and unexecuted verification scenarios.
+- Inspected 66 cited official source pages on 2026-09-21. Recorded source status and target-version limits; read Apple page bodies through official documentation JSON when the HTML reader exposed a JavaScript shell. Preserved prior source-review dates for unrelated term records.
+- Added fourteen source-qualified terms and nine scoped relations, bringing the terminology tables to twenty-five terms and seventeen relations. These are author-reviewed experimental judgments, not independent semantic approval.
+- Registered the twelve leaves in domain membership, local navigation, the closed Material v2 admission set, and npm packaging. The admitted corpus has 181 documents. New guidance remains experimental and does not add profile values, native implementations, or a domain.
+- Verified Markdown structure, links, IA, governance, domain membership, terminology, consumer handoffs, and material admission in an isolated checkout of the research changes. Domain/terminology/governance, consumer/evidence, and frozen-v1 regression suites passed; package installation and CLI/MCP retrieval passed. Fixed the package inventory test's omission of the three existing license/notice files while preserving its exact allow-list assertion.
+- Checked every cited URL and fragment. Applied two fresh-reader corrections to the term-comparison method and contributor verification route. Eight author-selected search probes retrieved the intended guide within the first two results; these are retrieval smoke checks, not an independent usability evaluation. No browser, native IME, assistive-technology, or product performance execution is claimed.
+
+Implementation handoff: `consumer_reference: consumer-reference/agent-native/registry.json`.
+
+Consumer reference: declared
+Consumer reference record: consumer-reference/agent-native/registry.json
+
+Terminology reliance: `dtcg.alias`, `fluent.alias-token`, `fluent.global-token`, `carbon.color-token`, `dtcg.resolver-modifier`, `html.popover`, `apple.popover`, `html.dialog`, `aria.dialog`, `apple.text-style`, `fluent.type-ramp`, `material3.typography`, `dtcg.typography`, `css.font`, `dtcg.token`, `dtcg.group`, and `css.custom-property`. Relation types used: `partial_overlap`, `implementation_representation`, and `not_comparable`. Named sources for these terms were rechecked on 2026-09-21; the older Figma, historical-format, component/pattern, and Layout relations retain their original review scope. Direct locators and boundaries are in [Term Cases](design-terminology/conflict-cases.md).
+
 ## 2026-09-09
 
 - Added a full-page fixed-viewport scene-navigation example with chapter hashes/history, wheel-burst gating, keyboard and art-surface swipe navigation, native copy overflow, immediate reduced-motion transitions, and a complete reading escape.

package/motion/accessible-motion.md

@@ -0,0 +1,90 @@
+---
+type: Domain Guide
+title: Accessible Motion And Equivalent Feedback
+description: Separate motion preferences, automatic updates, flashing, and semantic feedback before designing reduced-motion behavior.
+domain: motion
+lifecycle: experimental
+provenance_kind: local
+reviewed_on: 2026-09-21
+---
+
+# Accessible Motion And Equivalent Feedback
+
+Primary role: source-backed motion accessibility decision guide.
+
+## Repository Boundary
+
+This page owns product-motion decisions and their evidence requirements. Shared [accessibility evidence](../quality/evidence/accessibility.md) governs conformance claims. No motion values or decorative declarations become reusable Layout CSS.
+
+## Reusable Method
+
+Inventory each effect by trigger, duration, affected area, information conveyed, and available controls. Evaluate the separate source conditions below; one reduced-motion media query is not a complete accessibility review. Then specify an equivalent path that exposes the same information and actions with less movement.
+
+### What The Sources Establish
+
+| Source | Bounded finding | Decision it informs |
+| --- | --- | --- |
+| [WCAG 2.2 SC 2.3.3 explanation](https://www.w3.org/WAI/WCAG22/Understanding/animation-from-interactions.html) | The AAA criterion concerns disabling interaction-triggered motion animation unless essential. | Identify extra movement induced by scrolling, dragging, expanding, or changing routes. |
+| [SC 2.2.2 explanation](https://www.w3.org/WAI/WCAG22/Understanding/pause-stop-hide.html) | The A criterion has distinct conditions for automatically moving information and automatically updating information. The latter has no five-second exception. | Audit rotating content and live updates separately from a short transition. |
+| [SC 2.3.1 explanation](https://www.w3.org/WAI/WCAG22/Understanding/three-flashes-or-below-threshold.html) | Flash evaluation includes frequency and defined area/luminance thresholds. | A pause button cannot substitute for evaluating flashing content. |
+| [Media Queries Level 5](https://www.w3.org/TR/mediaqueries-5/#prefers-reduced-motion) | `prefers-reduced-motion` exposes a preference; it does not select an application-specific replacement. | Author the replacement and verify preference changes. |
+| [SC 4.1.3 explanation](https://www.w3.org/WAI/WCAG22/Understanding/status-messages.html) | Status information can require programmatic exposure without moving focus. | Preserve feedback when a spinner, movement, or success effect disappears. |
+
+WCAG Understanding pages are informative explanations of the [normative WCAG 2.2 requirements](https://www.w3.org/TR/WCAG22/). Media Queries Level 5 is a Working Draft. These sources do not establish implementation support for a particular browser or certify a product.
+
+### Classify Before Replacing
+
+| Product behavior | Local replacement proposal | Failure to look for |
+| --- | --- | --- |
+| Scroll-linked zoom into a product detail | Keep the reading sequence; switch details at explicit boundaries or expose them together. | Essential copy is available only at an intermediate animation frame. |
+| Reordering a list | Update the order and selection immediately; provide a concise completion message if needed. | Visual order changes while reading order or selected identity does not. |
+| Loading shimmer | Use a stationary placeholder and textual waiting state. | The placeholder is mistaken for loaded content or the request appears to have stopped. |
+| Modal entrance | Present the usable modal immediately, with the same focus and dismissal contract. | Focus is delayed until a completion event that never fires in reduced mode. |
+| Automatically advancing announcement | Provide durable stop/control behavior appropriate to the applicable criterion. | Moving focus elsewhere restarts an update the user had paused. |
+| Success celebration | Retain the durable success state and next action. | Removing confetti also removes the only completion signal. |
+
+These are proposed product choices, not W3C-prescribed recipes. A fade is another effect to evaluate; reducing translation does not prove that every replacement is comfortable.
+
+### Preference Changes During Work
+
+Record whether an in-product setting inherits the system preference or further reduces motion. Define how an active effect settles when the effective preference changes. The settlement must preserve the current task, release transient visual resources, and make the destination usable. Avoid replaying an entrance merely because the preference changed back.
+
+Separate pausing the presentation from pausing the underlying process. A dashboard may stop replacing visible figures while data collection continues. A resumed display must say whether it shows current information or replays buffered history. For transaction feedback, stopping an animation never means a server write was cancelled.
+
+## Opinionated Guidance
+
+Start with a complete stationary interaction, then add motion with a named explanatory purpose. This makes the no-motion path directly inspectable. Keep user-chosen pauses durable across focus changes and make preference controls reachable before the effect they govern.
+
+Do not infer an accessibility need from a device class. The effective preference, explicit user action, and actual interaction matter more than a touch/desktop label.
+
+## Platform-Specific Guidance
+
+Web CSS and script-driven effects need a coordinated preference owner. Native Reduce Motion behavior belongs to its named OS/API; see [Preferences And Accessibility](../platform-guides/preferences-and-accessibility.md). Animated media, canvas, and embedded content require their own controls and evidence because disabling a CSS transition does not govern them.
+
+## Unsupported Absolutes
+
+“Under five seconds is accessible,” “a crossfade is always safe,” and “the media query makes the page WCAG AA compliant” are unsupported. A criterion's conformance level is not a reason to claim that another criterion covers its behavior.
+
+## Verification Contract
+
+The following cases are unexecuted test designs. Record actual outcomes in the consumer's evidence, including source revision, browser/OS, input, effective preference, and the asserted result.
+
+| Case | Required observation |
+| --- | --- |
+| Reduced motion is active before load | Essential content and actions appear without waiting for motion. |
+| Preference changes halfway through a transition | The active task settles once; no stranded overlay, stale focus, or rejected-promise error remains. |
+| Keyboard activates the same action | The destination and feedback match the pointer path. |
+| Animation support is removed | The state transition still completes. |
+| User pauses automatic information, then tabs away | The pause persists; resumption follows the documented policy. |
+| Visual completion feedback is removed | The result remains available visually and through relevant assistive technology. |
+
+Source inspection verifies the criterion distinctions. DOM checks can verify state and focus; recordings can reveal movement. Neither alone establishes vestibular comfort or screen-reader announcement behavior. Re-review when source conditions, effect ownership, or the target runtime changes.
+
+## Source, License, And Attribution
+
+Locally authored synthesis. All linked external sources were inspected on 2026-09-21. No upstream prose, example code, or assets are reproduced. `consumer_reference: not_applicable` because this guide selects no consumer implementation record.
+
+## IA Navigation
+
+Parent: [Motion](index.md).
+Next: [Interruption And Retargeting](interruption-and-retargeting.md).

package/motion/index.md

@@ -25,6 +25,13 @@ These workflows and worked cases are usable experimental guidance. Expected-resu
 - [Motion Vocabulary](vocabulary.md) maps observed behavior to implementation-neutral terms while preserving ambiguity.
 - [Motion Review Workflow](review-workflow.md) structures evidence-first review and remediation.
 - [Motion Practice Reference](practice-reference.md) classifies mechanics, heuristics, platform notes, and unsupported claims.
+- [Observed Choreography Transcription](observed-choreography.md) transcribes an observed scroll choreography into Scene Composition Contract vocabulary.
+
+## Source-Backed Deep Dives
+
+- [Accessible Motion And Equivalent Feedback](accessible-motion.md). Separate motion preferences, automatic updates, and equivalent feedback.
+- [Interruption And Retargeting](interruption-and-retargeting.md). Resolve repeated input, cancellation, and stale completion callbacks.
+- [Motion Rendering And Performance](rendering-and-performance.md). Choose native mechanisms and diagnose measured delivery failures.
 
 ## Domain Contract
 

package/motion/interaction-recipes.md

@@ -60,7 +60,13 @@ Trace: pending → cancellation requested → confirmed cancelled or completed;
 
 Use when direct manipulation previews a change before commitment. Separate the preview value from the committed value. Release on a valid target commits; cancellation restores or reconciles with the current model. A new gesture retargets from the presented position where continuity is intended. Provide a task-equivalent non-drag operation.
 
-Test release inside/outside, cancellation, pointer loss, a changing destination, and repeated reversal. Focus and the selected item must remain traceable while visual position changes. The engine or browser adapter owns gesture events; the product owns acceptance of the new value.
+The non-drag operation has two separate audiences. [WCAG 2.2 Success Criterion 2.5.7 Dragging Movements](https://www.w3.org/TR/WCAG22/#dragging-movements) (Level AA) asks that functionality operated by dragging also be achievable with a single pointer without dragging: a click or tap, not a held path. Its [Understanding document](https://www.w3.org/WAI/WCAG22/Understanding/dragging-movements.html) states that keyboard equivalence does not meet this criterion by itself unless those controls can also be clicked or tapped, and that the keyboard and single-pointer requirements are evaluated independently. A sortable list with arrow-key reordering therefore still needs pointer-operable move controls, and move buttons that only respond to a pointer still need keyboard operation.
+
+Two exceptions bound the criterion. Dragging may remain the only pointer method when it is essential to the task, and the criterion does not cover dragging that the user agent determines and the author has not modified, such as native scrolling. The alternative cannot itself be a path-based gesture such as a swipe or flick; the Understanding document's own examples are tapping a slider track, move controls beside a sortable item, and a text input for a precise value. It does cover content that suppresses native scrolling and interprets the drag itself, which includes a custom carousel, a canvas pan, or the art-surface swipe in [full-viewport scene navigation](#full-viewport-scene-navigation). Record an essential claim with its reason rather than assuming it.
+
+Failure cases: the alternative exists only in a keyboard handler; the alternative appears only on hover, so touch cannot reach it; the alternative commits a different value or skips the validation that release performs; the alternative moves the item but leaves focus or the announced position on the old location.
+
+Test release inside/outside, cancellation, pointer loss, a changing destination, and repeated reversal. Run the same task three ways (drag, single-pointer activation without movement, keyboard only) and compare the committed value and the final focus. Focus and the selected item must remain traceable while visual position changes. The engine or browser adapter owns gesture events; the product owns acceptance of the new value.
 
 ### Scroll-Driven Story
 
@@ -156,7 +162,7 @@ The [Interaction Lab](../examples/domain-interactions/README.md) provides a boun
 
 ## Source, License, And Attribution
 
-Locally authored recipes and HTML. The linked W3C APG pages and Media Queries Level 5 were rechecked on 2026-09-08 for the specific semantics and preference signal above. No upstream examples or timing prescriptions are copied.
+Locally authored recipes and HTML. The linked W3C APG pages and Media Queries Level 5 were rechecked on 2026-09-08 for the specific semantics and preference signal above. WCAG 2.2 (W3C Recommendation, 12 December 2024) and its Understanding page for Success Criterion 2.5.7 (updated 10 August 2026) were rechecked on 2026-09-19 for the criterion text, its two exceptions, and its relationship to keyboard operation; the Understanding page is informative, and the failure cases above are local and unexecuted. No upstream examples or timing prescriptions are copied.
 
 ## IA Navigation
 

package/motion/interruption-and-retargeting.md

@@ -0,0 +1,90 @@
+---
+type: Domain Guide
+title: Interruption And Retargeting
+description: Keep semantic intent, presented motion, cancellation, and teardown consistent under repeated input.
+domain: motion
+lifecycle: experimental
+provenance_kind: local
+reviewed_on: 2026-09-21
+---
+
+# Interruption And Retargeting
+
+Primary role: motion lifecycle and ownership guide.
+
+## Repository Boundary
+
+This page describes presentation behavior when an interaction is interrupted. Application state and request authority remain in [State Management](../design-engineering/state-management/index.md). A presentation controller cannot silently cancel a transaction or overwrite newer semantic intent.
+
+## Reusable Method
+
+For each transition, record four independent facts: the committed application state, the current user intent, the presented visual state, and the current transition identity. Choose which fact authorizes each callback. A visible intermediate frame is not necessarily a valid application state.
+
+### Source Findings
+
+| Source | Bounded finding | Consequence |
+| --- | --- | --- |
+| [Web Animations, cancellation](https://www.w3.org/TR/web-animations-1/#canceling-an-animation-section) | Cancelling a non-idle animation rejects its current finished promise with `AbortError` and resets timing state. | Treat expected cancellation separately from an implementation failure. |
+| [Web Animations, playback](https://www.w3.org/TR/web-animations-1/#the-animation-interface) | Play, pause, reverse, finish, and cancel are distinct operations. | Select an operation by desired lifecycle behavior, not its convenient name. |
+| [CSS Transitions Level 2](https://www.w3.org/TR/css-transitions-2/) | Transition events include cancellation; entry styling can be supplied with `@starting-style` when prior rendered styling is absent. | A normal end event is not the only exit path. |
+| [View Transitions Level 1](https://www.w3.org/TR/css-view-transitions-1/#viewtransition) | Skipping the visual transition does not prevent its DOM update callback. | Visual cancellation is not transaction rollback. |
+| [Pointer Events Level 3](https://www.w3.org/TR/pointerevents3/#the-pointercancel-event) | A pointer stream can be cancelled by the user agent. | A drag needs an explicit cancellation path, not only pointer-up handling. |
+
+These are specification contracts at the documents read on 2026-09-21. Draft maturity and API presence do not prove behavior on a target browser; name the tested implementation separately.
+
+### Choose The Interruption Policy
+
+| Policy | Suitable local scenario | Cost or boundary |
+| --- | --- | --- |
+| Retarget from current presentation | A panel is asked to close before it finishes opening. | Sample or preserve the current pose; do not restart from a stale endpoint. |
+| Reverse the same effect | The underlying states and path are genuinely reversible. | Reversing visual time cannot undo committed external effects. |
+| Settle immediately | Motion is disabled, the surface is disposed, or presentation continuity is unimportant. | Preserve semantic state and focus even when no animation runs. |
+| Coalesce pending presentation | Several updates describe only the newest displayed reading. | Do not drop independent operation acknowledgements. |
+| Queue meaningful steps | The user explicitly needs a sequential demonstration. | Provide interruption or escape; state which queued events can be discarded. |
+
+The policy is a product proposal. Keep the queue bounded and its meaning explicit. A list of queued animations is not an audit log of business actions.
+
+### Worked Race: Open, Close, Open
+
+The user opens a details pane, closes it during entrance, and opens it again during exit. Give each new intent an identity. The oldest entrance completion may release its own animation handle, but it cannot mark the current pane closed, move focus, or remove the latest pane instance.
+
+| Event | Owner action | Invariant |
+| --- | --- | --- |
+| Open A | Commit open intent; establish an accessible pane and entrance effect. | Required semantics do not wait for an effect to finish. |
+| Close B during A | Invalidate A's authority; choose the exit policy and focus destination. | A's completion cannot restore open intent. |
+| Open C during B | Invalidate B; retarget or settle from the current presentation. | B cannot remove C's DOM instance. |
+| B's delayed completion | Clean up only B's resources. | Current intent remains C. |
+| Dispose surface | Invalidate all callbacks; release listeners and handles. | No later callback changes focus or another surface. |
+
+Specify when leaving content stops accepting input. If an exiting visual remains on screen after the semantic close, it must not leave a second active focus surface. Conversely, a modal's focus containment must remain correct until the chosen modal-close operation occurs. Review that timing with the [native interaction contract](../design-engineering/native-interaction-contracts.md).
+
+## Opinionated Guidance
+
+Prefer one owner per animated property and one lifecycle owner per surface. When multiple effects compose, explicitly name the composite rule and cleanup ownership. Do not use a timer equal to a nominal duration as the authority for saving data, unlocking an action, or removing a currently reused element.
+
+For direct manipulation, preserve the position reached by the user. Whether a release should preserve velocity, overshoot, or snap is a local perceptual decision; no spring parameter follows from this ownership model.
+
+## Platform-Specific Guidance
+
+CSS events, Web Animations promises, framework unmount hooks, and native gesture callbacks have different lifecycle semantics. Bind them through the same declared policy without claiming interchangeable APIs. Coordinate reduced-motion settlement through [Accessible Motion](accessible-motion.md).
+
+## Unsupported Absolutes
+
+`cancel()` does not mean “restore the original screen.” A resolved animation promise does not prove a server operation succeeded. A reverse animation does not guarantee that focus, history, or side effects were reversed.
+
+## Verification Contract
+
+Run repeated input at several points in the effect, including immediately before completion. The points are race probes, not statistically representative samples. Record request/intent identity, callback identity, final state, focused element, and remaining active effects.
+
+Exercise normal completion, cancellation, reversal, removal, reduced-motion change, and pointer cancellation. Inject a late callback from the previous transition and verify it cannot remove or refocus the current instance. Compare the no-animation path against the same semantic outcomes.
+
+These are unexecuted scenarios. A model test can prove callback acceptance rules in that model; actual event order and visual continuity require browser evidence. Re-review after a lifecycle adapter or animation API changes.
+
+## Source, License, And Attribution
+
+Locally authored synthesis of the linked specifications, inspected 2026-09-21. No upstream implementation is copied. `consumer_reference: not_applicable` because the example specifies a proposed interaction and selects no consumer record.
+
+## IA Navigation
+
+Parent: [Motion](index.md).
+Next: [Rendering And Performance](rendering-and-performance.md).

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).