@pixerate/editor 0.23.0 → 0.25.0

package/dist/migrate-iTlm3a8h.d.cts

@@ -0,0 +1,112 @@
+/** A section whose stored value did not fit; its defaults were used instead. */
+interface SectionProblem {
+    /** Top-level key of the section. */
+    section: string;
+    message: string;
+}
+/** Why a loaded document must not be written back. */
+type ReadOnlyReason = {
+    kind: "newerVersion";
+    version: number;
+    supported: number;
+    message: string;
+} | {
+    kind: "migrationFailed";
+    from: number;
+    message: string;
+} | {
+    kind: "invalid";
+    message: string;
+};
+/** What happened while loading a document. Nothing in here is fatal. */
+interface LoadReport {
+    /** Set when the document was upgraded step by step from this older version. */
+    migratedFrom: number | null;
+    /** The version found in the input (`null` when it had none). */
+    version: number | null;
+    /** Sections replaced by their defaults (see `loadSections`). */
+    problems: SectionProblem[];
+    /**
+     * Set when the document must not be saved over: written by a newer build,
+     * a migration step failed, or the input was not an object. Show the values,
+     * but never overwrite the stored document.
+     */
+    readOnly: ReadOnlyReason | null;
+    /** Top-level keys this build does not know; kept in `unknown` so a save can write them back. */
+    unknownKeys: string[];
+}
+/** True when something should be shown to the user. */
+declare function hasLoadProblems(report: LoadReport): boolean;
+declare function createLoadReport(partial?: Partial<LoadReport>): LoadReport;
+type JsonObject = Record<string, unknown>;
+/** One migration step: turns a document at version `from` into version `from + 1`. */
+type MigrationStep = (doc: JsonObject) => JsonObject | void;
+interface MigrateOptions {
+    /** The version this build writes. */
+    currentVersion: number;
+    /** Steps keyed by the version they start from. */
+    steps?: Record<number, MigrationStep>;
+    /** Key holding the version (default `"version"`). */
+    versionKey?: string;
+    /**
+     * Version assumed when the key is missing (default: `currentVersion`, i.e. a
+     * hand-written document is taken as current and the key is added).
+     */
+    missingVersion?: number;
+}
+interface MigrateResult {
+    /** The migrated document (a deep copy; the input is never modified). */
+    doc: JsonObject;
+    report: LoadReport;
+}
+/**
+ * Brings a stored document up to `currentVersion` by running one step per
+ * version (`steps[v]` turns version `v` into `v + 1`).
+ *
+ * - Missing version: taken as `missingVersion` (default current); the key is added.
+ * - Newer than `currentVersion`: left alone and reported `readOnly` (never overwrite
+ *   a file written by a newer build).
+ * - A missing or throwing step: the document is returned as it was before
+ *   migrating and reported `readOnly`.
+ * - Keys the steps do not touch are preserved.
+ */
+declare function migrateDocument(json: unknown, options: MigrateOptions): MigrateResult;
+/** How one top-level section is read. */
+interface SectionSpec<V> {
+    /** Validates / converts the stored value; throw (or return `undefined`) to reject it. */
+    parse: (value: unknown) => V | undefined;
+    /** Used when the section is missing or rejected. */
+    defaults: V | (() => V);
+}
+type SectionSpecs<T> = {
+    [K in keyof T]: SectionSpec<T[K]>;
+};
+interface LoadSectionsOptions {
+    /** Keys that are neither sections nor unknown (default `["version"]`). */
+    ignore?: string[];
+}
+interface LoadSectionsResult<T> {
+    value: T;
+    /** Sections that were present but rejected (missing ones are not problems). */
+    problems: SectionProblem[];
+    /** Top-level keys not described by `sections`; write them back to keep them. */
+    unknown: JsonObject;
+}
+/**
+ * Reads `doc` one top-level section at a time: a section that does not parse
+ * is reported and replaced by its defaults, every other section is kept. This
+ * keeps one bad value (e.g. a renamed enum) from resetting the whole document.
+ */
+declare function loadSections<T>(doc: unknown, sections: SectionSpecs<T>, options?: LoadSectionsOptions): LoadSectionsResult<T>;
+interface LoadDocumentOptions extends MigrateOptions, LoadSectionsOptions {
+}
+interface LoadDocumentResult<T> extends LoadSectionsResult<T> {
+    report: LoadReport;
+}
+/**
+ * `migrateDocument` followed by `loadSections`, with one `LoadReport`
+ * (`problems` and `unknownKeys` filled in).
+ */
+declare function loadDocument<T>(json: unknown, sections: SectionSpecs<T>, options: LoadDocumentOptions): LoadDocumentResult<T>;
+
+export { type JsonObject as J, type LoadDocumentOptions as L, type MigrateOptions as M, type ReadOnlyReason as R, type SectionProblem as S, type LoadDocumentResult as a, type LoadReport as b, type LoadSectionsOptions as c, type LoadSectionsResult as d, type MigrateResult as e, type MigrationStep as f, type SectionSpec as g, type SectionSpecs as h, createLoadReport as i, hasLoadProblems as j, loadSections as k, loadDocument as l, migrateDocument as m };

