@prestyj/cli 5.28.0 → 5.28.1

package/assets/motion/fonts/fonts.json

@@ -205,5 +205,61 @@
         "stretch": "75% 112.5%"
       }
     ]
+  },
+  {
+    "family": "Unbounded",
+    "dir": "unbounded",
+    "license": "OFL-1.1",
+    "use": "Wide, rounded display face for big titles.",
+    "files": [
+      {
+        "file": "unbounded-normal.woff2",
+        "style": "normal",
+        "weight": "200 900",
+        "stretch": null
+      }
+    ]
+  },
+  {
+    "family": "Sora",
+    "dir": "sora",
+    "license": "OFL-1.1",
+    "use": "Clean geometric sans for body text and captions.",
+    "files": [
+      {
+        "file": "sora-normal.woff2",
+        "style": "normal",
+        "weight": "100 800",
+        "stretch": null
+      }
+    ]
+  },
+  {
+    "family": "Short Stack",
+    "dir": "short-stack",
+    "license": "OFL-1.1",
+    "use": "Casual handwritten feel.",
+    "files": [
+      {
+        "file": "short-stack-normal.woff2",
+        "style": "normal",
+        "weight": "400",
+        "stretch": null
+      }
+    ]
+  },
+  {
+    "family": "Finger Paint",
+    "dir": "finger-paint",
+    "license": "OFL-1.1",
+    "use": "Playful painted, childlike handwritten feel.",
+    "files": [
+      {
+        "file": "finger-paint-normal.woff2",
+        "style": "normal",
+        "weight": "400",
+        "stretch": null
+      }
+    ]
   }
 ]

package/assets/motion/fonts/short-stack/OFL.txt

@@ -0,0 +1,94 @@
+Copyright (c) 2011 by Sorkin Type Co (www.sorkintype.com),
+with Reserved Font Name "Short Stack".
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+http://scripts.sil.org/OFL
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded, 
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

package/assets/motion/fonts/sora/OFL.txt

