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

package/dist/perf/web-vitals.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"web-vitals.js","sourceRoot":"","sources":["../../src/perf/web-vitals.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Core Web Vitals Collection\n *\n * Collects Core Web Vitals (LCP, FID, CLS, FCP, TTFB, INP) using\n * PerformanceObserver. Provides real-time metric collection with\n * rating classification based on web.dev thresholds.\n *\n * All browser APIs are guarded for SSR safety.\n *\n * @module @pwfabric/runtime/perf\n */\n\n// ============================================================\n// TYPES\n// ============================================================\n\n/** Web Vital metric names */\nexport type WebVitalName = 'LCP' | 'FID' | 'CLS' | 'FCP' | 'TTFB' | 'INP'\n\n/** Rating classification for a metric */\nexport type WebVitalRating = 'good' | 'needs-improvement' | 'poor'\n\n/** A single Web Vital measurement */\nexport interface WebVitalMetric {\n  /** Metric name */\n  readonly name: WebVitalName\n  /** Metric value (ms for timing metrics, unitless for CLS) */\n  readonly value: number\n  /** Rating based on web.dev thresholds */\n  readonly rating: WebVitalRating\n  /** Timestamp when the metric was collected */\n  readonly timestamp: number\n}\n\n/** Callback invoked when a metric is collected */\nexport type WebVitalCallback = (metric: WebVitalMetric) => void\n\n/** Aggregated report of all collected Web Vitals */\nexport interface WebVitalsReport {\n  /** Largest Contentful Paint */\n  readonly lcp?: WebVitalMetric | undefined\n  /** First Input Delay */\n  readonly fid?: WebVitalMetric | undefined\n  /** Cumulative Layout Shift */\n  readonly cls?: WebVitalMetric | undefined\n  /** First Contentful Paint */\n  readonly fcp?: WebVitalMetric | undefined\n  /** Time to First Byte */\n  readonly ttfb?: WebVitalMetric | undefined\n  /** Interaction to Next Paint */\n  readonly inp?: WebVitalMetric | undefined\n  /** Timestamp when the report was generated */\n  readonly collectedAt: number\n}\n\n// ============================================================\n// THRESHOLDS (from web.dev)\n// ============================================================\n\n/** Rating thresholds: [goodThreshold, poorThreshold] */\nconst THRESHOLDS: Record<WebVitalName, readonly [number, number]> = {\n  LCP: [2500, 4000],\n  FID: [100, 300],\n  CLS: [0.1, 0.25],\n  FCP: [1800, 3000],\n  TTFB: [800, 1800],\n  INP: [200, 500],\n} as const\n\n// ============================================================\n// UTILITY\n// ============================================================\n\n/**\n * Rate a metric value against web.dev thresholds.\n *\n * @param name - The metric name\n * @param value - The measured value\n * @returns The rating classification\n */\nexport function rateMetric(name: WebVitalName, value: number): WebVitalRating {\n  const threshold = THRESHOLDS[name]\n  if (!threshold) {\n    return 'good'\n  }\n  if (value <= threshold[0]) {\n    return 'good'\n  }\n  if (value > threshold[1]) {\n    return 'poor'\n  }\n  return 'needs-improvement'\n}\n\n// ============================================================\n// COLLECTOR\n// ============================================================\n\n/**\n * Collects Core Web Vitals using PerformanceObserver.\n *\n * Supports LCP, FID, CLS, FCP, TTFB, and INP metrics.\n * All observers are cleaned up on dispose.\n */\nexport class WebVitalsCollector {\n  private metrics = new Map<WebVitalName, WebVitalMetric>()\n  private observers: PerformanceObserver[] = []\n  private callbacks = new Map<WebVitalName, WebVitalCallback[]>()\n  private clsValue = 0\n  private clsSessionEntries: PerformanceEntry[] = []\n  private clsSessionValue = 0\n\n  /**\n   * Start collecting all Web Vitals.\n   *\n   * Creates PerformanceObservers for each metric type.\n   * Safe to call in SSR environments (no-ops silently).\n   */\n  startCollecting(): void {\n    if (typeof PerformanceObserver === 'undefined') {\n      return\n    }\n\n    this.observeLCP()\n    this.observeFID()\n    this.observeCLS()\n    this.observeFCP()\n    this.observeTTFB()\n    this.observeINP()\n  }\n\n  /**\n   * Register a callback for a specific metric.\n   *\n   * The callback fires each time the metric is updated.\n   *\n   * @param name - The metric name to observe\n   * @param callback - Function to call with the metric\n   */\n  onMetric(name: WebVitalName, callback: WebVitalCallback): void {\n    const existing = this.callbacks.get(name) ?? []\n    existing.push(callback)\n    this.callbacks.set(name, existing)\n  }\n\n  /**\n   * Get the current Web Vitals report.\n   *\n   * @returns A snapshot of all collected metrics\n   */\n  getReport(): WebVitalsReport {\n    return {\n      lcp: this.metrics.get('LCP'),\n      fid: this.metrics.get('FID'),\n      cls: this.metrics.get('CLS'),\n      fcp: this.metrics.get('FCP'),\n      ttfb: this.metrics.get('TTFB'),\n      inp: this.metrics.get('INP'),\n      collectedAt: Date.now(),\n    }\n  }\n\n  /**\n   * Stop collecting metrics and disconnect all observers.\n   */\n  stopCollecting(): void {\n    for (const observer of this.observers) {\n      observer.disconnect()\n    }\n    this.observers = []\n  }\n\n  /**\n   * Stop collecting and clear all state.\n   */\n  dispose(): void {\n    this.stopCollecting()\n    this.metrics.clear()\n    this.callbacks.clear()\n    this.clsValue = 0\n    this.clsSessionEntries = []\n    this.clsSessionValue = 0\n  }\n\n  // ----------------------------------------------------------\n  // Private: metric recording\n  // ----------------------------------------------------------\n\n  private recordMetric(name: WebVitalName, value: number): void {\n    const metric: WebVitalMetric = {\n      name,\n      value,\n      rating: rateMetric(name, value),\n      timestamp: Date.now(),\n    }\n    this.metrics.set(name, metric)\n\n    const cbs = this.callbacks.get(name)\n    if (cbs) {\n      for (const cb of cbs) {\n        cb(metric)\n      }\n    }\n  }\n\n  // ----------------------------------------------------------\n  // Private: observer helpers\n  // ----------------------------------------------------------\n\n  private tryObserve(\n    entryType: string,\n    handler: (entries: PerformanceEntryList) => void,\n    options?: { buffered?: boolean; type?: string }\n  ): void {\n    try {\n      const observer = new PerformanceObserver((list) => {\n        handler(list.getEntries())\n      })\n      const observeOptions: PerformanceObserverInit = {\n        type: options?.type ?? entryType,\n        buffered: options?.buffered ?? true,\n      }\n      observer.observe(observeOptions)\n      this.observers.push(observer)\n    } catch {\n      // Entry type not supported in this browser — silently skip\n    }\n  }\n\n  private observeLCP(): void {\n    this.tryObserve('largest-contentful-paint', (entries) => {\n      const last = entries[entries.length - 1]\n      if (last) {\n        this.recordMetric('LCP', last.startTime)\n      }\n    })\n  }\n\n  private observeFID(): void {\n    this.tryObserve('first-input', (entries) => {\n      const first = entries[0]\n      if (first) {\n        const fidEntry = first as PerformanceEventTiming\n        this.recordMetric('FID', fidEntry.processingStart - fidEntry.startTime)\n      }\n    })\n  }\n\n  private observeCLS(): void {\n    this.tryObserve('layout-shift', (entries) => {\n      for (const entry of entries) {\n        const lsEntry = entry as LayoutShiftEntry\n        // Only count shifts without recent user input\n        if (!lsEntry.hadRecentInput) {\n          // Session window algorithm\n          if (\n            this.clsSessionEntries.length > 0 &&\n            entry.startTime -\n              (this.clsSessionEntries[this.clsSessionEntries.length - 1]?.startTime ?? 0) >\n              1000\n          ) {\n            // Gap > 1s → start new session window\n            if (this.clsSessionValue > this.clsValue) {\n              this.clsValue = this.clsSessionValue\n            }\n            this.clsSessionEntries = []\n            this.clsSessionValue = 0\n          }\n\n          // Add to current session\n          if (\n            this.clsSessionEntries.length === 0 ||\n            entry.startTime - (this.clsSessionEntries[0]?.startTime ?? 0) <= 5000\n          ) {\n            this.clsSessionEntries.push(entry)\n            this.clsSessionValue += lsEntry.value\n          } else {\n            // Session exceeded 5s → start new session\n            if (this.clsSessionValue > this.clsValue) {\n              this.clsValue = this.clsSessionValue\n            }\n            this.clsSessionEntries = [entry]\n            this.clsSessionValue = lsEntry.value\n          }\n\n          // Report the max of current session and previous max\n          const currentCls = Math.max(this.clsValue, this.clsSessionValue)\n          this.recordMetric('CLS', currentCls)\n        }\n      }\n    })\n  }\n\n  private observeFCP(): void {\n    this.tryObserve('paint', (entries) => {\n      const fcp = entries.find((e) => e.name === 'first-contentful-paint')\n      if (fcp) {\n        this.recordMetric('FCP', fcp.startTime)\n      }\n    })\n  }\n\n  private observeTTFB(): void {\n    this.tryObserve('navigation', (entries) => {\n      const nav = entries[0] as PerformanceNavigationTiming | undefined\n      if (nav) {\n        this.recordMetric('TTFB', nav.responseStart)\n      }\n    })\n  }\n\n  private observeINP(): void {\n    this.tryObserve(\n      'event',\n      (entries) => {\n        let maxDuration = 0\n        for (const entry of entries) {\n          const eventEntry = entry as PerformanceEventTiming\n          if (eventEntry.duration > maxDuration) {\n            maxDuration = eventEntry.duration\n          }\n        }\n        if (maxDuration > 0) {\n          const existing = this.metrics.get('INP')\n          // INP tracks the worst interaction\n          if (!existing || maxDuration > existing.value) {\n            this.recordMetric('INP', maxDuration)\n          }\n        }\n      },\n      { type: 'event', buffered: true }\n    )\n  }\n}\n\n// ============================================================\n// LAYOUT SHIFT ENTRY TYPE (not in all TS libs)\n// ============================================================\n\ninterface LayoutShiftEntry extends PerformanceEntry {\n  readonly hadRecentInput: boolean\n  readonly value: number\n}\n\ninterface PerformanceEventTiming extends PerformanceEntry {\n  readonly processingStart: number\n  readonly duration: number\n}\n\n// ============================================================\n// FACTORY\n// ============================================================\n\n/**\n * Create a new WebVitalsCollector instance.\n *\n * @returns A new collector (not yet started)\n */\nexport function createWebVitalsCollector(): WebVitalsCollector {\n  return new WebVitalsCollector()\n}\n"]}

