@impractical-ai/motion 0.1.7 → 0.1.10

package/assets/engine.d.ts

@@ -41,6 +41,75 @@ export type TransitionResult = {
   root: HTMLElement
 }
 
+/** What the camera dives through. Every mode computes its own geometry —
+ * never hand-tune margins or wrap glyphs in spans to fake these. */
+export type ThroughVia =
+  | 'surface' // the element's face: its rect covers the frame (default)
+  | 'glyph' // one character's COUNTER (the enclosed hole) covers the frame
+  | 'word' // one word's rect covers the frame
+  | 'anchor'
+
+export type ThroughOpts = {
+  /** Dive mode. Default 'surface'. 'glyph' needs `char` (or `charIndex`),
+   * 'word' needs `word`; both address plain text — no wrapper spans.
+   * 'anchor' dives toward the element and, at the cut, match-frames the
+   * element matching the SAME selector in the post-swap world (its twin),
+   * so the subject persists while everything around it changes. */
+  via?: ThroughVia
+  /** glyph mode: the character to dive through — first occurrence in the
+   * target's text. The dive passes through its enclosed counter (o, e, a,
+   * 0…); characters without a hole throw with a diagnostic. */
+  char?: string
+  /** glyph mode: 0-based index into the target's text, instead of `char`. */
+  charIndex?: number
+  /** word mode: the word to dive through — first occurrence. */
+  word?: string
+  /** Takeover color. Defaults: surface/anchor — the target's effective
+   * background (first non-transparent backgroundColor walking up from the
+   * target); glyph/word — the surface BEHIND the text (the walk starts at
+   * the text element's parent), i.e. what actually shows through the
+   * counters. */
+  color?: string
+  /** Dive duration in seconds. Default 0.5. */
+  duration?: number
+  /** Dive ease. Default 'power3.in' (accelerates into the surface). */
+  ease?: string
+  /** Cover overshoot: 1.0 = the dive geometry (element rect, glyph counter,
+   * or word rect per `via`) exactly covers the frame at the cut. Default
+   * 1.15, so a few px of drift can never expose an edge. Override only for
+   * taste — every mode measures its own geometry, so no mode NEEDS a
+   * hand-tuned margin. */
+  margin?: number
+  /** The world swap, applied as seek-safe `tl.set`s at the exact cut moment
+   * while the frame is fully covered: `hide` gets autoAlpha 0, `show` gets
+   * autoAlpha 1. For anything richer, place your own `tl.set`s at the
+   * returned `cutAt` time. */
+  swap?: { hide?: gsap.TweenTarget; show?: gsap.TweenTarget }
+  /** Element in the post-swap world to ARRIVE from: at the cut the camera
+   * snaps to this element's own cover framing (measured after the swap), so
+   * releasing the overlay reveals it filling the frame, and the pull-out
+   * starts inside the new world — the match-frame landing. Omit to pull out
+   * from the dive's own framing. */
+  land?: string | Element
+  /** Framing the pull-out settles on. Default the full frame
+   * `{ scale: 1, x: 0, y: 0 }`. */
+  settle?: { scale: number; x: number; y: number }
+  /** Pull-out duration. Default 1.0. */
+  outDuration?: number
+  /** Pull-out ease. Default 'expo.out'. */
+  outEase?: string
+}
+
+export type ThroughResult = {
+  /** Full span: dive + pull-out. */
+  duration: number
+  /** Absolute timeline time of the cut — the frame is guaranteed fully
+   * covered here; schedule extra world-swap `tl.set`s at this time. */
+  cutAt: number
+  /** The takeover overlay's root element. */
+  root: HTMLElement
+}
+
 export type TransitionKit = {
   /** Cover the frame — put this at the end of a clip. Appends to the
    * timeline's end when no position is given. */
@@ -56,6 +125,29 @@ export type TransitionKit = {
     opts?: TransitionOpts,
     position?: gsap.Position
   ) => TransitionResult
+  /** The go-through: dive the camera INTO something until its color takes
+   * over the whole frame, cut worlds under the cover, then pull out into the
+   * new world. NEVER hand-roll this (a magic-scale zoom + a hand-timed
+   * `tl.set` swap + a re-aim) — through() computes the exact cover scale for
+   * its dive geometry, measures it in its state AT THE DIVE'S START TIME
+   * (entrances, moves, and tilts since build are all accounted for), and
+   * snaps a full-frame overlay in the right color at the cut so the
+   * takeover is guaranteed to the pixel. Four dive modes via `opts.via`:
+   * 'surface' (default — the element's face), 'glyph' (through one
+   * character's enclosed counter: `{ via: 'glyph', char: 'o' }` on plain
+   * text, no wrapper span — the hole is measured from the actual glyph
+   * outline, so the margin is computed, never tuned), 'word' (`{ via:
+   * 'word', word: 'world' }` — the word's rect), and 'anchor' (match-cut:
+   * dive toward the element, swap the world at the cut, and land on the
+   * element matching the same selector in the new world, so the subject
+   * persists while everything around it changes). Deterministic: every
+   * value is resolved once at build; the swap is `tl.set`s, never
+   * callbacks. Appends at the timeline's end when no position is given. */
+  through: (
+    target: string | Element,
+    opts?: ThroughOpts,
+    position?: gsap.Position
+  ) => ThroughResult
 }
 
 // ─── Text — named, deterministic text animations ─────────────────────────
