@flighthq/tokens 0.5.1-edge.685.f72fc7f

package/LICENSE.md

@@ -0,0 +1,9 @@
+# MIT License
+
+Copyright (c) 2013-2026 Joshua Granick and other contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,17 @@
+# @flighthq/tokens
+
+Explicit mode resolution and substitution for flight document scene tokens
+
+## Install
+
+```sh
+npm install @flighthq/tokens
+```
+
+Import the supported application-facing API from `@flighthq/tokens`. The `@flighthq/tokens/contract` export is the wider package-to-package contract used to compose Flight itself.
+
+This package is part of the locked-version Flight SDK graph. Applications may instead install and import `@flighthq/sdk` when package-level tree shaking is sufficient.
+
+- [Flight project](https://github.com/flighthq/flight)
+- [Source for @flighthq/tokens@0.5.1-edge.685.f72fc7f](https://github.com/flighthq/flight/tree/f72fc7feaa9653d950f39c7d2fe6365f48e82e51/packages/tokens)
+- [License](https://github.com/flighthq/flight/blob/f72fc7feaa9653d950f39c7d2fe6365f48e82e51/LICENSE.md)

package/dist/contract.d.ts

@@ -0,0 +1,3 @@
+export * from './flightDocumentSceneTokens';
+export * from './substituteFlightDocumentSceneTokens';
+//# sourceMappingURL=contract.d.ts.map

package/dist/contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"AAAA,cAAc,6BAA6B,CAAC;AAC5C,cAAc,uCAAuC,CAAC"}

package/dist/contract.js

@@ -0,0 +1,3 @@
+export * from './flightDocumentSceneTokens';
+export * from './substituteFlightDocumentSceneTokens';
+//# sourceMappingURL=contract.js.map

package/dist/contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.js","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"AAAA,cAAc,6BAA6B,CAAC;AAC5C,cAAc,uCAAuC,CAAC"}

package/dist/flightDocumentSceneTokens.d.ts

@@ -0,0 +1,5 @@
+import type { FlightDocumentRefusalExplanation, FlightDocumentScene, FlightDocumentTokenResolution, FlightDocumentTokenResolverRegistry } from '@flighthq/types/contract';
+export declare function createFlightDocumentTokenResolverRegistry(): FlightDocumentTokenResolverRegistry;
+export declare function explainFlightDocumentSceneTokenResolution(scene: Readonly<FlightDocumentScene>, mode: string, resolvers?: Readonly<FlightDocumentTokenResolverRegistry>): FlightDocumentRefusalExplanation | null;
+export declare function resolveFlightDocumentSceneTokens(scene: Readonly<FlightDocumentScene>, mode: string, resolvers?: Readonly<FlightDocumentTokenResolverRegistry>): FlightDocumentTokenResolution | null;
+//# sourceMappingURL=flightDocumentSceneTokens.d.ts.map

package/dist/flightDocumentSceneTokens.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flightDocumentSceneTokens.d.ts","sourceRoot":"","sources":["../src/flightDocumentSceneTokens.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,gCAAgC,EAChC,mBAAmB,EAEnB,6BAA6B,EAE7B,mCAAmC,EAEpC,MAAM,0BAA0B,CAAC;AAalC,wBAAgB,yCAAyC,IAAI,mCAAmC,CAO/F;AAED,wBAAgB,yCAAyC,CACvD,KAAK,EAAE,QAAQ,CAAC,mBAAmB,CAAC,EACpC,IAAI,EAAE,MAAM,EACZ,SAAS,CAAC,EAAE,QAAQ,CAAC,mCAAmC,CAAC,GACxD,gCAAgC,GAAG,IAAI,CAEzC;AAED,wBAAgB,gCAAgC,CAC9C,KAAK,EAAE,QAAQ,CAAC,mBAAmB,CAAC,EACpC,IAAI,EAAE,MAAM,EACZ,SAAS,CAAC,EAAE,QAAQ,CAAC,mCAAmC,CAAC,GACxD,6BAA6B,GAAG,IAAI,CAEtC"}

package/dist/flightDocumentSceneTokens.js

@@ -0,0 +1,130 @@
+import { createKeyedTable, getRegistryTableEntry, withRegistryTableEntry } from '@flighthq/registry/contract';
+import { FlightDocumentRefusalReason } from '@flighthq/types/contract';
+import { INVALID_FLIGHT_DOCUMENT_TOKEN_VALUE, isFlightDocumentTokenReference, readFlightDocumentTokenReferenceKey, substituteFlightDocumentTokenValue, } from './flightDocumentTokenReference';
+// The value kinds the SDK itself describes. A caller composes vendor kinds onto the returned table
+// with withRegistryTableEntry; nothing is registered at module scope, so a caller that never asks for
+// the built-ins never pays for them.
+export function createFlightDocumentTokenResolverRegistry() {
+    let resolvers = createKeyedTable(TOKEN_RESOLVER_REGISTRY_ID, TOKEN_RESOLVER_MISS_POLICY);
+    resolvers = withRegistryTableEntry(resolvers, 'Boolean', resolveBooleanTokenValue);
+    resolvers = withRegistryTableEntry(resolvers, 'Color', resolveColorTokenValue);
+    resolvers = withRegistryTableEntry(resolvers, 'Number', resolveNumberTokenValue);
+    resolvers = withRegistryTableEntry(resolvers, 'String', resolveStringTokenValue);
+    return { resolvers };
+}
+export function explainFlightDocumentSceneTokenResolution(scene, mode, resolvers) {
+    return readSceneTokens(scene, mode, resolvers).refusal;
+}
+export function resolveFlightDocumentSceneTokens(scene, mode, resolvers) {
+    return readSceneTokens(scene, mode, resolvers).resolution;
+}
+// One pass serves both exported seams so a refusal and a null can never disagree about the same input.
+function readSceneTokens(scene, mode, resolvers) {
+    const rows = new Map();
+    for (let index = 0; index < scene.tokens.length; index++) {
+        const token = scene.tokens[index];
+        rows.set(token.key, { index, token });
+    }
+    const state = { mode, resolvers, resolved: new Map(), rows, visiting: new Set() };
+    const values = {};
+    for (const token of scene.tokens) {
+        const resolved = resolveTokenKey(token.key, state);
+        if (resolved === INVALID_FLIGHT_DOCUMENT_TOKEN_VALUE)
+            return { refusal: state.refusal ?? null, resolution: null };
+        values[token.key] = resolved;
+    }
+    return { refusal: null, resolution: { mode, values } };
+}
+// Resolves one token to its concrete value for the requested mode, following an alias chain through
+// the same mode. Memoized so a diamond of aliases costs one resolution per token, and guarded by a
+// visiting set so a cycle is named instead of recursing until the stack ends.
+function resolveTokenKey(key, state, referencedFrom = '') {
+    const memo = state.resolved.get(key);
+    if (memo !== undefined)
+        return memo;
+    const row = state.rows.get(key);
+    if (row === undefined) {
+        return refuse(state, FlightDocumentRefusalReason.TokenUnresolved, referencedFrom, key, null, null);
+    }
+    const path = `tokens[${row.index}]`;
+    if (state.visiting.has(key)) {
+        return refuse(state, FlightDocumentRefusalReason.TokenReferenceCycle, path, key, null, row.token.kind);
+    }
+    const resolver = state.resolvers === undefined ? null : getRegistryTableEntry(state.resolvers.resolvers, row.token.kind);
+    if (resolver === null) {
+        const kindPath = `${path}.kind`;
+        return refuse(state, FlightDocumentRefusalReason.TokenResolverUnregistered, kindPath, key, null, row.token.kind);
+    }
+    const mode = row.token.values[state.mode] !== undefined ? state.mode : DEFAULT_MODE;
+    const authored = row.token.values[mode];
+    if (authored === undefined) {
+        return refuse(state, FlightDocumentRefusalReason.TokenModeUnresolved, path, key, state.mode, row.token.kind);
+    }
+    const modePath = `${path}.${mode}`;
+    state.visiting.add(key);
+    const substituted = isFlightDocumentTokenReference(authored)
+        ? resolveAlias(authored, row.token, modePath, state)
+        : substituteFlightDocumentTokenValue(authored, modePath, (key, at) => resolveTokenKey(key, state, at), (at) => void refuse(state, FlightDocumentRefusalReason.TokenReferenceInvalid, at, null, null, null));
+    state.visiting.delete(key);
+    if (substituted === INVALID_FLIGHT_DOCUMENT_TOKEN_VALUE)
+        return INVALID_FLIGHT_DOCUMENT_TOKEN_VALUE;
+    const value = resolver(substituted, row.token);
+    if (value === null) {
+        return refuse(state, FlightDocumentRefusalReason.TokenValueInvalid, modePath, key, mode, row.token.kind);
+    }
+    state.resolved.set(key, value);
+    return value;
+}
+// A whole-value reference is an ALIAS: it names another token of the same semantic type, so the kinds
+// must agree. A reference nested inside a composite value is an ordinary value substitution and
+// carries no such claim — the field it fills is not the token's own type.
+function resolveAlias(authored, token, path, state) {
+    const target = readFlightDocumentTokenReferenceKey(authored);
+    if (target === null) {
+        return refuse(state, FlightDocumentRefusalReason.TokenReferenceInvalid, path, token.key, null, token.kind);
+    }
+    const targetRow = state.rows.get(target);
+    if (targetRow !== undefined && targetRow.token.kind !== token.kind) {
+        const kindPath = `tokens[${targetRow.index}].kind`;
+        return refuse(state, FlightDocumentRefusalReason.TokenKindMismatch, kindPath, target, null, targetRow.token.kind);
+    }
+    return resolveTokenKey(target, state, path);
+}
+function refuse(state, reason, path, tokenKey, mode, kind) {
+    state.refusal ??= {
+        actual: null,
+        column: null,
+        kind,
+        limit: null,
+        line: null,
+        mode,
+        offset: null,
+        path,
+        reason,
+        resourceKey: null,
+        tokenKey,
+        version: null,
+    };
+    return INVALID_FLIGHT_DOCUMENT_TOKEN_VALUE;
+}
+function resolveBooleanTokenValue(value) {
+    return typeof value === 'boolean' ? value : null;
+}
+// Packed sRGB RGBA, matching the SDK-wide colour convention: one unsigned 32-bit integer, never a
+// float and never a separate alpha.
+function resolveColorTokenValue(value) {
+    if (typeof value !== 'number' || !Number.isInteger(value))
+        return null;
+    return value >= 0 && value <= 0xffffffff ? value : null;
+}
+function resolveNumberTokenValue(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : null;
+}
+function resolveStringTokenValue(value) {
+    return typeof value === 'string' ? value : null;
+}
+const DEFAULT_MODE = 'default';
+// A miss is a named refusal, never a substituted value: an unregistered kind must not resolve.
+const TOKEN_RESOLVER_MISS_POLICY = 'Unregistered';
+const TOKEN_RESOLVER_REGISTRY_ID = 'flight-document-token-resolvers';
+//# sourceMappingURL=flightDocumentSceneTokens.js.map

package/dist/flightDocumentSceneTokens.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"flightDocumentSceneTokens.js","sourceRoot":"","sources":["../src/flightDocumentSceneTokens.ts"],"names":[],"mappings":"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"}

