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

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

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

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

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

package/dist/render/data-cache.js

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"data-cache.js","sourceRoot":"","sources":["../../src/render/data-cache.ts"],"names":[],"mappings":"AAaA,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAA;AACpD,OAAO,EAAE,wBAAwB,EAAE,eAAe,EAAE,MAAM,eAAe,CAAA;AASzE;;;;;;;;;GASG;AACH,MAAM,UAAU,kBAAkB,CAChC,MAAmC,EACnC,KAAwC;IAExC,IAAI,MAAM,CAAC,IAAI,KAAK,OAAO,IAAI,MAAM,CAAC,IAAI,KAAK,QAAQ;QAAE,OAAO,SAAS,CAAA;IACzE,yEAAyE;IACzE,IAAI,MAAM,CAAC,IAAI,KAAK,MAAM,IAAI,MAAM,CAAC,QAAQ,KAAK,SAAS,IAAI,wBAAwB,CAAC,MAAM,CAAC,QAAQ,EAAE,KAAK,CAAC,EAAE,CAAC;QAChH,OAAO,SAAS,CAAA;IAClB,CAAC;IACD,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,iBAAiB,CAAC,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAA;IAC1E,MAAM,SAAS,GAAG,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,iBAAiB,CAAC,MAAM,CAAC,SAAS,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAA;IACtF,OAAO,IAAI,CAAC,SAAS,CAAC;QACpB,MAAM,CAAC,IAAI;QACX,MAAM,CAAC,EAAE;QACT,kEAAkE;QAClE,sEAAsE;QACtE,6CAA6C;QAC7C,MAAM,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,eAAe,CAAC,MAAM,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI;QAC9E,MAAM,CAAC,MAAM,IAAI,IAAI;QACrB,MAAM,CAAC,UAAU,IAAI,IAAI;QACzB,MAAM,CAAC,SAAS,IAAI,IAAI;QACxB,MAAM,CAAC,OAAO,IAAI,IAAI;QACtB,KAAK;QACL,SAAS;KACV,CAAC,CAAA;AACJ,CAAC","sourcesContent":["/**\n * A host-provided cache for fetched source data — stale-while-revalidate.\n *\n * A page the visitor has already seen should not come back empty while its\n * sources are re-fetched. The renderer knows nothing about where the cache\n * lives (the published-app runner keeps it in sessionStorage, a host may keep\n * it in memory); it only asks for a value by key on the first frame and\n * writes the fresh result back after a successful fetch. A failed fetch never\n * writes, so a good entry is not replaced by nothing.\n *\n * @module @pwfabric/runtime/render/data-cache\n */\nimport type { SurfaceDataSourceDefinition } from './data-binding-types.js'\nimport { resolveQueryState } from './query-state.js'\nimport { endpointMissingPathValue, resolveEndpoint } from './endpoint.js'\n\nexport interface SurfaceDataCache {\n  /** The last successful result for this key, or undefined. */\n  get(key: string): unknown\n  /** Remember a successful result. Must not throw on a full store. */\n  set(key: string, value: unknown): void\n}\n\n/**\n * The key a source's fetched data is remembered under.\n *\n * Built from everything that decides WHAT is fetched — kind, id, resolved address,\n * entity type, connector, and the query with its `{{state.*}}` placeholders\n * resolved against the current state — so page 2 never answers as page 1.\n * The `fallback` payload is left out: sample rows are not part of what was\n * fetched. `state` and `static` sources are never fetched, so they have no\n * key.\n */\nexport function dataSourceCacheKey(\n  source: SurfaceDataSourceDefinition,\n  state: Readonly<Record<string, unknown>>\n): string | undefined {\n  if (source.kind === 'state' || source.kind === 'static') return undefined\n  // An idle source (a required path value is empty) is not fetched either.\n  if (source.kind === 'rest' && source.endpoint !== undefined && endpointMissingPathValue(source.endpoint, state)) {\n    return undefined\n  }\n  const query = source.query ? resolveQueryState(source.query, state) : null\n  const aggregate = source.aggregate ? resolveQueryState(source.aggregate, state) : null\n  return JSON.stringify([\n    source.kind,\n    source.id,\n    // The RESOLVED address, not the template: with the template every\n    // `/products/{{state.id}}` shared one key, and `?id=13` opened on the\n    // rows cached for 12 until the fetch landed.\n    source.endpoint !== undefined ? resolveEndpoint(source.endpoint, state) : null,\n    source.method ?? null,\n    source.entityType ?? null,\n    source.connector ?? null,\n    source.returns ?? null,\n    query,\n    aggregate,\n  ])\n}\n"]}

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

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

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

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"derive-dark-theme.js","sourceRoot":"","sources":["../../src/render/derive-dark-theme.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAA","sourcesContent":["/**\n * Derive a dark theme variant from a light SurfaceTheme.\n *\n * A colour palette is a preset the end user edits — not a reason to ship a\n * separate appearance atom. The dark variant is DERIVED from the light palette\n * rather than authored twice.\n *\n * The implementation lives in `@pwfabric/contracts`\n * (`fabric/appearance-cascade`), because the derivation can run at WRITE\n * time: an authoring tool may bake the result into\n * `appearance.config.darkTheme` so the author can see and edit the dark palette\n * instead of it being invisible render-time magic. Render still derives as the\n * fallback for surfaces that carry no baked variant.\n *\n * @module @pwfabric/runtime/render/derive-dark-theme\n */\n\nexport { deriveDarkTheme } from '@pwfabric/contracts'\n"]}

