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

package/dist/glass/lens/tabSearchMember.d.ts

@@ -0,0 +1,38 @@
+import type { CapsuleShape } from '../renderSpecs.js';
+/**
+ * The trailing Search member of a minimizing tab bar (`Tab(role: .search)` on iPhone).
+ *
+ * Native reference: stock SwiftUI on iOS 27.0, iPhone 17 Pro Max (search-tab-split, Simulator
+ * tracks at 60 Hz) and the owner's Apple Music recording on a physical iPhone. On collapse the
+ * bar's trailing end separates into its own capsule within one or two frames: at the split it
+ * spans x = 339–413 of the 21–419 bar, full height. It then narrows from its leading edge into
+ * the 48 pt circle at x = 364–412 while the rest of the bar retracts into the leading shortcut.
+ * Expansion runs the other way: the circle widens back towards the bar and the growing bar
+ * merges with it. One glass field draws both members, so the parting and the merge are the
+ * field's smooth union, not a crossfade.
+ */
+/** Width of the trailing piece that separates from the bar (native: 419 − 339 pt). */
+export declare const SEARCH_SPLIT_WIDTH = 80;
+/** Diameter of the minimized Search circle. */
+export declare const SEARCH_CIRCLE_SIZE = 48;
+export declare const SEARCH_SPLIT_DELAY_MS = 12;
+/**
+ * How far the Search member has gone from the bar's trailing end (0) to the circle (1),
+ * `milliseconds` after its motion starts, beginning at the presented value `from`.
+ */
+export declare function searchMemberProgress(from: number, to: number, milliseconds: number): number;
+export type SearchMemberGeometry = {
+    /** Width and height of the tab bar's own frame (the expanded bar). */
+    dockWidth: number;
+    dockHeight: number;
+    /** Compact members' inset from the bar's edges; negative for a centred intrinsic platter. */
+    inset: number;
+};
+/**
+ * The Search member in the tab bar's frame. `progress` is the member's own spring; the height
+ * and trailing inset follow the bar's height channel so the two members part at the same height
+ * and keep concentric trailing caps.
+ */
+export declare function searchMemberShape(progress: number, heightProgress: number, { dockWidth, dockHeight, inset }: SearchMemberGeometry): CapsuleShape;
+/** Centre of the minimized Search circle in the tab bar's frame. */
+export declare function searchCircleCentre({ dockWidth, inset }: SearchMemberGeometry): number;

package/dist/glass/lens/tabSearchMember.js

