@urbicon-ui/blocks 6.21.1 → 6.21.3

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

@@ -1,18 +1,18 @@
 import { type SlotNames, type VariantProps } from '../../utils/variants.js';
 export declare const tooltipVariants: ((props?: {
-    visible?: boolean | undefined;
+    open?: boolean | undefined;
     intent?: "primary" | "secondary" | "info" | "success" | "warning" | "danger" | "neutral" | undefined;
     size?: "sm" | "md" | "lg" | undefined;
 } | undefined) => {
     base: (props?: ({
-        visible?: boolean | undefined;
+        open?: boolean | undefined;
         intent?: "primary" | "secondary" | "info" | "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?: ({
-        visible?: boolean | undefined;
+        open?: boolean | undefined;
         intent?: "primary" | "secondary" | "info" | "success" | "warning" | "danger" | "neutral" | undefined;
         size?: "sm" | "md" | "lg" | undefined;
     } & {
@@ -21,6 +21,6 @@ export declare const tooltipVariants: ((props?: {
 }) & {
     readonly config: import("../../utils/variants.js").TVConfig;
 };
-export type TooltipVariants = Omit<VariantProps<typeof tooltipVariants>, 'visible'>;
+export type TooltipVariants = Omit<VariantProps<typeof tooltipVariants>, 'open'>;
 /** Slot names derived from the `tv()` config above — single source of truth for `slotClasses`. */
 export type TooltipSlots = SlotNames<typeof tooltipVariants>;

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

@@ -33,7 +33,7 @@ export const tooltipVariants = tv({
         arrow: ['absolute w-2 h-2', 'bg-inherit transform rotate-45']
     },
     variants: {
-        visible: {
+        open: {
             true: { base: 'opacity-100' },
             false: { base: 'opacity-0' }
         },
@@ -53,7 +53,7 @@ export const tooltipVariants = tv({
         }
     },
     defaultVariants: {
-        visible: false,
+        open: false,
         intent: 'neutral',
         size: 'md'
     }

package/dist/primitives/index.d.ts

@@ -18,7 +18,7 @@ export type { CheckboxProps } from './Checkbox/index.js';
 export * from './Checkbox/index.js';
 export type { CollapsibleProps } from './Collapsible/index.js';
 export * from './Collapsible/index.js';
-export type { ComboboxOptionType, ComboboxProps } from './Combobox/index.js';
+export type { ComboboxGroup, ComboboxOptionType, ComboboxProps } from './Combobox/index.js';
 export * from './Combobox/index.js';
 export type { ConfirmDialogProps, ConfirmIntent } from './ConfirmDialog/index.js';
 export * from './ConfirmDialog/index.js';
@@ -34,7 +34,7 @@ export type { JourneyNode, JourneyStatus, JourneyTimelineProps } from './Journey
 export * from './JourneyTimeline/index.js';
 export type { MenuContext, MenuCustomSlots, MenuItemType, MenuObjectOption, MenuOption, MenuProps, MenuSectionHeader } from './Menu/index.js';
 export * from './Menu/index.js';
-export type { PaginationItemProps, PaginationProps } from './Pagination/index.js';
+export type { PaginationItemContext, PaginationItemProps, PaginationProps } from './Pagination/index.js';
 export * from './Pagination/index.js';
 export * from './Popover/index.js';
 export type { ProgressProps } from './Progress/index.js';
@@ -61,7 +61,7 @@ export type { TabItemProps, TabPanelProps, TabProps } from './Tab/index.js';
 export * from './Tab/index.js';
 export type { TextareaProps } from './Textarea/index.js';
 export * from './Textarea/index.js';
-export type { ToastData, ToastInput, ToastIntent, ToastPlacement, ToastProps, ToastShorthandOpts } from './Toast/index.js';
+export type { ToastAction, ToastData, ToastInput, ToastIntent, ToastPlacement, ToastPromiseOptions, ToastProps, ToastShorthandOpts } from './Toast/index.js';
 export * from './Toast/index.js';
 export { TOAST_INTENTS } from './Toast/index.js';
 export type { ToggleProps } from './Toggle/index.js';

package/dist/style/semantic.css

@@ -183,7 +183,12 @@
 
   /* === SHADOWS ===
      Dark mode uses higher alpha to compensate for low contrast against
-     dark surfaces. light-dark() handles the whole multi-layer shadow.
+     dark surfaces. light-dark() may wrap ONLY the per-layer <color> —
+     it is a color function, and layers must stay top-level
+     comma-separated. Wrapping the whole multi-layer list made every
+     `box-shadow: var(--blocks-shadow-*)` invalid at computed-value time
+     (shadows silently rendered as none, library-wide) — verified in
+     chromium before the 2026-07-13 fix.
 
      The shadow tint (`--blocks-shadow-tint`) is an oklch L C H triplet
      WITHOUT the alpha channel — declared on `:root` (not inside @theme)
@@ -192,34 +197,55 @@
      their shadow palette — e.g. editorial sets it to a dark brown so
      shadows blend with cream surfaces instead of reading as cool
      smudges. */
-  --color-shadow-xs: light-dark(
-    0 1px 2px 0 oklch(var(--blocks-shadow-tint) / 0.05),
-    0 1px 2px 0 oklch(var(--blocks-shadow-tint) / 0.2)
-  );
-  --color-shadow-sm: light-dark(
-    0 1px 3px 0 oklch(var(--blocks-shadow-tint) / 0.1) 0 1px 2px -1px
-      oklch(var(--blocks-shadow-tint) / 0.1),
-    0 1px 3px 0 oklch(var(--blocks-shadow-tint) / 0.3) 0 1px 2px -1px
-      oklch(var(--blocks-shadow-tint) / 0.3)
-  );
-  --color-shadow-base: light-dark(
-    0 4px 6px -1px oklch(var(--blocks-shadow-tint) / 0.1) 0 2px 4px -2px
-      oklch(var(--blocks-shadow-tint) / 0.1),
-    0 4px 6px -1px oklch(var(--blocks-shadow-tint) / 0.4) 0 2px 4px -2px
-      oklch(var(--blocks-shadow-tint) / 0.4)
-  );
-  --color-shadow-md: light-dark(
-    0 10px 15px -3px oklch(var(--blocks-shadow-tint) / 0.1) 0 4px 6px -4px
-      oklch(var(--blocks-shadow-tint) / 0.1),
-    0 10px 15px -3px oklch(var(--blocks-shadow-tint) / 0.4) 0 4px 6px -4px
-      oklch(var(--blocks-shadow-tint) / 0.4)
-  );
-  --color-shadow-lg: light-dark(
-    0 20px 25px -5px oklch(var(--blocks-shadow-tint) / 0.1) 0 8px 10px -6px
-      oklch(var(--blocks-shadow-tint) / 0.1),
-    0 20px 25px -5px oklch(var(--blocks-shadow-tint) / 0.5) 0 8px 10px -6px
-      oklch(var(--blocks-shadow-tint) / 0.5)
-  );
+  --color-shadow-xs: 0 1px 2px 0
+    light-dark(
+      oklch(var(--blocks-shadow-tint) / 0.05),
+      oklch(var(--blocks-shadow-tint) / 0.2)
+    );
+  --color-shadow-sm:
+    0 1px 3px 0
+      light-dark(
+        oklch(var(--blocks-shadow-tint) / 0.1),
+        oklch(var(--blocks-shadow-tint) / 0.3)
+      ),
+    0 1px 2px -1px
+      light-dark(
+        oklch(var(--blocks-shadow-tint) / 0.1),
+        oklch(var(--blocks-shadow-tint) / 0.3)
+      );
+  --color-shadow-base:
+    0 4px 6px -1px
+      light-dark(
+        oklch(var(--blocks-shadow-tint) / 0.1),
+        oklch(var(--blocks-shadow-tint) / 0.4)
+      ),
+    0 2px 4px -2px
+      light-dark(
+        oklch(var(--blocks-shadow-tint) / 0.1),
+        oklch(var(--blocks-shadow-tint) / 0.4)
+      );
+  --color-shadow-md:
+    0 10px 15px -3px
+      light-dark(
+        oklch(var(--blocks-shadow-tint) / 0.1),
+        oklch(var(--blocks-shadow-tint) / 0.4)
+      ),
+    0 4px 6px -4px
+      light-dark(
+        oklch(var(--blocks-shadow-tint) / 0.1),
+        oklch(var(--blocks-shadow-tint) / 0.4)
+      );
+  --color-shadow-lg:
+    0 20px 25px -5px
+      light-dark(
+        oklch(var(--blocks-shadow-tint) / 0.1),
+        oklch(var(--blocks-shadow-tint) / 0.5)
+      ),
+    0 8px 10px -6px
+      light-dark(
+        oklch(var(--blocks-shadow-tint) / 0.1),
+        oklch(var(--blocks-shadow-tint) / 0.5)
+      );
 }
 
 /* Shadow tint — declared on :root rather than inside @theme because

package/dist/translations/de.d.ts

@@ -1,6 +1,8 @@
 declare const _default: {
     readonly accessibility: {
         readonly avatar: "Avatar";
+        readonly breadcrumb: "Pfadnavigation";
+        readonly breadcrumbExpand: "Alle Pfadebenen anzeigen";
         readonly clearInput: "Eingabe löschen";
         readonly clearSearch: "Suche löschen";
         readonly clearSelection: "Auswahl löschen";
@@ -19,6 +21,7 @@ declare const _default: {
         readonly removableBadge: "Entfernbarer Badge";
         readonly removeBadge: "Badge entfernen";
         readonly removeFile: "{{name}} entfernen";
+        readonly removeTag: "{{label}} entfernen";
     };
     readonly button: {
         readonly close: "Schließen";

package/dist/translations/de.js

@@ -1,6 +1,8 @@
 export default {
     accessibility: {
         avatar: 'Avatar',
+        breadcrumb: 'Pfadnavigation',
+        breadcrumbExpand: 'Alle Pfadebenen anzeigen',
         clearInput: 'Eingabe löschen',
         clearSearch: 'Suche löschen',
         clearSelection: 'Auswahl löschen',
@@ -18,7 +20,8 @@ export default {
         toggleOptions: 'Optionen umschalten',
         removableBadge: 'Entfernbarer Badge',
         removeBadge: 'Badge entfernen',
-        removeFile: '{{name}} entfernen'
+        removeFile: '{{name}} entfernen',
+        removeTag: '{{label}} entfernen'
     },
     button: {
         close: 'Schließen',

package/dist/translations/en.d.ts

@@ -1,6 +1,8 @@
 declare const _default: {
     readonly accessibility: {
         readonly avatar: "Avatar";
+        readonly breadcrumb: "Breadcrumb";
+        readonly breadcrumbExpand: "Show all breadcrumb items";
         readonly clearInput: "Clear input";
         readonly clearSearch: "Clear search";
         readonly clearSelection: "Clear selection";
@@ -19,6 +21,7 @@ declare const _default: {
         readonly removableBadge: "Removable badge";
         readonly removeBadge: "Remove badge";
         readonly removeFile: "Remove {{name}}";
+        readonly removeTag: "Remove {{label}}";
     };
     readonly button: {
         readonly close: "Close";

package/dist/translations/en.js

@@ -1,6 +1,8 @@
 export default {
     accessibility: {
         avatar: 'Avatar',
+        breadcrumb: 'Breadcrumb',
+        breadcrumbExpand: 'Show all breadcrumb items',
         clearInput: 'Clear input',
         clearSearch: 'Clear search',
         clearSelection: 'Clear selection',
@@ -18,7 +20,8 @@ export default {
         toggleOptions: 'Toggle options',
         removableBadge: 'Removable badge',
         removeBadge: 'Remove badge',
-        removeFile: 'Remove {{name}}'
+        removeFile: 'Remove {{name}}',
+        removeTag: 'Remove {{label}}'
     },
     button: {
         close: 'Close',

package/dist/utils/figma-token-export.d.ts

@@ -4,6 +4,19 @@
  * Generates a Tokens Studio-compatible JSON export from the Urbicon UI
  * OKLCH design token system. Suitable for Figma plugins like "Tokens Studio
  * for Figma" (formerly Figma Tokens).
+ *
+ * The values below mirror the token truth in `../style/foundation.css`
+ * (palettes, radii) and `../style/semantic.css` (surface/text/border roles,
+ * shadows). They are hardcoded — this module runs in the browser and cannot
+ * read the CSS files at runtime — but guarded against drift by the
+ * co-located `figma-token-export.test.ts`, which parses both CSS files and
+ * compares every value. If you change a token in the CSS, that test fails
+ * until the export here is updated to match.
+ *
+ * Semantic tokens resolve light/dark via CSS `light-dark()`; this export
+ * carries the **light-mode** resolution (Figma has no mode-aware token
+ * values in plain Tokens Studio JSON). Dark mode swaps at the foundation
+ * layer, so the palette ramps below contain every shade both modes use.
  */
 export interface FigmaToken {
     value: string;

package/dist/utils/figma-token-export.js

@@ -4,10 +4,24 @@
  * Generates a Tokens Studio-compatible JSON export from the Urbicon UI
  * OKLCH design token system. Suitable for Figma plugins like "Tokens Studio
  * for Figma" (formerly Figma Tokens).
+ *
+ * The values below mirror the token truth in `../style/foundation.css`
+ * (palettes, radii) and `../style/semantic.css` (surface/text/border roles,
+ * shadows). They are hardcoded — this module runs in the browser and cannot
+ * read the CSS files at runtime — but guarded against drift by the
+ * co-located `figma-token-export.test.ts`, which parses both CSS files and
+ * compares every value. If you change a token in the CSS, that test fails
+ * until the export here is updated to match.
+ *
+ * Semantic tokens resolve light/dark via CSS `light-dark()`; this export
+ * carries the **light-mode** resolution (Figma has no mode-aware token
+ * values in plain Tokens Studio JSON). Dark mode swaps at the foundation
+ * layer, so the palette ramps below contain every shade both modes use.
  */
 const foundationColors = {
     neutral: {
         '0': 'oklch(1 0 0)',
+        '25': 'oklch(0.99 0.002 240)',
         '50': 'oklch(0.98 0.005 240)',
         '100': 'oklch(0.95 0.008 240)',
         '200': 'oklch(0.89 0.012 240)',
@@ -15,8 +29,11 @@ const foundationColors = {
         '400': 'oklch(0.7 0.015 240)',
         '500': 'oklch(0.55 0.016 240)',
         '600': 'oklch(0.42 0.017 240)',
+        '650': 'oklch(0.38 0.016 240)',
         '700': 'oklch(0.32 0.016 240)',
+        '750': 'oklch(0.28 0.014 240)',
         '800': 'oklch(0.23 0.015 240)',
+        '850': 'oklch(0.18 0.014 240)',
         '900': 'oklch(0.15 0.012 240)',
         '950': 'oklch(0.08 0.008 240)'
     },
@@ -46,18 +63,33 @@ const foundationColors = {
         '900': 'oklch(0.25 0.08 280)',
         '950': 'oklch(0.18 0.05 280)'
     },
+    'warm-neutral': {
+        '50': 'oklch(0.96 0.004 45)',
+        '100': 'oklch(0.92 0.006 45)',
+        '200': 'oklch(0.86 0.008 45)',
+        '300': 'oklch(0.78 0.01 45)',
+        '400': 'oklch(0.65 0.012 45)',
+        '500': 'oklch(0.5 0.008 45)',
+        '600': 'oklch(0.42 0.01 45)',
+        '700': 'oklch(0.35 0.012 45)',
+        '800': 'oklch(0.28 0.01 45)',
+        '900': 'oklch(0.2 0.008 45)',
+        '950': 'oklch(0.12 0.006 45)'
+    },
+    /* success/danger 400–700 are the WCAG-darkened ramps: white text on the
+       solid intent backgrounds passes AA (4.5:1). */
     success: {
         '50': 'oklch(0.95 0.03 140)',
         '100': 'oklch(0.9 0.05 140)',
         '200': 'oklch(0.82 0.08 140)',
         '300': 'oklch(0.74 0.11 140)',
-        '400': 'oklch(0.66 0.13 140)',
-        '500': 'oklch(0.65 0.15 140)',
-        '600': 'oklch(0.55 0.15 140)',
-        '700': 'oklch(0.45 0.13 140)',
-        '800': 'oklch(0.35 0.11 140)',
-        '900': 'oklch(0.25 0.08 140)',
-        '950': 'oklch(0.15 0.05 140)'
+        '400': 'oklch(0.62 0.14 140)',
+        '500': 'oklch(0.5 0.15 140)',
+        '600': 'oklch(0.44 0.14 140)',
+        '700': 'oklch(0.38 0.12 140)',
+        '800': 'oklch(0.3 0.1 140)',
+        '900': 'oklch(0.22 0.08 140)',
+        '950': 'oklch(0.14 0.05 140)'
     },
     warning: {
         '50': 'oklch(0.95 0.05 80)',
@@ -77,39 +109,67 @@ const foundationColors = {
         '100': 'oklch(0.9 0.08 25)',
         '200': 'oklch(0.82 0.1 25)',
         '300': 'oklch(0.74 0.12 25)',
-        '400': 'oklch(0.66 0.14 25)',
-        '500': 'oklch(0.65 0.18 25)',
-        '600': 'oklch(0.55 0.15 25)',
-        '700': 'oklch(0.45 0.13 25)',
-        '800': 'oklch(0.35 0.11 25)',
-        '900': 'oklch(0.25 0.08 25)',
-        '950': 'oklch(0.15 0.05 25)'
+        '400': 'oklch(0.62 0.16 25)',
+        '500': 'oklch(0.5 0.17 25)',
+        '600': 'oklch(0.44 0.16 25)',
+        '700': 'oklch(0.38 0.14 25)',
+        '800': 'oklch(0.3 0.12 25)',
+        '900': 'oklch(0.22 0.1 25)',
+        '950': 'oklch(0.14 0.07 25)'
+    },
+    info: {
+        '50': 'oklch(0.96 0.025 220)',
+        '100': 'oklch(0.92 0.045 220)',
+        '200': 'oklch(0.84 0.075 220)',
+        '300': 'oklch(0.76 0.105 220)',
+        '400': 'oklch(0.66 0.13 220)',
+        '500': 'oklch(0.55 0.14 220)',
+        '600': 'oklch(0.48 0.13 220)',
+        '700': 'oklch(0.4 0.11 220)',
+        '800': 'oklch(0.32 0.09 220)',
+        '900': 'oklch(0.24 0.07 220)',
+        '950': 'oklch(0.16 0.05 220)'
     }
 };
+/** Light-mode resolution of the semantic color roles in semantic.css. */
 const semanticTokens = {
     surface: {
-        base: { value: '{color.neutral.0}', description: 'Page background' },
-        raised: { value: '{color.neutral.50}', description: 'Slightly elevated surface' },
-        elevated: { value: '{color.neutral.50}', description: 'Elevated surface (cards)' },
-        overlay: { value: '{color.neutral.0}', description: 'Dialog/popover background' },
+        base: { value: '{color.neutral.0}', description: 'L1 — the page itself' },
+        quiet: { value: '{color.neutral.25}', description: 'L0 — ground beneath the page' },
+        elevated: { value: '{color.neutral.50}', description: 'L2 — lifted surfaces (popover, menu)' },
+        overlay: { value: '{color.neutral.0}', description: 'L3 — dialog/drawer/toast background' },
+        interactive: { value: '{color.neutral.100}', description: 'Interactive control background' },
+        hover: { value: '{color.neutral.100}', description: 'Hover state background' },
+        active: { value: '{color.neutral.200}', description: 'Active/pressed state background' },
+        disabled: { value: '{color.neutral.100}', description: 'Disabled surface' },
+        selected: { value: '{color.primary.50}', description: 'Selected item background' },
         subtle: { value: '{color.neutral.50}', description: 'Subtle background' },
         inverted: { value: '{color.neutral.900}', description: 'Inverted surface' }
     },
     text: {
         primary: { value: '{color.neutral.900}', description: 'Primary text' },
+        inverted: { value: '{color.neutral.0}', description: 'Inverted text (on dark bg)' },
         secondary: { value: '{color.neutral.700}', description: 'Secondary text' },
-        tertiary: { value: '{color.neutral.500}', description: 'Tertiary text' },
+        tertiary: { value: '{color.neutral.600}', description: 'Tertiary text (WCAG AA on base)' },
+        quaternary: { value: '{color.neutral.500}', description: 'Quaternary text (lowest emphasis)' },
         disabled: { value: '{color.neutral.300}', description: 'Disabled text' },
-        inverted: { value: '{color.neutral.0}', description: 'Inverted text (on dark bg)' },
-        'on-primary': { value: '{color.neutral.0}', description: 'Text on primary color bg' }
+        'on-dark': { value: '{color.neutral.0}', description: 'Text on dark surfaces' },
+        'on-primary': { value: '{color.neutral.0}', description: 'Text on primary color bg' },
+        'on-surface': { value: '{color.neutral.900}', description: 'Text on tinted surfaces' }
     },
     border: {
+        hairline: {
+            value: 'rgb(0 0 0 / 0.08)',
+            description: 'Quietest structural divider (rows, separators)'
+        },
         subtle: { value: '{color.neutral.200}', description: 'Subtle border' },
         default: { value: '{color.neutral.300}', description: 'Default border' },
         emphasis: { value: '{color.neutral.400}', description: 'Emphasized border' },
         strong: { value: '{color.neutral.500}', description: 'Strong border' }
     }
 };
+/* Tailwind 4 default spacing scale (4px per unit) — blocks defines no
+   custom spacing tokens. */
 const spacingTokens = {
     '0': '0',
     '1': '4px',
@@ -123,14 +183,24 @@ const spacingTokens = {
     '12': '48px',
     '16': '64px'
 };
+/* Physical radius scale + the semantic 3-tier vocabulary (commit/modify/
+   contain, plus the bridge adjacency radius) from foundation.css.
+   rem values are exported as px (1rem = 16px) for Figma. */
 const borderRadiusTokens = {
-    none: '0',
-    sm: '2px',
+    xs: '2px',
+    sm: '4px',
     md: '6px',
     lg: '8px',
     xl: '12px',
-    full: '9999px'
+    '2xl': '16px',
+    '3xl': '24px',
+    '4xl': '32px',
+    commit: { value: '9999px', description: 'Tier: actions, identity, status (pill)' },
+    modify: { value: '{borderRadius.sm}', description: 'Tier: editable surfaces, navigation' },
+    contain: { value: '{borderRadius.xs}', description: 'Tier: containers, panels, layout' },
+    bridge: { value: '{borderRadius.md}', description: 'Adjacency radius: panel anchored to a pill' }
 };
+/** Light-mode resolution of the shadow tokens (shadow tint = pure black). */
 const shadowTokens = {
     xs: '0 1px 2px 0 rgba(0,0,0,0.05)',
     sm: '0 1px 3px 0 rgba(0,0,0,0.1), 0 1px 2px -1px rgba(0,0,0,0.1)',
@@ -174,8 +244,11 @@ function buildSpacingTokens() {
 }
 function buildBorderRadiusTokens() {
     const result = {};
-    for (const [name, value] of Object.entries(borderRadiusTokens)) {
-        result[name] = { value, type: 'borderRadius' };
+    for (const [name, def] of Object.entries(borderRadiusTokens)) {
+        result[name] =
+            typeof def === 'string'
+                ? { value: def, type: 'borderRadius' }
+                : { value: def.value, type: 'borderRadius', description: def.description };
     }
     return result;
 }

package/dist/utils/guide.svelte.d.ts

@@ -103,8 +103,14 @@ export interface GuideTour {
  * consumer can inject a server-state adapter. Kept deliberately tiny.
  */
 export interface GuideStorageAdapter {
-    /** Returns the persisted set of seen/completed ids. */
-    load(): string[];
+    /**
+     * Returns the persisted set of seen/completed ids. Return a `string[]`
+     * synchronously (localStorage, the default) or a `Promise<string[]>` for a
+     * DB-/remote-backed store. While an async load is pending the seen set starts
+     * empty and is merged (union) with the resolved ids once they arrive — so a
+     * tour may briefly be startable before the store answers.
+     */
+    load(): string[] | Promise<string[]>;
     /** Persists the full set of seen/completed ids. */
     save(ids: string[]): void;
 }

package/dist/utils/guide.svelte.js

@@ -156,6 +156,22 @@ export class GuideController {
     #targets = new SvelteMap();
     /** Persisted "seen" ids. */
     #seen;
+    /** False only while an async `storage.load()` is still pending. */
+    #seenLoaded = true;
+    /**
+     * Set when the user writes (markSeen/resetSeen) while an async load is still
+     * pending, so the load's `.then` persists the merged union once — writing
+     * mid-load directly would clobber the remote store before its ids are merged in.
+     */
+    #pendingSeenWrite = false;
+    /**
+     * Ids the user forgot during the load window, so the merge doesn't resurrect
+     * them from the freshly-loaded remote set. A plain `Set` — pure bookkeeping,
+     * never rendered, so the `SvelteSet` rule doesn't apply.
+     */
+    #pendingRemovals = new Set();
+    /** `resetSeen()` (clear-all) during the load window: drop the remote set entirely. */
+    #pendingClearAll = false;
     #storage;
     #overlayStack;
     #dev;
@@ -209,7 +225,58 @@ export class GuideController {
         // `?? false` keeps `#dev` a strict boolean and means non-Vite consumers
         // simply get no dev warnings (rather than a crash).
         this.#dev = options.dev ?? import.meta.env?.DEV ?? false;
-        this.#seen = new SvelteSet(this.#storage.load());
+        // Sync adapters (localStorage) seed the set immediately. Async adapters
+        // (DB/remote) start empty and get their ids merged in when the promise
+        // settles — union, not replace, so anything marked seen in the meantime
+        // survives. A rejected load is swallowed (dev-warned): the tour just stays
+        // "unseen", which fails open rather than hiding help behind a broken store.
+        const loaded = this.#storage.load();
+        if (Array.isArray(loaded)) {
+            this.#seen = new SvelteSet(loaded);
+        }
+        else {
+            this.#seen = new SvelteSet();
+            this.#seenLoaded = false;
+            loaded
+                .then((ids) => {
+                // Merge the loaded set in, but honour writes made during the window:
+                // skip everything if the user cleared all, and don't resurrect ids the
+                // user explicitly forgot. Adds are safe (union is idempotent).
+                if (!this.#pendingClearAll) {
+                    for (const id of ids) {
+                        if (!this.#pendingRemovals.has(id))
+                            this.#seen.add(id);
+                    }
+                }
+                this.#seenLoaded = true;
+                // Reconcile persistence: if the user wrote during the window, the store
+                // still holds the pre-merge state (we deliberately didn't save then), so
+                // persist the union now. Nothing wrote → leave the store untouched (no
+                // write-amplification of a remote we just read).
+                if (this.#pendingSeenWrite)
+                    this.#storage.save([...this.#seen]);
+            })
+                .catch((err) => {
+                // Read failed: fail open (tour stays "unseen"). We don't persist the
+                // window's in-memory writes here — the store is in an unknown state, and
+                // blindly saving could destroy data we simply couldn't read ("read
+                // tolerant, write strict"). Later writes persist normally.
+                this.#seenLoaded = true;
+                if (this.#dev)
+                    console.warn('[Guide] storage.load() rejected:', err);
+            });
+        }
+    }
+    /**
+     * Persist the seen-set — unless an async load is still pending, in which case a
+     * direct save would clobber the not-yet-loaded remote store. Defer to the load's
+     * `.then` reconciliation instead (see the constructor).
+     */
+    #persistSeen() {
+        if (this.#seenLoaded)
+            this.#storage.save([...this.#seen]);
+        else
+            this.#pendingSeenWrite = true;
     }
     // ─── Target registry ──────────────────────────────────────────────────────
     /**
@@ -738,15 +805,29 @@ export class GuideController {
         if (this.#seen.has(id))
             return;
         this.#seen.add(id);
-        this.#storage.save([...this.#seen]);
+        // Re-seeing an id undoes a forget that's still pending reconciliation.
+        if (!this.#seenLoaded)
+            this.#pendingRemovals.delete(id);
+        this.#persistSeen();
     }
     /** Forget one id, or all of them when called without an argument. */
     resetSeen(id) {
-        if (id === undefined)
+        if (id === undefined) {
             this.#seen.clear();
-        else
+            // Clear-all during a pending load must survive the merge: drop the whole
+            // remote set, superseding any earlier pending removals.
+            if (!this.#seenLoaded) {
+                this.#pendingClearAll = true;
+                this.#pendingRemovals.clear();
+            }
+        }
+        else {
             this.#seen.delete(id);
-        this.#storage.save([...this.#seen]);
+            // Record the forget so the pending-load merge doesn't resurrect it.
+            if (!this.#seenLoaded)
+                this.#pendingRemovals.add(id);
+        }
+        this.#persistSeen();
     }
     /** Snapshot of all seen ids. */
     get seenIds() {