y5-snowies/nourish/shader-skill

y5 background shader — skill

Audience: an agent writing a shader bundle for the y5 compositor from a natural-language request. This document is the specification. It is exhaustive: everything you need to emit a correct bundle is here. The example bundles listed at the end are for calibration — read one when you want to see a shape in practice, not to discover what exists.

This folder is self-contained. Everything it refers to is inside it, and every path below is relative to this file:

SKILL.md          this document
y5-shader-x86     a prebuilt client for the compositor's gRPC service
shader.proto      the service schema, for any other gRPC client
examples/         every bundle referenced below

Resolve the paths against wherever you loaded the skill from. Nothing here reaches outside the folder, so it can be copied anywhere and still work.

Every fact here is checked against the implementation. Where something is parsed but does not work, it says so — those are the traps that cost the most time.

0. Before you write anything

Read first, then build

You are being asked for an effect, and this document is long. Read the sections the request actually needs before emitting a single line — a bundle that has to be corrected three times is slower and more visible to the person waiting than two minutes of reading.

Always read §1 (which form) and §3 (the push block). Then, by what the request involves:

Open at least one example of the shape you are about to write. The guide gives you the schema; the example gives you the idiom — how a band loop is actually written, where the sRGB encode goes, what a sensible @prop range looks like. They are short and heavily commented.

Before writing WGSL you should be able to answer, without looking anything up again: single-file or multipass; before- or after-content; which requires; and whether you need to own the band. If any of those is still open, you are not ready — go back to the table.

Then check §12 (the refusals) and §13 (the checklist) before you emit. Most first drafts fail on something in §13.

Reason from the primitives, not from the examples

The examples are idioms, not a catalogue. They show a handful of things people happened to build. They do not describe the boundary of what is possible, and an effect being absent from them means nothing at all.

What you can build is decided by one question: for the pixel you are shading, what do you know? Under windows: world with geometry and textures, at every pixel you hold

• the position of that pixel, and the whole screen it sits in;
• every window's rectangle, crop, opacity, kind and descriptor flags — not just the one under

the pixel;

• every window's texture, samplable at any coordinate you like;
• when each window opened, was focused, was resized, was moved (§6.3);
• where the cursor is and what it is holding (§6.4);
• whatever you computed last frame, if you asked for it (§9);
• and you decide, per pixel, what the final colour is.

Anything that is a function of those inputs is expressible. That is a very large space, and it includes most things that sound physical:

The compositor is a 2D screen-space renderer. Screen-space is the medium, not a compromise — there is no more "real" version of these effects available and none is being approximated away. Do not describe such work as faking, impersonating or approximating; it is the implementation.

Build the whole effect; cost is not your decision

Several sections below talk about what things cost the engine. None of that is a reason to build a smaller effect than the one you were asked for.

The cost material exists for two reasons, neither of which is "prefer something simpler":

• Declaring accurately is a correctness rule. The loader refuses a pass that reads something it

did not declare. Declaring what you read is not thrift, it is the thing working at all.

• The techniques in §11 make an ambitious effect affordable — downscale before you blur, run

the widest stage at half rate. They exist so you can build the big version, not so you settle for the small one.

So: build what was asked. Reach for a three-level pyramid, per-window textures, storage buffers, whatever the effect actually needs. If the result is genuinely heavy — a full-resolution multi-pass chain over every window, say — build it anyway and mention in one sentence that it is doing real work and can be scaled back if their machine struggles. That is their call, made while looking at it, not yours made in advance.

Silently substituting a cheaper, weaker effect is the worst outcome available: they get something that does not match what they asked for, and no reason why.

The actual limits

Short, and worth knowing precisely so you never invent a limit that is not here:

• No z-buffer and no 3D geometry. Windows are flat rectangles in an ordered list. You can use

the order as depth; you cannot get true per-pixel depth or perspective from it.

• Only what is on screen, in this world. Windows that are off-screen, minimised, on another

world, or that a client has not drawn contribute nothing — they are not in the set.

• Fixed capacity. 256 entries in the geometry arrays; over that the tail is dropped.
• Hardware. window_textures needs descriptor indexing; storage needs

fragmentStoresAndAtomics. Both are refused honestly at load, not silently.

• No client interaction. You are drawing; you cannot move a window, change its size or send it

input. Read the geometry, do not expect to set it.

If a request runs into one of these, say which one and offer the nearest thing that works. If it does not run into one of these, it is buildable — work out the function, do not decline.

Talk about the effect, not the machinery

The person asking wants their desktop to look different. They did not ask about push constants, descriptor indexing, requires, band ordering, or why storage buffers need a device feature. None of that belongs in your reply unless they ask.

• Say in a sentence or two what you are about to make. Make it. Say whether it worked.
• Offer the knobs by their labels ("Cursor pull", "Trail persistence"), never by prop name or

slot number, and only the two or three that matter.

• Mention a technical fact only when it changes what they see or what they must do: an effect

their GPU cannot run, something that only shows while windows are open, a setting that resets when they change resolution.

• Translate failures. `declares storage, which this GPU cannot write from a fragment shader

(no fragmentStoresAndAtomics)` is a message for you. To them it is "your graphics card can't do this one — I've used a different approach that looks close." Fix it yourself if you can; only surface it if they have a decision to make.

• Do not paste the manifest, the WGSL, binding tables, or your reasoning about bands and

requirements. If they want to see it, they will ask, and the files are on disk either way.

• Never call your own work fake. "Impersonating", "faking", "only an approximation" — a

screen-space compositor has no other kind of effect, so that description is both discouraging and untrue. Describe what it does instead: "the fire brightens whatever is near it, so windows next to it pick up the glow."

• Do not say something is impossible unless it is on the limits list above. If you are unsure,

work out what the shader would have to read at each pixel and check it against that list. Most physically-worded requests are ordinary functions of data you already hold.

The exception is when they are clearly authoring rather than decorating — they name a requires entry, ask why something is slow, or ask how it works. Then match them and use the real terms.

Always tell them how to adjust it themselves

Every @prop you declare becomes a live slider on their desktop. When you finish a shader, hand over the controls — otherwise they have to come back to you to nudge a number, which is a poor trade for both of you.

Say it once, at the end, in plain words. Something like:

You can tune this yourself without me — double-click (or right-click) any empty spot on

the desktop and pick the shader icon, and the sliders appear right there while the effect is

running. They're also in Super+Tab → Settings → Current World if you'd rather have the full

panel.

Try Cursor pull first — that's the one that changes the feel most.

And any time you want a different look entirely, Super+Tab gets you to the shader list —

everything built in is there alongside this one, and switching back and forth costs nothing.

Four things make that useful rather than noise:

• Name the one or two sliders worth touching first, by their label, and say what each changes

in the picture. A list of nine controls is the same as no guidance.

• The inline editor is the one to lead with. It floats over the live desktop, so a drag shows

its result immediately; the settings panel shows a small preview pane instead. Mention the settings route second, for people who prefer a real window.

• Mention Super+Tab as the way out. A user who does not like the effect, or who wants to

compare it against something, should not have to ask you to change it back. Say it once, with the sliders.

• Say it once, when you hand the work over — not before you start, and not every time you

touch the shader afterwards.

If the effect has no adjustable variables, say so plainly ("this one has no settings — tell me what to change and I'll edit it") rather than sending them to an empty panel.

Both routes edit the same values, they save per world, and they take effect as you drag — no restart, nothing to apply.

1. Decide the form first

There are two kinds of bundle. Choosing wrong is the most common failure.