feat(effects): shader effects in the document, and the agent tools

[EtienneLescot]

Summary

Second PR of agent-written shader effects (docs/shader-effects.md, section L.2): where an effect lives in the document, how agents write and re-read it, and what the compositor receives. Stacked on #1199 (contract v1 and the Windows pass): it targets that branch and will be retargeted to main once #1199 merges.

The document.

• Two optional lists, like vocabulary, so a document without effects carries neither key:
  • shaderEffects, the definitions: WGSL code, name, description, contract version, declared params, cached cost.
  • shaderEffectRanges, the regions: clip-anchored, with their values, target and lane.
• RegionKind gains "shaderEffect" across the whole modifier pipeline, so an effect moves, trims and goes away with its clip.
• A definition goes with its last region.

The tools.

• addEffect writes an effect and poses it, or reuses one by effectId. setEffect changes a region, setEffectDefinition changes an effect's code and parameters, getEffect reads one. removeModifier removes a region.
• The compositor checks the code first (checkShaderEffect), for both the MCP server and the in-app agent. A compile error comes back at the agent's line.
• Results give the cost tier, and a recommendation when a tier runs long. Never a refusal.
• One lane holds no overlap.
• getCurrentDocument lists effects and definitions without their code; getEffect gives the code.

The scene.

• Each fragment carries its definition and normalised values.
• It also carries the whole pill's span on the programme clock, so the effect's progress (ctx.region) runs across a cut.

Agents.

• The MCP resource openscreen://effects/contract holds the full contract and two examples. A TS test keeps it in step with the compositor's prelude, and a Rust test compiles its examples.
• The demo skill gains an effects entry.

Also:

• openscreen info counts effects.
• A workbench scenario, ripple on click, and document invariants for effects.
• Architecture docs: document model, timeline model, agent, MCP server, editor shell.

Not here: the macOS and Linux passes, getFrames without an export, and the editor's effect lane, which come in later PRs. Until the lane exists, an effect an agent writes renders in the preview and the export on Windows but does not show on the timeline.

Related issue

None.

Type of change

• Feature
• Documentation

Release impact

• Minor

Desktop impact

• Not platform-specific

Testing

Run and passing:

• npm run test: 4774 passed. One test in electron/mcp/media-tools.test.ts (runs one export at a time) failed under load and passes alone; that file is untouched here.
• tsc --noEmit for the app, tsconfig.test.json and tsconfig.workbench.json.
• cargo test -p openscreen-compositor --lib on Windows, including the new test that compiles the MCP contract's examples.
• New tests cover:
  • the tools (write, reuse, refuse on compile error, lane overlap, cost advice, edit, read, remove, snapshot);
  • the schema;
  • the scene projection (a trim splits a region in two fragments sharing one programme span);
  • a clip removal taking its effect and the definition along;
  • openscreen info.

Not run: npm run wb. Its config fails to load on this machine (@/lib left unresolved by Vite's config bundler). The same import chain exists on main, so this is likely not new, but I did not confirm it there. The new scenario typechecks.

🤖 Generated with Claude Code

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

• Configuration used: defaults
• Review profile: CHILL
• Plan: Advanced
• Run ID: eb5fb313-26d4-4a09-bbdd-b0df3f84556d

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[EtienneLescot]

Integrated into integration/shader-effects as 7907021: the same change, replayed on current main. GitHub closes, rather than marks merged, a PR whose head is already in its base. It reaches main through #1210.