@poodle64/ui 2026.8.7

package/dist/components/ui/app-shell/app-shell.svelte.d.ts

@@ -0,0 +1,157 @@
+/**
+     * The application shell: navigation, top bar and page frame, once.
+     *
+     * Primitives and page chrome are not what makes an app feel like an app — the
+     * shell is. Five household frontends were surveyed before this API was
+     * settled, and between them they had built five shells: a rail-plus-drawer,
+     * an eleven-file collapsible sidebar tree under its own top bar, and three
+     * header-only bars that each solved the mobile question differently. They
+     * agreed on almost nothing structurally while looking like they were trying
+     * to be the same thing.
+     *
+     * There is now exactly one composition, no variant prop to choose it: a
+     * permanent side rail on md+ (an overlay drawer below it) carrying primary
+     * navigation and a brand row that also carries the collapse toggle, PLUS a
+     * real top navbar (search, leading/trailing slots, theme toggle, identity) —
+     * always both together. Operator ruling, 31/07/2026: every household app
+     * renders one shell shape; apps do not choose variants.
+     *
+     * The collapse toggle sits at the rail's own top edge, on the brand row,
+     * where every comparable shell puts a control that acts on the rail — icon
+     * only, right of the wordmark, stacking under the mark when the rail is
+     * collapsed. The foot is left to the app.
+     *
+     * Search can sit in either of two places, because it reads as a different
+     * thing depending on what is beside it. `searchPlacement` defaults to
+     * `leading` — its historical spot just after the `context` slot, so a shell
+     * that never names the prop is unchanged — and `trailing` moves it into the
+     * right-hand group with the theme toggle and identity, so that when `context`
+     * carries route content the global affordance reads as global rather than as
+     * part of the switcher next to it.
+     *
+     * Content WIDTH is the one dimension that came back, as `measure`, and it
+     * came back on a measurement rather than on taste. "Always full-width" did
+     * not remove the decision, it pushed it down into every page: a consumer was
+     * surveyed at 2560px and had six distinct caps across nine routes, every one
+     * of them a hand-written `mx-auto max-w-*` at the top of a `+page.svelte`,
+     * between them using 15% to 79% of the width actually available. That is
+     * fifteen independent guesses, not a shell shape.
+     *
+     * `measure` is a small named scale, chosen once in the layout, and it is not
+     * the old `content` prop returning. It defaults to `full`, so a shell that
+     * never mentions it renders byte-identically; its tiers are CSS custom
+     * properties an app retunes without a release; and it exists to REPLACE
+     * per-page width decisions rather than to offer an app a look.
+     *
+     * Content TEXTURE came back the same way, on the same kind of evidence. Two
+     * apps had separately built one picture — a faint dot-grid floor with a soft
+     * accent vignette — under two names in two app.css files, and one of them
+     * applied it as a helper class per route, so it reached four routes out of
+     * about fifteen. Which pages wore the house atmosphere was decided by which
+     * pages someone had happened to touch. `texture` is one named picture the
+     * SHELL paints once, off by default, its inks tuned by custom properties.
+     *
+     * Everything else the surveyed apps differed on turned out to be a slot, not
+     * a variant: the brand, the identity surface, a context switcher, a banner, a
+     * secondary column. Those are snippets, so this package imports no app store,
+     * no app route and no app brand — the coupling that made the best shell in
+     * the estate unliftable in the first place.
+     *
+     * The minimum useful call is two props:
+     *
+     *     <AppShell nav={navGroups} brandTitle="Console" currentPath={page.url.pathname}>
+     *       {@render children()}
+     *     </AppShell>
+     */
+import type { Snippet } from 'svelte';
+import type { ShellMeasure } from './measure.js';
+import type { ShellTexture } from './texture.js';
+import { type NavSource } from './types.js';
+type $$ComponentProps = {
+    /** Navigation: bare items, groups, or a mix. Filter for permissions first. */
+    nav?: NavSource;
+    /** The primary nav landmark's accessible name — forwarded to the rail/drawer
+        AppNav. Distinguish it from a second shell on the same page, or from a
+        route-scoped secondary AppNav. */
+    navLabel?: string;
+    /**
+     * The current path, for active state and for closing the mobile nav on
+     * navigation. Apps pass `page.url.pathname`.
+     *
+     * It is a prop rather than a `$app/state` import on purpose: this package
+     * is built with svelte-package and has no SvelteKit runtime of its own, so
+     * importing `$app/state` would make SvelteKit a hard peer AND make the
+     * shell untestable outside a running app. One line at the call site buys
+     * a component that is framework-agnostic and genuinely drivable.
+     */
+    currentPath?: string;
+    /** Offer an icon-only collapse toggle at the rail head, on the brand row. */
+    collapsible?: boolean;
+    /** Rail collapse state. Bind it to persist the choice across sessions. */
+    collapsed?: boolean;
+    /** Full control of the brand lockup. Overrides brandTitle/brandMark. */
+    brand?: Snippet;
+    /** Wordmark text, rendered in the display face. */
+    brandTitle?: string;
+    /** The mark beside the wordmark — an app's own logo component. */
+    brandMark?: Snippet;
+    /** Where the brand links. */
+    homeHref?: string;
+    /** Full-width region directly under the top bar: reconnect notices, trials. */
+    banner?: Snippet;
+    /** Leading top-bar slot, before the search affordance: a context switcher. */
+    context?: Snippet;
+    /** Trailing top-bar slot, before the theme toggle: app-level action buttons. */
+    actions?: Snippet;
+    /** The signed-in user surface. Rendered once, at the end of the top bar. */
+    identity?: Snippet;
+    /** A secondary, route-scoped column between the nav and the page body. */
+    sidebar?: Snippet;
+    /** Provide to render the search affordance. Usually opens a CommandPalette. */
+    onSearch?: () => void;
+    searchLabel?: string;
+    /** The shortcut hint rendered in the search affordance; '' hides the kbd. */
+    searchShortcut?: string;
+    /**
+     * Where the search affordance sits in the top bar. `leading` (default)
+     * keeps its historical position just after the `context` slot; `trailing`
+     * moves it into the right-hand group with the theme toggle and identity —
+     * for when `context` carries route content and search should read as a
+     * global control rather than as part of it.
+     */
+    searchPlacement?: 'leading' | 'trailing';
+    themeToggle?: boolean;
+    /** Override the theme action. Defaults to mode-watcher's toggleMode. */
+    onToggleTheme?: () => void;
+    padded?: boolean;
+    /**
+     * How wide the page body may get, from a named scale: `prose` (72ch, for
+     * long-form running text), `page` (80rem — forms, detail views,
+     * settings), `wide` (120rem — indexes, grids, tables, dashboards), or
+     * `full` (no cap).
+     *
+     * Defaults to `full`, so a shell that does not mention it is unchanged.
+     * Set it in the layout, once: the point is that pages stop each deciding
+     * their own width. The cap is the content box's border box, so `padded`
+     * spends its padding inside the measure.
+     */
+    measure?: ShellMeasure;
+    /**
+     * The house atmosphere on the content region: `grid` (a dot-grid floor
+     * plus a corner vignette) or `none`.
+     *
+     * Defaults to `none`, so a shell that does not mention it is unchanged.
+     * Set it in the layout, once — that the SHELL paints it is the whole
+     * point, because a helper class apps apply per route is how one consumer
+     * ended up wearing the house texture on four routes out of fifteen. The
+     * inks and the pitch are `--ds-shell-texture-*` custom properties an app
+     * retunes in one declaration.
+     */
+    texture?: ShellTexture;
+    /** Extra classes on the scrolling content container. */
+    mainClass?: string;
+    children: Snippet;
+};
+declare const AppShell: import("svelte").Component<$$ComponentProps, {}, "collapsed">;
+type AppShell = ReturnType<typeof AppShell>;
+export default AppShell;

