flomotion 0.2.0 → 0.4.0

package/skills/motion-studio/looks/minimal.json

@@ -1,91 +0,0 @@
-{
-  "id": "minimal",
-  "name": "Minimal",
-  "description": "Calm and precise. DM Sans, soft neutrals, slow eases, dissolves.",
-  "palette": {
-    "bg": "#f6f5f2",
-    "fg": "#14141a",
-    "primary": "#2f5bff",
-    "accent": "#14141a",
-    "surface": "#ffffff",
-    "muted": "#7a7a86"
-  },
-  "background": "#f6f5f2",
-  "fonts": [
-    {
-      "id": "display",
-      "family": "DM Sans",
-      "source": "google",
-      "weights": [500, 700],
-      "variable": true,
-      "axes": {
-        "wght": [300, 700]
-      },
-      "subsets": ["latin"]
-    },
-    {
-      "id": "body",
-      "family": "DM Sans",
-      "source": "google",
-      "weights": [400, 500],
-      "variable": true,
-      "axes": {
-        "wght": [300, 700]
-      },
-      "subsets": ["latin"]
-    },
-    {
-      "id": "mono",
-      "family": "IBM Plex Mono",
-      "source": "google",
-      "weights": [400],
-      "subsets": ["latin"]
-    }
-  ],
-  "type": {
-    "display": {
-      "font": "display",
-      "size": 88,
-      "weight": 600,
-      "tracking": -20,
-      "leading": 1.06
-    },
-    "body": {
-      "font": "body",
-      "size": 40,
-      "weight": 400,
-      "tracking": 0,
-      "leading": 1.4
-    },
-    "mono": {
-      "font": "mono",
-      "size": 32,
-      "weight": 400,
-      "tracking": 0,
-      "leading": 1.5
-    },
-    "numerals": {
-      "font": "display",
-      "size": 150,
-      "weight": 600,
-      "tracking": -25,
-      "leading": 1
-    }
-  },
-  "easing": {
-    "in": "power3.out",
-    "out": "power3.in",
-    "pop": "back.out(1.2)",
-    "settle": "sine.inOut",
-    "spring": "spring(120,22)"
-  },
-  "transition": {
-    "type": "dissolve",
-    "duration": 0.6
-  },
-  "grain": 0,
-  "sound": {
-    "ui/pop": "freesound:soft-pop",
-    "ui/tick": "freesound:tick"
-  }
-}

package/skills/motion-studio/looks/sketch.json

@@ -1,83 +0,0 @@
-{
-  "id": "sketch",
-  "name": "Sketch",
-  "description": "Hand-drawn and playful. Permanent Marker display, paper colours, bouncy eases, wipes.",
-  "palette": {
-    "bg": "#fbf4e4",
-    "fg": "#2a2420",
-    "primary": "#e8452c",
-    "accent": "#2d7dd2",
-    "surface": "#fffaf0",
-    "muted": "#8c7f70"
-  },
-  "background": "#fbf4e4",
-  "fonts": [
-    {
-      "id": "display",
-      "family": "Permanent Marker",
-      "source": "google",
-      "weights": [400],
-      "subsets": ["latin"]
-    },
-    {
-      "id": "body",
-      "family": "Patrick Hand",
-      "source": "google",
-      "weights": [400],
-      "subsets": ["latin"]
-    },
-    {
-      "id": "mono",
-      "family": "Space Mono",
-      "source": "google",
-      "weights": [400],
-      "subsets": ["latin"]
-    }
-  ],
-  "type": {
-    "display": {
-      "font": "display",
-      "size": 96,
-      "weight": 400,
-      "tracking": 0,
-      "leading": 1.05
-    },
-    "body": {
-      "font": "body",
-      "size": 48,
-      "weight": 400,
-      "tracking": 0,
-      "leading": 1.25
-    },
-    "mono": {
-      "font": "mono",
-      "size": 32,
-      "weight": 400,
-      "tracking": 0,
-      "leading": 1.5
-    },
-    "numerals": {
-      "font": "display",
-      "size": 150,
-      "weight": 400,
-      "tracking": 0,
-      "leading": 1
-    }
-  },
-  "easing": {
-    "in": "back.out(2)",
-    "out": "back.in(1.4)",
-    "pop": "elastic.out(1,0.5)",
-    "settle": "power2.out",
-    "spring": "spring(150,12)"
-  },
-  "transition": {
-    "type": "wipe",
-    "duration": 0.45
-  },
-  "grain": 0.18,
-  "sound": {
-    "ui/pop": "freesound:pop",
-    "move/whip": "freesound:whoosh"
-  }
-}

