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

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

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

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"connections-context.d.ts","sourceRoot":"","sources":["../../src/render/connections-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAGH,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,wBAAwB,CAAA;AAErE;;;GAGG;AACH,eAAO,MAAM,yBAAyB,yDAAsD,CAAA;AAE5F;;;GAGG;AACH,wBAAgB,qBAAqB,IAAI,uBAAuB,GAAG,IAAI,CAEtE"}

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

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

@@ -0,0 +1,37 @@
+/**
+ * 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;
+//# sourceMappingURL=dark-theme-css.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"dark-theme-css.d.ts","sourceRoot":"","sources":["../../src/render/dark-theme-css.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAA;AAiB/D;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAChC,SAAS,CAAC,EAAE,MAAM,EAClB,MAAM,GAAE,oBAA+B,GACtC,MAAM,CAcR"}

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

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

@@ -0,0 +1,192 @@
+/**
+ * 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;
+}
+//# sourceMappingURL=data-binding-types.d.ts.map

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

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

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

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

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

package/dist/render/data-cache.d.ts

@@ -0,0 +1,31 @@
+/**
+ * A host-provided cache for fetched source data — stale-while-revalidate.
+ *
+ * A page the visitor has already seen should not come back empty while its
+ * sources are re-fetched. The renderer knows nothing about where the cache
+ * lives (the published-app runner keeps it in sessionStorage, a host may keep
+ * it in memory); it only asks for a value by key on the first frame and
+ * writes the fresh result back after a successful fetch. A failed fetch never
+ * writes, so a good entry is not replaced by nothing.
+ *
+ * @module @pwfabric/runtime/render/data-cache
+ */
+import type { SurfaceDataSourceDefinition } from './data-binding-types.js';
+export interface SurfaceDataCache {
+    /** The last successful result for this key, or undefined. */
+    get(key: string): unknown;
+    /** Remember a successful result. Must not throw on a full store. */
+    set(key: string, value: unknown): void;
+}
+/**
+ * The key a source's fetched data is remembered under.
+ *
+ * Built from everything that decides WHAT is fetched — kind, id, resolved address,
+ * entity type, connector, and the query with its `{{state.*}}` placeholders
+ * resolved against the current state — so page 2 never answers as page 1.
+ * The `fallback` payload is left out: sample rows are not part of what was
+ * fetched. `state` and `static` sources are never fetched, so they have no
+ * key.
+ */
+export declare function dataSourceCacheKey(source: SurfaceDataSourceDefinition, state: Readonly<Record<string, unknown>>): string | undefined;
+//# sourceMappingURL=data-cache.d.ts.map

package/dist/render/data-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"data-cache.d.ts","sourceRoot":"","sources":["../../src/render/data-cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,yBAAyB,CAAA;AAI1E,MAAM,WAAW,gBAAgB;IAC/B,6DAA6D;IAC7D,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;IACzB,oEAAoE;IACpE,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAAA;CACvC;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,2BAA2B,EACnC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GACvC,MAAM,GAAG,SAAS,CAsBpB"}

package/dist/render/data-cache.js

@@ -0,0 +1,37 @@
+import { resolveQueryState } from './query-state.js';
+import { endpointMissingPathValue, resolveEndpoint } from './endpoint.js';
+/**
+ * The key a source's fetched data is remembered under.
+ *
+ * Built from everything that decides WHAT is fetched — kind, id, resolved address,
+ * entity type, connector, and the query with its `{{state.*}}` placeholders
+ * resolved against the current state — so page 2 never answers as page 1.
+ * The `fallback` payload is left out: sample rows are not part of what was
+ * fetched. `state` and `static` sources are never fetched, so they have no
+ * key.
+ */
+export function dataSourceCacheKey(source, state) {
+    if (source.kind === 'state' || source.kind === 'static')
+        return undefined;
+    // An idle source (a required path value is empty) is not fetched either.
+    if (source.kind === 'rest' && source.endpoint !== undefined && endpointMissingPathValue(source.endpoint, state)) {
+        return undefined;
+    }
+    const query = source.query ? resolveQueryState(source.query, state) : null;
+    const aggregate = source.aggregate ? resolveQueryState(source.aggregate, state) : null;
+    return JSON.stringify([
+        source.kind,
+        source.id,
+        // The RESOLVED address, not the template: with the template every
+        // `/products/{{state.id}}` shared one key, and `?id=13` opened on the
+        // rows cached for 12 until the fetch landed.
+        source.endpoint !== undefined ? resolveEndpoint(source.endpoint, state) : null,
+        source.method ?? null,
+        source.entityType ?? null,
+        source.connector ?? null,
+        source.returns ?? null,
+        query,
+        aggregate,
+    ]);
+}
+//# sourceMappingURL=data-cache.js.map