package/dist/components/ui/app-shell/index.d.ts

@@ -0,0 +1,6 @@
+export { default as AppShell } from './app-shell.svelte';
+export { default as AppNav } from './app-nav.svelte';
+export { default } from './app-shell.svelte';
+export { SHELL_MEASURES, type ShellMeasure } from './measure.js';
+export { SHELL_TEXTURES, type ShellTexture } from './texture.js';
+export { hasActiveNavChild, isNavGroup, isNavItemActive, navChildren, toGroups, toItems, type IconComponent, type NavChildItem, type NavEntry, type NavGroup, type NavItem, type NavSource } from './types.js';

package/dist/components/ui/app-shell/index.js

@@ -0,0 +1,6 @@
+export { default as AppShell } from './app-shell.svelte';
+export { default as AppNav } from './app-nav.svelte';
+export { default } from './app-shell.svelte';
+export { SHELL_MEASURES } from './measure.js';
+export { SHELL_TEXTURES } from './texture.js';
+export { hasActiveNavChild, isNavGroup, isNavItemActive, navChildren, toGroups, toItems } from './types.js';

package/dist/components/ui/app-shell/measure.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The content measure: how wide the page body is allowed to get.
+ *
+ * A named scale rather than a width, because a width at the call site is the
+ * problem this exists to solve. Surveyed at 2560px, one consumer had six
+ * distinct caps across nine routes — `max-w-4xl` here, `max-w-[1600px]` there,
+ * a `max-w-md` form somewhere else — each written by whoever built that page,
+ * none of them wrong on its own, and no two agreeing. Between them they used
+ * 15% to 79% of the width available. A scale with four names cannot drift like
+ * that: it is one decision, taken once, in the layout.
+ *
+ * The tiers resolve through `--ds-shell-measure-*` custom properties (see
+ * `styles.css`), so an app retunes any of them in one declaration.
+ */
+/**
+ * - `prose` — a genuine reading measure (`72ch`) for long-form running text.
+ * - `page` — everyday pages: forms, detail views, settings (`80rem`).
+ * - `wide` — indexes, card grids, tables, dashboards (`120rem`).
+ * - `full` — no cap. The default, so omitting `measure` changes nothing.
+ *
+ * The 80rem tier is `page` rather than `default` on purpose. The prop's default
+ * is `full`, and a value literally named `default` that you do NOT get by
+ * default is a trap a reader falls into once each. It is also not `standard`,
+ * which this package already retired for being a name that says nothing.
+ */
+export type ShellMeasure = 'prose' | 'page' | 'wide' | 'full';
+/** Every measure, narrowest first — the order the scale is documented in. */
+export declare const SHELL_MEASURES: readonly ["prose", "page", "wide", "full"];

