@astratra/native-ui 0.1.0

package/src/index.d.ts

@@ -0,0 +1,229 @@
+/**
+ * @astratra/native-ui — the mobile interface kit.
+ *
+ * The React Native types are NOT imported: react-native is a peer, and this
+ * repository does not install it. Styles and animated values are typed
+ * loosely here (`NativeStyle`, `SharedNumber`) — the app's own types flow
+ * through untouched.
+ */
+import type { ComponentType, ReactElement, ReactNode } from 'react';
+import type { ColorScheme, GlassMode } from './logic';
+
+export * from './logic';
+
+/** A React Native style, style array or registered style. */
+export type NativeStyle = unknown;
+/** A Reanimated shared value holding a number (0..1 for `collapse`). */
+export interface SharedNumber {
+  value: number;
+}
+/** The scroll event React Native hands to `onScroll`. */
+export interface ScrollEventLike {
+  nativeEvent: { contentOffset: { y: number } };
+}
+
+/** The glass this device renders, decided once for the app. */
+export function getGlassMode(): GlassMode;
+
+/* ──────────────────────────────── Glass ─────────────────────────────── */
+
+export interface GlassSurfaceProps {
+  children?: ReactNode;
+  style?: NativeStyle;
+  /** Declared as for Apple's glass; off iOS it is painted at Apple's real weight. */
+  tintColor?: string;
+  glassStyle?: 'regular' | 'clear';
+  /** A button (keeps its shadow, gets the frost) rather than a container. */
+  interactive?: boolean;
+  scheme?: ColorScheme;
+  testID?: string;
+}
+export function GlassSurface(props: GlassSurfaceProps): ReactElement;
+
+export interface GlassGroupProps {
+  children?: ReactNode;
+  spacing?: number;
+  style?: NativeStyle;
+  [prop: string]: unknown;
+}
+export function GlassGroup(props: GlassGroupProps): ReactElement;
+
+export interface GlassButtonProps {
+  children?: ReactNode;
+  onPress?: () => void;
+  onLongPress?: () => void;
+  accessibilityLabel?: string;
+  /** Diameter of a circle, height of a pill. */
+  size?: number;
+  pill?: boolean;
+  /** Solid colour of the main action: tinted glass, light content. */
+  tint?: string;
+  disabled?: boolean;
+  selected?: boolean;
+  scheme?: ColorScheme;
+  style?: NativeStyle;
+  testID?: string;
+}
+export function GlassButton(props: GlassButtonProps): ReactElement;
+
+/* ─────────────────────────────── Cards ──────────────────────────────── */
+
+export interface PaleCardProps {
+  children?: ReactNode;
+  /** Accent colour for the current scheme; absent = the neutral card. */
+  tint?: string | null;
+  /** Defaults to white / black. */
+  pageBackground?: string;
+  /** The theme's text colour, used by the neutral card. */
+  ink?: string;
+  scheme?: ColorScheme;
+  style?: NativeStyle;
+  [prop: string]: unknown;
+}
+export function PaleCard(props: PaleCardProps): ReactElement;
+export function TappableCard(props: Omit<PaleCardProps, 'tint'> & { tint?: string }): ReactElement;
+export function usePaleCardColors(input?: {
+  tint?: string | null;
+  pageBackground?: string;
+  ink?: string;
+  scheme?: ColorScheme;
+}): { fill: string; top: string; bottom: string };
+
+export function Chevron(props: {
+  direction?: 'left' | 'right' | 'up' | 'down';
+  color?: string;
+  size?: number;
+  strokeWidth?: number;
+}): ReactElement;
+
+/* ──────────────────────────── Floating bars ─────────────────────────── */
+
+export function useCollapsingBar(): { collapse: SharedNumber; onScroll: (event: ScrollEventLike) => void };
+/** The shared fold style (translate + scale toward the bottom). */
+export function useCollapseTransform(collapse?: SharedNumber): NativeStyle;
+
+export interface FloatingPaginationProps {
+  page: number;
+  totalPages: number;
+  canPrevious: boolean;
+  canNext: boolean;
+  onPrevious: () => void;
+  onNext: () => void;
+  previousLabel: string;
+  nextLabel: string;
+  collapse?: SharedNumber;
+  /** Distance from the bottom when a footer button already sits there. */
+  bottom?: number;
+  bottomInset?: number;
+  onHaptic?: () => void;
+  previousIcon?: ReactNode;
+  nextIcon?: ReactNode;
+  scheme?: ColorScheme;
+  testID?: string;
+}
+export function FloatingPagination(props: FloatingPaginationProps): ReactElement;
+
+export interface TabIconState {
+  color: string;
+  size: number;
+  strokeWidth: number;
+  active: boolean;
+}
+
+export interface TabBarTab {
+  key: string;
+  label: string;
+  badge?: number;
+  icon?: (state: TabIconState) => ReactNode;
+}
+
+export interface TabBarColors {
+  active: string;
+  idle: string;
+  pill: string;
+  badge: string;
+  badgeRing: string;
+}
+
+export interface TabBarProps<T extends TabBarTab = TabBarTab> {
+  tabs: readonly T[];
+  activeKey: string;
+  onSelect: (tab: T) => void;
+  /** Raised in the middle, never takes the pill. */
+  centerKey?: string;
+  renderCenter?: (input: { tab: T; size: number }) => ReactNode;
+  collapse?: SharedNumber;
+  bottomInset?: number;
+  onHaptic?: () => void;
+  /** Delay before `onSelect`, so the pill's slide is seen. */
+  openDelay?: number;
+  /** e.g. expo-router's useFocusEffect, when the bar is rendered inside each screen. */
+  useFocusEffect?: (effect: () => void | (() => void)) => void;
+  colors?: Partial<TabBarColors>;
+  scheme?: ColorScheme;
+  testID?: string;
+}
+export function TabBar<T extends TabBarTab>(props: TabBarProps<T>): ReactElement;
+
+/* ────────────────────────── Collapsible header ──────────────────────── */
+
+export interface CollapsibleHeaderApi {
+  scrollY: SharedNumber;
+  threshold: SharedNumber;
+  onScroll: (event: ScrollEventLike) => void;
+  onTitleLayout: (event: { nativeEvent: { layout: { y: number; height: number } } }) => void;
+  onListTitleLayout: (event: { nativeEvent: { layout: { y: number; height: number } } }) => void;
+  measureTitle: (node: unknown) => void;
+  originRef: { current: unknown };
+}
+export function useCollapsibleHeader(options?: { topInset?: number }): CollapsibleHeaderApi;
+
+export interface CollapsibleHeaderProps {
+  title: string;
+  scrollY: SharedNumber;
+  threshold: SharedNumber;
+  /** Fixed on the left: usually a back GlassButton. */
+  leading?: ReactNode;
+  /** Fixed on the right. */
+  actions?: ReactNode;
+  topInset?: number;
+  gutter?: number;
+  pageBackground?: string;
+  titleColor?: string;
+  /** e.g. @react-native-masked-view/masked-view, for the iOS blur's fade. */
+  MaskedView?: ComponentType<{ style?: NativeStyle; maskElement: ReactElement; children?: ReactNode }>;
+  scheme?: ColorScheme;
+  testID?: string;
+}
+export function CollapsibleHeader(props: CollapsibleHeaderProps): ReactElement;
+
+export interface CollapsibleScreenProps extends Omit<CollapsibleHeaderProps, 'scrollY' | 'threshold'> {
+  largeTitle?: ReactNode;
+  children?: ReactNode;
+  contentContainerStyle?: NativeStyle;
+  scrollProps?: { onScroll?: (event: ScrollEventLike) => void; [prop: string]: unknown };
+}
+export function CollapsibleScreen(props: CollapsibleScreenProps): ReactElement;
+
+/* ───────────────────────────── AI answers ───────────────────────────── */
+
+export interface MarkdownViewProps {
+  content: string;
+  /** The person's own message: shown as typed. */
+  plain?: boolean;
+  /** Style overrides by name (body, heading, tableCell, …), merged with the defaults. */
+  styles?: Record<string, NativeStyle>;
+  onLinkPress?: (href: string) => void;
+  /** Copies one code block; the button shows only with a copyIcon. */
+  onCopyCode?: (text: string) => void | Promise<void>;
+  copyLabel?: string;
+  copyIcon?: ReactNode;
+  copiedIcon?: ReactNode;
+  /** Defaults to PixelRatio.getFontScale(). */
+  fontScale?: number;
+  tableVeilColor?: string;
+  testID?: string;
+}
+export function MarkdownView(props: MarkdownViewProps): ReactElement | null;
+export function MarkdownTable(props: { header: string[]; rows: string[][] }): ReactElement;
+export const MARKDOWN_STYLES: Readonly<Record<string, NativeStyle>>;

