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

package/dist/binding/two-way.js

@@ -0,0 +1,462 @@
+/**
+ * Two-way Data Binding
+ *
+ * P1-5: Extends the binding system with write-back capability.
+ * UI changes propagate back to the data source, enabling form inputs,
+ * editable fields, and other interactive elements to automatically
+ * update the data model.
+ *
+ * @module @pwfabric/runtime/binding/two-way
+ */
+import { resolvePath } from './expression.js';
+/**
+ * Parse a dot-notation path into segments for traversal
+ */
+function parsePath(path) {
+    const segments = [];
+    const regex = /(\w+)|\[(\d+)\]/g;
+    let match;
+    while ((match = regex.exec(path)) !== null) {
+        if (match[1] !== undefined) {
+            segments.push({ type: 'property', key: match[1] });
+        }
+        else if (match[2] !== undefined) {
+            segments.push({ type: 'index', index: parseInt(match[2], 10) });
+        }
+    }
+    return segments;
+}
+/**
+ * Set a value at a dot-notation path in an object, creating
+ * intermediate objects/arrays as needed.
+ *
+ * Mutates the target object in place.
+ */
+function setAtPath(obj, path, value) {
+    const segments = parsePath(path);
+    if (segments.length === 0)
+        return;
+    let current = obj;
+    for (let i = 0; i < segments.length - 1; i++) {
+        const segment = segments[i];
+        if (segment === undefined)
+            return;
+        if (segment.type === 'property') {
+            if (typeof current !== 'object' || current === null)
+                return;
+            const record = current;
+            if (record[segment.key] === undefined || record[segment.key] === null) {
+                // Look ahead to decide whether to create an object or array
+                const next = segments[i + 1];
+                record[segment.key] = next && next.type === 'index' ? [] : {};
+            }
+            current = record[segment.key];
+        }
+        else {
+            if (!Array.isArray(current))
+                return;
+            if (current[segment.index] === undefined || current[segment.index] === null) {
+                const next = segments[i + 1];
+                current[segment.index] = next && next.type === 'index' ? [] : {};
+            }
+            current = current[segment.index];
+        }
+    }
+    const last = segments[segments.length - 1];
+    if (last === undefined)
+        return;
+    if (last.type === 'property') {
+        if (typeof current === 'object' && current !== null) {
+            ;
+            current[last.key] = value;
+        }
+    }
+    else {
+        if (Array.isArray(current)) {
+            current[last.index] = value;
+        }
+    }
+}
+/**
+ * Deep-clone a plain object/array structure using structured clone
+ * semantics (JSON round-trip for simplicity and zero dependencies).
+ */
+function deepClone(value) {
+    if (value === undefined || value === null)
+        return value;
+    if (typeof value !== 'object')
+        return value;
+    return JSON.parse(JSON.stringify(value));
+}
+// ============================================================
+// TWO-WAY BINDING INSTANCE (INTERNAL)
+// ============================================================
+/**
+ * Internal class that implements a single two-way binding
+ */
+class TwoWayBindingInstance {
+    path;
+    _value;
+    _initialValue;
+    _error;
+    _isDirty = false;
+    _isValidating = false;
+    _disposed = false;
+    config;
+    manager;
+    debounceTimer;
+    constructor(config, initialValue, manager) {
+        this.path = config.path;
+        this.config = config;
+        this.manager = manager;
+        // Apply toView transform for initial value
+        const viewValue = config.transform?.toView
+            ? config.transform.toView(initialValue)
+            : initialValue;
+        this._value = viewValue;
+        this._initialValue = deepClone(viewValue);
+    }
+    get value() {
+        return this._value;
+    }
+    get error() {
+        return this._error;
+    }
+    get isDirty() {
+        return this._isDirty;
+    }
+    get isValidating() {
+        return this._isValidating;
+    }
+    setValue(newValue) {
+        if (this._disposed)
+            return;
+        const oldValue = this._value;
+        // Run validation if configured
+        if (this.config.validate) {
+            this._isValidating = true;
+            const result = this.config.validate(newValue);
+            this._isValidating = false;
+            if (!result.valid) {
+                this._error = result.error;
+                return;
+            }
+        }
+        // Clear any previous error
+        this._error = undefined;
+        // Update the local value
+        this._value = newValue;
+        // Track dirty state
+        this._isDirty = !isEqual(newValue, this._initialValue);
+        // Debounced write-back to model
+        this.scheduleWriteBack(newValue, oldValue);
+    }
+    reset() {
+        if (this._disposed)
+            return;
+        const oldValue = this._value;
+        this._value = deepClone(this._initialValue);
+        this._isDirty = false;
+        this._error = undefined;
+        this.clearDebounce();
+        // Write the reset value back to model immediately
+        const modelValue = this.config.transform?.toModel
+            ? this.config.transform.toModel(this._value)
+            : this._value;
+        this.manager.setValueInternal(this.path, modelValue, oldValue);
+    }
+    dispose() {
+        if (this._disposed)
+            return;
+        this._disposed = true;
+        this.clearDebounce();
+    }
+    /**
+     * Called by the manager when the model value changes externally
+     */
+    updateFromModel(modelValue) {
+        if (this._disposed)
+            return;
+        const viewValue = this.config.transform?.toView
+            ? this.config.transform.toView(modelValue)
+            : modelValue;
+        this._value = viewValue;
+        this._isDirty = !isEqual(viewValue, this._initialValue);
+    }
+    scheduleWriteBack(newValue, oldValue) {
+        this.clearDebounce();
+        const delay = this.config.debounceMs ?? DEFAULT_DEBOUNCE_MS;
+        if (delay <= 0) {
+            // Write immediately
+            this.writeBack(newValue, oldValue);
+            return;
+        }
+        this.debounceTimer = setTimeout(() => {
+            this.debounceTimer = undefined;
+            this.writeBack(newValue, oldValue);
+        }, delay);
+    }
+    writeBack(newValue, oldValue) {
+        if (this._disposed)
+            return;
+        // Apply toModel transform before writing back
+        const modelValue = this.config.transform?.toModel
+            ? this.config.transform.toModel(newValue)
+            : newValue;
+        this.manager.setValueInternal(this.path, modelValue, oldValue);
+    }
+    clearDebounce() {
+        if (this.debounceTimer !== undefined) {
+            clearTimeout(this.debounceTimer);
+            this.debounceTimer = undefined;
+        }
+    }
+}
+// ============================================================
+// CONSTANTS
+// ============================================================
+/** Default debounce delay in milliseconds */
+const DEFAULT_DEBOUNCE_MS = 300;
+// ============================================================
+// UTILITY
+// ============================================================
+/**
+ * Shallow equality check suitable for primitive and simple object values.
+ * Uses JSON serialization for object comparison (safe for plain data).
+ */
+function isEqual(a, b) {
+    if (a === b)
+        return true;
+    if (a === null || b === null)
+        return false;
+    if (a === undefined || b === undefined)
+        return false;
+    if (typeof a !== typeof b)
+        return false;
+    if (typeof a === 'object') {
+        try {
+            return JSON.stringify(a) === JSON.stringify(b);
+        }
+        catch {
+            return false;
+        }
+    }
+    return false;
+}
+// ============================================================
+// TWO-WAY BINDING MANAGER
+// ============================================================
+/**
+ * Manages two-way data bindings.
+ *
+ * Provides a central data store with path-based access, change listeners,
+ * validation, transforms, and batch update support. Each call to `bind()`
+ * creates a `TwoWayBinding` instance that can read/write a specific path
+ * in the data model.
+ */
+export class TwoWayBindingManager {
+    bindings = new Map();
+    data;
+    listeners = new Map();
+    batchDepth = 0;
+    pendingNotifications = [];
+    constructor(initialData) {
+        this.data = initialData ? deepClone(initialData) : {};
+    }
+    /**
+     * Create a two-way binding for a specific data path.
+     *
+     * Returns a `TwoWayBinding` instance that tracks the value at the path,
+     * supports validation and transforms, and writes changes back to the
+     * data model with optional debouncing.
+     */
+    bind(config) {
+        // Dispose any existing binding at this path
+        const existing = this.bindings.get(config.path);
+        if (existing) {
+            existing.dispose();
+        }
+        const currentValue = resolvePath(this.data, config.path);
+        const instance = new TwoWayBindingInstance(config, currentValue, this);
+        this.bindings.set(config.path, instance);
+        return instance;
+    }
+    /**
+     * Get the current value at a data path
+     */
+    getValue(path) {
+        return resolvePath(this.data, path);
+    }
+    /**
+     * Set a value at a data path, triggering change listeners
+     */
+    setValue(path, value) {
+        const oldValue = resolvePath(this.data, path);
+        // Write to data store
+        setAtPath(this.data, path, value);
+        // Update any binding watching this path
+        const binding = this.bindings.get(path);
+        if (binding) {
+            binding.updateFromModel(value);
+        }
+        // Notify listeners
+        this.notifyChange(path, value, oldValue);
+    }
+    /**
+     * Subscribe to changes at a data path.
+     *
+     * @returns Unsubscribe function
+     */
+    onChange(path, listener) {
+        let pathListeners = this.listeners.get(path);
+        if (!pathListeners) {
+            pathListeners = new Set();
+            this.listeners.set(path, pathListeners);
+        }
+        pathListeners.add(listener);
+        return () => {
+            pathListeners.delete(listener);
+            if (pathListeners.size === 0) {
+                this.listeners.delete(path);
+            }
+        };
+    }
+    /**
+     * Batch multiple updates together.
+     *
+     * Listener notifications are deferred until the outermost batch
+     * completes, then fired once per changed path.
+     */
+    batch(updates) {
+        this.batchDepth++;
+        try {
+            updates();
+        }
+        finally {
+            this.batchDepth--;
+            if (this.batchDepth === 0) {
+                this.flushPendingNotifications();
+            }
+        }
+    }
+    /**
+     * Get all bindings that have been modified from their initial values
+     */
+    getDirtyBindings() {
+        const dirty = [];
+        for (const binding of this.bindings.values()) {
+            if (binding.isDirty) {
+                dirty.push(binding);
+            }
+        }
+        return dirty;
+    }
+    /**
+     * Reset all bindings to their initial values
+     */
+    resetAll() {
+        for (const binding of this.bindings.values()) {
+            binding.reset();
+        }
+    }
+    /**
+     * Dispose all bindings and clear all listeners
+     */
+    dispose() {
+        for (const binding of this.bindings.values()) {
+            binding.dispose();
+        }
+        this.bindings.clear();
+        this.listeners.clear();
+        this.pendingNotifications.length = 0;
+    }
+    /**
+     * Internal method called by binding instances to write back to the model.
+     * Not part of the public API.
+     */
+    setValueInternal(path, modelValue, oldViewValue) {
+        const oldModelValue = resolvePath(this.data, path);
+        // Write to data store
+        setAtPath(this.data, path, modelValue);
+        // Notify listeners with model values
+        this.notifyChange(path, modelValue, oldModelValue ?? oldViewValue);
+    }
+    // ============================================================
+    // PRIVATE
+    // ============================================================
+    notifyChange(path, newValue, oldValue) {
+        if (this.batchDepth > 0) {
+            // During batch, accumulate notifications (last write wins per path)
+            const existingIdx = this.pendingNotifications.findIndex((n) => n.path === path);
+            if (existingIdx >= 0) {
+                const existing = this.pendingNotifications[existingIdx];
+                if (existing) {
+                    // Keep the original oldValue, update newValue
+                    this.pendingNotifications[existingIdx] = {
+                        path,
+                        newValue,
+                        oldValue: existing.oldValue,
+                    };
+                }
+            }
+            else {
+                this.pendingNotifications.push({ path, newValue, oldValue });
+            }
+            return;
+        }
+        this.fireListeners(path, newValue, oldValue);
+    }
+    flushPendingNotifications() {
+        // Copy and clear to handle re-entrant batch calls
+        const pending = [...this.pendingNotifications];
+        this.pendingNotifications.length = 0;
+        for (const { path, newValue, oldValue } of pending) {
+            this.fireListeners(path, newValue, oldValue);
+        }
+    }
+    fireListeners(path, newValue, oldValue) {
+        const pathListeners = this.listeners.get(path);
+        if (!pathListeners)
+            return;
+        for (const listener of pathListeners) {
+            try {
+                listener(newValue, oldValue);
+            }
+            catch {
+                // Swallow errors from listeners to prevent cascade failures
+            }
+        }
+    }
+}
+// ============================================================
+// FACTORY
+// ============================================================
+/**
+ * Create a two-way binding manager
+ *
+ * @param initialData - Optional initial data to populate the model
+ * @returns A new TwoWayBindingManager instance
+ *
+ * @example
+ * ```ts
+ * const manager = createTwoWayBindingManager({
+ *   user: { name: 'John', email: 'john@example.com' }
+ * })
+ *
+ * const nameBinding = manager.bind<string>({
+ *   path: 'user.name',
+ *   debounceMs: 200,
+ *   validate: (v) => ({
+ *     valid: typeof v === 'string' && v.length > 0,
+ *     error: 'Name is required',
+ *   }),
+ * })
+ *
+ * nameBinding.setValue('Jane')
+ * // After debounce, manager.getValue('user.name') === 'Jane'
+ * ```
+ */
+export function createTwoWayBindingManager(initialData) {
+    return new TwoWayBindingManager(initialData);
+}
+//# sourceMappingURL=two-way.js.map