package/dist/registry.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Capability Registry
+ *
+ * Registry for managing capability registration and lookup
+ *
+ * @module @pwfabric/runtime/registry
+ */
+import type { CapabilityId, Capability, RegistrationResult, Resolution } from '@pwfabric/contracts';
+/**
+ * Capability registry for managing registered capabilities
+ */
+export interface CapabilityRegistry {
+    /**
+     * Register a capability
+     */
+    register<C extends Capability>(capability: C): RegistrationResult<C>;
+    /**
+     * Unregister a capability
+     */
+    unregister(id: CapabilityId): boolean;
+    /**
+     * Resolve a capability by ID
+     */
+    resolve<C extends Capability>(id: CapabilityId): Resolution<C>;
+    /**
+     * Check if a capability is registered
+     */
+    has(id: CapabilityId): boolean;
+    /**
+     * Get all registered capability IDs
+     */
+    list(): readonly CapabilityId[];
+    /**
+     * Get the count of registered capabilities
+     */
+    size(): number;
+    /**
+     * Clear all registered capabilities
+     */
+    clear(): void;
+}
+/**
+ * In-memory capability registry
+ */
+export declare class InMemoryCapabilityRegistry implements CapabilityRegistry {
+    private readonly capabilities;
+    private readonly dependencyGraph;
+    register<C extends Capability>(capability: C): RegistrationResult<C>;
+    unregister(id: CapabilityId): boolean;
+    resolve<C extends Capability>(id: CapabilityId): Resolution<C>;
+    has(id: CapabilityId): boolean;
+    list(): readonly CapabilityId[];
+    size(): number;
+    clear(): void;
+    /**
+     * Detect circular dependencies using DFS
+     */
+    private detectCircularDependency;
+}
+/**
+ * Create a new capability registry
+ */
+export declare function createRegistry(): CapabilityRegistry;

package/dist/registry.js

