@expofp/config 3.11.10

package/dist/lib/strip-defaults.d.ts

@@ -0,0 +1,27 @@
+import * as z from 'zod';
+/**
+ * Return a clone of `schema` with every `.default()` and `.prefault()` removed,
+ * recursively.
+ *
+ * Layered config parses each source (manifest, options, localStorage, URL)
+ * against an all-optional schema and merges the results. A default left in
+ * those schemas would materialize on *every* layer's parse — and in Zod 4
+ * `.partial()` does NOT suppress it — so a higher, empty layer would stomp a
+ * lower layer's explicit value. Strip defaults for the per-layer parse and
+ * apply them once, afterwards (see `ConfigDefaults`).
+ *
+ * A stripped field becomes `.optional()`: a default exists precisely because
+ * the input may omit the key, so the stripped schema parses a partial layer
+ * (missing key → absent) instead of erroring on the now-defaultless field.
+ *
+ * Recurses through objects, arrays, and the optional/nullable/readonly wrapper
+ * chain, carrying each node's `.meta()` across (the `asset`/`cssAsset` tags
+ * `DataSchema` relies on). Nodes it does not recognize — unions, records,
+ * tuples, lazy, pipes — are returned untouched, so a default nested inside one
+ * of those is left in place, and object-level modes/refinements (`.strict()`,
+ * `.refine()`, `.min()`, …) on rebuilt containers are not carried over. The
+ * config schemas keep defaults at the object top level and use none of those,
+ * so the boundary does not bite; widen the checks below if that changes.
+ */
+export declare function stripDefaults(schema: z.core.$ZodType): z.ZodType;
+//# sourceMappingURL=strip-defaults.d.ts.map

package/dist/lib/strip-defaults.js

@@ -0,0 +1,55 @@
+import * as z from 'zod';
+/**
+ * Return a clone of `schema` with every `.default()` and `.prefault()` removed,
+ * recursively.
+ *
+ * Layered config parses each source (manifest, options, localStorage, URL)
+ * against an all-optional schema and merges the results. A default left in
+ * those schemas would materialize on *every* layer's parse — and in Zod 4
+ * `.partial()` does NOT suppress it — so a higher, empty layer would stomp a
+ * lower layer's explicit value. Strip defaults for the per-layer parse and
+ * apply them once, afterwards (see `ConfigDefaults`).
+ *
+ * A stripped field becomes `.optional()`: a default exists precisely because
+ * the input may omit the key, so the stripped schema parses a partial layer
+ * (missing key → absent) instead of erroring on the now-defaultless field.
+ *
+ * Recurses through objects, arrays, and the optional/nullable/readonly wrapper
+ * chain, carrying each node's `.meta()` across (the `asset`/`cssAsset` tags
+ * `DataSchema` relies on). Nodes it does not recognize — unions, records,
+ * tuples, lazy, pipes — are returned untouched, so a default nested inside one
+ * of those is left in place, and object-level modes/refinements (`.strict()`,
+ * `.refine()`, `.min()`, …) on rebuilt containers are not carried over. The
+ * config schemas keep defaults at the object top level and use none of those,
+ * so the boundary does not bite; widen the checks below if that changes.
+ */
+export function stripDefaults(schema) {
+    if (schema instanceof z.ZodDefault || schema instanceof z.ZodPrefault) {
+        return keepMeta(schema, stripDefaults(schema.unwrap()).optional());
+    }
+    if (schema instanceof z.ZodOptional) {
+        return keepMeta(schema, stripDefaults(schema.unwrap()).optional());
+    }
+    if (schema instanceof z.ZodNullable) {
+        return keepMeta(schema, stripDefaults(schema.unwrap()).nullable());
+    }
+    if (schema instanceof z.ZodReadonly) {
+        return keepMeta(schema, stripDefaults(schema.unwrap()).readonly());
+    }
+    if (schema instanceof z.ZodArray) {
+        return keepMeta(schema, z.array(stripDefaults(schema.element)));
+    }
+    if (schema instanceof z.ZodObject) {
+        const shape = {};
+        for (const [key, field] of Object.entries(schema.shape)) {
+            shape[key] = stripDefaults(field);
+        }
+        return keepMeta(schema, z.object(shape));
+    }
+    return schema;
+}
+/** Copy `source`'s registered `.meta()` onto `target`, if it has any. */
+function keepMeta(source, target) {
+    const meta = source.meta();
+    return meta ? target.meta(meta) : target;
+}

