@vitreajs/vitrea 0.15.0 → 0.17.0

package/dist/index.d.ts

@@ -370,7 +370,9 @@ interface ResolvedMotionPolicy {
      * does it — a morph is one continuous material transition, not two surfaces
      * dissolving. Reduced Motion reserves it for large plane shifts. (The
      * foreground light/dark crossfade of §Motion's driver table is a different,
-     * unconditional channel and is not governed here.)
+     * unconditional channel and is not governed here.) An explicitly authored
+     * `materialize` transition crossfades content, not the surface element: its
+     * material follows optical presence and is independent of this plane-shift rule.
      */
     readonly crossfade: "never" | "large-plane-shifts";
     /**
@@ -2125,6 +2127,11 @@ interface MaterialOuterShadow {
  * Units: CSS px for distance, linear light for colour, viewport coordinates with
  * y pointing down for direction.
  */
+type BackdropToneKnotRow = readonly [number, number, number] | readonly [number, number, number, number];
+interface MaterialOcclusionLiftByPolicy {
+    readonly reduceTransparency: number;
+    readonly increaseContrast: number;
+}
 interface MaterialProfile {
     /** Per-variant optics. `clear` is persistently more transparent than `regular`. */
     readonly optics: Readonly<Record<MaterialVariant, MaterialOptics>>;
@@ -2879,6 +2886,8 @@ interface MaterialProfile {
      * both directions by `packages/calibration/test/tier-coherence.test.ts`.
      */
     readonly increasedOcclusionLift: number;
+    /** Optional policy-specific levels. Absent keeps the shared lift exactly. */
+    readonly increasedOcclusionLiftByPolicy?: MaterialOcclusionLiftByPolicy;
     readonly strongBorderRim: MaterialRim;
     readonly reducedTintAdaptation: number;
     /**
@@ -2915,6 +2924,25 @@ interface MaterialProfile {
     readonly tintShadeDark: number;
     readonly tintShadeLight: number;
     readonly tintShadeStrength: number;
+    /**
+     * The fraction of the author's seed saturation retained before the shade law.
+     * The neutral endpoint is the seed's maximum linear channel, not its luminance:
+     * W27c's orange and blue checkerboard capsules at both 1x and 2x lose their hue
+     * to the SAME grey, despite the seeds having different luminances (§5.130).
+     * Strength still composites the resulting layer; it is not discarded.
+     * Absence means 1, the identity. Identity values are omitted from resolved
+     * documents so the frozen active profiles keep their existing fingerprints.
+     */
+    readonly tintChromaScale?: number;
+    /**
+     * The fraction of the tint shade retained when backdrop adaptation collapses
+     * the body. W27c's 1x light dark-solid tinted capsule requires Y 0.03678 while
+     * its checkerboard counterpart requires Y 0.45128. A chroma-only seed change
+     * cannot supply both: collapse forces the old shade to 1. Retention lets the
+     * same shade law follow the collapsed body's level instead of exposing the
+     * unshaded seed. Absence means 0, preserving the active law and its fingerprint.
+     */
+    readonly tintShadeCollapseRetention?: number;
     /**
      * **Backdrop tone adaptation (W7)** — the axis Apple's material has and this
      * one did not: over a dark enough backdrop the material stops being a lighter
@@ -3140,9 +3168,9 @@ interface MaterialProfile {
      * extreme-dark region stays with the collapse constants that were fitted
      * on it.
      */
-    readonly backdropToneAnchorX: readonly [number, number, number];
-    readonly backdropToneResponseThin: readonly [number, number, number];
-    readonly backdropToneResponseThick: readonly [number, number, number];
+    readonly backdropToneAnchorX: BackdropToneKnotRow;
+    readonly backdropToneResponseThin: BackdropToneKnotRow;
+    readonly backdropToneResponseThick: BackdropToneKnotRow;
     /**
      * How much authority the response law has in THIS profile, 0…1 (W9).
      *
@@ -3249,11 +3277,14 @@ interface MaterialProfilePatch {
     readonly lensOvalizationSpanMax?: number;
     readonly reducedTransparencyFrost?: number;
     readonly increasedOcclusionLift?: number;
+    readonly increasedOcclusionLiftByPolicy?: Readonly<Partial<MaterialOcclusionLiftByPolicy>>;
     readonly strongBorderRim?: Readonly<Partial<MaterialRim>>;
     readonly reducedTintAdaptation?: number;
     readonly tintShadeDark?: number;
     readonly tintShadeLight?: number;
     readonly tintShadeStrength?: number;
+    readonly tintChromaScale?: number;
+    readonly tintShadeCollapseRetention?: number;
     readonly backdropToneMax?: number;
     readonly backdropToneLow?: number;
     readonly backdropToneHigh?: number;
@@ -3263,9 +3294,9 @@ interface MaterialProfilePatch {
     readonly rimCollapsed?: number;
     readonly rimCollapsedTinted?: number;
     readonly rimTintChroma?: number;
-    readonly backdropToneAnchorX?: readonly [number, number, number];
-    readonly backdropToneResponseThin?: readonly [number, number, number];
-    readonly backdropToneResponseThick?: readonly [number, number, number];
+    readonly backdropToneAnchorX?: BackdropToneKnotRow;
+    readonly backdropToneResponseThin?: BackdropToneKnotRow;
+    readonly backdropToneResponseThick?: BackdropToneKnotRow;
     readonly backdropToneResponseStrength?: number;
     readonly outerShadow?: Readonly<Partial<MaterialOuterShadow>>;
     readonly lightDirection?: readonly [number, number];
@@ -3547,8 +3578,50 @@ interface SurfaceChannels {
      * when v1 gains one.
      */
     readonly shimmer: number;
-    /** `lensStrength`, 0..1. Multiplies the resolved refraction scale. */
+    /**
+     * `lensStrength`, 0..1+. Multiplies the resolved refraction scale.
+     *
+     * **The range is open above 1** (W27a), which is the range `@vitreajs/vitrea-web`'s
+     * `channels.ts` has always documented and the range the motion table has always
+     * driven: 1 at rest, 1.03 focused, 1.06 hover, 1.10 morphing, 1.14 pressed, and
+     * 0.5 disabled. The instance builder used to clamp the channel at 1 on its way
+     * into the shader, which left `disabled` as the only interaction state the lens
+     * could see and silently discarded every one that deepens it. The lens depth is
+     * still clamped to the surface's half span in the fragment stage, so a strength
+     * above 1 deepens the lens without pushing it through the surface.
+     */
     readonly lensStrength: number;
+    /**
+     * `materialization`, 0..1 — the surface's PRESENCE (W27d; contract X6).
+     *
+     * Apple's `Glass.identity` animates glass to nothing in place and
+     * `GlassEffectTransition.materialize` brings it back, and Apple states the
+     * mechanism twice: "prefer setting the effect property over the alpha", and a
+     * surface materializes "by gradually modulating the light bending and
+     * lensing". The runtime states it a third time from the other side — an
+     * `opacity` below 1 on a host or one of its ancestors forms a Backdrop Root
+     * and kills the group's proxy sampling — so presence is a scalar on the
+     * material's own optical terms and never on the element.
+     *
+     * It scales the lens's depth and magnitude, the body's mix away from the
+     * unblurred backdrop, the material's alpha, the author tint's coverage, the
+     * inner and outer shadows, the rim and the highlight. At 1 every one of those
+     * is a multiplication by exactly one, so the resting material is byte-identical
+     * to the material that had no channel.
+     *
+     * **Exactly 0 is not the bottom of that ramp but the absence of the surface**
+     * (`Glass.identity`). The member is dropped before the field pass
+     * (`resolveSurfaces`), so it owns no coverage and joins no union: a group whose
+     * members are all at 0 draws nothing at all, and one absent member of a
+     * connected group leaves its neighbours the pixels they would have had alone.
+     * A material scaled to nothing would still have been a silhouette, and a
+     * silhouette that eroded as it faded would be a geometric transition, which is
+     * what Apple says materializing is not.
+     *
+     * The renderer takes a value and never a time: the transit is the motion
+     * kernel's `monotonic-ease` driver, on the CPU, like every other channel here.
+     */
+    readonly materialization: number;
     /** Press point in viewport CSS px. Defaults to the surface's centre. */
     readonly pressPoint?: readonly [number, number];
 }
@@ -3649,23 +3722,15 @@ interface GroupRenderInput {
      */
     readonly backdropToneLinearLuminance?: number;
     /**
-     * The material's tint and alpha for a group that samples NOTHING (W11a) — a
-     * `css-backdrop` group whose blurred backdrop is a DOM proxy beneath the
-     * canvas, or a `none` group over the page itself. Such a group's body is
-     * not composited in the shader: the optics pass writes the material as a
-     * premultiplied layer and the browser composites it over the DOM, in
-     * encoded sRGB. A linear-light alpha written into that composite lands the
-     * surface darker than the same material sampled on the GPU — the gap
-     * `cssTintAlpha` closes for the CSS tier, at a declared reference level —
-     * so the host, which owns that mapping, resolves the pair once and hands
-     * the same numbers to both tiers. Linear light; the renderer folds the
-     * accessibility policy over it exactly as over the profile's own. Ignored
-     * wherever the group samples a backdrop; absent, the profile's pair is
-     * written as it is (the golden harness, which has no host).
+     * Enables the profile-at-tone material for a DOM layer (W27f G1).
+     * The reference is an encoded-compositing convention only, never a measured
+     * tone or permission to collapse. The profile itself stays in linear light.
+     * Absent preserves the renderer-only harness's legacy no-backdrop drawing;
+     * texture groups ignore this descriptor entirely.
      */
     readonly unsampledMaterial?: {
-        readonly tint: Rgb;
-        readonly tintAlpha: number;
+        readonly referenceBackdropLuminance: number;
+        readonly minimumTintContrast: number;
     };
     readonly variant?: MaterialVariant;
     /** Overrides the calibration-delegated union defaults. */
@@ -4269,6 +4334,17 @@ interface DrawFrameArgs {
     readonly timing?: TimingCollector;
     /** Clear the targets first. Default true. */
     readonly clear?: boolean;
+    /**
+     * Which plane these targets are, for a host that draws more than one.
+     *
+     * The renderer treats it as an opaque namespace: it qualifies each group's
+     * pooled resources (`groupResourceId`) so that one group id drawn on two
+     * planes owns two independent sets rather than reallocating one set twice a
+     * frame, and it appears in the resource labels. It names no logical group and
+     * no state. Omitted is the single-plane namespace, which is what a standalone
+     * renderer, the goldens and the calibration harness all draw in.
+     */
+    readonly plane?: string;
 }
 interface DrawFrameResult {
     readonly groupsDrawn: number;
@@ -4345,11 +4421,15 @@ interface GlassRenderer {
     /** The tunables in force. Read-only; `setMaterialProfile` is the way in. */
     readonly materialProfile: MaterialProfile;
     drawFrame(args: DrawFrameArgs): DrawFrameResult;
-    /** Targets for the participant path, where core drives the phases. */
+    /**
+     * Targets for the participant path, where core drives the phases. `plane` is
+     * `DrawFrameArgs.plane` — see it.
+     */
     setTargets(targets: {
         readonly optics: GPUTextureView;
         readonly highlight?: GPUTextureView;
         readonly format?: GPUTextureFormat;
+        readonly plane?: string;
     }): void;
     frameParticipant(): FrameParticipantView;
     /** Resolve any completed analysis readbacks into the adaptation drivers. */

package/dist/index.js

@@ -1,4 +1,4 @@
-import { MOTION_DRIVER_BY_CHANNEL, INTERACTION_STATES, SHAPE_FAMILIES } from './chunk-WM2DV3ZD.js';
+import { MOTION_DRIVER_BY_CHANNEL, INTERACTION_STATES, SHAPE_FAMILIES } from './chunk-IOTISK2R.js';
 
 // src/accessibility.ts
 var ACCESSIBILITY_FLAGS = [
@@ -1092,7 +1092,7 @@ function isHealthy(state) {
 
 // src/renderer-seam.ts
 async function loadWebGPURendererModule() {
-  return import('./dist-PT4PUS4K.js');
+  return import('./dist-T7PRMUM4.js');
 }
 async function loadWebGPURenderer() {
   const { createWebGPURenderer } = await loadWebGPURendererModule();