@expofp/config 3.11.10

package/README.md

@@ -0,0 +1,35 @@
+# @expofp/config
+
+The effective-config layer for the ExpoFP SDK. `loadConfig()` assembles the runtime's single copy of
+the expo data by layering manifest (+ legacy `data.js`) → options → localStorage → URL, resolving
+`$ref`s via `@expofp/resolve` against `@expofp/schema`; `setConfig`/`getConfig` hold the result.
+
+```ts
+setConfig(await loadConfig(manifestUrl));
+const config = getConfig();
+```
+
+**Schema validation** of the manifest and referenced documents (`data.js`, drawing, wayfinding) is an
+opt-in diagnostic — off by default (parsing the large expo documents costs time). Enable it per page
+load with `?validateSchema=1` in the URL or `efp-validateSchema=true` in localStorage (also a
+`@expofp/debug` panel toggle); timing for the parses it turns on logs on the `efp:config:validate`
+namespace. It is a load-time input only — the effective config never carries it.
+
+**Intents from the URL** ride the query in two forms, merged canonical-first: the bracketed array
+(`?intents[0][name]=selectBooth&intents[0][args][0]=A-12`) and a typable shortcut — the intent name
+as the key (`?selectBooth=A-12`, `?changeLanguage=fr`; multi-arg via `?name[0]=…&name[1]=…`). The
+shortcut keys are the `IntentsSchema` arm names, so the schema stays the URL allowlist; one shortcut
+per intent name, and a value that doesn't fit its intent is dropped (a visitor-edited URL never
+breaks boot).
+
+**The legacy URL grammar** (`legacy-url.ts`) is the compact deep-link language the floor plan has
+always spoken — `?<slug>`, `?route:B-12:A-3:false`, `?tour=t1`, `?planner=a:b&from=c`, one-shot
+params like `?blue-dot=…`. `parseLegacyQuery` turns a raw `location.search` into typed commands and
+`serializeSelection` writes a selection back in the same grammar (round-trip covered by tests), so
+shared links stay bidirectional. The floor plan's `url-dispatch` service binds the commands to
+stores and public methods; this codec stays pure — no DOM, no stores.
+
+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`.
+Build/test: `nx build config` · `nx test config`.

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+export { applyIntents } from './lib/apply-intents.js';
+export { getConfig, setConfig } from './lib/config-store.js';
+export { type DebugSettingDescriptor, toDebugSettings } from './lib/debug-settings.js';
+export { type LegacyOneShot, type LegacyPrimary, type LegacyUrlQuery, parseLegacyQuery, serializeSelection, 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 { 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';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,8 @@
+export { applyIntents } from './lib/apply-intents.js';
+export { getConfig, setConfig } from './lib/config-store.js';
+export { toDebugSettings } from './lib/debug-settings.js';
+export { parseLegacyQuery, serializeSelection, } from './lib/legacy-url.js';
+export { loadConfig } from './lib/load-config.js';
+export { serializeConfigResources, } from './lib/serialize-config-resources.js';
+export { parseFromUrlTolerant } from './lib/url-codec.js';
+export { parseIntentsFromUrl } from './lib/url-intents.js';

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

@@ -0,0 +1,10 @@
+import { type Intent } from '@expofp/schema';
+type IntentArgs = {
+    [I in Intent as I['name']]: I['args'];
+};
+type FloorPlanLike = {
+    [K in keyof IntentArgs]: (...args: IntentArgs[K]) => void;
+};
+export declare function applyIntents(fp: FloorPlanLike, intents: Intent[]): void;
+export {};
+//# sourceMappingURL=apply-intents.d.ts.map

package/dist/lib/apply-intents.js

@@ -0,0 +1,24 @@
+// The generic `K` keeps name↔args correlated for TS, so `fp[name](...args)` checks
+// out with no cast and no switch. Inlining this in the loop is what fails: there
+// `intent` is the whole union, so name/args decorrelate (the original error).
+function applyOne(fp, intent) {
+    // Intents ride on the deep-frozen effective config, but a method may
+    // normalize its input in place (RouteStore.selectCurrentPosition rewrites
+    // the point's fields) — hand it an owned mutable copy, the way any host
+    // calling the API would. Args are schema-validated plain data, so a JSON
+    // round-trip is lossless.
+    const args = JSON.parse(JSON.stringify(intent.args));
+    fp[intent.name](...args);
+}
+export function applyIntents(fp, intents) {
+    for (const intent of intents) {
+        try {
+            applyOne(fp, intent);
+        }
+        catch (error) {
+            // Intents ride in from the page URL — a bad deep link (unknown booth,
+            // half-formed args) must not take down the page or the intents after it.
+            console.error(`Intent ${intent.name} failed:`, error);
+        }
+    }
+}

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

@@ -0,0 +1,6 @@
+import { type Config } from '@expofp/schema';
+/** Install the active config (called once `loadConfig` has produced it). */
+export declare function setConfig(newConfig: Config): void;
+/** The active config. Throws if called before {@link setConfig}. */
+export declare function getConfig(): Config;
+//# sourceMappingURL=config-store.d.ts.map

package/dist/lib/config-store.js

@@ -0,0 +1,12 @@
+let config;
+/** Install the active config (called once `loadConfig` has produced it). */
+export function setConfig(newConfig) {
+    config = newConfig;
+}
+/** The active config. Throws if called before {@link setConfig}. */
+export function getConfig() {
+    if (!config) {
+        throw new Error('Config not loaded yet');
+    }
+    return config;
+}

package/dist/lib/debug-settings.d.ts

@@ -0,0 +1,16 @@
+import type * as z from 'zod';
+export type DebugSettingDescriptor = {
+    type: 'boolean';
+    optional: boolean;
+} | {
+    type: 'string';
+    optional: boolean;
+} | {
+    type: 'enum';
+    values: readonly string[];
+    optional: boolean;
+};
+export declare function toDebugSettings(schema: z.ZodType, options?: {
+    prefix?: string;
+}): Record<string, DebugSettingDescriptor>;
+//# sourceMappingURL=debug-settings.d.ts.map

package/dist/lib/debug-settings.js

@@ -0,0 +1,44 @@
+/**
+ * Debug-panel setting descriptors derived from a config schema — the bridge
+ * between the config's localStorage layer and `@expofp/debug`'s settings UI.
+ *
+ * `toDebugSettings(LocalStorageConfigSchema)` emits one plain-data descriptor
+ * per scalar field, keyed by the exact storage key the localStorage codec
+ * reads (`efp-` + field name), so a debug-panel edit is picked up by
+ * `loadConfig` on the next page load. Optional fields are marked `optional`:
+ * their editors get an explicit "default" state that removes the key, handing
+ * the decision back to the lower config layers. Fields with no scalar editor
+ * (objects, arrays, unions, numbers so far) are skipped and logged.
+ *
+ * The descriptor shape mirrors `@expofp/debug`'s `SettingDescriptor`
+ * structurally — no dependency between the packages; the host (the floorplan)
+ * passes the output to its `registerSettings`.
+ */
+import debug from 'debug';
+import { toJsonSchema } from './json-schema.js';
+import { DEFAULT_STORAGE_PREFIX } from './local-storage-codec.js';
+const log = debug('efp:config');
+export function toDebugSettings(schema, options = {}) {
+    const prefix = options.prefix ?? DEFAULT_STORAGE_PREFIX;
+    const root = toJsonSchema(schema);
+    const required = new Set(root.required ?? []);
+    const settings = {};
+    for (const [field, node] of Object.entries(root.properties ?? {})) {
+        const descriptor = toDescriptor(node, !required.has(field));
+        if (!descriptor) {
+            log('toDebugSettings', 'no editor for field, skipping', field, node.type);
+            continue;
+        }
+        settings[prefix + field] = descriptor;
+    }
+    return settings;
+}
+function toDescriptor(node, optional) {
+    if (node.type === 'string' && node.enum) {
+        return { type: 'enum', values: node.enum, optional };
+    }
+    if (node.type === 'boolean' || node.type === 'string') {
+        return { type: node.type, optional };
+    }
+    return undefined;
+}

package/dist/lib/json-schema.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Shared JSON-Schema introspection for the schema-driven machinery here and in
+ * `@expofp/config` (asset resolution, resource serialization, url-codec,
+ * url-intents, local-storage-codec): they all walk a plain Zod schema alongside
+ * a value, so they need a structural view of `z.toJSONSchema` output and
+ * string→scalar coercion by declared type.
+ */
+import * as z from 'zod';
+/**
+ * The slice of a JSON Schema node the walkers care about. `.meta()` keys pass
+ * through `z.toJSONSchema` and surface here — they are how a schema declares
+ * where its external resources live.
+ */
+export interface JsonSchemaNode {
+    type?: string;
+    properties?: Record<string, JsonSchemaNode>;
+    /**
+     * The schema for keys not covered by `properties`. A `z.record(z.string(), V)`
+     * has dynamic keys and no fixed `properties`, so its value schema `V` rides
+     * here (e.g. `fpSvgLayerJsRefs`); a loose object's open tail also surfaces
+     * here (as `{}`/`true`, both inert to the walk).
+     */
+    additionalProperties?: JsonSchemaNode | boolean;
+    required?: string[];
+    items?: JsonSchemaNode;
+    /** Per-position schemas of a tuple (`z.tuple`); its rest element rides on `items`. */
+    prefixItems?: JsonSchemaNode[];
+    anyOf?: JsonSchemaNode[];
+    oneOf?: JsonSchemaNode[];
+    /** Allowed values of a string-enum leaf. */
+    enum?: string[];
+    /** Value of a `z.literal` leaf — a discriminated union arm's tag. */
+    const?: unknown;
+    /** A string leaf holding one asset URL/path. */
+    asset?: boolean;
+    /** An `asset` whose URL is minted without an existence check — the resource may be missing. */
+    optionalAsset?: boolean;
+    /** A string leaf holding an SVG document whose `<image>` hrefs are asset paths. */
+    svgAsset?: boolean;
+    /** A string leaf holding CSS text whose `url(…)`s are asset paths. */
+    cssAsset?: boolean;
+    /** Stand-in for a `refSchema` meta — resolve it with {@link refSchemaOf}. */
+    refSchemaId?: string;
+}
+/** `schema` as a JSON Schema node tree (memoized per schema instance). */
+export declare function toJsonSchema(schema: z.ZodType): JsonSchemaNode;
+/** The live document schema a `$ref` node's `refSchema` meta points at. */
+export declare function refSchemaOf(node: JsonSchemaNode): z.ZodType | undefined;
+/** Does `value` plausibly belong to this schema branch? Used to pick union arms. */
+export declare function typeMatches(node: JsonSchemaNode, value: unknown): boolean;
+/**
+ * Walk the schema and a deflattened structure (raw strings at the leaves, the
+ * way a query string or storage yields values) together, coercing each leaf to
+ * its declared scalar type. Objects keep only the keys the schema names; a
+ * lone value destined for an array becomes a 1-element array; tuple positions
+ * coerce each by their own schema. A union coerces by the arm its literal
+ * discriminator names and is otherwise left as-is for the schema's `parse` to
+ * judge. Lenient like {@link coerceScalar} — this shapes the candidate, the
+ * schema's own `parse` does the real validation afterwards.
+ */
+export declare function coerceValue(node: JsonSchemaNode, value: unknown): unknown;
+/**
+ * Coerce a raw string to its declared scalar type. Lenient on purpose — the
+ * schema's own `parse` does the real validation afterwards.
+ */
+export declare function coerceScalar(raw: string, type: string | undefined): string | number | boolean;
+//# sourceMappingURL=json-schema.d.ts.map

package/dist/lib/json-schema.js

@@ -0,0 +1,136 @@
+/**
+ * Shared JSON-Schema introspection for the schema-driven machinery here and in
+ * `@expofp/config` (asset resolution, resource serialization, url-codec,
+ * url-intents, local-storage-codec): they all walk a plain Zod schema alongside
+ * a value, so they need a structural view of `z.toJSONSchema` output and
+ * string→scalar coercion by declared type.
+ */
+import * as z from 'zod';
+const cache = new WeakMap();
+// A `.meta({ refSchema: SomeSchema })` points a `$ref` field at its document's
+// LIVE schema. `z.toJSONSchema` emits pure JSON (a live schema cannot ride
+// through it), so the conversion stamps a string id on the node and parks the
+// schema here; `refSchemaOf` joins them back up.
+const refSchemas = new Map();
+let nextRefSchemaId = 0;
+/** `schema` as a JSON Schema node tree (memoized per schema instance). */
+export function toJsonSchema(schema) {
+    let node = cache.get(schema);
+    if (!node) {
+        node = z.toJSONSchema(schema, {
+            io: 'input',
+            override: ({ zodSchema, jsonSchema }) => {
+                const refSchema = z.globalRegistry.get(zodSchema)?.refSchema;
+                if (refSchema) {
+                    const id = String(nextRefSchemaId++);
+                    refSchemas.set(id, refSchema);
+                    jsonSchema.refSchemaId = id;
+                }
+            },
+        });
+        cache.set(schema, node);
+    }
+    return node;
+}
+/** The live document schema a `$ref` node's `refSchema` meta points at. */
+export function refSchemaOf(node) {
+    return node.refSchemaId === undefined ? undefined : refSchemas.get(node.refSchemaId);
+}
+/** Does `value` plausibly belong to this schema branch? Used to pick union arms. */
+export function typeMatches(node, value) {
+    switch (node.type) {
+        case 'object':
+            return typeof value === 'object' && value !== null && !Array.isArray(value);
+        case 'array':
+            return Array.isArray(value);
+        case 'string':
+            return typeof value === 'string';
+        case 'number':
+        case 'integer':
+            return typeof value === 'number';
+        case 'boolean':
+            return typeof value === 'boolean';
+        default:
+            return true; // untyped branch — let the recursion decide
+    }
+}
+/**
+ * Walk the schema and a deflattened structure (raw strings at the leaves, the
+ * way a query string or storage yields values) together, coercing each leaf to
+ * its declared scalar type. Objects keep only the keys the schema names; a
+ * lone value destined for an array becomes a 1-element array; tuple positions
+ * coerce each by their own schema. A union coerces by the arm its literal
+ * discriminator names and is otherwise left as-is for the schema's `parse` to
+ * judge. Lenient like {@link coerceScalar} — this shapes the candidate, the
+ * schema's own `parse` does the real validation afterwards.
+ */
+export function coerceValue(node, value) {
+    if (value === undefined) {
+        return undefined;
+    }
+    const variants = node.anyOf ?? node.oneOf;
+    if (variants) {
+        const variant = discriminatedVariant(variants, value);
+        return variant ? coerceValue(variant, value) : value; // no single arm — let schema.parse decide
+    }
+    if (node.type === 'object' && node.properties) {
+        if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+            return value; // shape mismatch — surface it as a schema error
+        }
+        const source = value;
+        const out = {};
+        for (const [key, child] of Object.entries(node.properties)) {
+            if (key in source) {
+                out[key] = coerceValue(child, source[key]);
+            }
+        }
+        return out;
+    }
+    if (node.type === 'array') {
+        const list = Array.isArray(value) ? value : [value]; // lenient: a lone value → 1-elem array
+        const tuple = node.prefixItems;
+        if (tuple) {
+            return list.map((element, index) => coerceValue(tuple[index] ?? node.items ?? {}, element));
+        }
+        const item = node.items ?? {};
+        return list.map((element) => coerceValue(item, element));
+    }
+    return typeof value === 'string' ? coerceScalar(value, node.type) : value;
+}
+/**
+ * The single union arm whose literal (`const`) properties all match `value` —
+ * how a discriminated union picks the arm to coerce by. The leaves are still
+ * raw strings when this runs, so a non-string literal matches its string form.
+ * `undefined` when the value is no object or when no (or several) arms match —
+ * nothing structural to say, the union stays uncoerced.
+ */
+function discriminatedVariant(variants, value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        return undefined;
+    }
+    const source = value;
+    const matches = variants.filter((variant) => {
+        const literals = Object.entries(variant.properties ?? {}).filter(([, property]) => property.const !== undefined);
+        return (literals.length > 0 &&
+            literals.every(([key, property]) => {
+                const raw = source[key];
+                return raw === property.const || raw === String(property.const);
+            }));
+    });
+    return matches.length === 1 ? matches[0] : undefined;
+}
+/**
+ * Coerce a raw string to its declared scalar type. Lenient on purpose — the
+ * schema's own `parse` does the real validation afterwards.
+ */
+export function coerceScalar(raw, type) {
+    if (type === 'number' || type === 'integer') {
+        // `Number('') === 0` — a blank value (`?camera[bearing]=`) must stay a
+        // string for the schema's parse to reject, not silently become a real 0
+        return raw.trim() === '' ? raw : Number(raw);
+    }
+    if (type === 'boolean') {
+        return /^(1|true|yes|on)$/i.test(raw);
+    }
+    return raw; // string, enum, or unknown
+}

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

@@ -0,0 +1,167 @@
+/**
+ * Legacy URL grammar — the compact deep-link language the floor plan has always
+ * spoken (`?<slug>`, `?route:B-12:A-3:false`, `?tour=t1`, `?planner=a:b&from=c`,
+ * one-shot params like `?blue-dot=…` or `?viewermode=1`), as one pure codec:
+ *
+ *   parseLegacyQuery(search)       raw `location.search` → typed commands
+ *   serializeSelection(selection)  selection descriptor  → `location.search`
+ *
+ * Both halves speak the SAME grammar, so shortcuts stay bidirectional: the slug
+ * a shared link carries is the slug the plan writes back when the visitor picks
+ * an entity (round-trip covered by tests). The floor plan maps commands to its
+ * public methods / stores and its UI state to a selection descriptor — nothing
+ * here touches a store or the DOM.
+ *
+ * Encoding contract (inherited from the legacy router, byte-compatible):
+ * the WHOLE query payload is one `encodeURIComponent` unit — `route:a:b`
+ * travels as `?route%3Aa%3Ab`, `planner&source=bookmarks` as
+ * `?planner%26source%3Dbookmarks` — and the parser decodes the whole string
+ * before splitting. Keys owned by the config layer (`UrlConfigSchema`) and
+ * intent-shortcut keys (`IntentsSchema` arm names) are consumed by `loadConfig`
+ * at boot, so the parser strips them from the residual slug here — one place
+ * knows the full key partition of the query.
+ *
+ * LEGACY GRAMMAR — frozen. Do not add keys or forms here. New URL capabilities
+ * are born in `UrlConfigSchema` (config keys) or `IntentsSchema` (intent arms)
+ * — see docs/evgeny-thoughts/2026-07-09-legacy-url-retirement.md §2. The parse
+ * side stays alive for links already shared in the wild, but only as a
+ * translator into those two channels; the sole legitimate consumer is
+ * `packages/floorplan/src/services/url-dispatch.ts` (lint-enforced).
+ */
+import { type Camera, type ListPanel } from '@expofp/schema';
+/** The list panels addressable by keyword (`?bookmarks`, `?sessions`, …). */
+export type LegacyListPanel = ListPanel;
+/**
+ * The exclusive part of a query — at most one of these dispatches per URL,
+ * mirroring the legacy router's `if/else` chain (its order is the array order
+ * of {@link parseLegacyQuery}'s classifier).
+ */
+export type LegacyPrimary = {
+    type: 'kiosk';
+    enabled: boolean | null;
+} | {
+    type: 'list';
+    list: LegacyListPanel;
+} | {
+    type: 'tour';
+    tourId: string;
+} | {
+    type: 'planner';
+    fromBookmarks: boolean;
+    items: string[];
+    from?: string;
+} | {
+    type: 'route';
+    to?: string;
+    from?: string;
+    accessible: boolean;
+    waypoints: string[];
+    title?: string;
+} | {
+    type: 'language';
+    langId?: string;
+} | {
+    type: 'printPdf';
+} | {
+    type: 'visibility';
+    hidden: string[];
+} | {
+    type: 'buildRoute';
+} | {
+    type: 'pathway';
+    pathwayId: string;
+    boothIds: string[];
+    exhibitorIds: string[];
+    tourId?: string;
+} | {
+    type: 'selectExhibitors';
+    values: string[];
+} | {
+    type: 'ownedByFilters';
+} | {
+    type: 'ownedByConfig';
+} | {
+    type: 'select';
+    slug: string;
+};
+/**
+ * Independent one-shot boot effects — the params the legacy router scrubbed
+ * from the URL as it consumed them. They are not written back (the single
+ * writer re-serializes the URL from state after dispatch, which drops them).
+ */
+export type LegacyOneShot = {
+    type: 'heatmap';
+    yah: boolean;
+    kiosk: boolean;
+} | {
+    type: 'blueDot';
+    x: number;
+    y: number;
+    layer?: string;
+    lat?: number;
+    lng?: number;
+} | {
+    type: 'viewerMode';
+    enabled: boolean;
+} | {
+    type: 'previewMode';
+    enabled: boolean;
+} | {
+    type: 'uiScale';
+    scale: number | null;
+    raw: string;
+} | {
+    type: 'resetUiScale';
+} | {
+    type: 'legacyBookmarks';
+    appendExhibitorId: number | null;
+} | {
+    type: 'camera';
+    camera: Camera;
+    roll?: number;
+};
+export interface LegacyUrlQuery {
+    primary: LegacyPrimary;
+    oneShots: LegacyOneShot[];
+}
+/**
+ * What the floor plan currently shows, for the URL — the serializer's input.
+ * `slug` covers every entity kind and free search text alike: the value IS the
+ * query, and the parser's `select` command resolves it back by catalog lookup.
+ */
+export type UrlSelection = {
+    type: 'none';
+} | {
+    type: 'slug';
+    slug: string;
+} | {
+    type: 'route';
+    to?: string;
+    from?: string;
+    accessible: boolean;
+    waypoints?: string[];
+} | {
+    type: 'planner';
+    fromBookmarks: boolean;
+    items?: string[];
+    from?: string;
+} | {
+    type: 'list';
+    list: LegacyListPanel;
+} | {
+    type: 'tour';
+    tourId: string;
+} | {
+    type: 'filter';
+    key: string;
+    value: string;
+};
+export declare function parseLegacyQuery(search: string): LegacyUrlQuery;
+/**
+ * The selection's canonical query — `''` for none, else `?<payload>` with the
+ * whole payload as one `encodeURIComponent` unit (the legacy contract). This is
+ * the string the single URL writer puts in the address bar, byte-compatible
+ * with the URLs the legacy router wrote (shared links keep working).
+ */
+export declare function serializeSelection(selection: UrlSelection): string;
+//# sourceMappingURL=legacy-url.d.ts.map