@@ -0,0 +1,74 @@
+/**
+ * The trailing Search member of a minimizing tab bar (`Tab(role: .search)` on iPhone).
+ *
+ * Native reference: stock SwiftUI on iOS 27.0, iPhone 17 Pro Max (search-tab-split, Simulator
+ * tracks at 60 Hz) and the owner's Apple Music recording on a physical iPhone. On collapse the
+ * bar's trailing end separates into its own capsule within one or two frames: at the split it
+ * spans x = 339–413 of the 21–419 bar, full height. It then narrows from its leading edge into
+ * the 48 pt circle at x = 364–412 while the rest of the bar retracts into the leading shortcut.
+ * Expansion runs the other way: the circle widens back towards the bar and the growing bar
+ * merges with it. One glass field draws both members, so the parting and the merge are the
+ * field's smooth union, not a crossfade.
+ */
+/** Width of the trailing piece that separates from the bar (native: 419 − 339 pt). */
+export const SEARCH_SPLIT_WIDTH = 80;
+/** Diameter of the minimized Search circle. */
+export const SEARCH_CIRCLE_SIZE = 48;
+/**
+ * The Search member's leading edge is a damped spring (mass 1). Fitted to the leading edge of
+ * the separated capsule in three dark collapse recordings (b, a, Library selected):
+ * stiffness 960, damping 52 (damping ratio 0.84), starting 12 ms after the bar's first painted
+ * change; RMS 0.05 of the 25 pt travel. Expansion reuses the same spring from the bar's onset.
+ */
+const SEARCH_STIFFNESS = 960;
+const SEARCH_DAMPING = 52;
+export const SEARCH_SPLIT_DELAY_MS = 12;
+/** After this the spring is within 0.1% of its target; return the target exactly. */
+const SEARCH_SETTLE_MS = 400;
+/** Normalized step response of the fitted spring: 0 at the start, 1 at rest. */
+function springStep(milliseconds) {
+    if (milliseconds <= 0)
+        return 0;
+    if (milliseconds >= SEARCH_SETTLE_MS)
+        return 1;
+    const seconds = milliseconds / 1000;
+    const natural = Math.sqrt(SEARCH_STIFFNESS);
+    const ratio = SEARCH_DAMPING / (2 * natural);
+    const damped = natural * Math.sqrt(1 - ratio * ratio);
+    const decay = Math.exp(-ratio * natural * seconds);
+    return (1 -
+        decay * (Math.cos(damped * seconds) + ((ratio * natural) / damped) * Math.sin(damped * seconds)));
+}
+/**
+ * How far the Search member has gone from the bar's trailing end (0) to the circle (1),
+ * `milliseconds` after its motion starts, beginning at the presented value `from`.
+ */
+export function searchMemberProgress(from, to, milliseconds) {
+    return from + (to - from) * springStep(milliseconds);
+}
+/**
+ * The Search member in the tab bar's frame. `progress` is the member's own spring; the height
+ * and trailing inset follow the bar's height channel so the two members part at the same height
+ * and keep concentric trailing caps.
+ */
+export function searchMemberShape(progress, heightProgress, { dockWidth, dockHeight, inset }) {
+    // The bar overshoots past its resting size on expansion (heightProgress below 0). It then
+    // contains the Search member, which stays within the resting bar instead of bulging out.
+    const settled = Math.max(0, heightProgress);
+    const right = dockWidth - inset * settled;
+    const splitLeft = dockWidth - SEARCH_SPLIT_WIDTH;
+    const circleLeft = dockWidth - inset - SEARCH_CIRCLE_SIZE;
+    const left = splitLeft + (circleLeft - splitLeft) * progress;
+    const height = dockHeight + (SEARCH_CIRCLE_SIZE - dockHeight) * settled;
+    return {
+        centerX: (left + right) / 2,
+        centerY: dockHeight / 2,
+        halfWidth: (right - left) / 2,
+        halfHeight: height / 2,
+        radius: height / 2,
+    };
+}
+/** Centre of the minimized Search circle in the tab bar's frame. */
+export function searchCircleCentre({ dockWidth, inset }) {
+    return dockWidth - inset - SEARCH_CIRCLE_SIZE / 2;
+}

package/dist/glass/lens/tabSelectionMaterial.d.ts

@@ -0,0 +1,20 @@
+import type { Appearance } from './theme.js';
+export { tabGlyphStyle } from './tabGlyphColours.js';
+export declare const TAB_BAR_LOCAL_CENTRES: readonly number[];
+export declare const TAB_BAR_BLUR_SIGMA: Readonly<{
+    light: number;
+    dark: number;
+}>;
+export declare const TAB_SELECTION_HEIGHT = 52;
+export declare const TAB_SELECTION_WIDTH = 96;
+export declare function stableTabSelection(appearance: Appearance): {
+    readonly blurSigmaCssPx: number;
+    readonly materialMix: 1;
+};
+export declare function tabSelectionCapsule(index: number, centres?: readonly number[], width?: number, height?: number, centerY?: number): {
+    centerX: number;
+    centerY: number;
+    halfHeight: number;
+    halfWidth: number;
+    radius: number;
+};

package/dist/glass/lens/tabSelectionMaterial.js