package/dist/migrate-iTlm3a8h.d.ts

@@ -0,0 +1,112 @@
+/** A section whose stored value did not fit; its defaults were used instead. */
+interface SectionProblem {
+    /** Top-level key of the section. */
+    section: string;
+    message: string;
+}
+/** Why a loaded document must not be written back. */
+type ReadOnlyReason = {
+    kind: "newerVersion";
+    version: number;
+    supported: number;
+    message: string;
+} | {
+    kind: "migrationFailed";
+    from: number;
+    message: string;
+} | {
+    kind: "invalid";
+    message: string;
+};
+/** What happened while loading a document. Nothing in here is fatal. */
+interface LoadReport {
+    /** Set when the document was upgraded step by step from this older version. */
+    migratedFrom: number | null;
+    /** The version found in the input (`null` when it had none). */
+    version: number | null;
+    /** Sections replaced by their defaults (see `loadSections`). */
+    problems: SectionProblem[];
+    /**
+     * Set when the document must not be saved over: written by a newer build,
+     * a migration step failed, or the input was not an object. Show the values,
+     * but never overwrite the stored document.
+     */
+    readOnly: ReadOnlyReason | null;
+    /** Top-level keys this build does not know; kept in `unknown` so a save can write them back. */
+    unknownKeys: string[];
+}
+/** True when something should be shown to the user. */
+declare function hasLoadProblems(report: LoadReport): boolean;
+declare function createLoadReport(partial?: Partial<LoadReport>): LoadReport;
+type JsonObject = Record<string, unknown>;
+/** One migration step: turns a document at version `from` into version `from + 1`. */
+type MigrationStep = (doc: JsonObject) => JsonObject | void;
+interface MigrateOptions {
+    /** The version this build writes. */
+    currentVersion: number;
+    /** Steps keyed by the version they start from. */
+    steps?: Record<number, MigrationStep>;
+    /** Key holding the version (default `"version"`). */
+    versionKey?: string;
+    /**
+     * Version assumed when the key is missing (default: `currentVersion`, i.e. a
+     * hand-written document is taken as current and the key is added).
+     */
+    missingVersion?: number;
+}
+interface MigrateResult {
+    /** The migrated document (a deep copy; the input is never modified). */
+    doc: JsonObject;
+    report: LoadReport;
+}
+/**
+ * Brings a stored document up to `currentVersion` by running one step per
+ * version (`steps[v]` turns version `v` into `v + 1`).
+ *
+ * - Missing version: taken as `missingVersion` (default current); the key is added.
+ * - Newer than `currentVersion`: left alone and reported `readOnly` (never overwrite
+ *   a file written by a newer build).
+ * - A missing or throwing step: the document is returned as it was before
+ *   migrating and reported `readOnly`.
+ * - Keys the steps do not touch are preserved.
+ */
+declare function migrateDocument(json: unknown, options: MigrateOptions): MigrateResult;
+/** How one top-level section is read. */
+interface SectionSpec<V> {
+    /** Validates / converts the stored value; throw (or return `undefined`) to reject it. */
+    parse: (value: unknown) => V | undefined;
+    /** Used when the section is missing or rejected. */
+    defaults: V | (() => V);
+}
+type SectionSpecs<T> = {
+    [K in keyof T]: SectionSpec<T[K]>;
+};
+interface LoadSectionsOptions {
+    /** Keys that are neither sections nor unknown (default `["version"]`). */
+    ignore?: string[];
+}
+interface LoadSectionsResult<T> {
+    value: T;
+    /** Sections that were present but rejected (missing ones are not problems). */
+    problems: SectionProblem[];
+    /** Top-level keys not described by `sections`; write them back to keep them. */
+    unknown: JsonObject;
+}
+/**
+ * Reads `doc` one top-level section at a time: a section that does not parse
+ * is reported and replaced by its defaults, every other section is kept. This
+ * keeps one bad value (e.g. a renamed enum) from resetting the whole document.
+ */
+declare function loadSections<T>(doc: unknown, sections: SectionSpecs<T>, options?: LoadSectionsOptions): LoadSectionsResult<T>;
+interface LoadDocumentOptions extends MigrateOptions, LoadSectionsOptions {
+}
+interface LoadDocumentResult<T> extends LoadSectionsResult<T> {
+    report: LoadReport;
+}
+/**
+ * `migrateDocument` followed by `loadSections`, with one `LoadReport`
+ * (`problems` and `unknownKeys` filled in).
+ */
+declare function loadDocument<T>(json: unknown, sections: SectionSpecs<T>, options: LoadDocumentOptions): LoadDocumentResult<T>;
+
+export { type JsonObject as J, type LoadDocumentOptions as L, type MigrateOptions as M, type ReadOnlyReason as R, type SectionProblem as S, type LoadDocumentResult as a, type LoadReport as b, type LoadSectionsOptions as c, type LoadSectionsResult as d, type MigrateResult as e, type MigrationStep as f, type SectionSpec as g, type SectionSpecs as h, createLoadReport as i, hasLoadProblems as j, loadSections as k, loadDocument as l, migrateDocument as m };