package/dist/components/ui/app-shell/measure.js

@@ -0,0 +1,21 @@
+/**
+ * The content measure: how wide the page body is allowed to get.
+ *
+ * A named scale rather than a width, because a width at the call site is the
+ * problem this exists to solve. Surveyed at 2560px, one consumer had six
+ * distinct caps across nine routes — `max-w-4xl` here, `max-w-[1600px]` there,
+ * a `max-w-md` form somewhere else — each written by whoever built that page,
+ * none of them wrong on its own, and no two agreeing. Between them they used
+ * 15% to 79% of the width available. A scale with four names cannot drift like
+ * that: it is one decision, taken once, in the layout.
+ *
+ * The tiers resolve through `--ds-shell-measure-*` custom properties (see
+ * `styles.css`), so an app retunes any of them in one declaration.
+ */
+/** Every measure, narrowest first — the order the scale is documented in. */
+export const SHELL_MEASURES = [
+    'prose',
+    'page',
+    'wide',
+    'full'
+];

package/dist/components/ui/app-shell/texture.d.ts

@@ -0,0 +1,32 @@
+/**
+ * The content texture: the house "atmosphere" the shell paints on its own
+ * scrolling content region.
+ *
+ * Two apps had independently built the same thing — a faint dot-grid floor with
+ * a soft accent vignette in one corner — under two names, in two app.css files,
+ * with two sets of local variables. Neither was wrong; between them they are
+ * exactly the drift this package exists to end. Worse, one of them applied it as
+ * a helper class per route: four routes out of about fifteen carried it, so
+ * whether a page wore the house atmosphere came down to which page someone had
+ * happened to touch. A texture an app has to REMEMBER to apply is not a texture,
+ * it is a coin toss with a stylesheet.
+ *
+ * So it moves onto the shell, where there is exactly one place to say it and no
+ * per-route decision left to get wrong. `none` is the default, so a shell that
+ * never mentions it renders byte-identically.
+ *
+ * It is one texture, not a menu. Both apps wanted the same picture, and the
+ * axes they actually differed on — how dark the dots are, how the vignette is
+ * tinted, how far apart the dots sit — are values, not designs. They are
+ * `--ds-shell-texture-*` custom properties an app retunes in one declaration
+ * (see `styles.css`), which is also how a "plain wash" is reached without a
+ * second name in this union: set the grid ink to `transparent` and the vignette
+ * remains.
+ */
+/**
+ * - `grid` — the house atmosphere: a dot-grid floor plus a corner vignette.
+ * - `none` — no texture. The default, so omitting `texture` changes nothing.
+ */
+export type ShellTexture = 'none' | 'grid';
+/** Every texture, the untextured default first — the order it is documented in. */
+export declare const SHELL_TEXTURES: readonly ["none", "grid"];

