@signal9/era-ui 12.1.2 → 13.0.0

package/dist/styles/index.css

@@ -1,14 +1,48 @@
-@import './themes.css';
-@import './density.css';
+/* ------------------------------------------------------------------ */
+/* CASCADE LAYERS                                                     */
+/*                                                                    */
+/* era's token CSS is LAYERED so a consumer can override it without   */
+/* a specificity fight. Unlayered styles beat every layer, so a       */
+/* consumer's own `:root[data-theme='mine']` block — written plainly, */
+/* no !important, no selector padding — now wins against era's, which */
+/* is what defining a theme downstream should feel like. Before this  */
+/* everything era shipped was unlayered, so it outranked the whole of */
+/* a consumer's own `@layer`ed Tailwind CSS.                          */
+/*                                                                    */
+/* WHAT IS DELIBERATELY NOT LAYERED, because layering would change    */
+/* what it means rather than just where it sits:                      */
+/*                                                                    */
+/*   typography.css and motion.css contain `!important` — the font    */
+/*   axis hammer and the reduced-motion guarantee. Layer order is     */
+/*   REVERSED for important declarations, so moving these into a      */
+/*   layer would make them beat a consumer's unlayered !important     */
+/*   instead of losing to it. That is a stronger claim than era has   */
+/*   any business making about someone else's page.                   */
+/*                                                                    */
+/*   The .era-text-trim.truncate collision guard (below) has to       */
+/*   outrank two single-class utilities, and utilities are layered.   */
+/*   Unlayered is precisely what lets it win.                         */
+/*                                                                    */
+/*   @utility and @theme are Tailwind's to place; it already layers   */
+/*   them.                                                            */
+/* ------------------------------------------------------------------ */
+@layer era.tokens, era.base;
+
+@import './themes.css' layer(era.tokens);
+@import './density.css' layer(era.tokens);
+/* Stacking contract — global tiers only; see the file for the local/global split. */
+@import './layers.css' layer(era.tokens);
 /* Motion axis (data-motion) — owns --era-duration + --era-ease. Imported before
- * surfaces so a [data-surface] block can override --era-ease as a delta. */
+ * surfaces so a [data-surface] block can override --era-ease as a delta.
+ * UNLAYERED: carries the prefers-reduced-motion !important — see above. */
 @import './motion.css';
 /* Surfaces: base contract first, then each surface's deltas. Order matters —
  * the base block and a surface's block target the same element, and the
- * surface's declarations must win. */
-@import './surfaces/base.css';
-@import './surfaces/glass.css';
-@import './surfaces/bevel.css';
+ * surface's declarations must win. Same layer, so source order still decides. */
+@import './surfaces/base.css' layer(era.tokens);
+@import './surfaces/glass.css' layer(era.tokens);
+@import './surfaces/bevel.css' layer(era.tokens);
+/* UNLAYERED: carries the font-axis !important — see above. */
 @import './typography.css';
 
 /* WHAT IS NOT HERE: vidstack's stylesheets, which the VideoPlayer needs and
@@ -35,13 +69,14 @@
 @source '../ui';
 @source '../ai';
 @source '../os';
-@source '../apps';
 
 /* Lucide icons use an SVG presentation attribute for stroke width by default.
  * Set it from an Era token globally so every imported Lucide component tracks
  * the same optical weight as adjacent body text and can be tuned in one place. */