package/dist/model-C1zApQM8.d.cts

@@ -0,0 +1,219 @@
+/**
+ * Design tokens (Figma-style "variables"): collections hold modes (e.g. Light / Dark) and
+ * typed variables with one value per mode. A value is a literal or an alias to another
+ * variable of the same type, possibly in another collection.
+ *
+ * The state is plain, immutable, JSON-serialisable data. Every operation returns a new state.
+ */
+/** A variable's type. */
+type TokenType = 'color' | 'number' | 'string' | 'boolean';
+declare const TOKEN_TYPES: readonly TokenType[];
+/** A resolved value: colours are normalised hex strings (`#rrggbb` or `#rrggbbaa`). */
+type TokenLiteral = string | number | boolean;
+/** A reference to another variable (by id). */
+interface TokenAlias {
+    alias: string;
+}
+/** What a variable holds in one mode. */
+type TokenValue = TokenLiteral | TokenAlias;
+interface TokenMode {
+    id: string;
+    name: string;
+}
+interface TokenCollection {
+    id: string;
+    name: string;
+    /** At least one mode. The first one is the default mode. */
+    modes: readonly TokenMode[];
+}
+/**
+ * Which properties pickers offer a variable for (figcraft / Figma scope ids). Scopes only
+ * filter pickers: binding out of scope still works.
+ */
+type TokenScope = 'ALL_SCOPES' | 'ALL_FILLS' | 'FRAME_FILL' | 'SHAPE_FILL' | 'TEXT_FILL' | 'STROKE_COLOR' | 'EFFECT_COLOR' | 'CORNER_RADIUS' | 'WIDTH_HEIGHT' | 'GAP' | 'OPACITY' | 'STROKE_FLOAT' | 'EFFECT_FLOAT' | 'FONT_WEIGHT' | 'FONT_SIZE' | 'LINE_HEIGHT' | 'LETTER_SPACING' | 'PARAGRAPH_SPACING' | 'PARAGRAPH_INDENT' | 'TEXT_CONTENT' | 'FONT_FAMILY' | 'FONT_STYLE';
+interface TokenVariable {
+    id: string;
+    /** Unique within its collection. `/` separates groups (`color/bg`). */
+    name: string;
+    collectionId: string;
+    type: TokenType;
+    /** Value per mode id of the collection. */
+    valuesByMode: Readonly<Record<string, TokenValue>>;
+    description?: string;
+    /** Pickers offer the variable for these scopes; `undefined` = every supported property. */
+    scopes?: readonly TokenScope[];
+    /** Unit for number variables in CSS / W3C export (`px`, `rem`, `ms`, …). */
+    unit?: string;
+}
+interface TokenState {
+    collections: readonly TokenCollection[];
+    variables: readonly TokenVariable[];
+}
+/**
+ * Chosen mode per collection: `{ [collectionId]: modeId }`. Collections not listed (or with an
+ * unknown mode) use their default (first) mode.
+ */
+type TokenModeContext = Readonly<Record<string, string>>;
+type TokenErrorCode = 'not-found' | 'invalid-name' | 'duplicate-name' | 'name-conflict' | 'invalid-type' | 'invalid-value' | 'type-mismatch' | 'alias-missing' | 'alias-cycle' | 'last-mode' | 'unknown-scope' | 'invalid-input';
+/** Thrown by token operations that are refused; `code` says why. */
+declare class TokenError extends Error {
+    readonly code: TokenErrorCode;
+    constructor(code: TokenErrorCode, message: string);
+}
+declare function isTokenAlias(value: unknown): value is TokenAlias;
+declare const EMPTY_TOKEN_STATE: TokenState;
+
+declare function getTokenCollection(state: TokenState, id: string): TokenCollection | undefined;
+declare function getTokenVariable(state: TokenState, id: string): TokenVariable | undefined;
+/** The collection with this name. */
+declare function findTokenCollection(state: TokenState, name: string): TokenCollection | undefined;
+/** The variable named `name` (in `collectionId` when given, else the first match). */
+declare function findTokenVariable(state: TokenState, name: string, collectionId?: string): TokenVariable | undefined;
+/** The variables of a collection, in order. */
+declare function getCollectionVariables(state: TokenState, collectionId: string): TokenVariable[];
+/** The collection's default (first) mode. */
+declare function getDefaultMode(collection: TokenCollection): TokenMode;
+/** The mode with id `key`, else the one named `key`. */
+declare function findTokenMode(collection: TokenCollection, key: string): TokenMode | undefined;
+/** The mode `collection` is in under `modes` (its chosen mode if valid, else the default). */
+declare function getCurrentMode(collection: TokenCollection, modes: TokenModeContext | undefined): TokenMode;
+/** A new variable's value per type: black, 0, empty, true (figcraft's pinned defaults). */
+declare function defaultTokenValue(type: TokenType): TokenLiteral;
+/** The literal as `type`, or `null` when it does not fit (colours are normalised). */
+declare function coerceTokenLiteral(type: TokenType, value: unknown): TokenLiteral | null;
+/** The type of a literal value (strings that are colours count as strings). */
+declare function literalTokenType(value: TokenLiteral): TokenType;
+/** A short text for a value: hex, number, string, boolean, or `→ name` for an alias. */
+declare function formatTokenValue(state: TokenState, value: TokenValue | undefined): string;
+type TokenResolutionErrorCode = 'missing' | 'cycle' | 'no-value' | 'type-mismatch';
+type TokenResolution = {
+    ok: true;
+    value: TokenLiteral;
+    type: TokenType;
+    /** The variable whose literal was used (the end of the alias chain). */
+    variable: TokenVariable;
+    /** Mode of `variable`'s collection that supplied the value. */
+    modeId: string;
+    /** Variable ids visited, starting with the requested one. */
+    chain: string[];
+} | {
+    ok: false;
+    code: TokenResolutionErrorCode;
+    message: string;
+    chain: string[];
+};
+/**
+ * Resolves variable `id` under `modes` (collection id → mode id; the default mode otherwise),
+ * following aliases. Each variable along the chain is read in its own collection's mode.
+ * Cycles, missing variables and type changes along the chain are reported, never thrown.
+ */
+declare function resolveToken(state: TokenState, id: string, modes?: TokenModeContext): TokenResolution;
+/** The resolved literal, or `undefined` when it does not resolve. */
+declare function resolveTokenValue(state: TokenState, id: string, modes?: TokenModeContext): TokenLiteral | undefined;
+/** The value of `variableId` in mode `modeId` of its own collection (other collections in their default mode). */
+declare function resolveTokenInMode(state: TokenState, variableId: string, modeId: string): TokenLiteral | undefined;
+/**
+ * Why `variable` cannot alias `targetId`, or `null` when it can: the target must exist, have
+ * the same type, and not lead back to `variable` through any alias in any mode.
+ */
+declare function checkTokenAlias(state: TokenState, variable: Pick<TokenVariable, 'id' | 'type' | 'name'>, targetId: string): TokenError | null;
+declare const TOKEN_SCOPES_BY_TYPE: Readonly<Record<TokenType, readonly TokenScope[]>>;
+/** Whether `scope` is a scope a variable of `type` can be limited to. */
+declare function isTokenScopeKnown(type: TokenType, scope: string): scope is TokenScope;
+/**
+ * Canonical scope list: known ids only, no repeats, `undefined` (no limit) when every
+ * supported property is named. Unknown ids throw `unknown-scope`.
+ */
+declare function normalizeTokenScopes(type: TokenType, scopes: readonly string[] | null | undefined): TokenScope[] | undefined;
+/** Whether pickers offer `variable` for a property of `scope` (no scope: any). */
+declare function isTokenInScope(variable: Pick<TokenVariable, 'scopes'>, scope: TokenScope | undefined): boolean;
+/** Trims each `/`-separated group; throws `invalid-name` when empty or not exportable. */
+declare function normalizeTokenName(name: unknown, what?: string): string;
+type TokenIdFactory = (kind: 'collection' | 'mode' | 'variable') => string;
+/** Default id factory: `crypto.randomUUID`, with a counter fallback. */
+declare const defaultTokenId: TokenIdFactory;
+interface CreateTokenCollectionInput {
+    name: string;
+    /** Mode names (default `['Default']`). */
+    modes?: readonly string[];
+}
+declare function createTokenCollection(state: TokenState, input: CreateTokenCollectionInput, createId?: TokenIdFactory): {
+    state: TokenState;
+    collection: TokenCollection;
+};
+declare function renameTokenCollection(state: TokenState, id: string, name: string): TokenState;
+/**
+ * Deletes variables `ids`. Variables aliasing one of them take its values (per mode: the deleted
+ * variable resolved in that mode when it is in the same collection, else in its default mode).
+ */
+declare function deleteTokenVariables(state: TokenState, ids: Iterable<string>): {
+    state: TokenState;
+    deleted: string[];
+};
+/** Deletes a collection and its variables (aliases into it are detached to their values). */
+declare function deleteTokenCollection(state: TokenState, id: string): {
+    state: TokenState;
+    deleted: string[];
+};
+/**
+ * Adds a mode. Variables start with the values of mode `from` (default: the default mode).
+ */
+declare function addTokenMode(state: TokenState, collectionId: string, name: string, options?: {
+    from?: string;
+}, createId?: TokenIdFactory): {
+    state: TokenState;
+    mode: TokenMode;
+};
+declare function renameTokenMode(state: TokenState, collectionId: string, modeId: string, name: string): TokenState;
+/** Removes a mode and its values; a collection keeps at least one mode. */
+declare function removeTokenMode(state: TokenState, collectionId: string, modeId: string): TokenState;
+/** Moves a mode to index `to` (clamped). Index 0 makes it the default mode. */
+declare function moveTokenMode(state: TokenState, collectionId: string, modeId: string, to: number): TokenState;
+interface CreateTokenVariableInput {
+    collectionId: string;
+    name: string;
+    type: TokenType;
+    /** Value for every mode (literal or `{ alias }`). Default: the type's default. */
+    value?: unknown;
+    /** Values by mode id or name (win over `value`). */
+    values?: Readonly<Record<string, unknown>>;
+    description?: string;
+    scopes?: readonly string[];
+    unit?: string;
+}
+/** A value for `variable`: a normalised literal or a checked alias. Throws when refused. */
+declare function prepareTokenValue(state: TokenState, variable: Pick<TokenVariable, 'id' | 'type' | 'name'>, value: unknown): TokenValue;
+declare function createTokenVariable(state: TokenState, input: CreateTokenVariableInput, createId?: TokenIdFactory): {
+    state: TokenState;
+    variable: TokenVariable;
+};
+/**
+ * Sets a variable's value in one mode (id or name; default: the default mode) to a literal or
+ * `{ alias: variableId }`. Aliases must keep the type and not create a cycle.
+ */
+declare function setTokenValue(state: TokenState, variableId: string, value: unknown, modeId?: string): TokenState;
+declare function renameTokenVariable(state: TokenState, variableId: string, name: string): TokenState;
+interface UpdateTokenVariableInput {
+    description?: string;
+    /** `null` clears the limit (every property). */
+    scopes?: readonly string[] | null;
+    /** `null` clears the unit. */
+    unit?: string | null;
+}
+declare function updateTokenVariable(state: TokenState, variableId: string, input: UpdateTokenVariableInput): TokenState;
+interface TokenStateIssue {
+    message: string;
+    collectionId?: string;
+    variableId?: string;
+}
+/**
+ * Reads untrusted data (e.g. a saved `TokenState`) and keeps what is valid: junk collections,
+ * modes and variables are dropped, bad values replaced by the type's default and alias cycles
+ * broken, each with an issue.
+ */
+declare function parseTokenState(input: unknown): {
+    state: TokenState;
+    issues: TokenStateIssue[];
+};
+
+export { resolveToken as $, deleteTokenCollection as A, deleteTokenVariables as B, type CreateTokenVariableInput as C, findTokenCollection as D, EMPTY_TOKEN_STATE as E, findTokenMode as F, findTokenVariable as G, formatTokenValue as H, getCollectionVariables as I, getCurrentMode as J, getDefaultMode as K, getTokenCollection as L, getTokenVariable as M, isTokenAlias as N, isTokenInScope as O, isTokenScopeKnown as P, literalTokenType as Q, moveTokenMode as R, normalizeTokenName as S, type TokenState as T, type UpdateTokenVariableInput as U, normalizeTokenScopes as V, prepareTokenValue as W, removeTokenMode as X, renameTokenCollection as Y, renameTokenMode as Z, renameTokenVariable as _, type TokenIdFactory as a, resolveTokenInMode as a0, resolveTokenValue as a1, setTokenValue as a2, updateTokenVariable as a3, type TokenCollection as b, type TokenVariable as c, type TokenModeContext as d, type TokenResolution as e, type TokenLiteral as f, type TokenMode as g, type CreateTokenCollectionInput as h, TOKEN_SCOPES_BY_TYPE as i, TOKEN_TYPES as j, type TokenAlias as k, TokenError as l, type TokenErrorCode as m, type TokenResolutionErrorCode as n, type TokenScope as o, parseTokenState as p, type TokenStateIssue as q, type TokenType as r, type TokenValue as s, addTokenMode as t, checkTokenAlias as u, coerceTokenLiteral as v, createTokenCollection as w, createTokenVariable as x, defaultTokenId as y, defaultTokenValue as z };