package/dist/flightDocumentTokenReference.d.ts

@@ -0,0 +1,6 @@
+import type { FlightDocumentValue } from '@flighthq/types/contract';
+export declare function isFlightDocumentTokenReference(value: FlightDocumentValue): value is string;
+export declare function readFlightDocumentTokenReferenceKey(value: string): string | null;
+export declare function substituteFlightDocumentTokenValue(value: FlightDocumentValue, path: string, lookup: (key: string, path: string) => FlightDocumentValue | typeof INVALID_FLIGHT_DOCUMENT_TOKEN_VALUE, refuseMalformed: (path: string) => void): FlightDocumentValue | typeof INVALID_FLIGHT_DOCUMENT_TOKEN_VALUE;
+export declare const INVALID_FLIGHT_DOCUMENT_TOKEN_VALUE: unique symbol;
+//# sourceMappingURL=flightDocumentTokenReference.d.ts.map

package/dist/flightDocumentTokenReference.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flightDocumentTokenReference.d.ts","sourceRoot":"","sources":["../src/flightDocumentTokenReference.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAKpE,wBAAgB,8BAA8B,CAAC,KAAK,EAAE,mBAAmB,GAAG,KAAK,IAAI,MAAM,CAE1F;AAID,wBAAgB,mCAAmC,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAGhF;AAKD,wBAAgB,kCAAkC,CAChD,KAAK,EAAE,mBAAmB,EAC1B,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,mBAAmB,GAAG,OAAO,mCAAmC,EACvG,eAAe,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,GACtC,mBAAmB,GAAG,OAAO,mCAAmC,CA4BlE;AAGD,eAAO,MAAM,mCAAmC,eAAgD,CAAC"}

package/dist/flightDocumentTokenReference.js

@@ -0,0 +1,57 @@
+// One statement of what a reference IS, shared by token-value resolution and node-field substitution.
+// Two copies would drift, and the copy that drifted would be whichever a later change forgot — the
+// same hazard the shape-command schema ruling names.
+export function isFlightDocumentTokenReference(value) {
+    return typeof value === 'string' && value.startsWith(REFERENCE_SIGIL) && !value.startsWith(REFERENCE_ESCAPE);
+}
+// The token key a reference names, or null when the scalar is a malformed reference. A caller must
+// have established that the value IS a reference; a plain string never reaches here.
+export function readFlightDocumentTokenReferenceKey(value) {
+    const key = value.slice(REFERENCE_SIGIL.length);
+    return FLIGHT_DOCUMENT_TOKEN_KEY_PATTERN.test(key) ? key : null;
+}
+// Walks a value tree and replaces every reference through `lookup`, which owns both the mapping from
+// key to value and the refusal it records when there is none. Returns the sentinel rather than null
+// because null is itself a representable document value, so it cannot mean failure here.
+export function substituteFlightDocumentTokenValue(value, path, lookup, refuseMalformed) {
+    if (typeof value === 'string') {
+        if (value.startsWith(REFERENCE_ESCAPE))
+            return value.slice(REFERENCE_SIGIL.length);
+        if (!isFlightDocumentTokenReference(value))
+            return value;
+        const key = readFlightDocumentTokenReferenceKey(value);
+        if (key === null) {
+            refuseMalformed(path);
+            return INVALID_FLIGHT_DOCUMENT_TOKEN_VALUE;
+        }
+        return lookup(key, path);
+    }
+    if (Array.isArray(value)) {
+        const out = [];
+        for (let index = 0; index < value.length; index++) {
+            const item = substituteFlightDocumentTokenValue(value[index], `${path}[${index}]`, lookup, refuseMalformed);
+            if (item === INVALID_FLIGHT_DOCUMENT_TOKEN_VALUE)
+                return item;
+            out.push(item);
+        }
+        return out;
+    }
+    if (value === null || typeof value !== 'object')
+        return value;
+    const out = {};
+    for (const key of Object.keys(value)) {
+        const item = substituteFlightDocumentTokenValue(value[key], `${path}.${key}`, lookup, refuseMalformed);
+        if (item === INVALID_FLIGHT_DOCUMENT_TOKEN_VALUE)
+            return item;
+        out[key] = item;
+    }
+    return out;
+}
+// A reference that could not be resolved. Distinct from null, which a document may legitimately hold.
+export const INVALID_FLIGHT_DOCUMENT_TOKEN_VALUE = Symbol('invalid-flight-document-token-value');
+// Token keys and mode names share the codec's plain-scalar shape, so an authored key never needs
+// quoting and a reference never needs escaping beyond its sigil.
+const FLIGHT_DOCUMENT_TOKEN_KEY_PATTERN = /^[A-Za-z_][A-Za-z0-9_.-]*$/;
+const REFERENCE_ESCAPE = '$$';
+const REFERENCE_SIGIL = '$';
+//# sourceMappingURL=flightDocumentTokenReference.js.map

