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

package/dist/render/types.d.ts

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

package/dist/render/types.js

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

package/dist/render/types.js.map

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

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

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

package/dist/render/visibility-css.js

@@ -0,0 +1,119 @@
+/**
+ * Per-breakpoint visibility CSS generation (the `hidden md:flex` equivalent).
+ *
+ * `block.layout.hideOn` / `block.layout.showOn` declare at which breakpoints a
+ * block is hidden / the only breakpoints where it is visible. Inline styles
+ * can't express media queries, so the runtime emits scoped CSS rules — keyed
+ * by the block's `data-block-id` — into the surface's generated `<style>`
+ * (alongside the box-sizing reset). The pixel thresholds are the SAME
+ * `BREAKPOINTS[].minWidth` values the span system uses.
+ *
+ * Semantics:
+ *   - `hideOn: ['xs','sm']` → hidden across the xs+sm ranges → hidden below the
+ *     md threshold (768px) → `@media (max-width:767.98px){ display:none }`.
+ *   - `showOn: ['lg','xl']` → visible ONLY in the lg+xl ranges → hidden below
+ *     lg (1024px) AND at/above the breakpoint after xl (2xl = 1536px).
+ *   - `showOn` is the inverse of `hideOn`; when both are present `showOn` wins.
+ *
+ * @module @pwfabric/runtime/render/visibility-css
+ */
+import { BREAKPOINTS, BREAKPOINT_ORDER } from '@pwfabric/core';
+import { blockSelector, collectScopedCss } from './scoped-css.js';
+/** Sub-pixel epsilon so `max-width` ranges don't overlap the next `min-width`. */
+const MAX_EPSILON = 0.02;
+/** `[minWidth, maxExclusive)` pixel range a named breakpoint covers. */
+function rangeFor(bp) {
+    const idx = BREAKPOINTS.findIndex((b) => b.name === bp);
+    const def = BREAKPOINTS[idx];
+    const next = BREAKPOINTS[idx + 1];
+    return {
+        min: def?.minWidth ?? 0,
+        maxExclusive: next?.minWidth ?? Number.POSITIVE_INFINITY,
+    };
+}
+/**
+ * Resolve the SET of breakpoints at which a block must be hidden, given its
+ * `hideOn` / `showOn` declarations. `showOn` takes precedence (the block is
+ * hidden at every breakpoint NOT listed in `showOn`).
+ */
+export function resolveHiddenBreakpoints(hideOn, showOn) {
+    if (showOn && showOn.length > 0) {
+        const visible = new Set(showOn);
+        return BREAKPOINT_ORDER.filter((bp) => !visible.has(bp));
+    }
+    if (hideOn && hideOn.length > 0) {
+        const hide = new Set(hideOn);
+        return BREAKPOINT_ORDER.filter((bp) => hide.has(bp));
+    }
+    return [];
+}
+/**
+ * Collapse a set of hidden breakpoints into the minimal set of
+ * `[min, maxExclusive)` pixel ranges (contiguous breakpoints merge).
+ */
+function collapseRanges(hidden) {
+    // Order by the canonical breakpoint order so contiguity is by ascending width.
+    const ordered = BREAKPOINT_ORDER.filter((bp) => hidden.includes(bp));
+    const out = [];
+    for (const bp of ordered) {
+        const r = rangeFor(bp);
+        const last = out[out.length - 1];
+        if (last && last.maxExclusive === r.min) {
+            last.maxExclusive = r.maxExclusive; // contiguous → extend
+        }
+        else {
+            out.push({ ...r });
+        }
+    }
+    return out;
+}
+/** Build a single `@media` condition for a `[min, maxExclusive)` range. */
+function mediaCondition(min, maxExclusive) {
+    const parts = [];
+    if (min > 0)
+        parts.push(`(min-width:${min}px)`);
+    if (Number.isFinite(maxExclusive))
+        parts.push(`(max-width:${maxExclusive - MAX_EPSILON}px)`);
+    return parts.join(' and ');
+}
+/**
+ * Emit the CSS rule(s) that hide a single block at the resolved breakpoints.
+ * Targets `[data-block-id="<id>"]` scoped under the surface root so it cannot
+ * leak to the host page. Uses `!important` so the rule beats the inline layout
+ * style (`display:grid`/flex on the wrapper) it must override.
+ *
+ * Returns '' when there is nothing to hide.
+ */
+export function blockVisibilityCss(blockId, hidden, surfaceId) {
+    if (hidden.length === 0)
+        return '';
+    const ranges = collapseRanges(hidden);
+    // The whole spectrum is hidden (no showOn match anywhere): unconditional hide.
+    const everything = ranges.length === 1 && ranges[0].min === 0 && !Number.isFinite(ranges[0].maxExclusive);
+    const selector = blockSelector(blockId, surfaceId);
+    if (everything) {
+        return `${selector}{display:none !important}`;
+    }
+    return ranges
+        .map((r) => {
+        const cond = mediaCondition(r.min, r.maxExclusive);
+        return `@media ${cond}{${selector}{display:none !important}}`;
+    })
+        .join('');
+}
+/**
+ * Walk a surface block tree and concatenate the per-block visibility CSS for
+ * every block declaring `hideOn` / `showOn`. Blocks without either are skipped
+ * (zero bytes emitted) so existing surfaces are byte-identical.
+ */
+export function collectVisibilityCss(blocks, surfaceId) {
+    return collectScopedCss(blocks, (block) => {
+        const layout = block.layout;
+        if (layout && (layout.hideOn?.length || layout.showOn?.length)) {
+            const hidden = resolveHiddenBreakpoints(layout.hideOn, layout.showOn);
+            return blockVisibilityCss(block.id, hidden, surfaceId);
+        }
+        return '';
+    });
+}
+//# sourceMappingURL=visibility-css.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"visibility-css.js","sourceRoot":"","sources":["../../src/render/visibility-css.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAGH,OAAO,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAA;AAE9D,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAA;AAEjE,kFAAkF;AAClF,MAAM,WAAW,GAAG,IAAI,CAAA;AAExB,wEAAwE;AACxE,SAAS,QAAQ,CAAC,EAAkB;IAClC,MAAM,GAAG,GAAG,WAAW,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,EAAE,CAAC,CAAA;IACvD,MAAM,GAAG,GAAG,WAAW,CAAC,GAAG,CAAC,CAAA;IAC5B,MAAM,IAAI,GAAG,WAAW,CAAC,GAAG,GAAG,CAAC,CAAC,CAAA;IACjC,OAAO;QACL,GAAG,EAAE,GAAG,EAAE,QAAQ,IAAI,CAAC;QACvB,YAAY,EAAE,IAAI,EAAE,QAAQ,IAAI,MAAM,CAAC,iBAAiB;KACzD,CAAA;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,wBAAwB,CACtC,MAA6C,EAC7C,MAA6C;IAE7C,IAAI,MAAM,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAChC,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,CAAA;QAC/B,OAAO,gBAAgB,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAA;IAC1D,CAAC;IACD,IAAI,MAAM,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAChC,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,CAAA;QAC5B,OAAO,gBAAgB,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAA;IACtD,CAAC;IACD,OAAO,EAAE,CAAA;AACX,CAAC;AAED;;;GAGG;AACH,SAAS,cAAc,CAAC,MAAwB;IAC9C,+EAA+E;IAC/E,MAAM,OAAO,GAAG,gBAAgB,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,CAAA;IACpE,MAAM,GAAG,GAA4C,EAAE,CAAA;IACvD,KAAK,MAAM,EAAE,IAAI,OAAO,EAAE,CAAC;QACzB,MAAM,CAAC,GAAG,QAAQ,CAAC,EAAE,CAAC,CAAA;QACtB,MAAM,IAAI,GAAG,GAAG,CAAC,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC,CAAA;QAChC,IAAI,IAAI,IAAI,IAAI,CAAC,YAAY,KAAK,CAAC,CAAC,GAAG,EAAE,CAAC;YACxC,IAAI,CAAC,YAAY,GAAG,CAAC,CAAC,YAAY,CAAA,CAAC,sBAAsB;QAC3D,CAAC;aAAM,CAAC;YACN,GAAG,CAAC,IAAI,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC,CAAA;QACpB,CAAC;IACH,CAAC;IACD,OAAO,GAAG,CAAA;AACZ,CAAC;AAED,2EAA2E;AAC3E,SAAS,cAAc,CAAC,GAAW,EAAE,YAAoB;IACvD,MAAM,KAAK,GAAa,EAAE,CAAA;IAC1B,IAAI,GAAG,GAAG,CAAC;QAAE,KAAK,CAAC,IAAI,CAAC,cAAc,GAAG,KAAK,CAAC,CAAA;IAC/C,IAAI,MAAM,CAAC,QAAQ,CAAC,YAAY,CAAC;QAAE,KAAK,CAAC,IAAI,CAAC,cAAc,YAAY,GAAG,WAAW,KAAK,CAAC,CAAA;IAC5F,OAAO,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAA;AAC5B,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,kBAAkB,CAChC,OAAe,EACf,MAAwB,EACxB,SAAkB;IAElB,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAA;IAClC,MAAM,MAAM,GAAG,cAAc,CAAC,MAAM,CAAC,CAAA;IACrC,+EAA+E;IAC/E,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,KAAK,CAAC,IAAI,MAAM,CAAC,CAAC,CAAE,CAAC,GAAG,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAE,CAAC,YAAY,CAAC,CAAA;IAC3G,MAAM,QAAQ,GAAG,aAAa,CAAC,OAAO,EAAE,SAAS,CAAC,CAAA;IAClD,IAAI,UAAU,EAAE,CAAC;QACf,OAAO,GAAG,QAAQ,2BAA2B,CAAA;IAC/C,CAAC;IACD,OAAO,MAAM;SACV,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;QACT,MAAM,IAAI,GAAG,cAAc,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,YAAY,CAAC,CAAA;QAClD,OAAO,UAAU,IAAI,IAAI,QAAQ,4BAA4B,CAAA;IAC/D,CAAC,CAAC;SACD,IAAI,CAAC,EAAE,CAAC,CAAA;AACb,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,oBAAoB,CAAC,MAAwB,EAAE,SAAkB;IAC/E,OAAO,gBAAgB,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,EAAE;QACxC,MAAM,MAAM,GAAG,KAAK,CAAC,MAER,CAAA;QACb,IAAI,MAAM,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,CAAC;YAC/D,MAAM,MAAM,GAAG,wBAAwB,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,CAAA;YACrE,OAAO,kBAAkB,CAAC,KAAK,CAAC,EAAE,EAAE,MAAM,EAAE,SAAS,CAAC,CAAA;QACxD,CAAC;QACD,OAAO,EAAE,CAAA;IACX,CAAC,CAAC,CAAA;AACJ,CAAC","sourcesContent":["/**\n * Per-breakpoint visibility CSS generation (the `hidden md:flex` equivalent).\n *\n * `block.layout.hideOn` / `block.layout.showOn` declare at which breakpoints a\n * block is hidden / the only breakpoints where it is visible. Inline styles\n * can't express media queries, so the runtime emits scoped CSS rules — keyed\n * by the block's `data-block-id` — into the surface's generated `<style>`\n * (alongside the box-sizing reset). The pixel thresholds are the SAME\n * `BREAKPOINTS[].minWidth` values the span system uses.\n *\n * Semantics:\n *   - `hideOn: ['xs','sm']` → hidden across the xs+sm ranges → hidden below the\n *     md threshold (768px) → `@media (max-width:767.98px){ display:none }`.\n *   - `showOn: ['lg','xl']` → visible ONLY in the lg+xl ranges → hidden below\n *     lg (1024px) AND at/above the breakpoint after xl (2xl = 1536px).\n *   - `showOn` is the inverse of `hideOn`; when both are present `showOn` wins.\n *\n * @module @pwfabric/runtime/render/visibility-css\n */\n\nimport type { Block } from '@pwfabric/core'\nimport { BREAKPOINTS, BREAKPOINT_ORDER } from '@pwfabric/core'\nimport type { BreakpointName } from '@pwfabric/core'\nimport { blockSelector, collectScopedCss } from './scoped-css.js'\n\n/** Sub-pixel epsilon so `max-width` ranges don't overlap the next `min-width`. */\nconst MAX_EPSILON = 0.02\n\n/** `[minWidth, maxExclusive)` pixel range a named breakpoint covers. */\nfunction rangeFor(bp: BreakpointName): { min: number; maxExclusive: number } {\n  const idx = BREAKPOINTS.findIndex((b) => b.name === bp)\n  const def = BREAKPOINTS[idx]\n  const next = BREAKPOINTS[idx + 1]\n  return {\n    min: def?.minWidth ?? 0,\n    maxExclusive: next?.minWidth ?? Number.POSITIVE_INFINITY,\n  }\n}\n\n/**\n * Resolve the SET of breakpoints at which a block must be hidden, given its\n * `hideOn` / `showOn` declarations. `showOn` takes precedence (the block is\n * hidden at every breakpoint NOT listed in `showOn`).\n */\nexport function resolveHiddenBreakpoints(\n  hideOn: readonly BreakpointName[] | undefined,\n  showOn: readonly BreakpointName[] | undefined\n): BreakpointName[] {\n  if (showOn && showOn.length > 0) {\n    const visible = new Set(showOn)\n    return BREAKPOINT_ORDER.filter((bp) => !visible.has(bp))\n  }\n  if (hideOn && hideOn.length > 0) {\n    const hide = new Set(hideOn)\n    return BREAKPOINT_ORDER.filter((bp) => hide.has(bp))\n  }\n  return []\n}\n\n/**\n * Collapse a set of hidden breakpoints into the minimal set of\n * `[min, maxExclusive)` pixel ranges (contiguous breakpoints merge).\n */\nfunction collapseRanges(hidden: BreakpointName[]): { min: number; maxExclusive: number }[] {\n  // Order by the canonical breakpoint order so contiguity is by ascending width.\n  const ordered = BREAKPOINT_ORDER.filter((bp) => hidden.includes(bp))\n  const out: { min: number; maxExclusive: number }[] = []\n  for (const bp of ordered) {\n    const r = rangeFor(bp)\n    const last = out[out.length - 1]\n    if (last && last.maxExclusive === r.min) {\n      last.maxExclusive = r.maxExclusive // contiguous → extend\n    } else {\n      out.push({ ...r })\n    }\n  }\n  return out\n}\n\n/** Build a single `@media` condition for a `[min, maxExclusive)` range. */\nfunction mediaCondition(min: number, maxExclusive: number): string {\n  const parts: string[] = []\n  if (min > 0) parts.push(`(min-width:${min}px)`)\n  if (Number.isFinite(maxExclusive)) parts.push(`(max-width:${maxExclusive - MAX_EPSILON}px)`)\n  return parts.join(' and ')\n}\n\n/**\n * Emit the CSS rule(s) that hide a single block at the resolved breakpoints.\n * Targets `[data-block-id=\"<id>\"]` scoped under the surface root so it cannot\n * leak to the host page. Uses `!important` so the rule beats the inline layout\n * style (`display:grid`/flex on the wrapper) it must override.\n *\n * Returns '' when there is nothing to hide.\n */\nexport function blockVisibilityCss(\n  blockId: string,\n  hidden: BreakpointName[],\n  surfaceId?: string\n): string {\n  if (hidden.length === 0) return ''\n  const ranges = collapseRanges(hidden)\n  // The whole spectrum is hidden (no showOn match anywhere): unconditional hide.\n  const everything = ranges.length === 1 && ranges[0]!.min === 0 && !Number.isFinite(ranges[0]!.maxExclusive)\n  const selector = blockSelector(blockId, surfaceId)\n  if (everything) {\n    return `${selector}{display:none !important}`\n  }\n  return ranges\n    .map((r) => {\n      const cond = mediaCondition(r.min, r.maxExclusive)\n      return `@media ${cond}{${selector}{display:none !important}}`\n    })\n    .join('')\n}\n\n/**\n * Walk a surface block tree and concatenate the per-block visibility CSS for\n * every block declaring `hideOn` / `showOn`. Blocks without either are skipped\n * (zero bytes emitted) so existing surfaces are byte-identical.\n */\nexport function collectVisibilityCss(blocks: readonly Block[], surfaceId?: string): string {\n  return collectScopedCss(blocks, (block) => {\n    const layout = block.layout as\n      | { hideOn?: readonly BreakpointName[]; showOn?: readonly BreakpointName[] }\n      | undefined\n    if (layout && (layout.hideOn?.length || layout.showOn?.length)) {\n      const hidden = resolveHiddenBreakpoints(layout.hideOn, layout.showOn)\n      return blockVisibilityCss(block.id, hidden, surfaceId)\n    }\n    return ''\n  })\n}\n"]}

package/dist/render/width-scope.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Width scope — splits blocks into groups while KEEPING SOURCE ORDER.
+ *
+ * WHY. If the surface 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 (on a 1536px screen
+ * a persistent rail would start 218px in from the edge). The rule: persistent
+ * navigation chrome belongs to the viewport, the content body to the measure.
+ *
+ * WHY GROUPS, NOT BUCKETS. A surface runs `[navbar][body…][bottombar]`.
+ * Collecting `viewport`-scoped blocks into one bucket and `container` ones
+ * into another would break the order and put the bottom bar next to the top
+ * bar. Consecutive grouping keeps the order: three groups, three DOM siblings.
+ *
+ * WHY NOT 100vw. The `width:100vw; margin-inline:calc(50% - 50vw)` trick is
+ * the short way out of a centred container and is NOT used: `100vw` counts
+ * the scrollbar too, so every page with a vertical scrollbar would get ~15px
+ * of horizontal overflow — the very defect this module exists to avoid.
+ *
+ * @module @pwfabric/runtime/render/width-scope
+ */
+import { type Block, type BreakpointName } from '@pwfabric/core';
+import type { WidthScope } from '@pwfabric/contracts';
+export interface WidthScopeChunk {
+    readonly scope: WidthScope;
+    readonly blocks: readonly Block[];
+}
+/**
+ * A block's scope at this breakpoint. Without a declaration it is
+ * `container`, so a block that declares nothing keeps the default behaviour.
+ */
+export declare function resolveWidthScope(block: Block, viewport: BreakpointName): WidthScope;
+/** Groups consecutive blocks of the same scope together; order is kept. */
+export declare function chunkByWidthScope(blocks: readonly Block[], viewport: BreakpointName): readonly WidthScopeChunk[];

package/dist/render/width-scope.js

@@ -0,0 +1,44 @@
+/**
+ * Width scope — splits blocks into groups while KEEPING SOURCE ORDER.
+ *
+ * WHY. If the surface 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 (on a 1536px screen
+ * a persistent rail would start 218px in from the edge). The rule: persistent
+ * navigation chrome belongs to the viewport, the content body to the measure.
+ *
+ * WHY GROUPS, NOT BUCKETS. A surface runs `[navbar][body…][bottombar]`.
+ * Collecting `viewport`-scoped blocks into one bucket and `container` ones
+ * into another would break the order and put the bottom bar next to the top
+ * bar. Consecutive grouping keeps the order: three groups, three DOM siblings.
+ *
+ * WHY NOT 100vw. The `width:100vw; margin-inline:calc(50% - 50vw)` trick is
+ * the short way out of a centred container and is NOT used: `100vw` counts
+ * the scrollbar too, so every page with a vertical scrollbar would get ~15px
+ * of horizontal overflow — the very defect this module exists to avoid.
+ *
+ * @module @pwfabric/runtime/render/width-scope
+ */
+import { DEFAULT_BLOCK_LAYOUT, resolveResponsiveValue, } from '@pwfabric/core';
+/**
+ * A block's scope at this breakpoint. Without a declaration it is
+ * `container`, so a block that declares nothing keeps the default behaviour.
+ */
+export function resolveWidthScope(block, viewport) {
+    const layout = block.layout ?? DEFAULT_BLOCK_LAYOUT;
+    return resolveResponsiveValue(layout.widthScope, viewport) ?? 'container';
+}
+/** Groups consecutive blocks of the same scope together; order is kept. */
+export function chunkByWidthScope(blocks, viewport) {
+    const chunks = [];
+    for (const block of blocks) {
+        const scope = resolveWidthScope(block, viewport);
+        const last = chunks[chunks.length - 1];
+        if (last && last.scope === scope)
+            last.blocks.push(block);
+        else
+            chunks.push({ scope, blocks: [block] });
+    }
+    return chunks;
+}
+//# sourceMappingURL=width-scope.js.map

package/dist/render/width-scope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"width-scope.js","sourceRoot":"","sources":["../../src/render/width-scope.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,EACL,oBAAoB,EACpB,sBAAsB,GAGvB,MAAM,gBAAgB,CAAA;AAWvB;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAAY,EAAE,QAAwB;IACtE,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,IAAI,oBAAoB,CAAA;IACnD,OAAO,sBAAsB,CAAC,MAAM,CAAC,UAAU,EAAE,QAAQ,CAAC,IAAI,WAAW,CAAA;AAC3E,CAAC;AAED,2EAA2E;AAC3E,MAAM,UAAU,iBAAiB,CAC/B,MAAwB,EACxB,QAAwB;IAExB,MAAM,MAAM,GAA6C,EAAE,CAAA;IAC3D,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,MAAM,KAAK,GAAG,iBAAiB,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAA;QAChD,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAA;QACtC,IAAI,IAAI,IAAI,IAAI,CAAC,KAAK,KAAK,KAAK;YAAE,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;;YACpD,MAAM,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC,CAAA;IAC9C,CAAC;IACD,OAAO,MAAM,CAAA;AACf,CAAC","sourcesContent":["/**\n * Width scope — splits blocks into groups while KEEPING SOURCE ORDER.\n *\n * WHY. If the surface 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 (on a 1536px screen\n * a persistent rail would start 218px in from the edge). The rule: persistent\n * navigation chrome belongs to the viewport, the content body to the measure.\n *\n * WHY GROUPS, NOT BUCKETS. A surface runs `[navbar][body…][bottombar]`.\n * Collecting `viewport`-scoped blocks into one bucket and `container` ones\n * into another would break the order and put the bottom bar next to the top\n * bar. Consecutive grouping keeps the order: three groups, three DOM siblings.\n *\n * WHY NOT 100vw. The `width:100vw; margin-inline:calc(50% - 50vw)` trick is\n * the short way out of a centred container and is NOT used: `100vw` counts\n * the scrollbar too, so every page with a vertical scrollbar would get ~15px\n * of horizontal overflow — the very defect this module exists to avoid.\n *\n * @module @pwfabric/runtime/render/width-scope\n */\nimport {\n  DEFAULT_BLOCK_LAYOUT,\n  resolveResponsiveValue,\n  type Block,\n  type BreakpointName,\n} from '@pwfabric/core'\n// `WidthScope` comes from CONTRACTS, not from core's parallel copy:\n// `block.layout` is typed by contracts, and the two definitions are kept in\n// sync by hand, so the contracts type is the one to follow.\nimport type { WidthScope } from '@pwfabric/contracts'\n\nexport interface WidthScopeChunk {\n  readonly scope: WidthScope\n  readonly blocks: readonly Block[]\n}\n\n/**\n * A block's scope at this breakpoint. Without a declaration it is\n * `container`, so a block that declares nothing keeps the default behaviour.\n */\nexport function resolveWidthScope(block: Block, viewport: BreakpointName): WidthScope {\n  const layout = block.layout ?? DEFAULT_BLOCK_LAYOUT\n  return resolveResponsiveValue(layout.widthScope, viewport) ?? 'container'\n}\n\n/** Groups consecutive blocks of the same scope together; order is kept. */\nexport function chunkByWidthScope(\n  blocks: readonly Block[],\n  viewport: BreakpointName\n): readonly WidthScopeChunk[] {\n  const chunks: { scope: WidthScope; blocks: Block[] }[] = []\n  for (const block of blocks) {\n    const scope = resolveWidthScope(block, viewport)\n    const last = chunks[chunks.length - 1]\n    if (last && last.scope === scope) last.blocks.push(block)\n    else chunks.push({ scope, blocks: [block] })\n  }\n  return chunks\n}\n"]}

package/dist/render/write-only-sources.d.ts

@@ -0,0 +1,33 @@
+/**
+ * WRITE-ONLY SOURCES — a form's target that nothing on the page reads.
+ *
+ * A data source a form writes to (`platform/entities` `config.formBindings[].sourceId`)
+ * was also fetched as a list on mount and again after every submit (the
+ * bridge's `refreshAll`). For an intake-only model — anonymous visitors may
+ * create, never list — that is a refused request on every visit and every
+ * submit (`GET /_host/records/<model>` → 403
+ * `RECORDS_NOT_PUBLIC`, `__errors.records` set, no block bound to it).
+ *
+ * A source is write-only when:
+ *  - at least one form binding targets it, and every binding that does writes
+ *    with POST (a PATCH/PUT needs the loaded record to know what to update), and
+ *  - its id is referenced NOWHERE else: no block (props, expressions, actions,
+ *    repeat), no behavior, no other source, no other capability config.
+ *
+ * The reference check is a whole-word search of every string, which errs on
+ * the side of fetching: a stray word equal to the id keeps today's behaviour.
+ * A write-only source stays declared and registered — it is still the write
+ * target — it is just never asked for its rows.
+ *
+ * @module @pwfabric/runtime/render/write-only-sources
+ */
+export interface WriteOnlySourceInput {
+    readonly blocks: readonly unknown[];
+    readonly dataSources: readonly {
+        readonly id: string;
+    }[];
+    readonly capabilities?: readonly unknown[] | undefined;
+    readonly behaviors?: readonly unknown[] | undefined;
+}
+/** The ids of the declared sources that are only ever written to. */
+export declare function writeOnlySourceIds(input: WriteOnlySourceInput): ReadonlySet<string>;