package/dist/components/ui/app-shell/texture.js

@@ -0,0 +1,27 @@
+/**
+ * The content texture: the house "atmosphere" the shell paints on its own
+ * scrolling content region.
+ *
+ * Two apps had independently built the same thing — a faint dot-grid floor with
+ * a soft accent vignette in one corner — under two names, in two app.css files,
+ * with two sets of local variables. Neither was wrong; between them they are
+ * exactly the drift this package exists to end. Worse, one of them applied it as
+ * a helper class per route: four routes out of about fifteen carried it, so
+ * whether a page wore the house atmosphere came down to which page someone had
+ * happened to touch. A texture an app has to REMEMBER to apply is not a texture,
+ * it is a coin toss with a stylesheet.
+ *
+ * So it moves onto the shell, where there is exactly one place to say it and no
+ * per-route decision left to get wrong. `none` is the default, so a shell that
+ * never mentions it renders byte-identically.
+ *
+ * It is one texture, not a menu. Both apps wanted the same picture, and the
+ * axes they actually differed on — how dark the dots are, how the vignette is
+ * tinted, how far apart the dots sit — are values, not designs. They are
+ * `--ds-shell-texture-*` custom properties an app retunes in one declaration
+ * (see `styles.css`), which is also how a "plain wash" is reached without a
+ * second name in this union: set the grid ink to `transparent` and the vignette
+ * remains.
+ */
+/** Every texture, the untextured default first — the order it is documented in. */
+export const SHELL_TEXTURES = ['none', 'grid'];

package/dist/components/ui/app-shell/types.d.ts