package/dist/binding/two-way.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"two-way.js","sourceRoot":"","sources":["../../src/binding/two-way.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Two-way Data Binding\n *\n * P1-5: Extends the binding system with write-back capability.\n * UI changes propagate back to the data source, enabling form inputs,\n * editable fields, and other interactive elements to automatically\n * update the data model.\n *\n * @module @pwfabric/runtime/binding/two-way\n */\n\nimport { resolvePath } from './expression.js'\n\n// ============================================================\n// TYPES\n// ============================================================\n\n/**\n * Configuration for a two-way binding\n */\nexport interface TwoWayBindingConfig {\n  /** Data path using dot-notation (e.g., \"user.profile.name\") */\n  readonly path: string\n  /** Debounce delay in ms for write-back (default: 300) */\n  readonly debounceMs?: number\n  /** Optional validation function run before setting value */\n  readonly validate?: (value: unknown) => ValidationResult\n  /** Optional transform functions between UI and model */\n  readonly transform?: {\n    readonly toModel?: (uiValue: unknown) => unknown\n    readonly toView?: (modelValue: unknown) => unknown\n  }\n}\n\n/**\n * Result of value validation\n */\nexport interface ValidationResult {\n  readonly valid: boolean\n  readonly error?: string\n}\n\n/**\n * A two-way binding instance for a specific data path\n */\nexport interface TwoWayBinding<T = unknown> {\n  /** The data path this binding targets */\n  readonly path: string\n  /** Current value at the path */\n  readonly value: T\n  /** Current validation error, if any */\n  readonly error?: string | undefined\n  /** Whether the value has changed from the initial value */\n  readonly isDirty: boolean\n  /** Whether validation is currently running */\n  readonly isValidating: boolean\n  /** Set a new value (triggers validation, debounced write-back) */\n  setValue(newValue: T): void\n  /** Reset value to the initial value */\n  reset(): void\n  /** Dispose the binding and clean up timers */\n  dispose(): void\n}\n\n/**\n * Listener called when a value changes at a path\n */\nexport type ChangeListener<T = unknown> = (newValue: T, oldValue: T) => void\n\n// ============================================================\n// PATH UTILITIES\n// ============================================================\n\n/**\n * Parsed segment of a data path\n */\ntype PathSegment = { type: 'property'; key: string } | { type: 'index'; index: number }\n\n/**\n * Parse a dot-notation path into segments for traversal\n */\nfunction parsePath(path: string): PathSegment[] {\n  const segments: PathSegment[] = []\n  const regex = /(\\w+)|\\[(\\d+)\\]/g\n  let match: RegExpExecArray | null\n\n  while ((match = regex.exec(path)) !== null) {\n    if (match[1] !== undefined) {\n      segments.push({ type: 'property', key: match[1] })\n    } else if (match[2] !== undefined) {\n      segments.push({ type: 'index', index: parseInt(match[2], 10) })\n    }\n  }\n\n  return segments\n}\n\n/**\n * Set a value at a dot-notation path in an object, creating\n * intermediate objects/arrays as needed.\n *\n * Mutates the target object in place.\n */\nfunction setAtPath(obj: Record<string, unknown>, path: string, value: unknown): void {\n  const segments = parsePath(path)\n  if (segments.length === 0) return\n\n  let current: unknown = obj\n\n  for (let i = 0; i < segments.length - 1; i++) {\n    const segment = segments[i]\n    if (segment === undefined) return\n\n    if (segment.type === 'property') {\n      if (typeof current !== 'object' || current === null) return\n      const record = current as Record<string, unknown>\n      if (record[segment.key] === undefined || record[segment.key] === null) {\n        // Look ahead to decide whether to create an object or array\n        const next = segments[i + 1]\n        record[segment.key] = next && next.type === 'index' ? [] : {}\n      }\n      current = record[segment.key]\n    } else {\n      if (!Array.isArray(current)) return\n      if (current[segment.index] === undefined || current[segment.index] === null) {\n        const next = segments[i + 1]\n        current[segment.index] = next && next.type === 'index' ? [] : {}\n      }\n      current = current[segment.index]\n    }\n  }\n\n  const last = segments[segments.length - 1]\n  if (last === undefined) return\n\n  if (last.type === 'property') {\n    if (typeof current === 'object' && current !== null) {\n      ;(current as Record<string, unknown>)[last.key] = value\n    }\n  } else {\n    if (Array.isArray(current)) {\n      current[last.index] = value\n    }\n  }\n}\n\n/**\n * Deep-clone a plain object/array structure using structured clone\n * semantics (JSON round-trip for simplicity and zero dependencies).\n */\nfunction deepClone<T>(value: T): T {\n  if (value === undefined || value === null) return value\n  if (typeof value !== 'object') return value\n  return JSON.parse(JSON.stringify(value)) as T\n}\n\n// ============================================================\n// TWO-WAY BINDING INSTANCE (INTERNAL)\n// ============================================================\n\n/**\n * Internal class that implements a single two-way binding\n */\nclass TwoWayBindingInstance<T = unknown> implements TwoWayBinding<T> {\n  readonly path: string\n\n  private _value: T\n  private _initialValue: T\n  private _error: string | undefined\n  private _isDirty = false\n  private _isValidating = false\n  private _disposed = false\n\n  private readonly config: TwoWayBindingConfig\n  private readonly manager: TwoWayBindingManager\n  private debounceTimer: ReturnType<typeof setTimeout> | undefined\n\n  constructor(config: TwoWayBindingConfig, initialValue: T, manager: TwoWayBindingManager) {\n    this.path = config.path\n    this.config = config\n    this.manager = manager\n\n    // Apply toView transform for initial value\n    const viewValue = config.transform?.toView\n      ? (config.transform.toView(initialValue) as T)\n      : initialValue\n\n    this._value = viewValue\n    this._initialValue = deepClone(viewValue)\n  }\n\n  get value(): T {\n    return this._value\n  }\n\n  get error(): string | undefined {\n    return this._error\n  }\n\n  get isDirty(): boolean {\n    return this._isDirty\n  }\n\n  get isValidating(): boolean {\n    return this._isValidating\n  }\n\n  setValue(newValue: T): void {\n    if (this._disposed) return\n\n    const oldValue = this._value\n\n    // Run validation if configured\n    if (this.config.validate) {\n      this._isValidating = true\n      const result = this.config.validate(newValue)\n      this._isValidating = false\n\n      if (!result.valid) {\n        this._error = result.error\n        return\n      }\n    }\n\n    // Clear any previous error\n    this._error = undefined\n\n    // Update the local value\n    this._value = newValue\n\n    // Track dirty state\n    this._isDirty = !isEqual(newValue, this._initialValue)\n\n    // Debounced write-back to model\n    this.scheduleWriteBack(newValue, oldValue)\n  }\n\n  reset(): void {\n    if (this._disposed) return\n\n    const oldValue = this._value\n    this._value = deepClone(this._initialValue)\n    this._isDirty = false\n    this._error = undefined\n    this.clearDebounce()\n\n    // Write the reset value back to model immediately\n    const modelValue = this.config.transform?.toModel\n      ? this.config.transform.toModel(this._value)\n      : this._value\n\n    this.manager.setValueInternal(this.path, modelValue, oldValue)\n  }\n\n  dispose(): void {\n    if (this._disposed) return\n    this._disposed = true\n    this.clearDebounce()\n  }\n\n  /**\n   * Called by the manager when the model value changes externally\n   */\n  updateFromModel(modelValue: unknown): void {\n    if (this._disposed) return\n\n    const viewValue = this.config.transform?.toView\n      ? (this.config.transform.toView(modelValue) as T)\n      : (modelValue as T)\n\n    this._value = viewValue\n    this._isDirty = !isEqual(viewValue, this._initialValue)\n  }\n\n  private scheduleWriteBack(newValue: T, oldValue: T): void {\n    this.clearDebounce()\n\n    const delay = this.config.debounceMs ?? DEFAULT_DEBOUNCE_MS\n\n    if (delay <= 0) {\n      // Write immediately\n      this.writeBack(newValue, oldValue)\n      return\n    }\n\n    this.debounceTimer = setTimeout(() => {\n      this.debounceTimer = undefined\n      this.writeBack(newValue, oldValue)\n    }, delay)\n  }\n\n  private writeBack(newValue: T, oldValue: T): void {\n    if (this._disposed) return\n\n    // Apply toModel transform before writing back\n    const modelValue = this.config.transform?.toModel\n      ? this.config.transform.toModel(newValue)\n      : newValue\n\n    this.manager.setValueInternal(this.path, modelValue, oldValue)\n  }\n\n  private clearDebounce(): void {\n    if (this.debounceTimer !== undefined) {\n      clearTimeout(this.debounceTimer)\n      this.debounceTimer = undefined\n    }\n  }\n}\n\n// ============================================================\n// CONSTANTS\n// ============================================================\n\n/** Default debounce delay in milliseconds */\nconst DEFAULT_DEBOUNCE_MS = 300\n\n// ============================================================\n// UTILITY\n// ============================================================\n\n/**\n * Shallow equality check suitable for primitive and simple object values.\n * Uses JSON serialization for object comparison (safe for plain data).\n */\nfunction isEqual(a: unknown, b: unknown): boolean {\n  if (a === b) return true\n  if (a === null || b === null) return false\n  if (a === undefined || b === undefined) return false\n  if (typeof a !== typeof b) return false\n  if (typeof a === 'object') {\n    try {\n      return JSON.stringify(a) === JSON.stringify(b)\n    } catch {\n      return false\n    }\n  }\n  return false\n}\n\n// ============================================================\n// TWO-WAY BINDING MANAGER\n// ============================================================\n\n/**\n * Manages two-way data bindings.\n *\n * Provides a central data store with path-based access, change listeners,\n * validation, transforms, and batch update support. Each call to `bind()`\n * creates a `TwoWayBinding` instance that can read/write a specific path\n * in the data model.\n */\nexport class TwoWayBindingManager {\n  private readonly bindings = new Map<string, TwoWayBindingInstance>()\n  private data: Record<string, unknown>\n  private readonly listeners = new Map<string, Set<ChangeListener>>()\n  private batchDepth = 0\n  private readonly pendingNotifications: {\n    path: string\n    newValue: unknown\n    oldValue: unknown\n  }[] = []\n\n  constructor(initialData?: Record<string, unknown>) {\n    this.data = initialData ? deepClone(initialData) : {}\n  }\n\n  /**\n   * Create a two-way binding for a specific data path.\n   *\n   * Returns a `TwoWayBinding` instance that tracks the value at the path,\n   * supports validation and transforms, and writes changes back to the\n   * data model with optional debouncing.\n   */\n  bind<T = unknown>(config: TwoWayBindingConfig): TwoWayBinding<T> {\n    // Dispose any existing binding at this path\n    const existing = this.bindings.get(config.path)\n    if (existing) {\n      existing.dispose()\n    }\n\n    const currentValue = resolvePath(this.data, config.path) as T\n    const instance = new TwoWayBindingInstance<T>(config, currentValue, this)\n\n    this.bindings.set(config.path, instance as TwoWayBindingInstance)\n\n    return instance\n  }\n\n  /**\n   * Get the current value at a data path\n   */\n  getValue(path: string): unknown {\n    return resolvePath(this.data, path)\n  }\n\n  /**\n   * Set a value at a data path, triggering change listeners\n   */\n  setValue(path: string, value: unknown): void {\n    const oldValue = resolvePath(this.data, path)\n\n    // Write to data store\n    setAtPath(this.data, path, value)\n\n    // Update any binding watching this path\n    const binding = this.bindings.get(path)\n    if (binding) {\n      binding.updateFromModel(value)\n    }\n\n    // Notify listeners\n    this.notifyChange(path, value, oldValue)\n  }\n\n  /**\n   * Subscribe to changes at a data path.\n   *\n   * @returns Unsubscribe function\n   */\n  onChange<T = unknown>(path: string, listener: ChangeListener<T>): () => void {\n    let pathListeners = this.listeners.get(path)\n    if (!pathListeners) {\n      pathListeners = new Set<ChangeListener>()\n      this.listeners.set(path, pathListeners)\n    }\n\n    pathListeners.add(listener as ChangeListener)\n\n    return () => {\n      pathListeners.delete(listener as ChangeListener)\n      if (pathListeners.size === 0) {\n        this.listeners.delete(path)\n      }\n    }\n  }\n\n  /**\n   * Batch multiple updates together.\n   *\n   * Listener notifications are deferred until the outermost batch\n   * completes, then fired once per changed path.\n   */\n  batch(updates: () => void): void {\n    this.batchDepth++\n\n    try {\n      updates()\n    } finally {\n      this.batchDepth--\n\n      if (this.batchDepth === 0) {\n        this.flushPendingNotifications()\n      }\n    }\n  }\n\n  /**\n   * Get all bindings that have been modified from their initial values\n   */\n  getDirtyBindings(): readonly TwoWayBinding[] {\n    const dirty: TwoWayBinding[] = []\n\n    for (const binding of this.bindings.values()) {\n      if (binding.isDirty) {\n        dirty.push(binding)\n      }\n    }\n\n    return dirty\n  }\n\n  /**\n   * Reset all bindings to their initial values\n   */\n  resetAll(): void {\n    for (const binding of this.bindings.values()) {\n      binding.reset()\n    }\n  }\n\n  /**\n   * Dispose all bindings and clear all listeners\n   */\n  dispose(): void {\n    for (const binding of this.bindings.values()) {\n      binding.dispose()\n    }\n    this.bindings.clear()\n    this.listeners.clear()\n    this.pendingNotifications.length = 0\n  }\n\n  /**\n   * Internal method called by binding instances to write back to the model.\n   * Not part of the public API.\n   */\n  setValueInternal(path: string, modelValue: unknown, oldViewValue: unknown): void {\n    const oldModelValue = resolvePath(this.data, path)\n\n    // Write to data store\n    setAtPath(this.data, path, modelValue)\n\n    // Notify listeners with model values\n    this.notifyChange(path, modelValue, oldModelValue ?? oldViewValue)\n  }\n\n  // ============================================================\n  // PRIVATE\n  // ============================================================\n\n  private notifyChange(path: string, newValue: unknown, oldValue: unknown): void {\n    if (this.batchDepth > 0) {\n      // During batch, accumulate notifications (last write wins per path)\n      const existingIdx = this.pendingNotifications.findIndex((n) => n.path === path)\n      if (existingIdx >= 0) {\n        const existing = this.pendingNotifications[existingIdx]\n        if (existing) {\n          // Keep the original oldValue, update newValue\n          this.pendingNotifications[existingIdx] = {\n            path,\n            newValue,\n            oldValue: existing.oldValue,\n          }\n        }\n      } else {\n        this.pendingNotifications.push({ path, newValue, oldValue })\n      }\n      return\n    }\n\n    this.fireListeners(path, newValue, oldValue)\n  }\n\n  private flushPendingNotifications(): void {\n    // Copy and clear to handle re-entrant batch calls\n    const pending = [...this.pendingNotifications]\n    this.pendingNotifications.length = 0\n\n    for (const { path, newValue, oldValue } of pending) {\n      this.fireListeners(path, newValue, oldValue)\n    }\n  }\n\n  private fireListeners(path: string, newValue: unknown, oldValue: unknown): void {\n    const pathListeners = this.listeners.get(path)\n    if (!pathListeners) return\n\n    for (const listener of pathListeners) {\n      try {\n        listener(newValue, oldValue)\n      } catch {\n        // Swallow errors from listeners to prevent cascade failures\n      }\n    }\n  }\n}\n\n// ============================================================\n// FACTORY\n// ============================================================\n\n/**\n * Create a two-way binding manager\n *\n * @param initialData - Optional initial data to populate the model\n * @returns A new TwoWayBindingManager instance\n *\n * @example\n * ```ts\n * const manager = createTwoWayBindingManager({\n *   user: { name: 'John', email: 'john@example.com' }\n * })\n *\n * const nameBinding = manager.bind<string>({\n *   path: 'user.name',\n *   debounceMs: 200,\n *   validate: (v) => ({\n *     valid: typeof v === 'string' && v.length > 0,\n *     error: 'Name is required',\n *   }),\n * })\n *\n * nameBinding.setValue('Jane')\n * // After debounce, manager.getValue('user.name') === 'Jane'\n * ```\n */\nexport function createTwoWayBindingManager(\n  initialData?: Record<string, unknown>\n): TwoWayBindingManager {\n  return new TwoWayBindingManager(initialData)\n}\n"]}

