@vitreajs/vitrea 0.1.0 → 0.2.0

package/README.md

@@ -25,34 +25,53 @@ selectable, focusable, IME-capable, and announced by a screen reader as a button
 ## Install
 
 ```bash
-npm install @vitreajs/vitrea @vitreajs/vitrea-react
+npm install @vitreajs/vitrea-react          # React
+npm install @vitreajs/vitrea-web            # plain JS, or your own adapter
 ```
 
-The library is called vitrea and publishes under the npm scope `@vitreajs`.
-`@vitreajs/vitrea` is the framework-agnostic runtime, `@vitreajs/vitrea-react`
-the declarative surface. These two are the only published packages: the
-geometry kernel, the motion kernel, the DOM host layer and the WebGPU renderer
-are internal and bundled into them at publish time, so an app installs two
-packages and gets zero transitive runtime dependencies beyond React itself.
+The library is called vitrea and publishes under the npm scope `@vitreajs`, in
+three packages that layer the way React's own do — a pure runtime, a DOM host
+over it, framework bindings over that:
+
+| Package | What it is | Depends on |
+| --- | --- | --- |
+| `@vitreajs/vitrea` | the framework-agnostic runtime: scene model, capability and tier resolution, material and accessibility policy. No DOM code at all. | nothing |
+| `@vitreajs/vitrea-web` | the browser host: element registration, plane management, backdrop proxies, the CSS-tier renderer, the WebGPU lifecycle. **Mounts a root from any framework, or none.** | `@vitreajs/vitrea` |
+| `@vitreajs/vitrea-react` | the declarative surface: `GlassRoot`, `GlassGroup`, `GlassSurface` and the v1 controls. | both of the above |
+
+Installing the React bindings pulls the other two in, so a React app still runs
+one `npm install` and gets no transitive runtime dependency outside this project
+beyond React itself. The geometry kernel, the motion kernel and the WebGPU
+renderer stay internal and are bundled in at publish time.
+
+**TypeScript.** The published declarations resolve on their own, on any
+TypeScript version, with no `types` entry and nothing extra installed —
+including with `skipLibCheck: false`. The WebGPU type names the artifacts use
+are declared inside them, and they merge with your own WebGPU types
+(TypeScript 6's DOM lib, `@types/web`, or `@webgpu/types`) rather than
+competing with them.
 
 ### Which package you actually import from
 
 | You are… | Install | Import |
 | --- | --- | --- |
-| writing a React app | `@vitreajs/vitrea @vitreajs/vitrea-react` | `@vitreajs/vitrea-react` for components, `@vitreajs/vitrea` for types |
-| reading the resolved capability state | either | `@vitreajs/vitrea` |
-| writing a Vue/Svelte/WC adapter | `@vitreajs/vitrea` | not yet supported — see below |
+| writing a React app | `@vitreajs/vitrea-react` | `@vitreajs/vitrea-react` for components, `@vitreajs/vitrea` for types |
+| writing plain JavaScript, or a Vue/Svelte/Web-Components adapter | `@vitreajs/vitrea-web` | `@vitreajs/vitrea-web` for `createGlassRoot`, `@vitreajs/vitrea` for types |
+| reading the resolved capability state | any of them | `@vitreajs/vitrea` |
 
-**One honest limit up front.** `vitrea` contains no DOM code at all, by design
+**Which one has the DOM in it.** `vitrea` contains no DOM code at all, by design
 (the purity law: the core, geometry and motion packages never touch `window`,
-`document` or `HTMLElement`). The browser host layer — element registration,
-plane management, backdrop proxies, the CSS-tier renderer, the WebGPU lifecycle —
-ships bundled *inside* `vitrea-react`. So in v1 the only way to render glass in a
-browser is through the React bindings. `vitrea` on its own gives you the scene
-model, the capability and tier resolver, the material and accessibility policy,
-and the frame-scheduler contract; it does not give you a mounted root. A
-framework-agnostic host entry point is post-v1 work, not a thing you can reach
-today by installing `vitrea` alone.
+`document` or `HTMLElement`). So `vitrea` on its own gives you the scene model,
+the capability and tier resolver, the material and accessibility policy, and the
+frame-scheduler contract — but not a mounted root. `vitrea-web` is the package
+that mounts one, and it is a peer of the React bindings rather than something
+hidden inside them: the same `createGlassRoot` the bindings use is the one a
+vanilla page calls. See [`@vitreajs/vitrea-web`](../platform-web/README.md) for
+the imperative quickstart.
+
+> Until 0.2 the host layer shipped bundled *inside* `vitrea-react`, so React was
+> the only way to render glass in a browser. That is what publishing this package
+> retired.
 
 ---
 