@@ -0,0 +1,126 @@
+/**
+ * Capability Registry
+ *
+ * Registry for managing capability registration and lookup
+ *
+ * @module @pwfabric/runtime/registry
+ */
+// ============================================================
+// IN-MEMORY REGISTRY IMPLEMENTATION
+// ============================================================
+/**
+ * In-memory capability registry
+ */
+export class InMemoryCapabilityRegistry {
+    capabilities = new Map();
+    dependencyGraph = new Map();
+    register(capability) {
+        const { id, dependencies } = capability;
+        // Check if already registered
+        if (this.capabilities.has(id)) {
+            const error = {
+                type: 'already_registered',
+                id,
+            };
+            return { success: false, error };
+        }
+        // Validate dependencies exist
+        for (const depId of dependencies) {
+            if (!this.capabilities.has(depId)) {
+                const error = {
+                    type: 'missing_dependency',
+                    id,
+                    missing: depId,
+                };
+                return { success: false, error };
+            }
+        }
+        // Check for circular dependencies
+        const cycle = this.detectCircularDependency(id, dependencies);
+        if (cycle) {
+            const error = {
+                type: 'circular_dependency',
+                cycle,
+            };
+            return { success: false, error };
+        }
+        // Register the capability
+        this.capabilities.set(id, capability);
+        this.dependencyGraph.set(id, new Set(dependencies));
+        return { success: true, capability };
+    }
+    unregister(id) {
+        if (!this.capabilities.has(id)) {
+            return false;
+        }
+        // Check if other capabilities depend on this one
+        for (const [, deps] of this.dependencyGraph) {
+            if (deps.has(id)) {
+                // Cannot unregister - something depends on it
+                return false;
+            }
+        }
+        this.capabilities.delete(id);
+        this.dependencyGraph.delete(id);
+        return true;
+    }
+    resolve(id) {
+        const capability = this.capabilities.get(id);
+        if (!capability) {
+            const reason = {
+                type: 'not_found',
+                id,
+            };
+            return { found: false, reason };
+        }
+        return { found: true, capability: capability };
+    }
+    has(id) {
+        return this.capabilities.has(id);
+    }
+    list() {
+        return Array.from(this.capabilities.keys());
+    }
+    size() {
+        return this.capabilities.size;
+    }
+    clear() {
+        this.capabilities.clear();
+        this.dependencyGraph.clear();
+    }
+    /**
+     * Detect circular dependencies using DFS
+     */
+    detectCircularDependency(newId, newDeps) {
+        const visited = new Set();
+        const path = [];
+        const dfs = (id) => {
+            if (path.includes(id)) {
+                // Found a cycle
+                const cycleStart = path.indexOf(id);
+                return [...path.slice(cycleStart), id];
+            }
+            if (visited.has(id)) {
+                return null;
+            }
+            visited.add(id);
+            path.push(id);
+            const deps = id === newId ? newDeps : Array.from(this.dependencyGraph.get(id) || []);
+            for (const depId of deps) {
+                const cycle = dfs(depId);
+                if (cycle)
+                    return cycle;
+            }
+            path.pop();
+            return null;
+        };
+        return dfs(newId);
+    }
+}
+/**
+ * Create a new capability registry
+ */
+export function createRegistry() {
+    return new InMemoryCapabilityRegistry();
+}
+//# sourceMappingURL=registry.js.map

package/dist/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Capability Registry\n *\n * Registry for managing capability registration and lookup\n *\n * @module @pwfabric/runtime/registry\n */\n\nimport type {\n  CapabilityId,\n  Capability,\n  RegistrationResult,\n  RegistrationError,\n  Resolution,\n  ResolutionFailure,\n} from '@pwfabric/contracts'\n\n// ============================================================\n// REGISTRY INTERFACE\n// ============================================================\n\n/**\n * Capability registry for managing registered capabilities\n */\nexport interface CapabilityRegistry {\n  /**\n   * Register a capability\n   */\n  register<C extends Capability>(capability: C): RegistrationResult<C>\n\n  /**\n   * Unregister a capability\n   */\n  unregister(id: CapabilityId): boolean\n\n  /**\n   * Resolve a capability by ID\n   */\n  resolve<C extends Capability>(id: CapabilityId): Resolution<C>\n\n  /**\n   * Check if a capability is registered\n   */\n  has(id: CapabilityId): boolean\n\n  /**\n   * Get all registered capability IDs\n   */\n  list(): readonly CapabilityId[]\n\n  /**\n   * Get the count of registered capabilities\n   */\n  size(): number\n\n  /**\n   * Clear all registered capabilities\n   */\n  clear(): void\n}\n\n// ============================================================\n// IN-MEMORY REGISTRY IMPLEMENTATION\n// ============================================================\n\n/**\n * In-memory capability registry\n */\nexport class InMemoryCapabilityRegistry implements CapabilityRegistry {\n  private readonly capabilities = new Map<CapabilityId, Capability>()\n  private readonly dependencyGraph = new Map<CapabilityId, Set<CapabilityId>>()\n\n  register<C extends Capability>(capability: C): RegistrationResult<C> {\n    const { id, dependencies } = capability\n\n    // Check if already registered\n    if (this.capabilities.has(id)) {\n      const error: RegistrationError = {\n        type: 'already_registered',\n        id,\n      }\n      return { success: false, error }\n    }\n\n    // Validate dependencies exist\n    for (const depId of dependencies) {\n      if (!this.capabilities.has(depId)) {\n        const error: RegistrationError = {\n          type: 'missing_dependency',\n          id,\n          missing: depId,\n        }\n        return { success: false, error }\n      }\n    }\n\n    // Check for circular dependencies\n    const cycle = this.detectCircularDependency(id, dependencies)\n    if (cycle) {\n      const error: RegistrationError = {\n        type: 'circular_dependency',\n        cycle,\n      }\n      return { success: false, error }\n    }\n\n    // Register the capability\n    this.capabilities.set(id, capability)\n    this.dependencyGraph.set(id, new Set(dependencies))\n\n    return { success: true, capability }\n  }\n\n  unregister(id: CapabilityId): boolean {\n    if (!this.capabilities.has(id)) {\n      return false\n    }\n\n    // Check if other capabilities depend on this one\n    for (const [, deps] of this.dependencyGraph) {\n      if (deps.has(id)) {\n        // Cannot unregister - something depends on it\n        return false\n      }\n    }\n\n    this.capabilities.delete(id)\n    this.dependencyGraph.delete(id)\n    return true\n  }\n\n  resolve<C extends Capability>(id: CapabilityId): Resolution<C> {\n    const capability = this.capabilities.get(id)\n\n    if (!capability) {\n      const reason: ResolutionFailure = {\n        type: 'not_found',\n        id,\n      }\n      return { found: false, reason }\n    }\n\n    return { found: true, capability: capability as C }\n  }\n\n  has(id: CapabilityId): boolean {\n    return this.capabilities.has(id)\n  }\n\n  list(): readonly CapabilityId[] {\n    return Array.from(this.capabilities.keys())\n  }\n\n  size(): number {\n    return this.capabilities.size\n  }\n\n  clear(): void {\n    this.capabilities.clear()\n    this.dependencyGraph.clear()\n  }\n\n  /**\n   * Detect circular dependencies using DFS\n   */\n  private detectCircularDependency(\n    newId: CapabilityId,\n    newDeps: readonly CapabilityId[]\n  ): readonly CapabilityId[] | null {\n    const visited = new Set<CapabilityId>()\n    const path: CapabilityId[] = []\n\n    const dfs = (id: CapabilityId): readonly CapabilityId[] | null => {\n      if (path.includes(id)) {\n        // Found a cycle\n        const cycleStart = path.indexOf(id)\n        return [...path.slice(cycleStart), id]\n      }\n\n      if (visited.has(id)) {\n        return null\n      }\n\n      visited.add(id)\n      path.push(id)\n\n      const deps = id === newId ? newDeps : Array.from(this.dependencyGraph.get(id) || [])\n      for (const depId of deps) {\n        const cycle = dfs(depId)\n        if (cycle) return cycle\n      }\n\n      path.pop()\n      return null\n    }\n\n    return dfs(newId)\n  }\n}\n\n/**\n * Create a new capability registry\n */\nexport function createRegistry(): CapabilityRegistry {\n  return new InMemoryCapabilityRegistry()\n}\n"]}

