@custardui/custardui 1.0.0

package/dist/types/src/lib/features/settings/types.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Configuration for the settings widget panel.
+ */
+export interface WidgetPanelConfig {
+    /** Widget title */
+    title?: string;
+    /** Widget description text */
+    description?: string;
+    /** Whether to show tab groups section in widget (default: true) */
+    showTabGroups?: boolean;
+    /** Whether to show reset button */
+    showReset?: boolean;
+    /** Widget theme */
+    theme?: 'light' | 'dark';
+}
+/**
+ * Configuration for the widget callout message.
+ */
+export interface WidgetCalloutConfig {
+    /** Whether to show the callout (default: false) */
+    show?: boolean;
+    /** Message to display in the callout */
+    message?: string;
+    /** Whether to enable pulse animation */
+    enablePulse?: boolean;
+    /** Custom background color */
+    backgroundColor?: string | undefined;
+    /** Custom text color */
+    textColor?: string | undefined;
+}
+/**
+ * Configuration for the widget icon appearance.
+ */
+export interface WidgetIconConfig {
+    /** Widget position */
+    position?: 'top-right' | 'top-left' | 'bottom-right' | 'bottom-left' | 'middle-left' | 'middle-right';
+    /** Custom icon color */
+    color?: string | undefined;
+    /** Custom background color */
+    backgroundColor?: string | undefined;
+    /** Custom opacity (0-1) */
+    opacity?: number | undefined;
+    /** Custom scale factor */
+    scale?: number;
+    /** Whether to show the icon (default: true) */
+    show?: boolean;
+}
+/**
+ * Top-level settings for the widget.
+ */
+export interface WidgetSettings {
+    /** Whether the settings widget is enabled */
+    enabled?: boolean;
+    /** Settings panel configuration */
+    panel?: WidgetPanelConfig;
+    /** Callout configuration options */
+    callout?: WidgetCalloutConfig;
+    /** Custom icon styling options */
+    icon?: WidgetIconConfig;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types/src/lib/features/settings/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../../../src/lib/features/settings/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,mBAAmB;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,8BAA8B;IAC9B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,mEAAmE;IACnE,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,mCAAmC;IACnC,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,mBAAmB;IACnB,KAAK,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,mDAAmD;IACnD,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,wCAAwC;IACxC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,wCAAwC;IACxC,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,8BAA8B;IAC9B,eAAe,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACrC,wBAAwB;IACxB,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAChC;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,sBAAsB;IACtB,QAAQ,CAAC,EACL,WAAW,GACX,UAAU,GACV,cAAc,GACd,aAAa,GACb,aAAa,GACb,cAAc,CAAC;IACnB,wBAAwB;IACxB,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,8BAA8B;IAC9B,eAAe,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACrC,2BAA2B;IAC3B,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,0BAA0B;IAC1B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,+CAA+C;IAC/C,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,6CAA6C;IAC7C,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,mCAAmC;IACnC,KAAK,CAAC,EAAE,iBAAiB,CAAC;IAC1B,oCAAoC;IACpC,OAAO,CAAC,EAAE,mBAAmB,CAAC;IAC9B,kCAAkC;IAClC,IAAI,CAAC,EAAE,gBAAgB,CAAC;CACzB"}

package/dist/types/src/lib/features/share/constants.d.ts

@@ -0,0 +1,4 @@
+export declare const DEFAULT_EXCLUDED_TAGS: string[];
+export declare const DEFAULT_EXCLUDED_IDS: string[];
+export declare const CV_SHARE_IGNORE_ATTRIBUTE = "data-cv-share-ignore";
+//# sourceMappingURL=constants.d.ts.map

package/dist/types/src/lib/features/share/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../../../../../src/lib/features/share/constants.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,qBAAqB,UAAiD,CAAC;AACpF,eAAO,MAAM,oBAAoB,EAAE,MAAM,EAAO,CAAC;AACjD,eAAO,MAAM,yBAAyB,yBAAyB,CAAC"}

package/dist/types/src/lib/features/share/share-logic.d.ts

@@ -0,0 +1,36 @@
+import { SvelteSet } from 'svelte/reactivity';
+export declare const CV_CUSTOM_ELEMENTS = "cv-tabgroup, cv-toggle";
+export declare const SHAREABLE_SELECTOR: string;
+export declare const SELECTED_CLASS = "cv-share-selected";
+export declare const HIGHLIGHT_TARGET_CLASS = "cv-highlight-target";
+export declare const HIDE_SELECTED_CLASS = "cv-share-selected-hide";
+export declare const HIDE_HIGHLIGHT_TARGET_CLASS = "cv-highlight-target-hide";
+export declare const HIGHLIGHT_SELECTED_CLASS = "cv-share-selected-highlight";
+export declare const HIGHLIGHT_TARGET_MODE_CLASS = "cv-highlight-target-mode";
+export declare const GENERIC_WRAPPER_IDS: string[];
+/**
+ * Determines if an element is a generic div wrapper (like a div used for layout)
+ * that should effectively be "ignored" or treated transparently during selection.
+ */
+export declare function isGenericWrapper(el: HTMLElement): boolean;
+/**
+ * Calculates the new set of selected elements based on the current selection
+ * and the new element to toggle/select.
+ *
+ * Implements the logic:
+ * 1. If an ancestor is already selected, ignore the new selection (Scenario B).
+ * 2. If children of the new selection are already selected, remove them (Scenario A) and add the new one.
+ * 3. Otherwise, just add the new one.
+ */
+export declare function calculateNewSelection(currentSelection: SvelteSet<HTMLElement>, newElement: HTMLElement): {
+    updatedSelection: SvelteSet<HTMLElement>;
+    changesMade: boolean;
+};
+/**
+ * Checks if an element or any of its ancestors should be excluded from sharing.
+ * @param element The element to check
+ * @param excludedTags Set of tag names to exclude
+ * @param excludedIds Set of IDs to exclude
+ */
+export declare function isExcluded(element: HTMLElement | null, excludedTags?: Set<string>, excludedIds?: Set<string>): boolean;
+//# sourceMappingURL=share-logic.d.ts.map

package/dist/types/src/lib/features/share/share-logic.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"share-logic.d.ts","sourceRoot":"","sources":["../../../../../../src/lib/features/share/share-logic.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAG9C,eAAO,MAAM,kBAAkB,2BAA2B,CAAC;AAE3D,eAAO,MAAM,kBAAkB,QACgE,CAAC;AAEhG,eAAO,MAAM,cAAc,sBAAsB,CAAC;AAClD,eAAO,MAAM,sBAAsB,wBAAwB,CAAC;AAC5D,eAAO,MAAM,mBAAmB,2BAA2B,CAAC;AAC5D,eAAO,MAAM,2BAA2B,6BAA6B,CAAC;AACtE,eAAO,MAAM,wBAAwB,gCAAgC,CAAC;AACtE,eAAO,MAAM,2BAA2B,6BAA6B,CAAC;AAGtE,eAAO,MAAM,mBAAmB,UAA0C,CAAC;AAE3E;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,WAAW,GAAG,OAAO,CAiBzD;AAED;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CACnC,gBAAgB,EAAE,SAAS,CAAC,WAAW,CAAC,EACxC,UAAU,EAAE,WAAW,GACtB;IAAE,gBAAgB,EAAE,SAAS,CAAC,WAAW,CAAC,CAAC;IAAC,WAAW,EAAE,OAAO,CAAA;CAAE,CA2CpE;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CACxB,OAAO,EAAE,WAAW,GAAG,IAAI,EAC3B,YAAY,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,EAC1B,WAAW,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,GACxB,OAAO,CAuBT"}

package/dist/types/src/lib/features/share/stores/share-store.svelte.d.ts

@@ -0,0 +1,24 @@
+import { SvelteSet } from 'svelte/reactivity';
+export type SelectionMode = 'show' | 'hide' | 'highlight';
+export declare class ShareStore {
+    isActive: boolean;
+    selectionMode: SelectionMode;
+    selectedElements: SvelteSet<HTMLElement>;
+    currentHoverTarget: HTMLElement | null;
+    shareCount: number;
+    toggleActive(active?: boolean): void;
+    setSelectionMode(mode: SelectionMode): void;
+    updateBodyClass(): void;
+    setHoverTarget(target: HTMLElement | null): void;
+    toggleElementSelection(el: HTMLElement): void;
+    toggleMultipleElements(elements: HTMLElement[]): void;
+    clearAllSelections(): void;
+    private _addHighlightClass;
+    private _removeHighlightClass;
+    private _addSelectionClass;
+    private _removeSelectionClass;
+    generateLink(): void;
+    previewLink(): void;
+}
+export declare const shareStore: ShareStore;
+//# sourceMappingURL=share-store.svelte.d.ts.map

package/dist/types/src/lib/features/share/stores/share-store.svelte.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"share-store.svelte.d.ts","sourceRoot":"","sources":["../../../../../../../src/lib/features/share/stores/share-store.svelte.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAa9C,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,MAAM,GAAG,WAAW,CAAC;AAE1D,qBAAa,UAAU;IACrB,QAAQ,UAAiB;IACzB,aAAa,gBAAiC;IAC9C,gBAAgB,yBAAgE;IAChF,kBAAkB,qBAAoC;IAEtD,UAAU,SAAwC;IAElD,YAAY,CAAC,MAAM,CAAC,EAAE,OAAO;IAuB7B,gBAAgB,CAAC,IAAI,EAAE,aAAa;IAgBpC,eAAe;IASf,cAAc,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI;IAczC,sBAAsB,CAAC,EAAE,EAAE,WAAW;IAwBtC,sBAAsB,CAAC,QAAQ,EAAE,WAAW,EAAE;IAO9C,kBAAkB;IAKlB,OAAO,CAAC,kBAAkB;IAU1B,OAAO,CAAC,qBAAqB;IAQ7B,OAAO,CAAC,kBAAkB;IAU1B,OAAO,CAAC,qBAAqB;IAI7B,YAAY;IA4CZ,WAAW;CA2BZ;AAED,eAAO,MAAM,UAAU,YAAmB,CAAC"}

package/dist/types/src/lib/features/share/types.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Configuration for excluded tags and IDs in Share/Focus modes
+ */
+export interface ShareExclusions {
+    tags?: string[];
+    ids?: string[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types/src/lib/features/share/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../../../src/lib/features/share/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,EAAE,CAAC;CAChB"}

package/dist/types/src/lib/features/tabs/types.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Configuration for a single tab within a tab group
+ */
+export interface TabConfig {
+    /** Tab identifier */
+    tabId: string;
+    /** Display label for the tab */
+    label?: string;
+    /** Value to set the placeholder to when this tab is active */
+    placeholderValue?: string;
+}
+/**
+ * Configuration for a tab group
+ */
+export interface TabGroupConfig {
+    /** Group identifier (stable across the page) */
+    groupId: string;
+    /** Display name for widget/nav */
+    label?: string;
+    /** ID of the placeholder variable to bind this group's selection to */
+    placeholderId?: string;
+    /** Available tabs in this group */
+    tabs: TabConfig[];
+    /** Determines if the tab group is only shown on pages where it's used. */
+    isLocal?: boolean;
+    /** Optional description to display below label */
+    description?: string;
+    /** Default tab ID to select */
+    default?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types/src/lib/features/tabs/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../../../src/lib/features/tabs/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,qBAAqB;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,gCAAgC;IAChC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,8DAA8D;IAC9D,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,gDAAgD;IAChD,OAAO,EAAE,MAAM,CAAC;IAChB,kCAAkC;IAClC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,uEAAuE;IACvE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,mCAAmC;IACnC,IAAI,EAAE,SAAS,EAAE,CAAC;IAClB,0EAA0E;IAC1E,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,kDAAkD;IAClD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,+BAA+B;IAC/B,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB"}

package/dist/types/src/lib/features/toggles/types.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Configuration for a single toggle.
+ */
+export interface ToggleConfig {
+    /** Toggle identifier */
+    toggleId: string;
+    /** Display label for the toggle */
+    label?: string;
+    /** Determines if the toggle is only shown on pages where it's used. */
+    isLocal?: boolean;
+    /** Optional description to display below functionality */
+    description?: string;
+    /** Default state for this toggle: 'show', 'hide', or 'peek' */
+    default?: 'show' | 'hide' | 'peek';
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types/src/lib/features/toggles/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../../../src/lib/features/toggles/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,wBAAwB;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,mCAAmC;IACnC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,uEAAuE;IACvE,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,0DAA0D;IAC1D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,+DAA+D;IAC/D,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;CACpC"}

package/dist/types/src/lib/features/url/url-action-handler.d.ts

@@ -0,0 +1,22 @@
+import type { SelectionMode } from '$features/share/stores/share-store.svelte';
+export type UrlActionType = 'OPEN_MODAL' | 'START_SHARE';
+export interface UrlAction {
+    type: UrlActionType;
+    mode?: SelectionMode;
+    triggerKey: string;
+    triggerSource: 'query' | 'hash';
+}
+export declare class UrlActionHandler {
+    private static rules;
+    /**
+     * Pure function: Parses the URL and returns the detected action if any.
+     * Iterates through the registry of rules.
+     */
+    static detectAction(location: Pick<Location, 'search' | 'hash'>): UrlAction | null;
+    /**
+     * Pure function: Returns the clean URL string after removing the action trigger.
+     * Delegates cleanup to the appropriate rule.
+     */
+    static getCleanedUrl(location: Pick<Location, 'href' | 'search' | 'hash'>, action: UrlAction): string;
+}
+//# sourceMappingURL=url-action-handler.d.ts.map

package/dist/types/src/lib/features/url/url-action-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"url-action-handler.d.ts","sourceRoot":"","sources":["../../../../../../src/lib/features/url/url-action-handler.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,2CAA2C,CAAC;AAE/E,MAAM,MAAM,aAAa,GAAG,YAAY,GAAG,aAAa,CAAC;AAEzD,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,aAAa,CAAC;IACpB,IAAI,CAAC,EAAE,aAAa,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,OAAO,GAAG,MAAM,CAAC;CACjC;AAkHD,qBAAa,gBAAgB;IAE3B,OAAO,CAAC,MAAM,CAAC,KAAK,CAIlB;IAEF;;;OAGG;IACH,MAAM,CAAC,YAAY,CAAC,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,QAAQ,GAAG,MAAM,CAAC,GAAG,SAAS,GAAG,IAAI;IAQlF;;;OAGG;IACH,MAAM,CAAC,aAAa,CAClB,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,QAAQ,GAAG,MAAM,CAAC,EACpD,MAAM,EAAE,SAAS,GAChB,MAAM;CAQV"}

package/dist/types/src/lib/features/url/url-action-router.svelte.d.ts

@@ -0,0 +1,26 @@
+import type { SelectionMode } from '$features/share/stores/share-store.svelte';
+export interface RouterOptions {
+    onOpenModal: () => void;
+    onStartShare: (mode?: SelectionMode) => void;
+    checkSettingsEnabled: () => boolean;
+}
+/**
+ * UrlActionRouter
+ *
+ * Responsibilities:
+ * - Listens for URL changes (popstate, hashchange) and initial page loads.
+ * - Detects "action triggers" in the URL (e.g., `?cv-open`, `?cv-share-show`) via `UrlActionHandler`.
+ * - Invokes the appropriate callbacks (open modal, start share) based on the detected action.
+ * - Cleans the URL after processing the action to prevent re-triggering on reload.
+ *
+ * This service acts as the bridge between browser URL state and the CustardUI UI state.
+ */
+export declare class UrlActionRouter {
+    private options;
+    private boundCheck;
+    constructor(options: RouterOptions);
+    init(): void;
+    destroy(): void;
+    private checkURLForAction;
+}
+//# sourceMappingURL=url-action-router.svelte.d.ts.map

package/dist/types/src/lib/features/url/url-action-router.svelte.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"url-action-router.svelte.d.ts","sourceRoot":"","sources":["../../../../../../src/lib/features/url/url-action-router.svelte.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,2CAA2C,CAAC;AAE/E,MAAM,WAAW,aAAa;IAC5B,WAAW,EAAE,MAAM,IAAI,CAAC;IACxB,YAAY,EAAE,CAAC,IAAI,CAAC,EAAE,aAAa,KAAK,IAAI,CAAC;IAC7C,oBAAoB,EAAE,MAAM,OAAO,CAAC;CACrC;AAED;;;;;;;;;;GAUG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,OAAO,CAAgB;IAC/B,OAAO,CAAC,UAAU,CAAa;gBAEnB,OAAO,EAAE,aAAa;IAK3B,IAAI;IAMJ,OAAO;IAKd,OAAO,CAAC,iBAAiB;CAe1B"}

package/dist/types/src/lib/features/url/url-state-manager.d.ts

@@ -0,0 +1,67 @@
+import type { State } from '$lib/types/index';
+/** Parameters owned by FocusService — never touched by URLStateManager */
+declare const FOCUS_PARAMS: string[];
+declare const MANAGED_PARAMS: string[];
+/**
+ * Elements currently present and tracked on the page.
+ */
+export interface PageElements {
+    toggles: Iterable<string>;
+    tabGroups: Iterable<string>;
+    placeholders: Iterable<string>;
+}
+/**
+ * URL State Manager for CustardUI.
+ * Handles encoding/decoding of view states as human-readable URL parameters.
+ *
+ * URL Schema:
+ *   ?t-show=A,B        — toggle IDs to explicitly show
+ *   ?t-peek=C          — toggle IDs to explicitly peek
+ *   ?t-hide=D          — toggle IDs to explicitly hide
+ *   ?tabs=g1:t1,g2:t2  — tab group selections (groupId:tabId pairs)
+ *   ?ph=key:val        — placeholder values (key:encodedValue pairs)
+ *
+ * Precedence model (applied by ActiveStateStore, not here):
+ * - Persisted state is loaded first as a base.
+ * - URL parameters act as a sparse override on top of persisted state.
+ *   Only toggles/tabs/placeholders mentioned in the URL are affected.
+ * - Tab-group-derived placeholders are always re-derived from the active tab,
+ *   so the `?tabs=` param is the sole source of truth for those values.
+ *
+ * `parseURL` is used on page load to read inbound link state.
+ * `generateShareableURL` is used to produce a link for the clipboard.
+ *
+ * Focus params (cv-show, cv-hide, cv-highlight) remain owned by FocusService.
+ */
+export declare class URLStateManager {
+    /**
+     * Parses the current page URL into a sparse delta state object.
+     * Only fields present in the URL are populated; the rest are omitted.
+     * Returns null if none of the managed parameters are present.
+     */
+    static parseURL(): State | null;
+    /**
+     * Generates a shareable URL that encodes the full current state.
+     *
+     * Encodes every toggle on the page explicitly (shown, peeked, or hidden)
+     * so the recipient sees the exact same view regardless of their local settings.
+     *
+     * Tab-group-derived placeholders are omitted from the URL — they are implied
+     * by the `?tabs=` parameter and will be re-derived by the recipient's store.
+     *
+     * Toggles, tabs, and placeholders NOT present on the current page are omitted,
+     * preventing cross-page state pollution.
+     *
+     * @param currentState The full application state to encode.
+     * @param pageElements The active elements detected on the current page.
+     */
+    static generateShareableURL(currentState: State | null | undefined, pageElements?: PageElements): string;
+    /**
+     * Clears all managed parameters from the current browser URL.
+     * This is called after parsing so that shared configurations don't stick around in
+     * the address bar when the user subsequently interacts with the page or refreshes.
+     */
+    static clearURL(): void;
+}
+export { FOCUS_PARAMS, MANAGED_PARAMS };
+//# sourceMappingURL=url-state-manager.d.ts.map

package/dist/types/src/lib/features/url/url-state-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"url-state-manager.d.ts","sourceRoot":"","sources":["../../../../../../src/lib/features/url/url-state-manager.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAQ9C,0EAA0E;AAC1E,QAAA,MAAM,YAAY,UAAyC,CAAC;AAC5D,QAAA,MAAM,cAAc,UAAkF,CAAC;AAuLvG;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC1B,SAAS,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC5B,YAAY,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;CAChC;AA6ED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBAAa,eAAe;IAC1B;;;;OAIG;WACW,QAAQ,IAAI,KAAK,GAAG,IAAI;IAetC;;;;;;;;;;;;;;OAcG;WACW,oBAAoB,CAChC,YAAY,EAAE,KAAK,GAAG,IAAI,GAAG,SAAS,EACtC,YAAY,GAAE,YAA+D,GAC5E,MAAM;IAgBT;;;;OAIG;WACW,QAAQ,IAAI,IAAI;CAiB/B;AAGD,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,CAAC"}

package/dist/types/src/lib/registry.d.ts

@@ -0,0 +1,8 @@
+import '$features/toggles/components/Toggle.svelte';
+import '$features/tabs/components/Tab.svelte';
+import '$features/tabs/components/TabGroup.svelte';
+import '$features/tabs/components/TabHeader.svelte';
+import '$features/tabs/components/TabBody.svelte';
+import '$features/placeholder/Placeholder.svelte';
+import '$features/placeholder/PlaceholderInput.svelte';
+//# sourceMappingURL=registry.d.ts.map

package/dist/types/src/lib/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../../../src/lib/registry.ts"],"names":[],"mappings":"AAAA,OAAO,4CAA4C,CAAC;AACpD,OAAO,sCAAsC,CAAC;AAC9C,OAAO,2CAA2C,CAAC;AACnD,OAAO,4CAA4C,CAAC;AACpD,OAAO,0CAA0C,CAAC;AAElD,OAAO,0CAA0C,CAAC;AAClD,OAAO,+CAA+C,CAAC"}

package/dist/types/src/lib/runtime.svelte.d.ts

@@ -0,0 +1,73 @@
+import type { ConfigFile } from '$lib/types/index';
+import type { AssetsManager } from '$features/render/assets';
+import type { AdaptationConfig } from '$features/adaptation/types';
+export interface RuntimeOptions {
+    assetsManager: AssetsManager;
+    configFile: ConfigFile;
+    rootEl?: HTMLElement | undefined;
+    storageKey?: string | undefined;
+    adaptationConfig?: AdaptationConfig | null;
+}
+/**
+ * The reactive runtime for CustardUI. Manages the full lifecycle: initialization,
+ * state resolution, reactive side-effects (URL sync, persistence), DOM observation, and teardown.
+ * Components (Toggle, TabGroup) are self-contained and self-managing via the global store.
+ */
+export declare class AppRuntime {
+    private rootEl;
+    private persistenceManager;
+    private focusService;
+    private observer?;
+    private destroyEffectRoot?;
+    private onHashChange?;
+    constructor(opt: RuntimeOptions);
+    /**
+     * Initialize all stores with configuration from the config file.
+     * Populates the singleton sub-stores with real data.
+     */
+    private initStores;
+    /**
+     * Resolves the starting application state by layering sources:
+     *
+     * 1. **Baseline**: `ActiveStateStore` initializes with defaults from the config file.
+     * 2. **Adaptation Defaults**: If an adaptation is active, its defaults are applied
+     *    on top of the config defaults (before persisted state, so user choices can win).
+     * 3. **Persistence**: If local storage has a saved state, it replaces the baseline (`applyState`).
+     * 4. **URL Overrides**: If the URL contains parameters (`?t-show=X`), these are applied
+     *    as **sparse overrides** (`applyDifferenceInState`). Toggles not mentioned in the URL
+     *    retain their values from persistence/defaults.
+     */
+    private resolveInitialState;
+    /**
+     * Starts the CustardUI execution engine.
+     *
+     * Components (Toggle, TabGroup) self-register during their mount lifecycle.
+     * This method starts the global observers for DOM changes and reactive state side-effects.
+     */
+    start(): void;
+    /**
+     * Performs an initial, non-reactive scan of the DOM for placeholders.
+     */
+    private scanDOM;
+    /**
+     * Sets up global reactivity using `$effect.root` for persistence and placeholder binding.
+     */
+    private startGlobalReactivity;
+    /**
+     * Sets up a MutationObserver to detect content added dynamically to the page
+     * (e.g. by other scripts, lazy loading, or client-side routing).
+     */
+    private startComponentObserver;
+    /**
+     * Processes a newly added DOM node to check for and hydrate placeholders.
+     */
+    private handleForPlaceholders;
+    resetToDefault(): void;
+    getIconPosition(): number | null;
+    saveIconPosition(offset: number): void;
+    clearIconPosition(): void;
+    isIntroSeen(): boolean;
+    markIntroSeen(): void;
+    destroy(): void;
+}
+//# sourceMappingURL=runtime.svelte.d.ts.map

package/dist/types/src/lib/runtime.svelte.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.svelte.d.ts","sourceRoot":"","sources":["../../../../src/lib/runtime.svelte.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAC7D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AAenE,MAAM,WAAW,cAAc;IAC7B,aAAa,EAAE,aAAa,CAAC;IAC7B,UAAU,EAAE,UAAU,CAAC;IACvB,MAAM,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC;IACjC,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,gBAAgB,CAAC,EAAE,gBAAgB,GAAG,IAAI,CAAC;CAC5C;AAED;;;;GAIG;AACH,qBAAa,UAAU;IACrB,OAAO,CAAC,MAAM,CAAc;IAC5B,OAAO,CAAC,kBAAkB,CAAqB;IAC/C,OAAO,CAAC,YAAY,CAAe;IAEnC,OAAO,CAAC,QAAQ,CAAC,CAAmB;IACpC,OAAO,CAAC,iBAAiB,CAAC,CAAa;IACvC,OAAO,CAAC,YAAY,CAAC,CAAa;gBAEtB,GAAG,EAAE,cAAc;IAuB/B;;;OAGG;IACH,OAAO,CAAC,UAAU;IAsBlB;;;;;;;;;;OAUG;IACH,OAAO,CAAC,mBAAmB;IA0B3B;;;;;OAKG;IACI,KAAK;IAQZ;;OAEG;IACH,OAAO,CAAC,OAAO;IAMf;;OAEG;IACH,OAAO,CAAC,qBAAqB;IA0B7B;;;OAGG;IACH,OAAO,CAAC,sBAAsB;IAY9B;;OAEG;IACH,OAAO,CAAC,qBAAqB;IA6BtB,cAAc;IASd,eAAe,IAAI,MAAM,GAAG,IAAI;IAKhC,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAItC,iBAAiB,IAAI,IAAI;IAMzB,WAAW,IAAI,OAAO;IAItB,aAAa,IAAI,IAAI;IAIrB,OAAO;CAQf"}

package/dist/types/src/lib/stores/active-state-store.svelte.d.ts

@@ -0,0 +1,144 @@
+import type { Config, State } from '$lib/types/index';
+import type { AdaptationConfig } from '$features/adaptation/types';
+/**
+ * Store for managing the application's configuration and user state.
+ * Handles:
+ * - Loading and storing static configuration.
+ * - Managing mutable user state (toggles, tabs, placeholders).
+ * - Computing default states based on configuration.
+ */
+export declare class ActiveStateStore {
+    /**
+     * Static configuration loaded at startup.
+     */
+    config: Config;
+    /**
+     * Explicit order of sections derived from the initial configuration JSON.
+     */
+    configSectionOrder: ("toggles" | "tabGroups" | "placeholders")[];
+    /**
+     * Mutable application state representing user choices.
+     * Use actions like `setPinnedTab` or `setToggles` to modify this.
+     */
+    state: State;
+    constructor(initialConfig?: Config);
+    /**
+     * Initialize with real configuration.
+     */
+    init(config: Config): void;
+    /**
+     * Set the pinned tab for a specific tab group.
+     * This syncs across all tab groups with the same ID.
+     * @param groupId The ID of the tab group.
+     * @param tabId The ID of the tab to pin.
+     */
+    setPinnedTab(groupId: string, tabId: string): void;
+    /**
+     * Update the visibility of toggles.
+     * @param shown List of IDs for toggles in "Show" state.
+     * @param peek List of IDs for toggles in "Peek" state.
+     */
+    setToggles(shown: string[], peek: string[]): void;
+    /**
+     * Set a specific placeholder value.
+     * @param key The ID/name of the placeholder.
+     * @param value The value to set.
+     */
+    setPlaceholder(key: string, value: string): void;
+    /**
+     * Replaces the full application state (e.g. from persistence).
+     *
+     * Precedence model:
+     * 1. Start from computed defaults (config-driven).
+     * 2. Layer in the incoming `newState`, sanitizing tabs and placeholders.
+     * 3. Sync any tab-group-derived placeholders that weren't explicitly set.
+     *
+     * @param newState The persisted state to restore.
+     */
+    applyState(newState: State): void;
+    /**
+     * Applies a sparse delta on top of the current state (e.g. from URL parameters).
+     *
+     * Semantics:
+     * - Only toggles explicitly mentioned in the delta are affected;
+     *   unmentioned toggles retain their current visibility.
+     * - Tab and placeholder entries in the delta are merged into (not replacing) current state.
+     * - Incoming tab IDs are validated against the config; invalid entries are dropped.
+     * - Incoming placeholder keys are validated against the registry; invalid keys are dropped.
+     * - After tab merges, tab-group-derived placeholders are automatically synced
+     *   unless the delta explicitly provides a value for them.
+     *
+     * @param deltaState Partial state describing only the changes to apply.
+     */
+    applyDifferenceInState(deltaState: State): void;
+    /**
+     * Applies adaptation defaults on top of the config defaults, before persisted state.
+     * User choices applied later via applyState() will override these.
+     *
+     * @param defaults The defaults section from the adaptation config
+     */
+    applyAdaptationDefaults(defaults: AdaptationConfig['defaults']): void;
+    /**
+     * Resets the application state to the computed defaults.
+     */
+    reset(): void;
+    computeDefaultState(): State;
+    /**
+     * Finds a toggle in the configuration using a case-insensitive ID match.
+     * @param toggleId The ID to search for.
+     * @returns The matched toggle configuration, or undefined if not found.
+     */
+    private getToggleConfigFromConfig;
+    /**
+     * Applies a map of toggleId → visibility to the current state.
+     * Removes each mentioned toggle from both lists, then re-adds to the correct one.
+     * Warns and drops unknown IDs (consistent with filterValidToggles).
+     */
+    private applyToggleMap;
+    /**
+     * Applies the toggle portion of a delta state.
+     * Toggles explicitly reassigned in the delta are moved to their new state;
+     * all others retain their current visibility.
+     */
+    private applyToggleDelta;
+    /**
+     * Merges a tab delta into the current state.
+     * Validates each incoming groupId and tabId against the configuration.
+     * Invalid entries are dropped with a warning; valid entries override the current selection.
+     * After merging, tab-group-derived placeholders are synced.
+     */
+    private applyTabsDelta;
+    /**
+     * Merges a placeholder delta into the current state.
+     * Only registered placeholder keys are accepted; others are dropped with a warning.
+     * Explicit placeholder values override any tab-derived value (winning over syncPlaceholdersFromTabs).
+     */
+    private applyPlaceholdersDelta;
+    /**
+     * Validates an incoming tab record against the configuration.
+     * Drops any groupId that doesn't exist in `config.tabGroups`,
+     * and any tabId that doesn't exist within that group.
+     *
+     * @param incomingTabs Raw tab record (e.g. from a URL or persistence).
+     * @returns A filtered record containing only valid groupId → tabId pairs.
+     */
+    private filterValidTabs;
+    /**
+     * Validates an incoming list of toggle IDs against the configuration.
+     * Invalid IDs are dropped with a warning.
+     */
+    private filterValidToggles;
+    /**
+     * Recalculates tab-group-derived placeholders for any tab group that hasn't been
+     * explicitly overridden in the `explicitPlaceholders` map.
+     *
+     * Skip rules (to avoid overwriting intentional values):
+     * - If the placeholder was explicitly included in the incoming state, skip it.
+     * - If the placeholder is owned by `config` (not a tab group), skip it.
+     *
+     * @param explicitPlaceholders Placeholders that were explicitly set in the incoming state.
+     */
+    private syncPlaceholdersFromTabs;
+}
+export declare const activeStateStore: ActiveStateStore;
+//# sourceMappingURL=active-state-store.svelte.d.ts.map

package/dist/types/src/lib/stores/active-state-store.svelte.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"active-state-store.svelte.d.ts","sourceRoot":"","sources":["../../../../../src/lib/stores/active-state-store.svelte.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,MAAM,EAAoB,KAAK,EAAgB,MAAM,kBAAkB,CAAC;AAEtF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AAEnE;;;;;;GAMG;AACH,qBAAa,gBAAgB;IAC3B;;OAEG;IACH,MAAM,SAAsB;IAE5B;;OAEG;IACH,kBAAkB,+CAAkC;IAEpD;;;OAGG;IACH,KAAK,QAKF;gBAES,aAAa,GAAE,MAAW;IAQtC;;OAEG;IACH,IAAI,CAAC,MAAM,EAAE,MAAM;IAiBnB;;;;;OAKG;IACH,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM;IAU3C;;;;OAIG;IACH,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE;IAK1C;;;;OAIG;IACH,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM;IAOzC;;;;;;;;;OASG;IACH,UAAU,CAAC,QAAQ,EAAE,KAAK;IAmB1B;;;;;;;;;;;;;OAaG;IACH,sBAAsB,CAAC,UAAU,EAAE,KAAK;IAMxC;;;;;OAKG;IACH,uBAAuB,CAAC,QAAQ,EAAE,gBAAgB,CAAC,UAAU,CAAC,GAAG,IAAI;IAcrE;;OAEG;IACH,KAAK;IAKE,mBAAmB,IAAI,KAAK;IAqDnC;;;;OAIG;IACH,OAAO,CAAC,yBAAyB;IAIjC;;;;OAIG;IACH,OAAO,CAAC,cAAc;IAwBtB;;;;OAIG;IACH,OAAO,CAAC,gBAAgB;IAqBxB;;;;;OAKG;IACH,OAAO,CAAC,cAAc;IAWtB;;;;OAIG;IACH,OAAO,CAAC,sBAAsB;IAO9B;;;;;;;OAOG;IACH,OAAO,CAAC,eAAe;IAsBvB;;;OAGG;IACH,OAAO,CAAC,kBAAkB;IAsB1B;;;;;;;;;OASG;IACH,OAAO,CAAC,wBAAwB;CAwBjC;AAED,eAAO,MAAM,gBAAgB,kBAAyB,CAAC"}

package/dist/types/src/lib/stores/derived-store.svelte.d.ts

@@ -0,0 +1,16 @@
+import type { AssetsManager } from '$features/render/assets';
+/**
+ * Cross-cutting derived state that combines data from multiple sub-stores.
+ * Holds only computed/derived values and assetsManager — no mutable application state.
+ */
+declare class DerivedStateStore {
+    assetsManager: AssetsManager | undefined;
+    menuToggles: import("../types").ToggleConfig[];
+    menuTabGroups: import("../types").TabGroupConfig[];
+    hasVisiblePlaceholders: boolean;
+    hasMenuOptions: boolean;
+    setAssetsManager(manager: AssetsManager): void;
+}
+export declare const derivedStore: DerivedStateStore;
+export {};
+//# sourceMappingURL=derived-store.svelte.d.ts.map

package/dist/types/src/lib/stores/derived-store.svelte.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"derived-store.svelte.d.ts","sourceRoot":"","sources":["../../../../../src/lib/stores/derived-store.svelte.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAK7D;;;GAGG;AACH,cAAM,iBAAiB;IACrB,aAAa,4BAAgD;IAI7D,WAAW,oCAKR;IAEH,aAAa,sCAKV;IAEH,sBAAsB,UAQnB;IAEH,cAAc,UAIZ;IAEF,gBAAgB,CAAC,OAAO,EAAE,aAAa;CAGxC;AAED,eAAO,MAAM,YAAY,mBAA0B,CAAC"}