@urbicon-ui/blocks 6.40.4 → 6.43.0

package/dist/primitives/Select/select.variants.js

@@ -1,4 +1,7 @@
+import { FIELD_MESSAGE_TONES, fieldErrorFrame } from '../../internal/field-chrome.js';
 import { tv } from '../../utils/variants.js';
+// The trigger is the focusable element, so the error ring lives on it directly.
+const focus = 'focus-visible';
 export const selectVariants = tv({
     slots: {
         wrapper: ['flex flex-col w-full gap-1.5'],
@@ -146,13 +149,19 @@ export const selectVariants = tv({
         // Declared BEFORE `error` so the error tone wins the message-color
         // bucket in every call shape — `{ error: true }` alone must read red.
         messageType: {
-            error: { message: 'text-danger' },
-            helper: { message: 'text-text-tertiary' }
+            error: { message: FIELD_MESSAGE_TONES.error },
+            helper: { message: FIELD_MESSAGE_TONES.helper }
         },
+        // Same error frame as every other field (shared fragment, so a token fix
+        // can't miss Select again). Unlike Input/Textarea/PinInput/TimeInput,
+        // Select has no `intent` axis, so nothing competes for the border/ring
+        // buckets and the frame can stay on the axis. If an `intent` axis is ever
+        // added here, move this to the compound stage — see the precedence note in
+        // input.variants.ts.
         error: {
             true: {
-                trigger: 'border-danger focus-visible:border-danger focus-visible:ring-danger/20',
-                message: 'text-danger'
+                trigger: fieldErrorFrame(focus),
+                message: FIELD_MESSAGE_TONES.error
             }
         },
         required: {

package/dist/primitives/Slider/Slider.svelte

@@ -160,7 +160,7 @@
       if (status === 'insideValidOnly') return 'var(--color-warning-subtle)';
       if (status === 'outsideValidDanger') return 'var(--color-danger-subtle)';
       if (status === 'outsideValidWarning') return 'var(--color-warning-subtle)';
-      return 'var(--color-surface-subtle)';
+      return 'var(--color-surface-interactive)';
     };
 
     const points = [min, ...zoneBoundaries, max];
@@ -460,6 +460,7 @@
             ? `${label} minimum`
             : bt('accessibility.minimum') || 'Minimum'}
         aria-describedby={describedBy}
+        aria-invalid={error ? 'true' : undefined}
         aria-disabled={disabled || undefined}
         class={unstyled ? (slotClasses?.thumb ?? '') : styles.thumb({ class: slotClasses?.thumb })}
         style="left: {thumbStartPosition}%"
@@ -479,6 +480,7 @@
             ? `${label} maximum`
             : bt('accessibility.maximum') || 'Maximum'}
         aria-describedby={describedBy}
+        aria-invalid={error ? 'true' : undefined}
         aria-disabled={disabled || undefined}
         class={unstyled ? (slotClasses?.thumb ?? '') : styles.thumb({ class: slotClasses?.thumb })}
         style="left: {thumbEndPosition}%"
@@ -495,6 +497,7 @@
         aria-labelledby={ariaLabelledby}
         aria-label={ariaLabelledby ? undefined : label || bt('accessibility.slider') || 'Slider'}
         aria-describedby={describedBy}
+        aria-invalid={error ? 'true' : undefined}
         aria-disabled={disabled || undefined}
         class={unstyled ? (slotClasses?.thumb ?? '') : styles.thumb({ class: slotClasses?.thumb })}
         style="left: {thumbPosition}%"

package/dist/primitives/Slider/slider.variants.js

@@ -7,8 +7,11 @@ export const sliderVariants = tv({
         valueText: ['text-sm tabular-nums text-text-tertiary'],
         base: ['relative flex items-center w-full touch-none select-none cursor-pointer'],
         // tier: commit — slider is a continuous-value pill (track + range + thumb).
+        // Track fill is `surface-interactive`, matching Toggle's unchecked track:
+        // `surface-subtle` resolves to the SAME neutral step as `surface-elevated`
+        // in both modes, so the groove vanished on any elevated card/popover.
         track: [
-            'relative w-full overflow-hidden rounded-commit bg-surface-subtle',
+            'relative w-full overflow-hidden rounded-commit bg-surface-interactive',
             'transition-[background-color] duration-[var(--blocks-duration-fast)]'
         ],
         range: [
@@ -20,7 +23,11 @@ export const sliderVariants = tv({
             'absolute rounded-commit bg-surface-base border-2',
             'shadow-[var(--blocks-shadow-sm)]',
             '-translate-x-1/2 -translate-y-1/2 top-1/2',
-            'transition-[box-shadow,transform] duration-[var(--blocks-duration-fast)]',
+            // `scale`, NOT `transform`: Tailwind 4 emits `scale-*` as the discrete
+            // `scale:` property — `hover:scale-110` is the only animated transform
+            // here, so it is the only one listed. The centring `-translate-*` above
+            // is static (the thumb travels via `left`), so `translate` stays out.
+            'transition-[box-shadow,scale] duration-[var(--blocks-duration-fast)]',
             'hover:scale-110 hover:shadow-[var(--blocks-shadow-md)]',
             'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-offset-2 focus-visible:ring-offset-surface-base'
         ],

package/dist/primitives/Textarea/textarea.variants.js

@@ -1,3 +1,4 @@
+import { fieldErrorFrame } from '../../internal/field-chrome.js';
 import { tv } from '../../utils/variants.js';
 export const textareaVariants = tv({
     slots: {
@@ -83,9 +84,11 @@ export const textareaVariants = tv({
             error: { message: 'text-danger' },
             helper: { message: 'text-text-tertiary' }
         },
+        // The error FRAME is not declared here — it lives in the compound stage
+        // below, where it beats `intent` by construction. See the precedence note
+        // on the first compound entry.
         error: {
             true: {
-                base: 'border-danger focus-visible:border-danger focus-visible:ring-danger/20',
                 message: 'text-danger'
             }
         },
@@ -101,6 +104,17 @@ export const textareaVariants = tv({
         }
     },
     compoundVariants: [
+        // ── Validation precedence: `error` beats `intent`, explicitly ────────────
+        // Both axes paint the SAME three buckets (border-color plus the focused
+        // border/ring tint), so exactly one of them can win. Emitting the error
+        // frame here rather than on the `error` axis makes that rule structural:
+        // compounds always fold after every axis, so `error: true` overrides
+        // whatever `intent` painted regardless of how the axes are ordered above
+        // (it used to hinge purely on `error` being DECLARED after `intent`).
+        {
+            error: true,
+            class: { base: fieldErrorFrame('focus-visible') }
+        },
         {
             variant: 'ghost',
             intent: ['success', 'warning', 'danger'],

package/dist/primitives/Toast/toast.variants.js

@@ -10,7 +10,11 @@ export const toastVariants = tv({
             'pointer-events-auto flex items-start gap-3 w-full max-w-sm',
             'rounded-contain p-4',
             'shadow-[var(--blocks-shadow-lg)]',
-            'transition-[color,background-color,box-shadow,opacity,transform] duration-[var(--blocks-duration-normal)] ease-[var(--blocks-ease-smooth)]'
+            // No transform entry: the enter/exit motion is Svelte's `transition:fly`,
+            // which runs as a CSS *animation* (keyframes) and ignores
+            // `transition-property` entirely. Nothing on this slot sets a
+            // scale/translate/rotate utility, so a `transform` entry was dead weight.
+            'transition-[color,background-color,box-shadow,opacity] duration-[var(--blocks-duration-normal)] ease-[var(--blocks-ease-smooth)]'
         ],
         icon: 'shrink-0 mt-0.5 w-5 h-5',
         content: 'flex-1 min-w-0',

package/dist/primitives/Toggle/toggle.variants.js

@@ -8,7 +8,26 @@ export const toggleVariants = tv({
         // rectangle switch that reads as inline-toolbar control.
         track: [
             'relative inline-flex items-center',
-            'transition-[color,background-color,border-color,box-shadow] duration-[var(--blocks-duration-fast)] ease-out',
+            'transition-[color,background-color,border-color,box-shadow,scale] duration-[var(--blocks-duration-fast)] ease-out',
+            // Press feedback on the control surface — the same small-element press
+            // cue Checkbox took from Badge/Avatar (`scale-95`), with `group-active`
+            // so pressing the label squeezes the switch too. It rides the TRACK,
+            // not the thumb, for three reasons:
+            //   1. the track is the switch's control surface — Checkbox puts the
+            //      cue on `box`, and the whole subtree (thumb included) squeezes
+            //      with it, so one class covers the entire control;
+            //   2. the `dot` variant *hides* the thumb, so a thumb-mounted cue
+            //      would silently vanish exactly where the control is smallest;
+            //   3. the thumb already drives motion through `translate` (its
+            //      resting `-translate-y-1/2` plus the per-size `translate-x-*`).
+            //      Tailwind 4 compiles `scale-*` to the discrete `scale` property,
+            //      which CSS applies AFTER `translate` about the element's own
+            //      centre — so a thumb-mounted cue would shrink the knob in place
+            //      at whichever end of the track it sits, reading as a rendering
+            //      glitch rather than a press.
+            // `scale` is in the transition list above, and reduced motion collapses
+            // `--blocks-duration-fast` to 1ms.
+            'group-active:scale-95',
             'border border-transparent',
             'peer-focus-visible:ring-2 peer-focus-visible:ring-primary/50',
             'peer-focus-visible:ring-offset-2 peer-focus-visible:ring-offset-surface-base'
@@ -104,7 +123,18 @@ export const toggleVariants = tv({
             variant: 'default',
             checked: false,
             class: {
-                track: 'bg-surface-interactive',
+                // Off-state hover steps the boundary up to `border-emphasis` — the
+                // same destination Checkbox's unchecked `outlined` box reaches, on
+                // the border the track already reserves (`border border-transparent`
+                // in the slot base, so nothing shifts).
+                // Deliberately NOT a fill step: the off track sits on
+                // `surface-interactive`, which resolves to the SAME value as
+                // `surface-hover` in light mode (both neutral-100) and as
+                // `surface-active` in dark (both neutral-700) — in the library
+                // default *and* under the docs Rooms skin. Either fill token would
+                // therefore be a silent no-op in one of the two modes; the border is
+                // the only step that reads in both.
+                track: 'bg-surface-interactive group-hover:border-border-emphasis',
                 thumb: 'translate-x-0'
             }
         },
@@ -113,7 +143,11 @@ export const toggleVariants = tv({
             variant: 'default',
             checked: false,
             withBorder: true,
-            class: { track: 'border-border-strong' }
+            // `border-strong` is the top of the border ladder, so the off-state
+            // hover above would *weaken* it (strong → emphasis). Pin the hover
+            // bucket to strong: an opt-in permanent boundary must not soften when
+            // the pointer arrives.
+            class: { track: 'border-border-strong group-hover:border-border-strong' }
         },
         {
             variant: 'default',
@@ -122,41 +156,58 @@ export const toggleVariants = tv({
             class: { track: 'ring-1 ring-inset ring-surface-base/40' }
         },
         // ── Checked track per intent (Switch-Pill only) ──
+        // Hover/active darken through the intent interaction-layer tokens — the
+        // same `bg-<intent>-hover` / `bg-<intent>-active` ladder Button and
+        // Checkbox use — via `group-*` so hovering/pressing the label counts too.
+        // The border stays on the base intent stop (as in Checkbox), leaving a
+        // hairline rim that makes the fill step legible.
         {
             variant: 'default',
             checked: true,
             intent: 'primary',
-            class: { track: 'bg-primary border-primary' }
+            class: {
+                track: 'bg-primary border-primary group-hover:bg-primary-hover group-active:bg-primary-active'
+            }
         },
         {
             variant: 'default',
             checked: true,
             intent: 'secondary',
-            class: { track: 'bg-secondary border-secondary' }
+            class: {
+                track: 'bg-secondary border-secondary group-hover:bg-secondary-hover group-active:bg-secondary-active'
+            }
         },
         {
             variant: 'default',
             checked: true,
             intent: 'success',
-            class: { track: 'bg-success border-success' }
+            class: {
+                track: 'bg-success border-success group-hover:bg-success-hover group-active:bg-success-active'
+            }
         },
         {
             variant: 'default',
             checked: true,
             intent: 'warning',
-            class: { track: 'bg-warning border-warning' }
+            class: {
+                track: 'bg-warning border-warning group-hover:bg-warning-hover group-active:bg-warning-active'
+            }
         },
         {
             variant: 'default',
             checked: true,
             intent: 'danger',
-            class: { track: 'bg-danger border-danger' }
+            class: {
+                track: 'bg-danger border-danger group-hover:bg-danger-hover group-active:bg-danger-active'
+            }
         },
         {
             variant: 'default',
             checked: true,
             intent: 'neutral',
-            class: { track: 'bg-neutral border-neutral' }
+            class: {
+                track: 'bg-neutral border-neutral group-hover:bg-neutral-hover group-active:bg-neutral-active'
+            }
         },
         // ── Error state: danger boundary on the unchecked track (Switch-Pill) ──
         // Mirrors Checkbox ("error overrides unchecked border"): the off state
@@ -165,11 +216,16 @@ export const toggleVariants = tv({
         // The dot-variant twin lives at the END of the compound list so it
         // folds over the dot-unchecked `border-border-default` (order is
         // semantic — later compounds win conflicting buckets).
+        // `group-hover:border-danger` pins the hover bucket as well — without it
+        // the off-state hover step above would repaint the error boundary neutral
+        // the moment the pointer arrives, which is exactly when the mark matters.
         {
             variant: 'default',
             error: true,
             checked: false,
-            class: { track: 'border-danger peer-focus-visible:ring-danger/40' }
+            class: {
+                track: 'border-danger group-hover:border-danger peer-focus-visible:ring-danger/40'
+            }
         },
         // ── Thumb translation per size when checked (Switch-Pill only) ──
         { variant: 'default', checked: true, size: 'xs', class: { thumb: 'translate-x-4' } },
@@ -193,50 +249,68 @@ export const toggleVariants = tv({
         {
             variant: 'dot',
             checked: false,
-            class: { track: 'border-border-default' }
+            // Off-state hover: `border-default` → `border-emphasis`, the exact
+            // ladder Checkbox's unchecked `outlined` box walks (the dot is
+            // outline-only, so its boundary is the whole control).
+            class: { track: 'border-border-default group-hover:border-border-emphasis' }
         },
+        // Same intent interaction layer as the Switch-Pill above — the dot is a
+        // filled intent surface too, just a 14px one.
         {
             variant: 'dot',
             checked: true,
             intent: 'primary',
-            class: { track: 'border-primary bg-primary' }
+            class: {
+                track: 'border-primary bg-primary group-hover:bg-primary-hover group-active:bg-primary-active'
+            }
         },
         {
             variant: 'dot',
             checked: true,
             intent: 'secondary',
-            class: { track: 'border-secondary bg-secondary' }
+            class: {
+                track: 'border-secondary bg-secondary group-hover:bg-secondary-hover group-active:bg-secondary-active'
+            }
         },
         {
             variant: 'dot',
             checked: true,
             intent: 'success',
-            class: { track: 'border-success bg-success' }
+            class: {
+                track: 'border-success bg-success group-hover:bg-success-hover group-active:bg-success-active'
+            }
         },
         {
             variant: 'dot',
             checked: true,
             intent: 'warning',
-            class: { track: 'border-warning bg-warning' }
+            class: {
+                track: 'border-warning bg-warning group-hover:bg-warning-hover group-active:bg-warning-active'
+            }
         },
         {
             variant: 'dot',
             checked: true,
             intent: 'danger',
-            class: { track: 'border-danger bg-danger' }
+            class: {
+                track: 'border-danger bg-danger group-hover:bg-danger-hover group-active:bg-danger-active'
+            }
         },
         {
             variant: 'dot',
             checked: true,
             intent: 'neutral',
-            class: { track: 'border-neutral bg-neutral' }
+            class: {
+                track: 'border-neutral bg-neutral group-hover:bg-neutral-hover group-active:bg-neutral-active'
+            }
         },
         // ── Error state, dot variant (must fold over dot-unchecked border) ──
+        // Pins the hover bucket too, for the same reason as the Switch-Pill twin.
         {
             variant: 'dot',
             error: true,
             checked: false,
-            class: { track: 'border-danger' }
+            class: { track: 'border-danger group-hover:border-danger' }
         }
     ],
     defaultVariants: {

package/dist/primitives/Tooltip/tooltip.variants.d.ts

@@ -1,19 +1,19 @@
 import { type SlotNames, type VariantProps } from '../../utils/variants.js';
 export declare const tooltipVariants: ((props?: {
     open?: boolean | undefined;
-    intent?: "primary" | "secondary" | "success" | "warning" | "danger" | "neutral" | "info" | undefined;
+    intent?: "primary" | "secondary" | "success" | "warning" | "danger" | "neutral" | undefined;
     size?: "sm" | "md" | "lg" | undefined;
 } | undefined) => {
     base: (props?: ({
         open?: boolean | undefined;
-        intent?: "primary" | "secondary" | "success" | "warning" | "danger" | "neutral" | "info" | undefined;
+        intent?: "primary" | "secondary" | "success" | "warning" | "danger" | "neutral" | undefined;
         size?: "sm" | "md" | "lg" | undefined;
     } & {
         class?: string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | /*elided*/ any | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined;
     }) | undefined) => string;
     arrow: (props?: ({
         open?: boolean | undefined;
-        intent?: "primary" | "secondary" | "success" | "warning" | "danger" | "neutral" | "info" | undefined;
+        intent?: "primary" | "secondary" | "success" | "warning" | "danger" | "neutral" | undefined;
         size?: "sm" | "md" | "lg" | undefined;
     } & {
         class?: string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | /*elided*/ any | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined;

package/dist/primitives/Tooltip/tooltip.variants.js

@@ -48,10 +48,14 @@ export const tooltipVariants = tv({
             true: { base: 'opacity-100 starting:opacity-0' },
             false: { base: 'opacity-0' }
         },
+        // The standard six-value palette. `info` is deliberately absent: it belongs
+        // to the feedback family (Alert, Toast), where it means "informational, and
+        // stable under a rebrand" — a tooltip is a container, and `info` sat one
+        // hue-step from `primary` (220 vs 240), so the two were barely
+        // distinguishable while implying a distinction that wasn't there.
         intent: {
             primary: { base: 'bg-primary text-text-on-primary' },
             secondary: { base: 'bg-secondary text-text-on-primary' },
-            info: { base: 'bg-info text-text-on-primary' },
             success: { base: 'bg-success text-text-on-primary' },
             warning: { base: 'bg-warning text-text-on-warning' },
             danger: { base: 'bg-danger text-text-on-primary' },

package/dist/utils/persistent-state.svelte.d.ts

@@ -13,15 +13,39 @@ export interface PersistentStateConfig<T> {
 /**
  * Create a persistent state that automatically syncs with storage
  * Uses Svelte 5 $state() for reactivity
+ *
+ * Besides `value`, the returned object exposes `hasStoredValue` — whether an
+ * entry for this key exists in storage. That is what lets a consumer tell a
+ * *stored empty* value (`[]`, `''`, `null` — the user cleared it) from *nothing
+ * stored at all*, so a cleared state can win over a default/seed instead of
+ * being re-applied on every load. Two rules keep that signal meaningful: a save
+ * that would not change the stored bytes is skipped, and an instance nobody
+ * wrote to never creates an entry for its own default (so `reset()` is not
+ * undone by the auto-save, and untouched state stays out of storage). Writing
+ * the default *back* — clearing — is a real write and does create the entry.
+ *
+ * Values must round-trip through the configured `serialize`/`deserialize`;
+ * `Set`/`Map` do not under the `JSON.stringify` default (they serialize to
+ * `{}`), so pass converting functions or store plain arrays/objects.
  */
 export declare function createPersistentState<T>(config: PersistentStateConfig<T>): {
     value: T;
+    /**
+     * Whether storage currently holds an entry for this key: `true` when
+     * construction (or `reload()`) found a parseable entry, and after a write
+     * actually reached storage; `false` when the key was absent or corrupt,
+     * after `reset()`, and always without a working storage (SSR, private
+     * mode). Use it to distinguish a stored empty value from an absent one.
+     */
+    readonly hasStoredValue: boolean;
     /**
      * Reset to default value and clear storage
      */
     reset(): void;
     /**
-     * Force immediate save (bypasses debounce)
+     * Force immediate save (bypasses debounce). A no-op when storage already
+     * holds exactly this value, and — like the auto-save — when the instance
+     * was never written to and still holds its default.
      */
     forceSave(): void;
     /**

package/dist/utils/persistent-state.svelte.js

@@ -30,33 +30,88 @@ function debounce(func, wait) {
 /**
  * Create a persistent state that automatically syncs with storage
  * Uses Svelte 5 $state() for reactivity
+ *
+ * Besides `value`, the returned object exposes `hasStoredValue` — whether an
+ * entry for this key exists in storage. That is what lets a consumer tell a
+ * *stored empty* value (`[]`, `''`, `null` — the user cleared it) from *nothing
+ * stored at all*, so a cleared state can win over a default/seed instead of
+ * being re-applied on every load. Two rules keep that signal meaningful: a save
+ * that would not change the stored bytes is skipped, and an instance nobody
+ * wrote to never creates an entry for its own default (so `reset()` is not
+ * undone by the auto-save, and untouched state stays out of storage). Writing
+ * the default *back* — clearing — is a real write and does create the entry.
+ *
+ * Values must round-trip through the configured `serialize`/`deserialize`;
+ * `Set`/`Map` do not under the `JSON.stringify` default (they serialize to
+ * `{}`), so pass converting functions or store plain arrays/objects.
  */
 export function createPersistentState(config) {
     const { key, defaultValue, storage: storageType = 'localStorage', serialize = JSON.stringify, deserialize = JSON.parse, debounceMs = 300, version = 1 } = config;
     const storageKey = `urbicon_${key}_v${version}`;
     const storage = getStorage(storageType);
     // Initialize state with stored value or default
-    const initialValue = loadFromStorage();
-    const state = $state({ value: initialValue });
+    const initial = loadFromStorage();
+    const state = $state({ value: initial.value, hasStored: initial.stored });
+    // A faithful mirror of what storage holds: the exact stored string, or `null`
+    // when the key is absent (or unparseable). It must never claim the default is
+    // stored when it is not — that would make the absent → stored-empty
+    // transition unwritable, which is exactly the state this module exists to
+    // preserve (the user cleared the axis).
+    let lastWritten = initial.raw;
+    // Whether the consumer ever wrote through this instance. Only used to keep an
+    // *untouched* instance from creating an entry for its own default.
+    let touched = false;
+    const defaultSerialized = trySerialize(defaultValue);
+    function trySerialize(value) {
+        try {
+            return serialize(value);
+        }
+        catch {
+            return null;
+        }
+    }
     function loadFromStorage() {
         if (!storage)
-            return defaultValue;
+            return { value: defaultValue, stored: false, raw: null };
         try {
             const stored = storage.getItem(storageKey);
             if (stored === null)
-                return defaultValue;
-            return deserialize(stored);
+                return { value: defaultValue, stored: false, raw: null };
+            return { value: deserialize(stored), stored: true, raw: stored };
         }
         catch (error) {
             console.warn(`Failed to load persistent state for key "${key}":`, error);
-            return defaultValue;
+            // A corrupt entry counts as *absent*, never as "stored": consumers use
+            // `hasStoredValue` to let a stored value win over their own default or
+            // seed, and unparseable junk must not win — it would block that default
+            // forever. The junk itself is left in place until something is actually
+            // written (the first real write overwrites it); an untouched instance
+            // does not clean it up, and does not need to — it reads as absent.
+            return { value: defaultValue, stored: false, raw: null };
         }
     }
     function saveToStorage(value) {
         if (!storage)
             return;
         try {
-            storage.setItem(storageKey, serialize(value));
+            const next = serialize(value);
+            // Storage already holds exactly this — nothing to do.
+            if (next === lastWritten)
+                return;
+            // Never *create* an entry for a value nobody touched. Without this the
+            // auto-save effect below would write every key with its own default on
+            // mount, making `hasStoredValue` useless (an untouched default would be
+            // indistinguishable from a deliberately cleared one) and re-creating the
+            // entry `reset()` just removed. Once the consumer has written — including
+            // writing the default back, i.e. clearing — the write goes through, even
+            // if the key does not exist yet. `forceSave()` obeys the same rule on
+            // purpose: a blanket flush (the table exposes one) must not create an
+            // entry for every untouched axis, which would retire all their seeds.
+            if (!touched && lastWritten === null && next === defaultSerialized)
+                return;
+            storage.setItem(storageKey, next);
+            lastWritten = next;
+            state.hasStored = true;
         }
         catch (error) {
             console.warn(`Failed to save persistent state for key "${key}":`, error);
@@ -73,17 +128,44 @@ export function createPersistentState(config) {
             return state.value;
         },
         set value(newValue) {
+            // Mark the instance as written-to *before* the state change, so the
+            // auto-save effect it triggers knows this is a deliberate value — that is
+            // what lets clearing back to the default create an entry.
+            touched = true;
             state.value = newValue;
         },
+        /**
+         * Whether storage currently holds an entry for this key: `true` when
+         * construction (or `reload()`) found a parseable entry, and after a write
+         * actually reached storage; `false` when the key was absent or corrupt,
+         * after `reset()`, and always without a working storage (SSR, private
+         * mode). Use it to distinguish a stored empty value from an absent one.
+         */
+        get hasStoredValue() {
+            return state.hasStored;
+        },
         /**
          * Reset to default value and clear storage
          */
         reset() {
             state.value = defaultValue;
-            storage?.removeItem(storageKey);
+            try {
+                storage?.removeItem(storageKey);
+            }
+            catch (error) {
+                console.warn(`Failed to clear persistent state for key "${key}":`, error);
+            }
+            state.hasStored = false;
+            // Back to "nothing stored", and untouched again — so the auto-save
+            // triggered by the assignment above does not immediately re-create the
+            // key we just removed. A later write (including clearing) still lands.
+            lastWritten = null;
+            touched = false;
         },
         /**
-         * Force immediate save (bypasses debounce)
+         * Force immediate save (bypasses debounce). A no-op when storage already
+         * holds exactly this value, and — like the auto-save — when the instance
+         * was never written to and still holds its default.
          */
         forceSave() {
             saveToStorage(state.value);
@@ -92,7 +174,13 @@ export function createPersistentState(config) {
          * Reload from storage
          */
         reload() {
-            state.value = loadFromStorage();
+            const next = loadFromStorage();
+            state.value = next.value;
+            state.hasStored = next.stored;
+            lastWritten = next.raw;
+            // The value now mirrors storage again; nothing here came from the
+            // consumer, so an absent key stays absent until the next real write.
+            touched = false;
         }
     };
 }

package/docs/MIGRATION-v5.md

@@ -80,6 +80,35 @@ The dead `tableVariants` export is removed (was unused in any consumer).
 <Table data={rows} columns={cols} />
 ```
 
+## 3b. Table state snippets renamed (v6.41)
+
+The Table's three state snippets are renamed to match the slot names they
+already had in `slotClasses` (`emptyState` / `loadingState` / `errorState`).
+That frees `loading` and `error` for the state props they are everywhere else
+in the library — the Table can now be told it is loading or has failed, which
+previously only the managed `queryFn` path could do.
+
+| Before (snippet) | After (snippet) | Freed prop             |
+| ---------------- | --------------- | ---------------------- |
+| `empty`          | `emptyState`    | —                      |
+| `loading`        | `loadingState`  | `loading?: boolean`    |
+| `error`          | `errorState`    | `error?: string\|null` |
+
+```svelte
+<!-- before -->
+<Table {items} {columns}>
+  {#snippet empty()}<tr><td colspan="99">Nothing here</td></tr>{/snippet}
+</Table>
+
+<!-- after — plus the new state props for data you fetch yourself -->
+<Table {items} {columns} loading={pending} error={failure}>
+  {#snippet emptyState()}<tr><td colspan="99">Nothing here</td></tr>{/snippet}
+</Table>
+```
+
+With a managed `queryFn` the table still owns both states and ignores the two
+props (DEV warns).
+
 ## 4. Dialog + Drawer intent
 
 Dialog and Drawer no longer draw a coloured `border-t-[3px]` accent for