openfilm 0.0.1 → 0.1.0

package/LICENSE

@@ -0,0 +1,55 @@
+Apache License
+
+Version 2.0, January 2004
+
+http://www.apache.org/licenses/ 
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+"License" shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document.
+
+"Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License.
+
+"Legal Entity" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity.
+
+"You" (or "Your") shall mean an individual or Legal Entity exercising permissions granted by this License.
+
+"Source" form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files.
+
+"Object" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types.
+
+"Work" shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work (an example is provided in the Appendix below).
+
+"Derivative Works" shall mean any work, whether in Source or Object form, that is based on (or derived from) the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this License, Derivative Works shall not include works that remain separable from, or merely link (or bind by name) to the interfaces of, the Work and Derivative Works thereof.
+
+"Contribution" shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, that is intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner. For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the Licensor for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by the copyright owner as "Not a Contribution."
+
+"Contributor" shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of their Contribution(s) with the Work to which such Contribution(s) was submitted. If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions:
+
+You must give any other recipients of the Work or Derivative Works a copy of this License; and
+
+You must cause any modified files to carry prominent notices stating that You changed the files; and
+
+You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and
+
+If the Work includes a "NOTICE" text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at least one of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License. You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS

package/README.md

@@ -1,7 +1,111 @@
-# OpenFilm
+<h1 align="center">OpenFilm</h1>
 
-Make any video. Change anything.
+<p align="center"><b>The open source AI video agent.</b><br>
+Turns your Codex, Claude Code or any coding agent into a video agent, and gives you an editor to change anything it makes.</p>
 
-A film is a web page that draws any moment of itself. OpenFilm gives coding agents one command to make films, and gives people an editor to change them.
+<p align="center">
+  <a href="#make-a-film">Make a film</a> ·
+  <a href="#fork-a-film">Fork a film</a> ·
+  <a href="#how-it-works">How it works</a> ·
+  <a href="SPEC.md">Spec</a> ·
+  <a href="templates/MANUAL.md">Manual</a>
+</p>
 