package/dist/render/BehaviorSurfaceProvider.d.ts

@@ -0,0 +1,65 @@
+/**
+ * BehaviorSurfaceProvider
+ *
+ * React provider that wraps a surface render session with a
+ * stable `SurfaceEventBus` instance and the real `surfaceId`.
+ *
+ * When `entityFormBindings` are supplied and an EntityFacade
+ * is available via EntityFacadeContext, automatically attaches form→entity
+ * bridges on mount and tears them down on unmount.
+ *
+ * All block children receive both values via context so they can emit events
+ * that carry a meaningful surface ID without prop-drilling.
+ *
+ * Lifecycle:
+ * - Emits `surface:load` on mount
+ * - Emits `surface:unload` on unmount
+ * - Re-creates the bus (and re-emits lifecycle events) when `surfaceId` changes
+ *
+ * @module @pwfabric/runtime/render/BehaviorSurfaceProvider
+ */
+import * as React from 'react';
+import type { SurfaceEventDescriptor } from '@pwfabric/contracts';
+import type { SurfaceDataSourceDefinition } from './data-binding-types.js';
+import type { FormEntityBridgeConfig } from '../forms/form-entity-bridge.js';
+import type { Block } from '@pwfabric/core';
+export interface BehaviorSurfaceProviderProps {
+    /** The ID of the surface being rendered */
+    readonly surfaceId: string;
+    /** Block render tree */
+    readonly children: React.ReactNode;
+    /**
+     * Declarative form→entity bridge configurations extracted
+     * from `surface.capabilities` (platform/entities config.formBindings).
+     * When provided and EntityFacade is available, bridges are auto-attached on
+     * mount and torn down on unmount.
+     */
+    readonly entityFormBindings?: readonly FormEntityBridgeConfig[];
+    /**
+     * The read sources, so a form's `sourceId` can be resolved to a destination.
+     * A source that names an entity type writes through the facade; anything
+     * else is an address and writes over HTTP.
+     */
+    readonly dataSources?: readonly SurfaceDataSourceDefinition[];
+    /**
+     * The surface renderer's single event handler. Subscribed to the bus via the
+     * global `*` wildcard so EVERY block-emitted event (with its full payload,
+     * incl. a declarative `action`) reaches the action dispatcher + host
+     * notification — the canonical path replacing the retired legacy
+     * `context.onEvent` shim that blocks used to call directly.
+     */
+    readonly onEvent?: (event: SurfaceEventDescriptor) => void;
+    /**
+     * The rendered (resolved) block tree, so a form's submission can be
+     * completed with the named controls inside it that `FormData` cannot see —
+     * read from page state by their `stateKey`.
+     */
+    readonly blocks?: readonly Block[];
+}
+/**
+ * Wraps a surface render tree with a scoped `SurfaceEventBus` and `surfaceId`.
+ *
+ * Place this as the outermost wrapper inside `SurfaceRenderer` so every block
+ * in the tree can call `useSurfaceEvents()` and `useSurfaceId()`.
+ */
+export declare function BehaviorSurfaceProvider({ surfaceId, children, entityFormBindings, dataSources, onEvent, blocks, }: BehaviorSurfaceProviderProps): React.ReactElement;

package/dist/render/BehaviorSurfaceProvider.js

