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

package/dist/render/capability-gate.js

@@ -0,0 +1,94 @@
+import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
+/**
+ * Capability Gate Components
+ *
+ * Entitlement enforcement at the rendering layer.
+ *
+ * Provides:
+ * - EntitlementProvider: React context for entitlement state
+ * - useEntitlements: Hook to read entitlement state
+ * - GatedBlockPlaceholder: Visual placeholder for unentitled blocks
+ *
+ * @module @pwfabric/runtime/render/capability-gate
+ */
+import * as React from 'react';
+// ============================================================
+// CONTEXT
+// ============================================================
+const EntitlementContext = React.createContext({
+    loaded: false,
+    entitledBlocks: new Set(),
+    entitledCapabilities: new Set(),
+    isBlockEntitled: () => true, // fail-open when no provider
+    isCapabilityEntitled: () => true,
+});
+// ============================================================
+// PROVIDER
+// ============================================================
+/**
+ * EntitlementProvider
+ *
+ * Wraps the app or surface renderer to provide entitlement state.
+ * When entitlements is null (not yet loaded), all checks pass (fail-open).
+ * Once loaded, enforcement is active.
+ */
+export function EntitlementProvider({ entitlements, children, }) {
+    const value = React.useMemo(() => {
+        if (!entitlements) {
+            return {
+                loaded: false,
+                entitledBlocks: new Set(),
+                entitledCapabilities: new Set(),
+                isBlockEntitled: () => true,
+                isCapabilityEntitled: () => true,
+            };
+        }
+        const blocks = new Set(entitlements.blocks);
+        const capabilities = new Set(entitlements.capabilities);
+        return {
+            loaded: true,
+            entitledBlocks: blocks,
+            entitledCapabilities: capabilities,
+            isBlockEntitled: (blockType) => blocks.has(blockType),
+            isCapabilityEntitled: (capability) => capabilities.has(capability),
+        };
+    }, [entitlements]);
+    return React.createElement(EntitlementContext.Provider, { value }, children);
+}
+// ============================================================
+// HOOK
+// ============================================================
+/**
+ * useEntitlements
+ *
+ * Read entitlement state from the nearest EntitlementProvider.
+ */
+export function useEntitlements() {
+    return React.useContext(EntitlementContext);
+}
+/**
+ * GatedBlockPlaceholder
+ *
+ * Renders a visual placeholder for blocks the tenant is not entitled to use.
+ * Uses inline styles (no Tailwind dependency in runtime package).
+ */
+export function GatedBlockPlaceholder({ blockId, blockType, }) {
+    return (_jsxs("div", { "data-block-id": blockId, "data-gated-block": blockType, style: {
+            display: 'flex',
+            flexDirection: 'column',
+            alignItems: 'center',
+            justifyContent: 'center',
+            padding: '24px 16px',
+            // Theme-tokened (was a hardcoded light-gray card that clashed on
+            // dark-themed surfaces). The copy stays — this is a deliberate
+            // marketplace CTA, not an error message.
+            border: '2px dashed var(--pw-color-border, #d1d5db)',
+            borderRadius: '8px',
+            backgroundColor: 'color-mix(in srgb, var(--pw-color-text, #6b7280) 5%, transparent)',
+            color: 'var(--pw-color-text-muted, #6b7280)',
+            textAlign: 'center',
+            minHeight: '80px',
+            gap: '4px',
+        }, children: [_jsxs("span", { style: { fontSize: '14px', fontWeight: 500 }, children: ['\u{1F512}', " ", blockType, " block"] }), _jsx("span", { style: { fontSize: '12px', color: 'var(--pw-color-text-muted, #9ca3af)' }, children: "Install from Marketplace" })] }));
+}
+//# sourceMappingURL=capability-gate.js.map