package/dist/lib/url-codec.d.ts

@@ -0,0 +1,46 @@
+/**
+ * URL query codec — value ⇄ `qs`-style bracketed query string, with coercion
+ * driven by an ordinary Zod schema (no `z.coerce`, nothing URL-specific in it):
+ *
+ *   parseFromUrl(schema, input)   URL or query string → validated value
+ *   toQueryString(value)          value → query string
+ *
+ * Decoding is two steps:
+ *   1. deflatten the bracketed query into a nested structure of strings:
+ *        view[center][lat]=10   → { view: { center: { lat: '10' } } }
+ *        tags[0]=a&tags[1]=b    → { tags: ['a', 'b'] }
+ *        exhibitors[0][id]=1    → { exhibitors: [ { id: '1' } ] }
+ *      Numeric indices are honored up to `qs`'s default `arrayLimit` (20);
+ *      above that the segment stays an object key, so a crafted
+ *      `?intents[999999999]=x` cannot inflate a billion-slot sparse array.
+ *   2. walk the schema (`z.toJSONSchema`) alongside that structure, coerce each
+ *      leaf to its declared type (string→number/boolean/…), then `schema.parse`.
+ *
+ * Encoding inverts step 1: nested value → bracketed keys (arrays use numeric
+ * indices). Round-trips for scalars, nested objects, scalar arrays and arrays of
+ * objects, provided you decode with the SAME schema. A discriminated union
+ * coerces by the arm its discriminator names (so `intents[…]` args get their
+ * types); other unions are left as-is for `schema.parse` to handle.
+ *
+ * The bracket syntax matches the widely-used `qs` library, so these query
+ * strings interop with `qs.parse` / `qs.stringify` and anything built on them.
+ */
+import type * as z from 'zod';
+export declare function parseFromUrl<S extends z.ZodType>(schema: S, input: string | URL): z.infer<S>;
+export declare function safeParseFromUrl<S extends z.ZodType>(schema: S, input: string | URL): z.ZodSafeParseResult<z.core.output<S>>;
+/**
+ * Like `parseFromUrl`, but drops the query keys that fail validation instead
+ * of throwing — a visitor-edited URL must never break the caller. Expects an
+ * all-optional object schema (which every per-source config slice is), so the
+ * parse is guaranteed to succeed once the offending keys are gone; anything
+ * not attributable to a top-level key still throws (a programming error, not
+ * URL noise).
+ */
+export declare function parseFromUrlTolerant<S extends z.ZodType>(schema: S, input: string | URL): {
+    value: z.infer<S>;
+    invalidKeys: string[];
+};
+/** URL or query string → the deflattened structure, keys in first-occurrence order. */
+export declare function deflattenQuery(input: string | URL): Record<string, unknown>;
+export declare function toQueryString(value: unknown): string;
+//# sourceMappingURL=url-codec.d.ts.map

package/dist/lib/url-codec.js