package/skills/motion-studio/references/motion.md

@@ -1,73 +0,0 @@
-# Motion
-
-Rules first, then patterns with the exact CodeCut props. Everything is a pure function of time, so a render repeats exactly.
-
-## Rules
-
-1. **Never linear motion.** Every move has an ease. `keyframe_set` takes it as the third value: `[0.4, 1, "expo.out"]`. A key's ease is the curve used to arrive at that key.
-2. **Fast in, slow settle.** Entrances use `expo.out` or `power3.out` (most of the distance in the first third). Exits are shorter than entrances and use `expo.in` or `power2.in`.
-3. **A slight overshoot for pops.** `back.out(1.8)` for things that land, `back.out(1.2)` for calm Looks. Do not overshoot text you need to read at the end.
-4. **Stagger 0.05 to 0.1 s.** Lists, letters and cards enter one after another. Under 0.04 s reads as one blob; over 0.15 s feels slow. Use `<Stagger each={0.08}>` around the children, or `SplitText` for text.
-5. **Overlap actions.** The next move starts before the last one has settled (about 60 to 70 % through). Nothing waits for everything else to stop.
-6. **A slow constant push on the camera.** Put a scale key on the Scene: `scale={[[0, 1], [3, 1.06]]}` over the scene's length. This also keeps the frame from ever being still (review check 4).
-7. **Parallax between depth layers.** Background moves 0.3 to 0.5 times as far as the foreground over the same time. Give them different `position` keys.
-8. **Sound on every landing.** Each impact effect has a `sound` tag; `sound_auto` places it. Check 10 in the review fails without it.
-9. **One idea per beat.** One hero move per scene; the rest supports it.
-10. **Hold the end state briefly** (0.3 to 0.5 s) before the next thing so the eye can read.
-
-## Durations
-
-| What             | Seconds                                                       |
-| ---------------- | ------------------------------------------------------------- |
-| Pop / small UI   | 0.25 to 0.4                                                   |
-| Title enter      | 0.5 to 0.7                                                    |
-| Scene transition | 0.3 (flash, cut) to 0.6 (dissolve)                            |
-| Counter          | 0.8 to 1.4                                                    |
-| Hold for reading | about 0.25 s per word on screen, minimum 1.2 s for a headline |
-
-## Patterns
-
-Entrance of a headline (props, no effect element needed):
-
-```tsx
-<Title
-  id="t1"
-  text="Ship videos as code"
-  size={118}
-  enter={{ from: "sw", distance: 120, ease: "expo.out", duration: 0.6 }}
-/>
-```
-
-A landing with weight (impact effect as a child of the layer):
-
-```tsx
-<Title id="t1" text="Boom" enter={{ from: "n", distance: 300, ease: "expo.in", duration: 0.25 }}>
-  <Shake id="t1-shake" amp={10} freq={14} decay={5} start="0.25s" />
-</Title>
-```
-
-`Shake`, `Thud`, `Slam`, `PunchZoom`, `Hitstop`, `Glitch`, `RGBSplit`, `Pulse`, `Wobble`, `SquashStretch` are impact effects. `start` is relative to the parent layer. Each has a default `sound` tag; set `sound=""` only when you want it silent on purpose.
-
-Staggered cards:
-
-```tsx
-<Stagger id="cards" each={0.08}>
-  <Card id="c1" enter={{ from: "s", distance: 80, ease: "expo.out" }} />
-  <Card id="c2" enter={{ from: "s", distance: 80, ease: "expo.out" }} />
-  <Card id="c3" enter={{ from: "s", distance: 80, ease: "expo.out" }} />
-</Stagger>
-```
-
-Text by word: `<SplitText id="h" text="Make it move" preset="rise" />`. Presets: rise, typewriter, wave, scramble, slam, blur-in, mask-reveal, weight-pulse, tracking-in, counter. Use `rise` or `mask-reveal` for headlines, `typewriter` for code and quotes, `slam` only once per film.
-
-Camera push on a scene: `scale={[[0, 1], [3, 1.06]]}` (the key times are relative to the Scene).
-
-Cut on a beat: end a scene on a hit and start the next on the following frame; use the Look's transition for a change of idea and a hard cut for the same idea.
-
-## What to avoid
-
-- Linear ease on anything that moves.
-- Everything entering at once.
-- Shake on every element (it stops meaning "hit"). Use it for the main impact of a scene.
-- Long fades on text the viewer must read quickly.
-- Randomness from code. Use `ctx.noise(seed, freq)` in expressions; the linter rejects `Math.random`, `Date.now` and timers.