@@ -0,0 +1,23 @@
+import { TAB_PILL_MATERIAL, TAB_BAR_MATERIAL } from './tabMaterialModel.js';
+export { tabGlyphStyle } from './tabGlyphColours.js';
+export const TAB_BAR_LOCAL_CENTRES = Object.freeze([53, 138, 223, 308]);
+export const TAB_BAR_BLUR_SIGMA = Object.freeze({
+    light: TAB_BAR_MATERIAL.light.sigma,
+    dark: TAB_BAR_MATERIAL.dark.sigma,
+});
+export const TAB_SELECTION_HEIGHT = 52;
+export const TAB_SELECTION_WIDTH = 96;
+// Effective dense-kernel sigma is explicit in the measured material model.
+export function stableTabSelection(appearance) {
+    return { blurSigmaCssPx: TAB_PILL_MATERIAL[appearance].sigma, materialMix: 1 };
+}
+export function tabSelectionCapsule(index, centres = TAB_BAR_LOCAL_CENTRES, width = TAB_SELECTION_WIDTH, height = TAB_SELECTION_HEIGHT, centerY = 31) {
+    const selected = Math.max(0, Math.min(centres.length - 1, Math.round(index)));
+    return {
+        centerX: centres[selected],
+        centerY,
+        halfHeight: height / 2,
+        halfWidth: width / 2,
+        radius: height / 2,
+    };
+}

package/dist/glass/lens/tabSelectionMeasurements.test-fixture.d.ts

@@ -0,0 +1,9 @@
+import type { Appearance } from './theme.js';
+export type TabSelectionMeasurement = Readonly<{
+    appearance: Appearance;
+    backdrop: readonly [number, number, number];
+    background: string;
+    bar: readonly [number, number, number];
+    pill: readonly [number, number, number];
+}>;
+export declare const TAB_SELECTION_MEASUREMENTS: readonly TabSelectionMeasurement[];

package/dist/glass/lens/tabSelectionMeasurements.test-fixture.js

@@ -0,0 +1,74 @@
+// Historical native flat targets, retained only for test/evidence comparison.
+// Runtime material coefficients never read this fixture.
+export const TAB_SELECTION_MEASUREMENTS = Object.freeze([
+    {
+        appearance: 'light',
+        backdrop: [0, 0, 0],
+        background: 'tint-black',
+        bar: [18, 18, 18],
+        pill: [52, 52, 52],
+    },
+    {
+        appearance: 'light',
+        backdrop: [32, 32, 32],
+        background: 'tint-dark-grey',
+        bar: [28, 28, 28],
+        pill: [61, 61, 61],
+    },
+    {
+        appearance: 'light',
+        backdrop: [10, 132, 255],
+        background: 'tint-saturated-blue',
+        bar: [149, 207, 255],
+        pill: [114, 184, 241],
+    },
+    {
+        appearance: 'light',
+        backdrop: [216, 216, 216],
+        background: 'tint-light-grey',
+        bar: [244, 244, 244],
+        pill: [225, 225, 225],
+    },
+    {
+        appearance: 'light',
+        backdrop: [255, 255, 255],
+        background: 'tint-white',
+        bar: [253, 253, 253],
+        pill: [235, 235, 235],
+    },
+    {
+        appearance: 'dark',
+        backdrop: [0, 0, 0],
+        background: 'tint-black',
+        bar: [19, 19, 19],
+        pill: [53, 53, 53],
+    },
+    {
+        appearance: 'dark',
+        backdrop: [32, 32, 32],
+        background: 'tint-dark-grey',
+        bar: [28, 28, 28],
+        pill: [61, 61, 61],
+    },
+    {
+        appearance: 'dark',
+        backdrop: [10, 132, 255],
+        background: 'tint-saturated-blue',
+        bar: [23, 93, 163],
+        pill: [47, 125, 203],
+    },
+    {
+        appearance: 'dark',
+        backdrop: [216, 216, 216],
+        background: 'tint-light-grey',
+        bar: [107, 107, 107],
+        pill: [137, 137, 137],
+    },
+    {
+        appearance: 'dark',
+        backdrop: [255, 255, 255],
+        background: 'tint-white',
+        bar: [253, 253, 253],
+        pill: [235, 235, 235],
+    },
+]);

package/dist/glass/lens/tabSettingsSymbol.d.ts

@@ -0,0 +1 @@
+export declare const TAB_SETTINGS_SYMBOL: string;

package/dist/glass/lens/tabSettingsSymbol.js

@@ -0,0 +1,2 @@
+import { coreSymbolSvg } from '../../symbols/svg.js';
+export const TAB_SETTINGS_SYMBOL = coreSymbolSvg('gearshape.fill');

