@lavalogic/scoria 0.36.0 → 0.37.0

package/dist/Helpers/Helpers.svelte.js

@@ -1,10 +1,17 @@
 import { dev } from '$app/environment';
-import { TableContext } from '../Components/Table/Types/Context/TableContext.svelte.js';
-import { LocalTableDataRepository } from '../Components/Table/Types/DataRepository/LocalTableDataRepository.svelte.js';
-import { CustomFilterType } from '../Components/Table/Types/Filtering/CustomFilterType.js';
 import { Sizing } from '../scss/sizing.js';
 import { untrack } from 'svelte';
 import { SvelteDate, SvelteSet } from 'svelte/reactivity';
+/**
+ * Returns the singular or plural form of `text` based on `quantity`.
+ * Handles common English suffix rules (`-s`, `-x`, `-z`, `-ch`,
+ * `-sh` -> `-es`; everything else -> `-s`). Set `capitalise` when
+ * the surrounding copy is upper-case (e.g. table headers).
+ *
+ * @param text - The singular form.
+ * @param quantity - When equal to `1`, the singular form is returned unchanged. Defaults to `2`.
+ * @param options.capitalise - When `true`, the appended suffix is upper-case.
+ */
 export function autoPluralise(text, quantity = 2, { capitalise = false } = {}) {
     if (quantity === 1) {
         return text;
@@ -32,13 +39,93 @@ export function autoPluralise(text, quantity = 2, { capitalise = false } = {}) {
         }
     }
 }
+/** Reactive set of lower-case English vowels; useful for "a" vs "an" decisions. */
 export const vowels = new SvelteSet(['a', 'e', 'i', 'o', 'u']);
 // generic is present to bypass floatAlias type requirements and the like
-export function generateShortUUID() {
+/**
+ * Returns the first 13 characters of a freshly generated v4 UUID.
+ *
+ * Inherits the entropy source of `generateUUID` (cryptographic when
+ * available, see that function's docstring), so the underlying random
+ * draw is strong. However, truncating a 128-bit UUID to 13 hex
+ * characters reduces it to roughly 52 bits of entropy, which makes
+ * collisions plausible at scale and renders the value vulnerable to
+ * brute-force guessing.
+ *
+ * WARNING: do NOT use `generateWeakId` for security-sensitive
+ * identifiers (CSRF tokens, session keys, password-reset codes,
+ * idempotency tokens). It is intended for short DOM `id` attributes
+ * and similar low-collision, non-secret labels only. For any
+ * security-sensitive identifier use `generateUUID` (or, in new code,
+ * `globalThis.crypto.randomUUID()` directly).
+ *
+ * The `<T extends string>` generic preserves the `BrandedString`
+ * ergonomics used by the rest of the helpers. Unlike `generateUUID`
+ * the brand parameter has no default - callers must opt in to a brand
+ * explicitly because the value is NOT a full UUID.
+ */
+export function generateWeakId() {
     return generateUUID().substring(0, 13);
 }
-// taken from https://stackoverflow.com/a/8809472/18712055
+/**
+ * @deprecated - use `generateWeakId`; the short form trades collision
+ * resistance for brevity and is NOT suitable for security tokens. The
+ * rename is part of the SecureUUIDs follow-up; this alias is preserved
+ * to avoid breaking existing consumers in the same release.
+ */
+export function generateShortUUID() {
+    return generateWeakId();
+}
+let __weakUUIDWarned = false;
+/**
+ * Generates an RFC 4122 version 4 UUID.
+ *
+ * Entropy source cascade (in order of preference):
+ *   1. `globalThis.crypto.randomUUID()` - native v4 UUID with
+ *      cryptographically secure randomness. Available in all modern
+ *      evergreen browsers (since 2022) and Node 19+.
+ *   2. `globalThis.crypto.getRandomValues(new Uint8Array(16))` - fills
+ *      16 random bytes from the platform CSPRNG, then sets the
+ *      version (0x40) and variant (0x80) nibbles to produce a v4 UUID.
+ *      Used when `randomUUID` is missing (older Safari, some embedded
+ *      runtimes) but the Web Crypto API is otherwise present.
+ *   3. A `Math.random()`-based fallback that mixes in `Date.now()` and
+ *      `performance.now()`. Emits a one-time `console.warn` to signal
+ *      that the entropy is NOT cryptographically secure. Only reached
+ *      on very old environments where `globalThis.crypto` itself is
+ *      unavailable.
+ *
+ * The `<T extends string>` generic preserves the `BrandedString`
+ * ergonomics used by the rest of the helpers: callers may stamp the
+ * returned value with a brand without an explicit cast.
+ *
+ * @returns A v4 UUID string of the form
+ *   `xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx` where `y` is one of
+ *   `8`, `9`, `a`, `b`.
+ */
 export function generateUUID() {
+    const cryptoRef = typeof globalThis !== 'undefined' ? globalThis.crypto : undefined;
+    if (cryptoRef?.randomUUID) {
+        return cryptoRef.randomUUID();
+    }
+    if (cryptoRef?.getRandomValues) {
+        const bytes = new Uint8Array(16);
+        cryptoRef.getRandomValues(bytes);
+        // Set version (v4) and variant (RFC 4122) bits.
+        bytes[6] = (bytes[6] & 0x0f) | 0x40;
+        bytes[8] = (bytes[8] & 0x3f) | 0x80;
+        const hex = [];
+        for (let i = 0; i < 16; i++) {
+            hex.push(bytes[i].toString(16).padStart(2, '0'));
+        }
+        return `${hex[0]}${hex[1]}${hex[2]}${hex[3]}-${hex[4]}${hex[5]}-${hex[6]}${hex[7]}-${hex[8]}${hex[9]}-${hex[10]}${hex[11]}${hex[12]}${hex[13]}${hex[14]}${hex[15]}`;
+    }
+    // Last-resort fallback for environments without Web Crypto at all.
+    // Taken from https://stackoverflow.com/a/8809472/18712055.
+    if (!__weakUUIDWarned) {
+        __weakUUIDWarned = true;
+        console.warn('scoria generateUUID: Web Crypto API is unavailable; falling back to Math.random for UUID generation. The resulting identifiers are NOT cryptographically secure and must not be used for security tokens.');
+    }
     let d = new SvelteDate().getTime(), 
     // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
     d2 = (typeof performance !== 'undefined' && performance.now && performance.now() * 1000) || 0;
@@ -55,6 +142,11 @@ export function generateUUID() {
         return (c == 'x' ? r : (r & 0x7) | 0x8).toString(16);
     });
 }