package/dist/flightDocumentTokenReference.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"flightDocumentTokenReference.js","sourceRoot":"","sources":["../src/flightDocumentTokenReference.ts"],"names":[],"mappings":"AAEA,sGAAsG;AACtG,mGAAmG;AACnG,qDAAqD;AACrD,MAAM,UAAU,8BAA8B,CAAC,KAA0B;IACvE,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,UAAU,CAAC,eAAe,CAAC,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,gBAAgB,CAAC,CAAC;AAC/G,CAAC;AAED,mGAAmG;AACnG,qFAAqF;AACrF,MAAM,UAAU,mCAAmC,CAAC,KAAa;IAC/D,MAAM,GAAG,GAAG,KAAK,CAAC,KAAK,CAAC,eAAe,CAAC,MAAM,CAAC,CAAC;IAChD,OAAO,iCAAiC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC;AAClE,CAAC;AAED,qGAAqG;AACrG,oGAAoG;AACpG,yFAAyF;AACzF,MAAM,UAAU,kCAAkC,CAChD,KAA0B,EAC1B,IAAY,EACZ,MAAuG,EACvG,eAAuC;IAEvC,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,IAAI,KAAK,CAAC,UAAU,CAAC,gBAAgB,CAAC;YAAE,OAAO,KAAK,CAAC,KAAK,CAAC,eAAe,CAAC,MAAM,CAAC,CAAC;QACnF,IAAI,CAAC,8BAA8B,CAAC,KAAK,CAAC;YAAE,OAAO,KAAK,CAAC;QACzD,MAAM,GAAG,GAAG,mCAAmC,CAAC,KAAK,CAAC,CAAC;QACvD,IAAI,GAAG,KAAK,IAAI,EAAE,CAAC;YACjB,eAAe,CAAC,IAAI,CAAC,CAAC;YACtB,OAAO,mCAAmC,CAAC;QAC7C,CAAC;QACD,OAAO,MAAM,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;IAC3B,CAAC;IACD,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACzB,MAAM,GAAG,GAA0B,EAAE,CAAC;QACtC,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,KAAK,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE,CAAC;YAClD,MAAM,IAAI,GAAG,kCAAkC,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,GAAG,IAAI,IAAI,KAAK,GAAG,EAAE,MAAM,EAAE,eAAe,CAAC,CAAC;YAC5G,IAAI,IAAI,KAAK,mCAAmC;gBAAE,OAAO,IAAI,CAAC;YAC9D,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACjB,CAAC;QACD,OAAO,GAAG,CAAC;IACb,CAAC;IACD,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC9D,MAAM,GAAG,GAAwC,EAAE,CAAC;IACpD,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QACrC,MAAM,IAAI,GAAG,kCAAkC,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,GAAG,IAAI,IAAI,GAAG,EAAE,EAAE,MAAM,EAAE,eAAe,CAAC,CAAC;QACvG,IAAI,IAAI,KAAK,mCAAmC;YAAE,OAAO,IAAI,CAAC;QAC9D,GAAG,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC;IAClB,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,sGAAsG;AACtG,MAAM,CAAC,MAAM,mCAAmC,GAAG,MAAM,CAAC,qCAAqC,CAAC,CAAC;AAEjG,iGAAiG;AACjG,iEAAiE;AACjE,MAAM,iCAAiC,GAAG,4BAA4B,CAAC;AACvE,MAAM,gBAAgB,GAAG,IAAI,CAAC;AAC9B,MAAM,eAAe,GAAG,GAAG,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from './flightDocumentSceneTokens';
+export * from './substituteFlightDocumentSceneTokens';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,6BAA6B,CAAC;AAC5C,cAAc,uCAAuC,CAAC"}

package/dist/index.js

@@ -0,0 +1,3 @@
+export * from './flightDocumentSceneTokens';
+export * from './substituteFlightDocumentSceneTokens';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,6BAA6B,CAAC;AAC5C,cAAc,uCAAuC,CAAC"}

package/dist/substituteFlightDocumentSceneTokens.d.ts

@@ -0,0 +1,4 @@
+import type { FlightDocumentRefusalExplanation, FlightDocumentScene, FlightDocumentTokenResolution } from '@flighthq/types/contract';
+export declare function explainFlightDocumentSceneTokenSubstitution(scene: Readonly<FlightDocumentScene>, resolution: Readonly<FlightDocumentTokenResolution>): FlightDocumentRefusalExplanation | null;
+export declare function substituteFlightDocumentSceneTokens<T extends Readonly<FlightDocumentScene>>(scene: T, resolution: Readonly<FlightDocumentTokenResolution>): T | null;
+//# sourceMappingURL=substituteFlightDocumentSceneTokens.d.ts.map

package/dist/substituteFlightDocumentSceneTokens.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"substituteFlightDocumentSceneTokens.d.ts","sourceRoot":"","sources":["../src/substituteFlightDocumentSceneTokens.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAGV,gCAAgC,EAChC,mBAAmB,EACnB,6BAA6B,EAE9B,MAAM,0BAA0B,CAAC;AAQlC,wBAAgB,2CAA2C,CACzD,KAAK,EAAE,QAAQ,CAAC,mBAAmB,CAAC,EACpC,UAAU,EAAE,QAAQ,CAAC,6BAA6B,CAAC,GAClD,gCAAgC,GAAG,IAAI,CAEzC;AAOD,wBAAgB,mCAAmC,CAAC,CAAC,SAAS,QAAQ,CAAC,mBAAmB,CAAC,EACzF,KAAK,EAAE,CAAC,EACR,UAAU,EAAE,QAAQ,CAAC,6BAA6B,CAAC,GAClD,CAAC,GAAG,IAAI,CAOV"}

package/dist/substituteFlightDocumentSceneTokens.js