@@ -0,0 +1,165 @@
+import { coerceValue, toJsonSchema } from './json-schema.js';
+/* ── Decode: URL → value ───────────────────────────────────────────────────── */
+export function parseFromUrl(schema, input) {
+    return schema.parse(coerceToSchema(schema, input));
+}
+export function safeParseFromUrl(schema, input) {
+    return schema.safeParse(coerceToSchema(schema, input));
+}
+/**
+ * Like `parseFromUrl`, but drops the query keys that fail validation instead
+ * of throwing — a visitor-edited URL must never break the caller. Expects an
+ * all-optional object schema (which every per-source config slice is), so the
+ * parse is guaranteed to succeed once the offending keys are gone; anything
+ * not attributable to a top-level key still throws (a programming error, not
+ * URL noise).
+ */
+export function parseFromUrlTolerant(schema, input) {
+    const candidate = coerceToSchema(schema, input);
+    const invalidKeys = [];
+    let result = schema.safeParse(candidate);
+    while (!result.success) {
+        const offending = new Set();
+        for (const issue of result.error.issues) {
+            const key = String(issue.path[0] ?? '');
+            if (key in candidate)
+                offending.add(key);
+        }
+        if (!offending.size)
+            throw result.error;
+        for (const key of offending) {
+            delete candidate[key];
+            invalidKeys.push(key);
+        }
+        result = schema.safeParse(candidate);
+    }
+    return { value: result.data, invalidKeys };
+}
+function coerceToSchema(schema, input) {
+    return coerceValue(toJsonSchema(schema), deflatten(toSearchParams(input)));
+}
+/* ── Deflatten: bracketed keys → nested objects/arrays of strings (schema-blind) ── */
+/** URL or query string → the deflattened structure, keys in first-occurrence order. */
+export function deflattenQuery(input) {
+    return deflatten(toSearchParams(input));
+}
+function deflatten(params) {
+    const root = {};
+    for (const [rawKey, value] of params) {
+        assignPath(root, parseKey(rawKey), value);
+    }
+    return root;
+}
+/** "a[b][c]" → ["a","b","c"] · "a[]" → ["a",""] · "a[0]" → ["a","0"] · "a" → ["a"]. */
+function parseKey(key) {
+    return key.replace(/\]/g, '').split('[');
+}
+/**
+ * Prototype-chain keys, never valid config keys. A query like
+ * `?__proto__[x]=1` or `?constructor[prototype][x]=1` would otherwise walk into
+ * `Object.prototype` / `Function.prototype` and pollute every object on the
+ * page — so any path that names one is dropped whole.
+ */
+const FORBIDDEN_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
+/**
+ * `qs`'s default `arrayLimit`: the largest bracket segment still treated as an
+ * array index. Above it the segment stays an object key — an unchecked index
+ * would set `length` directly, and `coerceValue`/Zod then iterate that length
+ * (`?intents[999999999]=x` → a billion-slot walk, twice per URL boot).
+ */
+const ARRAY_INDEX_LIMIT = 20;
+function isArrayIndex(segment) {
+    return /^\d+$/.test(segment) && Number(segment) <= ARRAY_INDEX_LIMIT;
+}
+function assignPath(root, path, value) {
+    let parent = root;
+    let parentKey = '';
+    let node = root;
+    for (let i = 0; i < path.length; i++) {
+        const segment = path[i];
+        if (FORBIDDEN_KEYS.has(segment))
+            return;
+        const isLast = i === path.length - 1;
+        const append = segment === '';
+        // an array addressed by anything but a capped index or an append is
+        // demoted to a plain object first (qs semantics) — writing the key into
+        // the array would otherwise grow `length` without bound
+        if (Array.isArray(node) && !append && !isArrayIndex(segment)) {
+            node = demoteArray(node, parent, parentKey);
+        }
+        if (isLast) {
+            if (append && Array.isArray(node)) {
+                node.push(value);
+            }
+            else {
+                node[segment] = value;
+            }
+            return;
+        }
+        const next = path[i + 1];
+        const childIsArray = next === '' || isArrayIndex(next);
+        if (append && Array.isArray(node)) {
+            const child = childIsArray ? [] : {};
+            node.push(child);
+            parent = node;
+            parentKey = String(node.length - 1);
+            node = child;
+        }
+        else {
+            const container = node;
+            const current = container[segment];
+            // an earlier `?key=value` entry may have parked a scalar here — replace
+            // it with a container (last writer wins, same as the reverse order);
+            // descending into a string primitive would throw on assignment
+            if (current === null || typeof current !== 'object') {
+                container[segment] = childIsArray ? [] : {};
+            }
+            parent = node;
+            parentKey = segment;
+            node = container[segment];
+        }
+    }
+}
+/** Copy an array's entries onto a plain object (indices become keys) and swap it into the parent. */
+function demoteArray(arr, parent, parentKey) {
+    const demoted = {};
+    arr.forEach((item, index) => {
+        demoted[index] = item;
+    });
+    parent[parentKey] = demoted;
+    return demoted;
+}
+/* ── Encode: value → bracketed query string (inverts deflatten) ─────────────── */
+export function toQueryString(value) {
+    const params = new URLSearchParams();
+    encodeNode(value, '', params);
+    return params.toString();
+}
+function encodeNode(value, prefix, params) {
+    if (value === undefined || value === null) {
+        return;
+    }
+    if (Array.isArray(value)) {
+        value.forEach((item, index) => encodeNode(item, `${prefix}[${index}]`, params));
+        return;
+    }
+    if (typeof value === 'object') {
+        for (const [key, child] of Object.entries(value)) {
+            encodeNode(child, prefix ? `${prefix}[${key}]` : key, params);
+        }
+        return;
+    }
+    // objects/arrays/null returned above, so `value` is a scalar here
+    // eslint-disable-next-line @typescript-eslint/no-base-to-string -- value is a scalar, not an object
+    params.append(prefix, String(value));
+}
+/** Accepts a URL instance, a full URL string, or a bare query (leading `?` optional). */
+function toSearchParams(input) {
+    if (input instanceof URL) {
+        return input.searchParams;
+    }
+    const q = input.indexOf('?');
+    const afterQuery = q >= 0 ? input.slice(q + 1) : input;
+    const hash = afterQuery.indexOf('#');
+    return new URLSearchParams(hash >= 0 ? afterQuery.slice(0, hash) : afterQuery);
+}

