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

package/dist/state/manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manager.js","sourceRoot":"","sources":["../../src/state/manager.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAA;AAE/C,+DAA+D;AAC/D,gCAAgC;AAChC,+DAA+D;AAE/D;;;GAGG;AACH,MAAM,OAAO,0BAA0B;IACpB,MAAM,GAAG,IAAI,GAAG,EAA+B,CAAA;IAC/C,aAAa,CAAkB;IAEhD,YAAY,gBAAkC,EAAE;QAC9C,IAAI,CAAC,aAAa,GAAG,aAAa,CAAA;IACpC,CAAC;IAED,WAAW,CAAI,SAAiB,EAAE,YAAe;QAC/C,wEAAwE;QACxE,IAAI,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,CAAC;YAC/B,MAAM,IAAI,KAAK,CAAC,2CAA2C,SAAS,EAAE,CAAC,CAAA;QACzE,CAAC;QAED,+DAA+D;QAC/D,MAAM,WAAW,GAAG,IAAI,CAAC,qBAAqB,CAAC,YAAY,CAAC,CAAA;QAC5D,MAAM,KAAK,GAAG,IAAI,kBAAkB,CAAU,WAAW,EAAE,IAAI,CAAC,aAAa,CAAC,CAAA;QAE9E,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,SAAS,EAAE,KAAK,CAAC,CAAA;QAEjC,OAAO,KAAsB,CAAA;IAC/B,CAAC;IAED,QAAQ,CAAI,SAAiB;QAC3B,OAAO,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,SAAS,CAA8B,CAAA;IAChE,CAAC;IAED,QAAQ,CAAC,SAAiB;QACxB,OAAO,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,SAAS,CAAC,CAAA;IACnC,CAAC;IAED,YAAY,CAAC,SAAiB;QAC5B,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,SAAS,CAAC,CAAA;QACxC,IAAI,KAAK,EAAE,CAAC;YACV,KAAK,CAAC,KAAK,EAAE,CAAA;YACb,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,CAAA;QAC/B,CAAC;IACH,CAAC;IAED,UAAU;QACR,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,EAAE,CAAC;YACzC,KAAK,CAAC,KAAK,EAAE,CAAA;QACf,CAAC;QACD,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAA;IACrB,CAAC;IAED,aAAa;QACX,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,CAAA;IACvC,CAAC;IAED;;;OAGG;IACH,gBAAgB,CAAI,SAAiB,EAAE,YAAgB;QACrD,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAI,SAAS,CAAC,CAAA;QAC5C,IAAI,QAAQ,EAAE,CAAC;YACb,OAAO,QAAQ,CAAA;QACjB,CAAC;QAED,OAAO,IAAI,CAAC,WAAW,CAAI,SAAS,EAAE,YAAY,IAAK,EAAQ,CAAC,CAAA;IAClE,CAAC;IAEO,qBAAqB,CAAI,YAAe;QAC9C,6DAA6D;QAC7D,IAAI,YAAY,KAAK,IAAI,IAAI,OAAO,YAAY,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,YAAY,CAAC,EAAE,CAAC;YAC9F,OAAO,YAAuC,CAAA;QAChD,CAAC;QAED,mCAAmC;QACnC,OAAO,EAAE,KAAK,EAAE,YAAY,EAAE,CAAA;IAChC,CAAC;CACF;AAED;;GAEG;AACH,MAAM,UAAU,yBAAyB,CAAC,MAAyB;IACjE,OAAO,IAAI,0BAA0B,CAAC,MAAM,CAAC,CAAA;AAC/C,CAAC","sourcesContent":["/**\n * Surface State Manager\n *\n * Manager for surface-scoped state stores\n *\n * @module @pwfabric/runtime/state/manager\n */\n\nimport type { SurfaceStateManager, StateStore, StateStoreConfig } from './types.js'\nimport { InMemoryStateStore } from './store.js'\n\n// ============================================================\n// DEFAULT SURFACE STATE MANAGER\n// ============================================================\n\n/**\n * Default implementation of SurfaceStateManager\n * Manages multiple state stores, one per surface\n */\nexport class DefaultSurfaceStateManager implements SurfaceStateManager {\n  private readonly stores = new Map<string, StateStore<unknown>>()\n  private readonly defaultConfig: StateStoreConfig\n\n  constructor(defaultConfig: StateStoreConfig = {}) {\n    this.defaultConfig = defaultConfig\n  }\n\n  createStore<T>(surfaceId: string, initialState: T): StateStore<T> {\n    // If store already exists, throw error to prevent accidental overwrites\n    if (this.stores.has(surfaceId)) {\n      throw new Error(`State store already exists for surface: ${surfaceId}`)\n    }\n\n    // Convert single value initialState to object format if needed\n    const stateObject = this.normalizeInitialState(initialState)\n    const store = new InMemoryStateStore<unknown>(stateObject, this.defaultConfig)\n\n    this.stores.set(surfaceId, store)\n\n    return store as StateStore<T>\n  }\n\n  getStore<T>(surfaceId: string): StateStore<T> | undefined {\n    return this.stores.get(surfaceId) as StateStore<T> | undefined\n  }\n\n  hasStore(surfaceId: string): boolean {\n    return this.stores.has(surfaceId)\n  }\n\n  destroyStore(surfaceId: string): void {\n    const store = this.stores.get(surfaceId)\n    if (store) {\n      store.clear()\n      this.stores.delete(surfaceId)\n    }\n  }\n\n  destroyAll(): void {\n    for (const store of this.stores.values()) {\n      store.clear()\n    }\n    this.stores.clear()\n  }\n\n  getSurfaceIds(): string[] {\n    return Array.from(this.stores.keys())\n  }\n\n  /**\n   * Get or create a store for a surface\n   * Creates a new store with empty initial state if it doesn't exist\n   */\n  getOrCreateStore<T>(surfaceId: string, initialState?: T): StateStore<T> {\n    const existing = this.getStore<T>(surfaceId)\n    if (existing) {\n      return existing\n    }\n\n    return this.createStore<T>(surfaceId, initialState ?? ({} as T))\n  }\n\n  private normalizeInitialState<T>(initialState: T): Record<string, unknown> {\n    // If already an object (but not null/array), use it directly\n    if (initialState !== null && typeof initialState === 'object' && !Array.isArray(initialState)) {\n      return initialState as Record<string, unknown>\n    }\n\n    // Otherwise, wrap in a 'value' key\n    return { value: initialState }\n  }\n}\n\n/**\n * Create a surface state manager\n */\nexport function createSurfaceStateManager(config?: StateStoreConfig): SurfaceStateManager {\n  return new DefaultSurfaceStateManager(config)\n}\n"]}