package/src/index.js

@@ -0,0 +1,20 @@
+/**
+ * @astratra/native-ui — the mobile interface kit: Liquid Glass on iOS, honest
+ * surfaces on Android, bars that fold on scroll, AI answers rendered clean.
+ *
+ * This entry loads react-native and the Expo modules. The pure rules alone
+ * live at `@astratra/native-ui/logic`, importable from plain Node.
+ */
+module.exports = {
+  ...require('./logic'),
+  ...require('./components/GlassSurface'),
+  ...require('./components/GlassButton'),
+  ...require('./components/PaleCard'),
+  ...require('./components/Chevron'),
+  ...require('./components/useCollapsingBar'),
+  ...require('./components/FloatingPagination'),
+  ...require('./components/TabBar'),
+  ...require('./components/CollapsibleHeader'),
+  ...require('./components/MarkdownView'),
+  getGlassMode: require('./components/runtime').getGlassMode
+};

package/src/logic/anchorQuestion.js

@@ -0,0 +1,41 @@
+/**
+ * The question at the top, the answer below — the way two people talk.
+ *
+ * When a message is sent to an assistant, the thread scrolls up to put the
+ * question at the top of the screen, and the answer is written in all the
+ * room left below. Before, the thread followed the bottom while the answer
+ * streamed: every line received made the screen jump, and nothing could be
+ * read calmly.
+ *
+ * For the question to be ABLE to reach the top even when the answer is short,
+ * there must be room under it: a reserve, which shrinks as the answer grows.
+ * Both computations live here, without React.
+ */
+
+/** The air left above the question once at the top, in points. */
+const ANCHOR_MARGIN = 12;
+
+/** Where to scroll to put the question at the top of the thread. */
+function anchorOffset(anchorY) {
+  return Math.max(0, anchorY - ANCHOR_MARGIN);
+}
+
+/**
+ * The reserve to leave under the question so it can rise to the top.
+ *
+ * `contentHeight` is the height of the REAL content, reserve excluded — read
+ * at the reserve's own position. The first version started from the total
+ * scroll height, reserve included, minus the current reserve: but that
+ * measure arrived one frame after the reserve it contained, so each new
+ * reserve skewed the next one, and the question fell back to the middle of
+ * the screen once the answer was done.
+ *
+ * With this, the maximum scroll is EXACTLY the question's position, whether
+ * the answer grows or shrinks: nothing pushes it back down. As soon as the
+ * answer fills the screen, the reserve drops to zero.
+ */
+function reserveBelowQuestion({ viewportHeight, contentHeight, anchorY }) {
+  return Math.max(0, Math.round(viewportHeight - (contentHeight - anchorOffset(anchorY))));
+}
+
+module.exports = { ANCHOR_MARGIN, anchorOffset, reserveBelowQuestion };

