handoff-app 1.2.2-7 → 2.0.0-0

package/src/transformers/preview/pattern/builder.ts

@@ -1,7 +1,14 @@
 import fs from 'fs-extra';
 import path from 'path';
+import { buildPatternDetailUrl } from '../../../artifacts/url';
 import Handoff from '../../../index';
 import { Logger } from '../../../utils/logger';
+import {
+  resolveComponentArtifactPresence,
+  resolveSharedArtifactPresence,
+  type ComponentArtifactPresence,
+  type SharedArtifactPresence,
+} from '../component/shared-artifacts';
 import { PatternListObject, PatternObject } from '../types';
 import { readPatternSummaryApi, syncPatternArtifacts, writePatternApi, writePatternHtml, writePatternSummaryApi } from './api';
 import { composePatternHtml } from './html';
@@ -37,7 +44,8 @@ async function buildPattern(
   patternId: string,
   pattern: PatternObject,
   componentOutputDir: string,
-  basePath: string
+  basePath: string,
+  sharedArtifacts: SharedArtifactPresence
 ): Promise<PatternListObject | null> {
   const fragments: { componentId: string; html: string }[] = [];
   let hasErrors = false;
@@ -77,6 +85,15 @@ async function buildPattern(
     fragments.push({ componentId: ref.id, html });
   }
 
+  // Resolve component-owned artifact presence for each composed component so the pattern references
+  // only the stylesheets that actually exist (no dangling references for style-less components).
+  const componentArtifacts = new Map<string, ComponentArtifactPresence>();
+  for (const fragment of fragments) {
+    if (!componentArtifacts.has(fragment.componentId)) {
+      componentArtifacts.set(fragment.componentId, resolveComponentArtifactPresence(handoff, fragment.componentId));
+    }
+  }
+
   if (fragments.length === 0) {
     Logger.warn(`Pattern "${patternId}" produced no fragments. Skipping.`);
     return null;
@@ -86,14 +103,14 @@ async function buildPattern(
     Logger.warn(`Pattern "${patternId}" has missing components but will be composed from available fragments.`);
   }
 
-  const composedHtml = composePatternHtml(patternId, pattern.title, fragments, basePath);
+  const composedHtml = composePatternHtml(patternId, pattern.title, fragments, basePath, sharedArtifacts, componentArtifacts);
   const patternUrl = `${patternId}.html`;
 
   const patternData: PatternListObject = {
     ...pattern,
     id: patternId,
     url: patternUrl,
-    path: `${basePath}/api/pattern/${patternId}.json`,
+    path: buildPatternDetailUrl(patternId, basePath),
   };
 
   await writePatternHtml(patternId, composedHtml, handoff);
@@ -109,7 +126,13 @@ async function buildPattern(
  * so that all component preview HTML files already exist on disk.
  */
 export async function processPatterns(handoff: Handoff, options?: ProcessPatternsOptions): Promise<PatternListObject[]> {
-  const runtimePatterns = handoff.runtimeConfig?.entries?.patterns ?? {};
+  // Resolve the pattern set through the storage-agnostic store (v2). The filesystem store is a read
+  // view over `runtimeConfig.entries.patterns`, so these are the same records the build has always
+  // used — rebuilt into the id-keyed map the build logic below expects.
+  const runtimePatterns: Record<string, PatternListObject> = {};
+  for (const pattern of await handoff.store.patterns.list()) {
+    runtimePatterns[pattern.id] = pattern;
+  }
   const patternIds = Object.keys(runtimePatterns);
   const onlyPatternIds = options?.onlyPatternIds;
   const isPartial = onlyPatternIds !== undefined;
@@ -122,6 +145,9 @@ export async function processPatterns(handoff: Handoff, options?: ProcessPattern
 
   const componentOutputDir = path.resolve(handoff.workingPath, 'public/api/component');
   const basePath = process.env.HANDOFF_APP_BASE_PATH ?? '';
+  // Resolve the shared/global artifacts once so composed patterns reference `component/main.css` and
+  // `component/main.js` only when present (deduplicated to a single global script per page).
+  const sharedArtifacts = resolveSharedArtifactPresence(handoff);
 
   if (!isPartial) {
     Logger.info(`Building ${patternIds.length} pattern(s)...`);
@@ -129,7 +155,7 @@ export async function processPatterns(handoff: Handoff, options?: ProcessPattern
 
     for (const patternId of patternIds) {
       const pattern = runtimePatterns[patternId];
-      const built = await buildPattern(handoff, patternId, pattern, componentOutputDir, basePath);
+      const built = await buildPattern(handoff, patternId, pattern, componentOutputDir, basePath, sharedArtifacts);
       if (built) {
         result.push(built);
       }
@@ -159,7 +185,7 @@ export async function processPatterns(handoff: Handoff, options?: ProcessPattern
   for (const patternId of patternIds) {
     if (onlyPatternIds.has(patternId)) {
       const pattern = runtimePatterns[patternId];
-      const built = await buildPattern(handoff, patternId, pattern, componentOutputDir, basePath);
+      const built = await buildPattern(handoff, patternId, pattern, componentOutputDir, basePath, sharedArtifacts);
       if (built) {
         existingById.set(patternId, built);
       } else {
@@ -167,7 +193,7 @@ export async function processPatterns(handoff: Handoff, options?: ProcessPattern
       }
     } else if (!existingById.has(patternId)) {
       const pattern = runtimePatterns[patternId];
-      const built = await buildPattern(handoff, patternId, pattern, componentOutputDir, basePath);
+      const built = await buildPattern(handoff, patternId, pattern, componentOutputDir, basePath, sharedArtifacts);
       if (built) {
         existingById.set(patternId, built);
       }

package/src/transformers/preview/pattern/html.ts

@@ -1,34 +1,47 @@
 import escape from 'lodash/escape';
 import { parse } from 'node-html-parser';
+import { SHARED_MAIN_CSS_ARTIFACT_PATH, SHARED_MAIN_JS_ARTIFACT_PATH } from '../../../artifacts';
+import { buildArtifactUrl } from '../../../artifacts/url';
+import type { ComponentArtifactPresence, SharedArtifactPresence } from '../component/shared-artifacts';
 
 /**
  * Composes multiple component preview HTML documents into a single-page HTML.
  *
- * Each component preview may be a React SSR document (with hydration scripts
- * and a `#root` / `#__APP_PROPS__` pair) or a static Handlebars document.
+ * Each component preview may be a React SSR document (server-rendered markup plus a `#root` /
+ * `#__APP_PROPS__` pair) or a static Handlebars document.
  *
- * This function namespaces the element ids per-fragment so multiple React
- * components can coexist and hydrate independently on the same page.
+ * React client/hydration bundles are component-owned artifacts (`component/<id>.client.js`). This
+ * composer copies no per-fragment bundle: it namespaces each fragment's root/props so multiple
+ * instances coexist, marks each root with the `data-handoff-component`/`data-handoff-props`
+ * attributes the component bundle hydrates by, and references each unique component's client artifact
+ * exactly once.
  *
- * Each hydration bundle gets its own `<script type="module">` tag for full
- * module-level isolation. This is critical because esbuild bundles React
- * into each script using module-scoped `var` declarations, and `hydrateRoot`
- * is asynchronous — sharing a single module scope would cause later bundles
- * to overwrite earlier React instances before hydration completes.
+ * Shared/global artifacts follow the shared-artifact model: `component/main.css` and
+ * `component/main.js` are referenced only when present, and the global script is emitted exactly once
+ * (deduplicated across fragments) so its top-level side effects run a single time, ahead of the
+ * per-component client bundles.
  */
 export const composePatternHtml = (
   _patternId: string,
   patternTitle: string,
   fragments: { componentId: string; html: string }[],
-  basePath: string
+  basePath: string,
+  sharedArtifacts: SharedArtifactPresence,
+  componentArtifacts: Map<string, ComponentArtifactPresence>
 ): string => {
   const cssHrefs = new Set<string>();
   const bodyParts: string[] = [];
-  const scriptTags: string[] = [];
+  const clientArtifactHrefs = new Set<string>();
 
-  cssHrefs.add(`${basePath}/api/component/main.css`);
+  if (sharedArtifacts.mainCss) {
+    cssHrefs.add(buildArtifactUrl(SHARED_MAIN_CSS_ARTIFACT_PATH, basePath));
+  }
   cssHrefs.add(`${basePath}/assets/css/preview.css`);
 
+  // Canonical URL of the shared global script; used to strip any per-fragment reference so the
+  // global script is emitted (and executed) exactly once for the whole composed page.
+  const globalScriptUrl = buildArtifactUrl(SHARED_MAIN_JS_ARTIFACT_PATH, basePath);
+
   const seenComponents = new Set<string>();
 
   for (let i = 0; i < fragments.length; i++) {
@@ -36,7 +49,11 @@ export const composePatternHtml = (
 
     if (!seenComponents.has(componentId)) {
       seenComponents.add(componentId);
-      cssHrefs.add(`${basePath}/api/component/${componentId}.css`);
+      // Reference a component's stylesheet only when it actually exists, so a pattern never requests
+      // an absent optional artifact for a component that declares no styles.
+      if (componentArtifacts.get(componentId)?.css) {
+        cssHrefs.add(buildArtifactUrl(`component/${componentId}.css`, basePath));
+      }
     }
 
     const doc = parse(html);
@@ -46,30 +63,40 @@ export const composePatternHtml = (
 
     // -- Extract props JSON (React SSR) ------------------------------------
     const propsScript = doc.querySelector('#__APP_PROPS__');
-    let propsContent = '{}';
+    let propsContent: string | null = null;
     if (propsScript) {
       propsContent = propsScript.textContent || '{}';
       propsScript.remove();
     }
 
-    // -- Extract and rewrite hydration scripts (React SSR) -----------------
-    // Each script becomes its own <script type="module"> for full isolation.
-    const moduleScripts = doc.querySelectorAll('script[type="module"]');
-    for (const script of moduleScripts) {
-      let code = script.textContent || '';
-      if (code.trim()) {
-        code = code
-          .replace(/__APP_PROPS__/g, namespacedPropsId)
-          .replace(/getElementById\(\s*["']root["']\s*\)/g, `getElementById("${namespacedRootId}")`);
-        scriptTags.push(`    <script type="module">\n${code}\n    </script>`);
-      }
+    // -- Drop the fragment's own client-artifact reference -----------------
+    // The bundle is referenced once per component for the whole page (below); a fragment must not
+    // carry its standalone-preview script tag into the composed document.
+    for (const script of doc.querySelectorAll('script[type="module"]')) {
       script.remove();
     }
 
+    // -- Drop the fragment's own global-script reference -------------------
+    // Static (Handlebars) fragments render the global `component/main.js` tag inside their body; left
+    // in place it would be inlined per fragment and run the global side effects multiple times. The
+    // page references the global script exactly once (below).
+    for (const script of doc.querySelectorAll('script')) {
+      if (script.getAttribute('src') === globalScriptUrl) {
+        script.remove();
+      }
+    }
+
     // -- Namespace the root element (React SSR) ----------------------------
+    // A React fragment exposes its mount point to the component bundle via stable data attributes.
     const rootEl = doc.querySelector('#root');
+    const isReactFragment = !!rootEl && propsContent !== null;
     if (rootEl) {
       rootEl.setAttribute('id', namespacedRootId);
+      if (isReactFragment) {
+        rootEl.setAttribute('data-handoff-component', componentId);
+        rootEl.setAttribute('data-handoff-props', namespacedPropsId);
+        clientArtifactHrefs.add(buildArtifactUrl(`component/${componentId}.client.js`, basePath));
+      }
     }
 
     // -- Extract body content ----------------------------------------------
@@ -80,9 +107,14 @@ export const composePatternHtml = (
         ? rootEl.outerHTML
         : doc.innerHTML || '';
 
+    const propsScriptTag =
+      propsContent !== null
+        ? `      <script id="${namespacedPropsId}" type="application/json">${propsContent}</script>\n`
+        : '';
+
     bodyParts.push(
       `    <div class="handoff-pattern-block" data-component="${componentId}" data-fragment="${i}">\n` +
-      `      <script id="${namespacedPropsId}" type="application/json">${propsContent}</script>\n` +
+      propsScriptTag +
       `      ${bodyContent}\n` +
       `    </div>`
     );
@@ -92,6 +124,18 @@ export const composePatternHtml = (
     .map((href) => `    <link rel="stylesheet" href="${href}" />`)
     .join('\n');
 
+  // The global script is referenced once for the whole page (deduplicated across fragments) and
+  // placed before the per-component client bundles so its side effects run first and exactly once.
+  const globalScriptTag = sharedArtifacts.mainJs
+    ? `    <script src="${buildArtifactUrl(SHARED_MAIN_JS_ARTIFACT_PATH, basePath)}"></script>`
+    : '';
+
+  const clientScriptTags = Array.from(clientArtifactHrefs)
+    .map((href) => `    <script type="module" src="${href}"></script>`)
+    .join('\n');
+
+  const scriptTags = [globalScriptTag, clientScriptTags].filter(Boolean).join('\n');
+
   return `<!DOCTYPE html>
 <html lang="en">
   <head>
@@ -101,7 +145,7 @@ ${linkTags}
   </head>
   <body>
 ${bodyParts.join('\n')}
-${scriptTags.join('\n')}
+${scriptTags}
   </body>
 </html>`;
 };

package/src/transformers/preview/types.ts

@@ -238,3 +238,45 @@ export type PatternListObject = {
   id: string;
   path: string;
 } & PatternObject;
+
+// ---------------------------------------------------------------------------
+// Page types
+// ---------------------------------------------------------------------------
+
+/**
+ * A documentation page authored as markdown. The frontmatter is parsed into these fields and the
+ * markdown body is the rendered content. Pages are workspace-authored under `<workingPath>/pages/`
+ * and are first-class registry entities (publish/checkout) alongside components and patterns. Unlike
+ * components/patterns there is no rendered-artifact pipeline: the raw markdown is stored and rendered
+ * at runtime.
+ */
+export type PageObject = {
+  title: string;
+  description?: string;
+  group?: string;
+  /** Sort weight within the nav section (lower first). */
+  weight?: number;
+  /** Alternative title used in navigation. */
+  menuTitle?: string;
+  /** SEO overrides. */
+  metaTitle?: string;
+  metaDescription?: string;
+  /** When `false`, the page is hidden from navigation. */
+  enabled?: boolean;
+  /** External link target — a URL/path string, or `true` to flag the section as external. */
+  external?: string | boolean;
+  /** Optional declarative submenu structure (mirrors the markdown frontmatter `menu`). */
+  menu?: { [key: string]: any };
+};
+
+export type PageListObject = {
+  /** Stable page id — its slug path (e.g. `guides/setup`), derived from the file location (id ≡ route). */
+  id: string;
+  /** Logical route the page is served at (e.g. `/guides/setup`). */
+  path: string;
+  /**
+   * Absolute filesystem path of the source `.md` (workspace store only). Workspace-only and stripped
+   * from the published transfer item — never persisted to or served from the registry.
+   */
+  sourcePath?: string;
+} & PageObject;

package/src/transformers/utils/handlebars.ts

@@ -2,6 +2,14 @@ import Handlebars from 'handlebars';
 import { RegisterHandlebarsHelpersContext } from '../../types/config';
 import { Logger } from '../../utils/logger';
 import { SlotMetadata } from '../preview/component';
+import {
+  renderComponentScriptTag,
+  renderComponentStyleLink,
+  renderGlobalScriptTag,
+  renderSharedStyleLinks,
+  type ComponentArtifactPresence,
+  type SharedArtifactPresence,
+} from '../preview/component/shared-artifacts';
 import { HandlebarsContext } from '../types';
 
 /**
@@ -74,17 +82,35 @@ export const registerHandlebarsHelpers = (
 export const createHandlebarsContext = (
   data: { id: string; properties: { [key: string]: SlotMetadata }; title: string },
   previewData: { values?: any },
-  options?: { includeSharedStyles?: boolean }
+  options?: {
+    includeSharedStyles?: boolean;
+    sharedArtifacts?: SharedArtifactPresence;
+    componentArtifacts?: ComponentArtifactPresence;
+  }
 ): HandlebarsContext => {
   const basePath = process.env.HANDOFF_APP_BASE_PATH ?? '';
-  const sharedStylesLink = options?.includeSharedStyles ? `<link rel="stylesheet" href="${basePath}/api/component/shared.css">` : '';
+  // Shared/global artifacts (`component/shared.css`, `component/main.css`, `component/main.js`) and
+  // the component's own css/js are referenced only when present, so a failed/absent build never
+  // produces a dangling reference. Absent presence info conservatively omits the artifacts.
+  const presence: SharedArtifactPresence = options?.sharedArtifacts ?? { mainJs: false, mainCss: false, sharedCss: false };
+  const componentPresence: ComponentArtifactPresence = options?.componentArtifacts ?? { css: false, js: false };
+  const sharedStyleLinks = renderSharedStyleLinks(presence, basePath, {
+    includeSharedStyles: options?.includeSharedStyles,
+  });
+  const componentStyleLink = renderComponentStyleLink(componentPresence, data.id, basePath);
+  // The global script loads before the component-specific script so global side effects run first.
+  const globalScriptTag = renderGlobalScriptTag(presence, basePath);
+  const componentScriptTag = renderComponentScriptTag(componentPresence, data.id, basePath);
 
   return {
     style:
-      `${sharedStylesLink}<link rel="stylesheet" href="${basePath}/api/component/main.css">` +
-      `<link rel="stylesheet" href="${basePath}/api/component/${data.id}.css">\n` +
+      `${sharedStyleLinks ? `${sharedStyleLinks}\n` : ''}` +
+      `${componentStyleLink ? `${componentStyleLink}\n` : ''}` +
       `<link rel="stylesheet" href="${basePath}/assets/css/preview.css">`,
-    script: `<script src="${basePath}/api/component/${data.id}.js"></script>\n<script src="${basePath}/assets/js/preview.js"></script><script>var fields = ${JSON.stringify(data.properties)};</script>`,
+    script:
+      `${globalScriptTag ? `${globalScriptTag}\n` : ''}` +
+      `${componentScriptTag ? `${componentScriptTag}\n` : ''}` +
+      `<script src="${basePath}/assets/js/preview.js"></script><script>var fields = ${JSON.stringify(data.properties)};</script>`,
     properties: previewData.values || {},
     fields: data.properties,
     title: data.title,

package/src/types/config.ts

@@ -3,7 +3,7 @@ import type Handlebars from 'handlebars';
 import { Types as HandoffTypes } from 'handoff-core';
 import { InlineConfig } from 'vite';
 import { SlotMetadata } from '../transformers/preview/component';
-import { ComponentListObject, PatternListObject, TransformComponentTokensResult } from '../transformers/preview/types';
+import { ComponentListObject, PageListObject, PatternListObject, TransformComponentTokensResult } from '../transformers/preview/types';
 import { ValidationResult } from './preview';
 
 export interface ImageStyle {
@@ -80,6 +80,102 @@ export interface NextAppConfig {
   };
 }
 
+/**
+ * Configuration for entry points to assets and components that will be built.
+ */
+export interface ConfigEntries {
+  /**
+   * Path to the main SCSS entry file
+   * @example "styles/main.scss"
+   */
+  scss?: string;
+  /**
+   * Path to the main JavaScript entry file
+   * @example "scripts/main.js"
+   */
+  js?: string;
+  /**
+   * Array of component paths to be included in the build
+   * @example ["components/button", "components/input"]
+   */
+  components?: string[];
+  /**
+   * Array of pattern paths to be included in the build.
+   * Patterns compose multiple component previews into single-page views.
+   * @example ["patterns/hero-section", "patterns"]
+   */
+  patterns?: string[];
+}
+
+/** Runtime mode. Resolved solely from `runtime.mode`; never inferred from env vars or connection settings. */
+export type RuntimeMode = 'workspace' | 'registry';
+
+/** Format used when synthesizing local workspace declarations. */
+export type DeclarationFormat = 'ts' | 'js' | 'cjs' | 'json';
+
+/**
+ * User-facing `runtime` configuration block. A single optional block that selects the runtime
+ * mode and carries mode-specific host/connection settings.
+ *
+ * Note: this is the authored shape. {@link RuntimeConfig} is the separate, resolved post-discovery
+ * shape used internally by the build/runtime.
+ */
+export interface HandoffRuntimeConfig {
+  /**
+   * The sole determinant of runtime mode. Defaults to `'workspace'` when omitted.
+   * Mode is never inferred from environment variables, database settings, or token presence.
+   */
+  mode?: RuntimeMode;
+  /** Workspace-mode settings. */
+  workspace?: {
+    entries?: ConfigEntries;
+    declarationFormat?: DeclarationFormat;
+  };
+  /** Registry-mode host settings. Env-var values are stored as names, never as secrets. */
+  registry?: {
+    /** Name of the env var holding the database URL. @default "DATABASE_URL" */
+    databaseUrlEnv?: string;
+    /** Name of the env var holding the registry API token. @default "HANDOFF_REGISTRY_API_TOKEN" */
+    apiTokenEnv?: string;
+    database?: {
+      /** @default "pg" */
+      adapter?: 'pg' | 'neon';
+    };
+    /**
+     * Where published asset blobs (icons/logos/fonts/sprites/archives) are stored. Defaults to the
+     * built-in PostgreSQL `bytea` store when omitted. Secrets are never persisted here - only the
+     * *names* of the env vars their values are read from at request time.
+     */
+    assetStorage?: {
+      /**
+       * Active storage provider for new uploads. `database` keeps bytes inline in Postgres; use the
+       * pre-packaged `vercel-blob` adapter or a `custom` module for object storage.
+       * @default "database"
+       */
+      adapter?: 'database' | 'vercel-blob' | 'custom';
+      /** For `adapter: "custom"` - server-only module path default-exporting a `defineAssetStorage` adapter. */
+      module?: string;
+      /** For `adapter: "vercel-blob"` - env var name holding the Blob read/write token. @default "BLOB_READ_WRITE_TOKEN" */
+      tokenEnv?: string;
+      /** Max bytes kept inline in the database `bytea` column (larger uploads are rejected). @default 4194304 */
+      maxInlineBytes?: number;
+      /** Non-secret adapter options (bucket env-var names, region, a custom `providerId`, …). */
+      options?: Record<string, unknown>;
+    };
+  };
+  /**
+   * Connected-workspace settings pointing at a remote registry. A connected workspace is
+   * `mode: 'workspace'` plus this block — it is not a third runtime mode.
+   */
+  registryConnection?: {
+    url?: string;
+    /** @default "HANDOFF_REGISTRY_URL" */
+    urlEnv?: string;
+    /** @default "HANDOFF_REGISTRY_ACCESS_TOKEN" */
+    accessTokenEnv?: string;
+  };
+}
+
 export interface Config {
   dev_access_token?: string | null | undefined;
   devAccessToken?: string | null | undefined;
@@ -108,32 +204,15 @@ export interface Config {
    * Configuration for the build pipeline
    */
   pipeline?: PipelineConfig;
+  /**
+   * Runtime configuration. `runtime.mode` is the sole determinant of runtime mode
+   * (`workspace` | `registry`), defaulting to `workspace` when omitted.
+   */
+  runtime?: HandoffRuntimeConfig;
   /**
    * Configuration for entry points to assets and components that will be built
    */
-  entries?: {
-    /**
-     * Path to the main SCSS entry file
-     * @example "styles/main.scss"
-     */
-    scss?: string;
-    /**
-     * Path to the main JavaScript entry file
-     * @example "scripts/main.js"
-     */
-    js?: string;
-    /**
-     * Array of component paths to be included in the build
-     * @example ["components/button", "components/input"]
-     */
-    components?: string[];
-    /**
-     * Array of pattern paths to be included in the build.
-     * Patterns compose multiple component previews into single-page views.
-     * @example ["patterns/hero-section", "patterns"]
-     */
-    patterns?: string[];
-  };
+  entries?: ConfigEntries;
   /**
    * Configuration for asset zip file download links
    * @default { icons: "/icons.zip", logos: "/logos.zip" }
@@ -286,7 +365,23 @@ export interface Config {
   };
 }
 
-export type ClientConfig = Pick<Config, 'app' | 'exportsOutputDirectory' | 'sitesOutputDirectory' | 'assets_zip_links' | 'useVariables'>;
+/**
+ * Non-secret runtime values projected to the browser. Only the resolved {@link RuntimeMode}
+ * crosses to the client; secrets and connection values never do.
+ */
+export interface ClientRuntimeConfig {
+  mode: RuntimeMode;
+  /**
+   * True when the runtime is a connected workspace (`mode: 'workspace'` plus a resolvable
+   * `registryConnection` URL). Non-secret: it never carries the URL or token value, only whether a
+   * connection is configured. Drives the workspace-only publish affordance in the docs UI.
+   */
+  connected: boolean;
+}
+
+export type ClientConfig = Pick<Config, 'app' | 'exportsOutputDirectory' | 'sitesOutputDirectory' | 'assets_zip_links' | 'useVariables'> & {
+  runtime: ClientRuntimeConfig;
+};
 
 export interface RuntimeConfigComponentOptions {
   cssRootClass?: string;
@@ -313,6 +408,9 @@ export interface RuntimeConfig {
     patterns: {
       [id: string]: PatternListObject;
     };
+    pages: {
+      [id: string]: PageListObject;
+    };
   };
   options: {
     [key: string]: RuntimeConfigComponentOptions;