flomotion 0.0.0-stage → 0.4.0

package/CHANGELOG.md

@@ -0,0 +1,93 @@
+# Changelog
+
+## Fixes and examples (unreleased)
+
+- **Audio mix is deterministic again.** With voice and music together, two renders of the same project could differ
+  in the last samples (`sidechaincompress` paired frames in thread order). The ducking chain now uses fixed frame
+  sizes; a regression test mixes the same project 8 times and fails without the fix.
+- **`examples/flomotion-ad`:** a 30 s vertical ad for flomotion, built with the studio skill (real live-view captures,
+  its own licence ledger on screen). See its `LOG.md` for what was and was not verified.
+
+## Rename: CodeCut is now flomotion everywhere
+
+- The product, packages (`@flomotion/*`), command (`flomotion`), project folder (`.flomotion/`), config file
+  (`flomotion.json`) and element ids (`fm_`) all use the name flomotion. The old `codecut` command and `@codecut/*`
+  imports are gone. Projects made before the rename: move `.codecut/` to `.flomotion/`, change the imports, and replace `.codecut/` with
+  `.flomotion/` inside `.flomotion/fonts.lock.json` and `.flomotion/ledger.json`
+  (`sed -i '' 's#\.codecut/#.flomotion/#g' .flomotion/*.json`).
+
+## 0.4.0: setup, your own material, and assets (unreleased)
+
+- **`flomotion setup`:** a guided setup (also `setup show | check | set | unset | sounds`, and `--yes`). You choose
+  how you supply the voiceover, the word timings, the sound effects and the graphics (your own recording,
+  transcript, sound files, logos and screenshots, or Freesound, ElevenLabs, Whisper, Pexels), and enter the keys that
+  go with it. Each key is checked with its real service (read-only) and saved only on your computer (`~/.config/
+flomotion/config.json`, mode 0600). It can also install the skill and add flomotion to Claude Code.
+- **Your own material:** `voice_import`, `transcript_import` (SRT, VTT, word-level JSON, lines with times, or plain
+  text, with an honest precision: word, cue, estimated), `sound_import`, a searchable library of your own sound
+  folder, and `asset_import`. Files may be anywhere on your computer; credentials and key folders are never read.
+- **Assets:** `asset_search` and `asset_get` for icons, emoji, brand logos (trademark: needs permission), photos and
+  illustrations (Iconify, Openverse, Pexels); `asset_capture` for sharp screenshots of your own product;
+  `brand_extract` for your site's colours, fonts and logos. Licences are classified, share-alike and
+  non-commercial refused, CC-BY credited, everything in the ledger; `lint` and the licence report cover images.
+- `setup_status` tool: the agent checks what exists before it plans, and tells you what is missing.
+- ElevenLabs quotes show your account's remaining characters. The server identifies itself as `flomotion` 0.4.0.
+- Skill: `flomotion-studio` 0.4.0 (Round 0 of the interview, `assets.md`, asset plan at G4, own material).
+- Tested: every tool, the wizard (scripted and piped), the key checks against local servers, Iconify and Openverse
+  for real, screenshots and brand extraction against a local site.
+- Not verified: Freesound, ElevenLabs and Pexels with real keys, Whisper, and the hidden key prompt on a real terminal.
+
+## 0.3.0: the flomotion-studio skill, install command and live view (unreleased)
+
+- **Skill:** `skills/flomotion-studio` (the main director skill: extensive interview, gates G0 to G6, looks, scene
+  blocks, checks, copywriting, sound and motion rules) replaces the earlier motion-studio skill. Reconciled with the
+  real tools: `references/mcp-tools.md` lists the 30 tools and error codes, `references/checks.md` says which checks
+  `review` computes and which the agent computes or cannot run, `references/block-recipes.md` has the 13 core blocks
+  as TSX (linted and rendered in all three looks by the tests), `references/components.md` is generated.
+- **Looks:** `clean-light`, `dark-product`, `bold-kinetic` exist in the engine (`theme="$look.clean-light"`),
+  matching the skill's JSON (a test keeps them in sync). The engine's `kinetic`, `minimal`, `sketch` stay for the
+  examples.
+- **Install:** `flomotion install skill` copies the skill to `~/.claude/skills` (or `--project`), replacing a previous
+  copy and noting an old `motion-studio` skill. `flomotion skill install` from 0.2.0 still works.
+- **Live view:** `flomotion ui` and `flomotion mcp --ui`: activity feed of every tool call, gate progress,
+  outline and timeline, a scrubbable preview rendered on demand, code with the latest change highlighted, review
+  results, assets with licences, renders, and history with Restore. Localhost only, no network.
+- The MCP server logs every call to `.flomotion/activity.jsonl`; `review` writes `.flomotion/review/last.json`;
+  the server identifies itself as `flomotion`.
+- Fixed: bin paths written `./dist/bin.mjs` were stripped by npm 11 at publish.
+
+## Phase 2: MCP server, sound, voice, review, skill (unreleased)
+
+- `@flomotion/mcp`: 30 tools and 4 resources over stdio (`flomotion mcp`), same patches as the edit ops, applied to the
+  TSX with ts-morph (formatting and comments kept, expressions refused, every write re-read and verified, history
+  snapshots with undo tokens). Typed errors with fix hints.
+- Freesound client (token auth, tag search, CC0/CC-BY filter, measured peak, ledger, credits file) with a local
+  catalogue fallback; voice providers (recording, local TTS stub, ElevenLabs quote then `confirm:true`);
+  transcription via whisper.cpp; `align_to_voice`; `sound_auto` for impact cues.
+- Review: 17-point checklist from the compiled animation, lint, ledger, measured mix and the rendered page.
+- `render` presets with credits and licence report; `mix_preview` with measured loudness.
+- `skills/motion-studio`: gated workflow, references (motion, sound, typography, saas-promo, review, generated
+  components), three Looks as data with a finished reference scene each, a finished example.
+- CLI: `mcp`, `skill install`; `render` writes credits and a licence report. Bundle: multi-entry esbuild build with
+  hooks so a published install (npm package `flomotion`) resolves `@flomotion/*` imports and compiles project TSX with no node_modules.
+- Fixed: `RGBSplit` and `Glitch` showed their effect before their start time (baked span began at the jump).
+  `lint` compared `CC0-1.0` with `CC0`. A sound reused for two tags lost its first peak name.
+- Tests: codemods, every tool, review checks, resources, stdio, schema round trip through an MCP call, skill files,
+  Look scenes, and the Gate 2 flow against test doubles.
+
+## Phase 1: core engine (unreleased)
+
+- Schema system (`defineComponent`/`defineEffect`, 20+ control builders) generating TS types, Zod validators,
+  MCP JSON Schema, docs and lint rules from one declaration.
+- JSX runtime, resolver (themes, tokens, refs, timing, expressions), timeline IR, HyperFrames HTML compiler with
+  baked, seekable animation; 10 transitions (`shader` is a stub).
+- Keyframes (modes, handles, spatial paths, loops) and pure expressions with a purity linter.
+- 76 definitions: structure, transform stack, media, typography (variable axes, rich text, animators and presets),
+  shapes, masks/mattes, layout, UI mocks, impact effects with sound tags, ColorGrade/Curves/Grain, layer styles.
+- Fonts: local, Google (CSS API, licence from google/fonts METADATA.pb), Fontsource fallback, URL, system; hash lock,
+  ledger, Chrome-measured layout cache, pre-render font gate, glyph-coverage lint.
+- 24 timeline edit operations and 16 keyframe operations as pure patch producers with undo.
+- Offline FFmpeg audio mixer (buses, sidechain ducking, loudnorm), deterministic.
+- CLI: `init lint render frame sheet fonts sync docs`.
+- Examples: `saas-promo`, `typography`. Tests: unit, compiler snapshots, goldens (perceptual hash), double render,
+  schema round trip, fonts, glyph lint, e2e.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 flomotion contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,66 @@
-# Temporary Holding Version
+# flomotion
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A code-first video editor. A video is one TSX file; every control a normal editor has is a typed prop or
+function. Claude edits it through an MCP server; rendering is done by
+[HyperFrames](https://github.com/heygen-com/hyperframes) (HTML + GSAP → headless Chrome + FFmpeg → MP4).
+
+> **Status: early (0.4).** The engine, the MCP server, the `flomotion-studio` skill and the live view are built and tested against
+> test doubles for Freesound, ElevenLabs and Whisper. Nothing has been run in a real Claude Code session yet:
+> see `docs/gate2-manual-checklist.md` in the repository. Editor type hints for project files are not shipped
+> yet (projects run; editors will not resolve `@flomotion/*` types).
+
+## Requirements
+
+Node 22+, **FFmpeg and ffprobe on PATH** (`brew install ffmpeg`), Google Chrome (or set `CHROME_PATH`).
+Optional: `whisper-cpp` for transcription (`brew install whisper-cpp`). Optional environment keys:
+`FREESOUND_API_KEY` (sound search and download), `GOOGLE_FONTS_API_KEY` (font search only),
+`ELEVENLABS_API_KEY` (generated voice; always quoted first, runs only with `confirm: true`).
+
+## Use it from Claude Code
+
+```bash
+npx -y flomotion install skill      # installs the flomotion-studio skill for all your projects (~/.claude/skills)
+mkdir my-video && cd my-video
+claude mcp add flomotion -e FREESOUND_API_KEY=… -- npx -y flomotion mcp --dir . --ui
+claude                              # describe the video you want
+```
+
+`flomotion install skill --project` installs into the current folder only. The skill runs a gated workflow:
+interview (extensive, with a read-back), direction, script, style frames, storyboard, draft, final. It stops for
+your OK at each gate. Sounds and fonts are fetched into a licence ledger; CC-BY credits are written next to the
+render. The agent cannot hear audio or judge taste, so it lists what you need to review.
+
+## Live view
+
+`--ui` on the MCP server (or `flomotion ui` in the project folder) serves a small page on `127.0.0.1:4317`. It shows,
+in real time: a **Storyboard** board where you and Claude brainstorm (`ideas.md`) and the plan (`storyboard.md`) shows as a timeline that turns green as scenes are built, each tool call Claude makes with its result, progress through the gates, the scene outline and
+timeline, a preview you can scrub (rendered on demand from the file on disk), the code with the latest change
+highlighted, review results, the sounds and fonts used with their licences, renders you can play, and the
+history with a Restore button. It is a viewer with undo and a notes board, not an editor yet. It listens on localhost only and loads
+nothing from the network.
+
+## CLI
+
+```bash
+flomotion mcp --dir . [--ui]      # MCP server over stdio (39 tools, 4 resources); --ui also serves the live view
+flomotion ui [--open]             # the live view for this folder
+flomotion install skill [--project]
+flomotion init my-video           # scaffold a project
+flomotion fonts sync my-video     # download and lock fonts (the only network use besides sound/voice tools)
+flomotion lint my-video
+flomotion render my-video         # -> my-video/renders/<id>.mp4 (+ .credits.txt, .licenses.json)
+flomotion frame my-video 2.5      # one PNG
+flomotion sheet my-video          # contact sheet
+flomotion docs                    # reference docs for every component, from the schemas
+```
+
+A project is `project.tsx` exporting a `<Composition>`; components are imported from `@flomotion/components`
+(or `flomotion/components`). Renders never use the network: fonts are locked by hash and checked before the first
+frame; a missing or changed font file fails the render with the font id and path.
+
+## Limits
+
+Some Later-tier options are typed stubs (`Precomp`, `Adjustment`, shader transitions, `.cube` LUTs, 3D text).
+Byte-identical renders are verified on one machine only. See `docs/later.md` in the repository.
+
+MIT licensed.