package/dist/state/store.d.ts

@@ -0,0 +1,40 @@
+/**
+ * In-Memory State Store
+ *
+ * In-memory state store implementation with reactive subscriptions
+ *
+ * @module @pwfabric/runtime/state/store
+ */
+import type { StateStore, StateChangeListener, StateStoreConfig, StateHistoryEntry } from './types.js';
+/**
+ * In-memory implementation of StateStore with reactive subscriptions
+ */
+export declare class InMemoryStateStore<T = unknown> implements StateStore<T> {
+    private readonly state;
+    private readonly listeners;
+    private readonly history;
+    private readonly config;
+    constructor(initialState?: Record<string, T>, config?: StateStoreConfig);
+    get(key: string): T | undefined;
+    set(key: string, value: T): void;
+    subscribe(key: string, listener: StateChangeListener<T>): () => void;
+    clear(): void;
+    keys(): string[];
+    has(key: string): boolean;
+    size(): number;
+    /**
+     * Get state change history for a key (if history is enabled)
+     */
+    getHistory(key: string): readonly StateHistoryEntry<T>[];
+    /**
+     * Get all current state as an object
+     */
+    getSnapshot(): Record<string, T>;
+    private notifyListeners;
+    private recordHistory;
+    private maybeClone;
+}
+/**
+ * Create an in-memory state store
+ */
+export declare function createStateStore<T = unknown>(initialState?: Record<string, T>, config?: StateStoreConfig): StateStore<T>;

package/dist/state/store.js

@@ -0,0 +1,145 @@
+/**
+ * In-Memory State Store
+ *
+ * In-memory state store implementation with reactive subscriptions
+ *
+ * @module @pwfabric/runtime/state/store
+ */
+// ============================================================
+// IN-MEMORY STATE STORE
+// ============================================================
+/**
+ * In-memory implementation of StateStore with reactive subscriptions
+ */
+export class InMemoryStateStore {
+    state = new Map();
+    listeners = new Map();
+    history = new Map();
+    config;
+    constructor(initialState = {}, config = {}) {
+        this.config = {
+            enableHistory: config.enableHistory ?? false,
+            maxHistorySize: config.maxHistorySize ?? 100,
+            deepClone: config.deepClone ?? false,
+        };
+        // Initialize with initial state
+        for (const [key, value] of Object.entries(initialState)) {
+            this.state.set(key, this.maybeClone(value));
+        }
+    }
+    get(key) {
+        const value = this.state.get(key);
+        return value !== undefined ? this.maybeClone(value) : undefined;
+    }
+    set(key, value) {
+        const previousValue = this.state.get(key);
+        const newValue = this.maybeClone(value);
+        this.state.set(key, newValue);
+        // Record history if enabled
+        if (this.config.enableHistory) {
+            this.recordHistory(key, newValue);
+        }
+        // Notify listeners
+        const event = {
+            key,
+            previousValue,
+            newValue,
+            timestamp: Date.now(),
+        };
+        this.notifyListeners(key, newValue, event);
+    }
+    subscribe(key, listener) {
+        let keyListeners = this.listeners.get(key);
+        if (!keyListeners) {
+            keyListeners = new Set();
+            this.listeners.set(key, keyListeners);
+        }
+        keyListeners.add(listener);
+        // Return unsubscribe function
+        return () => {
+            keyListeners.delete(listener);
+            if (keyListeners.size === 0) {
+                this.listeners.delete(key);
+            }
+        };
+    }
+    clear() {
+        this.state.clear();
+        this.listeners.clear();
+        this.history.clear();
+    }
+    keys() {
+        return Array.from(this.state.keys());
+    }
+    has(key) {
+        return this.state.has(key);
+    }
+    size() {
+        return this.state.size;
+    }
+    /**
+     * Get state change history for a key (if history is enabled)
+     */
+    getHistory(key) {
+        return this.history.get(key) ?? [];
+    }
+    /**
+     * Get all current state as an object
+     */
+    getSnapshot() {
+        const snapshot = {};
+        for (const [key, value] of this.state) {
+            snapshot[key] = this.maybeClone(value);
+        }
+        return snapshot;
+    }
+    notifyListeners(key, value, event) {
+        const keyListeners = this.listeners.get(key);
+        if (keyListeners) {
+            for (const listener of keyListeners) {
+                try {
+                    listener(value, event);
+                }
+                catch {
+                    // Swallow errors from listeners to prevent one bad listener from breaking others
+                }
+            }
+        }
+    }
+    recordHistory(key, value) {
+        let keyHistory = this.history.get(key);
+        if (!keyHistory) {
+            keyHistory = [];
+            this.history.set(key, keyHistory);
+        }
+        keyHistory.push({
+            value: this.maybeClone(value),
+            timestamp: Date.now(),
+        });
+        // Trim history if exceeds max size
+        while (keyHistory.length > this.config.maxHistorySize) {
+            keyHistory.shift();
+        }
+    }
+    maybeClone(value) {
+        if (!this.config.deepClone) {
+            return value;
+        }
+        // Simple deep clone using JSON (works for most cases)
+        // For more complex cases, a proper deep clone library would be needed
+        try {
+            return JSON.parse(JSON.stringify(value));
+        }
+        catch {
+            // If cloning fails, return original value
+            return value;
+        }
+    }
+}
+/**
+ * Create an in-memory state store
+ */
+export function createStateStore(initialState, config) {
+    return new InMemoryStateStore(initialState, config);
+}
+//# sourceMappingURL=store.js.map