package/dist/glass/lens/tabShapeResponse.d.ts

@@ -0,0 +1,7 @@
+export declare class TabShapeResponse {
+    private speed;
+    private brake;
+    private strain;
+    reset(): void;
+    sample(velocity: number, dt: number): number;
+}

package/dist/glass/lens/tabShapeResponse.js

@@ -0,0 +1,30 @@
+// reference fit candidate from the recorded fast/slow arrival controls. Native travel
+// flattens the lens; braking briefly contracts its width and raises its height.
+// These are coarse visual-fit parameters, not a material UIKit physical model.
+const clamp01 = (x) => Math.max(0, Math.min(1, x));
+export class TabShapeResponse {
+    speed = 0;
+    brake = 0;
+    strain = 0;
+    reset() {
+        this.speed = 0;
+        this.brake = 0;
+        this.strain = 0;
+    }
+    sample(velocity, dt) {
+        if (dt <= 0)
+            return this.strain;
+        // Long suspension gaps settle instead of injecting a large simulated step.
+        if (dt > 0.1) {
+            this.reset();
+            return 0;
+        }
+        const excitation = clamp01((Math.abs(velocity) - 300) / 1000);
+        const previousSpeed = this.speed;
+        this.speed += (excitation - this.speed) * (1 - Math.exp(-dt / 0.035));
+        this.brake = Math.min(1, this.brake * Math.exp(-dt / 0.16) + Math.max(0, previousSpeed - this.speed) * 2);
+        const target = 15 * this.speed - 12 * this.brake;
+        this.strain += (target - this.strain) * (1 - Math.exp(-dt / 0.035));
+        return this.strain;
+    }
+}

package/dist/glass/lens/theme.d.ts

@@ -0,0 +1,18 @@
+import type { IconTone } from './data.js';
+export type Appearance = 'dark' | 'light';
+export type SettingsPalette = Readonly<{
+    background: number;
+    cell: number;
+    label: number;
+    secondaryLabel: number;
+    separator: number;
+    pressed: number;
+    searchFill: number;
+    searchPlaceholder: number;
+    chrome: number;
+    chromeStroke: number;
+    indicator: number;
+    tabSelection: number;
+}>;
+export declare const PALETTES: Readonly<Record<Appearance, SettingsPalette>>;
+export declare const ICON_GRADIENTS: Readonly<Record<IconTone, readonly [number, number]>>;

package/dist/glass/lens/theme.js

@@ -0,0 +1,40 @@
+export const PALETTES = Object.freeze({
+    light: Object.freeze({
+        background: 0xf2f2f7,
+        cell: 0xffffff,
+        label: 0x000000,
+        secondaryLabel: 0x8e8e93,
+        separator: 0xe8e8e8,
+        pressed: 0xd1d1d6,
+        searchFill: 0xe3e3e8,
+        searchPlaceholder: 0x737378,
+        chrome: 0xf7f7fa,
+        chromeStroke: 0xffffff,
+        indicator: 0x8e8e93,
+        tabSelection: 0x0a84ff,
+    }),
+    dark: Object.freeze({
+        background: 0x000000,
+        cell: 0x1c1c1e,
+        label: 0xffffff,
+        secondaryLabel: 0x98989d,
+        separator: 0x38383a,
+        pressed: 0x3a3a3c,
+        searchFill: 0x1c1c1e,
+        searchPlaceholder: 0x98989d,
+        chrome: 0x232326,
+        chromeStroke: 0x4a4a4e,
+        indicator: 0x98989d,
+        tabSelection: 0x0a84ff,
+    }),
+});
+export const ICON_GRADIENTS = Object.freeze({
+    black: [0x3b3b3d, 0x050506],
+    blue: [0x40b6ff, 0x0787ed],
+    gray: [0xb9bbc0, 0x898b90],
+    green: [0x5bd662, 0x24a938],
+    orange: [0xffb13b, 0xf27912],
+    pink: [0xff648c, 0xf13b71],
+    purple: [0x9f7bff, 0x6753f1],
+    red: [0xff6262, 0xe23434],
+});

