pixi-effects 0.27.2 → 0.28.1

package/skills/pixi-effects/reference/direction.md

@@ -0,0 +1,136 @@
+# Directing a film (for any AI that makes video with code)
+
+Read this before you write a composition for anything longer than a title card: a product film, a company introduction, a launch, a data story. It is about the decisions around the renderer, so it names no tool; `SKILL.md` has the pixi-effects commands.
+
+A one-line prompt makes the model fill every missing decision with its safest default: large text in the middle, a gradient behind it, everything fading in, the logo last. The fix is not a cleverer prompt. It is to remove the missing decisions before anything is drawn, and to judge what was drawn with evidence.
+
+## The five layers (do not collapse them into one step)
+
+| Layer | The question | Where the answer lives |
+|---|---|---|
+| Director | What is the film trying to say, to whom? | `brief.md` |
+| Reference | What should it look and feel like? | `style-guide.md` |
+| Timeline | What changes at each beat, and why? | `shotlist.md` |
+| Renderer | How is every frame produced? | `src/` (seekable code) |
+| Critic | What failed, exactly where, and why? | `reviews/` |
+
+## Keep the decisions in files, not in the chat
+
+A film whose only record is a conversation is a lucky session. Put the decisions where the next run can read them:
+
+```
+film/
+  brief.md        the one-sentence goal, the audience, the product facts, the real assets
+  style-guide.md  palette, type, motion rules, banned defaults
+  shotlist.md     beats, states, timestamps, purpose
+  assets/         approved logos, photos, screens, footage, sound
+  src/            the composition and its code
+  reviews/        contact sheets and defect notes
+  out/            exports
+```
+
+The next film swaps the brief and the assets and keeps the rest. A run that stops can resume from the last file it finished and say which one is missing; "the last command exited 0" is never the definition of done.
+
+## brief.md: facts about the product, choices about the film
+
+Separate what is true (it comes from the product) from what is chosen (it comes from you). The model may invent a camera move or a stronger opening. It may not invent a dashboard, a figure, a logo or a client.
+
+```
+FILM
+One sentence: what the viewer should remember
+Audience:     who it is for
+Duration:     seconds
+Formats:      ask the human; one format unless they name more (see "Formats" below)
+
+ASSETS (paths; everything on screen comes from here)
+Logo · photos · screens · copy and numbers · brand type and colours · sound reference
+
+VISUAL RULES
+Keep:   traits taken from the reference
+Avoid:  the clichés you will not use
+Never:  invent a product screen, a metric, a claim or a logo
+
+DELIVERABLES
+Final video, poster frame, contact sheets, source, an asset list, a note on what a human still has to check
+```
+
+**Collect the assets first, list them, and read the list before building.** If the brief needs an asset that is missing, stop and ask. A convincing fake (a drawn logo, an invented dashboard, a guessed number) is the one failure that cannot be repaired afterwards. Words and numbers on screen are the source's own; take colours and type from the source itself (a site's CSS, a brand sheet), never from an adjective such as "premium".
+
+## style-guide.md: a visual grammar written down
+
+Without one the model supplies its own, which is why unrelated one-prompt films look related. Give it a frame, a film or the real site, and make it write what it saw:
+
+```
+REFERENCE ANALYSIS
+Palette:      the actual colours (hex), not an adjective
+Typography:   family, weight, scale
+Composition:  where the eye goes first
+Pacing:       average time between meaningful changes
+Motion:       snap, glide, overshoot, cut or hold
+Texture:      grain, paper, glass, flat
+DO NOT COPY:  the reference's subjects, logos, copy or product imagery
+```
+
+The result is a style guide, not a collage of borrowed shots. Add a **motion rule per class of object**, because "motion with weight" is the difference between decoration and direction: small controls snap, large panels settle, the camera is almost invisible, headlines enter strongly and then hold long enough to read, one playful object is allowed to overshoot. If everything overshoots, nothing feels precise. After each move ask: does the viewer know where to look?
+
+## shotlist.md: states and beats, not effects
+
+"Zoom in, then morph, then add particles" lists activity. A plan says what the viewer knows at each moment:
+
+```
+00-02  HOOK     one image that earns attention
+02-05  PROBLEM  the friction, shown, not described in a paragraph
+05-09  REVEAL   the product enters through a real interaction
+09-13  PROOF    one screen or number that demonstrates the claim
+13-16  CLOSE    a clean final state and a readable call to action
+```
+
+Each row has an entry state, an exit state and a reason to exist. For a UI film write the state list first (SEARCH → RESULT → DETAIL → ACTION → CONFIRMATION) so one component can change size, colour and content while staying recognisably the same object. The shot list is a contract: a shot nobody can justify is cut.
+
+## Seekable and deterministic, or it cannot be reviewed
+
+Frame 240 must render directly, without replaying frames 0 to 239: no hidden clock, no unseeded randomness, nothing that only works after eight seconds of running. Think of a frame as a query: `frame = render(time, shotlist, assets, style, seed)`. Then a revision is local (change one time value, one curve, one asset) and a reviewed frame stays reviewed. Two renders of the same moment must give the same pixels; check it.
+
+## Sound is on the same timeline
+
+Many AI films look finished with the sound off; then the click lands after the button, the cut misses the beat, the logo arrives before the music resolves. Write a beat grid and drive picture and sound from it: choose a tempo whose bar is a round number of seconds, put every cut on a bar line and every cue on the beat it belongs to. With a licensed or original track, measure its beats and cut against them. Test: close your eyes and listen; if the film has no shape without the picture, the sound is not finished.
+
+## Review the rendered frames, not your intent
+
+Do not start by watching a full export ten times, and do not describe what you meant to make. Ask the renderer for a contact sheet: one frame at every beat, a short strip around the fastest transitions, and a frame from the middle of each cut taken from the exported file. Look cold, then write the **three largest defects**, each with a **timestamp**, the **evidence** (what you see) and a **local fix**; patch only those, render those frames again. Ask for a second pair of eyes on the sheet whenever one is available: the author reads their own intent into it.
+
+```
+[ ] text readable at phone size (about 34 px or more on a 1080p frame)
+[ ] nothing in the outer 5 % of the frame
+[ ] real assets only, none redrawn or invented
+[ ] one type and colour system across scenes
+[ ] no awkward half-transition frame
+[ ] cuts and sound cues land together
+[ ] the first two seconds are a real hook
+[ ] the last frame works as a poster
+```
+
+"The agent made a video" stops when the file exists. "The agent directed a video" stops when the evidence says the film works.
+
+## Formats
+
+A 16:9 film and a 9:16 cut are different compositions: the vertical one needs larger type, fewer things at once, another layout, sometimes a tighter story. Never crop the middle of the wide one. **Do not make a format nobody asked for:** ask which formats are wanted, make one if the answer is "whatever", and offer the others. When more than one is wanted, keep the same assets, timeline and states, define the layout per format, and look at a contact sheet of each: an export is correct because the composition survived the format, not because the encoder finished.
+
+## Gates, and what to do when no human is there
+
+Long runs need places to stop. With a human present:
+
+1. approve the references and the asset list
+2. approve the style guide and the shot list
+3. look at representative stills
+4. look at a rough cut and its contact sheet
+5. repair the three highest-impact defects
+6. check sound, formats and deliverables
+
+Between gates the agent may work for hours; it never makes an irreversible brand decision (logo, claim, number) for the human, and a missing real asset is a blocker, not an invitation to invent one. If the reference is unclear, the right output is a question or one small test frame, not nine hundred polished wrong ones. With nobody to ask, record each decision you took as a "ruling" in the review notes, with what it costs if wrong, and finish with a short note of what still needs a human.
+
+## The loop
+
+PROMPT → CLIP is a demo. BRIEF → SYSTEM → FILM → REVIEW → BETTER SYSTEM is a studio: every stage leaves evidence the next one can use, and the tenth film can be better than the first.
+
+*The shape of this guide follows a published breakdown of building a code-rendered video studio around an AI model ("Motion Engineering", @0xwhrrari, September 2026); the wording and the checklist are rewritten for this library's users.*