package/dist/render/capability-gate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capability-gate.js","sourceRoot":"","sources":["../../src/render/capability-gate.tsx"],"names":[],"mappings":";AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAwC9B,+DAA+D;AAC/D,UAAU;AACV,+DAA+D;AAE/D,MAAM,kBAAkB,GAAG,KAAK,CAAC,aAAa,CAA0B;IACtE,MAAM,EAAE,KAAK;IACb,cAAc,EAAE,IAAI,GAAG,EAAE;IACzB,oBAAoB,EAAE,IAAI,GAAG,EAAE;IAC/B,eAAe,EAAE,GAAG,EAAE,CAAC,IAAI,EAAE,6BAA6B;IAC1D,oBAAoB,EAAE,GAAG,EAAE,CAAC,IAAI;CACjC,CAAC,CAAA;AAEF,+DAA+D;AAC/D,WAAW;AACX,+DAA+D;AAE/D;;;;;;GAMG;AACH,MAAM,UAAU,mBAAmB,CAAC,EAClC,YAAY,EACZ,QAAQ,GACiB;IACzB,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,CAA0B,GAAG,EAAE;QACxD,IAAI,CAAC,YAAY,EAAE,CAAC;YAClB,OAAO;gBACL,MAAM,EAAE,KAAK;gBACb,cAAc,EAAE,IAAI,GAAG,EAAE;gBACzB,oBAAoB,EAAE,IAAI,GAAG,EAAE;gBAC/B,eAAe,EAAE,GAAG,EAAE,CAAC,IAAI;gBAC3B,oBAAoB,EAAE,GAAG,EAAE,CAAC,IAAI;aACjC,CAAA;QACH,CAAC;QAED,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,YAAY,CAAC,MAAM,CAAC,CAAA;QAC3C,MAAM,YAAY,GAAG,IAAI,GAAG,CAAC,YAAY,CAAC,YAAY,CAAC,CAAA;QAEvD,OAAO;YACL,MAAM,EAAE,IAAI;YACZ,cAAc,EAAE,MAAM;YACtB,oBAAoB,EAAE,YAAY;YAClC,eAAe,EAAE,CAAC,SAAiB,EAAE,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,SAAS,CAAC;YAC7D,oBAAoB,EAAE,CAAC,UAAkB,EAAE,EAAE,CAAC,YAAY,CAAC,GAAG,CAAC,UAAU,CAAC;SAC3E,CAAA;IACH,CAAC,EAAE,CAAC,YAAY,CAAC,CAAC,CAAA;IAElB,OAAO,KAAK,CAAC,aAAa,CAAC,kBAAkB,CAAC,QAAQ,EAAE,EAAE,KAAK,EAAE,EAAE,QAAQ,CAAC,CAAA;AAC9E,CAAC;AAED,+DAA+D;AAC/D,OAAO;AACP,+DAA+D;AAE/D;;;;GAIG;AACH,MAAM,UAAU,eAAe;IAC7B,OAAO,KAAK,CAAC,UAAU,CAAC,kBAAkB,CAAC,CAAA;AAC7C,CAAC;AAWD;;;;;GAKG;AACH,MAAM,UAAU,qBAAqB,CAAC,EACpC,OAAO,EACP,SAAS,GACkB;IAC3B,OAAO,CACL,gCACiB,OAAO,sBACJ,SAAS,EAC3B,KAAK,EAAE;YACL,OAAO,EAAE,MAAM;YACf,aAAa,EAAE,QAAQ;YACvB,UAAU,EAAE,QAAQ;YACpB,cAAc,EAAE,QAAQ;YACxB,OAAO,EAAE,WAAW;YACpB,iEAAiE;YACjE,+DAA+D;YAC/D,yCAAyC;YACzC,MAAM,EAAE,4CAA4C;YACpD,YAAY,EAAE,KAAK;YACnB,eAAe,EAAE,mEAAmE;YACpF,KAAK,EAAE,qCAAqC;YAC5C,SAAS,EAAE,QAAQ;YACnB,SAAS,EAAE,MAAM;YACjB,GAAG,EAAE,KAAK;SACX,aAED,gBAAM,KAAK,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,GAAG,EAAE,aAC/C,WAAW,OAAG,SAAS,cACnB,EACP,eAAM,KAAK,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,qCAAqC,EAAE,yCAAiC,IAC5G,CACP,CAAA;AACH,CAAC","sourcesContent":["/**\n * Capability Gate Components\n *\n * Entitlement enforcement at the rendering layer.\n *\n * Provides:\n * - EntitlementProvider: React context for entitlement state\n * - useEntitlements: Hook to read entitlement state\n * - GatedBlockPlaceholder: Visual placeholder for unentitled blocks\n *\n * @module @pwfabric/runtime/render/capability-gate\n */\n\nimport * as React from 'react'\n\n// ============================================================\n// TYPES\n// ============================================================\n\n/**\n * The claim set this gate reads.\n *\n * Enforcing a claim set is a rendering mechanism; deciding WHO is entitled to\n * WHAT is the host's business. A host's own entitlement type conforms to this\n * shape structurally.\n *\n * Keeping the gate but not the vocabulary is the point: the engine can\n * enforce entitlements for a product it knows nothing about.\n */\nexport interface EntitlementClaims {\n  readonly blocks: readonly string[]\n  readonly capabilities: readonly string[]\n}\n\nexport interface EntitlementContextValue {\n  /** Whether entitlements have been loaded */\n  readonly loaded: boolean\n  /** Set of entitled block types */\n  readonly entitledBlocks: ReadonlySet<string>\n  /** Set of entitled capabilities */\n  readonly entitledCapabilities: ReadonlySet<string>\n  /** Check if a specific block type is entitled */\n  readonly isBlockEntitled: (blockType: string) => boolean\n  /** Check if a specific capability is entitled */\n  readonly isCapabilityEntitled: (capability: string) => boolean\n}\n\nexport interface EntitlementProviderProps {\n  /** The claim set from the host, or null if not yet loaded */\n  readonly entitlements: EntitlementClaims | null\n  readonly children: React.ReactNode\n}\n\n// ============================================================\n// CONTEXT\n// ============================================================\n\nconst EntitlementContext = React.createContext<EntitlementContextValue>({\n  loaded: false,\n  entitledBlocks: new Set(),\n  entitledCapabilities: new Set(),\n  isBlockEntitled: () => true, // fail-open when no provider\n  isCapabilityEntitled: () => true,\n})\n\n// ============================================================\n// PROVIDER\n// ============================================================\n\n/**\n * EntitlementProvider\n *\n * Wraps the app or surface renderer to provide entitlement state.\n * When entitlements is null (not yet loaded), all checks pass (fail-open).\n * Once loaded, enforcement is active.\n */\nexport function EntitlementProvider({\n  entitlements,\n  children,\n}: EntitlementProviderProps): React.ReactElement {\n  const value = React.useMemo<EntitlementContextValue>(() => {\n    if (!entitlements) {\n      return {\n        loaded: false,\n        entitledBlocks: new Set(),\n        entitledCapabilities: new Set(),\n        isBlockEntitled: () => true,\n        isCapabilityEntitled: () => true,\n      }\n    }\n\n    const blocks = new Set(entitlements.blocks)\n    const capabilities = new Set(entitlements.capabilities)\n\n    return {\n      loaded: true,\n      entitledBlocks: blocks,\n      entitledCapabilities: capabilities,\n      isBlockEntitled: (blockType: string) => blocks.has(blockType),\n      isCapabilityEntitled: (capability: string) => capabilities.has(capability),\n    }\n  }, [entitlements])\n\n  return React.createElement(EntitlementContext.Provider, { value }, children)\n}\n\n// ============================================================\n// HOOK\n// ============================================================\n\n/**\n * useEntitlements\n *\n * Read entitlement state from the nearest EntitlementProvider.\n */\nexport function useEntitlements(): EntitlementContextValue {\n  return React.useContext(EntitlementContext)\n}\n\n// ============================================================\n// GATED BLOCK PLACEHOLDER\n// ============================================================\n\nexport interface GatedBlockPlaceholderProps {\n  readonly blockId: string\n  readonly blockType: string\n}\n\n/**\n * GatedBlockPlaceholder\n *\n * Renders a visual placeholder for blocks the tenant is not entitled to use.\n * Uses inline styles (no Tailwind dependency in runtime package).\n */\nexport function GatedBlockPlaceholder({\n  blockId,\n  blockType,\n}: GatedBlockPlaceholderProps): React.ReactElement {\n  return (\n    <div\n      data-block-id={blockId}\n      data-gated-block={blockType}\n      style={{\n        display: 'flex',\n        flexDirection: 'column',\n        alignItems: 'center',\n        justifyContent: 'center',\n        padding: '24px 16px',\n        // Theme-tokened (was a hardcoded light-gray card that clashed on\n        // dark-themed surfaces). The copy stays — this is a deliberate\n        // marketplace CTA, not an error message.\n        border: '2px dashed var(--pw-color-border, #d1d5db)',\n        borderRadius: '8px',\n        backgroundColor: 'color-mix(in srgb, var(--pw-color-text, #6b7280) 5%, transparent)',\n        color: 'var(--pw-color-text-muted, #6b7280)',\n        textAlign: 'center',\n        minHeight: '80px',\n        gap: '4px',\n      }}\n    >\n      <span style={{ fontSize: '14px', fontWeight: 500 }}>\n        {'\\u{1F512}'} {blockType} block\n      </span>\n      <span style={{ fontSize: '12px', color: 'var(--pw-color-text-muted, #9ca3af)' }}>Install from Marketplace</span>\n    </div>\n  )\n}\n"]}

