@satinhq/kit 0.0.0-stage → 0.1.0-beta.0

package/dist/glass/submenuMotion.js

@@ -0,0 +1,306 @@
+import { animateElement, timelineStart } from '../motion/animate.js';
+import { menuSpring } from './lens/menuSpring.js';
+import { setGlassShapeTrack } from './shapeTrackRegistry.js';
+import { shapeTrackClock, shapeTrackEnvelope, shapeTrackFrame, } from './shapeTrack.js';
+import { springMotion, springTrack, sampledKeyframes, } from '../motion/springTrack.js';
+/**
+ * Nested menus, measured from stock SwiftUI on iOS 27.0 (submenus/SPEC.md).
+ *
+ * iPhone stacks each submenu over its parent: the parent shrinks to 0.97 about its top edge and
+ * its rows dim to half ink, and the child grows out of the row that opened it into a full-width
+ * platter whose title row sits 12 pt above where that row now is. iPad opens a cascade beside the
+ * parent instead: the child overlaps the parent's edge by 12 pt and its first row lines up with
+ * the row that opened it, while the parent stays as it was.
+ *
+ * Springs are fitted per track from a 60 Hz presentation-layer trace of the native Simulator
+ * (submenus-impl/fit-open-child.json and fit-back.json; RMS residuals under 0.2 pt / 0.004 ink).
+ * Forward and back are fitted separately: the child opens slightly underdamped (zeta 0.85) and
+ * collapses critically damped (zeta 1.0). The iPad cascade's motion is unmeasured; it uses the
+ * same child springs until an iPad trace exists.
+ *
+ * Only the glass changes size. The same trace shows the child's rows keeping their full size
+ * throughout: on the way back the glass shrinks around the title row while the rows drift 3.6 pt,
+ * so the title lands exactly on the row that opened it, and the title's chevron turns from down to
+ * forward on its own spring (measured Oct 13: the content and chevron fits).
+ */
+export const SUBMENU_GEOMETRY = {
+    /** Each ancestor level below the top submenu shrinks by this much more (0.97, 0.94, ...). */
+    parentScaleStep: 0.03,
+    /** Ink of an ancestor's rows while a submenu covers it. */
+    parentInk: 0.5,
+    /** The child's top sits this far above the (scaled) top of the row that opened it. */
+    phoneTitleLift: 12,
+    /** The iPad child overlaps the parent's edge by this much. */
+    padEdgeOverlap: 12,
+    /** The iPad child's first row starts this far above the row that opened it. */
+    padRowLift: 1,
+};
+const OPEN = {
+    /** Width, height and x of the child's glass: one spring. */
+    frame: { stiffness: 249.05, damping: 26.89 },
+    /** The glass's top settles faster than its size (overdamped). */
+    top: { stiffness: 1027.7, damping: 107.3 },
+    /** The child's rows keep their size and move only from the opening row to their place. */
+    content: { stiffness: 608.68, damping: 108.1 },
+    /** The title's chevron turns from pointing forward to pointing down. */
+    chevron: { stiffness: 1200, damping: 73.44 },
+    parentScale: { stiffness: 257.9, damping: 27.7 },
+    /** The parent's rows start dimming 50 ms after the child starts to grow. */
+    parentInk: { stiffness: 92.36, damping: 16.26, delay: 50 },
+};
+const BACK = {
+    frame: { stiffness: 246.2, damping: 31.35 },
+    top: { stiffness: 194.1, damping: 26.41 },
+    parentScale: { stiffness: 216.3, damping: 27.78 },
+    parentInk: { stiffness: 241.1, damping: 30.74 },
+    /** The child's rows fade out as it collapses into its row. */
+    fade: { stiffness: 157.5, damping: 25.07 },
+    /** The rows keep their size and move only until the title sits on the row that opened it. */
+    content: { stiffness: 148, damping: 21.41 },
+    /** The title's chevron turns back from pointing down to pointing forward. */
+    chevron: { stiffness: 150, damping: 24 },
+};
+export const SUBMENU_SPRINGS = { open: OPEN, back: BACK };
+/** Progress (0 to 1) of a measured spring `ms` after it starts. */
+export function springProgress(parameters, ms) {
+    return 1 - menuSpring(springMotion(parameters), ms).value;
+}
+/** Compositor keyframes for one measured spring, from `from` to `to`. */
+export function springKeyframes(parameters, frame) {
+    const track = springTrack(springMotion(parameters));
+    return { keyframes: sampledKeyframes(track, frame), duration: track.duration };
+}
+/** Scale of a level that has `covering` submenu levels open above it. */
+export function ancestorScale(covering) {
+    return 1 - SUBMENU_GEOMETRY.parentScaleStep * covering;
+}
+/**
+ * Where a phone submenu settles, in the root platter's coordinates. `parent` is the parent
+ * platter's resting frame and `row` the opening row's resting frame; the parent then shrinks to
+ * `parentScale` about its top edge.
+ */
+export function phoneSubmenuFrame(parent, row, parentScale, child, bounds) {
+    const scaledRowTop = parent.y + (row.y - parent.y) * parentScale;
+    const y = scaledRowTop - SUBMENU_GEOMETRY.phoneTitleLift;
+    return {
+        x: parent.x + (parent.width - child.width) / 2,
+        y: clamp(y, bounds.y, bounds.y + bounds.height - child.height),
+        width: child.width,
+        height: child.height,
+    };
+}
+/**
+ * Where an iPad submenu settles: beside the parent, overlapping its trailing edge, with its first
+ * row level with the opening row. It flips to the leading side when the trailing side has no room.
+ */
+export function padSubmenuFrame(parent, row, child, bounds) {
+    const overlap = SUBMENU_GEOMETRY.padEdgeOverlap;
+    const trailing = parent.x + parent.width - overlap;
+    const leading = parent.x + overlap - child.width;
+    const fitsTrailing = trailing + child.width <= bounds.x + bounds.width;
+    const y = row.y - SUBMENU_GEOMETRY.padRowLift - child.firstRowOffset;
+    // A window too narrow for either side keeps the child on screen over more of its parent.
+    const x = fitsTrailing || leading < bounds.x ? trailing : leading;
+    return {
+        x: clamp(x, bounds.x, bounds.x + bounds.width - child.width),
+        y: clamp(y, bounds.y, bounds.y + bounds.height - child.height),
+        width: child.width,
+        height: child.height,
+    };
+}
+function clamp(value, min, max) {
+    return Math.max(min, Math.min(value, Math.max(min, max)));
+}
+/** Glass frames are sampled at 120 Hz; the renderer and the page interpolate between them. */
+const SAMPLE_MS = 1000 / 120;
+/**
+ * The child's glass frame from `from` to `to`, sampled from the measured springs until it settles:
+ * x, width and height share one spring and the top has its own.
+ */
+export function submenuGlassFrames(from, to, direction) {
+    const springs = SUBMENU_SPRINGS[direction];
+    const frames = [];
+    for (let ms = 0;; ms += SAMPLE_MS) {
+        const size = springProgress(springs.frame, ms);
+        const top = springProgress(springs.top, ms);
+        const settled = Math.abs(1 - size) * Math.max(Math.abs(to.height - from.height), 1) < 0.05 &&
+            Math.abs(1 - top) * Math.max(Math.abs(to.y - from.y), 1) < 0.05;
+        if (settled || ms > 3000) {
+            frames.push(to);
+            break;
+        }
+        frames.push({
+            x: from.x + (to.x - from.x) * size,
+            y: from.y + (to.y - from.y) * top,
+            width: from.width + (to.width - from.width) * size,
+            height: from.height + (to.height - from.height) * size,
+        });
+    }
+    return { frames, duration: (frames.length - 1) * SAMPLE_MS };
+}
+/**
+ * Where a phone child's content must sit for its title row to cover the row that opened it:
+ * `titleOffset` is the title row's position inside the content. The child grows out of that place
+ * and collapses back into it, so the title never jumps when the platter appears or leaves.
+ */
+export function titleOnRow(row, titleOffset) {
+    return { x: row.x - titleOffset.x, y: row.y - titleOffset.y };
+}
+/** The content's position `ms` into a transition from `from` to `to`. */
+export function submenuContentAt(from, to, direction, ms) {
+    const progress = springProgress(SUBMENU_SPRINGS[direction].content, ms);
+    return { x: from.x + (to.x - from.x) * progress, y: from.y + (to.y - from.y) * progress };
+}
+/** Compositor keyframes that turn the title's chevron: forward is a quarter turn back from down. */
+export function chevronKeyframes(direction, fromDegrees) {
+    const forward = -90;
+    const start = fromDegrees ?? (direction === 'open' ? forward : 0);
+    const end = direction === 'open' ? 0 : forward;
+    return springKeyframes(SUBMENU_SPRINGS[direction].chevron, progress => ({
+        transform: `rotate(${start + (end - start) * progress}deg)`,
+    }));
+}
+const visibleFrames = new WeakMap();
+const contentPlaces = new WeakMap();
+const activeRuns = new WeakMap();
+/** Where a platter's glass is now (not its layout box, which may be larger while it moves). */
+export function submenuVisibleFrame(platter) {
+    return activeRuns.get(platter)?.frame() ?? visibleFrames.get(platter);
+}
+/**
+ * Move a child platter's glass from `from` to `to` on the measured springs, and its content from
+ * `contentFrom` to `contentTo` on its own spring.
+ *
+ * The platter's layout box holds the envelope of every frame of the run, so its glass canvas never
+ * resizes or moves: the backdrop stays where it is on screen and only the glass's edge moves
+ * (shapeTrack.ts). The glass is drawn from a shape track, and the content is clipped to the same
+ * frames, read from the same track. Returns a function that stops the motion where it is.
+ */
+export function animateSubmenuFrame(parts, from, to, contentFrom, contentTo, direction, done) {
+    const run = startRun(parts, from, to, direction, shapeTrackClock());
+    const { envelope, track } = run;
+    // Sample content until the same positional tolerance used by the old frame loop.
+    let duration = track.duration;
+    while (Math.hypot(contentTo.x - submenuContentAt(contentFrom, contentTo, direction, duration).x, contentTo.y - submenuContentAt(contentFrom, contentTo, direction, duration).y) >= 0.05 &&
+        duration < 10000)
+        duration += SAMPLE_MS;
+    const count = Math.max(1, Math.ceil(duration / SAMPLE_MS));
+    duration = count * SAMPLE_MS;
+    const placeAt = (age) => age >= duration
+        ? contentTo
+        : submenuContentAt(contentFrom, contentTo, direction, Math.max(0, age));
+    const contentFrames = [];
+    const clipFrames = [];
+    for (let index = 0; index <= count; index++) {
+        const age = index * SAMPLE_MS;
+        contentFrames.push({ offset: index / count, transform: run.transform(placeAt(age)) });
+        clipFrames.push({ offset: index / count, clipPath: run.clipPath(track.epoch + age) });
+    }
+    run.write(track.epoch, contentFrom);
+    const options = { duration, easing: 'linear', fill: 'both' };
+    const animations = [
+        animateElement(parts.content, contentFrames, options),
+        // The rounded clip must follow the glass without scaling the rows or their corners.
+        // WAAPI owns this track; compositor acceleration of clip-path needs WebKit evidence.
+        animateElement(parts.clip, clipFrames, options),
+    ];
+    const start = timelineStart(track.epoch - performance.timeOrigin);
+    for (const animation of animations)
+        animation.startTime = start;
+    const live = {
+        frame: () => run.frameAt(shapeTrackClock()),
+        content: () => placeAt(shapeTrackClock() - track.epoch),
+    };
+    activeRuns.set(parts.platter, live);
+    let stopped = false;
+    const stop = (finished) => {
+        if (stopped)
+            return;
+        stopped = true;
+        const at = finished ? track.epoch + duration : shapeTrackClock();
+        run.write(at, finished ? contentTo : placeAt(at - track.epoch));
+        // Freeze the renderer at the same point before a reversal or whole-menu dismissal.
+        const frame = shapeTrackFrame(track, at);
+        setGlassShapeTrack(parts.glass, { epoch: Number.MAX_VALUE, duration: 0, frames: [frame] });
+        if (activeRuns.get(parts.platter) === live)
+            activeRuns.delete(parts.platter);
+        for (const animation of animations)
+            animation.cancel();
+        if (finished) {
+            if (sameFrame(envelope, to)) {
+                setGlassShapeTrack(parts.glass, undefined);
+                parts.clip.style.clipPath = '';
+            }
+            done?.();
+        }
+    };
+    void Promise.all(animations.map(animation => animation.finished)).then(() => stop(true), () => { });
+    return () => stop(false);
+}
+/**
+ * Lay a platter out for a run that has not started: its box is already the run's envelope and its
+ * glass holds the first frame, so the glass the platter first appears with is drawn in the canvas
+ * the whole run keeps.
+ */
+export function holdSubmenuFrame(parts, from, to, contentFrom, direction) {
+    const run = startRun(parts, from, to, direction, Number.MAX_VALUE);
+    run.write(run.track.epoch, contentFrom);
+}
+/** Fix the run's envelope as the platter's layout box and give its glass the run's shape track. */
+function startRun(parts, from, to, direction, epoch) {
+    const { platter, glass, clip, content, cornerRadius } = parts;
+    const { frames, duration } = submenuGlassFrames(from, to, direction);
+    const laidOut = layoutBox(platter);
+    const envelope = shapeTrackEnvelope(laidOut ? [laidOut, ...frames] : frames);
+    writeBox(platter, envelope);
+    const local = (frame) => ({ ...frame, x: frame.x - envelope.x, y: frame.y - envelope.y });
+    const track = { epoch, duration, frames: frames.map(local) };
+    setGlassShapeTrack(glass, track);
+    const frameAt = (at) => {
+        const frame = shapeTrackFrame(track, at);
+        return { ...frame, x: frame.x + envelope.x, y: frame.y + envelope.y };
+    };
+    const transform = (place) => `translate(${place.x - envelope.x}px, ${place.y - envelope.y}px)`;
+    const clipPath = (at) => {
+        const frame = shapeTrackFrame(track, at);
+        const radius = Math.min(cornerRadius, frame.width / 2, frame.height / 2);
+        const right = envelope.width - frame.x - frame.width;
+        const bottom = envelope.height - frame.y - frame.height;
+        return `inset(${frame.y}px ${right}px ${bottom}px ${frame.x}px round ${radius}px)`;
+    };
+    // Writes happen only at admission, interruption and settlement, never per display frame.
+    const write = (at, place) => {
+        clip.style.clipPath = clipPath(at);
+        content.style.transform = transform(place);
+        visibleFrames.set(platter, frameAt(at));
+        contentPlaces.set(platter, place);
+    };
+    return { envelope, track, write, frameAt, transform, clipPath };
+}
+/** Where a platter's content sits now, if a transition has placed it. */
+export function submenuContentPlace(platter) {
+    return activeRuns.get(platter)?.content() ?? contentPlaces.get(platter);
+}
+function layoutBox(element) {
+    const style = element.style;
+    if (!style.width || !style.height)
+        return undefined;
+    return {
+        x: parseFloat(style.left),
+        y: parseFloat(style.top),
+        width: parseFloat(style.width),
+        height: parseFloat(style.height),
+    };
+}
+function writeBox(element, box) {
+    element.style.left = `${box.x}px`;
+    element.style.top = `${box.y}px`;
+    element.style.width = `${box.width}px`;
+    element.style.height = `${box.height}px`;
+}
+function sameFrame(a, b) {
+    return (Math.abs(a.x - b.x) < 0.25 &&
+        Math.abs(a.y - b.y) < 0.25 &&
+        Math.abs(a.width - b.width) < 0.25 &&
+        Math.abs(a.height - b.height) < 0.25);
+}

