Skip to content

Commit 6dfd3fa

Browse files
committed
feat(effects): shader effects in the document, and the agent tools
Agent-written shader effects (docs/shader-effects.md), the document half: where an effect lives, how agents write and re-read it, and what the compositor receives. Stacked on the contract v1 PR. - Schema: `shaderEffects` (definitions: WGSL code, name, description, contract, declared params, cached cost) and `shaderEffectRanges` (clip-anchored regions with their values, target and lane). Optional, like `vocabulary`: a document without effects carries neither key. - `RegionKind` gains "shaderEffect" through the whole modifier pipeline, so an effect moves, trims and goes with its clip. A definition goes with its last region. - Tools: addEffect (writes and poses, or reuses by effectId), setEffect, setEffectDefinition, getEffect; removeModifier removes a region. The compositor checks the code first (checkShaderEffect, wired for 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. - The scene gets each fragment with its definition, normalised values and the whole pill's span on the programme clock, so `ctx.region` runs across a cut. - MCP: the resource openscreen://effects/contract holds the full contract and two examples; a test keeps it in step with the prelude and a Rust test compiles its examples. - `openscreen info` counts effects; a workbench scenario (ripple on click) and document invariants for effects; the demo skill and the architecture docs say how it works.
1 parent 3b49358 commit 6dfd3fa

33 files changed

Lines changed: 1689 additions & 41 deletions

‎crates/compositor/src/shader_fx.rs‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -852,6 +852,33 @@ mod tests {
852852
assert_eq!((r.frame_reads, r.tier), (1, Tier::Light));
853853
}
854854

855+
/// The examples agents read in the MCP resource (`electron/mcp/effects-contract.ts`) compile
856+
/// against this prelude, at the tier the resource promises.
857+
#[test]
858+
fn the_examples_of_the_mcp_contract_compile() {
859+
let src = include_str!("../../../electron/mcp/effects-contract.ts");
860+
let examples: Vec<String> = src
861+
.split("## Example")
862+
.skip(1)
863+
.map(|section| {
864+
section
865+
.lines()
866+
.filter_map(|l| l.strip_prefix(" "))
867+
.collect::<Vec<_>>()
868+
.join("\n")
869+
})
870+
.collect();
871+
assert_eq!(examples.len(), 2, "le ripple et la vignette");
872+
let ripple = [
873+
decl("strength", ShaderParamType::Number),
874+
decl("radius", ShaderParamType::Number),
875+
decl("duration", ShaderParamType::Number),
876+
];
877+
let vignette = [decl("depth", ShaderParamType::Number), decl("tint", ShaderParamType::Color)];
878+
assert_eq!(analyze(&examples[0], &ripple).expect("ripple").report.tier, Tier::Light);
879+
assert_eq!(analyze(&examples[1], &vignette).expect("vignette").report.tier, Tier::Light);
880+
}
881+
855882
#[test]
856883
fn the_active_regions_and_their_progress() {
857884
let mut a = test_effect(VIGNETTE, vec![], &[]);

‎docs/shader-effects.md‎

Lines changed: 29 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -78,15 +78,15 @@ export const shaderEffectSchema = z.object({
7878
id: z.string().min(1), // "fx_…"
7979
name: z.string().min(1).max(60), // ce que la pilule affiche
8080
description: z.string().max(500).default(""), // pour l'agent suivant : ce que l'effet fait
81-
contract: z.literal(1),
81+
contract: z.number().int().positive(), // pas un littéral : voir C.5
8282
code: z.string().min(1).max(65_536), // plafond technique, pas un budget (C.7)
8383
params: z.array(shaderEffectParamSchema).max(32).default([]),
8484
origin: z.enum(["agent", "user"]).default("agent"),
85-
});
85+
cost: z.object({ tier, frameReads }).optional(), // estimation du compositeur, en cache
86+
}).superRefine(/* noms uniques, min ≤ default ≤ max */);
8687