-:where(.lucide) {
-	stroke-width: var(--era-glyph-stroke-width);
+@layer era.base {
+	:where(.lucide) {
+		stroke-width: var(--era-glyph-stroke-width);
+	}
 }
 
 /* The mask glyph is the one piece of type the UA picks for you, so era picks it
@@ -67,8 +102,10 @@
  * type="text" and masking it ourselves, which costs password-manager detection
  * and the screen-reader "password" announcement. Deliberately not done — the
  * semantics are worth more than the corner. */
-:where(input[type='password']) {
-	-webkit-text-security: var(--era-mask-glyph, disc);
+@layer era.base {
+	:where(input[type='password']) {
+		-webkit-text-security: var(--era-mask-glyph, disc);
+	}
 }
 
 /* Shared interactive-state recipe: quiet focus, disabled affordance.
@@ -351,6 +388,24 @@
 	text-box: trim-both ex alphabetic;
 }
 
+/* Tailwind v4 cannot resolve var() inside backdrop-blur-[], so the filter
+ * is a registered utility, gated to glass subtrees.
+ *
+ * It lives HERE rather than in surfaces/glass.css, where a surface's own
+ * chrome would naturally sit, because glass.css is imported into a cascade
+ * layer and `@utility` cannot be nested inside one. Surface-scoped RULES stay
+ * in their surface file; surface-scoped UTILITIES have to come out.
+ *
+ * @use the backdrop blur for a floating panel (popover, dialog, taskbar) — it
+ * applies only inside a data-surface="glass" subtree and is inert elsewhere,
+ * so it is safe to leave on a panel that renders under every surface. */
+@utility glass-blur {
+	[data-surface='glass'] & {
+		backdrop-filter: blur(var(--era-blur)) saturate(var(--era-saturate));
+		-webkit-backdrop-filter: blur(var(--era-blur)) saturate(var(--era-saturate));
+	}
+}
+
 /* In-progress text shimmer — a bright sweep through muted text (the standard
  * "working…" label treatment in streaming UIs). Timing derives from the motion
  * axis (10× --era-duration ≈ 1.5s at normal, 2.6s at extra); at instant the
@@ -541,6 +596,16 @@
 	 * bg-field-highlight its focused/hovered face. */
 	--color-field: var(--era-field-bg);
 	--color-field-highlight: var(--era-field-highlight);
+	/* @use the stacking tier for chrome that renders at the document root —
+	 * z-chrome (taskbar) < z-drawer (slide-over) < z-overlay (every dialog,
+	 * menu, popover and scrim) < z-toast < z-debug. A component ordering its
+	 * OWN parts inside an isolated context keeps small integers instead; see
+	 * styles/layers.css for why the two are different things. */
+	--z-index-chrome: var(--era-z-chrome);
+	--z-index-drawer: var(--era-z-drawer);
+	--z-index-overlay: var(--era-z-overlay);
+	--z-index-toast: var(--era-z-toast);
+	--z-index-debug: var(--era-z-debug);
 	/* Motion — bare transition utilities default to the motion axis, so
 	 * `transition-colors` alone is on-design (0s at instant, longer at extra).
 	 * ease-base/duration-base name the axis explicitly for overrides. */

package/dist/styles/layers.css

@@ -0,0 +1,48 @@
+/* ------------------------------------------------------------------ */
+/* THE STACKING CONTRACT                                              */
+/*                                                                    */
+/* Two kinds of z-index exist in this library, and conflating them is */
+/* what turns stacking into whack-a-mole.                             */
+/*                                                                    */
+/* GLOBAL TIERS — elements that render at the document root, either   */
+/* because they are shell chrome or because a portal put them there.  */
+/* These CAN collide with each other, from anywhere in the tree, so   */
+/* their order is a contract and they are named here. Nothing in the  */
+/* library may write a raw z-index in this band; scripts/check-layers */
+/* fails the build if it does.                                        */
+/*                                                                    */
+/* LOCAL STACKING — a component ordering its own parts (a video's     */
+/* poster under its controls, a pane's resize edges over its body).   */
+/* These stay small integers on purpose: they are meaningless outside */
+/* their own component and naming them with a global tier would claim */
+/* a relationship that does not exist. What makes them safe is not    */
+/* their value but ISOLATION — the ancestor establishing a stacking   */
+/* context, so the number cannot escape. The OS Desktop is the        */
+/* load-bearing example: it is `isolate`, so panes hand out 1..N      */
+/* freely and no pane can ever climb over a menu or a toast.          */
+/*                                                                    */
+/* The tiers are spaced to leave room, and 50 is deliberate: bits-ui  */
+/* portals its dialogs, menus and tooltips at z-50, so era's own      */
+/* floating chrome sits in that same band rather than fighting it.    */
+/* Anything that must beat a menu goes above; chrome that a menu must */
+/* open over goes below.                                              */
+/* ------------------------------------------------------------------ */
+:root {
+	/* Shell chrome — a taskbar or dock. BELOW the overlay band, so a
+	 * dropdown anchored to the taskbar opens over the taskbar. */
+	--era-z-chrome: 30;
+	/* Slide-over panels that hang off the chrome (a notification centre).
+	 * Above the chrome it emerges from, still under menus. */
+	--era-z-drawer: 40;
+	/* Every floating panel and every scrim: dialog, popover, select, menu,
+	 * tooltip, command bar. Shares bits-ui's own tier — within it, DOM order
+	 * decides, which is what makes a popover opened from inside a dialog land
+	 * above the dialog without either knowing about the other. */
+	--era-z-overlay: 50;
+	/* Transient system messages. Above the overlay band on purpose: a toast
+	 * that a modal can hide is a toast you will miss. */
+	--era-z-toast: 55;
+	/* Development overlays (the audit harness). Above everything it inspects,
+	 * because inspecting a dialog means drawing on top of one. */
+	--era-z-debug: 60;
+}

package/dist/styles/surfaces/base.css

@@ -196,8 +196,10 @@
  *     a bevel thumb sliding along a track), scope a rule to the surface and
  *     target the component's stable part, e.g. in the surface's own file:
  *       [data-surface='<name>'] [data-slot='switch-thumb'] { … }
- *     Keyframes and surface-only utilities live in that surface's file
- *     (precedent: the `glass-blur` @utility in glass.css).
+ *     Keyframes live in that surface's file. Surface-only UTILITIES cannot:
+ *     the surface files are imported into a cascade layer, and `@utility` may
+ *     not be nested inside one — so they live in styles/index.css alongside
+ *     the rest (precedent: `glass-blur`, which is gated to glass subtrees).
  *
  * Reduced-motion is handled centrally in motion.css — surfaces need not.
  */

package/dist/styles/surfaces/glass.css

@@ -155,16 +155,3 @@
 		--era-selection-shadow: none;
 	}
 }
