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

package/dist/render/surface-data-context.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Surface Data Context
+ *
+ * What the data-bound renderer has CURRENTLY bound, keyed by source id — the
+ * same object block expressions resolve `{{<sourceId>}}` against, offered to
+ * the providers that sit between the data layer and the blocks.
+ *
+ * The form writer needs it: a binding that says `PATCH` can only name a
+ * record the page has loaded, and until this context existed the writer
+ * could not see one — so it patched the collection path and the API said
+ * 404. `null` outside the data-bound path (behaviours-only surfaces, plain
+ * `SurfaceRenderer`), where there is nothing bound to consult.
+ *
+ * @module @pwfabric/runtime/render/surface-data-context
+ */
+export type SurfaceData = Readonly<Record<string, unknown>>;
+export declare const SurfaceDataContext: import("react").Context<Readonly<Record<string, unknown>> | null>;
+export declare function useSurfaceData(): SurfaceData | null;
+//# sourceMappingURL=surface-data-context.d.ts.map

package/dist/render/surface-data-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"surface-data-context.d.ts","sourceRoot":"","sources":["../../src/render/surface-data-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH,MAAM,MAAM,WAAW,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;AAE3D,eAAO,MAAM,kBAAkB,mEAA0C,CAAA;AAEzE,wBAAgB,cAAc,IAAI,WAAW,GAAG,IAAI,CAEnD"}

package/dist/render/surface-data-context.js

@@ -0,0 +1,21 @@
+/**
+ * Surface Data Context
+ *
+ * What the data-bound renderer has CURRENTLY bound, keyed by source id — the
+ * same object block expressions resolve `{{<sourceId>}}` against, offered to
+ * the providers that sit between the data layer and the blocks.
+ *
+ * The form writer needs it: a binding that says `PATCH` can only name a
+ * record the page has loaded, and until this context existed the writer
+ * could not see one — so it patched the collection path and the API said
+ * 404. `null` outside the data-bound path (behaviours-only surfaces, plain
+ * `SurfaceRenderer`), where there is nothing bound to consult.
+ *
+ * @module @pwfabric/runtime/render/surface-data-context
+ */
+import { createContext, useContext } from 'react';
+export const SurfaceDataContext = createContext(null);
+export function useSurfaceData() {
+    return useContext(SurfaceDataContext);
+}
+//# sourceMappingURL=surface-data-context.js.map

package/dist/render/surface-data-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"surface-data-context.js","sourceRoot":"","sources":["../../src/render/surface-data-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,OAAO,CAAA;AAIjD,MAAM,CAAC,MAAM,kBAAkB,GAAG,aAAa,CAAqB,IAAI,CAAC,CAAA;AAEzE,MAAM,UAAU,cAAc;IAC5B,OAAO,UAAU,CAAC,kBAAkB,CAAC,CAAA;AACvC,CAAC"}

package/dist/render/surface-event-bus.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Surface Event Bus Implementation
+ *
+ * In-process pub/sub bus scoped to a single rendered surface.
+ *
+ * @module @pwfabric/runtime/render/surface-event-bus
+ */
+import type { SurfaceEventBus } from '@pwfabric/contracts';
+/**
+ * Create a new `SurfaceEventBus` instance.
+ *
+ * Each surface renderer creates its own bus so that events from one surface
+ * do not leak into sibling or parent surfaces.
+ *
+ * Wildcard support: listeners registered as `"<namespace>:*"` (e.g.
+ * `"capability:*"`) receive every event whose type starts with that namespace
+ * prefix (e.g. `"capability:data-loaded"`).
+ */
+export declare function createSurfaceEventBus(): SurfaceEventBus;
+//# sourceMappingURL=surface-event-bus.d.ts.map

package/dist/render/surface-event-bus.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"surface-event-bus.d.ts","sourceRoot":"","sources":["../../src/render/surface-event-bus.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EACV,eAAe,EAIhB,MAAM,qBAAqB,CAAA;AAE5B;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,IAAI,eAAe,CA2DvD"}

package/dist/render/surface-event-bus.js