@@ -0,0 +1,93 @@
+Copyright 2019 The Sora Project Authors (https://github.com/sora-xor/sora-font)
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+
+This license is copied below, and is also available with a FAQ at: https://scripts.sil.org/OFL
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded, 
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

package/assets/motion/fonts/unbounded/OFL.txt

@@ -0,0 +1,93 @@
+Copyright 2022 The Unbounded Project Authors (https://github.com/googlefonts/unbounded)
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+https://scripts.sil.org/OFL
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded, 
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

package/assets/motion/library/README.md

@@ -102,3 +102,5 @@ project's `CREDITS.md` when added.
   2–3 scene recipes.
 - `sample.html`: a one-scene composition that shows the look, used for its
   preview. It links `assets/fonts/fonts.css` and `assets/looks/<id>.css`.
+  Videos should instead paste the `head` that `library.mjs look` returns: it
+  declares the fonts in the page, which `hf check` requires.

package/assets/motion/plugin.json

@@ -1,5 +1,5 @@
 {
   "name": "hyperframes",
   "version": "0.8.82",
-  "description": "EZ Motion's authored recipes and support skills, backed by the pinned HyperFrames runtime. Release-managed by GG; no self-updates."
+  "description": "EZ Motion's skills and craft references, backed by the pinned HyperFrames runtime. Release-managed by GG; no self-updates."
 }

package/assets/motion/references/motion-language.md

@@ -0,0 +1,128 @@
+# Motion language
+
+Use this for every video you design. The user's brand kit, references or a
+chosen library look override any default below. These are principles, not a
+house look. Choose the concept, palette and type fresh for every video; never
+copy an earlier video's.
+
+## The bar
+
+Make a showcase piece, as if the best motion designers will judge it frame by
+frame. Ambition means deliberate craft, not length or effect count. Every
+colour, word, cut and ease needs a reason. Cut generic defaults: plain fades,
+slowly drifting gradients, text that slides up and sits there. Judge it as the
+kind of video it is: an explainer by how clearly it teaches, a tribute by how
+it honours its subject, a launch by how it makes people want the product.
+
+## Plan first
+
+Before writing code, decide these and record them in the `Concept` and
+`Language` lines of `frame.md`. A few lines is enough; nobody approves them.
+
+- **Concept**: the idea the video demonstrates, in one sentence. Show it; don't
+  just state it.
+- **Motif**: one shape or element that recurs and links every scene.
+- **Register**: the tone (calm, playful, urgent, tender, precise…) and what it
+  means for size, speed, easing and colour. Take it from the brief, the brand
+  and the viewing context.
+- **Palette**: each colour's role.
+- **Type**: each family's role.
+- **Beat**: tempo, arc and frame rate.
+
+## Principles
+
+**Register.** Map the tone to motion before choosing anything else. Quiet,
+steady motion carries information and reading; expressive motion is saved for
+the moments that matter, because it only reads as special against calm. These
+pairings are illustrative, not presets: calm is long, soft moves and few of
+them; playful is springy overshoot, squash and stretch; luxurious is slow and
+precise with generous space; urgent is fast moves and hard cuts; tender is
+warm, slow and held; technical is precise and snapping.
+
+**Continuity.** Each scene hands something to the next: a shape, a word, a
+colour field or a camera move. Prefer match cuts and shape handoffs to
+cross-fades. The `type-as-spatial-handoff` study in [README.md](README.md) shows
+type becoming the next scene.
+
+**Palette.** A few colours, each with a role, derived from the brand, subject or
+references. How many, how saturated and how often the frame changes colour
+follow the register: full-frame colour blocks that change on most cuts suit a
+loud, kinetic piece; a calm, tender or documentary piece holds a steadier field
+and lets one accent carry attention. Gradients and glows are seasoning, not the
+base. Keep text readable.
+
+**No harmful flashing.** Anything flashing over more than about 3% of the frame
+counts. Keep light/dark swaps, and swaps to and from saturated red, to at most
+six in any one second (three flashes): faster flashing can trigger seizures,
+and `motion_check` fails it. A swap on every beat at 120 BPM is fine; a white
+flash frame on every half-beat is not.
+
+**Type.** Choose faces for the register and the reading job. Size follows the
+viewing context and how much there is to read: a kinetic poster can set one to
+three huge words per shot; an explainer, documentary or lyric video sets whole
+lines at a comfortable reading size. Size type against the frame's shorter side
+(in vertical video, the width inside the safe margins) and check that the
+longest word fits. Animate weight and width axes as motion, not only position
+and opacity. Use one display family, at most one contrasting voice, such as an
+italic serif, and small uppercase tracked mono for labels and UI where the
+subject calls for it. Bundled axes (see `fonts.mjs list` and its specimen):
+weight and width in Mona Sans, Hubot Sans, Anybody, Archivo, Bricolage
+Grotesque and Martian Mono; italics in Fraunces and Newsreader. Brand fonts win.
+
+**Motion.** Smooth by default, bounce by choice. Entrances settle on the
+critically damped spring or `power3.out` / `expo.out`; exits `power3.in`; moves
+`power3.inOut` or `expo.inOut`. Overshoot (`back.out`, `elastic.out` or an
+underdamped spring) is a register chosen for playful or physical work, never
+the default; see [easing](runtime/gsap-easing-and-stagger.md). Durations follow
+the register: roughly 0.15–0.5 s for snappy, energetic or technical motion, and
+0.6–1.5 s or longer for calm, luxurious or tender work. Staggers run 0.012–0.06 s
+for type and longer for larger elements. Use real animation principles where
+they help: anticipation before big moves, squash and stretch on impact, arcs
+instead of straight paths, overlapping action, follow-through and smears on fast
+moves. Lead with one movement at a time, with smaller overlapping motion under
+it. Every move starts, travels and lands on purpose; nothing drifts without a
+reason.
+
+**Pace.** Keep time on a grid: the track's beats (`hf beats`) when there is
+music, otherwise a tempo chosen for the register. Cut by how much there is to
+take in, not by the grid alone: a simple image can last one beat; a line to
+read or an idea to grasp holds for several. Meaningful text stays still and
+readable for at least the longer of 0.8 s and one second per 15 characters,
+longer for the key line; repeated or decorative words can go faster. Vary the
+density (build, release, rest) so the video is neither always fast nor always
+slow. Shape the whole to its form, with a beginning, development, peak and
+resolution even in five seconds. Illustratively: a launch builds to its
+product, an explainer steps through its idea, a lyric video follows the song's
+sections, a tribute lets each moment breathe. End on a composed frame held long
+enough to read, and declare that hold in the hold plan before checking.
+
+**3D, when the subject earns it.** One hero object whose material, light and
+camera come from the concept and register, not a stock tech look; add
+supporting elements only when they mean something. Resolve 3D back to flat 2D to
+hand off to the next scene. Use the bundled Three.js (`three.mjs`); no 3D by
+default.
+
+**Chrome, when it suits.** A small persistent mono layer (labels, timecode,
+chapter name, a progress bar with markers) makes a tech subject feel like a pro
+tool. Leave it out elsewhere.
+
+**Frame rate.** 30 fps suits most work. Use 60 fps when fast, dense motion or
+scrolling UI must read smoothly; it doubles render time. Renders carry no
+motion blur, so fast moves stutter at 24 fps: keep 24 fps for slow, filmic or
+handmade work.
+
+**Truth.** Show only real product UI, numbers and claims from the user's
+sources.
+
+## Building blocks
+
+Library looks (`library.mjs list looks`) are complete palette, type and rhythm
+systems; when one fits the concept, it replaces the palette and type choices
+above. Library pieces are optional building blocks.
+
+## Check against the plan
+
+When `motion_check` returns frames, compare them with the plan in `frame.md` as
+well as the technical results. A lost motif, an off-palette colour, a generic
+transition or unreadable type is a concrete defect: fix it and check the new
+render.

package/assets/motion/references/runtime/determinism-rules.md

@@ -15,7 +15,7 @@ For GSAP:
 - **Do not** call `tl.play()` for render-critical motion.
 - **Do not** create empty tweens only to set duration; use `data-duration` on the clip instead.
 
-Use the adjacent `gsap.md`, `gsap-timeline-and-labels.md` and `gsap-easing-and-stagger.md` for GSAP mechanics. These technical references do not override the selected recipe's geometry, timing or allowed input changes.
+Use the adjacent `gsap.md`, `gsap-timeline-and-labels.md` and `gsap-easing-and-stagger.md` for GSAP mechanics. These technical references do not choose the design; the video's plan in `frame.md` does.
 
 ## Determinism Rules
 
@@ -41,9 +41,9 @@ Build the visible end-state in static HTML and CSS first, then animate from/to t
 - **The root composition's total duration (render length / frame count) is fixed at compile time**, read once from the static root `data-duration` before scripts run, like `data-width` / `data-height`. A script or `--variables` value that rewrites the root `data-duration` afterward is ignored. To vary render length per output, author the root `data-duration` directly. (A _clip's_ own `data-duration` is re-read from the live DOM, so scripts/variables can still drive clip lengths. Only when the root omits `data-duration` does the renderer probe the live DOM / timeline for total length.)
 - Scene containers should fill the scene with `width: 100%; height: 100%; box-sizing: border-box`.
 - Use padding, flex, grid, and `max-width` for layout. Avoid positioning main content with hardcoded `top`/`left` offsets when a layout container can do it.
-- Preserve the recipe's positioning model. Absolute layers are appropriate when reproducing authored source geometry; generic layout preferences must not alter it.
+- Absolute layers are appropriate for deliberately placed design elements; keep one positioning model per scene.
 - Prefer transforms and opacity for animation.
-- Keep text inside its intended container. Only use wrapping, resizing or `window.__hyperframes.fitTextFontSize(text, { maxWidth, fontFamily, fontWeight })` when the recipe permits that fit policy; otherwise resolve the input conflict.
+- Keep text inside its intended container. Wrap, resize or use `window.__hyperframes.fitTextFontSize(text, { maxWidth, fontFamily, fontWeight })` deliberately; never let text clip silently.
 - For text measurement without DOM reflow, use `window.__hyperframes.pretext`. Measure off a canvas instead of writing into the page and reading it back, so nothing reflows: `pretext.prepare(text, font)` then `pretext.layout(prepared, maxWidth, lineHeight)` → `{ lineCount, height }`. `prepare` does the font measurement; everything downstream of a prepared string is arithmetic and cheap enough to run per frame. `fitTextFontSize` is built on it.
   - `layout` gives you height, not width. To size a container to its text (shrinkwrap), use `pretext.prepareWithSegments(text, font)` and then `pretext.measureNaturalWidth(prepared)` for the single-line width, or `pretext.measureLineStats(prepared, maxWidth)` for `{ lineCount, maxLineWidth }`.
   - `font` is a CSS font shorthand string, e.g. `"700 90px Inter"`.

package/assets/motion/references/runtime/gsap-easing-and-stagger.md

@@ -6,19 +6,19 @@ Built-in eases: `power1`, `power2`, `power3`, `power4`, `back`, `bounce`, `circ`
 
 Each has `.in`, `.out`, `.inOut` variants.
 
-| Ease                                       | Use for                                                                                         |
-| ------------------------------------------ | ----------------------------------------------------------------------------------------------- |
-| `power1.out`, `power2.out`                 | Gentle motion for secondary elements (a caption fade, a small shift). NOT the entrance default. |
-| `power3.out` (house default), `power4.out` | The standard long-tail settle. Entrances, title cards, hero reveals.                            |
-| `sine.inOut`                               | Long, slow, calm motion. Crossfades, ambient drift.                                             |
-| `back.out(1.7)`                            | Overshoot then settle. RARE — explicitly-playful register only, never a default.                |
-| `elastic.out(1, 0.3)`                      | Springy bounce. Same playful-only rule; prefer a baked spring (see Spring Eases below).         |
-| `expo.inOut`                               | Snappy, dramatic. Quick transitions between hero scenes.                                        |
-| `none` (linear)                            | Camera moves with timed counterpoint, mechanical motion.                                        |
+| Ease                                       | Use for                                                                                                 |
+| ------------------------------------------ | ------------------------------------------------------------------------------------------------------- |
+| `power1.out`, `power2.out`                 | Gentle motion for secondary elements (a caption fade, a small shift). NOT the entrance default.         |
+| `power3.out` (house default), `power4.out` | The standard long-tail settle. Entrances, title cards, hero reveals.                                    |
+| `sine.inOut`                               | Long, slow, calm motion. Crossfades, ambient drift.                                                     |
+| `back.out(1.7)`                            | Overshoot then settle. A chosen register (playful, physical), never a default.                          |
+| `elastic.out(1, 0.3)`                      | Springy bounce. Same register rule; prefer a baked spring (see Spring Eases below).                     |
+| `expo.inOut`                               | Snappy, dramatic. Quick transitions between hero scenes.                                                |
+| `none` (linear)                            | Camera moves with timed counterpoint, mechanical motion.                                                |
 
 Pick `.out` for entrances, `.in` for exits, `.inOut` for symmetric moves and continuous motion.
 
-**Smooth beats bouncy** — the motion doctrine (`rules/spring-pop-entrance.md`, the workflows' `motion-language.md`): entrances default to `power3.out` or the baked critically-damped spring (see Spring Eases below); overshoot eases (`back` / `elastic` / `bounce`) are a rare, explicitly-playful register, never the house style.
+**Smooth by default, bounce by choice** — the same rule as the Motion section of [`motion-language.md`](../motion-language.md): entrances default to `power3.out` or the baked critically-damped spring (see Spring Eases below); overshoot eases (`back` / `elastic` / `bounce`, or an underdamped spring) are a register the brief chooses for playful or physical work, never the house style.
 
 ## Easing Vocabulary (character & mood)
 
@@ -29,15 +29,15 @@ The full palette by character (each family has `.in`, `.out`, `.inOut` variants)
 | Family               | Character                                                                    | Typical use                                                                                                                                  |
 | -------------------- | ---------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
 | `power1`–`power4`    | Gentle (1) to aggressive (4) acceleration curves                             | General purpose. **power3 is the house workhorse**; power2 for gentle secondary motion, power4 for dramatic snaps                            |
-| `back(N)`            | Overshoot then settle. N controls how far past the target (1=subtle, 4=wild) | RARE — explicitly-playful register only, never a default. Keep N ≤ 2; prefer a baked spring at ζ 0.6–0.7 (physical settle, see Spring Eases) |
-| `elastic(amp, freq)` | Spring bounce. amp=magnitude, freq=oscillation speed                         | RARE — same playful-only rule; the baked spring (below) is the physical version                                                              |
-| `bounce`             | Ball-drop bouncing                                                           | RARE — physical-comedy register only (something literally dropping)                                                                          |
+| `back(N)`            | Overshoot then settle. N controls how far past the target (1=subtle, 4=wild) | Chosen register only (playful, physical), never a default. Keep N ≤ 2; prefer a baked spring at ζ 0.6–0.7 (physical settle, see Spring Eases) |
+| `elastic(amp, freq)` | Spring bounce. amp=magnitude, freq=oscillation speed                         | Same register rule; the baked spring (below) is the physical version                                                                         |
+| `bounce`             | Ball-drop bouncing                                                           | Physical-comedy register only (something literally dropping)                                                                                 |
 | `expo`               | Extreme acceleration curve (much steeper than power4)                        | Premium/luxury reveals, dramatic entrances                                                                                                   |
 | `sine`               | Smooth, organic, no hard edges                                               | Ambient float, breathing, Ken Burns, anything that loops. `.inOut` for yoyo motion                                                           |
 | `circ`               | Circular acceleration (starts very fast, ends very gentle or vice versa)     | Camera moves, scene transitions, orbital motion                                                                                              |
 | `steps(N)`           | Discrete N-step jumps, no interpolation                                      | Typing effects, cursor blink, counter ticks, retro/digital aesthetics                                                                        |
 
-**Mood mapping:** Match easing character to the beat's emotional content. Smooth/organic easings (`sine`, `power1`) feel contemplative and drifting. Aggressive deceleration (`power4.out`, `expo.out`) feels snappy and confident. Spring overshoot (`back.out`) feels bouncy and physical — but bouncy is a register, not an emphasis tool; reach for it only on explicitly-playful beats. The storyboard's mood description should guide which character fits — not a formula.
+**Mood mapping:** Match easing character to the beat's emotional content. Smooth/organic easings (`sine`, `power1`) feel contemplative and drifting. Aggressive deceleration (`power4.out`, `expo.out`) feels snappy and confident. Spring overshoot (`back.out`) feels bouncy and physical — but bouncy is a register, not an emphasis tool; reach for it only when the brief's register is playful or physical. The register recorded in `frame.md` should guide which character fits — not a formula.
 
 ## Defaults
 
@@ -58,7 +58,7 @@ Setting defaults at timeline scope is preferred — it documents the motion lang
 
 ## Spring Eases (baked physics, seek-safe)
 
-The "iOS feel" is a **damped spring's velocity curve**, not a bounce: a fast launch into a long asymptotic settle. Well-made system animations are critically damped or close to it — they barely overshoot, or don't at all. `power3.out` / `expo.out` approximate that curve; when you want the exact one — or a _physical_ overshoot for the rare playful register — bake the spring's closed-form solution into a function ease.
+The "iOS feel" is a **damped spring's velocity curve**, not a bounce: a fast launch into a long asymptotic settle. Well-made system animations are critically damped or close to it — they barely overshoot, or don't at all. `power3.out` / `expo.out` approximate that curve; when you want the exact one — or a _physical_ overshoot for a playful register — bake the spring's closed-form solution into a function ease.
 
 Why not a real-time spring library: an interactive spring is a stateful integrator (velocity accumulates frame to frame), which cannot be seeked deterministically — you'd have to simulate frames 0…N−1 to render frame N. The closed form below is a **pure function of progress** — no state, nothing to desync, seek-safe by construction. This is also why interaction-lib spring solvers are banned in compositions.
 
@@ -67,7 +67,7 @@ Why not a real-time spring library: an interactive spring is a stateful integrat
 // response         ≈ seconds one oscillation would take (0.3–0.6 for entrances)
 // dampingFraction  1.0       = critically damped — smooth settle, NO overshoot (house default)
 //                  0.80–0.85 ≈ the iOS system register — ~1–1.5% overshoot, felt not seen
-//                  0.60–0.70 = explicitly playful — ~5–10% overshoot (rare; replaces back.out)
+//                  0.60–0.70 = playful register — ~5–10% overshoot (by choice; replaces back.out)
 function springEase({ response = 0.5, dampingFraction = 1 } = {}) {
   const w = (2 * Math.PI) / response; // undamped natural frequency
   const z = dampingFraction;
@@ -120,20 +120,20 @@ tl.fromTo(
 | ----------------- | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
 | **1.0 (default)** | none (monotone) | The house settle — the exact curve `power3.out` approximates. Product / enterprise / serious tone.                                                 |
 | 0.80–0.85         | ~1–1.5%         | "Alive, not bouncy" — the iOS system default register. The overshoot is felt, not seen.                                                            |
-| 0.60–0.70         | ~5–10%          | Explicitly-playful ONLY (same rule as `back.out`, which this replaces — a spring's second-order settle reads physical where `back` reads cartoon). |
+| 0.60–0.70         | ~5–10%          | Playful register, by choice (same rule as `back.out`, which this replaces — a spring's second-order settle reads physical where `back` reads cartoon). |
 | < 0.55            | > 12%           | Don't. Cartoon-wobble territory.                                                                                                                   |
 
 | response  | duration (ζ=1) | feel                                                         |
 | --------- | -------------- | ------------------------------------------------------------ |
 | 0.25–0.35 | 0.37–0.51s     | tight snap — chips, small UI                                 |
 | 0.35–0.50 | 0.51–0.74s     | standard entrance                                            |
-| 0.50–0.70 | 0.74–1.03s     | weighted hero landing — check the `t ≤ 0.5s` visibility rule |
+| 0.50–0.70 | 0.74–1.03s     | weighted hero landing — when the shot opens on it, start it early so the subject is seen within about half a second |
 
 Craft notes:
 
 - **ζ=1 vs `power3.out`**: the true spring front-loads harder (~67% vs ~58% travelled at quarter-time) and settles on a longer asymptotic tail; max shape difference ~11%. That long tail is the "premium" read — use it when the settle IS the shot (a wordmark landing, a final lockup).
 - **At ζ<1, overshooting curves go on transforms only** — never on `opacity` (it would push past 1) or color. Split opacity onto its own `power2.out` tween at the same timeline position.
-- **Doctrine unchanged**: ζ below ~0.8 is still the rare, explicitly-playful exception (`rules/spring-pop-entrance.md`). The default of this section is ζ=1 — real spring physics is not a license for bounce.
+- **Default unchanged**: ζ below ~0.8 is a register the brief chooses, never a default. The default of this section is ζ=1 — real spring physics is not a license for bounce.
 
 ## Stagger
 

package/assets/motion/references/runtime/gsap.md

@@ -56,13 +56,13 @@ For transforms, autoAlpha, clearProps, and SVG specifics see `./gsap-transforms-
 
 ## Animated properties
 
-Prefer these efficient targets when they preserve the recipe's behaviour:
+Prefer these efficient targets when they achieve the intended motion:
 
 - **Compositor-cheap**: `opacity`, `x`, `y`, `scale`, `scaleX`, `scaleY`, `rotation`, `rotationX`, `rotationY`, `skewX`, `skewY`, `transformOrigin`
 - **Visual fills**: `color`, `backgroundColor`, `borderColor`, `borderRadius`
 - **CSS variables**: `"--hue": 180` etc.
 - **Media `volume`** (on `<audio>` / `<video>`): do not tween it for fades or ducking; use the `data-automation` volume lane (see `data-attributes.md`). A lane wins over a tween on the same element.
-- **DOM text `innerText`** (for numeric counters): tween it directly, e.g. `tl.to(el, { innerText: 100, snap: { innerText: 1 } })` — `snap` keeps it integer; the GSAP inspector recognizes it as a counter. Use a deterministic proxy value with `onUpdate` for locale formatting or suffix logic when the selected recipe needs it.
+- **DOM text `innerText`** (for numeric counters): tween it directly, e.g. `tl.to(el, { innerText: 100, snap: { innerText: 1 } })` — `snap` keeps it integer; the GSAP inspector recognizes it as a counter. Use a deterministic proxy value with `onUpdate` for locale formatting or suffix logic when the design needs it.
 
 **Avoid** (use the transform alias instead):
 
@@ -80,7 +80,7 @@ Prefer these efficient targets when they preserve the recipe's behaviour:
 - `./gsap-timeline-and-labels.md` — timeline creation, position parameter (`+=`, `<`, `>`), labels, nesting, sub-comp `fromTo` preference, playback control.
 - `./gsap-easing-and-stagger.md` — easing families, stagger objects, function-based values, `gsap.matchMedia()`, `gsap.defaults()`.
 - `./gsap-transforms-and-perf.md` — transform aliases, autoAlpha, `quickTo`, `will-change`, performance rules.
-- The selected recipe defines effects and motion mechanisms; these API examples are not additional creative instructions.
+- The video's plan defines effects and motion; these API examples are not additional creative instructions.
 
 ## Best Practices