@@ -0,0 +1,185 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * BehaviorSurfaceProvider
+ *
+ * React provider that wraps a surface render session with a
+ * stable `SurfaceEventBus` instance and the real `surfaceId`.
+ *
+ * When `entityFormBindings` are supplied and an EntityFacade
+ * is available via EntityFacadeContext, automatically attaches form→entity
+ * bridges on mount and tears them down on unmount.
+ *
+ * All block children receive both values via context so they can emit events
+ * that carry a meaningful surface ID without prop-drilling.
+ *
+ * Lifecycle:
+ * - Emits `surface:load` on mount
+ * - Emits `surface:unload` on unmount
+ * - Re-creates the bus (and re-emits lifecycle events) when `surfaceId` changes
+ *
+ * @module @pwfabric/runtime/render/BehaviorSurfaceProvider
+ */
+import * as React from 'react';
+import { SURFACE_EVENTS } from '@pwfabric/contracts';
+import { SurfaceEventContext } from './surface-event-context.js';
+import { SurfaceIdContext } from './surface-id-context.js';
+import { createSurfaceEventBus } from './surface-event-bus.js';
+import { useEntityFacade } from './entity-facade-context.js';
+import { useOptionalDataService } from '../data/DataCapabilityProvider.js';
+import { useSurfaceData } from './surface-data-context.js';
+import { attachFormEntityBridge } from '../forms/form-entity-bridge.js';
+import { resolveFormWriteTarget, toFormWriteError } from '../forms/form-write-target.js';
+import { completeNamedControlValues } from '../forms/named-control-values.js';
+/**
+ * Wraps a surface render tree with a scoped `SurfaceEventBus` and `surfaceId`.
+ *
+ * Place this as the outermost wrapper inside `SurfaceRenderer` so every block
+ * in the tree can call `useSurfaceEvents()` and `useSurfaceId()`.
+ */
+export function BehaviorSurfaceProvider({ surfaceId, children, entityFormBindings, dataSources, onEvent, blocks, }) {
+    // Canonical event path: the renderer's handler is subscribed to the global `*`
+    // wildcard. Every block emits through the bus (useSurfaceEvents) → this handler
+    // dispatches declarative actions (setState/refresh) + forwards to the host.
+    // A ref keeps the subscription stable while always calling the latest handler.
+    const onEventRef = React.useRef(onEvent);
+    onEventRef.current = onEvent;
+    // Re-create the bus when surfaceId changes so sibling surfaces stay isolated.
+    //
+    // The `*` subscription is attached HERE, at construction, rather than in an
+    // effect. `bus.emit` is synchronous and unbuffered: an event emitted while
+    // `handlers.get('*')` is empty is dropped and never replayed. React runs
+    // effects CHILD-FIRST, so a subscription owned by this provider would attach
+    // only after every block's own mount effect had already run — meaning any
+    // block that emits from its mount effect had its event silently swallowed,
+    // deterministically. The same gap opened, more narrowly, for interactions
+    // landing between a commit and its passive-effect flush, which is what made
+    // `dispatch-actions.dom` / `entity-list-reactive-repro.dom` flaky.
+    //
+    // Subscribing during render is safe here because the bus is constructed in
+    // this same factory: nothing outside observes it before we return, so there
+    // is no external mutation and re-running the factory yields an independent
+    // bus. No explicit teardown is needed either — the handler is reachable only
+    // through the bus, so a discarded bus takes its listener with it.
+    const bus = React.useMemo(() => {
+        const created = createSurfaceEventBus();
+        created.on('*', (event) => onEventRef.current?.(event));
+        return created;
+    }, [surfaceId]);
+    React.useEffect(() => {
+        bus.emit({ type: SURFACE_EVENTS.SURFACE_LOAD, surfaceId, timestamp: Date.now() });
+        return () => {
+            bus.emit({ type: SURFACE_EVENTS.SURFACE_UNLOAD, surfaceId, timestamp: Date.now() });
+        };
+    }, [bus, surfaceId]);
+    // auto-wire form→entity bridges when EntityFacade is available.
+    //
+    // Attached during render, for the same reason the `*` handler above is: a
+    // bridge that subscribes from an effect is not listening yet while the blocks
+    // it serves are already interactive, and `bus.emit` drops what nobody is
+    // listening for. A form submitted in that window lost its create outright —
+    // the residual flake in `entity-list-reactive-repro.dom` after the `*` fix,
+    // where the wildcard handler saw `form:submit` but the bridge never did.
+    //
+    // Previous bridges are torn down before new ones attach, so re-running this
+    // (deps change, or a StrictMode double render) never stacks duplicates.
+    const entityFacade = useEntityFacade();
+    // OPTIONAL, because this provider also mounts on the behaviours-only path
+    // where no data machinery exists. A form pointed at a rest source there has
+    // nowhere to write, and says so, rather than the whole surface failing to
+    // render.
+    const dataService = useOptionalDataService();
+    // What the page has bound RIGHT NOW, read at write time through a ref so a
+    // fresh fetch never re-attaches the bridges. Null outside the data-bound
+    // path, where no record can have loaded and every write is a create.
+    const surfaceData = useSurfaceData();
+    const surfaceDataRef = React.useRef(surfaceData);
+    surfaceDataRef.current = surfaceData;
+    /**
+     * THE ONE PLACE THAT KNOWS WHAT A SOURCE ID MEANS.
+     *
+     * The bridge does not, deliberately — that is what lets one declaration
+     * serve our own store and a third party's endpoint without the form knowing
+     * which it is talking to.
+     *
+     * THE VERB FOLLOWS THE RECORD. A binding that says `PATCH` can only update
+     * a record the source has loaded; with none loaded the honest write is a
+     * create. Otherwise a Profile form would PATCH the collection path, the API
+     * would answer 404 "Route not found", and the visitor would read "check the
+     * highlighted fields".
+     */
+    const writer = React.useMemo(() => {
+        const byId = new Map((dataSources ?? []).map((s) => [s.id, s]));
+        return {
+            async write(sourceId, values, method) {
+                const source = byId.get(sourceId);
+                const target = resolveFormWriteTarget(method, surfaceDataRef.current?.[sourceId]);
+                if (source?.kind === 'entity' && source.entityType && entityFacade) {
+                    const entityType = source.entityType;
+                    return target.recordId
+                        ? entityFacade.store.update(entityType, target.recordId, values)
+                        : entityFacade.store.create(entityType, values);
+                }
+                if (!source) {
+                    return {
+                        success: false,
+                        error: {
+                            type: 'not_found',
+                            message: `This form writes to "${sourceId}", which this page does not declare.`,
+                        },
+                    };
+                }
+                if (!dataService) {
+                    return {
+                        success: false,
+                        error: {
+                            type: 'connector',
+                            message: `This form writes to "${sourceId}", but this page has no data layer to write through.`,
+                        },
+                    };
+                }
+                const res = await dataService.fetchData(sourceId, {
+                    method: target.method,
+                    body: values,
+                    ...(target.recordId !== undefined ? { recordId: target.recordId } : {}),
+                });
+                if (!res.success)
+                    return { success: false, error: toFormWriteError(res.error) };
+                const written = res.data;
+                const id = written && typeof written === 'object' ? written['id'] : undefined;
+                return {
+                    success: true,
+                    data: (written ?? {}),
+                    id: (typeof id === 'string' || typeof id === 'number' ? String(id) : target.recordId ?? sourceId),
+                };
+            },
+        };
+    }, [dataSources, entityFacade, dataService]);
+    // Read at submit time through a ref, like the bound data, so a re-render
+    // never re-attaches the bridges.
+    const blocksRef = React.useRef(blocks);
+    blocksRef.current = blocks;
+    const completeValues = React.useCallback((formId, values) => {
+        const tree = blocksRef.current;
+        const state = surfaceDataRef.current?.['state'];
+        if (!tree || !state || typeof state !== 'object')
+            return values;
+        return completeNamedControlValues(tree, formId, values, state);
+    }, []);
+    const bridgeUnsubsRef = React.useRef([]);
+    React.useMemo(() => {
+        bridgeUnsubsRef.current.forEach((u) => u());
+        bridgeUnsubsRef.current = entityFormBindings?.length
+            ? entityFormBindings.map((cfg) => attachFormEntityBridge(bus, writer, cfg, completeValues))
+            : [];
+    }, [writer, bus, entityFormBindings, completeValues]);
+    // Detach on unmount. Keyed on nothing so it runs once per mount; the memo
+    // above owns teardown for every other transition.
+    React.useEffect(() => {
+        return () => {
+            bridgeUnsubsRef.current.forEach((u) => u());
+            bridgeUnsubsRef.current = [];
+        };
+    }, []);
+    return (_jsx(SurfaceEventContext.Provider, { value: bus, children: _jsx(SurfaceIdContext.Provider, { value: surfaceId, children: children }) }));
+}
+//# sourceMappingURL=BehaviorSurfaceProvider.js.map