package/dist/render/dynamic-artifact-context.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Dynamic Artifact Context Provider
+ *
+ * Provides dynamic block and starter descriptor maps
+ * to the component tree. Populated from the host's render grants.
+ *
+ * @module @pwfabric/runtime/render/dynamic-artifact-context
+ */
+import { type ReactNode } from 'react';
+import type { DynamicBlockDescriptor, DynamicStarterDescriptor } from '@pwfabric/contracts';
+export interface DynamicArtifactContextValue {
+    readonly dynamicBlocks: ReadonlyMap<string, DynamicBlockDescriptor>;
+    readonly dynamicStarters: ReadonlyMap<string, DynamicStarterDescriptor>;
+    readonly isLoaded: boolean;
+}
+export interface DynamicArtifactProviderProps {
+    readonly dynamicBlocks?: readonly DynamicBlockDescriptor[];
+    readonly dynamicStarters?: readonly DynamicStarterDescriptor[];
+    /**
+     * Whether the dynamic descriptors have finished loading. Server-rendered
+     * consumers (a published page) pass fully-resolved descriptors
+     * synchronously and omit this — it defaults to `true`. Client-side editors
+     * load descriptors from the host's aggregate after mount, so they pass the
+     * live loading state; consumers can then tell "still loading" apart from
+     * "genuinely no descriptor" instead of flashing every block as unknown on
+     * first paint.
+     */
+    readonly isLoaded?: boolean;
+    /**
+     * WARM THE WHOLE CATALOG ON MOUNT. Off by default, and that default is the
+     * point.
+     *
+     * This provider typically sits in the host app's root layout, so it is
+     * mounted on every route. Preloading from there downloads, hash-verifies and
+     * blob-imports every descriptor the host owns on pages that render none of
+     * them — dozens of bundles and tens of seconds of summed download on a page
+     * with no renderer at all.
+     *
+     * Rendering a block does not need this: `DynamicBlockWrapper` asks the
+     * loader for the descriptor it is about to draw, and the loader caches and
+     * de-dupes by block type. Turn it on only where a canvas is genuinely about
+     * to render arbitrary blocks and the round trip should already be in flight
+     * — a studio or an editor, never a layout.
+     */
+    readonly preload?: boolean;
+    readonly children: ReactNode;
+}
+/**
+ * Warm the loader's cache for a whole catalog, fire-and-forget.
+ *
+ * The imperative half of the same opt-in: a canvas that knows it is about to
+ * render arbitrary blocks can start the downloads itself, without the provider
+ * having to guess from the fact that it was mounted. Caching and de-duplication
+ * stay entirely the loader's business — calling this twice costs one download.
+ */
+export declare function preloadDynamicBlocks(descriptors: readonly DynamicBlockDescriptor[] | undefined | null): void;
+/**
+ * Provides dynamic block and starter descriptors to the component tree.
+ *
+ * Downloads nothing by itself: blocks load lazily as they are rendered. Pass
+ * `preload` to warm the whole catalog on mount.
+ */
+export declare function DynamicArtifactProvider({ dynamicBlocks, dynamicStarters, isLoaded, preload, children, }: DynamicArtifactProviderProps): ReactNode;
+/**
+ * Access dynamic block descriptors.
+ */
+export declare function useDynamicBlocks(): {
+    readonly blocks: ReadonlyMap<string, DynamicBlockDescriptor>;
+    readonly isLoaded: boolean;
+};
+/**
+ * Access dynamic starter descriptors.
+ */
+export declare function useDynamicStarters(): {
+    readonly starters: ReadonlyMap<string, DynamicStarterDescriptor>;
+    readonly isLoaded: boolean;
+};

package/dist/render/dynamic-artifact-context.js