package/dist/render/data-cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"data-cache.js","sourceRoot":"","sources":["../../src/render/data-cache.ts"],"names":[],"mappings":"AAaA,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAA;AACpD,OAAO,EAAE,wBAAwB,EAAE,eAAe,EAAE,MAAM,eAAe,CAAA;AASzE;;;;;;;;;GASG;AACH,MAAM,UAAU,kBAAkB,CAChC,MAAmC,EACnC,KAAwC;IAExC,IAAI,MAAM,CAAC,IAAI,KAAK,OAAO,IAAI,MAAM,CAAC,IAAI,KAAK,QAAQ;QAAE,OAAO,SAAS,CAAA;IACzE,yEAAyE;IACzE,IAAI,MAAM,CAAC,IAAI,KAAK,MAAM,IAAI,MAAM,CAAC,QAAQ,KAAK,SAAS,IAAI,wBAAwB,CAAC,MAAM,CAAC,QAAQ,EAAE,KAAK,CAAC,EAAE,CAAC;QAChH,OAAO,SAAS,CAAA;IAClB,CAAC;IACD,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,iBAAiB,CAAC,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAA;IAC1E,MAAM,SAAS,GAAG,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,iBAAiB,CAAC,MAAM,CAAC,SAAS,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAA;IACtF,OAAO,IAAI,CAAC,SAAS,CAAC;QACpB,MAAM,CAAC,IAAI;QACX,MAAM,CAAC,EAAE;QACT,kEAAkE;QAClE,sEAAsE;QACtE,6CAA6C;QAC7C,MAAM,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,eAAe,CAAC,MAAM,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI;QAC9E,MAAM,CAAC,MAAM,IAAI,IAAI;QACrB,MAAM,CAAC,UAAU,IAAI,IAAI;QACzB,MAAM,CAAC,SAAS,IAAI,IAAI;QACxB,MAAM,CAAC,OAAO,IAAI,IAAI;QACtB,KAAK;QACL,SAAS;KACV,CAAC,CAAA;AACJ,CAAC"}

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

@@ -0,0 +1,18 @@
+/**
+ * Derive a dark theme variant from a light SurfaceTheme.
+ *
+ * A colour palette is a preset the end user edits — not a reason to ship a
+ * separate appearance atom. The dark variant is DERIVED from the light palette
+ * rather than authored twice.
+ *
+ * The implementation lives in `@pwfabric/contracts`
+ * (`fabric/appearance-cascade`), because the derivation can run at WRITE
+ * time: an authoring tool may bake the result into
+ * `appearance.config.darkTheme` so the author can see and edit the dark palette
+ * instead of it being invisible render-time magic. Render still derives as the
+ * fallback for surfaces that carry no baked variant.
+ *
+ * @module @pwfabric/runtime/render/derive-dark-theme
+ */
+export { deriveDarkTheme } from '@pwfabric/contracts';
+//# sourceMappingURL=derive-dark-theme.d.ts.map

package/dist/render/derive-dark-theme.d.ts.map

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

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

@@ -0,0 +1,18 @@
+/**
+ * Derive a dark theme variant from a light SurfaceTheme.
+ *
+ * A colour palette is a preset the end user edits — not a reason to ship a
+ * separate appearance atom. The dark variant is DERIVED from the light palette
+ * rather than authored twice.
+ *
+ * The implementation lives in `@pwfabric/contracts`
+ * (`fabric/appearance-cascade`), because the derivation can run at WRITE
+ * time: an authoring tool may bake the result into
+ * `appearance.config.darkTheme` so the author can see and edit the dark palette
+ * instead of it being invisible render-time magic. Render still derives as the
+ * fallback for surfaces that carry no baked variant.
+ *
+ * @module @pwfabric/runtime/render/derive-dark-theme
+ */
+export { deriveDarkTheme } from '@pwfabric/contracts';
+//# sourceMappingURL=derive-dark-theme.js.map

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

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