# Task 1: Ref1 surface reflection

Source plan: final work instruction in Codex task `01a0c768-534f-7660-9d86-c5ae50f71b1f`.

## Goal

Keep Ref1 option 2's large rectangular color planes and dark eye/nose readability while making the whole glass pane, including grass, read as glass.

## Required implementation

- Preserve the existing rectangular light reflection in `src/shaders/mosaic.frag`.
- Add a broad, soft, low-strength reflection component derived from the existing curved normal and current view direction. Reuse the current light/intersection model where possible; do not add an environment texture, render pass, render target, UI, or dependency.
- Composite both reflections after color-plane simplification and before output color-space conversion. Do not put reflection into `REGION_ATLAS`, palette selection, or history.
- Control both reflections with the existing `uGlossStrength`. At gloss 0 the new reflection contribution must be exactly zero.
- Keep the same signed curved normal for refraction and reflection. Reflection must respond to view direction, be stable when still, and vary spatially rather than applying a uniform white mix.
- Keep the refraction `edgeWeight` and all existing world-delta/sample-boundary behavior unchanged. Add a separate surface-reflection edge weight, starting from `mix(0.35, 1.0, edgeWeight)`, and tune only if visual comparison shows a bright rim. Both existing and new reflection use the surface-reflection weight.
- Keep the pane bounds so reflection does not spill onto the wooden reveal/frame or outside the glass.

## Must remain unchanged

- Grid 13, curvature +1, gloss 0.30, region/distortion 1, camera 0.50 defaults and option ranges.
- Ref1 option 2 palette fitting, dark rectangular color-plane preservation, 70 ms history, view-dependent refraction, photo/depth placement, manual framing, and inner window reveal.
- No original eye/nose pixel restoration, global blur, stronger black grid, per-cell random brightness, time animation, grass/pet masks, automatic framing, or changes to Reeded/Frosted.

## TDD and automated verification

Before production shader edits, add one minimal source/math regression script that fails for the missing behavior and then passes. It must check only this change's invariants:

- gloss 0 removes both existing and broad reflection;
- surface reflection weight stays in range and does not replace the refraction edge weight;
- broad reflection is spatial/view dependent rather than a constant white mix;
- reflection composition remains outside `REGION_ATLAS` and before color-space conversion.

Record the exact RED and GREEN commands/output. Label source/math assertions honestly; they are not GPU visual verification. Run the existing six scripts and `npm.cmd run build` after implementation.

## Baseline and visual QA

- Preserve the exact pre-edit `src/shaders/mosaic.frag` under `docs/qa-surface-reflection/baseline-mosaic.frag` before editing.
- Use dog1 with completed AI depth and fixed values: Final/Mosaic, Grid 13, curvature +1, gloss 0.30, region/distortion 1, light X/Y 0.60/0.80, depth scale 0.25, camera offset 0.50, photo zoom/pan 1/0/0.
- Capture same-viewport images for baseline, broad reflection only, and final edge separation when practical. Also inspect gloss 0/0.30/0.40, curvature -1/0/+1, camera 0.90, a portrait viewport, and one indoor image.
- Passing visual result: grass shows distinct curved surface reflection rather than uniform brightening; adjacent cells respond coherently; pane edges retain material without a bright rim or leakage; eyes/nose remain dark and face/grass do not wash out.
- Gloss 0 must remain visually equivalent to the baseline. Distortion 0 and other glass modes must retain existing behavior.

## Write scope

- Required: `src/shaders/mosaic.frag`, one narrowly scoped script under `scripts/`, `docs/qa-surface-reflection/` baseline/QA/report files.
- `src/main.ts` may be edited only if inspection proves the existing uniforms cannot support the required shader behavior; explain first in the report.
- Do not touch palette/history shaders, UI, camera, photo/depth placement, or window reveal.

## Report contract

Write `docs/qa-surface-reflection/implementation-report.md` with changed files, final coefficients and rationale, RED/GREEN evidence, full verification results, visual comparison paths, and remaining limitations. Do not claim GPU or mobile behavior that was not observed.