@impractical-ai/motion 0.1.16 → 0.1.19

package/assets/motion-standard.md

@@ -0,0 +1,46 @@
+# Arrival, hold and exit — house motion standard
+
+Adopted by explicit user direction on 2026-10-19. It supersedes the 2026-09-26 "arrival and residual drift" rule (the Rox `ambientOffset` drift layer), which is withdrawn. Applies to newly authored or revised video, Atelier and reusable motion components.
+
+## Default behavior
+
+**Each foreground element follows one continuous trajectory: it arrives with energy, decelerates strongly to near-zero speed for the reading hold, then accelerates into its exit or its next authored move.**
+
+- The entrance and exit eases carry the whole shape. There is no separate drift layer, no constant velocity floor and no perpetual creep.
+- **Finish the visible travel quickly.** During the hold, the remaining travel of the entrance's ease tail must be under about 0.5 output px in total. The subject then reads as calm and still, not creeping. A long-tailed out-ease is fine as long as its last stretch covers less than half a pixel.
+- **Exits accelerate out of the near-zero state** (an in or in-out ease). Nothing starts from a hard stop, and the tail of the arrival flows into the exit without a velocity discontinuity.
+- **Whole entities, not every element.** Arrival, hold and exit apply to the larger entity on screen: a card, a product window, a headline block, a logo lockup. Its children (labels, icons, rows, words, buttons) ride with it inside the same transform. Do not recurse and give each child its own arrival, deceleration and exit: that reads as fidgeting and splits attention. Children may still have their own discrete actions inside the hold (text typing in, a toggle flipping, a row highlighting, a number counting), but not their own arrive/hold/exit motion.
+- “Hold”, “settled”, “landed” and “reading time” mean visually still, stable and readable. If a long hold needs life, add a discrete event (a click, a reveal, a state change), not a drift.
+
+### Why no creep
+
+Exports render in headless Linux Chromium, which snaps slowly moving text and elements to whole pixels. A slow drift does not glide: the subject sits still for many frames, then jumps a full pixel in one frame. At about 1 px/s that is a visible 1 px tick every ~0.9 s. This was measured on 2026-10-19 on a Slack-agent export (text holding for ~50 frames, then jumping ~0.7 px, repeatedly) and reproduced in isolation in Linux Chromium (1.0 px single-frame snaps). Mac Chrome positions text at fractional pixels, so the Studio preview can look smooth while the export ticks.
+
+## Ownership and grouping
+
+- The component controls foreground objects only. The host composition owns its environment. Never animate, zoom, rotate, translate, retime, pulse or otherwise modify a background merely to give a foreground component motion. A host-authored background may have its own independent clock.
+- Keep the environment outside the subject transform hierarchy. Prefer transparent reusable foreground exports; Atelier preview backgrounds are separate host layers.
+- Move a semantic assembly as one group: object, attached text, controls, caret, connector endpoints and contact shadow. The group is what arrives, holds and exits; its parts don't each get their own entrance.
+- Make things breathe: one primary focus at a time, with generous negative space and comfortable margins around it. Keep supporting context subordinate, and sequence competing text and actions so each lands and is read before the next. If crowded, remove or sequence content before shrinking it. Camera pushes and reframing may serve that focus; one focus does not require a locked camera. Do not use a generic card as the default container for every concept.
+- Preserve 3D hierarchy, object identity and attached geometry.
+
+## Determinism
+
+Derive every pose from the existing seekable composition clock. No wall-clock timers, unseeded randomness, infinite animation loops or accumulated per-frame deltas. Rewinding must reproduce the same pose.
+
+## Exceptions
+
+Genuine continuous travel is authored motion, not a hold: a ticker, a river of cards, a footage scrub or a deliberate camera move. Keep it fast enough to read as motion (well above a few px/s), or make it a cut. Historical exports are reference evidence, not assets to rewrite merely because the standard changed.
+
+## Review and acceptance
+
+1. Inspect the moving foreground at entrance, deceleration, hold and exit, in an export (not only the Studio preview).
+2. In a reading hold, sample two frames 0.3–0.5 s apart: the held subject should not have moved by a visible amount (under ~0.5 px).
+3. Confirm the exit accelerates out of the hold rather than jumping from a dead stop.
+4. Verify attached labels, controls, shadows and projected anchors keep their relationships, with safe margins and readability throughout.
+5. Verify object animation does not change the host background's framing or state.
+6. Check repeated, reverse and retimed seeks.
+
+## Maintenance and distribution
+
+This document is canonical. The director playbook and motion-direction skill carry the operative rule; AGENTS.md, CLAUDE.md, Atelier guidance and repository entry points link here. The CLI bootstrap skill includes a portable summary because installed agents may not have the repository. Its source is `cli/assets/impractical/SKILL.md`; `scripts/build-claude-plugin.mjs` synchronizes the repository skill and plugin copy. `scripts/build-motion-library.mjs` embeds the playbook and authoring skills into the served motion library. MCP initialization instructions also state the default.

package/dist/{api-V7Q3PIWY.js → api-LZ6H5LHP.js}