package/dist/render/conditional-states-css.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Conditional-state CSS generation (aria/data/disabled/checked/`:has(…)` variants).
+ *
+ * `block.style` sits inline and cannot express pseudo-classes or attribute
+ * selectors, and the fixed `block.states` field only covers the three
+ * interaction pseudo-classes (`:hover`/`:active`/`:focus-visible`). Everything
+ * else a block can style by STATE without JS — form pseudo-classes
+ * (`:disabled`, `:checked`, `:invalid`, `:required`), ARIA reflections
+ * (`[aria-expanded="true"]`), `data-*` flags (`[data-active]`), and structural
+ * `:has(…)` / sibling rules — lives in `block.conditionalStates`. Each entry's
+ * `selector` is a CSS suffix APPENDED to the block selector, so the runtime
+ * emits:
+ *
+ *   `[data-pw-surface] [data-block-id="<id>"]:disabled{ … }`
+ *   `[data-pw-surface] [data-block-id="<id>"][aria-expanded="true"]{ … }`
+ *   `[data-pw-surface] [data-block-id="<id>"]:has(> img){ … }`
+ *
+ * Keys are CSS camelCase property names (converted to kebab-case); declarations
+ * are emitted with `!important` because a block COMPONENT often applies the same
+ * CSS property inline with its own default, and inline beats any plain
+ * stylesheet rule. Scoped to `[data-block-id]`, so it only overrides the one
+ * block. Blocks without `conditionalStates` emit zero bytes so existing surfaces
+ * are byte-identical.
+ *
+ * @module @pwfabric/runtime/render/conditional-states-css
+ */
+import type { Block } from '@pwfabric/core';
+/**
+ * Emit the scoped CSS rule(s) for a single block's conditional states. Targets
+ * `[data-block-id="<id>"]<selector>` scoped under the surface root so it cannot
+ * leak to the host page. Entries with a malformed `selector` (not a valid
+ * suffix) or an empty `style` record are skipped. Returns '' when the block
+ * declares no usable conditional state.
+ */
+export declare function blockConditionalStatesCss(blockId: string, conditionalStates: NonNullable<Block['conditionalStates']>, surfaceId?: string): string;
+/**
+ * Walk a surface block tree and concatenate the per-block conditional-state CSS
+ * for every block declaring `conditionalStates`. Blocks without it are skipped
+ * (zero bytes emitted) so existing surfaces are byte-identical.
+ */
+export declare function collectConditionalStatesCss(blocks: readonly Block[], surfaceId?: string): string;

package/dist/render/conditional-states-css.js

@@ -0,0 +1,82 @@
+/**
+ * Conditional-state CSS generation (aria/data/disabled/checked/`:has(…)` variants).
+ *
+ * `block.style` sits inline and cannot express pseudo-classes or attribute
+ * selectors, and the fixed `block.states` field only covers the three
+ * interaction pseudo-classes (`:hover`/`:active`/`:focus-visible`). Everything
+ * else a block can style by STATE without JS — form pseudo-classes
+ * (`:disabled`, `:checked`, `:invalid`, `:required`), ARIA reflections
+ * (`[aria-expanded="true"]`), `data-*` flags (`[data-active]`), and structural
+ * `:has(…)` / sibling rules — lives in `block.conditionalStates`. Each entry's
+ * `selector` is a CSS suffix APPENDED to the block selector, so the runtime
+ * emits:
+ *
+ *   `[data-pw-surface] [data-block-id="<id>"]:disabled{ … }`
+ *   `[data-pw-surface] [data-block-id="<id>"][aria-expanded="true"]{ … }`
+ *   `[data-pw-surface] [data-block-id="<id>"]:has(> img){ … }`
+ *
+ * Keys are CSS camelCase property names (converted to kebab-case); declarations
+ * are emitted with `!important` because a block COMPONENT often applies the same
+ * CSS property inline with its own default, and inline beats any plain
+ * stylesheet rule. Scoped to `[data-block-id]`, so it only overrides the one
+ * block. Blocks without `conditionalStates` emit zero bytes so existing surfaces
+ * are byte-identical.
+ *
+ * @module @pwfabric/runtime/render/conditional-states-css
+ */
+import { blockSelector, camelToKebab, collectScopedCss } from './scoped-css.js';
+/** Serialize a camelCase decl record to `prop:value !important;…` (values pass through). */
+function declsToCss(decls) {
+    return Object.entries(decls)
+        .map(([prop, value]) => `${camelToKebab(prop)}:${value} !important`)
+        .join(';');
+}
+/**
+ * A conditional-state selector must be a SUFFIX that attaches directly to the
+ * block selector — never a bare/standalone selector that could match (and leak
+ * to) unrelated elements on the host page. Valid first characters:
+ *   `:` pseudo-class/element (`:disabled`, `:has(…)`)
+ *   `[` attribute selector (`[aria-expanded="true"]`, `[data-active]`)
+ *   `>` `+` `~` combinators (`> img`, `+ .x`, `~ .y`)
+ *   whitespace — descendant combinator (` .child`)
+ * Anything else (a bare `.class`, `div`, `*`, empty string) is rejected.
+ */
+function isValidSuffixSelector(selector) {
+    if (typeof selector !== 'string' || selector.length === 0)
+        return false;
+    const first = selector.charAt(0);
+    return first === ':' || first === '[' || first === '>' || first === '+' || first === '~' || /\s/.test(first);
+}
+/**
+ * Emit the scoped CSS rule(s) for a single block's conditional states. Targets
+ * `[data-block-id="<id>"]<selector>` scoped under the surface root so it cannot
+ * leak to the host page. Entries with a malformed `selector` (not a valid
+ * suffix) or an empty `style` record are skipped. Returns '' when the block
+ * declares no usable conditional state.
+ */
+export function blockConditionalStatesCss(blockId, conditionalStates, surfaceId) {
+    const selector = blockSelector(blockId, surfaceId);
+    let css = '';
+    for (const entry of conditionalStates) {
+        if (!entry || !isValidSuffixSelector(entry.selector))
+            continue;
+        const decls = entry.style;
+        if (!decls || Object.keys(decls).length === 0)
+            continue;
+        // Same wrapper-exclusion as states-css: the id matches two elements; the
+        // visual rule must land on the component root, not the square wrapper.
+        css += `${selector}:not([data-block-wrapper])${entry.selector}{${declsToCss(decls)}}`;
+    }
+    return css;
+}
+/**
+ * Walk a surface block tree and concatenate the per-block conditional-state CSS
+ * for every block declaring `conditionalStates`. Blocks without it are skipped
+ * (zero bytes emitted) so existing surfaces are byte-identical.
+ */
+export function collectConditionalStatesCss(blocks, surfaceId) {
+    return collectScopedCss(blocks, (block) => block.conditionalStates
+        ? blockConditionalStatesCss(block.id, block.conditionalStates, surfaceId)
+        : '');
+}
+//# sourceMappingURL=conditional-states-css.js.map