-Coming soon at [openfilm.dev](https://openfilm.dev).
+Videos made with agents end up as MP4s you can watch but not change, or in repos that each invent their own
+architecture. Either way, reusing one means rebuilding it. OpenFilm is one format every agent can read and change:
+a film is a web page that can draw any moment of itself, plus a `film.json` that cuts pages, footage and sound
+together.
+
+## Make a film
+
+Give your agent the skill:
+
+```sh
+npx skills add openfilm/openfilm
+```
+
+Then ask for a video:
+
+> Make a 20-second launch video for my CLI, with music and sound effects. Check your work and render the MP4.
+
+The agent runs `openfilm open`, which makes the project and opens it in OpenFilm Studio so you watch the film take
+shape and can change anything in it. It writes the pages, runs `openfilm look` after every change to see what it made,
+and renders the MP4 beside `film.json`.
+
+Needs Node 22 or later and ffmpeg. The first run downloads a headless Chromium (about 100 MB). Studio, the editor,
+comes with the package and runs on your machine.
+
+## Fork a film
+
+A film is a folder. Copy one, open it in your agent and say what to change:
+
+```sh
+cp -r examples/edit my-launch && cd my-launch
+```
+
+> Turn this into a launch video for Tally, a CLI that shows what each pull request adds to your cloud bill. Keep the
+> structure, pacing and sound.
+
+| Example | What it shows |
+| --- | --- |
+| [`examples/orbit`](examples/orbit) | One page: a WebGL scene (three.js) and a title, with its own sound |
+| [`examples/edit`](examples/edit) | Footage with a slow-motion stretch, a title page used twice with a person's edit, and music |
+| [`examples/compose`](examples/compose) | Two films by different agents cut into one: a picture-in-picture, a crossfade, and a person's edit to the other film's title |
+
+## How it works
+
+```js
+window.film = {
+  duration: 20, width: 1920, height: 1080,
+  ready: loadFonts(),                 // a Promise: fonts, images, models, data
+  frame(t) { /* draw the complete picture at t seconds, with anything */ },
+  audio: [{ src: 'music.wav' }, { src: 'sfx/hit.wav', at: 7.5, volume: 0.8 }],
+};
+```
+
+**The one rule:** the same `t` always draws the same picture, whatever was drawn before. Frames are requested out of
+order, in parallel and between frames (for motion blur), so any page that keeps the rule renders exactly, at any
+size, on any machine. There is nothing else to learn: no timing attributes, no adapters, no components. Use three.js,
+p5, GSAP, SVG, shaders or plain DOM.
+
+```sh
+openfilm open             # start or open the project; Studio shows it, live as the agent saves
+openfilm look   [t | a-b] # the agent's eyes: a contact sheet with the sound mix, one frame, or a range
+openfilm render [a-b]     # the MP4; --4k, --blur (motion blur), --alpha (.webm / .mov)
+openfilm get    <what>    # voice-over, music, sound effects, images and video: an OpenFilm account or your keys
+```
+
+`look` is what lets an agent finish without you. It draws the frames of its sheet twice, in two shuffled orders, and
+names any frame whose picture depended on a clock, unseeded randomness or what came before. It also reports page
+errors, failed requests, fonts that did not load, missing sounds and clipping.
+
+`film.json` is the edit: tracks of clips with `at`, `time`, `speed`, `fade`, `volume` and `transform`. A clip is
+footage, a still, a sound, or another film, so any film can become a shot in someone else's. `overrides` hold a
+person's changes to elements of a page (a CSS selector with position, scale, rotation, style or text), and agents
+keep them when they edit.
+
+`openfilm` with no arguments prints [the manual](templates/MANUAL.md), the whole of what an agent needs to know.
+[SPEC.md](SPEC.md) is for anyone building a player, renderer or editor.
+
+## Why no framework
+
+Frontier models have read more HTML, CSS and WebGL than any video framework can teach them. Given plain web code and
+one rule, they already make films as good as a framework's. A framework's rules then stop helping and start costing:
+tokens to read, conventions to keep, a runtime every copy depends on. OpenFilm keeps only the rule that makes
+rendering exact, and spends its effort where models really fail: checking the film and rendering it.
+
+## Media
+
+Media can come from anywhere: a service you already use (your agent reads its API docs and uses your key), your own
+code, or `openfilm get`, which makes voice-over, music, sound effects, images and video with an OpenFilm account or
+your own key for a service it knows. Creating never needs an account.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+The format, the CLI and Studio are [Apache-2.0](LICENSE). The OpenFilm name and logo are trademarks: see
+[TRADEMARK.md](TRADEMARK.md). The hosted service behind `openfilm get` and the OpenFilm desktop app are provided by the
+OpenFilm project and are not part of this repository.

package/SPEC.md

@@ -0,0 +1,176 @@
+# OpenFilm Protocol 0.1 (draft)
+
+A film is a web page that can draw any moment of itself.
+
+That is the whole idea. A page that exposes one object, `window.film`, can be previewed, scrubbed, checked,
+rendered to video, cut into a timeline and edited by any host that speaks this protocol. The page may be written
+with any library or none: three.js, p5, Canvas 2D, WebGL, GSAP, SVG, plain DOM. The protocol says nothing about
+how a page draws, only how a host asks it to.
+
+The key words MUST, SHOULD and MAY are used as in RFC 2119.
+
+## 1. The page
+
+```js
+window.film = {
+  duration: 12,                 // seconds, finite, > 0
+  width: 1920, height: 1080,    // the frame, in CSS pixels
+  fps: 30,                      // optional: the rate the film was designed for
+  ready: loadEverything(),      // optional: a Promise, or a function returning one
+  frame(t, info) { draw(t) },   // draw the picture at t seconds; may return a Promise
+  audio: [{ src: 'song.mp3' }], // optional: sound the host mixes under the picture
+};
+```
+
+| Field | Type | Meaning |
+| --- | --- | --- |
+| `duration` | number | Length in seconds. |
+| `width`, `height` | number | Frame size in CSS pixels. The host sizes the viewport to it; higher resolutions use device pixel ratio. |
+| `fps` | number? | The frame rate the film was designed for. Hosts MAY render at any rate. |
+| `ready` | Promise \| () => Promise | Resolves when fonts, images, models and data are loaded. The host calls `frame` only after it settles. For web fonts, load each face used (`document.fonts.load('700 64px Fraunces')`), not only `document.fonts.ready`. |
+| `frame(t, info)` | function | Draw the complete picture for time `t`, `0 ≤ t < duration`. If it returns a Promise, the picture is complete when it resolves. |
+| `audio` | AudioClip[]? | Sound for the film (§4). |
+| `stateful` | boolean? | Set when `frame` cannot jump to an arbitrary `t` (§3). |
+| `reset()` | function? | With `stateful`: return to `t = 0`. |
+
+`info` is `{ final: boolean }`: `false` while a person is watching or scrubbing, `true` when the frame is going
+into an export. A page MAY draw cheaper while `final` is false. Nothing else may change between the two.
+
+A page SHOULD set `window.film` before its `load` event. Hosts wait for it to appear (for at least 10 seconds
+after `load`) before reporting the page as not a film.
+
+## 2. The one rule: a frame is a function of t
+
+For the same `t`, `frame` MUST produce the same picture, whatever was drawn before it and in whatever order frames
+are requested. Hosts rely on this to scrub, to render frames in parallel, to render fractions of a frame for motion
+blur, and to re-render one shot without the rest.
+
+In practice:
+
+- Read time from `t`. A host holds the page's clocks at `t` while it draws (§5), so `performance.now()`,
+  `requestAnimationFrame` timestamps, `Date`, CSS animations and `Math.random` agree with it; timers and history
+  do not.
+- Repaint everything each call. Do not accumulate (`x += v`) across calls; if something has history (a trail, a
+  physics run), compute it from `t`, or precompute it during `ready` and look it up.
+- Tweens that record their start values the first time they run (GSAP `to`, `from`) remember whatever was on screen
+  then, which depends on the order frames were drawn. Give every tween explicit start and end values (`fromTo`).
+- Any library that runs its own clock is driven by `t` instead: `timeline.seek(t)`, `animation.currentTime = t * 1000`,
+  `p5.redraw()`, `renderer.render(scene, camera)`, `video.currentTime = …` (awaiting `seeked`).
+
+Notes for authors:
+
+- `window.film` may be assigned from a module script (`<script type="module">`): modules run before `load`.
+- A WebGL canvas is captured after `frame` returns. Draw inside `frame` and create the context with
+  `preserveDrawingBuffer: true`, or the host may capture a cleared buffer.
+- Size everything from `width`/`height` in CSS pixels. Hosts raise resolution with device pixel ratio, so a canvas
+  should allocate `width × devicePixelRatio` pixels.
+- Repeating a frame is not always bit-identical in a browser (layers are re-rasterized as they change). Hosts compare
+  repeated frames with a tolerance, not byte for byte.
+
+## 3. Stateful films
+
+Some films cannot jump: an agent simulation, a feedback shader. Such a page sets `stateful: true` and MAY provide
+`reset()`. A host then only calls `frame` with increasing `t` after a `reset()` (or a reload) and reaches a later
+`t` by stepping through the frames before it. Stateful films cannot be rendered in parallel or with motion blur
+from fractions of a frame. Prefer computing state from `t`.
+
+## 4. Sound
+
+Pages do not play sound when a host is present (§5). They declare it:
+
+```js
+audio: [
+  { src: 'music/song.mp3' },                                   // whole file from t = 0
+  { src: 'vo/line-3.m4a', at: 4.2, volume: 0.9 },              // starts at 4.2 s
+  { src: 'sfx/hit.wav', at: 7.5, from: 0.1, to: 0.6 },         // a slice of the source
+]
+```
+
+`src` is resolved against the page URL. `at` is the start in film seconds (default 0); `from`/`to` trim the source
+in source seconds (default: whole file); `volume` is linear gain (default 1); `speed` is the playback rate (default
+1, pitch kept). The host mixes and encodes the sound;
+it never records it from the page.
+
+Timing that follows sound (beats, onsets, word timings) is data, not API: precompute it into files the page reads
+during `ready`. Hosts MAY provide tools that write such files.
+
+## 5. Hosts
+
+Before any page script runs, a host sets `window.filmHost = { version: '0.1', name }`. When it is present the page
+MUST NOT advance on its own (no self-running loop, no autoplay of media or sound). When it is absent the page is
+being opened as an ordinary web page and SHOULD play itself, so every film is also a page you can just open:
+
+```js
+if (!window.filmHost) {
+  const t0 = performance.now();
+  const loop = () => { film.frame(((performance.now() - t0) / 1000) % film.duration, { final: false }); requestAnimationFrame(loop); };
+  Promise.resolve(typeof film.ready === 'function' ? film.ready() : film.ready).then(loop);
+}
+```
+
+A host:
+
+- serves the page over HTTP (not `file://`), with the page's folder as the root;
+- sizes the viewport to `width × height` (times a device pixel ratio for higher resolutions);
+- awaits `ready`, then calls `frame(t, info)` and awaits its result before capturing the viewport;
+- MAY call `frame` concurrently in separate page instances, and at fractional frame times;
+- passes `final: true` only for frames that go into an export;
+- reports uncaught errors and failed requests from the page.
+
+From the first frame it draws, a host holds the page's clocks at the frame's `t`: `performance.now()` and
+`requestAnimationFrame` timestamps read `t` in milliseconds, `Date` reads `t` after the epoch 2026-01-01T00:00:00Z,
+CSS and Web Animations the page left running stand at `t` (a CSS transition, whose progress is history, is
+finished), and `Math.random` restarts from a seed of `t` (while loading it runs from a fixed seed). Before the first
+frame (`ready`, loading) the page runs on real time. The reference host's prelude is `FILM_CLOCK` in
+`src/host.mjs`: `filmHost.time(t)` before `frame(t)`, `filmHost.settle(t)` after it.
+
+A page may play footage with native `<video>` elements and set `currentTime` from `t`. The host makes that exact:
+a media seek lands inside the frame it names, and the host waits for pending seeks before it captures.
+
+## 6. The edit: film.json
+
+A film page draws a shot. An edit, the part a person adjusts by hand in an editor, is data: `film.json`.
+
+```json
+{
+  "stage": { "w": 1920, "h": 1080 },
+  "tracks": [
+    { "clips": [{ "src": "scenes/title.html", "id": "title", "at": 1, "transform": { "t": [0, 0], "r": 0, "s": [1, 1] },
+        "overrides": [{ "at": "#title", "text": "Aura Pods", "style": { "color": "#7fd4ff" }, "t": [0, -40] }] }] },
+    { "clips": [{ "src": "footage/a.mp4", "id": "open", "at": 0, "time": [12.2, 15], "speed": 0.5, "volume": 0.8 }] },
+    { "clips": [{ "src": "music/bed.mp3", "id": "bed", "at": 0, "time": [0, 10], "volume": 0.5 }] }
+  ]
+}
+```
+
+- `stage`: the frame in CSS pixels.
+- `tracks`: track 0 is on top. A track has no kind: any clip goes on any track, and what a clip is comes from its
+  file — a film page (`.html`), a video, a still picture or a sound (by extension). Clips on one track do not
+  overlap; overlapping pictures (a crossfade, a picture-in-picture) sit on different tracks. A track may be `locked`,
+  `hidden` (no picture and no sound) or `muted`. A `kind` written by an earlier edition is read and dropped.
+- A clip's source (a video, a still, a page) is first fitted whole inside the stage and centered (contain); then its
+  `transform` applies, as in Figma: `t` [x, y] moves its top-left corner in px, `s` [x, y] scales its width and height
+  (the top-left corner stays), `r` rotates it clockwise in degrees about its own center.
+- A clip: `src` (relative to film.json), `id` (unique across the film; without it, the file's name), `at` (start on
+  the film, seconds; default 0), `time` ([in, out] in the source's own seconds; default: all of it; a still's `time`
+  is its length), `fade` (`[in, out]` seconds, or one number for both: opacity for picture, gain for sound),
+  `transform` on pictures (pages, videos, stills), `volume` on what has sound (pages, videos, sounds; linear gain, 0
+  mutes), and `speed` on videos and sounds (playback rate from 0.25 to 4, sound keeps its pitch): the clip lasts
+  `(out − in) / speed` on the film. A field the clip's kind does not take is an error.
+- A page clip is a film page: the host calls its `frame` with the clip's local time `in + (t − at)`, holding the
+  page's last frame when the clip runs past the page's end, and its `audio` is placed and trimmed with the clip.
+- Any other field is an error: a host reads film.json strictly, so a misspelled field is reported, not ignored. The
+  reference reading is `src/film-doc.mjs`.
+- `overrides` on a page clip are a person's tweaks to elements of the page, applied by the host after each frame:
+  `at` (a CSS selector), optional `n` (which match, from 1), `t` (translate px), `s` (scale), `r` (rotate degrees) as
+  the independent CSS transform properties so they compose with the page's own animation, `style` (CSS properties,
+  applied with priority), `text` (replaces the text of an element without children).
+- The sound of a `video` clip joins the mix unless its `volume` is 0.
+
+A host plays a film.json as a film (it is itself a protocol page), so a film.json can be previewed, checked and
+rendered like any page. Editors change film.json; the pages stay as their authors wrote them.
+
+## 7. Versioning
+
+This is version 0.1. Fields may be added; their absence must keep meaning what it means today. A page MAY declare
+`film.version`.