package/dist/binding/types.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Binding System Types
+ *
+ * Types for capability-to-surface binding
+ *
+ * @module @pwfabric/runtime/binding/types
+ */
+import type { CapabilityId, SurfaceId, ExecutionResult } from '@pwfabric/contracts';
+/**
+ * Binding state
+ */
+export type BindingState = 'unbound' | 'binding' | 'bound' | 'error' | 'stale';
+/**
+ * Binding configuration
+ */
+export interface BindingConfig {
+    readonly capabilityId: CapabilityId;
+    readonly alias?: string;
+    readonly transform?: RuntimeBindingTransform;
+    readonly cache?: BindingCacheConfig;
+    readonly retry?: RetryConfig;
+}
+/**
+ * Transform configuration for binding input/output (runtime version)
+ * Named differently from contracts BindingTransform to avoid export collision
+ */
+export interface RuntimeBindingTransform {
+    readonly input?: (data: unknown) => unknown;
+    readonly output?: (data: unknown) => unknown;
+}
+/**
+ * Cache configuration for binding (runtime version)
+ * Named differently from contracts CacheConfig to avoid export collision
+ */
+export interface BindingCacheConfig {
+    readonly enabled: boolean;
+    readonly ttl?: number;
+    readonly key?: string;
+}
+/**
+ * Retry configuration
+ */
+export interface RetryConfig {
+    readonly maxAttempts: number;
+    readonly backoff: 'fixed' | 'exponential';
+    readonly delayMs: number;
+}
+/**
+ * A bound capability instance
+ */
+export interface BoundCapability<TInput = unknown, TOutput = unknown> {
+    readonly id: string;
+    readonly capabilityId: CapabilityId;
+    readonly state: BindingState;
+    readonly config: BindingConfig;
+    readonly lastExecuted?: number;
+    readonly lastResult?: ExecutionResult<TOutput>;
+    readonly error?: BindingError;
+    /**
+     * Execute the bound capability
+     */
+    execute(input: TInput): Promise<ExecutionResult<TOutput>>;
+    /**
+     * Refresh the binding (re-execute with last input)
+     */
+    refresh(): Promise<ExecutionResult<TOutput>>;
+    /**
+     * Invalidate cached data
+     */
+    invalidate(): void;
+}
+/**
+ * Binding error
+ */
+export interface BindingError {
+    readonly type: 'resolution_failed' | 'execution_failed' | 'transform_failed' | 'cache_failed';
+    readonly message: string;
+    readonly cause?: unknown;
+}
+/**
+ * Context for binding resolution
+ */
+export interface BindingContext {
+    readonly surfaceId: SurfaceId;
+    readonly auth?: AuthContext;
+    readonly data: Record<string, unknown>;
+    readonly bindings: Map<string, BoundCapability>;
+}
+/**
+ * Authentication context
+ */
+export interface AuthContext {
+    readonly isAuthenticated: boolean;
+    readonly userId?: string;
+    readonly worldId?: string;
+    readonly scopes?: readonly string[];
+    readonly token?: string;
+    readonly expiresAt?: number;
+}
+/**
+ * Result of binding resolution
+ */
+export type BindingResult<T = unknown> = {
+    readonly success: true;
+    readonly binding: BoundCapability<unknown, T>;
+} | {
+    readonly success: false;
+    readonly error: BindingError;
+};
+/**
+ * Result of binding all capabilities for a surface
+ */
+export type SurfaceBindingResult = {
+    readonly success: true;
+    readonly context: BindingContext;
+} | {
+    readonly success: false;
+    readonly errors: readonly BindingError[];
+};

