@expofp/config 3.28.3 → 3.30.0

package/README.md

@@ -32,5 +32,9 @@ been retired (`?hide=`, `?centerxy=`, `?lang=`, …) are listed in `retiredKeys`
 old link opens a clean plan instead of replaying its query as search text.
 
 Also: `applyIntents` (dispatch `selectBooth` / `changeLanguage` / … to the floor plan),
-`serializeConfigResources` (collect schema-tagged assets + payloads for offline copies), and
-`toDebugSettings` (config schema → `@expofp/debug` panel). Types re-export from `@expofp/schema`.
+`serializeConfigResources` (collect schema-tagged assets + payloads for offline copies and normalized
+expo folders), `resolveUrl` / `compactUrl` (the `$/<expo>/<hash>/<name>` ⇄
+`https://<expo>.expofp.com/immutable/<hash>/<name>` codec of a normalized folder's store refs —
+`loadConfig` follows the folder's pointer `manifest.json` to its immutable snapshot and expands the
+refs, so an effective config only ever carries full URLs), and `toDebugSettings` (config schema →
+`@expofp/debug` panel). Types re-export from `@expofp/schema`.

package/dist/index.d.ts

@@ -5,7 +5,8 @@ export { parseDeprecatedUrlParams } from './lib/deprecated-url-params.js';
 export { type LegacyOneShot, type LegacyPrimary, type LegacyUrlQuery, parseLegacyQuery, serializeSelection, splitPlatformParams, type UrlSelection, } from './lib/legacy-url.js';
 export { loadConfig } from './lib/load-config.js';
 export { type StorageLike } from './lib/local-storage-codec.js';
-export { type ConfigResourceStore, serializeConfigResources, } from './lib/serialize-config-resources.js';
+export { type ConfigResourceStore, serializationFormat, serializeConfigResources, SERIALIZER_VERSION, } from './lib/serialize-config-resources.js';
+export { compactUrl, resolveUrl } from './lib/store-ref.js';
 export { parseFromUrlTolerant } from './lib/url-codec.js';
 export { parseIntentsFromUrl } from './lib/url-intents.js';
 export { type Config, type Consent, type Manifest, type Options } from '@expofp/schema';

package/dist/index.js

@@ -6,6 +6,7 @@ export { toDebugSettings } from './lib/debug-settings.js';
 export { parseDeprecatedUrlParams } from './lib/deprecated-url-params.js';
 export { parseLegacyQuery, serializeSelection, splitPlatformParams, } from './lib/legacy-url.js';
 export { loadConfig } from './lib/load-config.js';
-export { serializeConfigResources, } from './lib/serialize-config-resources.js';
+export { serializationFormat, serializeConfigResources, SERIALIZER_VERSION, } from './lib/serialize-config-resources.js';
+export { compactUrl, resolveUrl } from './lib/store-ref.js';
 export { parseFromUrlTolerant } from './lib/url-codec.js';
 export { parseIntentsFromUrl } from './lib/url-intents.js';

package/dist/lib/load-config.js

@@ -8,10 +8,11 @@ import { parseFromStorage } from './local-storage-codec.js';
 import { normalizeFpSvgLayerAliases } from './normalize-fp-svg.js';
 import { normalizeLegacyData } from './normalize-legacy-data.js';
 import { applyRebookingData } from './rebooking.js';
+import { resolveUrl } from './store-ref.js';
 import { parseFromUrlTolerant } from './url-codec.js';
 import { parseIntentsFromUrl } from './url-intents.js';
 import { readValidateFlag } from './validate-flag.js';
