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

package/dist/perf/web-vitals.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Core Web Vitals Collection
+ *
+ * Collects Core Web Vitals (LCP, FID, CLS, FCP, TTFB, INP) using
+ * PerformanceObserver. Provides real-time metric collection with
+ * rating classification based on web.dev thresholds.
+ *
+ * All browser APIs are guarded for SSR safety.
+ *
+ * @module @pwfabric/runtime/perf
+ */
+/** Web Vital metric names */
+export type WebVitalName = 'LCP' | 'FID' | 'CLS' | 'FCP' | 'TTFB' | 'INP';
+/** Rating classification for a metric */
+export type WebVitalRating = 'good' | 'needs-improvement' | 'poor';
+/** A single Web Vital measurement */
+export interface WebVitalMetric {
+    /** Metric name */
+    readonly name: WebVitalName;
+    /** Metric value (ms for timing metrics, unitless for CLS) */
+    readonly value: number;
+    /** Rating based on web.dev thresholds */
+    readonly rating: WebVitalRating;
+    /** Timestamp when the metric was collected */
+    readonly timestamp: number;
+}
+/** Callback invoked when a metric is collected */
+export type WebVitalCallback = (metric: WebVitalMetric) => void;
+/** Aggregated report of all collected Web Vitals */
+export interface WebVitalsReport {
+    /** Largest Contentful Paint */
+    readonly lcp?: WebVitalMetric | undefined;
+    /** First Input Delay */
+    readonly fid?: WebVitalMetric | undefined;
+    /** Cumulative Layout Shift */
+    readonly cls?: WebVitalMetric | undefined;
+    /** First Contentful Paint */
+    readonly fcp?: WebVitalMetric | undefined;
+    /** Time to First Byte */
+    readonly ttfb?: WebVitalMetric | undefined;
+    /** Interaction to Next Paint */
+    readonly inp?: WebVitalMetric | undefined;
+    /** Timestamp when the report was generated */
+    readonly collectedAt: number;
+}
+/**
+ * Rate a metric value against web.dev thresholds.
+ *
+ * @param name - The metric name
+ * @param value - The measured value
+ * @returns The rating classification
+ */
+export declare function rateMetric(name: WebVitalName, value: number): WebVitalRating;
+/**
+ * Collects Core Web Vitals using PerformanceObserver.
+ *
+ * Supports LCP, FID, CLS, FCP, TTFB, and INP metrics.
+ * All observers are cleaned up on dispose.
+ */
+export declare class WebVitalsCollector {
+    private metrics;
+    private observers;
+    private callbacks;
+    private clsValue;
+    private clsSessionEntries;
+    private clsSessionValue;
+    /**
+     * Start collecting all Web Vitals.
+     *
+     * Creates PerformanceObservers for each metric type.
+     * Safe to call in SSR environments (no-ops silently).
+     */
+    startCollecting(): void;
+    /**
+     * Register a callback for a specific metric.
+     *
+     * The callback fires each time the metric is updated.
+     *
+     * @param name - The metric name to observe
+     * @param callback - Function to call with the metric
+     */
+    onMetric(name: WebVitalName, callback: WebVitalCallback): void;
+    /**
+     * Get the current Web Vitals report.
+     *
+     * @returns A snapshot of all collected metrics
+     */
+    getReport(): WebVitalsReport;
+    /**
+     * Stop collecting metrics and disconnect all observers.
+     */
+    stopCollecting(): void;
+    /**
+     * Stop collecting and clear all state.
+     */
+    dispose(): void;
+    private recordMetric;
+    private tryObserve;
+    private observeLCP;
+    private observeFID;
+    private observeCLS;
+    private observeFCP;
+    private observeTTFB;
+    private observeINP;
+}
+/**
+ * Create a new WebVitalsCollector instance.
+ *
+ * @returns A new collector (not yet started)
+ */
+export declare function createWebVitalsCollector(): WebVitalsCollector;
+//# sourceMappingURL=web-vitals.d.ts.map

