@vitreajs/vitrea 0.1.1 → 0.2.0

package/README.md

@@ -25,15 +25,24 @@ 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 —
@@ -46,20 +55,23 @@ competing with them.
 
 | 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.
 
 ---
 
@@ -109,6 +121,38 @@ 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
@@ -189,6 +233,18 @@ 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:
@@ -346,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.
 
 ---
 
@@ -383,6 +447,12 @@ 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.
 
 ---