package/dist/glass/tabBarModel.d.ts

@@ -0,0 +1,12 @@
+import type { TabBarItem } from './TabBar.js';
+/** A bottom accessory expands native phone tabs to the full dock. */
+export declare const TabBarAccessoryContext: import("react").Context<boolean>;
+/** iOS 27 intrinsic platters have 8 pt end margins and 8 pt overlapping selections. */
+export declare function intrinsicTabGeometry(width: number, count: number): {
+    centres: number[];
+    selectionWidth: number;
+};
+export declare function isSupportedTabCount(count: number): boolean;
+export declare function resolveTabBarModel(items: readonly TabBarItem[], selected: string, allowUnselected?: boolean): {
+    selectedIndex: number;
+};

package/dist/glass/tabBarModel.js

@@ -0,0 +1,32 @@
+import { createContext } from 'react';
+/** A bottom accessory expands native phone tabs to the full dock. */
+export const TabBarAccessoryContext = createContext(false);
+/** iOS 27 intrinsic platters have 8 pt end margins and 8 pt overlapping selections. */
+export function intrinsicTabGeometry(width, count) {
+    const spacing = (width - 16) / count;
+    return {
+        centres: Array.from({ length: count }, (_, index) => 8 + spacing * (index + 0.5)),
+        selectionWidth: spacing + 8,
+    };
+}
+export function isSupportedTabCount(count) {
+    return count >= 2 && count <= 5;
+}
+export function resolveTabBarModel(items, selected, allowUnselected = false) {
+    if (!isSupportedTabCount(items.length)) {
+        throw new Error('TabBar requires between two and five controlled items.');
+    }
+    const ids = new Set();
+    for (const item of items) {
+        if (!item.id)
+            throw new Error('TabBar item ids must be non-empty.');
+        if (ids.has(item.id))
+            throw new Error(`TabBar item id "${item.id}" is duplicated.`);
+        ids.add(item.id);
+    }
+    const selectedIndex = items.findIndex(item => item.id === selected);
+    if (selectedIndex < 0 && !allowUnselected) {
+        throw new Error(`TabBar selected id "${selected}" is not registered.`);
+    }
+    return { selectedIndex };
+}