@@ -17,8 +17,8 @@ import {
   waitForJobs,
   withAdmissionReceipt,
   withMeteredCall
-} from "./chunk-CJLGKZMD.js";
-import "./chunk-AP27EKRR.js";
+} from "./chunk-5VN5GZWK.js";
+import "./chunk-XPFY56XH.js";
 import "./chunk-77HVPD4G.js";
 export {
   AGENT_HEADER,

package/dist/{chunk-UEPY33MB.js → chunk-4SKYR3FS.js}

@@ -1,20 +1,25 @@
 #!/usr/bin/env node
 import {
-  ApiContractError,
+  DEVICE_START_BODY,
+  fetchWorkspaces,
+  grantScope,
+  workspaceLabel
+} from "./chunk-ZJSSF74D.js";
+import {
   ApiError,
   delay,
   invokeAt,
   loadConfig,
   recoverCorruptConfig,
   saveConfig
-} from "./chunk-CJLGKZMD.js";
+} from "./chunk-5VN5GZWK.js";
 import {
   PACKAGE_COMMAND,
   PACKAGE_NAME,
   PACKAGE_VERSION,
   PRODUCTION_APP_URL,
   PRODUCTION_SUPABASE_URL
-} from "./chunk-AP27EKRR.js";
+} from "./chunk-XPFY56XH.js";
 
 // src/onboarding.ts
 import {
@@ -32,48 +37,6 @@ import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { spawnSync } from "node:child_process";
 import { createRequire } from "node:module";
-
-// src/workspaces.ts
-var UNSUPPORTED = {
-  supported: false,
-  keyScope: null,
-  lastOpenWorkspaceId: null,
-  workspaces: []
-};
-async function fetchWorkspaces(request) {
-  let result;
-  try {
-    result = await request("workspace-bootstrap", { action: "list_workspaces" });
-  } catch (error) {
-    if (error instanceof ApiContractError) return UNSUPPORTED;
-    throw error;
-  }
-  if (!Array.isArray(result?.workspaces)) return UNSUPPORTED;
-  const keyScope = result.keyScope === "user" ? "user" : result.keyScope === "org" ? "org" : null;
-  const workspaces = result.workspaces.filter((row) => typeof row?.id === "string").map((row) => ({
-    id: String(row.id),
-    name: typeof row.name === "string" ? row.name : null,
-    slug: typeof row.slug === "string" ? row.slug : null,
-    role: typeof row.role === "string" ? row.role : "",
-    plan: typeof row.plan === "string" ? row.plan : null,
-    usage: row.usage && typeof row.usage === "object" ? row.usage : null
-  }));
-  return {
-    supported: true,
-    keyScope,
-    lastOpenWorkspaceId: typeof result.lastOpenWorkspaceId === "string" ? result.lastOpenWorkspaceId : null,
-    workspaces
-  };
-}
-function workspaceLabel(workspace) {
-  return workspace.name ? `${workspace.name} (${workspace.id})` : workspace.id;
-}
-var DEVICE_START_BODY = { action: "start", scope: "user" };
-function grantScope(grant) {
-  return grant.scope === "user" ? "user" : "org";
-}
-
-// src/onboarding.ts
 var CLAUDE_MARKETPLACE = "Openpod/impractical-agent-plugins";
 var CLAUDE_PLUGIN = "impractical-motion@impractical";
 var CLAUDE_MARKETPLACE_NAME = "impractical";
@@ -817,10 +780,6 @@ async function setup(options) {
 }
 
 export {
-  fetchWorkspaces,
-  workspaceLabel,
-  DEVICE_START_BODY,
-  grantScope,
   openBrowser,
   setup
 };

package/dist/{chunk-CJLGKZMD.js → chunk-5VN5GZWK.js}

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

package/dist/chunk-D3OOI7XP.js

@@ -0,0 +1,111 @@
+#!/usr/bin/env node
+import {
+  external_exports
+} from "./chunk-QQ6NYC74.js";
+import {
+  invoke
+} from "./chunk-5VN5GZWK.js";
+
+// src/mcp/template-source.ts
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname, resolve, sep } from "node:path";
+var SLUG = /^[a-z0-9][a-z0-9-]{0,119}$/;
+async function fetchTemplate(slug, call) {
+  if (!SLUG.test(slug)) throw new Error(`"${slug}" isn't a template slug (lowercase letters, digits and dashes)`);
+  return call("atelier-library", { action: "film-source", slug });
+}
+var readingOrder = (paths) => [...paths].sort((a, b) => rank(a) - rank(b) || a.localeCompare(b));
+var rank = (path) => path === "direction.ts" ? 0 : path === "App.tsx" ? 1 : path.startsWith("kit/") ? 3 : 2;
+var templateSourceTool = {
+  name: "template_source",
+  title: "Read a template\u2019s code",
+  description: "The source of a template from the Impractical template library (by its slug, as the Studio or a prompt names it): direction.ts (its choreography: timing, eases, camera, transitions), App.tsx (its set and components) and the rest of its files. Call it whenever someone gives you a template to work from, and study how it is built and moves before you plan. Adapt its structure and motion to the new video; never copy its content.",
+  inputSchema: {
+    slug: external_exports.string().describe('The template\u2019s slug, e.g. "framer-cms-list-replica".')
+  },
+  // read-only library browsing: admitted (unmetered) as the library's other lookups are
+  admitAs: "atelier_study",
+  handler: async (args, ctx) => {
+    const source = await fetchTemplate(String(args.slug ?? ""), ctx.invoke);
+    const paths = readingOrder(Object.keys(source.files));
+    const kits = paths.filter((p) => p.startsWith("kit/"));
+    const shown = paths.filter((p) => !p.startsWith("kit/"));
+    return {
+      text: `TEMPLATE ${args.slug}: ${paths.length} file(s). Read direction.ts first (how it moves), then App.tsx (what it shows).` + (kits.length ? ` Kits it uses (install_kits provides them): ${kits.join(", ")}.` : "") + "\n\n" + shown.map((p) => `=== ${p} ===
+${source.files[p]}`).join("\n\n")
+    };
+  }
+};
+var TEMPLATE_PAGE = 25;
+function rankTemplates(items, query) {
+  const films = items.filter((item) => item.kind === "film");
+  const words = query.toLowerCase().split(/[^a-z0-9]+/).filter((word) => word.length > 1);
+  if (!words.length) return films;
+  const score = (item) => {
+    const name = `${item.title} ${item.slug}`.toLowerCase();
+    const about = `${item.creator ?? ""} ${item.description ?? ""}`.toLowerCase();
+    return words.reduce((sum, word) => sum + (name.includes(word) ? 3 : 0) + (about.includes(word) ? 1 : 0), 0);
+  };
+  return films.map((item) => ({ item, score: score(item) })).filter((x) => x.score > 0).sort((a, b) => b.score - a.score).map((x) => x.item);
+}
+var templateSearchTool = {
+  name: "template_search",
+  title: "Find a template",
+  description: 'Search the Impractical template library (the Studio\u2019s templates: complete films, many of them replicas of real launch films such as Notion Mail, Attio or Framer) by name or words, and get each match\u2019s slug. Use it when someone mentions a template, a film in the library, or "the X one", then read the one they mean with template_source. Leave the query empty to list them all. Results come a page at a time: when there are more, the reply says so and gives the `after` to pass for the next page.',
+  inputSchema: {
+    query: external_exports.string().max(200).optional().describe('Words from the template\u2019s name or what it shows, e.g. "notion mail" or "attio sequences".'),
+    after: external_exports.number().int().min(0).optional().describe("How many results to skip: the `after` a previous reply gave, for its next page.")
+  },
+  // read-only library browsing: admitted (unmetered) as the library's other lookups are
+  admitAs: "atelier_study",
+  handler: async (args, ctx) => {
+    const { items } = await ctx.invoke("atelier-library", { action: "catalog" });
+    const query = String(args.query ?? "");
+    const all = rankTemplates(items ?? [], query);
+    if (!all.length) {
+      return { text: `No template matches "${query}". Call template_search with no query to see them all.` };
+    }
+    const after = Math.min(Math.max(0, Number(args.after ?? 0) || 0), all.length);
+    const found = all.slice(after, after + TEMPLATE_PAGE);
+    if (!found.length) {
+      return { text: `That's past the last of the ${all.length} template(s)${query ? ` for "${query}"` : ""}. Call template_search without \`after\` to start over.` };
+    }
+    const lines = found.map(
+      (item) => `- ${item.slug}: ${item.title}${item.durationSeconds ? ` (${Math.round(item.durationSeconds)}s)` : ""}` + (item.description ? ` \u2014 ${item.description.slice(0, 200)}` : "")
+    );
+    const next = after + found.length;
+    const more = next < all.length ? `
+
+Showing ${after + 1}\u2013${next} of ${all.length}. ${all.length - next} more: template_search({ ${query ? `query: ${JSON.stringify(query)}, ` : ""}after: ${next} }).` : after > 0 ? `
+
+Showing ${after + 1}\u2013${next} of ${all.length}, the last page.` : "";
+    return {
+      text: `${all.length} template(s)${query ? ` for "${query}"` : ""}, best match first:
+${lines.join("\n")}${more}
+
+Read the one meant with template_source({ slug }).`
+    };
+  }
+};
+async function templateSourceCommand(slug, dir) {
+  if (!slug || !dir) throw new Error("Usage: impractical template-source <slug> --dir <folder>");
+  const source = await fetchTemplate(slug, invoke);
+  const root = resolve(dir);
+  const written = [];
+  for (const path of readingOrder(Object.keys(source.files))) {
+    const target = resolve(root, path);
+    if (!target.startsWith(root + sep)) continue;
+    mkdirSync(dirname(target), { recursive: true });
+    writeFileSync(target, source.files[path]);
+    written.push(path);
+  }
+  return written.join("\n");
+}
+
+export {
+  templateSourceTool,
+  TEMPLATE_PAGE,
+  rankTemplates,
+  templateSearchTool,
+  templateSourceCommand
+};