package/dist/state/store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.js","sourceRoot":"","sources":["../../src/state/store.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * In-Memory State Store\n *\n * In-memory state store implementation with reactive subscriptions\n *\n * @module @pwfabric/runtime/state/store\n */\n\nimport type {\n  StateStore,\n  StateChangeEvent,\n  StateChangeListener,\n  StateStoreConfig,\n  StateHistoryEntry,\n} from './types.js'\n\n// ============================================================\n// IN-MEMORY STATE STORE\n// ============================================================\n\n/**\n * In-memory implementation of StateStore with reactive subscriptions\n */\nexport class InMemoryStateStore<T = unknown> implements StateStore<T> {\n  private readonly state = new Map<string, T>()\n  private readonly listeners = new Map<string, Set<StateChangeListener<T>>>()\n  private readonly history = new Map<string, StateHistoryEntry<T>[]>()\n  private readonly config: Required<StateStoreConfig>\n\n  constructor(initialState: Record<string, T> = {}, config: StateStoreConfig = {}) {\n    this.config = {\n      enableHistory: config.enableHistory ?? false,\n      maxHistorySize: config.maxHistorySize ?? 100,\n      deepClone: config.deepClone ?? false,\n    }\n\n    // Initialize with initial state\n    for (const [key, value] of Object.entries(initialState)) {\n      this.state.set(key, this.maybeClone(value))\n    }\n  }\n\n  get(key: string): T | undefined {\n    const value = this.state.get(key)\n    return value !== undefined ? this.maybeClone(value) : undefined\n  }\n\n  set(key: string, value: T): void {\n    const previousValue = this.state.get(key)\n    const newValue = this.maybeClone(value)\n\n    this.state.set(key, newValue)\n\n    // Record history if enabled\n    if (this.config.enableHistory) {\n      this.recordHistory(key, newValue)\n    }\n\n    // Notify listeners\n    const event: StateChangeEvent<T> = {\n      key,\n      previousValue,\n      newValue,\n      timestamp: Date.now(),\n    }\n\n    this.notifyListeners(key, newValue, event)\n  }\n\n  subscribe(key: string, listener: StateChangeListener<T>): () => void {\n    let keyListeners = this.listeners.get(key)\n    if (!keyListeners) {\n      keyListeners = new Set()\n      this.listeners.set(key, keyListeners)\n    }\n\n    keyListeners.add(listener)\n\n    // Return unsubscribe function\n    return () => {\n      keyListeners.delete(listener)\n      if (keyListeners.size === 0) {\n        this.listeners.delete(key)\n      }\n    }\n  }\n\n  clear(): void {\n    this.state.clear()\n    this.listeners.clear()\n    this.history.clear()\n  }\n\n  keys(): string[] {\n    return Array.from(this.state.keys())\n  }\n\n  has(key: string): boolean {\n    return this.state.has(key)\n  }\n\n  size(): number {\n    return this.state.size\n  }\n\n  /**\n   * Get state change history for a key (if history is enabled)\n   */\n  getHistory(key: string): readonly StateHistoryEntry<T>[] {\n    return this.history.get(key) ?? []\n  }\n\n  /**\n   * Get all current state as an object\n   */\n  getSnapshot(): Record<string, T> {\n    const snapshot: Record<string, T> = {}\n    for (const [key, value] of this.state) {\n      snapshot[key] = this.maybeClone(value)\n    }\n    return snapshot\n  }\n\n  private notifyListeners(key: string, value: T, event: StateChangeEvent<T>): void {\n    const keyListeners = this.listeners.get(key)\n    if (keyListeners) {\n      for (const listener of keyListeners) {\n        try {\n          listener(value, event)\n        } catch {\n          // Swallow errors from listeners to prevent one bad listener from breaking others\n        }\n      }\n    }\n  }\n\n  private recordHistory(key: string, value: T): void {\n    let keyHistory = this.history.get(key)\n    if (!keyHistory) {\n      keyHistory = []\n      this.history.set(key, keyHistory)\n    }\n\n    keyHistory.push({\n      value: this.maybeClone(value),\n      timestamp: Date.now(),\n    })\n\n    // Trim history if exceeds max size\n    while (keyHistory.length > this.config.maxHistorySize) {\n      keyHistory.shift()\n    }\n  }\n\n  private maybeClone(value: T): T {\n    if (!this.config.deepClone) {\n      return value\n    }\n\n    // Simple deep clone using JSON (works for most cases)\n    // For more complex cases, a proper deep clone library would be needed\n    try {\n      return JSON.parse(JSON.stringify(value)) as T\n    } catch {\n      // If cloning fails, return original value\n      return value\n    }\n  }\n}\n\n/**\n * Create an in-memory state store\n */\nexport function createStateStore<T = unknown>(\n  initialState?: Record<string, T>,\n  config?: StateStoreConfig\n): StateStore<T> {\n  return new InMemoryStateStore<T>(initialState, config)\n}\n"]}