@@ -0,0 +1,72 @@
+import { FlightDocumentRefusalReason } from '@flighthq/types/contract';
+import { INVALID_FLIGHT_DOCUMENT_TOKEN_VALUE, substituteFlightDocumentTokenValue, } from './flightDocumentTokenReference';
+export function explainFlightDocumentSceneTokenSubstitution(scene, resolution) {
+    return readSubstitution(scene, resolution).refusal;
+}
+// Pure: the input scene is never touched and a new entry is returned for later materialization. The
+// dimension is preserved through the type parameter so a caller does not re-narrow what it passed in.
+// The readonly intent sits on the CONSTRAINT rather than on the parameter: Readonly<T> is homomorphic
+// and distributes, so a caller holding the FlightDocumentScene union — which is what document.scenes[i]
+// is — could not have inferred T at all.
+export function substituteFlightDocumentSceneTokens(scene, resolution) {
+    const substituted = readSubstitution(scene, resolution);
+    if (substituted.scene === null)
+        return null;
+    // The spread carries every scene-level section (layouts and tokens, plus backgroundColor or cameras
+    // and lights) unchanged, and only `scene` is replaced; T is preserved by construction rather than by
+    // narrowing, which no assertion in the language can express for a generic spread.
+    return { ...scene, scene: substituted.scene };
+}
+function readSubstitution(scene, resolution) {
+    const state = { resolution };
+    const root = substituteNode(scene.scene, 'scene', state);
+    if (root === null)
+        return { refusal: state.refusal ?? null, scene: null };
+    return { refusal: null, scene: root };
+}
+function substituteNode(node, path, state) {
+    const fields = {};
+    for (const name of Object.keys(node.fields)) {
+        const fieldPath = `${path}.fields.${name}`;
+        const value = substituteFlightDocumentTokenValue(node.fields[name], fieldPath, (key, at) => lookup(key, at, state), (at) => refuse(state, FlightDocumentRefusalReason.TokenReferenceInvalid, at, null));
+        if (value === INVALID_FLIGHT_DOCUMENT_TOKEN_VALUE)
+            return null;
+        fields[name] = value;
+    }
+    const children = [];
+    for (let index = 0; index < node.children.length; index++) {
+        const child = substituteNode(node.children[index], `${path}.children[${index}]`, state);
+        if (child === null)
+            return null;
+        children.push(child);
+    }
+    return { children, fields, kind: node.kind };
+}
+// A reference the resolution does not cover is a named refusal, never a `$…` string left in a field a
+// renderer will read as a number. Silent pass-through would make the file say one thing and the render
+// show another, with nothing reporting the difference.
+function lookup(key, path, state) {
+    const value = state.resolution.values[key];
+    if (value === undefined) {
+        refuse(state, FlightDocumentRefusalReason.TokenUnresolved, path, key);
+        return INVALID_FLIGHT_DOCUMENT_TOKEN_VALUE;
+    }
+    return value;
+}
+function refuse(state, reason, path, tokenKey) {
+    state.refusal ??= {
+        actual: null,
+        column: null,
+        kind: null,
+        limit: null,
+        line: null,
+        mode: state.resolution.mode,
+        offset: null,
+        path,
+        reason,
+        resourceKey: null,
+        tokenKey,
+        version: null,
+    };
+}
+//# sourceMappingURL=substituteFlightDocumentSceneTokens.js.map

package/dist/substituteFlightDocumentSceneTokens.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"substituteFlightDocumentSceneTokens.js","sourceRoot":"","sources":["../src/substituteFlightDocumentSceneTokens.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@flighthq/tokens",
+  "version": "0.5.1-edge.685.f72fc7f",
+  "author": "Joshua Granick and other contributors",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/flighthq/flight.git",
+    "directory": "packages/tokens"
+  },
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./contract": {
+      "types": "./dist/contract.d.ts",
+      "default": "./dist/contract.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src/**/*.test.ts",
+    "!dist/**/*.test.js",
+    "!dist/**/*.test.d.ts",
+    "!dist/**/*.test.js.map",
+    "!dist/**/*.test.d.ts.map"
+  ],
+  "scripts": {
+    "build": "tsc -b",
+    "clean": "tsc -b --clean",
+    "test": "vitest run --config vitest.config.ts",
+    "test:watch": "vitest --watch --config vitest.config.ts",
+    "prepack": "npm run clean && npm run clean:dist && npm run build",
+    "clean:dist": "tsx ../../scripts/clean-package-dist.ts"
+  },
+  "dependencies": {
+    "@flighthq/registry": "0.5.1-edge.685.f72fc7f",
+    "@flighthq/types": "0.5.1-edge.685.f72fc7f"
+  },
+  "devDependencies": {
+    "@flighthq/node": "*",
+    "@flighthq/scene-document": "*",
+    "@flighthq/scene2d": "*",
+    "typescript": "^5.3.0"
+  },
+  "description": "Explicit mode resolution and substitution for flight document scene tokens",
+  "sideEffects": false
+}

package/src/flightDocumentSceneTokenPipeline.test.ts