package/src/logic/collapse.js

@@ -0,0 +1,77 @@
+/**
+ * When a floating bar folds away and when it comes back — the Instagram rule.
+ *
+ * Scroll down into the page, the bar shrinks; scroll back up, it returns to
+ * full size. The decision lives here, without React, to be tested alone; the
+ * `useCollapsingBar` hook only feeds it scroll offsets.
+ *
+ * Two guards. A finger tremor (less than COLLAPSE_THRESHOLD points) changes
+ * nothing. And at the very top of the page the bar is always full: iOS's
+ * rubber-band bounce at the top must not fold it.
+ */
+
+/** Minimal travel, in points, for a direction to count. */
+const COLLAPSE_THRESHOLD = 8;
+/** Below this scroll offset the bar stays full. */
+const TOP_ZONE = 24;
+
+/**
+ * One step of the decision.
+ *
+ * `anchor` is where the direction was last decided: the offset is compared to
+ * IT, not to the previous frame, so that a slow scroll (one point per frame)
+ * still ends up counting. Comparing frame to frame, a slow reader could scroll
+ * a whole page without the bar ever moving.
+ *
+ * @param {{collapsed: boolean, anchor: number}} state
+ * @param {number} y  The scroll offset.
+ */
+function followScroll(state, y) {
+  if (y <= TOP_ZONE) return { collapsed: false, anchor: Math.max(0, y) };
+  const travel = y - state.anchor;
+  if (travel > COLLAPSE_THRESHOLD) return { collapsed: true, anchor: y };
+  if (travel < -COLLAPSE_THRESHOLD) return { collapsed: false, anchor: y };
+  return state;
+}
+
+/** The state a screen starts in. */
+const INITIAL_COLLAPSE = Object.freeze({ collapsed: false, anchor: 0 });
+
+/* ── Bar size ─────────────────────────────────────────────────────────────
+   Tuned on a standard iPhone (390 points wide). On a large phone the bar
+   looked tiny: it grows with the screen width — height, icons, labels,
+   together, not in length — up to 12 % more. Never smaller. */
+const REFERENCE_WIDTH = 390;
+const MAX_BAR_SCALE = 1.12;
+
+function barScale(screenWidth) {
+  const width = Number(screenWidth);
+  if (!Number.isFinite(width)) return 1;
+  return Math.min(MAX_BAR_SCALE, Math.max(1, width / REFERENCE_WIDTH));
+}
+
+/* Folded, a bar shrinks toward the bottom to 84 % and drops 6 points: its
+   labels fade, its icons stay — it can still be tapped. */
+const COLLAPSED_SCALE = 0.84;
+const COLLAPSED_DROP = 6;
+
+/**
+ * Where a floating bottom element sits: above the gesture bar / home
+ * indicator, never glued to the bottom edge.
+ */
+function floatingBottomOffset(bottomInset) {
+  return Math.max(18, (Number(bottomInset) || 0) + 8);
+}
+
+module.exports = {
+  COLLAPSE_THRESHOLD,
+  TOP_ZONE,
+  INITIAL_COLLAPSE,
+  followScroll,
+  REFERENCE_WIDTH,
+  MAX_BAR_SCALE,
+  barScale,
+  COLLAPSED_SCALE,
+  COLLAPSED_DROP,
+  floatingBottomOffset
+};