package/dist/state/types.d.ts

@@ -0,0 +1,107 @@
+/**
+ * State Management Types
+ *
+ * State management capability for surfaces
+ *
+ * @module @pwfabric/runtime/state/types
+ */
+/**
+ * Event emitted when state changes
+ */
+export interface StateChangeEvent<T = unknown> {
+    readonly key: string;
+    readonly previousValue: T | undefined;
+    readonly newValue: T;
+    readonly timestamp: number;
+}
+/**
+ * State change listener callback
+ */
+export type StateChangeListener<T = unknown> = (value: T, event: StateChangeEvent<T>) => void;
+/**
+ * State store interface for managing reactive state
+ */
+export interface StateStore<T = unknown> {
+    /**
+     * Get a value from the store
+     */
+    get(key: string): T | undefined;
+    /**
+     * Set a value in the store
+     */
+    set(key: string, value: T): void;
+    /**
+     * Subscribe to changes for a specific key
+     * Returns an unsubscribe function
+     */
+    subscribe(key: string, listener: StateChangeListener<T>): () => void;
+    /**
+     * Clear all state from the store
+     */
+    clear(): void;
+    /**
+     * Get all keys in the store
+     */
+    keys(): string[];
+    /**
+     * Check if a key exists in the store
+     */
+    has(key: string): boolean;
+    /**
+     * Get the number of entries in the store
+     */
+    size(): number;
+}
+/**
+ * Manager for surface-scoped state stores
+ */
+export interface SurfaceStateManager {
+    /**
+     * Create a new store for a surface with initial state
+     */
+    createStore<T>(surfaceId: string, initialState: T): StateStore<T>;
+    /**
+     * Get an existing store for a surface
+     */
+    getStore<T>(surfaceId: string): StateStore<T> | undefined;
+    /**
+     * Check if a store exists for a surface
+     */
+    hasStore(surfaceId: string): boolean;
+    /**
+     * Destroy a store for a surface
+     */
+    destroyStore(surfaceId: string): void;
+    /**
+     * Destroy all stores
+     */
+    destroyAll(): void;
+    /**
+     * Get all surface IDs with active stores
+     */
+    getSurfaceIds(): string[];
+}
+/**
+ * Configuration for state store
+ */
+export interface StateStoreConfig {
+    /**
+     * Whether to enable state change history
+     */
+    readonly enableHistory?: boolean;
+    /**
+     * Maximum history entries to keep per key
+     */
+    readonly maxHistorySize?: number;
+    /**
+     * Whether to deep clone values on get/set
+     */
+    readonly deepClone?: boolean;
+}
+/**
+ * State history entry
+ */
+export interface StateHistoryEntry<T = unknown> {
+    readonly value: T;
+    readonly timestamp: number;
+}

package/dist/state/types.js

@@ -0,0 +1,9 @@
+/**
+ * State Management Types
+ *
+ * State management capability for surfaces
+ *
+ * @module @pwfabric/runtime/state/types
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/state/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/state/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG","sourcesContent":["/**\n * State Management Types\n *\n * State management capability for surfaces\n *\n * @module @pwfabric/runtime/state/types\n */\n\n// ============================================================\n// STATE CHANGE EVENT\n// ============================================================\n\n/**\n * Event emitted when state changes\n */\nexport interface StateChangeEvent<T = unknown> {\n  readonly key: string\n  readonly previousValue: T | undefined\n  readonly newValue: T\n  readonly timestamp: number\n}\n\n/**\n * State change listener callback\n */\nexport type StateChangeListener<T = unknown> = (value: T, event: StateChangeEvent<T>) => void\n\n// ============================================================\n// STATE STORE\n// ============================================================\n\n/**\n * State store interface for managing reactive state\n */\nexport interface StateStore<T = unknown> {\n  /**\n   * Get a value from the store\n   */\n  get(key: string): T | undefined\n\n  /**\n   * Set a value in the store\n   */\n  set(key: string, value: T): void\n\n  /**\n   * Subscribe to changes for a specific key\n   * Returns an unsubscribe function\n   */\n  subscribe(key: string, listener: StateChangeListener<T>): () => void\n\n  /**\n   * Clear all state from the store\n   */\n  clear(): void\n\n  /**\n   * Get all keys in the store\n   */\n  keys(): string[]\n\n  /**\n   * Check if a key exists in the store\n   */\n  has(key: string): boolean\n\n  /**\n   * Get the number of entries in the store\n   */\n  size(): number\n}\n\n// ============================================================\n// SURFACE STATE MANAGER\n// ============================================================\n\n/**\n * Manager for surface-scoped state stores\n */\nexport interface SurfaceStateManager {\n  /**\n   * Create a new store for a surface with initial state\n   */\n  createStore<T>(surfaceId: string, initialState: T): StateStore<T>\n\n  /**\n   * Get an existing store for a surface\n   */\n  getStore<T>(surfaceId: string): StateStore<T> | undefined\n\n  /**\n   * Check if a store exists for a surface\n   */\n  hasStore(surfaceId: string): boolean\n\n  /**\n   * Destroy a store for a surface\n   */\n  destroyStore(surfaceId: string): void\n\n  /**\n   * Destroy all stores\n   */\n  destroyAll(): void\n\n  /**\n   * Get all surface IDs with active stores\n   */\n  getSurfaceIds(): string[]\n}\n\n// ============================================================\n// STATE CONFIGURATION\n// ============================================================\n\n/**\n * Configuration for state store\n */\nexport interface StateStoreConfig {\n  /**\n   * Whether to enable state change history\n   */\n  readonly enableHistory?: boolean\n\n  /**\n   * Maximum history entries to keep per key\n   */\n  readonly maxHistorySize?: number\n\n  /**\n   * Whether to deep clone values on get/set\n   */\n  readonly deepClone?: boolean\n}\n\n/**\n * State history entry\n */\nexport interface StateHistoryEntry<T = unknown> {\n  readonly value: T\n  readonly timestamp: number\n}\n"]}

