Skip to content

docs: mark the WebGL renderer experimental, take its switch off the demo, 0.24.2 - #64

Merged
Surdeddd merged 5 commits into
mainfrom
docs/webgl-experimental
Nov 15, 2026
Merged

Surdeddd merged 5 commits into
mainfrom
docs/webgl-experimental

Conversation

@Surdeddd

Copy link
Copy Markdown
Owner

What this changes

The WebGL renderer (@surdeddd/bottom-sheet/webgl) is marked experimental in the documentation, and its switch comes off the demo's workbench. No code in the package changes. Released as 0.24.2 so the README on npm carries the notice.

  • docs/webgl.md opens with an "Experimental" notice and gains a Known issues section.
  • README, README.ru, llms.txt: the /webgl row and the topics link say experimental. llms.txt tells assistants not to add the renderer unless asked, and context7.json gets the same rule.
  • docs/api-stability.md: /webgl is the exception to what can be relied on, and it is not frozen by 1.0.
  • Demo: the switch shows up only when the link carries #webgl=1, labelled experimental. The permalink writes the renderer flags only while they are on, so an ordinary link does not bring the switch back. The F.12 card says experimental.

Why

Tried on a real phone, the renderer makes the sheet's content jump. Reproduced on the live demo in WebKit with a GPU:

  • When a drag starts, the text moves from the DOM into a texture drawn on a 2D canvas, and it lands 3–4 px lower. It jumps back when the sheet settles. The canvas lays text out on its own, so fonts, letter-spacing and text-transform do not match the browser exactly. This is how the content lift works, not a one-line bug.
  • Text meant only for screen readers was drawn into the texture: "minimized" showed at the left edge of the sheet.
  • The velocity bend shakes the top edge on an uneven drag.

Removing /webgl would break anyone who imported it after 0.24.1 came out yesterday. Marking it experimental keeps them working, stops the docs and AI assistants from recommending it, and takes it off the demo, where every visitor saw the jump first. Whether it is fixed or removed is left for before 1.0.

Verification

  • npx tsc --noEmit — clean
  • npx vitest run — 100 files, 1040 passed, 2 skipped (permalink test now checks that a switched-off renderer leaves no trace in the link)
  • npx playwright test — demo-renderer in mobile-chrome, mobile-safari, firefox: 49 passed, 2 skipped (two new tests: the switch is hidden on the plain page, the link brings it back labelled experimental). a11y, sheet, adapters, demo-renderer in Chromium and WebKit: 73 passed, 7 skipped. Visual: 21 of 21 after regenerating the hero baselines
  • npm run size — not affected, no code under src/ changed
  • npm run docs:check — 39 files OK

Checklist

  • No comments added to src/ or demo/
  • Behaviour change is covered by a test that fails without the fix — both new e2e tests and the permalink test failed first
  • Public API change is reflected in docs/ and CHANGELOG.md — no API change; the notice is in both
  • Touched src/styles/bottom-sheet.css? — no
  • Added a subpath export? — no
  • Changed the demo's rendered layout? — the hero shows the version: darwin baselines in this PR, linux ones from Visual baselines (linux) follow as one more commit

On a real phone the renderer makes the sheet's text jump at the start
and the end of every drag, and a visitor who flips the switch sees that
first. The switch now shows up only when the link carries `webgl=1`, for
testing on devices, and says it is experimental. The link carries the
renderer flags only while they are on, so an ordinary permalink does not
bring the switch back. The feature card says experimental too.
The guide opens with a notice and lists the known issues: text that
shifts when it moves into the texture and back, screen-reader-only text
in the texture, a bend that reads as jitter, and Safari hiding the
renderer's name. The README tables, llms.txt and a Context7 rule mark
the entry experimental so assistants stop suggesting it, and the
stability page leaves /webgl out of what 1.0 freezes.
From the Visual baselines (linux) workflow run on this branch; only the
seven hero snapshots, which print the version.
@vercel

vercel Bot commented Nov 15, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
bottom-sheet-demo Ready Ready Preview Nov 15, 2026 10:35am UTC

@github-actions

Copy link
Copy Markdown

Bundle size report (gzip, threshold 5%)

File Base PR Δ bytes Δ % Status
dist/index.js 35.57 KB 35.57 KB +0 0.00% ok
dist/react.js 46.16 KB 46.16 KB +0 0.00% ok
dist/preact.js 0.05 KB 0.05 KB +0 0.00% ok
dist/vue.js 40.14 KB 40.14 KB +0 0.00% ok
dist/svelte.js 39.59 KB 39.59 KB +0 0.00% ok
dist/solid.js 38.21 KB 38.21 KB +0 0.00% ok
dist/qwik.js 38.27 KB 38.27 KB +0 0.00% ok
dist/element.js 46.33 KB 46.33 KB +0 0.00% ok
dist/element.iife.global.js 33.04 KB 33.04 KB +0 0.00% ok
dist/overlay.js 11.19 KB 11.19 KB +0 0.00% ok
dist/styles.css 2.68 KB 2.68 KB +0 0.00% ok
dist/themes/ios.css 0.27 KB 0.27 KB +0 0.00% ok
dist/themes/material.css 0.27 KB 0.27 KB +0 0.00% ok
dist/themes/vercel.css 0.24 KB 0.24 KB +0 0.00% ok

All tracked entries are within the 5% budget.

@Surdeddd
Surdeddd merged commit f8e0a54 into main Nov 15, 2026
12 checks passed
@Surdeddd
Surdeddd deleted the docs/webgl-experimental branch November 15, 2026 10:50

This branch was successfully deployed

2 active and 1 inactive deployments
Production — f8e0a54a Deployed Nov 15, 2026 by vercel[bot]
github-pages — f8e0a54a Deployed Nov 15, 2026 by Surdeddd via deploy #24
Preview — f8e0a54a Deployed Nov 15, 2026 by vercel[bot]
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