@@ -0,0 +1,134 @@
+/**
+ * The navigation vocabulary every app types its own config against.
+ *
+ * Five apps in the estate were surveyed before this shape was settled, and each
+ * had reinvented the same three fields under different names (`label`/`title`,
+ * `href`/`path`) plus one or two extras nobody else had. The intersection —
+ * label, href, icon — is what every one of them actually needed; `badge`,
+ * `exact` and `external` are the union of the genuine extras, each optional so
+ * the common case stays two fields.
+ *
+ * Deliberately ABSENT: any notion of who may see an item. Two apps gate nav on
+ * `is_admin` / per-module permission, and both do it with their own auth store.
+ * A shared package that knew about permissions would have to know about auth,
+ * which is exactly the coupling that made the reference shell unliftable. Apps
+ * filter before they pass:
+ *
+ *     const nav = $derived(allNav.filter((i) => !i.adminOnly || user.isAdmin));
+ */
+import type { Component } from 'svelte';
+/** A Lucide (or equivalent) icon component: takes a class, renders an SVG. */
+export type IconComponent = Component<{
+    class?: string;
+}>;
+/** One navigable destination. */
+export interface NavItem {
+    /** The visible text. Also the accessible name when the rail is collapsed. */
+    label: string;
+    /** Destination path. */
+    href: string;
+    /** Optional leading icon. Omit it for a label-only row; alignment is kept. */
+    icon?: IconComponent;
+    /** Optional trailing count or short tag (an unread count, a "beta" tag). */
+    badge?: string | number;
+    /**
+     * Match the current path exactly rather than by prefix. Prefix is the
+     * default because a section root should stay lit while you are inside it;
+     * `href: '/'` is always treated as exact, since every path is prefixed by it.
+     */
+    exact?: boolean;
+    /** Open in a new tab. Renders the standard rel and an off-site affordance. */
+    external?: boolean;
+    /**
+     * Additional path prefixes this item also owns, beyond its own `href`.
+     *
+     * Flat navigation has every section's children living under the section's
+     * own path, which `href`'s prefix match already covers. It breaks for a
+     * section whose children live under a different top-level route — a
+     * "browse" list whose detail pages sit at their own short URL rather than
+     * nested under the list. Each prefix here is matched exactly like `href`
+     * is (prefix, with the same path-segment boundary), independently of
+     * `exact` and independently of `href` being forced to exact at `/`: a root
+     * item can still claim an additional prefix by full path match.
+     */
+    matchPrefixes?: string[];
+    /**
+     * A section's own sub-navigation, disclosed in place beneath it.
+     *
+     * Without this, an app whose sections have their own inner navigation has
+     * nowhere to put it inside the rail. The observed workaround was modules in
+     * `nav` and the current module's pages in the `sidebar` snippet — two
+     * left-hand columns on a desktop, and, the reason this shape won over moving
+     * modules to a top bar, two surfaces on a phone that both want the same
+     * hamburger. One nested tree collapses to one drawer.
+     *
+     * Named `children`, not `items`, for a mechanical reason as well as a
+     * readable one: `isNavGroup` narrows on `'items' in entry`, so an item
+     * carrying `items` would be misread as a GROUP by every consumer of this
+     * vocabulary, this package's own renderer included.
+     *
+     * ONE level, and the type is what enforces it: a child is `NavItem` minus
+     * this field, so a second nesting is a compile error where the nav is
+     * authored rather than a rail nobody can read. The cap is deliberate. The
+     * rail is 15.5rem and every level costs an indent; by depth three the label
+     * has less room than the chevron beside it. Every household case is one
+     * level, and a genuinely deeper tree belongs in the page body, which has the
+     * width for it.
+     */
+    children?: readonly NavChildItem[];
+}
+/**
+ * A row inside a parent's disclosure: everything an item is, minus the ability
+ * to nest again.
+ */
+export type NavChildItem = Omit<NavItem, 'children'>;
+/** A titled run of items. The heading is optional — a leading group usually has none. */
+export interface NavGroup {
+    heading?: string;
+    items: NavItem[];
+}
+/**
+ * What the `nav` prop accepts: bare items, groups, or a mix.
+ *
+ * Three of the five surveyed apps have flat navigation and two have groups, so
+ * requiring one shape would have made three apps write `[{ items: [...] }]`
+ * wrapper noise or two apps flatten away their headings. A mixed array costs one
+ * type guard here and nothing at the call site.
+ */
+export type NavEntry = NavItem | NavGroup;
+export type NavSource = readonly NavEntry[];
+/** Narrow a mixed entry to a group. */
+export declare function isNavGroup(entry: NavEntry): entry is NavGroup;
+/** Normalise any accepted shape to groups, dropping groups that would render empty. */
+export declare function toGroups(nav: NavSource | undefined): NavGroup[];
+/** An item's disclosed rows, normalised — an empty list where there are none. */
+export declare function navChildren(item: NavItem): readonly NavChildItem[];
+/**
+ * Every item in source order, ignoring grouping — a parent immediately followed
+ * by its own children. Used by the command palette.
+ *
+ * Children are included because they are destinations like any other, and the
+ * palette is the fastest route to a page three levels into a section. An item
+ * with no children flattens exactly as it always did.
+ */
+export declare function toItems(nav: NavSource | undefined): NavItem[];
+/**
+ * Whether `item` is the current page.
+ *
+ * Prefix matching is what makes a section root stay lit on its children; the
+ * `+ '/'` is what stops `/audit` lighting up on `/audit-log`. A root href is
+ * forced to exact or it would match every path in the app — but that forcing
+ * applies only to `href` itself; `matchPrefixes` is always prefix-matched, so
+ * a root item can still claim a second, unrelated section by full path.
+ */
+export declare function isNavItemActive(item: NavItem, currentPath: string | undefined): boolean;
+/**
+ * Whether one of `item`'s disclosed children is the current page.
+ *
+ * Two things read this. It is what auto-opens the group you have navigated
+ * into — a rail that will not show you where you are is the defect this whole
+ * feature exists to avoid. And it marks a parent whose section you are inside
+ * but whose own `href` does not match, which flat prefix matching cannot see
+ * when the children live at their own top-level routes.
+ */
+export declare function hasActiveNavChild(item: NavItem, currentPath: string | undefined): boolean;

package/dist/components/ui/app-shell/types.js