package/dist/glass/lens/trace.d.ts

@@ -0,0 +1,2 @@
+export declare function trace(step: string): void;
+export declare function previousTrace(): string;

package/dist/glass/lens/trace.js

@@ -0,0 +1,27 @@
+/** Persistent step trace: survives a main-thread hang so the next launch can show where it stopped. */
+const KEY = 'satinGeometry-trace';
+const started = performance.now();
+let previous = [];
+try {
+    previous = JSON.parse(localStorage.getItem(KEY) ?? '[]');
+    localStorage.setItem(KEY, '[]');
+}
+catch {
+    previous = [];
+}
+let current = [];
+export function trace(step) {
+    current.push(`${((performance.now() - started) / 1000).toFixed(1)}:${step}`);
+    if (current.length > 14)
+        current = current.slice(-14);
+    try {
+        localStorage.setItem(KEY, JSON.stringify(current));
+    }
+    catch {
+        // ignore
+    }
+}
+export function previousTrace() {
+    // Latest step first: the hang is at the tail of the previous run.
+    return previous.length ? [...previous].reverse().join(' ← ') : '(none)';
+}

package/dist/glass/liquidContext.d.ts

@@ -0,0 +1,32 @@
+import type { GlassRegionRegistry } from './regionRegistry.js';
+import type { TabBarProps, TabItemFrame } from './TabBar.js';
+export type RegisteredTabBar = TabBarProps & Readonly<{
+    tint?: string;
+    insetHost?: HTMLElement;
+    intrinsicWidth?: boolean;
+    /** 'top': the regular-width iPad bar, laid out by `itemFrames` inside `insetHost`. */
+    placement?: 'bottom' | 'top';
+    itemFrames?: readonly TabItemFrame[];
+}>;
+export type MaterialEffectRegistration = Readonly<{
+    /** The one glass renderer. */
+    backend?: 'webgpu' | 'fallback';
+    regions?: GlassRegionRegistry;
+    ready: boolean;
+    preparingSources?: boolean;
+    preparedScreenKey?: string;
+    preparedAt?: number;
+    preparedSources?: ReadonlyMap<string, number>;
+    registerTabs: (id: string, tabs: RegisteredTabBar | undefined) => void;
+}>;
+export declare const MaterialEffectContext: import("react").Context<Readonly<{
+    /** The one glass renderer. */
+    backend?: 'webgpu' | 'fallback';
+    regions?: GlassRegionRegistry;
+    ready: boolean;
+    preparingSources?: boolean;
+    preparedScreenKey?: string;
+    preparedAt?: number;
+    preparedSources?: ReadonlyMap<string, number>;
+    registerTabs: (id: string, tabs: RegisteredTabBar | undefined) => void;
+}> | null>;

package/dist/glass/liquidContext.js

@@ -0,0 +1,2 @@
+import { createContext } from 'react';
+export const MaterialEffectContext = createContext(null);

package/dist/glass/menuPanelPlacement.d.ts