package/dist/glass/testing.d.ts

@@ -0,0 +1,14 @@
+export * from './renderSpecs.js';
+export * from './lens/Scene.js';
+export * from './lens/theme.js';
+export * from './lens/referenceBackground.js';
+export * from './lens/motion.js';
+export * from './lens/trace.js';
+export * from './lens/icons.js';
+export * from './lens/liquidMotion.js';
+export * from './lens/menuMotion.js';
+export * from './lens/tabSelectionMaterial.js';
+export * from './lens/tabPresentation.js';
+export { GlassPresentation as GlassSpecimen } from './GlassPresentation.js';
+export * from './lens/bitmapBackdrop.js';
+export { GlassConfusionReview } from './GlassConfusionReview.js';

package/dist/glass/testing.js

@@ -0,0 +1,14 @@
+export * from './renderSpecs.js';
+export * from './lens/Scene.js';
+export * from './lens/theme.js';
+export * from './lens/referenceBackground.js';
+export * from './lens/motion.js';
+export * from './lens/trace.js';
+export * from './lens/icons.js';
+export * from './lens/liquidMotion.js';
+export * from './lens/menuMotion.js';
+export * from './lens/tabSelectionMaterial.js';
+export * from './lens/tabPresentation.js';
+export { GlassPresentation as GlassSpecimen } from './GlassPresentation.js';
+export * from './lens/bitmapBackdrop.js';
+export { GlassConfusionReview } from './GlassConfusionReview.js';