package/dist/surface/expression.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Expression Evaluator
+ *
+ * Safe expression evaluation for surface rendering
+ *
+ * Expressions are used in conditionals, loops, and data bindings.
+ * This evaluator provides a safe, sandboxed way to evaluate expressions.
+ *
+ * @module @pwfabric/runtime/surface/expression
+ */
+export type ExpressionResult<T = unknown> = {
+    readonly success: true;
+    readonly value: T;
+} | {
+    readonly success: false;
+    readonly error: string;
+};
+/**
+ * Expression context - the scope for evaluation
+ */
+export interface ExpressionContext {
+    readonly data: Record<string, unknown>;
+    readonly helpers?: Record<string, (...args: unknown[]) => unknown>;
+}
+/**
+ * Resolve a dotted path in an object
+ * e.g., "user.profile.name" -> obj.user.profile.name
+ */
+export declare function resolvePath(obj: unknown, path: string): unknown;
+/**
+ * Evaluate an expression (the text between `{{` and `}}`).
+ *
+ * THE SAME PARSER AS THE BINDING EVALUATOR (binding/expression.ts). This used
+ * to be a regex/`split` evaluator of its own, and the two drifted: no
+ * parentheses, no arithmetic, helper arguments split on every comma — so
+ * `{{a == 'x' && (b || c)}}` failed, and a failed `visibleWhen` rendered its
+ * raw template, which counts as visible.
+ *
+ * Supported: paths (`user.name`, `items[0]`, `items.0`, hyphenated source ids
+ * `hero-stats.0.text`), literals, `! - +`, `* / %`, `+ -`, comparisons,
+ * `&& || ??` (short-circuit), `?:`, parentheses, array literals, helper calls
+ * (`join(xs, ', ')`) and a safe list of string / array / number methods
+ * (`name.toLowerCase().includes(q)`).
+ *
+ * Names resolve against `context.data`; a call resolves against
+ * `context.helpers`. In this mode a `-` between two name characters is part of
+ * the name (source ids are hyphenated) — write subtraction as `a - b`.
+ *
+ * A syntax error, an unknown helper or an unsupported method is a FAILURE
+ * (`success: false`), never a partial value.
+ */
+export declare function evaluate(expression: string, context: ExpressionContext): ExpressionResult;
+/**
+ * Interpolate expressions within a template string
+ * e.g., "Hello, {{user.name}}!" -> "Hello, John!"
+ */
+export declare function interpolate(template: string, context: ExpressionContext): ExpressionResult<string>;
+/**
+ * Default helper functions available in expressions
+ */
+export declare const DEFAULT_HELPERS: Record<string, (...args: unknown[]) => unknown>;
+/**
+ * Create an expression context with default helpers
+ */
+export declare function createExpressionContext(data: Record<string, unknown>, additionalHelpers?: Record<string, (...args: unknown[]) => unknown>): ExpressionContext;

package/dist/surface/expression.js

