@loidolt/theme-svelte 0.2.0 → 0.4.0

package/dist/components/Workspace.svelte

@@ -4,35 +4,56 @@
   import { cx } from '../utils.js';
 
   interface Props extends HTMLAttributes<HTMLDivElement> {
+    /** Full-width row above the panes — a ContextBar or toolbar. */
+    header?: Snippet;
     sidebar?: Snippet;
     children: Snippet;
     inspector?: Snippet;
+    /**
+     * Collapses the sidebar column when `false` — the toggle behind a "hide navigation" control.
+     * The snippet is left unrendered rather than hidden, so nothing in it holds focus or is
+     * reachable by the tab order while collapsed.
+     */
+    sidebarOpen?: boolean;
+    /** The same for the inspector column. */
+    inspectorOpen?: boolean;
     class?: string;
+    /** Extra classes for the main pane, replacing consumer reach-ins on `__main`. */
+    mainClass?: string;
     ref?: HTMLDivElement | null;
   }
 
   let {
+    header,
     sidebar,
     children,
     inspector,
+    sidebarOpen = true,
+    inspectorOpen = true,
     class: className,
+    mainClass,
     ref = $bindable(null),
     ...rest
   }: Props = $props();
+
+  const showSidebar = $derived(Boolean(sidebar) && sidebarOpen);
+  const showInspector = $derived(Boolean(inspector) && inspectorOpen);
 </script>
 
-<!-- The grid columns follow the snippets that are actually present. -->
+<!-- The grid columns follow the panes that are actually rendered. -->
 <div
   bind:this={ref}
   class={cx(
     'ldt-workspace',
-    sidebar && 'ldt-workspace--sidebar',
-    inspector && 'ldt-workspace--inspector',
+    header && 'ldt-workspace--header',
+    showSidebar && 'ldt-workspace--sidebar',
+    showInspector && 'ldt-workspace--inspector',
     className
   )}
   {...rest}
 >
