@impractical-ai/motion 0.1.9 → 0.1.11

package/README.md

@@ -34,6 +34,58 @@ Setup writes the API credential to `~/.impractical/config.json` with mode `0600`
 variables `IMPRACTICAL_API_KEY`, `IMPRACTICAL_SUPABASE_URL`, and `IMPRACTICAL_APP_URL` take
 precedence over that file.
 
+## Start from a shared video
+
+When the sender includes an editable project, the public video page has an
+**Edit this video** action. Its single command both connects your agent and
+copies the project into your workspace:
+
+```sh
+npx --yes @impractical-ai/motion@0.1.11 setup --agent --from https://impractical.ai/v/SHARE_TOKEN
+```
+
+Use the real URL copied from the page. Sign in when prompted, then restart your
+coding agent. The command prints your new project URL and a prompt containing
+its project ID. Drafts stay in your Impractical workspace and are edited through
+MCP; no source is executed or written into your current directory by this command.
+
+Already connected, or retrying an interrupted import:
+
+```sh
+npx --yes @impractical-ai/motion@0.1.11 clone https://impractical.ai/v/SHARE_TOKEN
+```
+
+Repeating the command returns the same copy for that share and workspace. The
+copy is independent of the sender's project. An MP4-only share cannot be cloned.
+
+## Choose who can edit a shared video
+
+Each link is **view only by default**. Upload without `--project` to share just
+the video and its public brand information; the page will hide **Edit this video**
+and the API will reject project-copy requests for that link:
+
+```sh
+npx --yes @impractical-ai/motion@0.1.11 share ./video.mp4 --title "For Acme" --references ./public-brand.json
+```
+
+`--project` explicitly lets recipients copy **all editable drafts and assets**
+from that project, so use a project you intend to share:
+
+```sh
+npx --yes @impractical-ai/motion@0.1.11 share ./video.mp4 --title "For Acme" --references ./public-brand.json --project PROJECT_ID
+```
+
+Enable cloning on an existing video share, or disable future clones:
+
+```sh
+npx --yes @impractical-ai/motion@0.1.11 share allow-editing SHARE_ID --project PROJECT_ID
+npx --yes @impractical-ai/motion@0.1.11 share view-only SHARE_ID
+```
+
+Detaching the source or revoking the video does not remove copies already owned
+by recipients. The existing upload API accepts the same opt-in as `projectId`.
+The shorter `share attach` and `share detach` aliases also remain supported.
+
 ## MCP server
 
 The installer configures supported clients to run:

package/assets/engine.d.ts