@@ -0,0 +1,88 @@
+/** Narrow a mixed entry to a group. */
+export function isNavGroup(entry) {
+    return 'items' in entry && Array.isArray(entry.items);
+}
+/** Normalise any accepted shape to groups, dropping groups that would render empty. */
+export function toGroups(nav) {
+    if (!nav)
+        return [];
+    const groups = [];
+    // Consecutive bare items collapse into one unheaded run, so a flat array
+    // renders as a single group rather than one group per item (which would
+    // space every link apart). A group entry closes the run.
+    let run = null;
+    for (const entry of nav) {
+        if (isNavGroup(entry)) {
+            run = null;
+            if (entry.items.length > 0)
+                groups.push(entry);
+        }
+        else {
+            if (!run) {
+                run = { items: [] };
+                groups.push(run);
+            }
+            run.items.push(entry);
+        }
+    }
+    return groups;
+}
+/** No allocation per call for the overwhelmingly common childless item. */
+const NO_CHILDREN = [];
+/** An item's disclosed rows, normalised — an empty list where there are none. */
+export function navChildren(item) {
+    return item.children ?? NO_CHILDREN;
+}
+/**
+ * Every item in source order, ignoring grouping — a parent immediately followed
+ * by its own children. Used by the command palette.
+ *
+ * Children are included because they are destinations like any other, and the
+ * palette is the fastest route to a page three levels into a section. An item
+ * with no children flattens exactly as it always did.
+ */
+export function toItems(nav) {
+    if (!nav)
+        return [];
+    return nav.flatMap((entry) => {
+        const items = isNavGroup(entry) ? entry.items : [entry];
+        return items.flatMap((item) => [item, ...navChildren(item)]);
+    });
+}
+/** Prefix-match `path` against `prefix`, without running past a path segment. */
+function matchesPrefix(path, prefix) {
+    return path === prefix || path.startsWith(prefix + '/');
+}
+/**
+ * Whether `item` is the current page.
+ *
+ * Prefix matching is what makes a section root stay lit on its children; the
+ * `+ '/'` is what stops `/audit` lighting up on `/audit-log`. A root href is
+ * forced to exact or it would match every path in the app — but that forcing
+ * applies only to `href` itself; `matchPrefixes` is always prefix-matched, so
+ * a root item can still claim a second, unrelated section by full path.
+ */
+export function isNavItemActive(item, currentPath) {
+    if (!currentPath)
+        return false;
+    const ownMatch = item.exact || item.href === '/'
+        ? currentPath === item.href
+        : matchesPrefix(currentPath, item.href);
+    if (ownMatch)
+        return true;
+    return (item.matchPrefixes ?? []).some((prefix) => matchesPrefix(currentPath, prefix));
+}
+/**
+ * Whether one of `item`'s disclosed children is the current page.
+ *
+ * Two things read this. It is what auto-opens the group you have navigated
+ * into — a rail that will not show you where you are is the defect this whole
+ * feature exists to avoid. And it marks a parent whose section you are inside
+ * but whose own `href` does not match, which flat prefix matching cannot see
+ * when the children live at their own top-level routes.
+ */
+export function hasActiveNavChild(item, currentPath) {
+    if (!currentPath)
+        return false;
+    return navChildren(item).some((child) => isNavItemActive(child, currentPath));
+}

package/dist/components/ui/arc-gauge/arc-gauge.svelte