@@ -93,6 +112,47 @@ sampling unit — one backdrop proxy, one blur, shared between its members:
 </GlassGroup>
 ```
 
+**A surface has no intrinsic size.** vitrea declares neither position nor size
+for one: it measures the box your CSS produced, once per frame, and fits the
+material to it. The element itself is portalled into its plane's host layer,
+which is a `position: absolute; inset: 0` overlay, so a surface places itself the
+way any overlay child does — give it your own width, height and positioning, and
+it will be exactly as big as you made it. This is also why press compression and
+morph deformation are composed transforms rather than shape changes: a transform
+cannot dirty the rect it is animating.
+
+### Glass is a controls-layer material
+
+There is one placement rule, and Apple states it as a prohibition rather than as
+advice: **"Don't use Liquid Glass in the content layer."** The material exists to
+separate the things you can act on from the things you are reading; putting it on
+both collapses that distinction. Apple names both failure modes: "including it in
+the content layer can result in unnecessary complexity and a confusing visual
+hierarchy", and, for stacking, "avoid applying the material to both layers.
+Instead, use fills, transparency, and vibrancy for the top elements."
+
+So: glass on the toolbar, not on the article you are reading through it. Glass on
+the row's button, not on the row. And glass on the control, never on the control *and* its
+container. Lists and tables are the case Apple calls out by name, and they are
+the case a web glass library gets wrong most often, because `asChild` will glass
+a `<tr>` as readily as a `<button>`.
+
+vitrea now checks the two compositions that are decidable from structure, at
+registration, in dev mode only:
+
+| code | fires when | what it tells you |
+| --- | --- | --- |
+| `glass-inside-glass` | a registered host sits inside another registered host's subtree | which pair, and to keep the material on whichever of the two is the control while the other takes a fill, a translucency or a vibrant foreground |
+| `glass-in-content-layer` | a host is registered on an element whose resolved ARIA role is a list or table structure | which element and which role, and either to move the glass onto the control the row holds or — if it really is a controls-layer container — to give it the role it means, at which point the check stands down |
+
+Both are advisory findings on the diagnostics channel rather than throws, and
+both are `devMode`-only: the check runs once per `registerHost` call and never
+from a frame, so a production build pays nothing for it. What vitrea does *not*
+check is the rest of the rule — whether anything is actually scrolling under a
+surface, whether a non-interactive label has been glassed, whether glass and
+content intersect at rest. Those need judgement or a per-frame observation, and a
+diagnostic that fires on a correct page is worse than no diagnostic.
+
 And to see what the runtime actually resolved to, rather than what you asked for:
 
 ```tsx
