@vitreajs/vitrea 0.10.0 → 0.13.0

package/dist/index.d.ts

@@ -1665,9 +1665,153 @@ interface MaterialOptics {
     /** Rim band half-width in CSS px, and its ambient brightness. */
     readonly rimWidth: number;
     readonly rimAlpha: number;
-    /** Specular exponent and gain on the rim. */
+    /**
+     * **The rim band's half-width at dpr 2** (W23; claims §5.100 §5, Decision
+     * Log 2 (d)) — `rimWidth`'s second reading, on the precedent of
+     * `sizeScatterGainMax2x` and its siblings and interpolated by the same
+     * `rampAtScale`.
+     *
+     * The rim's amplitude below is one law for both scales, and it cannot be: read
+     * at the contour, vitrea's per-CSS-px band integral RISES 19 % between 1x and
+     * 2x (0.068 → 0.081) while the reference's FALLS 10 % (0.229 → 0.205), so the
+     * same amplitude that lands the 1x dark-backdrop solids at −0.003…−0.007 lands
+     * the 2x rows at +0.037…+0.051. The mismatch is the band's shape and not its
+     * height: at 1x over a dark backdrop the two rims are already the same
+     * one-pixel line (the reference's second contour row carries 8 % of the peak
+     * and vitrea's −7 %), and at 2x vitrea spreads 35 % of its peak onto the second
+     * row where the reference puts 55 % of a NARROWER line. So `rimWidth` does not
+     * move — the 1x rows do not ask it to — and the 2x band narrows instead.
+     *
+     * At dpr ≤ 1 this constant is not read at all (`rimWidthAtScale`), so a profile
+     * that carries it renders the 1x material unchanged by construction.
+     */
+    readonly rimWidth2x: number;
+    /**
+     * Specular exponent and gain on the rim — **RETIRED from the rim (W24 G2;
+     * claims §5.108 §1, W24 Decision Log 2 (a)), and the note is set beside the
+     * W22 fit below rather than over it.**
+     *
+     * The term was `max(dot(normal, lightDirection), 0)^specularPower ×
+     * specularGain`, one-sided, added to the rim's amplitude. W24 read the
+     * reference's rim around the whole contour instead of per side and found the
+     * variation it was reaching for — but symmetric about the diagonal, not
+     * one-sided: the two ends of that diagonal are drawn EQUAL to a thousandth
+     * (2x dark tl 0.0418 against br 0.0418; 2x light 0.2786 against 0.2823), and
+     * over the nineteen untinted solid rows the one-sided form reaches a
+     * normalised RMS of 0.288 against the symmetric form's 0.148, degenerating in
+     * the fit to the ceiling of both its exponent and its floor trying to become
+     * symmetric. So the shape was wrong, which is the deeper reason W22 G1 rightly
+     * fitted the gain to 0 on the regular variant (claims §5.94 §3): no amount of
+     * a term with the wrong shape helps. `rimLitExponent` below is the shape the
+     * rows chose, and it replaces this one.
+     *
+     * Nothing on either canonical bed moves: the shipped profiles carry
+     * `specularGain` 0 on `regular` since W21/W22, and no scene on either bed or in
+     * the golden suite declares `clear`. What DOES change is the `clear` variant's
+     * unfitted structural 0.45, which drew a one-sided highlight this material is
+     * now measured not to have; it is recorded rather than replaced, because the
+     * lit factor is inert on `clear` for want of rows.
+     *
+     * The two constants stay on the profile so that the W22 fit's record and the
+     * profile documents that carry it remain readable, and so that removing them
+     * is one reviewable change of the profile's SHAPE rather than a side effect of
+     * a material gate. Nothing reads them.
+     */
     readonly specularPower: number;
     readonly specularGain: number;
+    /**
+     * **The rim's amplitude law (W23; claims §5.100 §4, Decision Log 2 (a))** — the
+     * term that lets the rim depend on what it is drawn over, which `rimAlpha`
+     * alone cannot.
+     *
+     * `rimAlpha` was an additive constant: the shader added `rimWeight × rimAlpha`
+     * and nothing scaled it. The reference's rim is not a constant. Read at the
+     * contour (claims §5.99, §5.100 §2; W23 X1) the light reference's rim is
+     * +0.23…0.26 of linear luminance over a dark solid, +0.13…0.21 over a
+     * structured backdrop and clipped to white over `light-solid`, while vitrea
+     * drew the same +0.060…0.078 everywhere; and the dark reference's rim GROWS
+     * with what is behind it, +0.026 over `dark-solid` and +0.103 over
+     * `light-solid`, at a body that moves by only a twelfth as much.
+     *
+     * `rimLevelGain` is the coefficient of the surface's OWN rendered level: the
+     * rim becomes `rimAlpha + rimLevelGain × luminance(surface)`. Four candidate
+     * forms were fitted on the reference's own solid, unclipped, uncollapsed sides
+     * — 44 in light and 36 in dark, from both canonical scales and both probe grids
+     * — and this one wins in both schemes on mean |residual|: 0.0081 / 0.0013
+     * against 0.0249 / 0.0253 for the additive constant, 0.0168 / 0.0259 for a pure
+     * screen and 0.0105 / 0.0042 for screen plus an environment term.
+     *
+     * The gain is SIGNED, and its sign is the whole finding. A negative gain is the
+     * screen form — a white line composited source-over at a fraction of the body's
+     * headroom, which is what the CSS tier's inset `box-shadow` already is — and
+     * the light material's rows want one. A positive gain is a rim that rides its
+     * own body up, and the dark material's rows want that, strongly.
+     *
+     * **The environment term is not here, and its absence is a measurement.** W23
+     * chartered `rimEnvGain` — a coefficient on the backdrop source's own average
+     * luminance — as the candidate (L3) for what makes the reference's rim clip
+     * over a bright backdrop while its body is nowhere near white. It is declined
+     * and REMOVED rather than shipped at 0: it is worse than this law on the
+     * reference in both schemes, and no row of either bed separates it on vitrea's
+     * side (a rendered ladder point at +0.10 of gain moved every solid cell by 0 or
+     * 0.0005, because `light-solid` clips and the dark solids have no environment
+     * to speak of). C9a §6.2's rule is that a constant whose rows do not separate
+     * it is not carried. What the reference does there is real and is recorded in
+     * the wave's Deferred list with its numbers: a bed with a mid-bright solid
+     * backdrop under a light-scheme thick surface would tell the environment apart
+     * from the body, and no bed that exists can.
+     */
+    readonly rimLevelGain: number;
+    /**
+     * **The lit edge (W24; claims §5.107)** — the exponent of the directional
+     * factor `(√2 · |n · L|)^rimLitExponent` the rim's whole amplitude is
+     * multiplied by, with `L` the profile's `rimLitAxis`.
+     *
+     * W23 gave the rim the right AMOUNT and the wrong SHAPE. Read around the whole
+     * contour rather than per side (`results/2026-09-09-w24-lit-edge/g0/
+     * read-angular.py`), Apple's rim is not constant: on the 2x dark
+     * `dark-solid__rrect-md` the bins whose normal points north-west and
+     * south-east read 0.0408 and 0.0418 against 0.0016 for north-east and
+     * south-west, with the four straight sides at 0.0312–0.0328; the same cell in
+     * the light scheme reads 0.284 / 0.286 against 0.038, sides 0.233–0.247.
+     * vitrea drew one number everywhere — a drawn line, which is what the user's
+     * eye called an aesthetic regression on the W23 landing sheet.
+     *
+     * No per-side reader could see it, and the reason is geometric: a light on the
+     * 45° diagonal projects EQUALLY on all four straight sides, so `L−R` and
+     * `T−B` are 0 for the reference exactly as they are for vitrea. The variation
+     * lives in the corner arcs, which W23's contour reader excludes by
+     * construction and W21's band reader averages into its corner overshoot.
+     *
+     * **The form is symmetric and it is not a Lambert.** Fitted on the reference's
+     * own bins over the 19 untinted solid cells of both canonical beds and both
+     * probe grids, `(√2 · |n · L|)^p` reaches an RMS of 0.148 of each cell's own
+     * peak against 0.288 for the one-sided `max(n · L, 0)^p` that W22's `spec`
+     * term draws and 0.312 for the flat rim vitrea ships. The one-sided form
+     * cannot reach both ends of a diagonal whose two corners the reference draws
+     * equal to a thousandth, and that — not its gain — is why W22 rightly fitted
+     * `specularGain` to 0.
+     *
+     * **There is no ambient floor.** The wave chartered `a + (1 − a)|n · L|^p` with
+     * `a` expected around 0.15 dark and 0.25 light. Every grouping of the rows fits
+     * `a` to 0.000 (the search ran 0…0.6 in steps of 0.005), because the bin mean
+     * of `|cos|^p` over the 22.5° straddling the null is already 0.10–0.16 and
+     * supplies everything the null bins carry. A constant every row fits to zero is
+     * a constant the material does not have (C9a §6.2), so it is not here.
+     *
+     * **The `√2` is the amplitude's re-expression, in closed form.** W23 fitted
+     * `rimAlpha` and `rimLevelGain` on the STRAIGHT SPANS, which under this factor
+     * sit at `(cos 45°)^p` of the peak. Normalising the dot product by `cos 45°`
+     * inside the power makes the factor exactly 1 wherever the normal is
+     * horizontal or vertical, at every exponent — so no fitted amplitude moves,
+     * W23's straight-span reads hold identically rather than approximately, and
+     * only the corners and the arcs change. It is why the CSS tier, whose inset
+     * shadow cannot vary around a contour, needs no re-fit either.
+     *
+     * At 0 the factor is `pow(x, 0)` = 1 for every normal, so a profile that does
+     * not carry this constant renders the W23 material byte for byte.
+     */
+    readonly rimLitExponent: number;
     /** Inner-shadow depth (0..1) and how much of it is applied. */
     readonly shadowDepth: number;
     readonly shadowAlpha: number;
@@ -2531,6 +2675,160 @@ interface MaterialProfile {
     readonly backdropToneLow: number;
     readonly backdropToneHigh: number;
     readonly backdropToneSizeBias: number;
+    /**
+     * **The transmission the collapse keeps (W24 G1)** — and the correction, set
+     * BESIDE the paragraph above rather than over it, of what "texture collapse"
+     * was measured on.
+     *
+     * W7 fitted the collapse on `dark-solid`, a backdrop with no texture in it,
+     * and the paragraph above therefore says the collapse converges the interior
+     * on the backdrop's mean COLOUR. On a solid backdrop the mean and the pixel
+     * are the same number, so the fit could not tell the two apart; the impulse
+     * bed can, and it says they are not the same. Through the reference's
+     * collapsed `impulse__capsule-button` the centre dot still comes through at
+     * +0.0065 linear over a body of 0.0065 at 1x and +0.0254 over 0.0065 at 2x,
+     * where vitrea's collapsed capsule passes exactly 0.0000 (claims §5.107 §2).
+     * The reference's collapsed material is a dark glass that still transmits what
+     * lies beneath it, blurred — it collapses the LEVEL, not the structure.
+     *
+     * The arithmetic the collapse already has makes the correction one constant.
+     * Writing `M` for the unadapted composite this pass would otherwise produce,
+     * the (colour, alpha) pair the shader solves reduces exactly to
+     * `colour = (1 − k)·M + k·target`, and `target` is today the group's mean
+     * backdrop colour — one number for the whole surface, which is precisely what
+     * flattens the dot away at `k` 1. So `collapseTransmission` lerps the TARGET
+     * from that mean (0) to the per-pixel blurred backdrop sample the refraction
+     * path already computed (1):
+     *
+     *     target = mix(toneColour.rgb, backdrop, collapseTransmission)
+     *
+     * The tone axis's ARGUMENT is untouched — `k` is still read from the group's
+     * mean luminance and the size bias, and the response law still solves against
+     * `toneAnchor.w` — so the collapse collapses exactly as far as it did and
+     * only stops flattening what is under it. The blurred sample's mean under the
+     * surface is the group's mean to within the difference between a local and a
+     * global average, so the body's LEVEL moves by less than a code where the
+     * backdrop is anything like uniform, and not at all where it is solid: over
+     * `dark-solid` the sample IS the mean and every collapsed cell of that bed is
+     * byte-identical at any value of this constant. That is the stop the fit is
+     * checked against.
+     *
+     * At 0 the target is the mean and the shader's arithmetic is W7's to the bit,
+     * which is why this can be added without moving a pixel anywhere.
+     *
+     * What it cannot carry is the reference's WIDTH. Fitted on the reference's own
+     * dot the transmitted profile is a 4 CSS px box convolved with σ 2.63 device
+     * px at 1x and σ 1.38 device px at 2x — the same kernel the reference's
+     * UNCOLLAPSED cells show (σ 2.86 / 1.40 device px on `impulse__rrect-md`), so
+     * the collapse does not change Apple's blur, but that kernel is neither
+     * CSS-invariant nor device-invariant and vitrea's is neither of those numbers.
+     * This constant sets how MUCH comes through; how WIDE it arrives is the
+     * material's own scatter law and is recorded as a gap, not fitted here
+     * (W24 G1 findings).
+     */
+    readonly collapseTransmission: number;
+    /**
+     * **The collapse's transmission at dpr 2** (W24 G1), the second anchor of the
+     * constant above, on the pattern `sizeScatterGainMax2x` established for the
+     * body's own second scale (claims §5.69 §1).
+     *
+     * It is a per-scale reading and not a per-scheme one, and the evidence is the
+     * fixtures': the light and dark captures of the collapsed cells are the same
+     * bytes, so the collapsed appearance is one appearance in both schemes, while
+     * the width the reference transmits through is a different number at each
+     * scale. Fitted on the reference's own dot, its kernel is a 4 CSS px box
+     * convolved with σ 2.63 device px at 1x and σ 1.38 device px at 2x — a width
+     * that is invariant in neither CSS nor device pixels — so the SHARE that comes
+     * through cannot be one number over a kernel that is two.
+     *
+     * Defaults to the 1x constant, so a profile that names only that one renders
+     * it at every ratio and this anchor is the identity on the landed material.
+     */
+    readonly collapseTransmission2x: number;
+    /**
+     * **The rim that survives the collapse (W23)** — the one mark the collapsed
+     * appearance keeps.
+     *
+     * The paragraph above is right about the body and wrong about the rim. W7 read
+     * the settled reference's `dark-solid__capsule-button` as "byte-identical to
+     * its own background, rim included", and at the contour it never was: the
+     * fixture carries a body one code BELOW its backdrop and a contour rim of
+     * +0.020 linear per CSS px (55/255 on a 28/255 backdrop at 2x), in every
+     * standard profile, at both scales, in both schemes (claims §5.99). vitrea
+     * folds that rim out with everything else through the shader's one
+     * `present = 1 − toneAdapt`, and the user's eye named the result: "not one of
+     * our glasses is visible on black, where Apple's clearly show their presence."
+     *
+     * So the shader's rim becomes
+     * `rimWeight × (rimAmplitude × present + rimCollapsed × toneAdapt)`: the
+     * scheme's own rim fading out with the adaptation as it does now, and an
+     * absolute rim the collapsed appearance owns rising with it. At `toneAdapt` 0
+     * nothing changes at all, which is why this constant can be added without
+     * moving a single uncollapsed pixel.
+     *
+     * It lives on the profile and NOT in the dark patch, because the collapsed
+     * appearance is scheme-independent and the fixtures say so: the light and dark
+     * fixtures of `dark-solid__capsule-button` are byte-identical at both scales
+     * (W23 X4). A reading that separates the schemes under collapse is a finding
+     * about the wave, not a second constant. G0 strengthened the evidence: the
+     * identity survives an AUTHOR TINT — `dark-solid__capsule-button__rest-tint-
+     * orange` is the same bytes in both schemes at both scales — so what the
+     * collapse draws is one appearance however the surface was painted.
+     *
+     * It is expressed in its own units and not in the dark rim's, because the two
+     * were measured apart: see the value's own note on the default profile.
+     */
+    readonly rimCollapsed: number;
+    /**
+     * **The rim a PAINTED surface keeps under the collapse** (W23 G1; claims
+     * §5.100 §5, Decision Log 2 (c)) — `rimCollapsed`'s sibling, at the author
+     * tint's full coverage, with the two lerped by the coverage between them.
+     *
+     * The reference's collapsed capsules keep +0.020 of contour rim bare and
+     * **+0.115 painted** (`dark-solid` and `impulse` `capsule-button`
+     * `rest-tint-orange`, both schemes, both scales, on fixtures that are the same
+     * bytes in the two schemes). An author tint over black is painted, not
+     * adapted: the tone collapse takes the material's own appearance to its
+     * backdrop and the colour the author put on it does not go with it.
+     *
+     * It is ABSOLUTE, in its own units, for the same reason `rimCollapsed` is and
+     * on the same evidence — and G1 measured what the alternative would have cost.
+     * Decision Log 2 (c) proposed gating the collapse itself on the tint's
+     * coverage, so that a painted surface keeps its APPEARANCE's own rim; rendered,
+     * that mechanism needs a gate of 0.534 on the light bed and 0.294 on the dark
+     * one to reach +0.115 on a cell whose reference fixture is byte-identical
+     * between the schemes, because it makes the kept rim proportional to each
+     * scheme's own amplitude law and those differ by 1.8× there. A proportional
+     * form cannot draw one appearance from two materials; an absolute one does,
+     * which is X4 again and the reason this constant has the shape it has.
+     *
+     * It is fitted on orange alone, and that is a stated limit: the reference's
+     * collapsed tint-blue capsule reads +0.176 against orange's +0.115, so the
+     * quantity depends on the tint's own colour, and every collapsed blue cell on
+     * the bed is holdout. What lands here is the orange rows' answer with the
+     * colour dependence recorded as future work.
+     */
+    readonly rimCollapsedTinted: number;
+    /**
+     * **How much of an author tint's own colour the rim's light is spent in**
+     * (W23 G3; claims §5.102) — 0…1, multiplied by the surface's tint coverage.
+     *
+     * Apple's rim on a painted surface is the paint LIFTED, not white added over
+     * it. Read on the contour row's straight-span mean colour at 2x in light, an
+     * orange paint of (255, 148, 0) rises to (254, 188, 0) with its blue channel
+     * still at 0, and a blue paint of (8, 120, 236) to (59, 199, 248); vitrea drew
+     * (255, 192, 130) and (145, 183, 255) — the same rim in white, which turns an
+     * orange edge peach and a blue edge lilac. No luminance clause sees it: the
+     * rim's amplitude is right and its colour is not.
+     *
+     * So the rim's light is spent in `mix(white, paint / max(paint), chroma × s)`.
+     * The paint is normalised by its own brightest channel rather than by its
+     * luminance, so a dark paint darkens the rim's HUE and not its amount, and the
+     * factor is the pixel's own tint strength, so an untinted surface keeps a white
+     * rim at every value of this constant — which is what makes the mechanism reach
+     * painted pixels only and every untinted capture byte-identical (W23 S10).
+     */
+    readonly rimTintChroma: number;
     /**
      * **The backdrop tone response (W9)** — the law that owns the interior MEAN,
      * where the four constants above own texture collapse and nothing else.
@@ -2591,6 +2889,31 @@ interface MaterialProfile {
      * specular from.
      */
     readonly lightDirection: readonly [number, number];
+    /**
+     * **The lit edge's axis (W24; claims §5.107)** — the unit direction `L` the
+     * rim's directional factor is symmetric about, in the same viewport
+     * coordinates as `lightDirection`, y pointing down.
+     *
+     * It is a SEPARATE constant from `lightDirection` and not a second reading of
+     * it, for two reasons the rows give. First, they are measured to differ: the
+     * rim's axis fits at 136° of compass bearing over the 19 solid rows (135.0° ±
+     * 0.7° over the dark rows alone, 137.7° ± 1.5° over the light ones), where
+     * `lightDirection` [−0.3714, −0.9285] is a bearing of 338.2°, an axis of
+     * 158.2° — 22° away, and it was fitted for the inner shadow and the sweep, not
+     * for the contour. Second, `light.xy` reaches the one-sided `spec` term this
+     * factor replaces, and re-pointing it to fit the contour would move the
+     * shadow's own light with it; a constant of its own keeps that seam where W2
+     * and W22 left it.
+     *
+     * The default is the exact diagonal (−1, −1)/√2 — a bearing of 135° — and not
+     * the fitted 136°: the rows do not separate the two (the joint fit's RMS moves
+     * by less than a thousandth between them), and only the exact diagonal makes
+     * the factor equal on all four straight sides, which is what lets the
+     * amplitude's re-expression be exact rather than a 2 % trade against W23's
+     * straight-span reads. `rimLitExponent` is 0, so the axis draws nothing until a
+     * profile carries an exponent.
+     */
+    readonly rimLitAxis: readonly [number, number];
     /** Specular sweep band width in radians, and the press glow's reach in CSS px. */
     readonly sweepBandRadians: number;
     readonly glowRadiusCss: number;
@@ -2653,12 +2976,18 @@ interface MaterialProfilePatch {
     readonly backdropToneLow?: number;
     readonly backdropToneHigh?: number;
     readonly backdropToneSizeBias?: number;
+    readonly collapseTransmission?: number;
+    readonly collapseTransmission2x?: number;
+    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 backdropToneResponseStrength?: number;
     readonly outerShadow?: Readonly<Partial<MaterialOuterShadow>>;
     readonly lightDirection?: readonly [number, number];
+    readonly rimLitAxis?: readonly [number, number];
     readonly sweepBandRadians?: number;
     readonly glowRadiusCss?: number;
     readonly glowGain?: number;
@@ -2926,6 +3255,16 @@ interface SurfaceChannels {
     readonly glow: number;
     /** Specular sweep position, 0..1 around the contour. */
     readonly sweep: number;
+    /**
+     * The shimmer's amplitude, 0..1 — the sweep's gain rather than its position.
+     *
+     * The band's angular coordinate covers the whole contour, so no phase is off
+     * the surface and the phase alone cannot mean "not shimmering"; this channel
+     * carries that. It is 0 on a resting surface, which makes the highlight pass's
+     * sweep term exactly zero there, and it is what a shimmer driver will output
+     * when v1 gains one.
+     */
+    readonly shimmer: number;
     /** `lensStrength`, 0..1. Multiplies the resolved refraction scale. */
     readonly lensStrength: number;
     /** Press point in viewport CSS px. Defaults to the surface's centre. */

package/dist/index.js

@@ -1092,7 +1092,7 @@ function isHealthy(state) {
 
 // src/renderer-seam.ts
 async function loadWebGPURendererModule() {
-  return import('./dist-3OXBJGMC.js');
+  return import('./dist-2V7EQHSR.js');
 }
 async function loadWebGPURenderer() {
   const { createWebGPURenderer } = await loadWebGPURendererModule();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vitreajs/vitrea",
-  "version": "0.10.0",
+  "version": "0.13.0",
   "description": "Framework-agnostic Liquid Glass material runtime: scene model, capability resolution, material policy, accessibility policy.",
   "license": "Apache-2.0",
   "homepage": "https://github.com/SSFSKIM/designer",