8788
export const shaderEffectRangeSchema = endGteStart(z.object({
8889
id: z.string().min(1), // "fxr_…", un par fragment
89-
groupId: z.string().min(1).optional(), // partagé par les fragments d'une même pilule
9090
startMs: z.number().nonnegative(), // cache dérivé de l'ancre, comme les zooms
9191
endMs: z.number().nonnegative(),
9292
...clipAnchorShape,
@@ -97,19 +97,23 @@ export const shaderEffectRangeSchema = endGteStart(z.object({
9797
}), "endMs", "startMs");
9898

9999
// documentSchemaShape
100-
shaderEffects: z.array(shaderEffectSchema).default([]),
101-
shaderEffectRanges: z.array(shaderEffectRangeSchema).default([]),
100+
shaderEffects: z.array(shaderEffectSchema).optional(),
101+
shaderEffectRanges: z.array(shaderEffectRangeSchema).optional(),
102102
```
103103

104104
- **`values`** ne porte que ce qui diffère du `default` de la définition. Une valeur hors bornes
105-
est ramenée dans les bornes au parse, sans erreur, comme les réglages du look.
105+
est ramenée dans ses bornes à l'écriture (les outils) et à la lecture (la scène), sans erreur.
106+
Le parse ne le peut pas : les bornes sont dans la définition, pas dans la région.
106107
- **Les `label`** sont écrits par l'agent, dans la langue de l'utilisateur, et affichés tels
107108
quels. Ils ne passent pas par l'i18n : c'est du contenu, pas de l'interface.
108-
- **`groupId`** reprend le principe du `trackId` des pistes audio. Une région coupée par un trim
109-
ou une frontière de clip reste une seule pilule. Sa progression (`ctx.region`) court sur la
110-
pilule entière, au lieu de repartir de zéro à chaque fragment.
111-
- **Une définition que plus aucune région n'utilise est retirée** à la sauvegarde. Le document ne
112-
garde pas de code mort.
109+
- **Une pilule, ce sont les fragments identiques et contigus** (`regionIdentityKey`), comme pour
110+
les zooms. Il n'y a pas de clé de groupe : une région coupée par un trim ou une frontière de
111+
clip reste une seule pilule, et sa progression (`ctx.region`) court sur la pilule entière (B.5).
112+
- **`cost`** est l'estimation du compositeur (C.7), mise en cache quand le code a été vérifié. Elle
113+
est dérivée, jamais une entrée : un code modifié la recalcule.
114+
- **Une définition que plus aucune région n'utilise est retirée** par l'édition qui a retiré sa
115+
dernière région (`removeRegion`, `mapAllRegionCollections`). Le document ne garde pas de code
116+
mort.
113117
- **Les `max` du schéma sont des plafonds techniques, pas des budgets.** Ils protègent le document
114118
(64 Ko de code, 32 paramètres, 8 lanes) et sont loin au-dessus de tout effet raisonnable. Ce que
115119
l'agent doit viser, ce sont les paliers de C.7.
@@ -146,9 +150,10 @@ ms brutes, sans ancre : elle restait en place pendant que les clips bougeaient.
146150

147151
### B.4 Persistance
148152

149-
- **Champs additifs, sans montée de `schemaVersion`.** C'est la convention d'`audioTracks` et de
150-
`vocabulary` : `.default([])`, et `z.object` qui ignore les clés inconnues. Un document écrit
151-
avant cette fonctionnalité s'ouvre tel quel.
153+
- **Champs additifs et optionnels, sans montée de `schemaVersion`.** C'est la convention de
154+
`vocabulary` : `.optional()`, et `z.object` qui ignore les clés inconnues. Un document écrit
155+
avant cette fonctionnalité s'ouvre tel quel, un document sans effet n'en porte aucune trace, et
156+
tout lecteur prend une liste absente pour vide.
152157
- **Le prix de ce choix.** Une build antérieure qui ouvre puis sauvegarde un projet perd ses
153158
effets en silence. Voir K, question 1.
154159
- **Pas dans les style presets.** Un preset porte le look du projet, jamais son contenu
@@ -500,7 +505,7 @@ lecture :
500505
"effectDefinitions": [
501506
{ "effectId": "fx_…", "name": "Ripple au clic",
502507
"description": "Une onde part de chaque clic et réfracte l'image.",
503-
"contract": 1, "lines": 22, "regions": 1, "compiles": true,
508+
"contract": 1, "lines": 22, "regions": 1,
504509
"cost": { "tier": "light", "frameReads": 4 },
505510
"params": [ { "name": "strength", "type": "number", "label": "Force",
506511
"default": 1, "min": 0, "max": 2 } ] }
@@ -512,7 +517,8 @@ lecture :
512517
- **Le code se lit par `getEffect`,** quand l'agent veut le modifier.
513518
- **`description` est écrite par l'agent** et lue par l'agent suivant. La description de l'outil
514519
l'exige : ce que l'effet fait, en une phrase, pas comment il le fait.
515-
- **`compiles`** dit si le code compile sur cette machine. `null` signifie « pas vérifié ici ».
520+
- **`cost`** est l'estimation mise en cache dans la définition. `null` signifie que rien n'a pu
521+
vérifier le code quand il a été écrit.
516522
- **`timeBaseNote`** nomme les effets parmi les régions en secondes de règle.
517523

518524
### E.3 Les retours
@@ -568,16 +574,16 @@ quatre ajouts d'une ligne, sur le modèle de `cameraSegmentation` :
568574

569575
### E.7 Le banc (workbench)
570576

571-
Deux scénarios, sur une mire avec une piste curseur :
577+
Un scénario, `effect-ripple-on-click`, sur une mire avec trois clics :
572578

573-
- **« ripple au clic ».** DSL attendu : une lecture du curseur, puis un `addEffect` qui couvre
574-
les clics. Comportement attendu : l'effet compile et le DSL le relit.
575-
- **« corrige l'effet ».** Le document porte un effet qui ne compile plus. Attendu : `getEffect`,
576-
puis un `setEffectDefinition` qui compile.
579+
- **Attendu :** un `addEffect` dont le code lit `ctx.clicks`, une région qui couvre chaque clic et
580+
la demi-seconde qui suit, et la cible `image`, puisque rien ne demande les textes.
581+
- **Pas exigé :** lire la piste du curseur. Le compositeur donne déjà les clics placés sur la
582+
sortie, c'est tout l'intérêt du contrat (C.2).
577583

578584
`documentInvariants` valide les deux nouvelles listes : chaque région pointe une définition
579-
existante, et ses `values` sont dans les bornes. Le harnais passe un validateur factice à
580-
`runChat`.
585+
existante, et ses `values` sont dans les bornes. Hors ligne, rien ne compile le code : le résultat
586+
dit `validated: false`, et les checks lisent le code comme du texte.
581587

582588
---
583589

‎electron/ai-edition/agent-tools.test.ts‎

Lines changed: 178 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -192,6 +192,7 @@ describe("the mutating-tool table", () => {
192192
"addAnnotation",
193193
"addAudio",
194194
"addCameraFullscreen",
195+
"addEffect",
195196
"addSpeed",
196197
"addTrim",
197198
"addTrims",
@@ -211,6 +212,8 @@ describe("the mutating-tool table", () => {
211212
"setAudio",
212213
"setCameraFullscreen",
213214
"setClipRange",
215+
"setEffect",
216+
"setEffectDefinition",
214217
"setEditorSettings",
215218
"setSpeed",
216219
"setTrim",
@@ -3734,3 +3737,178 @@ describe("clip structure (#1180)", () => {
37343737
});
37353738
});
37363739
});
3740+
3741+
describe("shader effects", () => {
3742+
const CODE = "fn effect(uv: vec2<f32>) -> vec4<f32> { return frame(uv) * params.level; }";
3743+
const params = [
3744+
{ type: "number", name: "level", label: "Level", default: 1, min: 0, max: 2 },
3745+
{ type: "color", name: "tint", label: "Tint", default: "#000000" },
3746+
];
3747+
// Stands in for the compositor's check: refuses `nope`, prices every effect at 4 reads.
3748+
const checkShaderEffect = (code: string) =>
3749+
code.includes("nope")
3750+
? { error: "error: no definition in scope for identifier: `nope`" }
3751+
: { tier: "light" as const, frameReads: 4, iterations: 0 };
3752+
const options = { checkShaderEffect };
3753+
const run = (document: AxcutDocument, name: string, args: unknown) =>
3754+
executeAgentTool(document, name, JSON.stringify(args), options);
3755+
const add = (document: AxcutDocument, args: Record<string, unknown> = {}) =>
3756+
run(document, "addEffect", {
3757+
startSec: 2,
3758+
endSec: 6,
3759+
effect: { name: "Dim", description: "Dims the picture.", code: CODE, params },
3760+
...args,
3761+
});
3762+
3763+
it("writes the effect and poses it, anchored, with only the values that differ", () => {
3764+
const added = add(fixtureDocument(), { values: { level: 0.5, tint: "#000000" } });
3765+
expect(added.ok).toBe(true);
3766+
const doc = added.document as AxcutDocument;
3767+
const [effect] = doc.shaderEffects ?? [];
3768+
const [range] = doc.shaderEffectRanges ?? [];
3769+
expect(effect).toMatchObject({
3770+
name: "Dim",
3771+
contract: 1,
3772+
origin: "agent",
3773+
cost: { tier: "light", frameReads: 4 },
3774+
});
3775+
expect(range).toMatchObject({
3776+
effectId: effect.id,
3777+
startMs: 2000,
3778+
endMs: 6000,
3779+
clipId: "clip_1",
3780+
values: { level: 0.5 },
3781+
target: "image",
3782+
lane: 0,
3783+
});
3784+
expect(JSON.parse(added.resultJson)).toMatchObject({
3785+
effectRegionId: range.id,
3786+
effectId: effect.id,
3787+
validated: true,
3788+
cost: { tier: "light", busiestTier: "light" },
3789+
});
3790+
expect(() => documentSchema.parse(doc)).not.toThrow();
3791+
});
3792+
3793+
it("refuses code that does not compile, with the compiler's error, and changes nothing", () => {
3794+
const refused = add(fixtureDocument(), {
3795+
effect: {
3796+
name: "Broken",
3797+
description: "",
3798+
code: "fn effect(uv: vec2<f32>) -> vec4<f32> { return nope; }",
3799+
},
3800+
});
3801+
expect(refused.ok).toBe(false);
3802+
expect(refused.document).toBeUndefined();
3803+
expect(JSON.parse(refused.resultJson).error).toMatch(/does not compile[\s\S]*nope/);
3804+
});
3805+
3806+
it("takes either a new effect or one of the project's, not both or neither", () => {
3807+
const doc = add(fixtureDocument()).document as AxcutDocument;
3808+
const effectId = doc.shaderEffects?.[0].id;
3809+
expect(run(doc, "addEffect", { startSec: 8, endSec: 9 }).ok).toBe(false);
3810+
const reused = run(doc, "addEffect", { startSec: 8, endSec: 9, effectId });
3811+
expect(reused.ok).toBe(true);
3812+
expect(reused.document?.shaderEffects).toHaveLength(1);
3813+
expect(reused.document?.shaderEffectRanges).toHaveLength(2);
3814+
});
3815+
3816+
it("keeps one lane free of overlaps, and points to another lane", () => {
3817+
const doc = add(fixtureDocument()).document as AxcutDocument;
3818+
const blocked = add(doc, { startSec: 4, endSec: 8 });
3819+
expect(blocked.ok).toBe(false);
3820+
expect(JSON.parse(blocked.resultJson).error).toMatch(/lane 0[\s\S]*another lane/);
3821+
expect(add(doc, { startSec: 4, endSec: 8, lane: 1 }).ok).toBe(true);
3822+
});
3823+
3824+
it("recommends a lighter tier when a heavy effect runs long, and never refuses it", () => {
3825+
const heavy = {
3826+
...options,
3827+
checkShaderEffect: () => ({ tier: "heavy" as const, frameReads: 100 }),
3828+
};
3829+
const added = executeAgentTool(
3830+
fixtureDocument(),
3831+
"addEffect",
3832+
JSON.stringify({
3833+
startSec: 0,
3834+
endSec: 40,
3835+
effect: { name: "Blur", description: "", code: CODE, params },
3836+
}),
3837+
heavy,
3838+
);
3839+
expect(added.ok).toBe(true);
3840+
expect(JSON.parse(added.resultJson).cost.advice).toMatch(/heavy over 40\.0 s/);
3841+
});
3842+
3843+
it("re-tunes, retargets and moves a region; a value back at its default is dropped", () => {
3844+
const doc = add(fixtureDocument(), { values: { level: 0.5 } }).document as AxcutDocument;
3845+
const regionId = doc.shaderEffectRanges?.[0].id;
3846+
const tuned = run(doc, "setEffect", {
3847+
effectRegionId: regionId,
3848+
values: { level: 1, tint: "#ff0000" },
3849+
target: "both",
3850+
startSec: 10,
3851+
endSec: 12,
3852+
});
3853+
expect(tuned.ok).toBe(true);
3854+
expect(tuned.document?.shaderEffectRanges?.[0]).toMatchObject({
3855+
startMs: 10000,
3856+
endMs: 12000,
3857+
target: "both",
3858+
values: { tint: "#ff0000" },
3859+
});
3860+
});
3861+
3862+
it("changes the definition for every region, recompiles, and drops a removed parameter's values", () => {
3863+
const doc = add(fixtureDocument(), { values: { tint: "#ff0000" } }).document as AxcutDocument;
3864+
const effectId = doc.shaderEffects?.[0].id;
3865+
const refused = run(doc, "setEffectDefinition", {
3866+
effectId,
3867+
code: "fn effect(uv: vec2<f32>) -> vec4<f32> { return nope; }",
3868+
});
3869+
expect(refused.ok).toBe(false);
3870+
const changed = run(doc, "setEffectDefinition", { effectId, params: [params[0]] });
3871+
expect(changed.ok).toBe(true);
3872+
expect(changed.document?.shaderEffectRanges?.[0].values).toEqual({});
3873+
expect(JSON.parse(changed.resultJson)).toMatchObject({ regions: 1, validated: true });
3874+
});
3875+
3876+
it("reads an effect's code by getEffect, and lists effects without it in the snapshot", () => {
3877+
const doc = add(fixtureDocument()).document as AxcutDocument;
3878+
const effectId = doc.shaderEffects?.[0].id;
3879+
const read = JSON.parse(run(doc, "getEffect", { effectId }).resultJson);
3880+
expect(read).toMatchObject({
3881+
code: CODE,
3882+
regions: [{ startSec: 2, endSec: 6, target: "image", lane: 0 }],
3883+
});
3884+
const snapshot = JSON.parse(run(doc, "getCurrentDocument", {}).resultJson);
3885+
expect(snapshot.effects).toEqual([
3886+
expect.objectContaining({ effectId, name: "Dim", startSec: 2, endSec: 6 }),
3887+
]);
3888+
expect(snapshot.effectDefinitions[0]).toMatchObject({ effectId, lines: 1, regions: 1 });
3889+
expect(snapshot.effectDefinitions[0].code).toBeUndefined();
3890+
expect(snapshot.timeBaseNote).toMatch(/effects/);
3891+
});
3892+
3893+
it("removes a region by removeModifier, and its definition with the last one", () => {
3894+
const doc = add(fixtureDocument()).document as AxcutDocument;
3895+
const removed = run(doc, "removeModifier", { id: doc.shaderEffectRanges?.[0].id });
3896+
expect(removed.ok).toBe(true);
3897+
expect(JSON.parse(removed.resultJson).kind).toBe("shaderEffect");
3898+
expect(removed.document?.shaderEffectRanges).toEqual([]);
3899+
expect(removed.document?.shaderEffects).toEqual([]);
3900+
});
3901+
3902+
it("says when nothing could check the code", () => {
3903+
const added = executeAgentTool(
3904+
fixtureDocument(),
3905+
"addEffect",
3906+
JSON.stringify({
3907+
startSec: 1,
3908+
endSec: 2,
3909+
effect: { name: "Dim", description: "", code: CODE, params },
3910+
}),
3911+
);
3912+
expect(JSON.parse(added.resultJson)).toMatchObject({ validated: false, cost: null });
3913+
});
3914+
});

0 commit comments

Comments
 (0)