@pwfabric/runtime 0.0.0-stage → 1.0.0-rc.1

package/dist/binding/engine.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Binding Engine
+ *
+ * Resolves and manages capability bindings for surfaces
+ *
+ * @module @pwfabric/runtime/binding/engine
+ */
+import type { SurfaceId } from '@pwfabric/contracts';
+import type { FabricKernel } from '../kernel.js';
+import type { BindingConfig, BoundCapability, BindingContext, BindingResult, SurfaceBindingResult, AuthContext } from './types.js';
+import type { CacheProvider } from '../cache/types.js';
+/**
+ * Binding engine interface
+ */
+export interface BindingEngine {
+    /**
+     * Bind a capability to a surface
+     */
+    bind<TOutput>(surfaceId: SurfaceId, config: BindingConfig): BindingResult<TOutput>;
+    /**
+     * Bind all capabilities for a surface
+     */
+    bindAll(surfaceId: SurfaceId, configs: readonly BindingConfig[]): SurfaceBindingResult;
+    /**
+     * Get a bound capability
+     */
+    get(surfaceId: SurfaceId, alias: string): BoundCapability | undefined;
+    /**
+     * Unbind a capability
+     */
+    unbind(surfaceId: SurfaceId, alias: string): boolean;
+    /**
+     * Unbind all capabilities for a surface
+     */
+    unbindAll(surfaceId: SurfaceId): void;
+    /**
+     * Get binding context for a surface
+     */
+    getContext(surfaceId: SurfaceId): BindingContext | undefined;
+    /**
+     * Set authentication context
+     */
+    setAuthContext(surfaceId: SurfaceId, auth: AuthContext): void;
+}
+/**
+ * Runtime binding engine implementation
+ */
+export declare class RuntimeBindingEngine implements BindingEngine {
+    private readonly fabric;
+    private readonly cache;
+    private readonly contexts;
+    constructor(fabric: FabricKernel, cache?: CacheProvider);
+    bind<TOutput>(surfaceId: SurfaceId, config: BindingConfig): BindingResult<TOutput>;
+    bindAll(surfaceId: SurfaceId, configs: readonly BindingConfig[]): SurfaceBindingResult;
+    get(surfaceId: SurfaceId, alias: string): BoundCapability | undefined;
+    unbind(surfaceId: SurfaceId, alias: string): boolean;
+    unbindAll(surfaceId: SurfaceId): void;
+    getContext(surfaceId: SurfaceId): BindingContext | undefined;
+    setAuthContext(surfaceId: SurfaceId, auth: AuthContext): void;
+    private createBoundCapability;
+}
+/**
+ * Create a binding engine
+ */
+export declare function createBindingEngine(fabric: FabricKernel, cache?: CacheProvider): BindingEngine;

package/dist/binding/engine.js

