@impractical-ai/motion 0.1.0

package/assets/impractical/SKILL.md

@@ -0,0 +1,215 @@
+---
+name: impractical
+description: Create and refine studio-quality motion-graphics launch videos with Impractical Motion. Use when the user wants a marketing, launch, promo, or product video made or tweaked, mentions Impractical, or wants to edit an Impractical draft, extract a brand kit, or export a final MP4.
+---
+
+# Impractical Motion
+
+You direct the video yourself. Impractical provides the engine, the preview
+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)
+
+Call the `account_status` tool (`whoami` is its legacy alias). If the
+Impractical tools are not available, the Claude plugin is not connected. Tell
+the user to run:
+
+    npx --yes @impractical-ai/motion setup --claude
+
+Then ask them to run `/reload-plugins` and type `continue`. 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.
+
+If they gave a brand URL and no kit exists yet:
+
+    brand_list
+    brand_extract  { url: "https://example.com" }
+
+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 build error if your code does not compile** — that is
+your compile loop, so read it and fix 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 thing on
+  screen, and a move. A beat with no move is not a beat.
+- **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`.
+- **Fast**: entrances 0.4–0.6s, exits shorter, staggers ~0.2s apart, nothing
+  over 1s but a deliberate hold drift or slow push.
+- **Nothing is ever static.** Every hold carries a slow drift or camera push.
+- 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.
+
+## 5. Export and hand off
+
+    export_video  { draftId: "..." }
+    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.
+
+## 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.

package/dist/chunk-2RJVXP4V.js

@@ -0,0 +1,325 @@
+#!/usr/bin/env node
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __commonJS = (cb, mod) => function __require() {
+  return mod || (0, cb[__getOwnPropNames(cb)[0]])((mod = { exports: {} }).exports, mod), mod.exports;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+
+// src/config.ts
+import { readFileSync, writeFileSync, mkdirSync, chmodSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+// src/constants.ts
+var PRODUCTION_APP_URL = "https://motion.impractical.ai";
+var PRODUCTION_SUPABASE_URL = "https://uaxjweednprtbhbceify.supabase.co";
+var PACKAGE_NAME = "@impractical-ai/motion";
+var PACKAGE_COMMAND = `npx --yes ${PACKAGE_NAME}`;
+
+// src/config.ts
+var configDir = () => join(homedir(), ".impractical");
+var configPath = () => join(configDir(), "config.json");
+function loadConfig() {
+  let stored = {};
+  try {
+    stored = JSON.parse(readFileSync(configPath(), "utf8"));
+  } catch {
+  }
+  return {
+    apiKey: process.env.IMPRACTICAL_API_KEY ?? stored.apiKey,
+    supabaseUrl: process.env.IMPRACTICAL_SUPABASE_URL ?? stored.supabaseUrl ?? PRODUCTION_SUPABASE_URL,
+    appUrl: process.env.IMPRACTICAL_APP_URL ?? stored.appUrl ?? PRODUCTION_APP_URL
+  };
+}
+function saveConfig(patch) {
+  let stored = {};
+  try {
+    stored = JSON.parse(readFileSync(configPath(), "utf8"));
+  } catch {
+  }
+  const next = { ...stored, ...patch };
+  mkdirSync(configDir(), { recursive: true });
+  writeFileSync(configPath(), JSON.stringify(next, null, 2) + "\n");
+  chmodSync(configPath(), 384);
+  return next;
+}
+function requireConfig() {
+  const config = loadConfig();
+  if (!config.supabaseUrl) {
+    throw new Error("Not configured. Run: npx --yes @impractical-ai/motion setup --claude");
+  }
+  if (!config.apiKey) {
+    throw new Error("Not connected. Run: npx --yes @impractical-ai/motion setup --claude");
+  }
+  return config;
+}
+
+// src/api.ts
+import { AsyncLocalStorage } from "node:async_hooks";
+import { randomUUID } from "node:crypto";
+var admissionContext = new AsyncLocalStorage();
+var ApiError = class extends Error {
+  constructor(status, message, fn) {
+    super(message);
+    this.status = status;
+    this.fn = fn;
+  }
+};
+async function invoke(name, body = {}) {
+  const { apiKey, supabaseUrl } = requireConfig();
+  const receipt = admissionContext.getStore();
+  return invokeAt(supabaseUrl, name, body, apiKey, receipt);
+}
+async function invokeAt(supabaseUrl, name, body = {}, apiKey, admissionReceipt) {
+  const response = await fetch(`${supabaseUrl.replace(/\/$/, "")}/functions/v1/${name}`, {
+    method: "POST",
+    headers: {
+      ...apiKey ? { authorization: `Bearer ${apiKey}` } : {},
+      ...admissionReceipt ? { "x-impractical-admission": admissionReceipt } : {},
+      "content-type": "application/json"
+    },
+    body: JSON.stringify(body)
+  });
+  const text = await response.text();
+  let data = null;
+  try {
+    data = text ? JSON.parse(text) : null;
+  } catch {
+  }
+  if (!response.ok) {
+    const message = data?.error ?? (text || `${name} failed (${response.status})`);
+    throw new ApiError(response.status, message, name);
+  }
+  return data;
+}
+async function admitMcpCall(toolName, callId = randomUUID()) {
+  const { apiKey, supabaseUrl } = requireConfig();
+  return invokeAt(supabaseUrl, "mcp-admission", { callId, toolName }, apiKey);
+}
+function withAdmissionReceipt(receipt, task) {
+  return admissionContext.run(receipt, task);
+}
+async function withMeteredCall(toolName, task) {
+  const admission = await admitMcpCall(toolName);
+  return withAdmissionReceipt(admission.receipt, task);
+}
+var delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+async function jobStatus(jobIds) {
+  const result = await invoke("job-status", { jobIds });
+  return result.jobs;
+}
+async function waitForJobs(jobIds, onTick, deadlineMs = 72e5) {
+  const deadline = Date.now() + deadlineMs;
+  const terminal = /* @__PURE__ */ new Set();
+  let latest = [];
+  while (terminal.size < jobIds.length) {
+    if (Date.now() >= deadline) throw new Error("Timed out waiting for jobs");
+    latest = await jobStatus(jobIds);
+    for (const row of latest) {
+      if (row.status === "completed" || row.status === "failed" || row.status === "canceled") {
+        terminal.add(row.id);
+      }
+    }
+    onTick(latest);
+    if (terminal.size < jobIds.length) await delay(2e3);
+  }
+  return latest;
+}
+function studioLink(appUrl, projectId, slug) {
+  const base = (appUrl ?? "http://localhost:5173").replace(/\/$/, "");
+  return `${base}/projects/${projectId}/studio${slug ? `?scene=${slug}` : ""}`;
+}
+
+// src/onboarding.ts
+import { chmodSync as chmodSync2, existsSync, mkdirSync as mkdirSync2, readFileSync as readFileSync2, writeFileSync as writeFileSync2 } from "node:fs";
+import { homedir as homedir2 } from "node:os";
+import { dirname, join as join2 } from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawnSync } from "node:child_process";
+var CLAUDE_MARKETPLACE = "Openpod/impractical-agent-plugins";
+var CLAUDE_PLUGIN = "impractical-motion@impractical";
+function commandResult(command, args) {
+  return spawnSync(command, args, { encoding: "utf8", windowsHide: true });
+}
+function requireCommand(command, label) {
+  const result = commandResult(command, ["--version"]);
+  if (result.error || result.status !== 0) {
+    throw new Error(`${label} is required before setup can continue.`);
+  }
+}
+function hasChrome() {
+  const macPaths = [
+    "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+    "/Applications/Chromium.app/Contents/MacOS/Chromium"
+  ];
+  if (macPaths.some(existsSync)) return true;
+  return ["google-chrome", "google-chrome-stable", "chromium", "chromium-browser"].some((command) => {
+    const result = spawnSync(command, ["--version"], { stdio: "ignore", windowsHide: true });
+    return !result.error && result.status === 0;
+  });
+}
+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, tolerateAlreadyInstalled = false) {
+  const result = commandResult("claude", args);
+  if (!result.error && result.status === 0) return;
+  const detail = `${result.stdout ?? ""}
+${result.stderr ?? ""}`.trim();
+  if (tolerateAlreadyInstalled && /already (?:added|exists|installed|configured)/i.test(detail)) return;
+  throw new Error(`Claude plugin setup failed: ${detail || result.error?.message || "unknown error"}`);
+}
+function installClaudePlugin() {
+  runClaude(["plugin", "marketplace", "add", CLAUDE_MARKETPLACE], true);
+  runClaude(["plugin", "install", CLAUDE_PLUGIN, "--scope", "user"], true);
+  runClaude(["plugin", "marketplace", "update", "impractical"], true);
+  runClaude(["plugin", "update", CLAUDE_PLUGIN], true);
+}
+var skillSourcePath = () => fileURLToPath(new URL("../assets/impractical/SKILL.md", import.meta.url));
+function installSkills(home = homedir2(), sourcePath = skillSourcePath()) {
+  const source = readFileSync2(sourcePath, "utf8");
+  const targets = [
+    {
+      harness: "Claude Code",
+      path: join2(home, ".claude", "skills", "impractical", "SKILL.md")
+    },
+    {
+      harness: "Codex",
+      path: join2(home, ".codex", "skills", "impractical", "SKILL.md")
+    }
+  ];
+  for (const target of targets) {
+    mkdirSync2(dirname(target.path), { recursive: true, mode: 448 });
+    writeFileSync2(target.path, source, { mode: 420 });
+  }
+  return targets;
+}
+function browserCommand(url) {
+  if (process.platform === "darwin") return { command: "open", args: [url] };
+  if (process.platform === "win32") return { command: "cmd", args: ["/c", "start", "", url] };
+  return { command: "xdg-open", args: [url] };
+}
+function openBrowser(url) {
+  const launch = browserCommand(url);
+  const result = spawnSync(launch.command, launch.args, {
+    stdio: "ignore",
+    windowsHide: true
+  });
+  return !result.error && result.status === 0;
+}
+async function waitForApproval(supabaseUrl, authorization, log) {
+  const deadline = Date.parse(authorization.expiresAt);
+  const intervalMs = Math.max(1, authorization.intervalSeconds) * 1e3;
+  let announced = false;
+  while (Date.now() < deadline) {
+    const result = await invokeAt(supabaseUrl, "cli-device-auth", {
+      action: "poll",
+      deviceCode: authorization.deviceCode
+    });
+    if (result.status === "authorized") return result.apiKey;
+    if (!announced) {
+      log("Waiting for browser approval\u2026");
+      announced = true;
+    }
+    await delay(intervalMs);
+  }
+  throw new Error(`Authorization expired. Run \`${PACKAGE_COMMAND} setup --claude\` again.`);
+}
+async function setup(options) {
+  if (options.installClaudePlugin) verifyClaudePrerequisites();
+  const supabaseUrl = process.env.IMPRACTICAL_SUPABASE_URL?.trim() || PRODUCTION_SUPABASE_URL;
+  const appUrl = process.env.IMPRACTICAL_APP_URL?.trim() || PRODUCTION_APP_URL;
+  const authorization = await invokeAt(supabaseUrl, "cli-device-auth", {
+    action: "start"
+  });
+  options.log("");
+  options.log("Connect Impractical Motion");
+  options.log(`Code: ${authorization.userCode}`);
+  options.log(`Open: ${authorization.verificationUri}`);
+  options.log("");
+  if (options.openBrowser) {
+    const opened = openBrowser(authorization.verificationUri);
+    options.log(opened ? "Opened your browser." : "Could not open a browser automatically; use the link above.");
+  }
+  let apiKey;
+  try {
+    apiKey = await waitForApproval(supabaseUrl, authorization, options.log);
+  } catch (error) {
+    if (error instanceof ApiError && error.status === 410) {
+      throw new Error(`Authorization expired. Run \`${PACKAGE_COMMAND} setup --claude\` again.`);
+    }
+    throw error;
+  }
+  saveConfig({ apiKey, supabaseUrl, appUrl });
+  const configPath2 = join2(homedir2(), ".impractical", "config.json");
+  chmodSync2(configPath2, 384);
+  const verified = await invokeAt(
+    supabaseUrl,
+    "workspace-bootstrap",
+    {},
+    apiKey
+  );
+  if (options.installClaudePlugin) installClaudePlugin();
+  const installed = options.installAgentSkills ? installSkills() : [];
+  options.log("");
+  options.log("Connected.");
+  for (const skill of installed) {
+    options.log(`Installed /impractical for ${skill.harness}.`);
+  }
+  if (options.installClaudePlugin) {
+    options.log(`Installed ${CLAUDE_PLUGIN} for Claude Code (user scope).`);
+  }
+  options.log(`Workspace: ${verified.orgId}${verified.plan ? ` \xB7 ${verified.plan}` : ""}`);
+  options.log("");
+  options.log("Run /reload-plugins, then type continue.");
+  return { installed, appUrl, supabaseUrl };
+}
+
+export {
+  __commonJS,
+  __export,
+  __toESM,
+  PRODUCTION_APP_URL,
+  PRODUCTION_SUPABASE_URL,
+  loadConfig,
+  saveConfig,
+  requireConfig,
+  ApiError,
+  invoke,
+  invokeAt,
+  admitMcpCall,
+  withAdmissionReceipt,
+  withMeteredCall,
+  jobStatus,
+  waitForJobs,
+  studioLink,
+  openBrowser,
+  setup
+};