-  {#if sidebar}{@render sidebar()}{/if}
-  <div class="ldt-workspace__main">{@render children()}</div>
-  {#if inspector}{@render inspector()}{/if}
+  {#if header}<div class="ldt-workspace__header">{@render header()}</div>{/if}
+  {#if showSidebar}{@render sidebar!()}{/if}
+  <div class={cx('ldt-workspace__main', mainClass)}>{@render children()}</div>
+  {#if showInspector}{@render inspector!()}{/if}
 </div>

package/dist/components/Workspace.svelte.d.ts

@@ -1,10 +1,22 @@
 import type { Snippet } from 'svelte';
 import type { HTMLAttributes } from 'svelte/elements';
 interface Props extends HTMLAttributes<HTMLDivElement> {
+    /** Full-width row above the panes — a ContextBar or toolbar. */
+    header?: Snippet;
     sidebar?: Snippet;
     children: Snippet;
     inspector?: Snippet;
+    /**
+     * Collapses the sidebar column when `false` — the toggle behind a "hide navigation" control.
+     * The snippet is left unrendered rather than hidden, so nothing in it holds focus or is
+     * reachable by the tab order while collapsed.
+     */
+    sidebarOpen?: boolean;
+    /** The same for the inspector column. */
+    inspectorOpen?: boolean;
     class?: string;
+    /** Extra classes for the main pane, replacing consumer reach-ins on `__main`. */
+    mainClass?: string;
     ref?: HTMLDivElement | null;
 }
 declare const Workspace: import("svelte").Component<Props, {}, "ref">;

package/dist/index.d.ts

@@ -1,36 +1,59 @@
+export { default as Accordion } from './components/Accordion.svelte';
 export { default as Alert } from './components/Alert.svelte';
+export { default as AlertDialog } from './components/AlertDialog.svelte';
 export { default as AppShell } from './components/AppShell.svelte';
 export { default as Badge } from './components/Badge.svelte';
 export { default as Brand } from './components/Brand.svelte';
+export { default as Breadcrumbs } from './components/Breadcrumbs.svelte';
 export { default as Button } from './components/Button.svelte';
 export { default as Card } from './components/Card.svelte';
 export { default as Checkbox } from './components/Checkbox.svelte';
+export { default as CodeBlock } from './components/CodeBlock.svelte';
+export { default as CommentList } from './components/CommentList.svelte';
 export { default as ContextBar } from './components/ContextBar.svelte';
 export { default as Dialog } from './components/Dialog.svelte';
+export { default as Drawer } from './components/Drawer.svelte';
 export { default as DropdownMenu } from './components/DropdownMenu.svelte';
+export { default as EmptyState } from './components/EmptyState.svelte';
 export { default as Field } from './components/Field.svelte';
+export { default as Fieldset } from './components/Fieldset.svelte';
+export { default as FileInput } from './components/FileInput.svelte';
+export { default as Filmstrip } from './components/Filmstrip.svelte';
+export { default as FloatingBar } from './components/FloatingBar.svelte';
 export { default as IconButton } from './components/IconButton.svelte';
 export { default as Input } from './components/Input.svelte';
 export { default as Label } from './components/Label.svelte';
+export { default as ListRow } from './components/ListRow.svelte';
+export { default as Marker } from './components/Marker.svelte';
 export { default as NavMenu } from './components/NavMenu.svelte';
 export { default as NumberField } from './components/NumberField.svelte';
 export { default as PageHeader } from './components/PageHeader.svelte';
+export { default as Pagination } from './components/Pagination.svelte';
 export { default as Panel } from './components/Panel.svelte';
 export { default as Popover } from './components/Popover.svelte';
 export { default as Progress } from './components/Progress.svelte';
 export { default as RadioGroup } from './components/RadioGroup.svelte';
+export { default as RecordStepper } from './components/RecordStepper.svelte';
 export { default as Section } from './components/Section.svelte';
+export { default as SegmentedNav } from './components/SegmentedNav.svelte';
 export { default as Select } from './components/Select.svelte';
 export { default as Separator } from './components/Separator.svelte';
 export { default as Sidebar } from './components/Sidebar.svelte';
 export { default as Skeleton } from './components/Skeleton.svelte';
 export { default as Spinner } from './components/Spinner.svelte';
+export { default as Stat } from './components/Stat.svelte';
+export { default as StatusDot } from './components/StatusDot.svelte';
+export { default as SwatchGroup } from './components/SwatchGroup.svelte';
 export { default as Switch } from './components/Switch.svelte';
 export { default as Table } from './components/Table.svelte';
+export { default as TableHeader } from './components/TableHeader.svelte';
 export { default as Tabs } from './components/Tabs.svelte';
 export { default as Textarea } from './components/Textarea.svelte';
+export { default as ThemeToggle } from './components/ThemeToggle.svelte';
+export { default as Thumbnail } from './components/Thumbnail.svelte';
 export { default as Toast } from './components/Toast.svelte';
 export { default as ToastViewport } from './components/ToastViewport.svelte';
+export { default as ToggleGroup } from './components/ToggleGroup.svelte';
 export { default as Tooltip } from './components/Tooltip.svelte';
 export { default as TooltipProvider } from './components/TooltipProvider.svelte';
 export { default as Topbar } from './components/Topbar.svelte';
@@ -39,8 +62,12 @@ export { default as Workspace } from './components/Workspace.svelte';
  * Bits UI primitives behind the wrappers, for menus and overlays this package does not
  * model declaratively (checkbox/radio items, submenus, custom overlay composition).
  */
-export { Dialog as DialogPrimitive, DropdownMenu as DropdownMenuPrimitive, Popover as PopoverPrimitive, Tabs as TabsPrimitive, Tooltip as TooltipPrimitive, } from 'bits-ui';
+export { Accordion as AccordionPrimitive, AlertDialog as AlertDialogPrimitive, Dialog as DialogPrimitive, DropdownMenu as DropdownMenuPrimitive, Pagination as PaginationPrimitive, Popover as PopoverPrimitive, Tabs as TabsPrimitive, ToggleGroup as ToggleGroupPrimitive, Tooltip as TooltipPrimitive, } from 'bits-ui';
 export { cx } from './utils.js';
 export { createToaster } from './toaster.svelte.js';
 export type { Toaster, ToasterOptions, ToastOptions, ToastRecord } from './toaster.svelte.js';
-export type { ActionVariant, Alignment, BadgeVariant, ControlSize, DialogSize, HeadingLevel, MenuItem, NavItem, Option, Orientation, Placement, StatusVariant, TriggerChildProps, } from './types.js';
+export { createTheme, themeScript } from './theme.svelte.js';
+export type { ColorScheme, Theme, ThemeOptions, ThemePreference, ThemeScriptOptions, } from './theme.svelte.js';
+export { breakpointQuery, createMediaQuery } from './media.svelte.js';
+export type { BreakpointName, MediaQuery, MediaQueryOptions } from './media.svelte.js';
+export type { ActionVariant, Alignment, BadgeSize, BadgeVariant, ColumnAlign, Crumb, Disclosure, ControlSize, DialogSize, HeadingLevel, MenuItem, NavItem, Option, Orientation, Placement, SortDirection, StatusVariant, TriggerChildProps, } from './types.js';

package/dist/index.js

@@ -1,36 +1,59 @@
+export { default as Accordion } from './components/Accordion.svelte';
 export { default as Alert } from './components/Alert.svelte';
+export { default as AlertDialog } from './components/AlertDialog.svelte';
 export { default as AppShell } from './components/AppShell.svelte';
 export { default as Badge } from './components/Badge.svelte';
 export { default as Brand } from './components/Brand.svelte';
+export { default as Breadcrumbs } from './components/Breadcrumbs.svelte';
 export { default as Button } from './components/Button.svelte';
 export { default as Card } from './components/Card.svelte';
 export { default as Checkbox } from './components/Checkbox.svelte';
+export { default as CodeBlock } from './components/CodeBlock.svelte';
+export { default as CommentList } from './components/CommentList.svelte';
 export { default as ContextBar } from './components/ContextBar.svelte';
 export { default as Dialog } from './components/Dialog.svelte';
+export { default as Drawer } from './components/Drawer.svelte';
 export { default as DropdownMenu } from './components/DropdownMenu.svelte';
+export { default as EmptyState } from './components/EmptyState.svelte';
 export { default as Field } from './components/Field.svelte';
+export { default as Fieldset } from './components/Fieldset.svelte';
+export { default as FileInput } from './components/FileInput.svelte';
+export { default as Filmstrip } from './components/Filmstrip.svelte';
+export { default as FloatingBar } from './components/FloatingBar.svelte';
 export { default as IconButton } from './components/IconButton.svelte';
 export { default as Input } from './components/Input.svelte';
 export { default as Label } from './components/Label.svelte';
+export { default as ListRow } from './components/ListRow.svelte';
+export { default as Marker } from './components/Marker.svelte';
 export { default as NavMenu } from './components/NavMenu.svelte';
 export { default as NumberField } from './components/NumberField.svelte';
 export { default as PageHeader } from './components/PageHeader.svelte';
+export { default as Pagination } from './components/Pagination.svelte';
 export { default as Panel } from './components/Panel.svelte';
 export { default as Popover } from './components/Popover.svelte';
 export { default as Progress } from './components/Progress.svelte';
 export { default as RadioGroup } from './components/RadioGroup.svelte';
+export { default as RecordStepper } from './components/RecordStepper.svelte';
 export { default as Section } from './components/Section.svelte';
+export { default as SegmentedNav } from './components/SegmentedNav.svelte';
 export { default as Select } from './components/Select.svelte';
 export { default as Separator } from './components/Separator.svelte';
 export { default as Sidebar } from './components/Sidebar.svelte';
 export { default as Skeleton } from './components/Skeleton.svelte';
 export { default as Spinner } from './components/Spinner.svelte';
+export { default as Stat } from './components/Stat.svelte';
+export { default as StatusDot } from './components/StatusDot.svelte';
+export { default as SwatchGroup } from './components/SwatchGroup.svelte';
 export { default as Switch } from './components/Switch.svelte';
 export { default as Table } from './components/Table.svelte';
+export { default as TableHeader } from './components/TableHeader.svelte';
 export { default as Tabs } from './components/Tabs.svelte';
 export { default as Textarea } from './components/Textarea.svelte';
+export { default as ThemeToggle } from './components/ThemeToggle.svelte';
+export { default as Thumbnail } from './components/Thumbnail.svelte';
 export { default as Toast } from './components/Toast.svelte';
 export { default as ToastViewport } from './components/ToastViewport.svelte';
+export { default as ToggleGroup } from './components/ToggleGroup.svelte';
 export { default as Tooltip } from './components/Tooltip.svelte';
 export { default as TooltipProvider } from './components/TooltipProvider.svelte';
 export { default as Topbar } from './components/Topbar.svelte';
@@ -39,6 +62,8 @@ export { default as Workspace } from './components/Workspace.svelte';
  * Bits UI primitives behind the wrappers, for menus and overlays this package does not
  * model declaratively (checkbox/radio items, submenus, custom overlay composition).
  */
-export { Dialog as DialogPrimitive, DropdownMenu as DropdownMenuPrimitive, Popover as PopoverPrimitive, Tabs as TabsPrimitive, Tooltip as TooltipPrimitive, } from 'bits-ui';
+export { Accordion as AccordionPrimitive, AlertDialog as AlertDialogPrimitive, Dialog as DialogPrimitive, DropdownMenu as DropdownMenuPrimitive, Pagination as PaginationPrimitive, Popover as PopoverPrimitive, Tabs as TabsPrimitive, ToggleGroup as ToggleGroupPrimitive, Tooltip as TooltipPrimitive, } from 'bits-ui';
 export { cx } from './utils.js';
 export { createToaster } from './toaster.svelte.js';
+export { createTheme, themeScript } from './theme.svelte.js';
+export { breakpointQuery, createMediaQuery } from './media.svelte.js';

package/dist/media.svelte.d.ts

@@ -0,0 +1,48 @@
+import { breakpoints } from '@loidolt/theme-tokens';
+export interface MediaQueryOptions {
+    /**
+     * What `matches` reports before a `matchMedia` result exists — during SSR, and on the very
+     * first client frame if the environment has no `matchMedia`. Pick the value that renders the
+     * layout you would rather ship to a bot or an old browser; it defaults to `false`.
+     */
+    fallback?: boolean;
+}
+export interface MediaQuery {
+    /** Live match state. Reactive — read it in markup or a `$derived`. */
+    readonly matches: boolean;
+    readonly query: string;
+    /**
+     * Removes the change listener. Called automatically when the query is created during
+     * component initialisation; call it yourself for a module-scope instance you want to retire.
+     */
+    destroy(): void;
+}
+/**
+ * Reactive `matchMedia`.
+ *
+ * ```svelte
+ * <script lang="ts">
+ *   import { createMediaQuery, breakpointQuery } from '@loidolt/theme-svelte';
+ *   const compact = createMediaQuery(breakpointQuery('compact'));
+ * </script>
+ *
+ * {#if compact.matches}<Drawer …/>{:else}<Sidebar …/>{/if}
+ * ```
+ *
+ * SSR-safe: on the server `matches` is the `fallback` and nothing subscribes. Because the
+ * server cannot know the viewport, markup that switches on a media query hydrates with the
+ * fallback branch and swaps on the first client frame — render both branches, or gate the
+ * swap on a mount flag, if that flash matters.
+ */
+export declare function createMediaQuery(query: string, options?: MediaQueryOptions): MediaQuery;
+export type BreakpointName = keyof typeof breakpoints;
+/**
+ * The media query for a token breakpoint. `below` (the default) matches the narrow side, which
+ * is the direction the stylesheet's own `@media (max-width: …)` blocks use.
+ *
+ * ```ts
+ * breakpointQuery('compact');           // '(max-width: 760px)'
+ * breakpointQuery('compact', 'above');  // '(min-width: 760.02px)'
+ * ```
+ */
+export declare function breakpointQuery(name: BreakpointName, direction?: 'below' | 'above'): string;

package/dist/media.svelte.js

@@ -0,0 +1,69 @@
+import { onDestroy } from 'svelte';
+import { breakpoints } from '@loidolt/theme-tokens';
+/**
+ * Reactive `matchMedia`.
+ *
+ * ```svelte
+ * <script lang="ts">
+ *   import { createMediaQuery, breakpointQuery } from '@loidolt/theme-svelte';
+ *   const compact = createMediaQuery(breakpointQuery('compact'));
+ * </script>
+ *
+ * {#if compact.matches}<Drawer …/>{:else}<Sidebar …/>{/if}
+ * ```
+ *
+ * SSR-safe: on the server `matches` is the `fallback` and nothing subscribes. Because the
+ * server cannot know the viewport, markup that switches on a media query hydrates with the
+ * fallback branch and swaps on the first client frame — render both branches, or gate the
+ * swap on a mount flag, if that flash matters.
+ */
+export function createMediaQuery(query, options = {}) {
+    const { fallback = false } = options;
+    let matches = $state(fallback);
+    let list;
+    const update = (event) => {
+        matches = event.matches;
+    };
+    if (typeof window !== 'undefined' && typeof window.matchMedia === 'function') {
+        list = window.matchMedia(query);
+        matches = list.matches;
+        list.addEventListener('change', update);
+    }
+    const destroy = () => {
+        list?.removeEventListener('change', update);
+        list = undefined;
+    };
+    // A query created inside a component should not outlive it. Created at module scope — the
+    // usual place for an app-wide singleton — there is no component to hook into, and the caller
+    // owns `destroy()` instead.
+    try {
+        onDestroy(destroy);
+    }
+    catch {
+        /* module scope: no lifecycle to attach to */
+    }
+    return {
+        get matches() {
+            return matches;
+        },
+        query,
+        destroy,
+    };
+}
+/**
+ * The media query for a token breakpoint. `below` (the default) matches the narrow side, which
+ * is the direction the stylesheet's own `@media (max-width: …)` blocks use.
+ *
+ * ```ts
+ * breakpointQuery('compact');           // '(max-width: 760px)'
+ * breakpointQuery('compact', 'above');  // '(min-width: 760.02px)'
+ * ```
+ */
+export function breakpointQuery(name, direction = 'below') {
+    const value = breakpoints[name];
+    if (direction === 'below')
+        return `(max-width: ${value})`;
+    // 0.02px, not 1px: the CSS Media Queries spec resolves widths at fractional precision, so a
+    // whole-pixel step leaves a dead zone on fractional-DPI viewports where neither side matches.
+    return `(min-width: ${Number.parseFloat(value) + 0.02}px)`;
+}

package/dist/theme.svelte.d.ts

@@ -0,0 +1,86 @@
+/** What the user chose. `system` defers to `prefers-color-scheme`. */
+export type ThemePreference = 'light' | 'dark' | 'system';
+/** What that choice resolves to right now — the value written to the DOM. */
+export type ColorScheme = 'light' | 'dark';
+export interface ThemeOptions {
+    /** `localStorage` key holding the preference. Set to `null` to keep the choice in memory. */
+    storageKey?: string | null;
+    /** Attribute the resolved scheme is written to. Must match the stylesheet's selector. */
+    attribute?: string;
+    /** Element the attribute lands on. Defaults to `<html>`. */
+    element?: HTMLElement | null;
+    /** Preference before anything is stored. */
+    defaultPreference?: ThemePreference;
+    /** What `system` resolves to where `prefers-color-scheme` cannot be read (SSR, old engines). */
+    defaultScheme?: ColorScheme;
+    /**
+     * Mirror the choice across tabs by listening for `storage` events. On by default; turn it off
+     * if separate windows should be able to hold different themes.
+     */
+    sync?: boolean;
+}
+export interface Theme {
+    /** The stored choice. Assignable: `theme.preference = 'dark'`. */
+    preference: ThemePreference;
+    /** The scheme in force — `preference`, or the system scheme when that is `system`. */
+    readonly resolved: ColorScheme;
+    /** What the system currently prefers, regardless of the choice. */
+    readonly system: ColorScheme;
+    /** Flips between explicit light and dark, starting from whatever is showing. */
+    toggle(): void;
+    /** Removes the media and storage listeners. Automatic for a component-scoped instance. */
+    destroy(): void;
+}
+/**
+ * Theme state: the stored preference, the system preference, and the resolved scheme written to
+ * the DOM.
+ *
+ * ```ts
+ * // src/lib/theme.ts — one instance for the app
+ * import { createTheme } from '@loidolt/theme-svelte';
+ * export const theme = createTheme();
+ * ```
+ *
+ * ```svelte
+ * <button onclick={theme.toggle}>{theme.resolved === 'dark' ? 'Light' : 'Dark'} mode</button>
+ * ```
+ *
+ * The **resolved** scheme is always written out, even for `system`, so the same store drives
+ * both `@loidolt/theme-styles/dark` (attribute-only) and `/dark-auto` (which also follows
+ * `prefers-color-scheme`): an explicit `data-theme="light"` is exactly what `dark-auto` expects
+ * to see when a user overrides a dark system.
+ *
+ * Pair it with {@link themeScript} in `app.html`, or the first paint of a reload is light.
+ */
+export declare function createTheme(options?: ThemeOptions): Theme;
+export interface ThemeScriptOptions extends Pick<ThemeOptions, 'storageKey' | 'attribute' | 'defaultPreference' | 'defaultScheme'> {
+    /** Wrap the source in a `<script>` tag. Off by default, so it can go inside your own tag. */
+    tag?: boolean;
+}
+/**
+ * The blocking snippet that stops the light-mode flash on reload. It performs the same resolve
+ * as {@link createTheme} — read the stored preference, fall back to `prefers-color-scheme`,
+ * write the attribute — before the browser paints.
+ *
+ * It must run **synchronously in `<head>`, before the stylesheet's first paint**. A module
+ * script, a `defer`ed script, or anything in `<body>` is too late by definition.
+ *
+ * ```html
+ * <!-- src/app.html -->
+ * <head>
+ *   %sveltekit.head%
+ *   <script>__LOIDOLT_THEME__</script>
+ * </head>
+ * ```
+ *
+ * ```ts
+ * // src/hooks.server.ts
+ * import { themeScript } from '@loidolt/theme-svelte';
+ * export const handle = ({ event, resolve }) =>
+ *   resolve(event, { transformPageChunk: ({ html }) => html.replace('__LOIDOLT_THEME__', themeScript()) });
+ * ```
+ *
+ * Returns source only unless `tag` is set. The output contains no `<` at all, so it is safe to
+ * inline in an HTML `<script>` element without further escaping.
+ */
+export declare function themeScript(options?: ThemeScriptOptions): string;

package/dist/theme.svelte.js

@@ -0,0 +1,166 @@
+import { onDestroy } from 'svelte';
+const SCHEMES = ['light', 'dark', 'system'];
+const isPreference = (value) => typeof value === 'string' && SCHEMES.includes(value);
+/**
+ * Theme state: the stored preference, the system preference, and the resolved scheme written to
+ * the DOM.
+ *
+ * ```ts
+ * // src/lib/theme.ts — one instance for the app
+ * import { createTheme } from '@loidolt/theme-svelte';
+ * export const theme = createTheme();
+ * ```
+ *
+ * ```svelte
+ * <button onclick={theme.toggle}>{theme.resolved === 'dark' ? 'Light' : 'Dark'} mode</button>
+ * ```
+ *
+ * The **resolved** scheme is always written out, even for `system`, so the same store drives
+ * both `@loidolt/theme-styles/dark` (attribute-only) and `/dark-auto` (which also follows
+ * `prefers-color-scheme`): an explicit `data-theme="light"` is exactly what `dark-auto` expects
+ * to see when a user overrides a dark system.
+ *
+ * Pair it with {@link themeScript} in `app.html`, or the first paint of a reload is light.
+ */
+export function createTheme(options = {}) {
+    const { storageKey = 'loidolt-theme', attribute = 'data-theme', element, defaultPreference = 'system', defaultScheme = 'light', sync = true, } = options;
+    const browser = typeof document !== 'undefined';
+    const target = element ?? (browser ? document.documentElement : null);
+    const read = () => {
+        if (!browser || storageKey === null)
+            return defaultPreference;
+        try {
+            const stored = localStorage.getItem(storageKey);
+            return isPreference(stored) ? stored : defaultPreference;
+        }
+        catch {
+            // Storage can throw outright in a partitioned iframe or with cookies blocked. A theme is
+            // not worth breaking the page over — fall back to the default and keep the choice in memory.
+            return defaultPreference;
+        }
+    };
+    let preference = $state(read());
+    let system = $state(defaultScheme);
+    let media;
+    const onSystemChange = (event) => {
+        system = event.matches ? 'dark' : 'light';
+        apply();
+    };
+    if (browser && typeof window.matchMedia === 'function') {
+        media = window.matchMedia('(prefers-color-scheme: dark)');
+        system = media.matches ? 'dark' : 'light';
+        media.addEventListener('change', onSystemChange);
+    }
+    const resolve = () => (preference === 'system' ? system : preference);
+    function apply() {
+        target?.setAttribute(attribute, resolve());
+    }
+    const onStorage = (event) => {
+        if (event.key !== storageKey)
+            return;
+        // A cleared key means another tab reset to the default rather than picking a scheme.
+        preference = isPreference(event.newValue) ? event.newValue : defaultPreference;
+        apply();
+    };
+    if (browser && sync && storageKey !== null)
+        window.addEventListener('storage', onStorage);
+    // Written on creation, not in an effect: `createTheme()` is meant to be callable at module
+    // scope, where there is no reactive context to own an effect.
+    apply();
+    function set(next) {
+        preference = next;
+        if (browser && storageKey !== null) {
+            try {
+                localStorage.setItem(storageKey, next);
+            }
+            catch {
+                /* see `read`: unavailable storage degrades to a memory-only choice */
+            }
+        }
+        apply();
+    }
+    const destroy = () => {
+        media?.removeEventListener('change', onSystemChange);
+        media = undefined;
+        if (browser && sync && storageKey !== null)
+            window.removeEventListener('storage', onStorage);
+    };
+    try {
+        onDestroy(destroy);
+    }
+    catch {
+        /* module scope: the caller owns `destroy()` */
+    }
+    return {
+        get preference() {
+            return preference;
+        },
+        set preference(next) {
+            set(next);
+        },
+        get resolved() {
+            return resolve();
+        },
+        get system() {
+            return system;
+        },
+        toggle() {
+            set(resolve() === 'dark' ? 'light' : 'dark');
+        },
+        destroy,
+    };
+}
+/**
+ * The blocking snippet that stops the light-mode flash on reload. It performs the same resolve
+ * as {@link createTheme} — read the stored preference, fall back to `prefers-color-scheme`,
+ * write the attribute — before the browser paints.
+ *
+ * It must run **synchronously in `<head>`, before the stylesheet's first paint**. A module
+ * script, a `defer`ed script, or anything in `<body>` is too late by definition.
+ *
+ * ```html
+ * <!-- src/app.html -->
+ * <head>
+ *   %sveltekit.head%
+ *   <script>__LOIDOLT_THEME__</script>
+ * </head>
+ * ```
+ *
+ * ```ts
+ * // src/hooks.server.ts
+ * import { themeScript } from '@loidolt/theme-svelte';
+ * export const handle = ({ event, resolve }) =>
+ *   resolve(event, { transformPageChunk: ({ html }) => html.replace('__LOIDOLT_THEME__', themeScript()) });
+ * ```
+ *
+ * Returns source only unless `tag` is set. The output contains no `<` at all, so it is safe to
+ * inline in an HTML `<script>` element without further escaping.
+ */
+export function themeScript(options = {}) {
+    const { storageKey = 'loidolt-theme', attribute = 'data-theme', defaultPreference = 'system', defaultScheme = 'light', tag = false, } = options;
+    // JSON string escaping alone leaves `<` intact, including a literal `</script>` that would end
+    // an inline script element. Escaping HTML-significant characters and the two JavaScript line
+    // separators keeps every option inside its string literal in both source-only and tagged forms.
+    const serialize = (value) => JSON.stringify(value)
+        .replaceAll('<', '\\u003c')
+        .replaceAll('>', '\\u003e')
+        .replaceAll('&', '\\u0026')
+        .replaceAll('\u2028', '\\u2028')
+        .replaceAll('\u2029', '\\u2029');
+    const key = serialize(storageKey);
+    const attr = serialize(attribute);
+    const fallback = serialize(defaultPreference);
+    const scheme = serialize(defaultScheme);
+    const source = `(function(){try{` +
+        `var p=${fallback};` +
+        // Storage failure must not skip system resolution and attribute application.
+        `try{var v=${key}===null?null:localStorage.getItem(${key});` +
+        `if(v==="light"||v==="dark"||v==="system")p=v;}catch(e){}` +
+        `var s=${scheme};` +
+        `if(typeof matchMedia==="function")s=matchMedia("(prefers-color-scheme: dark)").matches?"dark":"light";` +
+        `document.documentElement.setAttribute(${attr},p==="system"?s:p);` +
+        // A theme is cosmetic; a throw here would abort a blocking head script and take the page
+        // down with it. Swallow and let the stylesheet's own default stand.
+        `}catch(e){}})()`;
+    return tag ? `<script>${source}</script>` : source;
+}

package/dist/toaster.svelte.d.ts

@@ -26,6 +26,8 @@ export interface Toaster {
     pause(): void;
     /** Resumes with the time each toast had left — call on pointer leave / focus out. */
     resume(): void;
+    /** Clears the queue and every timer. Automatic for a component-scoped instance. */
+    destroy(): void;
 }
 /**
  * Queue behind `Toast` / `ToastViewport`: auto-dismiss with the remaining time preserved