@@ -0,0 +1,268 @@
+/**
+ * Binding Engine
+ *
+ * Resolves and manages capability bindings for surfaces
+ *
+ * @module @pwfabric/runtime/binding/engine
+ */
+import { executionErr } from '@pwfabric/contracts';
+// ============================================================
+// RUNTIME BINDING ENGINE
+// ============================================================
+/**
+ * Runtime binding engine implementation
+ */
+export class RuntimeBindingEngine {
+    fabric;
+    cache;
+    contexts = new Map();
+    constructor(fabric, cache) {
+        this.fabric = fabric;
+        this.cache = cache;
+    }
+    bind(surfaceId, config) {
+        // Resolve capability from fabric
+        const resolution = this.fabric.resolve(config.capabilityId);
+        if (!resolution.found) {
+            return {
+                success: false,
+                error: {
+                    type: 'resolution_failed',
+                    message: `Capability ${config.capabilityId} not found`,
+                },
+            };
+        }
+        const alias = config.alias ?? config.capabilityId;
+        // Create bound capability
+        const boundCapability = this.createBoundCapability(surfaceId, alias, resolution.capability, config);
+        // Get or create context
+        let context = this.contexts.get(surfaceId);
+        if (!context) {
+            context = {
+                surfaceId,
+                data: {},
+                bindings: new Map(),
+            };
+            this.contexts.set(surfaceId, context);
+        }
+        // Add to bindings
+        context.bindings.set(alias, boundCapability);
+        return { success: true, binding: boundCapability };
+    }
+    bindAll(surfaceId, configs) {
+        const errors = [];
+        for (const config of configs) {
+            const result = this.bind(surfaceId, config);
+            if (!result.success) {
+                errors.push(result.error);
+            }
+        }
+        if (errors.length > 0) {
+            return { success: false, errors };
+        }
+        const context = this.contexts.get(surfaceId);
+        if (!context) {
+            return {
+                success: false,
+                errors: [{ type: 'resolution_failed', message: 'Context not created' }],
+            };
+        }
+        return { success: true, context };
+    }
+    get(surfaceId, alias) {
+        return this.contexts.get(surfaceId)?.bindings.get(alias);
+    }
+    unbind(surfaceId, alias) {
+        const context = this.contexts.get(surfaceId);
+        if (!context)
+            return false;
+        return context.bindings.delete(alias);
+    }
+    unbindAll(surfaceId) {
+        this.contexts.delete(surfaceId);
+    }
+    getContext(surfaceId) {
+        return this.contexts.get(surfaceId);
+    }
+    setAuthContext(surfaceId, auth) {
+        const existing = this.contexts.get(surfaceId);
+        if (existing) {
+            const updated = {
+                ...existing,
+                auth,
+            };
+            this.contexts.set(surfaceId, updated);
+        }
+        else {
+            this.contexts.set(surfaceId, {
+                surfaceId,
+                auth,
+                data: {},
+                bindings: new Map(),
+            });
+        }
+    }
+    createBoundCapability(surfaceId, alias, _capability, config) {
+        let state = 'bound';
+        let lastExecuted;
+        let lastResult;
+        let lastInput;
+        let error;
+        const execute = async (input) => {
+            state = 'binding';
+            lastInput = input;
+            try {
+                // Apply input transform if configured
+                let transformedInput = input;
+                if (config.transform?.input) {
+                    try {
+                        transformedInput = config.transform.input(input);
+                    }
+                    catch (e) {
+                        state = 'error';
+                        error = {
+                            type: 'transform_failed',
+                            message: `Input transform failed: ${e}`,
+                            cause: e,
+                        };
+                        const execError = {
+                            type: 'execution_error',
+                            message: error.message,
+                            capabilityId: config.capabilityId,
+                        };
+                        return executionErr(execError);
+                    }
+                }
+                // Check cache if enabled
+                if (config.cache?.enabled && this.cache) {
+                    const cacheKey = config.cache.key ?? `${surfaceId}:${alias}:${JSON.stringify(input)}`;
+                    const cached = await this.cache.get(cacheKey);
+                    if (cached !== undefined) {
+                        state = 'bound';
+                        lastExecuted = Date.now();
+                        lastResult = { success: true, data: cached };
+                        return lastResult;
+                    }
+                }
+                // Execute capability
+                const result = await this.fabric.execute(config.capabilityId, transformedInput);
+                if (result.success) {
+                    // Apply output transform if configured
+                    let output = result.data;
+                    if (config.transform?.output) {
+                        try {
+                            output = config.transform.output(output);
+                        }
+                        catch (e) {
+                            state = 'error';
+                            error = {
+                                type: 'transform_failed',
+                                message: `Output transform failed: ${e}`,
+                                cause: e,
+                            };
+                            const execError = {
+                                type: 'execution_error',
+                                message: error.message,
+                                capabilityId: config.capabilityId,
+                            };
+                            return executionErr(execError);
+                        }
+                    }
+                    // Store in cache if enabled
+                    if (config.cache?.enabled && this.cache) {
+                        const cacheKey = config.cache.key ?? `${surfaceId}:${alias}:${JSON.stringify(input)}`;
+                        await this.cache.set(cacheKey, output, config.cache.ttl);
+                    }
+                    state = 'bound';
+                    lastExecuted = Date.now();
+                    lastResult = { success: true, data: output };
+                    return lastResult;
+                }
+                else {
+                    state = 'error';
+                    error = {
+                        type: 'execution_failed',
+                        message: result.error.message,
+                        cause: result.error,
+                    };
+                    lastResult = result;
+                    return result;
+                }
+            }
+            catch (e) {
+                state = 'error';
+                error = {
+                    type: 'execution_failed',
+                    message: `Execution failed: ${e}`,
+                    cause: e,
+                };
+                const execError = {
+                    type: 'execution_error',
+                    message: error.message,
+                    capabilityId: config.capabilityId,
+                };
+                return executionErr(execError);
+            }
+        };
+        const refresh = async () => {
+            if (lastInput === undefined) {
+                const execError = {
+                    type: 'execution_error',
+                    message: 'No previous input to refresh',
+                    capabilityId: config.capabilityId,
+                };
+                return executionErr(execError);
+            }
+            return execute(lastInput);
+        };
+        const invalidate = () => {
+            state = 'stale';
+            if (config.cache?.enabled && this.cache) {
+                const cacheKey = config.cache.key ?? `${surfaceId}:${alias}:${JSON.stringify(lastInput)}`;
+                this.cache.delete(cacheKey);
+            }
+        };
+        const boundCapability = {
+            get id() {
+                return `${surfaceId}:${alias}`;
+            },
+            capabilityId: config.capabilityId,
+            get state() {
+                return state;
+            },
+            config,
+            execute,
+            refresh,
+            invalidate,
+        };
+        // Use Object.defineProperties for optional getters to satisfy exactOptionalPropertyTypes
+        Object.defineProperties(boundCapability, {
+            lastExecuted: {
+                get() {
+                    return lastExecuted;
+                },
+                enumerable: true,
+            },
+            lastResult: {
+                get() {
+                    return lastResult;
+                },
+                enumerable: true,
+            },
+            error: {
+                get() {
+                    return error;
+                },
+                enumerable: true,
+            },
+        });
+        return boundCapability;
+    }
+}
+/**
+ * Create a binding engine
+ */
+export function createBindingEngine(fabric, cache) {
+    return new RuntimeBindingEngine(fabric, cache);
+}
+//# sourceMappingURL=engine.js.map