package/dist/glass/tokens.d.ts

@@ -0,0 +1,79 @@
+export type GlassVariant = 'regular' | 'clear';
+export declare const GLASS_BAR_HEIGHT_PX = 54;
+export declare const GLASS_TAB_BAR_HEIGHT_PX = 60;
+export declare const GLASS_TAB_BAR_INLINE_INSET_PX = 16;
+export declare const GLASS_TAB_BAR_BOTTOM_GAP_PX = 21;
+export declare const GLASS_COMPACT_TAB_BAR_HEIGHT_PX = 44;
+export declare const GLASS_COMPACT_TAB_BAR_BOTTOM_GAP_PX = 20;
+export declare const GLASS_CONTROL_SIZE_PX = 44;
+export declare const GLASS_LENS_STRENGTH = 0.1;
+export declare const GLASS_LENS_CHROMATIC_ABERRATION = 0.2;
+export declare const GLASS_LENS_BLUR_PX = 0;
+export declare const GLASS_LENS_DEPTH_PX = 10;
+export declare const GLASS_LENS_CURVATURE = 0.65;
+export declare const GLASS_LENS_SPLAY = 1;
+export declare const GLASS_LENS_GLOW = 0.1;
+export declare const GLASS_LENS_GLOW_SPREAD = 1;
+export declare const GLASS_LENS_GLOW_EXPONENT = 1.5;
+export declare const GLASS_LENS_EDGE_HIGHLIGHT = 0.25;
+export declare const GLASS_LENS_EDGE_WIDTH_PX = 3;
+export declare const GLASS_LENS_EDGE_EXPONENT = 1.5;
+export declare const GLASS_LENS_SPECULAR = 1;
+export declare const GLASS_LENS_SPECULAR_ANGLE_DEG = 45;
+export declare const GLASS_REGULAR_SATURATION = 1.04;
+export declare const GLASS_CLEAR_SATURATION = 1;
+export declare const GLASS_REGULAR_BRIGHTNESS = 1.02;
+export declare const GLASS_CLEAR_BRIGHTNESS = 1;
+export declare const GLASS_TINT_RGB = "255 255 255";
+export declare const GLASS_REGULAR_TINT_ALPHA = 0.06;
+export declare const GLASS_CLEAR_TINT_ALPHA = 0;
+export declare const GLASS_RIM_HIGHLIGHT_ALPHA = 0.25;
+export declare const GLASS_RIM_SHADOW_ALPHA = 0.35;
+export declare const GLASS_BAR_EDGE_HIGHLIGHT_ALPHA = 0.25;
+export declare const GLASS_BAR_SHADOW_ALPHA = 0.2;
+export declare const GLASS_SELECTION_DURATION_MS = 300;
+export declare const GLASS_SELECTION_EASING = "cubic-bezier(0.2, 0.82, 0.2, 1)";
+export declare const glassTokens: Readonly<{
+    barHeight: 54;
+    tabBarHeight: 60;
+    tabBarInlineInset: 16;
+    tabBarBottomGap: 21;
+    controlSize: 44;
+    lens: Readonly<{
+        blur: 0;
+        chromaticAberration: 0.2;
+        curvature: 0.65;
+        depth: 10;
+        edgeExponent: 1.5;
+        edgeHighlight: 0.25;
+        edgeWidth: 3;
+        glow: 0.1;
+        glowExponent: 1.5;
+        glowSpread: 1;
+        specular: 1;
+        specularAngle: 45;
+        splay: 1;
+        strength: 0.1;
+    }>;
+    regular: Readonly<{
+        brightness: 1.02;
+        saturation: 1.04;
+        tintAlpha: 0.06;
+    }>;
+    clear: Readonly<{
+        brightness: 1;
+        saturation: 1;
+        tintAlpha: 0;
+    }>;
+    rim: Readonly<{
+        barEdgeHighlightAlpha: 0.25;
+        barShadowAlpha: 0.2;
+        highlightAlpha: 0.25;
+        shadowAlpha: 0.35;
+    }>;
+    tintRgb: "255 255 255";
+    selection: Readonly<{
+        duration: 300;
+        easing: "cubic-bezier(0.2, 0.82, 0.2, 1)";
+    }>;
+}>;

