@vitreajs/vitrea 0.1.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,36 @@
+NOTICE — vitrea
+================
+
+Copyright (c) 2026 Minhyeok Kim
+
+Licensed under the Apache License, Version 2.0 (the "License"); you may not
+use these files except in compliance with the License. You may obtain a copy
+of the License in the LICENSE file distributed with this package, or at
+http://www.apache.org/licenses/LICENSE-2.0
+
+This package is original work. The internal packages bundled into it
+(@vitrea/geometry, @vitrea/motion, @vitrea/renderer-webgpu) are part of the
+same project and carry the same copyright and license.
+
+Trademarks
+-----------
+"Liquid Glass" is the name of Apple Inc.'s design language. It is referenced
+here descriptively — to state what material this library replicates and what
+its fidelity is measured against — never as a claim of origin, endorsement, or
+association. "Apple", "macOS", "SwiftUI", "Safari" and "Metal" are trademarks
+of Apple Inc., and appear only in that descriptive sense.
+
+vitrea is not affiliated with, endorsed by, or sponsored by Apple Inc. It is
+not an Apple product, not built on Apple frameworks, and not a port of Apple
+code. It is an independent open-source reimplementation of a published visual
+material, calibrated against screen captures of Apple's own rendering on
+macOS 26.5.
+
+Other names appearing in this project's documentation ("Chromium", "Chrome",
+"Firefox", "WebKit", "Figma") are trademarks of their respective owners and
+are used only in descriptive reference.
+
+Contact
+-------
+Minhyeok Kim <kimmi@l1ngual.com>
+https://github.com/SSFSKIM/designer

package/README.md