package/dist/binding/engine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.js","sourceRoot":"","sources":["../../src/binding/engine.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Binding Engine\n *\n * Resolves and manages capability bindings for surfaces\n *\n * @module @pwfabric/runtime/binding/engine\n */\n\nimport type { SurfaceId, Capability, ExecutionResult, ExecutionError } from '@pwfabric/contracts'\nimport { executionErr } from '@pwfabric/contracts'\nimport type { FabricKernel } from '../kernel.js'\nimport type {\n  BindingConfig,\n  BoundCapability,\n  BindingState,\n  BindingError,\n  BindingContext,\n  BindingResult,\n  SurfaceBindingResult,\n  AuthContext,\n} from './types.js'\nimport type { CacheProvider } from '../cache/types.js'\n\n// ============================================================\n// BINDING ENGINE\n// ============================================================\n\n/**\n * Binding engine interface\n */\nexport interface BindingEngine {\n  /**\n   * Bind a capability to a surface\n   */\n  bind<TOutput>(surfaceId: SurfaceId, config: BindingConfig): BindingResult<TOutput>\n\n  /**\n   * Bind all capabilities for a surface\n   */\n  bindAll(surfaceId: SurfaceId, configs: readonly BindingConfig[]): SurfaceBindingResult\n\n  /**\n   * Get a bound capability\n   */\n  get(surfaceId: SurfaceId, alias: string): BoundCapability | undefined\n\n  /**\n   * Unbind a capability\n   */\n  unbind(surfaceId: SurfaceId, alias: string): boolean\n\n  /**\n   * Unbind all capabilities for a surface\n   */\n  unbindAll(surfaceId: SurfaceId): void\n\n  /**\n   * Get binding context for a surface\n   */\n  getContext(surfaceId: SurfaceId): BindingContext | undefined\n\n  /**\n   * Set authentication context\n   */\n  setAuthContext(surfaceId: SurfaceId, auth: AuthContext): void\n}\n\n// ============================================================\n// RUNTIME BINDING ENGINE\n// ============================================================\n\n/**\n * Runtime binding engine implementation\n */\nexport class RuntimeBindingEngine implements BindingEngine {\n  private readonly fabric: FabricKernel\n  private readonly cache: CacheProvider | undefined\n  private readonly contexts = new Map<SurfaceId, BindingContext>()\n\n  constructor(fabric: FabricKernel, cache?: CacheProvider) {\n    this.fabric = fabric\n    this.cache = cache\n  }\n\n  bind<TOutput>(surfaceId: SurfaceId, config: BindingConfig): BindingResult<TOutput> {\n    // Resolve capability from fabric\n    const resolution = this.fabric.resolve(config.capabilityId)\n    if (!resolution.found) {\n      return {\n        success: false,\n        error: {\n          type: 'resolution_failed',\n          message: `Capability ${config.capabilityId} not found`,\n        },\n      }\n    }\n\n    const alias = config.alias ?? config.capabilityId\n\n    // Create bound capability\n    const boundCapability = this.createBoundCapability<unknown, TOutput>(\n      surfaceId,\n      alias,\n      resolution.capability,\n      config\n    )\n\n    // Get or create context\n    let context = this.contexts.get(surfaceId)\n    if (!context) {\n      context = {\n        surfaceId,\n        data: {},\n        bindings: new Map(),\n      }\n      this.contexts.set(surfaceId, context)\n    }\n\n    // Add to bindings\n    context.bindings.set(alias, boundCapability as BoundCapability)\n\n    return { success: true, binding: boundCapability }\n  }\n\n  bindAll(surfaceId: SurfaceId, configs: readonly BindingConfig[]): SurfaceBindingResult {\n    const errors: BindingError[] = []\n\n    for (const config of configs) {\n      const result = this.bind(surfaceId, config)\n      if (!result.success) {\n        errors.push(result.error)\n      }\n    }\n\n    if (errors.length > 0) {\n      return { success: false, errors }\n    }\n\n    const context = this.contexts.get(surfaceId)\n    if (!context) {\n      return {\n        success: false,\n        errors: [{ type: 'resolution_failed', message: 'Context not created' }],\n      }\n    }\n\n    return { success: true, context }\n  }\n\n  get(surfaceId: SurfaceId, alias: string): BoundCapability | undefined {\n    return this.contexts.get(surfaceId)?.bindings.get(alias)\n  }\n\n  unbind(surfaceId: SurfaceId, alias: string): boolean {\n    const context = this.contexts.get(surfaceId)\n    if (!context) return false\n    return context.bindings.delete(alias)\n  }\n\n  unbindAll(surfaceId: SurfaceId): void {\n    this.contexts.delete(surfaceId)\n  }\n\n  getContext(surfaceId: SurfaceId): BindingContext | undefined {\n    return this.contexts.get(surfaceId)\n  }\n\n  setAuthContext(surfaceId: SurfaceId, auth: AuthContext): void {\n    const existing = this.contexts.get(surfaceId)\n    if (existing) {\n      const updated: BindingContext = {\n        ...existing,\n        auth,\n      }\n      this.contexts.set(surfaceId, updated)\n    } else {\n      this.contexts.set(surfaceId, {\n        surfaceId,\n        auth,\n        data: {},\n        bindings: new Map(),\n      })\n    }\n  }\n\n  private createBoundCapability<TInput, TOutput>(\n    surfaceId: SurfaceId,\n    alias: string,\n    _capability: Capability,\n    config: BindingConfig\n  ): BoundCapability<TInput, TOutput> {\n    let state: BindingState = 'bound'\n    let lastExecuted: number | undefined\n    let lastResult: ExecutionResult<TOutput> | undefined\n    let lastInput: TInput | undefined\n    let error: BindingError | undefined\n\n    const execute = async (input: TInput): Promise<ExecutionResult<TOutput>> => {\n      state = 'binding'\n      lastInput = input\n\n      try {\n        // Apply input transform if configured\n        let transformedInput = input\n        if (config.transform?.input) {\n          try {\n            transformedInput = config.transform.input(input) as TInput\n          } catch (e) {\n            state = 'error'\n            error = {\n              type: 'transform_failed',\n              message: `Input transform failed: ${e}`,\n              cause: e,\n            }\n            const execError: ExecutionError = {\n              type: 'execution_error',\n              message: error.message,\n              capabilityId: config.capabilityId,\n            }\n            return executionErr(execError)\n          }\n        }\n\n        // Check cache if enabled\n        if (config.cache?.enabled && this.cache) {\n          const cacheKey = config.cache.key ?? `${surfaceId}:${alias}:${JSON.stringify(input)}`\n          const cached = await this.cache.get<TOutput>(cacheKey)\n          if (cached !== undefined) {\n            state = 'bound'\n            lastExecuted = Date.now()\n            lastResult = { success: true, data: cached }\n            return lastResult\n          }\n        }\n\n        // Execute capability\n        const result = await this.fabric.execute<TInput, TOutput>(\n          config.capabilityId,\n          transformedInput\n        )\n\n        if (result.success) {\n          // Apply output transform if configured\n          let output = result.data\n          if (config.transform?.output) {\n            try {\n              output = config.transform.output(output) as TOutput\n            } catch (e) {\n              state = 'error'\n              error = {\n                type: 'transform_failed',\n                message: `Output transform failed: ${e}`,\n                cause: e,\n              }\n              const execError: ExecutionError = {\n                type: 'execution_error',\n                message: error.message,\n                capabilityId: config.capabilityId,\n              }\n              return executionErr(execError)\n            }\n          }\n\n          // Store in cache if enabled\n          if (config.cache?.enabled && this.cache) {\n            const cacheKey = config.cache.key ?? `${surfaceId}:${alias}:${JSON.stringify(input)}`\n            await this.cache.set(cacheKey, output, config.cache.ttl)\n          }\n\n          state = 'bound'\n          lastExecuted = Date.now()\n          lastResult = { success: true, data: output }\n          return lastResult\n        } else {\n          state = 'error'\n          error = {\n            type: 'execution_failed',\n            message: result.error.message,\n            cause: result.error,\n          }\n          lastResult = result\n          return result\n        }\n      } catch (e) {\n        state = 'error'\n        error = {\n          type: 'execution_failed',\n          message: `Execution failed: ${e}`,\n          cause: e,\n        }\n        const execError: ExecutionError = {\n          type: 'execution_error',\n          message: error.message,\n          capabilityId: config.capabilityId,\n        }\n        return executionErr(execError)\n      }\n    }\n\n    const refresh = async (): Promise<ExecutionResult<TOutput>> => {\n      if (lastInput === undefined) {\n        const execError: ExecutionError = {\n          type: 'execution_error',\n          message: 'No previous input to refresh',\n          capabilityId: config.capabilityId,\n        }\n        return executionErr(execError)\n      }\n      return execute(lastInput)\n    }\n\n    const invalidate = (): void => {\n      state = 'stale'\n      if (config.cache?.enabled && this.cache) {\n        const cacheKey = config.cache.key ?? `${surfaceId}:${alias}:${JSON.stringify(lastInput)}`\n        this.cache.delete(cacheKey)\n      }\n    }\n\n    const boundCapability: BoundCapability<TInput, TOutput> = {\n      get id() {\n        return `${surfaceId}:${alias}`\n      },\n      capabilityId: config.capabilityId,\n      get state() {\n        return state\n      },\n      config,\n      execute,\n      refresh,\n      invalidate,\n    }\n\n    // Use Object.defineProperties for optional getters to satisfy exactOptionalPropertyTypes\n    Object.defineProperties(boundCapability, {\n      lastExecuted: {\n        get() {\n          return lastExecuted\n        },\n        enumerable: true,\n      },\n      lastResult: {\n        get() {\n          return lastResult\n        },\n        enumerable: true,\n      },\n      error: {\n        get() {\n          return error\n        },\n        enumerable: true,\n      },\n    })\n\n    return boundCapability\n  }\n}\n\n/**\n * Create a binding engine\n */\nexport function createBindingEngine(fabric: FabricKernel, cache?: CacheProvider): BindingEngine {\n  return new RuntimeBindingEngine(fabric, cache)\n}\n"]}