package/TRADEMARK.md

@@ -0,0 +1,25 @@
+# OpenFilm trademarks
+
+The code in this repository is licensed under [Apache-2.0](LICENSE): use it, change it, ship it. The license does not
+cover the OpenFilm name and logo (Apache-2.0, section 6). This page says how you can use them, so that people always
+know what comes from the OpenFilm project and what does not.
+
+## You can
+
+- Say what your work does with OpenFilm: "made with OpenFilm", "an OpenFilm film", "works with OpenFilm", "for the
+  OpenFilm format".
+- Refer to OpenFilm in articles, talks, tutorials, courses and videos.
+- Fork this repository and keep the name while you work on changes you mean to send back.
+- Redistribute unmodified releases under their own name.
+
+## You can't, without written permission
+
+- Name a modified version, a product, a hosted service or a company "OpenFilm", or anything easily confused with it.
+  A fork you publish as your own needs its own name.
+- Use the OpenFilm logo for your own product or service, or a logo that looks like it.
+- Suggest that the OpenFilm project made, endorses or supports your work when it does not.
+- Use "openfilm" in a domain name, package name or account name in a way that looks official.
+
+## Questions
+
+Write to legal@openfilm.dev. If you are not sure whether a use is fine, ask: most are.

package/bin/openfilm.mjs