@@ -0,0 +1,179 @@
+/**
+ * Expression Evaluator
+ *
+ * Safe expression evaluation for surface rendering
+ *
+ * Expressions are used in conditionals, loops, and data bindings.
+ * This evaluator provides a safe, sandboxed way to evaluate expressions.
+ *
+ * @module @pwfabric/runtime/surface/expression
+ */
+// ============================================================
+// EXPRESSION TYPES
+// ============================================================
+/**
+ * Expression result
+ */
+import { DEFAULT_BINDING_HELPERS, evaluateWithScope, readProperty } from '../binding/expression.js';
+// ============================================================
+// PATH RESOLUTION
+// ============================================================
+/**
+ * Resolve a dotted path in an object
+ * e.g., "user.profile.name" -> obj.user.profile.name
+ */
+export function resolvePath(obj, path) {
+    if (!path || typeof obj !== 'object' || obj === null) {
+        return undefined;
+    }
+    const parts = path.split('.');
+    let current = obj;
+    for (const part of parts) {
+        if (current === null || current === undefined) {
+            return undefined;
+        }
+        // Handle array indexing: items[0]
+        const arrayMatch = part.match(/^(\w+)\[(\d+)\]$/);
+        if (arrayMatch) {
+            const prop = arrayMatch[1];
+            const index = arrayMatch[2];
+            if (prop && index) {
+                current = readProperty(current, prop);
+                if (Array.isArray(current)) {
+                    current = current[parseInt(index, 10)];
+                }
+                else {
+                    return undefined;
+                }
+            }
+        }
+        else if (typeof current === 'object') {
+            // A list of ONE record is read through — see readProperty.
+            current = readProperty(current, part);
+        }
+        else {
+            return undefined;
+        }
+    }
+    return current;
+}
+// ============================================================
+// EXPRESSION EVALUATOR
+// ============================================================
+/**
+ * Evaluate an expression (the text between `{{` and `}}`).
+ *
+ * THE SAME PARSER AS THE BINDING EVALUATOR (binding/expression.ts). This used
+ * to be a regex/`split` evaluator of its own, and the two drifted: no
+ * parentheses, no arithmetic, helper arguments split on every comma — so
+ * `{{a == 'x' && (b || c)}}` failed, and a failed `visibleWhen` rendered its
+ * raw template, which counts as visible.
+ *
+ * Supported: paths (`user.name`, `items[0]`, `items.0`, hyphenated source ids
+ * `hero-stats.0.text`), literals, `! - +`, `* / %`, `+ -`, comparisons,
+ * `&& || ??` (short-circuit), `?:`, parentheses, array literals, helper calls
+ * (`join(xs, ', ')`) and a safe list of string / array / number methods
+ * (`name.toLowerCase().includes(q)`).
+ *
+ * Names resolve against `context.data`; a call resolves against
+ * `context.helpers`. In this mode a `-` between two name characters is part of
+ * the name (source ids are hyphenated) — write subtraction as `a - b`.
+ *
+ * A syntax error, an unknown helper or an unsupported method is a FAILURE
+ * (`success: false`), never a partial value.
+ */
+export function evaluate(expression, context) {
+    try {
+        const data = context.data;
+        const helpers = context.helpers;
+        const value = evaluateWithScope(expression, {
+            lookup: (name) => data[name],
+            helper: (name) => helpers && Object.prototype.hasOwnProperty.call(helpers, name) ? helpers[name] : undefined,
+        }, { hyphenNames: true });
+        return { success: true, value };
+    }
+    catch (e) {
+        return { success: false, error: `Unable to evaluate expression: ${expression.trim()} — ${e instanceof Error ? e.message : String(e)}` };
+    }
+}
+// ============================================================
+// INTERPOLATION
+// ============================================================
+/**
+ * Interpolate expressions within a template string
+ * e.g., "Hello, {{user.name}}!" -> "Hello, John!"
+ */
+export function interpolate(template, context) {
+    const pattern = /\{\{(.+?)\}\}/g;
+    let result = template;
+    let match;
+    while ((match = pattern.exec(template)) !== null) {
+        const placeholder = match[0];
+        const expression = match[1];
+        if (!expression)
+            continue;
+        const evalResult = evaluate(expression.trim(), context);
+        if (!evalResult.success) {
+            return evalResult;
+        }
+        // CALLBACK replacer, NOT a string replacement. When its second argument is
+        // a string, `String.replace` treats `$&`, `$\``, `$'`, `$$` as REPLACEMENT
+        // PATTERNS: `"$$5"` in the data would print as `"$5"`, and `"a$&b"` would
+        // bring back the placeholder itself. The sibling evaluator
+        // (binding/expression.ts) uses a callback too.
+        const replacement = String(evalResult.value ?? '');
+        result = result.replace(placeholder, () => replacement);
+    }
+    return { success: true, value: result };
+}
+// ============================================================
+// BUILT-IN HELPERS
+// ============================================================
+/**
+ * Default helper functions available in expressions
+ */
+export const DEFAULT_HELPERS = {
+    // The binding evaluator's helper set comes first. Two evaluators exist —
+    // binding/expression (bindings, computed values) and this one (block props
+    // through resolveBlockExpressions) — and their helper lists drifted:
+    // `sumBy`, `groupCount`, `min`, `max`, `currency`, `date`… live in the
+    // binding set, and without it a KPI tile authored as
+    // `{{sumBy(customers,'mrr')}}` would render the raw template. One name, one meaning: the surface-specific entries below
+    // override where both define the same name.
+    ...DEFAULT_BINDING_HELPERS,
+    // String helpers
+    upper: (s) => String(s).toUpperCase(),
+    lower: (s) => String(s).toLowerCase(),
+    trim: (s) => String(s).trim(),
+    length: (s) => (Array.isArray(s) ? s.length : String(s).length),
+    concat: (...args) => args.map(String).join(''),
+    // Number helpers
+    // `round` comes from the binding set: `round(n)` as before, `round(n, 2)`
+    // to two decimals (this override used to drop the second argument).
+    floor: (n) => Math.floor(Number(n)),
+    ceil: (n) => Math.ceil(Number(n)),
+    abs: (n) => Math.abs(Number(n)),
+    // Array helpers
+    first: (arr) => (Array.isArray(arr) ? arr[0] : undefined),
+    last: (arr) => (Array.isArray(arr) ? arr[arr.length - 1] : undefined),
+    isEmpty: (v) => v === null || v === undefined || v === '' || (Array.isArray(v) && v.length === 0),
+    isNotEmpty: (v) => v !== null && v !== undefined && v !== '' && !(Array.isArray(v) && v.length === 0),
+    // Type helpers
+    typeof: (v) => typeof v,
+    isArray: (v) => Array.isArray(v),
+    isString: (v) => typeof v === 'string',
+    isNumber: (v) => typeof v === 'number',
+    isBool: (v) => typeof v === 'boolean',
+    // Formatting helpers
+    json: (v) => JSON.stringify(v),
+};
+/**
+ * Create an expression context with default helpers
+ */
+export function createExpressionContext(data, additionalHelpers) {
+    return {
+        data,
+        helpers: { ...DEFAULT_HELPERS, ...additionalHelpers },
+    };
+}
+//# sourceMappingURL=expression.js.map