package/skills/motion-studio/references/review.md

@@ -1,32 +0,0 @@
-# Review checklist (17 points)
-
-`review` decides what it can from the compiled project, the mix and (unless `deep:false`) a rendered-page measurement. Items marked "eyes" always need you to look at the contact sheet in a second, separate pass. Fix failures, call `review` again, at most three rounds, then show the user what still fails.
-
-| #   | Check                                                                      | How it is decided                                                   | Typical fix                                                                     |
-| --- | -------------------------------------------------------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
-| 1   | Frame 0 has motion                                                         | Something is already changing within 0.1 s                          | Start an enter or a slow push at 0 s                                            |
-| 2   | A hero element carries across 4+ beats                                     | A layer spans 4 scenes; else eyes                                   | Move the hero onto its own track, or repeat it with the same look in every beat |
-| 3   | Something new at least every 2 s                                           | A layer appears or a move starts at least every 2 s                 | Add an element, a cut or a new move in the gap named                            |
-| 4   | No static frame longer than 0.5 s                                          | Nothing on screen changes for more than 0.5 s                       | Slow push, drift, pulse or stagger                                              |
-| 5   | Every spoken word on screen is in sync with the voice                      | Captions follow the voice; other words: eyes                        | `align_to_voice`                                                                |
-| 6   | Numbers shown add up                                                       | Lists the numbers; you add them up                                  | Fix the number or the script                                                    |
-| 7   | No overlapping or clipped text                                             | Measured in the rendered page at several times; eyes if skipped     | Shorten, shrink, or move                                                        |
-| 8   | All text inside the SafeArea for the format                                | Lint rule `text-outside-safe-area`                                  | Put it inside `<SafeArea preset=…>`                                             |
-| 9   | Contrast of text against its background passes                             | Lint plus measured contrast                                         | Lighter or darker colour; a card or scrim behind text                           |
-| 10  | Every impact effect has a sound on its frame                               | Impact cues against sfx events (0.1 s)                              | `sound_auto`                                                                    |
-| 11  | Voice is always on top in the mix                                          | Music ducks 6 dB or more; gains compared                            | Lower music/sfx gain, raise `duckAmount`                                        |
-| 12  | Loudness within target                                                     | Measured integrated LUFS within 1.5 of -14, peak under -1 dBTP      | Adjust gains                                                                    |
-| 13  | Transitions are used with intent                                           | More than two types warns; always eyes                              | One signature transition, hard cuts elsewhere                                   |
-| 14  | Looks and type are consistent with the chosen Look                         | Theme set, font count; eyes                                         | Use `$brand.*` and `$type.*`                                                    |
-| 15  | Captions readable (line length, reading speed)                             | Line length at most 32 characters, at most 21 characters per second | Lower `maxChars`/`maxWords`, longer `hold`                                      |
-| 16  | All assets have ledger entries (downloaded ones; your own files need none) | Ledger lookup                                                       | Fetch with `sound_get` / `font_get`                                             |
-| 17  | CC-BY credits are present in the license report                            | Attribution entries have an author and become `credits.txt`         | Re-fetch with `sound_get`                                                       |
-
-## The second pass
-
-Open the contact sheet image. For each check marked manual or needs-eyes, write one sentence saying what you see and whether it passes. Be specific ("the logo on frames 1, 4, 7 and 10 is the same teal circle"). If you cannot tell from the image, say so and ask the user. Never write "looks good" without naming what you looked at.
-
-## Honest limits
-
-- Audio is measured, not heard. State levels and peak positions; ask the user to listen.
-- Taste is not measurable. The checklist catches mechanical problems; the user decides if it is good.

