Merge remote-tracking branch 'origin/main' into HEAD

2026-10-30 13:08:07 -06:00 · 2026-10-30 01:24:36 +07:00
parent 65130dbcee 676eeb8d07
commit 6af2bedfe0
146 changed files with 9259 additions and 694 deletions
@@ -614,7 +614,9 @@ Extension points and the bundled extensions: [plugins.md](plugins.md).
  Display Style between Timecode and Frames: `file.projectSettings {"timeDisplay": "frames"}`.
 * `prop.pickWhip {layer, prop, target: {layer, prop, dimension?}}` links a property as its
  expression pick whip does; `dimension` picks one of the target's values (`position[0]`), as a
-  drop on that value field does.
+  drop on that value field does. `byIndex: true` (an Alt pick whip: Alt held as it drops) refers
+  to an effect's properties by their index, `effect("Color Control")(1)`: it still reads a
+  renamed property, but another one if properties are reordered.
 * Every property row has a property pick whip in the Parent & Link column
  (`timeline.prop.<uid>.propertyPickWhip`; the expression row's is `timeline.prop.<uid>.pickWhip`).
  Dragged onto another property's name or value, in the Timeline or Effect Controls
@@ -680,6 +682,19 @@ effectcraft-cli exec file.importLottie '{"path":"anim.json"}' main.ecproj --save
 effectcraft-cli render main.ecproj --comp Main --out main.mov --format prores --progress   # progress lines on stderr for a program that reads them
 ```

+A long `run` doesn't fit on a command line (Windows caps it at 32 767 characters, Linux one
+argument at 128 KiB). `run --args-file F` reads the same `<id> <json>` arguments one per line;
+`run --commands FILE` reads steps as a JSON array of `{"command": ID, "params": {…}}` objects, or one
+such object per line (JSON Lines), and `--commands -` reads them from standard input. `--commands`
+may be repeated; its steps run after the positional pairs and `--args-file`. A malformed step is a
+usage error naming its index (from 0, as in the results) before anything runs, and the error of a step
+that fails ends with `(step N)`:
+
+```sh
+effectcraft-cli run --commands steps.json --empty --save-as main.ecproj
+generate-steps | effectcraft-cli run main.ecproj --commands - --save --json
+```
+
 Scripts written against After Effects' documented scripting API run with `script`:

 ```sh
@@ -37,7 +37,7 @@ cpal or muda. Everything in L0 to L4, the egui UI and the web app also build for
 | L3 | `render` | Evaluation and compositing: sources, masks, effects, transforms, 3D, motion blur, mattes, blending, layer cache, audio mixdown |
 | L3 | `media` | Footage decoding (FilmCraft's pure-Rust codecs), image sequences, Photoshop and SVG stills, frame cache |
 | L3 | `expr` | The expression engine (JavaScript via boa) with the After Effects object model |
-| L3 | `export` | Render queue encoding: H.264, HEVC and AV1 MP4, ProRes, WebM (VP9 + alpha or AV1, Opus), PNG/JPEG/TIFF/EXR sequences, GIF, WAV/AIFF |
+| L3 | `export` | Render queue encoding: H.264, HEVC and AV1 MP4, ProRes, WebM (VP9 + alpha or AV1, Opus), PNG/JPEG/TIFF/EXR/Targa sequences, GIF, WAV/AIFF |
 | L3 | `gpu` | The GPU compositor and GPU effects on wgpu compute shaders (Metal, Vulkan, Direct3D 12, WebGPU), checked against the CPU renderer |
 | L3 | `interchange` | Premiere Pro interop through timeline interchange (FCP7 XML, FCPXML, OTIO, EDL, AAF, OMF via FilmCraft's `filmcraft-interchange`): sequences ↔ compositions (§6a) |
 | L3 | `lottie` | Lottie JSON / dotLottie import and export (layers, precomps, eased and spatial keyframes, shapes, masks, mattes) with a warnings list for what Lottie cannot express |
@@ -345,7 +345,10 @@ as NaNs (a kernel that skips pixels fails the oracle) and validation errors pani
 (`ui-egui::frames`); headless renders, the CLI (unless `--gpu`) and CI use the CPU. Outside
 tests, device errors are logged rather than fatal. A viewer frame that runs out of video memory
 (`Gpu::within_memory`) renders on the CPU, the uploaded layers and pooled textures are freed, and
-the RAM preview keeps half as many GPU frames from then on. A frame whose render panics is
+the RAM preview keeps half as many GPU frames from then on. The same guard catches a frame's
+validation errors (an invalid texture, often left by a failed allocation): that frame renders on
+the CPU and the kept textures are freed, but the compositor stays on and, with no allocation
+failure before it, the RAM preview keeps its GPU frames (#1319). A frame whose render panics is
 rendered again on the CPU or released, never left in progress. Native readbacks and timing waits
 share a finite deadline; failure retires pending readbacks exactly once, and late results are
 discarded. The desktop executable and browser page own their shared device's error/loss handlers and forward
@@ -71,6 +71,16 @@ After the fix, all ten tangents equal AE's to the printed 0.001 px, and the two
 test `spatial_auto_bezier_tangents_follow_after_effects` checks the rule on other original keys,
 including a timing change. AE's output stays local; only the script and these scores are tracked.

+## Rectangle path start point
+
+Measured on 19 October 2026 with After Effects 2026 (26.2) on 400 × 300 shape rectangles with Trim
+Paths: a plain rectangle starts at its top-right corner and runs clockwise (0–25 % covers the right
+edge and 50 px of the bottom); with Roundness 40 it starts where the top-right arc meets the right
+edge. Start 70 / End 30 draws 30–70 %. EffectCraft started at the top-left corner (and the rounded
+rectangle elsewhere), so trimmed rectangles drew the wrong segment (86 of 5184 grid points off,
+now 5 at stroke edges). `effectcraft_path::rect` now draws AE's order, which also gives Convert to
+Bezier AE's vertex order. Regression test: `rectangles_start_where_after_effects_starts_them`.
+
 ## Still unmeasured

 Rendered frame comparisons now have a deterministic `effectcraft_effects::fidelity::compare_frames`
@@ -48,7 +48,7 @@ trips and renders, checked by tests, not against After Effects), **partial** (na
 | GIF | R/W | yes | yes (animated) | good |
 | BMP | R | yes | — | good |
 | WebP | — | yes (still; animated WebP as footage with its frames, timing and alpha, #762) | — | beyond After Effects |
-| Targa `.tga` | R/W | yes (still and sequence; alpha interpreted on import) | none | good for import (#745); no Targa output |
+| Targa `.tga` | R/W | yes (still and sequence; alpha interpreted on import) | yes (sequence; uncompressed 24-bit RGB or 32-bit RGB + Alpha, straight or premultiplied) | good: import (#745); output reads back through it unchanged; the alpha is not labelled in the file (no TGA 2.0 extension area), so it is interpreted on import |
 | DPX / Cineon `.dpx` `.cin` | R/W | yes (still and sequence; 8/10/12/16-bit luma, RGB, RGBA, both byte orders; log code values shown as stored) | none | partial: import (#756); no Interpret Footage ▸ Cineon Settings (log to linear), no DPX output; common in film VFX |
 | Radiance `.hdr` | R/W | yes (still and sequence, 32-bit linear float like OpenEXR) | none | good for import (#745); no Radiance output |
 | SGI, PICT, ElectricImage, RLA/RPF images | R | none | none | Legacy; RPF camera data import exists (`keys.rpfCameraImport`) |
@@ -96,19 +96,19 @@ trips and renders, checked by tests, not against After Effects), **partial** (na
 | Mocha shapes | R (Mocha AE) | own documented JSON | — | Mocha's format is not public |
 | Vanishing Point `.vpe` | R | none | — | no public specification; the menu entry explains why |

-## Render queue outputs (`OutputFormat::ALL`, 13)
+## Render queue outputs (`OutputFormat::ALL`, 14)

 H.264 MP4, HEVC MP4, AV1 MP4, ProRes MOV, uncompressed 8-bit RGB / RGB + Alpha MOV (`raw `, + PCM;
-#372), WebM (VP9 or AV1 + Opus), PNG / JPEG / TIFF / OpenEXR sequences, animated GIF, WAV, AIFF.
+#372), WebM (VP9 or AV1 + Opus), PNG / JPEG / TIFF / OpenEXR / Targa sequences, animated GIF, WAV, AIFF.
 Missing against After Effects + Media Encoder: 16-bpc uncompressed, AVI and lossless-compressed
-single-file video (Animation / PNG codecs), DPX / Targa / Photoshop sequences, MXF, DNxHR, hardware
+single-file video (Animation / PNG codecs), DPX / Photoshop sequences, MXF, DNxHR, hardware
 encoders ([hardware-parity.md](hardware-parity.md)), and rendering safely over an existing file
 (#325).

 ## Estimate

 **≈ 130–230 h**: `.aep` / `.aepx` import 80–160 h (after the owner decision), wiring TGA / DPX /
-HDR / MXF / AVI / DNx import and DPX/TGA output 10–20 h, FBX animation and skinning, USD and Substance 20–40 h,
+HDR / MXF / AVI / DNx import and DPX output 10–20 h, FBX animation and skinning, USD and Substance 20–40 h,
 relinking 6–12 h, `.mogrt`-compatible templates 15–30 h (partly parallel with the rest).

 ## Revision history
@@ -133,6 +133,12 @@ The most important missing piece: it turns every other estimate here into a meas
  the prompt, with their layers, in one undo step, for single items, multiple selections and
  folder contents. Nothing happens with an empty selection, in other panels, while typing or with
  a dialog open, and the next Delete still asks.
+- Regression evidence for [#947](https://github.com/storytold/effectcraft/issues/947): the
+  preview startup tests in `ui_audio_scrub`, checked headlessly on Windows with a fake output
+  device, start an audible preview on an uncached comp. The playhead holds the first frame until
+  the frames ahead are cached, the sound starts at that frame (from 0 s and from 1 s, also for a
+  30 s work area), and a tone lasting only the first 100 ms reaches the output. Video off still
+  starts at once, no device plays the picture, and Stop while preparing leaves nothing playing.
 - Regression evidence for [#612](https://github.com/storytold/effectcraft/issues/612): the
  `ui_gradient_value` and `ui_gradient_editor` input tests, checked headlessly on Windows, open
  the Gradient Editor from the Timeline's "Edit Gradient…" on a shape layer's Gradient Fill. They
@@ -22,10 +22,10 @@ interface; Arabic and Hebrew text *in layers* is supported through its Middle Ea
  or on a repeated row. The generated Effect menu is not part of that fixed tree: its entries
  and category submenus take their labels from the effect catalog below.
 - **Panels, dialogs, buttons, tooltips:** `crates/ui-egui/src/i18n/ui.rs`, keyed by the English
-  source string, with English fallback. Catalogs exist for Japanese (410 rows), Simplified and
-  Traditional Chinese (506 each), Ukrainian (505), Brazilian Portuguese (400) and Czech (501);
-  counted at 470ea7a3. Georgian has every row the Chinese catalogs have at this revision (695, as
-  both Chinese catalogs now have), plus 191 for panels converted to the catalog.
+  source string, with English fallback. Catalogs exist for Japanese (693 rows), Simplified and
+  Traditional Chinese (695 and 648 since #2244 pruned the Traditional one), Ukrainian (524),
+  Brazilian Portuguese (695) and Czech (518), counted at this tree. Georgian has every row the
+  Simplified Chinese catalog has, plus 191 for panels converted to the catalog.
 - **Effect names:** `crates/ui-egui/src/i18n/effects.rs`, keyed by **effect id**, in Simplified
  Chinese and Georgian (307 rows, one per effect in the registry, plus its 21 categories). The registry's
  English name stays the effect's identity: `effect.list`, `effect.apply {"effect": …}`, scripts
@@ -71,14 +71,14 @@ the true percentages are slightly lower.
 | Language | Code | UI strings translated | Dialogs / tooltips / help | Script support | Native review | Status | To `full` |
 |---|---|---|---|---|---|---|---|
 | English | `en` | ≈ 3,900 (100%, source) | All; docs in English | — | yes | full | — |
-| Simplified Chinese | `zh-hans` | 1,130 (≈ 29%): menus 624 rows, panels 506 | Panels and dialogs partly; no help, effect names translated (306) and their parameter names not; Home screen literals unwrapped (#574, closed) | System CJK fallback; Han follows the UI language; CJK text in comps renders wrongly (#453); IME in text layers | no | partial | 6–9 h + review |
-| Spanish | `es` | 624 (≈ 16%) | Menus only (panel catalog in open PR #996) | Latin, fine | no | menus only | 7–10 h + review |
+| Simplified Chinese | `zh-hans` | 1,324 (≈ 34%): menus 629 rows, panels 695 | Panels and dialogs at the zh source list; no help, effect names translated (307) and their parameter names not; Home screen literals unwrapped (#574, closed) | System CJK fallback; Han follows the UI language; CJK text in comps renders wrongly (#453); IME in text layers | no | partial | 6–9 h + review |
+| Spanish | `es` | 1,142 (≈ 29%): menus 629 rows, panels 513 | Menus only; the panel catalog from #996 | Latin, fine | no | partial | 9–12 h + review |
 | Hindi | `hi` | 0 | — | UI: Devanagari fallback font but no shaping; text layers shape Devanagari | no | none (After Effects: none) | 9–13 h + shaping in the UI |
 | Arabic | `ar` | 0 | — | UI: Arabic fallback font but no shaping and no RTL layout; text layers: bidi + shaping | no | none (After Effects: none) | 9–13 h + 15–25 h RTL UI |
 | French | `fr` | 624 (≈ 16%) | Menus only | Latin, fine | no | menus only | 7–10 h + review |
-| Portuguese (Brazil) | `pt-br` | 1,024 (≈ 26%): menus 624 rows, panels 400 | Panels and dialogs partly | Latin, fine | no | partial | 6–9 h + review |
+| Portuguese (Brazil) | `pt-br` | 1,324 (≈ 34%): menus 629 rows, panels 695 | Panels and dialogs at the Chinese catalogs' source list; the six keys main added after that count are translated too; AI-assisted, not yet native-speaker proofread | Latin, fine | no | partial | independent native review |
 | Indonesian | `id` | 0 | — | Latin, fine | no | none (After Effects: none) | 8–12 h + review |
-| Japanese | `ja` | 1,034 (≈ 27%): menus 624 rows, panels 410 | Panels and dialogs partly | Japanese system fallback; vertical text and Tate-Chu-Yoko in text layers; IME | no | partial | 6–9 h + review |
+| Japanese | `ja` | 1,322 (≈ 34%): menus 629 rows, panels 693 | Panels and dialogs partly | Japanese system fallback; vertical text and Tate-Chu-Yoko in text layers; IME | no | partial | 6–9 h + review |
 | German | `de` | 624 (≈ 16%) | Menus only (open PR #666 adds interface translations) | Latin, fine | no | menus only | 7–10 h + review |
 | Korean | `ko` | 0 | — | Hangul fallback probe added (#599, closed); not checked on macOS here | no | none | 9–13 h + review |
 | Vietnamese | `vi` | 0 | — | Latin with stacked diacritics; untested | no | none (After Effects: none) | 8–12 h + review |
@@ -87,16 +87,17 @@ Other languages EffectCraft ships (4):

 | Language | Code | UI strings translated | Status | To `full` |
 |---|---|---|---|---|
-| Traditional Chinese | `zh-hant` | 1,130 (≈ 29%): menus 624 rows, panels 506 | partial | 6–9 h + review |
-| Ukrainian | `uk` | 1,129 (≈ 29%): menus 624 rows, panels 505 | partial | 6–9 h + review |
-| Czech | `cs` | 1,125 (≈ 29%): menus 624 rows, panels 501 | Existing catalog entries covered; unwrapped UI, effects and engine text still in English; AI-assisted, not yet native-speaker proofread | Remaining strings + independent native review |
+| Traditional Chinese | `zh-hant` | 1,277 (≈ 33%): menus 629 rows, panels 648 | partial | 6–9 h + review |
+| Ukrainian | `uk` | 1,153 (≈ 29%): menus 629 rows, panels 524 | partial | 6–9 h + review |
+| Czech | `cs` | 1,147 (≈ 29%): menus 629 rows, panels 518 | Existing catalog entries covered; unwrapped UI, effects and engine text still in English; AI-assisted, not yet native-speaker proofread | Remaining strings + independent native review |
 | Georgian | `ka` | 1,514 (≈ 39%): menus 628 rows, panels 886 (the Chinese catalogs' 695 plus 191 Georgian-only rows: form dialogs, context menus, column headers), effect names 307 + 21 categories; native-speaker reviewed | partial | 5–8 h |

 Russian (`ru`) has a menu catalog (624 rows, ≈ 16%); After Effects also ships Italian, which EffectCraft does not (8–12 h).

-**Overall: ≈ 18%**, the average coverage of After Effects' 10 non-English languages
-(Simplified and Traditional Chinese 29%, Japanese 27%, Brazilian Portuguese 26%, Spanish, French,
-German and Russian 16%, Korean and Italian 0%; 175 / 10, was ≈ 12% on 10 October). This is the localization row in
+**Overall: ≈ 21%**, the average coverage of After Effects' 10 non-English languages
+(Simplified Chinese, Traditional Chinese, Japanese and Brazilian Portuguese 34%, Spanish 29%,
+French, German and Russian 16%, Korean and Italian 0%; 212 / 10, was ≈ 12% on 10 October;
+Ukrainian (≈ 29%) and Czech (≈ 29%) are EffectCraft-only and stay out of that average). This is the localization row in
 [target-app-parity.md](target-app-parity.md#by-dimension).

 **Effort.** One-time work first: route parameter names and engine messages through
@@ -111,6 +112,7 @@ can give; only Georgian, contributed by a native speaker (#1843), has had it.

 | Date | Change | Summary |
 |---|---|---|
+| 2026-10-18 | minor | Brazilian Portuguese completes its panel catalog (278 new rows, 417 → 695, the Chinese catalogs' source list); the doc recount closes the drift the batch merges left in every language's panel count; AI-assisted, not yet native-speaker proofread |
 | 2026-10-12 | minor | Recounted: Russian, French, German and Czech menus (#873, #987), Brazilian Portuguese and Czech panels (#830, #987), Hangul probe (#599); overall ≈ 12% to ≈ 18%; Korean and Italian still absent |
 | 2026-10-14 | minor | Georgian (`ka`): menus 628, panels 886 (191 Georgian-only, in `GEORGIAN_PANELS`), effect names and categories in `effects.rs` |
 | 2026-10-10 | major | First localization parity document: catalog rows counted for all six languages, the twelve-language table, After Effects' 11 shipped languages from its bundle |
@@ -12,12 +12,12 @@ Guide):
 | After Effects | EffectCraft | |
 |---|---|---|
 | Effect plug-ins (C/C++ SDK, `.aex` / `.plugin`) | [Effect plug-ins](#effect-plug-ins): WebAssembly modules (plug-in API v1) or Rust; the `Plug-ins` folder next to the settings loads at start-up | Different ABI: After Effects SDK plug-ins can't run (G8) |
-| Scripts folder: its scripts are listed in File ▸ Scripts | `Scripts/` in the settings folder (File ▸ Scripts ▸ Install Script File… copies a script there), listed in File ▸ Scripts with the bundled samples | Same |
+| Scripts folder: its scripts are listed in File ▸ Scripts | `Scripts/` in the settings folder (File ▸ Scripts ▸ Install Script File… copies a script there), listed in File ▸ Scripts with the bundled samples; a subfolder (one level) is a submenu named after it | Same |
 | File ▸ Scripts ▸ Run Script File… (`.jsx`, `.jsxbin`) | `.jsx` / `.js` | Gap: `.jsxbin` (an undocumented binary encoding) |
 | File ▸ Scripts ▸ Recent Script Files: the 10 most recently run scripts; Cmd+Option+Shift+D (Ctrl+Alt+Shift+D on Windows) reruns one | File ▸ Scripts ▸ Recent Script Files lists the 10 scripts run last (script files and File ▸ Scripts entries, newest first, kept in the settings); Cmd+Alt+Shift+D runs the most recent one again (`file.runScript {"recent": 0}`, a key that can be changed in Edit ▸ Keyboard Shortcuts) | Same |
 | ExtendScript preprocessor directives (`#include`, `#target`, `#targetengine`) | `#include` / `//@include` / `#includepath` inline files relative to the script (once each, depth-limited, file gate applies); `#target`, `#targetengine`, `#strict` are ignored | Same |
 | `Scripts/Startup` and `Scripts/Shutdown`: run in alphabetical order when the app starts and quits | Not run | Gap |
-| `Scripts/ScriptUI Panels`: listed at the bottom of the Window menu, dockable like the app's own panels, `this` is the panel | `Scripts/ScriptUI Panels/` in the settings folder (File ▸ Scripts ▸ Install ScriptUI Panel… copies one there), listed at the bottom of the Window menu, docked like any panel, `this` is the panel; the panels open when the app quits open again at the next launch | Same. Where a panel was docked isn't kept: workspace layouts aren't saved between launches |
+| `Scripts/ScriptUI Panels`: listed at the bottom of the Window menu, dockable like the app's own panels, `this` is the panel | `Scripts/ScriptUI Panels/` in the settings folder (File ▸ Scripts ▸ Install ScriptUI Panel… copies one there), listed at the bottom of the Window menu (a subfolder, one level, is a submenu named after it), docked like any panel, `this` is the panel; the panels open when the app quits open again at the next launch | Same. Where a panel was docked isn't kept: workspace layouts aren't saved between launches |
 | Keyboard shortcuts for scripts (the Keyboard Shortcuts editor lists the scripts of the Scripts folder) | Shortcuts bind to commands and menu entries; the File ▸ Scripts and Window menu entries of scripts aren't offered | Gap |
 | Running a script from the command line (`afterfx -r script.jsx`) | `effectcraft-cli script`, the control channel's and MCP's `script.run` | Same purpose, other entry points |
 | `app.settings` (kept in the preferences between sessions) | Kept in `script_settings.json` in the settings folder (`script.settings.get` / `script.settings.save`) | Same |
@@ -41,6 +41,11 @@ journaled and the same as the UI's action. The `effectcraft-script` crate's docs
  folder). It is listed in File ▸ Scripts at once (After Effects asks for a restart).
 * `file.scripts.list` lists installed and bundled scripts and panels; `file.runScript {name}` runs
  one; `file.uninstallScript {name}` removes an installed one.
+* A subfolder of `Scripts/` is a submenu of File ▸ Scripts named after the folder, and its scripts
+  are named `Folder/File.jsx` in `file.scripts.list` and `file.runScript`. One level of folders is
+  listed; deeper folders are not. `file.uninstallScript` removes only scripts at the top of the
+  Scripts folders: delete a script in a subfolder yourself. A subfolder may be a link to another
+  folder (an extension's own), and uninstall never deletes a file through it.

 ## ScriptUI panels

@@ -52,6 +57,13 @@ other panel. Closing the tab closes the panel (its `onClose` runs). Panels open
 quits open again at the next launch (`window.restoreScriptPanels`, which the desktop and web apps
 run at start-up; the list is `scriptui_panels.json` in the settings folder).

+To group panels, for example the several panels of one extension, make a subfolder of
+`Scripts/ScriptUI Panels/` and put them in it: `Scripts/ScriptUI Panels/My Tools/Animate.jsx` is
+listed as Window ▸ My Tools ▸ Animate.jsx, its tab is titled Animate, and commands name it
+`My Tools/Animate.jsx` (`window.scriptPanel {name}`). One level of folders is listed. Install
+ScriptUI Panel… copies a panel to the top of the folder; make the subfolder and move panels into it
+yourself, and delete them from it yourself too.
+
 Run from File ▸ Scripts instead, the same script gets no panel, so it should make a floating
 palette itself. A minimal panel:

@@ -22,7 +22,7 @@ our own scripts; no real-world script library has been run against both apps.
 | `$.evalFile`, `BridgeTalk` | Evaluate another script file; identify the host application and message other Adobe applications | `$.evalFile` evaluates a file relative to the calling file (nested at most 32 deep, under the scripts' file gate) and returns its last value; `BridgeTalk` names the host honestly (`appName` `effectcraft`, its version); messaging other applications throws "not supported" | partial | `tests_evalfile.rs` (#760); no inter-application messaging |
 | ScriptUI | Dialogs, palettes, dockable panels, resource strings, `onDraw` / ScriptUIGraphics, mouse events | Same, dockable panels reopen at launch | good | `ui_scriptui`, `tests_ui*` |
 | `app.scheduleTask` / `cancelTask` | One-shot and repeating tasks (polling, panel refresh) until `cancelTask` | Same: repeating tasks run every `delay` ms (at least 50 ms, at most 64 pending per script) until `cancelTask`, until they throw (reported once, then cancelled), or until their owner goes: a script's last window closing, or the project closing for scripts without windows; frontends tick them every frame, agents with `script.runTasks` | good | `tests_tasks.rs` (#773); one-shot tasks of a script file still run right after it, not after their delay |
-| Scripts menu, ScriptUI Panels folder | yes | yes | same | [plugins.md](plugins.md) |
+| Scripts menu, ScriptUI Panels folder | yes | yes; a subfolder (one level) of either folder is a submenu named after it | same | [plugins.md](plugins.md) |
 | Startup / Shutdown folders | yes | not run | missing | plugins.md |
 | `#include`, `#target` directives | yes | `#include` / `//@include` / `#includepath` inline files relative to the including script (once each, nested at most 32 deep, under the scripts' file gate; errors name the included file and line); `#target`, `#targetengine`, `#strict` are ignored | good | `tests_include.rs` (#759); installed scripts and panels have no folder of their own, so they include from the project's folder or absolute paths |
 | `.jsxbin` | yes | no | out of scope | No public specification |
@@ -0,0 +1,64 @@
+# User docs: rules for agents and contributors
+
+Everything in this folder (except this file, CLAUDE.md and README.md) is published at
+https://getartcraft.com/docs/effectcraft. The file path is the URL:
+`troubleshooting/gpu-not-used.md` → `/docs/effectcraft/troubleshooting/gpu-not-used`.
+Renaming a file breaks links, so add the old path to `redirect_from` when you rename.
+
+## Who reads this
+
+Artists using EffectCraft, Discord mods answering them, and AI assistants looking things up for
+either. Write for an artist, not a developer.
+
+## Page rules
+
+- One question or problem per page. Lead with the answer or the fix in the first two lines.
+- Plain words, short sentences, numbered steps for anything the reader does.
+- Start the body at `##`. The page title comes from frontmatter.
+- Link to other pages instead of repeating them. Use relative links to the `.md` file:
+  `[Install EffectCraft](../getting-started/install.md)`.
+- No marketing copy, no "simply", no claims you have not checked in the code, a release or an issue.
+- Call the product "EffectCraft", as the app, its downloads and getartcraft.com do.
+- Name UI labels exactly as the app shows them, in **bold**. Menu paths use the menu text from
+  `crates/engine/src/menus.rs`.
+- Shortcuts: the code writes `Cmd`, which is Ctrl on Windows and Linux. Write Ctrl for Windows.
+- Windows 11 is the only Windows version to name.
+- Troubleshooting pages: `## Symptoms`, `## Fix`, `## Why this happens` (optional),
+  `## Still stuck?` (link the issue tracker or Discord).
+
+## Frontmatter
+
+    ---
+    title: EffectCraft does not use my graphics card
+    description: One sentence for search results, link previews and AI summaries.
+    order: 10                 # optional, sorts within the folder (lower first)
+    verified: 0.8.0           # optional, app version you last checked this page against
+    redirect_from: [old/path] # optional, old URLs (relative to /docs/effectcraft)
+    ---
+
+Only `key: value` and `key: [a, b]` lines work. Quote values that start with a quote or contain ` #`.
+
+Set `verified` to the latest release (the newest release tag) after checking the page against that tag with `git show <tag>:<path>`. Pages describe the latest release users download, not unreleased code on main.
+
+## Folders
+
+- `getting-started/` install and first run
+- `guides/` how to do one thing
+- `troubleshooting/` symptom → fix
+- `faq/` short answers
+- `reference/` lists and settings
+
+A folder's `index.md` names the folder in the sidebar. Files or folders starting with `_` are
+drafts and are not published.
+
+## Check before you push
+
+    node <path to your artcraft-services checkout>/frontend/apps/artcraft-website-next/scripts/docs/core.mjs docs/user
+
+The checker lives in storytold/artcraft-services. A CI check will be added once it is on that repo's main branch.
+
+## Support PRs
+
+Pages written to answer a user question come in as PRs titled `docs(support): <page title>`.
+Review them like code: check every claim against the source. Problems and bug reports go in the
+[issue tracker](https://github.com/storytold/effectcraft/issues).
@@ -0,0 +1 @@
+Read `AGENTS.md` in this folder: it has the rules for the user docs.
@@ -0,0 +1,22 @@
+---
+title: Can EffectCraft open After Effects projects?
+description: EffectCraft cannot open .aep or .aepx files, and After Effects plug-ins do not run. It saves .ecproj files and imports Lottie.
+order: 10
+verified: 0.9.2
+---
+
+No. EffectCraft cannot open After Effects projects (`.aep` or `.aepx`), and After Effects plug-ins do not run in it.
+
+## What it opens instead
+
+- Its own projects, saved as `.ecproj`. These are readable, versioned JSON files.
+- Lottie animations, with **File ▸ Import ▸ Lottie...**. Each opens as a new composition.
+- Photoshop and PDF or Illustrator files, imported as footage or as a composition. See [Import footage and image sequences](../guides/import-footage.md).
+
+## What carries over
+
+Expressions are JavaScript with the After Effects object model, such as `wiggle`, `loopOut` and `thisComp.layer("...")`. The panels, shortcuts and effect parameter names follow After Effects, so the skills carry over.
+
+## Status
+
+Reading `.aep` files is the largest known gap between EffectCraft and After Effects. It is listed in the project's [gap list](https://github.com/storytold/effectcraft/blob/main/docs/gaps.md), and the maintainers have not yet decided how to approach it.
@@ -0,0 +1,8 @@
+---
+title: FAQ
+description: Short answers about EffectCraft.
+order: 40
+---
+
+- [Can EffectCraft open After Effects projects?](after-effects-projects.md)
+- [Is EffectCraft free, and where does it run?](price-and-platforms.md)
@@ -0,0 +1,24 @@
+---
+title: Is EffectCraft free, and where does it run?
+description: EffectCraft is free and open source under MIT or Apache-2.0, and runs on Windows, macOS, Linux and in the browser.
+order: 20
+verified: 0.9.2
+---
+
+Yes, EffectCraft is free. It is open source, dual-licensed under MIT or Apache-2.0, at your option. It has no telemetry, and it uses no network access unless you ask for it.
+
+## Where it runs
+
+| Platform | Builds                                                                                 |
+|----------|----------------------------------------------------------------------------------------|
+| Windows  | x64, arm64 and 32-bit x86, as MSI installers and portable zips                         |
+| macOS    | One universal app for Apple silicon and Intel                                          |
+| Linux    | x86_64 and aarch64 as AppImage, Flatpak, deb, rpm and tar.gz; riscv64 deb, rpm, tar.gz |
+| FreeBSD  | x86_64 tar.gz                                                                          |
+| Browser  | A web build that runs the full app                                                     |
+
+See [Install EffectCraft](../getting-started/install.md) for the files.
+
+## How mature is it?
+
+EffectCraft is in alpha. The README calls macOS the most tested platform, and says Linux and Windows users have hit basic interaction bugs that are being fixed first. Bug reports in the [issue tracker](https://github.com/storytold/effectcraft/issues) are the most useful thing you can send.
@@ -0,0 +1,8 @@
+---
+title: Getting started
+description: Install EffectCraft and make your first composition.
+order: 10
+---
+
+- [Install EffectCraft](install.md)
+- [Make your first composition](../guides/make-a-composition.md)
@@ -0,0 +1,58 @@
+---
+title: Install EffectCraft
+description: Download EffectCraft for Windows 11, macOS or Linux, install it, or install it through ArtCraft Launcher.
+order: 10
+verified: 0.9.2
+---
+
+The easiest way is the [EffectCraft page on getartcraft.com](https://getartcraft.com/apps/effectcraft). For a specific file, use the [latest release](https://github.com/storytold/effectcraft/releases/latest) on GitHub. In the file names, `<version>` stands for the version number, for example `0.9.2`.
+
+## Windows 11
+
+1. Open the [latest release](https://github.com/storytold/effectcraft/releases/latest).
+2. Download `effectcraft-<version>-windows-x64.msi`. It fits most PCs (Intel and AMD, 64-bit).
+3. Run the file and follow the installer. It asks where to install EffectCraft and offers a **Create a desktop shortcut** box.
+4. Start **EffectCraft** from the Start menu.
+
+The release also has an `arm64` installer for Snapdragon and other ARM PCs. The installers are code-signed and install for all users. Later versions install into the same folder.
+
+To run it without installing, download `effectcraft-<version>-windows-x64-portable.zip` instead. It contains `effectcraft.exe` and the command-line tool `effectcraft-cli.exe`. The `arm64` build has a portable zip too.
+
+There are also 32-bit `x86` builds, as an installer and a portable zip.
+
+## macOS
+
+1. Download `effectcraft-<version>-macos-universal.dmg`. It works on Apple silicon and Intel Macs and is signed and notarized.
+2. Open it and drag EffectCraft to Applications.
+
+The command-line tool is a separate download for macOS: `effectcraft-cli-<version>-macos-universal.zip`.
+
+## Linux
+
+Pick one file from the release. Replace `x86_64` with `aarch64` on ARM.
+
+| File                                          | How to use it                            |
+|-----------------------------------------------|------------------------------------------|
+| `effectcraft-<version>-linux-x86_64.AppImage` | Run `chmod +x` on the file, then run it. |
+| `effectcraft-<version>-linux-x86_64.deb`      | For Debian and Ubuntu.                   |
+| `effectcraft-<version>-linux-x86_64.rpm`      | For Fedora, RHEL and openSUSE.           |
+| `effectcraft-<version>-linux-x86_64.flatpak`  | `flatpak install --user <file>`          |
+| `effectcraft-<version>-linux-x86_64.tar.gz`   | Unpack it anywhere.                      |
+
+For RISC-V 64-bit there is a `.deb`, an `.rpm` and a `.tar.gz` (`riscv64` in the file name). They need glibc 2.39 or newer. There is also a FreeBSD x86_64 `.tar.gz`.
+
+## In the browser
+
+`effectcraft-web-<version>.zip` is the web build. It is a static site that runs in a modern browser and needs to be hosted on a web server. Projects, media and settings stay in the browser's private storage and on your computer.
+
+## Install through ArtCraft Launcher
+
+ArtCraft Launcher lists EffectCraft. Click **Install** on its card. See [Install and update Craft apps](https://getartcraft.com/docs/craft-launcher/guides/install-and-update-apps).
+
+## Check the download
+
+`SHA256SUMS.txt` on the release page lists a checksum for every file.
+
+## Next
+
+Open EffectCraft and make something: [Make your first composition](../guides/make-a-composition.md). If you only want to look around, choose **Open Demo Project** on the Home screen.
@@ -0,0 +1,35 @@
+---
+title: Add an effect
+description: Apply an effect such as Gaussian Blur to a layer and change its settings in Effect Controls.
+order: 30
+verified: 0.9.2
+---
+
+Select a layer, then choose the effect from the **Effect** menu, or double-click it in the **Effects & Presets** panel. Change its settings in **Effect Controls** (F3).
+
+Shortcuts on this page use Ctrl. On macOS, use Cmd instead of Ctrl.
+
+## Steps
+
+1. Select a layer in the Timeline.
+2. Apply an effect in one of two ways:
+   - Choose it from the **Effect** menu. Effects are grouped by category, for example **Effect ▸ Blur & Sharpen ▸ Gaussian Blur**.
+   - Open **Window ▸ Effects & Presets** (Ctrl+5). Type in the search field, then double-click the effect. Dragging it onto a layer works too.
+3. Open **Window ▸ Effect Controls** (F3), or choose **Effect ▸ Effect Controls**. The effect's settings are listed there. **Gaussian Blur** has **Blurriness**, **Blur Dimensions** and **Repeat Edge Pixels**.
+4. Change a value. Click the stopwatch beside it to animate it, as in [Animate with keyframes](animate-with-keyframes.md).
+
+If no layer is selected when you double-click an effect, EffectCraft shows **Select a layer to apply to**. Select a layer and try again.
+
+## Remove or reuse effects
+
+- **Effect ▸ Last Effect** applies the effect you used last.
+- **Effect ▸ Remove All** takes every effect off the selected layers.
+- In **Effects & Presets**, click the star on an effect to add it to Favorites. Recently used effects are listed too.
+
+## Layer styles
+
+For drop shadows, glows and bevels, use **Layer ▸ Layer Styles**. It lists **Drop Shadow**, **Inner Shadow**, **Outer Glow**, **Inner Glow**, **Bevel and Emboss** and **Satin**, among others.
+
+## Next
+
+[Render a video](render-a-video.md).
@@ -0,0 +1,35 @@
+---
+title: Animate with keyframes
+description: Fly a layer in with two Position keyframes and smooth the motion with Easy Ease.
+order: 20
+verified: 0.9.2
+---
+
+Click the stopwatch beside a property to start animating it, move the current-time indicator, then change the value. The second keyframe appears by itself. Select both keyframes and press F9 to ease the motion.
+
+You need a composition with a layer. See [Make your first composition](make-a-composition.md).
+
+Shortcuts on this page use Ctrl. On macOS, use Cmd instead of Ctrl and Option instead of Alt.
+
+## Steps
+
+1. In the Timeline, twirl the layer open, then open **Transform**.
+2. Set the starting value. For a layer that flies in from the left, scrub or type a **Position** that is outside the frame.
+3. Click the stopwatch beside **Position**. It turns blue and records a keyframe at the current time.
+4. Drag the blue current-time indicator to about 0:00:01:00, or click in the time ruler.
+5. Drag the layer to its final place in the Composition viewer, or scrub the **Position** value. Because the stopwatch is on, a second keyframe appears by itself.
+6. Select both keyframes (drag a box around them, or click the **Position** name) and press F9. This is **Animation ▸ Keyframe Assistant ▸ Easy Ease**. The layer now glides in and settles.
+7. Press the Spacebar, or use Play in the Preview panel, to watch it. Press it again to stop.
+
+## Other things you can do
+
+- Click the keyframe button in the layer's property row to add or remove a keyframe at the current time. Its tooltip reads **Add or remove keyframe**.
+- Choose **Animation ▸ Keyframe Assistant ▸ Easy Ease In** (Shift+F9) or **Easy Ease Out** to ease one side only.
+- Choose **Animation ▸ Toggle Hold Keyframe** for a keyframe that jumps instead of moving.
+- Choose **Animation ▸ Keyframe Interpolation...** or **Keyframe Velocity...** to set the curve exactly.
+- Hold Alt and click a stopwatch to add an expression.
+- The Graph Editor shows value and speed graphs with draggable handles.
+
+## Next
+
+[Add an effect](add-an-effect.md).
@@ -0,0 +1,49 @@
+---
+title: Import footage and image sequences
+description: Bring video, images and numbered image sequences into an EffectCraft project, and change how footage is read.
+order: 50
+verified: 0.9.2
+---
+
+Choose **File ▸ Import ▸ File...** (Ctrl+I) and pick your files, or drop files on the EffectCraft window. Numbered stills such as `shot_0001.png` can import as one sequence that plays like a movie.
+
+Shortcuts on this page use Ctrl. On macOS, use Cmd instead of Ctrl and Option instead of Alt.
+
+## Import files
+
+1. Choose **File ▸ Import ▸ File...** to pick one file. Use **File ▸ Import ▸ Multiple Files...** to pick several.
+2. Photoshop and PDF or Illustrator files first ask whether to import them as footage or as a composition.
+3. The footage appears in the Project panel. Drag it onto the Composition viewer to make a layer where you drop it, or into the Timeline. If no composition is open, dropping it on the empty viewer makes a new composition from it.
+
+You can also drop files or folders on the window. Files dropped on the Composition viewer become layers there. A dropped Photoshop file asks how to import it, as **File ▸ Import ▸ File...** does. The **Media Browser** (**Window ▸ Media Browser**) browses folders and imports what you pick.
+
+## Import an image sequence
+
+1. Choose **File ▸ Import ▸ File...** and pick any one numbered file of the run.
+2. In the **Import Image Sequence** dialog, check the run it found. It also lists missing frames.
+3. Tick the sequence option, which is named after the file type, for example **PNG Sequence**. When it is off, the files import as separate stills. It is off by default.
+4. Set **Frame rate (fps)**. The default comes from **Sequence Footage** on the Import page of the preferences (**Edit ▸ Preferences ▸ Import...**; on macOS: **EffectCraft ▸ Settings... ▸ Import...**), which is 30 fps.
+5. Confirm. The run arrives as one footage item named like `shot_[0001-0250].png`.
+
+**Force alphabetical order** imports every image of that type in the folder in name order, whatever the numbering. Use it for files that are not numbered consistently.
+
+Stills in PNG, JPEG, TIFF, OpenEXR, BMP, WebP, Targa (`.tga`), Radiance HDR (`.hdr`), DPX and Cineon (`.cin`) can form a sequence. PSD, SVG and PDF files import one by one.
+
+If the numbering skips a frame, EffectCraft shows colour bars for it. Put the missing files in the folder and choose **File ▸ Reload Footage** to fill the gap.
+
+## Change how footage is read
+
+Select the footage in the Project panel and choose **File ▸ Interpret Footage ▸ Main...** (Ctrl+Alt+G). The dialog has **Alpha**, **Assume this frame rate** and **Start Timecode**, among others. A change applies everywhere the footage is used.
+
+For example, a 250-frame sequence at 25 fps lasts 10 seconds. At 24 fps it lasts 10.4 seconds.
+
+## Replace or reload footage
+
+- **File ▸ Replace Footage ▸ File...** (Ctrl+H) points the item at another file.
+- **File ▸ Reload Footage** (Ctrl+Alt+L) reads the files again. A sequence picks up frames added to its folder.
+
+If footage shows as missing, see [Footage is missing or offline](../troubleshooting/footage-missing.md).
+
+## Linux with Wayland
+
+Dragging files onto the window does not work on native Wayland sessions. Use **File ▸ Import ▸ File...** instead.
@@ -0,0 +1,11 @@
+---
+title: Guides
+description: Step-by-step guides for the main tasks in EffectCraft.
+order: 20
+---
+
+- [Make your first composition](make-a-composition.md)
+- [Animate with keyframes](animate-with-keyframes.md)
+- [Add an effect](add-an-effect.md)
+- [Render a video](render-a-video.md)
+- [Import footage and image sequences](import-footage.md)
@@ -0,0 +1,34 @@
+---
+title: Make your first composition
+description: Create a composition, add a text layer and save the project as an .ecproj file.
+order: 10
+verified: 0.9.2
+---
+
+Choose **Composition ▸ New Composition...**, set the size, frame rate and duration, click **OK**, then add layers from the **Layer ▸ New** menu. Shortcuts below use Ctrl on Windows and Linux. On macOS, use Cmd.
+
+## Steps
+
+1. Choose **Composition ▸ New Composition...** (Ctrl+N). On the Home screen, click **New Composition** instead.
+2. In the dialog, type a **Composition Name**. The default is `Comp 1`.
+3. Pick a **Preset**, or set **Width**, **Height**, **Frame Rate** and **Duration**. The presets include `HDTV 1080 24`, `UHD 4K 25` and `Social Media Square · 1080x1080 · 30 fps`.
+4. Click **OK**. The composition opens in the Composition panel and the Timeline.
+5. Choose **Layer ▸ New ▸ Text** and type your text. A text layer appears at the top of the Timeline, and its name follows what you type.
+6. Add more layers from **Layer ▸ New**: **Solid...**, **Shape Layer**, **Null Object**, **Adjustment Layer**, **Light...** and **Camera...**.
+7. Choose **File ▸ Save** to save the project.
+
+Projects are saved as `.ecproj` files. An `.ecproj` file is readable JSON, so it also works with version control.
+
+## Change the settings later
+
+Choose **Composition ▸ Composition Settings...** to change the name, size, frame rate or duration. The dialog has **Basic**, **Advanced** and **3D Renderer** tabs.
+
+To keep a size and frame rate for later, click the **+** button next to **Preset** (**Save Preset…**) and name it. Your presets are listed above the built-in ones, in this dialog and in **New Composition...**. To remove one, select it and click the bin button (**Delete Preset**).
+
+## Learn in the app
+
+The in-app tutorial **Animate a title** walks through a similar title animation. To open it, choose **Help ▸ In-App Tutorials...**.
+
+## Next
+
+[Animate with keyframes](animate-with-keyframes.md).
@@ -0,0 +1,52 @@
+---
+title: Render a video
+description: Add a composition to the Render Queue, choose a format such as H.264, pick where to save and click Render.
+order: 40
+verified: 0.9.2
+---
+
+Select the composition, choose **Composition ▸ Add to Render Queue** (Ctrl+M), set the output file, then click **Render** in the Render Queue panel. The default format is H.264, saved as an `.mp4` file named after the composition.
+
+Shortcuts on this page use Ctrl. On macOS, use Cmd instead of Ctrl and Option instead of Alt.
+
+## Steps
+
+1. Select the composition in the Project panel or open it.
+2. Choose **Composition ▸ Add to Render Queue** (Ctrl+M). You can also drag compositions onto the Render Queue panel. Open the panel with **Window ▸ Render Queue** (Ctrl+Alt+0).
+3. The queue lists the item with its **Comp Name**, **Status**, **Started** and **Render Time**. Twirl the item open to see **Render Settings:**, **Output Module:** and **Output To**.
+4. Click **Output Module:** and choose a format. The menu entries read **Format: H.264**, **Format: QuickTime (ProRes)** and so on.
+5. Click the file name next to **Output To** to choose where to save. Alt-click it to edit the name template instead.
+6. Check that the **Render** tick box at the left of the item is on. It is on by default, and only ticked items render.
+7. Click **Render**. The status changes to **Rendering** with a percentage. Click **Stop** to cancel.
+
+Tick **Notify** to get a sound and a notification when the queue finishes.
+
+## Formats
+
+The **Output Module:** menu lists the formats your build can export:
+
+| Menu entry               | File type                   |
+|--------------------------|-----------------------------|
+| H.264                    | `.mp4`                      |
+| QuickTime (ProRes)       | `.mov`                      |
+| QuickTime (Uncompressed) | `.mov`                      |
+| HEVC (H.265)             | `.mp4`                      |
+| AV1                      | `.mp4`                      |
+| WebM (VP9 + Opus)        | `.webm`                     |
+| PNG Sequence             | `.png`, one file per frame  |
+| JPEG Sequence            | `.jpg`, one file per frame  |
+| TIFF Sequence            | `.tif`, one file per frame  |
+| OpenEXR Sequence         | `.exr`, one file per frame  |
+| Animated GIF             | `.gif`                      |
+| WAV                      | `.wav`, audio only          |
+| AIFF                     | `.aif`, audio only          |
+
+To keep transparency, choose **Channels: RGB + Alpha** in the **Output Module:** menu. It appears for formats that can store alpha, such as QuickTime (ProRes), QuickTime (Uncompressed) and PNG Sequence. H.264, HEVC, AV1 and JPEG Sequence cannot.
+
+## Render only part of a composition
+
+Click **Render Settings:** and choose **Time Span: Work Area Only** or **Time Span: Length of Comp**. The same menu sets **Quality: Best** or **Quality: Draft** and the resolution (**Resolution: Full**, **Half**, **Third** or **Quarter**).
+
+## Export a Lottie animation instead
+
+Choose **File ▸ Export ▸ Lottie JSON...** to write a composition as `.json` or `.lottie`. EffectCraft lists anything Lottie cannot express. To open one, choose **File ▸ Import ▸ Lottie...**.
@@ -0,0 +1,36 @@
+---
+title: EffectCraft
+description: EffectCraft is a free, open-source app for motion graphics and visual effects, an alternative to Adobe After Effects.
+verified: 0.9.2
+---
+
+EffectCraft is a free, open-source app for animated titles, motion graphics and compositing. It is an alternative to Adobe After Effects.
+
+You build a composition from layers (solids, shapes, text, footage, other compositions), animate their properties with keyframes, add effects and render the result. The panels and shortcuts follow After Effects: Project, Composition, Timeline, Effect Controls, Effects & Presets and the Render Queue. It runs on macOS, Windows and Linux, and in the browser.
+
+EffectCraft is young and in alpha. It cannot open After Effects projects (`.aep`), and some things still behave differently from After Effects. See [Can EffectCraft open After Effects projects?](faq/after-effects-projects.md).
+
+## Start here
+
+- [Install EffectCraft](getting-started/install.md)
+- [Make your first composition](guides/make-a-composition.md)
+- [Animate with keyframes](guides/animate-with-keyframes.md)
+- [Add an effect](guides/add-an-effect.md)
+- [Render a video](guides/render-a-video.md)
+- [Import footage and image sequences](guides/import-footage.md)
+
+## When something is wrong
+
+- [EffectCraft does not use my graphics card](troubleshooting/gpu-not-used.md)
+- [Footage is missing or offline](troubleshooting/footage-missing.md)
+
+## Sections
+
+- [Getting started](getting-started/index.md)
+- [Guides](guides/index.md)
+- [Troubleshooting](troubleshooting/index.md)
+- [FAQ](faq/index.md)
+
+## Get help
+
+Ask in [Discord](https://discord.gg/artcraft) or open an issue in the [issue tracker](https://github.com/storytold/effectcraft/issues). Say which version and which system you use.
@@ -0,0 +1,35 @@
+---
+title: Footage is missing or offline
+description: Find missing footage in an EffectCraft project, relink it to a folder or replace it with another file.
+order: 20
+verified: 0.9.2
+---
+
+Choose **File ▸ Dependencies ▸ Relink Missing Footage...** and pick the folder where your files are now. For files that stay missing, choose **File ▸ Replace Footage ▸ File...**.
+
+Shortcuts on this page use Ctrl. On macOS, use Cmd instead of Ctrl and Option instead of Alt.
+
+## Symptoms
+
+- A footage item in the Project panel is flagged as missing after you open a project.
+- EffectCraft shows a message that footage items are missing.
+
+## Fix
+
+1. Choose **File ▸ Dependencies ▸ Find Missing Footage**. EffectCraft selects every missing item in the Project panel and shows how many it found.
+2. Choose **File ▸ Dependencies ▸ Relink Missing Footage...** and pick the folder that holds your files. EffectCraft searches that folder and its subfolders.
+3. It relinks files whose names are unique and whose type, dimensions and codec match what the project saved. The whole relink is one undo step.
+4. For anything left over, select the item and choose **File ▸ Replace Footage ▸ File...** (Ctrl+H), then pick the file yourself. This also covers files with duplicate names in the folder, which Relink leaves alone.
+5. After you copy or render files into a folder, choose **File ▸ Reload Footage** (Ctrl+Alt+L) to read them again.
+
+Relinking keeps item names, interpretation and layer timing. It does not change your files. For image sequences, every saved frame must be in the new folder. Relink Missing Footage is not available in the browser version.
+
+## Why this happens
+
+A project stores where each footage file is. If you move or rename the files, or open the project on another computer, the project cannot find them.
+
+Projects built with the command-line tool or an agent can use relative paths such as `bg.mp4`. Before 0.8.0, the app looked for those in its own working directory instead of next to the project file. Since 0.8.0 it also looks next to the project file ([pull request #676](https://github.com/storytold/effectcraft/pull/676)). The reporter on macOS has not confirmed the fix yet ([issue #652](https://github.com/storytold/effectcraft/issues/652)).
+
+## Still stuck?
+
+Ask in [Discord](https://discord.gg/artcraft) or open an issue in the [issue tracker](https://github.com/storytold/effectcraft/issues). Say which system you use, whether the project came from another computer or from the command-line tool, and where the footage is stored.
@@ -0,0 +1,42 @@
+---
+title: EffectCraft does not use my graphics card
+description: What to do when the report says GPU none (CPU compositing), the window picked another adapter, or GPU effects fail on Windows 11 with DirectX 12.
+order: 10
+verified: 0.9.2
+---
+
+Open **Help ▸ System Compatibility Report...** and read the **GPU:** and **Window graphics:** lines. If the window runs on the wrong adapter, set **Window Graphics** to **Automatic** in the preferences (**Edit ▸ Preferences ▸ Startup & Repair...**; on macOS: **EffectCraft ▸ Settings... ▸ Startup & Repair...**) and restart EffectCraft.
+
+## Symptoms
+
+- The report says `GPU: none (CPU compositing)` followed by a reason.
+- The `Window graphics:` line names an adapter or backend you did not expect, for example an integrated or OpenGL adapter instead of your graphics card.
+
+## Fix
+
+1. Choose **Help ▸ System Compatibility Report...**. Copy the text.
+2. Look at the `Window graphics:` line. If it shows the wrong adapter, continue. If it shows your card, go to **Still stuck?** below.
+3. Choose **Edit ▸ Preferences ▸ Startup & Repair...**. On macOS, choose **EffectCraft ▸ Settings... ▸ Startup & Repair...**.
+4. Set **Window Graphics** to **Automatic**. The other choice is **OpenGL (compatibility)**.
+5. Close EffectCraft and start it again. The change applies from the next launch.
+6. Open the report again and check that `Window graphics:` now names your card.
+
+One user whose GPU was not detected on 0.8.0 fixed it this way: they set the window graphics to Automatic, and EffectCraft started through Vulkan ([issue #596](https://github.com/storytold/effectcraft/issues/596)).
+
+If the window runs on your card but the report still says `GPU: none (CPU compositing)`, the reason after it says why the GPU compositor did not start. With **OpenGL (compatibility)**, compositing always runs on the CPU, because the GPU compositor needs DirectX 12, Vulkan, Metal or WebGPU.
+
+## Why this happens
+
+When the graphics driver stops EffectCraft as its window opens, the next launch switches to OpenGL by itself. That keeps the app usable. Setting **Window Graphics** to **Automatic** lets EffectCraft choose the graphics backend again.
+
+The **GPU Information...** button on the Previews page of the preferences names the adapter the GPU compositor runs on. When compositing runs on the CPU, it says why after `GPU compositing is off:`. It also shows the `Window graphics:` line. For a bug report, still send the whole System Compatibility Report.
+
+## Windows 11 with DirectX 12
+
+On some Windows 11 PCs with NVIDIA GPUs, the GPU compositor fails to start on DirectX 12 because the FXC shader compiler rejects some of EffectCraft's GPU kernels. Two users reproduced this with an RTX 4060 laptop GPU and an RTX 3060. In their tests EffectCraft fell back to CPU compositing, and the same build started on Vulkan. This is still open in 0.9.2 as [issue #613](https://github.com/storytold/effectcraft/issues/613). Check the issue for updates.
+
+The window can also take a long time to appear. On 0.8.0 with an RTX 5060 Ti, one user measured 69 seconds before the window showed on DirectX 12 without a working DXC shader compiler, against 3 seconds on Vulkan, which is what Automatic picked on that PC. If you close EffectCraft during that wait, the next launch uses OpenGL and has no GPU compositor until you set **Window Graphics** back to **Automatic** (steps above). So wait for the window on the first launch.
+
+## Still stuck?
+
+Ask in [Discord](https://discord.gg/artcraft) or open an issue in the [issue tracker](https://github.com/storytold/effectcraft/issues). Include the whole System Compatibility Report, your graphics card and driver version, and whether you also have an integrated GPU.
@@ -0,0 +1,10 @@
+---
+title: Troubleshooting
+description: Fixes for common EffectCraft problems.
+order: 30
+---
+
+- [EffectCraft does not use my graphics card](gpu-not-used.md)
+- [Footage is missing or offline](footage-missing.md)
+
+Not listed? Open an issue in the [issue tracker](https://github.com/storytold/effectcraft/issues) or ask in [Discord](https://discord.gg/artcraft). Include the text from **Help ▸ System Compatibility Report...**.
				`@@ -0,0 +1 @@`
				Read `AGENTS.md` in this folder: it has the rules for the user docs.