package/dist/surface/expression.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"expression.js","sourceRoot":"","sources":["../../src/surface/expression.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Expression Evaluator\n *\n * Safe expression evaluation for surface rendering\n *\n * Expressions are used in conditionals, loops, and data bindings.\n * This evaluator provides a safe, sandboxed way to evaluate expressions.\n *\n * @module @pwfabric/runtime/surface/expression\n */\n\n// ============================================================\n// EXPRESSION TYPES\n// ============================================================\n\n/**\n * Expression result\n */\nimport { DEFAULT_BINDING_HELPERS, evaluateWithScope, readProperty } from '../binding/expression.js'\n\nexport type ExpressionResult<T = unknown> =\n  | { readonly success: true; readonly value: T }\n  | { readonly success: false; readonly error: string }\n\n/**\n * Expression context - the scope for evaluation\n */\nexport interface ExpressionContext {\n  readonly data: Record<string, unknown>\n  readonly helpers?: Record<string, (...args: unknown[]) => unknown>\n}\n\n// ============================================================\n// PATH RESOLUTION\n// ============================================================\n\n/**\n * Resolve a dotted path in an object\n * e.g., \"user.profile.name\" -> obj.user.profile.name\n */\nexport function resolvePath(obj: unknown, path: string): unknown {\n  if (!path || typeof obj !== 'object' || obj === null) {\n    return undefined\n  }\n\n  const parts = path.split('.')\n  let current: unknown = obj\n\n  for (const part of parts) {\n    if (current === null || current === undefined) {\n      return undefined\n    }\n\n    // Handle array indexing: items[0]\n    const arrayMatch = part.match(/^(\\w+)\\[(\\d+)\\]$/)\n    if (arrayMatch) {\n      const prop = arrayMatch[1]\n      const index = arrayMatch[2]\n      if (prop && index) {\n        current = readProperty(current, prop)\n        if (Array.isArray(current)) {\n          current = current[parseInt(index, 10)]\n        } else {\n          return undefined\n        }\n      }\n    } else if (typeof current === 'object') {\n      // A list of ONE record is read through — see readProperty.\n      current = readProperty(current, part)\n    } else {\n      return undefined\n    }\n  }\n\n  return current\n}\n\n// ============================================================\n// EXPRESSION EVALUATOR\n// ============================================================\n\n/**\n * Evaluate an expression (the text between `{{` and `}}`).\n *\n * THE SAME PARSER AS THE BINDING EVALUATOR (binding/expression.ts). This used\n * to be a regex/`split` evaluator of its own, and the two drifted: no\n * parentheses, no arithmetic, helper arguments split on every comma — so\n * `{{a == 'x' && (b || c)}}` failed, and a failed `visibleWhen` rendered its\n * raw template, which counts as visible.\n *\n * Supported: paths (`user.name`, `items[0]`, `items.0`, hyphenated source ids\n * `hero-stats.0.text`), literals, `! - +`, `* / %`, `+ -`, comparisons,\n * `&& || ??` (short-circuit), `?:`, parentheses, array literals, helper calls\n * (`join(xs, ', ')`) and a safe list of string / array / number methods\n * (`name.toLowerCase().includes(q)`).\n *\n * Names resolve against `context.data`; a call resolves against\n * `context.helpers`. In this mode a `-` between two name characters is part of\n * the name (source ids are hyphenated) — write subtraction as `a - b`.\n *\n * A syntax error, an unknown helper or an unsupported method is a FAILURE\n * (`success: false`), never a partial value.\n */\nexport function evaluate(expression: string, context: ExpressionContext): ExpressionResult {\n  try {\n    const data = context.data\n    const helpers = context.helpers\n    const value = evaluateWithScope(\n      expression,\n      {\n        lookup: (name) => data[name],\n        helper: (name) =>\n          helpers && Object.prototype.hasOwnProperty.call(helpers, name) ? helpers[name] : undefined,\n      },\n      { hyphenNames: true }\n    )\n    return { success: true, value }\n  } catch (e) {\n    return { success: false, error: `Unable to evaluate expression: ${expression.trim()} — ${e instanceof Error ? e.message : String(e)}` }\n  }\n}\n\n// ============================================================\n// INTERPOLATION\n// ============================================================\n\n/**\n * Interpolate expressions within a template string\n * e.g., \"Hello, {{user.name}}!\" -> \"Hello, John!\"\n */\nexport function interpolate(\n  template: string,\n  context: ExpressionContext\n): ExpressionResult<string> {\n  const pattern = /\\{\\{(.+?)\\}\\}/g\n  let result = template\n  let match: RegExpExecArray | null\n\n  while ((match = pattern.exec(template)) !== null) {\n    const placeholder = match[0]\n    const expression = match[1]\n    if (!expression) continue\n    const evalResult = evaluate(expression.trim(), context)\n    if (!evalResult.success) {\n      return evalResult as ExpressionResult<string>\n    }\n    // CALLBACK replacer, NOT a string replacement. When its second argument is\n    // a string, `String.replace` treats `$&`, `$\\``, `$'`, `$$` as REPLACEMENT\n    // PATTERNS: `\"$$5\"` in the data would print as `\"$5\"`, and `\"a$&b\"` would\n    // bring back the placeholder itself. The sibling evaluator\n    // (binding/expression.ts) uses a callback too.\n    const replacement = String(evalResult.value ?? '')\n    result = result.replace(placeholder, () => replacement)\n  }\n\n  return { success: true, value: result }\n}\n\n// ============================================================\n// BUILT-IN HELPERS\n// ============================================================\n\n/**\n * Default helper functions available in expressions\n */\nexport const DEFAULT_HELPERS: Record<string, (...args: unknown[]) => unknown> = {\n  // The binding evaluator's helper set comes first. Two evaluators exist —\n  // binding/expression (bindings, computed values) and this one (block props\n  // through resolveBlockExpressions) — and their helper lists drifted:\n  // `sumBy`, `groupCount`, `min`, `max`, `currency`, `date`… live in the\n  // binding set, and without it a KPI tile authored as\n  // `{{sumBy(customers,'mrr')}}` would render the raw template. One name, one meaning: the surface-specific entries below\n  // override where both define the same name.\n  ...DEFAULT_BINDING_HELPERS,\n  // String helpers\n  upper: (s: unknown) => String(s).toUpperCase(),\n  lower: (s: unknown) => String(s).toLowerCase(),\n  trim: (s: unknown) => String(s).trim(),\n  length: (s: unknown) => (Array.isArray(s) ? s.length : String(s).length),\n  concat: (...args: unknown[]) => args.map(String).join(''),\n\n  // Number helpers\n  // `round` comes from the binding set: `round(n)` as before, `round(n, 2)`\n  // to two decimals (this override used to drop the second argument).\n  floor: (n: unknown) => Math.floor(Number(n)),\n  ceil: (n: unknown) => Math.ceil(Number(n)),\n  abs: (n: unknown) => Math.abs(Number(n)),\n\n  // Array helpers\n  first: (arr: unknown) => (Array.isArray(arr) ? arr[0] : undefined),\n  last: (arr: unknown) => (Array.isArray(arr) ? arr[arr.length - 1] : undefined),\n  isEmpty: (v: unknown) =>\n    v === null || v === undefined || v === '' || (Array.isArray(v) && v.length === 0),\n  isNotEmpty: (v: unknown) =>\n    v !== null && v !== undefined && v !== '' && !(Array.isArray(v) && v.length === 0),\n\n  // Type helpers\n  typeof: (v: unknown) => typeof v,\n  isArray: (v: unknown) => Array.isArray(v),\n  isString: (v: unknown) => typeof v === 'string',\n  isNumber: (v: unknown) => typeof v === 'number',\n  isBool: (v: unknown) => typeof v === 'boolean',\n\n  // Formatting helpers\n  json: (v: unknown) => JSON.stringify(v),\n}\n\n/**\n * Create an expression context with default helpers\n */\nexport function createExpressionContext(\n  data: Record<string, unknown>,\n  additionalHelpers?: Record<string, (...args: unknown[]) => unknown>\n): ExpressionContext {\n  return {\n    data,\n    helpers: { ...DEFAULT_HELPERS, ...additionalHelpers },\n  }\n}\n"]}