package/src/logic/collapsibleHeader.js

@@ -0,0 +1,103 @@
+/**
+ * The collapsible page header, in numbers.
+ *
+ * Scrolling down a page used to take everything away — the title, the back
+ * button — and the reader no longer knew where they were. The rule now:
+ *
+ *  - the back button and the action buttons stay FIXED, always there;
+ *  - the large title scrolls away with the page;
+ *  - once it has gone, a small bar fades in at the top: the content slides
+ *    under it, blurred, and the page name is written in its centre.
+ *
+ * Under the bar, a FADE and not a line: the bar's background overflows by a
+ * few points and dies out there, so content disappears under it instead of
+ * being cut clean — a straight edge read as a rule drawn across the screen.
+ */
+const { parseColor } = require('./color');
+
+/** The bar's height, below the status bar. */
+const HEADER_BAR_HEIGHT = 52;
+/** The fade-in happens over these points of scroll, just before the threshold. */
+const HEADER_FADE_RUN = 28;
+/**
+ * Length of the fade under the bar, per platform.
+ *
+ * Android is shorter and lighter: without a blur, a solid band under the
+ * title "weighed too much". Its background lets the content show (94 % then
+ * 80 % at the bar's bottom edge) and dies out over a shorter band.
+ */
+const HEADER_BOTTOM_FADE = Object.freeze({ ios: 26, android: 16 });
+/** Before the title has been measured, the bar appears after this offset. */
+const HEADER_DEFAULT_THRESHOLD = 72;
+
+/**
+ * The scroll offset at which the bar has fully appeared: when the bottom of
+ * the large title passes under the bar. The content starts BELOW the bar, so
+ * the bar's own height comes off — and the status-bar inset too, when the
+ * scrolling content carries it as padding instead of a safe-area view. Never
+ * below 40: a page with a tiny title would otherwise show the bar at the
+ * first pixel of scroll.
+ *
+ * @param {number} titleBottom  Bottom of the title, in content coordinates.
+ * @param {number} [topInset]   Inset padded INSIDE the scroll content, if any.
+ */
+function headerThreshold(titleBottom, topInset = 0) {
+  return Math.max(40, titleBottom - HEADER_BAR_HEIGHT - topInset);
+}
+
+/*
+ * The two fade functions carry the 'worklet' directive: the header's animated
+ * styles call them on the UI thread, where only worklets can run. In Node the
+ * directive is an inert string.
+ */
+
+/** Input/output ranges for the bar's opacity. */
+function headerBarFade(threshold) {
+  'worklet';
+  return { input: [threshold - HEADER_FADE_RUN, threshold], output: [0, 1] };
+}
+
+/**
+ * Input ranges for the small title: it starts later than the bar and rises
+ * 6 points as it appears, so it lands rather than blinks.
+ */
+function headerTitleFade(threshold) {
+  'worklet';
+  return {
+    opacity: { input: [threshold - HEADER_FADE_RUN / 2, threshold + 8], output: [0, 1] },
+    translateY: { input: [threshold - HEADER_FADE_RUN, threshold + 8], output: [6, 0] }
+  };
+}
+
+function headerBottomFade(platform) {
+  return platform === 'android' ? HEADER_BOTTOM_FADE.android : HEADER_BOTTOM_FADE.ios;
+}
+
+/** Gradient stops: solid down to the bar's bottom edge, then dying out in the overflow. */
+function headerGradientStops(barHeight, fadeLength) {
+  return [0, barHeight / (barHeight + fadeLength), 1];
+}
+
+/**
+ * Android's background: the page colour, fading the same way. Its blur came
+ * out "dirty"; a clean gradient stays clean. Accepts any colour notation —
+ * appending hex alpha digits to a colour only works if it was `#rrggbb`.
+ */
+function androidHeaderColors(pageBackground) {
+  const c = parseColor(pageBackground) || { r: 255, g: 255, b: 255 };
+  const rgba = (a) => `rgba(${c.r},${c.g},${c.b},${a})`;
+  return [rgba(0.94), rgba(0.8), rgba(0)];
+}
+
+module.exports = {
+  HEADER_BAR_HEIGHT,
+  HEADER_FADE_RUN,
+  HEADER_BOTTOM_FADE,
+  HEADER_DEFAULT_THRESHOLD,
+  headerThreshold,
+  headerBarFade,
+  headerTitleFade,
+  headerBottomFade,
+  headerGradientStops,
+  androidHeaderColors
+};