@@ -41,17 +41,44 @@ 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 = {
-  /** Takeover color. Default: the target's effective background (first
-   * non-transparent backgroundColor walking up from the target), read at
-   * build time. */
+  /** 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 target exactly covers the frame at the cut.
-   * Default 1.15, so a few px of layout drift can never expose an edge. */
+  /** 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
@@ -98,16 +125,24 @@ export type TransitionKit = {
     opts?: TransitionOpts,
     position?: gsap.Position
   ) => TransitionResult
-  /** The go-through: dive the camera INTO an element until its color takes
+  /** 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
-   * the target, measures the target in its state AT THE DIVE'S START TIME
+   * 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 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. */
+   * 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,
@@ -1107,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
@@ -1122,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
@@ -1425,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: (
@@ -1485,13 +1537,20 @@ export type DirectionContext = {
    * '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.
-   * `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
+   * `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' }`. */
@@ -1660,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 —
@@ -1764,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/dist/{api-NVZQJBVP.js → api-FMMG3W6J.js}

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

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

@@ -3,7 +3,7 @@
 // package.json
 var package_default = {
   name: "@impractical-ai/motion",
-  version: "0.1.9",
+  version: "0.1.11",
   private: false,
   description: "Create and refine Impractical Motion videos from coding agents and the terminal.",
   homepage: "https://github.com/Openpod/impractical-motion#readme",
@@ -56,7 +56,7 @@ 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_COMMIT = "9f06a02" ? "9f06a02" : "dev";
 var BUILD_ID = `${PACKAGE_VERSION}+${BUILD_COMMIT}`;
 var PACKAGE_COMMAND = `npx --yes ${PACKAGE_NAME}`;
 

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

@@ -6,14 +6,14 @@ import {
   loadConfig,
   recoverCorruptConfig,
   saveConfig
-} from "./chunk-KI5E2464.js";
+} from "./chunk-VTHAZQEV.js";
 import {
   PACKAGE_COMMAND,
   PACKAGE_NAME,
   PACKAGE_VERSION,
   PRODUCTION_APP_URL,
   PRODUCTION_SUPABASE_URL
-} from "./chunk-H5TR3QJN.js";
+} from "./chunk-HGA2O3JM.js";
 
 // src/onboarding.ts
 import {

package/dist/{chunk-KI5E2464.js → chunk-VTHAZQEV.js}

@@ -2,7 +2,7 @@
 import {
   PRODUCTION_APP_URL,
   PRODUCTION_SUPABASE_URL
-} from "./chunk-H5TR3QJN.js";
+} from "./chunk-HGA2O3JM.js";
 
 // src/config.ts
 import {
@@ -141,6 +141,9 @@ function bodyRecord(body) {
 function validateApiResponse(name, body, data) {
   if (!isRecord(data)) throw new ApiContractError(name, "a JSON object");
   const input = bodyRecord(body);
+  if (name === "video-shares" && input.action === "clone" && (typeof data.projectId !== "string" || !/^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(data.projectId) || typeof data.alreadyForked !== "boolean")) {
+    throw new ApiContractError(name, "a projectId and alreadyForked flag");
+  }
   if (name === "workspace-bootstrap") {
     const billing = data.billing;
     if (typeof data.orgId !== "string" || typeof data.plan !== "string" || typeof data.hasAccess !== "boolean" || !isRecord(billing) || typeof billing.status !== "string") {

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

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   setup
-} from "./chunk-NG3Q3BYW.js";
+} from "./chunk-SN6SLPIC.js";
 import {
   invoke,
   invokeAt,
@@ -11,8 +11,8 @@ import {
   saveConfig,
   studioLink,
   waitForJobs
-} from "./chunk-KI5E2464.js";
-import "./chunk-H5TR3QJN.js";
+} from "./chunk-VTHAZQEV.js";
+import "./chunk-HGA2O3JM.js";
 import "./chunk-77HVPD4G.js";
 
 // src/commands.ts
@@ -1204,6 +1204,133 @@ function buildInitialFiles(input) {
 // ../src/shared/video-models.ts
 var DEFAULT_OPENROUTER_VIDEO_MODEL = "anthropic/claude-opus-5";
 
+// ../src/shared/video-clone-command.ts
+var TOKEN = /^[A-Za-z0-9_-]{43}$/;
+var SHARE_HOSTS = /* @__PURE__ */ new Set(["impractical.ai", "www.impractical.ai", "impractical-video-shares.vercel.app"]);
+function videoShareToken(source) {
+  if (TOKEN.test(source)) return source;
+  try {
+    const url = new URL(source);
+    const token = url.pathname.match(/^\/v\/([A-Za-z0-9_-]{43})\/?$/)?.[1];
+    if (url.protocol === "https:" && SHARE_HOSTS.has(url.host) && !url.username && !url.password && !url.search && !url.hash && token) return token;
+  } catch {
+  }
+  throw new Error("Use an Impractical video share URL: https://impractical.ai/v/<token>");
+}
+
+// src/clone-video-project.ts
+async function cloneVideoProject(source, json = false) {
+  const token = videoShareToken(source);
+  const result = await invoke("video-shares", { action: "clone", token });
+  const url = studioLink(requireConfig().appUrl, result.projectId);
+  if (json) {
+    console.log(JSON.stringify({ ...result, url }, null, 2));
+    return;
+  }
+  console.log(result.alreadyForked ? "Your editable copy is ready." : "Copied the project into your workspace.");
+  console.log(`Open: ${url}`);
+  console.log(`Project: ${result.projectId}`);
+  console.log("After restarting your agent, paste:");
+  console.log(`Use Impractical to open project ${result.projectId} and help me iterate on this video.`);
+}
+
+// src/video-sharing.ts
+import { openAsBlob } from "node:fs";
+import { readFile, stat } from "node:fs/promises";
+import { basename as basename2, extname as extname2 } from "node:path";
+async function shareVideo(rest, flags) {
+  const config = requireConfig();
+  const request = async (body) => {
+    const response = await fetch(
+      `${config.supabaseUrl.replace(/\/$/, "")}/functions/v1/video-shares`,
+      {
+        method: body ? "POST" : "GET",
+        redirect: "error",
+        signal: AbortSignal.timeout(45e3),
+        headers: { authorization: `Bearer ${config.apiKey}`, "content-type": "application/json" },
+        body: body ? JSON.stringify(body) : void 0
+      }
+    );
+    const data = await response.json().catch(() => ({}));
+    if (!response.ok) throw new Error(data.error || `Video sharing failed (${response.status})`);
+    return data;
+  };
+  if (rest[0] === "list") {
+    console.log(JSON.stringify(await request(), null, 2));
+    return;
+  }
+  if (rest[0] === "revoke") {
+    if (!rest[1]) throw new Error("Usage: impractical share revoke <share-id>");
+    await request({ action: "revoke", id: rest[1] });
+    console.log("Share link revoked. Already-open videos may remain playable for up to 5 minutes.");
+    return;
+  }
+  const allowEditing = rest[0] === "allow-editing" || rest[0] === "attach";
+  const viewOnly = rest[0] === "view-only" || rest[0] === "detach";
+  if (allowEditing || viewOnly) {
+    if (!rest[1] || allowEditing && typeof flags.project !== "string") {
+      throw new Error("Usage: impractical share allow-editing <share-id> --project <id> | share view-only <share-id>");
+    }
+    await request({ action: "attach-project", id: rest[1], projectId: viewOnly ? null : flags.project });
+    console.log(allowEditing ? "Editing allowed for this link. Recipients can make their own editable copy." : "This link is now view only. Future project copies are disabled; existing recipient copies remain theirs.");
+    return;
+  }
+  const filePath = rest[0];
+  if (!filePath || extname2(filePath).toLowerCase() !== ".mp4") {
+    throw new Error(
+      'Usage: impractical share ./video.mp4 [--title "A video for Acme"] [--message "..."] [--references ./public-brand.json] [--project <id>] [--expires-in 7] [--json]'
+    );
+  }
+  const info = await stat(filePath);
+  if (!info.isFile() || info.size < 16 || info.size > 3e8) {
+    throw new Error("Choose an MP4 up to 300 MB");
+  }
+  const days = flags["expires-in"] === void 0 ? null : Number(flags["expires-in"]);
+  if (days !== null && (!Number.isFinite(days) || days <= 0 || days > 3650)) {
+    throw new Error("--expires-in must be a number of days between 0 and 3650");
+  }
+  const file = await openAsBlob(filePath, { type: "video/mp4" });
+  const header = new Uint8Array(await file.slice(0, 16).arrayBuffer());
+  if (String.fromCharCode(...header.slice(4, 8)) !== "ftyp") {
+    throw new Error("This file does not have an MP4 header");
+  }
+  let references;
+  if (typeof flags.references === "string") {
+    const metadataFile = await stat(flags.references);
+    if (!metadataFile.isFile() || metadataFile.size > 4e6) throw new Error("Public references must be a JSON file up to 4 MB");
+    references = JSON.parse(await readFile(flags.references, "utf8"));
+  }
+  const prepared = await request({
+    action: "prepare",
+    bytes: info.size,
+    title: typeof flags.title === "string" ? flags.title : basename2(filePath, extname2(filePath)).slice(0, 160),
+    message: typeof flags.message === "string" ? flags.message : "",
+    expiresAt: days === null ? null : new Date(Date.now() + days * 864e5).toISOString(),
+    ...references === void 0 ? {} : { references },
+    ...typeof flags.project === "string" ? { projectId: flags.project } : {}
+  });
+  try {
+    const form = new FormData();
+    form.append("cacheControl", "0");
+    form.append("", file, basename2(filePath));
+    const response = await fetch(prepared.upload.signedUrl, {
+      method: "PUT",
+      body: form,
+      headers: { "x-upsert": "false" },
+      redirect: "error",
+      signal: AbortSignal.timeout(15 * 6e4)
+    });
+    await response.body?.cancel();
+    if (!response.ok) throw new Error(`MP4 upload failed (${response.status}). Please try again`);
+    const share = await request({ action: "complete", id: prepared.id });
+    console.log(flags.json ? JSON.stringify(share, null, 2) : share.url);
+  } catch (error) {
+    await request({ action: "revoke", id: prepared.id }).catch(() => {
+    });
+    throw error;
+  }
+}
+
 // src/commands.ts
 var flagString = (flags, name) => {
   const value = flags[name];
@@ -1218,6 +1345,8 @@ var flagList = (flags, name) => {
 var flagBool = (flags, name) => flags[name] === true;
 var out = (line) => console.log(line);
 async function setup2(flags) {
+  const source = flagString(flags, "from");
+  if (source !== void 0) videoShareToken(source);
   const claude = flagBool(flags, "claude");
   const agent = flagBool(flags, "agent");
   await setup({
@@ -1227,6 +1356,11 @@ async function setup2(flags) {
     openBrowser: !flagBool(flags, "no-open"),
     log: out
   });
+  if (source !== void 0) await cloneVideoProject(source);
+}
+async function clone(positional, flags) {
+  if (positional.length !== 1) throw new Error("Usage: impractical clone <video-share-url> [--json]");
+  await cloneVideoProject(positional[0], flagBool(flags, "json"));
 }
 async function login(flags) {
   const patch = {};
@@ -1522,12 +1656,14 @@ function validateMeteredCommand(command, positional, flags) {
 }
 export {
   brand,
+  clone,
   exportDraft,
   generate,
   keys,
   link,
   login,
   setup2 as setup,
+  shareVideo,
   status,
   upload,
   validateMeteredCommand,

package/dist/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   PACKAGE_VERSION
-} from "./chunk-H5TR3QJN.js";
+} from "./chunk-HGA2O3JM.js";
 import "./chunk-77HVPD4G.js";
 
 // src/cli-args.ts
@@ -17,6 +17,7 @@ var CLI_OPTIONS = {
   brand: { type: "string" },
   asset: { type: "string", multiple: true },
   project: { type: "string" },
+  from: { type: "string" },
   feedback: { type: "string" },
   model: { type: "string" },
   slug: { type: "string" },
@@ -26,6 +27,11 @@ var CLI_OPTIONS = {
   out: { type: "string" },
   draft: { type: "string" },
   id: { type: "string" },
+  title: { type: "string" },
+  message: { type: "string" },
+  references: { type: "string" },
+  "expires-in": { type: "string" },
+  json: { type: "boolean" },
   wait: { type: "boolean" },
   agent: { type: "boolean" },
   claude: { type: "boolean" },
@@ -48,6 +54,7 @@ var HELP = `impractical \u2014 Impractical Motion from your terminal (and your c
 Setup
   setup --claude                Sign in and install the Claude plugin + MCP
   setup --agent                 Sign in and install MCP for detected coding agents
+        --from <video-share-url> Also copy the shared project into your workspace
   login --key imk_...           Manual credential override for development
   whoami                       Show org and plan status
   keys [list|revoke <id>]      List or revoke agent API keys
@@ -66,6 +73,14 @@ Edit drafts
   Editing happens through the MCP server (see "Agents" above) \u2014 draft source
   lives in the cloud, so there is no working copy to pull or push.
   link <projectId> [slug]      Print the studio tweak-UI URL
+  clone <video-share-url>      Add an editable copy to your connected workspace
+
+Share videos
+  share <file.mp4> [--title "..."] [--references brand.json] [--project <id>]
+        Omit --project for a view-only link (the default)
+  share allow-editing <share-id> --project <id>  Let recipients copy and edit
+  share view-only <share-id>   Hide editing and block future project copies
+  share list | share revoke <share-id>
 
 Assets & brands
   upload <file> --project <id> --draft <id>
@@ -97,6 +112,10 @@ async function runCli(args, deps) {
   switch (command) {
     case "setup":
       return commands.setup(flags);
+    case "clone":
+      return commands.clone(rest, flags);
+    case "share":
+      return commands.shareVideo(rest, flags);
     case "motion":
       if (rest[0] === "wizard") return commands.setup(flags);
       break;
@@ -140,11 +159,11 @@ async function runCli(args, deps) {
 // src/index.ts
 runCli(process.argv.slice(2), {
   writeLine: (line) => console.log(line),
-  loadCommands: () => import("./commands-56WH3ZVJ.js"),
-  loadApi: () => import("./api-NVZQJBVP.js"),
-  loadMcp: () => import("./stdio-MJ4LTXME.js")
+  loadCommands: () => import("./commands-EDRH2XMY.js"),
+  loadApi: () => import("./api-FMMG3W6J.js"),
+  loadMcp: () => import("./stdio-VBPVT2KS.js")
 }).catch(async (error) => {
-  const { ApiError } = await import("./api-NVZQJBVP.js");
+  const { ApiError } = await import("./api-FMMG3W6J.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.");

package/dist/{stdio-MJ4LTXME.js → stdio-VBPVT2KS.js}

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   openBrowser
-} from "./chunk-NG3Q3BYW.js";
+} from "./chunk-SN6SLPIC.js";
 import {
   ApiError,
   admitMcpCall,
@@ -11,13 +11,13 @@ import {
   saveConfig,
   validateApiResponse,
   withAdmissionReceipt
-} from "./chunk-KI5E2464.js";
+} from "./chunk-VTHAZQEV.js";
 import {
   BUILD_COMMIT,
   PACKAGE_VERSION,
   PRODUCTION_APP_URL,
   PRODUCTION_SUPABASE_URL
-} from "./chunk-H5TR3QJN.js";
+} from "./chunk-HGA2O3JM.js";
 import {
   __commonJS,
   __export,
@@ -31037,11 +31037,24 @@ import { join } from "node:path";
 import { chromium } from "playwright-core";
 var PROTOCOL = 3;
 var MAX_AGE_MS = 12 * 60 * 60 * 1e3;
-var STATE_DIR = () => join(homedir(), ".impractical");
+function framesHome() {
+  const override = process.env.IMPRACTICAL_FRAMES_HOME?.trim();
+  return override ? override : join(homedir(), ".impractical");
+}
+function usingDefaultFramesHome() {
+  return framesHome() === join(homedir(), ".impractical");
+}
+var STATE_DIR = () => framesHome();
 var ADVERT = () => join(STATE_DIR(), "frames-daemon.json");
 var LOCK = () => join(STATE_DIR(), "frames-daemon.lock");
 var CLIENTS = () => join(STATE_DIR(), "frames-clients");
 var BINARIES = () => join(STATE_DIR(), "frames-binaries.json");
+function profileRoot() {
+  if (usingDefaultFramesHome()) return tmpdir();
+  const root = join(framesHome(), "tmp");
+  mkdirSync(root, { recursive: true });
+  return root;
+}
 function alive(pid) {
   if (!Number.isInteger(pid) || pid <= 0) return false;
   try {
@@ -31198,7 +31211,7 @@ async function waitForPort(userDataDir, timeoutMs = 3e4) {
 }
 async function spawnDaemon(launcher, executable) {
   mkdirSync(STATE_DIR(), { recursive: true });
-  const userDataDir = mkdtempSync(join(tmpdir(), "impractical-frames-"));
+  const userDataDir = mkdtempSync(join(profileRoot(), "impractical-frames-"));
   const child = spawn(executable, browserArgs(executable, 0, userDataDir), {
     detached: true,
     stdio: "ignore"
@@ -32567,6 +32580,125 @@ function imperceptibleTweens(tweens, intervals, options = {}) {
     return mean2 < threshold;
   });
 }
+var DRIFT_MIN_SECONDS = 1.2;
+var DRIFT_EASES = /* @__PURE__ */ new Set([
+  "none",
+  "linear",
+  "power0",
+  "power0.none",
+  "power0.in",
+  "power0.out",
+  "power0.inOut"
+]);
+var DRIFT_MAX_SCALE_DELTA = 0.15;
+var DRIFT_MAX_TRANSLATE = { px: 60, vw: 3.5, vh: 6, "%": 6 };
+var DRIFT_SCALE_PROPS = /* @__PURE__ */ new Set(["scale", "scaleX", "scaleY"]);
+var DRIFT_TRANSLATE_PROPS = /* @__PURE__ */ new Set(["x", "y", "xPercent", "yPercent"]);
+var DRIFT_ROTATE_PROPS = /* @__PURE__ */ new Set(["rotation", "rotationZ"]);
+var DRIFT_PASSIVE_PROPS = /* @__PURE__ */ new Set(["transformOrigin", "force3D", "willChange"]);
+var parseMagnitude = (value) => {
+  if (typeof value === "number") return { amount: value, unit: "px" };
+  if (typeof value !== "string") return null;
+  const match = /^\s*([+-]=)?\s*(-?\d*\.?\d+)\s*([a-z%]*)\s*$/i.exec(value);
+  if (!match) return null;
+  return { amount: Number(match[2]), unit: (match[3] || "px").toLowerCase() };
+};
+function isDriftTween(tween) {
+  if (tween.end - tween.start < DRIFT_MIN_SECONDS) return false;
+  if (!DRIFT_EASES.has(tween.ease)) return false;
+  if (tween.yoyo) return false;
+  const active2 = tween.props.filter((prop) => !DRIFT_PASSIVE_PROPS.has(prop));
+  if (!active2.length) return false;
+  for (const prop of active2) {
+    const value = tween.values?.[prop];
+    if (DRIFT_SCALE_PROPS.has(prop)) {
+      const parsed = parseMagnitude(value);
+      if (parsed && Math.abs(parsed.amount - 1) > DRIFT_MAX_SCALE_DELTA) return false;
+    } else if (DRIFT_TRANSLATE_PROPS.has(prop)) {
+      const parsed = parseMagnitude(value);
+      const ceiling = parsed ? DRIFT_MAX_TRANSLATE[parsed.unit] ?? DRIFT_MAX_TRANSLATE.px : null;
+      if (parsed && ceiling !== null && Math.abs(parsed.amount) > ceiling) return false;
+    } else if (DRIFT_ROTATE_PROPS.has(prop)) {
+      const parsed = parseMagnitude(value);
+      if (parsed && Math.abs(parsed.amount) > 15) return false;
+    } else {
+      return false;
+    }
+  }
+  return true;
+}
+var coincides = (a, b, tolerance = 0.06) => Math.abs(a.start - b.start) <= tolerance && Math.abs(a.end - b.end) <= tolerance;
+function driftFindings(input) {
+  const cameraDrifts = (input.engine ?? []).filter(
+    (tween) => tween.kind === "camera" && tween.end - tween.start >= DRIFT_MIN_SECONDS && DRIFT_EASES.has(tween.ease)
+  );
+  const stageLike = (tween) => tween.targets.some((target) => /^[a-z][a-z0-9]*$/i.test(target)) || ["scale", "x", "y"].every((prop) => tween.props.includes(prop));
+  const out = [];
+  for (const tween of input.tweens ?? []) {
+    if (!isDriftTween(tween)) continue;
+    const camera = stageLike(tween) && cameraDrifts.some((span) => coincides(tween, span));
+    out.push({ tween, target: camera ? "camera" : tween.text ? "text" : "media" });
+  }
+  for (const span of cameraDrifts) {
+    if (out.some((finding) => finding.target === "camera" && coincides(finding.tween, span))) continue;
+    out.push({
+      tween: { start: span.start, end: span.end, targets: ["camera"], props: ["scale", "x", "y"], ease: span.ease },
+      target: "camera"
+    });
+  }
+  return out.sort((a, b) => a.tween.start - b.tween.start);
+}
+var describeDrift = (finding) => {
+  const { tween } = finding;
+  const props = tween.props.filter((prop) => !DRIFT_PASSIVE_PROPS.has(prop));
+  const kind = props.some((prop) => DRIFT_SCALE_PROPS.has(prop)) ? "scale" : props.some((prop) => DRIFT_ROTATE_PROPS.has(prop)) ? "rotation" : "translate";
+  const where = finding.target === "camera" ? "the camera" : finding.target === "text" ? `text (${tween.targets[0] ?? "target"})` : tween.targets[0] ?? "target";
+  return `DRIFT ${formatTime(tween.start)}-${formatTime(tween.end)}s on ${where}: a ${(tween.end - tween.start).toFixed(1)}s linear (ease=${tween.ease}) sub-pixel ${kind}`;
+};
+function driftFailures(findings) {
+  return findings.filter((finding) => finding.target !== "media").map(
+    (finding) => `${describeDrift(finding)} re-rasterizes every glyph each frame and renders as micro-flicker in the export. Delete it and hold clean \u2014 the dead-air line it prevents is not a defect.`
+  );
+}
+var DRIFT_GATE_ENV = "IMPRACTICAL_DRIFT_GATE";
+function driftGateEnabled(env = process.env) {
+  return !/^(0|false|off|no)$/i.test(env[DRIFT_GATE_ENV]?.trim() ?? "");
+}
+var SHIMMER_MAX_CHANGE = 0.12;
+var SHIMMER_MIN_SPREAD = 0.4;
+var SHIMMER_MAX_TOP_SHARE = 0.5;
+var SHIMMER_TOP_CELLS = 5;
+var SHIMMER_MIN_SECONDS = 0.75;
+function isShimmerInterval(interval, cells) {
+  if (!cells?.length) return false;
+  if (interval.changed < DEAD_THRESHOLD || interval.changed >= SHIMMER_MAX_CHANGE) return false;
+  const touched = cells.filter((cell) => cell > 0).length / cells.length;
+  if (touched < SHIMMER_MIN_SPREAD) return false;
+  const total = cells.reduce((sum, cell) => sum + cell, 0);
+  if (total <= 0) return false;
+  const top = [...cells].sort((a, b) => b - a).slice(0, SHIMMER_TOP_CELLS).reduce((sum, cell) => sum + cell, 0);
+  return top / total <= SHIMMER_MAX_TOP_SHARE;
+}
+function shimmerSpans(intervals, cellDiffs) {
+  const spans2 = [];
+  let open = null;
+  intervals.forEach((interval, i) => {
+    if (isShimmerInterval(interval, cellDiffs[i])) {
+      if (open) {
+        open.end = interval.end;
+        open.peak = Math.max(open.peak, interval.changed);
+      } else {
+        open = { start: interval.start, end: interval.end, peak: interval.changed };
+      }
+    } else if (open) {
+      spans2.push(open);
+      open = null;
+    }
+  });
+  if (open) spans2.push(open);
+  return spans2.filter((span) => span.end - span.start >= SHIMMER_MIN_SECONDS);
+}
+var READING_HOLD_MAX_SECONDS = 1.5;
 var formatTime = (value) => value.toFixed(2);
 var bar = (changed) => {
   const filled = Math.round(Math.min(changed / 0.25, 1) * 10);
@@ -32621,6 +32753,10 @@ function splitFocusMoments(times, cellDiffs, budget = FOCAL_BUDGET) {
 }
 function motionReport(input) {
   const { intervals, tweens, plan } = input;
+  const shimmer = input.shimmer ?? [];
+  const inShimmer = (interval) => shimmer.some((span) => interval.start >= span.start - 1e-9 && interval.end <= span.end + 1e-9);
+  const drifts = input.drifts ?? [];
+  const driftByTween = new Map(drifts.map((finding) => [finding.tween, finding]));
   const lines = [];
   lines.push(
     `MOTION ANALYSIS ${formatTime(input.from)}\u2013${formatTime(input.to)}s of ${formatTime(input.duration)}s \u2014 ${plan.times.length} samples, ${plan.stepSeconds.toFixed(3)}s apart` + (plan.coarsened ? ` (coarsened to fit ${plan.times.length} samples \u2014 analyze a narrower window for every-${input.everyNthFrame}-frames density)` : ` (every ${input.everyNthFrame} frames)`) + "."
@@ -32638,15 +32774,45 @@ function motionReport(input) {
   const dead = deadAirSpans(intervals);
   lines.push("");
   if (dead.length) {
-    lines.push("DEAD AIR \u2014 nothing perceptible moves. Decide what should own this time:");
+    lines.push(
+      `DEAD AIR \u2014 nothing perceptible moves. A reading hold (up to ${READING_HOLD_MAX_SECONDS}s) is a legitimate choice and needs no fix; longer is time no one is directing. Never "fix" a hold with a slow drift \u2014 see DRIFT below:`
+    );
     for (const span of dead) {
+      const length = span.end - span.start;
       lines.push(
-        `  ${formatTime(span.start)}\u2013${formatTime(span.end)}s (${(span.end - span.start).toFixed(2)}s)`
+        `  ${formatTime(span.start)}\u2013${formatTime(span.end)}s (${length.toFixed(2)}s)` + (length <= READING_HOLD_MAX_SECONDS ? " \u2014 reading hold, fine" : "")
       );
     }
   } else {
     lines.push("DEAD AIR: none in this window.");
   }
+  if (shimmer.length) {
+    lines.push("");
+    lines.push(
+      "SHIMMER \u2014 low, diffuse, whole-frame change with no focal region. Nothing is moving; the frame is re-rasterizing (a sub-pixel scale or translate on the camera or on text). This renders as micro-flicker in the export, not as hold-life, and is counted as STATIC:"
+    );
+    for (const span of shimmer.slice(0, 8)) {
+      lines.push(
+        `  ${formatTime(span.start)}\u2013${formatTime(span.end)}s (${(span.end - span.start).toFixed(2)}s, peak ${(span.peak * 100).toFixed(1)}%)`
+      );
+    }
+  }
+  const flicker = drifts.filter((finding) => finding.target !== "media");
+  const mediaDrifts = drifts.filter((finding) => finding.target === "media");
+  if (flicker.length) {
+    lines.push("");
+    lines.push(
+      `DRIFT = FLICKER \u2014 ${flicker.length} slow linear transform(s) on the camera or on text. A sub-pixel scale/translate across a hold re-rasterizes every glyph each frame: invisible as motion, visible as shimmer in the MP4. These block export. Delete them and hold clean; if a hold needs life, move something without text (a cover image, a gradient plate) with a move that starts and settles:`
+    );
+    for (const finding of flicker) lines.push(`  ${describeDrift(finding)}`);
+  }
+  if (mediaDrifts.length) {
+    lines.push("");
+    lines.push(
+      `DRIFT (allowed) \u2014 ${mediaDrifts.length} slow linear transform(s) on non-text elements. Fine on a photo or a plate; confirm the target really carries no glyphs:`
+    );
+    for (const finding of mediaDrifts) lines.push(`  ${describeDrift(finding)}`);
+  }
   if (input.breathless) {
     lines.push("");
     if (input.breathless.length) {
@@ -32706,39 +32872,56 @@ function motionReport(input) {
     const flagged = new Set(imperceptibleTweens(tweens, intervals));
     lines.push("TIMELINE \u2014 the tweens actually scheduled in this window (absolute seconds):");
     for (const tween of [...tweens].sort((a, b) => a.start - b.start)) {
-      const flag = flagged.has(tween) ? "  \u26A0 runs but changes almost no pixels \u2014 likely an imperceptible magnitude; make it visibly larger or give the time to something else" : "";
+      const drift = driftByTween.get(tween);
+      const flag = drift ? drift.target === "media" ? "  \xB7 slow linear drift on a non-text element (allowed)" : "  \u26A0 DRIFT \u2014 linear sub-pixel transform on the camera/text; renders as flicker, not motion. Delete it and hold clean." : flagged.has(tween) ? "  \u26A0 runs but changes almost no pixels \u2014 likely an imperceptible magnitude; make it visibly larger or delete it and hold clean (never a slow drift)" : "";
       lines.push(`  ${describeTween(tween)}${flag}`);
     }
     const covered = intervals.filter(
       (interval) => tweens.some((tween) => tween.end > interval.start && tween.start < interval.end)
     ).length;
-    const perceptible = intervals.filter((interval) => interval.changed >= DEAD_THRESHOLD).length;
+    const perceptible = intervals.filter(
+      (interval) => interval.changed >= DEAD_THRESHOLD && !inShimmer(interval)
+    ).length;
+    const shimmering = intervals.filter(
+      (interval) => interval.changed >= DEAD_THRESHOLD && inShimmer(interval)
+    ).length;
     lines.push("");
     lines.push(
-      `Coverage: tweens are active in ${Math.round(covered / Math.max(1, intervals.length) * 100)}% of intervals; perceptible motion occupies ${Math.round(perceptible / Math.max(1, intervals.length) * 100)}%.`
+      `Coverage: tweens are active in ${Math.round(covered / Math.max(1, intervals.length) * 100)}% of intervals; perceptible motion occupies ${Math.round(perceptible / Math.max(1, intervals.length) * 100)}%` + (shimmering ? ` (a further ${Math.round(shimmering / Math.max(1, intervals.length) * 100)}% is shimmer, counted as static).` : ".")
     );
   }
   return lines.join("\n");
 }
 var REFERENCE_STATIC_BAND = { low: 0.35, median: 0.45, high: 0.55 };
-function envelopeLine(intervals) {
+function envelopeLine(intervals, shimmer = []) {
   if (!intervals.length) return "";
-  const still = intervals.filter((interval) => interval.changed < DEAD_THRESHOLD).length / intervals.length;
+  const inShimmer = (interval) => shimmer.some((span) => interval.start >= span.start - 1e-9 && interval.end <= span.end + 1e-9);
+  const still = intervals.filter((interval) => interval.changed < DEAD_THRESHOLD || inShimmer(interval)).length / intervals.length;
   const delta = still - REFERENCE_STATIC_BAND.median;
   return `REFERENCE ENVELOPE: reference launch films run ~${Math.round(REFERENCE_STATIC_BAND.low * 100)}-${Math.round(REFERENCE_STATIC_BAND.high * 100)}% static (median ~${Math.round(REFERENCE_STATIC_BAND.median * 100)}%); this window: ${(still * 100).toFixed(1)}%` + (delta > 0.1 ? ` \u2014 ${Math.round(delta * 100)} points stiller than the reference norm.` : " \u2014 inside the norm.");
 }
 function repairMenu(input) {
   const out = [];
+  const driftTweens = new Set((input.drifts ?? []).map((finding) => finding.tween));
+  for (const finding of input.drifts ?? []) {
+    if (finding.target === "media") continue;
+    out.push(
+      `REPAIR ${describeDrift(finding)}: delete it. It is not hold-life \u2014 it is glyph flicker. A held frame is the correct state for a hold; if the beat genuinely needs motion, give it a discrete event (a click, a reveal, a state change) or move a non-text element with a move that starts and settles.`
+    );
+  }
   for (const span of input.deadSpans) {
+    const length = span.end - span.start;
+    if (length <= READING_HOLD_MAX_SECONDS) continue;
     const sample = input.textSamples?.find((candidate) => candidate.time >= span.start && candidate.time <= span.end);
     const anchor = sample?.blocks.find((block) => block.inViewport && block.selector)?.selector;
     out.push(
-      `REPAIR dead air ${span.start.toFixed(2)}-${span.end.toFixed(2)}s: either trim the hold (pull the next cut to ~${(span.start + 0.9).toFixed(1)}s), or give it hold-life` + (anchor ? ` \u2014 e.g. a slow camera push toward ${anchor} (ease-in-out-cubic, the full span)` : "") + ". A reading hold may rest ~1s; longer needs visible life."
+      `REPAIR dead air ${span.start.toFixed(2)}-${span.end.toFixed(2)}s (${length.toFixed(1)}s): either trim the hold (pull the next cut to ~${(span.start + READING_HOLD_MAX_SECONDS).toFixed(1)}s), or add a discrete event` + (anchor ? ` \u2014 a click, reveal, or state change on/near ${anchor}` : " \u2014 a click, a reveal, a state change") + `. Do NOT add a slow scale/translate on the camera or on text to fill it: that measures as motion and renders as flicker. A reading hold under ${READING_HOLD_MAX_SECONDS}s is fine as it is.`
     );
   }
   for (const tween of input.imperceptible) {
+    if (driftTweens.has(tween)) continue;
     out.push(
-      `REPAIR imperceptible tween ${tween.start.toFixed(2)}-${tween.end.toFixed(2)}s on ${tween.targets[0] ?? "target"} (${tween.props.slice(0, 3).join(",")}): the change is below what a viewer can see \u2014 multiply the distance roughly 5-10x, or delete it and hold clean.`
+      `REPAIR imperceptible tween ${tween.start.toFixed(2)}-${tween.end.toFixed(2)}s on ${tween.targets[0] ?? "target"} (${tween.props.slice(0, 3).join(",")}): the change is below what a viewer can see \u2014 multiply the distance roughly 5-10x, or delete it and hold clean (never stretch it into a slow drift).`
     );
   }
   return out;
@@ -33197,7 +33380,8 @@ async function extractTimeline(page) {
           ease: typeof easeRaw === "string" ? easeRaw : easeRaw ? "custom" : "default",
           values,
           scene,
-          yoyo: Boolean(vars.yoyo)
+          yoyo: Boolean(vars.yoyo),
+          text: Boolean(firstElement && (firstElement.textContent ?? "").trim().length > 0)
         });
       }
     };
@@ -33491,6 +33675,8 @@ var getMotionTool = {
         frames.map((frame) => frame.time),
         diffs
       );
+      const drifts = driftFindings({ tweens, engine: engineTweens });
+      const shimmer = shimmerSpans(intervals, cellDiffs);
       const censusSection = censusOn && textSamples.length ? textCensusReport(textSamples) : "";
       let contractSection = "";
       if (textContractEnabled() && textSamples.length >= 2) {
@@ -33516,7 +33702,7 @@ var getMotionTool = {
       let v2Section = "";
       if (inspectV2Enabled()) {
         const v2Lines = [];
-        const envelope = envelopeLine(intervals);
+        const envelope = envelopeLine(intervals, shimmer);
         if (envelope) v2Lines.push(envelope);
         const beats = ctx.qualityLoopState?.beatsByDraft.get(String(args.draftId)) ?? [];
         v2Lines.push(...beatVerdicts(beats, intervals));
@@ -33524,6 +33710,7 @@ var getMotionTool = {
           ...repairMenu({
             deadSpans: deadAirSpans(intervals),
             imperceptible: tweens ? imperceptibleTweens(tweens, intervals) : [],
+            drifts,
             textSamples
           })
         );
@@ -33543,6 +33730,8 @@ var getMotionTool = {
       let splitFocus = splitFocusMoments(
         frames.map((frame) => frame.time),
         cellDiffs
+      ).filter(
+        (moment) => !shimmer.some((span) => moment.start >= span.start - 1e-9 && moment.end <= span.end + 1e-9)
       );
       let breathless = breathlessSpans(intervals);
       let cadence = tweens ? cadenceMoments(tweens) : void 0;
@@ -33575,7 +33764,7 @@ var getMotionTool = {
         } catch {
         }
       }
-      const report = motionReport({ from, to, plan, everyNthFrame, intervals, tweens, duration: duration3, splitFocus, breathless, cadence });
+      const report = motionReport({ from, to, plan, everyNthFrame, intervals, tweens, duration: duration3, splitFocus, breathless, cadence, drifts, shimmer });
       const lines = [
         report,
         ...passPlan.includeSheets ? [] : [
@@ -33596,7 +33785,7 @@ var getMotionTool = {
         ...catalogSection ? ["", catalogSection] : [],
         ...session.warnings.map((warning) => `WARNING: ${warning}`),
         "",
-        "These are measurements, not style rules. Dead air and imperceptible tweens are time no one is directing \u2014 decide narratively what should own that time, change the direction, and measure again."
+        "These are measurements, not style rules. Dead air longer than a reading hold and imperceptible tweens are time no one is directing \u2014 decide narratively what should own that time, change the direction, and measure again. A reading hold is allowed to be still: never fill it with a slow drift on the camera or on text, which measures as motion and renders as flicker."
       ];
       if (ctx.qualityLoop) {
         if (!finalReview) {
@@ -33637,7 +33826,8 @@ var getMotionTool = {
               stepSeconds: plan.stepSeconds,
               samples: plan.times.length,
               craft: craftCapture,
-              framingFailures: framing
+              framingFailures: framing,
+              driftFailures: driftGateEnabled() ? driftFailures(drifts) : []
             });
             lines.push(
               `FINAL MOTION REVIEW RECORDED for revision ${session.revision} \u2014 ${plan.times.length} samples, ${plan.stepSeconds.toFixed(3)}s apart` + (plan.coarsened ? " (coarsened below one-in-five by film length)" : "") + ". Any later edit invalidates this evidence."
@@ -33659,7 +33849,7 @@ function motionLabServerInstructions() {
   return `
 
 MOTION LAB IS ENABLED \u2014 an opt-in local experiment:
-Static frames measure composition; they are blind to velocity, overlap, and dead air. After every successful preview build, call get_motion across the full duration BEFORE judging the cut, and again on any window you edit. Treat its output as measurements, not style rules: a dead-air span or a flagged imperceptible tween is time no one is directing \u2014 decide what should own that time, fix the direction, and measure again. A cut is not done while the report shows dead air you did not choose deliberately. get_frames remains the tool for composition close-ups.
+Static frames measure composition; they are blind to velocity, overlap, and dead air. After every successful preview build, call get_motion across the full duration BEFORE judging the cut, and again on any window you edit. Treat its output as measurements, not style rules: a dead-air span longer than a reading hold (~1.5s) or a flagged imperceptible tween is time no one is directing \u2014 decide what should own that time, fix the direction, and measure again. A reading hold is allowed to be completely still. NEVER quiet a dead-air line with a slow linear scale or translate on the camera or on any element carrying text: it measures as motion and renders as micro-flicker in the export, and the report's DRIFT finding blocks export. get_frames remains the tool for composition close-ups.
 When the quality loop is 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.`;
 }
 
@@ -34009,7 +34199,7 @@ Creative contract: ${contract.singleIdea} Visual proof: ${contract.visualProof}`
 function motionCoverageFailure(input) {
   if (!input.motionLab) return null;
   if (!input.capture) {
-    return 'The motion lab requires full-duration motion coverage: call get_motion({ draftId, reviewMode: "final" }) and resolve the dead air and imperceptible tweens it reports before exporting.';
+    return 'The motion lab requires full-duration motion coverage: call get_motion({ draftId, reviewMode: "final" }) and read the dead-air, drift, and imperceptible-tween findings it reports before exporting. A reading hold may stay still; a drift must go.';
   }
   if (input.capture.revision !== input.frameReviewRevision) {
     return `The motion review covered revision ${input.capture.revision}, but the final frame review covered revision ${input.frameReviewRevision}. Review the same revision with both.`;
@@ -34020,6 +34210,10 @@ function framingMotionFailure(capture) {
   if (!capture?.framingFailures?.length) return null;
   return "The final motion review found broken framing \u2014 fix these shots and review again:\n" + capture.framingFailures.map((finding) => `- ${finding}`).join("\n");
 }
+function driftMotionFailure(capture) {
+  if (!capture?.driftFailures?.length) return null;
+  return "The final motion review found drift that renders as flicker \u2014 delete these tweens and hold clean, then review again (a still reading hold is the correct state, not a defect):\n" + capture.driftFailures.map((finding) => `- ${finding}`).join("\n");
+}
 function craftMotionFailure(input) {
   if (!input.craftLab) return null;
   const craft = input.capture?.craft;
@@ -34641,15 +34835,26 @@ var upgradeTool = {
 var listProjects = {
   name: "list_projects",
   title: "List video projects",
-  description: "List video projects in the connected workspace, newest first. Large workspaces: pass limit/offset to page instead of relying on a truncated dump, and nameFilter to search.",
+  description: "List video projects in the connected workspace, newest first. Large workspaces: pass limit/offset to page instead of relying on a truncated dump, and nameFilter to search. The tool pages through the server list internally, so totals describe the whole workspace (up to 2,000 projects).",
   inputSchema: {
     limit: external_exports.number().int().min(1).max(200).optional().describe("Return at most this many projects (default: all)."),
     offset: external_exports.number().int().min(0).optional().describe("Skip this many projects, for paging."),
     nameFilter: external_exports.string().optional().describe("Case-insensitive substring match on the project name/slug.")
   },
   handler: async (args, ctx) => {
-    const result = await ctx.invoke("list-projects", {});
-    let projects = result.projects ?? [];
+    const fetched = [];
+    let serverOffset = 0;
+    for (let pageCount = 0; serverOffset !== null && pageCount < 20; pageCount++) {
+      const result = await ctx.invoke("list-projects", {
+        offset: serverOffset,
+        limit: 100
+      });
+      const rows = result.projects ?? [];
+      fetched.push(...rows);
+      serverOffset = rows.length > 0 && typeof result.nextOffset === "number" ? result.nextOffset : null;
+    }
+    const truncated = serverOffset !== null;
+    let projects = fetched;
     const total = projects.length;
     const filter = typeof args.nameFilter === "string" ? args.nameFilter.trim().toLowerCase() : "";
     if (filter) {
@@ -34667,6 +34872,7 @@ var listProjects = {
       offset,
       returned: projects.length,
       hasMore: offset + projects.length < matched,
+      ...truncated ? { note: "Workspace exceeds 2,000 projects; totals reflect the first 2,000." } : {},
       projects
     });
   }
@@ -34685,7 +34891,9 @@ var createVideo = {
   inputSchema: {
     valueProp: external_exports.string().min(1).describe("One or two sentences on what ships and why it matters."),
     name: external_exports.string().optional().describe("Human-readable project name. Defaults to the slug."),
-    slug: external_exports.string().optional().describe("URL-safe project slug. Generated when omitted."),
+    slug: external_exports.string().optional().describe(
+      "URL-safe project slug. Generated when omitted (recommended). An explicit slug that collides with a different existing project is rejected with a 409 \u2014 it never attaches to that project; pass projectId instead to edit an existing project."
+    ),
     vibe: external_exports.string().optional().describe("Tone, e.g. 'confident'. Defaults to 'confident'."),
     brandSlug: external_exports.string().optional().describe("Brand kit slug from brand_list. Its colors and fonts become brand.json."),
     appCode: external_exports.string().optional().describe("The product's front-end code, used as the starting point for App.tsx."),
@@ -34975,7 +35183,7 @@ var exportVideo = {
       }) ?? craftMotionFailure({
         craftLab: ctx.craftLab === true,
         capture: ctx.qualityLoopState?.finalMotionReviewByDraft.get(String(args.draftId))
-      }) ?? framingMotionFailure(ctx.qualityLoopState?.finalMotionReviewByDraft.get(String(args.draftId)));
+      }) ?? framingMotionFailure(ctx.qualityLoopState?.finalMotionReviewByDraft.get(String(args.draftId))) ?? driftMotionFailure(ctx.qualityLoopState?.finalMotionReviewByDraft.get(String(args.draftId)));
       if (failure) return fail(`Quality gate blocked export: ${failure}`);
     }
     const started = await ctx.invoke("start-export", { draftId: args.draftId });
@@ -35921,7 +36129,14 @@ THE MOTION FLOOR \u2014 these hold even if you read nothing else:
 ` + // Item 8 is the content doctrine, which is still under experiment: it ships
     // only when IMPRACTICAL_CONTENT_DOCTRINE is set, so the same switch governs
     // the doctrine here and in the phased flow's phase 2.
-    (contentDoctrineEnabled() ? "8. CONTENT: pretend the viewer has never heard of this product. Figure out the one thing they should walk away knowing, and say it in as few words as possible. If a smart 16-year-old could not repeat a line back in their own words, the line means nothing \u2014 cut it. No buzzwords, no vague taglines. Say a thing, then show it happening \u2014 in that order, one after the other, never both at once. Give the viewer exactly one thing to read at a time: no little label above a headline, no subtitle under it." : "") + "\n9. ICONS: always use real icons from the icon library, never typographic or ASCII stand-ins. lucide-react is available in every draft \u2014 `import { ArrowRight, Check } from 'lucide-react'`. An arrow is <ArrowRight/>, not \u2192 or ->; a tick is <Check/>, not \u2713; a chevron is <ChevronRight/>, not >; a play control is <Play/>, not \u25B6. Glyphs inherit the text font, so they land on the baseline at the wrong weight and optical size and read as a placeholder, and they cannot take a stroke width or animate as their own element. The same goes for emoji standing in for a UI affordance.\n10. FOCAL BUDGET: one focal point at a time. At most ONE region of the frame changes at once (a full-frame camera move is one change; a subject plus its direct reaction is the limit). A claim and the product may NEVER share the same space: while a statement is up, the product is fully cleared or fully hidden \u2014 dimming it under the words is not separation. Never stack anything on top of a dashboard while the dashboard is the subject. An element that finished its job exits before the next enters; the motion report now measures split focus and stacked text, and the film is not done while either fires.\n11. COMPONENT REHEARSAL: build and judge the hero components BEFORE choreographing the film. For each component that must look real (the dashboard, the inbox, the editor): build it, render it with get_frames in each state the beats will put it through, compare it against the reference you studied, and iterate until it holds up as a still. Only then write the timeline. A component that cannot survive a paused frame will not survive motion, and choreographing a broken component wastes every revision that follows.\n12. SCALE TRUTH: a product element never exceeds its native proportion. When a toast, button, or label must be readable, push the CAMERA to it so the whole UI scales together \u2014 never blow one element up inside otherwise-small chrome; an oversized toast over tiny UI text reads as a fake. The same for pointers: a cursor or caret is sized relative to the UI it operates on (match the product's zoom factor; at 67% zoom the cursor is 67% size), a caret pins to its text baseline, and a cursor tip lands ON its target, never near it. The census measures inflated elements; the film is not done while it fires.\n13. PACING: slow down. Stillness is a tool, not a defect \u2014 the dead-air check finds UNOWNED time, not quiet time. After every claim and every proof, HOLD: the viewer needs settled time to focus before the next change. The motion report flags nonstop motion (TOO FAST) exactly like it flags dead air, and the film is not done while either fires. THE CADENCE: one action at a time, about one every 1\u20131.5 seconds \u2014 a click, a panel opening, a card landing each count as one action. Let each settle before the next. The kit and camera defaults are already tuned to this; never override their durations to be FASTER. The report measures action frequency and flags stretches that pack more.\n14. CUTS: a scene change lands ONLY on a declared beat boundary \u2014 never mid-beat, never mid-read. A transition is either a real camera move (the house dolly) or a hard cut covered by the incoming element; a 0.1\u20130.3s squash-collapse is neither. Vary how scenes leave \u2014 the same exit mechanism back to back reads as a loop, and a scene alive under ~2 seconds never registered. The motion score measures all of this.\n15. THE GO-THROUGH: to dive into a button/card/color until it takes over the frame and becomes the next scene, ALWAYS use transition.through(target, { swap, land }) \u2014 never hand-roll it with a big camera.move scale plus a timed tl.set swap. Hand-rolled dives aim at build-time positions and miss; through() measures the target at the dive's start time, computes the exact cover scale, and guarantees the cut lands under full cover." + (ctx.qualityLoop ? qualityLoopServerInstructions() : "") + (ctx.motionLab ? motionLabServerInstructions() : "") + (ctx.craftLab ? "\n\nCRAFT LAB IS ENABLED \u2014 get_motion additionally prints a CRAFT ENVELOPE (depth, vocabulary, rhythm, continuity, geometry) band-scored against the house references. Camera motion is exempt from the restraint verdicts. Export enforces objective craft floors: at least one camera move, zero unresolved beat mismatches, zero geometry deformations, no dead-air span over 2.5s. Self-scores are recorded but do not gate; identical scorecards across drafts are rejected." : "") + (ctx.phasedFlow ? phasedServerInstructions() : "")
+    (contentDoctrineEnabled() ? "8. CONTENT: pretend the viewer has never heard of this product. Figure out the one thing they should walk away knowing, and say it in as few words as possible. If a smart 16-year-old could not repeat a line back in their own words, the line means nothing \u2014 cut it. No buzzwords, no vague taglines. Say a thing, then show it happening \u2014 in that order, one after the other, never both at once. Give the viewer exactly one thing to read at a time: no little label above a headline, no subtitle under it." : "") + `
+9. ICONS: always use real icons from the icon library, never typographic or ASCII stand-ins. lucide-react is available in every draft \u2014 \`import { ArrowRight, Check } from 'lucide-react'\`. An arrow is <ArrowRight/>, not \u2192 or ->; a tick is <Check/>, not \u2713; a chevron is <ChevronRight/>, not >; a play control is <Play/>, not \u25B6. Glyphs inherit the text font, so they land on the baseline at the wrong weight and optical size and read as a placeholder, and they cannot take a stroke width or animate as their own element. The same goes for emoji standing in for a UI affordance.
+10. FOCAL BUDGET: one focal point at a time. At most ONE region of the frame changes at once (a full-frame camera move is one change; a subject plus its direct reaction is the limit). A claim and the product may NEVER share the same space: while a statement is up, the product is fully cleared or fully hidden \u2014 dimming it under the words is not separation. Never stack anything on top of a dashboard while the dashboard is the subject. An element that finished its job exits before the next enters; the motion report now measures split focus and stacked text, and the film is not done while either fires.
+11. COMPONENT REHEARSAL: build and judge the hero components BEFORE choreographing the film. For each component that must look real (the dashboard, the inbox, the editor): build it, render it with get_frames in each state the beats will put it through, compare it against the reference you studied, and iterate until it holds up as a still. Only then write the timeline. A component that cannot survive a paused frame will not survive motion, and choreographing a broken component wastes every revision that follows.
+12. SCALE TRUTH: a product element never exceeds its native proportion. When a toast, button, or label must be readable, push the CAMERA to it so the whole UI scales together \u2014 never blow one element up inside otherwise-small chrome; an oversized toast over tiny UI text reads as a fake. The same for pointers: a cursor or caret is sized relative to the UI it operates on (match the product's zoom factor; at 67% zoom the cursor is 67% size), a caret pins to its text baseline, and a cursor tip lands ON its target, never near it. The census measures inflated elements; the film is not done while it fires.
+13. PACING: slow down. Stillness is a tool, not a defect \u2014 the dead-air check finds UNOWNED time, not quiet time. After every claim and every proof, HOLD: the viewer needs settled time to focus before the next change. The motion report flags nonstop motion (TOO FAST) exactly like it flags dead air, and the film is not done while either fires. THE CADENCE: one action at a time, about one every 1\u20131.5 seconds \u2014 a click, a panel opening, a card landing each count as one action. Let each settle before the next. The kit and camera defaults are already tuned to this; never override their durations to be FASTER. The report measures action frequency and flags stretches that pack more.
+14. CUTS: a scene change lands ONLY on a declared beat boundary \u2014 never mid-beat, never mid-read. A transition is either a real camera move (the house dolly) or a hard cut covered by the incoming element; a 0.1\u20130.3s squash-collapse is neither. Vary how scenes leave \u2014 the same exit mechanism back to back reads as a loop, and a scene alive under ~2 seconds never registered. The motion score measures all of this.
+15. THE GO-THROUGH: to dive into a button/card/color until it takes over the frame and becomes the next scene, ALWAYS use transition.through(target, { swap, land }) \u2014 never hand-roll it with a big camera.move scale plus a timed tl.set swap. Hand-rolled dives aim at build-time positions and miss; through() measures the target at the dive's start time, computes the exact cover scale, and guarantees the cut lands under full cover. It has modes: { via: "glyph", char: "o" } dives through a character's enclosed counter on PLAIN text (never wrap glyphs in spans or tune margins by hand \u2014 the hole is measured from the glyph outline), { via: "word", word: "..." } dives through a word, and { via: "anchor" } is the match-cut: the subject persists across the cut while the world changes around it.` + (ctx.qualityLoop ? qualityLoopServerInstructions() : "") + (ctx.motionLab ? motionLabServerInstructions() : "") + (ctx.craftLab ? "\n\nCRAFT LAB IS ENABLED \u2014 get_motion additionally prints a CRAFT ENVELOPE (depth, vocabulary, rhythm, continuity, geometry) band-scored against the house references. Camera motion is exempt from the restraint verdicts. Export enforces objective craft floors: at least one camera move, zero unresolved beat mismatches, zero geometry deformations, no dead-air span over 2.5s. Self-scores are recorded but do not gate; identical scorecards across drafts are rejected." : "") + (ctx.phasedFlow ? phasedServerInstructions() : "")
   );
 }
 function createServer(ctx) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@impractical-ai/motion",
-  "version": "0.1.9",
+  "version": "0.1.11",
   "private": false,
   "description": "Create and refine Impractical Motion videos from coding agents and the terminal.",
   "homepage": "https://github.com/Openpod/impractical-motion#readme",