package/skills/motion-studio/references/saas-promo.md

@@ -1,29 +0,0 @@
-# The six-beat SaaS promo (30 s, 9:16)
-
-`project_create` with `template: "saas-promo"` makes these six scenes, empty, at these times. Change the times only if the script needs it, and keep the total.
-
-| Beat        | Scene id   | Start | Length | Job                                                                          |
-| ----------- | ---------- | ----- | ------ | ---------------------------------------------------------------------------- |
-| 1. Hook     | `hook`     | 0 s   | 3 s    | Stop the scroll. One bold claim or question, in motion on frame 0.           |
-| 2. Problem  | `problem`  | 3 s   | 5 s    | Name the pain in the viewer's words. Show it, do not explain it.             |
-| 3. Reveal   | `reveal`   | 8 s   | 6 s    | The product arrives. The biggest move and the biggest sound of the film.     |
-| 4. Features | `features` | 14 s  | 9 s    | Three things, one at a time, each with proof on screen (UI, number, result). |
-| 5. Proof    | `proof`    | 23 s  | 4 s    | One number, one quote, or one logo row. Only what the user gave you.         |
-| 6. CTA      | `cta`      | 27 s  | 3 s    | One action, one URL or button. Hold it.                                      |
-
-## Rules for each beat
-
-- **Hook:** the first frame already moves (review check 1). Text is large (96 px or more on 1080 wide), at most 7 words, inside the safe area. The hero element introduced here should come back in later beats (check 2).
-- **Problem:** two short lines at most. Contrast with the hook: slower, or a colour shift. Something new on screen at least every 2 s (check 3).
-- **Reveal:** use the Look's signature transition into this scene. A `Slam` or `PunchZoom` on the product name, with a `hit/boom` or `hit/land` sound.
-- **Features:** a stagger of 0.08 s. Counters use `<Counter over="1s" />` with tabular figures. Show the product through `UIMock` with `Cursor` clicks rather than describing it.
-- **Proof:** do not invent numbers. If the user gave none, make this a "what you get" beat with a checklist, and tell them why.
-- **CTA:** the action in the user's words, a `Pulse` on the button, quiet music tail. Hold the final state for 1 s or more.
-
-## Timing against the script
-
-About 2.5 spoken words per second: 30 s holds about 75 words. Write the script first (step 2), record or generate the voice (step 4), then adjust scene lengths to the real voice and use `align_to_voice` to start the on-screen words with the spoken ones.
-
-## Captions
-
-For vertical video use `<Captions voice="#vo" captionStyle="karaoke" maxChars={22} maxWords={4} />` near the lower third, inside the safe area, 64 px or more, heavy weight, a contrasting active colour. See `typography.md`.

package/skills/motion-studio/references/sound.md