package/dist/binding/expression.d.ts

@@ -0,0 +1,150 @@
+/**
+ * Expression Evaluator for Data Binding
+ *
+ * Enhanced expression evaluation for data binding in surfaces
+ *
+ * This module extends the base expression evaluator with:
+ * - Arithmetic operations (+, -, *, /, %)
+ * - Data/state/params context separation
+ * - Dependency extraction for reactive updates
+ * - Safe null-coalescing operators
+ *
+ * @module @pwfabric/runtime/binding/expression
+ */
+/**
+ * Context for expression evaluation in data binding
+ */
+export interface BindingExpressionContext {
+    /** Data from data sources */
+    readonly data: Record<string, unknown>;
+    /** State from state stores */
+    readonly state: Record<string, unknown>;
+    /** URL/route parameters */
+    readonly params: Record<string, unknown>;
+    /** Custom helper functions */
+    readonly helpers?: Record<string, (...args: unknown[]) => unknown>;
+}
+/**
+ * Result of expression evaluation
+ */
+export type ExpressionEvalResult<T = unknown> = {
+    readonly success: true;
+    readonly value: T;
+} | {
+    readonly success: false;
+    readonly error: string;
+};
+/**
+ * Expression evaluator interface for data binding
+ */
+export interface ExpressionEvaluator {
+    /**
+     * Evaluate an expression in the given context
+     */
+    evaluate(expression: string, context: BindingExpressionContext): unknown;
+    /**
+     * Check if a value is an expression (contains {{...}})
+     */
+    isExpression(value: unknown): boolean;
+    /**
+     * Extract dependencies from an expression for reactive updates
+     */
+    extractDependencies(expression: string): ExpressionDependency[];
+    /**
+     * Interpolate expressions in a template string
+     */
+    interpolate(template: string, context: BindingExpressionContext): string;
+}
+/**
+ * Dependency extracted from an expression
+ */
+export interface ExpressionDependency {
+    /** The source of the dependency */
+    readonly source: 'data' | 'state' | 'params';
+    /** The path within the source */
+    readonly path: string;
+}
+/**
+ * Read one named property off a value, stepping into a list of one record.
+ *
+ * A LIST SOURCE ALWAYS BINDS AS A LIST (DataBoundSurfaceRenderer): a `rest`,
+ * `entity` or `graphql` source answering with ONE object is bound as `[obj]`,
+ * so `{{src[0].field}}` and `{{src.length}}` behave the same whatever the
+ * endpoint returned. But a detail page is authored as `{{product.title}}`, and
+ * a property read on an array finds nothing — such a page would render blank
+ * (`{{rows.name}}` → empty while `{{rows[0].name}}` → "banana").
+ *
+ * So: when the value is an array of EXACTLY ONE element and the array itself
+ * does not carry the key (not `length`, not an index, not an array method),
+ * the read continues into that one element. A list of two or more is a list —
+ * its `.title` stays undefined, as it always was. Both evaluators (this one
+ * and surface/expression) read properties through here, so a path means the
+ * same thing in a binding and in a block prop.
+ */
+export declare function readProperty(target: unknown, key: string): unknown;
+/**
+ * Resolve a dotted path in an object, handling nested properties and array indices
+ *
+ * @example
+ * resolvePath({ user: { name: 'John' } }, 'user.name') // 'John'
+ * resolvePath({ items: ['a', 'b'] }, 'items[0]') // 'a'
+ * resolvePath({ users: [{ name: 'John' }] }, 'users[0].name') // 'John'
+ */
+export declare function resolvePath(obj: unknown, path: string): unknown;
+/** Lexical options — the only grammar differences between the two callers. */
+export interface ExpressionSyntaxOptions {
+    /**
+     * `hero-stats-data.0.text` is ONE name. Surface data-source ids are
+     * hyphenated, and the surface evaluator always read them as paths, so in
+     * that mode a `-` between two name characters with no space around it is
+     * part of the name. Subtraction needs spaces there: `a - b`.
+     */
+    readonly hyphenNames?: boolean;
+    /** The binding evaluator has always read the literal `undefined` as `null`. */
+    readonly undefinedAsNull?: boolean;
+}
+/**
+ * How a bare name and a call resolve. The grammar is shared; the scope is the
+ * caller's: bindings see `data` / `state` / `params`, block props see the
+ * surface's expression data (`state`, source ids, `item`, `__errors`, …).
+ */
+export interface NameResolver {
+    /** The value of a bare name. */
+    lookup(name: string): unknown;
+    /** The helper a call names, or undefined when there is none. */
+    helper(name: string): ((...args: unknown[]) => unknown) | undefined;
+}
+/**
+ * Evaluate one expression (the text between `{{` and `}}`) against a scope.
+ * Throws on a syntax error, an unknown helper or an unsupported method — the
+ * two public evaluators turn that into `{ success: false }`.
+ */
+export declare function evaluateWithScope(expression: string, scope: NameResolver, opts?: ExpressionSyntaxOptions): unknown;
+/**
+ * Evaluate an expression with full context support
+ */
+export declare function evaluateExpression(expression: string, context: BindingExpressionContext): ExpressionEvalResult;
+/**
+ * Extract dependencies from an expression for reactive updates
+ */
+export declare function extractDependencies(expression: string): ExpressionDependency[];
+/**
+ * Check if a value contains expression syntax
+ */
+export declare function isExpression(value: unknown): boolean;
+/**
+ * Interpolate expressions within a template string
+ *
+ * @example
+ * interpolate('Hello, {{user.name}}!', context) // 'Hello, John!'
+ * interpolate('Total: {{price * quantity}}', context) // 'Total: 100'
+ */
+export declare function interpolate(template: string, context: BindingExpressionContext): string;
+/**
+ * Default helper functions for expressions
+ */
+export declare const DEFAULT_BINDING_HELPERS: Record<string, (...args: unknown[]) => unknown>;
+/**
+ * Create an expression evaluator with context and helpers
+ */
+export declare function createExpressionEvaluator(additionalHelpers?: Record<string, (...args: unknown[]) => unknown>): ExpressionEvaluator;