package/dist/model-C1zApQM8.d.ts

@@ -0,0 +1,219 @@
+/**
+ * Design tokens (Figma-style "variables"): collections hold modes (e.g. Light / Dark) and
+ * typed variables with one value per mode. A value is a literal or an alias to another
+ * variable of the same type, possibly in another collection.
+ *
+ * The state is plain, immutable, JSON-serialisable data. Every operation returns a new state.
+ */
+/** A variable's type. */
+type TokenType = 'color' | 'number' | 'string' | 'boolean';
+declare const TOKEN_TYPES: readonly TokenType[];
+/** A resolved value: colours are normalised hex strings (`#rrggbb` or `#rrggbbaa`). */
+type TokenLiteral = string | number | boolean;
+/** A reference to another variable (by id). */
+interface TokenAlias {
+    alias: string;
+}
+/** What a variable holds in one mode. */
+type TokenValue = TokenLiteral | TokenAlias;
+interface TokenMode {
+    id: string;
+    name: string;
+}
+interface TokenCollection {
+    id: string;
+    name: string;
+    /** At least one mode. The first one is the default mode. */
+    modes: readonly TokenMode[];
+}
+/**
+ * Which properties pickers offer a variable for (figcraft / Figma scope ids). Scopes only
+ * filter pickers: binding out of scope still works.
+ */
+type TokenScope = 'ALL_SCOPES' | 'ALL_FILLS' | 'FRAME_FILL' | 'SHAPE_FILL' | 'TEXT_FILL' | 'STROKE_COLOR' | 'EFFECT_COLOR' | 'CORNER_RADIUS' | 'WIDTH_HEIGHT' | 'GAP' | 'OPACITY' | 'STROKE_FLOAT' | 'EFFECT_FLOAT' | 'FONT_WEIGHT' | 'FONT_SIZE' | 'LINE_HEIGHT' | 'LETTER_SPACING' | 'PARAGRAPH_SPACING' | 'PARAGRAPH_INDENT' | 'TEXT_CONTENT' | 'FONT_FAMILY' | 'FONT_STYLE';
+interface TokenVariable {
+    id: string;
+    /** Unique within its collection. `/` separates groups (`color/bg`). */
+    name: string;
+    collectionId: string;
+    type: TokenType;
+    /** Value per mode id of the collection. */
+    valuesByMode: Readonly<Record<string, TokenValue>>;
+    description?: string;
+    /** Pickers offer the variable for these scopes; `undefined` = every supported property. */
+    scopes?: readonly TokenScope[];
+    /** Unit for number variables in CSS / W3C export (`px`, `rem`, `ms`, …). */
+    unit?: string;
+}
+interface TokenState {
+    collections: readonly TokenCollection[];
+    variables: readonly TokenVariable[];
+}
+/**
+ * Chosen mode per collection: `{ [collectionId]: modeId }`. Collections not listed (or with an
+ * unknown mode) use their default (first) mode.
+ */
+type TokenModeContext = Readonly<Record<string, string>>;
+type TokenErrorCode = 'not-found' | 'invalid-name' | 'duplicate-name' | 'name-conflict' | 'invalid-type' | 'invalid-value' | 'type-mismatch' | 'alias-missing' | 'alias-cycle' | 'last-mode' | 'unknown-scope' | 'invalid-input';
+/** Thrown by token operations that are refused; `code` says why. */
+declare class TokenError extends Error {
+    readonly code: TokenErrorCode;
+    constructor(code: TokenErrorCode, message: string);
+}
+declare function isTokenAlias(value: unknown): value is TokenAlias;
+declare const EMPTY_TOKEN_STATE: TokenState;
+
+declare function getTokenCollection(state: TokenState, id: string): TokenCollection | undefined;
+declare function getTokenVariable(state: TokenState, id: string): TokenVariable | undefined;
+/** The collection with this name. */
+declare function findTokenCollection(state: TokenState, name: string): TokenCollection | undefined;
+/** The variable named `name` (in `collectionId` when given, else the first match). */
+declare function findTokenVariable(state: TokenState, name: string, collectionId?: string): TokenVariable | undefined;
+/** The variables of a collection, in order. */
+declare function getCollectionVariables(state: TokenState, collectionId: string): TokenVariable[];
+/** The collection's default (first) mode. */
+declare function getDefaultMode(collection: TokenCollection): TokenMode;
+/** The mode with id `key`, else the one named `key`. */
+declare function findTokenMode(collection: TokenCollection, key: string): TokenMode | undefined;
+/** The mode `collection` is in under `modes` (its chosen mode if valid, else the default). */
+declare function getCurrentMode(collection: TokenCollection, modes: TokenModeContext | undefined): TokenMode;
+/** A new variable's value per type: black, 0, empty, true (figcraft's pinned defaults). */
+declare function defaultTokenValue(type: TokenType): TokenLiteral;
+/** The literal as `type`, or `null` when it does not fit (colours are normalised). */
+declare function coerceTokenLiteral(type: TokenType, value: unknown): TokenLiteral | null;
+/** The type of a literal value (strings that are colours count as strings). */
+declare function literalTokenType(value: TokenLiteral): TokenType;
+/** A short text for a value: hex, number, string, boolean, or `→ name` for an alias. */
+declare function formatTokenValue(state: TokenState, value: TokenValue | undefined): string;
+type TokenResolutionErrorCode = 'missing' | 'cycle' | 'no-value' | 'type-mismatch';
+type TokenResolution = {
+    ok: true;
+    value: TokenLiteral;
+    type: TokenType;
+    /** The variable whose literal was used (the end of the alias chain). */
+    variable: TokenVariable;
+    /** Mode of `variable`'s collection that supplied the value. */
+    modeId: string;
+    /** Variable ids visited, starting with the requested one. */
+    chain: string[];
+} | {
+    ok: false;
+    code: TokenResolutionErrorCode;
+    message: string;
+    chain: string[];
+};
+/**
+ * Resolves variable `id` under `modes` (collection id → mode id; the default mode otherwise),
+ * following aliases. Each variable along the chain is read in its own collection's mode.
+ * Cycles, missing variables and type changes along the chain are reported, never thrown.
+ */
+declare function resolveToken(state: TokenState, id: string, modes?: TokenModeContext): TokenResolution;
+/** The resolved literal, or `undefined` when it does not resolve. */
+declare function resolveTokenValue(state: TokenState, id: string, modes?: TokenModeContext): TokenLiteral | undefined;
+/** The value of `variableId` in mode `modeId` of its own collection (other collections in their default mode). */
+declare function resolveTokenInMode(state: TokenState, variableId: string, modeId: string): TokenLiteral | undefined;
+/**
+ * Why `variable` cannot alias `targetId`, or `null` when it can: the target must exist, have
+ * the same type, and not lead back to `variable` through any alias in any mode.
+ */
+declare function checkTokenAlias(state: TokenState, variable: Pick<TokenVariable, 'id' | 'type' | 'name'>, targetId: string): TokenError | null;
+declare const TOKEN_SCOPES_BY_TYPE: Readonly<Record<TokenType, readonly TokenScope[]>>;
+/** Whether `scope` is a scope a variable of `type` can be limited to. */
+declare function isTokenScopeKnown(type: TokenType, scope: string): scope is TokenScope;
+/**
+ * Canonical scope list: known ids only, no repeats, `undefined` (no limit) when every
+ * supported property is named. Unknown ids throw `unknown-scope`.
+ */
+declare function normalizeTokenScopes(type: TokenType, scopes: readonly string[] | null | undefined): TokenScope[] | undefined;
+/** Whether pickers offer `variable` for a property of `scope` (no scope: any). */
+declare function isTokenInScope(variable: Pick<TokenVariable, 'scopes'>, scope: TokenScope | undefined): boolean;
+/** Trims each `/`-separated group; throws `invalid-name` when empty or not exportable. */
+declare function normalizeTokenName(name: unknown, what?: string): string;
+type TokenIdFactory = (kind: 'collection' | 'mode' | 'variable') => string;
+/** Default id factory: `crypto.randomUUID`, with a counter fallback. */
+declare const defaultTokenId: TokenIdFactory;
+interface CreateTokenCollectionInput {
+    name: string;
+    /** Mode names (default `['Default']`). */
+    modes?: readonly string[];
+}
+declare function createTokenCollection(state: TokenState, input: CreateTokenCollectionInput, createId?: TokenIdFactory): {
+    state: TokenState;
+    collection: TokenCollection;
+};
+declare function renameTokenCollection(state: TokenState, id: string, name: string): TokenState;
+/**
+ * Deletes variables `ids`. Variables aliasing one of them take its values (per mode: the deleted
+ * variable resolved in that mode when it is in the same collection, else in its default mode).
+ */
+declare function deleteTokenVariables(state: TokenState, ids: Iterable<string>): {
+    state: TokenState;
+    deleted: string[];
+};
+/** Deletes a collection and its variables (aliases into it are detached to their values). */
+declare function deleteTokenCollection(state: TokenState, id: string): {
+    state: TokenState;
+    deleted: string[];
+};
+/**
+ * Adds a mode. Variables start with the values of mode `from` (default: the default mode).
+ */
+declare function addTokenMode(state: TokenState, collectionId: string, name: string, options?: {
+    from?: string;
+}, createId?: TokenIdFactory): {
+    state: TokenState;
+    mode: TokenMode;
+};
+declare function renameTokenMode(state: TokenState, collectionId: string, modeId: string, name: string): TokenState;
+/** Removes a mode and its values; a collection keeps at least one mode. */
+declare function removeTokenMode(state: TokenState, collectionId: string, modeId: string): TokenState;
+/** Moves a mode to index `to` (clamped). Index 0 makes it the default mode. */
+declare function moveTokenMode(state: TokenState, collectionId: string, modeId: string, to: number): TokenState;
+interface CreateTokenVariableInput {
+    collectionId: string;
+    name: string;
+    type: TokenType;
+    /** Value for every mode (literal or `{ alias }`). Default: the type's default. */
+    value?: unknown;
+    /** Values by mode id or name (win over `value`). */
+    values?: Readonly<Record<string, unknown>>;
+    description?: string;
+    scopes?: readonly string[];
+    unit?: string;
+}
+/** A value for `variable`: a normalised literal or a checked alias. Throws when refused. */
+declare function prepareTokenValue(state: TokenState, variable: Pick<TokenVariable, 'id' | 'type' | 'name'>, value: unknown): TokenValue;
+declare function createTokenVariable(state: TokenState, input: CreateTokenVariableInput, createId?: TokenIdFactory): {
+    state: TokenState;
+    variable: TokenVariable;
+};
+/**
+ * Sets a variable's value in one mode (id or name; default: the default mode) to a literal or
+ * `{ alias: variableId }`. Aliases must keep the type and not create a cycle.
+ */
+declare function setTokenValue(state: TokenState, variableId: string, value: unknown, modeId?: string): TokenState;
+declare function renameTokenVariable(state: TokenState, variableId: string, name: string): TokenState;
+interface UpdateTokenVariableInput {
+    description?: string;
+    /** `null` clears the limit (every property). */
+    scopes?: readonly string[] | null;
+    /** `null` clears the unit. */
+    unit?: string | null;
+}
+declare function updateTokenVariable(state: TokenState, variableId: string, input: UpdateTokenVariableInput): TokenState;
+interface TokenStateIssue {
+    message: string;
+    collectionId?: string;
+    variableId?: string;
+}
+/**
+ * Reads untrusted data (e.g. a saved `TokenState`) and keeps what is valid: junk collections,
+ * modes and variables are dropped, bad values replaced by the type's default and alias cycles
+ * broken, each with an issue.
+ */
+declare function parseTokenState(input: unknown): {
+    state: TokenState;
+    issues: TokenStateIssue[];
+};
+
+export { resolveToken as $, deleteTokenCollection as A, deleteTokenVariables as B, type CreateTokenVariableInput as C, findTokenCollection as D, EMPTY_TOKEN_STATE as E, findTokenMode as F, findTokenVariable as G, formatTokenValue as H, getCollectionVariables as I, getCurrentMode as J, getDefaultMode as K, getTokenCollection as L, getTokenVariable as M, isTokenAlias as N, isTokenInScope as O, isTokenScopeKnown as P, literalTokenType as Q, moveTokenMode as R, normalizeTokenName as S, type TokenState as T, type UpdateTokenVariableInput as U, normalizeTokenScopes as V, prepareTokenValue as W, removeTokenMode as X, renameTokenCollection as Y, renameTokenMode as Z, renameTokenVariable as _, type TokenIdFactory as a, resolveTokenInMode as a0, resolveTokenValue as a1, setTokenValue as a2, updateTokenVariable as a3, type TokenCollection as b, type TokenVariable as c, type TokenModeContext as d, type TokenResolution as e, type TokenLiteral as f, type TokenMode as g, type CreateTokenCollectionInput as h, TOKEN_SCOPES_BY_TYPE as i, TOKEN_TYPES as j, type TokenAlias as k, TokenError as l, type TokenErrorCode as m, type TokenResolutionErrorCode as n, type TokenScope as o, parseTokenState as p, type TokenStateIssue as q, type TokenType as r, type TokenValue as s, addTokenMode as t, checkTokenAlias as u, coerceTokenLiteral as v, createTokenCollection as w, createTokenVariable as x, defaultTokenId as y, defaultTokenValue as z };