package/dist/render/conditional-states-css.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"conditional-states-css.js","sourceRoot":"","sources":["../../src/render/conditional-states-css.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAGH,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAA;AAE/E,4FAA4F;AAC5F,SAAS,UAAU,CAAC,KAAuC;IACzD,OAAO,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC;SACzB,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,GAAG,YAAY,CAAC,IAAI,CAAC,IAAI,KAAK,aAAa,CAAC;SACnE,IAAI,CAAC,GAAG,CAAC,CAAA;AACd,CAAC;AAED;;;;;;;;;GASG;AACH,SAAS,qBAAqB,CAAC,QAAgB;IAC7C,IAAI,OAAO,QAAQ,KAAK,QAAQ,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,KAAK,CAAA;IACvE,MAAM,KAAK,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAA;IAChC,OAAO,KAAK,KAAK,GAAG,IAAI,KAAK,KAAK,GAAG,IAAI,KAAK,KAAK,GAAG,IAAI,KAAK,KAAK,GAAG,IAAI,KAAK,KAAK,GAAG,IAAI,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;AAC9G,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,yBAAyB,CACvC,OAAe,EACf,iBAA0D,EAC1D,SAAkB;IAElB,MAAM,QAAQ,GAAG,aAAa,CAAC,OAAO,EAAE,SAAS,CAAC,CAAA;IAClD,IAAI,GAAG,GAAG,EAAE,CAAA;IACZ,KAAK,MAAM,KAAK,IAAI,iBAAiB,EAAE,CAAC;QACtC,IAAI,CAAC,KAAK,IAAI,CAAC,qBAAqB,CAAC,KAAK,CAAC,QAAQ,CAAC;YAAE,SAAQ;QAC9D,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAA;QACzB,IAAI,CAAC,KAAK,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,MAAM,KAAK,CAAC;YAAE,SAAQ;QACvD,yEAAyE;QACzE,uEAAuE;QACvE,GAAG,IAAI,GAAG,QAAQ,6BAA6B,KAAK,CAAC,QAAQ,IAAI,UAAU,CAAC,KAAK,CAAC,GAAG,CAAA;IACvF,CAAC;IACD,OAAO,GAAG,CAAA;AACZ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,2BAA2B,CAAC,MAAwB,EAAE,SAAkB;IACtF,OAAO,gBAAgB,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,EAAE,CACxC,KAAK,CAAC,iBAAiB;QACrB,CAAC,CAAC,yBAAyB,CAAC,KAAK,CAAC,EAAE,EAAE,KAAK,CAAC,iBAAiB,EAAE,SAAS,CAAC;QACzE,CAAC,CAAC,EAAE,CACP,CAAA;AACH,CAAC","sourcesContent":["/**\n * Conditional-state CSS generation (aria/data/disabled/checked/`:has(…)` variants).\n *\n * `block.style` sits inline and cannot express pseudo-classes or attribute\n * selectors, and the fixed `block.states` field only covers the three\n * interaction pseudo-classes (`:hover`/`:active`/`:focus-visible`). Everything\n * else a block can style by STATE without JS — form pseudo-classes\n * (`:disabled`, `:checked`, `:invalid`, `:required`), ARIA reflections\n * (`[aria-expanded=\"true\"]`), `data-*` flags (`[data-active]`), and structural\n * `:has(…)` / sibling rules — lives in `block.conditionalStates`. Each entry's\n * `selector` is a CSS suffix APPENDED to the block selector, so the runtime\n * emits:\n *\n *   `[data-pw-surface] [data-block-id=\"<id>\"]:disabled{ … }`\n *   `[data-pw-surface] [data-block-id=\"<id>\"][aria-expanded=\"true\"]{ … }`\n *   `[data-pw-surface] [data-block-id=\"<id>\"]:has(> img){ … }`\n *\n * Keys are CSS camelCase property names (converted to kebab-case); declarations\n * are emitted with `!important` because a block COMPONENT often applies the same\n * CSS property inline with its own default, and inline beats any plain\n * stylesheet rule. Scoped to `[data-block-id]`, so it only overrides the one\n * block. Blocks without `conditionalStates` emit zero bytes so existing surfaces\n * are byte-identical.\n *\n * @module @pwfabric/runtime/render/conditional-states-css\n */\n\nimport type { Block } from '@pwfabric/core'\nimport { blockSelector, camelToKebab, collectScopedCss } from './scoped-css.js'\n\n/** Serialize a camelCase decl record to `prop:value !important;…` (values pass through). */\nfunction declsToCss(decls: Readonly<Record<string, string>>): string {\n  return Object.entries(decls)\n    .map(([prop, value]) => `${camelToKebab(prop)}:${value} !important`)\n    .join(';')\n}\n\n/**\n * A conditional-state selector must be a SUFFIX that attaches directly to the\n * block selector — never a bare/standalone selector that could match (and leak\n * to) unrelated elements on the host page. Valid first characters:\n *   `:` pseudo-class/element (`:disabled`, `:has(…)`)\n *   `[` attribute selector (`[aria-expanded=\"true\"]`, `[data-active]`)\n *   `>` `+` `~` combinators (`> img`, `+ .x`, `~ .y`)\n *   whitespace — descendant combinator (` .child`)\n * Anything else (a bare `.class`, `div`, `*`, empty string) is rejected.\n */\nfunction isValidSuffixSelector(selector: string): boolean {\n  if (typeof selector !== 'string' || selector.length === 0) return false\n  const first = selector.charAt(0)\n  return first === ':' || first === '[' || first === '>' || first === '+' || first === '~' || /\\s/.test(first)\n}\n\n/**\n * Emit the scoped CSS rule(s) for a single block's conditional states. Targets\n * `[data-block-id=\"<id>\"]<selector>` scoped under the surface root so it cannot\n * leak to the host page. Entries with a malformed `selector` (not a valid\n * suffix) or an empty `style` record are skipped. Returns '' when the block\n * declares no usable conditional state.\n */\nexport function blockConditionalStatesCss(\n  blockId: string,\n  conditionalStates: NonNullable<Block['conditionalStates']>,\n  surfaceId?: string\n): string {\n  const selector = blockSelector(blockId, surfaceId)\n  let css = ''\n  for (const entry of conditionalStates) {\n    if (!entry || !isValidSuffixSelector(entry.selector)) continue\n    const decls = entry.style\n    if (!decls || Object.keys(decls).length === 0) continue\n    // Same wrapper-exclusion as states-css: the id matches two elements; the\n    // visual rule must land on the component root, not the square wrapper.\n    css += `${selector}:not([data-block-wrapper])${entry.selector}{${declsToCss(decls)}}`\n  }\n  return css\n}\n\n/**\n * Walk a surface block tree and concatenate the per-block conditional-state CSS\n * for every block declaring `conditionalStates`. Blocks without it are skipped\n * (zero bytes emitted) so existing surfaces are byte-identical.\n */\nexport function collectConditionalStatesCss(blocks: readonly Block[], surfaceId?: string): string {\n  return collectScopedCss(blocks, (block) =>\n    block.conditionalStates\n      ? blockConditionalStatesCss(block.id, block.conditionalStates, surfaceId)\n      : ''\n  )\n}\n"]}