@@ -1050,11 +1142,16 @@ export type SentenceHandle = {
 // ─── Morph — any element becomes any other element ───────────────────────
 
 export type MorphOpts = {
-  /** 'apple' = expo-out flight (~90% of the change in the first ~15% of the
-   * time, long soft landing). 'spring' = the reference bounce: expo-out
-   * flight, then a LIGHT damped sine rides the same path — calibrated from
-   * the dnyxstudios AE expression (amp .04·v, freq 1.8Hz, decay e^-3t,
-   * eased envelope). One motion, no delayed settle, ~one visible overshoot. */
+  /** 'apple' = a firm in-out flight that keeps the deformation READABLE —
+   * the shape change is the subject, so it may not be over in three frames.
+   * 'spring' = the same flight with the reference bounce: a LIGHT damped
+   * sine riding the same path, calibrated from the dnyxstudios AE expression
+   * (amp .04·v, freq 1.8Hz, decay e^-3t, eased envelope). One motion, no
+   * delayed settle, ~one visible overshoot.
+   *
+   * Both are `ease-in-out-*` by design. A morph is travel WITHIN the frame,
+   * and the house table reserves `ease-out-*` for entrances; a front-loaded
+   * curve finishes the transformation before the viewer can look at it. */
   feel?: 'apple' | 'spring'
   /** Tune the 'spring' bounce. `amp` = first overshoot as a fraction of the
    * travel (default 0.025 — light), `freq` Hz (default 1.8), `decay` per
@@ -1065,17 +1162,26 @@ export type MorphOpts = {
   /** Flight curve — ANY GSAP ease works: house names, 'elastic.out(1, 0.4)',
    * 'back.out(1.8)'… Overshoots extrapolate past the target (kept renderable). */
   ease?: string
-  /** 0..1 — center of the A→B crossfade along the flight. */
+  /** 0..1 in EASED space — where along the SHAPE CHANGE the surface swaps
+   * from A to B. Not a fade midpoint: at this instant both sides hold the
+   * same box and the same chrome, so the swap is a match-frame cut. 0.5
+   * means "when the shape is halfway between the two," which is what the
+   * viewer actually perceives. */
   handoff?: number
-  /** Width of the crossfade as a fraction of the flight (default 0.3 —
-   * tight; each side shows only near its natural shape). */
-  crossfade?: number
+  /** Fraction of the flight over which unmatched content departs and
+   * arrives (default 0.42). Content displaces along the travel vector and
+   * must be clear of the seam — that emptiness is what makes the cut
+   * invisible, so widening this past ~0.5 will start to show the swap. */
+  content?: number
   /** Arc lift in px (0 disables). Default: auto from travel distance. */
   arc?: number
-  /** Part choreography (default 'stagger'): the target's direct children
-   * arrive individually inside the landing box; the source's children are
-   * absorbed as it leaves. `false` = containers only. */
-  parts?: 'stagger' | false
+  /** Content choreography (default 'displace'): unmatched children leave and
+   * arrive by moving ALONG the travel vector — replacement reads as motion,
+   * and both sides are clear of the seam before the surfaces swap.
+   * `false` = containers only; children hold still and stay counter-scaled,
+   * which is right when the two sides share a background image or the
+   * content is meant to look continuous. */
+  parts?: 'displace' | false
   /** Sub-component matching (default 'auto'): elements tagged
    * `data-morph="name"` on BOTH sides (any depth) morph INTO each other —
    * each pair rides its own interpolated box inside the flight, so the
@@ -1368,9 +1474,12 @@ export type DirectionContext = {
      * a long dwell at both ends and a confident glide through the middle.
      * These defaults ARE the recommended camera physics: do NOT pass ease
      * or duration here unless the user explicitly asks for a different
-     * camera feel. The two sanctioned exceptions: a slow ambient drift
-     * (`duration: 2–5, ease: 'none'`) and an instant reframe behind a
-     * covering element (`duration: 0.01`). Anything between 0.05–0.4s is
+     * camera feel. The one sanctioned exception: an instant reframe behind
+     * a covering element (`duration: 0.01`). A slow linear drift
+     * (`duration: 2–5, ease: 'none'`) is NOT one — sub-pixel motion on the
+     * whole stage re-rasterizes every glyph each frame and renders as
+     * micro-flicker; the motion lab flags it as DRIFT and export blocks.
+     * Hold the camera still instead. Anything between 0.05–0.4s is
      * neither a move nor a cut — avoid it. `ease-in-out-cubic` is for
      * ELEMENT travel, never the camera. */
     move: (
@@ -1427,7 +1536,21 @@ export type DirectionContext = {
    * 'pixels', 'iris', opts `{ color?, direction?: 'left'|'right'|'up'|
    * 'down', duration?, cell?, at? }`. `out` with no position appends at the
    * clip's end — the standard way to end a clip for a cut; `in` at position
-   * 0 starts the clip covered and reveals it. All return `{ duration }` (full span including
+   * 0 starts the clip covered and reveals it.
+   * `transition.through(target, { via?, char?, word?, swap?, land?, color?,
+   * duration?, outDuration? }, position?)` is the GO-THROUGH: dive INTO
+   * something until its color takes over the frame, world-swap under the
+   * cover, pull out into the new world. `via` picks the dive geometry:
+   * 'surface' (default, the element's face), 'glyph' (`{ via: 'glyph',
+   * char: 'o' }` — through the character's enclosed counter, measured from
+   * the real glyph outline on plain text: no wrapper spans, no hand-tuned
+   * margins), 'word' (`{ via: 'word', word: 'world' }` — the word's rect),
+   * 'anchor' (match-cut: the subject persists across the cut — the same
+   * selector's twin in the new world is the landing — while everything
+   * around it changes). Never hand-roll a dive (a magic-scale camera.move +
+   * a hand-timed swap): through() computes the exact cover scale, measures
+   * at the dive's own start time, and guarantees full coverage at the cut.
+   * All return `{ duration }` (full span including
    * stagger) for sequencing, and accept `(target, effect, opts?, position?)`
    * with opts `{ by?: 'chars'|'words'|'lines', duration?, stagger?, ease?,
    * from?: 'start'|'center'|'end'|'edges' }`. */
@@ -1596,10 +1719,17 @@ export type DirectionContext = {
    * eases the container instead of live reflow. */
   sentence: SentenceKit['sentence']
   /** Universal shape morph: any element becomes any other element, a rect, or
-   * `'frame'`. FLIP box + interpolated rounded-rect clip-path silhouette +
-   * content-clone crossfade (`handoff` sets where). Author the TARGET hidden
-   * (`autoAlpha: 0`); the morph reveals it at arrival. `fromPath`/`toPath`
-   * accept real SVG paths for logo endcards. Export-worker safe. */
+   * `'frame'`. Both real elements ride ONE interpolated box (position, size,
+   * corner radius, arc lift) while the source's chrome is driven onto the
+   * target's — at `handoff` the two are the same picture, so the surfaces
+   * HARD-CUT and never crossfade. Matched sub-components (`data-morph="name"`
+   * on both sides) travel; unmatched content displaces along the travel
+   * vector; children are counter-scaled so nothing stretches.
+   *
+   * Author the TARGET hidden (`autoAlpha: 0`); the morph reveals it at
+   * arrival. Every visual state is a pure function of eased progress, so it
+   * is export-worker safe. For MANY-to-many structure — recursing into
+   * sub-components, N→1 gathers, 1→N splits — install `kit/morphtree`. */
   morph: MorphKit['morph']
   /** The chip⇄full-bleed round trip: grows the element to cover the frame,
    * holds, returns home (`back: false` to stay). Scale IS the transition —
@@ -1700,8 +1830,9 @@ export type BuiltScene = {
 //   promo-in     ease-in-quart   (.895,.03,.685,.22) — exits, dives
 //
 // Rule of thumb from the reference promos: entrances ~0.4–0.6s on promo-out
-// (visually settled inside 0.15s), line staggers ~0.2s, holds carry a slow
-// linear scale drift (~4%/s, ease 'none'), pops that need bounce use
+// (visually settled inside 0.15s), line staggers ~0.2s, holds are held STILL
+// (a slow linear scale drift re-rasterizes glyphs every frame and renders as
+// micro-flicker — never add one), pops that need bounce use
 // back.out(1.8–2), and background/color cuts are HARD (no crossfade).
 
 /** Registered ease names usable anywhere GSAP accepts an ease. */

package/assets/impractical/SKILL.md

@@ -10,7 +10,7 @@ build, the render, and the studio the user tweaks in — you provide the
 direction. Everything runs through the **Impractical MCP server**; the video's
 source code lives in the cloud, never in the user's project directory.
 
-## 0. Setup check (once per session)
+## Setup check (once per session)
 
 Call the `account_status` tool (`whoami` is its legacy alias). If the
 Impractical tools are not available, the current coding agent is not connected.
@@ -19,269 +19,41 @@ Tell the user to run:
     npx --yes @impractical-ai/motion setup --agent
 
 Then ask them to restart or reload their coding agent and type `continue`.
-Claude Code users who specifically want the full plugin can run the same command
-with `--claude` instead. If the weekly quota is exhausted, call `upgrade` to give
-the user the authenticated billing page.
-
-## 1. Read the engine before you write anything
-
-Call **`engine_types`** first. It returns the TypeScript surface a scene is
-written against: the `ctx` object, every named text/logo/transition effect with
-its options, the named eases, and the determinism rules. Writing a direction
-without reading it produces slop.
-
-## 2. Make a video
-
-Before scaffolding, call **`motion_context`** with the user's brief — plus
-`brandSlug` and `contentType` when you know them. It returns the current
-versioned house skills, the best matching production references, available
-template schemas, and rendered reference frames. Study those frames and sources
-before choosing a template. The library is live: do not rely on a remembered
-catalog from an earlier session.
-
-When the workspace has personalization enabled, the result also carries the
-user's resolved motion profile: `personalStyleSkill` (confirmed preferences —
-follow it like house guidance), `acceptedExamples`, a reranked
-style/template order, and a `contextId`. Pass that `contextId` to
-`create_video` as `motionContextId` so the draft is pinned to the
-recommendations that produced it.
-
-Gather from the user (ask only for what's missing):
-
-- **Value prop** (required): one or two sentences on what ships and why it matters.
-- Optional: their product's front-end code, a brand URL, screen recordings.
-
-Before `create_video`, write a compact creative contract. This is a planning
-record, not a new scene format:
-
-- audience
-- the single idea the viewer should remember
-- the visual moment that proves it without explanatory copy
-- how the reference's hierarchy/pacing will be translated rather than copied
-- the real product source (and whether anything must be reconstructed)
-- opening, proof, and payoff
-
-When the local quality-loop experiment is enabled, pass that contract as
-`creativeContract` to `create_video`. The tool will reject an unplanned start.
-
-If they gave a brand URL and no kit exists yet:
-
-    brand_list
-    brand_extract  { url: "https://example.com" }
-    brand_extract  { jobId: "<returned run id>", wait: true }
-
-Then scaffold the project:
-
-    create_video  { valueProp: "...", brandSlug?: "example-com", appCode?: "...", templateId?: "...", templateParams?: {...} }
-
-This creates the project and a draft with starter files. It deliberately does
-**not** run a server-side director — you are the director.
-
-## 3. Direct it
-
-A scene is two files, and both must exist for the preview to build:
-
-- **`App.tsx`** — the stage markup. Plain React and CSS; this is the product UI
-  on screen.
-- **`direction.ts`** — the choreography. `export default (ctx) => { ... }`
-  against one paused GSAP timeline.
-
-Write them with `write_draft_files` (whole files) or `edit_draft_file` (exact
-string replacement — prefer this for revisions). Every save rebuilds the
-preview and returns the committed revision plus its build job id immediately.
-Follow that id with `job_status { jobIds: ["..."], wait: true }`; that result is
-your compile loop, so read and fix any build error rather than guessing.
-
-Rules that matter:
-
-- `brand.json` is law for colors and fonts. Read it; do not invent a palette.
-- Never edit `project.json`.
-- The timeline is rendered by seeking frame by frame. Anything that is not a
-  pure function of timeline position — `Date.now()`, `Math.random()`,
-  `setTimeout`, CSS animations, autoplaying `<video>` — desynchronises the
-  export. Use `ctx.video()` for footage.
-- Only `.ts/.tsx/.js/.jsx/.css/.json` files sync, max 100 per draft.
-
-Craft, briefly — the full language is `guidance.motionDirection` in the
-`motion_context` result. That copy is live and versioned; this summary is a
-snapshot, so when the two disagree, the tool result wins.
-
-- **Beat it out before writing code.** Every beat needs a time, a visible
-  subject, and a narrative purpose. An intentional reading hold is valid.
-- **Text enters on `rise`** — `text.reveal(el, 'rise')` on `promo-out`, lines
-  ~0.2s apart. Do *not* default type to `'blur'`: word-by-word de-blur reads as
-  out-of-focus, and across a stagger it turns to mush. Blur is for whole-frame
-  moves — `fx.spike(el, 'blur')` alongside a whip or dive, where it hides the
-  cut. Never animate blur above 20px.
-- **Every ease is a named house curve.** `ease-out-*` for entrances,
-  `ease-in-out-*` for travel and every camera move, `ease-in-*` for exits and
-  dives only. Never leave an ease unspecified; never put `ease-in-*` on an
-  entrance. The promo subset: `promo-out`, `promo-soft`, `promo-inout`,
-  `promo-in`, `launch-out`.
-- **Decisive**: entrances 0.4–0.6s, exits shorter, staggers ~0.2s apart.
-  Longer movement needs a narrative reason; important states may hold still.
-- Budget one primary and at most one supporting motion. Keep backgrounds stable
-  unless their movement is explicitly authored.
-- Hold long enough to read. A beat that looks legible scrubbing the timeline is
-  usually still too fast on screen.
-- Cut hard between sections; crossfading backgrounds reads as cheap.
-- One idea per beat. If two things move for different reasons at once, split them.
-
-### The five moves that separate a real video from a generated one
-
-These are the engine's `ctx.fx` and `ctx.mask` kits. Reaching for them is most
-of the gap between output that looks authored and output that looks scripted.
-Full signatures are in the engine types; the rules of thumb are:
-
-1. **Hide every whip cut with one spike, never two tweens.**
-   ```ts
-   camera.move(camera.framing('[data-next]'), { duration: 0.28, ease: 'promo-inout' }, 'whip')
-   fx.spike('[data-panel]', 'blur', { amount: 14 }, 'whip')     // ONE call
-   ```
-   Hand-writing `tl.to(stage, { filter: 'blur(12px)' })` up and back is the
-   single most common way this looks amateur: the two tweens drift out of sync
-   and the user gets two unlinked controls. `fx.spike` is one tween, in and
-   out, locked to the move.
-
-2. **Feather full-frame reveals.** `mask.reveal(el, 'feather', { direction, softness: 0.3 })`
-   — a hard edge across a whole frame reads cheap, and `clip-path` cannot make
-   a soft one at all. Use `wipe`/`iris`/`slit`/`barn` when you want the hard
-   edge deliberately; `radial` and `blinds` for softer variety.
-
-3. **Land on light, not on opacity.** One `fx.spike(el, 'bloom')` as a beat
-   settles reads as a light source. Fading opacity reads as a slideshow.
-
-4. **Put colour inside the letters.** `mask.fill(el, { gradient, drift })` uses
-   `background-clip: text`, so the gradient lives in the glyphs and moves
-   through them. Far stronger than a coloured headline, and one call.
-
-5. **Composite light instead of shipping a PNG.**
-   `mask.blend(disc, 'screen')` behind type gives glow with no asset.
-   `multiply` for ink on cream, `luminosity` for duotone.
-
-Two things to get right or the effect misfires:
-
-- **Grain must be continuous.** Apply it once to a full-frame plate that sits
-  above every beat and is never cut (`fx.apply(plate, 'grain', { amount: 0.2 })`),
-  or it visibly blinks at each hard cut.
-- **Effects are seasoning.** One or two per beat. `displace`, `chroma`, and
-  `threshold` are accents for a single hit, not a look to hold.
-
-Ask `motion_context` for the **`optical`** style to see all of this composed in
-one reference, or the **`whip-cut`**, **`soft-reveal`**, and **`gradient-type`**
-templates for a working scene you can adapt.
-
-## 4. Look at your work
-
-    get_frames  { draftId: "...", times: [0, 1, 2, 3] }
-
-This renders real frames on the user's machine and returns them as images. Ask
-for several times in one call — once the page is open the extra frames are
-nearly free.
-
-**Always look at frames before telling the user a change is done.** If a frame
-shows text clipped, an element off-frame, or a blank region, fix it and look
-again. This is the difference between shipping a video and shipping a guess.
-
-When the `get_motion` tool is available (the local motion lab experiment),
-prefer it as the first look after every preview build:
-
-    get_motion  { draftId: "..." }                       // whole scene
-    get_motion  { draftId: "...", from: 4.8, to: 6.4 }   // one weak window
-
-Static frames measure composition; `get_motion` measures motion — dense
-contact sheets where the difference between adjacent tiles IS the motion,
-plus measured pixel change per interval, dead-air spans, and the timeline's
-actual tweens with any that run without producing visible change. Fix what it
-flags, then use `get_frames` for composition close-ups.
-
-With the quality loop also enabled, the final review is two-part and export
-requires both on the same revision: `get_frames { reviewMode: "final" }` for
-composition and legibility at native resolution, and
-`get_motion { draftId, reviewMode: "final" }` for full-duration motion
-coverage at one frame in five.
-
-For a new launch video, build and review the proof beat before completing the
-rest. When the local quality loop is enabled:
-
-    get_frames  { draftId: "...", times: [/* proof beat */], reviewMode: "proof" }
-
-For the final pass, review at least eight representative timestamps including
-`t=0` and the settled closing frame:
-
-    get_frames  { draftId: "...", times: [/* whole timeline */], reviewMode: "final" }
-
-The final critic scores the visible result—not the code or effort—on narrative
-clarity, visual proof, product authenticity, composition, legibility, pacing,
-reference fidelity, and technical integrity. Use timestamped evidence. A weak
-score is a revision brief, not permission to describe the cut as “clean.”
-
-## 5. Export and hand off
-
-    export_video  { draftId: "...", qualityReview?: {/* required by local quality loop */} }
-    job_status    { jobIds: ["<returned job id>"], wait: true }
-    studio_link   { projectId: "...", slug: "..." }
-
-Always give the user the studio link — that is where they watch the cuts and
-tweak visually. The export URL expires, so only export once they are happy.
+Claude Code users who specifically want the full plugin can run the same
+command with `--claude` instead. If the weekly quota is exhausted, call
+`upgrade` to give the user the authenticated billing page.
+
+## Get the playbook, then follow it
+
+The full, current director playbook is SERVED, not bundled: call **`motion_context`**
+with the user's brief (plus `brandSlug` and `contentType`
+when known). Its `guidance.director` field carries the complete house playbook
+for this library version — workflow, review discipline, export rules. Read it
+and follow it before writing any scene code. `engine_types` returns the
+TypeScript contract a scene is written against; read it before writing a
+direction.
+
+## The tool loop (the shape; the served playbook has the craft)
+
+Create with `create_video`, then write `App.tsx` and `direction.ts` with
+`write_draft_files` (whole files) or `edit_draft_file` (exact string
+replacement — prefer it for revisions). Every save rebuilds the preview and
+returns the committed revision plus its build job id immediately; follow that
+id with `job_status` and fix any build error it returns. Call `install_kits`
+once right after `create_video` — the kit sources are served into the draft.
+`brand_extract` builds a brand kit from a URL. Call `get_frames` to SEE the
+result before telling the user it is done, then `export_video`, then hand the
+user the `studio_link`.
 
 ## Timeouts and lost acknowledgements
 
 Build, export, and brand-extraction calls return their job or run id before
-waiting. Continue build/export ids with `job_status`, and continue a brand run
-with `brand_extract { jobId, wait: true }` (never the URL again). If the MCP
-client kills any call and shows only a timeout, the mutation may still have
-committed even though its acknowledgement was lost.
-**Never blindly retry a mutating or metered call.** Verify state first:
-
-- After `write_draft_files` / `edit_draft_file`, use `list_draft_files` and
-  `read_draft_file` to confirm the intended revision and source.
-- After an export or other project mutation, use `get_project` / `list_projects`
-  to check whether it already started or completed.
-- After `brand_extract`, continue its returned id with `brand_extract { jobId, wait: true }`. If the
-  start acknowledgement was lost, check `brand_list` / `brand_get` before
-  starting another extraction, especially when `reextract: true`.
-
-Retry only when those reads prove the mutation did not commit. Otherwise
-continue from the state you observed; a duplicate edit or export wastes quota.
-
-## The personal motion profile
-
-The `motion_profile` tool manages what Impractical remembers about this user's
-taste. The rules are strict because trust in the profile depends on them:
-
-- **Read before directing.** The personalized context from `motion_context`
-  already includes the resolved profile; call `motion_profile { action: 'get' }`
-  only when the user asks about their profile or you need rule keys.
-- **`remember` is for explicit requests only** — "remember that I like…",
-  "always keep my videos under 15 seconds". Never call `remember` for a
-  preference you merely inferred.
-- **Inferred preferences go through `propose`.** If the user's feedback during
-  this session implies a durable preference, submit it as a structured rule
-  with `propose`. It becomes a pending proposal that has zero effect until the
-  user confirms it.
-- **Present at most one pending proposal, and only after a completed video.**
-  If `motion_context` returned `pendingProposal`, mention it once after the
-  export or when the user is clearly done — one sentence, e.g. "Want me to
-  remember that you prefer faster pacing? (yes/no)". Call `confirm` or
-  `reject` with their answer. Never present more than one, never mid-work, and
-  **never silently confirm**.
-- The user can `pause`, `forget` a single rule, or `reset` everything; do these
-  only when asked.
-
-## Conflicts
-
-The web tweak chat edits the same draft. `edit_draft_file` reads, edits and
-writes in one call against the current revision, so ordinary races resolve
-themselves. If a tool reports the draft changed underneath your edit, re-read
-the file and re-apply your change on top of the new content — never paste stale
-content back.
-
-If a tool reports the draft is locked by a job, wait for that job with
-`job_status { wait: true }` and retry.
-
-## Costs
-
-- Preview builds and exports run on Impractical's infrastructure; the direction
-  thinking is yours, so iterate on the code freely.
-- Preview rebuilds take tens of seconds. Batch your edits, then look at frames.
+waiting. If the MCP client kills a call and shows only a timeout, the mutation
+may still have committed. **Never blindly retry a mutating or metered call.**
+Verify state first: after a write, use `list_draft_files` and
+`read_draft_file` to confirm the intended revision; after an export, check
+`get_project`; after `brand_extract`, continue its returned id.
+Retry only when those reads prove the mutation did not commit.
+
+Before directing an existing draft, read `notes.json` — the user's queued
+edits come first; mark each handled item `done`.

package/dist/{api-DR3NJ7TI.js → api-4WE4LYPB.js}

@@ -13,8 +13,8 @@ import {
   waitForJobs,
   withAdmissionReceipt,
   withMeteredCall
-} from "./chunk-MQKW7NFI.js";
-import "./chunk-Z74SLKEU.js";
+} from "./chunk-CZANULCU.js";
+import "./chunk-6FVZ6IWR.js";
 import "./chunk-77HVPD4G.js";
 export {
   ApiContractError,

package/dist/{chunk-Z74SLKEU.js → chunk-6FVZ6IWR.js}

@@ -3,7 +3,7 @@
 // package.json
 var package_default = {
   name: "@impractical-ai/motion",
-  version: "0.1.7",
+  version: "0.1.10",
   private: false,
   description: "Create and refine Impractical Motion videos from coding agents and the terminal.",
   homepage: "https://github.com/Openpod/impractical-motion#readme",
@@ -28,9 +28,9 @@ var package_default = {
     node: ">=22"
   },
   scripts: {
-    build: 'node ../scripts/verify-locked-cli-install.mjs && node ../scripts/build-engine-dts.mjs --cli-only && rm -rf dist && ./node_modules/esbuild/bin/esbuild src/index.ts --bundle --platform=node --format=esm --target=node22 --splitting --outdir=dist --external:playwright-core --banner:js="#!/usr/bin/env node" && chmod +x dist/index.js',
+    build: 'node ../scripts/verify-locked-cli-install.mjs && node ../scripts/build-engine-dts.mjs --cli-only && rm -rf dist && ./node_modules/esbuild/bin/esbuild src/index.ts --define:__BUILD_COMMIT__=\\"$(git rev-parse --short HEAD 2>/dev/null || echo dev)\\" --bundle --platform=node --format=esm --target=node22 --splitting --outdir=dist --external:playwright-core --banner:js="#!/usr/bin/env node" && chmod +x dist/index.js',
     typecheck: "tsc --noEmit",
-    test: "npm run typecheck && npm run build && esbuild tests/onboarding.test.ts tests/mcp-tools.test.ts tests/mcp-frames.test.ts tests/mcp-motion.test.ts tests/mcp-motion-score.test.ts tests/mcp-install-font.test.ts tests/mcp-metric-catalog.test.ts tests/mcp-text-census.test.ts tests/mcp-phased-flow.test.ts tests/mcp-preflight.test.ts tests/engine-dts.test.ts tests/mcp-connect.test.ts tests/mcp-longpoll.test.ts tests/mcp-agent-timeout.test.ts tests/api-hardening.test.ts --bundle --platform=node --format=esm --packages=external --outdir=dist --out-extension:.js=.mjs && node --test dist/onboarding.test.mjs dist/mcp-tools.test.mjs dist/mcp-frames.test.mjs dist/mcp-motion.test.mjs dist/mcp-motion-score.test.mjs dist/mcp-install-font.test.mjs dist/mcp-metric-catalog.test.mjs dist/mcp-text-census.test.mjs dist/mcp-phased-flow.test.mjs dist/mcp-preflight.test.mjs dist/engine-dts.test.mjs dist/mcp-connect.test.mjs dist/mcp-longpoll.test.mjs dist/mcp-agent-timeout.test.mjs dist/api-hardening.test.mjs",
+    test: "npm run typecheck && npm run build && esbuild tests/onboarding.test.ts tests/mcp-tools.test.ts tests/mcp-frames.test.ts tests/mcp-browser-pool.test.ts tests/mcp-motion.test.ts tests/mcp-craft.test.ts tests/mcp-depthkit.test.ts tests/mcp-motion-score.test.ts tests/mcp-install-font.test.ts tests/mcp-metric-catalog.test.ts tests/mcp-text-census.test.ts tests/mcp-phased-flow.test.ts tests/mcp-preflight.test.ts tests/engine-dts.test.ts tests/mcp-connect.test.ts tests/mcp-longpoll.test.ts tests/mcp-agent-timeout.test.ts tests/api-hardening.test.ts --bundle --platform=node --format=esm --packages=external --outdir=dist --out-extension:.js=.mjs && node --test dist/onboarding.test.mjs dist/mcp-tools.test.mjs dist/mcp-frames.test.mjs dist/mcp-browser-pool.test.mjs dist/mcp-motion.test.mjs dist/mcp-craft.test.mjs dist/mcp-depthkit.test.mjs dist/mcp-motion-score.test.mjs dist/mcp-install-font.test.mjs dist/mcp-metric-catalog.test.mjs dist/mcp-text-census.test.mjs dist/mcp-phased-flow.test.mjs dist/mcp-preflight.test.mjs dist/engine-dts.test.mjs dist/mcp-connect.test.mjs dist/mcp-longpoll.test.mjs dist/mcp-agent-timeout.test.mjs dist/api-hardening.test.mjs",
     prepack: "npm run build"
   },
   publishConfig: {
@@ -56,6 +56,8 @@ var PRODUCTION_APP_URL = "https://motion.impractical.ai";
 var PRODUCTION_SUPABASE_URL = "https://uaxjweednprtbhbceify.supabase.co";
 var PACKAGE_NAME = "@impractical-ai/motion";
 var PACKAGE_VERSION = package_default.version;
+var BUILD_COMMIT = "779568a" ? "779568a" : "dev";
+var BUILD_ID = `${PACKAGE_VERSION}+${BUILD_COMMIT}`;
 var PACKAGE_COMMAND = `npx --yes ${PACKAGE_NAME}`;
 
 export {
@@ -63,5 +65,6 @@ export {
   PRODUCTION_SUPABASE_URL,
   PACKAGE_NAME,
   PACKAGE_VERSION,
+  BUILD_COMMIT,
   PACKAGE_COMMAND
 };

package/dist/{chunk-MQKW7NFI.js → chunk-CZANULCU.js}

@@ -2,7 +2,7 @@
 import {
   PRODUCTION_APP_URL,
   PRODUCTION_SUPABASE_URL
-} from "./chunk-Z74SLKEU.js";
+} from "./chunk-6FVZ6IWR.js";
 
 // src/config.ts
 import {