@@ -0,0 +1,51 @@
+type Rect = Readonly<{
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}>;
+/** How far a trigger's centre may sit from the middle of the screen and still get a centred
+ * panel (points). iPhone 17 Pro Max Simulator, iOS 27.0, a 129 pt capsule trigger at 14
+ * positions: centred at 4.5, 15.5, 19.5 and 20.5 pt from the middle, edge-aligned at 25.5, 29.5,
+ * 30.5 and beyond. Other screen widths were not measured. */
+export declare const MENU_CENTER_BAND = 22;
+/** Lifted non-row content (iPhone 17 Pro Max Simulator, iOS 27.0, stock `.contextMenu` on a grid
+ * tile with and without `preview:`; native menu measurements native-iphone stills): the menu sits 20 pt from
+ * the lifted box (tile 19.8, preview 20.0) and takes the box's leading or trailing edge on its
+ * side of the screen, with no centred band (tall bubbles 19.5 and 30 pt off centre align
+ * leading; content exactly centred is unmeasured and aligns leading). iPad does the same for
+ * lifted bubbles (native iPad: tall leading, short trailing, 18-19 pt at the 1 pt contour
+ * resolution), and puts a custom preview's menu beside it, top-aligned, 20-21 pt away. */
+export declare const CONTEXT_CONTENT_GAP = 20;
+/** How much lifted non-row content grows. A 192 x 230 pt grid tile settles at 1.115 and a
+ * 159 x 38 pt bubble at 1.15 (same stills); a full-width row keeps its own measured lift. Both
+ * points fit growing the longest side by 26 pt, at most 1.15. Two sizes were measured. */
+export declare function contextContentScale(width: number, height: number): number;
+/** Where lifted content (or its custom preview, `size`) settles: centred on its resting source,
+ * kept inside the screen (native keeps 20 pt), and moved up or down only when its menu would fit
+ * neither below nor above it. Native tile and preview stills: centred on the whole tile
+ * (artwork and labels), clamped to the 20 pt side margin. Tall bubbles (native menu measurements stills):
+ * the content moves the shorter way that frees room for its menu (3 positions), and content too
+ * tall to share the screen with its menu sits at the bottom with the menu over its top. */
+export declare function contextLiftBox(rest: Rect, size: Readonly<{
+    width: number;
+    height: number;
+}>, menuHeight: number, available: Rect): Rect;
+/** Stock Menu keeps its first row over the trigger. The September 27 iPad
+ * reference puts its center 3pt below the text trigger (3.5pt for ellipsis).
+ * Center the panel horizontally, then move it inside the usable viewport.
+ *
+ * iPhone (October 1 reference, capsule, full-width, toolbar-group and circle triggers): a trigger
+ * near the middle of the screen gets a panel centred on it; any other trigger gets a panel whose
+ * edge is the trigger glass's own edge on its side of the screen (a toolbar group's edge, whichever
+ * member opened the menu). The panel's top is the trigger's top; when it does not fit below, its
+ * bottom is the trigger's bottom and it opens upward. This is an idiom distinction, not a
+ * window-width breakpoint. */
+export declare function menuPanelPlacement(trigger: Rect, panel: Rect, firstRow: Rect | undefined, available: Rect, phone?: boolean, source?: 'trigger' | 'context' | 'context-content' | 'context-preview'): {
+    left: number;
+    top: number;
+};
+/** An iPhone menu hangs from its trigger's top, and opens upward from its trigger's bottom when
+ * it would not fit below (and does fit above). */
+export declare function menuOpensUpward(trigger: Rect, panel: Rect, available: Rect): boolean;
+export {};

package/dist/glass/menuPanelPlacement.js

