@higgsfield/video-editor-mcp 1.1.1-dev.0 → 2.0.0

package/plugin/skills/video-editing/references/failure-modes.md

@@ -1,37 +0,0 @@
-# Limits and diagnostics
-
-| Symptom / refusal                 | Contract                                                                                       |
-| --------------------------------- | ---------------------------------------------------------------------------------------------- |
-| Frame or motion field unknown     | Installed CLI/types determine support; source changes do not update an installed bundle        |
-| Fill under hug / unresolved slot  | Fill needs a resolvable parent axis; absolute frames need dimensions                           |
-| Child or keys exceed lifetime     | Local spans must fit the owner; frames exclude their exact endpoint                            |
-| `animate` object rejected         | `animate` is an array; frame `motion` is an object                                             |
-| Duplicate property tracks         | Replacement channels have one owner; raw offsets add and uniform scales multiply               |
-| Incorrect shader animation target | `effectIndex` selects a declared effect; `effectParam` is its existing numeric key             |
-| Missing shader / texture / GL     | Rendering fails; texture binding uses imported `handle.id`, not URL or handle object           |
-| Shader raster overflow            | Raster bounds exclude overflowing child/stroke/ink; clip or inset the content                  |
-| LUT / shader adjustment / HTML    | Unsupported by the native CLI                                                                  |
-| Text `fill` / rect stroke object  | Text uses `color`; rect uses flat `strokeColor`/`strokeWidth`; path has `stroke` object        |
-| Missing glyphs                    | Font registration does not establish glyph coverage; Lucide paths have no font dependency      |
-| Stretched footage                 | `fill` stretches; frame-slot `contain`/`cover` preserve aspect                                 |
-| Unexpected source moment          | `from`/`trimStart` are source time, not placement time                                         |
-| Lost human edits                  | Whole-script build replaces timeline; fresh `inspect` + bounded `do`/`ops` preserve other work |
-
-## Evidence provided by each command
-
-- `doctor`: installed native dependencies and render smoke.
-- `compose` with `dryRun: true`: validation and compiled layout, without mutation.
-- `inspect --at`: evaluated parameters and lifetimes, not shader execution/world geometry.
-- `frame` / `render`: actual pixels and runtime diagnostics. `sheet` samples frames.
-- `probe` / ffprobe: actual media streams; extensions do not establish codecs/depth.
-
-Ten-bit encoding does not guarantee ten-bit processing. Render `fallbacks` report
-windows that used the eight-bit compositor; GLSL itself is RGBA8. Shader GL selection
-is independent of video encoder `accel`. Native and browser shader support differ.
-
-Main10 sources decode directly through ffmpeg without a compatibility transcode.
-Frame equality requires matching assets/fonts/runtime. MP4 metadata and encoders
-can change container hashes. An interrupted render or a successful script with no
-render call is not a completed movie.
-
-[API](compose.md) · [Inspection](editor-measured.md)

package/plugin/skills/video-editing/references/local-setup.md

@@ -1,25 +0,0 @@
-# Local plugin setup
-
-The Higgsfield Video Editor plugin supplies `video-editing`, `motion-craft` and
-the `video_editing_*` tools. Run setup on the user's Mac, outside `sandbox_exec`.
-Requires Node.js 22.12 or later.
-
-```sh
-dir="$HOME/.higgsfield/video-editor-mcp"
-npm install --prefix "$dir" --registry=https://registry.npmjs.org/ --ignore-scripts --no-audit --no-fund @higgsfield/video-editor-mcp@latest
-cli="$dir/node_modules/@higgsfield/video-editor-mcp/dist/cli.mjs"
-node "$cli" doctor
-node "$cli" install-plugin
-```
-
-If the registry is unreachable or denies the package, report the error. Never
-substitute a different package or bypass the registry. Fix a failed doctor check.
-Reload the desktop app to discover plugin skills, then start a new chat for its
-tools. If a standalone `higgsfield-use-video-editor` MCP registration is also
-present, inspect it and remove it before using the plugin to avoid duplicate
-tools. Do not remove an entry with a different configuration.
-
-The npm install's launcher checks for updates in the background at startup, at
-most once per hour. Server, UI, Higgsedit and the registered plugin bundle update
-together; active chats retain their current version. Reload the app for updated
-skills and metadata. `node "$cli" update` forces an immediate check.