package/dist/render/connections-context.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Surface Connections React Context
+ *
+ * Carries the surface's CONNECTIONS CONTEXT — the world's configured
+ * connections (name/connector/config, single dialect with the runner's
+ * `connections.json` entries) plus the loaded engine registry — through
+ * the render tree. Pattern mirrors `EntityFacadeContext`.
+ *
+ * Consumers:
+ * - `DataBoundSurfaceRenderer` routes `{kind:'entity', connector}` data
+ *   sources through the registry (via the renderer prop, not this context
+ *   — the fetch runs above `SurfaceRenderer`).
+ * - Pack blocks on the engine-bridge path read connections/config here
+ *   (platform source) instead of the runner's bundled connections.json —
+ *   same shape, different source.
+ *
+ * Absent provider = null = today's behavior (additive, opt-in).
+ *
+ * @module @pwfabric/runtime/render/connections-context
+ */
+import type { SurfaceConnectionsValue } from '../connectors/types.js';
+/**
+ * React context carrying the connections context. Defaults to null —
+ * hosts that don't provide it keep today's behavior everywhere.
+ */
+export declare const SurfaceConnectionsContext: import("react").Context<SurfaceConnectionsValue | null>;
+/**
+ * Returns the connections context from the nearest provider, or null when
+ * the host didn't opt in (runner default path, legacy platform rendering).
+ */
+export declare function useSurfaceConnections(): SurfaceConnectionsValue | null;

package/dist/render/connections-context.js

@@ -0,0 +1,34 @@
+/**
+ * Surface Connections React Context
+ *
+ * Carries the surface's CONNECTIONS CONTEXT — the world's configured
+ * connections (name/connector/config, single dialect with the runner's
+ * `connections.json` entries) plus the loaded engine registry — through
+ * the render tree. Pattern mirrors `EntityFacadeContext`.
+ *
+ * Consumers:
+ * - `DataBoundSurfaceRenderer` routes `{kind:'entity', connector}` data
+ *   sources through the registry (via the renderer prop, not this context
+ *   — the fetch runs above `SurfaceRenderer`).
+ * - Pack blocks on the engine-bridge path read connections/config here
+ *   (platform source) instead of the runner's bundled connections.json —
+ *   same shape, different source.
+ *
+ * Absent provider = null = today's behavior (additive, opt-in).
+ *
+ * @module @pwfabric/runtime/render/connections-context
+ */
+import { createContext, useContext } from 'react';
+/**
+ * React context carrying the connections context. Defaults to null —
+ * hosts that don't provide it keep today's behavior everywhere.
+ */
+export const SurfaceConnectionsContext = createContext(null);
+/**
+ * Returns the connections context from the nearest provider, or null when
+ * the host didn't opt in (runner default path, legacy platform rendering).
+ */
+export function useSurfaceConnections() {
+    return useContext(SurfaceConnectionsContext);
+}
+//# sourceMappingURL=connections-context.js.map

package/dist/render/connections-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"connections-context.js","sourceRoot":"","sources":["../../src/render/connections-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,OAAO,CAAA;AAGjD;;;GAGG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,aAAa,CAAiC,IAAI,CAAC,CAAA;AAE5F;;;GAGG;AACH,MAAM,UAAU,qBAAqB;IACnC,OAAO,UAAU,CAAC,yBAAyB,CAAC,CAAA;AAC9C,CAAC","sourcesContent":["/**\n * Surface Connections React Context\n *\n * Carries the surface's CONNECTIONS CONTEXT — the world's configured\n * connections (name/connector/config, single dialect with the runner's\n * `connections.json` entries) plus the loaded engine registry — through\n * the render tree. Pattern mirrors `EntityFacadeContext`.\n *\n * Consumers:\n * - `DataBoundSurfaceRenderer` routes `{kind:'entity', connector}` data\n *   sources through the registry (via the renderer prop, not this context\n *   — the fetch runs above `SurfaceRenderer`).\n * - Pack blocks on the engine-bridge path read connections/config here\n *   (platform source) instead of the runner's bundled connections.json —\n *   same shape, different source.\n *\n * Absent provider = null = today's behavior (additive, opt-in).\n *\n * @module @pwfabric/runtime/render/connections-context\n */\n\nimport { createContext, useContext } from 'react'\nimport type { SurfaceConnectionsValue } from '../connectors/types.js'\n\n/**\n * React context carrying the connections context. Defaults to null —\n * hosts that don't provide it keep today's behavior everywhere.\n */\nexport const SurfaceConnectionsContext = createContext<SurfaceConnectionsValue | null>(null)\n\n/**\n * Returns the connections context from the nearest provider, or null when\n * the host didn't opt in (runner default path, legacy platform rendering).\n */\nexport function useSurfaceConnections(): SurfaceConnectionsValue | null {\n  return useContext(SurfaceConnectionsContext)\n}\n"]}