package/dist/perf/web-vitals.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"web-vitals.d.ts","sourceRoot":"","sources":["../../src/perf/web-vitals.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAMH,6BAA6B;AAC7B,MAAM,MAAM,YAAY,GAAG,KAAK,GAAG,KAAK,GAAG,KAAK,GAAG,KAAK,GAAG,MAAM,GAAG,KAAK,CAAA;AAEzE,yCAAyC;AACzC,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,mBAAmB,GAAG,MAAM,CAAA;AAElE,qCAAqC;AACrC,MAAM,WAAW,cAAc;IAC7B,kBAAkB;IAClB,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAA;IAC3B,6DAA6D;IAC7D,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,yCAAyC;IACzC,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAA;IAC/B,8CAA8C;IAC9C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;CAC3B;AAED,kDAAkD;AAClD,MAAM,MAAM,gBAAgB,GAAG,CAAC,MAAM,EAAE,cAAc,KAAK,IAAI,CAAA;AAE/D,oDAAoD;AACpD,MAAM,WAAW,eAAe;IAC9B,+BAA+B;IAC/B,QAAQ,CAAC,GAAG,CAAC,EAAE,cAAc,GAAG,SAAS,CAAA;IACzC,wBAAwB;IACxB,QAAQ,CAAC,GAAG,CAAC,EAAE,cAAc,GAAG,SAAS,CAAA;IACzC,8BAA8B;IAC9B,QAAQ,CAAC,GAAG,CAAC,EAAE,cAAc,GAAG,SAAS,CAAA;IACzC,6BAA6B;IAC7B,QAAQ,CAAC,GAAG,CAAC,EAAE,cAAc,GAAG,SAAS,CAAA;IACzC,yBAAyB;IACzB,QAAQ,CAAC,IAAI,CAAC,EAAE,cAAc,GAAG,SAAS,CAAA;IAC1C,gCAAgC;IAChC,QAAQ,CAAC,GAAG,CAAC,EAAE,cAAc,GAAG,SAAS,CAAA;IACzC,8CAA8C;IAC9C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;CAC7B;AAoBD;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,GAAG,cAAc,CAY5E;AAMD;;;;;GAKG;AACH,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,OAAO,CAA0C;IACzD,OAAO,CAAC,SAAS,CAA4B;IAC7C,OAAO,CAAC,SAAS,CAA8C;IAC/D,OAAO,CAAC,QAAQ,CAAI;IACpB,OAAO,CAAC,iBAAiB,CAAyB;IAClD,OAAO,CAAC,eAAe,CAAI;IAE3B;;;;;OAKG;IACH,eAAe,IAAI,IAAI;IAavB;;;;;;;OAOG;IACH,QAAQ,CAAC,IAAI,EAAE,YAAY,EAAE,QAAQ,EAAE,gBAAgB,GAAG,IAAI;IAM9D;;;;OAIG;IACH,SAAS,IAAI,eAAe;IAY5B;;OAEG;IACH,cAAc,IAAI,IAAI;IAOtB;;OAEG;IACH,OAAO,IAAI,IAAI;IAaf,OAAO,CAAC,YAAY;IAqBpB,OAAO,CAAC,UAAU;IAoBlB,OAAO,CAAC,UAAU;IASlB,OAAO,CAAC,UAAU;IAUlB,OAAO,CAAC,UAAU;IA6ClB,OAAO,CAAC,UAAU;IASlB,OAAO,CAAC,WAAW;IASnB,OAAO,CAAC,UAAU;CAsBnB;AAoBD;;;;GAIG;AACH,wBAAgB,wBAAwB,IAAI,kBAAkB,CAE7D"}

package/dist/perf/web-vitals.js