package/plugin/skills/video-editing/references/motion-language.md

@@ -1,27 +0,0 @@
-# Motion feature mappings
-
-These are combinations of native features, not additional preset names.
-Exact fields and limits: [composition API](compose.md).
-
-| Result                            | Supported mechanism                                                          |
-| --------------------------------- | ---------------------------------------------------------------------------- |
-| Entrance / hold / exit            | Frame `motion.enter`, `settle`, end-anchored `exit`                          |
-| Pop / overshoot / spring          | Choreography easing objects or explicit raw scale keys                       |
-| Staggered cards                   | `motion.timeline.stagger` with `each`; targets are immediate child frames    |
-| Word / character / line arrival   | Text `motion.by`; one text clip                                              |
-| Wipe / phrase highlight           | Frame `clip` + `reveal`, or animated mask geometry                           |
-| Counter and bar                   | One timeline leaf with `targets`: transform bindings plus explicit `counter` |
-| Slider / cursor / target coupling | Shared `targets` progress or identical authored key times                    |
-| State replacement                 | Timed sibling clips, opacity tracks, or sequence transitions                 |
-| Repeated movement                 | Finite closed `animate` chain with `repeat`                                  |
-| Connector reveal / morph          | Mask wipe, or matching `d`/`morphTo` with `morphProgress`                    |
-| Camera move / parallax            | Parent frame transforms, or compose camera with top-level `z`                |
-| Particles / glitch                | Finite generated shapes and deterministic authored keyframe tables           |
-
-A mask wipe is not a path-length-aware stroke draw. Shaped glyph outlines instead
-support `textDrawProgress` with font bytes and visible stroke.
-
-Shared counters use held scene-fps samples for all coupled bindings, not a
-runtime text callback. Independent animated values are not automatically coupled.
-A color tween is a solid-color change; gradient stencils use separate geometry
-and mattes. None of these mappings implies cross-scene object identity.

package/plugin/skills/video-editing/references/provenance.md

@@ -1,7 +0,0 @@
-# Reference provenance
-
-This skill's reference organization was informed by the public Apache-2.0 project [heygen-com/hyperframes](https://github.com/heygen-com/hyperframes), inspected at commit `8800214`.
-
-Only general documentation patterns were retained, such as separating renderer contracts from examples and grouping related capabilities by deliverable.
-
-All commands, APIs, schemas, timing semantics, effects, layout behavior, project mutation rules, and limitations documented here are for `higgsedit`. HyperFrames-specific `data-*` clips, GSAP timelines, adapters, lint commands, and render architecture are not supported `higgsedit` syntax.

package/plugin/skills/video-editing/references/sandbox.md

