@lavalogic/scoria 0.37.52 → 0.37.54

package/dist/Components/Table/ColumnFactory.svelte.js

@@ -11,7 +11,7 @@
  * `minSize`, …) via the `commonProps(...)` helper. `id` is passed explicitly
  * at each call site so its narrowed literal type survives the object spread.
  */
-import { formatDateTime, generateUUID, syntheticColumnId } from '../../Helpers/Helpers.svelte.js';
+import { formatDateTime, syntheticColumnId } from '../../Helpers/Helpers.svelte.js';
 import { CheckboxDef } from './Types/Columns/Definitions/Accessors/CheckboxDef.svelte.js';
 import { DateInputDef } from './Types/Columns/Definitions/Accessors/DateInputDef.svelte.js';
 import { NumberInputDef } from './Types/Columns/Definitions/Accessors/NumberInputDef.svelte.js';
@@ -130,22 +130,6 @@ function commonProps(opts, kind) {
         filterGroup: opts.filterGroup,
     };
 }
-/** Generate a column id for a kind whose option type does not require an
- *  `id` from the caller.
- *
- *  - With `hint`: used verbatim. `idHint` is the server-side-filtering
- *    contract; the column id flows through `createRemoteRowSource` as
- *    the query-string key the server expects, so a synthetic prefix
- *    would make every server reject the field as unknown.
- *  - Without `hint`: fall back to `${prefix}-${UUID}` so the id is unique
- *    within the table. Such columns cannot participate in server-driven
- *    filtering (the server has no way to know the random suffix). */
-function mintSyntheticId(prefix, hint) {
-    if (hint != null) {
-        return syntheticColumnId(hint);
-    }
-    return syntheticColumnId(`${prefix}-${generateUUID()}`);
-}
 /** Resolve an `options` field that may be a static array or an async loader
  *  into the always-loader form the Def expects. The spread drops the
  *  readonly modifier the Def's signature lacks. Loaders may return either
@@ -185,6 +169,35 @@ function formatLocaleDate(value) {
     return '';
 }
 export function createColumnFactory() {
+    // Per-factory deterministic counters for synthetic (hint-less) column
+    // ids. The `columns: (col) => [...]` closure runs the factory methods
+    // in the same order every time `createTable` rebuilds the table, so
+    // `${prefix}-${n}` is stable across re-creations - which the
+    // persisted-layout and column-preset round-trips key on. A random
+    // UUID per build silently broke both (every mount produced fresh ids
+    // that no saved snapshot could match).
+    // eslint-disable-next-line svelte/prefer-svelte-reactivity
+    const syntheticIdCounters = new Map();
+    /** Mint a column id for a kind whose option type does not require an
+     *  `id` from the caller.
+     *
+     *  - With `hint`: used verbatim. `idHint` is the server-side-filtering
+     *    contract; the column id flows through `createRemoteRowSource` as
+     *    the query-string key the server expects, so a synthetic prefix
+     *    would make every server reject the field as unknown.
+     *  - Without `hint`: fall back to a deterministic `${prefix}-${n}`
+     *    (n is a per-prefix, per-factory counter) so the id is unique
+     *    within the table and stable across rebuilds. Such columns cannot
+     *    participate in server-driven filtering (the server has no column
+     *    matching the synthetic id). */
+    function mintId(prefix, hint) {
+        if (hint != null) {
+            return syntheticColumnId(hint);
+        }
+        const n = syntheticIdCounters.get(prefix) ?? 0;
+        syntheticIdCounters.set(prefix, n + 1);
+        return syntheticColumnId(`${prefix}-${n}`);
+    }
     const factory = {
         // ─── Accessor kinds ─────────────────────────────────────────
         text(opts) {
@@ -296,7 +309,7 @@ export function createColumnFactory() {
         },
         // ─── Display kinds ──────────────────────────────────────────
         display(opts) {
-            const id = mintSyntheticId('display', opts.idHint);
+            const id = mintId('display', opts.idHint);
             const normalisedOptions = opts.getOptions
                 ? normaliseOptionsLoader(opts.getOptions)
                 : undefined;
@@ -357,7 +370,7 @@ export function createColumnFactory() {
             return makeSpec('display', def);
         },
         bubble(opts) {
-            const id = mintSyntheticId('bubble', opts.idHint);
+            const id = mintId('bubble', opts.idHint);
             const normalisedOptions = opts.getOptions
                 ? normaliseOptionsLoader(opts.getOptions)
                 : undefined;
@@ -384,7 +397,7 @@ export function createColumnFactory() {
             return makeSpec('bubble', def);
         },
         progress(opts) {
-            const id = mintSyntheticId('progress', opts.idHint);
+            const id = mintId('progress', opts.idHint);
             // Normalise scalar ratio to `[fraction, 1]` tuple for the Def.
             const tupleAccessor = (row, index) => {
                 const raw = opts.value(row, index);
@@ -417,7 +430,7 @@ export function createColumnFactory() {
             return makeSpec('progress', def);
         },
         validity(opts) {
-            const id = mintSyntheticId('validity', opts?.idHint);
+            const id = mintId('validity', opts?.idHint);
             const fallbackValid = () => 'Valid';
             const def = new ValidityDef({
                 id,
@@ -437,6 +450,7 @@ export function createColumnFactory() {
         rowSelection(opts) {
             const def = new RowSelectionDef({
                 isSelectable: opts?.isSelectable ?? (() => true),
+                id: mintId('is-selectable'),
             });
             // RowSelection has no public width option — apply the per-kind
             // default so the column does not fall back to the 48px ColumnDef
@@ -464,6 +478,7 @@ export function createColumnFactory() {
             const def = new ActionsDef({
                 actions: wrapped,
                 isEnabled: isEnabledFn ? (item) => isEnabledFn(item) : undefined,
+                id: mintId('actions'),
             });
             // Actions has no public width option — apply the per-kind default.
             def.width = KIND_DEFAULT_WIDTHS.actions;
@@ -480,7 +495,7 @@ export function createColumnFactory() {
                 : (inner) => inner[opts.childRowId];
             const userIsEnabled = opts.isEnabled;
             const def = new ExpandDef({
-                id: mintSyntheticId('expand'),
+                id: mintId('expand'),
                 header: opts.header ?? '',
                 isEnabled: userIsEnabled ?? (() => true),
                 accessorFn: opts.childRows,

package/dist/Components/Table/Types/Columns/Definitions/Actions/ActionsDef.svelte.d.ts

@@ -2,9 +2,10 @@ import type { ColourSet } from '../../../../../../scss/colours.js';
 import type { TableActionButton } from '../../TableActionButton.js';
 import { ColumnDef, type ColumnDefProps } from '../ColumnDef.svelte.js';
 /**
- * Construction-time props for `ActionsDef`. Omits `id` and `header`
- * because the class generates a stable id via `generateUUID` and pins
- * the header to `'Actions'`.
+ * Construction-time props for `ActionsDef`. Omits `header` (pinned to
+ * `'Actions'`) and makes `id` optional: the typed column factory passes
+ * a deterministic `actions-<n>` id, and a `generateUUID`-suffixed id is
+ * minted only when none is supplied.
  *
  * Notes:
  * - `isEnabled` defaults to `true` for every button if omitted.
@@ -19,15 +20,23 @@ export interface ActionsDefProps<T extends object, in FilterValueType> extends O
     isEnabled?: (item: T, index: number, button: TableActionButton<T>) => boolean | Promise<boolean>;
     /** Per-row, per-button colour override. */
     getColourSet?: (item: T, index: number, button: TableActionButton<T>) => ColourSet;
+    /**
+     * Optional explicit column id. The typed column factory passes a
+     * deterministic id (`actions-<n>`) so the column keeps the same id
+     * across table re-creations - which persisted-layout and preset
+     * round-trips key on. When omitted a random id is minted.
+     */
+    id?: ColumnDefProps<T, FilterValueType>['id'];
 }
 /**
  * `ActionsDef<T, FilterValueType>` is a column whose cells render a
  * row of buttons. It is non-sortable, non-filterable, and pins its
  * header to `'Actions'`.
  *
- * Note: the generated id uses `generateUUID()` (UUIDv7); two `ActionsDef`
- * instances constructed in the same render pass will have distinct ids
- * so consumers must keep a single instance per table.
+ * Note: when constructed without an explicit `id` the fallback id uses
+ * `generateUUID()`, which is NOT stable across table rebuilds; consumers
+ * that need a persisted-layout-safe id (the typed column factory) pass
+ * a deterministic `id` instead.
  */
 export declare class ActionsDef<T extends object, in FilterValueType> extends ColumnDef<T, FilterValueType> {
     constructor(props: ActionsDefProps<T, FilterValueType>);

package/dist/Components/Table/Types/Columns/Definitions/Actions/ActionsDef.svelte.js

@@ -6,14 +6,15 @@ import { ColumnDef } from '../ColumnDef.svelte.js';
  * row of buttons. It is non-sortable, non-filterable, and pins its
  * header to `'Actions'`.
  *
- * Note: the generated id uses `generateUUID()` (UUIDv7); two `ActionsDef`
- * instances constructed in the same render pass will have distinct ids
- * so consumers must keep a single instance per table.
+ * Note: when constructed without an explicit `id` the fallback id uses
+ * `generateUUID()`, which is NOT stable across table rebuilds; consumers
+ * that need a persisted-layout-safe id (the typed column factory) pass
+ * a deterministic `id` instead.
  */
 export class ActionsDef extends ColumnDef {
     constructor(props) {
         super({
-            id: syntheticColumnId(`actions-${generateUUID()}`),
+            id: props.id ?? syntheticColumnId(`actions-${generateUUID()}`),
             header: 'Actions',
             allowSorting: false,
             allowFiltering: false,

package/dist/Components/Table/Types/Columns/Definitions/RowSelection/RowSelectionDef.svelte.d.ts

@@ -11,12 +11,20 @@ export interface RowSelectionDefProps<T extends object, FilterValueType = BoolFi
     isSelectable: (item: T, index: number) => boolean | Promise<boolean>;
     /** Optional row validity predicate. */
     isValid?: ColumnDefProps<T, FilterValueType>['isValid'];
+    /**
+     * Optional explicit column id. The typed column factory passes a
+     * deterministic id (`is-selectable-<n>`) so the column keeps the
+     * same id across table re-creations - which persisted-layout and
+     * preset round-trips key on. When omitted a random id is minted.
+     */
+    id?: ColumnDefProps<T, FilterValueType>['id'];
 }
 /**
  * `RowSelectionDef<T, FilterValueType>` is the checkbox column that
  * drives row selection. Non-sortable and non-filterable; the header
- * reads `'Row Selected'` and the id is generated via `generateUUID`
- * (UUIDv7).
+ * reads `'Row Selected'`. The id is taken from `props.id` when supplied
+ * (the typed column factory passes a deterministic `is-selectable-<n>`)
+ * and otherwise falls back to a `generateUUID`-suffixed id.
  *
  * @remarks
  *

package/dist/Components/Table/Types/Columns/Definitions/RowSelection/RowSelectionDef.svelte.js

@@ -4,8 +4,9 @@ import { ColumnDef } from '../ColumnDef.svelte.js';
 /**
  * `RowSelectionDef<T, FilterValueType>` is the checkbox column that
  * drives row selection. Non-sortable and non-filterable; the header
- * reads `'Row Selected'` and the id is generated via `generateUUID`
- * (UUIDv7).
+ * reads `'Row Selected'`. The id is taken from `props.id` when supplied
+ * (the typed column factory passes a deterministic `is-selectable-<n>`)
+ * and otherwise falls back to a `generateUUID`-suffixed id.
  *
  * @remarks
  *
@@ -28,7 +29,7 @@ export class RowSelectionDef extends ColumnDef {
             ? { isSelectable: propsOrIsSelectable, isValid: legacyIsValid }
             : propsOrIsSelectable;
         super({
-            id: syntheticColumnId(`is-selectable-${generateUUID()}`),
+            id: props.id ?? syntheticColumnId(`is-selectable-${generateUUID()}`),
             header: 'Row Selected',
             allowSorting: false,
             allowFiltering: false,

package/dist/Components/Table/Types/Columns/JSONTableLayout.d.ts

@@ -0,0 +1,42 @@
+import type { ColumnSizingState } from './ColumnSizingState.js';
+import type { JSONColumnPinningState } from './JSONColumnPinningState.js';
+import type { VisibilityState } from './VisibilityState.js';
+/**
+ * Persisted-to-localStorage snapshot of a table's *live* column layout -
+ * the order / visibility / pinning / width state a user builds up by
+ * dragging, hiding and resizing columns, as distinct from an explicitly
+ * saved named preset (`JSONColumnDefSet`).
+ *
+ * `TableContext` writes this automatically on every layout change and
+ * re-applies it on the next mount, so a user's tweaks survive navigation
+ * and reloads without having to save a preset - persisted until the
+ * browser storage is cleared or the table's column set changes (schema
+ * drift, which drops the stale snapshot).
+ *
+ * Only ids and primitive maps are stored - never the column-def objects
+ * themselves - so the snapshot stays small and is trivially validated.
+ */
+export interface JSONTableLayout {
+    /** Column ids in display order (memory-index order). */
+    columnOrder: Array<string>;
+    /** Tri-state per-column visibility map. */
+    visibility: VisibilityState;
+    /** Pinned-left / pinned-right column ids with their pinned widths. */
+    pinning: JSONColumnPinningState;
+    /** Per-column user-set widths in pixels. */
+    sizing: ColumnSizingState;
+}
+/**
+ * Schema version for the persisted `JSONTableLayout` envelope. Bump when
+ * the shape changes in a backwards-incompatible way; `readVersionedJSON`
+ * silently drops envelopes written under a different version.
+ */
+export declare const TABLE_LAYOUT_SCHEMA_VERSION = 1;
+/**
+ * Conservative typeguard for a persisted `JSONTableLayout`. localStorage
+ * is same-origin-writable so the decoded value is untrusted; this checks
+ * the envelope shape and every field's primitive type. `TableContext`
+ * performs the deeper "do these ids still match the live column set"
+ * check before applying.
+ */
+export declare function isJSONTableLayout(raw: unknown): raw is JSONTableLayout;

package/dist/Components/Table/Types/Columns/JSONTableLayout.js

@@ -0,0 +1,58 @@
+/**
+ * Schema version for the persisted `JSONTableLayout` envelope. Bump when
+ * the shape changes in a backwards-incompatible way; `readVersionedJSON`
+ * silently drops envelopes written under a different version.
+ */
+export const TABLE_LAYOUT_SCHEMA_VERSION = 1;
+/**
+ * Conservative typeguard for a persisted `JSONTableLayout`. localStorage
+ * is same-origin-writable so the decoded value is untrusted; this checks
+ * the envelope shape and every field's primitive type. `TableContext`
+ * performs the deeper "do these ids still match the live column set"
+ * check before applying.
+ */
+export function isJSONTableLayout(raw) {
+    if (typeof raw !== 'object' || raw === null) {
+        return false;
+    }
+    const candidate = raw;
+    if (!Array.isArray(candidate.columnOrder) ||
+        !candidate.columnOrder.every((id) => typeof id === 'string')) {
+        return false;
+    }
+    if (!isPrimitiveRecord(candidate.visibility, (v) => typeof v === 'boolean')) {
+        return false;
+    }
+    if (!isPrimitiveRecord(candidate.sizing, (v) => typeof v === 'number')) {
+        return false;
+    }
+    return isJSONPinningState(candidate.pinning);
+}
+/** Validates a plain (non-array) object whose values all satisfy `valueGuard`. */
+function isPrimitiveRecord(raw, valueGuard) {
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+        return false;
+    }
+    return Object.values(raw).every(valueGuard);
+}
+/** Validates the `{ left?, right? }` array-pair pinning shape. */
+function isJSONPinningState(raw) {
+    if (typeof raw !== 'object' || raw === null) {
+        return false;
+    }
+    const candidate = raw;
+    return isPinSide(candidate.left) && isPinSide(candidate.right);
+}
+/** Validates one optional pinning side: absent, or an array of `[id, width]`. */
+function isPinSide(raw) {
+    if (raw === undefined) {
+        return true;
+    }
+    if (!Array.isArray(raw)) {
+        return false;
+    }
+    return raw.every((entry) => Array.isArray(entry) &&
+        entry.length === 2 &&
+        typeof entry[0] === 'string' &&
+        typeof entry[1] === 'number');
+}

package/dist/Components/Table/Types/Context/PreferencesState.svelte.d.ts

@@ -1,4 +1,5 @@
 import type { ColumnPinningState } from '../Columns/ColumnPinningState.js';
+import { type JSONTableLayout } from '../Columns/JSONTableLayout.js';
 import type { ColumnDef } from '../Columns/Definitions/ColumnDef.svelte.js';
 import type { ColumnDefSet } from '../Columns/Definitions/ColumnDefSet.js';
 import type { JSONColumnDefSet } from '../Columns/Definitions/JSONColumnDefSet.js';
@@ -139,7 +140,7 @@ export declare class PreferencesState<T extends object> {
      * for the same namespacing convention; the `<user>` segment is
      * `getUserId() ?? 'anon'` (see `userIdSegment`).
      */
-    storageKey(suffix: 'presets' | 'selected-preset-name' | 'settings'): string;
+    storageKey(suffix: 'presets' | 'selected-preset-name' | 'settings' | 'layout'): string;
     /**
      * Boot-time hydration helper. Reads the persisted preset list from
      * `localStorage`, validates it against `isJSONColumnDefSetArray`,
@@ -172,6 +173,30 @@ export declare class PreferencesState<T extends object> {
      * the live column-def shape (schema drift or column-set change).
      */
     clearPresetsAndSelection(): void;
+    /**
+     * Boot-time hydration helper. Reads the auto-saved live-layout
+     * snapshot (column order / visibility / pinning / sizing the user
+     * built up without saving a named preset). Returns `null` for a
+     * missing slot, a schema-version mismatch, or a value that fails
+     * validation, so the parent can fall back to the default layout.
+     *
+     * `localStorage` access is gated by the parent's `browser` check;
+     * this method assumes the caller already verified the environment.
+     */
+    loadLayout(): JSONTableLayout | null;
+    /**
+     * Persist the live-layout snapshot. Written by the parent on every
+     * column order / visibility / pinning / sizing change, wrapped in a
+     * versioned envelope so a future schema bump drops stale snapshots
+     * cleanly. Storage failures are swallowed inside `writeJSON`.
+     */
+    persistLayout(layout: JSONTableLayout): void;
+    /**
+     * Drop the persisted live-layout snapshot. Called when the snapshot
+     * no longer matches the table's column set (schema drift) or when
+     * table state is explicitly reset.
+     */
+    clearLayout(): void;
     /**
      * Persist the selected-preset name as plain text (no JSON
      * envelope - the slot is a single string by design).

package/dist/Components/Table/Types/Context/PreferencesState.svelte.js

@@ -1,5 +1,6 @@
 import { dev } from '$app/environment';
-import { readJSON } from '../../../../Helpers/Storage.js';
+import { readJSON, readVersionedJSON, writeJSON } from '../../../../Helpers/Storage.js';
+import { isJSONTableLayout, TABLE_LAYOUT_SCHEMA_VERSION, } from '../Columns/JSONTableLayout.js';
 /**
  * Conservative typeguard for the persisted preset list. Storage is
  * same-origin-writable so only the array shape can be trusted;
@@ -192,6 +193,53 @@ export class PreferencesState {
         localStorage.removeItem(this.storageKey('presets'));
         localStorage.removeItem(this.storageKey('selected-preset-name'));
     }
+    /**
+     * Boot-time hydration helper. Reads the auto-saved live-layout
+     * snapshot (column order / visibility / pinning / sizing the user
+     * built up without saving a named preset). Returns `null` for a
+     * missing slot, a schema-version mismatch, or a value that fails
+     * validation, so the parent can fall back to the default layout.
+     *
+     * `localStorage` access is gated by the parent's `browser` check;
+     * this method assumes the caller already verified the environment.
+     */
+    loadLayout() {
+        // Reference-equality sentinel: `readVersionedJSON` demands a
+        // fallback of the value type, so a distinct object instance is
+        // used to distinguish "no usable slot" from a real snapshot.
+        const fallback = {
+            columnOrder: [],
+            visibility: {},
+            pinning: {},
+            sizing: {},
+        };
+        const saved = readVersionedJSON(localStorage, this.storageKey('layout'), TABLE_LAYOUT_SCHEMA_VERSION, isJSONTableLayout, fallback);
+        return saved === fallback ? null : saved;
+    }
+    /**
+     * Persist the live-layout snapshot. Written by the parent on every
+     * column order / visibility / pinning / sizing change, wrapped in a
+     * versioned envelope so a future schema bump drops stale snapshots
+     * cleanly. Storage failures are swallowed inside `writeJSON`.
+     */
+    persistLayout(layout) {
+        writeJSON(localStorage, this.storageKey('layout'), layout, TABLE_LAYOUT_SCHEMA_VERSION);
+    }
+    /**
+     * Drop the persisted live-layout snapshot. Called when the snapshot
+     * no longer matches the table's column set (schema drift) or when
+     * table state is explicitly reset.
+     */
+    clearLayout() {
+        try {
+            localStorage.removeItem(this.storageKey('layout'));
+        }
+        catch (e) {
+            if (dev) {
+                console.warn('table layout slot clear failed:', e);
+            }
+        }
+    }
     /**
      * Persist the selected-preset name as plain text (no JSON
      * envelope - the slot is a single string by design).

package/dist/Components/Table/Types/Context/TableContext.svelte.d.ts

@@ -73,6 +73,21 @@ export declare class TableContext<T extends object, RowIdType extends Primitive>
     static init<T extends object, RowIdType extends Primitive>(defaultColumnDefs: DefsWrapper<T>, tableName: string, dataRepo: IDataRepository<T>, options: TableInitOptions<T, RowIdType>): TableContext<T, RowIdType>;
     protected constructor(INTERNAL_ONLY: symbol, defaultColumnDefs: DefsWrapper<T>, tableName: string, dataRepo: IDataRepository<T>, allowCopy: boolean, enableResize: boolean, allowColumnReordering: boolean, allowQuickFiltering: boolean, showQuickFilterByDefault: boolean, allowAdvancedFiltering: boolean, toolbarPosition: ToolbarPosition, displayFooter: boolean, selectionExtractor: TableInitOptions<T, RowIdType>['selectionExtractor'], getUserId: () => string | undefined, _onEditCell: TableInitOptions<T, RowIdType>['onEditCell'], debug: boolean);
     private isSelectable;
+    /**
+     * `false` until the boot-time layout hydration (`_hydrateLayout`)
+     * has run. The auto-persist `$effect` reads this gate so the live
+     * layout is not written back during construction / hydration -
+     * which would clobber the saved snapshot with the default layout.
+     */
+    private _layoutHydrated;
+    /**
+     * Pending debounce timer for the layout auto-persist. Deliberately
+     * not cleared on teardown: a still-pending write should flush even
+     * if the user navigates away mid-debounce, and `persistLayout` only
+     * touches `localStorage` (no reactive state, no DOM) so it is safe
+     * to run after the component is gone.
+     */
+    private _layoutPersistTimer;
     private _paginationRepo;
     get paginationRepo(): IDataRepository<T> | undefined;
     set paginationRepo(v: IDataRepository<T> | undefined);
@@ -620,6 +635,33 @@ export declare class TableContext<T extends object, RowIdType extends Primitive>
      * persistence boundary lives in the sub-context.
      */
     private _updateLocalStorageSettings;
+    /**
+     * Snapshot the live column layout - order / visibility / pinning /
+     * sizing - into the persistable `JSONTableLayout` shape. Reads every
+     * layout `$state` slot so the auto-persist `$effect` re-runs whenever
+     * any of them change.
+     */
+    private _captureLayout;
+    /**
+     * Apply a persisted `JSONTableLayout` to the live column state. The
+     * snapshot is dropped (and ignored) when its column-id set no longer
+     * matches the table's current columns - a column added or removed
+     * since the snapshot was written invalidates it.
+     */
+    private _applyLayout;
+    /**
+     * Boot-time hydration. Reads the auto-saved live-layout snapshot and
+     * applies it on top of whatever the preset flow produced, restoring
+     * the user's last column order / visibility / pinning / sizing.
+     * No-op when no snapshot is stored.
+     */
+    private _hydrateLayout;
+    /**
+     * Drop the persisted live-layout snapshot for this table. The next
+     * mount falls back to the default column layout. Exposed so a host
+     * app can wire an explicit "reset table layout" control.
+     */
+    clearPersistedLayout(): void;
     /**
      * Delegates to `_columnLayout.visualColumns`. The underscore prefix
      * is preserved so the existing read sites in `tabForward` /

package/dist/Components/Table/Types/Context/TableContext.svelte.js

@@ -19,6 +19,13 @@ import { PaginationType } from '../Pagination/PaginationType.js';
 import { ToolbarPosition } from '../Toolbar/ToolbarPosition.js';
 const SORTING_ICON_WIDTH = 24;
 const InternalSymbol = Symbol();
+/**
+ * Debounce window (ms) for the auto-persist of the live column layout.
+ * Collapses a burst of changes - notably a drag-resize, which fires a
+ * width update on every pointer move - into a single `localStorage`
+ * write once the user settles.
+ */
+const LAYOUT_PERSIST_DEBOUNCE_MS = 250;
 /**
  * Default values applied by `TableContext.init` for any `TableInitOptions`
  * field the consumer omits. Frozen so callers (notably `NestedTable`)
@@ -339,6 +346,26 @@ export class TableContext {
         if (hasPagination(dataRepo)) {
             this.paginationRepo = dataRepo;
         }
+        // Auto-persist the live column layout (order / visibility /
+        // pinning / sizing) to localStorage on every change, so a user's
+        // drag-reorder, hide/show and resize tweaks survive navigation
+        // and reload without having to save a named preset. Gated on
+        // `_layoutHydrated` so the boot-time hydration below does not race
+        // a write of the default layout over the saved snapshot, and
+        // debounced so a drag-resize storm collapses to a single write.
+        $effect(() => {
+            const snapshot = this._captureLayout();
+            if (!this._layoutHydrated) {
+                return;
+            }
+            if (this._layoutPersistTimer !== undefined) {
+                clearTimeout(this._layoutPersistTimer);
+            }
+            this._layoutPersistTimer = setTimeout(() => {
+                this._layoutPersistTimer = undefined;
+                this._preferences.persistLayout(snapshot);
+            }, LAYOUT_PERSIST_DEBOUNCE_MS);
+        });
         if (browser) {
             this._getUserDefaults();
             const removeInvalidPresets = () => {
@@ -400,6 +427,13 @@ export class TableContext {
                     }
                     this._preferences.setPresets(presets);
                 }
+            })
+                .then(() => {
+                // Restore the auto-saved live layout on top of whatever
+                // the preset flow produced, then open the auto-persist
+                // gate. Runs regardless of which preset branch was taken.
+                this._hydrateLayout();
+                this._layoutHydrated = true;
             })
                 .catch(devCatch);
         }
@@ -407,6 +441,21 @@ export class TableContext {
     // #endregion
     // #region stores
     isSelectable = $state(false);
+    /**
+     * `false` until the boot-time layout hydration (`_hydrateLayout`)
+     * has run. The auto-persist `$effect` reads this gate so the live
+     * layout is not written back during construction / hydration -
+     * which would clobber the saved snapshot with the default layout.
+     */
+    _layoutHydrated = $state(false);
+    /**
+     * Pending debounce timer for the layout auto-persist. Deliberately
+     * not cleared on teardown: a still-pending write should flush even
+     * if the user navigates away mid-debounce, and `persistLayout` only
+     * touches `localStorage` (no reactive state, no DOM) so it is safe
+     * to run after the component is gone.
+     */
+    _layoutPersistTimer = undefined;
     _paginationRepo = $state();
     get paginationRepo() {
         return this._paginationRepo;
@@ -1762,6 +1811,95 @@ export class TableContext {
         };
         this._preferences.persistSettings(settingsObject);
     }
+    /**
+     * Snapshot the live column layout - order / visibility / pinning /
+     * sizing - into the persistable `JSONTableLayout` shape. Reads every
+     * layout `$state` slot so the auto-persist `$effect` re-runs whenever
+     * any of them change.
+     */
+    _captureLayout() {
+        const columnOrder = this.columnDefs
+            .slice()
+            .sort((a, b) => a.index - b.index)
+            .map((def) => def.id);
+        const pinning = {
+            left: [...(this.columnPinning.left?.entries() ?? [])],
+            right: [...(this.columnPinning.right?.entries() ?? [])],
+        };
+        return {
+            columnOrder,
+            visibility: { ...this.columnVisibility },
+            pinning,
+            sizing: { ...this.columnSizing },
+        };
+    }
+    /**
+     * Apply a persisted `JSONTableLayout` to the live column state. The
+     * snapshot is dropped (and ignored) when its column-id set no longer
+     * matches the table's current columns - a column added or removed
+     * since the snapshot was written invalidates it.
+     */
+    _applyLayout(layout) {
+        const defs = this.columnDefs;
+        // Keyed by plain `string` (not the branded `ColumnId`) so the
+        // persisted-snapshot ids - read back as plain strings - look up
+        // cleanly.
+        // eslint-disable-next-line svelte/prefer-svelte-reactivity
+        const byId = new Map(defs.map((def) => [def.id, def]));
+        // Schema-drift guard: the snapshot must describe exactly the
+        // current column set, otherwise it is stale and is discarded.
+        const matchesColumnSet = layout.columnOrder.length === defs.length && layout.columnOrder.every((id) => byId.has(id));
+        if (!matchesColumnSet) {
+            this._preferences.clearLayout();
+            return;
+        }
+        // Order: re-index the defs into the saved order.
+        const ordered = layout.columnOrder.map((id, index) => {
+            const def = byId.get(id);
+            if (!def) {
+                throw new Error(`_applyLayout: missing column def for id "${id}"`);
+            }
+            def.index = index;
+            return def;
+        });
+        this.columnDefs = ordered;
+        // Visibility / sizing: keep only ids still present in the table.
+        const visibility = {};
+        for (const [id, visible] of Object.entries(layout.visibility)) {
+            if (byId.has(id)) {
+                visibility[id] = visible;
+            }
+        }
+        this.columnVisibility = visibility;
+        const sizing = {};
+        for (const [id, width] of Object.entries(layout.sizing)) {
+            if (byId.has(id)) {
+                sizing[id] = width;
+            }
+        }
+        this.columnSizing = sizing;
+        this.columnPinning = adaptJSONPinningState(layout.pinning);
+    }
+    /**
+     * Boot-time hydration. Reads the auto-saved live-layout snapshot and
+     * applies it on top of whatever the preset flow produced, restoring
+     * the user's last column order / visibility / pinning / sizing.
+     * No-op when no snapshot is stored.
+     */
+    _hydrateLayout() {
+        const layout = this._preferences.loadLayout();
+        if (layout) {
+            this._applyLayout(layout);
+        }
+    }
+    /**
+     * Drop the persisted live-layout snapshot for this table. The next
+     * mount falls back to the default column layout. Exposed so a host
+     * app can wire an explicit "reset table layout" control.
+     */
+    clearPersistedLayout() {
+        this._preferences.clearLayout();
+    }
     /**
      * Delegates to `_columnLayout.visualColumns`. The underscore prefix
      * is preserved so the existing read sites in `tabForward` /

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@lavalogic/scoria",
   "description": "Svelte components used for the FloWMS Web Frontend",
-  "version": "0.37.52",
+  "version": "0.37.54",
   "publishConfig": {
     "access": "restricted"
   },