+/**
+ * Creates a `RefWrapper<T>` whose `value` is `$state`-backed.
+ * Used to pass mutable reactive references into contexts and
+ * across module boundaries without exposing the underlying rune.
+ */
 export function refWrapper(initial) {
     let value = $state(initial);
     return {
@@ -66,6 +158,52 @@ export function refWrapper(initial) {
         },
     };
 }
+/**
+ * Ergonomic constructor for the {@link CssLength} brand. The runtime
+ * value is the raw string the caller supplied; the cast is purely a
+ * compile-time tag. There is intentionally no validation - the
+ * browser is the authoritative parser for CSS length tokens. Use
+ * this at the call-site so the brand is obvious in the diff.
+ *
+ * @example
+ * ```ts
+ * <Icon name="cog" float left={cssLength('10px')} />
+ * ```
+ */
+export function cssLength(value) {
+    return value;
+}
+/**
+ * Ergonomic constructor for the {@link ScoriaStorageKey} brand. Use
+ * at the call-site of components that persist state to
+ * `sessionStorage` / `localStorage` (e.g. `StepForm`,
+ * `VerticalTabGroup`) so the brand is obvious in the diff.
+ */
+export function scoriaStorageKey(value) {
+    return value;
+}
+/**
+ * Ergonomic constructor for the {@link SyntheticColumnId} brand.
+ * Use at the call-site of `ColumnDef` constructors whose `id` is not
+ * a key on the row type (e.g. `RowSelectionDef`, `ExpandDef`,
+ * `ActionsDef`, `FilterOnlyDef`) so the brand is obvious in the diff.
+ *
+ * @example
+ * ```ts
+ * super({
+ *   id: syntheticColumnId(`is-selectable-${generateUUID()}`),
+ *   ...
+ * });
+ * ```
+ */
+export function syntheticColumnId(value) {
+    return value;
+}
+/**
+ * Formats a date into the `YYYY-MM-DD 00:00:00` shape expected by
+ * the FloWMS SQL backend. Accepts bare `Date` objects or any
+ * branded date string scoria models elsewhere.
+ */
 export function SQLFriendly(date) {
     if (typeof date === 'string') {
         date = new SvelteDate(date);
@@ -75,22 +213,13 @@ export function SQLFriendly(date) {
         .toString()
         .padStart(2, '0')} 00:00:00`;
 }
+/**
+ * Like {@link SQLFriendly} but keeps the local time component
+ * (`YYYY-MM-DDTHH:MM:SS±HH:MM`). Accepts an optional separate
+ * `timeDate` argument when the date and time-of-day need to come
+ * from different sources.
+ */
 export function SQLFriendlyWithLocalTime(date, timeDate) {
-    if (typeof date === 'string') {
-        // eslint-disable-next-line svelte/prefer-svelte-reactivity
-        date = new Date(date);
-    }
-    if (typeof timeDate === 'string') {
-        // eslint-disable-next-line svelte/prefer-svelte-reactivity
-        timeDate = new Date(timeDate);
-    }
-    return `${date.getFullYear()}-${(date.getMonth() + 1).toString().padStart(2, '0')}-${date
-        .getDate()
-        .toString()
-        .padStart(2, '0')} ${localTimeFormat.format(timeDate ?? date)}`;
-}
-//HACK: transition will happen soon. Until then, this format cannot be used in production
-export function SQLFriendlyWithLocalTime_new(date, timeDate) {
     if (typeof date === 'string') {
         // eslint-disable-next-line svelte/prefer-svelte-reactivity
         date = new Date(date);
@@ -100,12 +229,17 @@ export function SQLFriendlyWithLocalTime_new(date, timeDate) {
         timeDate = new Date(timeDate);
     }
     const d = date;
-    const t = (timeDate ?? date);
+    const t = timeDate ?? date;
     const pad = (n) => String(n).padStart(2, '0');
     const off = -t.getTimezoneOffset();
     const sign = off >= 0 ? '+' : '-';
     return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}T${pad(t.getHours())}:${pad(t.getMinutes())}:${pad(t.getSeconds())}${sign}${pad(Math.floor(Math.abs(off) / 60))}:${pad(Math.abs(off) % 60)}`;
 }
+/**
+ * Shared `Intl.DateTimeFormat` configured for UK locale, 24-hour
+ * clock, and the browser-resolved timezone. Useful for rendering
+ * timestamps consistently across scoria.
+ */
 export const localTimeFormat = new Intl.DateTimeFormat('en-GB', {
     hour: '2-digit',
     hourCycle: 'h23',
@@ -113,6 +247,13 @@ export const localTimeFormat = new Intl.DateTimeFormat('en-GB', {
     second: '2-digit',
     timeZone: Intl.DateTimeFormat().resolvedOptions().timeZone,
 });
+/**
+ * Default `onkeydown` handler that blurs the focused element when
+ * the user presses an alphanumeric key. Used on input wrappers
+ * and buttons so that scanner-driven barcode characters do not
+ * accumulate inside the focused field; instead the buffer goes
+ * to `UntypedInputContext`.
+ */
 export function passthrough(e) {
     if (!e.key.match(/^[a-zA-Z0-9[\]]$/gm)) {
         return;
@@ -120,6 +261,11 @@ export function passthrough(e) {
     e.target.blur();
 }
 let __canvas;
+/**
+ * Returns a shared, memoised 2D canvas context used for offscreen
+ * text measurement (column auto-sizing, ellipsis truncation, etc).
+ * Returns `null` when the environment cannot create a `<canvas>`.
+ */
 export function getCanvasContext() {
     if (!__canvas) {
         const _canvas = document.createElement('canvas');
@@ -133,6 +279,7 @@ export function getCanvasContext() {
     }
     return __canvas.getContext('2d');
 }
+/** Type guard for {@link IErrorResponse}. */
 export function isErrorResponse(error) {
     return (error != null &&
         typeof error === 'object' &&
@@ -140,9 +287,25 @@ export function isErrorResponse(error) {
         (Array.isArray(error.errors) || typeof error.errors === 'string') &&
         !!error.errors.length);
 }
+/**
+ * Type guard for the structural-`Error` shape. Returns `true` for
+ * any object with a `string` `message` property, which covers both
+ * native `Error` and cross-realm error-like objects.
+ */
 export function isJSError(error) {
     return 'message' in error && typeof error.message == 'string';
 }
+/**
+ * Best-effort extraction of a user-displayable error message from
+ * an unknown error value. Handles {@link IErrorResponse}, plain JS
+ * `Error`, and arbitrary strings; falls back to the literal
+ * `'Unknown Error'` when no recognisable shape is found.
+ *
+ * Callers that surface the output to the clipboard (e.g.
+ * `ToastContext.toast`) must gate `includeStack` and `includeCause`
+ * on `dev` so production users cannot accidentally exfiltrate
+ * backend internals.
+ */
 export function getErrorMessage(error, { includeUUID = true, includeStack = false, includeCause = false } = {}) {
     if (!error) {
         return 'Unknown Error';
@@ -180,11 +343,31 @@ export function getErrorMessage(error, { includeUUID = true, includeStack = fals
     }
     return errorList || 'Unknown Error';
 }
+/**
+ * Pragmatic email-address validation regex. Module-lifted so the
+ * pattern object is reused across calls instead of recompiled on
+ * each invocation.
+ */
+const EMAIL_REGEX = /^(([^<>()[\]\\.,;:\s@"]+(\.[^<>()[\]\\.,;:\s@"]+)*)|.(".+"))@((\[[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\])|(([a-zA-Z\-0-9]+\.)+[a-zA-Z]{2,}))$/;
+/**
+ * Returns `true` when the supplied string parses as a plausible
+ * email address. Lower-cases first so address-portion comparisons
+ * are case-insensitive. Not RFC-5322 exhaustive; intended for
+ * UI-level pre-submission validation only.
+ */
 export function isValidEmailAddress(emailAddress) {
-    return emailAddress
-        .toLowerCase()
-        .match(/^(([^<>()[\]\\.,;:\s@"]+(\.[^<>()[\]\\.,;:\s@"]+)*)|.(".+"))@((\[[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\])|(([a-zA-Z\-0-9]+\.)+[a-zA-Z]{2,}))$/);
+    return EMAIL_REGEX.test(emailAddress.toLowerCase());
 }
+/**
+ * Svelte action that resizes a CSS grid item to span the row count
+ * required by its first child's height. Useful for masonry-style
+ * layouts where rows are uniform but content height is dynamic.
+ *
+ * Returns a teardown that disconnects the underlying
+ * `ResizeObserver` entirely; the previous implementation only
+ * unobserved the child, which left the observer registered with
+ * the browser and leaked the reference.
+ */
 export function gridItem(element) {
     const firstChild = element.firstElementChild;
     if (!firstChild) {
@@ -202,9 +385,14 @@ export function gridItem(element) {
     });
     observer.observe(firstChild);
     return () => {
-        observer.unobserve(firstChild);
+        observer.disconnect();
     };
 }
+/**
+ * Resolves after `delay` milliseconds. The internal `setTimeout`
+ * call is wrapped in `untrack` so reactive scopes that `await`
+ * `asyncSleep` do not register the sleep as a dependency.
+ */
 export async function asyncSleep(delay) {
     await untrack(() => new Promise((r) => {
         void setTimeout(() => {
@@ -212,6 +400,15 @@ export async function asyncSleep(delay) {
         }, delay);
     }));
 }
+/**
+ * Maps each element of `array` through `callback`, returning the
+ * result synchronously when every callback returns a non-Promise
+ * value and otherwise returning a `Promise<Array<R>>`.
+ *
+ * Tightening the return to `Promise<Array<R>>` unconditionally is
+ * tracked in the Helpers workorder; the union is preserved here to
+ * avoid microtask scheduling for purely-synchronous call sites.
+ */
 export function asyncMap(array, callback) {
     const results = new Array(array.length);
     const pending = [];
@@ -242,6 +439,12 @@ export function asyncMap(array, callback) {
     }
     return Promise.all(pending).then(() => results);
 }
+/**
+ * Calls `callback` on every element of `array`. Returns `void`
+ * when no callback returned a Promise; otherwise returns a
+ * `Promise<void>` that resolves once every pending callback has
+ * settled.
+ */
 export function asyncForEach(array, callback) {
     const pending = [];
     try {
@@ -265,6 +468,10 @@ export function asyncForEach(array, callback) {
     }
     return Promise.all(pending).then(() => { });
 }
+/**
+ * Maps each element to an array of `R` and concatenates the
+ * results. Sync fast-path matches {@link asyncMap}.
+ */
 export function asyncFlatMap(array, callback) {
     const results = new Array(array.length);
     const pending = [];
@@ -295,6 +502,10 @@ export function asyncFlatMap(array, callback) {
     }
     return Promise.all(pending).then(() => results.flat());
 }
+/**
+ * Returns `true` as soon as any callback returns truthy.
+ * Short-circuits on synchronous truthy returns.
+ */
 export function asyncSome(array, callback) {
     const asyncItems = [];
     try {
@@ -327,6 +538,10 @@ export function asyncSome(array, callback) {
         Promise.all(promises).then((r) => r.some(Boolean)),
     ]);
 }
+/**
+ * Returns `true` when every callback returns truthy.
+ * Short-circuits on the first synchronous falsy return.
+ */
 export function asyncAll(array, callback) {
     if (array.length === 0) {
         return true;
@@ -364,7 +579,12 @@ export function asyncAll(array, callback) {
         Promise.all(promises).then((r) => r.every(Boolean)),
     ]);
 }
+/** Alias of {@link asyncAll}. */
 export const asyncEvery = asyncAll;
+/**
+ * Filters the array by the result of `callback`, returning the
+ * indices of matching elements (sorted ascending).
+ */
 export function asyncFilterIndices(array, callback) {
     const filtered = [];
     const pending = [];
@@ -397,6 +617,10 @@ export function asyncFilterIndices(array, callback) {
     }
     return Promise.all(pending).then(() => filtered.sort((a, b) => a - b));
 }
+/**
+ * Filters the array by the result of `callback`, returning the
+ * matching elements (sorted by their original index).
+ */
 export function asyncFilter(array, callback) {
     const filtered = asyncFilterIndices(array, callback);
     if (Array.isArray(filtered)) {
@@ -404,75 +628,47 @@ export function asyncFilter(array, callback) {
     }
     return filtered.then((f) => f.sort((a, b) => a - b).map((i) => array[i]));
 }
+/**
+ * Promise-catch handler that logs in development and silently
+ * swallows in production. Intended for fire-and-forget tasks
+ * where the user-visible error path is already covered (e.g.
+ * `ToastContext.toast`).
+ */
 export function devCatch(e) {
     if (dev) {
         console.log(e);
     }
 }
-export function hasQuery(customFilter) {
-    return (!!customFilter &&
-        customFilter.type == CustomFilterType.Select &&
-        !!customFilter.query &&
-        typeof customFilter.query == 'function');
-}
+/** Type guard for the date-range tuple shape used by the date filter. */
 export function isDateTuple(value) {
     return (Array.isArray(value) &&
         value.length < 3 &&
         (value[0] === null || (typeof value[0] == 'object' && value[0] instanceof Date)) &&
         (value[1] === null || (typeof value[1] == 'object' && value[1] instanceof Date)));
 }
+/**
+ * Type guard for the numeric-range array shape used by the number
+ * filter (single number, single null, or [min, max] tuple).
+ */
 export function isNumericArray(value) {
     return Array.isArray(value) && (value[0] === null || typeof value[0] == 'number');
 }
+/**
+ * Type guard distinguishing a bare {@link Validity} value from a
+ * {@link ValidityWrapper} object carrying both `value` and `reason`.
+ */
 export function isValidityTuple(v) {
     return v != null && typeof v == 'object';
 }
+/** Unicode horizontal ellipsis (U+2026). */
 export const ellipses = '…';
+/** Standard "loading..." placeholder text with U+2026 ellipsis. */
 export const loadingText = 'loading…';
+/**
+ * Type-safe `in` check: narrows `key` to a known key of `obj`.
+ * Useful for indexing into objects when the index variable is
+ * typed as plain `string`.
+ */
 export function isKeyOf(key, obj) {
     return key in obj;
 }
-export function createLocalTable(args) {
-    const localRepo = new LocalTableDataRepository(args.name, args.data, args.getUserId);
-    return TableContext.init(args.defs, args.name, localRepo, {
-        selectionExtractor: args.selectionExtractor,
-        getUserId: args.getUserId,
-    });
-}
-export function getAccessorSortingFn(accessorFn, desc) {
-    return desc
-        ? (_a, _b) => {
-            const a = accessorFn(_a);
-            const b = accessorFn(_b);
-            if (a == undefined && b != undefined) {
-                return 1;
-            }
-            if (b == undefined && a != undefined) {
-                return -1;
-            }
-            if (a < b) {
-                return 1;
-            }
-            if (a > b) {
-                return -1;
-            }
-            return 0;
-        }
-        : (_a, _b) => {
-            const a = accessorFn(_a);
-            const b = accessorFn(_b);
-            if (a == undefined && b != undefined) {
-                return 1;
-            }
-            if (b == undefined && a != undefined) {
-                return -1;
-            }
-            if (a < b) {
-                return -1;
-            }
-            if (a > b) {
-                return 1;
-            }
-            return 0;
-        };
-}

package/dist/Helpers/INamed.d.ts

@@ -1,3 +1,9 @@
+/**
+ * Minimal "thing with a name" interface used by storybook fixtures
+ * and a handful of internal types. Prefer a more specific
+ * interface in new code; this is retained for backwards
+ * compatibility with existing consumers.
+ */
 export interface INamed {
     name: string;
 }

package/dist/Helpers/Storage.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Attempt to load a key from `storage`, JSON-decode the slot, and pass
+ * the raw decoded value through `validator`. Returns the typed value on
+ * success or `fallback` on every failure path:
+ *
+ * - the slot is missing (`getItem` returned `null`);
+ * - the slot is not valid JSON (throws inside `JSON.parse` are caught);
+ * - the decoded value fails `validator`;
+ * - `storage` itself throws (private browsing, quota errors).
+ *
+ * All failure paths return `fallback`. When `dev` is true and a value is
+ * present but malformed, the helper emits a single `console.warn` so
+ * issues are visible during development without ever leaking into
+ * production logs.
+ *
+ * Storage is same-origin and writable by any script running in that
+ * origin, so any value retrieved here is untrusted: the validator is the
+ * only barrier between persisted data and downstream reactive state.
+ *
+ * @typeParam T The validated shape returned on success.
+ * @param storage `localStorage`, `sessionStorage`, or any `Storage`-shaped object.
+ * @param key The slot to read. Callers are responsible for namespacing.
+ * @param validator A type guard that decides whether `raw` is a `T`.
+ * @param fallback Value returned on every failure path.
+ * @returns The validated `T` on success, otherwise `fallback`.
+ */
+export declare function readJSON<T>(storage: Storage, key: string, validator: (raw: unknown) => raw is T, fallback: T): T;
+/**
+ * Persist `value` to `storage` as a JSON envelope of the shape
+ * `{ v: schemaVersion, value }`. The envelope lets readers
+ * (see {@link readVersionedJSON}) detect schema drift and drop entries
+ * written by an older or future build instead of feeding them into
+ * reactive state.
+ *
+ * Throws from `JSON.stringify` (circular references) or from `setItem`
+ * (quota errors, locked storage) are swallowed and logged via
+ * `console.warn` in `dev` only. Persistence failure is never fatal: the
+ * caller's in-memory state is the source of truth.
+ *
+ * @typeParam T The value type to persist.
+ * @param storage `localStorage`, `sessionStorage`, or any `Storage`-shaped object.
+ * @param key The slot to write. Callers are responsible for namespacing.
+ * @param value The value to serialise.
+ * @param schemaVersion An integer that bumps whenever the persisted
+ *                     shape changes in a backwards-incompatible way.
+ */
+export declare function writeJSON<T>(storage: Storage, key: string, value: T, schemaVersion: number): void;
+/**
+ * Read an envelope written by {@link writeJSON} and unwrap its `value`
+ * if the recorded schema version matches `currentVersion` and the
+ * inner value satisfies `validator`.
+ *
+ * Returns `fallback` for every failure path: missing slot, malformed
+ * JSON, missing envelope shape, version mismatch, validator rejection,
+ * or storage throws. A version mismatch is treated as silent rejection
+ * so that callers can roll the schema forward without leaving stale
+ * shapes in user storage.
+ *
+ * @typeParam T The validated inner value type.
+ * @param storage `localStorage`, `sessionStorage`, or any `Storage`-shaped object.
+ * @param key The slot to read. Callers are responsible for namespacing.
+ * @param currentVersion The schema version this reader expects.
+ * @param validator A type guard applied to the unwrapped inner value.
+ * @param fallback Value returned on every failure path.
+ * @returns The validated `T` on success, otherwise `fallback`.
+ */
+export declare function readVersionedJSON<T>(storage: Storage, key: string, currentVersion: number, validator: (raw: unknown) => raw is T, fallback: T): T;