package/dist/render/dark-theme-css.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Dark theme variant CSS generation (the "both strategies" dark mode).
+ *
+ * Light theme tokens stay INLINE on the surface root (`[data-pw-surface]`); this
+ * module emits the scoped rules that override them under TWO conditions:
+ *
+ *   1. Manual force-dark — `[data-pw-surface="<sid>"][data-pw-theme="dark"]{…}`
+ *      (host toggles `data-pw-theme="dark"` on the root regardless of OS).
+ *   2. Auto (OS preference) — `@media (prefers-color-scheme:dark){
+ *      [data-pw-surface="<sid>"]:not([data-pw-theme="light"]){…}}` (applies
+ *      unless the host has force-toggled light).
+ *
+ * The selector carries the surface ID by VALUE. It used to match on the mere
+ * PRESENCE of `[data-pw-surface]`, which was a real bug: the embed autoloader
+ * hydrates every `[data-pw-surface]` element in a document, so a host page can
+ * hold several surfaces with different palettes. Each emitted its own `<style>`
+ * with the same value-less selector and `!important`, so equal specificity made
+ * DOCUMENT ORDER decide — the last surface's dark palette repainted all of them.
+ * Reproduced in Chromium: a blue-themed surface rendered the amber surface's
+ * dark background. The light theme was never affected because its values are
+ * inline per element and custom properties inherit.
+ *
+ * @module @pwfabric/runtime/render/dark-theme-css
+ */
+import type { AppearanceModePolicy } from '@pwfabric/contracts';
+/**
+ * Build the dark theme CSS from a resolved dark CSS-variable map (the output of
+ * `resolveAppearanceDarkVars`). Emits BOTH the manual force-dark rule and the
+ * `prefers-color-scheme:dark` auto rule. Returns '' when there are no dark vars.
+ *
+ * @param darkVars - resolved `--pw-*` map for the dark variant
+ * @param surfaceId - scopes the rules to ONE surface. Omit only when rendering a
+ *   single surface in isolation (unit tests); the renderer always supplies it,
+ *   because two surfaces sharing a document must not share a dark palette.
+ */
+export declare function buildDarkThemeCss(darkVars: Record<string, string>, surfaceId?: string, policy?: AppearanceModePolicy): string;

package/dist/render/dark-theme-css.js

@@ -0,0 +1,67 @@
+/**
+ * Dark theme variant CSS generation (the "both strategies" dark mode).
+ *
+ * Light theme tokens stay INLINE on the surface root (`[data-pw-surface]`); this
+ * module emits the scoped rules that override them under TWO conditions:
+ *
+ *   1. Manual force-dark — `[data-pw-surface="<sid>"][data-pw-theme="dark"]{…}`
+ *      (host toggles `data-pw-theme="dark"` on the root regardless of OS).
+ *   2. Auto (OS preference) — `@media (prefers-color-scheme:dark){
+ *      [data-pw-surface="<sid>"]:not([data-pw-theme="light"]){…}}` (applies
+ *      unless the host has force-toggled light).
+ *
+ * The selector carries the surface ID by VALUE. It used to match on the mere
+ * PRESENCE of `[data-pw-surface]`, which was a real bug: the embed autoloader
+ * hydrates every `[data-pw-surface]` element in a document, so a host page can
+ * hold several surfaces with different palettes. Each emitted its own `<style>`
+ * with the same value-less selector and `!important`, so equal specificity made
+ * DOCUMENT ORDER decide — the last surface's dark palette repainted all of them.
+ * Reproduced in Chromium: a blue-themed surface rendered the amber surface's
+ * dark background. The light theme was never affected because its values are
+ * inline per element and custom properties inherit.
+ *
+ * @module @pwfabric/runtime/render/dark-theme-css
+ */
+import { surfaceScope } from './scoped-css.js';
+/**
+ * Serialize a `--pw-*` CSS-var map to `--pw-…:val !important;…`.
+ * `!important`: the LIGHT theme vars are applied INLINE on the surface root
+ * (`rootStyle`), and an inline declaration beats any stylesheet/@media rule — so
+ * without `!important` the dark overrides would never take effect. `!important`
+ * on a custom-property declaration is honoured by the cascade and lets the
+ * stylesheet dark vars override the inline light vars.
+ */
+function varsToCss(vars) {
+    return Object.entries(vars)
+        .map(([name, value]) => `${name}:${value} !important`)
+        .join(';');
+}
+/**
+ * Build the dark theme CSS from a resolved dark CSS-variable map (the output of
+ * `resolveAppearanceDarkVars`). Emits BOTH the manual force-dark rule and the
+ * `prefers-color-scheme:dark` auto rule. Returns '' when there are no dark vars.
+ *
+ * @param darkVars - resolved `--pw-*` map for the dark variant
+ * @param surfaceId - scopes the rules to ONE surface. Omit only when rendering a
+ *   single surface in isolation (unit tests); the renderer always supplies it,
+ *   because two surfaces sharing a document must not share a dark palette.
+ */
+export function buildDarkThemeCss(darkVars, surfaceId, policy = 'system') {
+    // The app says which modes it wears. A light-only app emits no
+    // dark rule at all, so a dark device keeps it light; a dark-only app wears the
+    // dark palette unconditionally. `system` follows the device.
+    if (policy === 'light')
+        return '';
+    const body = varsToCss(darkVars);
+    if (!body)
+        return '';
+    const scope = surfaceScope(surfaceId);
+    if (policy === 'dark')
+        return `${scope}{${body}}`;
+    // 1. Manual force-dark (host sets data-pw-theme="dark").
+    const manual = `${scope}[data-pw-theme="dark"]{${body}}`;
+    // 2. Auto via OS preference, unless force-light (data-pw-theme="light").
+    const auto = `@media (prefers-color-scheme:dark){${scope}:not([data-pw-theme="light"]){${body}}}`;
+    return manual + auto;
+}
+//# sourceMappingURL=dark-theme-css.js.map