@@ -0,0 +1,128 @@
+/** How far a trigger's centre may sit from the middle of the screen and still get a centred
+ * panel (points). iPhone 17 Pro Max Simulator, iOS 27.0, a 129 pt capsule trigger at 14
+ * positions: centred at 4.5, 15.5, 19.5 and 20.5 pt from the middle, edge-aligned at 25.5, 29.5,
+ * 30.5 and beyond. Other screen widths were not measured. */
+export const MENU_CENTER_BAND = 22;
+/** Lifted non-row content (iPhone 17 Pro Max Simulator, iOS 27.0, stock `.contextMenu` on a grid
+ * tile with and without `preview:`; native menu measurements native-iphone stills): the menu sits 20 pt from
+ * the lifted box (tile 19.8, preview 20.0) and takes the box's leading or trailing edge on its
+ * side of the screen, with no centred band (tall bubbles 19.5 and 30 pt off centre align
+ * leading; content exactly centred is unmeasured and aligns leading). iPad does the same for
+ * lifted bubbles (native iPad: tall leading, short trailing, 18-19 pt at the 1 pt contour
+ * resolution), and puts a custom preview's menu beside it, top-aligned, 20-21 pt away. */
+export const CONTEXT_CONTENT_GAP = 20;
+/** How much lifted non-row content grows. A 192 x 230 pt grid tile settles at 1.115 and a
+ * 159 x 38 pt bubble at 1.15 (same stills); a full-width row keeps its own measured lift. Both
+ * points fit growing the longest side by 26 pt, at most 1.15. Two sizes were measured. */
+export function contextContentScale(width, height) {
+    const longest = Math.max(width, height, 1);
+    return Math.min(1.15, (longest + 26) / longest);
+}
+/** Where lifted content (or its custom preview, `size`) settles: centred on its resting source,
+ * kept inside the screen (native keeps 20 pt), and moved up or down only when its menu would fit
+ * neither below nor above it. Native tile and preview stills: centred on the whole tile
+ * (artwork and labels), clamped to the 20 pt side margin. Tall bubbles (native menu measurements stills):
+ * the content moves the shorter way that frees room for its menu (3 positions), and content too
+ * tall to share the screen with its menu sits at the bottom with the menu over its top. */
+export function contextLiftBox(rest, size, menuHeight, available) {
+    const width = Math.min(size.width, available.width);
+    const height = Math.min(size.height, available.height);
+    const clamp = (value, start, extent, length) => Math.max(start, Math.min(value, start + Math.max(0, extent - length)));
+    const x = clamp(rest.x + (rest.width - width) / 2, available.x, available.width, width);
+    let y = clamp(rest.y + (rest.height - height) / 2, available.y, available.height, height);
+    const bottom = available.y + available.height;
+    const fitsBelow = y + height + CONTEXT_CONTENT_GAP + menuHeight <= bottom;
+    const fitsAbove = y - CONTEXT_CONTENT_GAP - menuHeight >= available.y;
+    if (!fitsBelow && !fitsAbove) {
+        const up = bottom - menuHeight - CONTEXT_CONTENT_GAP - height;
+        const down = available.y + menuHeight + CONTEXT_CONTENT_GAP;
+        y = up < available.y ? bottom - height : Math.abs(up - y) <= Math.abs(down - y) ? up : down;
+    }
+    return { x, y, width, height };
+}
+/** Stock Menu keeps its first row over the trigger. The September 27 iPad
+ * reference puts its center 3pt below the text trigger (3.5pt for ellipsis).
+ * Center the panel horizontally, then move it inside the usable viewport.
+ *
+ * iPhone (October 1 reference, capsule, full-width, toolbar-group and circle triggers): a trigger
+ * near the middle of the screen gets a panel centred on it; any other trigger gets a panel whose
+ * edge is the trigger glass's own edge on its side of the screen (a toolbar group's edge, whichever
+ * member opened the menu). The panel's top is the trigger's top; when it does not fit below, its
+ * bottom is the trigger's bottom and it opens upward. This is an idiom distinction, not a
+ * window-width breakpoint. */
+export function menuPanelPlacement(trigger, panel, firstRow, available, phone = false, source = 'trigger') {
+    const clamp = (value, start, extent, size) => Math.max(start, Math.min(value, start + Math.max(0, extent - size)));
+    const triggerCenter = trigger.x + trigger.width / 2;
+    if (source !== 'trigger') {
+        // Native iPad paired held state: 17pt between a row and its menu edge. A phone row's menu
+        // sits 12 pt below the row; lifted content (or a custom preview) keeps 20 pt from its lifted
+        // box, and the menu takes the box's edge on its side of the screen (CONTEXT_CONTENT_GAP).
+        const content = source !== 'context';
+        if (!phone && source === 'context-preview') {
+            // iPad: beside the preview on the roomier side, when it fits there (a right-column tile's
+            // preview gets its menu on the left).
+            const right = available.x + available.width;
+            const before = trigger.x - CONTEXT_CONTENT_GAP - panel.width;
+            const after = trigger.x + trigger.width + CONTEXT_CONTENT_GAP;
+            const roomierBefore = trigger.x - available.x > right - (trigger.x + trigger.width);
+            const fitsBefore = before >= available.x;
+            const fitsAfter = after + panel.width <= right;
+            if (fitsBefore || fitsAfter)
+                return {
+                    left: (roomierBefore && fitsBefore) || !fitsAfter ? before : after,
+                    top: clamp(trigger.y, available.y, available.height, panel.height),
+                };
+        }
+        const gap = content ? CONTEXT_CONTENT_GAP : phone ? 12 : 17;
+        const below = trigger.y + trigger.height + gap;
+        const above = trigger.y - panel.height - gap;
+        const offset = triggerCenter - (available.x + available.width / 2);
+        // Lifted content keeps an edge even 19.5 pt off centre (r2 698 pt bubble: leading).
+        const left = !content
+            ? triggerCenter - panel.width / 2
+            : offset <= 0
+                ? trigger.x
+                : trigger.x + trigger.width - panel.width;
+        const bottom = available.y + available.height;
+        // Lifted content's menu takes the roomier side when it fits there (native: a second-row
+        // tile and a lower bubble open upward, a first-row tile and a preview downward).
+        const roomier = content && trigger.y - available.y > bottom - (trigger.y + trigger.height);
+        // Content too tall to leave room on either side keeps the menu over its top.
+        const over = content && above < available.y && below + panel.height > bottom;
+        return {
+            left: clamp(left, available.x, available.width, panel.width),
+            top: clamp(over
+                ? available.y
+                : above >= available.y && (roomier || below + panel.height > bottom)
+                    ? above
+                    : below, available.y, available.height, panel.height),
+        };
+    }
+    if (phone) {
+        const offset = triggerCenter - (available.x + available.width / 2);
+        const left = Math.abs(offset) <= MENU_CENTER_BAND
+            ? triggerCenter - panel.width / 2
+            : offset < 0
+                ? trigger.x
+                : trigger.x + trigger.width - panel.width;
+        const top = menuOpensUpward(trigger, panel, available)
+            ? trigger.y + trigger.height - panel.height
+            : trigger.y;
+        return {
+            left: clamp(left, available.x, available.width, panel.width),
+            top: clamp(top, available.y, available.height, panel.height),
+        };
+    }
+    const rowCenter = firstRow ? firstRow.y + firstRow.height / 2 - panel.y : panel.height / 2;
+    return {
+        left: clamp(triggerCenter - panel.width / 2, available.x, available.width, panel.width),
+        top: clamp(trigger.y + trigger.height / 2 + 3 - rowCenter, available.y, available.height, panel.height),
+    };
+}
+/** An iPhone menu hangs from its trigger's top, and opens upward from its trigger's bottom when
+ * it would not fit below (and does fit above). */
+export function menuOpensUpward(trigger, panel, available) {
+    const fitsBelow = trigger.y + panel.height <= available.y + available.height;
+    const fitsAbove = trigger.y + trigger.height - panel.height >= available.y;
+    return !fitsBelow && fitsAbove;
+}