@@ -0,0 +1,89 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * Dynamic Artifact Context Provider
+ *
+ * Provides dynamic block and starter descriptor maps
+ * to the component tree. Populated from the host's render grants.
+ *
+ * @module @pwfabric/runtime/render/dynamic-artifact-context
+ */
+import { createContext, useContext, useEffect, useMemo } from 'react';
+import { BlockModuleLoader } from './dynamic-block-loader.js';
+// ============================================================
+// CONTEXT
+// ============================================================
+const DynamicArtifactContext = createContext({
+    dynamicBlocks: new Map(),
+    dynamicStarters: new Map(),
+    isLoaded: false,
+});
+// ============================================================
+// PROVIDER
+// ============================================================
+/**
+ * Warm the loader's cache for a whole catalog, fire-and-forget.
+ *
+ * The imperative half of the same opt-in: a canvas that knows it is about to
+ * render arbitrary blocks can start the downloads itself, without the provider
+ * having to guess from the fact that it was mounted. Caching and de-duplication
+ * stay entirely the loader's business — calling this twice costs one download.
+ */
+export function preloadDynamicBlocks(descriptors) {
+    if (!descriptors || descriptors.length === 0)
+        return;
+    BlockModuleLoader.preload(descriptors);
+}
+/**
+ * Provides dynamic block and starter descriptors to the component tree.
+ *
+ * Downloads nothing by itself: blocks load lazily as they are rendered. Pass
+ * `preload` to warm the whole catalog on mount.
+ */
+export function DynamicArtifactProvider({ dynamicBlocks, dynamicStarters, isLoaded = true, preload = false, children, }) {
+    const value = useMemo(() => {
+        const blockMap = new Map();
+        const starterMap = new Map();
+        if (dynamicBlocks) {
+            for (const block of dynamicBlocks) {
+                blockMap.set(block.blockType, block);
+            }
+        }
+        if (dynamicStarters) {
+            for (const starter of dynamicStarters) {
+                starterMap.set(starter.starterId, starter);
+            }
+        }
+        return {
+            dynamicBlocks: blockMap,
+            dynamicStarters: starterMap,
+            isLoaded,
+        };
+    }, [dynamicBlocks, dynamicStarters, isLoaded]);
+    // In an effect, not in the memo above: a preload is a side effect and a
+    // render is not the place for one — inside `useMemo` it also ran during
+    // server rendering, where nothing can consume the result.
+    useEffect(() => {
+        if (!preload)
+            return;
+        preloadDynamicBlocks(dynamicBlocks);
+    }, [preload, dynamicBlocks]);
+    return _jsx(DynamicArtifactContext.Provider, { value: value, children: children });
+}
+// ============================================================
+// HOOKS
+// ============================================================
+/**
+ * Access dynamic block descriptors.
+ */
+export function useDynamicBlocks() {
+    const ctx = useContext(DynamicArtifactContext);
+    return { blocks: ctx.dynamicBlocks, isLoaded: ctx.isLoaded };
+}
+/**
+ * Access dynamic starter descriptors.
+ */
+export function useDynamicStarters() {
+    const ctx = useContext(DynamicArtifactContext);
+    return { starters: ctx.dynamicStarters, isLoaded: ctx.isLoaded };
+}
+//# sourceMappingURL=dynamic-artifact-context.js.map