-
-/* Tailwind v4 cannot resolve var() inside backdrop-blur-[], so the filter
- * is a registered utility, gated to glass subtrees.
- *
- * @use the backdrop blur for a floating panel (popover, dialog, taskbar) — it
- * applies only inside a data-surface="glass" subtree and is inert elsewhere,
- * so it is safe to leave on a panel that renders under every surface. */
-@utility glass-blur {
-	[data-surface='glass'] & {
-		backdrop-filter: blur(var(--era-blur)) saturate(var(--era-saturate));
-		-webkit-backdrop-filter: blur(var(--era-blur)) saturate(var(--era-saturate));
-	}
-}

package/dist/theme/index.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Authoring a theme, with the contract in the type system.
+ *
+ * A theme was a block of hand-written CSS, and the set of tokens it had to
+ * define existed only in the heads of the people who had written one before.
+ * Nothing checked it. The failure mode is not a build error — it is a token
+ * that quietly inherits the DEFAULT theme's value and looks almost right: era's
+ * own `sand` shipped with accent foregrounds inherited from a palette whose
+ * floor was half a lightness step away, and the result measured 2.48:1 before
+ * anyone noticed it by eye.
+ *
+ * So the contract is a type. Every token the system's `@theme` block depends on
+ * is a required field, `themeCss()` turns a checked object into the CSS text,
+ * and omitting one is a compile error rather than a contrast bug.
+ *
+ * Three tokens are deliberately OPTIONAL, because era defines them once at the
+ * root and a theme is not expected to restate them: `bright`, `link` and
+ * `muted`. Setting them overrides the default; leaving them out inherits it,
+ * which is what era's own themes do.
+ *
+ * This is an AUTHORING helper, not a runtime. It returns a string. Put it in a
+ * `.css.ts`-style build step, a `<style>` in your root layout, or paste the
+ * output — era's own themes stay hand-written CSS because their values carry
+ * measured rationale in comments that generated output would lose.
+ */
+/** The 12-step ramp, background (1) through to the brightest ink (12). */
+export type Scale12 = readonly [
+    string,
+    string,
+    string,
+    string,
+    string,
+    string,
+    string,
+    string,
+    string,
+    string,
+    string,
+    string
+];
+/** `step(5)` → `var(--color-5)` — point a semantic token at a rung. */
+export declare const step: (n: 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12) => string;
+export interface ThemeMode {
+    /** Drives `color-scheme`, and with it the UA's own form controls and scrollbars. */
+    scheme: 'dark' | 'light';
+    /** The ramp. Every other token may reference a rung with `step()`. */
+    scale: Scale12;
+    /** Chrome. */
+    border: string;
+    surface: string;
+    hover: string;
+    fg: string;
+    /** Accents, each with the ink that sits ON it — the pair is the point. */
+    primary: string;
+    primaryFg: string;
+    primaryHover: string;
+    destructive: string;
+    destructiveFg: string;
+    success: string;
+    successFg: string;
+    warning: string;
+    warningFg: string;
+    /** Optional — era defines these at the root; set to override. */
+    bright?: string;
+    link?: string;
+    muted?: string;
+    /**
+     * Anything else the theme owns, as bare token names: `{ 'color-ink':
+     * 'oklch(0.24 0.03 60)' }`. era's `sand` needs exactly this — its palette has
+     * no rung dark enough to serve as accent ink, so it defines its own.
+     */
+    extra?: Record<string, string>;
+}
+export interface Theme {
+    /** Selected with `data-theme="<name>"`. */
+    name: string;
+    dark: ThemeMode;
+    light: ThemeMode;
+}
+/**
+ * The CSS for a theme: a dark block, a `prefers-color-scheme: light` block, and
+ * the explicit `.light` / `.dark` class escapes that let a subtree opt out.
+ *
+ * Emitted into `@layer era.tokens` so it sits exactly where era's own themes
+ * sit — a consumer's later, unlayered CSS still wins over both.
+ */
+export declare function themeCss(theme: Theme): string;

