@impractical-ai/motion 0.1.7 → 0.1.9

package/assets/engine.d.ts

@@ -41,6 +41,48 @@ export type TransitionResult = {
   root: HTMLElement
 }
 
+export type ThroughOpts = {
+  /** Takeover color. Default: the target's effective background (first
+   * non-transparent backgroundColor walking up from the target), read at
+   * build time. */
+  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 target exactly covers the frame at the cut.
+   * Default 1.15, so a few px of layout drift can never expose an edge. */
+  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 +98,21 @@ export type TransitionKit = {
     opts?: TransitionOpts,
     position?: gsap.Position
   ) => TransitionResult
+  /** The go-through: dive the camera INTO an element 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
+   * the target, measures the target 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 target's color at the cut so the
+   * takeover is guaranteed to the pixel. 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 ─────────────────────────
@@ -1427,7 +1484,14 @@ 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, { swap?, land?, color?, duration?,
+   * outDuration? }, position?)` is the GO-THROUGH: dive INTO an element
+   * until its color takes over the frame, world-swap under the cover, pull
+   * out into the new world. Never hand-roll a dive (a magic-scale
+   * camera.move + a hand-timed swap): through() computes the exact cover
+   * scale, measures the target 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' }`. */

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-NVZQJBVP.js}

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

package/dist/{chunk-Z74SLKEU.js → chunk-H5TR3QJN.js}