package/dist/lib/url-intents.d.ts

@@ -0,0 +1,30 @@
+/**
+ * URL intent shortcuts — the typable counterpart to the canonical bracketed
+ * form (`?intents[0][name]=selectBooth&intents[0][args][0]=A-12`): the intent
+ * name is the query key, its args are the value.
+ *
+ *   ?selectBooth=A-12                          one intent, a lone value is its 1-tuple args
+ *   ?selectBooth=A-12&changeLanguage=fr        two intents, played in param order
+ *   ?selectRoute[0]=A-12&selectRoute[1]=B-30   qs brackets — here one waypoint-list argument
+ *   ?showPathway[0]=p-1&showPathway[1][0]=e-1  …or a real multi-argument tuple
+ *   ?openPlanner[fromBookmarks]=true           args coerce to the arm's declared types
+ *
+ * The key set is the `IntentsSchema` arm names, so a new intent gets its
+ * shortcut automatically and the schema stays the URL allowlist — a query can
+ * never name a method outside the union. One shortcut per intent name (a
+ * repeated key keeps the last value, plain qs semantics); the bracketed
+ * `intents[…]` form remains the general syntax for repeats and exotic args.
+ */
+import { type Intent } from '@expofp/schema';
+/**
+ * Extract shortcut intents from a page URL, in first-occurrence param order.
+ * Tolerant like `parseFromUrlTolerant`: a key whose value does not fit its
+ * intent's args is dropped and reported in `invalidKeys` — a visitor-edited
+ * URL must never break boot. Keys naming no intent are ignored (they belong
+ * to other query consumers).
+ */
+export declare function parseIntentsFromUrl(input: string | URL): {
+    intents: Intent[];
+    invalidKeys: string[];
+};
+//# sourceMappingURL=url-intents.d.ts.map

package/dist/lib/url-intents.js

