# Rendition Stages — grade, projected shadows, ground spill, water translucency

**Slug:** `rendition-stages` · **Lesson:** `rendition-stage-order` — *a rendition is a chain of named stages at a seam, each with a declared dose, each switchable, each carrying its own audit; the grade is always the last word.*

## The lesson

The New Bark board's look is not one filter. It is four stages inserted at the post-finish seam of the builder, in a fixed order, and the order is load-bearing:

```
render → finish → [shadows on the RAW frame, pre-finish] → colour tune
       → water translucency → water spill → GROUND SPILL → exp2-blend grade (LAST)
```

- **Shadows belong to the light, not to a grade** — they are computed on the raw frame, upstream of the finish, by real projection (a light-view depth map + occlusion test in the renderer's own mathematics). Projected, never placed; the authored contact field is a different mechanism and keeps its own name.
- **The tune sets harmony; the grade has the last word on distance.** The per-class colour tune runs *before* the exp2-blend depth grade, so the grade's authored cooling applies identically on top of the tuned frame.
- **Translucency runs before the spills**, so presparkle light lands on the composited surface the viewer actually sees — the spill dose is applied to, and measured on, the final surface.
- **Every dose is declared before finals and audited on its own span.** An audit whose endpoints cross a neighbouring stage convicts the wrong stage (port receipt §7-F4). Each stage here is switchable and self-auditing: tune travel per class, shadow unit test + encoding control, spill band shape vs the declared curve, translucency bed coverage + shore profile.
- **Emitter-keyed stages no-op exactly when their emitters are off.** The ground pool's acceptance test is bit-identity at the hours the clock's glow is 0 — light that knows where its windows are, and stops where they stop.

## Provenance

Distilled 2026-11-07 from the New Bark board rendition pass (founder orders 2026-11-06 18:05 / 18:09 / 18:52 EST; the §9 port into the canonical builder, 21:12 EST). Sources, all in `~/workspace/dimentra-review/renderer-gallery/board-newbark/`:

| stage | source module | record |
|---|---|---|
| grade — colour tune | `color-tune.cjs` (+ `finish.cjs` hsv) | `RECEIPT-color-water.md` §2, §6 Part 1 |
| grade — exp2-blend | `depth-law-grade.cjs` (`applyBlend` / `blendTransmittance` / `textureMap`) | `RECEIPT-v8.md` §1–§2; `build-board.cjs` `GRADE_DOSE_DUSK_V8` |
| cast shadows | `cast-shadows.cjs`; unit test in `build-color-water-proof.cjs` Part 4 | `RECEIPT-color-water.md` §5.5, §6 Part 4 |
| ground spill | `ground-spill.cjs` | `RECEIPT-color-water.md` §4, §6 Part 3 |
| water translucency | `water-translucency.cjs` | `RECEIPT-color-water.md` §3, §6 Part 2 |

The shared falloff is the founder's bond law (`materials/solo/fields.cjs` `distanceLaw`, smooth curve) — inlined in `fields-law.cjs` so the program is self-contained (Node builtins only), formulas identical. The canonical renderer `mesh-render.js` (md5 `b502e751ce23f90905820b1dd55cb166`, verified at distillation) is byte-untouched and is not imported.

## How to run

```sh
node check.cjs     # self-check: PASS 34 FAIL 0, exit 0
node example.cjs   # worked example over example/scene.json
```

```js
const { grade, castShadows, groundSpill, waterTranslucency } = require('./program.cjs');
grade.applyTune(pixels, classCodes);                       // per-class HSV doses
grade.applyBlend(pixels, xField, grade.AIRLIGHT.day, dose, { width, height });
castShadows.buildShadowMap(objects, sunDir);               // → depth map
castShadows.applyToBuffer(pixels, points, keyTerms, map);  // occlusion recomposition
groundSpill.applyToBuffer(pixels, positions, isGround, emitters, { emission, glow });
waterTranslucency.applyToBuffer(pixels, bedPixels, shoreDist, isWater);
```

Buffers are `Uint8ClampedArray` RGBA (the board's pixel-type law). Classification/ownership (who is grass, who is water, where the shore is) stays with the caller — the source modules separate `classifyFrame` / `shoreDistanceField` from application the same way; `shoreDistanceField`, `extractEmitters`, `bedTexture`, `keyDirectTerm` are carried for callers that need them.

## Worked example

`example.cjs` runs all four stages in seam order over one 64×64 synthetic scene (`example/scene.json`: grass field, roof block, pond, one occluder box, one lit window; clock pinned to 20:00 so the spill is live). Actual output, 2026-11-07 run:

```
before: grass 86,140,52 · roof 178,52,44 · water(shore) 46,102,150 · water(deep) 46,102,150
stage castShadows: {"shadowedPx":39,"changedPx":39,"meanAbsDelta":90}
stage grade/tune: tuned {"grass":3232,"roof":192,"water":672} {"changedPx":4096,"meanAbsDelta":4.19}
stage waterTranslucency: {"waterPx":672,"blended":387,"changedPx":387,"meanAbsDelta":62.89}
  shore profile (meanBedShare by band): 0-0.25:0.492 0.25-0.5:0.463 0.5-1:0.37 1-1.5:0.213 1.5-2.2:0.053 2.2-inf:0
stage groundSpill: {"touched":120,"meanAddLuma":5.14,"maxAddLuma":13.74,"emissionFactor":1,"changedPx":111,"meanAbsDelta":15.41}
stage grade/blend: {"graded":3776,"changedPx":3520,"meanAbsDelta":16.1}
after:  grass 95,144,68 · roof 178,55,47 · water(shore) 103,128,142 · water(deep) 59,108,157 · grass@window-front 101,151,59
```

Reading it: the box shadows exactly its footprint + north throw (39 px); the tune moves everything a breath (mean |Δ| 4.19); the pond's shore pixel ends up half bed-sand (`103,128,142` — the sand showing through), its deep pixel stays water-led; the window-front grass is warmer than the open field (`101,151,59` vs `95,144,68`); the blend grade cools the far field toward the day airlight last. The example's shadow key term is a fixed illustrative linear term — the full Cook–Torrance re-derivation is `castShadows.keyDirectTerm`, exercised by the unit test's geometry.

## Filed numbers — reproduced vs cited

**Reproduced in `check.cjs` (unit level, synthetic buffers, `PASS 34 FAIL 0`):**

| claim | filed | reproduced |
|---|---|---|
| shadow synthetic unit test (two suns, box on plane) | 6/6 | **6/6** |
| shadow core property | occluded darkens / lit sides exactly unchanged | occluded byte drops, unoccluded bit-identical |
| tune saturation deltas | grass +0.020 · water +0.025 · roof −0.010 · canopy +0.015 (declared) | within ±0.005 per sample pixel (byte quantisation) |
| tune identity anchor | roof: no hue/value move | dH ≈ 0°, V ratio 1.000 |
| blend transmittance | T(1) = 0.84 day as-filed · dusk dose T(1) = 0.80, gate 0.60 | exact to 1e-9; T(0.3) = 1 under the dusk gate |
| spill peak add luma, full emission | 13.84 | 13.845 from the dose arithmetic |
| spill 19:00 dose factor | 0.494× (emission 0.6674 / 1.35) | 0.4944; peak 6.845 vs filed 6.84 |
| spill gate | hard zero at/past 2.0 cells | opacity ≡ 0 at 2.0 / 2.5 / 3.0; beyond-gate pixel bit-identical; glow 0 = exact no-op |
| water shore-band bed shares | 0.479 / 0.436 / 0.335 / 0.176 / 0.050 | **0.480 / 0.436 / 0.331 / 0.174 / 0.035** — the stage's own function over a uniform synthetic shore strip (400 px/band), all within 0.02 of filed |

**Cited, not reproduced (pipeline-level — they belong to the full board render, not to a unit):** ground-spill band deltas +12.80 / +9.26 / +4.30 / +0.71 / 0 / 0 and 20:00 pool (42,502 px touched, mean +5.28); translucency coverage 10,498/10,498 water px, 0 void, shore HF 7.514 → 9.059; shadowed px 29,293 (day) / 128,622 (dusk), receiver agreement 307,200/307,200, encoding control max delta 0; frame HF 1.7198 → 1.8291 (day); v8 grade measured rows (frameHF 1.7198 / 1.0018, dusk valSep +6.29, vrr 0.8436). Sources: `measurements-color-water.json`, `measurements-v8.json`, `RECEIPT-port.md` §2.

## Consumers

The canonical board builder (`build-board.cjs`, via the §9 port — it imports the source modules directly; this program is the school-library distillation of the same stages, not a replacement import for the builder) · Emerald rendition · N64 rendition (per `programs.json` registry entry). Any future seam-stage work (new spill receiver classes, new tune classes) starts from these stage signatures.

## Honest limits

- **The last water band is distribution-sensitive.** The filed 0.050 is the mean over the real pond's shore distribution (pixels cluster toward the shallow edge of the 1.5–2.2 band); a uniform strip gives 0.035. The function is identical — the difference is the input distribution, and the check's tolerance (0.02) names it rather than hiding it.
- **Shadows: only the key light casts**; smooth-shaded faces (tree tiers, figure heads/hair) get their removed term from the flat face normal — occlusion *geometry* is exact, the *amount* on those faces is approximate (source scope, carried verbatim). The 512² map's tip resolution is ~0.2 cells (filed, §8-F11) — no claim here depends on sub-0.2-cell shadow tips.
- **The full `applyCastShadows` harness path is not distilled** — camera unprojection, receiver rasterization against the harness owner map, and the ground-field analytic points belong to the board builder. This program carries the projection core (map, test, term, recomposition) with caller-supplied surface points.
- **The bed pass discipline** (`assertBedPass` / `assertBedCoverage`, bed-variant construction via the builder's mesh validator) stays with the builder; this program carries the composite arithmetic, the bed texture, and the shore field.
- **Grade context is the caller's**: airlight is a WorldClock output in the builder (`gradeContextFor`); the filed day/dusk airlights are carried as constants here. The world-clock program owns that derivation.
- The tune's classifier (owner map + map data + water blue-dominance gate) is represented by its constants (`CODE`, `WATER_DOM`, `DOSES`); classification itself needs a rendered frame and is not re-run here.