package/dist/render/BehaviorSurfaceProvider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"BehaviorSurfaceProvider.js","sourceRoot":"","sources":["../../src/render/BehaviorSurfaceProvider.tsx"],"names":[],"mappings":"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","sourcesContent":["/**\n * BehaviorSurfaceProvider\n *\n * React provider that wraps a surface render session with a\n * stable `SurfaceEventBus` instance and the real `surfaceId`.\n *\n * When `entityFormBindings` are supplied and an EntityFacade\n * is available via EntityFacadeContext, automatically attaches form→entity\n * bridges on mount and tears them down on unmount.\n *\n * All block children receive both values via context so they can emit events\n * that carry a meaningful surface ID without prop-drilling.\n *\n * Lifecycle:\n * - Emits `surface:load` on mount\n * - Emits `surface:unload` on unmount\n * - Re-creates the bus (and re-emits lifecycle events) when `surfaceId` changes\n *\n * @module @pwfabric/runtime/render/BehaviorSurfaceProvider\n */\n\nimport * as React from 'react'\nimport { SURFACE_EVENTS } from '@pwfabric/contracts'\nimport type { SurfaceEventDescriptor } from '@pwfabric/contracts'\nimport { SurfaceEventContext } from './surface-event-context.js'\nimport { SurfaceIdContext } from './surface-id-context.js'\nimport { createSurfaceEventBus } from './surface-event-bus.js'\nimport { useEntityFacade } from './entity-facade-context.js'\nimport { useOptionalDataService } from '../data/DataCapabilityProvider.js'\nimport { useSurfaceData } from './surface-data-context.js'\nimport { attachFormEntityBridge } from '../forms/form-entity-bridge.js'\nimport type { FormWriter } from '../forms/form-entity-bridge.js'\nimport { resolveFormWriteTarget, toFormWriteError } from '../forms/form-write-target.js'\nimport type { SurfaceDataSourceDefinition } from './data-binding-types.js'\nimport type { FormEntityBridgeConfig } from '../forms/form-entity-bridge.js'\nimport { completeNamedControlValues } from '../forms/named-control-values.js'\nimport type { Block } from '@pwfabric/core'\n\nexport interface BehaviorSurfaceProviderProps {\n  /** The ID of the surface being rendered */\n  readonly surfaceId: string\n  /** Block render tree */\n  readonly children: React.ReactNode\n  /**\n   * Declarative form→entity bridge configurations extracted\n   * from `surface.capabilities` (platform/entities config.formBindings).\n   * When provided and EntityFacade is available, bridges are auto-attached on\n   * mount and torn down on unmount.\n   */\n  readonly entityFormBindings?: readonly FormEntityBridgeConfig[]\n  /**\n   * The read sources, so a form's `sourceId` can be resolved to a destination.\n   * A source that names an entity type writes through the facade; anything\n   * else is an address and writes over HTTP.\n   */\n  readonly dataSources?: readonly SurfaceDataSourceDefinition[]\n  /**\n   * The surface renderer's single event handler. Subscribed to the bus via the\n   * global `*` wildcard so EVERY block-emitted event (with its full payload,\n   * incl. a declarative `action`) reaches the action dispatcher + host\n   * notification — the canonical path replacing the retired legacy\n   * `context.onEvent` shim that blocks used to call directly.\n   */\n  readonly onEvent?: (event: SurfaceEventDescriptor) => void\n  /**\n   * The rendered (resolved) block tree, so a form's submission can be\n   * completed with the named controls inside it that `FormData` cannot see —\n   * read from page state by their `stateKey`.\n   */\n  readonly blocks?: readonly Block[]\n}\n\n/**\n * Wraps a surface render tree with a scoped `SurfaceEventBus` and `surfaceId`.\n *\n * Place this as the outermost wrapper inside `SurfaceRenderer` so every block\n * in the tree can call `useSurfaceEvents()` and `useSurfaceId()`.\n */\nexport function BehaviorSurfaceProvider({\n  surfaceId,\n  children,\n  entityFormBindings,\n  dataSources,\n  onEvent,\n  blocks,\n}: BehaviorSurfaceProviderProps): React.ReactElement {\n  // Canonical event path: the renderer's handler is subscribed to the global `*`\n  // wildcard. Every block emits through the bus (useSurfaceEvents) → this handler\n  // dispatches declarative actions (setState/refresh) + forwards to the host.\n  // A ref keeps the subscription stable while always calling the latest handler.\n  const onEventRef = React.useRef(onEvent)\n  onEventRef.current = onEvent\n\n  // Re-create the bus when surfaceId changes so sibling surfaces stay isolated.\n  //\n  // The `*` subscription is attached HERE, at construction, rather than in an\n  // effect. `bus.emit` is synchronous and unbuffered: an event emitted while\n  // `handlers.get('*')` is empty is dropped and never replayed. React runs\n  // effects CHILD-FIRST, so a subscription owned by this provider would attach\n  // only after every block's own mount effect had already run — meaning any\n  // block that emits from its mount effect had its event silently swallowed,\n  // deterministically. The same gap opened, more narrowly, for interactions\n  // landing between a commit and its passive-effect flush, which is what made\n  // `dispatch-actions.dom` / `entity-list-reactive-repro.dom` flaky.\n  //\n  // Subscribing during render is safe here because the bus is constructed in\n  // this same factory: nothing outside observes it before we return, so there\n  // is no external mutation and re-running the factory yields an independent\n  // bus. No explicit teardown is needed either — the handler is reachable only\n  // through the bus, so a discarded bus takes its listener with it.\n  const bus = React.useMemo(() => {\n    const created = createSurfaceEventBus()\n    created.on('*', (event) => onEventRef.current?.(event))\n    return created\n  }, [surfaceId])\n\n  React.useEffect(() => {\n    bus.emit({ type: SURFACE_EVENTS.SURFACE_LOAD, surfaceId, timestamp: Date.now() })\n    return () => {\n      bus.emit({ type: SURFACE_EVENTS.SURFACE_UNLOAD, surfaceId, timestamp: Date.now() })\n    }\n  }, [bus, surfaceId])\n\n  // auto-wire form→entity bridges when EntityFacade is available.\n  //\n  // Attached during render, for the same reason the `*` handler above is: a\n  // bridge that subscribes from an effect is not listening yet while the blocks\n  // it serves are already interactive, and `bus.emit` drops what nobody is\n  // listening for. A form submitted in that window lost its create outright —\n  // the residual flake in `entity-list-reactive-repro.dom` after the `*` fix,\n  // where the wildcard handler saw `form:submit` but the bridge never did.\n  //\n  // Previous bridges are torn down before new ones attach, so re-running this\n  // (deps change, or a StrictMode double render) never stacks duplicates.\n  const entityFacade = useEntityFacade()\n  // OPTIONAL, because this provider also mounts on the behaviours-only path\n  // where no data machinery exists. A form pointed at a rest source there has\n  // nowhere to write, and says so, rather than the whole surface failing to\n  // render.\n  const dataService = useOptionalDataService()\n\n  // What the page has bound RIGHT NOW, read at write time through a ref so a\n  // fresh fetch never re-attaches the bridges. Null outside the data-bound\n  // path, where no record can have loaded and every write is a create.\n  const surfaceData = useSurfaceData()\n  const surfaceDataRef = React.useRef(surfaceData)\n  surfaceDataRef.current = surfaceData\n\n  /**\n   * THE ONE PLACE THAT KNOWS WHAT A SOURCE ID MEANS.\n   *\n   * The bridge does not, deliberately — that is what lets one declaration\n   * serve our own store and a third party's endpoint without the form knowing\n   * which it is talking to.\n   *\n   * THE VERB FOLLOWS THE RECORD. A binding that says `PATCH` can only update\n   * a record the source has loaded; with none loaded the honest write is a\n   * create. Otherwise a Profile form would PATCH the collection path, the API\n   * would answer 404 \"Route not found\", and the visitor would read \"check the\n   * highlighted fields\".\n   */\n  const writer = React.useMemo<FormWriter>(() => {\n    const byId = new Map((dataSources ?? []).map((s) => [s.id, s]))\n    return {\n      async write(sourceId, values, method) {\n        const source = byId.get(sourceId)\n        const target = resolveFormWriteTarget(method, surfaceDataRef.current?.[sourceId])\n        if (source?.kind === 'entity' && source.entityType && entityFacade) {\n          const entityType = source.entityType as never\n          return target.recordId\n            ? entityFacade.store.update(entityType, target.recordId as never, values)\n            : entityFacade.store.create(entityType, values)\n        }\n        if (!source) {\n          return {\n            success: false,\n            error: {\n              type: 'not_found',\n              message: `This form writes to \"${sourceId}\", which this page does not declare.`,\n            },\n          }\n        }\n        if (!dataService) {\n          return {\n            success: false,\n            error: {\n              type: 'connector',\n              message: `This form writes to \"${sourceId}\", but this page has no data layer to write through.`,\n            },\n          }\n        }\n        const res = await dataService.fetchData(sourceId, {\n          method: target.method,\n          body: values,\n          ...(target.recordId !== undefined ? { recordId: target.recordId } : {}),\n        })\n        if (!res.success) return { success: false, error: toFormWriteError(res.error) }\n        const written = res.data as Record<string, unknown> | null\n        const id = written && typeof written === 'object' ? written['id'] : undefined\n        return {\n          success: true,\n          data: (written ?? {}) as never,\n          id: (typeof id === 'string' || typeof id === 'number' ? String(id) : target.recordId ?? sourceId) as never,\n        }\n      },\n    }\n  }, [dataSources, entityFacade, dataService])\n\n  // Read at submit time through a ref, like the bound data, so a re-render\n  // never re-attaches the bridges.\n  const blocksRef = React.useRef(blocks)\n  blocksRef.current = blocks\n  const completeValues = React.useCallback(\n    (formId: string, values: Record<string, unknown>): Record<string, unknown> => {\n      const tree = blocksRef.current\n      const state = surfaceDataRef.current?.['state']\n      if (!tree || !state || typeof state !== 'object') return values\n      return completeNamedControlValues(tree, formId, values, state as Record<string, unknown>)\n    },\n    []\n  )\n\n  const bridgeUnsubsRef = React.useRef<readonly (() => void)[]>([])\n  React.useMemo(() => {\n    bridgeUnsubsRef.current.forEach((u) => u())\n    bridgeUnsubsRef.current = entityFormBindings?.length\n      ? entityFormBindings.map((cfg) => attachFormEntityBridge(bus, writer, cfg, completeValues))\n      : []\n  }, [writer, bus, entityFormBindings, completeValues])\n\n  // Detach on unmount. Keyed on nothing so it runs once per mount; the memo\n  // above owns teardown for every other transition.\n  React.useEffect(() => {\n    return () => {\n      bridgeUnsubsRef.current.forEach((u) => u())\n      bridgeUnsubsRef.current = []\n    }\n  }, [])\n\n  return (\n    <SurfaceEventContext.Provider value={bus}>\n      <SurfaceIdContext.Provider value={surfaceId}>{children}</SurfaceIdContext.Provider>\n    </SurfaceEventContext.Provider>\n  )\n}\n"]}