package/dist/glass/menuPresenter.d.ts

@@ -0,0 +1,34 @@
+import type { MenuEntry } from './menuTypes.js';
+import { type MenuContactSample } from '../menu/menuContact.js';
+import { type ReactNode } from 'react';
+import { type PressableProps } from '../press/Pressable.js';
+export type MenuTriggerProps = Pick<PressableProps, 'onPress' | 'disabled' | 'aria-expanded' | 'aria-haspopup' | 'aria-controls'>;
+export type MenuProps = Readonly<{
+    label: ReactNode;
+    disabled?: boolean;
+    actions: readonly MenuEntry[];
+    /** @unstable Custom menu triggers may change. Forward every supplied trigger prop. */
+    trigger?: (props: MenuTriggerProps) => ReactNode;
+}>;
+/** Shared presentation and contact ownership for every menu source. */
+export type MenuSource = {
+    kind: 'trigger';
+    element: HTMLElement;
+    contact?: MenuContactSample;
+} | {
+    kind: 'context';
+    element: HTMLElement;
+    contact?: MenuContactSample;
+};
+export declare function useMenuPresenter({ label, actions, disabled, preview, }: Omit<MenuProps, 'trigger'> & {
+    preview?: ReactNode;
+}): {
+    id: string;
+    open: boolean;
+    presentation: import("react").ReactPortal | null;
+    close: () => void;
+    ownsContact: () => boolean;
+    prepare(next: MenuSource, pointerId?: number, contactEpoch?: number): void;
+    show: (next?: MenuSource) => void;
+    cancelPreparation(pointerId?: number): void;
+};