Repository navigation
Implement and prove AETHER WebGL runtime lifecycle #9
Description
Status refresh — 2026-08-21
Disposition: OPEN — contract merged; runtime implementation and browser evidence are absent.
Current evidence
- Current
main:dd45f60dd6c9195a9c29a2c311bf4cfab7705716. - PR qa: define WebGL runtime lifecycle evidence contract #11 merged only
docs/verification/WEBGL_LIFECYCLE_CONTRACT.md; contract head384056af76d8313ec74191f47092a302a4e52c8f, merge commitdd45f60…. - Current
src/components/ShaderCanvas.tsxblobad6fab1f1437764a68aede60a311f73690fa1c3estill:- throws/console-logs when WebGL is unavailable;
- has no visible fallback;
- has no context-loss/restoration listeners;
- does not abort shader fetches;
- does not honor reduced motion;
- cancels only the last frame and does not release shaders/program/buffer/listeners.
.github/workflows/webgl-browser-evidence.ymldoes not exist.@playwright/testis not declared in the current package manifest.
Branch creation order
Create fix/webgl-runtime-lifecycle-v1 from main@dd45f60dd6c9195a9c29a2c311bf4cfab7705716.
Allowed change surface
src/components/ShaderCanvas.tsxtests/webgl/**docs/verification/WEBGL_LIFECYCLE_CONTRACT.md.github/workflows/webgl-browser-evidence.ymlpackage.jsonandpackage-lock.jsononly if needed to pin one browser-test dependency
No shader source, uniform design, tokens, gallery UI, pricing, deployment, or WebGPU work.
TDD build order
- Add failing browser tests for null context, context loss, restoration, unmount, source-change cancellation, reduced motion, and healthy nonblank output.
- Add a visible fallback with equivalent accessible status.
- Factor resource creation/disposal so restoration rebuilds program, shaders, buffer, uniforms, and frame scheduling.
- Add one
AbortControllerper shader request and cancel on source change/unmount. - Implement reduced-motion as a stable meaningful frame without a continuous decorative loop.
- Dispose animation frames, listeners, requests, shaders, program, buffer, and any observers on teardown.
- Add the browser-evidence workflow and retain screenshots, console inventory, and a machine-readable receipt.
- Run
npm ci, typecheck, lint, build, browser suite, and healthy visual comparison; open a draft PR.
Definition of done
All six contract scenarios have browser evidence, no uncaught errors or post-unmount work remains, and the healthy-path visual has no unexplained delta.
Stop conditions
Stop if browser automation requires an unpinned install, healthy appearance changes, context restoration cannot reconstruct owned resources, any edit escapes the allowlist, or a shader redesign appears necessary.
Historical scope (preserved)
Verified evidence gap
AETHER draft PR #7 records nine static WebGL checks. Four are currently proven in source and five remain not-proven:
- accessible visible fallback when WebGL is unavailable;
- context-loss handling;
- context-restoration and resource reconstruction;
- pending shader-fetch cancellation;
- reduced-motion render-loop behavior.
Static inspection is not runtime proof.
Allowed paths only
src/components/ShaderCanvas.tsx
tests/webgl/**
docs/verification/WEBGL_LIFECYCLE_CONTRACT.md
.github/workflows/webgl-browser-evidence.yml
Required behavior
- present a visible, screen-reader-accessible fallback instead of console-only failure;
- listen for
webglcontextlost, prevent default, and stop rendering; - rebuild program, shaders, buffers, uniforms, and scheduling after
webglcontextrestored; - abort pending shader-source fetches on unmount and source change;
- pause or replace continuous animation under
prefers-reduced-motion; - release frame scheduling and GPU resources during teardown;
- preserve the existing shader appearance when WebGL is healthy.
QA
- Playwright or equivalent browser test with
getContext('webgl')forced tonull; - synthetic context loss and restoration;
- no animation frames after unmount;
- no unresolved fetch after source change;
- reduced-motion test;
- nonblank-canvas smoke test;
- console error inventory;
- artifact screenshots and execution receipt.
Non-goals
- no shader or uniform redesign;
- no token, gallery, pricing, dependency-version, deployment, or secret changes;
- no WebGPU migration.
Approval gate
Use a new branch and draft PR after the reproducible-build contract is reviewed. Exact changed-file inventory required. Keep unmerged until browser evidence passes and Jennipher approves the lifecycle behavior.
Activity
[-]Add browser evidence for WebGL fallback, lifecycle, and reduced motion[/-][+]Implement and prove AETHER WebGL runtime lifecycle[/+]