package/dist/theme/index.js

@@ -0,0 +1,86 @@
+/**
+ * Authoring a theme, with the contract in the type system.
+ *
+ * A theme was a block of hand-written CSS, and the set of tokens it had to
+ * define existed only in the heads of the people who had written one before.
+ * Nothing checked it. The failure mode is not a build error — it is a token
+ * that quietly inherits the DEFAULT theme's value and looks almost right: era's
+ * own `sand` shipped with accent foregrounds inherited from a palette whose
+ * floor was half a lightness step away, and the result measured 2.48:1 before
+ * anyone noticed it by eye.
+ *
+ * So the contract is a type. Every token the system's `@theme` block depends on
+ * is a required field, `themeCss()` turns a checked object into the CSS text,
+ * and omitting one is a compile error rather than a contrast bug.
+ *
+ * Three tokens are deliberately OPTIONAL, because era defines them once at the
+ * root and a theme is not expected to restate them: `bright`, `link` and
+ * `muted`. Setting them overrides the default; leaving them out inherits it,
+ * which is what era's own themes do.
+ *
+ * This is an AUTHORING helper, not a runtime. It returns a string. Put it in a
+ * `.css.ts`-style build step, a `<style>` in your root layout, or paste the
+ * output — era's own themes stay hand-written CSS because their values carry
+ * measured rationale in comments that generated output would lose.
+ */
+/** `step(5)` → `var(--color-5)` — point a semantic token at a rung. */
+export const step = (n) => `var(--color-${n})`;
+const TOKEN = {
+    border: '--color-border',
+    surface: '--color-surface',
+    hover: '--color-hover',
+    fg: '--color-fg',
+    primary: '--color-primary',
+    primaryFg: '--color-primary-fg',
+    primaryHover: '--color-primary-hover',
+    destructive: '--color-destructive',
+    destructiveFg: '--color-destructive-fg',
+    success: '--color-success',
+    successFg: '--color-success-fg',
+    warning: '--color-warning',
+    warningFg: '--color-warning-fg',
+    bright: '--color-bright',
+    link: '--color-link',
+    muted: '--color-muted'
+};
+function modeBody(mode, indent) {
+    const lines = [`${indent}color-scheme: ${mode.scheme};`, ''];
+    mode.scale.forEach((value, i) => lines.push(`${indent}--color-${i + 1}: ${value};`));
+    lines.push('');
+    for (const [key, token] of Object.entries(TOKEN)) {
+        const value = mode[key];
+        if (typeof value === 'string')
+            lines.push(`${indent}${token}: ${value};`);
+    }
+    for (const [name, value] of Object.entries(mode.extra ?? {})) {
+        lines.push(`${indent}--${name.replace(/^--/, '')}: ${value};`);
+    }
+    return lines.join('\n');
+}
+/**
+ * The CSS for a theme: a dark block, a `prefers-color-scheme: light` block, and
+ * the explicit `.light` / `.dark` class escapes that let a subtree opt out.
+ *
+ * Emitted into `@layer era.tokens` so it sits exactly where era's own themes
+ * sit — a consumer's later, unlayered CSS still wins over both.
+ */
+export function themeCss(theme) {
+    const { name, dark, light } = theme;
+    return `@layer era.tokens {
+\t:root[data-theme='${name}'],
+\t[data-theme='${name}'].dark {
+${modeBody(dark, '\t\t')}
+\t}
+
+\t@media (prefers-color-scheme: light) {
+\t\t:root[data-theme='${name}']:not(.dark) {
+${modeBody(light, '\t\t\t')}
+\t\t}
+\t}
+
+\t[data-theme='${name}'].light {
+${modeBody(light, '\t\t')}
+\t}
+}
+`;
+}