@@ -1,47 +0,0 @@
-# Sound
-
-You cannot hear. You choose sounds from their tag, description, measured duration and measured peak, and then you ask the user to listen.
-
-## Tags (what each is for)
-
-| Tag                | Job                         | Typical length |
-| ------------------ | --------------------------- | -------------- |
-| `ui/pop`           | A small element appears     | 0.03 to 0.8 s  |
-| `ui/tap`           | A tap or press              | 0.02 to 0.6 s  |
-| `ui/tick`          | A counter step, a tiny tick | 0.01 to 0.4 s  |
-| `move/whip`        | A fast move or whip pan     | 0.1 to 1.2 s   |
-| `move/whoosh-deep` | A big slow move             | 0.4 to 2.5 s   |
-| `hit/land`         | A heavy element lands       | 0.1 to 1.5 s   |
-| `hit/punch`        | A sharp hit                 | 0.05 to 1 s    |
-| `hit/boom`         | A big boom for a reveal     | 0.5 to 4 s     |
-| `tech/click`       | A UI click                  | 0.01 to 0.5 s  |
-| `tech/data`        | Data or numbers appear      | 0.1 to 2 s     |
-| `tech/glass`       | A bright glassy accent      | 0.2 to 2.5 s   |
-| `tech/success`     | A success moment            | 0.3 to 2.5 s   |
-| `tech/glitch`      | A glitch or error           | 0.1 to 1.5 s   |
-
-`sound_search` with `tag` adds good search words and the length range. Add your own `query` words for flavour ("wooden", "soft").
-
-## Workflow
-
-1. `sound_auto` (dry run) lists impact effects with no sound on their frame.
-2. Apply it, or `sound_search` and `sound_get` by hand. `sound_get` downloads, measures the loudest moment (`peak`), and writes the ledger. Pass `tag` so the peak gets the job's name (`hit/land` gives `peak="land"`).
-3. Place with `<Sound id src="freesound:123" at="0.6s" peak="land" gain={-6} />`. `at` is where the peak must land; the clip starts early by the measured peak offset. Review check 10 allows 0.1 s.
-4. `mix_preview`. Read `peakLandsAt` for each sound and the measured loudness.
-5. Tell the user which sounds you picked (name, author, licence, description) and ask them to listen.
-
-## Levels
-
-- Voice is on top. Music is set 10 to 14 dB below the voice and ducks another 12 dB (`duckAmount`) while the voice speaks.
-- SFX sit 3 to 9 dB below the voice, except the one main hit per scene.
-- The master is normalised to -14 LUFS for social. Check 12 passes within 1.5 LU.
-- Do not stack more than two loud sounds on one frame.
-
-## Licensing
-
-- Default allowed: CC0 and CC-BY. CC-BY needs credit: `render` writes `<name>.credits.txt`; tell the user to paste it into the post or description.
-- NonCommercial and other licences are refused with `license_blocked`. Pick another sound.
-- To restrict to CC0 only, set `"soundLicenses": ["CC0"]` in `codecut.json`.
-- With only a Freesound API key the downloaded file is the HQ MP3 preview (original files need OAuth). The ledger entry says so.
-- Without `FREESOUND_API_KEY`, list your own licensed files in `sounds/catalog.json` and `sound_search` uses them.
-- Your own files (recordings, tracks you licensed) need no ledger entry, but the rights are yours to confirm.

package/skills/motion-studio/references/typography.md