package/dist/render/dynamic-artifact-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dynamic-artifact-context.js","sourceRoot":"","sources":["../../src/render/dynamic-artifact-context.tsx"],"names":[],"mappings":";AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,SAAS,EAAE,OAAO,EAAkB,MAAM,OAAO,CAAA;AAErF,OAAO,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAA;AA6C7D,+DAA+D;AAC/D,UAAU;AACV,+DAA+D;AAE/D,MAAM,sBAAsB,GAAG,aAAa,CAA8B;IACxE,aAAa,EAAE,IAAI,GAAG,EAAE;IACxB,eAAe,EAAE,IAAI,GAAG,EAAE;IAC1B,QAAQ,EAAE,KAAK;CAChB,CAAC,CAAA;AAEF,+DAA+D;AAC/D,WAAW;AACX,+DAA+D;AAE/D;;;;;;;GAOG;AACH,MAAM,UAAU,oBAAoB,CAClC,WAAiE;IAEjE,IAAI,CAAC,WAAW,IAAI,WAAW,CAAC,MAAM,KAAK,CAAC;QAAE,OAAM;IACpD,iBAAiB,CAAC,OAAO,CAAC,WAAW,CAAC,CAAA;AACxC,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,uBAAuB,CAAC,EACtC,aAAa,EACb,eAAe,EACf,QAAQ,GAAG,IAAI,EACf,OAAO,GAAG,KAAK,EACf,QAAQ,GACqB;IAC7B,MAAM,KAAK,GAAG,OAAO,CAA8B,GAAG,EAAE;QACtD,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAkC,CAAA;QAC1D,MAAM,UAAU,GAAG,IAAI,GAAG,EAAoC,CAAA;QAE9D,IAAI,aAAa,EAAE,CAAC;YAClB,KAAK,MAAM,KAAK,IAAI,aAAa,EAAE,CAAC;gBAClC,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,SAAS,EAAE,KAAK,CAAC,CAAA;YACtC,CAAC;QACH,CAAC;QAED,IAAI,eAAe,EAAE,CAAC;YACpB,KAAK,MAAM,OAAO,IAAI,eAAe,EAAE,CAAC;gBACtC,UAAU,CAAC,GAAG,CAAC,OAAO,CAAC,SAAS,EAAE,OAAO,CAAC,CAAA;YAC5C,CAAC;QACH,CAAC;QAED,OAAO;YACL,aAAa,EAAE,QAAQ;YACvB,eAAe,EAAE,UAAU;YAC3B,QAAQ;SACT,CAAA;IACH,CAAC,EAAE,CAAC,aAAa,EAAE,eAAe,EAAE,QAAQ,CAAC,CAAC,CAAA;IAE9C,wEAAwE;IACxE,wEAAwE;IACxE,0DAA0D;IAC1D,SAAS,CAAC,GAAG,EAAE;QACb,IAAI,CAAC,OAAO;YAAE,OAAM;QACpB,oBAAoB,CAAC,aAAa,CAAC,CAAA;IACrC,CAAC,EAAE,CAAC,OAAO,EAAE,aAAa,CAAC,CAAC,CAAA;IAE5B,OAAO,KAAC,sBAAsB,CAAC,QAAQ,IAAC,KAAK,EAAE,KAAK,YAAG,QAAQ,GAAmC,CAAA;AACpG,CAAC;AAED,+DAA+D;AAC/D,QAAQ;AACR,+DAA+D;AAE/D;;GAEG;AACH,MAAM,UAAU,gBAAgB;IAI9B,MAAM,GAAG,GAAG,UAAU,CAAC,sBAAsB,CAAC,CAAA;IAC9C,OAAO,EAAE,MAAM,EAAE,GAAG,CAAC,aAAa,EAAE,QAAQ,EAAE,GAAG,CAAC,QAAQ,EAAE,CAAA;AAC9D,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,kBAAkB;IAIhC,MAAM,GAAG,GAAG,UAAU,CAAC,sBAAsB,CAAC,CAAA;IAC9C,OAAO,EAAE,QAAQ,EAAE,GAAG,CAAC,eAAe,EAAE,QAAQ,EAAE,GAAG,CAAC,QAAQ,EAAE,CAAA;AAClE,CAAC","sourcesContent":["/**\n * Dynamic Artifact Context Provider\n *\n * Provides dynamic block and starter descriptor maps\n * to the component tree. Populated from the host's render grants.\n *\n * @module @pwfabric/runtime/render/dynamic-artifact-context\n */\n\nimport { createContext, useContext, useEffect, useMemo, type ReactNode } from 'react'\nimport type { DynamicBlockDescriptor, DynamicStarterDescriptor } from '@pwfabric/contracts'\nimport { BlockModuleLoader } from './dynamic-block-loader.js'\n\n// ============================================================\n// TYPES\n// ============================================================\n\nexport interface DynamicArtifactContextValue {\n  readonly dynamicBlocks: ReadonlyMap<string, DynamicBlockDescriptor>\n  readonly dynamicStarters: ReadonlyMap<string, DynamicStarterDescriptor>\n  readonly isLoaded: boolean\n}\n\nexport interface DynamicArtifactProviderProps {\n  readonly dynamicBlocks?: readonly DynamicBlockDescriptor[]\n  readonly dynamicStarters?: readonly DynamicStarterDescriptor[]\n  /**\n   * Whether the dynamic descriptors have finished loading. Server-rendered\n   * consumers (a published page) pass fully-resolved descriptors\n   * synchronously and omit this — it defaults to `true`. Client-side editors\n   * load descriptors from the host's aggregate after mount, so they pass the\n   * live loading state; consumers can then tell \"still loading\" apart from\n   * \"genuinely no descriptor\" instead of flashing every block as unknown on\n   * first paint.\n   */\n  readonly isLoaded?: boolean\n  /**\n   * WARM THE WHOLE CATALOG ON MOUNT. Off by default, and that default is the\n   * point.\n   *\n   * This provider typically sits in the host app's root layout, so it is\n   * mounted on every route. Preloading from there downloads, hash-verifies and\n   * blob-imports every descriptor the host owns on pages that render none of\n   * them — dozens of bundles and tens of seconds of summed download on a page\n   * with no renderer at all.\n   *\n   * Rendering a block does not need this: `DynamicBlockWrapper` asks the\n   * loader for the descriptor it is about to draw, and the loader caches and\n   * de-dupes by block type. Turn it on only where a canvas is genuinely about\n   * to render arbitrary blocks and the round trip should already be in flight\n   * — a studio or an editor, never a layout.\n   */\n  readonly preload?: boolean\n  readonly children: ReactNode\n}\n\n// ============================================================\n// CONTEXT\n// ============================================================\n\nconst DynamicArtifactContext = createContext<DynamicArtifactContextValue>({\n  dynamicBlocks: new Map(),\n  dynamicStarters: new Map(),\n  isLoaded: false,\n})\n\n// ============================================================\n// PROVIDER\n// ============================================================\n\n/**\n * Warm the loader's cache for a whole catalog, fire-and-forget.\n *\n * The imperative half of the same opt-in: a canvas that knows it is about to\n * render arbitrary blocks can start the downloads itself, without the provider\n * having to guess from the fact that it was mounted. Caching and de-duplication\n * stay entirely the loader's business — calling this twice costs one download.\n */\nexport function preloadDynamicBlocks(\n  descriptors: readonly DynamicBlockDescriptor[] | undefined | null\n): void {\n  if (!descriptors || descriptors.length === 0) return\n  BlockModuleLoader.preload(descriptors)\n}\n\n/**\n * Provides dynamic block and starter descriptors to the component tree.\n *\n * Downloads nothing by itself: blocks load lazily as they are rendered. Pass\n * `preload` to warm the whole catalog on mount.\n */\nexport function DynamicArtifactProvider({\n  dynamicBlocks,\n  dynamicStarters,\n  isLoaded = true,\n  preload = false,\n  children,\n}: DynamicArtifactProviderProps): ReactNode {\n  const value = useMemo<DynamicArtifactContextValue>(() => {\n    const blockMap = new Map<string, DynamicBlockDescriptor>()\n    const starterMap = new Map<string, DynamicStarterDescriptor>()\n\n    if (dynamicBlocks) {\n      for (const block of dynamicBlocks) {\n        blockMap.set(block.blockType, block)\n      }\n    }\n\n    if (dynamicStarters) {\n      for (const starter of dynamicStarters) {\n        starterMap.set(starter.starterId, starter)\n      }\n    }\n\n    return {\n      dynamicBlocks: blockMap,\n      dynamicStarters: starterMap,\n      isLoaded,\n    }\n  }, [dynamicBlocks, dynamicStarters, isLoaded])\n\n  // In an effect, not in the memo above: a preload is a side effect and a\n  // render is not the place for one — inside `useMemo` it also ran during\n  // server rendering, where nothing can consume the result.\n  useEffect(() => {\n    if (!preload) return\n    preloadDynamicBlocks(dynamicBlocks)\n  }, [preload, dynamicBlocks])\n\n  return <DynamicArtifactContext.Provider value={value}>{children}</DynamicArtifactContext.Provider>\n}\n\n// ============================================================\n// HOOKS\n// ============================================================\n\n/**\n * Access dynamic block descriptors.\n */\nexport function useDynamicBlocks(): {\n  readonly blocks: ReadonlyMap<string, DynamicBlockDescriptor>\n  readonly isLoaded: boolean\n} {\n  const ctx = useContext(DynamicArtifactContext)\n  return { blocks: ctx.dynamicBlocks, isLoaded: ctx.isLoaded }\n}\n\n/**\n * Access dynamic starter descriptors.\n */\nexport function useDynamicStarters(): {\n  readonly starters: ReadonlyMap<string, DynamicStarterDescriptor>\n  readonly isLoaded: boolean\n} {\n  const ctx = useContext(DynamicArtifactContext)\n  return { starters: ctx.dynamicStarters, isLoaded: ctx.isLoaded }\n}\n"]}

