routegraph 0.0.0-stage → 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,793 @@
+/** Core shared types for AppNav. Everything here is plain data and JSON friendly. */
+type JsonPrimitive = string | number | boolean | null;
+type JsonValue = JsonPrimitive | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+type JsonObject = {
+    [key: string]: JsonValue;
+};
+type VariableType = "string" | "number" | "boolean" | "null" | "object" | "array" | "any";
+declare const VARIABLE_TYPES: readonly VariableType[];
+type DiagnosticSeverity = "error" | "warning";
+interface Diagnostic {
+    severity: DiagnosticSeverity;
+    code: string;
+    message: string;
+    file?: string;
+    line?: number;
+    column?: number;
+    /** Screen, edge, variable or action identifiers involved. */
+    ids?: string[];
+}
+/**
+ * Payload shapes for the built in actions. This is a convenience for typed
+ * narrowing (see `isAction`). Custom schemas can supply their own map through
+ * the generic parameter of `isAction`.
+ */
+interface DefaultActionMap {
+    TAP: {
+        target: string;
+        waitFor?: string;
+        timeoutMs?: number;
+        match?: JsonObject;
+        index?: number;
+    };
+    LONG_PRESS: {
+        target: string;
+        durationMs?: number;
+    };
+    TYPE: {
+        target: string;
+        text: string;
+        clearFirst?: boolean;
+    };
+    SWIPE: {
+        direction: "up" | "down" | "left" | "right";
+        target?: string;
+        distance?: number;
+    };
+    SCROLL: {
+        target?: string;
+        to?: string;
+        direction?: "up" | "down" | "left" | "right";
+    };
+    BACK: Record<string, never>;
+    WAIT: {
+        until?: string;
+        durationMs?: number;
+        timeoutMs?: number;
+    };
+    SET_STATE: {
+        key: string;
+        value: JsonValue;
+    };
+    ASSERT: {
+        condition: string;
+        message?: string;
+    };
+}
+/** Any object whose keys are action types and whose values are payload shapes. */
+type ActionMap = {
+    [type: string]: object;
+};
+interface Screen {
+    readonly id: string;
+    readonly name: string;
+    readonly meta: JsonObject;
+    /** Declaration order, used for deterministic tie breaking. */
+    readonly index: number;
+}
+interface ActionDeclaration {
+    readonly type: string;
+    readonly data: JsonObject;
+    readonly line?: number;
+    readonly column?: number;
+}
+interface Condition {
+    readonly source: string;
+    readonly ast: ConditionNode;
+}
+type ConditionNode = {
+    type: "literal";
+    value: JsonValue;
+} | {
+    type: "ref";
+    path: string[];
+} | {
+    type: "not";
+    arg: ConditionNode;
+} | {
+    type: "and";
+    left: ConditionNode;
+    right: ConditionNode;
+} | {
+    type: "or";
+    left: ConditionNode;
+    right: ConditionNode;
+} | {
+    type: "compare";
+    op: string;
+    left: ConditionNode;
+    right: ConditionNode;
+};
+interface Edge {
+    readonly id: string;
+    readonly from: string;
+    readonly to: string;
+    readonly cost: number;
+    readonly condition?: Condition;
+    readonly actions: readonly ActionDeclaration[];
+    readonly meta: JsonObject;
+    /** Declaration order, used for deterministic tie breaking. */
+    readonly index: number;
+    readonly line?: number;
+    readonly column?: number;
+}
+interface VariableDeclaration {
+    readonly name: string;
+    readonly type: VariableType;
+    readonly hasDefault: boolean;
+    readonly default?: JsonValue;
+    readonly line?: number;
+    readonly column?: number;
+}
+/** Parsed but unvalidated edge as written in the source. */
+interface RawEdge {
+    id?: string;
+    from: string;
+    to: string;
+    cost?: number;
+    condition?: string;
+    actions: ActionDeclaration[];
+    meta: JsonObject;
+    line: number;
+    column: number;
+}
+interface RawScreen {
+    id: string;
+    name: string;
+    meta: JsonObject;
+    line: number;
+    column: number;
+}
+/** Intermediate representation produced by `parseGraph`. */
+interface Graph {
+    version: number;
+    app?: string;
+    file?: string;
+    variables: VariableDeclaration[];
+    screens: RawScreen[];
+    edges: RawEdge[];
+    hasEnd: boolean;
+}
+type ReadFile = (path: string) => Promise<string>;
+
+interface ErrorLocation {
+    file?: string;
+    line?: number;
+    column?: number;
+    ids?: string[];
+}
+/** Base class for every error thrown by AppNav. */
+declare class AppNavError extends Error {
+    readonly code: string;
+    readonly file?: string;
+    readonly line?: number;
+    readonly column?: number;
+    readonly ids?: string[];
+    readonly cause?: unknown;
+    constructor(code: string, message: string, location?: ErrorLocation, cause?: unknown);
+}
+declare class ParseError extends AppNavError {
+    constructor(message: string, location?: ErrorLocation, code?: string);
+}
+declare class UnsupportedVersionError extends AppNavError {
+    constructor(version: string | number, location?: ErrorLocation);
+}
+declare class ValidationError extends AppNavError {
+    readonly diagnostics: Diagnostic[];
+    constructor(diagnostics: Diagnostic[], file?: string);
+}
+declare class SchemaError extends AppNavError {
+    constructor(message: string, ids?: string[]);
+}
+declare class VariableError extends AppNavError {
+    constructor(message: string, location?: ErrorLocation, code?: string);
+}
+declare class ConditionError extends AppNavError {
+    constructor(message: string, location?: ErrorLocation, code?: string);
+}
+declare class UnknownScreenError extends AppNavError {
+    constructor(id: string);
+}
+declare class NoPathError extends AppNavError {
+    readonly from: string;
+    readonly to: string;
+    constructor(from: string, to: string, algorithm: string);
+}
+declare class ExtensionError extends AppNavError {
+    readonly extension: string;
+    constructor(extension: string, message: string, cause?: unknown, ids?: string[]);
+}
+/** Thrown by the synchronous builders when an extension returns a promise. */
+declare class AsyncExtensionError extends AppNavError {
+    constructor(what: string);
+}
+declare class ActionHandlerError extends AppNavError {
+    constructor(code: string, message: string, ids?: string[], cause?: unknown);
+}
+declare class FileLoadError extends AppNavError {
+    constructor(message: string, path?: string, cause?: unknown);
+}
+declare function toDiagnostic(err: AppNavError, severity?: "error" | "warning"): Diagnostic;
+
+declare const SUPPORTED_GRAPH_VERSIONS: readonly number[];
+interface ParseOptions {
+    /** File name used in error messages. */
+    file?: string;
+    /** Override the accepted NAVGRAPH versions. */
+    supportedVersions?: readonly number[];
+}
+/**
+ * Parse `.navgraph` source text into a Graph. This performs syntax checks only;
+ * run `validateGraph` (or `indexGraph`) for semantic checks.
+ *
+ * Grammar summary:
+ *   document  := "NAVGRAPH/" int item* ["END"]
+ *   item      := app | var | screen | edge
+ *   app       := "APP" string
+ *   var       := "VAR" NAME ":" type ["=" json]
+ *   screen    := "SCREEN" id string [json-object]
+ *   edge      := id "->" id ["[" attr ("," attr)* "]"] ["{" action* "}"]
+ *   action    := "DO" TYPE [json-object]
+ * Comments start with # and run to the end of the line. Whitespace between
+ * tokens is insignificant except that VAR, SCREEN and APP end at a line break.
+ */
+declare function parseGraph(text: string, options?: ParseOptions): Graph;
+
+/**
+ * Safe condition language. No eval, no JS.
+ *
+ *   expr    := or
+ *   or      := and (("||" | "or") and)*
+ *   and     := not (("&&" | "and") not)*
+ *   not     := ("!" | "not") not | compare
+ *   compare := primary [op primary]      op: == != < <= > >= or a word operator
+ *   primary := string | number | true | false | null | path | "(" expr ")"
+ *   path    := ident ("." ident)*
+ *
+ * Unknown values: a path that resolves to nothing is `undefined`. Undefined is
+ * falsy, every comparison with undefined is false except "!=" which is true.
+ * Set `strict` to throw instead.
+ */
+type ConditionOperator = (left: JsonValue | undefined, right: JsonValue | undefined) => boolean;
+interface ConditionContext {
+    variables?: Readonly<Record<string, JsonValue>>;
+    state?: Readonly<Record<string, unknown>>;
+}
+interface ConditionOptions {
+    /** Extra word operators, e.g. { startsWith: (a, b) => ... }. */
+    operators?: Readonly<Record<string, ConditionOperator>>;
+    /** Throw on unknown paths instead of treating them as undefined. */
+    strict?: boolean;
+}
+declare const BUILTIN_OPERATORS: Readonly<Record<string, ConditionOperator>>;
+/** Parse a condition expression into an AST. Throws ConditionError on bad syntax. */
+declare function parseCondition(source: string): Condition;
+/** All paths referenced by a condition, as dotted strings. */
+declare function conditionRefs(node: ConditionNode, out?: string[]): string[];
+/** Evaluate a parsed condition against a context. */
+declare function evaluateCondition(condition: Condition | ConditionNode, ctx?: ConditionContext, options?: ConditionOptions): boolean;
+
+type VariableScope = Readonly<Record<string, JsonValue>>;
+interface ScopeInputs {
+    /** Route inputs. Override graph defaults. */
+    variables?: Readonly<Record<string, JsonValue>>;
+    /** Runtime values discovered during execution. Override route inputs. */
+    runtime?: Readonly<Record<string, JsonValue>>;
+    /** When true, values for undeclared variables are rejected. */
+    strict?: boolean;
+}
+type Segment = {
+    kind: "text";
+    value: string;
+} | {
+    kind: "var";
+    name: string;
+};
+/**
+ * Tokenise a template string. `$NAME$` is a reference, `$$` is a literal `$`.
+ * A lone `$` that does not form a reference is kept as text.
+ */
+declare function parseTemplate(input: string): Segment[];
+/** Names of all variables referenced anywhere inside a JSON value (strings only, not keys). */
+declare function collectReferences(value: JsonValue, out?: Set<string>): Set<string>;
+declare function typeOfValue(v: unknown): VariableType;
+declare function matchesType(v: unknown, type: VariableType): boolean;
+/**
+ * Build the effective variable scope.
+ * Precedence, lowest to highest: graph defaults, route inputs, runtime values.
+ * Every supplied value for a declared variable is type checked.
+ */
+declare function buildScope(declarations: Readonly<Record<string, VariableDeclaration>>, inputs?: ScopeInputs): VariableScope;
+/** Resolve `$VAR$` references inside a JSON value. Returns a new value; the input is untouched. */
+declare function resolveValue(value: JsonValue, scope: VariableScope, declarations?: Readonly<Record<string, VariableDeclaration>>, where?: {
+    ids?: string[];
+}): JsonValue;
+
+type PropertyType = "string" | "number" | "integer" | "boolean" | "null" | "object" | "array" | "any";
+interface PropertySchema {
+    type?: PropertyType | PropertyType[];
+    description?: string;
+    enum?: JsonValue[];
+    minimum?: number;
+    maximum?: number;
+    /** For objects. */
+    required?: string[];
+    properties?: Record<string, PropertySchema>;
+    additionalProperties?: boolean | PropertySchema;
+    /** For arrays. */
+    items?: PropertySchema;
+}
+interface ActionDefinition extends PropertySchema {
+    description?: string;
+}
+interface SchemaDefinition {
+    $schema?: string;
+    schemaVersion: 1;
+    name?: string;
+    /** "default", the name of a registered schema, or a file path when using loadSchema(). */
+    extends?: string;
+    /** Inherited action names this schema intentionally redefines. */
+    overrides?: string[];
+    /** Inherited action names this schema intentionally removes. */
+    remove?: string[];
+    actions?: Record<string, ActionDefinition>;
+    /** Validation for custom edge attributes such as [label="x"]. */
+    edgeMetadata?: Record<string, PropertySchema>;
+    /** Validation for SCREEN metadata objects. */
+    screenMetadata?: Record<string, PropertySchema>;
+}
+interface ResolvedSchema {
+    readonly schemaVersion: 1;
+    readonly name: string;
+    readonly actions: Readonly<Record<string, ActionDefinition>>;
+    readonly edgeMetadata: Readonly<Record<string, PropertySchema>>;
+    readonly screenMetadata: Readonly<Record<string, PropertySchema>>;
+}
+declare const DEFAULT_SCHEMA_DEFINITION: SchemaDefinition;
+/** Resolve a schema definition, applying `extends`. Synchronous; `extends` must be "default" or registered. */
+declare function resolveSchema(def: SchemaDefinition, parent?: ResolvedSchema): ResolvedSchema;
+declare function getDefaultSchema(): ResolvedSchema;
+/** Register a named schema so other schemas can `extends` it. */
+declare function registerSchema(name: string, schema: SchemaDefinition | ResolvedSchema): ResolvedSchema;
+declare function unregisterSchema(name: string): boolean;
+interface LoadSchemaOptions {
+    readFile?: ReadFile;
+}
+/**
+ * Load a schema. Accepts nothing (the default schema), a definition object, an
+ * already resolved schema, or a file path (JSON). File based `extends` chains work.
+ */
+declare function loadSchema(input?: string | SchemaDefinition | ResolvedSchema, options?: LoadSchemaOptions): Promise<ResolvedSchema>;
+interface ValidationContext {
+    declarations?: Readonly<Record<string, VariableDeclaration>>;
+}
+/**
+ * Validate a JSON value against a PropertySchema. Strings that are exactly one
+ * `$VAR$` reference are checked against the variable's declared type instead of
+ * the string value. Returns a list of human readable problems.
+ */
+declare function validateAgainst(value: unknown, schema: PropertySchema, path: string, ctx?: ValidationContext): string[];
+
+/**
+ * Default file reader. Uses Node's built in fs when it is available and
+ * otherwise explains how to supply a reader. React Native has no filesystem
+ * access by default, so pass `readFile` (for example from expo-file-system or
+ * react-native-fs) or use the in-memory APIs such as `indexTreeFromText`.
+ */
+declare const defaultReadFile: ReadFile;
+
+interface ValidateOptions {
+    /** Require condition identifiers to be declared VARs. Default false (unknown names are looked up in app state). */
+    strictConditions?: boolean;
+    /** Allow `$NAME$` references to variables that are not declared. Default false. */
+    allowUndeclaredVariables?: boolean;
+    /** Extra word operators permitted in conditions. */
+    conditionOperators?: Readonly<Record<string, ConditionOperator>>;
+}
+interface ValidationResult {
+    ok: boolean;
+    errors: Diagnostic[];
+    warnings: Diagnostic[];
+    diagnostics: Diagnostic[];
+}
+/** Semantic validation of a parsed graph. Never throws for graph problems. */
+declare function validateGraph(graph: Graph, schema?: SchemaDefinition | ResolvedSchema, options?: ValidateOptions): ValidationResult;
+/** Throws a ValidationError when the result has errors. */
+declare function assertValid(result: ValidationResult, file?: string): void;
+interface IndexOptions extends ParseOptions, ValidateOptions {
+    /** A schema object, or a resolved schema. For file paths use indexTree(). */
+    schema?: SchemaDefinition | ResolvedSchema;
+    /** Cost applied to edges that do not declare one. Default 1. */
+    defaultCost?: number;
+    /** "throw" (default) raises ValidationError. "collect" keeps going and records tree.diagnostics. */
+    diagnostics?: "throw" | "collect";
+}
+interface IndexFileOptions extends Omit<IndexOptions, "schema"> {
+    /** Schema object, resolved schema, or path to a .navschema JSON file. */
+    schema?: string | SchemaDefinition | ResolvedSchema;
+    /** Custom file reader. Required in runtimes without Node's fs (React Native). */
+    readFile?: ReadFile;
+}
+/** Methods and data shared by every tree. */
+declare class NavigationTree {
+    readonly app?: string;
+    readonly version: number;
+    readonly file?: string;
+    readonly schema: ResolvedSchema;
+    readonly variables: Readonly<Record<string, VariableDeclaration>>;
+    readonly screens: ReadonlyMap<string, Screen>;
+    readonly edges: readonly Edge[];
+    readonly diagnostics: readonly Diagnostic[];
+    private readonly adjacency;
+    private readonly reverse;
+    constructor(parts: {
+        app?: string;
+        version: number;
+        file?: string;
+        schema: ResolvedSchema;
+        variables: Record<string, VariableDeclaration>;
+        screens: Map<string, Screen>;
+        edges: Edge[];
+        diagnostics: Diagnostic[];
+    });
+    /** Authoritative lookup. Throws UnknownScreenError when missing. */
+    screen(id: string): Screen;
+    hasScreen(id: string): boolean;
+    /** Edges leaving a screen, in declaration order. */
+    outgoing(id: string): readonly Edge[];
+    incoming(id: string): readonly Edge[];
+    edge(id: string): Edge | undefined;
+    /** Plain JSON snapshot of the graph. */
+    toJSON(): JsonObject;
+}
+type Reserved = keyof NavigationTree;
+/**
+ * A tree plus `tree.<screenId>` shortcuts. Provide the ids as a type argument
+ * for typed shortcuts: `indexTree<"home" | "cart">(...)`. Without a type
+ * argument only the core API is typed; use `tree.screen("id")`.
+ */
+type NavTree<Id extends string = string> = NavigationTree & (string extends Id ? unknown : {
+    readonly [K in Exclude<Id, Reserved | "constructor" | "__proto__">]: Screen;
+});
+declare function indexGraph<Id extends string = string>(graph: Graph, options?: IndexOptions): NavTree<Id>;
+/** Synchronous: parse, validate and index graph text that is already in memory. */
+declare function indexTreeFromText<Id extends string = string>(text: string, options?: IndexOptions): NavTree<Id>;
+/** Async: read a .navgraph file (and optional schema file), then parse, validate and index it. */
+declare function indexTree<Id extends string = string>(path: string, options?: IndexFileOptions): Promise<NavTree<Id>>;
+
+declare const ASTAR: "astar";
+declare const DIJKSTRA: "dijkstra";
+declare const BFS: "bfs";
+type BuiltinAlgorithm = typeof ASTAR | typeof DIJKSTRA | typeof BFS;
+type Heuristic = (from: Screen, goal: Screen, tree: NavigationTree) => number;
+interface SearchContext {
+    readonly tree: NavigationTree;
+    readonly start: Screen;
+    readonly goal: Screen;
+    /** Traversable edges leaving a screen, already filtered by conditions, in declaration order. */
+    neighbors(screen: Screen): readonly Edge[];
+    /** Validated edge cost. */
+    cost(edge: Edge): number;
+    heuristic(screen: Screen): number;
+}
+interface SearchResult {
+    edges: Edge[];
+    cost: number;
+    visited: number;
+}
+/** A pathfinding algorithm. Return undefined when the goal is unreachable. */
+type PathfindingAlgorithm = (ctx: SearchContext) => SearchResult | undefined;
+type AlgorithmRef = BuiltinAlgorithm | (string & {}) | PathfindingAlgorithm;
+interface PathOptions {
+    /** Route input variables. Used for condition evaluation and stored on the path. */
+    variables?: Readonly<Record<string, JsonValue>>;
+    /** Runtime values. Override route inputs. */
+    runtime?: Readonly<Record<string, JsonValue>>;
+    /** Application state looked up by conditions when a name is not a variable. */
+    state?: Readonly<Record<string, unknown>>;
+    /** Heuristic for A*. Must be admissible for optimal routes. Default 0. */
+    heuristic?: Heuristic;
+    /** Override the cost of an edge, for example to penalise risky transitions. Must return a finite number >= 0. */
+    costFn?: (edge: Edge) => number;
+    /** Extra veto on edges. Return false to exclude an edge. */
+    edgeFilter?: (edge: Edge) => boolean;
+    /** Extra word operators for conditions. */
+    conditionOperators?: Readonly<Record<string, ConditionOperator>>;
+    /** Throw when a condition refers to an unknown value. Default false. */
+    strictConditions?: boolean;
+    /** Reject route variables that are not declared in the graph. */
+    strictVariables?: boolean;
+}
+interface Path {
+    readonly from: string;
+    readonly to: string;
+    /** Screen ids in order, including both ends. */
+    readonly screens: string[];
+    readonly edges: Edge[];
+    readonly cost: number;
+    readonly algorithm: string;
+    /** Number of nodes expanded by the search. */
+    readonly visited: number;
+    /** Route variables supplied to calculatePath. */
+    readonly variables: Record<string, JsonValue>;
+    /** Owning tree (not enumerable, so JSON.stringify(path) stays clean). */
+    readonly tree: NavigationTree;
+}
+type PathResult = {
+    ok: true;
+    path: Path;
+} | {
+    ok: false;
+    error: NoPathError;
+};
+/** Register a custom algorithm so it can be selected by name. */
+declare function registerAlgorithm(name: string, fn: PathfindingAlgorithm): void;
+/**
+ * Compute a route between two screens without throwing for "no route".
+ * Unknown screens and invalid options still throw.
+ */
+declare function tryCalculatePath(tree: NavigationTree, start: string | Screen, end: string | Screen, algorithm?: AlgorithmRef, options?: PathOptions): PathResult;
+/** Compute a route. Throws NoPathError when the destination is unreachable. */
+declare function calculatePath(tree: NavigationTree, start: string | Screen, end: string | Screen, algorithm?: AlgorithmRef, options?: PathOptions): Path;
+/** Ids of every screen reachable from `start` under the given conditions (BFS). */
+declare function findReachable(tree: NavigationTree, start: string | Screen, options?: PathOptions): string[];
+
+type MaybePromise<T> = T | PromiseLike<T>;
+type HookResult<Out> = Out | void | undefined;
+type Hook<Ctx, Out> = (ctx: Ctx) => MaybePromise<HookResult<Out>>;
+interface BaseContext<V extends JsonObject> {
+    /** Extension name. */
+    readonly name: string;
+    /** Extension local configuration merged with per build overrides. */
+    readonly variables: Readonly<V>;
+    /** Resolved route variables (graph defaults, route inputs, runtime). */
+    readonly routeVariables: Readonly<Record<string, JsonValue>>;
+    readonly tree: NavigationTree;
+    readonly path: Path;
+    /** Outputs of extensions listed in `dependsOn`, for this same node. */
+    readonly outputs: Readonly<Record<string, JsonValue>>;
+}
+interface ActionContext<V extends JsonObject = JsonObject> extends BaseContext<V> {
+    readonly action: Readonly<InstructionAction>;
+    readonly actionIndex: number;
+    readonly step: Readonly<InstructionStep>;
+    readonly edge: Edge;
+    readonly from: Screen;
+    readonly to: Screen;
+}
+interface StepContext<V extends JsonObject = JsonObject> extends BaseContext<V> {
+    /** The step with action level extension output already attached. */
+    readonly step: Readonly<InstructionStep>;
+    readonly edge: Edge;
+    readonly from: Screen;
+    readonly to: Screen;
+}
+interface RouteContext<V extends JsonObject = JsonObject> extends BaseContext<V> {
+    /** The full instruction tree with action and step output already attached. */
+    readonly instructions: Readonly<Instructions>;
+    readonly from: Screen;
+    readonly to: Screen;
+}
+interface ExtensionDefinition<N extends string = string, Out extends JsonValue = JsonValue, V extends JsonObject = JsonObject> {
+    name: N;
+    /** Local configuration. Never mutates graph or route variables. */
+    variables?: V;
+    /** Names of extensions whose output for the same node this one reads via `ctx.outputs`. */
+    dependsOn?: readonly string[];
+    /** Shorthand for `action`. Called once per action. */
+    run?: Hook<ActionContext<V>, Out>;
+    action?: Hook<ActionContext<V>, Out>;
+    /** Called once per screen to screen transition, after its actions. */
+    step?: Hook<StepContext<V>, Out>;
+    /** Called once after every step has been built. */
+    route?: Hook<RouteContext<V>, Out>;
+    /** Optional output check. Return true, or a string describing the problem. */
+    validate?: (output: Out) => boolean | string;
+}
+/** Definition without a name, for the inline object form. */
+type InlineExtension<Out extends JsonValue = JsonValue, V extends JsonObject = JsonObject> = Omit<ExtensionDefinition<string, Out, V>, "name">;
+declare const OUTPUT: unique symbol;
+interface Extension<N extends string = string, Out extends JsonValue = JsonValue, V extends JsonObject = JsonObject> {
+    readonly name: N;
+    readonly variables: Readonly<V>;
+    readonly dependsOn: readonly string[];
+    readonly hooks: {
+        readonly action?: Hook<ActionContext<V>, Out>;
+        readonly step?: Hook<StepContext<V>, Out>;
+        readonly route?: Hook<RouteContext<V>, Out>;
+    };
+    readonly validate?: (output: Out) => boolean | string;
+    /** Type only marker used by `getExtensionOutput`. */
+    readonly [OUTPUT]?: Out;
+}
+type AnyExtension = Extension<any, any, any>;
+type OutputOf<E> = E extends Extension<any, infer O, any> ? O : never;
+type NameOf<E> = E extends Extension<infer N, any, any> ? N : never;
+/** Hooks that return nothing infer `never`; treat that as "any JSON value". */
+type OutputOrJson<Out> = [Out] extends [never] ? JsonValue : Out;
+type ExtensionsInput = readonly AnyExtension[] | Readonly<Record<string, InlineExtension<JsonValue, JsonObject>>>;
+/** Validate and create a reusable extension definition. */
+declare function defineExtension<N extends string, Out extends JsonValue = JsonValue, V extends JsonObject = JsonObject>(definition: ExtensionDefinition<N, Out, V>): Extension<N, OutputOrJson<Out>, V>;
+/** Normalise the array or inline-object forms into an ordered, dependency sorted list. */
+declare function normalizeExtensions(input: ExtensionsInput | undefined): AnyExtension[];
+/** Typed read of an extension's output from any node (action, step or the route). */
+declare function getExtensionOutput<E extends AnyExtension>(node: {
+    readonly extensions: Readonly<Record<string, JsonValue>>;
+}, extension: E): OutputOf<E> | undefined;
+
+interface InstructionAction<T extends string = string, D extends JsonObject = JsonObject> {
+    type: T;
+    /** Resolved payload, with all `$VAR$` references substituted. */
+    data: D;
+    /** Extension output, keyed by extension name. */
+    extensions: Record<string, JsonValue>;
+    /** Original payload before substitution. Only present with `includeUnresolved`. */
+    unresolved?: JsonObject;
+}
+interface InstructionStep {
+    n: number;
+    from: string;
+    to: string;
+    /** Id of the graph edge this step traverses. */
+    edge: string;
+    cost: number;
+    actions: InstructionAction[];
+    extensions: Record<string, JsonValue>;
+}
+interface Instructions {
+    from: string;
+    to: string;
+    path: string[];
+    steps: InstructionStep[];
+    cost: number;
+    /** Route level extension output. */
+    extensions: Record<string, JsonValue>;
+    meta: {
+        app?: string;
+        algorithm: string;
+        generator: string;
+    };
+    /** Present only when `onError: "collect"` swallowed extension failures. */
+    warnings?: Diagnostic[];
+}
+interface BuildOptions {
+    /** Route inputs. Override graph defaults and anything stored on the path. */
+    variables?: Readonly<Record<string, JsonValue>>;
+    /** Runtime values. Override route inputs. */
+    runtime?: Readonly<Record<string, JsonValue>>;
+    /** Extensions as an array of defineExtension() results, or an inline map keyed by name. */
+    extensions?: ExtensionsInput;
+    /** Per extension configuration overrides, keyed by extension name. */
+    extensionVariables?: Readonly<Record<string, JsonObject>>;
+    /** "throw" (default) fails on the first extension error. "collect" records warnings and continues. */
+    onError?: "throw" | "collect";
+    /** Keep the original unresolved payload on each action as `unresolved`. */
+    includeUnresolved?: boolean;
+    /** Reject route variables that are not declared in the graph. */
+    strictVariables?: boolean;
+}
+/**
+ * Build the instruction tree. Always returns a promise and awaits async
+ * extension hooks. Use `buildInstructionsSync` when every hook is synchronous.
+ */
+declare function buildInstructions(path: Path, options?: BuildOptions): Promise<Instructions>;
+/**
+ * Synchronous variant. Throws AsyncExtensionError if any hook returns a promise.
+ */
+declare function buildInstructionsSync(path: Path, options?: BuildOptions): Instructions;
+/**
+ * Narrow an action to a known type with a typed payload. Works with the
+ * built in actions out of the box; pass your own map as the first type
+ * argument for custom actions: `isAction<MyActions, "SCAN_QR">(a, "SCAN_QR")`.
+ */
+declare function isAction<M extends object = DefaultActionMap, K extends keyof M & string = keyof M & string>(action: InstructionAction, type: K): action is InstructionAction<K, M[K] & JsonObject>;
+
+/**
+ * Optional, opt-in execution layer. AppNav core never runs actions. Register
+ * handlers explicitly by action type and pass generated instructions in.
+ */
+interface HandlerContext<Ctx = unknown> {
+    readonly action: Readonly<InstructionAction>;
+    readonly step: Readonly<InstructionStep>;
+    readonly instructions: Readonly<Instructions>;
+    /** Caller supplied runtime context (navigation ref, driver, test harness, ...). */
+    readonly context: Ctx;
+    readonly attempt: number;
+    readonly signal?: AbortSignal;
+}
+type ActionHandler<Ctx = unknown, R = unknown> = (ctx: HandlerContext<Ctx>) => R | PromiseLike<R>;
+interface HandlerOptions {
+    /** Async execution only. Fails the attempt after this many milliseconds. */
+    timeoutMs?: number;
+    /** Extra attempts after the first failure. Default 0. */
+    retries?: number;
+    /** Async execution only. Delay between attempts. Default 0. */
+    retryDelayMs?: number;
+}
+interface ExecuteOptions<Ctx = unknown> {
+    context?: Ctx;
+    /** Keep running after a failed action. Default false. */
+    continueOnError?: boolean;
+    /** Skip actions without a handler instead of failing. Default false. */
+    skipUnhandled?: boolean;
+    signal?: AbortSignal;
+    onAction?: (result: ActionResult, step: InstructionStep) => void;
+}
+interface ActionResult {
+    stepN: number;
+    actionIndex: number;
+    type: string;
+    status: "ok" | "error" | "skipped";
+    value?: unknown;
+    error?: unknown;
+    attempts: number;
+}
+interface ExecutionResult {
+    ok: boolean;
+    results: ActionResult[];
+}
+declare class Runtime<Ctx = unknown> {
+    private readonly handlers;
+    register<T extends string = string>(type: T, handler: ActionHandler<Ctx>, options?: HandlerOptions): this;
+    unregister(type: string): boolean;
+    has(type: string): boolean;
+    /** Run instructions. Awaits async handlers and honours timeouts, retries and abort signals. */
+    execute(instructions: Instructions, options?: ExecuteOptions<Ctx>): Promise<ExecutionResult>;
+    /** Run instructions with synchronous handlers only. Throws AsyncExtensionError if a handler returns a promise. */
+    executeSync(instructions: Instructions, options?: ExecuteOptions<Ctx>): ExecutionResult;
+    private job;
+}
+declare function createRuntime<Ctx = unknown>(handlers?: Record<string, ActionHandler<Ctx> | {
+    handler: ActionHandler<Ctx>;
+    options?: HandlerOptions;
+}>): Runtime<Ctx>;
+/** Shared runtime used by `registerActionHandler` for apps that prefer a global registry. */
+declare const defaultRuntime: Runtime<unknown>;
+declare function registerActionHandler<T extends string = string>(type: T, handler: ActionHandler<unknown>, options?: HandlerOptions): void;
+
+declare const AppNavNamespace_ASTAR: typeof ASTAR;
+declare const AppNavNamespace_BFS: typeof BFS;
+declare const AppNavNamespace_DIJKSTRA: typeof DIJKSTRA;
+declare const AppNavNamespace_assertValid: typeof assertValid;
+declare const AppNavNamespace_buildInstructions: typeof buildInstructions;
+declare const AppNavNamespace_buildInstructionsSync: typeof buildInstructionsSync;
+declare const AppNavNamespace_calculatePath: typeof calculatePath;
+declare const AppNavNamespace_createRuntime: typeof createRuntime;
+declare const AppNavNamespace_defineExtension: typeof defineExtension;
+declare const AppNavNamespace_evaluateCondition: typeof evaluateCondition;
+declare const AppNavNamespace_findReachable: typeof findReachable;
+declare const AppNavNamespace_getExtensionOutput: typeof getExtensionOutput;
+declare const AppNavNamespace_indexGraph: typeof indexGraph;
+declare const AppNavNamespace_indexTree: typeof indexTree;
+declare const AppNavNamespace_indexTreeFromText: typeof indexTreeFromText;
+declare const AppNavNamespace_isAction: typeof isAction;
+declare const AppNavNamespace_loadSchema: typeof loadSchema;
+declare const AppNavNamespace_parseCondition: typeof parseCondition;
+declare const AppNavNamespace_parseGraph: typeof parseGraph;
+declare const AppNavNamespace_registerActionHandler: typeof registerActionHandler;
+declare const AppNavNamespace_registerAlgorithm: typeof registerAlgorithm;
+declare const AppNavNamespace_registerSchema: typeof registerSchema;
+declare const AppNavNamespace_resolveSchema: typeof resolveSchema;
+declare const AppNavNamespace_tryCalculatePath: typeof tryCalculatePath;
+declare const AppNavNamespace_validateGraph: typeof validateGraph;
+declare namespace AppNavNamespace {
+  export { AppNavNamespace_ASTAR as ASTAR, AppNavNamespace_BFS as BFS, AppNavNamespace_DIJKSTRA as DIJKSTRA, AppNavNamespace_assertValid as assertValid, AppNavNamespace_buildInstructions as buildInstructions, AppNavNamespace_buildInstructionsSync as buildInstructionsSync, AppNavNamespace_calculatePath as calculatePath, AppNavNamespace_createRuntime as createRuntime, AppNavNamespace_defineExtension as defineExtension, AppNavNamespace_evaluateCondition as evaluateCondition, AppNavNamespace_findReachable as findReachable, AppNavNamespace_getExtensionOutput as getExtensionOutput, AppNavNamespace_indexGraph as indexGraph, AppNavNamespace_indexTree as indexTree, AppNavNamespace_indexTreeFromText as indexTreeFromText, AppNavNamespace_isAction as isAction, AppNavNamespace_loadSchema as loadSchema, AppNavNamespace_parseCondition as parseCondition, AppNavNamespace_parseGraph as parseGraph, AppNavNamespace_registerActionHandler as registerActionHandler, AppNavNamespace_registerAlgorithm as registerAlgorithm, AppNavNamespace_registerSchema as registerSchema, AppNavNamespace_resolveSchema as resolveSchema, AppNavNamespace_tryCalculatePath as tryCalculatePath, AppNavNamespace_validateGraph as validateGraph };
+}
+
+/** Namespace object for `import { AppNav } from "routegraph"`. */
+declare const AppNav: typeof AppNavNamespace;
+declare const VERSION = "0.1.0";
+
+export { ASTAR, type ActionContext, type ActionDeclaration, type ActionDefinition, type ActionHandler, ActionHandlerError, type ActionMap, type ActionResult, type AlgorithmRef, type AnyExtension, AppNav, AppNavError, AsyncExtensionError, BFS, BUILTIN_OPERATORS, type BuildOptions, type BuiltinAlgorithm, type Condition, type ConditionContext, ConditionError, type ConditionNode, type ConditionOperator, type ConditionOptions, DEFAULT_SCHEMA_DEFINITION, DIJKSTRA, type DefaultActionMap, type Diagnostic, type DiagnosticSeverity, type Edge, type ErrorLocation, type ExecuteOptions, type ExecutionResult, type Extension, type ExtensionDefinition, ExtensionError, type ExtensionsInput, FileLoadError, type Graph, type HandlerContext, type HandlerOptions, type Heuristic, type Hook, type IndexFileOptions, type IndexOptions, type InlineExtension, type InstructionAction, type InstructionStep, type Instructions, type JsonObject, type JsonPrimitive, type JsonValue, type LoadSchemaOptions, type NameOf, type NavTree, NavigationTree, NoPathError, type OutputOf, ParseError, type ParseOptions, type Path, type PathOptions, type PathResult, type PathfindingAlgorithm, type PropertySchema, type PropertyType, type RawEdge, type RawScreen, type ReadFile, type ResolvedSchema, type RouteContext, Runtime, SUPPORTED_GRAPH_VERSIONS, type SchemaDefinition, SchemaError, type ScopeInputs, type Screen, type SearchContext, type SearchResult, type StepContext, UnknownScreenError, UnsupportedVersionError, VARIABLE_TYPES, VERSION, type ValidateOptions, ValidationError, type ValidationResult, type VariableDeclaration, VariableError, type VariableScope, type VariableType, assertValid, buildInstructions, buildInstructionsSync, buildScope, calculatePath, collectReferences, conditionRefs, createRuntime, defaultReadFile, defaultRuntime, defineExtension, evaluateCondition, findReachable, getDefaultSchema, getExtensionOutput, indexGraph, indexTree, indexTreeFromText, isAction, loadSchema, matchesType, normalizeExtensions, parseCondition, parseGraph, parseTemplate, registerActionHandler, registerAlgorithm, registerSchema, resolveSchema, resolveValue, toDiagnostic, tryCalculatePath, typeOfValue, unregisterSchema, validateAgainst, validateGraph };