flomotion 0.0.0-stage → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,37 @@
+# Changelog
+
+## Phase 2: MCP server, sound, voice, review, skill (unreleased)
+
+- `@codecut/mcp`: 30 tools and 4 resources over stdio (`codecut 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 `@codecut/*` 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 CodeCut 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,57 @@
-# Temporary Holding Version
+# flomotion (CodeCut)
 
-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.
+The npm package is **`flomotion`**. The tool is called CodeCut and its command is `codecut` (`flomotion` works as an alias).
+
+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.2).** The engine, the MCP server and the `motion-studio` skill 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 `@codecut/*` 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
+mkdir my-video && cd my-video
+claude mcp add codecut -e FREESOUND_API_KEY=… -- npx -y flomotion mcp --dir .
+npx -y flomotion skill install        # copies the motion-studio skill to .claude/skills
+claude                              # describe the video you want
+```
+
+The skill runs a gated workflow: intake, script, look, voice, storyboard, build, sound, review, 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 asks you to listen and approve.
+
+## CLI
+
+```bash
+codecut mcp --dir .             # MCP server over stdio (30 tools, 4 resources)
+codecut skill install [--global]
+codecut init my-video           # scaffold a project
+codecut fonts sync my-video     # download and lock fonts (the only network use besides sound/voice tools)
+codecut lint my-video
+codecut render my-video         # -> my-video/renders/<id>.mp4 (+ .credits.txt, .licenses.json)
+codecut frame my-video 2.5      # one PNG
+codecut sheet my-video          # contact sheet
+codecut docs                    # reference docs for every component, from the schemas
+```
+
+A project is `project.tsx` exporting a `<Composition>`; components are imported from `@codecut/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.