@@ -0,0 +1,58 @@
+/**
+ * URL intent shortcuts — the typable counterpart to the canonical bracketed
+ * form (`?intents[0][name]=selectBooth&intents[0][args][0]=A-12`): the intent
+ * name is the query key, its args are the value.
+ *
+ *   ?selectBooth=A-12                          one intent, a lone value is its 1-tuple args
+ *   ?selectBooth=A-12&changeLanguage=fr        two intents, played in param order
+ *   ?selectRoute[0]=A-12&selectRoute[1]=B-30   qs brackets — here one waypoint-list argument
+ *   ?showPathway[0]=p-1&showPathway[1][0]=e-1  …or a real multi-argument tuple
+ *   ?openPlanner[fromBookmarks]=true           args coerce to the arm's declared types
+ *
+ * The key set is the `IntentsSchema` arm names, so a new intent gets its
+ * shortcut automatically and the schema stays the URL allowlist — a query can
+ * never name a method outside the union. One shortcut per intent name (a
+ * repeated key keeps the last value, plain qs semantics); the bracketed
+ * `intents[…]` form remains the general syntax for repeats and exotic args.
+ */
+import { IntentsSchema } from '@expofp/schema';
+import { coerceValue, toJsonSchema } from './json-schema.js';
+import { deflattenQuery } from './url-codec.js';
+const intentNames = new Set(IntentsSchema.options.map((arm) => arm.shape.name.value));
+/**
+ * Extract shortcut intents from a page URL, in first-occurrence param order.
+ * Tolerant like `parseFromUrlTolerant`: a key whose value does not fit its
+ * intent's args is dropped and reported in `invalidKeys` — a visitor-edited
+ * URL must never break boot. Keys naming no intent are ignored (they belong
+ * to other query consumers).
+ */
+export function parseIntentsFromUrl(input) {
+    const intents = [];
+    const invalidKeys = [];
+    for (const [name, value] of Object.entries(deflattenQuery(input))) {
+        if (!intentNames.has(name))
+            continue;
+        // A bare `?key` is an empty args tuple. Anything else is ambiguous between
+        // the args TUPLE and a single array-valued ARGUMENT: `?selectBooth[0]=A`
+        // is a 1-tuple, `?selectRoute[0]=A&selectRoute[1]=B` one waypoint list.
+        // Try the tuple reading first (existing shortcuts keep their meaning),
+        // then the same value wrapped as the tuple's sole argument; the first
+        // candidate that validates wins. Only this function knows about the
+        // ambiguity — the schema and the url-codec never see it.
+        const asTuple = Array.isArray(value) ? value : [value];
+        const candidates = value === '' ? [[]] : [asTuple, [asTuple]];
+        // args arrive as raw query strings — coerce them by the schema of the arm
+        // `name` picks (booleans/numbers inside object args), exactly like the
+        // bracketed `intents[…]` form going through the url-codec
+        const parsed = candidates
+            .map((args) => IntentsSchema.safeParse(coerceValue(toJsonSchema(IntentsSchema), { name, args })))
+            .find((result) => result.success);
+        if (parsed) {
+            intents.push(parsed.data);
+        }
+        else {
+            invalidKeys.push(name);
+        }
+    }
+    return { intents, invalidKeys };
+}

package/dist/lib/validate-flag.d.ts

@@ -0,0 +1,10 @@
+import { type StorageLike } from './local-storage-codec.js';
+/**
+ * Whether to validate schemas during this load. Reads `validateSchema` from the
+ * URL query (`?validateSchema=1`) then localStorage (`efp-validateSchema`), the
+ * URL winning; absent from both, off. A URL value other than `1/true/yes/on`
+ * reads as an explicit off (and overrides localStorage). Node callers (the
+ * offline CLI) pass neither and always get `false`.
+ */
+export declare function readValidateFlag(url?: string, storage?: StorageLike): boolean;
+//# sourceMappingURL=validate-flag.d.ts.map

package/dist/lib/validate-flag.js

