@lyeve-labs/ui-kit 0.17.1 → 0.19.0

package/dist/components/dialog/dialog-manager.svelte.d.ts

@@ -40,13 +40,32 @@ export declare function dismissDialog(id?: string): void;
  * Close all open dialogs, rejecting their promises.
  */
 export declare function dismissAllDialogs(): void;
+/** The labels a caller may override on a confirm dialog. */
+export interface ConfirmOptions {
+    /**
+     * The verb on the accepting button. Defaults to `Confirm`.
+     *
+     * Name the action rather than accepting the default wherever the caller has
+     * a verb of its own: a button reading `Delete` says what happens, and one
+     * reading `Confirm` only says that something does. ConfirmDialog has always
+     * read this, but until it was reachable from here a caller had to drop to
+     * openDialog and setDialogMeta to reach it, so every call site took the
+     * generic label instead.
+     */
+    confirmLabel?: string;
+    /** The verb on the dismissing button. Defaults to `Cancel`. */
+    cancelLabel?: string;
+}
 /**
  * Convenience: confirm dialog.
  * Returns `true` if user confirmed, `false` if cancelled.
  *
  *   const ok = await confirm('Delete item?', 'This cannot be undone.');
+ *   const ok = await confirm('Delete item?', 'This cannot be undone.', {
+ *     confirmLabel: 'Delete',
+ *   });
  */
-export declare function confirm(title: string, message?: string): Promise<boolean>;
+export declare function confirm(title: string, message?: string, options?: ConfirmOptions): Promise<boolean>;
 /**
  * Set metadata on a dialog entry after it's opened.
  * Used by convenience wrappers to pass extra data without polluting DialogOptions.

package/dist/components/dialog/dialog-manager.svelte.js

@@ -136,11 +136,22 @@ export function dismissAllDialogs() {
  * Returns `true` if user confirmed, `false` if cancelled.
  *
  *   const ok = await confirm('Delete item?', 'This cannot be undone.');
+ *   const ok = await confirm('Delete item?', 'This cannot be undone.', {
+ *     confirmLabel: 'Delete',
+ *   });
  */
