greenlight-motion 0.1.1 → 0.1.3

package/dist/script-inputs.json

@@ -29,6 +29,7 @@
   "frontend/src/motionEngine/sceneScriptBundle.js",
   "frontend/src/motionEngine/sceneScriptGuide.js",
   "frontend/src/motionEngine/template.js",
-  "frontend/src/utils/cssGradient.js"
+  "frontend/src/utils/cssGradient.js",
+  "skills/greenlight-dash/references/video-design.md"
  ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "greenlight-motion",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "GreenLight Motion Engine: AI agents make motion-design videos (3D, camera, effects, transitions, text animation, particles, motion blur) with the GreenLight Dash Video Editor's own engine, in the user's browser.",
   "keywords": [
     "video",

package/skill/SKILL.md

@@ -18,7 +18,7 @@ You never write UI or animation code. If something is not in the format, it is n
 ## Setup (once per machine)
 
 ```
-npx greenlight-motion@0.1.1 doctor
+npx greenlight-motion@0.1.3 doctor
 ```
 
 It checks Node 18+, Chrome or Edge, WebGPU and H.264 encoding, and prints a fix for anything missing. Do not install
@@ -32,7 +32,7 @@ animation presets (the same converter the GreenLight Motion connector uses in Cl
 keyframes rarely look as good. The format, the design rules and the catalogues: `skill/references/scene-script.md`.
 
 ```
-npx greenlight-motion@0.1.1 script <folder> --from scenes.json   # or write <folder>/script.json, then: script <folder>
+npx greenlight-motion@0.1.3 script <folder> --from scenes.json   # or write <folder>/script.json, then: script <folder>
 ```
 
 Then `check` and `stills` (below), fix the SCRIPT and run `script` again — it rewrites `project.json`. For what a
@@ -41,14 +41,14 @@ workflow below and stop running `script` (it refuses to overwrite a project edit
 
 ## Workflow
 
-1. `npx greenlight-motion@0.1.1 init <folder>` — starts from a working example (title, subtitle, accent line, four
+1. `npx greenlight-motion@0.1.3 init <folder>` — starts from a working example (title, subtitle, accent line, four
    options). `--from file.json` starts from a project you have (for example one exported from GreenLight Dash).
 2. Edit `<folder>/project.json` — for changes to an EXISTING project prefer `apply` (below): it checks every edit and
    applies all or nothing. Put pictures, video, sound and fonts in `<folder>/assets/` and refer to them as
    `"asset:<file>"` (e.g. `"url": "asset:product.png"`).
-3. `npx greenlight-motion@0.1.1 check <folder>` — fix everything it lists (missing files, template mistakes, blank
+3. `npx greenlight-motion@0.1.3 check <folder>` — fix everything it lists (missing files, template mistakes, blank
    frames, page errors). `--json` for machine output.
-4. `npx greenlight-motion@0.1.1 stills <folder>` — renders frames and **a labelled contact sheet**. Open and look at
+4. `npx greenlight-motion@0.1.3 stills <folder>` — renders frames and **a labelled contact sheet**. Open and look at
    it before you go on: layout, readability, timing. Fix and repeat. `--at 0.5,1.2,3` for exact times.
 5. Hand it over: tell the user to open `<folder>/index.html` (Chrome or Edge), or `pack` it into one file, or
    `render` the MP4 yourself (`--fps 60 --motion-blur` for fast motion).
@@ -111,9 +111,9 @@ editor's own normalizer), so write only what you mean.
 - Not here: MotionFast templates (`mediaType: "motion"`) live only in GreenLight Dash — build the look from layers.
 
 Full references (generated from the editor's own docs; ignore the `/api/` routes they mention):
-`skill/references/` — scene-script, video-projects, video-text, video-text-kinetic, video-text-presets, video-shapes, video-keyframes,
+`skill/references/` — video-design, scene-script, video-projects, video-text, video-text-kinetic, video-text-presets, video-shapes, video-keyframes,
 video-camera, video-3d, video-effects, video-transitions, video-particles, video-paths, video-backgrounds, video-grid.
-Machine-readable lists: `npx greenlight-motion@0.1.1 schema effects | transitions | easings | paths | expressions`.
+Machine-readable lists: `npx greenlight-motion@0.1.3 schema effects | transitions | easings | paths | expressions`.
 
 ## Template
 
@@ -160,7 +160,7 @@ an absolute moment; `align` `sync` (default) / `start` / `end`; `offset` seconds
 
 The library is 77 hand-picked sounds in categories (whooshes and swooshes, transitions, clicks, pop-ups and
 notifications, data blips, typing and writing, foley, bubbles, impacts and bass drops, camera, gears, voice clips).
-`npx greenlight-motion@0.1.1 schema sounds` lists every one with its `category`, `use` (what it is for), `duration`
+`npx greenlight-motion@0.1.3 schema sounds` lists every one with its `category`, `use` (what it is for), `duration`
 and `sync`. Pick by `category` and `use`, then by name.
 
 - **Where the files come from:** the GreenLight sound CDN. `build` downloads each sound a cue uses into
@@ -176,7 +176,7 @@ The page has **Notes**: the user marks what should change right on the frame (a
 and writes a note for each mark. Every note carries the moment (seconds and frame), the mark in composition pixels
 and the layers under it (item ids in project.json), so you change exactly that and nothing else.
 
-- **They review on this computer:** run `npx greenlight-motion@0.1.1 review <folder>` and give them the URL it prints
+- **They review on this computer:** run `npx greenlight-motion@0.1.3 review <folder>` and give them the URL it prints
   (it keeps running; `--open` opens their browser, only when they ask). Their notes land in `<folder>/review/`: read
   `review/NOTES.md`, look at the `at-<t>s.png` pictures (the marks are numbered), make the changes (`apply`), `build`
   again and tell them to reload the page.
@@ -205,11 +205,11 @@ that fails (`plugin`); look at `stills` for the look. A package that carries its
 
 The same project opens in GreenLight Dash (the desktop editor this engine comes from) for full editing: the page's
 edit note offers **Open in GreenLight Dash** (it imports the folder as a new project on the open board; a page with
-changes saves a `.glvideo`). `npx greenlight-motion@0.1.1 pack <folder> --glvideo` writes that file yourself: ONE
+changes saves a `.glvideo`). `npx greenlight-motion@0.1.3 pack <folder> --glvideo` writes that file yourself: ONE
 `.glvideo` (the project + its files) that opens in GreenLight Dash on a double-click, or dropped on its board. Hand it
 over when the user wants to keep editing in the app. A
 GreenLight Dash project comes the other way through the app's **Export for agents** — a ready folder like the one
-`init` makes, with the options the author ticked. `npx greenlight-motion@0.1.1 init <folder> --from <its project.json>`
+`init` makes, with the options the author ticked. `npx greenlight-motion@0.1.3 init <folder> --from <its project.json>`
 starts from one too. Never tell the user they must install it: the page plays, changes options and renders on its own.
 
 ## Files
@@ -238,13 +238,6 @@ When the user has not named one, choose from these first. Each still has to suit
 
 ## Motion design that looks made, not generated
 
-- **Timing.** Entrances 0.4–0.8 s, exits faster than entrances. Stagger related elements by 0.06–0.12 s. Give the eye
-  a held moment (≥ 1 s) on anything the viewer must read: about 3 words per second.
-- **Easing by intent.** Entrances: `AE Out` or `Expo Out` (fast start, soft landing). Camera and big moves: `AE Smooth`. A layer that passes through (in, glide, out): `Smooth Glide` with the `glide` ƒx Soft on that track, keys ±100 % → ∓150 % with the last key at 80 % (the Glide presets; see video-keyframes.md).
-  Playful arrivals: `Back Out` or `Overshoot`. Exits: `Ease In`. `Linear` only for constant motion (tickers, rotation).
-  The full list with the real curves: `schema easings`.
-- **One focal move at a time.** If everything moves, nothing reads. Secondary elements move less and later.
-- **Hierarchy through size and weight**, not colour alone; keep text inside the safe area (|panX|, |panY| ≤ 40).
-- **Camera** moves are slow and small unless they are the point. Fast motion at 60 fps with motion blur.
-- **Review the contact sheet** every round: blank frames, collisions, unreadable text, and anything off-frame are
-  your bugs to fix before the user sees them.
+Read `skill/references/video-design.md` before the first version and check every version against it: one idea per
+scene, words on screen, hierarchy, timing, easing by intent, text animation picks, transitions, camera, sound and what
+to look for in the contact sheet. It is the same text GreenLight Dash's agents and the chat connector use.

package/skill/references/scene-script.md

@@ -58,15 +58,8 @@ works too (it has to stay reachable). SVG you write: `{ "type": "image", "svg":
 
 ## What makes it look made, not generated
 
-- **One idea per scene**, 3–6 scenes, 2–3 s each; at most ~8 words on screen at once, held ≥ 1 s (people read ~3 words a second).
-- **Hierarchy**: one headline per scene; supporting text much smaller; one accent colour; strong contrast.
-- **Timing**: stagger related elements 0.06–0.12 s; one focal move at a time — supporting elements move less and later; exits faster than entrances.
-- **Text animation** moves words or letters, never whole lines (the presets do this). Keep one family per video; use calm presets (glide-text,
-  classic-fade-up, classic-rise-mask) for long lines, punchy ones (swing-pop, whip, letter-vortex) for 1–3 words. glide-continuous and
-  glide-soft-stop never let the text rest: only when the user asks for drifting text.
-- **Transitions**: vary two or three kinds across the video; the camera stays subtle.
-- **Sound**: auto is a good base; add `data-1` / `selection-data-click` for UI-like pops, `cinematic-transition-13` for a big reveal.
-- **9:16**: bigger text, stacked vertically, everything in the middle 80 %.
+references/video-design.md — the same design rules GreenLight Dash's agents and the chat connector use. Read it before
+the first version and check every version against it.
 
 ## Catalogues
 

package/skill/references/video-design.md

@@ -0,0 +1,65 @@
+# Motion design that looks made, not generated
+
+What makes a video read as designed rather than generated. The rules hold however the video is built — a project
+through the app's API, `project.json` with the engine's CLI, or a scene script — so read them before the first version
+and check every version against them.
+
+## Story and words
+
+- **One idea per scene**: 3–6 scenes of 2–3 s for a short video. A scene that says two things says neither.
+- **At most ~8 words on screen at once, held at least 1 s.** People read about 3 words a second; text that leaves
+  before it is read is noise.
+- **9:16**: bigger text, stacked vertically, everything in the middle 80 %.
+
+## Hierarchy
+
+- One headline per scene; supporting text much smaller. Hierarchy comes from size and weight, not colour alone.
+- One accent colour and strong contrast.
+- Keep text inside the middle 80 % of the frame (in a project: |panX| and |panY| ≤ 40): players and feeds crop the
+  edges.
+
+## Timing
+
+- Stagger related elements by 0.06–0.12 s.
+- **One focal move at a time.** If everything moves, nothing reads: supporting elements move less and later.
+- Shapes and pictures enter in 0.4–0.8 s; exits are faster than entrances.
+- A text animation takes at least 0.8–1 s over the whole line, first unit in to last unit settled, unless the video
+  needs snap (a beat hit, a glitch flick): faster text flashes past before it is read. The arithmetic per kind of
+  animation: video-projects.md, Text animation pace.
+
+## Easing by intent
+
+- Entrances: `AE Out` or `Expo Out` (fast start, soft landing). Camera and big moves: `AE Smooth`.
+- A layer that passes through (in, glide, out): `Smooth Glide` with the `glide` expression — the Glide keyframe
+  presets build it (video-keyframes.md).
+- Playful arrivals: `Back Out` or `Overshoot`. Exits: `Ease In`.
+- `Linear` only for constant motion: tickers, rotation, progress along a path.
+
+## Text animation
+
+- Animate words or letters, never a whole line at once — the text presets do this.
+- One family per video. Calm presets for lines and captions: Glide Text (`glide-text`), Classic Fade Up
+  (`classic-fade-up`), Classic Rise (Mask) (`classic-rise-mask`); Focus Type (`focus-type`) for a title.
+- Punchy presets that tilt or overshoot — Swing Pop (`swing-pop`), Whip (`whip`), Letter Vortex (`letter-vortex`) —
+  only on 1–3 words when the video wants energy. On a longer caption they read cheap.
+- Glide Continuous (`glide-continuous`) and Glide Soft Stop (`glide-soft-stop`) never let the text rest: use them
+  only when the user asks for drifting text.
+- On a coloured card, pick a preset without a colour band (Classic Rise (Mask), Classic Fade Up): a band's colour can
+  clash with the card.
+
+## Transitions and camera
+
+- Vary two or three kinds of transition across a video: one kind everywhere looks like a template, a new one at
+  every cut looks random.
+- Camera moves are slow and small unless they are the point. Fast motion looks best at 60 fps with motion blur.
+
+## Sound
+
+- A soft whoosh on each transition and on the first headline is a good base. `data-1` or `selection-data-click` for
+  UI-like pops, `cinematic-transition-13` for one big reveal.
+
+## What to check in every version
+
+Look at real frames across the video (a contact sheet) before the user sees it — the JSON doesn't show these:
+blank or empty frames, overlapping or cut-off text, text too small or gone too fast, nothing moving or everything
+moving at once, weak hierarchy, clashing colours. Fix them and look again; two rounds are usually enough.

package/skill/references/video-projects.md

@@ -351,35 +351,49 @@ POST   /api/video-presets/import?board_id={board_id}   # multipart `file` = a pr
 
 ### GreenLight Motion pages (Export for agents)
 
-A project can leave the app as a **GreenLight Motion Engine page**: a folder with `index.html` (plays the project in
-Chrome/Edge from a double-click, nothing to install: preview, read-only layer timeline, an options panel, Render MP4),
-`project.json` (the editor `data` above + `name`, `formatVersion: 1` and `template` — the options), and `assets/`
-(`assets/media/<rel>` = the board's `/media/<rel>` files under their original refs, `assets/hdr/`, `assets/models/`).
-In the app: Video Editor ▸ project chip ▸ **Export for agents**. Over the API:
+A project leaves the app through Video Editor ▸ project chip ▸ **Export for agents**, as ONE of:
+- **a `.glvideo` file** (the window's default, `format: "glvideo"`): the project in one file, for a Claude chat (drop it
+  on the GreenLight Motion connector's video page) or another GreenLight Dash (double-click). Layout below.
+- **a GreenLight Motion Engine page** (`format: "folder"`, the API's default): a folder with `index.html` (plays the
+  project in Chrome/Edge from a double-click, nothing to install: the studio — preview, layers, options, Notes,
+  Render MP4), `project.json` (the editor `data` above + `name`, `formatVersion: 1` and `template` — the options), and
+  `assets/` (`assets/media/<rel>` = the board's `/media/<rel>` files under their original refs, `assets/hdr/`,
+  `assets/models/`). For an agent on this computer that works on `project.json`.
+
+Over the API:
 
 ```
 GET  /api/moodboards/{board_id}/video-projects/{project_id}/light-report
      → { name, template | null, leftOut: [{ kind, reason, layers[] }], engine: bool, defaultDest }
 POST /api/moodboards/{board_id}/video-projects/{project_id}/export-light
      { "dest?": "/abs/parent/folder", "title?": "…", "template?": { "title", "fields": [ … ] },
-       "modelFiles?": { "<preset id>": "<the URL the app serves its .glb at>" }, "pack?": false }
-     → { folder, index, packed: { path, bytes } | null, files, bytes, missing, leftOut, fields }
+       "modelFiles?": { "<preset id>": "<the URL the app serves its .glb at>" }, "format?": "folder" | "glvideo",
+       "pack?": false, "smaller?": false, "progressId?": "<8–64 of A-Z a-z 0-9 ->" }
+     → folder:  { folder, index, packed: { path, bytes } | null, files, bytes, missing, leftOut, fields, smaller }
+     → glvideo: { format: "glvideo", glvideo: "<dest>/<title>.glvideo", folder: <dest>, bytes, files, missing, leftOut, fields, smaller }
+GET  /api/video-projects/export-light/progress/{progressId}
+     → { phase: waiting | files | page | done, done, total, file, converting }   (a .glvideo has no `page` phase)
 POST /api/moodboards/{board_id}/video-projects/import-light
      { "path": "/abs/folder | …/index.html | a one-file page.html | a .glvideo file", "activate?": true }
      → the new project (like POST video-projects) + { copied }
-GET  /api/moodboards/{board_id}/video-projects/{project_id}/glvideo
-     → <name>.glvideo (answers once the whole file is written)
+GET  /api/moodboards/{board_id}/video-projects/{project_id}/glvideo?models=<JSON { "<preset id>": "<the URL the app serves its .glb at>" }>
+     → <name>.glvideo (answers once the whole file is written; `models` as in export-light's modelFiles — without it the
+       3D device presets are left out)
 ```
 
 - A `.glvideo` is the same project folder in one stored zip: `glvideo.json` (`{format: "glvideo", version: 1, title}`),
-  `project.json`, `assets/media/<rel>` and `assets/hdr/`. It is the file to hand a project to another GreenLight Dash:
-  `import-light` with its path opens it there as a new project.
+  `project.json`, `assets/media/<rel>`, `assets/hdr/` and `assets/models/` (the 3D device presets the project uses). It
+  is the file to hand a project to another GreenLight Dash (`import-light` with its path opens it there as a new
+  project) or to a chat: the GreenLight Motion connector's `open_video` page reads it in the user's browser, and
+  `get_video` / `edit_video` change it there.
 
 - `template.fields[]` = `{ key, label, type: text|color|image|number|select|toggle, targets: [{ itemId | clipId | (neither = project), path }] }`
   — e.g. `{ "key": "headline", "label": "Headline", "type": "text", "targets": [{ "itemId": "<item id>", "path": "textContent" }] }`,
   a shape colour `path: "shapeFillColor"`, the background `{ "path": "background.solidColor" }`. Omit `template` to keep
-  the project's saved one; `pack: true` also writes one self-contained `.html` next to the folder (for a Claude
-  artifact: keep it under 16 MB).
+  the project's saved one; `pack: true` (folder only) also writes one self-contained `.html` next to the folder (for a
+  Claude artifact: keep it under 16 MB). `smaller: true` puts WAV sounds in as MP3 and PNG pictures as WebP (transparency
+  kept) and points the exported project at them — the board keeps its originals; `smaller` in the answer is
+  `{ sounds, pictures, before, after }`. A name already taken gets a number: `<title> 2.glvideo`, `<title> 2/`.
 - The template is kept beside the project (`<board folder>/.motion/<project id>.template.json`), not in its `data`.
 - `import-light` copies every file into the board (`motion-<title>/`), except a `/media/` file this machine already
   has byte for byte; the template comes back too. It is what the page's **Open in GreenLight Dash** button does