@@ -0,0 +1,36 @@
+/**
+ * The `validateSchema` opt-in, read up front from the page inputs.
+ *
+ * Schema validation on load — the manifest in `load-config.ts` and every
+ * referenced document in `visit-resources.ts` — is a diagnostic gate: the
+ * pipeline never depends on the parse output, so it is OFF by default because
+ * parsing the large expo documents costs time. This reads the opt-in from the
+ * same URL-query / localStorage layering every config flag uses (the shared
+ * codecs and the `validateSchema` field on `UrlConfigSchema` /
+ * `LocalStorageConfigSchema`), the URL winning over localStorage.
+ *
+ * It is read HERE, before the config layers are assembled, rather than off the
+ * effective config, because the parses it gates run first — the manifest parse
+ * is `loadConfig`'s opening step, and the document parses fire while the layers
+ * are still being fetched. For the same reason it does not honor `ignoreQuery`
+ * (that value is not settled yet): `?validateSchema=1` turns validation on even
+ * for an embed that otherwise isolates itself from the page URL, which is what a
+ * developer reaching for this diagnostic wants.
+ */
+import { LocalStorageConfigSchema, UrlConfigSchema } from '@expofp/schema';
+import { parseFromStorage } from './local-storage-codec.js';
+import { parseFromUrlTolerant } from './url-codec.js';
+/**
+ * Whether to validate schemas during this load. Reads `validateSchema` from the
+ * URL query (`?validateSchema=1`) then localStorage (`efp-validateSchema`), the
+ * URL winning; absent from both, off. A URL value other than `1/true/yes/on`
+ * reads as an explicit off (and overrides localStorage). Node callers (the
+ * offline CLI) pass neither and always get `false`.
+ */
+export function readValidateFlag(url, storage) {
+    const fromUrl = url !== undefined ? parseFromUrlTolerant(UrlConfigSchema, url).value.validateSchema : undefined;
+    const fromStorage = storage
+        ? parseFromStorage(LocalStorageConfigSchema, storage).validateSchema
+        : undefined;
+    return fromUrl ?? fromStorage ?? false;
+}

package/dist/lib/validate-timing.d.ts

@@ -0,0 +1,3 @@
+/** Time one schema `parse()` and record it against the running summary. */
+export declare function timeValidation<T>(parse: () => T): T;
+//# sourceMappingURL=validate-timing.d.ts.map

package/dist/lib/validate-timing.js

@@ -0,0 +1,52 @@
+import debug from 'debug';
+/**
+ * Timing for the schema validations gated by the opt-in `validateSchema` flag
+ * (the manifest in `load-config.ts`, every referenced document in
+ * `visit-resources.ts`).
+ *
+ * {@link timeValidation} wraps one `parse()`, folds its cost into a running
+ * total kept since the module first loaded (i.e. per page load), and logs a
+ * cumulative summary on `efp:config:validate`. Logging is throttled to at most
+ * one line per second — a burst of document validations emits one leading line,
+ * then a trailing line once it settles carries the final total. When the
+ * namespace is disabled (the production default) the wrapper is a straight
+ * pass-through, so the cost is a single boolean check.
+ */
+const log = debug('efp:config:validate');
+let totalMs = 0;
+let count = 0;
+// -Infinity so the first validation always clears the 1s gate and emits a
+// leading line, however far into the page's life it runs.
+let lastEmitMs = -Infinity;
+let trailingScheduled = false;
+function emit() {
+    lastEmitMs = performance.now();
+    log('%d validations, %sms total since page load', count, totalMs.toFixed(1));
+}
+/** Time one schema `parse()` and record it against the running summary. */
+export function timeValidation(parse) {
+    if (!log.enabled)
+        return parse();
+    const start = performance.now();
+    try {
+        return parse();
+    }
+    finally {
+        totalMs += performance.now() - start;
+        count++;
+        const sinceEmit = performance.now() - lastEmitMs;
+        if (sinceEmit >= 1000) {
+            emit();
+        }
+        else if (!trailingScheduled) {
+            // Flush the final total after the burst settles, without holding a Node
+            // process open (unref is a no-op on the browser's numeric timer id).
+            trailingScheduled = true;
+            const timer = setTimeout(() => {
+                trailingScheduled = false;
+                emit();
+            }, 1000 - sinceEmit);
+            timer.unref?.();
+        }
+    }
+}

package/dist/lib/visit-resources.d.ts