@@ -1,2 +1,154 @@
 #!/usr/bin/env node
-console.log('OpenFilm is coming soon: https://openfilm.dev');
+import { parseArgs } from 'node:util';
+
+const USAGE = `openfilm — a film is a function of time: given t, it draws that moment
+
+  openfilm open   [folder]            start or open the project; Studio shows it to the person
+  openfilm look   [what] [t | a-b]    check the film and draw it: a contact sheet with its sound and loudness
+  openfilm render [a-b]               the MP4, saved beside film.json
+  openfilm get    [what] [--options]  voice-over, music, sound effects, transcripts, images, video, made by a provider
+
+  Run with no arguments for the manual; \`openfilm <command> --help\` for one command's options.
+  look, render and get work on the project around the current folder.
+  Exit status: 0 done, 1 the film or the command failed (the output says why), 2 not a project or a wrong command.`;
+
+/* one command's help: what it does, what it takes, where its output goes */
+const COMMAND_HELP = {
+  open: `openfilm open [folder]
+
+  Start or open a project (default: the current folder). A folder that is not a project yet gets an empty
+  film.json, { "stage": { "w": 1920, "h": 1080 }, "tracks": [] }; nothing else is created.
+  Starts OpenFilm Studio if it is not running and prints its address. A Studio page already open switches to the
+  project; otherwise open the address in your built-in browser, and if no page connects within 15 s, Studio opens
+  the person's browser (OPENFILM_NO_BROWSER=1: never).`,
+  look: `openfilm look [what] [t | a-b]
+
+  what   the project (default), a film page (.html), or a media file (video, image, sound)
+  t      one frame at full size, e.g. 4.5
+  a-b    a dense sheet of a stretch, e.g. 3-6
+         without either: a contact sheet of the whole thing, its sound and loudness, and a check that
+         the same t draws the same picture
+
+  Writes PNGs under .film/look/ of the project and prints their paths.
+
+  --count <n>     frames in a sheet (12)`,
+  render: `openfilm render [a-b]
+
+  Render the project around the current folder to video.
+  The whole film goes to <project>/<folder name>.mp4, beside film.json; a range (a-b) goes to .film/render/.
+
+  --out <file>    another path; .webm or .mov with --alpha
+  --fps <n>       frame rate (30)
+  --4k            3840 px wide              --scale <n>     any device pixel ratio
+  --blur          motion blur (8 samples)   --samples <n>   --shutter <0..1>
+  --alpha         transparent background    --workers <n>   parallel browsers`,
+};
+
+/* `openfilm` alone: the manual, the whole of what an agent needs to know. `get` takes any options its verb has,
+   so it goes to Studio (studio/client.mjs) before the fixed options below are parsed. */
+const RAW = process.argv.slice(2);
+/* the command as the agent can type it here: `npx openfilm` once published, `openfilm` where it is installed */
+const RUN = process.env.npm_command === 'exec' ? 'npx openfilm' : 'openfilm';
+if (RAW.length === 0) {
+  const { readFileSync } = await import('node:fs');
+  console.log(readFileSync(new URL('../templates/MANUAL.md', import.meta.url), 'utf8').replaceAll('npx openfilm', RUN));
+  process.exit(0);
+}
+if (RAW[0] === 'get') {
+  let result;
+  try { result = await (await import('../studio/client.mjs')).getMedia(RAW.slice(1), (line) => console.error(line)); }
+  catch (e) { result = { code: 1, lines: [`openfilm get: ${e.message}`] }; }
+  for (const line of result.lines) console.log(line);
+  process.exit(result.code);
+}
+
+const { values: o, positionals } = parseArgs({
+  allowPositionals: true,
+  options: {
+    count: { type: 'string' }, out: { type: 'string', short: 'o' }, '4k': { type: 'boolean' }, scale: { type: 'string' },
+    blur: { type: 'boolean' }, samples: { type: 'string' }, shutter: { type: 'string' }, alpha: { type: 'boolean' },
+    fps: { type: 'string' }, workers: { type: 'string' }, help: { type: 'boolean', short: 'h' },
+  },
+});
+const [cmd, ...args] = positionals;
+/* the help speaks the name this was run as: `openfilm` or `npx openfilm` */
+const NAME = RUN;
+const named = (text) => text.replace(/^( {2})?openfilm(?= )/gm, `$1${NAME}`).replace('`openfilm <command>', `\`${NAME} <command>`);
+const HELP = named(USAGE);
+if (o.help && COMMAND_HELP[cmd]) { console.log(named(COMMAND_HELP[cmd])); process.exit(0); }
+if (o.help || !cmd) { console.log(HELP); process.exit(0); }
+const num = (v) => (v == null ? undefined : Number(v));
+const opts = { ...o, count: num(o.count), scale: num(o.scale), samples: num(o.samples), shutter: num(o.shutter), fps: num(o.fps), workers: num(o.workers) };
+const commands = {
+  open: () => open(args[0] ?? '.'),
+  look: () => import('../src/look.mjs').then((m) => m.look(args, opts)),
+  render: () => import('../src/render.mjs').then((m) => m.render(args, opts)),
+};
+/** Make (or find) the project and show it in Studio; `.film/opened` marks a project Studio has shown. @param {string} folder */
+async function open(folder) {
+  const { openInStudio } = await import('../studio/client.mjs');
+  const { mkdirSync, writeFileSync } = await import('node:fs');
+  const { join } = await import('node:path');
+  const fallback = process.env.OPENFILM_NO_BROWSER ? 0 : 15;
+  try {
+    const { project, url, pages } = await openInStudio(folder, { fallback, say: (line) => console.error(line) });
+    mkdirSync(join(project.path, '.film'), { recursive: true });
+    writeFileSync(join(project.path, '.film', 'opened'), '');
+    return { ok: true, lines: [`project  ${project.path}`, `Studio   ${url}`, pages
+      ? '         the Studio page already open switched to this project'
+      : fallback ? `         open it in your built-in browser if you have one; otherwise it opens in the person's browser in ${fallback} s`
+        : '         open it in your built-in browser, or give it to the person'] };
+  } catch (e) { return { ok: false, lines: [`${NAME} open: ${e.message}`] }; }
+}
+if (!commands[cmd]) { console.error(`${NAME}: no command ${cmd}\n\n${HELP}`); process.exit(2); }
+
+if (cmd === 'look' || cmd === 'render') {
+  const { existsSync } = await import('node:fs');
+  const { dirname, join, resolve } = await import('node:path');
+  /* a project is made by \`open\`: look and render work in one (the one around here, or around what they look at) */
+  const around = (from) => { for (let up = resolve(from); up !== dirname(up); up = dirname(up)) if (existsSync(join(up, 'film.json'))) return up; return null; };
+  const target = args.find((a) => !/^\d+(\.\d+)?(-\d+(\.\d+)?)?$/.test(a));
+  const project = around('.') ?? (target ? around(existsSync(target) && !/\.html?$/i.test(target) ? dirname(resolve(target)) : target) : null);
+  if (!project) { console.error(`${NAME} ${cmd}: ${resolve('.')} is not in a project; \`${NAME} open\` makes one and shows it in Studio`); process.exit(2); }
+  /* a project Studio has never shown (copied, cloned, forked): show it now, so the person watches from the start */
+  if (!existsSync(join(project, '.film', 'opened'))) {
+    const shown = await open(project);
+    for (const line of shown.lines) console.error(line);
+    if (!shown.ok) console.error(`${NAME} ${cmd}: carrying on without Studio`);
+  }
+}
+
+/** The first run on a machine has no browser yet: fetch Playwright's Chromium once, then run the command again. */
+async function installChromium() {
+  const { createRequire } = await import('node:module');
+  const { spawnSync } = await import('node:child_process');
+  const { dirname, join } = await import('node:path');
+  const cli = join(dirname(createRequire(import.meta.url).resolve('playwright-core/package.json')), 'cli.js');
+  console.error(`${NAME}: first run on this machine, downloading the browser films are drawn in (about 100 MB, once)`);
+  const r = spawnSync(process.execPath, [cli, 'install', 'chromium-headless-shell'], { stdio: ['ignore', 'inherit', 'inherit'] });
+  if (r.status !== 0) throw new Error('could not download the browser; run `npx playwright-core install chromium-headless-shell` and try again');
+}
+
+if (cmd === 'look' || cmd === 'render') {
+  const { spawnSync } = await import('node:child_process');
+  const missing = () => ['ffmpeg', 'ffprobe'].some((bin) => spawnSync(bin, ['-version'], { stdio: 'ignore' }).error);
+  if (missing()) {
+    console.error(`${NAME} ${cmd}: needs ffmpeg and ffprobe on the PATH (macOS: brew install ffmpeg · Debian/Ubuntu: sudo apt install ffmpeg · Windows: winget install ffmpeg)`);
+    process.exit(2);
+  }
+}
+
+try {
+  let result;
+  try { result = await commands[cmd](); }
+  catch (e) {
+    if (!/Executable doesn't exist/.test(e.message)) throw e;
+    await installChromium();
+    result = await commands[cmd]();
+  }
+  for (const line of result.lines) console.log(line);
+  if (result.ok === false) process.exitCode = 1;
+} catch (e) {
+  console.error(`${NAME} ${cmd}: ${e.message}`);
+  process.exit(1);
+}

package/package.json

@@ -1,10 +1,75 @@
 {
   "name": "openfilm",
-  "version": "0.0.1",
-  "description": "OpenFilm: make any video, change anything. A film is a web page that draws any moment of itself. Coming soon.",
-  "homepage": "https://openfilm.dev",
+  "version": "0.1.0",
+  "description": "OpenFilm: a film is a web page that can draw any moment of itself. The spec, the agent manual and the `openfilm` command.",
   "license": "Apache-2.0",
-  "bin": { "openfilm": "bin/openfilm.mjs" },
-  "files": ["bin", "README.md"],
-  "engines": { "node": ">=22" }
+  "homepage": "https://openfilm.dev",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/openfilm/openfilm.git"
+  },
+  "bugs": {
+    "url": "https://github.com/openfilm/openfilm/issues"
+  },
+  "keywords": [
+    "video",
+    "motion-graphics",
+    "agents",
+    "claude-code",
+    "codex",
+    "animation",
+    "render"
+  ],
+  "type": "module",
+  "bin": {
+    "openfilm": "bin/openfilm.mjs"
+  },
+  "exports": {
+    "./film-doc": "./src/film-doc.mjs",
+    "./host": "./src/host.mjs",
+    "./shared": "./src/shared.mjs",
+    "./look": "./src/look.mjs",
+    "./render": "./src/render.mjs",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "README.md",
+    "SPEC.md",
+    "TRADEMARK.md",
+    "bin",
+    "skills",
+    "src",
+    "!src/*.test.mjs",
+    "templates",
+    "studio/server",
+    "studio/client.mjs",
+    "studio/ui/dist",
+    "!studio/**/*.test.mjs"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "dependencies": {
+    "playwright-core": "1.61.1"
+  },
+  "scripts": {
+    "test": "node --test --test-concurrency=1 src/*.test.mjs studio/*.test.mjs studio/server/*.test.mjs studio/server/providers/*.test.mjs studio/ui/src/editor/*.test.ts",
+    "typecheck": "tsc -p studio/server && tsc -p studio/ui",
+    "build:ui": "vite build --config studio/ui/vite.config.ts",
+    "prepack": "npm run build:ui"
+  },
+  "devDependencies": {
+    "@fontsource-variable/inter": "^5.3.0",
+    "@tailwindcss/vite": "^4.3.3",
+    "@types/node": "^22.20.5",
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
+    "@vitejs/plugin-react": "^5.2.0",
+    "lucide-react": "^0.469.0",
+    "react": "^19.3.0",
+    "react-dom": "^19.3.0",
+    "tailwindcss": "^4.3.3",
+    "typescript": "^5.9.3",
+    "vite": "^7.3.6"
+  }
 }

package/skills/openfilm/SKILL.md

@@ -0,0 +1,9 @@
+---
+name: openfilm
+description: Make videos as web pages with OpenFilm. Use when the user asks for a video, motion graphics, an animation, a launch film, an explainer, a music video, or to edit, cut, check or render a film (film.json and pages with window.film).
+---
+
+# OpenFilm
+
+Run `npx -y openfilm` and follow the manual it prints: it is the whole of OpenFilm, a few hundred words. Run it again
+whenever you need it.