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

package/dist/render/responsive-style-css.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Per-prop responsive style CSS generation (block.style values vary by breakpoint).
+ *
+ * `block.style` sits inline and can express a single value per property; it
+ * cannot express media queries. A style prop whose value is a
+ * `ResponsiveValue<string>` map (`{ xs?, sm?, md?, lg?, xl?, '2xl'? }`) instead
+ * of a flat string declares a value that varies per breakpoint. The renderer
+ * flattens the base (`xs` / smallest defined) value inline so SSR / no-JS get a
+ * sane default; this collector emits the LARGER-breakpoint values as scoped,
+ * mobile-first `min-width` media-query rules — keyed by the block's
+ * `data-block-id` — that override upward. Same mechanism `layout.hideOn`/
+ * `showOn` (visibility-css) and `block.states` (states-css) use.
+ *
+ * For a block with `style.padding = { xs:'8px', md:'24px', lg:'48px' }`:
+ *
+ *   `@media (min-width:768px){[data-pw-surface] [data-block-id="<id>"]{padding:24px}}`
+ *   `@media (min-width:1024px){[data-pw-surface] [data-block-id="<id>"]{padding:48px}}`
+ *
+ * The `xs` (base) value is NOT emitted here — it is rendered inline by the
+ * renderer. Flat string values emit zero bytes (the inline path owns them).
+ * Blocks without any responsive style value emit zero bytes so existing
+ * surfaces are byte-identical.
+ *
+ * @module @pwfabric/runtime/render/responsive-style-css
+ */
+import type { Block } from '@pwfabric/core';
+/**
+ * Emit the scoped per-breakpoint media-query CSS for a single block's
+ * responsive style props. Targets `[data-block-id="<id>"]` scoped under the
+ * surface root so it cannot leak to the host page. Only breakpoints LARGER than
+ * `xs` are emitted (the `xs`/base value is inline); each emitted breakpoint key
+ * becomes a `@media (min-width:<px>)` rule. Returns '' when the block declares
+ * no responsive style value.
+ */
+export declare function blockResponsiveStyleCss(blockId: string, style: NonNullable<Block['style']>, surfaceId?: string): string;
+/**
+ * Walk a surface block tree and concatenate the per-block responsive style CSS
+ * for every block declaring a `ResponsiveValue` style prop. Blocks with only
+ * flat string style values (or no style) are skipped (zero bytes emitted) so
+ * existing surfaces are byte-identical.
+ */
+export declare function collectResponsiveStyleCss(blocks: readonly Block[], surfaceId?: string): string;

package/dist/render/responsive-style-css.js

@@ -0,0 +1,123 @@
+/**
+ * Per-prop responsive style CSS generation (block.style values vary by breakpoint).
+ *
+ * `block.style` sits inline and can express a single value per property; it
+ * cannot express media queries. A style prop whose value is a
+ * `ResponsiveValue<string>` map (`{ xs?, sm?, md?, lg?, xl?, '2xl'? }`) instead
+ * of a flat string declares a value that varies per breakpoint. The renderer
+ * flattens the base (`xs` / smallest defined) value inline so SSR / no-JS get a
+ * sane default; this collector emits the LARGER-breakpoint values as scoped,
+ * mobile-first `min-width` media-query rules — keyed by the block's
+ * `data-block-id` — that override upward. Same mechanism `layout.hideOn`/
+ * `showOn` (visibility-css) and `block.states` (states-css) use.
+ *
+ * For a block with `style.padding = { xs:'8px', md:'24px', lg:'48px' }`:
+ *
+ *   `@media (min-width:768px){[data-pw-surface] [data-block-id="<id>"]{padding:24px}}`
+ *   `@media (min-width:1024px){[data-pw-surface] [data-block-id="<id>"]{padding:48px}}`
+ *
+ * The `xs` (base) value is NOT emitted here — it is rendered inline by the
+ * renderer. Flat string values emit zero bytes (the inline path owns them).
+ * Blocks without any responsive style value emit zero bytes so existing
+ * surfaces are byte-identical.
+ *
+ * @module @pwfabric/runtime/render/responsive-style-css
+ */
+import { BREAKPOINTS, BREAKPOINT_ORDER } from '@pwfabric/core';
+import { blockSelector, camelToKebab, collectScopedCss, LAYOUT_HOIST_KEYS, WRAPPER_ATTR } from './scoped-css.js';
+/** Breakpoint name → `minWidth` px (same thresholds the span/visibility systems use). */
+function minWidthFor(bp) {
+    return BREAKPOINTS.find((b) => b.name === bp)?.minWidth ?? 0;
+}
+/** A style prop value is responsive when it is a non-null object (not a flat string). */
+function isResponsiveValue(value) {
+    return typeof value === 'object' && value !== null;
+}
+/**
+ * Emit the scoped per-breakpoint media-query CSS for a single block's
+ * responsive style props. Targets `[data-block-id="<id>"]` scoped under the
+ * surface root so it cannot leak to the host page. Only breakpoints LARGER than
+ * `xs` are emitted (the `xs`/base value is inline); each emitted breakpoint key
+ * becomes a `@media (min-width:<px>)` rule. Returns '' when the block declares
+ * no responsive style value.
+ */
+export function blockResponsiveStyleCss(blockId, style, surfaceId) {
+    const selector = blockSelector(blockId, surfaceId);
+    // Group declarations by breakpoint so one prop's md value and another prop's
+    // md value share a single `@media` rule (mirrors how a mobile-first stylesheet
+    // would be authored). The base (smallest defined breakpoint per prop) is a
+    // NON-media rule so ALL breakpoints live in the stylesheet — never inline.
+    // (Inline always beats stylesheet rules incl. @media, so a flattened-inline
+    // base would pin the value and the larger @media overrides would never apply.)
+    // THE HOISTING RULE APPLIES ON THE SELECTOR SIDE TOO.
+    //
+    // `[data-block-id]` matches BOTH the wrapper AND the component root. For flat
+    // values the renderer hoists margin/maxWidth/flex to the wrapper and removes
+    // them from the root; for responsive values the value leaves the inline style
+    // and lands here, so without the same split here the rule would apply TWICE
+    // (`marginTop:'-40%'` → both -335px and -256px).
+    //
+    // Hence two sets: hoisted keys go ONLY to the wrapper, the rest ONLY to the
+    // component root.
+    const HOIST = new Set(LAYOUT_HOIST_KEYS);
+    const baseDecls = [];
+    const byBreakpoint = new Map();
+    const baseHoist = [];
+    const byBreakpointHoist = new Map();
+    for (const [prop, value] of Object.entries(style)) {
+        if (!isResponsiveValue(value))
+            continue; // flat string → inline path owns it
+        let baseTaken = false;
+        // BREAKPOINT_ORDER is mobile-first ascending → first defined key is the base.
+        for (const bp of BREAKPOINT_ORDER) {
+            const v = value[bp];
+            if (v === undefined)
+                continue;
+            // `!important`: a block COMPONENT often applies the same CSS property
+            // inline with its own default (e.g. the text block sets
+            // `font-size: var(--pw-font-size-base)`). Inline beats any stylesheet rule,
+            // so without `!important` the author's responsive value would be pinned to
+            // the component default. Scoped to `[data-block-id]`, this only overrides
+            // the one block's own responsive props. Base + larger are both `!important`
+            // at equal specificity → source order (larger emitted later) wins on match.
+            const hoisted = HOIST.has(prop);
+            const bag = hoisted ? baseHoist : baseDecls;
+            const map = hoisted ? byBreakpointHoist : byBreakpoint;
+            if (!baseTaken) {
+                bag.push(`${camelToKebab(prop)}:${v} !important`);
+                baseTaken = true;
+            }
+            else {
+                const decls = map.get(bp) ?? [];
+                decls.push(`${camelToKebab(prop)}:${v} !important`);
+                map.set(bp, decls);
+            }
+        }
+    }
+    let css = '';
+    // Base (non-media) first, then ascending breakpoint order so larger
+    // breakpoints (later in source) win the cascade at equal specificity.
+    const emit = (sel, base, map) => {
+        if (base.length > 0)
+            css += `${sel}{${base.join(';')}}`;
+        for (const bp of BREAKPOINT_ORDER) {
+            const decls = map.get(bp);
+            if (!decls || decls.length === 0)
+                continue;
+            css += `@media (min-width:${minWidthFor(bp)}px){${sel}{${decls.join(';')}}}`;
+        }
+    };
+    emit(`${selector}:not(${WRAPPER_ATTR})`, baseDecls, byBreakpoint);
+    emit(`${selector}${WRAPPER_ATTR}`, baseHoist, byBreakpointHoist);
+    return css;
+}
+/**
+ * Walk a surface block tree and concatenate the per-block responsive style CSS
+ * for every block declaring a `ResponsiveValue` style prop. Blocks with only
+ * flat string style values (or no style) are skipped (zero bytes emitted) so
+ * existing surfaces are byte-identical.
+ */
+export function collectResponsiveStyleCss(blocks, surfaceId) {
+    return collectScopedCss(blocks, (block) => block.style ? blockResponsiveStyleCss(block.id, block.style, surfaceId) : '');
+}
+//# sourceMappingURL=responsive-style-css.js.map