@@ -0,0 +1,268 @@
+/**
+ * Core Web Vitals Collection
+ *
+ * Collects Core Web Vitals (LCP, FID, CLS, FCP, TTFB, INP) using
+ * PerformanceObserver. Provides real-time metric collection with
+ * rating classification based on web.dev thresholds.
+ *
+ * All browser APIs are guarded for SSR safety.
+ *
+ * @module @pwfabric/runtime/perf
+ */
+// ============================================================
+// THRESHOLDS (from web.dev)
+// ============================================================
+/** Rating thresholds: [goodThreshold, poorThreshold] */
+const THRESHOLDS = {
+    LCP: [2500, 4000],
+    FID: [100, 300],
+    CLS: [0.1, 0.25],
+    FCP: [1800, 3000],
+    TTFB: [800, 1800],
+    INP: [200, 500],
+};
+// ============================================================
+// UTILITY
+// ============================================================
+/**
+ * Rate a metric value against web.dev thresholds.
+ *
+ * @param name - The metric name
+ * @param value - The measured value
+ * @returns The rating classification
+ */
+export function rateMetric(name, value) {
+    const threshold = THRESHOLDS[name];
+    if (!threshold) {
+        return 'good';
+    }
+    if (value <= threshold[0]) {
+        return 'good';
+    }
+    if (value > threshold[1]) {
+        return 'poor';
+    }
+    return 'needs-improvement';
+}
+// ============================================================
+// COLLECTOR
+// ============================================================
+/**
+ * Collects Core Web Vitals using PerformanceObserver.
+ *
+ * Supports LCP, FID, CLS, FCP, TTFB, and INP metrics.
+ * All observers are cleaned up on dispose.
+ */
+export class WebVitalsCollector {
+    metrics = new Map();
+    observers = [];
+    callbacks = new Map();
+    clsValue = 0;
+    clsSessionEntries = [];
+    clsSessionValue = 0;
+    /**
+     * Start collecting all Web Vitals.
+     *
+     * Creates PerformanceObservers for each metric type.
+     * Safe to call in SSR environments (no-ops silently).
+     */
+    startCollecting() {
+        if (typeof PerformanceObserver === 'undefined') {
+            return;
+        }
+        this.observeLCP();
+        this.observeFID();
+        this.observeCLS();
+        this.observeFCP();
+        this.observeTTFB();
+        this.observeINP();
+    }
+    /**
+     * Register a callback for a specific metric.
+     *
+     * The callback fires each time the metric is updated.
+     *
+     * @param name - The metric name to observe
+     * @param callback - Function to call with the metric
+     */
+    onMetric(name, callback) {
+        const existing = this.callbacks.get(name) ?? [];
+        existing.push(callback);
+        this.callbacks.set(name, existing);
+    }
+    /**
+     * Get the current Web Vitals report.
+     *
+     * @returns A snapshot of all collected metrics
+     */
+    getReport() {
+        return {
+            lcp: this.metrics.get('LCP'),
+            fid: this.metrics.get('FID'),
+            cls: this.metrics.get('CLS'),
+            fcp: this.metrics.get('FCP'),
+            ttfb: this.metrics.get('TTFB'),
+            inp: this.metrics.get('INP'),
+            collectedAt: Date.now(),
+        };
+    }
+    /**
+     * Stop collecting metrics and disconnect all observers.
+     */
+    stopCollecting() {
+        for (const observer of this.observers) {
+            observer.disconnect();
+        }
+        this.observers = [];
+    }
+    /**
+     * Stop collecting and clear all state.
+     */
+    dispose() {
+        this.stopCollecting();
+        this.metrics.clear();
+        this.callbacks.clear();
+        this.clsValue = 0;
+        this.clsSessionEntries = [];
+        this.clsSessionValue = 0;
+    }
+    // ----------------------------------------------------------
+    // Private: metric recording
+    // ----------------------------------------------------------
+    recordMetric(name, value) {
+        const metric = {
+            name,
+            value,
+            rating: rateMetric(name, value),
+            timestamp: Date.now(),
+        };
+        this.metrics.set(name, metric);
+        const cbs = this.callbacks.get(name);
+        if (cbs) {
+            for (const cb of cbs) {
+                cb(metric);
+            }
+        }
+    }
+    // ----------------------------------------------------------
+    // Private: observer helpers
+    // ----------------------------------------------------------
+    tryObserve(entryType, handler, options) {
+        try {
+            const observer = new PerformanceObserver((list) => {
+                handler(list.getEntries());
+            });
+            const observeOptions = {
+                type: options?.type ?? entryType,
+                buffered: options?.buffered ?? true,
+            };
+            observer.observe(observeOptions);
+            this.observers.push(observer);
+        }
+        catch {
+            // Entry type not supported in this browser — silently skip
+        }
+    }
+    observeLCP() {
+        this.tryObserve('largest-contentful-paint', (entries) => {
+            const last = entries[entries.length - 1];
+            if (last) {
+                this.recordMetric('LCP', last.startTime);
+            }
+        });
+    }
+    observeFID() {
+        this.tryObserve('first-input', (entries) => {
+            const first = entries[0];
+            if (first) {
+                const fidEntry = first;
+                this.recordMetric('FID', fidEntry.processingStart - fidEntry.startTime);
+            }
+        });
+    }
+    observeCLS() {
+        this.tryObserve('layout-shift', (entries) => {
+            for (const entry of entries) {
+                const lsEntry = entry;
+                // Only count shifts without recent user input
+                if (!lsEntry.hadRecentInput) {
+                    // Session window algorithm
+                    if (this.clsSessionEntries.length > 0 &&
+                        entry.startTime -
+                            (this.clsSessionEntries[this.clsSessionEntries.length - 1]?.startTime ?? 0) >
+                            1000) {
+                        // Gap > 1s → start new session window
+                        if (this.clsSessionValue > this.clsValue) {
+                            this.clsValue = this.clsSessionValue;
+                        }
+                        this.clsSessionEntries = [];
+                        this.clsSessionValue = 0;
+                    }
+                    // Add to current session
+                    if (this.clsSessionEntries.length === 0 ||
+                        entry.startTime - (this.clsSessionEntries[0]?.startTime ?? 0) <= 5000) {
+                        this.clsSessionEntries.push(entry);
+                        this.clsSessionValue += lsEntry.value;
+                    }
+                    else {
+                        // Session exceeded 5s → start new session
+                        if (this.clsSessionValue > this.clsValue) {
+                            this.clsValue = this.clsSessionValue;
+                        }
+                        this.clsSessionEntries = [entry];
+                        this.clsSessionValue = lsEntry.value;
+                    }
+                    // Report the max of current session and previous max
+                    const currentCls = Math.max(this.clsValue, this.clsSessionValue);
+                    this.recordMetric('CLS', currentCls);
+                }
+            }
+        });
+    }
+    observeFCP() {
+        this.tryObserve('paint', (entries) => {
+            const fcp = entries.find((e) => e.name === 'first-contentful-paint');
+            if (fcp) {
+                this.recordMetric('FCP', fcp.startTime);
+            }
+        });
+    }
+    observeTTFB() {
+        this.tryObserve('navigation', (entries) => {
+            const nav = entries[0];
+            if (nav) {
+                this.recordMetric('TTFB', nav.responseStart);
+            }
+        });
+    }
+    observeINP() {
+        this.tryObserve('event', (entries) => {
+            let maxDuration = 0;
+            for (const entry of entries) {
+                const eventEntry = entry;
+                if (eventEntry.duration > maxDuration) {
+                    maxDuration = eventEntry.duration;
+                }
+            }
+            if (maxDuration > 0) {
+                const existing = this.metrics.get('INP');
+                // INP tracks the worst interaction
+                if (!existing || maxDuration > existing.value) {
+                    this.recordMetric('INP', maxDuration);
+                }
+            }
+        }, { type: 'event', buffered: true });
+    }
+}
+// ============================================================
+// FACTORY
+// ============================================================
+/**
+ * Create a new WebVitalsCollector instance.
+ *
+ * @returns A new collector (not yet started)
+ */
+export function createWebVitalsCollector() {
+    return new WebVitalsCollector();
+}
+//# sourceMappingURL=web-vitals.js.map

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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"}