@@ -0,0 +1,359 @@
+# vitrea
+
+**A production-oriented, reference-calibrated material compositor for semantic web
+controls.**
+
+vitrea replicates Apple's Liquid Glass material and interaction system — WWDC25's
+`glassEffect`, `GlassEffectContainer`, `interactive()`, `glassEffectID` — on the
+web, in TypeScript. Not a blur preset: real-time size-parameterized lensing,
+per-element adaptation of tint and foreground to the live backdrop,
+container-scoped sampling, and shape-to-shape morphing.
+
+This is not the first WebGPU glass demo, and it does not claim to be. Prior art
+exists and is good at what it does. What vitrea is built for is the part the
+demos leave out: explicit backdrop contracts, shared sampling groups, coherent
+cross-element morphing, adaptive accessibility, progressive fidelity tiers that
+report what they actually resolved to, and fidelity numbers backed by a versioned
+harness that diffs against native captures instead of against a screenshot
+somebody eyeballed.
+
+The label on every glass control stays real DOM. A `GlassButton` is a `<button>`:
+selectable, focusable, IME-capable, and announced by a screen reader as a button.
+
+---
+
+## Install
+
+```bash
+npm install @vitreajs/vitrea @vitreajs/vitrea-react
+```
+
+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.
+
+### 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 |
+
+**One honest limit up front.** `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.
+
+---
+
+## Quickstart
+
+```tsx
+import { GlassRoot, GlassGroup, GlassToolbar, GlassButton, useGlassCapabilities } from "@vitreajs/vitrea-react";
+
+export function App() {
+  return (
+    <GlassRoot renderer="webgpu">
+      {/* Your page. Ordinary DOM, and it stays ordinary DOM. */}
+      <YourPage />
+
+      {/* A toolbar creates its own sampling group; `hint` tells the runtime what
+          is behind it, because vitrea never pretends to analyse arbitrary DOM. */}
+      <GlassToolbar
+        aria-label="Actions"
+        groupProps={{ hint: { tone: "dark", luminance: 0.18 } }}
+        style={{ position: "fixed", bottom: 32, left: "50%", transform: "translateX(-50%)" }}
+      >
+        <GlassButton onClick={share}>Share</GlassButton>
+        <GlassButton onClick={save}>Save</GlassButton>
+      </GlassToolbar>
+    </GlassRoot>
+  );
+}
+```
+
+Surfaces that are not toolbar members go in an explicit group. A group is the
+sampling unit — one backdrop proxy, one blur, shared between its members:
+
+```tsx
+<GlassGroup id="hero" hint={{ tone: "light" }}>
+  <GlassSurface radius={20} thickness={10}>
+    <h1>Anything you like in here</h1>
+  </GlassSurface>
+</GlassGroup>
+```
+
+And to see what the runtime actually resolved to, rather than what you asked for:
+
+```tsx
+function TierReadout() {
+  const state = useGlassCapabilities("hero");
+  if (state === undefined) return null;
+  return (
+    <p>
+      configured {state.configuredSource}, drawing on {state.activeRenderer},
+      sampling {state.samplingBackend}, refraction {state.refraction}
+      {state.health === "demoted" ? ` — demoted: ${state.demotionReason}` : ""}
+    </p>
+  );
+}
+```
+
+Run the demo app in this repository to see all of it working, including the
+side-by-side native reference pairs:
+
+```bash
+pnpm install && pnpm -r build
+pnpm --filter demo dev     # http://localhost:5173, add ?renderer=css to force the tier
+```
+
+---
+
+## The capability model: the honesty contract, as a feature
+
+Most glass libraries have one quality knob and fail quietly when the platform
+cannot honour it. vitrea separates what your app **configures** from what the
+runtime **resolves**, and the resolved state is a closed set of legal
+combinations rather than a free product of axes — because a free product admits
+states that are meaningless (a registered GPU texture with no WebGPU; a
+CORS-tainted video reported as exact analysis).
+
+Every group reports:
+
+```ts
+interface GlassGroupState {
+  configuredSource: "texture" | "dom";      // what you declared — never mutated
+  activeRenderer:  "webgpu" | "css";        // what is actually drawing
+  samplingBackend: "gpu-texture" | "css-backdrop" | "none";
+  refraction:      "true" | "approximate" | "none";
+  analysis:        "exact" | "hint" | "none";
+  health:          "ok" | "demoted";
+  demotionReason?: "no-webgpu" | "no-backdrop-filter" | "tainted-source"
+                 | "incompatible-texture" | "device-lost" | "probe-failed"
+                 | "governor";
+}
+```
+
+Three properties are worth knowing, because they are the reason the model exists:
+
+**`configuredSource` survives demotion.** You can always see what you asked for
+next to what you got. Nothing silently rewrites your intent.
+
+**Every demotion names a reason and a recovery.** `device-lost` recovers when a
+device is restored; `tainted-source` when the source is replaced;
+`probe-failed` when the probe re-passes. `no-webgpu` names its recovery as
+`"none"` — honestly unrecoverable inside the session, rather than implying a
+retry that will never succeed.
+
+**Choosing the CSS tier is not a fault.** A root that never requested WebGPU
+resolves its groups to `activeRenderer: "css"` with `health: "ok"` and no
+demotion reason. Labelling deliberate intent as a fault would invert the whole
+point.
+
+### The three healthy configurations
+
+| 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. |
+| **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`. |
+
+vitrea does not automatically pixel-analyse arbitrary DOM, and never claims to.
+There is a built-in best-effort estimator that reads known background colours and
+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.
+
+### Tiers degrade within themselves before they switch
+
+The quality governor first reduces refraction resolution, adaptation cadence and
+edge analysis *inside* the current tier. Switching tiers happens only with long
+hysteresis and a cooldown, and never mid-interaction. Intra-tier degradation is
+not a state change, so it does not churn your readouts.
+
+---
+
+## Fidelity
+
+vitrea's material is tuned against real captures of Apple's material, not against
+recollection. `apps/reference-apple` is a SwiftUI harness running the actual
+`glassEffect` API; `packages/calibration` captures both sides over identical
+pre-rendered raster backgrounds and diffs them on shape, material, motion and
+perceptual axes, keyed by native profile × web cell.
+
+The full record is
+[`docs/doperpowers/specs/c9a-fidelity-claims.md`](https://github.com/SSFSKIM/designer/blob/main/docs/doperpowers/specs/c9a-fidelity-claims.md).
+The claims, in the words that document states them:
+
+### The texture tier
+
+> **Reference-calibrated against macOS 26.5 captures.** vitrea's WebGPU texture
+> tier — its own shader math over a GPU-owned backdrop — was calibrated against
+> 30 ScreenCaptureKit captures of Apple's `glassEffect` material on macOS 26.5,
+> in the cell *Chromium 151, `gpu-texture` backend, Apple Metal-3 adapter, sRGB,
+> 1× scale*. Across the six scenes held out of tuning, the rendered result
+> reaches a silhouette IoU of 0.9924 mean / 0.9612 worst, a contour distance of
+> 0.18 px mean / 0.56 px worst-cell-mean, SSIM 0.9475 mean / 0.9007 worst, and
+> OKLab ΔE 0.0320 mean / 0.0548 worst. Tuning improved every one of those axes
+> over the untuned defaults. It is not pixel-identical to Apple's material and
+> two named gaps remain open.
+
+### The CSS (dom) tier
+
+> **No cross-engine pixel-wise fidelity claim is made for the dom tier, and none
+> can be. On Chromium, in the same cell with `renderer: css` and
+> `samplingBackend: css-backdrop`: OKLab ΔE 0.0091 mean / 0.0240 worst and SSIM
+> 0.9700 mean / 0.9304 worst over the 12 light calibration cells, ΔE 0.0108 /
+> 0.0273 over the 6 validation cells, and ΔE 0.0291 mean / 0.0560 worst with SSIM
+> 0.9373 / 0.9205 on the six scenes held out of all tuning. Silhouette IoU 0.9424
+> mean over the calibration cells and 0.9684 on holdout, with a 1.06 px mean
+> contour distance.**
+
+This tier does not hold a material of its own: it **converts** the one the root
+carries, through a mapping whose single fitted constant is tuned against the
+cross-tier difference rather than against the fixtures. That is a deliberate
+trade, recorded rather than hidden — a CSS tier fitted independently against
+Apple is free to drift from the GPU tier the moment either is retuned, while a
+converted one inherits the GPU tier's fidelity by construction. The price is now
+0.0099 against Apple where an independent fit reached 0.0094.
+
+> **Tier coherence, and only in this wording.** On Chromium, a group that demotes
+> from the WebGPU texture tier to the CSS tier keeps the same material to within
+> 1.3% of its interior level in the mean and 11% on the worst measured cell, at a
+> cross-tier OKLab ΔE of 0.0063 mean / 0.0124 worst over the fitted sets and
+> 0.0188 / 0.0313 over the held-out ones. It is **not** the same rendering —
+> refraction is absent on the CSS tier by contract (`refraction: "none"`) — but
+> the material's opacity, tint and frost do not change visibly on demotion.
+
+Exact coherence is unreachable, and the arithmetic says so before any capture
+does: the renderer applies its transfer function *after* the blend and the page
+applies it *before*, so matching the two composites needs a different CSS alpha at
+every backdrop level (0.761 at linear 0.05, 0.635 at 0.8). One scalar is exact at
+one level and necessarily wrong either side of it. What remains is a property of
+`backdrop-filter`, not a residual anyone can tune away.
+
+The cross-engine absence is not laziness. Gecko and WebKit render
+`backdrop-filter` as a complete no-op in every automatable capture path — headless
+and headed Playwright, retail `--screenshot`, WebDriver BiDi, WKWebView
+`takeSnapshot` — while rendering it correctly live. A screenshot comparison on
+those engines measures a blank image. Their visual behaviour is verified by a
+manual self-scoring page instead, and that is a release gate rather than a CI
+check.
+
+### What is *not* claimed
+
+- **Never "pixel-identical to Apple."** Every figure above is scoped to one
+  native profile and one web cell, and says so.
+- **No press-state fidelity claim.** Apple's `Glass.interactive(true)` opts the
+  material into *responding* to press input rather than posing it pressed, and
+  Apple exposes no declarative pressed pose — so the native "pressed" captures
+  are byte-identical to their rest counterparts (verified by SHA-256, all four).
+  Those cells compare vitrea's pressed pose against Apple's rest pose. They were
+  also excluded from the tuning decision.
+- **No adopted pass/fail thresholds.** The thresholds in the claims document are
+  *proposals for a human gate*, not self-certification.
+- **1× only.** The capture machine reports `backingScaleFactor` 1.0, so every
+  figure is a 1× figure. The two accessibility-mode profiles have no captures at
+  all yet; macOS exposes those display modes as read-only, so each needs its own
+  capture run.
+- **The glass-over-glass cells are a mixed-backend claim.** Natively the upper
+  `glassEffect` samples the lower one's rendered output; on the web that
+  relationship *is* the plane sandwich, so those cells resolve to
+  `gpu-texture + css-backdrop` with `refraction: "approximate"` even on the GPU
+  tier. They are counted in the holdout numbers, and they are the two lowest
+  SSIM figures in that set.
+- **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.
+
+---
+
+## Browser support
+
+Two tiers, and the CSS tier is a hard requirement rather than a courtesy —
+WebGPU is not everywhere, and pretending otherwise is what the capability model
+exists to prevent.
+
+| Engine | WebGPU (texture tier) | CSS tier |
+| --- | --- | --- |
+| **Chromium** (Chrome, Edge) | Default-on from 113 on desktop, 121 on Android | Yes. Byte-exact backdrop-proxy sampling equivalence, measured across 122 capture variants |
+| **Safari / WebKit** | Default-on from Safari 26 | Yes, manually verified — automated capture cannot observe `backdrop-filter` on this engine |
+| **Firefox / Gecko** | Default-on from 141 on Windows, 145 on ARM Mac; **still flagged on Linux** | Yes, manually verified — same automated-capture blindness |
+
+Where WebGPU is missing, every group resolves to `activeRenderer: "css"` with
+`demotionReason: "no-webgpu"`, renders presentable CSS-tier glass, and logs no
+errors. Asking for the GPU tier is not the same as getting it, and
+`useGlassCapabilities()` is how you find out which happened.
+
+### Contract limits you should know before designing around it
+
+- All glass lives inside `GlassRoot`'s managed planes. v1 ships exactly two —
+  base and one overlay — and menus portal internally to the overlay plane.
+  Arbitrary interleaving with foreign stacking contexts is out of contract.
+- Two glass surfaces must not overlap **within one plane**. This is a dev-mode
+  error rather than an assumption: the paint sandwich cannot place one surface's
+  body above another surface's DOM label. Overlap across planes is the supported
+  case and is what the morph uses.
+- Glass hosts must not sit beneath an ancestor whose `filter`, `opacity`, `mask`
+  or `clip` changes the backdrop root. The relevant CSS specification explicitly
+  lacks working-group consensus here, so engines may legitimately differ — which
+  is why a startup conformance probe validates the proxy topology and demotes a
+  group to the CSS tier when sampling proves non-equivalent, rather than trusting
+  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.
+
+---
+
+## Accessibility
+
+Accessibility is policy in `vitrea`, applied by the host layer through media
+queries, with per-root prop overrides. It is resolved, not bolted on: each
+preference has a declared consequence for the material or the motion, and the
+strictest active preference wins.
+
+| Preference | What changes |
+| --- | --- |
+| `prefers-reduced-motion` | No elastic overshoot, no deformation, no shimmer travel. Morphs become non-elastic interpolation. Direct-manipulation positional continuity is preserved — reduced motion is not *no* motion. |
+| `prefers-reduced-transparency` | More frost, less refraction, higher occlusion. |
+| `prefers-contrast: more` | Stronger borders, near-monochrome foregrounds, reduced ambient tint. |
+| `forced-colors: active` | System colours, borders, **no glass** — every optical axis goes with it. |
+
+The first three are overridable per root:
+
+```tsx
+<GlassRoot reducedTransparency={true} increasedContrast="system" />
+```
+
+`forced-colors` deliberately has **no** override prop, and its absence is
+enforced in the type system: an operating-system colour mandate is not an app's
+to switch off.
+
+`prefers-reduced-transparency` is not Baseline across engines. On a platform that
+cannot answer the query, leaving it on `"system"` silently resolves it to false
+and the user's preference is lost — so vitrea emits a diagnostic saying exactly
+that. The explicit override is load-bearing, not a courtesy.
+
+One documented obligation on your side: content that vitrea portals into a plane
+leaves its original DOM position, so if that content was inside a landmark
+region, you own re-establishing the landmark. A `role`/landmark seam on the morph
+component is deferred post-v1 API work.
+
+---
+
+## License
+
+Apache License 2.0. See [`LICENSE`](https://github.com/SSFSKIM/designer/blob/main/LICENSE).
+
+"Liquid Glass" is the name of Apple Inc.'s design language, referenced here
+descriptively to say what this library replicates. vitrea is not affiliated with,
+endorsed by, or sponsored by Apple Inc. See [`NOTICE`](https://github.com/SSFSKIM/designer/blob/main/NOTICE).