package/skills/pixi-effects/reference/pitfalls.md

@@ -127,3 +127,6 @@ A good habit that catches most of these: after `init`, read `window.__logs` (see
 97. **A deck inside your own composition loses its `transitions` and `stops`** unless you take them across: `const d = deck({ width: 1920, height: 1080, pages })`, then `{ type: 'composition', sequences: d.composition.sequences, transitions: d.composition.transitions }`. Pass `width` / `height` yourself for a page that is not the movie's own size.
 98. **A matte layer needs a fill.** A named matte (`mask: 'glass'`) that is a shape with no `fillColor` / `fillGradient` (or a text with no fill) cuts everything away and nothing warns: the layers it should show simply vanish. Give the matte a fill (white for `alpha`, a gradient for `luma`).
 99. **In a `music` score a capital letter is a chord and a lowercase one a note.** `G7` is G dominant seventh, `C5` a power chord, `C6` a sixth chord; `g7`, `c5`, `c6` are notes (octave 7 is a very high note: it used to be what `G7` meant, silently). A bare note in capitals (`Bb2`) is refused with the lowercase spelling (`bb2`); inside brackets (`[C4 E4 G4]`) any case is a note. An unknown chord kind suggests the nearest (`Cmin7` → `Cm7`, `Csus` → `Csus4`, `CM7` → `Cmaj7`).
+100. **Read the score back before you trust it.** `check` prints a `music` block: every track's length in bars (a track that ends early or has a short bar is named), the names that start in each bar with their beat (`Am(2)` starts on beat 2; no mark = the downbeat; the first four names of a bar are shown, `musicEvents()` lists everything), and the drum span. Count bars by the read-back, not by hand: a bar of 3 beats in a score with no `meter` is shown as bars of 4, so set `meter: 3` for a waltz. Drums repeat by themselves and `from` / `to` are beats; `swing` only moves notes that start off the beat, so a comp on beats 2 and 4 stays straight.
+101. **A film built from one adjective looks like every other one.** Read `reference/direction.md` and write `brief.md` / `style-guide.md` / `shotlist.md` first: real assets with paths, the one sentence to remember, a row per beat with entry and exit state. If a real asset is missing, ask: a drawn fake (a logo, a dashboard, a figure) is the failure that matters. Judge the contact sheet cold: three defects, each with a timestamp, evidence and a local fix.
+102. **A vertical cut is a second composition, not a crop, and only when someone asked for it.** One source, a layout function, `?f=9x16`; `check` and `render` take `--query f=9x16` (recipe `two-formats`). Look at a contact sheet of each format: type that fits wide is tiny tall. Ask which formats are wanted; make one if the answer is open. In a 1080p film keep every line of text at 34 px or more; if you cannot read it in a sheet tile, a phone cannot.

package/skills/pixi-effects/reference/recipes.md

@@ -1103,6 +1103,31 @@ return [
 ];
 ```
 
+## One source, two formats (16:9 and 9:16), and a photo inside a region
+
+Only when a vertical cut is wanted (ask first). It is not a crop of the wide one: write each scene as a function of a layout, switch with a query (`?f=9x16`), and render each format on its own: `npx pixi-effects check film.html --query f=9x16`, `npx pixi-effects render film.html --query f=9x16 -o film-9x16.mp4`. `photo()` fits a picture into any rectangle like CSS `cover` (scale from the image's own size, a mask for the rectangle); `scale: 'cover'` only fits the PARENT.
+
+```js
+// @docs-only two-formats
+const PORTRAIT = new URLSearchParams(location.search).get('f') === '9x16';
+const W = PORTRAIT ? 1080 : 1920, H = PORTRAIT ? 1920 : 1080, MX = PORTRAIT ? 76 : 150;      // margins: nothing important in the outer 5 %
+const IMG = { hero: [1920, 1280] };                                                           // each photo's size (assets: [{ name: 'hero', src: '...' }])
+const photo = (key, x, y, w, h, duration) => {
+  const cover = Math.max(w / IMG[key][0], h / IMG[key][1]);
+  return { type: 'image', asset: key, duration,
+    mask: { type: 'shape', shape: 'rect', width: w, height: h, initial: { x: x + w / 2, y: y + h / 2, fillColor: '#fff' } },     // the mask lives in the parent's coordinates
+    initial: { x: x + w / 2, y: y + h / 2, anchorX: 0.5, anchorY: 0.5, scale: cover },                                             // image anchors go in `initial`
+    keyframes: [{ at: 0, to: { scale: cover * 1.1 }, duration, ease: 'sine.inOut' }] };                                             // a slow push
+};
+const scene = { type: 'composition', name: 'hook', at: 0, duration: 5.5, width: W, height: H, sequences: [
+  photo('hero', 0, 0, W, H, 5.5),
+  { type: 'text', text: 'Headline', initial: { x: MX, y: PORTRAIT ? 1150 : 620 }, style: { fontSize: PORTRAIT ? 100 : 112, fill: '#fff' } },   // wide: lower left; tall: lower third
+] };
+// movie.init({ width: W, height: H, composition: { sequences: [scene] } })
+```
+
+---
+
 ## A batch of videos from a table (one video per row)
 
 A batch of videos is a loop outside the video. The page reads what changes from its address (`new URLSearchParams(location.search)`), and `pixi-effects-render --query "name=Aiko&score=92"` opens it with those values. Names with spaces or non-Latin letters must be URL-encoded (`jq -sRr @uri` as below, or `encodeURIComponent` in Node). Each video starts its own browser, so N videos cost N start-ups: try one with `--draft` (half size, fast), then render the real ones. To make the pieces of one row differ in more than text, use the same values to pick colours or an image name.

package/skills/pixi-effects/template.html

@@ -4,7 +4,7 @@
   <meta charset="UTF-8" />
   <meta name="viewport" content="width=device-width, initial-scale=1" />
   <title>pixi-effects video</title>
-  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/pixi-effects@0.27.2/dist/loader.css" />   <!-- the loader: HTML + CSS only, so it is on screen at once and keeps moving while the page builds the video -->
+  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/pixi-effects@0.28.1/dist/loader.css" />   <!-- the loader: HTML + CSS only, so it is on screen at once and keeps moving while the page builds the video -->
   <style>
     body { background: #0d1220; margin: 0; padding: 16px; }
     .stage { position: relative; width: min(960px, 100%); }                 /* the player and the loader both sit inside this box */
@@ -37,16 +37,16 @@
     "imports": {
       "pixi.js":                 "https://esm.sh/pixi.js@8.22.0?bundle-deps",
       "mediabunny":              "https://esm.sh/mediabunny",
-      "pixi-effects":            "https://cdn.jsdelivr.net/npm/pixi-effects@0.27.2/dist/index.js",
-      "pixi-effects/controller": "https://cdn.jsdelivr.net/npm/pixi-effects@0.27.2/dist/Controller.js",
-      "pixi-effects/presenter":  "https://cdn.jsdelivr.net/npm/pixi-effects@0.27.2/dist/Presenter.js",
-      "pixi-effects/three":      "https://cdn.jsdelivr.net/npm/pixi-effects@0.27.2/dist/three.js",
+      "pixi-effects":            "https://cdn.jsdelivr.net/npm/pixi-effects@0.28.1/dist/index.js",
+      "pixi-effects/controller": "https://cdn.jsdelivr.net/npm/pixi-effects@0.28.1/dist/Controller.js",
+      "pixi-effects/presenter":  "https://cdn.jsdelivr.net/npm/pixi-effects@0.28.1/dist/Presenter.js",
+      "pixi-effects/three":      "https://cdn.jsdelivr.net/npm/pixi-effects@0.28.1/dist/three.js",
       "pixi-filters":            "https://esm.sh/pixi-filters@6.1.5?external=pixi.js",
       "three":                   "https://esm.sh/three@0.178.0"
     }
   }
   </script>
-  <link rel="modulepreload" href="https://cdn.jsdelivr.net/npm/pixi-effects@0.27.2/dist/index.js" />   <!-- after the import map: the library downloads while the page is parsed -->
+  <link rel="modulepreload" href="https://cdn.jsdelivr.net/npm/pixi-effects@0.28.1/dist/index.js" />   <!-- after the import map: the library downloads while the page is parsed -->
 
   <script type="module">
     import { Movie, kenBurns, withFade } from 'pixi-effects';

package/dist/Composition-DRCTWIYH.cjs

@@ -1,16 +0,0 @@
-'use strict';
-
-var chunkC7HJJ7MZ_cjs = require('./chunk-C7HJJ7MZ.cjs');
-require('./chunk-YOV6MEXH.cjs');
-require('./chunk-P4GY3Z4G.cjs');
-require('./chunk-ZMAD3KJU.cjs');
-require('./chunk-TWZNOUM7.cjs');
-
-
-
-Object.defineProperty(exports, "CompositionSequence", {
-  enumerable: true,
-  get: function () { return chunkC7HJJ7MZ_cjs.CompositionSequence; }
-});
-//# sourceMappingURL=Composition-DRCTWIYH.cjs.map
-//# sourceMappingURL=Composition-DRCTWIYH.cjs.map

package/dist/Composition-TZHVYIGH.js

@@ -1,7 +0,0 @@
-export { CompositionSequence } from './chunk-K3F2YKL4.js';
-import './chunk-BQNNZEAX.js';
-import './chunk-TYWFKCPY.js';
-import './chunk-45QKLD6M.js';
-import './chunk-BXOCEZ4U.js';
-//# sourceMappingURL=Composition-TZHVYIGH.js.map
-//# sourceMappingURL=Composition-TZHVYIGH.js.map