package/dist/render/dynamic-block-loader.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Dynamic Block Module Loader
+ *
+ * Loads third-party block ESM modules at runtime via dynamic import().
+ * extends to first-party packs — the loader now SHA-256 hash
+ * checks the bundle bytes against `descriptor.integrity` before evaluation
+ * and discovers both the component and the BlockDefinition under stable
+ * export names (`Component` + `definition`) emitted by the bundle wrapper.
+ *
+ * @module @pwfabric/runtime/render/dynamic-block-loader
+ */
+import type { BlockDefinition } from '@pwfabric/core';
+import type { DynamicBlockDescriptor } from '@pwfabric/contracts';
+import type { BlockComponent } from './types.js';
+export interface LoadedAtom {
+    readonly Component: BlockComponent;
+    readonly definition: BlockDefinition | null;
+}
+/**
+ * Singleton loader for dynamic block ESM modules.
+ *
+ * - Caches loaded modules by blockType
+ * - Deduplicates concurrent requests for the same module
+ * - Provides preload for fire-and-forget pre-fetching
+ */
+declare class BlockModuleLoaderImpl {
+    private readonly cache;
+    private readonly pending;
+    /**
+     * Load a dynamic block module and return its component.
+     */
+    load(descriptor: DynamicBlockDescriptor): Promise<BlockComponent>;
+    /**
+     * load both the component and the BlockDefinition. Hash-checks
+     * the bundle bytes against `descriptor.integrity` before evaluation.
+     */
+    loadAtom(descriptor: DynamicBlockDescriptor): Promise<LoadedAtom>;
+    /**
+     * Preload multiple block modules (fire-and-forget).
+     */
+    preload(descriptors: readonly DynamicBlockDescriptor[]): void;
+    /**
+     * Check if a block module is already loaded.
+     */
+    isLoaded(blockType: string): boolean;
+    /**
+     * Synchronously get a cached block component, or null if not yet loaded.
+     */
+    getSync(blockType: string): BlockComponent | null;
+    /**
+     * Synchronously get the cached block definition, or null if not yet loaded
+     * (or the bundle did not export one).
+     */
+    getDefinitionSync(blockType: string): BlockDefinition | null;
+    /**
+     * Invalidate cache for a specific block type or all blocks.
+     */
+    invalidate(blockType?: string): void;
+    private doLoad;
+}
+/**
+ * SHA-256 verify the fetched bundle bytes against `descriptor.integrity`.
+ *
+ * Accepted formats:
+ * - bare 64-char hex (the format `bundleHash` is stored in DB / listing
+ *   metadata)
+ * - SRI-style `sha256-<base64>` (allowed for forward-compat with W3C
+ *   subresource-integrity strings)
+ *
+ * Empty / missing integrity is treated as a hard failure — this is a
+ * security boundary, not a hint.
+ *
+ * Exported for unit tests; runtime callers should use `BlockModuleLoader.load`.
+ */
+export declare function verifyIntegrity(bytes: ArrayBuffer, integrity: string, blockType: string): Promise<void>;
+/**
+ * Singleton instance
+ */
+export declare const BlockModuleLoader: BlockModuleLoaderImpl;
+export {};

package/dist/render/dynamic-block-loader.js