@@ -0,0 +1,68 @@
+/**
+ * Surface Event Bus Implementation
+ *
+ * In-process pub/sub bus scoped to a single rendered surface.
+ *
+ * @module @pwfabric/runtime/render/surface-event-bus
+ */
+/**
+ * Create a new `SurfaceEventBus` instance.
+ *
+ * Each surface renderer creates its own bus so that events from one surface
+ * do not leak into sibling or parent surfaces.
+ *
+ * Wildcard support: listeners registered as `"<namespace>:*"` (e.g.
+ * `"capability:*"`) receive every event whose type starts with that namespace
+ * prefix (e.g. `"capability:data-loaded"`).
+ */
+export function createSurfaceEventBus() {
+    const handlers = new Map();
+    return {
+        emit(event) {
+            // Dev-mode payload validation — async/lazy, does not block emit
+            if (process.env.NODE_ENV === 'development') {
+                // Import lazily to avoid prod bundle size impact
+                void import('@pwfabric/contracts').then(({ SURFACE_EVENT_PAYLOAD_SCHEMAS }) => {
+                    const schema = SURFACE_EVENT_PAYLOAD_SCHEMAS[event.type];
+                    if (schema && event.payload !== undefined) {
+                        const result = schema.safeParse(event.payload);
+                        if (!result.success) {
+                            console.warn(`[SurfaceEventBus] Payload validation warning for '${event.type}':`, result.error.flatten());
+                        }
+                    }
+                });
+            }
+            // Exact-match listeners
+            const exactSet = handlers.get(event.type);
+            if (exactSet) {
+                exactSet.forEach((h) => h(event));
+            }
+            // Wildcard listeners for the namespace prefix (e.g. "block:*")
+            const ns = event.type.split(':')[0];
+            const wildcardSet = handlers.get(`${ns}:*`);
+            if (wildcardSet) {
+                wildcardSet.forEach((h) => h(event));
+            }
+            // Global wildcard "*" — every event. The surface renderer subscribes its
+            // single event handler here so block-emitted events (with their full
+            // payload, incl. a declarative `action`) reach the action dispatcher. This
+            // is what lets a form's submit→setState run via the canonical bus path
+            // instead of the retired legacy `context.onEvent` shim.
+            const globalSet = handlers.get('*');
+            if (globalSet) {
+                globalSet.forEach((h) => h(event));
+            }
+        },
+        on(eventType, handler) {
+            if (!handlers.has(eventType)) {
+                handlers.set(eventType, new Set());
+            }
+            handlers.get(eventType)?.add(handler);
+            return () => handlers.get(eventType)?.delete(handler);
+        },
+        off(eventType, handler) {
+            handlers.get(eventType)?.delete(handler);
+        },
+    };
+}
+//# sourceMappingURL=surface-event-bus.js.map

package/dist/render/surface-event-bus.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"surface-event-bus.js","sourceRoot":"","sources":["../../src/render/surface-event-bus.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AASH;;;;;;;;;GASG;AACH,MAAM,UAAU,qBAAqB;IACnC,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAoC,CAAA;IAE5D,OAAO;QACL,IAAI,CAAC,KAA6B;YAChC,gEAAgE;YAChE,IAAI,OAAO,CAAC,GAAG,CAAC,QAAQ,KAAK,aAAa,EAAE,CAAC;gBAC3C,iDAAiD;gBACjD,KAAK,MAAM,CAAC,qBAAqB,CAAC,CAAC,IAAI,CAAC,CAAC,EAAE,6BAA6B,EAAE,EAAE,EAAE;oBAC5E,MAAM,MAAM,GACV,6BAA6B,CAAC,KAAK,CAAC,IAAkD,CAAC,CAAA;oBACzF,IAAI,MAAM,IAAI,KAAK,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;wBAC1C,MAAM,MAAM,GAAG,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,OAAO,CAAC,CAAA;wBAC9C,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;4BACpB,OAAO,CAAC,IAAI,CACV,qDAAqD,KAAK,CAAC,IAAI,IAAI,EACnE,MAAM,CAAC,KAAK,CAAC,OAAO,EAAE,CACvB,CAAA;wBACH,CAAC;oBACH,CAAC;gBACH,CAAC,CAAC,CAAA;YACJ,CAAC;YAED,wBAAwB;YACxB,MAAM,QAAQ,GAAG,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAA;YACzC,IAAI,QAAQ,EAAE,CAAC;gBACb,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAA;YACnC,CAAC;YAED,+DAA+D;YAC/D,MAAM,EAAE,GAAG,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAA;YACnC,MAAM,WAAW,GAAG,QAAQ,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,CAAA;YAC3C,IAAI,WAAW,EAAE,CAAC;gBAChB,WAAW,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAA;YACtC,CAAC;YAED,yEAAyE;YACzE,qEAAqE;YACrE,2EAA2E;YAC3E,uEAAuE;YACvE,wDAAwD;YACxD,MAAM,SAAS,GAAG,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;YACnC,IAAI,SAAS,EAAE,CAAC;gBACd,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAA;YACpC,CAAC;QACH,CAAC;QAED,EAAE,CAAC,SAAiB,EAAE,OAA4B;YAChD,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,CAAC;gBAC7B,QAAQ,CAAC,GAAG,CAAC,SAAS,EAAE,IAAI,GAAG,EAAE,CAAC,CAAA;YACpC,CAAC;YACD,QAAQ,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,GAAG,CAAC,OAAO,CAAC,CAAA;YACrC,OAAO,GAAG,EAAE,CAAC,QAAQ,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC,OAAO,CAAC,CAAA;QACvD,CAAC;QAED,GAAG,CAAC,SAAiB,EAAE,OAA4B;YACjD,QAAQ,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC,OAAO,CAAC,CAAA;QAC1C,CAAC;KACF,CAAA;AACH,CAAC"}