package/dist/glass/tokens.js

@@ -0,0 +1,86 @@
+export const GLASS_BAR_HEIGHT_PX = 54;
+export const GLASS_TAB_BAR_HEIGHT_PX = 60;
+export const GLASS_TAB_BAR_INLINE_INSET_PX = 16;
+// UIKit's iOS 27 floating tab platter ends 21 pt above the physical screen
+// bottom. This is a screen-edge offset, not extra padding above WebKit's
+// reported safe-area inset; UIKit deliberately occupies the bottom safe area.
+export const GLASS_TAB_BAR_BOTTOM_GAP_PX = 21;
+// Rough-edges native reference: compact phone platter occupies y376–420 in a 440 pt screen.
+export const GLASS_COMPACT_TAB_BAR_HEIGHT_PX = 44;
+export const GLASS_COMPACT_TAB_BAR_BOTTOM_GAP_PX = 20;
+export const GLASS_CONTROL_SIZE_PX = 44;
+// Optical defaults ported from liquid-glass-web-react under the MIT license.
+// The map adapts strength to each registered bar's own geometry.
+export const GLASS_LENS_STRENGTH = 0.1;
+export const GLASS_LENS_CHROMATIC_ABERRATION = 0.2;
+export const GLASS_LENS_BLUR_PX = 0;
+export const GLASS_LENS_DEPTH_PX = 10;
+export const GLASS_LENS_CURVATURE = 0.65;
+export const GLASS_LENS_SPLAY = 1;
+export const GLASS_LENS_GLOW = 0.1;
+export const GLASS_LENS_GLOW_SPREAD = 1;
+export const GLASS_LENS_GLOW_EXPONENT = 1.5;
+export const GLASS_LENS_EDGE_HIGHLIGHT = 0.25;
+export const GLASS_LENS_EDGE_WIDTH_PX = 3;
+export const GLASS_LENS_EDGE_EXPONENT = 1.5;
+export const GLASS_LENS_SPECULAR = 1;
+export const GLASS_LENS_SPECULAR_ANGLE_DEG = 45;
+// The CSS-only fallback stays close to passthrough. It supplies a restrained
+// bright material and rim when the foreground displacement gate is unavailable.
+export const GLASS_REGULAR_SATURATION = 1.04;
+export const GLASS_CLEAR_SATURATION = 1;
+export const GLASS_REGULAR_BRIGHTNESS = 1.02;
+export const GLASS_CLEAR_BRIGHTNESS = 1;
+export const GLASS_TINT_RGB = '255 255 255';
+export const GLASS_REGULAR_TINT_ALPHA = 0.06;
+export const GLASS_CLEAR_TINT_ALPHA = 0;
+export const GLASS_RIM_HIGHLIGHT_ALPHA = 0.25;
+export const GLASS_RIM_SHADOW_ALPHA = 0.35;
+export const GLASS_BAR_EDGE_HIGHLIGHT_ALPHA = 0.25;
+export const GLASS_BAR_SHADOW_ALPHA = 0.2;
+export const GLASS_SELECTION_DURATION_MS = 300;
+export const GLASS_SELECTION_EASING = 'cubic-bezier(0.2, 0.82, 0.2, 1)';
+export const glassTokens = Object.freeze({
+    barHeight: GLASS_BAR_HEIGHT_PX,
+    tabBarHeight: GLASS_TAB_BAR_HEIGHT_PX,
+    tabBarInlineInset: GLASS_TAB_BAR_INLINE_INSET_PX,
+    tabBarBottomGap: GLASS_TAB_BAR_BOTTOM_GAP_PX,
+    controlSize: GLASS_CONTROL_SIZE_PX,
+    lens: Object.freeze({
+        blur: GLASS_LENS_BLUR_PX,
+        chromaticAberration: GLASS_LENS_CHROMATIC_ABERRATION,
+        curvature: GLASS_LENS_CURVATURE,
+        depth: GLASS_LENS_DEPTH_PX,
+        edgeExponent: GLASS_LENS_EDGE_EXPONENT,
+        edgeHighlight: GLASS_LENS_EDGE_HIGHLIGHT,
+        edgeWidth: GLASS_LENS_EDGE_WIDTH_PX,
+        glow: GLASS_LENS_GLOW,
+        glowExponent: GLASS_LENS_GLOW_EXPONENT,
+        glowSpread: GLASS_LENS_GLOW_SPREAD,
+        specular: GLASS_LENS_SPECULAR,
+        specularAngle: GLASS_LENS_SPECULAR_ANGLE_DEG,
+        splay: GLASS_LENS_SPLAY,
+        strength: GLASS_LENS_STRENGTH,
+    }),
+    regular: Object.freeze({
+        brightness: GLASS_REGULAR_BRIGHTNESS,
+        saturation: GLASS_REGULAR_SATURATION,
+        tintAlpha: GLASS_REGULAR_TINT_ALPHA,
+    }),
+    clear: Object.freeze({
+        brightness: GLASS_CLEAR_BRIGHTNESS,
+        saturation: GLASS_CLEAR_SATURATION,
+        tintAlpha: GLASS_CLEAR_TINT_ALPHA,
+    }),
+    rim: Object.freeze({
+        barEdgeHighlightAlpha: GLASS_BAR_EDGE_HIGHLIGHT_ALPHA,
+        barShadowAlpha: GLASS_BAR_SHADOW_ALPHA,
+        highlightAlpha: GLASS_RIM_HIGHLIGHT_ALPHA,
+        shadowAlpha: GLASS_RIM_SHADOW_ALPHA,
+    }),
+    tintRgb: GLASS_TINT_RGB,
+    selection: Object.freeze({
+        duration: GLASS_SELECTION_DURATION_MS,
+        easing: GLASS_SELECTION_EASING,
+    }),
+});