package/dist/ui/alert-dialog/alert-dialog-content.svelte

@@ -11,11 +11,11 @@
 </script>
 
 <AlertDialog.Portal>
-	<AlertDialog.Overlay class="fixed inset-0 z-50 bg-overlay" />
+	<AlertDialog.Overlay class="fixed inset-0 z-overlay bg-overlay" />
 	<AlertDialog.Content
 		bind:ref
 		class={cn(
-			'fixed top-1/2 left-1/2 z-50 flex w-full max-w-md -translate-x-1/2 -translate-y-1/2 flex-col gap-gutter rounded-bar border border-divider bg-well p-card shadow-lg glass-blur',
+			'fixed top-1/2 left-1/2 z-overlay flex w-full max-w-md -translate-x-1/2 -translate-y-1/2 flex-col gap-gutter rounded-bar border border-divider bg-well p-card shadow-lg glass-blur',
 			className
 		)}
 		{...restProps}

package/dist/ui/alert-dialog/alert-dialog-overlay.svelte

@@ -11,6 +11,6 @@
 
 <AlertDialog.Overlay
 	bind:ref
-	class={cn('fixed inset-0 z-50 bg-overlay', className)}
+	class={cn('fixed inset-0 z-overlay bg-overlay', className)}
 	{...restProps}
 />

package/dist/ui/badge/badge.svelte