@@ -1,31 +0,0 @@
-This reference applies to sandbox `project.json` projects, not local TSX.
-
-# Sandbox script API
-
-Scripts accept JSX/TSX or supplied node builders; no React or DOM runtime.
-
-| Call                                                                              | Result                      |
-| --------------------------------------------------------------------------------- | --------------------------- |
-| `await project({dir, size, fps, background})`                                     | Create/open project         |
-| `await p.add(file)`                                                               | Import asset; return handle |
-| `p.cut(handle, {from, dur, at, fit})`                                             | Place footage/audio         |
-| `p.compose(nodes, {at, dur, name, camera})`                                       | Place native graphics/media |
-| `p.duration()` / `await p.read()`                                                 | Timeline length / document  |
-| `await p.frame(time, out)`                                                        | PNG                         |
-| `await p.render(out, {draft, depth, codec, bitrate, accel, shards, concurrency})` | Encoded movie               |
-
-`from` is source seconds; composition `at` is timeline seconds. Frame children
-and animations use local seconds. `cut` and `compose` record work synchronously.
-
-See the [complete example](compose.md#complete-example).
-
-## Capabilities
-
-| Area     | Features                                                                                                   |
-| -------- | ---------------------------------------------------------------------------------------------------------- |
-| Media    | Import images/video/audio; source trims, cuts, fitting and audio mixing                                    |
-| Layout   | Persistent frames: column, row, equal-column grid, absolute; fill/hug sizing                               |
-| Graphics | Text, shaped fonts, rectangles, gradients, paths, Lucide icons, masks and mattes                           |
-| Motion   | Raw keyframes, frame choreography, shared counters, token text, transitions, 2.5D camera                   |
-| Effects  | Standard filters, shadows, motion blur, custom GLSL, image textures, animated uniforms                     |
-| Output   | Native PNGs, contact sheets, MP4/MOV/MKV, H.264, H.265/HEVC Main10, AV1, target bitrate, editable projects |

package/plugin/skills/video-editing/references/shot-blueprints.md

@@ -1,24 +0,0 @@
-# Shot construction primitives
-
-These are capability mappings, not required scene templates.
-
-| Need                               | Native primitives                                                                  |
-| ---------------------------------- | ---------------------------------------------------------------------------------- |
-| Sequential phrases or states       | `sequence`, child `at`/`duration`, text keyframes                                  |
-| Cards, lists, or logo walls        | persistent `frame` with column, row, or equal-column grid layout                   |
-| Input-to-result demonstration      | frames for UI regions, cursor paths, explicit state clips                          |
-| Control and target moving together | shared keyframe data applied to separate nodes or frame motion targets             |
-| Footage beside graphics            | row/column frame with a centered `media` slot and text/card frames                 |
-| Talking head with overlays         | spine cut for audio/picture plus composed frames for titles and cards              |
-| Metrics and charts                 | text, rect, path, `effectParam`, width/height, color, and draw-progress tracks     |
-| Hub-and-spoke diagram              | path connectors, icon/media nodes, groups, and 2D transforms                       |
-| Before/after comparison            | row or grid frames with synchronized node tracks                                   |
-| Zoom or parallax                   | top-level `z` values plus `compose(..., { camera })`, or group/frame 2D transforms |
-| Logo or title build                | path, shaped-text draw progress, masks, reveal, token motion, and keyframes        |
-| Abstract field                     | deterministic path/rect states, gradients, effects, and explicit tracks            |
-
-Persistent frames retain editable layout. `layout="grid"` supports an integer `columns` count with equal columns; spans and `minmax` are unsupported. `layout="none"` enables deliberate positioning.
-
-Frame child clocks are parent-local. Keyframes are node-local. A child with explicit timing must fit the parent's half-open lifetime. There are no per-frame callbacks; represent state with keyframes, sequence children, text motion, frame choreography, or explicit clips.
-
-Use `contain` or `cover` media in a frame with resolvable dimensions. Animate frame width/height when layout should reflow; use `reveal` when layout should remain fixed.

package/plugin/skills/video-editing/references/title-animation.md

@@ -1,29 +0,0 @@
-# Title animation primitives
-
-Titles are native node trees. There is no title-animation library or per-frame callback API.
-
-## Primitives
-
-- **Move, scale, rotate, fade:** node `animate` tracks or frame `motion`.
-- **Blur and color:** raw `animate` tracks, not frame poses.
-- **Token entrance:** `text.motion` by character, word, or line.
-- **Wipe:** frame `reveal` or node mask with `maskWidth`/`maskHeight` animation.
-- **Outline and draw-on:** text `strokeColor`/`strokeWidth`; shaped text `textDrawProgress`; path `strokeWidth` animation or mask reveals.
-- **Reflowing resize:** animate persistent frame `width` or `height`.
-- **Fixed-layout transform:** animate a frame or group transform.
-- **State sequence:** `sequence` children, explicit child timing, or keyframe chains.
-- **2.5D camera:** top-level node `z` plus `compose(..., { camera })`.
-- **Effects:** ordered node `effects`; animate numeric parameters with `property: "effectParam"`, `effectIndex`, and `effectParam`.
-- **Motion blur:** `motionBlur: true` or `{ samples, shutter }`; effects are evaluated through motion-blur samples.
-
-## Timing contract
-
-Animation times are local to the node. Replacement properties use one track; raw offsets add and uniform scales multiply. Keyframe times must strictly increase and the chain must end within the node lifetime. Frame children use the immediate parent's local clock and must fit its half-open lifetime.
-
-Component node trees compile at local time zero. Place only the component instance root on the timeline; nested nodes retain local timing.
-
-A positioned frame can use `origin="center"` for center-based transforms. Frame `width`/`height` tracks trigger layout; `reveal` does not.
-
-Text uses flat `strokeColor` and `strokeWidth`, not a `stroke` object. `path()` accepts `M/L/H/V/C/Q/Z` commands in its own pixel coordinate system and does not scale path data merely because `width` or `height` changes.
-
-Raw easing accepts named curves or four cubic-bezier handles. Frame choreography also supports steps, overshoot, and bounded spring timing.

package/plugin/skills/video-editing/references/tsx-projects.md

@@ -1,187 +0,0 @@
-# Local project guide
-
-The local document is `index.tsx` with assets in `media/` and output in `renders/`.
-Use local `video_editing_*` tools, not sandbox project APIs. Import assets with
-`video_editing_import_media` and check them with `video_editing_media_probe`.
-
-## Project
-
-```tsx
-export default function Project() {
-  return (
-    <stage id="stage">
-      <scene id="scene" width={1080} height={1920} fps={30} fill="#0b0c0e">
-        <sequence id="cuts">
-          <video
-            id="a"
-            src="./media/a.mp4"
-            width={1080}
-            height={1920}
-            start={0}
-            end={4}
-            transition={{ type: "dissolve", duration: 0.5 }}
-          />
-          <video
-            id="b"
-            src="./media/b.mp4"
-            width={1080}
-            height={1920}
-            start={4}
-            end={7}
-            sourceIn={2}
-          />
-        </sequence>
-        <text
-          id="title"
-          x={90}
-          y={860}
-          width={900}
-          end={3}
-          fontSize={96}
-          fontWeight={700}
-          align="center"
-          fill="#ffffff"
-          enter={{ preset: "slide-up", duration: 0.4 }}
-        >
-          Title
-        </text>
-      </scene>
-    </stage>
-  );
-}
-```
-
-## Loop
-
-Read `video_editing_outline`, make bounded `video_editing_edit` changes, preview
-with `video_editing_preview_frames`, then render and poll `video_editing_render_status`.
-Undo/redo is shared with the panel. Rendered files remain on the user's disk.
-
-## Edits
-
-| op          | Fields                                          | Notes                                                          |
-| ----------- | ----------------------------------------------- | -------------------------------------------------------------- |
-| `set-prop`  | `id`, `name`, `value`                           | Literal JSON; `null` removes; paths like `animate.opacity.1.1` |
-| `set-text`  | `id`, `text`                                    | `<text>` content                                               |
-| `insert`    | `id` (parent), `tag`, `props`, `text`, `before` | Returns the new id; `props` cannot set `id`                    |
-| `remove`    | `id`                                            |                                                                |
-| `move`      | `id`, `parent`, `before`                        |                                                                |
-| `retime`    | `id`, `start`, `end`                            | On the parent's clock                                          |
-| `set-const` | `name`, `value`, `file`                         | An `@inspect` const from the outline                           |
-
-Refusals write nothing: `expression` (the prop is computed by code), `loop-bound` (made inside a
-`map`), `shared-component` (one component used in several places), `not-found`, `ambiguous-id` and
-`invalid`. Change the controlling `@inspect` const, edit an unshared element instead, or explain the
-limit. Do not repeat a refused edit unchanged.
-
-A path like `animate.opacity.1.1` (the second keyframe's value) only addresses a literal that already
-exists. To add one, set the whole prop: `name: "animate"` with `{ opacity: [[0, 0], [0.5, 1]] }`.
-
-## Time
-
-`Time` is seconds, `"30f"` (frames at the scene fps), `"MM:SS"` or `"HH:MM:SS"`. `start`/`end` are on the
-parent scene's or group's clock. Keyframe times are relative to the element's start.
-
-## Elements
-
-`stage`, `scene`, `group`, `sequence`, `rect`, `text`, `textRange`, `image`, `video`, `audio`,
-`captions`, `adjustmentLayer`, `shaderPaint`, `surface` and `html`.
-
-- Transform on visual elements: `x`, `y`, `width`, `height`, `anchorX`/`anchorY` (fractions of the box,
-  default top-left), `rotation` (degrees), `scale`, `opacity`, `blur`, shadows, `stroke`, `clip`,
-  `blend`, `mask`, `effects` and `constrainX`/`constrainY`.
-- `fill` takes a CSS colour or `{ type: "linear" | "radial", rotation, stops }`.
-- `video`/`audio`: `sourceIn`, `volume`, `muted`, `fadeIn`, `fadeOut`, `speed`, `preservePitch` and
-  `syncTo` (the id of another recording to align by audio). `video`/`image`: `fit` (`cover`, `contain`
-  or `fill`) and `cornerRadius`.
-- `sequence`: clips back to back. Give each child `start`/`end` with every `start` at the previous
-  `end`; `check` warns about overlaps. A child's `transition` is `dissolve`, `slideFromRight`,
-  `slideFromLeft`, `fadeToBlack`, `fadeToWhite`, `whipPan`, `zoomThrough` or `pixelDissolve`.
-- `textRange start end` restyles characters of its parent `<text>`.
-- `captions src`: a `.srt`, `.vtt` or word-timed `.json` transcript; `preset` is `classic`, `whisper`,
-  `cascade`, `spotlight`, `paper`, `guinea` or `stark`. Shift `sourceIn`/`sourceOut` along with the
-  footage.
-- `adjustmentLayer`: draws nothing; its transform applies to the sibling just before it, which makes
-  punch-ins and shakes.
-
-## Timeline structure
-
-Each direct child of a scene creates a timeline track, even when its lifetime does
-not overlap another child. A direct `<sequence>` creates one track containing its
-children as clips; a `<group>` keeps its overlapping children inside one editable clip.
-
-For consecutive graphic shots, put each shot's text and shapes in a named group,
-then put the shot groups in one sequence. Keep independent overlays and audio on
-separate tracks when their timing or stacking requires it. Do not put overlapping
-elements directly in a sequence or move unrelated layers together merely to reduce
-the track count. Preserve sibling order: later siblings paint above earlier ones.
-
-Use full-scene group geometry for unchanged coordinates. Child times are on the
-group's clock: when moving an element into a group starting at 4s, subtract 4s from
-its start/end, preserving its animation keyframes relative to its own start.
-Keep the computed offsets without rounding; rounding can move an entrance by one frame.
-The edit API currently rounds numbers to milliseconds. Inspect written timing after
-regrouping; use TSX expressions such as `start={7.8 - 7}` when exact timing requires it.
-
-This four-shot graphic has one track with four group clips. Inside a group, the
-background and title overlap and remain individually editable:
-
-```tsx
-export default function Project() {
-  return (
-    <stage id="stage">
-      <scene id="scene" width={640} height={360} fps={30} end={4} fill="#101629">
-        <sequence id="poster" name="Poster shots">
-          <group id="intro" name="Intro" width={640} height={360} start={0} end={1}>
-            <rect id="intro-bg" width={640} height={360} fill="#101629" end={1} />
-            <text id="intro-title" x={40} y={120} end={1} fontSize={48} fill="#ffffff">
-              MAKE
-            </text>
-          </group>
-          <group id="room" name="Room" width={640} height={360} start={1} end={2}>
-            <rect id="room-bg" width={640} height={360} fill="#6252f4" end={1} />
-            <text
-              id="room-title"
-              x={40}
-              y={120}
-              start={0.1}
-              end={1}
-              fontSize={48}
-              fill="#ffffff"
-              enter={{ preset: "fade", duration: 0.2 }}
-            >
-              ROOM
-            </text>
-          </group>
-          <group id="for" name="For" width={640} height={360} start={2} end={3}>
-            <rect id="for-bg" width={640} height={360} fill="#25204f" end={1} />
-            <text id="for-title" x={40} y={120} end={1} fontSize={48} fill="#ffffff">
-              FOR
-            </text>
-          </group>
-          <group id="wonder" name="Wonder" width={640} height={360} start={3} end={4}>
-            <rect id="wonder-bg" width={640} height={360} fill="#ff6338" end={1} />
-            <text id="wonder-title" x={40} y={120} end={1} fontSize={48} fill="#ffffff">
-              WONDER
-            </text>
-          </group>
-        </sequence>
-      </scene>
-    </stage>
-  );
-}
-```
-
-Inspect the outline after authoring: these groups should appear under `poster`,
-with their text and shapes one level deeper. Check shot boundaries and an animated
-instant in the preview as well; a successful MP4 render does not verify track structure.
-
-## Motion
-
-`animate={{ opacity: [[0, 0], [0.5, 1, "easeOut"]] }}`: each keyframe is
-`[time, value, easing?]`, and the easing applies to the segment that starts there. Easings are
-`linear`, `easeIn`, `easeOut`, `easeInOut`, `step` and `cubicBezier(x1, y1, x2, y2)`. Most numeric props and `fill` are animatable.
-
-`enter`/`exit` take `{ preset, duration, easing, at }`. The presets are `fade`, `grow`, `shrink`, `blur`,
-`slide-left`, `slide-right`, `slide-up`, `slide-down`, `spin` and `twist`, plus the text-only
-`appear-word`, `appear-character` and `scramble`.

package/plugin/skills/video-editing/references/workflows.md

@@ -1,41 +0,0 @@
-# Project commands and sync
-
-## Mutation models
-
-| Project         | Behavior                                                              |
-| --------------- | --------------------------------------------------------------------- |
-| Script-owned    | `build edit.jsx` creates/replaces its timeline                        |
-| Existing/shared | Fresh `read`/`inspect` plus bounded `do` or `ops` changes             |
-| Canonical       | Host-provided connection, ordered transactions and actor-scoped undo  |
-| Legacy linked   | File pull/push; concurrent whole-file writes can overwrite each other |
-
-```bash
-higgsedit read PROJECT
-higgsedit inspect PROJECT --id CLIP_ID --at 6.5
-higgsedit do PROJECT --list
-higgsedit do PROJECT trim --clipId CLIP_ID --start 1 --end 4
-higgsedit ops PROJECT patch.json
-```
-
-`trim` changes edges in place without moving other clips; its start/end are
-absolute scene seconds. `inspect --at` uses whole-project timeline seconds and
-requires an ID or unambiguous name. Evaluated effects are not execution proof.
-IDs/array paths can change after rebuilds; ops paths require current document state.
-
-Other verbs include `place`, `insert_ripple`, `remove_ripple`, `broll`, `duck`,
-`remove_silences`, and component placement/update. The installed `--list` and
-per-verb `--help` provide parameters.
-
-## Components and connections
-
-`components build` compiles local modules; `component.place`, `component.patch`
-and `component.update` operate on instances. [Component clocks](assembly.md).
-
-Legacy `sync link|unlink|push|pull|clone|status|archive` manages file-backed sharing.
-Canonical `sync attach` and `sync new-canonical` use supplied connection config;
-legacy clone/link is not a substitute for canonical credentials.
-
-The OpenAI tool surface has no editable-project publishing service. Local project
-files are not hosted editor URLs. Canonical sync needs an explicitly supplied
-connection; the skill does not supply credentials. Whole-script rebuild still
-replaces the timeline.