package/dist/surface/index.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Surface Rendering Module
+ *
+ * Surface JSON interpreter, renderer, layout system, and primitives
+ *
+ * This module provides the complete surface rendering pipeline:
+ * - JSON interpretation and validation
+ * - Layout resolution (slots, conditionals, loops)
+ * - Deterministic rendering
+ * - Built-in primitives
+ *
+ * @module @pwfabric/runtime/surface
+ */
+export type { PrimitiveType, BaseNodeProps, RenderNode, SurfaceJSON, BindingJSON, LayoutJSON, RenderContext, RenderResult, RenderOutput, RenderError, RenderErrorCode, } from './types.js';
+export { createNode, createRenderContext, createChildContext, renderSuccess, renderError, } from './types.js';
+export type { ExpressionResult, ExpressionContext } from './expression.js';
+export { evaluate, interpolate, resolvePath, createExpressionContext, DEFAULT_HELPERS, } from './expression.js';
+export type { LayoutResult } from './layout.js';
+export { resolveLayout, createSlotMap, extractSlots, composeLayouts, wrapInContainer, validateLayout, } from './layout.js';
+export type { TextProps, ContainerProps, ButtonProps, InputProps, ImageProps, LinkProps, ListProps, HeadingProps, SpacerProps, DividerProps, SlotProps, ConditionalProps, LoopProps, PrimitiveDefinition, PropDefinition, } from './primitives.js';
+export { PRIMITIVE_DEFINITIONS, text, container, button, heading, spacer, divider, isPrimitive, getPrimitiveDefinition, } from './primitives.js';
+export { surfaceJsonSchema, layoutJsonSchema, bindingJsonSchema, environmentSchema, isSurfaceJSON, isLayoutJSON, isBindingJSON, } from './schemas.js';
+export type { InterpretedSurface, InterpretationResult, InterpretSurfaceOptions, } from './interpreter.js';
+export { interpretSurface, parseSurfaceJSON, SurfaceBuilder, surface, createSurfaceContext, } from './interpreter.js';
+export type { RenderOptions, SurfaceRenderer } from './renderer.js';
+export { DeterministicRenderer, createRenderer, renderSurface, isRenderSuccess, isRenderError, serializeNode, serializeOutput, hashNode, verifyDeterminism, } from './renderer.js';
+export type { BlockPropsValidationResult, BlockPropsValidationOptions, LayoutPropsIssue, ManifestPropSpec, BlockManifestPropsMap, ManifestPropFinding, ManifestPropFindingCode, } from './validation.js';
+export { validateBlockProps, validateLayoutProps, blockManifestPropFindings, manifestPropFindings, } from './validation.js';
+export type { MapTransformConfig, FilterTransformConfig, PickTransformConfig, OmitTransformConfig, CustomTransformConfig, TypedTransformConfig, TransformValidationResult, } from './transforms.js';
+export { mapTransformConfigSchema, filterTransformConfigSchema, pickTransformConfigSchema, omitTransformConfigSchema, customTransformConfigSchema, validateTransformConfig, narrowTransformDescriptor, createMapTransform, createFilterTransform, createPickTransform, createOmitTransform, createCustomTransform, } from './transforms.js';
+export type { TypedWebOutput, TypedApiOutput, TypedCliOutput, OutputFactoryResult, } from './output.js';
+export { createWebOutput, createApiOutput, createCliOutput } from './output.js';