@@ -1,50 +0,0 @@
-# Typography
-
-You cannot judge taste from an image, but you can check legibility and mechanical problems. Propose, show the frame, and let the user choose.
-
-## The rules
-
-1. **One display face and one body face.** Get contrast from weight and width, not from a third family. The linter warns above 3 families (display, body, mono at most).
-2. **Hierarchy by size, weight and colour, in that order.** Three levels per screen: headline, support line, small print. If everything is bold, nothing is.
-3. **Sizes for a 1080 px wide frame** (scale for other widths): headline 96 to 140 px, support 44 to 56 px, small print 34 px minimum (the linter rejects text under about 28 px), captions 60 to 72 px. Landscape 1920 px wide: scale by 1.3 to 1.5.
-4. **Tabular figures for anything that counts.** `<Counter>` does this for you. For other numbers set `features={["tnum"]}` so the width does not jitter. Use lining figures (`"lnum"`) next to caps.
-5. **Track all-caps.** Add 40 to 100 (thousandths of an em) to `tracking` for `case="upper"`. Tighten large display text by -15 to -30.
-6. **Line length.** Headlines at most 3 lines, 4 to 7 words total. Body at most 40 characters per line on mobile. Break by meaning (`maxWidth` as a percentage, not hard breaks).
-7. **Safe areas.** Keep text inside `<SafeArea preset="reels">` (also `shorts`, `tiktok`, `feed`). The platform UI covers the top, the bottom and the right edge. Review check 8 fails otherwise.
-8. **Leading.** 1.0 to 1.1 for display, 1.25 to 1.4 for body. Do not use the default 1.15 for big headlines.
-9. **Contrast.** At least 3:1 for large text, 4.5:1 for small. Put text on a card or scrim, not on a busy picture.
-10. **Check the glyphs.** `font_check` before you write text in another script (Devanagari, Arabic, Thai, CJK). The lint rule `missing-glyph` rejects characters the face cannot draw and lists them. Add a face that covers that script instead of letting it fall back.
-
-## Captions
-
-- At most 22 to 28 characters per line on 9:16, 2 lines maximum, 1 to 4 words per page (`maxChars`, `maxWords`).
-- Reading speed at most 21 characters per second (review check 15). Fast speech: fewer words per page, not smaller text.
-- Weight 700 to 900, 64 px or more, a dark outline or card behind it, active word in the Look's accent colour (`captionStyle="karaoke"`), or scaled (`"pop"`). Use `"word"` for hype, `"line"` for calm explainers.
-- Lower third, inside the safe area, never over the face or the product.
-- Export with the project: `.srt`/`.vtt` come from the same word timings.
-
-## The Looks
-
-Use the Look's type tokens through `font="$type.display"` and `$brand.*` colours. Do not hard-code families.
-
-| Look    | Display                                                    | Body             | Mono               | Scale (display / body / numerals) | Feel                       |
-| ------- | ---------------------------------------------------------- | ---------------- | ------------------ | --------------------------------- | -------------------------- |
-| kinetic | Space Grotesk 700 (variable wght 300 to 700), tracking -25 | Inter 400/600    | JetBrains Mono 500 | 104 / 44 / 160 px                 | Loud, fast, hard contrast  |
-| minimal | DM Sans 600 (variable), tracking -20                       | DM Sans 400/500  | IBM Plex Mono 400  | 88 / 40 / 150 px                  | Calm, precise, lots of air |
-| sketch  | Permanent Marker 400                                       | Patrick Hand 400 | Space Mono 400     | 96 / 48 / 150 px                  | Hand-drawn, playful        |
-
-Pairing logic: a characterful display face with a neutral body face. Do not pair two characterful faces. Variable fonts let you animate weight (`axes={{ wght: [[0, 300], [0.6, 700, "expo.out"]] }}`) for emphasis instead of switching families.
-
-## Using `font_preview`
-
-1. `font_get` the face so it is on disk and locked.
-2. `font_preview` with `fontId`, a line of the **real** text from the script, and a size near the real one (for example 96).
-3. Open the PNG. Check: are the letters distinct (I, l, 1; O, 0), do the numerals look right, does the weight read at phone size, do accents and special characters render?
-4. Show the user the preview and the alternatives; say what you checked and what you cannot judge (personality, brand fit). Ask them to choose.
-
-## Mechanics worth knowing
-
-- Fonts are declared in `<Fonts>`; `font_get` adds the declaration and downloads the files once. Renders never use the network, and a changed or missing font file fails the render naming the font id.
-- Google Fonts are licensed individually (mostly OFL). The ledger records each; `font_list` shows them.
-- Variable axes (`wght`, `wdth`, `slnt`, `opsz`) are animatable props on text. Keep weight changes smooth and small (a 200 to 300 swing), they are for emphasis.
-- Numerals in big counters: use the Look's `$type.numerals` token.