-export function confirm(title, message) {
+export function confirm(title, message, options) {
     const id = `confirm-${++idCounter}`;
     const promise = openDialog({ id, size: 'sm', title });
-    setDialogMeta(id, { confirmTitle: title, confirmMessage: message ?? '' });
+    setDialogMeta(id, {
+        confirmTitle: title,
+        confirmMessage: message ?? '',
+        // Undefined keys are dropped rather than written, because ConfirmDialog
+        // decides its default by type-checking the meta value: writing undefined
+        // would be indistinguishable from an override to the empty case.
+        ...(options?.confirmLabel !== undefined ? { confirmLabel: options.confirmLabel } : {}),
+        ...(options?.cancelLabel !== undefined ? { cancelLabel: options.cancelLabel } : {}),
+    });
     // Cancelling a dialog dismisses it, and dismissal rejects. Callers write
     // `if (await confirm(...))`, so a rejection on Cancel is an unhandled
     // rejection on the ordinary path rather than an error anyone meant to

package/dist/index.d.ts

@@ -20,6 +20,7 @@ export { default as Table } from './components/Table.svelte';
 export { default as DescriptionList } from './components/DescriptionList.svelte';
 export { default as Toolbar } from './components/Toolbar.svelte';
 export { default as TreeView } from './components/TreeView.svelte';
+export type { CellFit } from './components/Table.svelte';
 export type { PageWidth, SectionVariant } from './internal/layout.js';
 export type { TreeNode, TriState } from './internal/tree.js';
 export { default as Button } from './components/Button.svelte';
@@ -75,6 +76,7 @@ export { default as Kbd } from './components/Kbd.svelte';
 export { default as CopyButton } from './components/CopyButton.svelte';
 export { default as Avatar } from './components/Avatar.svelte';
 export { default as AvatarGroup } from './components/AvatarGroup.svelte';
+export { default as Logo } from './components/Logo.svelte';
 export { default as ThemeToggle } from './components/ThemeToggle.svelte';
 export { default as Toaster } from './components/Toaster.svelte';
 export { toast } from './stores/toast.svelte.js';
@@ -83,7 +85,8 @@ export { default as DialogContainer } from './components/dialog/DialogContainer.
 export { default as Dialog } from './components/dialog/Dialog.svelte';
 export { default as ConfirmDialog } from './components/dialog/ConfirmDialog.svelte';
 export { openDialog, closeDialog, dismissDialog, dismissAllDialogs, confirm, setDialogMeta, getDialogStack, } from './components/dialog/dialog-manager.svelte.js';
+export type { ConfirmOptions } from './components/dialog/dialog-manager.svelte.js';
 export type { DialogOptions, DialogEntry, DialogSize } from './components/dialog/types.js';
 export { cn, type ClassValue } from './utils/cn.js';
-export { getTheme, setTheme, toggleTheme, themeBootScript, type Theme } from './utils/theme.js';
-export declare const VERSION = "0.17.1";
+export { getTheme, getThemePreference, nextThemePreference, resolveTheme, setTheme, setThemePreference, systemTheme, themeBootScript, toggleTheme, watchSystemTheme, THEME_PREFERENCES, type Theme, type ThemePreference, } from './utils/theme.js';
+export declare const VERSION = "0.19.0";

package/dist/index.js

@@ -76,6 +76,10 @@ export { default as CopyButton } from './components/CopyButton.svelte';
 // ── Media ──────────────────────────────────────────────────────────────────
 export { default as Avatar } from './components/Avatar.svelte';
 export { default as AvatarGroup } from './components/AvatarGroup.svelte';
+// The product mark. Two applications carried their own copy of the same lockup
+// and the two had drifted apart in size, in weight and in how they answered the
+// theme; the kit owns it now.
+export { default as Logo } from './components/Logo.svelte';
 // ── Theming & toasts ───────────────────────────────────────────────────────
 export { default as ThemeToggle } from './components/ThemeToggle.svelte';
 export { default as Toaster } from './components/Toaster.svelte';
@@ -88,8 +92,8 @@ export { default as ConfirmDialog } from './components/dialog/ConfirmDialog.svel
 export { openDialog, closeDialog, dismissDialog, dismissAllDialogs, confirm, setDialogMeta, getDialogStack, } from './components/dialog/dialog-manager.svelte.js';
 // ── Utilities ──────────────────────────────────────────────────────────────
 export { cn } from './utils/cn.js';
-export { getTheme, setTheme, toggleTheme, themeBootScript } from './utils/theme.js';
+export { getTheme, getThemePreference, nextThemePreference, resolveTheme, setTheme, setThemePreference, systemTheme, themeBootScript, toggleTheme, watchSystemTheme, THEME_PREFERENCES, } from './utils/theme.js';
 // ── Version ────────────────────────────────────────────────────────────────
 // Generated from package.json by `pnpm version:sync`. Bump package.json, never
 // this line; the build and the test suite fail when the two disagree.
-export const VERSION = '0.17.1';
+export const VERSION = '0.19.0';

package/dist/internal/href.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The one rule the kit applies to an href it did not write itself.
+ *
+ * A component takes a URL from its caller, and a caller takes it from data, so
+ * `javascript:` and `data:` arrive as markup and leave as a script the page
+ * never wrote. Button carried this rule inline and Pagination now builds hrefs
+ * from a caller supplied function, and a rule kept in two places is a rule that
+ * gets fixed in one of them.
+ *
+ * Not exported from the package entry point - this is an implementation detail.
+ */
+/** The href as given, or nothing when its scheme is one no component will emit. */
+export declare function safeHref(href: string | undefined | null): string | undefined;

package/dist/internal/href.js

@@ -0,0 +1,27 @@
+/**
+ * The one rule the kit applies to an href it did not write itself.
+ *
+ * A component takes a URL from its caller, and a caller takes it from data, so
+ * `javascript:` and `data:` arrive as markup and leave as a script the page
+ * never wrote. Button carried this rule inline and Pagination now builds hrefs
+ * from a caller supplied function, and a rule kept in two places is a rule that
+ * gets fixed in one of them.
+ *
+ * Not exported from the package entry point - this is an implementation detail.
+ */
+/**
+ * The characters a browser drops before it reads the scheme.
+ *
+ * The URL parser trims leading and trailing ASCII whitespace and strips tab,
+ * line feed and carriage return from anywhere in the value, so a tab written
+ * inside the word `javascript` still navigates while an anchored scheme test on
+ * the raw string sees an unknown scheme and allows it through.
+ */
+const IGNORED = /[\u0000-\u0020]/g;
+const DENIED = /^(?:javascript|data|vbscript):/i;
+/** The href as given, or nothing when its scheme is one no component will emit. */
+export function safeHref(href) {
+    if (!href)
+        return undefined;
+    return DENIED.test(href.replace(IGNORED, '')) ? undefined : href;
+}

package/dist/internal/layout.js

@@ -137,10 +137,19 @@ export function sectionHeading(level, variant = 'default') {
     // it rather than a title, so it does not take the level's size at all.
     if (variant === 'eyebrow')
         return 'text-xs font-medium uppercase tracking-wide text-faint';
+    // Level 2 is the brand ramp's H3, which the guideline describes as the card
+    // and group head this is. Its leading and tracking come with it: a --text-*
+    // token sets font-size and nothing else, so the ratio has to be asked for by
+    // name or the heading inherits whatever line-height its parent had.
+    //
     // Level 3 drops a size rather than a weight. Inside a card it sits under the
     // card's own semibold title, and two semibold lines at the same size read as
-    // one heading broken in half.
-    return level === 2 ? 'text-lg font-semibold text-fg' : 'text-sm font-semibold text-fg';
+    // one heading broken in half. It stays at text-sm: the ramp holds nothing
+    // between 16px and 22px, and 16px is exactly the size of the card title it
+    // has to sit below.
+    return level === 2
+        ? 'text-h3 leading-h3 tracking-h3 font-semibold text-fg'
+        : 'text-sm font-semibold text-fg';
 }
 /**
  * The authed app frame, stated once for every app that has one.

package/dist/internal/panel.d.ts

@@ -40,7 +40,7 @@
  * needs a boundary that clears 3:1, which line does not. It carries the
  * resting text colour so a row can override it with a single utility.
  */
-export declare const PANEL_SURFACE = "absolute z-50 mt-1 rounded-xl border border-line-strong bg-surface text-fg shadow-2xl";
+export declare const PANEL_SURFACE = "absolute z-dropdown mt-1 rounded-xl border border-line-strong bg-surface text-fg shadow-2xl";
 /**
  * The scrolling region inside it.
  *

package/dist/internal/panel.js

@@ -40,7 +40,7 @@
  * needs a boundary that clears 3:1, which line does not. It carries the
  * resting text colour so a row can override it with a single utility.
  */
-export const PANEL_SURFACE = 'absolute z-50 mt-1 rounded-xl border border-line-strong bg-surface text-fg shadow-2xl';
+export const PANEL_SURFACE = 'absolute z-dropdown mt-1 rounded-xl border border-line-strong bg-surface text-fg shadow-2xl';
 /**
  * The scrolling region inside it.
  *
@@ -55,7 +55,7 @@ export const PANEL_LIST = 'max-h-panel-max overflow-y-auto overscroll-contain py
  * No background and no text colour of its own: it inherits both from the
  * surface, which leaves each state below a single utility to override.
  */
-export const PANEL_OPTION = 'flex w-full items-center gap-2.5 px-3 py-2 text-left text-sm ' +
+export const PANEL_OPTION = 'flex w-full items-center gap-2.5 px-3 py-2 text-start text-sm ' +
     'transition-colors duration-150 outline-none hover:bg-surface-2 ' +
     'focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-brand';
 /**

package/dist/styles/theme.css

@@ -79,6 +79,61 @@
   --radius-xl: 16px;
   --radius-2xl: 24px;
 
+  /* -- Elevation - the stacking order of everything that floats --- *
+   *  Every floating surface in the kit carried a bare z-50, so which
+   *  one won was decided by document order: a Dropdown opened after a
+   *  Modal painted over it, and the same two in the other order did
+   *  not. The layer a surface belongs to is a property of the surface,
+   *  so it is named here once and each component asks for its layer by
+   *  name.
+   *
+   *  The ramp starts at 100 and leaves everything below it to the
+   *  consuming app. The admin's own chrome sits at z-10 and z-20
+   *  today, and a kit layer landing on either number would tie with
+   *  it and resolve, again, by document order.
+   *
+   *  The steps are 100 apart because one of these layers holds a
+   *  stack rather than a surface: the dialog manager offsets each
+   *  dialog above the one it opened over, and a ramp in steps of ten
+   *  would put the eleventh dialog through the ceiling of its own
+   *  layer and under the tooltip above it.
+   *
+   *  tooltip sits above modal because a tooltip on a control inside a
+   *  dialog is drawn while that dialog is the topmost surface. toast
+   *  sits above tooltip because it reports the outcome of the action
+   *  the tooltip described. skip-link is above everything: it is the
+   *  first focusable thing in the document and nothing may cover it.
+   *
+   *  No sticky rung is declared. Nothing in the kit is sticky or
+   *  fixed below the dropdown layer, and a token no rule reads is the
+   *  defect this scale was written to end.                           */
+  --z-index-dropdown: 100; /* a panel anchored to its trigger    */
+  --z-index-overlay: 200; /* the scrim behind a drawer or modal */
+  --z-index-drawer: 300; /* a panel docked to a viewport edge  */
+  --z-index-modal: 400; /* a centred dialog, and the stack    */
+  --z-index-tooltip: 500; /* a label attached to a control      */
+  --z-index-toast: 600; /* transient status                   */
+  --z-index-skip-link: 700; /* the first tab stop in the document */
+
+  /* -- Motion - how long a transition or an entrance runs -------- *
+   *  Four durations shipped as literals inside the animate-[...]
+   *  utility of the component that used them, so the only way to
+   *  read the kit's motion was to grep four components. They are
+   *  stated here at the values they already ran at.
+   *
+   *  Tailwind builds no utility from a --duration-* token: there is
+   *  no such theme namespace, and `duration-collapse` compiles to
+   *  nothing at all. Each one is read through var() from an
+   *  arbitrary utility instead, which is why they are listed in
+   *  VAR_ONLY in theme-tokens.test.ts.
+   *
+   *  The reduced-motion block at the foot of this file overrides
+   *  every one of them and stays the authority on whether they run. */
+  --duration-modal-in: 120ms; /* Modal, the centred entrance   */
+  --duration-toast-in: 140ms; /* Toaster, one toast arriving   */
+  --duration-drawer-in: 150ms; /* Drawer, either edge           */
+  --duration-collapse: 200ms; /* Accordion and Collapsible     */
+
   /* ── Typography · families ───────────────────────────────────── */
   --font-sans:
     'Inter', ui-sans-serif, system-ui, -apple-system, 'Segoe UI', Roboto, 'Helvetica Neue', Arial,
@@ -96,6 +151,8 @@
    *  Body      16px   1.55   0        400     Default body copy  *
    *  Caption   13px   1.50   0        400     Labels, metadata   *
    *  Mono      18px   1.50   0        500     Code, eyebrows     *
+   *  The ramp the guideline states, for marketing surfaces.      *
+   *  The scale the console renders is declared below it.         *
    *                                                          */
   --text-display: 4rem; /* 64px */
   --text-h1: 2.75rem; /* 44px */
@@ -118,6 +175,57 @@
   --tracking-h2: -0.02em;
   --tracking-h3: -0.015em;
 
+  /* -- Typography - console type scale --------------------------- *
+   *  Token       Size   Line   Where it renders                    *
+   *  text-xs     12px   16px   labels, table heads, metadata, hints*
+   *  text-sm     14px   20px   body copy and every control         *
+   *  text-base   16px   24px   a card title, the large button      *
+   *  text-lg     18px   28px   a dialog title, a small stat value  *
+   *  text-xl     20px   28px   the large wordmark                  *
+   *  text-2xl    24px   32px   a stat value, an empty-state glyph  *
+   *
+   *  Two scales, on purpose, and this is the one the components
+   *  are drawn in.
+   *
+   *  The ramp above is the brand guideline's, and it is a marketing
+   *  ramp: it runs 64 / 44 / 32 / 22 / 16 / 13, holds nothing
+   *  between 16px and 22px, and has no step at 14px at all. A
+   *  console's body copy is 14px and its labels are 12px, both
+   *  below the ramp's floor, so adopting the ramp wholesale would
+   *  have meant restyling every screen to fit a scale drawn for a
+   *  landing page. The ramp keeps its steps for the surfaces it was
+   *  drawn for, and the two overlap at exactly the two steps a
+   *  console does reach: PageHeader takes H2 for the page title and
+   *  SectionHeading takes H3 for a section head.
+   *
+   *  These are Tailwind's own steps at Tailwind's own values,
+   *  stated here rather than inherited silently. Nothing renders
+   *  one pixel differently for it. What changes is that the scale
+   *  the components are built from is now declared beside the one
+   *  they are not, so a designer reading this file sees both, and
+   *  moving console body copy to 15px is one line here instead of
+   *  49 class attributes. Restated rather than renamed: an app
+   *  writing `text-sm` in its own markup and a component writing it
+   *  in the kit's must mean the same size, and a private spelling
+   *  of the same 14px would be a second name for one thing.
+   *
+   *  A step is declared with its leading, because a --text-* token
+   *  sets font-size and nothing else. Only the six steps the kit
+   *  actually renders are declared; the larger ones a marketing
+   *  page reaches for stay as Tailwind ships them.               */
+  --text-xs: 0.75rem; /* 12px */
+  --text-xs--line-height: calc(1 / 0.75); /* 16px */
+  --text-sm: 0.875rem; /* 14px */
+  --text-sm--line-height: calc(1.25 / 0.875); /* 20px */
+  --text-base: 1rem; /* 16px */
+  --text-base--line-height: calc(1.5 / 1); /* 24px */
+  --text-lg: 1.125rem; /* 18px */
+  --text-lg--line-height: calc(1.75 / 1.125); /* 28px */
+  --text-xl: 1.25rem; /* 20px */
+  --text-xl--line-height: calc(1.75 / 1.25); /* 28px */
+  --text-2xl: 1.5rem; /* 24px */
+  --text-2xl--line-height: calc(2 / 1.5); /* 32px */
+
   /* ── Spacing grid · 4px base (semantic shortcuts) ────────────── *
    *  Tailwind's default 0.25rem (4px) grid is unchanged.          *
    *  These tokens add named slots for common component spacing.   */
@@ -181,6 +289,65 @@ html[data-theme='light'] {
   --color-danger: #ab1a1a;
 }
 
+/*
+ * The entrance keyframes, declared here and not in the components that play
+ * them.
+ *
+ * Modal, Drawer and Toaster each held their own `@keyframes` in a scoped
+ * `<style>` block and started it from a Tailwind `animate-[...]` class. Svelte
+ * renames a scoped keyframe to `svelte-<hash>-<name>` and rewrites only the
+ * references inside that same style block, so the class asked the browser for
+ * `modal-in` while the only rule declared was `svelte-ta60gp-modal-in`. An
+ * animation-name that resolves to nothing is not an error: the element simply
+ * appears, and all four entrances had been dead in every consumer.
+ *
+ * A keyframe named from a class has to be global, and the file every consumer
+ * already imports is the one place it can be global from.
+ */
+@keyframes modal-in {
+  from {
+    opacity: 0;
+    transform: translateY(6px) scale(0.98);
+  }
+  to {
+    opacity: 1;
+    transform: translateY(0) scale(1);
+  }
+}
+
+@keyframes drawer-in-right {
+  from {
+    opacity: 0;
+    transform: translateX(16px);
+  }
+  to {
+    opacity: 1;
+    transform: translateX(0);
+  }
+}
+
+@keyframes drawer-in-left {
+  from {
+    opacity: 0;
+    transform: translateX(-16px);
+  }
+  to {
+    opacity: 1;
+    transform: translateX(0);
+  }
+}
+
+@keyframes toast-in {
+  from {
+    opacity: 0;
+    transform: translateX(12px);
+  }
+  to {
+    opacity: 1;
+    transform: translateX(0);
+  }
+}
+
 @layer base {
   html {
     background-color: var(--color-ink);
@@ -238,3 +405,124 @@ html[data-theme='light'] {
     }
   }
 }
+
+/*
+ * Print.
+ *
+ * The estate had no `@media print` rule anywhere, and three surfaces print:
+ * the portal prints an invoice, the ops console prints an audit log, the admin
+ * prints a subject-access export. All three printed the sidebar, the theme
+ * toggle and the nav, in a dark palette, and all three printed one screenful
+ * and stopped, because the shell is `h-screen` with the content column set to
+ * `overflow-auto` and paper has neither a viewport nor a scrollbar.
+ *
+ * These rules are deliberately outside `@layer base`. An unlayered declaration
+ * beats every layered one whatever its specificity, so a `bg-surface` utility
+ * on a card cannot put the dark surface back.
+ *
+ * Three markers, each stating what paper needs rather than what an element is:
+ *
+ *   data-print="hide"    chrome that exists to navigate. Paper cannot be
+ *                        navigated, so it is noise on every page.
+ *   data-print="unclip"  a box that clips on screen because the screen is a
+ *                        fixed height. On paper it must give up its height and
+ *                        its overflow or the content past the first page is
+ *                        never printed.
+ *   data-print="keep"    a block that reads as one thing and must not be split
+ *                        across a page break.
+ */
+@media print {
+  /*
+   * The palette, not the components.
+   *
+   * Every kit component paints from these tokens, so redefining them here
+   * turns the whole library monochrome without a single component knowing
+   * about paper. Browsers drop backgrounds when printing by default, which
+   * left light text on the white the printer supplies; naming white here means
+   * the two agree either way.
+   *
+   * The status hues collapse to black rather than to a print-safe tint. A
+   * colour that carries meaning on screen carries none through a mono printer,
+   * and a legible black label beats an unreadable coloured one.
+   */
+  html,
+  html[data-theme='light'] {
+    --color-ink: #ffffff;
+    --color-surface: #ffffff;
+    --color-surface-2: #ffffff;
+    --color-line: #999999;
+    --color-line-strong: #666666;
+    --color-fg: #000000;
+    --color-muted: #000000;
+    --color-faint: #000000;
+    --color-brand: #000000;
+    --color-brand-light: #000000;
+    --color-brand-deep: #000000;
+    --color-violet: #000000;
+    --color-success: #000000;
+    --color-warn: #000000;
+    --color-danger: #000000;
+    color-scheme: light;
+  }
+
+  html,
+  body {
+    background: #ffffff;
+    color: #000000;
+  }
+
+  [data-print='hide'] {
+    display: none !important;
+  }
+
+  /*
+   * height as well as overflow. The shell is `h-screen`, so releasing the
+   * overflow alone still caps the printed document at one viewport.
+   */
+  [data-print='unclip'] {
+    overflow: visible !important;
+    height: auto !important;
+    max-height: none !important;
+  }
+
+  [data-print='keep'],
+  tr,
+  li {
+    break-inside: avoid;
+  }
+
+  /* A table running past one page repeats its own column headings. */
+  thead {
+    display: table-header-group;
+  }
+
+  tfoot {
+    display: table-footer-group;
+  }
+
+  /*
+   * A heading orphaned at the foot of a page belongs to the section on the
+   * next one.
+   */
+  h1,
+  h2,
+  h3 {
+    break-after: avoid;
+  }
+
+  /*
+   * The target of a link, for the links a reader cannot follow from paper and
+   * could not guess.
+   *
+   * Absolute links only. An invoice full of "(/portal/invoices/8841)" after
+   * every internal link is noise, and the reader holding the paper is already
+   * inside that application. A caller whose absolute link is decorative, or
+   * whose text is the URL already, opts out per link.
+   */
+  a[href^='http']:not([data-print='bare'])::after {
+    content: ' <' attr(href) '>';
+    font-size: 0.85em;
+    font-weight: normal;
+    word-break: break-all;
+  }
+}

package/dist/utils/theme.d.ts

@@ -5,22 +5,87 @@
  * The `<ThemeToggle />` component uses these under the hood; you can also
  * call them directly when you need to set the theme from a layout, route
  * loader, or an inline `<script>` that runs before paint.
+ *
+ * Two vocabularies, and the distinction is the whole point:
+ *
+ *   Theme            what is painted. `dark` or `light`, and it is what
+ *                    `data-theme` holds and what every palette rule keys off.
+ *   ThemePreference  what the reader asked for. `dark`, `light`, or `system`,
+ *                    which is a standing instruction to follow the operating
+ *                    system rather than a colour.
+ *
+ * The kit resolved a preference in exactly one place, the pre-paint script,
+ * and nothing else could read it back. A control could therefore offer two
+ * states and no third, so a reader who wanted the operating system's choice
+ * had to keep re-picking it by hand, and one console forked ThemeToggle rather
+ * than ship that. `system` is now a value the storage key holds and every
+ * helper here understands.
  */
+/** What is painted. */
 export type Theme = 'dark' | 'light';
+/** What the reader asked for. `system` resolves against the OS at read time. */
+export type ThemePreference = Theme | 'system';
+/** The order a control cycles through, and the order a picker lists. */
+export declare const THEME_PREFERENCES: readonly ThemePreference[];
 /**
  * Inline-script payload that should run *before* the first paint to avoid
  * the flash-of-wrong-theme. Drop the returned string into a `<script>` tag
  * in the `<head>` of your app shell.
  *
  * Picks the theme in this order:
- *   1. `localStorage["lyeve-theme"]` if set
- *   2. The user's OS preference (`prefers-color-scheme`)
- *   3. Dark (the default brand palette)
+ *   1. `localStorage["lyeve-theme"]` when it holds `'light'` or `'dark'`
+ *   2. The user's OS preference (`prefers-color-scheme`), which is also what
+ *      the stored value `'system'` asks for
+ *   3. Dark (the default brand palette), including when storage throws
  */
 export declare function themeBootScript(): string;
+/**
+ * What the operating system is asking for.
+ *
+ * Dark unless the OS says light, which is the same fallback the pre-paint
+ * script uses and the same one a browser without `matchMedia` gets.
+ */
+export declare function systemTheme(): Theme;
+/** The theme a preference resolves to right now. */
+export declare function resolveTheme(preference: ThemePreference): Theme;
+/**
+ * What the reader asked for, from storage.
+ *
+ * `system` when nothing is stored, which is the default this kit resolves by
+ * and not a guess: an unanswered question is answered by the operating system,
+ * because the reader already answered it there.
+ */
+export declare function getThemePreference(): ThemePreference;
 /** Read the current theme. SSR-safe; returns `'dark'` on the server. */
 export declare function getTheme(): Theme;
+/**
+ * Record a preference, apply what it resolves to, and return the applied theme.
+ *
+ * `system` is stored under its own name rather than by clearing the key. The
+ * two are indistinguishable on the next read otherwise, and they are not the
+ * same thing: one reader chose to follow the OS and the other has not chosen
+ * anything yet. Both resolve identically today; only one of them is a decision
+ * a later default may not override.
+ */
+export declare function setThemePreference(preference: ThemePreference): Theme;
 /** Apply a theme and persist the choice to `localStorage`. */
 export declare function setTheme(theme: Theme): void;
+/**
+ * The next preference in `order`, wrapping at the end.
+ *
+ * Takes the list so a surface that offers only two states cycles through only
+ * those two. A preference that is not in the list starts the cycle at its
+ * first entry rather than falling out of it.
+ */
+export declare function nextThemePreference(current: ThemePreference, order?: readonly ThemePreference[]): ThemePreference;
 /** Flip between dark and light. Returns the new theme. */
 export declare function toggleTheme(): Theme;
+/**
+ * Call `onChange` whenever the operating system's choice changes. Returns the
+ * unsubscribe function, and a no-op one where there is no `matchMedia`.
+ *
+ * A page resolving `system` has to repaint when the OS flips at dusk. Without
+ * this the preference is honoured once, at load, and reads as ignored for the
+ * rest of the session.
+ */
+export declare function watchSystemTheme(onChange: (theme: Theme) => void): () => void;