package/dist/render/responsive-style-css.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"responsive-style-css.js","sourceRoot":"","sources":["../../src/render/responsive-style-css.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Per-prop responsive style CSS generation (block.style values vary by breakpoint).\n *\n * `block.style` sits inline and can express a single value per property; it\n * cannot express media queries. A style prop whose value is a\n * `ResponsiveValue<string>` map (`{ xs?, sm?, md?, lg?, xl?, '2xl'? }`) instead\n * of a flat string declares a value that varies per breakpoint. The renderer\n * flattens the base (`xs` / smallest defined) value inline so SSR / no-JS get a\n * sane default; this collector emits the LARGER-breakpoint values as scoped,\n * mobile-first `min-width` media-query rules — keyed by the block's\n * `data-block-id` — that override upward. Same mechanism `layout.hideOn`/\n * `showOn` (visibility-css) and `block.states` (states-css) use.\n *\n * For a block with `style.padding = { xs:'8px', md:'24px', lg:'48px' }`:\n *\n *   `@media (min-width:768px){[data-pw-surface] [data-block-id=\"<id>\"]{padding:24px}}`\n *   `@media (min-width:1024px){[data-pw-surface] [data-block-id=\"<id>\"]{padding:48px}}`\n *\n * The `xs` (base) value is NOT emitted here — it is rendered inline by the\n * renderer. Flat string values emit zero bytes (the inline path owns them).\n * Blocks without any responsive style value emit zero bytes so existing\n * surfaces are byte-identical.\n *\n * @module @pwfabric/runtime/render/responsive-style-css\n */\n\nimport type { Block } from '@pwfabric/core'\nimport { BREAKPOINTS, BREAKPOINT_ORDER } from '@pwfabric/core'\nimport type { BreakpointName } from '@pwfabric/core'\nimport { blockSelector, camelToKebab, collectScopedCss, LAYOUT_HOIST_KEYS, WRAPPER_ATTR } from './scoped-css.js'\n\n/** Breakpoint name → `minWidth` px (same thresholds the span/visibility systems use). */\nfunction minWidthFor(bp: BreakpointName): number {\n  return BREAKPOINTS.find((b) => b.name === bp)?.minWidth ?? 0\n}\n\n/** A per-breakpoint value map (the responsive form of a style prop value). */\ntype ResponsiveStyleValue = Partial<Record<BreakpointName, string>>\n\n/** A style prop value is responsive when it is a non-null object (not a flat string). */\nfunction isResponsiveValue(value: unknown): value is ResponsiveStyleValue {\n  return typeof value === 'object' && value !== null\n}\n\n/**\n * Emit the scoped per-breakpoint media-query CSS for a single block's\n * responsive style props. Targets `[data-block-id=\"<id>\"]` scoped under the\n * surface root so it cannot leak to the host page. Only breakpoints LARGER than\n * `xs` are emitted (the `xs`/base value is inline); each emitted breakpoint key\n * becomes a `@media (min-width:<px>)` rule. Returns '' when the block declares\n * no responsive style value.\n */\nexport function blockResponsiveStyleCss(\n  blockId: string,\n  style: NonNullable<Block['style']>,\n  surfaceId?: string\n): string {\n  const selector = blockSelector(blockId, surfaceId)\n  // Group declarations by breakpoint so one prop's md value and another prop's\n  // md value share a single `@media` rule (mirrors how a mobile-first stylesheet\n  // would be authored). The base (smallest defined breakpoint per prop) is a\n  // NON-media rule so ALL breakpoints live in the stylesheet — never inline.\n  // (Inline always beats stylesheet rules incl. @media, so a flattened-inline\n  // base would pin the value and the larger @media overrides would never apply.)\n  // THE HOISTING RULE APPLIES ON THE SELECTOR SIDE TOO.\n  //\n  // `[data-block-id]` matches BOTH the wrapper AND the component root. For flat\n  // values the renderer hoists margin/maxWidth/flex to the wrapper and removes\n  // them from the root; for responsive values the value leaves the inline style\n  // and lands here, so without the same split here the rule would apply TWICE\n  // (`marginTop:'-40%'` → both -335px and -256px).\n  //\n  // Hence two sets: hoisted keys go ONLY to the wrapper, the rest ONLY to the\n  // component root.\n  const HOIST = new Set<string>(LAYOUT_HOIST_KEYS)\n  const baseDecls: string[] = []\n  const byBreakpoint = new Map<BreakpointName, string[]>()\n  const baseHoist: string[] = []\n  const byBreakpointHoist = new Map<BreakpointName, string[]>()\n\n  for (const [prop, value] of Object.entries(style)) {\n    if (!isResponsiveValue(value)) continue // flat string → inline path owns it\n    let baseTaken = false\n    // BREAKPOINT_ORDER is mobile-first ascending → first defined key is the base.\n    for (const bp of BREAKPOINT_ORDER) {\n      const v = value[bp]\n      if (v === undefined) continue\n      // `!important`: a block COMPONENT often applies the same CSS property\n      // inline with its own default (e.g. the text block sets\n      // `font-size: var(--pw-font-size-base)`). Inline beats any stylesheet rule,\n      // so without `!important` the author's responsive value would be pinned to\n      // the component default. Scoped to `[data-block-id]`, this only overrides\n      // the one block's own responsive props. Base + larger are both `!important`\n      // at equal specificity → source order (larger emitted later) wins on match.\n      const hoisted = HOIST.has(prop)\n      const bag = hoisted ? baseHoist : baseDecls\n      const map = hoisted ? byBreakpointHoist : byBreakpoint\n      if (!baseTaken) {\n        bag.push(`${camelToKebab(prop)}:${v} !important`)\n        baseTaken = true\n      } else {\n        const decls = map.get(bp) ?? []\n        decls.push(`${camelToKebab(prop)}:${v} !important`)\n        map.set(bp, decls)\n      }\n    }\n  }\n\n  let css = ''\n  // Base (non-media) first, then ascending breakpoint order so larger\n  // breakpoints (later in source) win the cascade at equal specificity.\n  const emit = (sel: string, base: string[], map: Map<BreakpointName, string[]>): void => {\n    if (base.length > 0) css += `${sel}{${base.join(';')}}`\n    for (const bp of BREAKPOINT_ORDER) {\n      const decls = map.get(bp)\n      if (!decls || decls.length === 0) continue\n      css += `@media (min-width:${minWidthFor(bp)}px){${sel}{${decls.join(';')}}}`\n    }\n  }\n  emit(`${selector}:not(${WRAPPER_ATTR})`, baseDecls, byBreakpoint)\n  emit(`${selector}${WRAPPER_ATTR}`, baseHoist, byBreakpointHoist)\n  return css\n}\n\n/**\n * Walk a surface block tree and concatenate the per-block responsive style CSS\n * for every block declaring a `ResponsiveValue` style prop. Blocks with only\n * flat string style values (or no style) are skipped (zero bytes emitted) so\n * existing surfaces are byte-identical.\n */\nexport function collectResponsiveStyleCss(blocks: readonly Block[], surfaceId?: string): string {\n  return collectScopedCss(blocks, (block) =>\n    block.style ? blockResponsiveStyleCss(block.id, block.style, surfaceId) : ''\n  )\n}\n"]}

package/dist/render/responsive.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Responsive Rendering Utilities
+ *
+ * Viewport-aware layout resolution for runtime rendering.
+ * Re-exports pure functions from @pwfabric/core and provides
+ * React-specific viewport hook.
+ *
+ * @module @pwfabric/runtime/render/responsive
+ */
+import * as React from 'react';
+import type { BlockLayout, BreakpointName } from '@pwfabric/core';
+export { resolveResponsiveValue, resolveSpanAtBreakpoint, getColumnsAtBreakpoint, getBreakpointForWidth, } from '@pwfabric/core';
+/**
+ * Resolve the complete block layout at a given viewport breakpoint.
+ * Returns span, offset, order, and hidden values.
+ */
+export declare function resolveBlockLayout(layout: BlockLayout, viewport: BreakpointName): {
+    span: number;
+    offset: number | undefined;
+    order: number | undefined;
+    hidden: boolean | undefined;
+};
+/**
+ * Surface root — carries NO MEASURE.
+ *
+ * If the root carried both the 12-column grid and
+ * `maxWidth: var(--pw-layout-container-max-width)` + `margin: 0 auto`,
+ * persistent chrome would sit inside the centred box too (a persistent rail
+ * would start well in from the screen edge, as part of the narrower container).
+ *
+ * The measure goes to the inner container through `resolveMeasureStyle`;
+ * the root is flow only.
+ */
+export declare function resolveSurfaceRootStyle(gap?: string | number, padding?: string | number): React.CSSProperties;
+/**
+ * Measured container — the wrapper of `container`-scoped blocks.
+ *
+ * The 12-column grid and `containerMaxWidth` live HERE. Blocks that declare
+ * `widthScope:'viewport'` are drawn as SIBLINGS of this container, not its
+ * children — the escape is placement, not a CSS trick (see render/width-scope.ts).
+ */
+export declare function resolveMeasureStyle(viewport: BreakpointName, gap?: string | number, padding?: string | number, containerMaxWidth?: string): React.CSSProperties;
+/**
+ * React hook that returns the current viewport breakpoint.
+ * Uses matchMedia for efficient viewport detection.
+ *
+ * Returns 'lg' on server (SSR fallback).
+ */
+export declare function useViewport(): BreakpointName;

package/dist/render/responsive.js

@@ -0,0 +1,99 @@
+/**
+ * Responsive Rendering Utilities
+ *
+ * Viewport-aware layout resolution for runtime rendering.
+ * Re-exports pure functions from @pwfabric/core and provides
+ * React-specific viewport hook.
+ *
+ * @module @pwfabric/runtime/render/responsive
+ */
+import * as React from 'react';
+import { BREAKPOINTS, resolveSpanAtBreakpoint, resolveResponsiveValue, getColumnsAtBreakpoint, getBreakpointForWidth, } from '@pwfabric/core';
+// Re-export pure functions for convenience
+export { resolveResponsiveValue, resolveSpanAtBreakpoint, getColumnsAtBreakpoint, getBreakpointForWidth, } from '@pwfabric/core';
+// ============================================================
+// BLOCK STYLE RESOLUTION
+// ============================================================
+/**
+ * Resolve the complete block layout at a given viewport breakpoint.
+ * Returns span, offset, order, and hidden values.
+ */
+export function resolveBlockLayout(layout, viewport) {
+    return {
+        span: resolveSpanAtBreakpoint(layout, viewport),
+        offset: resolveResponsiveValue(layout.offset, viewport),
+        order: resolveResponsiveValue(layout.order, viewport),
+        hidden: resolveResponsiveValue(layout.hidden, viewport),
+    };
+}
+/**
+ * Surface root — carries NO MEASURE.
+ *
+ * If the root carried both the 12-column grid and
+ * `maxWidth: var(--pw-layout-container-max-width)` + `margin: 0 auto`,
+ * persistent chrome would sit inside the centred box too (a persistent rail
+ * would start well in from the screen edge, as part of the narrower container).
+ *
+ * The measure goes to the inner container through `resolveMeasureStyle`;
+ * the root is flow only.
+ */
+export function resolveSurfaceRootStyle(gap = 16, padding = 0) {
+    return {
+        display: 'flex',
+        flexDirection: 'column',
+        gap: typeof gap === 'number' ? `${gap}px` : gap,
+        padding: typeof padding === 'number' ? `${padding}px` : padding,
+    };
+}
+/**
+ * Measured container — the wrapper of `container`-scoped blocks.
+ *
+ * The 12-column grid and `containerMaxWidth` live HERE. Blocks that declare
+ * `widthScope:'viewport'` are drawn as SIBLINGS of this container, not its
+ * children — the escape is placement, not a CSS trick (see render/width-scope.ts).
+ */
+export function resolveMeasureStyle(viewport, gap = 16, padding = 24, containerMaxWidth = 'var(--pw-layout-container-max-width)') {
+    const columns = getColumnsAtBreakpoint(viewport);
+    return {
+        display: 'grid',
+        gridTemplateColumns: `repeat(${columns}, 1fr)`,
+        gap: typeof gap === 'number' ? `${gap}px` : gap,
+        padding: typeof padding === 'number' ? `${padding}px` : padding,
+        maxWidth: containerMaxWidth,
+        margin: '0 auto',
+        width: '100%',
+    };
+}
+// ============================================================
+// VIEWPORT HOOK
+// ============================================================
+/**
+ * React hook that returns the current viewport breakpoint.
+ * Uses matchMedia for efficient viewport detection.
+ *
+ * Returns 'lg' on server (SSR fallback).
+ */
+export function useViewport() {
+    const [breakpoint, setBreakpoint] = React.useState('lg');
+    React.useEffect(() => {
+        // Set initial value from current window width
+        setBreakpoint(getBreakpointForWidth(window.innerWidth));
+        // Create media query listeners for each breakpoint transition
+        const listeners = [];
+        for (const bp of BREAKPOINTS) {
+            const mql = window.matchMedia(`(min-width: ${bp.minWidth}px)`);
+            const handler = () => {
+                setBreakpoint(getBreakpointForWidth(window.innerWidth));
+            };
+            mql.addEventListener('change', handler);
+            listeners.push({ mql, handler });
+        }
+        return () => {
+            for (const { mql, handler } of listeners) {
+                mql.removeEventListener('change', handler);
+            }
+        };
+    }, []);
+    return breakpoint;
+}
+//# sourceMappingURL=responsive.js.map

package/dist/render/responsive.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"responsive.js","sourceRoot":"","sources":["../../src/render/responsive.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Responsive Rendering Utilities\n *\n * Viewport-aware layout resolution for runtime rendering.\n * Re-exports pure functions from @pwfabric/core and provides\n * React-specific viewport hook.\n *\n * @module @pwfabric/runtime/render/responsive\n */\n\nimport * as React from 'react'\nimport type { BlockLayout, BreakpointName } from '@pwfabric/core'\nimport {\n  BREAKPOINTS,\n  resolveSpanAtBreakpoint,\n  resolveResponsiveValue,\n  getColumnsAtBreakpoint,\n  getBreakpointForWidth,\n} from '@pwfabric/core'\n\n// Re-export pure functions for convenience\nexport {\n  resolveResponsiveValue,\n  resolveSpanAtBreakpoint,\n  getColumnsAtBreakpoint,\n  getBreakpointForWidth,\n} from '@pwfabric/core'\n\n// ============================================================\n// BLOCK STYLE RESOLUTION\n// ============================================================\n\n/**\n * Resolve the complete block layout at a given viewport breakpoint.\n * Returns span, offset, order, and hidden values.\n */\nexport function resolveBlockLayout(\n  layout: BlockLayout,\n  viewport: BreakpointName\n): {\n  span: number\n  offset: number | undefined\n  order: number | undefined\n  hidden: boolean | undefined\n} {\n  return {\n    span: resolveSpanAtBreakpoint(layout, viewport),\n    offset: resolveResponsiveValue(layout.offset, viewport),\n    order: resolveResponsiveValue(layout.order, viewport),\n    hidden: resolveResponsiveValue(layout.hidden, viewport),\n  }\n}\n\n/**\n * Surface root — carries NO MEASURE.\n *\n * If the root carried both the 12-column grid and\n * `maxWidth: var(--pw-layout-container-max-width)` + `margin: 0 auto`,\n * persistent chrome would sit inside the centred box too (a persistent rail\n * would start well in from the screen edge, as part of the narrower container).\n *\n * The measure goes to the inner container through `resolveMeasureStyle`;\n * the root is flow only.\n */\nexport function resolveSurfaceRootStyle(\n  gap: string | number = 16,\n  padding: string | number = 0\n): React.CSSProperties {\n  return {\n    display: 'flex',\n    flexDirection: 'column',\n    gap: typeof gap === 'number' ? `${gap}px` : gap,\n    padding: typeof padding === 'number' ? `${padding}px` : padding,\n  }\n}\n\n/**\n * Measured container — the wrapper of `container`-scoped blocks.\n *\n * The 12-column grid and `containerMaxWidth` live HERE. Blocks that declare\n * `widthScope:'viewport'` are drawn as SIBLINGS of this container, not its\n * children — the escape is placement, not a CSS trick (see render/width-scope.ts).\n */\nexport function resolveMeasureStyle(\n  viewport: BreakpointName,\n  gap: string | number = 16,\n  padding: string | number = 24,\n  containerMaxWidth = 'var(--pw-layout-container-max-width)'\n): React.CSSProperties {\n  const columns = getColumnsAtBreakpoint(viewport)\n  return {\n    display: 'grid',\n    gridTemplateColumns: `repeat(${columns}, 1fr)`,\n    gap: typeof gap === 'number' ? `${gap}px` : gap,\n    padding: typeof padding === 'number' ? `${padding}px` : padding,\n    maxWidth: containerMaxWidth,\n    margin: '0 auto',\n    width: '100%',\n  }\n}\n\n// ============================================================\n// VIEWPORT HOOK\n// ============================================================\n\n/**\n * React hook that returns the current viewport breakpoint.\n * Uses matchMedia for efficient viewport detection.\n *\n * Returns 'lg' on server (SSR fallback).\n */\nexport function useViewport(): BreakpointName {\n  const [breakpoint, setBreakpoint] = React.useState<BreakpointName>('lg')\n\n  React.useEffect(() => {\n    // Set initial value from current window width\n    setBreakpoint(getBreakpointForWidth(window.innerWidth))\n\n    // Create media query listeners for each breakpoint transition\n    const listeners: { mql: MediaQueryList; handler: () => void }[] = []\n\n    for (const bp of BREAKPOINTS) {\n      const mql = window.matchMedia(`(min-width: ${bp.minWidth}px)`)\n      const handler = (): void => {\n        setBreakpoint(getBreakpointForWidth(window.innerWidth))\n      }\n      mql.addEventListener('change', handler)\n      listeners.push({ mql, handler })\n    }\n\n    return () => {\n      for (const { mql, handler } of listeners) {\n        mql.removeEventListener('change', handler)\n      }\n    }\n  }, [])\n\n  return breakpoint\n}\n"]}

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

@@ -0,0 +1,71 @@
+/**
+ * Shared helpers for the scoped per-block CSS collectors.
+ *
+ * The runtime emits several kinds of scoped `<style>` rules keyed by a block's
+ * stable `data-block-id` (visibility / interaction-states / responsive-style /
+ * conditional-states / group-states). They all share the SAME primitives:
+ *
+ *   - `cssEscapeId(id)`      — conservative attribute-value escaper for block ids.
+ *   - `camelToKebab(prop)`   — CSS camelCase property name → kebab-case.
+ *   - `blockSelector(id)`    — `[data-pw-surface] [data-block-id="<escaped>"]`,
+ *                              the scoped base selector every rule attaches to.
+ *   - `collectScopedCss(blocks, perBlockFn)` — walk the block tree (including
+ *                              children) and concatenate each block's CSS as
+ *                              produced by `perBlockFn(block)`.
+ *
+ * Centralising these keeps the per-collector files focused on their own
+ * selector/declaration semantics and guarantees byte-identical output across
+ * the family (the same escaper, the same selector string, the same walk order).
+ *
+ * @module @pwfabric/runtime/render/scoped-css
+ */
+import type { Block } from '@pwfabric/core';
+/** Conservative CSS attribute-selector value escaper (block ids are slugs, but be safe). */
+export declare function cssEscapeId(id: string): string;
+/** camelCase CSS property → kebab-case (e.g. `backgroundColor` → `background-color`). */
+export declare function camelToKebab(prop: string): string;
+/** The bare `[data-block-id="<escaped-id>"]` attribute selector (no surface scope). */
+export declare function blockIdAttr(id: string): string;
+/**
+ * The surface-root selector a scoped rule hangs off.
+ *
+ * With a `surfaceId` this is `[data-pw-surface="<id>"]` — scope carried by the
+ * attribute's VALUE, not merely its presence. That matters because the embed
+ * autoloader hydrates EVERY `[data-pw-surface]` element in a document, so a host
+ * page can hold several surfaces at once; a value-less selector makes each
+ * surface's rules apply to all of them, and the last one in document order wins.
+ *
+ * Without a `surfaceId` it degrades to the historical `[data-pw-surface]`, which
+ * is correct for rules whose content is identical for every surface (the base
+ * CSS) and for unit tests that render a single surface.
+ */
+export declare function surfaceScope(surfaceId?: string): string;
+/**
+ * The scoped base selector a per-block rule attaches to:
+ * `[data-pw-surface="<sid>"] [data-block-id="<escaped-id>"]`. Scoped under the
+ * surface root so a rule can never leak to the host page — and, when the surface
+ * id is supplied, never to a SIBLING surface that happens to reuse a block id.
+ */
+export declare function blockSelector(id: string, surfaceId?: string): string;
+/**
+ * Walk a surface block tree (depth-first, children after their parent — the
+ * order all collectors used) and concatenate the per-block CSS produced by
+ * `perBlockFn(block)`. Blocks for which `perBlockFn` returns '' contribute zero
+ * bytes, so existing surfaces stay byte-identical.
+ */
+export declare function collectScopedCss(blocks: readonly Block[], perBlockFn: (block: Block) => string): string;
+/**
+ * Style keys HOISTED to the wrapper — kept here so the renderer and the
+ * responsive CSS generator see the SAME list.
+ *
+ * This list is a RULE: these keys apply to the outer wrapper, not the
+ * component root. For flat values the renderer hoists them; for responsive
+ * values the value leaves the inline style entirely and lands in CSS, so the
+ * same rule has to be expressed on the selector side — otherwise the rule
+ * matches both the wrapper and the root and the value is applied TWICE
+ * (`marginTop:'-40%'` would move content by both -335px and -256px).
+ */
+export declare const FLEX_HOIST_KEYS: readonly ["flex", "flexGrow", "flexShrink", "flexBasis"];
+export declare const LAYOUT_HOIST_KEYS: readonly ["margin", "marginTop", "marginRight", "marginBottom", "marginLeft", "maxWidth", "minWidth", "flex", "flexGrow", "flexShrink", "flexBasis"];
+/** The attribute that tells the wrapper from the component root (the same marker states-css uses). */
+export declare const WRAPPER_ATTR = "[data-block-wrapper]";

package/dist/render/scoped-css.js

@@ -0,0 +1,102 @@
+/**
+ * Shared helpers for the scoped per-block CSS collectors.
+ *
+ * The runtime emits several kinds of scoped `<style>` rules keyed by a block's
+ * stable `data-block-id` (visibility / interaction-states / responsive-style /
+ * conditional-states / group-states). They all share the SAME primitives:
+ *
+ *   - `cssEscapeId(id)`      — conservative attribute-value escaper for block ids.
+ *   - `camelToKebab(prop)`   — CSS camelCase property name → kebab-case.
+ *   - `blockSelector(id)`    — `[data-pw-surface] [data-block-id="<escaped>"]`,
+ *                              the scoped base selector every rule attaches to.
+ *   - `collectScopedCss(blocks, perBlockFn)` — walk the block tree (including
+ *                              children) and concatenate each block's CSS as
+ *                              produced by `perBlockFn(block)`.
+ *
+ * Centralising these keeps the per-collector files focused on their own
+ * selector/declaration semantics and guarantees byte-identical output across
+ * the family (the same escaper, the same selector string, the same walk order).
+ *
+ * @module @pwfabric/runtime/render/scoped-css
+ */
+/** Conservative CSS attribute-selector value escaper (block ids are slugs, but be safe). */
+export function cssEscapeId(id) {
+    return id.replace(/["\\]/g, '\\$&');
+}
+/** camelCase CSS property → kebab-case (e.g. `backgroundColor` → `background-color`). */
+export function camelToKebab(prop) {
+    return prop.replace(/[A-Z]/g, (m) => `-${m.toLowerCase()}`);
+}
+/** The bare `[data-block-id="<escaped-id>"]` attribute selector (no surface scope). */
+export function blockIdAttr(id) {
+    return `[data-block-id="${cssEscapeId(id)}"]`;
+}
+/**
+ * The surface-root selector a scoped rule hangs off.
+ *
+ * With a `surfaceId` this is `[data-pw-surface="<id>"]` — scope carried by the
+ * attribute's VALUE, not merely its presence. That matters because the embed
+ * autoloader hydrates EVERY `[data-pw-surface]` element in a document, so a host
+ * page can hold several surfaces at once; a value-less selector makes each
+ * surface's rules apply to all of them, and the last one in document order wins.
+ *
+ * Without a `surfaceId` it degrades to the historical `[data-pw-surface]`, which
+ * is correct for rules whose content is identical for every surface (the base
+ * CSS) and for unit tests that render a single surface.
+ */
+export function surfaceScope(surfaceId) {
+    return surfaceId ? `[data-pw-surface="${cssEscapeId(surfaceId)}"]` : '[data-pw-surface]';
+}
+/**
+ * The scoped base selector a per-block rule attaches to:
+ * `[data-pw-surface="<sid>"] [data-block-id="<escaped-id>"]`. Scoped under the
+ * surface root so a rule can never leak to the host page — and, when the surface
+ * id is supplied, never to a SIBLING surface that happens to reuse a block id.
+ */
+export function blockSelector(id, surfaceId) {
+    return `${surfaceScope(surfaceId)} ${blockIdAttr(id)}`;
+}
+/**
+ * Walk a surface block tree (depth-first, children after their parent — the
+ * order all collectors used) and concatenate the per-block CSS produced by
+ * `perBlockFn(block)`. Blocks for which `perBlockFn` returns '' contribute zero
+ * bytes, so existing surfaces stay byte-identical.
+ */
+export function collectScopedCss(blocks, perBlockFn) {
+    let css = '';
+    const walk = (block) => {
+        css += perBlockFn(block);
+        if (block.children) {
+            for (const child of block.children)
+                walk(child);
+        }
+    };
+    for (const block of blocks)
+        walk(block);
+    return css;
+}
+/**
+ * Style keys HOISTED to the wrapper — kept here so the renderer and the
+ * responsive CSS generator see the SAME list.
+ *
+ * This list is a RULE: these keys apply to the outer wrapper, not the
+ * component root. For flat values the renderer hoists them; for responsive
+ * values the value leaves the inline style entirely and lands in CSS, so the
+ * same rule has to be expressed on the selector side — otherwise the rule
+ * matches both the wrapper and the root and the value is applied TWICE
+ * (`marginTop:'-40%'` would move content by both -335px and -256px).
+ */
+export const FLEX_HOIST_KEYS = ['flex', 'flexGrow', 'flexShrink', 'flexBasis'];
+export const LAYOUT_HOIST_KEYS = [
+    'margin',
+    'marginTop',
+    'marginRight',
+    'marginBottom',
+    'marginLeft',
+    'maxWidth',
+    'minWidth',
+    ...FLEX_HOIST_KEYS,
+];
+/** The attribute that tells the wrapper from the component root (the same marker states-css uses). */
+export const WRAPPER_ATTR = '[data-block-wrapper]';
+//# sourceMappingURL=scoped-css.js.map

package/dist/render/scoped-css.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scoped-css.js","sourceRoot":"","sources":["../../src/render/scoped-css.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAIH,4FAA4F;AAC5F,MAAM,UAAU,WAAW,CAAC,EAAU;IACpC,OAAO,EAAE,CAAC,OAAO,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAA;AACrC,CAAC;AAED,yFAAyF;AACzF,MAAM,UAAU,YAAY,CAAC,IAAY;IACvC,OAAO,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC,WAAW,EAAE,EAAE,CAAC,CAAA;AAC7D,CAAC;AAED,uFAAuF;AACvF,MAAM,UAAU,WAAW,CAAC,EAAU;IACpC,OAAO,mBAAmB,WAAW,CAAC,EAAE,CAAC,IAAI,CAAA;AAC/C,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,YAAY,CAAC,SAAkB;IAC7C,OAAO,SAAS,CAAC,CAAC,CAAC,qBAAqB,WAAW,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,mBAAmB,CAAA;AAC1F,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAAC,EAAU,EAAE,SAAkB;IAC1D,OAAO,GAAG,YAAY,CAAC,SAAS,CAAC,IAAI,WAAW,CAAC,EAAE,CAAC,EAAE,CAAA;AACxD,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAC9B,MAAwB,EACxB,UAAoC;IAEpC,IAAI,GAAG,GAAG,EAAE,CAAA;IACZ,MAAM,IAAI,GAAG,CAAC,KAAY,EAAQ,EAAE;QAClC,GAAG,IAAI,UAAU,CAAC,KAAK,CAAC,CAAA;QACxB,IAAI,KAAK,CAAC,QAAQ,EAAE,CAAC;YACnB,KAAK,MAAM,KAAK,IAAI,KAAK,CAAC,QAAQ;gBAAE,IAAI,CAAC,KAAK,CAAC,CAAA;QACjD,CAAC;IACH,CAAC,CAAA;IACD,KAAK,MAAM,KAAK,IAAI,MAAM;QAAE,IAAI,CAAC,KAAK,CAAC,CAAA;IACvC,OAAO,GAAG,CAAA;AACZ,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,MAAM,EAAE,UAAU,EAAE,YAAY,EAAE,WAAW,CAAU,CAAA;AAEvF,MAAM,CAAC,MAAM,iBAAiB,GAAG;IAC/B,QAAQ;IACR,WAAW;IACX,aAAa;IACb,cAAc;IACd,YAAY;IACZ,UAAU;IACV,UAAU;IACV,GAAG,eAAe;CACV,CAAA;AAEV,sGAAsG;AACtG,MAAM,CAAC,MAAM,YAAY,GAAG,sBAAsB,CAAA","sourcesContent":["/**\n * Shared helpers for the scoped per-block CSS collectors.\n *\n * The runtime emits several kinds of scoped `<style>` rules keyed by a block's\n * stable `data-block-id` (visibility / interaction-states / responsive-style /\n * conditional-states / group-states). They all share the SAME primitives:\n *\n *   - `cssEscapeId(id)`      — conservative attribute-value escaper for block ids.\n *   - `camelToKebab(prop)`   — CSS camelCase property name → kebab-case.\n *   - `blockSelector(id)`    — `[data-pw-surface] [data-block-id=\"<escaped>\"]`,\n *                              the scoped base selector every rule attaches to.\n *   - `collectScopedCss(blocks, perBlockFn)` — walk the block tree (including\n *                              children) and concatenate each block's CSS as\n *                              produced by `perBlockFn(block)`.\n *\n * Centralising these keeps the per-collector files focused on their own\n * selector/declaration semantics and guarantees byte-identical output across\n * the family (the same escaper, the same selector string, the same walk order).\n *\n * @module @pwfabric/runtime/render/scoped-css\n */\n\nimport type { Block } from '@pwfabric/core'\n\n/** Conservative CSS attribute-selector value escaper (block ids are slugs, but be safe). */\nexport function cssEscapeId(id: string): string {\n  return id.replace(/[\"\\\\]/g, '\\\\$&')\n}\n\n/** camelCase CSS property → kebab-case (e.g. `backgroundColor` → `background-color`). */\nexport function camelToKebab(prop: string): string {\n  return prop.replace(/[A-Z]/g, (m) => `-${m.toLowerCase()}`)\n}\n\n/** The bare `[data-block-id=\"<escaped-id>\"]` attribute selector (no surface scope). */\nexport function blockIdAttr(id: string): string {\n  return `[data-block-id=\"${cssEscapeId(id)}\"]`\n}\n\n/**\n * The surface-root selector a scoped rule hangs off.\n *\n * With a `surfaceId` this is `[data-pw-surface=\"<id>\"]` — scope carried by the\n * attribute's VALUE, not merely its presence. That matters because the embed\n * autoloader hydrates EVERY `[data-pw-surface]` element in a document, so a host\n * page can hold several surfaces at once; a value-less selector makes each\n * surface's rules apply to all of them, and the last one in document order wins.\n *\n * Without a `surfaceId` it degrades to the historical `[data-pw-surface]`, which\n * is correct for rules whose content is identical for every surface (the base\n * CSS) and for unit tests that render a single surface.\n */\nexport function surfaceScope(surfaceId?: string): string {\n  return surfaceId ? `[data-pw-surface=\"${cssEscapeId(surfaceId)}\"]` : '[data-pw-surface]'\n}\n\n/**\n * The scoped base selector a per-block rule attaches to:\n * `[data-pw-surface=\"<sid>\"] [data-block-id=\"<escaped-id>\"]`. Scoped under the\n * surface root so a rule can never leak to the host page — and, when the surface\n * id is supplied, never to a SIBLING surface that happens to reuse a block id.\n */\nexport function blockSelector(id: string, surfaceId?: string): string {\n  return `${surfaceScope(surfaceId)} ${blockIdAttr(id)}`\n}\n\n/**\n * Walk a surface block tree (depth-first, children after their parent — the\n * order all collectors used) and concatenate the per-block CSS produced by\n * `perBlockFn(block)`. Blocks for which `perBlockFn` returns '' contribute zero\n * bytes, so existing surfaces stay byte-identical.\n */\nexport function collectScopedCss(\n  blocks: readonly Block[],\n  perBlockFn: (block: Block) => string\n): string {\n  let css = ''\n  const walk = (block: Block): void => {\n    css += perBlockFn(block)\n    if (block.children) {\n      for (const child of block.children) walk(child)\n    }\n  }\n  for (const block of blocks) walk(block)\n  return css\n}\n\n/**\n * Style keys HOISTED to the wrapper — kept here so the renderer and the\n * responsive CSS generator see the SAME list.\n *\n * This list is a RULE: these keys apply to the outer wrapper, not the\n * component root. For flat values the renderer hoists them; for responsive\n * values the value leaves the inline style entirely and lands in CSS, so the\n * same rule has to be expressed on the selector side — otherwise the rule\n * matches both the wrapper and the root and the value is applied TWICE\n * (`marginTop:'-40%'` would move content by both -335px and -256px).\n */\nexport const FLEX_HOIST_KEYS = ['flex', 'flexGrow', 'flexShrink', 'flexBasis'] as const\n\nexport const LAYOUT_HOIST_KEYS = [\n  'margin',\n  'marginTop',\n  'marginRight',\n  'marginBottom',\n  'marginLeft',\n  'maxWidth',\n  'minWidth',\n  ...FLEX_HOIST_KEYS,\n] as const\n\n/** The attribute that tells the wrapper from the component root (the same marker states-css uses). */\nexport const WRAPPER_ATTR = '[data-block-wrapper]'\n"]}

package/dist/render/shell-selection.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Shell selection — the state a SPLIT shell runs on.
+ *
+ * WHY THIS IS IN THE RUNTIME AND NOT IN THE BLOCK. A split surface (list on the
+ * left, detail on the right) has exactly one piece of state: which item is
+ * selected. Kept inside the block it is invisible to everything else — the URL
+ * does not move, so the page cannot be linked to, the browser Back button does
+ * nothing, and a second block on the same surface (a header showing the
+ * selected record's title, a toolbar acting on it) has no way to read it.
+ *
+ * So selection is a SURFACE-level fact with a URL projection:
+ *
+ *   ?<key>=<itemId>
+ *
+ * and this module is the single place that reads and writes it.
+ *
+ * THE URL IS THE SOURCE OF TRUTH when syncing is on. React state mirrors it
+ * rather than the other way round, which is what makes a pasted link, a Back
+ * press and a click on the list all land in the same place — three paths, one
+ * rule.
+ *
+ * INERT HOSTS DO NOT NAVIGATE. An editor or preview canvas renders the same
+ * block with `interactionMode: 'inert'`; there the selection stays in memory and
+ * the host's own URL is never touched. That mirrors the existing rule for blocks
+ * that navigate or write data.
+ */
+import * as React from 'react';
+type Listener = () => void;
+export interface ShellSelectionStore {
+    /** Current selection for a key, or undefined when nothing is selected. */
+    get(key: string): string | undefined;
+    /** Select an item. Writes the URL when this store syncs. */
+    set(key: string, id: string | undefined): void;
+    subscribe(listener: Listener): () => void;
+    readonly syncUrl: boolean;
+}
+/**
+ * Create a selection store.
+ *
+ * `syncUrl: false` gives an in-memory store with identical semantics — the same
+ * hook, the same cross-block sharing, no address-bar side effects.
+ */
+export declare function createShellSelectionStore(syncUrl: boolean): ShellSelectionStore;
+export declare const ShellSelectionContext: React.Context<ShellSelectionStore | null>;
+export interface ShellSelectionProviderProps {
+    /** Off for editor/preview canvases — selection works, the address bar does not move. */
+    readonly syncUrl?: boolean;
+    readonly children: React.ReactNode;
+}
+export declare function ShellSelectionProvider({ syncUrl, children, }: ShellSelectionProviderProps): React.ReactElement;
+export interface ShellSelectionOptions {
+    /** Selected when the URL carries nothing — normally the first list item. */
+    readonly fallback?: string | undefined;
+    /**
+     * Override the provider. A block rendered inert must not move the host's URL
+     * even when the surrounding surface is live.
+     */
+    readonly syncUrl?: boolean;
+}
+/**
+ * Read and write the shell selection for `key`.
+ *
+ * Works with OR without a provider: with no `ShellSelectionProvider` above it,
+ * the hook makes its own store, so a block dropped into a bare React tree keeps
+ * behaving instead of throwing. The provider only widens the scope — one store
+ * per surface means two blocks reading the same key see the same value.
+ */
+export declare function useShellSelection(key: string, options?: ShellSelectionOptions): readonly [string | undefined, (id: string | undefined) => void];
+export {};