package/dist/render/BlockErrorBoundary.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Block Error Boundary
+ *
+ * React class component that isolates block-level render crashes.
+ * If a single block throws during render, only that block shows
+ * a fallback UI — the rest of the surface stays intact.
+ *
+ * @module @pwfabric/runtime/render/BlockErrorBoundary
+ */
+import * as React from 'react';
+interface BlockErrorBoundaryProps {
+    readonly blockId: string;
+    readonly blockType: string;
+    readonly children: React.ReactNode;
+}
+interface BlockErrorBoundaryState {
+    readonly hasError: boolean;
+    readonly error: Error | null;
+}
+export declare class BlockErrorBoundary extends React.Component<BlockErrorBoundaryProps, BlockErrorBoundaryState> {
+    constructor(props: BlockErrorBoundaryProps);
+    static getDerivedStateFromError(error: Error): BlockErrorBoundaryState;
+    componentDidCatch(error: Error, info: React.ErrorInfo): void;
+    render(): React.ReactNode;
+}
+export {};

package/dist/render/BlockErrorBoundary.js

@@ -0,0 +1,41 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * Block Error Boundary
+ *
+ * React class component that isolates block-level render crashes.
+ * If a single block throws during render, only that block shows
+ * a fallback UI — the rest of the surface stays intact.
+ *
+ * @module @pwfabric/runtime/render/BlockErrorBoundary
+ */
+import * as React from 'react';
+export class BlockErrorBoundary extends React.Component {
+    constructor(props) {
+        super(props);
+        this.state = { hasError: false, error: null };
+    }
+    static getDerivedStateFromError(error) {
+        return { hasError: true, error };
+    }
+    componentDidCatch(error, info) {
+        console.error(`[PWFabric] Block render error: ${this.props.blockType}#${this.props.blockId}`, error, info.componentStack);
+    }
+    render() {
+        if (this.state.hasError) {
+            // Quiet-shape fallback: no visible copy — the earlier card leaked the
+            // raw exception message ("Cannot read properties of undefined…") to end
+            // users in a hardcoded light-red dev box. The error tint + dashed
+            // border signal "this section failed"; the technical message stays in
+            // the title tooltip and in the componentDidCatch console.error above,
+            // and data-block-error keeps it queryable for tests/tooling.
+            return (_jsx("div", { style: {
+                    border: '2px dashed var(--pw-color-error, #ef4444)',
+                    borderRadius: '8px',
+                    backgroundColor: 'color-mix(in srgb, var(--pw-color-error, #ef4444) 8%, transparent)',
+                    minHeight: '32px',
+                }, "data-block-error": this.props.blockId, "data-block-error-type": this.props.blockType, title: this.state.error?.message ?? 'Unknown error' }));
+        }
+        return this.props.children;
+    }
+}
+//# sourceMappingURL=BlockErrorBoundary.js.map