@@ -0,0 +1,197 @@
+/**
+ * Dynamic Block Module Loader
+ *
+ * Loads third-party block ESM modules at runtime via dynamic import().
+ * extends to first-party packs — the loader now SHA-256 hash
+ * checks the bundle bytes against `descriptor.integrity` before evaluation
+ * and discovers both the component and the BlockDefinition under stable
+ * export names (`Component` + `definition`) emitted by the bundle wrapper.
+ *
+ * @module @pwfabric/runtime/render/dynamic-block-loader
+ */
+// ============================================================
+// MODULE LOADER
+// ============================================================
+/**
+ * Singleton loader for dynamic block ESM modules.
+ *
+ * - Caches loaded modules by blockType
+ * - Deduplicates concurrent requests for the same module
+ * - Provides preload for fire-and-forget pre-fetching
+ */
+class BlockModuleLoaderImpl {
+    cache = new Map();
+    pending = new Map();
+    /**
+     * Load a dynamic block module and return its component.
+     */
+    async load(descriptor) {
+        const atom = await this.loadAtom(descriptor);
+        return atom.Component;
+    }
+    /**
+     * load both the component and the BlockDefinition. Hash-checks
+     * the bundle bytes against `descriptor.integrity` before evaluation.
+     */
+    async loadAtom(descriptor) {
+        // Check cache
+        const cached = this.cache.get(descriptor.blockType);
+        if (cached)
+            return { Component: cached.component, definition: cached.definition };
+        // Check pending (dedup concurrent requests)
+        const inflight = this.pending.get(descriptor.blockType);
+        if (inflight)
+            return inflight;
+        const promise = this.doLoad(descriptor);
+        this.pending.set(descriptor.blockType, promise);
+        try {
+            const atom = await promise;
+            this.cache.set(descriptor.blockType, {
+                component: atom.Component,
+                definition: atom.definition,
+                loadedAt: Date.now(),
+            });
+            return atom;
+        }
+        finally {
+            this.pending.delete(descriptor.blockType);
+        }
+    }
+    /**
+     * Preload multiple block modules (fire-and-forget).
+     */
+    preload(descriptors) {
+        for (const descriptor of descriptors) {
+            if (!this.cache.has(descriptor.blockType) && !this.pending.has(descriptor.blockType)) {
+                this.loadAtom(descriptor).catch(() => {
+                    // Preload failure is non-fatal
+                });
+            }
+        }
+    }
+    /**
+     * Check if a block module is already loaded.
+     */
+    isLoaded(blockType) {
+        return this.cache.has(blockType);
+    }
+    /**
+     * Synchronously get a cached block component, or null if not yet loaded.
+     */
+    getSync(blockType) {
+        return this.cache.get(blockType)?.component ?? null;
+    }
+    /**
+     * Synchronously get the cached block definition, or null if not yet loaded
+     * (or the bundle did not export one).
+     */
+    getDefinitionSync(blockType) {
+        return this.cache.get(blockType)?.definition ?? null;
+    }
+    /**
+     * Invalidate cache for a specific block type or all blocks.
+     */
+    invalidate(blockType) {
+        if (blockType) {
+            this.cache.delete(blockType);
+        }
+        else {
+            this.cache.clear();
+        }
+    }
+    async doLoad(descriptor) {
+        const LOAD_TIMEOUT_MS = 10_000;
+        const fetchAndImport = async () => {
+            // integrity is required before evaluation. We fetch the
+            // bundle, hash-verify the bytes against `descriptor.integrity`, and
+            // only then create a Blob URL and feed it to `import()`. Skipping
+            // this would let a CDN-side compromise execute attacker code under
+            // our origin.
+            const res = await fetch(descriptor.moduleUrl, { credentials: 'omit' });
+            if (!res.ok) {
+                throw new Error(`Bundle fetch failed for ${descriptor.blockType}: ${res.status}`);
+            }
+            const bytes = await res.arrayBuffer();
+            await verifyIntegrity(bytes, descriptor.integrity, descriptor.blockType);
+            const blob = new Blob([bytes], { type: 'text/javascript' });
+            const blobUrl = URL.createObjectURL(blob);
+            try {
+                return (await import(/* webpackIgnore: true */ blobUrl));
+            }
+            finally {
+                URL.revokeObjectURL(blobUrl);
+            }
+        };
+        const loadPromise = fetchAndImport();
+        const timeoutPromise = new Promise((_, reject) => setTimeout(() => reject(new Error(`Module load timed out after ${LOAD_TIMEOUT_MS / 1000}s`)), LOAD_TIMEOUT_MS));
+        const mod = await Promise.race([loadPromise, timeoutPromise]);
+        // wrapper convention emits `Component` + `definition`.
+        // Fall back to legacy export names so older bundles keep working.
+        const component = mod.Component ?? mod.default ?? mod.component ?? mod.render;
+        if (!component || typeof component !== 'function') {
+            throw new Error(`Module at ${descriptor.moduleUrl} does not export a valid block component`);
+        }
+        const definition = mod.definition && typeof mod.definition === 'object' ? mod.definition : null;
+        return { Component: component, definition };
+    }
+}
+// ============================================================
+// HASH VERIFICATION
+// ============================================================
+/**
+ * SHA-256 verify the fetched bundle bytes against `descriptor.integrity`.
+ *
+ * Accepted formats:
+ * - bare 64-char hex (the format `bundleHash` is stored in DB / listing
+ *   metadata)
+ * - SRI-style `sha256-<base64>` (allowed for forward-compat with W3C
+ *   subresource-integrity strings)
+ *
+ * Empty / missing integrity is treated as a hard failure — this is a
+ * security boundary, not a hint.
+ *
+ * Exported for unit tests; runtime callers should use `BlockModuleLoader.load`.
+ */
+export async function verifyIntegrity(bytes, integrity, blockType) {
+    if (!integrity) {
+        throw new Error(`Missing integrity for ${blockType}; refusing to evaluate bundle`);
+    }
+    const computed = new Uint8Array(await crypto.subtle.digest('SHA-256', bytes));
+    const computedHex = bytesToHex(computed);
+    const expected = integrity.trim();
+    if (/^[0-9a-f]{64}$/i.test(expected)) {
+        if (computedHex.toLowerCase() !== expected.toLowerCase()) {
+            throw new Error(`Integrity check failed for ${blockType}`);
+        }
+        return;
+    }
+    const sriMatch = /^sha256-(.+)$/i.exec(expected);
+    if (sriMatch) {
+        const expectedB64 = sriMatch[1] ?? '';
+        const computedB64 = bytesToBase64(computed);
+        if (expectedB64.replace(/=+$/, '') !== computedB64.replace(/=+$/, '')) {
+            throw new Error(`Integrity check failed for ${blockType}`);
+        }
+        return;
+    }
+    throw new Error(`Unrecognized integrity format for ${blockType}`);
+}
+function bytesToHex(bytes) {
+    let out = '';
+    for (const v of bytes) {
+        out += v.toString(16).padStart(2, '0');
+    }
+    return out;
+}
+function bytesToBase64(bytes) {
+    let bin = '';
+    for (const v of bytes) {
+        bin += String.fromCharCode(v);
+    }
+    return btoa(bin);
+}
+/**
+ * Singleton instance
+ */
+export const BlockModuleLoader = new BlockModuleLoaderImpl();
+//# sourceMappingURL=dynamic-block-loader.js.map