@@ -3,7 +3,7 @@
 // package.json
 var package_default = {
   name: "@impractical-ai/motion",
-  version: "0.1.7",
+  version: "0.1.9",
   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 = "fd0fa24" ? "fd0fa24" : "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-KI5E2464.js}

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

package/dist/{chunk-M7SHFM25.js → chunk-NG3Q3BYW.js}

@@ -6,14 +6,14 @@ import {
   loadConfig,
   recoverCorruptConfig,
   saveConfig
-} from "./chunk-MQKW7NFI.js";
+} from "./chunk-KI5E2464.js";
 import {
   PACKAGE_COMMAND,
   PACKAGE_NAME,
   PACKAGE_VERSION,
   PRODUCTION_APP_URL,
   PRODUCTION_SUPABASE_URL
-} from "./chunk-Z74SLKEU.js";
+} from "./chunk-H5TR3QJN.js";
 
 // src/onboarding.ts
 import {
@@ -30,6 +30,7 @@ import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { spawnSync } from "node:child_process";
+import { createRequire } from "node:module";
 var CLAUDE_MARKETPLACE = "Openpod/impractical-agent-plugins";
 var CLAUDE_PLUGIN = "impractical-motion@impractical";
 var CLAUDE_MARKETPLACE_NAME = "impractical";
@@ -426,7 +427,7 @@ Official setup guide: ${CLAUDE_INSTALL_URL}`
     throw new Error(`${label} is required before setup can continue.`);
   }
 }
-function hasChrome() {
+function hasSystemChrome() {
   const macPaths = [
     "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
     "/Applications/Chromium.app/Contents/MacOS/Chromium"
@@ -437,11 +438,62 @@ function hasChrome() {
     return !result.error && result.status === 0;
   });
 }
+function playwrightCli() {
+  try {
+    const require_ = createRequire(import.meta.url);
+    const cli = join(dirname(require_.resolve("playwright-core/package.json")), "cli.js");
+    return existsSync(cli) ? cli : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function managedBrowserPath() {
+  const cli = playwrightCli();
+  if (!cli) return void 0;
+  const probe = spawnSync(
+    process.execPath,
+    [cli, "install", "--dry-run", "chromium-headless-shell"],
+    { encoding: "utf8", windowsHide: true }
+  );
+  if (probe.error || probe.status !== 0) return void 0;
+  const match = /^\s*Install location:\s*(.+?)\s*$/m.exec(probe.stdout ?? "");
+  return match?.[1];
+}
+function hasManagedBrowser() {
+  const path = managedBrowserPath();
+  return Boolean(path && existsSync(path));
+}
+function ensureRenderBrowser(log = () => {
+}) {
+  if (hasManagedBrowser()) return;
+  const cli = playwrightCli();
+  if (!cli) {
+    if (hasSystemChrome()) return;
+    throw new Error(
+      "A browser is required to inspect video frames, and the bundled installer could not be found. Install Google Chrome, or run `npx playwright-core install chromium-headless-shell`."
+    );
+  }
+  log("Installing a headless browser for frame capture (one time, a few hundred MB)...");
+  const result = spawnSync(process.execPath, [cli, "install", "chromium-headless-shell"], {
+    stdio: "inherit",
+    windowsHide: true
+  });
+  if (!result.error && result.status === 0) {
+    log("Headless browser ready.");
+    return;
+  }
+  if (hasSystemChrome()) {
+    log("Could not install the headless browser; falling back to your installed Chrome.");
+    return;
+  }
+  throw new Error(
+    "Could not install a browser for frame capture, and no Chrome or Chromium was found. Install Google Chrome, or run `npx playwright-core install chromium-headless-shell` and re-run setup."
+  );
+}
 function verifyClaudePrerequisites() {
   const major = Number(process.versions.node.split(".")[0]);
   if (!Number.isInteger(major) || major < 22) throw new Error("Node.js 22 or newer is required.");
   requireCommand("claude", "Claude Code");
-  if (!hasChrome()) throw new Error("Google Chrome or Chromium is required to inspect video frames.");
 }
 function runClaude(args, log, tolerateAlreadyInstalled = false) {
   const result = commandResult("claude", args);
@@ -618,6 +670,7 @@ async function setup(options) {
   if (options.installAgentMcp) {
     verifyAgentPrerequisites();
   }
+  ensureRenderBrowser(options.log);
   const corruptConfigBackup = recoverCorruptConfig();
   if (corruptConfigBackup) {
     options.log(`Backed up invalid configuration to ${corruptConfigBackup}; starting clean.`);

package/dist/{commands-R3LJU2BW.js → commands-56WH3ZVJ.js}

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   setup
-} from "./chunk-M7SHFM25.js";
+} from "./chunk-NG3Q3BYW.js";
 import {
   invoke,
   invokeAt,
@@ -11,8 +11,8 @@ import {
   saveConfig,
   studioLink,
   waitForJobs
-} from "./chunk-MQKW7NFI.js";
-import "./chunk-Z74SLKEU.js";
+} from "./chunk-KI5E2464.js";
+import "./chunk-H5TR3QJN.js";
 import "./chunk-77HVPD4G.js";
 
 // src/commands.ts

package/dist/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   PACKAGE_VERSION
-} from "./chunk-Z74SLKEU.js";
+} from "./chunk-H5TR3QJN.js";
 import "./chunk-77HVPD4G.js";
 
 // src/cli-args.ts
@@ -140,11 +140,11 @@ async function runCli(args, deps) {
 // src/index.ts
 runCli(process.argv.slice(2), {
   writeLine: (line) => console.log(line),
-  loadCommands: () => import("./commands-R3LJU2BW.js"),
-  loadApi: () => import("./api-DR3NJ7TI.js"),
-  loadMcp: () => import("./stdio-XUVQKDCB.js")
+  loadCommands: () => import("./commands-56WH3ZVJ.js"),
+  loadApi: () => import("./api-NVZQJBVP.js"),
+  loadMcp: () => import("./stdio-MJ4LTXME.js")
 }).catch(async (error) => {
-  const { ApiError } = await import("./api-DR3NJ7TI.js");
+  const { ApiError } = await import("./api-NVZQJBVP.js");
   if (error instanceof ApiError) {
     console.error(`Error (${error.status} from ${error.fn}): ${error.message}`);
     if (error.status === 429) console.error("Weekly MCP allowance reached. Upgrade or wait for Monday UTC.");