@@ -0,0 +1,85 @@
+/**
+ * visit-resources — the one schema-guided resource walk, used for both jobs:
+ *
+ * - **Absolutization** (`documentRef`): every ref the config mints carries a
+ *   `process` hook = "validate with my schema, then walk me with a handler
+ *   that rebases relative paths onto the ref's own directory". Resolution
+ *   therefore always settles documents whose asset URLs are absolute.
+ * - **Serialization** (`serializeConfigResources`): the same walk over the
+ *   whole config with a storage handler — and a `$ref` is just another kind
+ *   of asset, one whose handling resolves the document and recurses into it.
+ *
+ * The walk is value-driven and schema-guided: meta tags say what a string
+ * leaf holds (`asset`, `svgAsset`, `cssAsset`), and a
+ * `{ $ref }` object is an external document (its node's `refSchema` meta
+ * points at the document's schema).
+ * Which behaviors fire falls out of which hooks the handler provides — a
+ * handler without `document` leaves refs alone. `value` is mutated in place
+ * and must be an object or array.
+ */
+import { type Ref } from '@expofp/resolve';
+import type * as z from 'zod';
+export interface ResourceHandler {
+    /**
+     * One asset URL; return the URL to write in its place. `optional` marks an
+     * `optionalAsset`-tagged leaf — a URL minted without an existence check, so
+     * the resource may not exist and storing it is best-effort.
+     */
+    asset(url: string, optional?: boolean): string | Promise<string>;
+    /** A ref's resolved — and internally rewritten — document; return the new ref URL. */
+    document?(refUrl: string, document: unknown): string | Promise<string>;
+    /**
+     * Tolerate a ref that failed to resolve — the field is dropped. Omitted,
+     * the failure propagates and aborts the walk; throw from here to abort
+     * selectively.
+     */
+    documentError?(refUrl: string, error: unknown): void;
+    /**
+     * Fetch one `@import`ed stylesheet's text so the walk can splice it into the
+     * importing CSS (see `inlineCssImports` — a stylesheet kept as a fetched
+     * file would be served with the wrong MIME type, its inner `url(…)`s left
+     * remote). Omitted, `@import` URLs are treated as opaque assets — right for
+     * live absolutization, where the browser fetches them itself.
+     */
+    stylesheetText?(url: string): string | Promise<string>;
+}
+export interface VisitResourcesOptions {
+    signal?: AbortSignal | null;
+}
+/** Set by `loadConfig` from the `validateSchema` flag; gates the parses below. */
+export declare function setValidateManifest(on: boolean): void;
+/**
+ * An own, mutable copy of a document — validated when the flag is on.
+ *
+ * Every consumer of a resolved document needs its own copy anyway (`resolve`
+ * deep-freezes what it settles, and downstream code mutates in place), and a
+ * Zod parse of these loose, transform-free schemas already IS a fresh copy.
+ * So validation rides the copy that had to be made regardless: parse when
+ * validating, `deepClone` when not — one copy either way, never two.
+ */
+export declare function validateOrClone<T>(schema: z.ZodType, value: T): T;
+/**
+ * Decorate a ref with the one processing rule for referenced documents: take
+ * an own copy — validated against `schema` when the flag is on (see
+ * `validateOrClone`) — then make every schema-tagged resource path absolute
+ * against the ref's own directory — the standard web rule for a live load.
+ * An optional `normalize` hook runs on the copy in between: it folds legacy
+ * shape quirks onto the canonical keys, so the schema-guided walk (and every
+ * consumer) sees the canonical shape (e.g. `normalizeFpSvgLayerAliases`).
+ *
+ * An offline copy instead references its saved documents by *relative*
+ * (page-relative, host-less) paths, and their assets already carry final
+ * serialized paths. Rebasing one of those onto the doc's own relative
+ * directory would double the path (`…/<doc-dir>/<doc-dir>/asset` → 404), so
+ * absolutization is skipped whenever the ref's directory is not itself
+ * absolute — the runtime then resolves the page-relative asset against the
+ * page, wherever the copy is mounted. (A rooted `/…` offline ref stays
+ * absolute, and its already-rooted assets pass through unchanged either way.)
+ *
+ * The rewrite runs on an own copy, so it never touches the fetch-cached raw
+ * document.
+ */
+export declare function documentRef<R extends Ref<unknown>>(ref: R, schema: z.ZodType, normalize?: (document: object) => void): R;
+/** Rewrite every schema-tagged resource of `value` through `handler`, in place. */
+export declare function visitResources(schema: z.ZodType, value: object, handler: ResourceHandler, options?: VisitResourcesOptions): Promise<void>;
+//# sourceMappingURL=visit-resources.d.ts.map