package/src/logic/color.js

@@ -0,0 +1,68 @@
+/**
+ * Colour arithmetic, without a colour library.
+ *
+ * Every surface of the kit mixes a tint into a page colour, or re-weights the
+ * alpha of a tint. Doing it here, on plain strings, is what lets a test check
+ * the result to the digit instead of judging a screenshot.
+ */
+
+/**
+ * Reads `#rgb`, `#rrggbb`, `#rrggbbaa`, `rgb()` or `rgba()`.
+ * Returns `{ r, g, b, a }`, or null for anything else (a named colour, a
+ * typo) — the caller decides what an unreadable colour falls back to.
+ */
+function parseColor(value) {
+  if (typeof value !== 'string') return null;
+  const v = value.trim().toLowerCase();
+  const short = /^#([0-9a-f])([0-9a-f])([0-9a-f])$/.exec(v);
+  if (short) {
+    const [r, g, b] = [short[1], short[2], short[3]].map((c) => parseInt(c + c, 16));
+    return { r, g, b, a: 1 };
+  }
+  const long = /^#([0-9a-f]{2})([0-9a-f]{2})([0-9a-f]{2})([0-9a-f]{2})?$/.exec(v);
+  if (long) {
+    const [r, g, b] = [long[1], long[2], long[3]].map((c) => parseInt(c, 16));
+    return { r, g, b, a: long[4] ? parseInt(long[4], 16) / 255 : 1 };
+  }
+  const fn = /^rgba?\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)\s*(?:,\s*([\d.]+)\s*)?\)$/.exec(v);
+  if (fn) {
+    return { r: Number(fn[1]), g: Number(fn[2]), b: Number(fn[3]), a: fn[4] === undefined ? 1 : Number(fn[4]) };
+  }
+  return null;
+}
+
+function toHex({ r, g, b }) {
+  return `#${[r, g, b]
+    .map((c) =>
+      Math.round(Math.min(255, Math.max(0, c)))
+        .toString(16)
+        .padStart(2, '0')
+    )
+    .join('')}`;
+}
+
+/**
+ * `tint` laid over `background` at `proportion`, returned OPAQUE.
+ *
+ * Opaque on purpose: a page often paints a pattern (a grid, a gradient) under
+ * its content, and a translucent card lets that pattern show through as a
+ * faint checkerboard. The alpha of either input is ignored.
+ */
+function mixColors(background, tint, proportion) {
+  const base = parseColor(background) || { r: 255, g: 255, b: 255 };
+  const colour = parseColor(tint) || base;
+  return toHex({
+    r: base.r + (colour.r - base.r) * proportion,
+    g: base.g + (colour.g - base.g) * proportion,
+    b: base.b + (colour.b - base.b) * proportion
+  });
+}
+
+/** The same colour at another alpha, whatever notation it came in. */
+function withAlpha(color, alpha) {
+  const c = parseColor(color);
+  if (!c) return color;
+  return `rgba(${c.r},${c.g},${c.b},${Number(alpha.toFixed(3))})`;
+}
+
+module.exports = { parseColor, mixColors, withAlpha };

