The VS Code of video editing, built for agents.
TypeScript
Add initial documentation for Diffusion Studio, including README, CLI reference, asset management, and composition guidelines.
konstantin-paulus707c08190f6a
diff --git a/README.md b/README.mdnew file mode 100644index 00000000..0099a05f--- /dev/null+++ b/README.md@@ -0,0 +1,130 @@+# Diffusion Studio++**FFmpeg for agents:** a video editor you drive from the command line, with a generative-AI and vision toolchain built in.++Diffusion Studio is a canvas-based video editor. What makes it different is `dapi`, its CLI: every part of the editor (projects, the scene graph, the asset library, AI generation, rendering) is scriptable over a local socket, with JSON on stdout and deterministic exit codes. A human uses the canvas; an agent uses `dapi`. Both edit the same document.++```sh+dapi open # use -b to run the editor headless+dapi mount hero.tsx # render a composition into it+dapi node export -o hero.mp4 # encode the scene to disk+```++## Compositions as code++Compositions are [SolidJS](https://www.solidjs.com) modules. `dapi mount` compiles them and renders each element into an editable node in the document; re-mounting rebuilds in place, like reloading a webpage. Solid's control flow (`<For>`, `<Show>`, …) and any npm package are available to compose the tree, and generative assets are declared as values and produced on mount:++```tsx+import { For } from "solid-js";+import { generate } from "@diffusionstudio/jsx";++const hero = generate.image({ prompt: "A neon city at night, cinematic" });+const motion = generate.video({ prompt: "slow camera push-in", startFrame: hero });++const TITLES = [+ { text: "The Grid", inPoint: 0, outPoint: 2.5 },+ { text: "Neon Nights", inPoint: 2.5, outPoint: 5 },+];++export default function Project() {+ return (+ <scene key="intro" name="Intro" width={1920} height={1080} fill="black">+ <video src={motion} width={1920} height={1080} />+ <sequence>+ <For each={TITLES}>+ {(t) => (+ <text+ textAlign="center"+ textBaseline="middle"+ fontSize={128}+ width={1920}+ height={1080}+ fill="white"+ inPoint={t.inPoint}+ outPoint={t.outPoint}+ >+ {t.text}+ </text>+ )}+ </For>+ </sequence>+ </scene>+ );+}+```++Everything a mount produces stays a first-class editor node, so a person can pick up in the UI exactly where the script left off.++## Seeing and hearing the media++Cutting footage requires looking at it. The CLI ships the inspection tools an agent needs to work with media it cannot watch:++```sh+dapi asset probe clip.mp4 # container + codec metadata, like ffprobe+dapi asset frame clip.mp4 -t 0 12 45 # decode frames to PNGs+dapi asset visualize track.mp3 # waveform / filmstrip previews+dapi asset transcript interview.wav # timed, word-level transcript+dapi asset analyze b-roll.mp4 -p "when is the product shown?" # ask a vision model+dapi asset sync lav.wav -v camera.mp4 # align external audio to camera audio+dapi node screenshot # see the canvas itself+```++## CLI at a glance++| Command | Purpose |+| --- | --- |+| `dapi open` | Launch the app, open a file, or turn a folder of footage into a project |+| `dapi context` | Summary of the open project: scenes, playhead, fonts |+| `dapi mount` | Compile and mount a JSX composition |+| `dapi node …` | The scene graph: `ls`, `tree`, `grep`, `patch`, `insert`, `cp`, `rm`, `screenshot`, `export` |+| `dapi asset …` | The media library: `add`, `ls`, `probe`, `frame`, `visualize`, `analyze`, `transcript`, `sync`, `export` |+| `dapi project …` / `dapi folder …` / `dapi selection …` | Projects, library folders, canvas selection |+| `dapi models` / `dapi voices` / `dapi fonts` | Discover generation models, speech voices, local fonts |++Conventions throughout: single results are one JSON value, collections are JSON Lines, errors go to stderr with exit code `1`. Everything is built to be piped, grepped, and driven by a program.++## Documentation++- [Getting started](docs/getting-started.md): install the CLI, open a project, first mount, first export+- [CLI reference](docs/cli.md): every command, its options, and its output+- [Writing compositions](docs/composition.md): the JSX API with elements, timing, paints, generative assets, and captions+- [Working with media](docs/assets.md): the asset library and the vision/audio toolchain++## Repository layout++| Path | Package | What it is |+| --- | --- | --- |+| `apps/web` | `@diffusionstudio/web` | The editor UI (Solid + Vite) |+| `apps/desktop` | `@diffusionstudio/desktop` | Electron shell hosting the editor |+| `apps/cli` | `@diffusionstudio/cli` | The `dapi` CLI |+| `packages/jsx` | `@diffusionstudio/jsx` | Solid JSX runtime and types for compositions |++## Contributing / local setup++Requirements: Node 20+ and npm.++```sh+git clone https://github.com/diffusionstudio/editor.git+cd editor+npm install++npm run dev # editor in the browser (Vite dev server)+npm run dev:desktop # editor as a desktop app (Electron)+```++To build the CLI and put `dapi` on your PATH (macOS/Homebrew layout; adjust the link target for other setups):++```sh+npm run symlink:create --workspace=@diffusionstudio/cli+```++Before sending a PR:++```sh+npm run check # typecheck all workspaces+npm run lint # lint all workspaces+```++## License++[MPL-2.0](LICENSE)diff --git a/docs/README.md b/docs/README.mdnew file mode 100644index 00000000..587d8a7a--- /dev/null+++ b/docs/README.md@@ -0,0 +1,10 @@+# Diffusion Studio documentation++Diffusion Studio is driven through `dapi`, its CLI. Start here:++- [Getting started](getting-started.md): install the CLI, open a project, first mount, first export+- [CLI reference](cli.md): every command, its options, and its output+- [Writing compositions](composition.md): the JSX API with elements, timing, paints, generative assets, and captions+- [Working with media](assets.md): the asset library and the vision/audio toolchain++The exhaustive specifications these docs are distilled from live with the CLI source: [api-spec.md](../apps/cli/api-spec.md) and [jsx-spec.md](../apps/cli/jsx-spec.md).diff --git a/docs/assets.md b/docs/assets.mdnew file mode 100644index 00000000..675076b5--- /dev/null+++ b/docs/assets.md@@ -0,0 +1,92 @@+# Working with media++The asset library holds a project's media. Beyond storage, the CLI ships an inspection toolchain (probe, decode, visualize, transcribe, analyze, align) so an agent can *look at* footage before cutting it. All of it runs locally except `analyze` and `transcript`, which use hosted models.++**Id or path:** every inspection command takes either an asset id or a local file path. A path is imported into the library first, then inspected, so `dapi asset probe clip.mp4` works on a file that isn't in the project yet.++## The library++```sh+dapi asset add <paths...> [--folder <id>] # import files+dapi asset ls [--folder <id>] [--depth N] # the library as a folder tree+dapi asset mv <ids...> [--to <folderId>] # move assets between folders+dapi asset rm <ids...> # delete assets+dapi asset export <ids...> [-o <path>] # write original file bytes back to disk (no re-encode)+```++Folders nest arbitrarily and are managed with `dapi folder`:++```sh+dapi folder ls [parentId]+dapi folder create <name> [-p, --parent <id>]+dapi folder rename <id> <name>+dapi folder mv <ids...> [--to <folderId>]+dapi folder rm <ids...> # cascades: deletes all descendant folders AND assets;+ # the output reports the deleted counts+```++Omitting a folder id anywhere always means the library root. (Opening a folder with `dapi open ./dir` builds this tree automatically from the directory structure; see [Getting started](getting-started.md#turn-a-folder-of-footage-into-a-project).)++## Inspecting media++### `asset probe`++```sh+dapi asset probe <id|path>+```++Container and per-track technical metadata (format, duration, codec parameters), demuxed locally without decoding, like `ffprobe`. Packet stats (frame rate, bitrate) are estimated from a leading sample, so they're fast but approximate.++### `asset frame`++```sh+dapi asset frame <id|path> [-t <time...>] [-o <dir>]+```++Decodes video frames at the given timestamps to PNGs, at the asset's full resolution. Prints `{ time, path }` per frame. (For the *composited* canvas instead of the raw asset, use `dapi node screenshot`.)++### `asset visualize`++```sh+dapi asset visualize <id|path> [-s <start>] [-e <end>] [-x <scale>] [-o <path>]+```++Renders a one-image preview chosen by media type: audio gets an amplitude **waveform** with a time axis, video gets a **filmstrip** of evenly sampled frames with the audio waveform beneath it, and images get a thumbnail. `-s`/`-e` window the preview; `-x` trades thumbnail size against grid density. Prints `{ path }`.++### `asset transcript`++```sh+dapi asset transcript <id|path>+```++Transcribes speech in a video or audio asset. Returns segments with **word-level start/end times in seconds**: the raw material for caption timing, jump cuts, and content search.++### `asset analyze`++```sh+dapi asset analyze <id|path> [-p <prompt>] [-s <start>] [-e <end>]+```++Puts a multimodal model in front of an image, video, or audio asset. Without a prompt, returns a general description; with one, answers it ("what's the dominant color?", "when is the product shown?"). `-s`/`-e` scope the analyzed segment; timestamps in the answer are relative to `-s`.++### `asset sync`++```sh+dapi asset sync <audioId|path> -v <videoId|path>+```++Measures the offset between a standalone recording (a lav or voice track) and the camera audio of the same take, by cross-correlation. Prints `{ offsetSeconds, confidence }` with the convention `audioStart = videoStart + offsetSeconds`; a clear match scores above ~0.9. Read-only: position the clip yourself with the reported offset.++## A typical agent pass++```sh+dapi open -b ./shoot # project from footage+dapi asset ls --depth 1 # what's here?+dapi asset probe gbHJ # what format is it?+dapi asset visualize gbHJ # what does it look like over time?+dapi asset transcript gbHJ # what is said, and when?+dapi asset analyze gbHJ -p "best moment for a thumbnail?"+dapi mount cut.tsx # compose the edit+dapi node screenshot # verify visually+dapi node export -o cut.mp4 # ship it+```diff --git a/docs/cli.md b/docs/cli.mdnew file mode 100644index 00000000..2e648cfd--- /dev/null+++ b/docs/cli.md@@ -0,0 +1,201 @@+# CLI reference++`dapi` drives a running Diffusion Studio instance over a local socket. Every command except `open` and `fonts` needs the app running; launch it with `dapi open` (add `-b` for headless).++## Conventions++- **stdout is JSON.** Single results are one JSON value; collections and batch results are JSON Lines (one object per line, no surrounding array). `mount` and `node insert` print nothing on success.+- **stderr is for humans:** error messages and progress spinners.+- **Exit codes:** `0` on success, `1` on any error.+- **Unix names are canonical:** `ls`, `rm`, `cp`, `mv`, `grep`. The English forms (`list`, `remove`, `duplicate`, `move`) are aliases, and `get` is an alias for every `ls`.+- **Group aliases:** `selection`→`sel`, `node`→`n`, `project`→`p`, `asset`→`a`, `folder`→`fld`, `context`→`ctx`.+- **Batch commands** (`node rm`, `node patch`, `asset add`, …) emit one `{ status: "fulfilled" | "rejected", … }` line per input, so partial failures are visible per item.++### Time values++Wherever a command takes a time, three formats are accepted (frames are at 30 fps):++| Format | Example | Meaning |+| --- | --- | --- |+| number | `2.2` | seconds |+| `"<n>f"` | `"45f"` | frames |+| clock | `"02:30"`, `"01:02:30"` | MM:SS or HH:MM:SS |++Times in output are plain seconds, except in `node ls`, whose raw records use engine units (frames, packed `0xRRGGBB` colors, dB).++## App++### `open`++```sh+dapi open [target] [-b, --background]+```++Launches the app, or opens a target: a file, a `diffusion://` deep link, or a **folder**, which creates a project from the folder's media (or switches to the one created earlier; see [Getting started](getting-started.md#turn-a-folder-of-footage-into-a-project)). `--background` launches with no window, for headless use. The only command that doesn't need the app already running (besides `fonts`).++### `whoami`++Prints the signed-in account `{ id, email, provider }`, or `null`.++### `context`++Prints the open project's essentials: project id and name, entity count, scenes with sizes, the active scene, the playhead position (frames), and available font families. Call it first.++## Composing++### `mount`++```sh+dapi mount (<path> | --code <str>)+```++Compiles a Solid JSX module and mounts its rendered roots into the document. Re-mounting rebuilds keyed roots in place, like reloading a webpage. Declared generative assets are produced during the mount, which blocks until they land. With `--code`, a bare JSX expression is wrapped into a module automatically. See [Writing compositions](composition.md).++### `node insert`++```sh+dapi node insert <parentId> (<path> | --code <str>) [-i, --index <N>]+```++Same pipeline as `mount`, but inserts the rendered roots as children of an existing entity instead of mounting document roots. Roots take no `key`; every run inserts fresh nodes. `--index` sets the position among the parent's children (node roots only). Also how you extend sub-entities, e.g. adding a stop to a gradient:++```sh+dapi node insert <paintId> --code '<colorStop offset={0.5} color="#FF0055" />'+```++### `node patch`++```sh+dapi node patch ([path.json] | --json <str>)+```++Assigns JSX props on existing entities. The payload is an array of `{ id, …props }`, taking exactly the props a JSX element takes (see the [element reference](composition.md#elements)). A rejected entry applies none of its props. Renaming is patching `name`; recoloring is patching `fill`; paints and color stops are patchable too.++```sh+dapi node patch --json '[{ "id": 42, "x": 100, "opacity": 0.5 }]'+```++Note: `src` resolves asynchronously after the other props; patch it on its own to keep failure reporting unambiguous.++## Inspecting the scene graph++### `node tree`++```sh+dapi node tree [id] [--depth N]+```++An entity's subtree as nested JSON: structure only, with a compact `description` per node. The way to discover ids. Default depth `3`; `0` means the full subtree. Omit the id for one tree per top-level node.++### `node ls`++```sh+dapi node ls [ids...]+```++The raw entity records: every component the entity carries, in engine units. The property-level counterpart to `tree`. With no ids, lists the top-level nodes.++### `node grep`++```sh+dapi node grep <pattern> [id] [-i] [-t <types...>] [-k <components...>] [-l] [-c]+```++Searches entity records by regex and prints matching entities with the components that matched. `[id]` scopes to a subtree. `-t` filters by node type, `-k` restricts to specific components, `-l` prints refs only, `-c` prints a count. Find nodes by name with `dapi node grep -k Name Title`; find every entity with a `Trim` component with `dapi node grep -k Trim .`.++### `node screenshot`++```sh+dapi node screenshot [id] [-t, --time <time>]+```++Focuses the node (or the active scene, if omitted) and captures it to a PNG at the given timeline position. Prints `{ path }`.++### `selection`++```sh+dapi selection ls # the selected nodes+dapi selection set [ids...] # replace the selection (no ids = clear)+dapi selection focus # pan/zoom the canvas to the selection+```++Mutations print the resulting selection, so calls can be chained without a follow-up read.++## Editing nodes++### `node cp`++Deep-clones nodes including descendants: `dapi node cp <ids...>`. Prints `{ sourceId, newId }` per input.++### `node rm`++Deletes nodes and their descendants: `dapi node rm <ids...>`.++## Rendering++### `node export`++```sh+dapi node export [id] [-o, --output <path>] ([config.json] | --json <str>)+```++Renders a scene to a video file, locally. Defaults to the active scene and an MP4 (H.264, 10 Mbps, 1080p, AAC 128 kbps) in the temp directory; prints `{ path }`. Long-running: progress goes to stderr, stdout stays clean JSON. The encode window follows the scene's workarea.++All config fields are optional:++```jsonc+{+ "format": "mp4", // "mp4" | "webm" | "ogg" | "mov"+ "video": {+ "codec": "avc", // "avc" | "hevc" | "vp9" | "av1" | "vp8"+ "bitrate": 10000000, // bits/sec+ "fps": 30, // default: the scene's frame rate+ "resolution": 1080, // target height; width follows the scene's aspect+ "enabled": true+ },+ "audio": {+ "codec": "aac", // "aac" | "opus"+ "bitrate": 128000,+ "sampleRate": 48000,+ "numberOfChannels": 2,+ "enabled": true // false = video only+ },+ "trim": { "end": 30 } // seconds; cap the encode+}+```++## Projects++```sh+dapi project active # the open project, or null+dapi project ls # all projects, most recent first+dapi project create [name] # create and open+dapi project set <id> # switch to a project+dapi project rm <id> # delete+```++## Assets and folders++The library commands (`asset add/ls/mv/rm/export`, `folder ls/create/rename/mv/rm`) and the media-inspection commands (`probe`, `transcript`, `analyze`, `visualize`, `frame`, `sync`) are covered in [Working with media](assets.md).++## Discovery++### `models`++```sh+dapi models [image|video|audio]+```++Lists the generation models available per media type, with each model's id and its constraints (durations, aspect ratios, features). These are what you reference from `generate.*` declarations.++### `voices`++Lists the speech voices for `generate.voice` declarations.++### `fonts`++```sh+dapi fonts [-f <pattern>] [-w <weights...>] [-s normal|italic] [-l <n>] [-n]+```++Lists local font families and variants (macOS only). `-n` prints plain family names. Works without the app running.diff --git a/docs/composition.md b/docs/composition.mdnew file mode 100644index 00000000..c866a728--- /dev/null+++ b/docs/composition.md@@ -0,0 +1,180 @@+# Writing compositions++Compositions are **Solid JSX modules**. `dapi mount` compiles the module, runs it in the app, and renders every JSX element into an editable node in the document: no hidden DOM, no CSS, no layout pass. All positioning is explicit pixels.++```tsx+export default function Project() {+ return (+ <scene key="intro" name="Intro" width={1920} height={1080} fill="black">+ {/* ... */}+ </scene>+ );+}+```++The module's default export is the project component. Solid's control flow (`<For>`, `<Show>`, …) and primitives (`createSignal`, `createMemo`, …) are available to *compose* the tree; the render is one-shot: after commit, the nodes belong to the document and signal changes no longer affect it. The update path is re-running the mount.++**Dependencies:** `solid-js` and `@diffusionstudio/jsx` are provided by the app; everything else you import (npm packages, local files, JSON) is bundled by the CLI. Libraries must be browser-compatible.++## Roots and keys++Every top-level element declares its identity with a `key`:++- Mounting rebuilds the existing node carrying that key, or creates it. Entity id and canvas position are preserved across re-mounts.+- Keyed nodes the render no longer produces are **deleted**; the mount owns its keyed roots. Unkeyed nodes (made by hand in the editor) are never touched.+- Keys must be unique within a render. Give roots a `name` too: the key identifies, the name labels.++The first rendered root becomes the active scene. New roots are auto-placed on the canvas near the viewport center; `<scene>` has no `x`/`y` because canvas arrangement is an editor concern, not part of the composition.++## Elements++| Element | What it makes |+| --- | --- |+| `<scene>` | A scene; clips children to its `width`×`height`. Document root only; scenes don't nest. |+| `<group>` | Container with a transform; give it `fill` to draw a rectangle. |+| `<rect>` | A filled rectangle. |+| `<text>` | Editable text. |+| `<video>` / `<image>` | Media; `src` is required. |+| `<audio>` | Sound only, no spatial props. |+| `<sequence>` | Lays children out back-to-back in time. |+| `<captions>` | Transcribes the scene's audio into styled captions. |+| `<solidPaint>`, `<linearGradientPaint>`, `<radialGradientPaint>`, `<colorStop>` | Fills, declared as children; see [Paints](#paints). |++User-defined components are ordinary Solid components; only intrinsic elements produce nodes.++### Common props++| Prop | Default | Meaning |+| --- | --- | --- |+| `key` | none | Stable identity; required on document roots. |+| `name` | none | Node name in the editor. |+| `x`, `y` | `0` | Position in px, relative to the parent, origin top-left. |+| `width`, `height` | parent size | Box size in px. |+| `rotation` | `0` | Degrees. |+| `opacity` | `1` | `0`–`1`. |+| `cornerRadius` | `0` | Px. |+| `inPoint`, `outPoint`, `startTime` | see [Timing](#timing) | Temporal placement. |++**Every box defaults to its parent's box**, the JSX analog of `position: absolute; inset: 0`. So a centered full-frame title is just:++```tsx+<text textAlign="center" textBaseline="middle" fontSize={128}>Hello</text>+```++### Per-element props++- **`<scene>`**: `key`, `width`, `height` (all required), `name`, `fill`. No timing or transform props.+- **`<rect>` / `<group>`**: `fill` (any CSS color; alpha is ignored, use `opacity`).+- **`<video>`**: `src` (required), `objectFit` (`"cover"` | `"contain"` | `"fill"`, default `"cover"`), `volume` (`0`–`1`).+- **`<image>`**: `src` (required), `objectFit` (default `"contain"`).+- **`<audio>`**: `src` (required), `volume`, timing props.+- **`<text>`**: string children (required), `fontFamily` (see `dapi fonts`), `fontSize`, `fontWeight`, `fontStyle`, `fill`, `textAlign`, `textBaseline`.++These same props are what `dapi node patch` assigns on existing nodes.++## Media sources++`src` accepts:++- an **absolute path** like `"/Movies/clip.mp4"`+- a **remote URL**, registered as a remote asset+- an **asset id**: an imported library asset (see `dapi asset ls`)+- an **`AssetRef`**: the value returned by a `generate.*` declaration++## Timing++Composition-relative, Lottie-inspired. Values take any [time format](cli.md#time-values) (seconds, `"45f"` frames, `"MM:SS"`).++| Prop | Meaning |+| --- | --- |+| `inPoint` / `outPoint` | The window on the parent timeline where the node is visible/audible. Omitted: media fits its natural duration, groups auto-fit their children. |+| `startTime` | Where source time 0 sits on the composition timeline (defaults to the in point). May be negative to skip into the source. |++```tsx+<video src="/Movies/clip.mp4" inPoint={0} outPoint={16} startTime="-30f" />+// plays from composition 0-16 s, starting 1 s (30 frames) into the source+```++`<sequence>` removes the arithmetic for back-to-back cuts: children are placed sequentially and non-overlapping in document order.++## Paints++A node's fill is a **paint child**; the `fill` prop is shorthand for a solid paint. Declaring paints as children unlocks gradients and stacking (later paints render on top, including over the media paint of a `<video>` or `<image>`):++```tsx+<rect width={640} height={360} cornerRadius={24}>+ <linearGradientPaint rotation={90}>+ <colorStop offset={0} color="#FF0055" />+ <colorStop offset={1} color="#0055FF" />+ </linearGradientPaint>+</rect>+```++`<solidPaint>` takes `color` (required) and `opacity`; gradient paints take `rotation` and `opacity` and only `<colorStop>` children (`offset` and `color` required). Colors are any CSS color; alpha is ignored, use `opacity`.++## Generated assets++Assets that don't exist yet are declared as values with the `generate` namespace and passed wherever a source is expected:++```tsx+import { generate } from "@diffusionstudio/jsx";++const hero = generate.image({ prompt: "A neon city at night, cinematic", seed: 42 });+const motion = generate.video({ prompt: "slow camera push-in", startFrame: hero, duration: 5 });+const vo = generate.voice({ prompt: "Welcome to the future." });+```++- `generate.image({ prompt, model?, aspectRatio?, refs?, seed? })`+- `generate.video({ prompt, model?, aspectRatio?, duration?, audio?, startFrame?, endFrame?, seed? })`+- `generate.voice({ prompt, voice? })` where `prompt` is the text to speak+- `generate.audio({ prompt, model? })`++Run `dapi models <type>` for valid model ids and per-model constraints, `dapi voices` for voices.++Declarations are pure: nothing generates until the mount commits, and refs never used by a mounted element are dropped. Because `startFrame`/`endFrame`/`refs` take refs as values, dependencies generate in the right order and cycles are impossible.++**Caching:** results are cached by content (model, prompt, resolved refs, seed, …) within a session: re-mounting an unchanged project reuses assets instead of regenerating, and identical declarations collapse to one asset. Set `seed` for reproducibility.++## Captions++`<captions />` inside a scene transcribes that scene's audio into a styled, timed caption node. It runs after generated assets land (so it can caption generated voice-over), attaches asynchronously, and is cached against the scene's audible mix, so re-mounting with unchanged audio doesn't re-transcribe.++```tsx+<captions preset="spotlight" colors={["#FF0055"]} />+```++| Preset | Style |+| --- | --- |+| `"classic"` (default) | Centered lowercase text, soft drop shadow, a few words at a time. |+| `"cascade"` | Light text lower-left; words appear as spoken. |+| `"spotlight"` | Bold italic centered line; the spoken word lights up (1 color slot). |+| `"whisper"` | Small, wide, understated ~2 s phrases. |+| `"paper"` | Centered two-line block; the spoken line is emphasized. |+| `"guinea"` | Uppercase display; the spoken word enlarges and cycles 3 colors (3 slots). |+| `"stark"` | Heavy uppercase, difference-blended into the footage. |++`colors` fills a preset's color slots in order; presets without slots ignore it.++## Types and tooling++For IntelliSense and typechecking in a project folder:++```sh+npm install --save-dev @diffusionstudio/jsx solid-js+```++```jsonc+// tsconfig.json+{+ "compilerOptions": {+ "jsx": "preserve",+ "jsxImportSource": "@diffusionstudio/jsx"+ }+}+```++The CLI strips types without checking them; run `tsc --noEmit` for type safety.++## Errors++Compile errors surface on stderr before the app is contacted. Evaluate/mount errors (invalid props, a root without `key`, nested `<scene>`, …) abort with **nothing inserted**. Generation errors surface after all generations settle; the mounted tree stays committed and the affected placeholder is left without media. Runtime errors map back to your source via sourcemaps.diff --git a/docs/getting-started.md b/docs/getting-started.mdnew file mode 100644index 00000000..828af947--- /dev/null+++ b/docs/getting-started.md@@ -0,0 +1,78 @@+# Getting started++## Install the CLI++The CLI is built from this repository. With Node 20+ installed:++```sh+git clone https://github.com/diffusionstudio/editor.git+cd editor+npm install+npm run symlink:create --workspace=@diffusionstudio/cli+```++`symlink:create` builds `dapi` and links it into `/opt/homebrew/bin` (the macOS/Homebrew layout). On other setups, build with `npm run build --workspace=@diffusionstudio/cli` and link `apps/cli/dist/index.js` onto your PATH yourself.++## Launch the editor++Every `dapi` command except `open` and `fonts` talks to a running Diffusion Studio instance. Start one:++```sh+dapi open # launch the app+dapi open -b # launch headless (no window), ideal for agents and CI+```++When developing from source, `npm run dev:desktop` starts the app too.++## Turn a folder of footage into a project++Point `open` at a directory and it becomes a project: every supported media file underneath is imported, with the directory structure mirrored as library folders.++```sh+dapi open ./shoot-2026-07+```++The first run creates the project and writes a `.dapi` marker file into the folder; later runs read the marker and just switch to that project. Commit the marker to share one project across a team, or add it to `.gitignore` to keep the association per-clone.++You can also manage projects directly: `dapi project create`, `dapi project ls`, `dapi project set <id>`.++## Look around++```sh+dapi context # the open project: scenes, active scene, playhead, fonts+dapi asset ls # the media library as a folder tree+```++`dapi context` (alias `ctx`) is the right first call in any session; it tells you what is on the canvas before you change it.++## Mount your first composition++Compositions are Solid JSX modules rendered into the document with `dapi mount`. For a one-liner, pass code inline:++```sh+dapi mount --code '<scene key="hello" name="Hello" width={1920} height={1080} fill="black">+ <text textAlign="center" textBaseline="middle" fontSize={120} fill="white">Hello World</text>+</scene>'+```++The `key` is the scene's stable identity: re-running the mount rebuilds that scene in place instead of adding a copy. For anything real, put the module in a file (`dapi mount hero.tsx`) and see [Writing compositions](composition.md).++Check the result visually:++```sh+dapi node screenshot # prints { "path": "/tmp/….png" }+```++## Export++```sh+dapi node export -o hello.mp4+```++Renders the active scene locally with sensible defaults (MP4, H.264, 1080p). Codec, bitrate, resolution, and trim are configurable; see [`node export`](cli.md#node-export) in the CLI reference.++## Next++- [CLI reference](cli.md): the full command surface+- [Writing compositions](composition.md): timing, paints, generative assets, captions+- [Working with media](assets.md): probe, transcribe, analyze, and align footage