-import { documentRef, setValidateManifest, validateOrClone } from './visit-resources.js';
+import { documentRef, isRefShaped, setValidateManifest, validateOrClone, visitResources, } from './visit-resources.js';
 const log = debug('efp:config');
 /**
  * Assemble the effective config — the runtime's single, complete copy of the
@@ -42,11 +43,17 @@ export async function loadConfig(manifest, options, url, storage) {
     // layers merge, so it can't come off the effective config. See readValidateFlag.
     const validateSchema = readValidateFlag(url, storage);
     setValidateManifest(validateSchema); // gates the referenced-document parses (visit-resources)
-    // Take an OWN copy of the resolved manifest (validated when the flag is on —
-    // see validateOrClone): `resolve` deep-freezes what it settles, an offline
-    // manifest carries the full event data (booths, exhibitors, …), and
-    // `normalizeLegacyData` below mutates those nested objects in place.
-    manifest = validateOrClone(ManifestSchema, await resolve(manifest));
+    // A normalized expo folder's mutable `manifest.json` is a tiny pointer
+    // (`{"$ref": "$/<expo>/<hash>/manifest.json"}`) — follow the chain down to
+    // the snapshot first. Then take an OWN copy of the settled manifest
+    // (validated when the flag is on — see validateOrClone): `resolve`
+    // deep-freezes what it settles, an offline or normalized manifest carries
+    // the full event data (booths, exhibitors, …), and `normalizeLegacyData`
+    // below mutates those nested objects in place. Store refs (`$/…`) expand
+    // into their canonical immutable URLs right here — the effective config
+    // only ever carries full URLs, so no consumer sees the notation.
+    manifest = validateOrClone(ManifestSchema, await resolveManifestChain(manifest));
+    await expandManifestStoreRefs(manifest);
     // The legacy event-data directory and the data-revision pin are INPUTS,
     // consumed right here — the effective config carries only the refs derived
     // from them, so neither is merged.
@@ -195,6 +202,45 @@ export async function loadConfig(manifest, options, url, storage) {
     deepFreeze(config);
     return config;
 }
+/**
+ * Hops a manifest pointer chain may take before it must have settled. The
+ * normalized form needs exactly one (mutable pointer → immutable snapshot);
+ * the ceiling only guards against a cyclic or runaway chain.
+ */
+const MANIFEST_POINTER_HOPS_MAX = 3;
+/**
+ * Follow the «pointer → snapshot» chain: a settled manifest that is itself
+ * ref-shaped is a pointer — resolve what it points at, until a document
+ * settles. A store ref (`$/…`) expands by the fixed convention before its
+ * fetch, the input ref included; a rooted local pointer resolves against
+ * the page like any rooted URL. Chain-walking lives here, not in
+ * `@expofp/resolve` — the resolver stays one-layered and domain-free.
+ */
+async function resolveManifestChain(input) {
+    let current = input;
+    for (let hops = 0;; hops++) {
+        if (isRefShaped(current))
+            current = { ...current, $ref: resolveUrl(current.$ref) };
+        const settled = await resolve(current);
+        if (!isRefShaped(settled))
+            return settled;
+        if (hops >= MANIFEST_POINTER_HOPS_MAX) {
+            throw new Error(`loadConfig: manifest pointer chain deeper than ${MANIFEST_POINTER_HOPS_MAX} at ${settled.$ref}`);
+        }
+        log('loadConfig', 'manifest is a pointer, following it to', settled.$ref);
+        current = { $ref: settled.$ref };
+    }
+}
+/**
+ * Expand every store ref (`$/…`) of a normalized manifest — asset URLs and
+ * document `$ref`s alike — into its canonical URL, via the one schema-guided
+ * walk. Passthrough for other values, so compat and offline manifests come
+ * out untouched.
+ */
+async function expandManifestStoreRefs(manifest) {
+    const expand = (url) => resolveUrl(url);
+    await visitResources(ManifestSchema, manifest, { asset: expand, ref: expand });
+}
 async function loadLegacyDataJs(baseUrl, version) {
     // data.js is a window-assigning script like fp.svg.js — resolve() evaluates
     // it to its globals and the expo data document rides on `__data`. The

package/dist/lib/serialize-config-resources.d.ts

@@ -19,4 +19,28 @@ export type ConfigResourceStore = ResourceHandler;
 export declare function serializeConfigResources(config: Config, store: ConfigResourceStore, options?: {
     signal?: AbortSignal | null;
 }): Promise<Manifest>;
+/**
+ * Version of the serialization POLICY — what {@link serializeConfigResources}
+ * does to a config beyond what the schema says: the walk's rewrite rules
+ * (`visit-resources`), the CSS `@import` splicing, the legacy normalization.
+ * Bump it by hand when that behavior changes without a schema change; it is
+ * one half of {@link serializationFormat}.
+ */
+export declare const SERIALIZER_VERSION = 1;
+/**
+ * The identity of the form a serialized manifest takes — the text a generator
+ * hashes into its format stamp. Two halves: the JSON Schema of `ConfigSchema`
+ * (the shape every snapshot follows; the referenced document schemas ride
+ * inside it, so a drawing- or wayfinding-schema change counts too — a schema
+ * change is a format change by construction, no hand bump needed) and
+ * {@link SERIALIZER_VERSION}. Deterministic across processes and platforms
+ * for one build of the packages.
+ *
+ * A snapshot built under one stamp must not be served under a runtime that
+ * expects another: the cloud generator (plan G § 2, wave G2) keys its
+ * level-0 "nothing changed" skip on this stamp next to the data revision, so
+ * a deploy that changes the format rebuilds every snapshot and a deploy that
+ * does not leaves them alone.
+ */
+export declare function serializationFormat(): string;
 //# sourceMappingURL=serialize-config-resources.d.ts.map

package/dist/lib/serialize-config-resources.js

@@ -1,4 +1,5 @@
 import { ConfigSchema } from '@expofp/schema';
+import * as z from 'zod';
 import { visitResources } from './visit-resources.js';
 /**
  * Serialize a loaded config into a portable manifest: every schema-tagged
@@ -18,3 +19,32 @@ export async function serializeConfigResources(config, store, options) {
     await visitResources(ConfigSchema, manifest, store, { signal: options?.signal });
     return manifest;
 }
+/**
+ * Version of the serialization POLICY — what {@link serializeConfigResources}
+ * does to a config beyond what the schema says: the walk's rewrite rules
+ * (`visit-resources`), the CSS `@import` splicing, the legacy normalization.
+ * Bump it by hand when that behavior changes without a schema change; it is
+ * one half of {@link serializationFormat}.
+ */
+export const SERIALIZER_VERSION = 1;
+/**
+ * The identity of the form a serialized manifest takes — the text a generator
+ * hashes into its format stamp. Two halves: the JSON Schema of `ConfigSchema`
+ * (the shape every snapshot follows; the referenced document schemas ride
+ * inside it, so a drawing- or wayfinding-schema change counts too — a schema
+ * change is a format change by construction, no hand bump needed) and
+ * {@link SERIALIZER_VERSION}. Deterministic across processes and platforms
+ * for one build of the packages.
+ *
+ * A snapshot built under one stamp must not be served under a runtime that
+ * expects another: the cloud generator (plan G § 2, wave G2) keys its
+ * level-0 "nothing changed" skip on this stamp next to the data revision, so
+ * a deploy that changes the format rebuilds every snapshot and a deploy that
+ * does not leaves them alone.
+ */
+export function serializationFormat() {
+    return JSON.stringify({
+        serializer: SERIALIZER_VERSION,
+        schema: z.toJSONSchema(ConfigSchema, { io: 'input' }),
+    });
+}

package/dist/lib/store-ref.d.ts

@@ -0,0 +1,40 @@
+/**
+ * The `$/` notation of the normalized expo form (plan G § 3) — the codec
+ * between a store ref and the canonical URL it aliases.
+ *
+ * Every object of an expo's content-addressed store lives at one URL fixed
+ * forever — `https://<expo>.expofp.com/immutable/<hash>/<name>`, the expo's
+ * production host whichever contour generated or serves the folder — and
+ * the store ref `$/<expo>/<hash>/<name>` is that URL's alias by pure prefix
+ * substitution. No document, page or base URL takes part, so a snapshot
+ * reads identically from a contour page, an integrator's host, a local
+ * `floorplan.js`, an inline copy or a Node tool. The two forms are
+ * equivalent and a creator compacts at will: shorter bytes, an explicit
+ * "store content" marker, and an alias that survives a domain move.
+ *
+ * The marker is unambiguous by generation invariant, not by URL illegality:
+ * a store only ever returns canonical URLs, and no passthrough value ever
+ * starts with `$/`. A ref left unexpanded by mistake breaks loudly — an
+ * honest 404 on `<base>/$/…` — where a `#/…` fragment would fail silently.
+ *
+ * The schema `.meta` walker (`visit-resources`) calls the codec at every
+ * URL-carrying place — manifest fields, document `$ref`s, CSS `url(…)`
+ * tokens, `<image>` hrefs of a drawing — so prose like `US$/day` is never
+ * touched, and the effective config only ever carries full URLs.
+ */
+/** Whether a URL-carrying value is a store ref (`$/…`). */
+export declare function isStoreRef(value: string): boolean;
+/**
+ * Expand a store ref into the canonical URL it aliases:
+ * `$/demo/ZL-InrvJgYpz1-k2/logo.png` →
+ * `https://demo.expofp.com/immutable/ZL-InrvJgYpz1-k2/logo.png`. Any other
+ * value — a full URL, a rooted or relative path, a `data:` URI — passes
+ * through untouched. A malformed `$/…` is a generation bug and throws.
+ */
+export declare function resolveUrl(ref: string): string;
+/**
+ * Compact a canonical store URL into its `$/` alias — the inverse of
+ * {@link resolveUrl}; any other URL passes through untouched.
+ */
+export declare function compactUrl(url: string): string;
+//# sourceMappingURL=store-ref.d.ts.map

package/dist/lib/store-ref.js

@@ -0,0 +1,56 @@
+/**
+ * The `$/` notation of the normalized expo form (plan G § 3) — the codec
+ * between a store ref and the canonical URL it aliases.
+ *
+ * Every object of an expo's content-addressed store lives at one URL fixed
+ * forever — `https://<expo>.expofp.com/immutable/<hash>/<name>`, the expo's
+ * production host whichever contour generated or serves the folder — and
+ * the store ref `$/<expo>/<hash>/<name>` is that URL's alias by pure prefix
+ * substitution. No document, page or base URL takes part, so a snapshot
+ * reads identically from a contour page, an integrator's host, a local
+ * `floorplan.js`, an inline copy or a Node tool. The two forms are
+ * equivalent and a creator compacts at will: shorter bytes, an explicit
+ * "store content" marker, and an alias that survives a domain move.
+ *
+ * The marker is unambiguous by generation invariant, not by URL illegality:
+ * a store only ever returns canonical URLs, and no passthrough value ever
+ * starts with `$/`. A ref left unexpanded by mistake breaks loudly — an
+ * honest 404 on `<base>/$/…` — where a `#/…` fragment would fail silently.
+ *
+ * The schema `.meta` walker (`visit-resources`) calls the codec at every
+ * URL-carrying place — manifest fields, document `$ref`s, CSS `url(…)`
+ * tokens, `<image>` hrefs of a drawing — so prose like `US$/day` is never
+ * touched, and the effective config only ever carries full URLs.
+ */
+const STORE_REF_PREFIX = '$/';
+/** `$/<expo>/<key>` — the expo is one lowercase DNS label, the key is the rest verbatim. */
+const STORE_REF = /^\$\/([a-z0-9-]+)\/(.+)$/;
+/** The canonical store URL: the expo's production host, `/immutable/<key>`. */
+const CANONICAL_URL = /^https:\/\/([a-z0-9-]+)\.expofp\.com\/immutable\/(.+)$/;
+/** Whether a URL-carrying value is a store ref (`$/…`). */
+export function isStoreRef(value) {
+    return value.startsWith(STORE_REF_PREFIX);
+}
+/**
+ * Expand a store ref into the canonical URL it aliases:
+ * `$/demo/ZL-InrvJgYpz1-k2/logo.png` →
+ * `https://demo.expofp.com/immutable/ZL-InrvJgYpz1-k2/logo.png`. Any other
+ * value — a full URL, a rooted or relative path, a `data:` URI — passes
+ * through untouched. A malformed `$/…` is a generation bug and throws.
+ */
+export function resolveUrl(ref) {
+    if (!isStoreRef(ref))
+        return ref;
+    const match = STORE_REF.exec(ref);
+    if (!match)
+        throw new Error(`resolveUrl: malformed store ref ${JSON.stringify(ref)}`);
+    return `https://${match[1]}.expofp.com/immutable/${match[2]}`;
+}
+/**
+ * Compact a canonical store URL into its `$/` alias — the inverse of
+ * {@link resolveUrl}; any other URL passes through untouched.
+ */
+export function compactUrl(url) {
+    const match = CANONICAL_URL.exec(url);
+    return match ? `${STORE_REF_PREFIX}${match[1]}/${match[2]}` : url;
+}

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

@@ -21,13 +21,23 @@ 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.
+     * One asset URL; return the URL to write in its place, or `undefined` to
+     * drop the field. Dropping is only meaningful for `optional` leaves — an
+     * `optionalAsset` tag marks a URL minted without an existence check, so the
+     * resource may not exist and storing it is best-effort (a store that finds
+     * it missing drops the field rather than write a dead URL; today's optional
+     * assets are all object fields, where a drop deletes the key).
      */
-    asset(url: string, optional?: boolean): string | Promise<string>;
+    asset(url: string, optional?: boolean): string | undefined | Promise<string | undefined>;
     /** A ref's resolved — and internally rewritten — document; return the new ref URL. */
     document?(refUrl: string, document: unknown): string | Promise<string>;
+    /**
+     * Rewrite a ref's URL in place WITHOUT resolving its document — the
+     * expansion hook for store refs (`$/…`) in a normalized manifest, where
+     * the document must stay lazy. When present it takes the whole ref
+     * branch: `document`/`documentError` do not fire on the same walk.
+     */
+    ref?(refUrl: string): 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
@@ -82,4 +92,8 @@ export declare function validateOrClone<T>(schema: z.ZodType, value: T): T;
 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>;
+/** Package-internal: `loadConfig`'s pointer-chain loop probes with it too. */
+export declare function isRefShaped(value: unknown): value is {
+    $ref: string;
+};
 //# sourceMappingURL=visit-resources.d.ts.map

package/dist/lib/visit-resources.js

@@ -21,6 +21,7 @@ import { getResolved, isResolved, resolve } from '@expofp/resolve';
 import { deepClone } from '@expofp/utils';
 import { refSchemaOf, toJsonSchema, typeMatches } from './json-schema.js';
 import { collectCssUrls, collectSvgImageAssets, inlineCssImports, isAbsoluteUrl, refDirectory, rewriteCssUrls, rewriteSvgImageAssets, toAbsoluteUrl, } from './resource-urls.js';
+import { isStoreRef, resolveUrl } from './store-ref.js';
 import { timeValidation } from './validate-timing.js';
 /**
  * Gates every schema validation (`parse`) of the large expo documents —
@@ -82,7 +83,10 @@ export function documentRef(ref, schema, normalize) {
         const base = refDirectory(refUrl);
         const rebase = isAbsoluteUrl(base);
         await visitResources(schema, document, {
-            asset: (url) => (rebase ? toAbsoluteUrl(url, base) : url),
+            // A store ref (`$/…` — normalized snapshots) expands by the fixed
+            // convention, wherever the document came from (store-ref.ts); other
+            // paths get the standard web rebase.
+            asset: (url) => (isStoreRef(url) ? resolveUrl(url) : rebase ? toAbsoluteUrl(url, base) : url),
         });
         return document;
     };
@@ -105,6 +109,10 @@ async function walk(node, value, assign, handler, options) {
     // Rooted refs are already local — honored verbatim, like every other
     // rooted resource URL.
     if (isRefShaped(value)) {
+        if (handler.ref) {
+            assign({ $ref: await handler.ref(value.$ref) });
+            return;
+        }
         if (!handler.document || value.$ref.startsWith('/'))
             return;
         const refUrl = value.$ref;
@@ -155,8 +163,10 @@ async function walk(node, value, assign, handler, options) {
             for (const url of collectCssUrls(css)) {
                 if (external.has(url))
                     continue; // a kept @import's URL stays remote
-                // only scheme-qualified CSS urls are fetchable resources (legacy parity)
-                if (/^[a-z][a-z0-9+.-]*:/i.test(url)) {
+                // Only scheme-qualified CSS urls are fetchable resources (legacy
+                // parity) — plus store refs (`$/…`), which a normalized snapshot
+                // carries there and the load must expand back symmetrically.
+                if (isStoreRef(url) || /^[a-z][a-z0-9+.-]*:/i.test(url)) {
                     rewrites.set(url, await handler.asset(url));
                 }
             }
@@ -189,7 +199,8 @@ async function walk(node, value, assign, handler, options) {
         }
     }
 }
-function isRefShaped(value) {
+/** Package-internal: `loadConfig`'s pointer-chain loop probes with it too. */
+export function isRefShaped(value) {
     return (typeof value === 'object' && value !== null && '$ref' in value && typeof value.$ref === 'string');
 }
 /** The root is an object/array container — leaves rewrite inside it. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@expofp/config",
-  "version": "3.28.3",
+  "version": "3.30.0",
   "type": "module",
   "description": "ExpoFP SDK internal: config layer and schemas",
   "homepage": "https://developer.expofp.com/",
@@ -29,8 +29,8 @@
     "debug": "^4.4.3",
     "tslib": "^2.3.0",
     "zod": "4.4.3",
-    "@expofp/resolve": "3.28.3",
-    "@expofp/schema": "3.28.3",
-    "@expofp/utils": "3.28.3"
+    "@expofp/resolve": "3.30.0",
+    "@expofp/schema": "3.30.0",
+    "@expofp/utils": "3.30.0"
   }
 }