package/dist/binding/types.js

@@ -0,0 +1,9 @@
+/**
+ * Binding System Types
+ *
+ * Types for capability-to-surface binding
+ *
+ * @module @pwfabric/runtime/binding/types
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/binding/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/binding/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG","sourcesContent":["/**\n * Binding System Types\n *\n * Types for capability-to-surface binding\n *\n * @module @pwfabric/runtime/binding/types\n */\n\nimport type { CapabilityId, SurfaceId, ExecutionResult } from '@pwfabric/contracts'\n\n// ============================================================\n// BINDING TYPES\n// ============================================================\n\n/**\n * Binding state\n */\nexport type BindingState = 'unbound' | 'binding' | 'bound' | 'error' | 'stale'\n\n/**\n * Binding configuration\n */\nexport interface BindingConfig {\n  readonly capabilityId: CapabilityId\n  readonly alias?: string\n  readonly transform?: RuntimeBindingTransform\n  readonly cache?: BindingCacheConfig\n  readonly retry?: RetryConfig\n}\n\n/**\n * Transform configuration for binding input/output (runtime version)\n * Named differently from contracts BindingTransform to avoid export collision\n */\nexport interface RuntimeBindingTransform {\n  readonly input?: (data: unknown) => unknown\n  readonly output?: (data: unknown) => unknown\n}\n\n/**\n * Cache configuration for binding (runtime version)\n * Named differently from contracts CacheConfig to avoid export collision\n */\nexport interface BindingCacheConfig {\n  readonly enabled: boolean\n  readonly ttl?: number\n  readonly key?: string\n}\n\n/**\n * Retry configuration\n */\nexport interface RetryConfig {\n  readonly maxAttempts: number\n  readonly backoff: 'fixed' | 'exponential'\n  readonly delayMs: number\n}\n\n// ============================================================\n// BINDING INSTANCE\n// ============================================================\n\n/**\n * A bound capability instance\n */\nexport interface BoundCapability<TInput = unknown, TOutput = unknown> {\n  readonly id: string\n  readonly capabilityId: CapabilityId\n  readonly state: BindingState\n  readonly config: BindingConfig\n  readonly lastExecuted?: number\n  readonly lastResult?: ExecutionResult<TOutput>\n  readonly error?: BindingError\n\n  /**\n   * Execute the bound capability\n   */\n  execute(input: TInput): Promise<ExecutionResult<TOutput>>\n\n  /**\n   * Refresh the binding (re-execute with last input)\n   */\n  refresh(): Promise<ExecutionResult<TOutput>>\n\n  /**\n   * Invalidate cached data\n   */\n  invalidate(): void\n}\n\n/**\n * Binding error\n */\nexport interface BindingError {\n  readonly type: 'resolution_failed' | 'execution_failed' | 'transform_failed' | 'cache_failed'\n  readonly message: string\n  readonly cause?: unknown\n}\n\n// ============================================================\n// BINDING CONTEXT\n// ============================================================\n\n/**\n * Context for binding resolution\n */\nexport interface BindingContext {\n  readonly surfaceId: SurfaceId\n  readonly auth?: AuthContext\n  readonly data: Record<string, unknown>\n  readonly bindings: Map<string, BoundCapability>\n}\n\n/**\n * Authentication context\n */\nexport interface AuthContext {\n  readonly isAuthenticated: boolean\n  readonly userId?: string\n  readonly worldId?: string\n  readonly scopes?: readonly string[]\n  readonly token?: string\n  readonly expiresAt?: number\n}\n\n// ============================================================\n// BINDING RESULT\n// ============================================================\n\n/**\n * Result of binding resolution\n */\nexport type BindingResult<T = unknown> =\n  | { readonly success: true; readonly binding: BoundCapability<unknown, T> }\n  | { readonly success: false; readonly error: BindingError }\n\n/**\n * Result of binding all capabilities for a surface\n */\nexport type SurfaceBindingResult =\n  | { readonly success: true; readonly context: BindingContext }\n  | { readonly success: false; readonly errors: readonly BindingError[] }\n"]}