package/dist/render/dark-theme-css.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dark-theme-css.js","sourceRoot":"","sources":["../../src/render/dark-theme-css.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAGH,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAA;AAE9C;;;;;;;GAOG;AACH,SAAS,SAAS,CAAC,IAA4B;IAC7C,OAAO,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC;SACxB,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,GAAG,IAAI,IAAI,KAAK,aAAa,CAAC;SACrD,IAAI,CAAC,GAAG,CAAC,CAAA;AACd,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,iBAAiB,CAC/B,QAAgC,EAChC,SAAkB,EAClB,SAA+B,QAAQ;IAEvC,+DAA+D;IAC/D,+EAA+E;IAC/E,6DAA6D;IAC7D,IAAI,MAAM,KAAK,OAAO;QAAE,OAAO,EAAE,CAAA;IACjC,MAAM,IAAI,GAAG,SAAS,CAAC,QAAQ,CAAC,CAAA;IAChC,IAAI,CAAC,IAAI;QAAE,OAAO,EAAE,CAAA;IACpB,MAAM,KAAK,GAAG,YAAY,CAAC,SAAS,CAAC,CAAA;IACrC,IAAI,MAAM,KAAK,MAAM;QAAE,OAAO,GAAG,KAAK,IAAI,IAAI,GAAG,CAAA;IACjD,yDAAyD;IACzD,MAAM,MAAM,GAAG,GAAG,KAAK,0BAA0B,IAAI,GAAG,CAAA;IACxD,yEAAyE;IACzE,MAAM,IAAI,GAAG,sCAAsC,KAAK,iCAAiC,IAAI,IAAI,CAAA;IACjG,OAAO,MAAM,GAAG,IAAI,CAAA;AACtB,CAAC","sourcesContent":["/**\n * Dark theme variant CSS generation (the \"both strategies\" dark mode).\n *\n * Light theme tokens stay INLINE on the surface root (`[data-pw-surface]`); this\n * module emits the scoped rules that override them under TWO conditions:\n *\n *   1. Manual force-dark — `[data-pw-surface=\"<sid>\"][data-pw-theme=\"dark\"]{…}`\n *      (host toggles `data-pw-theme=\"dark\"` on the root regardless of OS).\n *   2. Auto (OS preference) — `@media (prefers-color-scheme:dark){\n *      [data-pw-surface=\"<sid>\"]:not([data-pw-theme=\"light\"]){…}}` (applies\n *      unless the host has force-toggled light).\n *\n * The selector carries the surface ID by VALUE. It used to match on the mere\n * PRESENCE of `[data-pw-surface]`, which was a real bug: the embed autoloader\n * hydrates every `[data-pw-surface]` element in a document, so a host page can\n * hold several surfaces with different palettes. Each emitted its own `<style>`\n * with the same value-less selector and `!important`, so equal specificity made\n * DOCUMENT ORDER decide — the last surface's dark palette repainted all of them.\n * Reproduced in Chromium: a blue-themed surface rendered the amber surface's\n * dark background. The light theme was never affected because its values are\n * inline per element and custom properties inherit.\n *\n * @module @pwfabric/runtime/render/dark-theme-css\n */\n\nimport type { AppearanceModePolicy } from '@pwfabric/contracts'\nimport { surfaceScope } from './scoped-css.js'\n\n/**\n * Serialize a `--pw-*` CSS-var map to `--pw-…:val !important;…`.\n * `!important`: the LIGHT theme vars are applied INLINE on the surface root\n * (`rootStyle`), and an inline declaration beats any stylesheet/@media rule — so\n * without `!important` the dark overrides would never take effect. `!important`\n * on a custom-property declaration is honoured by the cascade and lets the\n * stylesheet dark vars override the inline light vars.\n */\nfunction varsToCss(vars: Record<string, string>): string {\n  return Object.entries(vars)\n    .map(([name, value]) => `${name}:${value} !important`)\n    .join(';')\n}\n\n/**\n * Build the dark theme CSS from a resolved dark CSS-variable map (the output of\n * `resolveAppearanceDarkVars`). Emits BOTH the manual force-dark rule and the\n * `prefers-color-scheme:dark` auto rule. Returns '' when there are no dark vars.\n *\n * @param darkVars - resolved `--pw-*` map for the dark variant\n * @param surfaceId - scopes the rules to ONE surface. Omit only when rendering a\n *   single surface in isolation (unit tests); the renderer always supplies it,\n *   because two surfaces sharing a document must not share a dark palette.\n */\nexport function buildDarkThemeCss(\n  darkVars: Record<string, string>,\n  surfaceId?: string,\n  policy: AppearanceModePolicy = 'system'\n): string {\n  // The app says which modes it wears. A light-only app emits no\n  // dark rule at all, so a dark device keeps it light; a dark-only app wears the\n  // dark palette unconditionally. `system` follows the device.\n  if (policy === 'light') return ''\n  const body = varsToCss(darkVars)\n  if (!body) return ''\n  const scope = surfaceScope(surfaceId)\n  if (policy === 'dark') return `${scope}{${body}}`\n  // 1. Manual force-dark (host sets data-pw-theme=\"dark\").\n  const manual = `${scope}[data-pw-theme=\"dark\"]{${body}}`\n  // 2. Auto via OS preference, unless force-light (data-pw-theme=\"light\").\n  const auto = `@media (prefers-color-scheme:dark){${scope}:not([data-pw-theme=\"light\"]){${body}}}`\n  return manual + auto\n}\n"]}

package/dist/render/data-binding-types.d.ts

@@ -0,0 +1,191 @@
+/**
+ * Data Binding Types for Surface Renderer
+ *
+ * Type definitions for data-bound surface rendering.
+ * These types define the shape of surface JSON definitions that include
+ * dataSources, state, and expression-based prop bindings.
+ *
+ * @module @pwfabric/runtime/render/data-binding-types
+ */
+import type { SurfaceDataCache } from './data-cache.js';
+import type { Block } from '@pwfabric/core';
+import type { RenderableSurface, SurfaceRendererProps } from './types.js';
+import type { DataServiceConfig } from '../data/types.js';
+/**
+ * Source kinds supported in surface JSON definitions.
+ * Note: 'computed' is excluded because functions can't be serialized in JSON.
+ */
+export type SurfaceDataSourceKind = 'rest' | 'static' | 'state' | 'entity';
+/**
+ * Data source definition within a surface JSON.
+ * Unlike DataSourceDefinition from data/types, this is JSON-serializable.
+ */
+export interface SurfaceDataSourceDefinition {
+    /** Unique source identifier, used as the key in expression context */
+    readonly id: string;
+    /** Source kind */
+    readonly kind: SurfaceDataSourceKind;
+    /** REST endpoint (may contain {{state.key}} placeholders) */
+    readonly endpoint?: string;
+    /** HTTP method for REST sources */
+    readonly method?: 'GET' | 'POST' | 'PUT' | 'DELETE';
+    /** Static inline data */
+    readonly staticData?: unknown;
+    /** Auto-refresh interval in ms (0 or undefined = no auto-refresh) */
+    readonly refreshInterval?: number;
+    /** Optional HTTP headers to include in REST requests (e.g. Authorization) */
+    readonly headers?: Readonly<Record<string, string>>;
+    /** Entity type to list (kind: 'entity') via the platform/entities facade */
+    readonly entityType?: string;
+    /** Optional query for entity sources (filter/sort/pagination). String
+     * leaves may carry `{{state.x}}` expressions — resolved against surface
+     * state before the connector is called (see render/query-state.ts). */
+    readonly query?: Readonly<Record<string, unknown>>;
+    /** Payload bound when the source cannot be served (connector missing /
+     * failed). `__errors.<id>` stays populated alongside it. */
+    readonly fallback?: unknown;
+    /**
+     * Contract parity with `dataSourceSchema.connector`: which
+     * data-plane engine serves this entity source (e.g. 'graph-lists').
+     * Routed through the host-provided `ConnectorEngineRegistry` when the
+     * connection is registered there; absent/unregistered = the default
+     * entity facade path (today's behavior).
+     */
+    readonly connector?: string;
+    /**
+     * The response property holding the list — `data`, `products`, or absent
+     * when the body IS the array. Dotted paths allowed for a nested one.
+     */
+    readonly returns?: string;
+    /** world auth binding BY NAME — never credential values. */
+    readonly authProviderRef?: string;
+    /**
+     * Contract parity with `dataSourceSchema.aggregate`: ask for ONE
+     * NUMBER over the collection instead of its rows. The source binds
+     * `{ fn, field?, value, count }` — `{{<id>.value}}` — and is exempt from
+     * the list wrap. `filter` leaves may carry `{{state.x}}` like `query`.
+     */
+    readonly aggregate?: {
+        readonly fn: 'count' | 'sum' | 'avg';
+        readonly field?: string;
+        readonly filter?: Readonly<Record<string, unknown>>;
+    };
+}
+/**
+ * Action types that blocks can dispatch via their action prop.
+ */
+export type SurfaceActionType = 'setState' | 'refresh' | 'refreshAll' | 'showBlock' | 'hideBlock' | 'navigate';
+/**
+ * Action dispatched by a block (e.g. button click, tab change).
+ */
+export type SurfaceAction = {
+    readonly type: 'setState';
+    readonly key: string;
+    readonly value: unknown;
+} | {
+    readonly type: 'refresh';
+    readonly sourceId: string;
+} | {
+    readonly type: 'refreshAll';
+} | {
+    readonly type: 'showBlock';
+    readonly blockId: string;
+} | {
+    readonly type: 'hideBlock';
+    readonly blockId: string;
+} | {
+    readonly type: 'navigate';
+    readonly url: string;
+};
+/**
+ * What a block's `action` prop may hold: one action, or a list run in order
+ * on the block's click (`block:click`) — never on its other events.
+ */
+export type BlockActionProp = SurfaceAction | readonly SurfaceAction[];
+/**
+ * A behavior stored on a published surface — maps an event trigger to one or more actions.
+ * The `event` field accepts canonical colon form (`block:click`) or legacy dot form
+ * (`surface.load`) — normalized at match time by `canonicalizeEventType`.
+ */
+export interface RuntimeBehavior {
+    readonly id: string;
+    readonly event: string;
+    readonly targetBlockId?: string;
+    readonly actions: readonly SurfaceAction[];
+}
+/**
+ * Surface definition extended with data binding capabilities.
+ * This is the shape of a surface JSON that uses live data.
+ */
+export interface DataBoundSurface {
+    /**
+     * Stable surface id — SurfaceRenderer's render scope.
+     *
+     * Omitted from this type originally, which made the drop invisible: the
+     * renderer decomposes the surface into blocks/appearance/capabilities and
+     * rebuilds it, and a field the type never had could not survive the rebuild.
+     * Downstream, `[data-pw-surface]` rendered with an EMPTY value and every
+     * per-surface rule (dark theme, visibility, interaction states) fell back to
+     * the value-less selector shared by every surface in the document — the exact
+     * collision the scoping was added to prevent.
+     */
+    readonly id?: string;
+    /** Block composition */
+    readonly blocks: readonly Block[];
+    /** ui-appearance atom reference (theme + layout + styleVariables consolidated). */
+    readonly appearance?: RenderableSurface['appearance'];
+    /** capability list — `platform/persistence` carries dataSources + initialState in its config. */
+    readonly capabilities?: RenderableSurface['capabilities'];
+}
+/**
+ * Props for DataBoundSurfaceRenderer.
+ * Extends SurfaceRendererProps but accepts a DataBoundSurface.
+ */
+export interface DataBoundSurfaceRendererProps extends Omit<SurfaceRendererProps, 'surface'> {
+    /** Surface definition with optional dataSources and state */
+    readonly surface: DataBoundSurface;
+    /** Stored behaviors to execute when their trigger event fires on the bus */
+    readonly behaviors?: readonly RuntimeBehavior[];
+    /**
+     * Intercept a `navigate` action before the default `window.location.assign`
+     * fallback runs. Return `true` to signal the host handled it (e.g. swapped
+     * to a sibling page in place, connected-preview style) — the default hard
+     * navigation is skipped. Return `false`/`undefined` to fall through to the
+     * default behavior.
+     */
+    readonly onNavigateAction?: (url: string) => boolean;
+    /**
+     * What to render while the initial `fetchAllSources` pass is in flight.
+     *
+     * - `'gate'` (default) — the historical behavior: an all-or-nothing
+     *   "Loading data..." placeholder replaces the ENTIRE block tree until the
+     *   first fetch settles. Kept as the default so existing consumers (e.g.
+     *   published `/s/` pages) are byte-identical.
+     * - `'immediate'` — render the block tree right away; expressions bound to
+     *   still-loading sources resolve to `undefined` (never a literal `{{…}}`
+     *   string — path expressions always evaluate successfully) and fill in as
+     *   each source lands. Static chrome (navbar, headings, footer) is visible
+     *   from the first frame. Pair with the `__loading.<sourceId>` /
+     *   `__anyLoading` expression keys to drive per-widget skeletons.
+     */
+    readonly loadingStrategy?: 'gate' | 'immediate';
+    /**
+     * Yesterday's rows while today's load. A source whose key (see
+     * `dataSourceCacheKey`) is present is seeded from the cache on the first
+     * frame and still re-fetched; the fresh result replaces the seed and is
+     * written back. Pairs naturally with `loadingStrategy: 'immediate'`.
+     */
+    readonly dataCache?: SurfaceDataCache;
+    /**
+     * Configuration for the DataService this renderer creates.
+     *
+     * IT WAS NEVER PASSED. `<DataCapabilityProvider>` was mounted bare, so the
+     * service was built with no config — which means `getAccessToken` was always
+     * undefined and every `authProviderRef` on every rest source resolved to
+     * nobody. The field parsed, travelled and was read by a resolver that could
+     * not exist. Threading it is the repair; it is also what lets a host say
+     * which origin is its own, so our API can be called with a cookie and
+     * nobody else's can.
+     */
+    readonly dataServiceConfig?: DataServiceConfig;
+}

package/dist/render/data-binding-types.js

@@ -0,0 +1,11 @@
+/**
+ * Data Binding Types for Surface Renderer
+ *
+ * Type definitions for data-bound surface rendering.
+ * These types define the shape of surface JSON definitions that include
+ * dataSources, state, and expression-based prop bindings.
+ *
+ * @module @pwfabric/runtime/render/data-binding-types
+ */
+export {};
+//# sourceMappingURL=data-binding-types.js.map