package/dist/registry.d.ts

@@ -0,0 +1,64 @@
+/**
+ * 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;
+//# sourceMappingURL=registry.d.ts.map

package/dist/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EACV,YAAY,EACZ,UAAU,EACV,kBAAkB,EAElB,UAAU,EAEX,MAAM,qBAAqB,CAAA;AAM5B;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC;;OAEG;IACH,QAAQ,CAAC,CAAC,SAAS,UAAU,EAAE,UAAU,EAAE,CAAC,GAAG,kBAAkB,CAAC,CAAC,CAAC,CAAA;IAEpE;;OAEG;IACH,UAAU,CAAC,EAAE,EAAE,YAAY,GAAG,OAAO,CAAA;IAErC;;OAEG;IACH,OAAO,CAAC,CAAC,SAAS,UAAU,EAAE,EAAE,EAAE,YAAY,GAAG,UAAU,CAAC,CAAC,CAAC,CAAA;IAE9D;;OAEG;IACH,GAAG,CAAC,EAAE,EAAE,YAAY,GAAG,OAAO,CAAA;IAE9B;;OAEG;IACH,IAAI,IAAI,SAAS,YAAY,EAAE,CAAA;IAE/B;;OAEG;IACH,IAAI,IAAI,MAAM,CAAA;IAEd;;OAEG;IACH,KAAK,IAAI,IAAI,CAAA;CACd;AAMD;;GAEG;AACH,qBAAa,0BAA2B,YAAW,kBAAkB;IACnE,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAsC;IACnE,OAAO,CAAC,QAAQ,CAAC,eAAe,CAA6C;IAE7E,QAAQ,CAAC,CAAC,SAAS,UAAU,EAAE,UAAU,EAAE,CAAC,GAAG,kBAAkB,CAAC,CAAC,CAAC;IAyCpE,UAAU,CAAC,EAAE,EAAE,YAAY,GAAG,OAAO;IAkBrC,OAAO,CAAC,CAAC,SAAS,UAAU,EAAE,EAAE,EAAE,YAAY,GAAG,UAAU,CAAC,CAAC,CAAC;IAc9D,GAAG,CAAC,EAAE,EAAE,YAAY,GAAG,OAAO;IAI9B,IAAI,IAAI,SAAS,YAAY,EAAE;IAI/B,IAAI,IAAI,MAAM;IAId,KAAK,IAAI,IAAI;IAKb;;OAEG;IACH,OAAO,CAAC,wBAAwB;CAiCjC;AAED;;GAEG;AACH,wBAAgB,cAAc,IAAI,kBAAkB,CAEnD"}

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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"}

package/dist/render/BehaviorSurfaceProvider.d.ts

@@ -0,0 +1,66 @@
+/**
+ * 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;
+//# sourceMappingURL=BehaviorSurfaceProvider.d.ts.map

package/dist/render/BehaviorSurfaceProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BehaviorSurfaceProvider.d.ts","sourceRoot":"","sources":["../../src/render/BehaviorSurfaceProvider.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAE9B,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAA;AAUjE,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,yBAAyB,CAAA;AAC1E,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,gCAAgC,CAAA;AAE5E,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAA;AAE3C,MAAM,WAAW,4BAA4B;IAC3C,2CAA2C;IAC3C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,wBAAwB;IACxB,QAAQ,CAAC,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAA;IAClC;;;;;OAKG;IACH,QAAQ,CAAC,kBAAkB,CAAC,EAAE,SAAS,sBAAsB,EAAE,CAAA;IAC/D;;;;OAIG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,2BAA2B,EAAE,CAAA;IAC7D;;;;;;OAMG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,sBAAsB,KAAK,IAAI,CAAA;IAC1D;;;;OAIG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,KAAK,EAAE,CAAA;CACnC;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,EACtC,SAAS,EACT,QAAQ,EACR,kBAAkB,EAClB,WAAW,EACX,OAAO,EACP,MAAM,GACP,EAAE,4BAA4B,GAAG,KAAK,CAAC,YAAY,CA+JnD"}