package/dist/render/surface-event-context.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Surface Event Context
+ *
+ * Re-exports the canonical `SurfaceEventContext` from `@pwfabric/runtime/blocks`.
+ * Runtime code that sets the context via
+ * `BehaviorSurfaceProvider` and block components that consume it via
+ * `useSurfaceEvents` share the same context object through this re-export.
+ *
+ * @module @pwfabric/runtime/render/surface-event-context
+ */
+export { SurfaceEventContext } from '../blocks/surface-event-context.js';
+//# sourceMappingURL=surface-event-context.d.ts.map

package/dist/render/surface-event-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"surface-event-context.d.ts","sourceRoot":"","sources":["../../src/render/surface-event-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,mBAAmB,EAAE,MAAM,oCAAoC,CAAA"}

package/dist/render/surface-event-context.js

@@ -0,0 +1,12 @@
+/**
+ * Surface Event Context
+ *
+ * Re-exports the canonical `SurfaceEventContext` from `@pwfabric/runtime/blocks`.
+ * Runtime code that sets the context via
+ * `BehaviorSurfaceProvider` and block components that consume it via
+ * `useSurfaceEvents` share the same context object through this re-export.
+ *
+ * @module @pwfabric/runtime/render/surface-event-context
+ */
+export { SurfaceEventContext } from '../blocks/surface-event-context.js';
+//# sourceMappingURL=surface-event-context.js.map

package/dist/render/surface-event-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"surface-event-context.js","sourceRoot":"","sources":["../../src/render/surface-event-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,mBAAmB,EAAE,MAAM,oCAAoC,CAAA"}

package/dist/render/surface-id-context.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Surface ID Context
+ *
+ * Re-exports the canonical `SurfaceIdContext` from `@pwfabric/runtime/blocks`.
+ *
+ * @module @pwfabric/runtime/render/surface-id-context
+ */
+export { SurfaceIdContext } from '../blocks/surface-id-context.js';
+//# sourceMappingURL=surface-id-context.d.ts.map

package/dist/render/surface-id-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"surface-id-context.d.ts","sourceRoot":"","sources":["../../src/render/surface-id-context.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAA"}

package/dist/render/surface-id-context.js

@@ -0,0 +1,9 @@
+/**
+ * Surface ID Context
+ *
+ * Re-exports the canonical `SurfaceIdContext` from `@pwfabric/runtime/blocks`.
+ *
+ * @module @pwfabric/runtime/render/surface-id-context
+ */
+export { SurfaceIdContext } from '../blocks/surface-id-context.js';
+//# sourceMappingURL=surface-id-context.js.map

package/dist/render/surface-id-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"surface-id-context.js","sourceRoot":"","sources":["../../src/render/surface-id-context.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAA"}

package/dist/render/theme-utils.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Surface Theme Utilities
+ *
+ * Surface Theme Engine — converts SurfaceTheme to CSS custom properties.
+ *
+ * The implementation MOVED to `@pwfabric/contracts`
+ * (`fabric/appearance-cascade`) shared with the theme exporter (export
+ * `theme.css`) and the authoring studio (bake the dark variant at write time) need the same
+ * transform, and `contracts` is the only leaf all three can reach. This module
+ * stays as the runtime-facing name so existing import paths keep working.
+ *
+ * @module @pwfabric/runtime/render/theme-utils
+ */
+export { surfaceThemeToCSS } from '@pwfabric/contracts';
+//# sourceMappingURL=theme-utils.d.ts.map

package/dist/render/theme-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"theme-utils.d.ts","sourceRoot":"","sources":["../../src/render/theme-utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAA"}

package/dist/render/theme-utils.js

@@ -0,0 +1,15 @@
+/**
+ * Surface Theme Utilities
+ *
+ * Surface Theme Engine — converts SurfaceTheme to CSS custom properties.
+ *
+ * The implementation MOVED to `@pwfabric/contracts`
+ * (`fabric/appearance-cascade`) shared with the theme exporter (export
+ * `theme.css`) and the authoring studio (bake the dark variant at write time) need the same
+ * transform, and `contracts` is the only leaf all three can reach. This module
+ * stays as the runtime-facing name so existing import paths keep working.
+ *
+ * @module @pwfabric/runtime/render/theme-utils
+ */
+export { surfaceThemeToCSS } from '@pwfabric/contracts';
+//# sourceMappingURL=theme-utils.js.map

package/dist/render/theme-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"theme-utils.js","sourceRoot":"","sources":["../../src/render/theme-utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAA"}

package/dist/render/types.d.ts

@@ -0,0 +1,283 @@
+/**
+ * Surface Renderer Types
+ *
+ * Phase 2A.1: Type definitions for Surface-to-React rendering
+ *
+ * @module @pwfabric/runtime/render/types
+ */
+import type { Block, BreakpointName, SurfaceDocument, SurfaceTheme } from '@pwfabric/contracts';
+import type { CSSProperties, ReactNode } from 'react';
+import type { ImageAdapter as ImageAdapterType } from '../adapters/types.js';
+import type { EntityFacade } from '../entity/facade.js';
+import type { SurfaceConnectionsValue } from '../connectors/types.js';
+export type { EntityFacade } from '../entity/facade.js';
+export type { ImageAdapter, ImageAdapterProps } from '../adapters/types.js';
+type ImageAdapter = ImageAdapterType;
+/**
+ * Capability types that can be required by surfaces
+ * (defined capabilities)
+ */
+export type CapabilityType = 'auth' | 'data' | 'state' | 'navigation' | 'analytics' | 'seo' | 'i18n' | 'forms';
+/**
+ * Renderable surface interface
+ *
+ * A structural projection of SurfaceDocument containing only the fields
+ * needed for rendering. Any object with the matching shape can be rendered,
+ * including custom definitions.
+ *
+ * Derived from SurfaceDocument so it stays structurally aligned with the
+ * canonical type.
+ */
+export type RenderableSurface = Pick<SurfaceDocument, 'blocks' | 'appearance' | 'capabilities'> & {
+    /** Optional surface identifier — used by `BehaviorSurfaceProvider` to scope the event bus */
+    readonly id?: string;
+};
+/**
+ * Props passed to block components
+ */
+export interface BlockComponentProps<T = Record<string, unknown>> {
+    /** Block definition */
+    readonly block: Block;
+    /** Resolved props (validated and defaulted) */
+    readonly props: T;
+    /** Rendered children (for container blocks) */
+    readonly children?: ReactNode;
+    /** Block context for capability access */
+    readonly context: BlockContext;
+}
+/**
+ * Block component type
+ */
+export type BlockComponent<T = Record<string, unknown>> = ((props: BlockComponentProps<T>) => ReactNode) & {
+    /**
+     * How the block wants to be sized when it sits in a flex ROW.
+     *
+     * The engine's default for a row child is an equal share (`flex: 1 1 0`) —
+     * right for two content columns, wrong for an avatar, a badge, a button: an
+     * intrinsic thing stretched to half a row is the single most measured layout
+     * defect of the 2026-09 surface audit (127 hand-written `flex: 0 0 auto`
+     * overrides across 14 receipts). A block whose natural width is its content
+     * declares `sizing: 'intrinsic'` — as a static on the component, the same
+     * way `displayName` travels — and the engine gives it `flex: 0 0 auto`.
+     * An authored flex hint on the instance still wins. The engine memorises no
+     * block names: the block declares, the engine obeys.
+     */
+    sizing?: BlockSizing;
+};
+/** The only sizing word the engine knows besides its default (fluid share). */
+export type BlockSizing = 'intrinsic';
+/**
+ * Block component registry
+ */
+export type BlockComponentRegistry = Record<string, BlockComponent>;
+/**
+ * Capability provider interface
+ */
+export interface CapabilityProvider {
+    /** Capability type */
+    readonly type: CapabilityType;
+    /** Provider-specific data */
+    readonly data?: unknown;
+}
+/**
+ * Block rendering context
+ */
+export interface BlockContext {
+    /** Available capabilities */
+    readonly capabilities: Map<CapabilityType, CapabilityProvider>;
+    /** Base path for routing */
+    readonly basePath: string;
+    /** Event handler */
+    readonly onEvent: ((event: SurfaceEvent) => void) | undefined;
+    /** Image adapter for framework-specific optimization */
+    readonly imageAdapter: ImageAdapter | undefined;
+    /** Current viewport breakpoint for responsive rendering */
+    readonly viewport?: BreakpointName;
+    /**
+     * Interaction mode (ADR render-unification). `onEvent` is a pure notification
+     * and always fires; `interactionMode` gates real SIDE-EFFECTS. Blocks that
+     * perform real navigation or data writes (e.g. `window.location.href`) MUST
+     * skip those when `interactionMode === 'inert'` so editor/preview renders
+     * don't trigger navigation or external mutations. Defaults to `live`.
+     */
+    readonly interactionMode?: BlockInteractionMode;
+}
+/**
+ * Surface event types
+ */
+export type SurfaceEventType = 'click' | 'submit' | 'change' | 'navigate' | 'custom';
+/**
+ * Surface event
+ */
+export interface SurfaceEvent {
+    /** Event type */
+    readonly type: SurfaceEventType;
+    /** Block ID that triggered the event */
+    readonly blockId: string;
+    /** Event payload */
+    readonly payload?: unknown;
+    /** Original DOM event (if applicable) */
+    readonly originalEvent?: Event;
+    /** Canonical bus event name (e.g. 'block:click', 'form:submit') — set by the renderer bridge */
+    readonly canonicalType?: string;
+}
+/**
+ * Surface renderer props
+ */
+/**
+ * Interaction mode for the runtime render (ADR render-unification).
+ * - `live` (default): full runtime behavior — data-source auto-refresh timers run
+ *   and block-dispatched surface actions/events fire.
+ * - `inert`: editor/preview render — no auto-refresh timers, block-dispatched
+ *   surface actions are no-ops, so an editor can intercept clicks (e.g. for
+ *   selection) without the surface mutating its own state.
+ */
+export type BlockInteractionMode = 'live' | 'inert';
+/**
+ * Props the runtime puts on each block's outermost wrapper element. The exact
+ * shape `renderBlock` would spread onto its own `<div>`. An editor decorator
+ * (see `renderBlockWrapper`) spreads these onto its own element so the runtime's
+ * computed layout + the per-block selector survive — the decorator never
+ * recomputes layout.
+ */
+export interface BlockWrapperProps {
+    readonly style?: CSSProperties;
+    /**
+     * The block id as a DOM id, so `#<blockId>` is a reachable anchor.
+     *
+     * Separate from `data-block-id`, which addresses blocks for styling and
+     * editing: only a real `id` makes a fragment link scroll, so without it
+     * same-page navigation would be silently impossible.
+     *
+     * A decorator that renders its own wrapper receives this and is expected to
+     * apply it — two elements carrying one id is worse than none.
+     */
+    readonly id?: string;
+    /** Unified per-block selector — present on every render path. */
+    readonly 'data-block-id': string;
+    /** Any other `data-*` attributes the runtime sets (e.g. data-dynamic-block). */
+    readonly [dataAttr: `data-${string}`]: string | undefined;
+}
+/**
+ * Arguments passed to a `renderBlockWrapper` decorator. `children` is the
+ * runtime-rendered block content (already wrapped in its error boundary);
+ * `wrapperProps` carries the runtime-computed layout style + selectors.
+ */
+export interface BlockWrapperRenderArgs {
+    readonly block: Block;
+    readonly children: ReactNode;
+    readonly wrapperProps: BlockWrapperProps;
+    readonly parentBlock?: Block;
+}
+export interface SurfaceRendererProps {
+    /** Surface definition (starter or custom) */
+    readonly surface: RenderableSurface;
+    /** Capability providers */
+    readonly capabilities?: CapabilityProvider[];
+    /**
+     * App-level color scheme hint (kept for external API compat, not injected into BlockContext).
+     * Surface visual theming is done via surface.theme.
+     */
+    readonly theme?: 'light' | 'dark';
+    /**
+     * the Project's shared theme tokens,
+     * merged as a layer BETWEEN the platform defaults and this surface's own
+     * `appearance.config.theme` — a surface that hasn't set a given token
+     * inherits the project's; one that has, keeps winning. Only wired for the
+     * in-process fallback resolution path (no tenant-installed ui-appearance
+     * atom bundle active); published/public rendering does not consume this
+     * yet — editor-only for now.
+     */
+    readonly projectTheme?: SurfaceTheme;
+    /**
+     * The Project's dark OVERRIDES (`appearanceConfig.darkTheme`), as the authoring studio writes
+     * them: only the tokens the author changed. They sit on top of the dark
+     * variant DERIVED from the effective light theme, under this surface's own
+     * `appearance.config.darkTheme`. Omit it and the dark mode is the derivation
+     * plus the surface's overrides, as before.
+     */
+    readonly projectDarkTheme?: SurfaceTheme;
+    /** Base path for links/routing */
+    readonly basePath?: string;
+    /** Event handler */
+    readonly onEvent?: (event: SurfaceEvent) => void;
+    /** Custom block component overrides */
+    readonly components?: Partial<BlockComponentRegistry>;
+    /** Wrapper className */
+    readonly className?: string;
+    /** Explicit viewport override (if not set, uses auto-detection) */
+    readonly viewport?: BreakpointName;
+    /** Grid gap between blocks in pixels (default: 16) */
+    readonly gap?: number | undefined;
+    /** Surface inner padding in pixels (default: 24) */
+    readonly padding?: number | undefined;
+    /**
+     * Image adapter for framework-specific image optimization
+     *
+     * Allows using Next.js Image, Astro Image, etc. while keeping
+     * surface definitions framework-agnostic.
+     *
+     * @example
+     * ```tsx
+     * import { NextImageAdapter } from '@pwfabric/runtime/adapters'
+     *
+     * <SurfaceRenderer
+     *   surface={mySurface}
+     *   imageAdapter={NextImageAdapter}
+     * />
+     * ```
+     */
+    readonly imageAdapter?: ImageAdapter;
+    /**
+     * EntityFacade instance for data model access.
+     * When provided, entity data sources and form bindings are activated.
+     * platform/entities is Tier 1 always-on — this prop is optional only
+     * because caller controls instantiation (ConnectorRegistry binding is app-specific).
+     */
+    readonly entityFacade?: EntityFacade;
+    /**
+     * The surface's connections context — the world's
+     * configured connections (single dialect with the runner's
+     * `connections.json` entries) plus the loaded connector-engine registry.
+     * When provided, `{kind:'entity', connector}` data sources route through
+     * the registry and the value is exposed to blocks via
+     * `SurfaceConnectionsContext`. Absent = today's behavior (additive).
+     */
+    readonly connections?: SurfaceConnectionsValue;
+    /**
+     * Editor-only seam (ADR render-unification): wrap each block's layout wrapper
+     * with custom chrome (selection/drag/hover). Receives the runtime-computed
+     * `wrapperProps` so the decorator never recomputes layout. When omitted
+     * (runtime/published path), each block renders in the default `<div>` —
+     * byte-identical to before this seam existed.
+     */
+    readonly renderBlockWrapper?: (args: BlockWrapperRenderArgs) => ReactNode;
+    /**
+     * Interaction mode. Defaults to `live`. `inert` suppresses data auto-refresh
+     * and block-dispatched surface actions (for editor/preview embedding).
+     */
+    readonly interactionMode?: BlockInteractionMode;
+}
+/**
+ * Block renderer props (internal)
+ */
+export interface BlockRendererProps {
+    /** Block to render */
+    readonly block: Block;
+    /** Rendering context */
+    readonly context: BlockContext;
+    /** Component registry */
+    readonly components: BlockComponentRegistry;
+}
+/**
+ * Render result with metadata
+ */
+export interface RenderResult {
+    /** Rendered element */
+    readonly element: ReactNode;
+    /** Block IDs in render tree */
+    readonly blockIds: string[];
+    /** Required capabilities */
+    readonly requiredCapabilities: CapabilityType[];
+}
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/render/types.ts"],"names":[],"mappings":"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"}

package/dist/render/types.js

@@ -0,0 +1,9 @@
+/**
+ * Surface Renderer Types
+ *
+ * Phase 2A.1: Type definitions for Surface-to-React rendering
+ *
+ * @module @pwfabric/runtime/render/types
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/render/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/render/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}

package/dist/render/visibility-css.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Per-breakpoint visibility CSS generation (the `hidden md:flex` equivalent).
+ *
+ * `block.layout.hideOn` / `block.layout.showOn` declare at which breakpoints a
+ * block is hidden / the only breakpoints where it is visible. Inline styles
+ * can't express media queries, so the runtime emits scoped CSS rules — keyed
+ * by the block's `data-block-id` — into the surface's generated `<style>`
+ * (alongside the box-sizing reset). The pixel thresholds are the SAME
+ * `BREAKPOINTS[].minWidth` values the span system uses.
+ *
+ * Semantics:
+ *   - `hideOn: ['xs','sm']` → hidden across the xs+sm ranges → hidden below the
+ *     md threshold (768px) → `@media (max-width:767.98px){ display:none }`.
+ *   - `showOn: ['lg','xl']` → visible ONLY in the lg+xl ranges → hidden below
+ *     lg (1024px) AND at/above the breakpoint after xl (2xl = 1536px).
+ *   - `showOn` is the inverse of `hideOn`; when both are present `showOn` wins.
+ *
+ * @module @pwfabric/runtime/render/visibility-css
+ */
+import type { Block } from '@pwfabric/core';
+import type { BreakpointName } from '@pwfabric/core';
+/**
+ * Resolve the SET of breakpoints at which a block must be hidden, given its
+ * `hideOn` / `showOn` declarations. `showOn` takes precedence (the block is
+ * hidden at every breakpoint NOT listed in `showOn`).
+ */
+export declare function resolveHiddenBreakpoints(hideOn: readonly BreakpointName[] | undefined, showOn: readonly BreakpointName[] | undefined): BreakpointName[];
+/**
+ * Emit the CSS rule(s) that hide a single block at the resolved breakpoints.
+ * Targets `[data-block-id="<id>"]` scoped under the surface root so it cannot
+ * leak to the host page. Uses `!important` so the rule beats the inline layout
+ * style (`display:grid`/flex on the wrapper) it must override.
+ *
+ * Returns '' when there is nothing to hide.
+ */
+export declare function blockVisibilityCss(blockId: string, hidden: BreakpointName[], surfaceId?: string): string;
+/**
+ * Walk a surface block tree and concatenate the per-block visibility CSS for
+ * every block declaring `hideOn` / `showOn`. Blocks without either are skipped
+ * (zero bytes emitted) so existing surfaces are byte-identical.
+ */
+export declare function collectVisibilityCss(blocks: readonly Block[], surfaceId?: string): string;
+//# sourceMappingURL=visibility-css.d.ts.map

package/dist/render/visibility-css.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"visibility-css.d.ts","sourceRoot":"","sources":["../../src/render/visibility-css.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAA;AAE3C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAA;AAiBpD;;;;GAIG;AACH,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,SAAS,cAAc,EAAE,GAAG,SAAS,EAC7C,MAAM,EAAE,SAAS,cAAc,EAAE,GAAG,SAAS,GAC5C,cAAc,EAAE,CAUlB;AA8BD;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,cAAc,EAAE,EACxB,SAAS,CAAC,EAAE,MAAM,GACjB,MAAM,CAeR;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,SAAS,KAAK,EAAE,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,CAWzF"}