Skip to content

fix(textures): default createImageBitmapSupport to 'auto' so Chrome 38 doesn't throw#132

Merged
chiefcll merged 1 commit into
mainfrom
fix/createimagebitmap-auto-default
Jul 17, 2026
Merged

fix(textures): default createImageBitmapSupport to 'auto' so Chrome 38 doesn't throw#132
chiefcll merged 1 commit into
mainfrom
fix/createimagebitmap-auto-default

Conversation

@chiefcll

Copy link
Copy Markdown
Contributor

What

Changes the default createImageBitmapSupport from 'full' to 'auto'.

Why

createImageBitmap was not added to Chrome until v50, but the renderer's documented support floor is Chrome 38. With the old default 'full', CoreTextureManager sets hasCreateImageBitmap = true without probing (initialize()), so on any runtime lacking the API — including Chrome 38–49 — ImageTexture calls the undefined global through WebPlatform.createImageBitmap and throws on the first image load. The renderer effectively did not work out-of-the-box on its own stated floor unless the integrator knew to pass createImageBitmapSupport: 'auto'.

How

'auto' runs the existing 1×1-PNG probe (validateCreateImageBitmap) through the platform, correctly detecting basic/options/full support and falling back to new Image() when the API is absent. This path already exists and is well-tested; the fix just makes it the default.

  • No behavior change on modern browsers: the probe resolves to full support, so the capability outcome is identical — only a negligible one-time startup probe is added.
  • Platform-respecting: because the probe calls platform.createImageBitmap, custom platforms are detected correctly (a bare global typeof guard would not respect them).
  • Escape hatch preserved: integrators on a known-modern runtime can still set 'full' / 'options' / 'basic' explicitly to skip the probe.

Also updates the setting's doc comment (@defaultValue, fallback behavior, and a note that forcing a level the runtime lacks will fail to load images).

Reviewer notes

  • Aligns the default with the behavior BROWSERS.md already documents: "the renderer will use a 1×1 PNG Pixel to validate whether the createImageBitmap API is available."
  • Init becomes async-by-default (waits on the probe), but the renderer already supports async init — textures queued before initialized fires are drained on init, and Stage listens for the initialized event. No consumer contract changes.
  • Not observable in the browser preview: on a modern dev browser 'auto' resolves to 'full', so there is no visual difference; the fix matters only on runtimes without createImageBitmap. Verified via tsc --build + existing ImageTexture / Stage / texture-manager unit tests (all green).
  • Follow-ups from the same Chrome-38 audit (not in this PR): internal queueMicrotask fallback; per-frame allocation cleanups in CoreTextNode/Stage; evaluate alpha:false on the drawing buffer.

🤖 Generated with Claude Code

…8 doesn't throw

The default was 'full', which makes CoreTextureManager set
hasCreateImageBitmap = true WITHOUT probing. On any runtime that lacks
createImageBitmap — including the documented Chrome 38 support floor, since
the API was not added until Chrome 50 — ImageTexture then calls the
undefined global via WebPlatform.createImageBitmap and throws on the first
image load.

'auto' runs the existing 1x1-PNG probe (validateCreateImageBitmap) through
the platform, correctly detecting support and falling back to `new Image()`
when it's absent. On modern browsers the probe resolves to full support, so
capability is unchanged; the only cost is a negligible one-time startup
probe. Integrators on a known-modern runtime can still set 'full'/'options'/
'basic' explicitly to skip it.

This aligns the default with the behavior BROWSERS.md already documents
("the renderer will use a 1x1 PNG Pixel to validate whether the
createImageBitmap API is available").

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@chiefcll
chiefcll merged commit fd66b33 into main Jul 17, 2026
3 checks passed
@chiefcll
chiefcll deleted the fix/createimagebitmap-auto-default branch July 17, 2026 14:09
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant