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

package/dist/render/endpoint.d.ts

@@ -0,0 +1,18 @@
+/** The form a single state value takes inside a mixed endpoint. */
+export declare function encodeEndpointValue(value: unknown): string;
+export declare function resolveEndpoint(endpoint: string, state: Readonly<Record<string, unknown>>): string;
+/**
+ * Would this endpoint be requested with a required value MISSING?
+ *
+ * A detail source is authored as `/carts/{{state.numara}}`. Until the visitor
+ * types a number, `numara` is empty and the request would go to `/carts/` —
+ * the whole collection (DummyJSON redirects there), which then fails `returns`
+ * and opens the page on an error. A placeholder in the PATH is
+ * required: when it resolves to nothing (`''`, `null`, `undefined`) or cannot
+ * be evaluated, the source is not fetched at all and stays idle.
+ *
+ * A placeholder in the QUERY STRING (`?q={{state.q}}`) is not required — an
+ * empty search box legitimately means "no constraint". An endpoint that is
+ * ONE expression (`{{state.url}}`) is required as a whole.
+ */
+export declare function endpointMissingPathValue(endpoint: string, state: Readonly<Record<string, unknown>>): boolean;

package/dist/render/endpoint.js

@@ -0,0 +1,109 @@
+/**
+ * resolveEndpoint — place surface state into a REST source's `endpoint`.
+ *
+ * EVERY VALUE IS URL-ENCODED WHEN THE ENDPOINT MIXES TEXT AND EXPRESSIONS.
+ *
+ * A raw interpolation would be harmless if state could only come from the
+ * page's own controls, but a published app can seed state from its address
+ * (`/product?id=12`): `?id=12/../../admin` or `?id=1%26role=owner` would
+ * rewrite the path or the query of a request the visitor's credential rides on. A space or a `ü`
+ * was always encoded by `fetch`; what this adds is `& # + % ? /`.
+ *
+ * Three rules:
+ *
+ *   - mixed endpoint (`/products/{{state.id}}`, `?q={{state.q}}`): each value
+ *     goes through `encodeURIComponent` — ALL values, not only the ones that
+ *     came from the address, because the renderer cannot tell them apart;
+ *   - a value that is exactly `.` or `..` becomes `''` — `encodeURIComponent`
+ *     leaves both alone, and a lone `..` segment still climbs a directory;
+ *   - an endpoint that is ONE expression (`"{{state.url}}"`) is left as it
+ *     resolves, unencoded — today's behaviour. The published-app runner never
+ *     seeds a key read there (nor one read in the scheme/host part), so the
+ *     address cannot reach it.
+ *
+ * A failed expression leaves the endpoint as authored, as it always did.
+ *
+ * @module @pwfabric/runtime/render/endpoint
+ */
+import { createExpressionContext, evaluate, interpolate } from '../surface/expression.js';
+/** `"{{ expr }}"` and nothing else (surrounding whitespace allowed). */
+const WHOLE = /^\s*\{\{\s*([^{}]+?)\s*\}\}\s*$/;
+/** One `{{ … }}` placeholder — the same shape `interpolate` walks. */
+const PLACEHOLDER = /\{\{(.+?)\}\}/g;
+/** The form a single state value takes inside a mixed endpoint. */
+export function encodeEndpointValue(value) {
+    const s = String(value ?? '');
+    if (s === '.' || s === '..')
+        return '';
+    return encodeURIComponent(s);
+}
+export function resolveEndpoint(endpoint, state) {
+    if (!endpoint.includes('{{'))
+        return endpoint;
+    const ctx = createExpressionContext({ state: state });
+    // One expression: resolved as before, no encoding (see module note).
+    if (WHOLE.test(endpoint)) {
+        const r = interpolate(endpoint, ctx);
+        return r.success ? r.value : endpoint;
+    }
+    let failed = false;
+    const out = endpoint.replace(PLACEHOLDER, (_match, expression) => {
+        if (failed)
+            return '';
+        const r = evaluate(expression.trim(), ctx);
+        if (!r.success) {
+            failed = true;
+            return '';
+        }
+        return encodeEndpointValue(r.value);
+    });
+    return failed ? endpoint : out;
+}
+/**
+ * Would this endpoint be requested with a required value MISSING?
+ *
+ * A detail source is authored as `/carts/{{state.numara}}`. Until the visitor
+ * types a number, `numara` is empty and the request would go to `/carts/` —
+ * the whole collection (DummyJSON redirects there), which then fails `returns`
+ * and opens the page on an error. A placeholder in the PATH is
+ * required: when it resolves to nothing (`''`, `null`, `undefined`) or cannot
+ * be evaluated, the source is not fetched at all and stays idle.
+ *
+ * A placeholder in the QUERY STRING (`?q={{state.q}}`) is not required — an
+ * empty search box legitimately means "no constraint". An endpoint that is
+ * ONE expression (`{{state.url}}`) is required as a whole.
+ */
+export function endpointMissingPathValue(endpoint, state) {
+    if (!endpoint.includes('{{'))
+        return false;
+    const ctx = createExpressionContext({ state: state });
+    const empty = (expression) => {
+        const r = evaluate(expression.trim(), ctx);
+        return !r.success || r.value === undefined || r.value === null || String(r.value).trim() === '';
+    };
+    const whole = WHOLE.exec(endpoint);
+    if (whole)
+        return empty(whole[1] ?? '');
+    // The path part ends at the first `?` or `#` that is not inside a placeholder.
+    let pathEnd = endpoint.length;
+    for (let i = 0, depth = 0; i < endpoint.length; i++) {
+        if (endpoint.startsWith('{{', i)) {
+            depth++;
+            i++;
+        }
+        else if (endpoint.startsWith('}}', i) && depth > 0) {
+            depth--;
+            i++;
+        }
+        else if (depth === 0 && (endpoint[i] === '?' || endpoint[i] === '#')) {
+            pathEnd = i;
+            break;
+        }
+    }
+    for (const m of endpoint.slice(0, pathEnd).matchAll(PLACEHOLDER)) {
+        if (empty(m[1] ?? ''))
+            return true;
+    }
+    return false;
+}
+//# sourceMappingURL=endpoint.js.map

package/dist/render/endpoint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"endpoint.js","sourceRoot":"","sources":["../../src/render/endpoint.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * resolveEndpoint — place surface state into a REST source's `endpoint`.\n *\n * EVERY VALUE IS URL-ENCODED WHEN THE ENDPOINT MIXES TEXT AND EXPRESSIONS.\n *\n * A raw interpolation would be harmless if state could only come from the\n * page's own controls, but a published app can seed state from its address\n * (`/product?id=12`): `?id=12/../../admin` or `?id=1%26role=owner` would\n * rewrite the path or the query of a request the visitor's credential rides on. A space or a `ü`\n * was always encoded by `fetch`; what this adds is `& # + % ? /`.\n *\n * Three rules:\n *\n *   - mixed endpoint (`/products/{{state.id}}`, `?q={{state.q}}`): each value\n *     goes through `encodeURIComponent` — ALL values, not only the ones that\n *     came from the address, because the renderer cannot tell them apart;\n *   - a value that is exactly `.` or `..` becomes `''` — `encodeURIComponent`\n *     leaves both alone, and a lone `..` segment still climbs a directory;\n *   - an endpoint that is ONE expression (`\"{{state.url}}\"`) is left as it\n *     resolves, unencoded — today's behaviour. The published-app runner never\n *     seeds a key read there (nor one read in the scheme/host part), so the\n *     address cannot reach it.\n *\n * A failed expression leaves the endpoint as authored, as it always did.\n *\n * @module @pwfabric/runtime/render/endpoint\n */\nimport { createExpressionContext, evaluate, interpolate } from '../surface/expression.js'\n\n/** `\"{{ expr }}\"` and nothing else (surrounding whitespace allowed). */\nconst WHOLE = /^\\s*\\{\\{\\s*([^{}]+?)\\s*\\}\\}\\s*$/\n\n/** One `{{ … }}` placeholder — the same shape `interpolate` walks. */\nconst PLACEHOLDER = /\\{\\{(.+?)\\}\\}/g\n\n/** The form a single state value takes inside a mixed endpoint. */\nexport function encodeEndpointValue(value: unknown): string {\n  const s = String(value ?? '')\n  if (s === '.' || s === '..') return ''\n  return encodeURIComponent(s)\n}\n\nexport function resolveEndpoint(endpoint: string, state: Readonly<Record<string, unknown>>): string {\n  if (!endpoint.includes('{{')) return endpoint\n  const ctx = createExpressionContext({ state: state as Record<string, unknown> })\n\n  // One expression: resolved as before, no encoding (see module note).\n  if (WHOLE.test(endpoint)) {\n    const r = interpolate(endpoint, ctx)\n    return r.success ? r.value : endpoint\n  }\n\n  let failed = false\n  const out = endpoint.replace(PLACEHOLDER, (_match, expression: string) => {\n    if (failed) return ''\n    const r = evaluate(expression.trim(), ctx)\n    if (!r.success) {\n      failed = true\n      return ''\n    }\n    return encodeEndpointValue(r.value)\n  })\n  return failed ? endpoint : out\n}\n\n/**\n * Would this endpoint be requested with a required value MISSING?\n *\n * A detail source is authored as `/carts/{{state.numara}}`. Until the visitor\n * types a number, `numara` is empty and the request would go to `/carts/` —\n * the whole collection (DummyJSON redirects there), which then fails `returns`\n * and opens the page on an error. A placeholder in the PATH is\n * required: when it resolves to nothing (`''`, `null`, `undefined`) or cannot\n * be evaluated, the source is not fetched at all and stays idle.\n *\n * A placeholder in the QUERY STRING (`?q={{state.q}}`) is not required — an\n * empty search box legitimately means \"no constraint\". An endpoint that is\n * ONE expression (`{{state.url}}`) is required as a whole.\n */\nexport function endpointMissingPathValue(\n  endpoint: string,\n  state: Readonly<Record<string, unknown>>\n): boolean {\n  if (!endpoint.includes('{{')) return false\n  const ctx = createExpressionContext({ state: state as Record<string, unknown> })\n  const empty = (expression: string): boolean => {\n    const r = evaluate(expression.trim(), ctx)\n    return !r.success || r.value === undefined || r.value === null || String(r.value).trim() === ''\n  }\n  const whole = WHOLE.exec(endpoint)\n  if (whole) return empty(whole[1] ?? '')\n\n  // The path part ends at the first `?` or `#` that is not inside a placeholder.\n  let pathEnd = endpoint.length\n  for (let i = 0, depth = 0; i < endpoint.length; i++) {\n    if (endpoint.startsWith('{{', i)) {\n      depth++\n      i++\n    } else if (endpoint.startsWith('}}', i) && depth > 0) {\n      depth--\n      i++\n    } else if (depth === 0 && (endpoint[i] === '?' || endpoint[i] === '#')) {\n      pathEnd = i\n      break\n    }\n  }\n  for (const m of endpoint.slice(0, pathEnd).matchAll(PLACEHOLDER)) {\n    if (empty(m[1] ?? '')) return true\n  }\n  return false\n}\n"]}

package/dist/render/entity-facade-context.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Entity Facade React Context
+ *
+ * Provides EntityFacade to the surface render tree via React
+ * context. Pattern mirrors SurfaceRoutingContext / useSurfaceRouting().
+ *
+ * Injection point: EntityFacadeContext.Provider wraps BehaviorSurfaceProvider
+ * inside SurfaceRenderer when entityFacade prop is supplied.
+ *
+ * @module @pwfabric/runtime/render/entity-facade-context
+ */
+import type { EntityFacade } from '../entity/facade.js';
+/**
+ * React context that carries an EntityFacade instance through the render tree.
+ * Defaults to null — blocks that require entity access check for null and
+ * gracefully handle the absent-facade case.
+ */
+export declare const EntityFacadeContext: import("react").Context<EntityFacade | null>;
+/**
+ * Returns the EntityFacade from the nearest EntityFacadeContext.Provider.
+ * Returns null when no provider is present (entity support not configured).
+ *
+ * @example
+ * ```tsx
+ * import { useEntityFacade } from '@pwfabric/runtime/render'
+ *
+ * function MyBlock() {
+ *   const facade = useEntityFacade()
+ *   if (!facade) return null  // No entity support configured
+ *   const result = await facade.store.query('Employee', {})
+ * }
+ * ```
+ */
+export declare function useEntityFacade(): EntityFacade | null;

package/dist/render/entity-facade-context.js

@@ -0,0 +1,37 @@
+/**
+ * Entity Facade React Context
+ *
+ * Provides EntityFacade to the surface render tree via React
+ * context. Pattern mirrors SurfaceRoutingContext / useSurfaceRouting().
+ *
+ * Injection point: EntityFacadeContext.Provider wraps BehaviorSurfaceProvider
+ * inside SurfaceRenderer when entityFacade prop is supplied.
+ *
+ * @module @pwfabric/runtime/render/entity-facade-context
+ */
+import { createContext, useContext } from 'react';
+/**
+ * React context that carries an EntityFacade instance through the render tree.
+ * Defaults to null — blocks that require entity access check for null and
+ * gracefully handle the absent-facade case.
+ */
+export const EntityFacadeContext = createContext(null);
+/**
+ * Returns the EntityFacade from the nearest EntityFacadeContext.Provider.
+ * Returns null when no provider is present (entity support not configured).
+ *
+ * @example
+ * ```tsx
+ * import { useEntityFacade } from '@pwfabric/runtime/render'
+ *
+ * function MyBlock() {
+ *   const facade = useEntityFacade()
+ *   if (!facade) return null  // No entity support configured
+ *   const result = await facade.store.query('Employee', {})
+ * }
+ * ```
+ */
+export function useEntityFacade() {
+    return useContext(EntityFacadeContext);
+}
+//# sourceMappingURL=entity-facade-context.js.map

package/dist/render/entity-facade-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity-facade-context.js","sourceRoot":"","sources":["../../src/render/entity-facade-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,OAAO,CAAA;AAGjD;;;;GAIG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,aAAa,CAAsB,IAAI,CAAC,CAAA;AAE3E;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,eAAe;IAC7B,OAAO,UAAU,CAAC,mBAAmB,CAAC,CAAA;AACxC,CAAC","sourcesContent":["/**\n * Entity Facade React Context\n *\n * Provides EntityFacade to the surface render tree via React\n * context. Pattern mirrors SurfaceRoutingContext / useSurfaceRouting().\n *\n * Injection point: EntityFacadeContext.Provider wraps BehaviorSurfaceProvider\n * inside SurfaceRenderer when entityFacade prop is supplied.\n *\n * @module @pwfabric/runtime/render/entity-facade-context\n */\n\nimport { createContext, useContext } from 'react'\nimport type { EntityFacade } from '../entity/facade.js'\n\n/**\n * React context that carries an EntityFacade instance through the render tree.\n * Defaults to null — blocks that require entity access check for null and\n * gracefully handle the absent-facade case.\n */\nexport const EntityFacadeContext = createContext<EntityFacade | null>(null)\n\n/**\n * Returns the EntityFacade from the nearest EntityFacadeContext.Provider.\n * Returns null when no provider is present (entity support not configured).\n *\n * @example\n * ```tsx\n * import { useEntityFacade } from '@pwfabric/runtime/render'\n *\n * function MyBlock() {\n *   const facade = useEntityFacade()\n *   if (!facade) return null  // No entity support configured\n *   const result = await facade.store.query('Employee', {})\n * }\n * ```\n */\nexport function useEntityFacade(): EntityFacade | null {\n  return useContext(EntityFacadeContext)\n}\n"]}

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

@@ -0,0 +1,41 @@
+/**
+ * Group-hover scoped CSS generation (Tailwind `group` + `group-hover:`).
+ *
+ * A parent container marked `groupRoot: true` is a hover SOURCE: hovering it
+ * restyles descendants that declare `groupStates.hover`. `block.style` is inline
+ * and can express neither the ancestor `:hover` nor the descendant relationship,
+ * so the runtime emits a scoped descendant rule keyed by BOTH block ids:
+ *
+ *   `[data-pw-surface] [data-block-id="<rootId>"]:hover [data-block-id="<thisId>"]{ … }`
+ *
+ * The host element already rendered for every block (`data-block-id`) is
+ * sufficient on both ends — no extra attribute is needed. Keys are CSS camelCase
+ * property names (converted to kebab-case); declarations are emitted with
+ * `!important` because a block COMPONENT often applies the same property inline
+ * with its own default and inline beats any plain stylesheet rule. Scoped to the
+ * one descendant under the one root.
+ *
+ * Only the NEAREST ancestor with `groupRoot:true` drives a block's
+ * `groupStates`; a block with `groupStates.hover` but no `groupRoot` ancestor
+ * emits zero bytes. Surfaces using no `groupStates` emit zero bytes so existing
+ * surfaces are byte-identical.
+ *
+ * @module @pwfabric/runtime/render/group-states-css
+ */
+import type { Block } from '@pwfabric/core';
+/**
+ * Emit the scoped group-hover rule for a single descendant block, given the id
+ * of the nearest `groupRoot` ancestor. Targets
+ * `[data-block-id="<rootId>"]:hover [data-block-id="<thisId>"]` scoped under the
+ * surface root. Returns '' when the descendant declares no non-empty
+ * `groupStates.hover` record.
+ */
+export declare function blockGroupStatesCss(rootId: string, thisId: string, groupStates: NonNullable<Block['groupStates']>, surfaceId?: string): string;
+/**
+ * Walk a surface block tree tracking the nearest ancestor marked
+ * `groupRoot: true`; for each block declaring `groupStates.hover` UNDER such an
+ * ancestor, concatenate its scoped group-hover CSS. Blocks with `groupStates`
+ * but no `groupRoot` ancestor — and surfaces with no `groupStates` at all —
+ * emit zero bytes (existing surfaces byte-identical).
+ */
+export declare function collectGroupStatesCss(blocks: readonly Block[], surfaceId?: string): string;

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

@@ -0,0 +1,73 @@
+/**
+ * Group-hover scoped CSS generation (Tailwind `group` + `group-hover:`).
+ *
+ * A parent container marked `groupRoot: true` is a hover SOURCE: hovering it
+ * restyles descendants that declare `groupStates.hover`. `block.style` is inline
+ * and can express neither the ancestor `:hover` nor the descendant relationship,
+ * so the runtime emits a scoped descendant rule keyed by BOTH block ids:
+ *
+ *   `[data-pw-surface] [data-block-id="<rootId>"]:hover [data-block-id="<thisId>"]{ … }`
+ *
+ * The host element already rendered for every block (`data-block-id`) is
+ * sufficient on both ends — no extra attribute is needed. Keys are CSS camelCase
+ * property names (converted to kebab-case); declarations are emitted with
+ * `!important` because a block COMPONENT often applies the same property inline
+ * with its own default and inline beats any plain stylesheet rule. Scoped to the
+ * one descendant under the one root.
+ *
+ * Only the NEAREST ancestor with `groupRoot:true` drives a block's
+ * `groupStates`; a block with `groupStates.hover` but no `groupRoot` ancestor
+ * emits zero bytes. Surfaces using no `groupStates` emit zero bytes so existing
+ * surfaces are byte-identical.
+ *
+ * @module @pwfabric/runtime/render/group-states-css
+ */
+import { blockIdAttr, blockSelector, camelToKebab } 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(';');
+}
+/**
+ * Emit the scoped group-hover rule for a single descendant block, given the id
+ * of the nearest `groupRoot` ancestor. Targets
+ * `[data-block-id="<rootId>"]:hover [data-block-id="<thisId>"]` scoped under the
+ * surface root. Returns '' when the descendant declares no non-empty
+ * `groupStates.hover` record.
+ */
+export function blockGroupStatesCss(rootId, thisId, groupStates, surfaceId) {
+    const decls = groupStates.hover;
+    if (!decls || Object.keys(decls).length === 0)
+        return '';
+    // `blockSelector(rootId)` already includes the `[data-pw-surface]` prefix; the
+    // descendant half is just the bare `[data-block-id]` attribute selector (the
+    // shared surface scope is carried by the root half).
+    return `${blockSelector(rootId, surfaceId)}:hover ${blockIdAttr(thisId)}{${declsToCss(decls)}}`;
+}
+/**
+ * Walk a surface block tree tracking the nearest ancestor marked
+ * `groupRoot: true`; for each block declaring `groupStates.hover` UNDER such an
+ * ancestor, concatenate its scoped group-hover CSS. Blocks with `groupStates`
+ * but no `groupRoot` ancestor — and surfaces with no `groupStates` at all —
+ * emit zero bytes (existing surfaces byte-identical).
+ */
+export function collectGroupStatesCss(blocks, surfaceId) {
+    let css = '';
+    const walk = (block, nearestRootId) => {
+        if (block.groupStates && nearestRootId !== undefined) {
+            css += blockGroupStatesCss(nearestRootId, block.id, block.groupStates, surfaceId);
+        }
+        // This block becomes the nearest root for its own descendants when it is a
+        // group root (innermost groupRoot wins).
+        const rootForChildren = block.groupRoot ? block.id : nearestRootId;
+        if (block.children) {
+            for (const child of block.children)
+                walk(child, rootForChildren);
+        }
+    };
+    for (const block of blocks)
+        walk(block, undefined);
+    return css;
+}
+//# sourceMappingURL=group-states-css.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"group-states-css.js","sourceRoot":"","sources":["../../src/render/group-states-css.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAGH,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAA;AAE1E,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;;;;;;GAMG;AACH,MAAM,UAAU,mBAAmB,CACjC,MAAc,EACd,MAAc,EACd,WAA8C,EAC9C,SAAkB;IAElB,MAAM,KAAK,GAAG,WAAW,CAAC,KAAK,CAAA;IAC/B,IAAI,CAAC,KAAK,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAA;IACxD,+EAA+E;IAC/E,6EAA6E;IAC7E,qDAAqD;IACrD,OAAO,GAAG,aAAa,CAAC,MAAM,EAAE,SAAS,CAAC,UAAU,WAAW,CAAC,MAAM,CAAC,IAAI,UAAU,CAAC,KAAK,CAAC,GAAG,CAAA;AACjG,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,qBAAqB,CAAC,MAAwB,EAAE,SAAkB;IAChF,IAAI,GAAG,GAAG,EAAE,CAAA;IACZ,MAAM,IAAI,GAAG,CAAC,KAAY,EAAE,aAAiC,EAAQ,EAAE;QACrE,IAAI,KAAK,CAAC,WAAW,IAAI,aAAa,KAAK,SAAS,EAAE,CAAC;YACrD,GAAG,IAAI,mBAAmB,CAAC,aAAa,EAAE,KAAK,CAAC,EAAE,EAAE,KAAK,CAAC,WAAW,EAAE,SAAS,CAAC,CAAA;QACnF,CAAC;QACD,2EAA2E;QAC3E,yCAAyC;QACzC,MAAM,eAAe,GAAG,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC,aAAa,CAAA;QAClE,IAAI,KAAK,CAAC,QAAQ,EAAE,CAAC;YACnB,KAAK,MAAM,KAAK,IAAI,KAAK,CAAC,QAAQ;gBAAE,IAAI,CAAC,KAAK,EAAE,eAAe,CAAC,CAAA;QAClE,CAAC;IACH,CAAC,CAAA;IACD,KAAK,MAAM,KAAK,IAAI,MAAM;QAAE,IAAI,CAAC,KAAK,EAAE,SAAS,CAAC,CAAA;IAClD,OAAO,GAAG,CAAA;AACZ,CAAC","sourcesContent":["/**\n * Group-hover scoped CSS generation (Tailwind `group` + `group-hover:`).\n *\n * A parent container marked `groupRoot: true` is a hover SOURCE: hovering it\n * restyles descendants that declare `groupStates.hover`. `block.style` is inline\n * and can express neither the ancestor `:hover` nor the descendant relationship,\n * so the runtime emits a scoped descendant rule keyed by BOTH block ids:\n *\n *   `[data-pw-surface] [data-block-id=\"<rootId>\"]:hover [data-block-id=\"<thisId>\"]{ … }`\n *\n * The host element already rendered for every block (`data-block-id`) is\n * sufficient on both ends — no extra attribute is needed. Keys are CSS camelCase\n * property names (converted to kebab-case); declarations are emitted with\n * `!important` because a block COMPONENT often applies the same property inline\n * with its own default and inline beats any plain stylesheet rule. Scoped to the\n * one descendant under the one root.\n *\n * Only the NEAREST ancestor with `groupRoot:true` drives a block's\n * `groupStates`; a block with `groupStates.hover` but no `groupRoot` ancestor\n * emits zero bytes. Surfaces using no `groupStates` emit zero bytes so existing\n * surfaces are byte-identical.\n *\n * @module @pwfabric/runtime/render/group-states-css\n */\n\nimport type { Block } from '@pwfabric/core'\nimport { blockIdAttr, blockSelector, camelToKebab } 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 * Emit the scoped group-hover rule for a single descendant block, given the id\n * of the nearest `groupRoot` ancestor. Targets\n * `[data-block-id=\"<rootId>\"]:hover [data-block-id=\"<thisId>\"]` scoped under the\n * surface root. Returns '' when the descendant declares no non-empty\n * `groupStates.hover` record.\n */\nexport function blockGroupStatesCss(\n  rootId: string,\n  thisId: string,\n  groupStates: NonNullable<Block['groupStates']>,\n  surfaceId?: string\n): string {\n  const decls = groupStates.hover\n  if (!decls || Object.keys(decls).length === 0) return ''\n  // `blockSelector(rootId)` already includes the `[data-pw-surface]` prefix; the\n  // descendant half is just the bare `[data-block-id]` attribute selector (the\n  // shared surface scope is carried by the root half).\n  return `${blockSelector(rootId, surfaceId)}:hover ${blockIdAttr(thisId)}{${declsToCss(decls)}}`\n}\n\n/**\n * Walk a surface block tree tracking the nearest ancestor marked\n * `groupRoot: true`; for each block declaring `groupStates.hover` UNDER such an\n * ancestor, concatenate its scoped group-hover CSS. Blocks with `groupStates`\n * but no `groupRoot` ancestor — and surfaces with no `groupStates` at all —\n * emit zero bytes (existing surfaces byte-identical).\n */\nexport function collectGroupStatesCss(blocks: readonly Block[], surfaceId?: string): string {\n  let css = ''\n  const walk = (block: Block, nearestRootId: string | undefined): void => {\n    if (block.groupStates && nearestRootId !== undefined) {\n      css += blockGroupStatesCss(nearestRootId, block.id, block.groupStates, surfaceId)\n    }\n    // This block becomes the nearest root for its own descendants when it is a\n    // group root (innermost groupRoot wins).\n    const rootForChildren = block.groupRoot ? block.id : nearestRootId\n    if (block.children) {\n      for (const child of block.children) walk(child, rootForChildren)\n    }\n  }\n  for (const block of blocks) walk(block, undefined)\n  return css\n}\n"]}

package/dist/render/hooks/useSurfaceEvents.d.ts

@@ -0,0 +1,8 @@
+/**
+ * useSurfaceEvents hook
+ *
+ * Re-exports from `@pwfabric/runtime/blocks` (its canonical home).
+ *
+ * @module @pwfabric/runtime/render/hooks/useSurfaceEvents
+ */
+export { useSurfaceEvents } from '../../blocks/index.js';

package/dist/render/hooks/useSurfaceEvents.js

@@ -0,0 +1,9 @@
+/**
+ * useSurfaceEvents hook
+ *
+ * Re-exports from `@pwfabric/runtime/blocks` (its canonical home).
+ *
+ * @module @pwfabric/runtime/render/hooks/useSurfaceEvents
+ */
+export { useSurfaceEvents } from '../../blocks/index.js';
+//# sourceMappingURL=useSurfaceEvents.js.map

package/dist/render/hooks/useSurfaceEvents.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useSurfaceEvents.js","sourceRoot":"","sources":["../../../src/render/hooks/useSurfaceEvents.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAA","sourcesContent":["/**\n * useSurfaceEvents hook\n *\n * Re-exports from `@pwfabric/runtime/blocks` (its canonical home).\n *\n * @module @pwfabric/runtime/render/hooks/useSurfaceEvents\n */\n\nexport { useSurfaceEvents } from '../../blocks/index.js'\n"]}

package/dist/render/hooks/useSurfaceId.d.ts

@@ -0,0 +1,8 @@
+/**
+ * useSurfaceId hook
+ *
+ * Re-exports from `@pwfabric/runtime/blocks` (its canonical home).
+ *
+ * @module @pwfabric/runtime/render/hooks/useSurfaceId
+ */
+export { useSurfaceId } from '../../blocks/index.js';

package/dist/render/hooks/useSurfaceId.js

@@ -0,0 +1,9 @@
+/**
+ * useSurfaceId hook
+ *
+ * Re-exports from `@pwfabric/runtime/blocks` (its canonical home).
+ *
+ * @module @pwfabric/runtime/render/hooks/useSurfaceId
+ */
+export { useSurfaceId } from '../../blocks/index.js';
+//# sourceMappingURL=useSurfaceId.js.map

package/dist/render/hooks/useSurfaceId.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useSurfaceId.js","sourceRoot":"","sources":["../../../src/render/hooks/useSurfaceId.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAA","sourcesContent":["/**\n * useSurfaceId hook\n *\n * Re-exports from `@pwfabric/runtime/blocks` (its canonical home).\n *\n * @module @pwfabric/runtime/render/hooks/useSurfaceId\n */\n\nexport { useSurfaceId } from '../../blocks/index.js'\n"]}

package/dist/render/index.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Surface Renderer Module
+ *
+ * Phase 2A.1: Surface-to-React rendering infrastructure
+ *
+ * @module @pwfabric/runtime/render
+ */
+export type { BlockComponentProps, BlockComponent, BlockComponentRegistry, CapabilityProvider, BlockContext, SurfaceEventType, SurfaceEvent, SurfaceRendererProps, BlockRendererProps, RenderResult, RenderableSurface, CapabilityType, ImageAdapter, ImageAdapterProps, BlockWrapperProps, BlockWrapperRenderArgs, BlockInteractionMode, } from './types.js';
+export { SurfaceRenderer, BlockRenderer, getBlockIds, findBlockById, updateBlockById, } from './renderer.js';
+export { surfaceThemeToCSS } from './theme-utils.js';
+export { deriveDarkTheme } from './derive-dark-theme.js';
+export { resolveResponsiveValue, resolveSpanAtBreakpoint, getColumnsAtBreakpoint, getBreakpointForWidth, resolveBlockLayout, resolveMeasureStyle, resolveSurfaceRootStyle, useViewport, } from './responsive.js';
+export { collectVisibilityCss, blockVisibilityCss, resolveHiddenBreakpoints, } from './visibility-css.js';
+export { collectStatesCss, blockStatesCss } from './states-css.js';
+export { collectConditionalStatesCss, blockConditionalStatesCss, } from './conditional-states-css.js';
+export { buildKeyframesCss } from './keyframes-css.js';
+export { collectResponsiveStyleCss, blockResponsiveStyleCss, } from './responsive-style-css.js';
+export { collectGroupStatesCss, blockGroupStatesCss } from './group-states-css.js';
+export { cssEscapeId, camelToKebab, blockIdAttr, blockSelector, collectScopedCss, } from './scoped-css.js';
+export { buildDarkThemeCss } from './dark-theme-css.js';
+export { resolveAppearanceDarkVars, resolveAppearanceKeyframes } from './appearance-resolver.js';
+export type { SurfaceDataSourceKind, SurfaceDataSourceDefinition, SurfaceActionType, SurfaceAction, BlockActionProp, DataBoundSurface, DataBoundSurfaceRendererProps, } from './data-binding-types.js';
+export { DataBoundSurfaceRenderer, surfaceNeedsDataBinding, blockActionsOf } from './DataBoundSurfaceRenderer.js';
+export { resolveEndpoint, encodeEndpointValue } from './endpoint.js';
+export { dataSourceCacheKey } from './data-cache.js';
+export type { SurfaceDataCache } from './data-cache.js';
+export { resolveBlockExpressions, resolveString } from './resolve-expressions.js';
+export { BlockErrorBoundary } from './BlockErrorBoundary.js';
+export type { EntitlementContextValue, EntitlementProviderProps, GatedBlockPlaceholderProps, } from './capability-gate.js';
+export { EntitlementProvider, useEntitlements, GatedBlockPlaceholder } from './capability-gate.js';
+export { BlockModuleLoader } from './dynamic-block-loader.js';
+export type { DynamicBlockWrapperProps } from './DynamicBlockWrapper.js';
+export { DynamicBlockWrapper } from './DynamicBlockWrapper.js';
+export type { DynamicArtifactContextValue, DynamicArtifactProviderProps, } from './dynamic-artifact-context.js';
+export { DynamicArtifactProvider, preloadDynamicBlocks, useDynamicBlocks, useDynamicStarters, } from './dynamic-artifact-context.js';
+export { createSurfaceEventBus } from './surface-event-bus.js';
+export { SurfaceEventContext } from './surface-event-context.js';
+export { useSurfaceEvents } from './hooks/useSurfaceEvents.js';
+export type { BehaviorSurfaceProviderProps } from './BehaviorSurfaceProvider.js';
+export { BehaviorSurfaceProvider } from './BehaviorSurfaceProvider.js';
+export { SurfaceIdContext } from './surface-id-context.js';
+export { useSurfaceId } from './hooks/useSurfaceId.js';
+export { EntityFacadeContext, useEntityFacade } from './entity-facade-context.js';
+export { SurfaceDataContext, useSurfaceData } from './surface-data-context.js';
+export type { SurfaceData } from './surface-data-context.js';
+export { SurfaceConnectionsContext, useSurfaceConnections } from './connections-context.js';
+export type { ShellSelectionStore, ShellSelectionOptions, ShellSelectionProviderProps } from './shell-selection.js';
+export { ShellSelectionContext, ShellSelectionProvider, createShellSelectionStore, useShellSelection, } from './shell-selection.js';

package/dist/render/index.js

@@ -0,0 +1,61 @@
+/**
+ * Surface Renderer Module
+ *
+ * Phase 2A.1: Surface-to-React rendering infrastructure
+ *
+ * @module @pwfabric/runtime/render
+ */
+// Components
+export { SurfaceRenderer, BlockRenderer, getBlockIds, findBlockById, updateBlockById, } from './renderer.js';
+// legacy first-party `*Block` component re-exports +
+// `defaultBlockComponents` retired. Components flow through the install
+// pipeline (pwpack publish → CDN bundle → BlockModuleLoader); the static
+// re-exports that lived here are gone.
+// Theme utilities
+export { surfaceThemeToCSS } from './theme-utils.js';
+export { deriveDarkTheme } from './derive-dark-theme.js';
+// Responsive utilities
+export { resolveResponsiveValue, resolveSpanAtBreakpoint, getColumnsAtBreakpoint, getBreakpointForWidth, resolveBlockLayout, resolveMeasureStyle, resolveSurfaceRootStyle, useViewport, } from './responsive.js';
+// Per-breakpoint visibility (hideOn/showOn) CSS generation
+export { collectVisibilityCss, blockVisibilityCss, resolveHiddenBreakpoints, } from './visibility-css.js';
+// Interaction-state (hover/active/focus) CSS generation
+export { collectStatesCss, blockStatesCss } from './states-css.js';
+// Conditional-state (aria/data/disabled/checked/:has) CSS generation
+export { collectConditionalStatesCss, blockConditionalStatesCss, } from './conditional-states-css.js';
+// Surface keyframe registry (appearance.config.keyframes) CSS generation
+export { buildKeyframesCss } from './keyframes-css.js';
+// Per-prop responsive style (block.style breakpoint maps) CSS generation
+export { collectResponsiveStyleCss, blockResponsiveStyleCss, } from './responsive-style-css.js';
+// Group-hover (block.groupRoot + descendant block.groupStates) CSS generation
+export { collectGroupStatesCss, blockGroupStatesCss } from './group-states-css.js';
+// Shared scoped-CSS helpers (used by the per-block collectors above)
+export { cssEscapeId, camelToKebab, blockIdAttr, blockSelector, collectScopedCss, } from './scoped-css.js';
+// Dark theme variant CSS generation + resolver
+export { buildDarkThemeCss } from './dark-theme-css.js';
+export { resolveAppearanceDarkVars, resolveAppearanceKeyframes } from './appearance-resolver.js';
+export { DataBoundSurfaceRenderer, surfaceNeedsDataBinding, blockActionsOf } from './DataBoundSurfaceRenderer.js';
+export { resolveEndpoint, encodeEndpointValue } from './endpoint.js';
+export { dataSourceCacheKey } from './data-cache.js';
+export { resolveBlockExpressions, resolveString } from './resolve-expressions.js';
+// Block Error Boundary (crash isolation)
+export { BlockErrorBoundary } from './BlockErrorBoundary.js';
+export { EntitlementProvider, useEntitlements, GatedBlockPlaceholder } from './capability-gate.js';
+// Dynamic Artifact Loading
+export { BlockModuleLoader } from './dynamic-block-loader.js';
+export { DynamicBlockWrapper } from './DynamicBlockWrapper.js';
+export { DynamicArtifactProvider, preloadDynamicBlocks, useDynamicBlocks, useDynamicStarters, } from './dynamic-artifact-context.js';
+// Surface event protocol
+export { createSurfaceEventBus } from './surface-event-bus.js';
+export { SurfaceEventContext } from './surface-event-context.js';
+export { useSurfaceEvents } from './hooks/useSurfaceEvents.js';
+export { BehaviorSurfaceProvider } from './BehaviorSurfaceProvider.js';
+export { SurfaceIdContext } from './surface-id-context.js';
+export { useSurfaceId } from './hooks/useSurfaceId.js';
+// EntityFacade → Surface Renderer integration
+export { EntityFacadeContext, useEntityFacade } from './entity-facade-context.js';
+// What the data-bound path has currently bound, by source id (form writer reads it)
+export { SurfaceDataContext, useSurfaceData } from './surface-data-context.js';
+// Connections context (world connections + engine registry)
+export { SurfaceConnectionsContext, useSurfaceConnections } from './connections-context.js';
+export { ShellSelectionContext, ShellSelectionProvider, createShellSelectionStore, useShellSelection, } from './shell-selection.js';
+//# sourceMappingURL=index.js.map

package/dist/render/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/render/index.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Surface Renderer Module\n *\n * Phase 2A.1: Surface-to-React rendering infrastructure\n *\n * @module @pwfabric/runtime/render\n */\n\n// Types\nexport type {\n  BlockComponentProps,\n  BlockComponent,\n  BlockComponentRegistry,\n  CapabilityProvider,\n  BlockContext,\n  SurfaceEventType,\n  SurfaceEvent,\n  SurfaceRendererProps,\n  BlockRendererProps,\n  RenderResult,\n  RenderableSurface,\n  CapabilityType,\n  ImageAdapter,\n  ImageAdapterProps,\n  BlockWrapperProps,\n  BlockWrapperRenderArgs,\n  BlockInteractionMode,\n} from './types.js'\n\n// Components\nexport {\n  SurfaceRenderer,\n  BlockRenderer,\n  getBlockIds,\n  findBlockById,\n  updateBlockById,\n} from './renderer.js'\n\n// legacy first-party `*Block` component re-exports +\n// `defaultBlockComponents` retired. Components flow through the install\n// pipeline (pwpack publish → CDN bundle → BlockModuleLoader); the static\n// re-exports that lived here are gone.\n\n// Theme utilities\nexport { surfaceThemeToCSS } from './theme-utils.js'\nexport { deriveDarkTheme } from './derive-dark-theme.js'\n\n// Responsive utilities\nexport {\n  resolveResponsiveValue,\n  resolveSpanAtBreakpoint,\n  getColumnsAtBreakpoint,\n  getBreakpointForWidth,\n  resolveBlockLayout,\n  resolveMeasureStyle,\n  resolveSurfaceRootStyle,\n  useViewport,\n} from './responsive.js'\n\n// Per-breakpoint visibility (hideOn/showOn) CSS generation\nexport {\n  collectVisibilityCss,\n  blockVisibilityCss,\n  resolveHiddenBreakpoints,\n} from './visibility-css.js'\n\n// Interaction-state (hover/active/focus) CSS generation\nexport { collectStatesCss, blockStatesCss } from './states-css.js'\n\n// Conditional-state (aria/data/disabled/checked/:has) CSS generation\nexport {\n  collectConditionalStatesCss,\n  blockConditionalStatesCss,\n} from './conditional-states-css.js'\n\n// Surface keyframe registry (appearance.config.keyframes) CSS generation\nexport { buildKeyframesCss } from './keyframes-css.js'\n\n// Per-prop responsive style (block.style breakpoint maps) CSS generation\nexport {\n  collectResponsiveStyleCss,\n  blockResponsiveStyleCss,\n} from './responsive-style-css.js'\n\n// Group-hover (block.groupRoot + descendant block.groupStates) CSS generation\nexport { collectGroupStatesCss, blockGroupStatesCss } from './group-states-css.js'\n\n// Shared scoped-CSS helpers (used by the per-block collectors above)\nexport {\n  cssEscapeId,\n  camelToKebab,\n  blockIdAttr,\n  blockSelector,\n  collectScopedCss,\n} from './scoped-css.js'\n\n// Dark theme variant CSS generation + resolver\nexport { buildDarkThemeCss } from './dark-theme-css.js'\nexport { resolveAppearanceDarkVars, resolveAppearanceKeyframes } from './appearance-resolver.js'\n\n// Data-bound rendering\nexport type {\n  SurfaceDataSourceKind,\n  SurfaceDataSourceDefinition,\n  SurfaceActionType,\n  SurfaceAction,\n  BlockActionProp,\n  DataBoundSurface,\n  DataBoundSurfaceRendererProps,\n} from './data-binding-types.js'\n\nexport { DataBoundSurfaceRenderer, surfaceNeedsDataBinding, blockActionsOf } from './DataBoundSurfaceRenderer.js'\nexport { resolveEndpoint, encodeEndpointValue } from './endpoint.js'\nexport { dataSourceCacheKey } from './data-cache.js'\nexport type { SurfaceDataCache } from './data-cache.js'\nexport { resolveBlockExpressions, resolveString } from './resolve-expressions.js'\n\n// Block Error Boundary (crash isolation)\nexport { BlockErrorBoundary } from './BlockErrorBoundary.js'\n\n// Capability Gate (Entitlement enforcement)\nexport type {\n  EntitlementContextValue,\n  EntitlementProviderProps,\n  GatedBlockPlaceholderProps,\n} from './capability-gate.js'\nexport { EntitlementProvider, useEntitlements, GatedBlockPlaceholder } from './capability-gate.js'\n\n// Dynamic Artifact Loading\nexport { BlockModuleLoader } from './dynamic-block-loader.js'\nexport type { DynamicBlockWrapperProps } from './DynamicBlockWrapper.js'\nexport { DynamicBlockWrapper } from './DynamicBlockWrapper.js'\nexport type {\n  DynamicArtifactContextValue,\n  DynamicArtifactProviderProps,\n} from './dynamic-artifact-context.js'\nexport {\n  DynamicArtifactProvider,\n  preloadDynamicBlocks,\n  useDynamicBlocks,\n  useDynamicStarters,\n} from './dynamic-artifact-context.js'\n\n// Surface event protocol\nexport { createSurfaceEventBus } from './surface-event-bus.js'\nexport { SurfaceEventContext } from './surface-event-context.js'\nexport { useSurfaceEvents } from './hooks/useSurfaceEvents.js'\n\n// BehaviorSurfaceProvider — runtime surface wiring\nexport type { BehaviorSurfaceProviderProps } from './BehaviorSurfaceProvider.js'\nexport { BehaviorSurfaceProvider } from './BehaviorSurfaceProvider.js'\nexport { SurfaceIdContext } from './surface-id-context.js'\nexport { useSurfaceId } from './hooks/useSurfaceId.js'\n\n// EntityFacade → Surface Renderer integration\nexport { EntityFacadeContext, useEntityFacade } from './entity-facade-context.js'\n\n// What the data-bound path has currently bound, by source id (form writer reads it)\nexport { SurfaceDataContext, useSurfaceData } from './surface-data-context.js'\nexport type { SurfaceData } from './surface-data-context.js'\n\n// Connections context (world connections + engine registry)\nexport { SurfaceConnectionsContext, useSurfaceConnections } from './connections-context.js'\n\n// Shell × body: SPLIT shell selection, projected onto the URL so a selected\n// record can be linked to and the Back button undoes the selection.\nexport type { ShellSelectionStore, ShellSelectionOptions, ShellSelectionProviderProps } from './shell-selection.js'\nexport {\n  ShellSelectionContext,\n  ShellSelectionProvider,\n  createShellSelectionStore,\n  useShellSelection,\n} from './shell-selection.js'\n"]}

package/dist/render/interaction-rule-engine.d.ts

@@ -0,0 +1,12 @@
+import type { InteractionRule, InteractionRuleEngine, SurfaceEventTrigger, SurfaceEventDescriptor } from '@pwfabric/contracts';
+export type { InteractionRule, InteractionRuleEngine, SurfaceEventTrigger };
+export declare class DefaultInteractionRuleEngine implements InteractionRuleEngine {
+    private readonly rules;
+    register(rule: InteractionRule): void;
+    unregister(ruleId: string): boolean;
+    attach(bus: {
+        on(pattern: string, handler: (e: SurfaceEventDescriptor) => void): () => void;
+    }): () => void;
+    clear(): void;
+}
+export declare function createInteractionRuleEngine(): InteractionRuleEngine;

package/dist/render/interaction-rule-engine.js

@@ -0,0 +1,47 @@
+// packages/runtime/src/render/interaction-rule-engine.ts
+// DefaultInteractionRuleEngine (formerly DefaultSurfaceBehaviorEngine)
+export class DefaultInteractionRuleEngine {
+    rules = new Map();
+    register(rule) {
+        this.rules.set(rule.id, rule);
+    }
+    unregister(ruleId) {
+        return this.rules.delete(ruleId);
+    }
+    attach(bus) {
+        const unsubscribers = [];
+        // Group rules by trigger, subscribe once per trigger
+        const byTrigger = new Map();
+        for (const rule of this.rules.values()) {
+            const existing = byTrigger.get(rule.trigger) ?? [];
+            existing.push(rule);
+            byTrigger.set(rule.trigger, existing);
+        }
+        for (const [trigger, triggerRules] of byTrigger) {
+            const unsub = bus.on(trigger, async (event) => {
+                // Sort by priority (higher = first)
+                const sorted = [...triggerRules].sort((a, b) => (b.priority ?? 0) - (a.priority ?? 0));
+                for (const rule of sorted) {
+                    try {
+                        if (rule.guard && !rule.guard(event))
+                            continue;
+                        await rule.action(event);
+                    }
+                    catch (err) {
+                        // Fail-safe: log but don't break other rules
+                        console.warn(`[InteractionRuleEngine] Rule '${rule.id}' failed:`, err);
+                    }
+                }
+            });
+            unsubscribers.push(unsub);
+        }
+        return () => unsubscribers.forEach((u) => u());
+    }
+    clear() {
+        this.rules.clear();
+    }
+}
+export function createInteractionRuleEngine() {
+    return new DefaultInteractionRuleEngine();
+}
+//# sourceMappingURL=interaction-rule-engine.js.map

package/dist/render/interaction-rule-engine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"interaction-rule-engine.js","sourceRoot":"","sources":["../../src/render/interaction-rule-engine.ts"],"names":[],"mappings":"AAAA,yDAAyD;AACzD,uEAAuE;AAWvE,MAAM,OAAO,4BAA4B;IACtB,KAAK,GAAG,IAAI,GAAG,EAA2B,CAAA;IAE3D,QAAQ,CAAC,IAAqB;QAC5B,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,EAAE,IAAI,CAAC,CAAA;IAC/B,CAAC;IAED,UAAU,CAAC,MAAc;QACvB,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;IAClC,CAAC;IAED,MAAM,CAAC,GAEN;QACC,MAAM,aAAa,GAAmB,EAAE,CAAA;QAExC,qDAAqD;QACrD,MAAM,SAAS,GAAG,IAAI,GAAG,EAA6B,CAAA;QACtD,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,EAAE,CAAC;YACvC,MAAM,QAAQ,GAAG,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,CAAA;YAClD,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;YACnB,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAA;QACvC,CAAC;QAED,KAAK,MAAM,CAAC,OAAO,EAAE,YAAY,CAAC,IAAI,SAAS,EAAE,CAAC;YAChD,MAAM,KAAK,GAAG,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,KAAK,EAAE,KAA6B,EAAE,EAAE;gBACpE,oCAAoC;gBACpC,MAAM,MAAM,GAAG,CAAC,GAAG,YAAY,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,QAAQ,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,QAAQ,IAAI,CAAC,CAAC,CAAC,CAAA;gBACtF,KAAK,MAAM,IAAI,IAAI,MAAM,EAAE,CAAC;oBAC1B,IAAI,CAAC;wBACH,IAAI,IAAI,CAAC,KAAK,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC;4BAAE,SAAQ;wBAC9C,MAAM,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;oBAC1B,CAAC;oBAAC,OAAO,GAAG,EAAE,CAAC;wBACb,6CAA6C;wBAC7C,OAAO,CAAC,IAAI,CAAC,iCAAiC,IAAI,CAAC,EAAE,WAAW,EAAE,GAAG,CAAC,CAAA;oBACxE,CAAC;gBACH,CAAC;YACH,CAAC,CAAC,CAAA;YACF,aAAa,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;QAC3B,CAAC;QAED,OAAO,GAAG,EAAE,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,CAAA;IAChD,CAAC;IAED,KAAK;QACH,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAA;IACpB,CAAC;CACF;AAED,MAAM,UAAU,2BAA2B;IACzC,OAAO,IAAI,4BAA4B,EAAE,CAAA;AAC3C,CAAC","sourcesContent":["// packages/runtime/src/render/interaction-rule-engine.ts\n// DefaultInteractionRuleEngine (formerly DefaultSurfaceBehaviorEngine)\n\nimport type {\n  InteractionRule,\n  InteractionRuleEngine,\n  SurfaceEventTrigger,\n  SurfaceEventDescriptor,\n} from '@pwfabric/contracts'\n\nexport type { InteractionRule, InteractionRuleEngine, SurfaceEventTrigger }\n\nexport class DefaultInteractionRuleEngine implements InteractionRuleEngine {\n  private readonly rules = new Map<string, InteractionRule>()\n\n  register(rule: InteractionRule): void {\n    this.rules.set(rule.id, rule)\n  }\n\n  unregister(ruleId: string): boolean {\n    return this.rules.delete(ruleId)\n  }\n\n  attach(bus: {\n    on(pattern: string, handler: (e: SurfaceEventDescriptor) => void): () => void\n  }): () => void {\n    const unsubscribers: (() => void)[] = []\n\n    // Group rules by trigger, subscribe once per trigger\n    const byTrigger = new Map<string, InteractionRule[]>()\n    for (const rule of this.rules.values()) {\n      const existing = byTrigger.get(rule.trigger) ?? []\n      existing.push(rule)\n      byTrigger.set(rule.trigger, existing)\n    }\n\n    for (const [trigger, triggerRules] of byTrigger) {\n      const unsub = bus.on(trigger, async (event: SurfaceEventDescriptor) => {\n        // Sort by priority (higher = first)\n        const sorted = [...triggerRules].sort((a, b) => (b.priority ?? 0) - (a.priority ?? 0))\n        for (const rule of sorted) {\n          try {\n            if (rule.guard && !rule.guard(event)) continue\n            await rule.action(event)\n          } catch (err) {\n            // Fail-safe: log but don't break other rules\n            console.warn(`[InteractionRuleEngine] Rule '${rule.id}' failed:`, err)\n          }\n        }\n      })\n      unsubscribers.push(unsub)\n    }\n\n    return () => unsubscribers.forEach((u) => u())\n  }\n\n  clear(): void {\n    this.rules.clear()\n  }\n}\n\nexport function createInteractionRuleEngine(): InteractionRuleEngine {\n  return new DefaultInteractionRuleEngine()\n}\n"]}