@@ -0,0 +1,125 @@
+import { getNodeChildren } from '@flighthq/node/contract';
+import { createKeyedTable, withRegistryTableEntry } from '@flighthq/registry/contract';
+import { createFlightDocumentScene2DMaterialization, parseFlightDocumentText } from '@flighthq/scene-document/contract';
+import { createDisplayObject, createSprite } from '@flighthq/scene2d/contract';
+import type {
+  FlightDocument,
+  FlightDocumentFields,
+  FlightDocumentNodeSchema,
+  FlightDocumentScene2D,
+  FlightDocumentSchemaRegistry,
+  Node2D,
+  NodeAny,
+} from '@flighthq/types/contract';
+import { DisplayObjectKind, SpriteKind } from '@flighthq/types/contract';
+
+import {
+  createFlightDocumentTokenResolverRegistry,
+  resolveFlightDocumentSceneTokens,
+} from './flightDocumentSceneTokens';
+import { substituteFlightDocumentSceneTokens } from './substituteFlightDocumentSceneTokens';
+
+// The one flow no single package can cover: authored text, through resolution and substitution, into
+// a materialized scene. It is the serialization round-trip carve-out in the testing conventions, not a
+// generic integration bucket — each stage's own behavior is unit-tested where it lives.
+describe('flightDocumentSceneTokenPipeline', () => {
+  it('carries an authored reference through to the materialized node for the requested mode', () => {
+    const document = parseAuthoredDocument();
+    const substituted = substituteScene(document, 'dark');
+    const materialization = createFlightDocumentScene2DMaterialization(
+      { ...document, scenes: [substituted] },
+      createTestSchemas(),
+    );
+    const child = getNodeChildren(materialization?.scene.root as NodeAny)[0] as Node2D;
+    // 0.25 and 40 are the dark variants written in the fixture text below, restated here rather than
+    // read back out of the document: sourcing them from the parsed tokens would pass for any mapping.
+    expect(child.alpha).toBe(0.25);
+    expect(child.x).toBe(40);
+  });
+
+  it('produces the other mode values from the same authored document', () => {
+    const document = parseAuthoredDocument();
+    const substituted = substituteScene(document, 'light');
+    const materialization = createFlightDocumentScene2DMaterialization(
+      { ...document, scenes: [substituted] },
+      createTestSchemas(),
+    );
+    const child = getNodeChildren(materialization?.scene.root as NodeAny)[0] as Node2D;
+    expect(child.alpha).toBe(1);
+    expect(child.x).toBe(40);
+  });
+
+  it('refuses the whole flow when a referenced token is not declared', () => {
+    const document = parseFlightDocumentText(
+      'flight: 1\ndefaultScene: 0\nscenes:\n' +
+        '  - kind: Scene2D\n    scene:\n      kind: DisplayObject\n      children:\n' +
+        '        - kind: Sprite\n          alpha: "$opacity.absent"\n',
+    );
+    if (document === null) throw new Error('expected the fixture to parse');
+    const scene = document.scenes[0];
+    const resolution = resolveFlightDocumentSceneTokens(scene, 'dark', createFlightDocumentTokenResolverRegistry());
+    if (resolution === null) throw new Error('expected an empty token table to resolve');
+    expect(substituteFlightDocumentSceneTokens(scene, resolution)).toBeNull();
+  });
+});
+
+function parseAuthoredDocument(): FlightDocument {
+  const document = parseFlightDocumentText(
+    'flight: 1\ndefaultScene: 0\nscenes:\n' +
+      '  - kind: Scene2D\n' +
+      '    scene:\n      kind: DisplayObject\n      children:\n' +
+      '        - kind: Sprite\n          alpha: "$opacity.panel"\n          x: "$space.inset"\n' +
+      '    tokens:\n' +
+      '      - kind: Number\n        key: opacity.panel\n        dark: 0.25\n        light: 1\n' +
+      '      - kind: Number\n        key: space.inset\n        default: 40\n',
+  );
+  if (document === null) throw new Error('expected the authored token fixture to parse');
+  return document;
+}
+
+function substituteScene(document: Readonly<FlightDocument>, mode: string): FlightDocumentScene2D {
+  const scene = document.scenes[0];
+  if (scene.kind !== 'Scene2D') throw new Error('expected a 2D fixture entry');
+  const resolution = resolveFlightDocumentSceneTokens(scene, mode, createFlightDocumentTokenResolverRegistry());
+  if (resolution === null) throw new Error('expected the fixture token table to resolve');
+  const substituted = substituteFlightDocumentSceneTokens(scene, resolution);
+  if (substituted === null) throw new Error('expected every authored reference to substitute');
+  return substituted;
+}
+
+function createTestSchemas(): FlightDocumentSchemaRegistry {
+  const displayObjectSchema: FlightDocumentNodeSchema = {
+    createNode: (fields: Readonly<FlightDocumentFields>) => applyFields(createDisplayObject(), fields),
+    fields: [],
+    kind: DisplayObjectKind,
+    writeNodeFields: () => true,
+  };
+  const spriteSchema: FlightDocumentNodeSchema = {
+    createNode: (fields: Readonly<FlightDocumentFields>) => applyFields(createSprite(), fields),
+    fields: [
+      { defaultValue: 1, name: 'alpha', required: false, validate: (value) => typeof value === 'number' },
+      { defaultValue: 0, name: 'x', required: false, validate: (value) => typeof value === 'number' },
+    ],
+    kind: SpriteKind,
+    writeNodeFields: () => true,
+  };
+  let nodeSchemas = createKeyedTable<FlightDocumentNodeSchema>('flight-document.node', 'none');
+  nodeSchemas = withRegistryTableEntry(nodeSchemas, DisplayObjectKind, displayObjectSchema);
+  nodeSchemas = withRegistryTableEntry(nodeSchemas, SpriteKind, spriteSchema);
+  return {
+    interactiveStateExtensionSchemas: createKeyedTable('flight-document.interactive-state-extension', 'none'),
+    interactiveStateTransitionSchemas: createKeyedTable('flight-document.interactive-state-transition', 'none'),
+    nodeSchemas,
+    resourceSchemas: createKeyedTable('flight-document.resource', 'none'),
+    shapeCommandSchemas: createKeyedTable('flight-document.shape-command', 'none'),
+  };
+}
+
+// Deliberately assigns only when the field is already a number: a reference that failed to substitute
+// arrives as a string, and this fixture must leave the default in place rather than coerce it, so a
+// broken substitution shows up as a failed assertion instead of NaN.
+function applyFields(target: Node2D, fields: Readonly<FlightDocumentFields>): Node2D {
+  if (typeof fields['alpha'] === 'number') target.alpha = fields['alpha'];
+  if (typeof fields['x'] === 'number') target.x = fields['x'];
+  return target;
+}

package/src/flightDocumentSceneTokens.test.ts

