@impractical-ai/motion 0.1.0 → 0.1.2

package/README.md

@@ -0,0 +1,43 @@
+# Impractical Motion CLI
+
+Connect Claude Code to Impractical Motion through its MCP server.
+
+## Requirements
+
+- Node.js 22 or newer
+- Claude Code installed and signed in
+- Google Chrome or Chromium for frame inspection
+
+## Setup
+
+```sh
+npx --yes @impractical-ai/motion setup --claude
+```
+
+Approve the device code in the browser, then run `/reload-plugins` in Claude Code and type
+`continue`. Re-running setup verifies and reuses a working credential, refreshes the user-scoped
+plugin, and does not require another browser authorization.
+
+Setup writes the API credential to `~/.impractical/config.json` with mode `0600`. Environment
+variables `IMPRACTICAL_API_KEY`, `IMPRACTICAL_SUPABASE_URL`, and `IMPRACTICAL_APP_URL` take
+precedence over that file.
+
+## MCP server
+
+The installed Claude plugin launches the server automatically. Other MCP clients can run:
+
+```sh
+npx --yes @impractical-ai/motion mcp
+```
+
+Check the connection with:
+
+```sh
+npx --yes --package @impractical-ai/motion impractical whoami
+```
+
+A healthy result prints the workspace org and plan. `claude mcp list` only proves that the MCP
+process starts; it does not verify the Impractical credential.
+
+If authorization is rejected, rerun the setup command. If the configuration file is malformed,
+the CLI reports its exact path instead of silently ignoring it.

package/assets/engine.d.ts

@@ -65,7 +65,7 @@ export type TextUnit = 'chars' | 'words' | 'lines'
 export type RevealEffect =
   | 'rise' // masked characters rise in from below (the house classic)
   | 'fall' // masked characters drop in from above
-  | 'blur' // words de-blur and fade in
+  | 'blur' // special effect only: never default readable text to word-by-word de-blur
   | 'wave' // characters bob up with an overshoot, heavily overlapped
   | 'flip' // characters flip up from flat (3D rotationX)
   | 'pop' // characters scale in with a springy overshoot
@@ -708,6 +708,12 @@ export type SceneInspection = {
   tweens: TweenInfo[]
   cameraSets: CameraSetInfo[]
   overrides: SceneOverrides
+  /**
+   * Non-fatal build complaints — a step whose element is gone, a text effect
+   * with nothing left to split. The scene still plays; these say what silently
+   * does nothing so a stale selector can't rot unnoticed.
+   */
+  warnings: string[]
 }
 
 export type DirectionContext = {

package/assets/impractical/SKILL.md

@@ -53,6 +53,7 @@ If they gave a brand URL and no kit exists yet:
 
     brand_list
     brand_extract  { url: "https://example.com" }
+    brand_extract  { jobId: "<returned run id>", wait: true }
 
 Then scaffold the project:
 
@@ -72,8 +73,9 @@ A scene is two files, and both must exist for the preview to build:
 
 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.
+preview and returns the committed revision plus its build job id immediately.
+Follow that id with `job_status { jobIds: ["..."], wait: true }`; that result is
+your compile loop, so read and fix any build error rather than guessing.
 
 Rules that matter:
 
@@ -168,11 +170,32 @@ again. This is the difference between shipping a video and shipping a guess.
 ## 5. Export and hand off
 
     export_video  { draftId: "..." }
+    job_status    { jobIds: ["<returned job id>"], wait: true }
     studio_link   { projectId: "...", slug: "..." }
 
 Always give the user the studio link — that is where they watch the cuts and
 tweak visually. The export URL expires, so only export once they are happy.
 
+## Timeouts and lost acknowledgements
+
+Build, export, and brand-extraction calls return their job or run id before
+waiting. Continue build/export ids with `job_status`, and continue a brand run
+with `brand_extract { jobId, wait: true }` (never the URL again). If the MCP
+client kills any call and shows only a timeout, the mutation may still have
+committed even though its acknowledgement was lost.
+**Never blindly retry a mutating or metered call.** Verify state first:
+
+- After `write_draft_files` / `edit_draft_file`, use `list_draft_files` and
+  `read_draft_file` to confirm the intended revision and source.
+- After an export or other project mutation, use `get_project` / `list_projects`
+  to check whether it already started or completed.
+- After `brand_extract`, continue its returned id with `brand_extract { jobId, wait: true }`. If the
+  start acknowledgement was lost, check `brand_list` / `brand_get` before
+  starting another extraction, especially when `reextract: true`.
+
+Retry only when those reads prove the mutation did not commit. Otherwise
+continue from the state you observed; a duplicate edit or export wastes quota.
+
 ## The personal motion profile
 
 The `motion_profile` tool manages what Impractical remembers about this user's