package/dist/render/BlockErrorBoundary.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"BlockErrorBoundary.js","sourceRoot":"","sources":["../../src/render/BlockErrorBoundary.tsx"],"names":[],"mappings":";AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAa9B,MAAM,OAAO,kBAAmB,SAAQ,KAAK,CAAC,SAG7C;IACC,YAAY,KAA8B;QACxC,KAAK,CAAC,KAAK,CAAC,CAAA;QACZ,IAAI,CAAC,KAAK,GAAG,EAAE,QAAQ,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,CAAA;IAC/C,CAAC;IAED,MAAM,CAAC,wBAAwB,CAAC,KAAY;QAC1C,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,KAAK,EAAE,CAAA;IAClC,CAAC;IAEQ,iBAAiB,CAAC,KAAY,EAAE,IAAqB;QAC5D,OAAO,CAAC,KAAK,CACX,kCAAkC,IAAI,CAAC,KAAK,CAAC,SAAS,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,EAC9E,KAAK,EACL,IAAI,CAAC,cAAc,CACpB,CAAA;IACH,CAAC;IAEQ,MAAM;QACb,IAAI,IAAI,CAAC,KAAK,CAAC,QAAQ,EAAE,CAAC;YACxB,sEAAsE;YACtE,wEAAwE;YACxE,kEAAkE;YAClE,sEAAsE;YACtE,sEAAsE;YACtE,6DAA6D;YAC7D,OAAO,CACL,cACE,KAAK,EAAE;oBACL,MAAM,EAAE,2CAA2C;oBACnD,YAAY,EAAE,KAAK;oBACnB,eAAe,EAAE,oEAAoE;oBACrF,SAAS,EAAE,MAAM;iBAClB,sBACiB,IAAI,CAAC,KAAK,CAAC,OAAO,2BACb,IAAI,CAAC,KAAK,CAAC,SAAS,EAC3C,KAAK,EAAE,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,OAAO,IAAI,eAAe,GACnD,CACH,CAAA;QACH,CAAC;QAED,OAAO,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAA;IAC5B,CAAC;CACF","sourcesContent":["/**\n * Block Error Boundary\n *\n * React class component that isolates block-level render crashes.\n * If a single block throws during render, only that block shows\n * a fallback UI — the rest of the surface stays intact.\n *\n * @module @pwfabric/runtime/render/BlockErrorBoundary\n */\n\nimport * as React from 'react'\n\ninterface BlockErrorBoundaryProps {\n  readonly blockId: string\n  readonly blockType: string\n  readonly children: React.ReactNode\n}\n\ninterface BlockErrorBoundaryState {\n  readonly hasError: boolean\n  readonly error: Error | null\n}\n\nexport class BlockErrorBoundary extends React.Component<\n  BlockErrorBoundaryProps,\n  BlockErrorBoundaryState\n> {\n  constructor(props: BlockErrorBoundaryProps) {\n    super(props)\n    this.state = { hasError: false, error: null }\n  }\n\n  static getDerivedStateFromError(error: Error): BlockErrorBoundaryState {\n    return { hasError: true, error }\n  }\n\n  override componentDidCatch(error: Error, info: React.ErrorInfo): void {\n    console.error(\n      `[PWFabric] Block render error: ${this.props.blockType}#${this.props.blockId}`,\n      error,\n      info.componentStack\n    )\n  }\n\n  override render(): React.ReactNode {\n    if (this.state.hasError) {\n      // Quiet-shape fallback: no visible copy — the earlier card leaked the\n      // raw exception message (\"Cannot read properties of undefined…\") to end\n      // users in a hardcoded light-red dev box. The error tint + dashed\n      // border signal \"this section failed\"; the technical message stays in\n      // the title tooltip and in the componentDidCatch console.error above,\n      // and data-block-error keeps it queryable for tests/tooling.\n      return (\n        <div\n          style={{\n            border: '2px dashed var(--pw-color-error, #ef4444)',\n            borderRadius: '8px',\n            backgroundColor: 'color-mix(in srgb, var(--pw-color-error, #ef4444) 8%, transparent)',\n            minHeight: '32px',\n          }}\n          data-block-error={this.props.blockId}\n          data-block-error-type={this.props.blockType}\n          title={this.state.error?.message ?? 'Unknown error'}\n        />\n      )\n    }\n\n    return this.props.children\n  }\n}\n"]}