@@ -0,0 +1,235 @@
+import { withRegistryTableEntry } from '@flighthq/registry/contract';
+import type {
+  FlightDocumentScene2D,
+  FlightDocumentToken,
+  FlightDocumentTokenResolverRegistry,
+} from '@flighthq/types/contract';
+import { FlightDocumentRefusalReason } from '@flighthq/types/contract';
+
+import {
+  createFlightDocumentTokenResolverRegistry,
+  explainFlightDocumentSceneTokenResolution,
+  resolveFlightDocumentSceneTokens,
+} from './flightDocumentSceneTokens';
+
+describe('createFlightDocumentTokenResolverRegistry', () => {
+  it('admits each built-in kind only for the values that kind describes', () => {
+    const registry = createFlightDocumentTokenResolverRegistry();
+    expect(resolveOne(registry, token('Color', { default: 0x3366ccff }))).toEqual({ 'a.token': 0x3366ccff });
+    expect(resolveOne(registry, token('Color', { default: -1 }))).toBeNull();
+    expect(resolveOne(registry, token('Color', { default: 1.5 }))).toBeNull();
+    expect(resolveOne(registry, token('Color', { default: 0x1_0000_0000 }))).toBeNull();
+    expect(resolveOne(registry, token('Color', { default: 'blue' }))).toBeNull();
+    expect(resolveOne(registry, token('Number', { default: 1.5 }))).toEqual({ 'a.token': 1.5 });
+    expect(resolveOne(registry, token('Number', { default: 'wide' }))).toBeNull();
+    expect(resolveOne(registry, token('Boolean', { default: true }))).toEqual({ 'a.token': true });
+    expect(resolveOne(registry, token('Boolean', { default: 1 }))).toBeNull();
+    expect(resolveOne(registry, token('String', { default: 'Inter' }))).toEqual({ 'a.token': 'Inter' });
+    expect(resolveOne(registry, token('String', { default: 12 }))).toBeNull();
+  });
+
+  it('stays open to a vendor kind the SDK never registered', () => {
+    const registry = createFlightDocumentTokenResolverRegistry();
+    const extended: FlightDocumentTokenResolverRegistry = {
+      resolvers: withResolver(registry, 'acme.Duration', (value) => (typeof value === 'number' ? value : null)),
+    };
+    expect(resolveOne(extended, token('acme.Duration', { default: 150 }))).toEqual({ 'a.token': 150 });
+  });
+});
+
+describe('explainFlightDocumentSceneTokenResolution', () => {
+  it('names an unregistered kind against the token that carries it', () => {
+    const scene = sceneWith([token('acme.Shadow', { default: 1 })]);
+    const explanation = explainFlightDocumentSceneTokenResolution(
+      scene,
+      'dark',
+      createFlightDocumentTokenResolverRegistry(),
+    );
+    expect(explanation?.reason).toBe(FlightDocumentRefusalReason.TokenResolverUnregistered);
+    expect(explanation?.kind).toBe('acme.Shadow');
+    expect(explanation?.tokenKey).toBe('a.token');
+    expect(explanation?.path).toBe('tokens[0].kind');
+  });
+
+  it('names a value the kind refused, with the mode it was authored under', () => {
+    const scene = sceneWith([token('Color', { dark: 'midnight' })]);
+    const explanation = explainFlightDocumentSceneTokenResolution(
+      scene,
+      'dark',
+      createFlightDocumentTokenResolverRegistry(),
+    );
+    expect(explanation?.reason).toBe(FlightDocumentRefusalReason.TokenValueInvalid);
+    expect(explanation?.mode).toBe('dark');
+    expect(explanation?.path).toBe('tokens[0].dark');
+  });
+
+  it('names a token that declares neither the requested mode nor a default', () => {
+    const scene = sceneWith([token('Color', { light: 0xffffffff })]);
+    const explanation = explainFlightDocumentSceneTokenResolution(
+      scene,
+      'dark',
+      createFlightDocumentTokenResolverRegistry(),
+    );
+    expect(explanation?.reason).toBe(FlightDocumentRefusalReason.TokenModeUnresolved);
+    expect(explanation?.mode).toBe('dark');
+    expect(explanation?.tokenKey).toBe('a.token');
+  });
+
+  it('names an alias whose target no token declares', () => {
+    const scene = sceneWith([{ key: 'color.card', kind: 'Color', values: { default: '$color.absent' } }]);
+    const explanation = explainFlightDocumentSceneTokenResolution(
+      scene,
+      'dark',
+      createFlightDocumentTokenResolverRegistry(),
+    );
+    expect(explanation?.reason).toBe(FlightDocumentRefusalReason.TokenUnresolved);
+    expect(explanation?.tokenKey).toBe('color.absent');
+  });
+
+  it('names an alias cycle instead of following it forever', () => {
+    const scene = sceneWith([
+      { key: 'a', kind: 'Color', values: { default: '$b' } },
+      { key: 'b', kind: 'Color', values: { default: '$a' } },
+    ]);
+    const explanation = explainFlightDocumentSceneTokenResolution(
+      scene,
+      'dark',
+      createFlightDocumentTokenResolverRegistry(),
+    );
+    expect(explanation?.reason).toBe(FlightDocumentRefusalReason.TokenReferenceCycle);
+  });
+
+  it('names a self-referential token as a cycle', () => {
+    const scene = sceneWith([{ key: 'a', kind: 'Color', values: { default: '$a' } }]);
+    const explanation = explainFlightDocumentSceneTokenResolution(
+      scene,
+      'dark',
+      createFlightDocumentTokenResolverRegistry(),
+    );
+    expect(explanation?.reason).toBe(FlightDocumentRefusalReason.TokenReferenceCycle);
+    expect(explanation?.tokenKey).toBe('a');
+  });
+
+  it('names an alias whose target is a different kind', () => {
+    const scene = sceneWith([
+      { key: 'color.card', kind: 'Color', values: { default: '$space.gutter' } },
+      { key: 'space.gutter', kind: 'Number', values: { default: 8 } },
+    ]);
+    const explanation = explainFlightDocumentSceneTokenResolution(
+      scene,
+      'dark',
+      createFlightDocumentTokenResolverRegistry(),
+    );
+    expect(explanation?.reason).toBe(FlightDocumentRefusalReason.TokenKindMismatch);
+    expect(explanation?.tokenKey).toBe('space.gutter');
+  });
+
+  it('names a malformed reference rather than treating it as an ordinary string', () => {
+    const scene = sceneWith([{ key: 'a', kind: 'String', values: { default: '$9lives' } }]);
+    const explanation = explainFlightDocumentSceneTokenResolution(
+      scene,
+      'dark',
+      createFlightDocumentTokenResolverRegistry(),
+    );
+    expect(explanation?.reason).toBe(FlightDocumentRefusalReason.TokenReferenceInvalid);
+  });
+
+  it('reports nothing when every token resolves', () => {
+    const scene = sceneWith([token('Color', { default: 0x3366ccff })]);
+    expect(
+      explainFlightDocumentSceneTokenResolution(scene, 'dark', createFlightDocumentTokenResolverRegistry()),
+    ).toBeNull();
+  });
+});
+
+describe('resolveFlightDocumentSceneTokens', () => {
+  it('prefers the requested mode over the default', () => {
+    const scene = sceneWith([token('Color', { dark: 0x1a1a1aff, default: 0x808080ff, light: 0xffffffff })]);
+    const resolution = resolveFlightDocumentSceneTokens(scene, 'dark', createFlightDocumentTokenResolverRegistry());
+    expect(resolution).toEqual({ mode: 'dark', values: { 'a.token': 0x1a1a1aff } });
+  });
+
+  it('falls back to the default mode when the requested one is absent', () => {
+    const scene = sceneWith([token('Color', { default: 0x808080ff, light: 0xffffffff })]);
+    const resolution = resolveFlightDocumentSceneTokens(scene, 'dark', createFlightDocumentTokenResolverRegistry());
+    expect(resolution?.values).toEqual({ 'a.token': 0x808080ff });
+  });
+
+  it('resolves an alias inside the requested mode rather than through the target default', () => {
+    const scene = sceneWith([
+      { key: 'color.card', kind: 'Color', values: { default: '$color.background' } },
+      { key: 'color.background', kind: 'Color', values: { dark: 0x1a1a1aff, light: 0xffffffff } },
+    ]);
+    const resolution = resolveFlightDocumentSceneTokens(scene, 'dark', createFlightDocumentTokenResolverRegistry());
+    expect(resolution?.values['color.card']).toBe(0x1a1a1aff);
+    expect(
+      resolveFlightDocumentSceneTokens(scene, 'light', createFlightDocumentTokenResolverRegistry())?.values[
+        'color.card'
+      ],
+    ).toBe(0xffffffff);
+  });
+
+  it('follows an alias chain to its concrete value', () => {
+    const scene = sceneWith([
+      { key: 'a', kind: 'Color', values: { default: '$b' } },
+      { key: 'b', kind: 'Color', values: { default: '$c' } },
+      { key: 'c', kind: 'Color', values: { default: 0x3366ccff } },
+    ]);
+    const resolution = resolveFlightDocumentSceneTokens(scene, 'dark', createFlightDocumentTokenResolverRegistry());
+    expect(resolution?.values).toEqual({ a: 0x3366ccff, b: 0x3366ccff, c: 0x3366ccff });
+  });
+
+  it('resolves an escaped literal dollar sign instead of looking it up', () => {
+    const scene = sceneWith([{ key: 'price.label', kind: 'String', values: { default: '$$5.00' } }]);
+    const resolution = resolveFlightDocumentSceneTokens(scene, 'dark', createFlightDocumentTokenResolverRegistry());
+    expect(resolution?.values['price.label']).toBe('$5.00');
+  });
+
+  it('resolves an empty token section to an empty table rather than refusing', () => {
+    const resolution = resolveFlightDocumentSceneTokens(
+      sceneWith([]),
+      'dark',
+      createFlightDocumentTokenResolverRegistry(),
+    );
+    expect(resolution).toEqual({ mode: 'dark', values: {} });
+  });
+
+  it('returns null wherever the explain seam reports a refusal', () => {
+    const scene = sceneWith([token('Color', { dark: 'midnight' })]);
+    expect(resolveFlightDocumentSceneTokens(scene, 'dark', createFlightDocumentTokenResolverRegistry())).toBeNull();
+  });
+
+  it('refuses every kind when no resolver registry is supplied', () => {
+    expect(resolveFlightDocumentSceneTokens(sceneWith([token('Color', { default: 1 })]), 'dark')).toBeNull();
+  });
+});
+
+function resolveOne(
+  registry: Readonly<FlightDocumentTokenResolverRegistry>,
+  entry: FlightDocumentToken,
+): Record<string, unknown> | null {
+  const resolution = resolveFlightDocumentSceneTokens(sceneWith([entry]), 'dark', registry);
+  return resolution === null ? null : { ...resolution.values };
+}
+
+function sceneWith(tokens: readonly FlightDocumentToken[]): FlightDocumentScene2D {
+  return {
+    backgroundColor: null,
+    kind: 'Scene2D',
+    layouts: [],
+    scene: { children: [], fields: {}, kind: 'DisplayObject' },
+    tokens: [...tokens],
+  };
+}
+
+function token(kind: string, values: FlightDocumentToken['values']): FlightDocumentToken {
+  return { key: 'a.token', kind, values };
+}
+
+function withResolver(
+  registry: Readonly<FlightDocumentTokenResolverRegistry>,
+  kind: string,
+  resolver: (value: unknown) => unknown,
+): FlightDocumentTokenResolverRegistry['resolvers'] {
+  return withRegistryTableEntry(registry.resolvers, kind, resolver as never);
+}

