LearnNewsExamplesServices
Frontmatter
id19168
titleNeo.canvas.Base can only acquire a 2d OffscreenCanvas context
stateClosed
labels
enhancementai
assigneesneo-fable-clio
createdAtSep 24, 2026, 4:31 PM
updatedAtSep 24, 2026, 6:18 PM
githubUrlhttps://github.com/neomjs/neo/issues/19168
authorneo-fable-clio
commentsCount0
parentIssuenull
subIssues[]
subIssuesCompleted0
subIssuesTotal0
contentTrust
projected
quarantined0
signals[]
blockedBy[]
blocking[]
closedAtSep 24, 2026, 6:18 PM

Neo.canvas.Base can only acquire a 2d OffscreenCanvas context

neo-fable-clio
neo-fable-clio commented on Sep 24, 2026, 4:31 PM

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:

  1. contextType: '2d' — the OffscreenCanvas#getContext() type. Non-reactive: read once when the canvas arrives.
  2. contextAttributes: null — the second getContext() argument (WebGLContextAttributes / CanvasRenderingContext2DSettings), passed only when set.
  3. 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.
  4. 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

  • AC-1 — a Neo.canvas.Base subclass with no override acquires getContext('2d') with no attributes argument; the four Portal canvases are not in the diff.
  • AC-2 — a subclass declaring contextType: 'webgl2' and contextAttributes receives getContext('webgl2', attributes); context holds the returned object; updateSize and onGraphMounted fire as before; the loop starts when hasChange is set.
  • AC-3 — a null context leaves context null, calls neither onGraphMounted nor the loop, and logs one error naming the class and the type.
  • AC-4 — test/playwright/unit/canvas/ContextAcquisition.spec.mjs covers AC-1..3 with a fake canvasWindowMap canvas whose getContext records its arguments; AC-2 and AC-3 red at origin/dev (the base ignores the configs and starts the loop on null), AC-1 green there as the control.
  • AC-5 (post-merge) — the D#19151 canvas-worker witness drops its waitForCanvas override for the two config lines; receipt on D#19151.

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