@@ -40,16 +40,29 @@
 	let {
 		ref = $bindable(null),
 		tone = 'default',
+		lead,
 		children,
 		class: className,
 		...restProps
 	}: HTMLAttributes<HTMLSpanElement> & {
 		ref?: HTMLSpanElement | null;
 		tone?: 'default' | 'accent' | 'destructive' | 'success' | 'warning';
+		/** Icon rendered BEFORE the label, outside it. Use this rather than putting
+		 * an icon in `children`: the label then gets its own box, which is the only
+		 * place era's ink centring can reach. */
+		lead?: Snippet;
 		children?: Snippet;
 	} = $props();
 </script>
 
 <span bind:this={ref} class={cn(badgeVariants({ tone }), className)} {...restProps}>
-	{@render children?.()}
+	{#if lead}
+		{@render lead()}
+	{/if}
+	<!-- The label box exists ONLY when `lead` is used. Rendering it for every call
+	     site changed the DOM everywhere: a `display:contents` span has no box, and
+	     the geometry audits walk real boxes. Opt-in keeps the legacy shape
+	     byte-identical and gives the new shape a real box for the CAP-band trim a token wants. -->
+	{#if lead}<span class="era-text-trim-caps">{@render children?.()}</span
+		>{:else}{@render children?.()}{/if}
 </span>

package/dist/ui/badge/badge.svelte.d.ts

@@ -28,6 +28,10 @@ import type { HTMLAttributes } from 'svelte/elements';
 type $$ComponentProps = HTMLAttributes<HTMLSpanElement> & {
     ref?: HTMLSpanElement | null;
     tone?: 'default' | 'accent' | 'destructive' | 'success' | 'warning';
+    /** Icon rendered BEFORE the label, outside it. Use this rather than putting
+     * an icon in `children`: the label then gets its own box, which is the only
+     * place era's ink centring can reach. */
+    lead?: Snippet;
     children?: Snippet;
 };
 declare const Badge: import("svelte").Component<$$ComponentProps, {}, "ref">;

package/dist/ui/button/button.svelte

@@ -15,6 +15,8 @@
 		loading = false,
 		loadingLabel,
 		disabled,
+		lead,
+		trail,
 		children,
 		class: className,
 		...restProps
@@ -32,6 +34,12 @@
 		loading?: boolean;
 		/** Screen-reader-only label announced while `loading` is true. */
 		loadingLabel?: string;
+		/** Icon rendered BEFORE the label, outside it. Use this rather than putting
+		 * an icon in `children`: the label then gets its own box, which is the only
+		 * place era's ink centring can reach (see era-label-ink). */
+		lead?: Snippet;
+		/** Icon rendered AFTER the label, outside it. Same reason as `lead`. */
+		trail?: Snippet;
 		children?: Snippet;
 	} = $props();
 
@@ -71,12 +79,22 @@
 		forwards the button's own gap so the icon/label spacing is unchanged.
 	-->
 	<!--
-		not-has-[svg]:era-label-ink — a text-only button ink-centres its label.
-		The span is otherwise a flex box, and a flex box's bare text is an
-		ANONYMOUS item that `text-box-trim` can never reach, so the label fell back
-		to line-box centring by font metrics (the bug era-label-ink documents).
-		With an icon present the box must stay flex for the gap, and that case is
-		still on the fallback — typography/inert-trim reports it.
+		THE LABEL GETS ITS OWN BOX, which is what `lead`/`trail` are for.
+
+		Bare text in a flex container is an ANONYMOUS flex item, and
+		`text-box-trim` can never reach one — so a label beside an icon is centred
+		by font metrics rather than by its typographic band, and no CSS can change
+		that. A <span> that is a flex item is BLOCKIFIED, so the trim does apply to
+		it; putting the icon OUTSIDE that span is what removes the anonymous item.
+
+		WHAT THIS IS AND IS NOT WORTH: measured on a real button across all four
+		density modes and all three shipped stacks, the legacy shape and this one
+		both centre their ink to 0px. So this is not a pixel fix — it is an API
+		fix. It makes the label ADDRESSABLE, which is what turns
+		typography/anonymous-text from a law era permanently violates into one it
+		can satisfy, and it is the shape every comparable library uses for
+		icon+label. The legacy `<Button><Check /> Save</Button>` still renders
+		unchanged, and the audit goes on reporting it.
 	-->
 	<span
 		data-button-content
@@ -86,6 +104,18 @@
 			<LoaderCircle class="size-icon shrink-0 animate-spin" aria-hidden="true" />
 			{#if loadingLabel}<span class="sr-only">{loadingLabel}</span>{/if}
 		{/if}
-		{@render children?.()}
+		<!-- The label box exists ONLY when `lead`/`trail` are used. Rendering it
+		     unconditionally changed the DOM for every legacy call site: a
+		     `display:contents` span has no box, and the geometry audits walk real
+		     boxes, so an icon button's nesting measurements went to pieces. Opting
+		     in keeps the old shape byte-identical and gives the new shape a real
+		     box for the trim to act on. -->
+		{#if lead || trail}
+			{@render lead?.()}
+			{#if children}<span class="era-text-trim">{@render children()}</span>{/if}
+			{@render trail?.()}
+		{:else}
+			{@render children?.()}
+		{/if}
 	</span>
 </Button.Root>

package/dist/ui/button/button.svelte.d.ts

@@ -14,6 +14,12 @@ type $$ComponentProps = Button.RootProps & {
     loading?: boolean;
     /** Screen-reader-only label announced while `loading` is true. */
     loadingLabel?: string;
+    /** Icon rendered BEFORE the label, outside it. Use this rather than putting
+     * an icon in `children`: the label then gets its own box, which is the only
+     * place era's ink centring can reach (see era-label-ink). */
+    lead?: Snippet;
+    /** Icon rendered AFTER the label, outside it. Same reason as `lead`. */
+    trail?: Snippet;
     children?: Snippet;
 };
 declare const Button: import("svelte").Component<$$ComponentProps, {}, "ref">;

package/dist/ui/chip/chip.svelte

@@ -68,6 +68,7 @@
 		ref = $bindable(null),
 		size = 'chip',
 		ondismiss,
+		lead,
 		children,
 		class: className,
 		...restProps
@@ -77,6 +78,10 @@
 		 * that nests inside an md container (a select trigger, a button). */
 		size?: 'chip' | 'pill';
 		ondismiss?: () => void;
+		/** Icon rendered BEFORE the label, outside it. Use this rather than putting
+		 * an icon in `children`: the label then gets its own box, which is the only
+		 * place era's ink centring can reach. */
+		lead?: Snippet;
 		children?: Snippet;
 	} = $props();
 </script>
@@ -86,7 +91,15 @@
 	class={cn(chipVariants({ size, dismissible: !!ondismiss }), className)}
 	{...restProps}
 >
-	{@render children?.()}
+	{#if lead}
+		{@render lead()}
+	{/if}
+	<!-- The label box exists ONLY when `lead` is used. Rendering it for every call
+	     site changed the DOM everywhere: a `display:contents` span has no box, and
+	     the geometry audits walk real boxes. Opt-in keeps the legacy shape
+	     byte-identical and gives the new shape a real box for the trim. -->
+	{#if lead}<span class="era-text-trim">{@render children?.()}</span
+		>{:else}{@render children?.()}{/if}
 	{#if ondismiss}
 		<!--
 			Stop pointerdown/up from bubbling to ancestor triggers (Select.Trigger,

package/dist/ui/chip/chip.svelte.d.ts

@@ -34,6 +34,10 @@ type $$ComponentProps = HTMLAttributes<HTMLDivElement> & {
      * that nests inside an md container (a select trigger, a button). */
     size?: 'chip' | 'pill';
     ondismiss?: () => void;
+    /** Icon rendered BEFORE the label, outside it. Use this rather than putting
+     * an icon in `children`: the label then gets its own box, which is the only
+     * place era's ink centring can reach. */
+    lead?: Snippet;
     children?: Snippet;
 };
 declare const Chip: import("svelte").Component<$$ComponentProps, {}, "ref">;

package/dist/ui/combobox/combobox-content.svelte

@@ -15,7 +15,7 @@
 	bind:ref
 	align="start"
 	class={cn(
-		'z-50 w-max min-w-(--bits-combobox-anchor-width) overflow-hidden rounded-control bg-elevated p-menu shadow-lg glass-blur data-[side=bottom]:rounded-t-none data-[side=top]:rounded-b-none',
+		'z-overlay w-max min-w-(--bits-combobox-anchor-width) overflow-hidden rounded-control bg-elevated p-menu shadow-lg glass-blur data-[side=bottom]:rounded-t-none data-[side=top]:rounded-b-none',
 		className
 	)}
 	{sideOffset}

package/dist/ui/command-bar/command-bar.svelte

@@ -266,7 +266,7 @@
 			role="listbox"
 			tabindex="-1"
 			aria-label="Commands"
-			class="absolute top-full left-0 z-50 max-h-64 w-full overflow-x-hidden overflow-y-auto bg-elevated shadow-lg glass-blur"
+			class="absolute top-full left-0 z-overlay max-h-64 w-full overflow-x-hidden overflow-y-auto bg-elevated shadow-lg glass-blur"
 			onmousedown={(e) => e.preventDefault()}
 		>
 			{#if !filtered.length}

package/dist/ui/context-menu/context-menu-content.svelte

@@ -21,7 +21,7 @@
 		// 2px frame that stops a full-width highlight from breaking their chrome.
 		// A fixed gutter was tried here and rejected: it padded flat menus too.
 		class={cn(
-			'z-50 w-max overflow-hidden rounded-control bg-elevated p-menu shadow-lg glass-blur',
+			'z-overlay w-max overflow-hidden rounded-control bg-elevated p-menu shadow-lg glass-blur',
 			className
 		)}
 		{sideOffset}

package/dist/ui/context-menu/context-menu-sub-content.svelte

@@ -15,7 +15,7 @@
 	<ContextMenu.SubContent
 		bind:ref
 		class={cn(
-			'z-50 w-max overflow-hidden rounded-control bg-elevated p-menu shadow-lg glass-blur',
+			'z-overlay w-max overflow-hidden rounded-control bg-elevated p-menu shadow-lg glass-blur',
 			className
 		)}
 		{sideOffset}

package/dist/ui/date-picker/date-picker-content.svelte

@@ -14,7 +14,7 @@
 <DatePicker.Content
 	bind:ref
 	align="start"
-	class={cn('z-50 rounded-bar bg-elevated p-content shadow-lg glass-blur', className)}
+	class={cn('z-overlay rounded-bar bg-elevated p-content shadow-lg glass-blur', className)}
 	{sideOffset}
 	{...restProps}
 >

package/dist/ui/date-range-picker/date-range-picker-content.svelte

@@ -14,7 +14,7 @@
 <DateRangePicker.Content
 	bind:ref
 	align="start"
-	class={cn('z-50 rounded-bar bg-elevated p-content shadow-lg glass-blur', className)}
+	class={cn('z-overlay rounded-bar bg-elevated p-content shadow-lg glass-blur', className)}
 	{sideOffset}
 	{...restProps}
 >

package/dist/ui/dialog/dialog-content.svelte

@@ -30,7 +30,7 @@
 	<Dialog.Content
 		bind:ref
 		class={cn(
-			'fixed top-1/2 left-1/2 z-50 flex w-full max-w-md -translate-x-1/2 -translate-y-1/2 flex-col border border-divider bg-well shadow-lg glass-blur',
+			'fixed top-1/2 left-1/2 z-overlay flex w-full max-w-md -translate-x-1/2 -translate-y-1/2 flex-col border border-divider bg-well shadow-lg glass-blur',
 			header ? 'rounded-control' : 'gap-gutter rounded-bar p-card',
 			className
 		)}