package/src/logic/glass.js

@@ -0,0 +1,151 @@
+/**
+ * The glass rules, decided without react-native so they test dry.
+ *
+ * WHICH GLASS. The device's glass mode comes from `resolveGlassMode` in
+ * `@astratra/native` — one rule for the whole Astratra stack, not a second
+ * copy here. This kit only ever asks one question of it: is the answer
+ * `'native'` (Apple's own Liquid Glass material)?
+ *
+ * Everything else — Android, an iPhone below iOS 26, the web — gets a VISIBLE
+ * SURFACE, not an imitation. That was learnt the hard way. Android was first
+ * given its native backdrop blur (`dimezisBlurView`, the `'blur'` answer):
+ * the blur worked, but it imitated a material that does not exist on Android.
+ * It captures the view hierarchy and re-blurs it every frame, and the result
+ * looked neither like Apple's glass nor like Material — a dense, opaque grey,
+ * obvious on the tab bar and around every round button. Android says "surface
+ * resting on the page" with a fill, a radius and an elevation; that is what
+ * it gets.
+ */
+const { parseColor } = require('./color');
+
+/**
+ * The real weight Apple gives a tint.
+ *
+ * Measured to the pixel on the same screens, iOS vs Android: a `GlassView`
+ * tinted white at 0.4 leaves a light background... unchanged — 240,242,251
+ * inside as outside. Apple does not PAINT the tint; it modulates its frosting
+ * with it, and on light backgrounds almost nothing of it reaches the eye.
+ * Painting the tint as declared on Android gave panels visibly milkier than
+ * the same screens on iOS — THE visible difference between the two builds.
+ * A quarter of the declared weight gets close to Apple's rendering while
+ * keeping the surface visible at all.
+ */
+const TINT_WEIGHT = 0.25;
+
+/**
+ * The frosting of Apple's INTERACTIVE glass.
+ *
+ * Unlike a container, a button has matter: measured on a back button, iOS
+ * renders it LIGHTER than the background (+7) where a container stays
+ * neutral. The shadow a button declares shows through a translucent fill (on
+ * both systems — CALayer and Android's boxShadow both draw it under the whole
+ * surface), so the frosting must cover it too; hence this weight, calibrated
+ * to the pixel against iOS.
+ */
+const INTERACTIVE_FROST = 0.4;
+
+/** Style keys that draw a shadow, on either platform. */
+const SHADOW_KEYS = ['boxShadow', 'shadowColor', 'shadowOpacity', 'shadowRadius', 'shadowOffset', 'elevation'];
+
+/**
+ * The tint a caller asked the glass for, at the weight Apple really gives it.
+ *
+ * Only a TRANSLUCENT tint is re-weighted. An opaque colour (`#3b6cf0`) is not
+ * a glass tint, it is paint: the caller wants that colour, and quartering it
+ * would turn a primary action into a pale ghost of itself.
+ */
+function tintAtAppleWeight(color, interactive) {
+  const c = parseColor(color);
+  if (!c || !(c.a < 1)) return color;
+  const composed = interactive ? 1 - (1 - INTERACTIVE_FROST) * (1 - c.a) : c.a * TINT_WEIGHT;
+  return `rgba(${c.r},${c.g},${c.b},${composed.toFixed(3)})`;
+}
+
+/**
+ * The surface style off Apple's glass, with iOS's shadow rule applied.
+ *
+ * On iOS, CALayer computes a shadow from the view's ALPHA silhouette: an
+ * almost transparent glass container casts practically nothing — a panel with
+ * a declared shadow shows NO outline on iOS. Android's boxShadow always draws
+ * the full rectangle: every container came out ringed by a ghost frame that
+ * does not exist on iOS. So a container's shadow is removed; a button's —
+ * whose frosting gives it a real fill — is kept, as iOS shows it.
+ *
+ * Takes an already-flattened style and returns a new object.
+ */
+function surfaceStyleOffApple(flatStyle, interactive) {
+  const style = { ...(flatStyle || {}) };
+  if (!interactive) for (const key of SHADOW_KEYS) delete style[key];
+  return style;
+}
+
+/**
+ * The default tint of an untinted glass button.
+ *
+ * On iOS 0.14 of white is enough: Apple's glass adds its own matter on top.
+ * Off Apple's glass there is no such layer — at the same value the button
+ * would vanish. It needs a real fill.
+ */
+function glassButtonTint({ mode, selected = false } = {}) {
+  if (mode === 'native') return selected ? 'rgba(255,255,255,0.35)' : 'rgba(255,255,255,0.14)';
+  return selected ? 'rgba(255,255,255,0.98)' : 'rgba(255,255,255,0.9)';
+}
+
+/**
+ * The matter of a glass button: an object caught in an ice cube.
+ *
+ * The glass needs DEPTH — a highlight at the top, a denser foot — and what it
+ * carries must come out sharp on top instead of being dimmed by a veil.
+ *
+ * Returns `{ glassStyle, highlight, glow }`, and deliberately nothing else:
+ * no stroke. A white hairline at the top and an ink outline around read as
+ * "lines that show it's plastic ice". On a real iPhone icon nothing rings the
+ * glass — the light is INSIDE it.
+ */
+function glassButtonMaterial({ mode, scheme = 'light', tinted = false } = {}) {
+  const dark = scheme === 'dark';
+  /* `regular` frosts AND slightly darkens what it covers: on a white page it
+     made the buttons grey and dull on a real iPhone. `clear` keeps the lens
+     and its reflections without the veil. In dark mode the frosting is what
+     separates the button from the night background. A tinted button carries
+     its own colour: `clear` lets it through without washing it out. */
+  const glassStyle = tinted || !dark ? 'clear' : 'regular';
+
+  /* The top catches the light, the bottom thickens: this gradient is what
+     reads as a domed volume rather than a flat disc. On a solid colour the
+     highlight is stronger — it has to show on blue. */
+  const highlight = tinted
+    ? ['rgba(255,255,255,0.34)', 'rgba(255,255,255,0)', 'rgba(0,0,0,0.10)']
+    : dark
+      ? ['rgba(255,255,255,0.16)', 'rgba(255,255,255,0)', 'rgba(0,0,0,0.22)']
+      : ['rgba(255,255,255,0.70)', 'rgba(255,255,255,0)', 'rgba(13,18,53,0.05)'];
+
+  /* The glow: iOS casts the shadow of a view WITHOUT a fill onto the
+     silhouette of its content — the icon, the letters. A light halo around a
+     dark icon lifts it off the glass; a dark shadow under a light icon (tinted
+     button, dark mode) makes it pop. Android draws the whole rectangle
+     instead: that would be a grey halo around every button. */
+  const glow =
+    mode !== 'native'
+      ? null
+      : tinted || dark
+        ? {
+            shadowColor: '#000000',
+            shadowOpacity: dark && !tinted ? 0.45 : 0.28,
+            shadowRadius: 2,
+            shadowOffset: { width: 0, height: 1 }
+          }
+        : { shadowColor: '#ffffff', shadowOpacity: 0.95, shadowRadius: 2.5, shadowOffset: { width: 0, height: 0 } };
+
+  return { glassStyle, highlight, glow };
+}
+
+module.exports = {
+  TINT_WEIGHT,
+  INTERACTIVE_FROST,
+  SHADOW_KEYS,
+  tintAtAppleWeight,
+  surfaceStyleOffApple,
+  glassButtonTint,
+  glassButtonMaterial
+};