package/src/flightDocumentTokenReference.test.ts

@@ -0,0 +1,86 @@
+import {
+  INVALID_FLIGHT_DOCUMENT_TOKEN_VALUE,
+  isFlightDocumentTokenReference,
+  readFlightDocumentTokenReferenceKey,
+  substituteFlightDocumentTokenValue,
+} from './flightDocumentTokenReference';
+
+describe('INVALID_FLIGHT_DOCUMENT_TOKEN_VALUE', () => {
+  it('is distinct from null, which a document may legitimately hold', () => {
+    expect(INVALID_FLIGHT_DOCUMENT_TOKEN_VALUE).not.toBeNull();
+    expect(typeof INVALID_FLIGHT_DOCUMENT_TOKEN_VALUE).toBe('symbol');
+  });
+});
+
+describe('isFlightDocumentTokenReference', () => {
+  it('accepts a sigil-prefixed scalar and rejects an escaped or ordinary one', () => {
+    expect(isFlightDocumentTokenReference('$color.primary')).toBe(true);
+    expect(isFlightDocumentTokenReference('$$5.00')).toBe(false);
+    expect(isFlightDocumentTokenReference('color.primary')).toBe(false);
+  });
+
+  it('rejects every non-string value, including one that could carry a reference inside it', () => {
+    expect(isFlightDocumentTokenReference(8)).toBe(false);
+    expect(isFlightDocumentTokenReference(null)).toBe(false);
+    expect(isFlightDocumentTokenReference(['$color.primary'])).toBe(false);
+  });
+});
+
+describe('readFlightDocumentTokenReferenceKey', () => {
+  it('reads a dotted key as one flat name rather than a path', () => {
+    expect(readFlightDocumentTokenReferenceKey('$color.primary')).toBe('color.primary');
+    expect(readFlightDocumentTokenReferenceKey('$acme.brand.primary')).toBe('acme.brand.primary');
+  });
+
+  it('refuses a key the codec would have had to quote', () => {
+    expect(readFlightDocumentTokenReferenceKey('$9lives')).toBeNull();
+    expect(readFlightDocumentTokenReferenceKey('$')).toBeNull();
+    expect(readFlightDocumentTokenReferenceKey('$has space')).toBeNull();
+  });
+});
+
+describe('substituteFlightDocumentTokenValue', () => {
+  it('replaces references at every depth and leaves other scalars alone', () => {
+    const value = substituteFlightDocumentTokenValue(
+      { commands: [{ beginFill: { alpha: 1, color: '$color.primary' } }], name: 'card' },
+      'fields',
+      (key) => (key === 'color.primary' ? 0x3366ccff : INVALID_FLIGHT_DOCUMENT_TOKEN_VALUE),
+      fail,
+    );
+    expect(value).toEqual({ commands: [{ beginFill: { alpha: 1, color: 0x3366ccff } }], name: 'card' });
+  });
+
+  it('unescapes a doubled sigil without consulting the lookup', () => {
+    expect(substituteFlightDocumentTokenValue('$$5.00', 'fields.text', fail as never, fail)).toBe('$5.00');
+  });
+
+  it('reports the path of a malformed reference and stops', () => {
+    const paths: string[] = [];
+    const value = substituteFlightDocumentTokenValue(
+      { commands: [{ beginFill: { color: '$9lives' } }] },
+      'fields',
+      () => INVALID_FLIGHT_DOCUMENT_TOKEN_VALUE,
+      (path) => paths.push(path),
+    );
+    expect(value).toBe(INVALID_FLIGHT_DOCUMENT_TOKEN_VALUE);
+    expect(paths).toEqual(['fields.commands[0].beginFill.color']);
+  });
+
+  it('propagates a lookup refusal out of a nested array', () => {
+    const value = substituteFlightDocumentTokenValue(
+      [1, ['$color.absent']],
+      'fields.ratios',
+      () => INVALID_FLIGHT_DOCUMENT_TOKEN_VALUE,
+      fail,
+    );
+    expect(value).toBe(INVALID_FLIGHT_DOCUMENT_TOKEN_VALUE);
+  });
+
+  it('returns a null scalar as a value rather than as a failure', () => {
+    expect(substituteFlightDocumentTokenValue(null, 'fields.blendMode', fail as never, fail)).toBeNull();
+  });
+});
+
+function fail(): never {
+  throw new Error('the walker consulted a seam this case must never reach');
+}

package/src/substituteFlightDocumentSceneTokens.test.ts

