@olonjs/core 1.0.127 → 1.1.2

package/dist/runtime.d.ts

@@ -0,0 +1,1117 @@
+import { ClassValue } from 'clsx';
+import { Component } from 'react';
+import { Context } from 'react';
+import { default as default_2 } from 'react';
+import { ErrorInfo } from 'react';
+import { JSX } from 'react/jsx-runtime';
+import { LucideIcon } from 'lucide-react';
+import { ReactNode } from 'react';
+import { z } from 'zod';
+
+export declare interface AddSectionConfig {
+    addableSectionTypes?: string[];
+    sectionTypeLabels?: Record<string, string>;
+    getDefaultSectionData?: (sectionType: string) => Record<string, unknown>;
+}
+
+export declare const AddSectionLibrary: default_2.FC<AddSectionLibraryProps>;
+
+declare interface AddSectionLibraryProps {
+    open: boolean;
+    onClose: () => void;
+    /** Section type ids that can be added (e.g. from config.addSection.addableSectionTypes or derived). */
+    sectionTypes: string[];
+    /** Optional display label per type; falls back to humanized type id. */
+    sectionTypeLabels?: Record<string, string>;
+    onSelect: (sectionType: string) => void;
+}
+
+export declare namespace admin {
+    export {
+        AddSectionLibrary,
+        AdminSidebar,
+        LayerItem,
+        FormFactory,
+        InputWidgets,
+        WidgetType,
+        PageSelector,
+        PreviewEntry,
+        buildSelectionPath,
+        StudioStage
+    }
+}
+
+export declare const AdminSidebar: default_2.FC<AdminSidebarProps>;
+
+declare interface AdminSidebarProps {
+    selectedSection: SelectedSectionInfo | null;
+    pageData: PageConfig | {
+        sections: Section[];
+    };
+    /** All sections (header + page sections + footer) for resolving modal section data. */
+    allSectionsData?: Section[];
+    onUpdate: (newData: Record<string, unknown>) => void;
+    /** Update a section by id/scope (e.g. from settings modal). When provided with allSectionsData, gear opens modal. */
+    onUpdateSection?: OnUpdateSection;
+    onClose: () => void;
+    /** Root-to-leaf path for deep focus (e.g. silos -> blocks). When null, no canvas selection. */
+    expandedItemPath?: Array<{
+        fieldKey: string;
+        itemId?: string;
+    }> | null;
+    onReorderSection?: (sectionId: string, newIndex: number) => void;
+    allLayers?: LayerItem[];
+    activeSectionId?: string | null;
+    onRequestScrollToSection?: (sectionId: string) => void;
+    onDeleteSection?: (sectionId: string) => void;
+    /** When provided, shows an "Add section" button in the inspector header that opens the section library. */
+    onAddSection?: () => void;
+    /** Whether there are unsaved changes for the current draft. */
+    hasChanges?: boolean;
+    /** Save to file (writes JSON to repo via server). */
+    onSaveToFile?: () => void;
+    /** Hot Save callback (typically cloud save2edge). */
+    onHotSave?: () => void;
+    /** Cold Save callback (typically save2repo / deploy pipeline). */
+    onColdSave?: () => void;
+    /** When true, show "Salvato" in the status bar (e.g. for 2s after save-to-file succeeds). */
+    saveSuccessFeedback?: boolean;
+    /** When true, show "Saved" feedback for hot save (e.g. for 2s after success). */
+    hotSaveSuccessFeedback?: boolean;
+    /** When true, hot save action is currently running. */
+    hotSaveInProgress?: boolean;
+    /** Controls visibility of the local Save button. */
+    showLocalSave?: boolean;
+    /** Controls visibility of Hot Save button. */
+    showHotSave?: boolean;
+    /** Controls visibility of Save2Repo / Cold Save button. */
+    showColdSave?: boolean;
+    /** Restore page from file (resets in-memory draft for current slug). Hidden by default; set showResetToFile to display. */
+    onResetToFile?: () => void;
+    /** When true, shows the "Ripristina da file" button (default false = hidden). */
+    showResetToFile?: boolean;
+    /** Available page slugs. When length > 0 and onPageChange set, shows page selector under Inspector header. */
+    pageSlugs?: string[];
+    /** Current page slug. */
+    currentSlug?: string;
+    /** Called when user selects another page; engine should navigate to /admin/:slug. */
+    onPageChange?: (slug: string) => void;
+}
+
+export declare function applyValueAtSelectionPath(rootData: Record<string, unknown>, selectionPath: SelectionPath, value: unknown): Record<string, unknown>;
+
+export declare interface AssetsConfig {
+    assetsBaseUrl?: string;
+    assetsManifest?: LibraryImageEntry[];
+    /**
+     * Uploads an image and returns the final canonical URL that must be persisted in JSON.
+     *
+     * Valid examples:
+     * - /assets/images/foo.png
+     * - /assets/tenant-a/foo.png
+     * - https://cdn.example.com/foo.png
+     *
+     * Invalid examples:
+     * - public/assets/foo.png
+     * - C:\\foo\\bar.png
+     * - data:image/png;base64,...
+     */
+    onAssetUpload?: (file: File) => Promise<string>;
+}
+
+export declare const BaseArrayItem: z.ZodObject<{
+    id: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    id?: string | undefined;
+}, {
+    id?: string | undefined;
+}>;
+
+export declare interface BaseSection<K extends keyof SectionDataRegistry> {
+    id: string;
+    type: K;
+    data: SectionDataRegistry[K];
+    settings?: K extends keyof SectionSettingsRegistry ? SectionSettingsRegistry[K] : BaseSectionSettings;
+}
+
+/**
+ * Base schemas shared by section capsules (CIP governance).
+ * Capsules extend these for consistent anchorId, array items, and settings.
+ */
+export declare const BaseSectionData: z.ZodObject<{
+    id: z.ZodOptional<z.ZodString>;
+    anchorId: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    id?: string | undefined;
+    anchorId?: string | undefined;
+}, {
+    id?: string | undefined;
+    anchorId?: string | undefined;
+}>;
+
+/**
+ * KERNEL: The Base Contract (MTRP)
+ * Core is self-contained; structural types live here.
+ */
+export declare interface BaseSectionSettings {
+    [key: string]: unknown;
+}
+
+export declare const BaseSectionSettingsSchema: z.ZodObject<{
+    paddingTop: z.ZodDefault<z.ZodEnum<["none", "sm", "md", "lg", "xl", "2xl"]>>;
+    paddingBottom: z.ZodDefault<z.ZodEnum<["none", "sm", "md", "lg", "xl", "2xl"]>>;
+    theme: z.ZodDefault<z.ZodEnum<["dark", "light", "accent"]>>;
+    container: z.ZodDefault<z.ZodEnum<["boxed", "fluid"]>>;
+}, "strip", z.ZodTypeAny, {
+    paddingTop: "none" | "sm" | "md" | "lg" | "xl" | "2xl";
+    paddingBottom: "none" | "sm" | "md" | "lg" | "xl" | "2xl";
+    theme: "dark" | "light" | "accent";
+    container: "boxed" | "fluid";
+}, {
+    paddingTop?: "none" | "sm" | "md" | "lg" | "xl" | "2xl" | undefined;
+    paddingBottom?: "none" | "sm" | "md" | "lg" | "xl" | "2xl" | undefined;
+    theme?: "dark" | "light" | "accent" | undefined;
+    container?: "boxed" | "fluid" | undefined;
+}>;
+
+/**
+ * Shared types between Admin Engine and Input Registry.
+ */
+export declare interface BaseWidgetProps<T = unknown> {
+    label: string;
+    value: T;
+    onChange: (val: T) => void;
+    options?: string[];
+}
+
+declare function buildLlmsTxt(input: BuildSiteManifestInput): string;
+
+declare function buildPageContract({ slug, pageConfig, schemas, submissionSchemas, siteConfig, }: BuildPageContractInput): OlonJsPageContract;
+
+export declare function buildPageContractHref(slug: string): string;
+
+declare interface BuildPageContractInput {
+    slug: string;
+    pageConfig: PageConfig;
+    schemas: JsonPagesConfig['schemas'];
+    submissionSchemas?: JsonPagesConfig['submissionSchemas'];
+    siteConfig: SiteConfig;
+}
+
+declare function buildPageManifest(input: BuildPageContractInput): OlonJsPageManifest;
+
+export declare function buildPageManifestHref(slug: string): string;
+
+declare function buildSelectionPath(root: HTMLElement, sectionEl: HTMLElement): SelectionPath;
+
+declare function buildSiteManifest({ pages, schemas, submissionSchemas, siteConfig, }: BuildSiteManifestInput): OlonJsSiteManifestIndex;
+
+declare interface BuildSiteManifestInput {
+    pages: Record<string, PageConfig>;
+    schemas: JsonPagesConfig['schemas'];
+    submissionSchemas?: JsonPagesConfig['submissionSchemas'];
+    siteConfig: SiteConfig;
+}
+
+export declare function buildThemeVariableMap(theme: ThemeConfig): Record<string, string>;
+
+export declare function buildWebMcpSaveToolName(): string;
+
+export declare function buildWebMcpToolName(): string;
+
+export declare function cn(...inputs: ClassValue[]): string;
+
+export declare interface ConfigContextValue {
+    registry: Registry;
+    schemas: Schemas;
+    tenantId?: string;
+    basePath?: string;
+    assets?: AssetsConfig;
+    overlayDisabledSectionTypes?: string[];
+}
+
+export declare const ConfigProvider: default_2.FC<{
+    config: Pick<JsonPagesConfig, 'registry' | 'schemas' | 'tenantId' | 'basePath' | 'assets' | 'overlayDisabledSectionTypes'>;
+    children: default_2.ReactNode;
+}>;
+
+export declare namespace contract {
+    export {
+        shouldRenderSiteGlobalHeader,
+        BaseSectionSettings,
+        SectionDataRegistry,
+        SectionSettingsRegistry,
+        BaseSection,
+        FallbackSection,
+        Section,
+        SectionType,
+        MenuItem,
+        MenuConfig,
+        PageMeta,
+        PageConfig,
+        SiteIdentity,
+        SiteConfig,
+        ThemeTokenMap,
+        ThemeColors,
+        ThemeFontFamily,
+        ThemeTypography,
+        ThemeBorderRadius,
+        ThemeTokens,
+        ThemeConfig,
+        ProjectState,
+        PageRendererProps,
+        SelectionPathSegment,
+        SelectionPath,
+        PersistenceConfig,
+        ThemeCssConfig,
+        AddSectionConfig,
+        LibraryImageEntry,
+        AssetsConfig,
+        WebMcpConfig,
+        JsonPagesConfig,
+        resolveHeaderMenuItems,
+        resolveSectionMenuItems,
+        resolveRuntimeConfig,
+        RefDocuments,
+        buildPageContractHref,
+        buildPageManifestHref,
+        buildPageContract,
+        buildPageManifest,
+        buildSiteManifest,
+        buildLlmsTxt,
+        WebMcpToolContract,
+        WebMcpSectionInstance,
+        OlonJsPageContract,
+        OlonJsPageManifest,
+        OlonJsSiteManifestIndex,
+        BuildPageContractInput,
+        BuildSiteManifestInput,
+        BaseWidgetProps
+    }
+}
+
+export declare function createWebMcpSaveToolInputSchema(): Record<string, unknown>;
+
+export declare function createWebMcpToolInputSchema(): Record<string, unknown>;
+
+export declare const CtaSchema: z.ZodObject<{
+    id: z.ZodOptional<z.ZodString>;
+    label: z.ZodString;
+    href: z.ZodString;
+    variant: z.ZodDefault<z.ZodEnum<["primary", "secondary", "accent"]>>;
+}, "strip", z.ZodTypeAny, {
+    label: string;
+    href: string;
+    variant: "accent" | "primary" | "secondary";
+    id?: string | undefined;
+}, {
+    label: string;
+    href: string;
+    id?: string | undefined;
+    variant?: "accent" | "primary" | "secondary" | undefined;
+}>;
+
+export declare const DefaultNotFound: default_2.FC;
+
+export declare const DEPLOY_STEPS: readonly DeployStep[];
+
+export declare type DeployPhase = 'idle' | 'running' | 'done' | 'error';
+
+export declare interface DeployStep {
+    id: StepId;
+    label: string;
+    verb: string;
+    poem: [string, string];
+    color: string;
+    glyph: string;
+    duration: number;
+}
+
+/**
+ * Engine-level error boundary: prevents black screen on any render error
+ * and surfaces a visible error UI.
+ */
+export declare class EngineErrorBoundary extends Component<{
+    children: ReactNode;
+}, {
+    hasError: boolean;
+    error: Error | null;
+}> {
+    constructor(props: {
+        children: ReactNode;
+    });
+    static getDerivedStateFromError(error: Error): {
+        hasError: boolean;
+        error: Error;
+    };
+    componentDidCatch(error: Error, errorInfo: ErrorInfo): void;
+    render(): string | number | bigint | boolean | JSX.Element | Iterable<default_2.ReactNode> | Promise<string | number | bigint | boolean | default_2.ReactPortal | default_2.ReactElement<unknown, string | default_2.JSXElementConstructor<any>> | Iterable<default_2.ReactNode> | null | undefined> | null | undefined;
+}
+
+export declare function ensureWebMcpRuntime(): void;
+
+/** Structural shape used when no tenant has augmented the registries. */
+export declare interface FallbackSection {
+    id: string;
+    type: string;
+    data: Record<string, unknown>;
+    settings?: Record<string, unknown>;
+}
+
+export declare const FormFactory: default_2.FC<FormFactoryProps>;
+
+declare interface FormFactoryProps {
+    schema: z.ZodObject<z.ZodRawShape>;
+    data: Record<string, unknown>;
+    onChange: (newData: Record<string, unknown>) => void;
+    /** When set, only render fields whose key is in this array (e.g. Content vs Settings tabs). */
+    keys?: string[] | null;
+    /** Root-to-leaf path for deep focus (e.g. silos -> blocks). First segment applies to this level. */
+    expandedItemPath?: Array<{
+        fieldKey: string;
+        itemId?: string;
+    }> | null;
+    /** Called when user expands/collapses an array item in the sidebar (so parent can drive fade). */
+    onSidebarExpandedItemChange?: (item: {
+        fieldKey: string;
+        itemId?: string;
+    } | null) => void;
+}
+
+export declare interface FormState {
+    status: FormStatus;
+    message: string;
+}
+
+export declare type FormStatus = 'idle' | 'submitting' | 'success' | 'error';
+
+/**
+ * Image picker field: object { url, alt? } with ui:image-picker for Form Factory.
+ * Use in section data and resolve with resolveAssetUrl(url, tenantId) in View.
+ */
+export declare const ImageSelectionSchema: z.ZodObject<{
+    url: z.ZodString;
+    alt: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    url: string;
+    alt?: string | undefined;
+}, {
+    url: string;
+    alt?: string | undefined;
+}>;
+
+export declare const InputWidgets: {
+    readonly 'ui:text': ({ label, value, onChange }: BaseWidgetProps<string>) => JSX.Element;
+    readonly 'ui:textarea': ({ label, value, onChange }: BaseWidgetProps<string>) => JSX.Element;
+    readonly 'ui:select': ({ label, value, onChange, options }: BaseWidgetProps<string>) => JSX.Element;
+    readonly 'ui:checkbox': ({ label, value, onChange }: BaseWidgetProps<boolean>) => JSX.Element;
+    readonly 'ui:image-picker': ({ label, value, onChange }: BaseWidgetProps<unknown>) => JSX.Element;
+    readonly 'ui:icon-picker': ({ label, value, onChange }: BaseWidgetProps<string>) => JSX.Element;
+};
+
+export declare const isCanonicalAssetUrl: (path: string) => boolean;
+
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+
+export declare const isTransientAssetUrl: (path: string) => boolean;
+
+export declare interface JsonPagesConfig {
+    tenantId: string;
+    basePath?: string;
+    registry: Record<string, default_2.ComponentType<unknown>>;
+    schemas: Record<string, {
+        parse: (v: unknown) => unknown;
+        shape?: Record<string, unknown>;
+    }>;
+    /**
+     * Optional registry of Zod submission schemas for sections that can be filled
+     * by external agents (e.g. MCP-connected AI clients).
+     *
+     * Keyed by the same section-type strings used in `schemas`. Each value is a
+     * Zod schema describing the section's *submission payload* (what the user
+     * fills in) — distinct from `schemas` entries, which describe the section's
+     * *UI configuration* (how the tenant author configures the section).
+     *
+     * When a section type appears on a page AND has an entry here, its JSON
+     * Schema representation is emitted on the page contract as
+     * `sectionSubmissionSchemas` (see `OlonJsPageContract`).
+     *
+     * The shape mirrors `schemas` (duck-typed on `{ parse, shape? }`) so core
+     * does not force `zod` on consumers at the type level. In practice tenants
+     * pass `z.object(...)` instances; the JSON Schema serializer casts to
+     * `z.ZodTypeAny` at its own boundary.
+     *
+     * See `docs/decisions/ADR-0002-form-submission-schemas.md` for rationale,
+     * tenant convention, and the full emission contract.
+     */
+    submissionSchemas?: Record<string, {
+        parse: (v: unknown) => unknown;
+        shape?: Record<string, unknown>;
+    }>;
+    pages: Record<string, PageConfig>;
+    siteConfig: SiteConfig;
+    themeConfig: ThemeConfig;
+    menuConfig: MenuConfig;
+    refDocuments?: Record<string, unknown>;
+    persistence?: Partial<PersistenceConfig>;
+    themeCss: ThemeCssConfig;
+    NotFoundComponent?: default_2.ComponentType;
+    addSection?: AddSectionConfig;
+    assets?: AssetsConfig;
+    overlayDisabledSectionTypes?: string[];
+    webmcp?: WebMcpConfig;
+    iconRegistry?: Record<string, LucideIcon>;
+}
+
+export declare function JsonPagesEngine({ config }: JsonPagesEngineProps): JSX.Element;
+
+export declare interface JsonPagesEngineProps {
+    config: JsonPagesConfig;
+}
+
+export declare namespace kernel {
+    export {
+        resolveHeaderMenuItems,
+        resolveRuntimeConfig,
+        resolveSectionMenuItems,
+        shouldRenderSiteGlobalHeader,
+        BaseSectionSettings,
+        SectionDataRegistry,
+        SectionSettingsRegistry,
+        BaseSection,
+        FallbackSection,
+        Section,
+        SectionType,
+        MenuItem,
+        MenuConfig,
+        PageMeta,
+        PageConfig,
+        SiteIdentity,
+        SiteConfig,
+        ThemeTokenMap,
+        ThemeColors,
+        ThemeFontFamily,
+        ThemeTypography,
+        ThemeBorderRadius,
+        ThemeTokens,
+        ThemeConfig,
+        ProjectState,
+        PageRendererProps,
+        SelectionPathSegment,
+        SelectionPath,
+        PersistenceConfig,
+        ThemeCssConfig,
+        AddSectionConfig,
+        LibraryImageEntry,
+        AssetsConfig,
+        WebMcpConfig,
+        JsonPagesConfig,
+        BaseWidgetProps
+    }
+}
+
+export declare interface LayerItem {
+    id: string;
+    type: string;
+    scope: string;
+    title?: string;
+}
+
+export declare interface LibraryImageEntry {
+    id: string;
+    url: string;
+    alt: string;
+    tags?: string[];
+}
+
+export declare interface MenuConfig {
+    main?: MenuItem[];
+    [key: string]: MenuItem[] | undefined;
+}
+
+export declare interface MenuItem {
+    label: string;
+    href: string;
+    icon?: string;
+    external?: boolean;
+    isCta?: boolean;
+    children?: MenuItem[];
+}
+
+export declare function normalizeBasePath(value?: string): string;
+
+export declare function normalizeSlugSegments(value: string): string;
+
+/**
+ * Context holding the submission state of every olon-managed form,
+ * keyed by the form's id attribute (or anchorId).
+ * Provided by App.tsx via useOlonForms().
+ */
+export declare const OlonFormsContext: Context<Record<string, FormState>>;
+
+export declare function OlonJSEngine({ config }: OlonJSEngineProps): JSX.Element;
+
+export declare interface OlonJSEngineProps {
+    config: JsonPagesConfig;
+}
+
+declare interface OlonJsPageContract {
+    version: '1.0.0';
+    kind: 'olonjs-page-contract';
+    slug: string;
+    title: string;
+    description: string;
+    manifestHref: string;
+    systemPrompt: string;
+    sectionTypes: string[];
+    sectionInstances: WebMcpSectionInstance[];
+    sectionSchemas: Record<string, Record<string, unknown>>;
+    /**
+     * Optional JSON Schema representations of submission payloads for form-capable
+     * sections present on this page. Keyed by section type.
+     *
+     * Emitted only for section types that (a) actually appear on this page AND
+     * (b) have an entry in `JsonPagesConfig.submissionSchemas`. Absent (not `{}`)
+     * when no section on the page qualifies, to keep the contract tight.
+     *
+     * MCP agents consuming this contract can discover form shapes directly from
+     * reading the page, without requiring a separate tool call.
+     *
+     * See `docs/decisions/ADR-0002-form-submission-schemas.md` (emission contract).
+     */
+    sectionSubmissionSchemas?: Record<string, Record<string, unknown>>;
+    tools: WebMcpToolContract[];
+}
+
+declare interface OlonJsPageManifest {
+    version: '1.0.0';
+    kind: 'olonjs-page-mcp-manifest';
+    generatedAt: string;
+    slug: string;
+    title: string;
+    description: string;
+    contractHref: string;
+    transport: {
+        kind: 'window-message';
+        requestType: string;
+        resultType: string;
+        target: 'window';
+    };
+    capabilities: {
+        resources: Array<{
+            uri: string;
+            name: string;
+            mimeType: string;
+            description: string;
+        }>;
+    };
+    sectionTypes: string[];
+    sectionInstances: WebMcpSectionInstance[];
+    tools: Array<Pick<WebMcpToolContract, 'name' | 'description'>>;
+}
+
+declare interface OlonJsSiteManifestIndex {
+    version: '1.0.0';
+    kind: 'olonjs-mcp-manifest-index';
+    generatedAt: string;
+    pages: Array<{
+        slug: string;
+        title: string;
+        description: string;
+        manifestHref: string;
+        contractHref: string;
+        sectionTypes: string[];
+    }>;
+}
+
+/** Used by the section-settings modal to update a section without changing Inspector selection. */
+export declare type OnUpdateSection = (sectionId: string, scope: 'global' | 'local', sectionType: string, newData: Record<string, unknown>) => void;
+
+export declare interface PageConfig {
+    id: string;
+    slug: string;
+    meta: PageMeta;
+    sections: Section[];
+    /** When `false`, Core does not render the global header from `site.json` for this page. Omitted = default (show if configured). */
+    'global-header'?: boolean;
+}
+
+export declare interface PageMeta {
+    title: string;
+    description: string;
+}
+
+export declare const PageRenderer: default_2.FC<Props>;
+
+export declare interface PageRendererProps {
+    pageConfig: PageConfig;
+    siteConfig: SiteConfig;
+    menuConfig: MenuConfig;
+    selectedId?: string | null;
+}
+
+/**
+ * Enterprise-grade page switcher: popover trigger + list, a11y, single source of styling.
+ * Use in Inspector header when multiple pages exist and onPageChange is provided.
+ */
+declare const PageSelector: default_2.FC<PageSelectorProps>;
+
+declare interface PageSelectorProps {
+    /** Available page slugs. */
+    pageSlugs: string[];
+    /** Current page slug. */
+    currentSlug: string;
+    /** Called when user selects another page. */
+    onPageChange: (slug: string) => void;
+    /** Optional: show section count per page (e.g. "9s"). Omit to hide. */
+    sectionCount?: number;
+    /** Optional: when set, shows "New page" and calls this on click. Omit to hide (no dead UI). */
+    onNewPage?: () => void;
+    /** Optional class for the wrapper (e.g. spacing). */
+    className?: string;
+    /** Optional: override label for current page (default: capitalized slug). */
+    currentPageLabel?: string;
+}
+
+export declare function parseWebMcpMutationArgs(rawArgs: unknown): WebMcpMutationArgs;
+
+export declare interface PersistenceConfig {
+    saveToFile?: (state: ProjectState, slug: string) => Promise<void>;
+    hotSave?: (state: ProjectState, slug: string) => Promise<void>;
+    coldSave?: (state: ProjectState, slug: string) => Promise<void>;
+    showLocalSave?: boolean;
+    showHotSave?: boolean;
+    showColdSave?: boolean;
+    flushUploadedAssets?: (urls: string[]) => Promise<Record<string, string>>;
+}
+
+export declare const PreviewEntry: default_2.FC;
+
+export declare const PreviewRoute: default_2.FC<PreviewRouteProps>;
+
+export declare interface PreviewRouteProps {
+    tenantCss: string;
+    adminCss: string;
+}
+
+/**
+ * PROJECT STATE (The Universal Data Bundle)
+ * Moved to Kernel to serve as SSOT for Engine and Persistence.
+ */
+export declare interface ProjectState {
+    page: PageConfig;
+    site: SiteConfig;
+    menu: MenuConfig;
+    theme: ThemeConfig;
+}
+
+declare type Props = PageRendererProps & {
+    onReorder?: (sectionId: string, newIndex: number) => void;
+    scrollToSectionId?: string | null;
+    onActiveSectionChange?: (sectionId: string | null) => void;
+};
+
+declare type RefDocuments = NonNullable<JsonPagesConfig['refDocuments']>;
+
+export declare function registerWebMcpTool(tool: WebMcpTool): () => void;
+
+declare type Registry = JsonPagesConfig['registry'];
+
+export declare const resolveAssetUrl: (path: string, tenantId?: string, basePath?: string) => string;
+
+export declare function resolveHeaderMenuItems(headerData: unknown, fallbackMain: MenuItem[]): MenuItem[];
+
+export declare function resolveMenuMainFromHeaderData(headerData: unknown, fallbackMain: MenuItem[]): MenuItem[];
+
+export declare function resolvePageFromRegistry(pageRegistry: Record<string, PageConfig>, requestedSlug: string): PageConfig | undefined;
+
+export declare function resolveRuntimeConfig(input: RuntimeResolutionInput): RuntimeResolutionResult;
+
+export declare function resolveSectionMenuItems(section: Section, fallbackMain: MenuItem[]): MenuItem[] | undefined;
+
+export declare function resolveSlugFromPathname(pathname: string, prefix?: string): string;
+
+export declare function resolveWebMcpMutationData(currentData: Record<string, unknown>, args: WebMcpMutationArgs): Record<string, unknown>;
+
+export declare namespace runtime {
+    export {
+        PageRenderer,
+        SectionRenderer,
+        JsonPagesEngine,
+        JsonPagesEngineProps,
+        StudioProvider,
+        useStudio,
+        ConfigProvider,
+        useConfig,
+        ConfigContextValue,
+        ThemeLoader,
+        ThemeLoaderProps,
+        DefaultNotFound,
+        STUDIO_EVENTS,
+        EngineErrorBoundary,
+        OlonJSEngine,
+        OlonJSEngineProps,
+        PreviewRoute,
+        PreviewRouteProps,
+        StudioRoute,
+        StudioRouteProps,
+        VisitorRoute,
+        VisitorRouteProps,
+        buildPageContractHref,
+        buildPageManifestHref,
+        syncHeadLink,
+        syncWebMcpJsonLd,
+        isRecord,
+        normalizeSlugSegments,
+        resolveMenuMainFromHeaderData,
+        resolvePageFromRegistry,
+        resolveSlugFromPathname,
+        isCanonicalAssetUrl,
+        isTransientAssetUrl,
+        resolveAssetUrl,
+        useDocumentMeta,
+        buildThemeVariableMap,
+        themeManager,
+        normalizeBasePath,
+        withBasePath
+    }
+}
+
+declare interface RuntimeResolutionInput {
+    pages: Record<string, PageConfig>;
+    siteConfig: SiteConfig;
+    themeConfig: ThemeConfig;
+    menuConfig: MenuConfig;
+    refDocuments?: JsonPagesConfig['refDocuments'];
+}
+
+declare interface RuntimeResolutionResult {
+    pages: Record<string, PageConfig>;
+    siteConfig: SiteConfig;
+    themeConfig: ThemeConfig;
+    menuConfig: MenuConfig;
+}
+
+declare interface SaveStreamDoneEvent {
+    deployUrl?: string;
+    commitSha?: string;
+}
+
+declare interface SaveStreamLogEvent {
+    stepId: StepId;
+    message: string;
+}
+
+declare interface SaveStreamStepEvent {
+    id: StepId;
+    status: 'running' | 'done';
+    label?: string;
+}
+
+declare type Schemas = JsonPagesConfig['schemas'];
+
+/** Computed union of all registered section types. */
+export declare type Section = keyof SectionDataRegistry extends never ? FallbackSection : {
+    [K in keyof SectionDataRegistry]: BaseSection<K>;
+}[keyof SectionDataRegistry];
+
+export declare interface SectionDataRegistry {
+}
+
+export declare const SectionRenderer: default_2.FC<SectionRendererProps>;
+
+declare interface SectionRendererProps {
+    section: Section;
+    menu?: MenuItem[];
+    selectedId?: string | null;
+    reorderable?: boolean;
+    sectionIndex?: number;
+    totalSections?: number;
+    onReorder?: (sectionId: string, newIndex: number) => void;
+}
+
+export declare interface SectionSettingsRegistry {
+}
+
+export declare type SectionType = keyof SectionDataRegistry extends never ? string : keyof SectionDataRegistry;
+
+declare interface SelectedSectionInfo {
+    id: string;
+    type: string;
+    scope: string;
+}
+
+export declare type SelectionPath = SelectionPathSegment[];
+
+export declare interface SelectionPathSegment {
+    fieldKey: string;
+    itemId?: string;
+}
+
+/** Whether the global `site.json` header should be rendered for this page. */
+export declare function shouldRenderSiteGlobalHeader(page: PageConfig, site: SiteConfig): boolean;
+
+export declare interface SiteConfig {
+    identity: SiteIdentity;
+    header?: Section;
+    footer: Section;
+}
+
+export declare interface SiteIdentity {
+    title: string;
+    logoUrl?: string;
+}
+
+export declare function startCloudSaveStream(input: StartCloudSaveStreamInput): Promise<void>;
+
+declare interface StartCloudSaveStreamInput {
+    apiBaseUrl: string;
+    apiKey: string;
+    path: string;
+    content: unknown;
+    message?: string;
+    signal?: AbortSignal;
+    onStep: (event: SaveStreamStepEvent) => void;
+    onLog?: (event: SaveStreamLogEvent) => void;
+    onDone: (event: SaveStreamDoneEvent) => void;
+}
+
+export declare type StepId = 'commit' | 'push' | 'build' | 'live';
+
+export declare type StepState = 'pending' | 'active' | 'done';
+
+export declare namespace studio {
+    export {
+        STUDIO_EVENTS,
+        StudioProvider,
+        useStudio,
+        admin
+    }
+}
+
+export declare const STUDIO_EVENTS: {
+    readonly UPDATE_DRAFTS: "jsonpages:update-drafts";
+    readonly SYNC_SELECTION: "jsonpages:sync-selection";
+    readonly SECTION_SELECT: "jsonpages:section-select";
+    readonly INLINE_FIELD_UPDATE: "jsonpages:inline-field-update";
+    readonly INLINE_FLUSHED: "jsonpages:inline-flushed";
+    readonly REQUEST_SCROLL_TO_SECTION: "jsonpages:request-scroll-to-section";
+    readonly REQUEST_INLINE_FLUSH: "jsonpages:request-inline-flush";
+    readonly ACTIVE_SECTION_CHANGED: "jsonpages:active-section-changed";
+    readonly STAGE_READY: "jsonpages:stage-ready";
+    readonly WEBMCP_TOOL_CALL: "olonjs:webmcp:tool-call";
+    readonly WEBMCP_TOOL_RESULT: "olonjs:webmcp:tool-result";
+};
+
+declare interface StudioContextType {
+    mode: StudioMode;
+}
+
+declare type StudioMode = 'visitor' | 'studio';
+
+export declare const StudioProvider: default_2.FC<{
+    mode: StudioMode;
+    children: ReactNode;
+}>;
+
+export declare const StudioRoute: default_2.FC<StudioRouteProps>;
+
+export declare interface StudioRouteProps {
+    pageRegistry: Record<string, PageConfig>;
+    schemas: JsonPagesConfig['schemas'];
+    siteConfig: SiteConfig;
+    menuConfig: MenuConfig;
+    themeConfig: JsonPagesConfig['themeConfig'];
+    refDocuments?: JsonPagesConfig['refDocuments'];
+    tenantCss: string;
+    adminCss: string;
+    addSectionConfig: JsonPagesConfig['addSection'];
+    addableSectionTypes: string[];
+    webMcp?: JsonPagesConfig['webmcp'];
+    saveToFile?: (state: ProjectState, slug: string) => Promise<void>;
+    hotSave?: (state: ProjectState, slug: string) => Promise<void>;
+    coldSave?: (state: ProjectState, slug: string) => Promise<void>;
+    showLocalSave?: boolean;
+    showHotSave?: boolean;
+    showColdSave?: boolean;
+}
+
+/**
+ * 📺 STUDIO STAGE (Full Preview Mode)
+ * Manages the Iframe and the PostMessage protocol.
+ * NOW INCLUDES: Handshake Listener to fix the "Waiting..." race condition.
+ */
+export declare const StudioStage: default_2.FC<StudioStageProps>;
+
+declare interface StudioStageProps {
+    draft: PageConfig;
+    globalDraft: SiteConfig;
+    menuConfig: MenuConfig;
+    themeConfig: ThemeConfig;
+    slug: string;
+    selectedId?: string | null;
+    scrollToSectionId?: string | null;
+    onScrollRequested?: () => void;
+}
+
+export declare function syncHeadLink(rel: string, href: string): void;
+
+export declare function syncWebMcpJsonLd(title: string, description: string, url: string): void;
+
+export declare interface ThemeBorderRadius {
+    [key: string]: string;
+}
+
+export declare interface ThemeColors {
+    [key: string]: string;
+}
+
+export declare interface ThemeConfig {
+    name: string;
+    tokens: ThemeTokens;
+}
+
+export declare interface ThemeCssConfig {
+    tenant: string;
+    admin?: string;
+}
+
+export declare interface ThemeFontFamily {
+    [key: string]: string | undefined;
+}
+
+export declare const ThemeLoader: default_2.FC<ThemeLoaderProps>;
+
+export declare interface ThemeLoaderProps {
+    mode: 'tenant' | 'admin';
+    tenantCss: string;
+    adminCss: string;
+    children: default_2.ReactNode;
+}
+
+export declare const themeManager: {
+    setTheme: (theme: ThemeConfig) => void;
+};
+
+export declare interface ThemeTokenMap {
+    [key: string]: string;
+}
+
+export declare interface ThemeTokens {
+    colors: ThemeColors;
+    typography: ThemeTypography;
+    borderRadius: ThemeBorderRadius;
+}
+
+export declare interface ThemeTypography {
+    fontFamily: ThemeFontFamily;
+}
+
+export declare function useConfig(): ConfigContextValue;
+
+export declare const useDocumentMeta: (meta: PageMeta) => void;
+
+/**
+ * Read the submission state for a specific form.
+ * @param formId - must match the id attribute on the <form> element.
+ */
+export declare function useFormState(formId: string): FormState;
+
+export declare const useStudio: () => StudioContextType;
+
+export declare const VisitorRoute: default_2.FC<VisitorRouteProps>;
+
+export declare interface VisitorRouteProps {
+    pageRegistry: Record<string, PageConfig>;
+    siteConfig: SiteConfig;
+    menuConfig: MenuConfig;
+    themeConfig: JsonPagesConfig['themeConfig'];
+    refDocuments?: JsonPagesConfig['refDocuments'];
+    tenantCss: string;
+    adminCss: string;
+    NotFoundComponent: default_2.ComponentType;
+}
+
+export declare namespace webmcp {
+    export {
+        applyValueAtSelectionPath,
+        buildWebMcpToolName,
+        buildWebMcpSaveToolName,
+        createWebMcpToolInputSchema,
+        createWebMcpSaveToolInputSchema,
+        ensureWebMcpRuntime,
+        parseWebMcpMutationArgs,
+        registerWebMcpTool,
+        resolveWebMcpMutationData,
+        WebMcpMutationArgs,
+        buildLlmsTxt,
+        buildPageContract,
+        buildPageContractHref,
+        buildPageManifest,
+        buildPageManifestHref,
+        buildSiteManifest,
+        BuildPageContractInput,
+        BuildSiteManifestInput,
+        OlonJsPageContract,
+        OlonJsPageManifest,
+        OlonJsSiteManifestIndex,
+        WebMcpSectionInstance,
+        WebMcpToolContract
+    }
+}
+
+export declare interface WebMcpConfig {
+    enabled?: boolean;
+    namespace?: string;
+}
+
+export declare interface WebMcpMutationArgs {
+    slug?: string;
+    sectionId: string;
+    sectionType?: string;
+    scope?: 'global' | 'local';
+    data?: Record<string, unknown>;
+    itemPath?: SelectionPath;
+    fieldKey?: string;
+    value?: unknown;
+}
+
+declare interface WebMcpSectionInstance {
+    id: string;
+    type: string;
+    scope: 'global' | 'local';
+    label: string;
+}
+
+declare type WebMcpTool = {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+    execute: (args: unknown) => Promise<unknown> | unknown;
+};
+
+declare interface WebMcpToolContract {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+}
+
+export declare type WidgetType = keyof typeof InputWidgets;
+
+export declare function withBasePath(pathname: string, basePath?: string): string;
+
+/**
+ * Mixin for any section capsule that includes a contact form.
+ * Merge into the section data schema to expose recipientEmail
+ * as an editable field in the Studio inspector.
+ * The View must set data-olon-recipient={data.recipientEmail} on the <form>.
+ */
+export declare const WithFormRecipient: z.ZodObject<{
+    recipientEmail: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    recipientEmail?: string | undefined;
+}, {
+    recipientEmail?: string | undefined;
+}>;
+
+export { }