@@ -0,0 +1,112 @@
+<script lang="ts" module>
+	import type { Status } from '../status/index.js';
+
+	// The gauge's tone is a health read, not the full five-state vocabulary —
+	// info/neutral have no caller today, so the type stays a named subset
+	// rather than widening to all of Status speculatively.
+	export type GaugeTone = Extract<Status, 'success' | 'warning' | 'error'>;
+</script>
+
+<script lang="ts">
+	import type { SVGAttributes } from 'svelte/elements';
+	import { cn } from '../../../utils.js';
+
+	// Radial capacity/percentage gauge: a compact SVG ring for a single 0–100
+	// metric where a StatCard's full metric tile would be too heavy — a
+	// token-burn dial, a rate-limit-window ring. `size` is both the viewBox
+	// unit and the gauge's physical footprint, so a consumer picks its
+	// on-screen size directly (36 for a small inline dial, 42 for a
+	// standalone one) rather than trusting ambient sizing.
+	let {
+		pct = 0,
+		tone = 'success',
+		size = 42,
+		showLabel = false,
+		label = '',
+		ref = $bindable(null),
+		class: className,
+		...restProps
+	}: Omit<SVGAttributes<SVGSVGElement>, 'class'> & {
+		pct?: number;
+		tone?: GaugeTone;
+		size?: number;
+		showLabel?: boolean;
+		label?: string;
+		ref?: SVGSVGElement | null;
+		class?: string;
+	} = $props();
+
+	const clampedPct = $derived(Math.max(0, Math.min(100, pct)));
+
+	const toneVar: Record<GaugeTone, string> = {
+		success: 'var(--ds-color-status-success)',
+		warning: 'var(--ds-color-status-warning)',
+		error: 'var(--ds-color-status-error)'
+	};
+
+	const cx = $derived(size / 2);
+	const cy = $derived(size / 2);
+	const r = $derived(size / 2 - 4);
+	const circumference = $derived(2 * Math.PI * r);
+	const offset = $derived(circumference * (1 - clampedPct / 100));
+	const color = $derived(toneVar[tone] ?? toneVar.success);
+	const big = $derived(size >= 40);
+	const strokeWidth = 4;
+</script>
+
+<svg
+	bind:this={ref}
+	viewBox="0 0 {size} {size}"
+	width={size}
+	height={size}
+	aria-label="{clampedPct}% used"
+	class={cn(className)}
+	{...restProps}
+>
+	<circle cx={cx} cy={cy} r={r} fill="none" stroke="var(--ds-color-surface-3)" stroke-width={strokeWidth} />
+	<circle
+		cx={cx}
+		cy={cy}
+		r={r}
+		fill="none"
+		stroke={color}
+		stroke-width={strokeWidth}
+		stroke-linecap="round"
+		stroke-dasharray={circumference}
+		stroke-dashoffset={offset}
+		transform="rotate(-90 {cx} {cy})"
+	/>
+	{#if big && showLabel}
+		<!--
+			The percentage and unit-label glyphs below are graphic annotations
+			scaled by the viewBox, not CSS/DOM running text — the household's
+			~0.75rem type floor governs body copy, not a numeral drawn inside a
+			purpose-built, self-contained radial gauge. Growing them to clear
+			that floor would blow out the ring's established compact geometry
+			(a 36–42 SVG-unit footprint), so they stay at their literal 10 and
+			5.4 user-unit sizes deliberately (design-system#15).
+		-->
+		<text
+			x={cx}
+			y={cy - 0.5}
+			text-anchor="middle"
+			dominant-baseline="central"
+			font-family="var(--ds-font-code)"
+			font-size="10"
+			font-weight="600"
+			fill="var(--ds-color-foreground)"
+		>{clampedPct}%</text>
+		{#if label}
+			<text
+				x={cx}
+				y={cy + 7.5}
+				text-anchor="middle"
+				dominant-baseline="central"
+				font-family="var(--ds-font-body)"
+				font-size="5.4"
+				fill="var(--ds-color-muted-foreground)"
+				letter-spacing="0.5"
+			>{label.toUpperCase()}</text>
+		{/if}
+	{/if}
+</svg>

package/dist/components/ui/arc-gauge/arc-gauge.svelte.d.ts

@@ -0,0 +1,15 @@
+import type { Status } from '../status/index.js';
+export type GaugeTone = Extract<Status, 'success' | 'warning' | 'error'>;
+import type { SVGAttributes } from 'svelte/elements';
+type $$ComponentProps = Omit<SVGAttributes<SVGSVGElement>, 'class'> & {
+    pct?: number;
+    tone?: GaugeTone;
+    size?: number;
+    showLabel?: boolean;
+    label?: string;
+    ref?: SVGSVGElement | null;
+    class?: string;
+};
+declare const ArcGauge: import("svelte").Component<$$ComponentProps, {}, "ref">;
+type ArcGauge = ReturnType<typeof ArcGauge>;
+export default ArcGauge;

package/dist/components/ui/arc-gauge/index.d.ts

@@ -0,0 +1,3 @@
+export { default as ArcGauge } from './arc-gauge.svelte';
+export { default } from './arc-gauge.svelte';
+export type { GaugeTone } from './arc-gauge.svelte';

package/dist/components/ui/arc-gauge/index.js

@@ -0,0 +1,2 @@
+export { default as ArcGauge } from './arc-gauge.svelte';
+export { default } from './arc-gauge.svelte';