@@ -139,8 +199,8 @@ interface GlassGroupState {
   analysis:        "exact" | "hint" | "none";
   health:          "ok" | "demoted";
   demotionReason?: "no-webgpu" | "no-backdrop-filter" | "tainted-source"
-                 | "incompatible-texture" | "device-lost" | "probe-failed"
-                 | "governor";
+                 | "incompatible-texture" | "no-texture-supplied" | "device-lost"
+                 | "probe-failed" | "governor";
 }
 ```
 
@@ -164,7 +224,7 @@ point.
 
 | Configuration | What you get |
 | --- | --- |
-| **texture + exact** — you register an image, video, canvas or procedural texture as the group's backdrop | Full refraction. Edge lensing visibly bends the backdrop; a larger surface lenses deeper than a small one over the same content. Luminance, variance and edge-density analysis run on the GPU. |
+| **texture + exact** — you register an image, video or canvas as the group's backdrop | Full refraction. Edge lensing visibly bends the backdrop; a larger surface lenses deeper than a small one over the same content. Luminance, variance and edge-density analysis run on the GPU. |
 | **dom + hint** — arbitrary page content, plus a `hint` (or an estimator provider) | The browser compositor does the blur through a masked backdrop proxy; the GPU renders rim lensing, tint, glow and morphs. Adaptation comes from your hint. |
 | **dom + none** — arbitrary page content, no hint (the default) | Fixed regular material, geometry-driven rim and specular, foreground from tokens or `color-scheme`. |
 
@@ -173,6 +233,74 @@ There is a built-in best-effort estimator that reads known background colours an
 images where CORS permits, and it is documented as an estimator every place it
 appears — not as pixel analysis, because that is not what it is.
 
+**The backdrop reading decides the material's own appearance too, not only the
+foreground.** Apple's material stops being a lighter thing in front of a dark
+enough backdrop and takes that backdrop's tone; vitrea does the same, size-gated,
+so a 44 px control disappears into a near-black backdrop while a large panel over
+the same one keeps most of its own appearance. Read the table above with that in
+mind: **texture + exact** measures the tone from the pixels you supplied,
+**dom + hint** adapts to the tone your hint declares, and **dom + none** does not
+adapt at all — it will not guess a backdrop it has not been shown, on either tier.
+Nothing happens above roughly a fifth of the luminance range, so an ordinary page
+is untouched. Measured against the macOS 26.5 reference; the law and its numbers
+are in `docs/doperpowers/specs/c9a-fidelity-claims.md` §5.8.
+
+### Registering a texture backdrop
+
+The texture path is two steps, and it is two because of the purity law above:
+`vitrea` may not hold an `HTMLImageElement`, so it cannot be the thing you hand
+pixels to. The group **declares** the source; the root **supplies** it.
+
+```tsx
+import { GlassGroup, GlassSurface, useGlassRoot } from "@vitreajs/vitrea-react";
+
+function Hero() {
+  const root = useGlassRoot();
+
+  return (
+    <>
+      {/* 1. Declare. `configuredSource` stays "texture" through any demotion. */}
+      <GlassGroup id="hero" backdrop={{ kind: "texture", id: "hero" }}>
+        <GlassSurface radius={26} thickness={18}>…</GlassSurface>
+      </GlassGroup>
+
+      {/* 2. Supply. The id is what joins the two halves; the order does not
+             matter, and `setBackdropTexture` marks the source dirty itself, so
+             handing the pixels over is the whole wiring. */}
+      <img
+        src="/hero.jpg"
+        alt=""
+        onLoad={(event) =>
+          root?.setBackdropTexture("hero", { kind: "image", image: event.currentTarget })
+        }
+      />
+    </>
+  );
+}
+```
+
+The other two forms are `{ kind: "canvas", canvas }` and `{ kind: "video", video }`.
+A video and a live canvas are re-imported on every frame that samples them; a
+decoded image is imported once. Passing `undefined` withdraws a source's pixels.
+
+Declaring a texture and never supplying one is not a silent hole: the group
+resolves to `health: "demoted"` with `demotionReason: "no-texture-supplied"` and
+keeps drawing tint, rim and glow. The readout names the missing half.
+
+**Where the texture is placed.** The renderer maps the source over the **whole
+viewport**, cover-fit — it fills the viewport and the overflow is cropped
+symmetrically, the same geometry as `object-fit: cover` on a
+`position: fixed; inset: 0` element. Not over the group, and not over the
+surface.
+
+This matters whenever your app paints the same image itself, which is the usual
+case: the picture is on the page and the glass sits on top of it. The two
+mappings have to agree. An `<img>` sized to a region, under a texture mapped to
+the viewport, samples a different crop of the same file — and the mismatch
+appears as the glass showing the wrong part of the picture, which reads
+convincingly like a lensing artefact rather than a registration error. Paint your
+copy viewport-sized and `object-fit: cover`, or accept that the two will differ.
+
 ### Tiers degrade within themselves before they switch
 
 The quality governor first reduces refraction resolution, adaptation cadence and
@@ -274,6 +402,14 @@ check.
 - **Tier coherence is a Chromium measurement of a material's level**, on one
   profile, at 1×. It does not say the two tiers are identical, and it does not
   hold on Gecko or WebKit — nothing measurable does there.
+- **No fidelity claim for the author tint.** `GlassSurface`'s `tint` prop is
+  implemented on both tiers and visually verified on both, but every constant in
+  the tone curve that turns an author's colour into "a range of tones mapped to
+  content brightness underneath" is an advisory default. The tinted native
+  captures that would fit them were taken on 2026-08-30 and could not be used:
+  they carry the tint's strength but not its colour, so two scenes declaring
+  different seeds came back byte-identical (claims §5.10). Until a re-captured
+  bed exists the tint's appearance is designed, not calibrated.
 
 ---
 
@@ -311,6 +447,74 @@ errors. Asking for the GPU tier is not the same as getting it, and
   a support query.
 - v1 corner radii are uniform. The `radii` API keeps its four-component shape,
   but a non-uniform set is a dev-mode error; per-corner algebra is post-v1.
+- **One author tint seed per group.** A tint is declared per surface and its
+  strength is honoured per surface, but a group is one optics pass and carries
+  one seed, so two *different* tint colours in one group raise a dev-mode warning
+  and the WebGPU tier draws them all in the first surface's colour. One coloured
+  control among plain ones — Apple's own guidance for tinting — is the supported
+  composition.
+
+---
+
+## Testing your app
+
+### The readout is trustworthy; the environment may not be
+
+`useGlassCapabilities()` reports what resolved. If it says
+`demotionReason: "no-webgpu"`, that session genuinely had no WebGPU — the
+readout is not the thing to doubt. What is worth doubting is the environment,
+because one browser-automation default removes WebGPU without removing anything
+you would notice.
+
+**Playwright's bundled headless shell hands back a software adapter.** This repo
+measures three different answers on one machine depending on how Chromium is
+launched: the default headless shell resolves to a SwiftShader adapter, while
+`channel: "chromium"` — the full browser binary — resolves to real hardware. A
+suite that never asks for the channel runs entirely green on the CSS tier, and
+every readout in it honestly says `no-webgpu`, which is what makes this the worst
+kind of failure: nothing is broken, it is just the other tier, and the
+instrumentation agrees with the wrong answer.
+
+```ts
+// playwright.config.ts
+projects: [
+  {
+    name: "chromium-gpu",
+    use: {
+      channel: "chromium",
+      launchOptions: {
+        args: ["--enable-unsafe-webgpu", "--enable-features=Vulkan,WebGPU"],
+      },
+    },
+  },
+],
+```
+
+Two further requirements are not optional. `navigator.gpu` is undefined outside a
+secure context, so serve the page over `http://localhost` — on `file://` and
+`data:` URLs the absence reads exactly like "no WebGPU on this machine". And a
+test that means to assert the GPU tier should **fail** when no adapter answers
+rather than skip, and fail rather than quietly accept a software one; otherwise
+it asserts nothing.
+
+### What is in the DOM differs by tier
+
+The backdrop-proxy elements are not a general debugging landmark. A
+`[data-vitrea-proxy]` element exists only where the GPU tier is sampling
+arbitrary DOM:
+
+| Resolved state | What the runtime puts in the DOM |
+| --- | --- |
+| `activeRenderer: "webgpu"`, `samplingBackend: "css-backdrop"` | one `[data-vitrea-proxy]` per group **per plane** it has members on |
+| `activeRenderer: "webgpu"`, `samplingBackend: "gpu-texture"` | no proxy — the backdrop is a GPU texture, so there is nothing in the page to filter |
+| `activeRenderer: "css"` | no proxies at all: the CSS tier applies `backdrop-filter` **in place**, on each glass host element |
+
+So "find the proxy" is an assertion about one resolved state, not about the
+dom-backdrop path in general — and its absence on the CSS tier is the design
+rather than a fault, which is also why `probe-failed` can demote to that tier at
+all: the very thing that failed is not on its path. To assert the CSS tier, read
+the host element's own computed `backdrop-filter`, `background-color` and
+`border-color`. To assert which tier you are on, read `useGlassCapabilities()`.
 
 ---