package/dist/render/dynamic-block-loader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dynamic-block-loader.js","sourceRoot":"","sources":["../../src/render/dynamic-block-loader.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Dynamic Block Module Loader\n *\n * Loads third-party block ESM modules at runtime via dynamic import().\n * extends to first-party packs — the loader now SHA-256 hash\n * checks the bundle bytes against `descriptor.integrity` before evaluation\n * and discovers both the component and the BlockDefinition under stable\n * export names (`Component` + `definition`) emitted by the bundle wrapper.\n *\n * @module @pwfabric/runtime/render/dynamic-block-loader\n */\n\nimport type { BlockDefinition } from '@pwfabric/core'\nimport type { DynamicBlockDescriptor } from '@pwfabric/contracts'\nimport type { BlockComponent } from './types.js'\n\n// ============================================================\n// TYPES\n// ============================================================\n\nexport interface LoadedAtom {\n  readonly Component: BlockComponent\n  readonly definition: BlockDefinition | null\n}\n\ninterface CachedModule {\n  readonly component: BlockComponent\n  readonly definition: BlockDefinition | null\n  readonly loadedAt: number\n}\n\ninterface BlockModule {\n  readonly default?: BlockComponent\n  readonly component?: BlockComponent\n  readonly render?: BlockComponent\n  /** wrapper convention */\n  readonly Component?: BlockComponent\n  readonly definition?: BlockDefinition\n}\n\n// ============================================================\n// MODULE LOADER\n// ============================================================\n\n/**\n * Singleton loader for dynamic block ESM modules.\n *\n * - Caches loaded modules by blockType\n * - Deduplicates concurrent requests for the same module\n * - Provides preload for fire-and-forget pre-fetching\n */\nclass BlockModuleLoaderImpl {\n  private readonly cache = new Map<string, CachedModule>()\n  private readonly pending = new Map<string, Promise<LoadedAtom>>()\n\n  /**\n   * Load a dynamic block module and return its component.\n   */\n  async load(descriptor: DynamicBlockDescriptor): Promise<BlockComponent> {\n    const atom = await this.loadAtom(descriptor)\n    return atom.Component\n  }\n\n  /**\n   * load both the component and the BlockDefinition. Hash-checks\n   * the bundle bytes against `descriptor.integrity` before evaluation.\n   */\n  async loadAtom(descriptor: DynamicBlockDescriptor): Promise<LoadedAtom> {\n    // Check cache\n    const cached = this.cache.get(descriptor.blockType)\n    if (cached) return { Component: cached.component, definition: cached.definition }\n\n    // Check pending (dedup concurrent requests)\n    const inflight = this.pending.get(descriptor.blockType)\n    if (inflight) return inflight\n\n    const promise = this.doLoad(descriptor)\n    this.pending.set(descriptor.blockType, promise)\n\n    try {\n      const atom = await promise\n      this.cache.set(descriptor.blockType, {\n        component: atom.Component,\n        definition: atom.definition,\n        loadedAt: Date.now(),\n      })\n      return atom\n    } finally {\n      this.pending.delete(descriptor.blockType)\n    }\n  }\n\n  /**\n   * Preload multiple block modules (fire-and-forget).\n   */\n  preload(descriptors: readonly DynamicBlockDescriptor[]): void {\n    for (const descriptor of descriptors) {\n      if (!this.cache.has(descriptor.blockType) && !this.pending.has(descriptor.blockType)) {\n        this.loadAtom(descriptor).catch(() => {\n          // Preload failure is non-fatal\n        })\n      }\n    }\n  }\n\n  /**\n   * Check if a block module is already loaded.\n   */\n  isLoaded(blockType: string): boolean {\n    return this.cache.has(blockType)\n  }\n\n  /**\n   * Synchronously get a cached block component, or null if not yet loaded.\n   */\n  getSync(blockType: string): BlockComponent | null {\n    return this.cache.get(blockType)?.component ?? null\n  }\n\n  /**\n   * Synchronously get the cached block definition, or null if not yet loaded\n   * (or the bundle did not export one).\n   */\n  getDefinitionSync(blockType: string): BlockDefinition | null {\n    return this.cache.get(blockType)?.definition ?? null\n  }\n\n  /**\n   * Invalidate cache for a specific block type or all blocks.\n   */\n  invalidate(blockType?: string): void {\n    if (blockType) {\n      this.cache.delete(blockType)\n    } else {\n      this.cache.clear()\n    }\n  }\n\n  private async doLoad(descriptor: DynamicBlockDescriptor): Promise<LoadedAtom> {\n    const LOAD_TIMEOUT_MS = 10_000\n\n    const fetchAndImport = async (): Promise<BlockModule> => {\n      // integrity is required before evaluation. We fetch the\n      // bundle, hash-verify the bytes against `descriptor.integrity`, and\n      // only then create a Blob URL and feed it to `import()`. Skipping\n      // this would let a CDN-side compromise execute attacker code under\n      // our origin.\n      const res = await fetch(descriptor.moduleUrl, { credentials: 'omit' })\n      if (!res.ok) {\n        throw new Error(`Bundle fetch failed for ${descriptor.blockType}: ${res.status}`)\n      }\n      const bytes = await res.arrayBuffer()\n      await verifyIntegrity(bytes, descriptor.integrity, descriptor.blockType)\n\n      const blob = new Blob([bytes], { type: 'text/javascript' })\n      const blobUrl = URL.createObjectURL(blob)\n      try {\n        return (await import(/* webpackIgnore: true */ blobUrl)) as BlockModule\n      } finally {\n        URL.revokeObjectURL(blobUrl)\n      }\n    }\n\n    const loadPromise = fetchAndImport()\n    const timeoutPromise = new Promise<never>((_, reject) =>\n      setTimeout(\n        () => reject(new Error(`Module load timed out after ${LOAD_TIMEOUT_MS / 1000}s`)),\n        LOAD_TIMEOUT_MS\n      )\n    )\n\n    const mod = await Promise.race([loadPromise, timeoutPromise])\n\n    // wrapper convention emits `Component` + `definition`.\n    // Fall back to legacy export names so older bundles keep working.\n    const component = mod.Component ?? mod.default ?? mod.component ?? mod.render\n    if (!component || typeof component !== 'function') {\n      throw new Error(`Module at ${descriptor.moduleUrl} does not export a valid block component`)\n    }\n    const definition: BlockDefinition | null =\n      mod.definition && typeof mod.definition === 'object' ? mod.definition : null\n\n    return { Component: component, definition }\n  }\n}\n\n// ============================================================\n// HASH VERIFICATION\n// ============================================================\n\n/**\n * SHA-256 verify the fetched bundle bytes against `descriptor.integrity`.\n *\n * Accepted formats:\n * - bare 64-char hex (the format `bundleHash` is stored in DB / listing\n *   metadata)\n * - SRI-style `sha256-<base64>` (allowed for forward-compat with W3C\n *   subresource-integrity strings)\n *\n * Empty / missing integrity is treated as a hard failure — this is a\n * security boundary, not a hint.\n *\n * Exported for unit tests; runtime callers should use `BlockModuleLoader.load`.\n */\nexport async function verifyIntegrity(\n  bytes: ArrayBuffer,\n  integrity: string,\n  blockType: string\n): Promise<void> {\n  if (!integrity) {\n    throw new Error(`Missing integrity for ${blockType}; refusing to evaluate bundle`)\n  }\n  const computed = new Uint8Array(await crypto.subtle.digest('SHA-256', bytes))\n  const computedHex = bytesToHex(computed)\n  const expected = integrity.trim()\n\n  if (/^[0-9a-f]{64}$/i.test(expected)) {\n    if (computedHex.toLowerCase() !== expected.toLowerCase()) {\n      throw new Error(`Integrity check failed for ${blockType}`)\n    }\n    return\n  }\n\n  const sriMatch = /^sha256-(.+)$/i.exec(expected)\n  if (sriMatch) {\n    const expectedB64 = sriMatch[1] ?? ''\n    const computedB64 = bytesToBase64(computed)\n    if (expectedB64.replace(/=+$/, '') !== computedB64.replace(/=+$/, '')) {\n      throw new Error(`Integrity check failed for ${blockType}`)\n    }\n    return\n  }\n\n  throw new Error(`Unrecognized integrity format for ${blockType}`)\n}\n\nfunction bytesToHex(bytes: Uint8Array): string {\n  let out = ''\n  for (const v of bytes) {\n    out += v.toString(16).padStart(2, '0')\n  }\n  return out\n}\n\nfunction bytesToBase64(bytes: Uint8Array): string {\n  let bin = ''\n  for (const v of bytes) {\n    bin += String.fromCharCode(v)\n  }\n  return btoa(bin)\n}\n\n/**\n * Singleton instance\n */\nexport const BlockModuleLoader = new BlockModuleLoaderImpl()\n"]}