package/dist/glass/toolbarMaterialContext.d.ts

@@ -0,0 +1,28 @@
+import { type ReactNode } from 'react';
+import type { Glass, GlassShape } from './regions.js';
+/** Navigation glass items own material independently of entry content opacity. */
+export declare const ToolbarMaterialContext: import("react").Context<boolean>;
+export type ToolbarMaterial = {
+    glass: Glass;
+    shape: GlassShape;
+    press?: 'button' | 'bar' | 'menu';
+};
+/** A child describes the slot's material without registering a second renderer region. */
+export declare const toolbarMaterials: WeakMap<HTMLElement, ToolbarMaterial>;
+/** Each run of top-level glass items gets a persistent placement/index owner. */
+export declare function toolbarMaterialOwner(content: HTMLElement | null | undefined): HTMLElement | null | undefined;
+export declare function toolbarMaterialItems(slot: HTMLElement | undefined): HTMLElement[];
+/** Items of consecutive `ToolbarItem`s (one each, with no spacer between) share one glass capsule,
+ * as iOS 26+ merges adjacent bar items of a placement. The principal placement never merges. */
+export declare function toolbarMaterialRuns(slot: HTMLElement | undefined): HTMLElement[][];
+/** SearchDrawer hides the bar items of a screen presenting search; they own no glass. */
+export declare function toolbarSearchHidden(element: HTMLElement): boolean;
+export declare function bindToolbarMaterialContent(material: HTMLElement, content: HTMLElement): void;
+export declare function toolbarMaterialContent(material: HTMLElement): HTMLElement;
+/** Every content item carried by the same glass capsule as this trigger. */
+export declare function toolbarMenuContents(trigger: HTMLElement | null | undefined): HTMLElement[];
+export declare function toolbarMenuTrigger(trigger: HTMLElement | null | undefined): HTMLElement | null | undefined;
+/** A portal must have its canvas on its first commit, before first-show readiness binds. */
+export declare function ToolbarMaterialPortal({ children }: {
+    children: ReactNode;
+}): import("react").FunctionComponentElement<import("react").ProviderProps<boolean>>;