@@ -0,0 +1,178 @@
+import type {
+  FlightDocumentNode,
+  FlightDocumentScene,
+  FlightDocumentScene2D,
+  FlightDocumentScene3D,
+  FlightDocumentToken,
+  FlightDocumentTokenResolution,
+} from '@flighthq/types/contract';
+import { FlightDocumentRefusalReason } from '@flighthq/types/contract';
+
+import {
+  createFlightDocumentTokenResolverRegistry,
+  resolveFlightDocumentSceneTokens,
+} from './flightDocumentSceneTokens';
+import {
+  explainFlightDocumentSceneTokenSubstitution,
+  substituteFlightDocumentSceneTokens,
+} from './substituteFlightDocumentSceneTokens';
+
+describe('explainFlightDocumentSceneTokenSubstitution', () => {
+  it('names a reference no resolved token covers, with the field that carries it', () => {
+    const scene = sceneWith({ children: [], fields: { fill: '$color.absent' }, kind: 'Shape' }, [
+      { key: 'color.background', kind: 'Color', values: { default: 0xffffffff } },
+    ]);
+    const explanation = explainFlightDocumentSceneTokenSubstitution(scene, resolutionOf(scene));
+    expect(explanation?.reason).toBe(FlightDocumentRefusalReason.TokenUnresolved);
+    expect(explanation?.tokenKey).toBe('color.absent');
+    expect(explanation?.path).toBe('scene.fields.fill');
+  });
+
+  it('names a malformed reference rather than passing the raw string through', () => {
+    const scene = sceneWith({ children: [], fields: { fill: '$9lives' }, kind: 'Shape' }, []);
+    const explanation = explainFlightDocumentSceneTokenSubstitution(scene, resolutionOf(scene));
+    expect(explanation?.reason).toBe(FlightDocumentRefusalReason.TokenReferenceInvalid);
+    expect(explanation?.path).toBe('scene.fields.fill');
+  });
+
+  it('qualifies the path of a reference nested in a descendant command list', () => {
+    const scene = sceneWith(
+      {
+        children: [
+          { children: [], fields: {}, kind: 'Sprite' },
+          { children: [], fields: { commands: [{ beginFill: { color: '$color.absent' } }] }, kind: 'Shape' },
+        ],
+        fields: {},
+        kind: 'DisplayObject',
+      },
+      [],
+    );
+    const explanation = explainFlightDocumentSceneTokenSubstitution(scene, resolutionOf(scene));
+    expect(explanation?.path).toBe('scene.children[1].fields.commands[0].beginFill.color');
+  });
+
+  it('reports nothing when every reference resolves', () => {
+    const scene = sceneWith({ children: [], fields: { fill: '$color.background' }, kind: 'Shape' }, [
+      { key: 'color.background', kind: 'Color', values: { default: 0xffffffff } },
+    ]);
+    expect(explainFlightDocumentSceneTokenSubstitution(scene, resolutionOf(scene))).toBeNull();
+  });
+});
+
+describe('substituteFlightDocumentSceneTokens', () => {
+  it('replaces a reference nested inside a command argument map inside an array', () => {
+    const scene = sceneWith(
+      {
+        children: [
+          {
+            children: [],
+            fields: {
+              commands: [
+                { beginFill: { alpha: 1, color: '$color.background' } },
+                { drawRectangle: { height: '$space.gutter', width: 120 } },
+              ],
+            },
+            kind: 'Shape',
+          },
+        ],
+        fields: {},
+        kind: 'DisplayObject',
+      },
+      [
+        { key: 'color.background', kind: 'Color', values: { dark: 0x1a1a1aff, light: 0xffffffff } },
+        { key: 'space.gutter', kind: 'Number', values: { default: 8 } },
+      ],
+    );
+    const substituted = substituteFlightDocumentSceneTokens(scene, resolutionOf(scene, 'dark'));
+    // The expected values are literals, not reads back out of the token rows the substitution used: a
+    // test that sourced them from scene.tokens would pass for any mapping, including the wrong one.
+    expect(substituted?.scene.children[0].fields['commands']).toEqual([
+      { beginFill: { alpha: 1, color: 0x1a1a1aff } },
+      { drawRectangle: { height: 8, width: 120 } },
+    ]);
+  });
+
+  it('leaves a scene without references structurally equal to its input', () => {
+    const scene = sceneWith({ children: [], fields: { x: 12 }, kind: 'Sprite' }, []);
+    expect(substituteFlightDocumentSceneTokens(scene, resolutionOf(scene))).toEqual(scene);
+  });
+
+  it('never mutates the scene it was given', () => {
+    const scene = sceneWith({ children: [], fields: { fill: '$color.background' }, kind: 'Shape' }, [
+      { key: 'color.background', kind: 'Color', values: { default: 0xffffffff } },
+    ]);
+    substituteFlightDocumentSceneTokens(scene, resolutionOf(scene));
+    expect(scene.scene.fields['fill']).toBe('$color.background');
+  });
+
+  it('keeps the token section so the palette still round-trips', () => {
+    const scene = sceneWith({ children: [], fields: { fill: '$color.background' }, kind: 'Shape' }, [
+      { key: 'color.background', kind: 'Color', values: { default: 0xffffffff } },
+    ]);
+    expect(substituteFlightDocumentSceneTokens(scene, resolutionOf(scene))?.tokens).toEqual(scene.tokens);
+  });
+
+  it('preserves inert layout metadata while substituting node fields', () => {
+    const scene = sceneWith({ children: [], fields: { fill: '$color.background', name: 'root' }, kind: 'Shape' }, [
+      { key: 'color.background', kind: 'Color', values: { default: 0xffffffff } },
+    ]);
+    scene.layouts.push({
+      targets: ['root'],
+      tree: {
+        nodes: [{ containerStyle: { gap: 8 }, itemStyle: null, kind: 'acme.Flow', parentIndex: -1 }],
+      },
+    });
+
+    expect(substituteFlightDocumentSceneTokens(scene, resolutionOf(scene))?.layouts).toBe(scene.layouts);
+  });
+
+  it('resolves an escaped dollar sign to a literal instead of looking it up', () => {
+    const scene = sceneWith({ children: [], fields: { text: '$$5.00' }, kind: 'TextLabel' }, []);
+    expect(substituteFlightDocumentSceneTokens(scene, resolutionOf(scene))?.scene.fields['text']).toBe('$5.00');
+  });
+
+  it('preserves the 3D dimension and its camera and light sections', () => {
+    const scene: FlightDocumentScene3D = {
+      cameras: [],
+      kind: 'Scene3D',
+      layouts: [],
+      lights: [],
+      scene: { children: [], fields: { alpha: '$opacity.dim' }, kind: 'Node3D' },
+      tokens: [{ key: 'opacity.dim', kind: 'Number', values: { default: 0.5 } }],
+    };
+    const resolution = resolveFlightDocumentSceneTokens(scene, 'dark', createFlightDocumentTokenResolverRegistry());
+    if (resolution === null) throw new Error('expected the 3D token fixture to resolve');
+    const substituted = substituteFlightDocumentSceneTokens(scene, resolution);
+    expect(substituted?.kind).toBe('Scene3D');
+    expect(substituted?.cameras).toEqual([]);
+    expect(substituted?.scene.fields['alpha']).toBe(0.5);
+  });
+
+  it('accepts the scene union a caller reads out of document.scenes without narrowing it first', () => {
+    const entries: FlightDocumentScene[] = [
+      sceneWith({ children: [], fields: { fill: '$color.background' }, kind: 'Shape' }, [
+        { key: 'color.background', kind: 'Color', values: { default: 0xffffffff } },
+      ]),
+    ];
+    const substituted = substituteFlightDocumentSceneTokens(entries[0], resolutionOf(entries[0]));
+    expect(substituted?.kind).toBe('Scene2D');
+  });
+
+  it('returns null wherever the explain seam reports a refusal', () => {
+    const scene = sceneWith({ children: [], fields: { fill: '$color.absent' }, kind: 'Shape' }, []);
+    expect(substituteFlightDocumentSceneTokens(scene, resolutionOf(scene))).toBeNull();
+  });
+});
+
+function resolutionOf(
+  scene: Readonly<FlightDocumentScene2D | FlightDocumentScene3D>,
+  mode = 'default',
+): FlightDocumentTokenResolution {
+  const resolution = resolveFlightDocumentSceneTokens(scene, mode, createFlightDocumentTokenResolverRegistry());
+  if (resolution === null) throw new Error('expected the fixture token table to resolve');
+  return resolution;
+}
+
+function sceneWith(scene: FlightDocumentNode, tokens: readonly FlightDocumentToken[]): FlightDocumentScene2D {
+  return { backgroundColor: null, kind: 'Scene2D', layouts: [], scene, tokens: [...tokens] };
+}