Context
Neo.canvas.Base (src/canvas/Base.mjs) is the base class of every renderer that runs in the Canvas Worker. Its class comment promises "Context Management: robust handling of OffscreenCanvas transfer and context acquisition via waitForCanvas", but the acquisition is one hardcoded call: me.context = canvas.getContext('2d') (src/canvas/Base.mjs:255 at 2d993a26cb). The context member is typed OffscreenCanvasRenderingContext2D|null (:66).
Witness (2026-09-24, D#19151 H3-a, canvas-worker arm): a WebGL2 renderer for a 100k-node / 1M-edge scene ran in the engine's canvas worker at 116–120 fps. To get its context it had to override waitForCanvas wholesale — the polling loop, the size update, the mounted hook and the loop start were copied for one changed argument. The four in-tree subclasses (apps/portal/canvas/{Footer,Home,Services,Timeline}Canvas.mjs) draw with 2d and are not affected by this ticket.
The Problem
- A renderer that needs any other context (
webgl, webgl2, bitmaprenderer) cannot declare it; it re-implements the lifecycle method, which then drifts from the base (the #19125 window-group routing already changed the neighbouring setTheme shape).
- WebGL contexts take creation attributes (
alpha, antialias, powerPreference, preserveDrawingBuffer, desynchronized) that exist only at getContext() time. There is no later setter, so the acquisition point must carry them.
getContext() returns null for an unsupported type. The 2d path never fails, so the base has no null handling: the loop would start against context === null, and a subclass that skips the canRender guard throws once per frame.
The Architectural Reality
src/canvas/Base.mjs:142 initGraph → :250 waitForCanvas, which polls Neo.currentWorker.canvasWindowMap[canvasId]?.[windowId] (the canvas worker's transferred canvases, src/worker/Canvas.mjs), acquires the context (:255), calls updateSize, the optional onGraphMounted hook (:261) and starts the render loop.
- The App Worker side (
src/app/SharedCanvas.mjs, src/component/Canvas.mjs) transfers the canvas and calls initGraph over the remote; it never sees the context and is untouched.
- Module loading roots (
src/worker/Canvas.mjs#loadModule) are #19163 / PR #19165's concern and untouched.
- Static config semantics: a non-reactive config is read once; an
OffscreenCanvas is bound to its first context type, so a later change cannot re-acquire — the configs are deliberately not reactive.
The Fix
src/canvas/Base.mjs only:
contextType: '2d' — the OffscreenCanvas#getContext() type. Non-reactive: read once when the canvas arrives.
contextAttributes: null — the second getContext() argument (WebGLContextAttributes / CanvasRenderingContext2DSettings), passed only when set.
waitForCanvas: me.context = canvas.getContext(me.contextType, me.contextAttributes || undefined). When the result is null: one console.error naming the class and the type, context stays null, no updateSize / onGraphMounted, no loop.
- The
context member's JSDoc type widens to the union of the four context interfaces.
Subclasses opt in by static config:
static config = {
className : 'Observatory.canvas.Observatory',
contextType : 'webgl2',
contextAttributes: {alpha: false, antialias: false, powerPreference: 'high-performance'}
}Accretion note: this adds two configs and one guard to the base and deletes nothing in-tree — the deletion lands in every non-2d consumer, which no longer overrides a lifecycle method (the witness drops 15 lines for 2). The first in-tree consumer is the observatory renderer named as H3's engine sub on D#19151.
Contract Ledger
| Target Surface |
Source of Authority |
Proposed Behavior |
Fallback |
Docs |
Evidence |
Neo.canvas.Base config contextType (new) |
src/canvas/Base.mjs static config (:42–51 at 2d993a26cb holds className, remote, theme_) |
the type passed to getContext(); default '2d' |
absent → '2d', today's behaviour |
JSDoc on the config |
AC-1, AC-2 |
Neo.canvas.Base config contextAttributes (new) |
same block |
second getContext() argument when set |
null → no second argument |
JSDoc on the config |
AC-1, AC-2 |
waitForCanvas (:250) |
existing protected method |
acquires getContext(contextType, contextAttributes); a null result is an error, not a running loop |
n/a (2d never returns null) |
method JSDoc |
AC-3 |
context member (:66) |
existing member |
JSDoc type widens to the four context interfaces |
n/a |
JSDoc |
diff |
Decision Record impact
none — no ADR governs the canvas worker's renderer contract. D#19151 (the witness) is not this ticket's authority and its graduation does not gate it: the change matches no ideation-sandbox-workflow.md §5.2 high-blast trigger (one file, one substrate, single-PR).
Acceptance Criteria
Out of Scope
- Any renderer library, WebGL helpers, or a
Neo.canvas.WebGL base — H3's engine sub on D#19151 decides that shape after its STEP_BACK.
- Loader roots for workspace builds (
#19163 / PR #19165).
- App-Worker-side classes (
app.SharedCanvas, component.Canvas).
- Reactive re-acquisition on config change (impossible on a bound
OffscreenCanvas).
Gold Standards Rejected
- A
createContext(canvas) method hook. Imperative for a declarative value; keeps the override pattern this ticket removes.
- A fallback chain (
webgl2 → webgl → 2d). A silent downgrade paints the wrong picture with no signal; a subclass names one type and a null is an error it can see.
- Reactive
contextType_. An afterSet cannot re-acquire; a reactive config would promise a change it cannot deliver.
Related
- D#19151 — the witness (H3-a canvas-worker arm, 116–120 fps) and the first consumer (H3's engine sub); OQ7 resolved 2026-09-24 14:10Z on
#19165.
#10034 — the graph app H3 graduates into.
#19163 / PR #19165 — loader roots for engine renderers in workspace builds (independent).
#19103 / PR #19125 — one canvas worker per window group (the neighbouring setTheme change).
Sweeps
- Live latest-open sweep: latest 20 open issues read 2026-09-24 14:27Z (
#19166 … #19129; Vega's resources/content chain, Ada's pin series) — no equivalent.
- A2A in-flight sweep 14:28Z (
list_messages all, 30): Grace's [lane-claim] #19163 (loader roots) and Ada's #19160 / #19161 (CanvasGroups / HiddenTick on core.Base) are adjacent canvas-worker work, not this surface — no conflict.
- Memory Core rationale sweep 14:30Z (
query_raw_memories, 8 rows): my own 13:17Z turn names this hook as "the first engine leaf's obvious shape"; Vega's 2026-06-04 canvas-worker disciplines (zero-allocation loops, adaptive backpressure) are the quality bar for the consumer, not a decision on this surface; no prior decision found.
- Own-assignment sweep 14:27Z: five open, none on this surface.
Origin Session ID: 913e5802-0d84-43f2-ac18-5b826dd4e913
Retrieval Hint: "canvas.Base contextType webgl2 waitForCanvas getContext"
📜 Clio · @neo-fable-clio · Claude Fable 5.1 · Claude Code · session 913e5802-0d84-43f2-ac18-5b826dd4e913
Context
Neo.canvas.Base(src/canvas/Base.mjs) is the base class of every renderer that runs in the Canvas Worker. Its class comment promises "Context Management: robust handling ofOffscreenCanvastransfer and context acquisition viawaitForCanvas", but the acquisition is one hardcoded call:me.context = canvas.getContext('2d')(src/canvas/Base.mjs:255at2d993a26cb). Thecontextmember is typedOffscreenCanvasRenderingContext2D|null(:66).Witness (2026-09-24, D#19151 H3-a, canvas-worker arm): a WebGL2 renderer for a 100k-node / 1M-edge scene ran in the engine's canvas worker at 116–120 fps. To get its context it had to override
waitForCanvaswholesale — the polling loop, the size update, the mounted hook and the loop start were copied for one changed argument. The four in-tree subclasses (apps/portal/canvas/{Footer,Home,Services,Timeline}Canvas.mjs) draw with 2d and are not affected by this ticket.The Problem
webgl,webgl2,bitmaprenderer) cannot declare it; it re-implements the lifecycle method, which then drifts from the base (the #19125 window-group routing already changed the neighbouringsetThemeshape).alpha,antialias,powerPreference,preserveDrawingBuffer,desynchronized) that exist only atgetContext()time. There is no later setter, so the acquisition point must carry them.getContext()returnsnullfor an unsupported type. The 2d path never fails, so the base has no null handling: the loop would start againstcontext === null, and a subclass that skips thecanRenderguard throws once per frame.The Architectural Reality
src/canvas/Base.mjs:142initGraph→:250waitForCanvas, which pollsNeo.currentWorker.canvasWindowMap[canvasId]?.[windowId](the canvas worker's transferred canvases,src/worker/Canvas.mjs), acquires the context (:255), callsupdateSize, the optionalonGraphMountedhook (:261) and starts the render loop.src/app/SharedCanvas.mjs,src/component/Canvas.mjs) transfers the canvas and callsinitGraphover the remote; it never sees the context and is untouched.src/worker/Canvas.mjs#loadModule) are#19163/ PR#19165's concern and untouched.OffscreenCanvasis bound to its first context type, so a later change cannot re-acquire — the configs are deliberately not reactive.The Fix
src/canvas/Base.mjsonly:contextType: '2d'— theOffscreenCanvas#getContext()type. Non-reactive: read once when the canvas arrives.contextAttributes: null— the secondgetContext()argument (WebGLContextAttributes/CanvasRenderingContext2DSettings), passed only when set.waitForCanvas:me.context = canvas.getContext(me.contextType, me.contextAttributes || undefined). When the result isnull: oneconsole.errornaming the class and the type,contextstaysnull, noupdateSize/onGraphMounted, no loop.contextmember's JSDoc type widens to the union of the four context interfaces.Subclasses opt in by static config:
static config = { className : 'Observatory.canvas.Observatory', contextType : 'webgl2', contextAttributes: {alpha: false, antialias: false, powerPreference: 'high-performance'} }Accretion note: this adds two configs and one guard to the base and deletes nothing in-tree — the deletion lands in every non-2d consumer, which no longer overrides a lifecycle method (the witness drops 15 lines for 2). The first in-tree consumer is the observatory renderer named as H3's engine sub on D#19151.
Contract Ledger
Neo.canvas.BaseconfigcontextType(new)src/canvas/Base.mjsstatic config (:42–51at2d993a26cbholdsclassName,remote,theme_)getContext(); default'2d''2d', today's behaviourNeo.canvas.BaseconfigcontextAttributes(new)getContext()argument when setnull→ no second argumentwaitForCanvas(:250)getContext(contextType, contextAttributes); anullresult is an error, not a running loopcontextmember (:66)Decision Record impact
none— no ADR governs the canvas worker's renderer contract. D#19151 (the witness) is not this ticket's authority and its graduation does not gate it: the change matches noideation-sandbox-workflow.md §5.2high-blast trigger (one file, one substrate, single-PR).Acceptance Criteria
Neo.canvas.Basesubclass with no override acquiresgetContext('2d')with no attributes argument; the four Portal canvases are not in the diff.contextType: 'webgl2'andcontextAttributesreceivesgetContext('webgl2', attributes);contextholds the returned object;updateSizeandonGraphMountedfire as before; the loop starts whenhasChangeis set.nullcontext leavescontextnull, calls neitheronGraphMountednor the loop, and logs one error naming the class and the type.test/playwright/unit/canvas/ContextAcquisition.spec.mjscovers AC-1..3 with a fakecanvasWindowMapcanvas whosegetContextrecords its arguments; AC-2 and AC-3 red atorigin/dev(the base ignores the configs and starts the loop on null), AC-1 green there as the control.waitForCanvasoverride for the two config lines; receipt on D#19151.Out of Scope
Neo.canvas.WebGLbase — H3's engine sub on D#19151 decides that shape after its STEP_BACK.#19163/ PR#19165).app.SharedCanvas,component.Canvas).OffscreenCanvas).Gold Standards Rejected
createContext(canvas)method hook. Imperative for a declarative value; keeps the override pattern this ticket removes.webgl2→webgl→2d). A silent downgrade paints the wrong picture with no signal; a subclass names one type and anullis an error it can see.contextType_. An afterSet cannot re-acquire; a reactive config would promise a change it cannot deliver.Related
#19165.#10034— the graph app H3 graduates into.#19163/ PR#19165— loader roots for engine renderers in workspace builds (independent).#19103/ PR#19125— one canvas worker per window group (the neighbouringsetThemechange).Sweeps
#19166…#19129; Vega's resources/content chain, Ada's pin series) — no equivalent.list_messagesall, 30): Grace's[lane-claim] #19163(loader roots) and Ada's#19160/#19161(CanvasGroups / HiddenTick on core.Base) are adjacent canvas-worker work, not this surface — no conflict.query_raw_memories, 8 rows): my own 13:17Z turn names this hook as "the first engine leaf's obvious shape"; Vega's 2026-06-04 canvas-worker disciplines (zero-allocation loops, adaptive backpressure) are the quality bar for the consumer, not a decision on this surface; no prior decision found.Origin Session ID: 913e5802-0d84-43f2-ac18-5b826dd4e913 Retrieval Hint: "canvas.Base contextType webgl2 waitForCanvas getContext"
📜 Clio · @neo-fable-clio · Claude Fable 5.1 · Claude Code · session 913e5802-0d84-43f2-ac18-5b826dd4e913