package/dist/glass/toolbarMaterialContext.js

@@ -0,0 +1,66 @@
+import { createContext, createElement } from 'react';
+/** Navigation glass items own material independently of entry content opacity. */
+export const ToolbarMaterialContext = createContext(false);
+/** A child describes the slot's material without registering a second renderer region. */
+export const toolbarMaterials = new WeakMap();
+/** Each run of top-level glass items gets a persistent placement/index owner. */
+export function toolbarMaterialOwner(content) {
+    const slot = content?.closest('[data-satin-navigation-toolbar-slot]');
+    if (!slot || !content)
+        return;
+    const runs = toolbarMaterialRuns(slot);
+    const index = runs.findIndex(run => run.some(item => item === content || item.contains(content)));
+    if (index < 0)
+        return;
+    return slot
+        .closest('[data-satin-navigation-chrome]')
+        ?.querySelector(`[data-satin-toolbar-glass="${slot.dataset.satinNavigationToolbarSlot}"][data-satin-toolbar-glass-item="${index}"]`);
+}
+export function toolbarMaterialItems(slot) {
+    return [...(slot?.querySelectorAll('[data-satin-glass-slot-content]') ?? [])].filter(item => !item.parentElement?.closest('[data-satin-glass-slot-content]'));
+}
+/** Items of consecutive `ToolbarItem`s (one each, with no spacer between) share one glass capsule,
+ * as iOS 26+ merges adjacent bar items of a placement. The principal placement never merges. */
+export function toolbarMaterialRuns(slot) {
+    const runs = [];
+    let previous = null;
+    for (const item of toolbarMaterialItems(slot)) {
+        const wrapper = item.closest('[data-satin-toolbar-item="item"]');
+        const joins = slot?.dataset.satinNavigationToolbarSlot !== 'principal' &&
+            wrapper !== null &&
+            previous !== null &&
+            previous.nextElementSibling === wrapper &&
+            toolbarMaterialItems(wrapper).length === 1;
+        if (joins)
+            runs.at(-1).push(item);
+        else
+            runs.push([item]);
+        previous = wrapper && toolbarMaterialItems(wrapper).length === 1 ? wrapper : null;
+    }
+    return runs;
+}
+/** SearchDrawer hides the bar items of a screen presenting search; they own no glass. */
+export function toolbarSearchHidden(element) {
+    return Boolean(element.closest('[data-satin-entry-toolbar][data-satin-search-presented]'));
+}
+const materialContents = new WeakMap();
+export function bindToolbarMaterialContent(material, content) {
+    materialContents.set(material, content);
+}
+export function toolbarMaterialContent(material) {
+    return materialContents.get(material) ?? material;
+}
+/** Every content item carried by the same glass capsule as this trigger. */
+export function toolbarMenuContents(trigger) {
+    const slot = trigger?.closest('[data-satin-navigation-toolbar-slot]');
+    return (toolbarMaterialRuns(slot ?? undefined).find(run => run.some(item => item === trigger || (trigger && item.contains(trigger)))) ?? (trigger ? [trigger] : []));
+}
+/* Keep Menu trigger geometry local to its presentation context. */
+export function toolbarMenuTrigger(trigger) {
+    const slot = trigger?.closest('[data-satin-navigation-toolbar-slot]');
+    return (toolbarMaterialItems(slot ?? undefined).find(item => item === trigger || (trigger && item.contains(trigger))) ?? trigger);
+}
+/** A portal must have its canvas on its first commit, before first-show readiness binds. */
+export function ToolbarMaterialPortal({ children }) {
+    return createElement(ToolbarMaterialContext, { value: false }, children);
+}

package/dist/glass/topLayer.d.ts

@@ -0,0 +1,5 @@
+/** An open dialog in the top layer (showModal): painted above the scene, not in its DOM plane.
+ * A non-modal dialog (show()) paints in flow, as part of the plane it sits in. */
+export declare const topLayerDialog: (dialog: Element) => boolean;
+/** The modal dialog whose top-layer plane paints `element` (null: the page's own planes). */
+export declare function topLayerDialogOf(element: Element): HTMLDialogElement | null;

package/dist/glass/topLayer.js

@@ -0,0 +1,10 @@
+/** An open dialog in the top layer (showModal): painted above the scene, not in its DOM plane.
+ * A non-modal dialog (show()) paints in flow, as part of the plane it sits in. */
+export const topLayerDialog = (dialog) => dialog.open && dialog.matches(':modal');
+/** The modal dialog whose top-layer plane paints `element` (null: the page's own planes). */
+export function topLayerDialogOf(element) {
+    for (let dialog = element.closest('dialog'); dialog; dialog = dialog.parentElement?.closest('dialog') ?? null)
+        if (topLayerDialog(dialog))
+            return dialog;
+    return null;
+}