@wabot-dev/framework 0.9.80 → 2.0.0-beta.0

package/dist/src/index.js

@@ -130,6 +130,20 @@ export { socketController } from './feature/socket-controller/metadata/@socketCo
 export { onSocketEvent } from './feature/socket-controller/metadata/@onSocketEvent.js';
 export { SocketControllerMetadataStore } from './feature/socket-controller/metadata/SocketControllerMetadataStore.js';
 export { runSocketControllers } from './feature/socket-controller/runSocketControllers.js';
+export { uiController } from './feature/ui-controller/metadata/@uiController.js';
+export { view } from './feature/ui-controller/metadata/@view.js';
+export { action } from './feature/ui-controller/metadata/@action.js';
+export { uiMiddleware } from './feature/ui-controller/metadata/@uiMiddleware.js';
+export { UiControllerMetadataStore } from './feature/ui-controller/metadata/UiControllerMetadataStore.js';
+export { UiRendererRegistry } from './feature/ui-controller/renderer/UiRendererRegistry.js';
+export { ISLAND_MARKER, getIslandMeta, isIsland, island, setIslandId } from './feature/ui-controller/island/island.js';
+export { deserializeProps, serializeProps } from './feature/ui-controller/island/serialize.js';
+export { ISLAND_FILE_PATTERN, IslandRegistry, isIslandFile, toIslandId } from './feature/ui-controller/island/IslandRegistry.js';
+export { renderDocument } from './feature/ui-controller/document/renderDocument.js';
+export { REDIRECT_MARKER, isRedirect, redirect } from './feature/ui-controller/document/helpers.js';
+export { escapeAttr, escapeHtml } from './feature/ui-controller/document/escape.js';
+export { actionUrl, callAction } from './feature/ui-controller/actions.js';
+export { registerUiControllers, runUiControllers } from './feature/ui-controller/runUiControllers.js';
 export { PgCronJobRepository } from './addon/async/pg/PgCronJobRepository.js';
 export { PgJobRepository } from './addon/async/pg/PgJobRepository.js';
 export { PgTransactionAdapter } from './addon/async/pg/PgTransactionAdapter.js';
@@ -165,6 +179,7 @@ export { PgChatMemory } from './addon/chat-bot/pg/PgChatMemory.js';
 export { InMemoryChatMemory } from './addon/chat-bot/in-memory/InMemoryChatMemory.js';
 export { InMemoryChatRepository } from './addon/chat-bot/in-memory/InMemoryChatRepository.js';
 export { WabotChatAdapter } from './addon/chat-bot/wabot/WabotChatAdapter.js';
+export { XAIChatAdapter } from './addon/chat-bot/xai/XAIChatAdapter.js';
 export { cmd } from './addon/chat-controller/cmd/@cmd.js';
 export { CmdChannel, readJsonFromFile, writeJsonToFile } from './addon/chat-controller/cmd/CmdChannel.js';
 export { CmdChannelConfig } from './addon/chat-controller/cmd/CmdChannelConfig.js';
@@ -172,6 +187,21 @@ export { CmdChannelServer } from './addon/chat-controller/cmd/CmdChannelServer.j
 export { cmdChannelName } from './addon/chat-controller/cmd/cmdChannelName.js';
 export { cmdChannelSocketPath } from './addon/chat-controller/cmd/cmdChannelSocketPath.js';
 export { runCmdClient } from './addon/chat-controller/cmd/runCmdClient.js';
+export { hubspotChannelName } from './addon/chat-controller/hubspot/hubspotChannelName.js';
+export { HubSpotChannelConfig } from './addon/chat-controller/hubspot/HubSpotChannelConfig.js';
+export { verifyHubSpotSignatureV3 } from './addon/chat-controller/hubspot/verifyHubSpotSignatureV3.js';
+export { downloadHubSpotAttachments } from './addon/chat-controller/hubspot/downloadHubSpotAttachments.js';
+export { HubSpotSender } from './addon/chat-controller/hubspot/HubSpotSender.js';
+export { HubSpotWebhookController } from './addon/chat-controller/hubspot/HubSpotWebhookController.js';
+export { HubSpotReceiver } from './addon/chat-controller/hubspot/HubSpotReceiver.js';
+export { HubSpotChannel } from './addon/chat-controller/hubspot/HubSpotChannel.js';
+export { markdownToChatHtml as markdownToHubSpotHtml, markdownToChatHtml as markdownToTelegramHtml } from './addon/chat-controller/markdown/markdownToChatHtml.js';
+export { hubspot } from './addon/chat-controller/hubspot/@hubspot.js';
+export { slack } from './addon/chat-controller/slack/@slack.js';
+export { SlackChannelConfig } from './addon/chat-controller/slack/SlackChannelConfig.js';
+export { SlackChannel } from './addon/chat-controller/slack/SlackChannel.js';
+export { slackChannelName } from './addon/chat-controller/slack/slackChannelName.js';
+export { markdownToSlackMrkdwn } from './addon/chat-controller/slack/markdownToSlackMrkdwn.js';
 export { socket } from './addon/chat-controller/socket/@socket.js';
 export { SocketChannel, SocketChannelMessageFile, SocketChannelReceivedMessage } from './addon/chat-controller/socket/SocketChannel.js';
 export { SocketChannelConfig } from './addon/chat-controller/socket/SocketChannelConfig.js';
@@ -180,7 +210,6 @@ export { telegram } from './addon/chat-controller/telegram/@telegram.js';
 export { TelegramChannelConfig } from './addon/chat-controller/telegram/TelegramChannelConfig.js';
 export { TelegramChannel } from './addon/chat-controller/telegram/TelegramChannel.js';
 export { telegramChannelName } from './addon/chat-controller/telegram/telegramChannelName.js';
-export { markdownToTelegramHtml } from './addon/chat-controller/telegram/markdownToTelegramHtml.js';
 export { WhatsAppReceiverByCloudApi } from './addon/chat-controller/whatsapp/cloud-api/WhatsAppReceiverByCloudApi.js';
 export { WhatsAppApiSender } from './addon/chat-controller/whatsapp/cloud-api/WhatsAppApiSender.js';
 export { kapso } from './addon/chat-controller/whatsapp/kapso/@kapso.js';

package/dist/src/testing/index.d.ts

@@ -701,6 +701,48 @@ declare class RestHarness {
 }
 declare function createRestHarness(options: IRestHarnessOptions): Promise<RestHarness>;
 
+interface IUiHarnessOptions {
+    controllers: IConstructor<any>[];
+    /** Extra DI registrations visible to middlewares and controllers: [token, instance]. */
+    register?: [any, any][];
+}
+interface IUiRequestOptions {
+    body?: unknown;
+    headers?: Record<string, string>;
+    query?: Record<string, string>;
+    /** Follow redirects ("follow", default) or capture them ("manual"). */
+    redirect?: 'follow' | 'manual';
+}
+interface IUiResponse {
+    status: number;
+    /** Raw response body. */
+    text: string;
+    headers: Headers;
+    /** Parse the body as JSON (for @action responses). */
+    json(): any;
+}
+/**
+ * Mounts @uiController classes on a private HTTP server (ephemeral port) and
+ * exercises the real pipeline: middlewares/guards, validation, SSR and actions.
+ * Islands render as static SSR HTML (no client bundling needed for tests).
+ */
+declare class UiHarness {
+    readonly container: DependencyContainer;
+    private server;
+    private baseUrl;
+    private constructor();
+    static create(options: IUiHarnessOptions): Promise<UiHarness>;
+    private listen;
+    get url(): string;
+    /** GET a view; returns the rendered HTML document. */
+    get(path: string, options?: IUiRequestOptions): Promise<IUiResponse>;
+    /** POST to an @action route (e.g. "/my/ui/_action/addTodo"). */
+    action(path: string, body?: unknown, options?: IUiRequestOptions): Promise<IUiResponse>;
+    request(method: string, path: string, options?: IUiRequestOptions): Promise<IUiResponse>;
+    close(): Promise<void>;
+}
+declare function createUiHarness(options: IUiHarnessOptions): Promise<UiHarness>;
+
 interface ICronHandler {
     handle(): void | Promise<void>;
     handleError?(e: any): void | Promise<void>;
@@ -773,4 +815,4 @@ interface ICronValidationOptions {
 /** Check that a sequence of dates matches consecutive firings of a cron expression. */
 declare function isValidCronSequence(cronExpression: string, dates: Date[], options?: ICronValidationOptions): boolean;
 
-export { AsyncHarness, ChatBotHarness, ChatControllerHarness, type IAsyncHarnessOptions, type IChatAdapterConformanceCase, type IChatAdapterConformanceReq, type IChatBotHarnessOptions, type IChatBotTurn, type IChatControllerHarnessOptions, type ICronValidationOptions, type IEntityFixtureOptions, type IFileFixtureOptions, type ILlmJudgeEvaluateReq, type ILlmJudgeOptions, type ILlmJudgeVerdict, type IMockChatAdapterOptions, type IMockChatAdapterResponse, type IRestHarnessOptions, type IRestRequestOptions, type IRestResponse, type ITestJwtOptions, type IValidationFixtureResult, type IValidationIssue, LlmJudge, MockChatAdapter, RestHarness, TestApiKeyRepository, TestChatMemory, TestChatRepository, TestJwt, assertInvalid, assertValid, botItem, chatAdapterConformanceCases, createAsyncHarness, createChatBotHarness, createChatControllerHarness, createRestHarness, documentMessage, entityFixture, humanItem, humanMessage, imageMessage, isValidCronSequence, renderTranscript, setupTestJwt, testImageBase64Url, testPdfBase64Url, useMemoryRepositories, validateFixture, wait, waitUntil };
+export { AsyncHarness, ChatBotHarness, ChatControllerHarness, type IAsyncHarnessOptions, type IChatAdapterConformanceCase, type IChatAdapterConformanceReq, type IChatBotHarnessOptions, type IChatBotTurn, type IChatControllerHarnessOptions, type ICronValidationOptions, type IEntityFixtureOptions, type IFileFixtureOptions, type ILlmJudgeEvaluateReq, type ILlmJudgeOptions, type ILlmJudgeVerdict, type IMockChatAdapterOptions, type IMockChatAdapterResponse, type IRestHarnessOptions, type IRestRequestOptions, type IRestResponse, type ITestJwtOptions, type IUiHarnessOptions, type IUiRequestOptions, type IUiResponse, type IValidationFixtureResult, type IValidationIssue, LlmJudge, MockChatAdapter, RestHarness, TestApiKeyRepository, TestChatMemory, TestChatRepository, TestJwt, UiHarness, assertInvalid, assertValid, botItem, chatAdapterConformanceCases, createAsyncHarness, createChatBotHarness, createChatControllerHarness, createRestHarness, createUiHarness, documentMessage, entityFixture, humanItem, humanMessage, imageMessage, isValidCronSequence, renderTranscript, setupTestJwt, testImageBase64Url, testPdfBase64Url, useMemoryRepositories, validateFixture, wait, waitUntil };

package/dist/src/testing/index.js

@@ -6,6 +6,7 @@ export { LlmJudge, renderTranscript } from './LlmJudge.js';
 export { botItem, documentMessage, humanItem, humanMessage, imageMessage, testImageBase64Url, testPdfBase64Url } from './fixtures.js';
 export { chatAdapterConformanceCases } from './conformance/chatAdapterConformanceCases.js';
 export { RestHarness, createRestHarness } from './restHarness.js';
+export { UiHarness, createUiHarness } from './uiHarness.js';
 export { AsyncHarness, createAsyncHarness } from './asyncHarness.js';
 export { entityFixture, useMemoryRepositories } from './repositories.js';
 export { TestApiKeyRepository, TestJwt, setupTestJwt } from './auth.js';

package/dist/src/testing/uiHarness.js

@@ -0,0 +1,102 @@
+import { container } from '../core/injection/index.js';
+import { ExpressProvider } from '../feature/express/ExpressProvider.js';
+import { HttpServerProvider } from '../feature/http/HttpServerProvider.js';
+import '../feature/ui-controller/metadata/UiControllerMetadataStore.js';
+import { UiRendererRegistry } from '../feature/ui-controller/renderer/UiRendererRegistry.js';
+import '../feature/ui-controller/island/IslandRegistry.js';
+import { registerUiControllers } from '../feature/ui-controller/runUiControllers.js';
+import { PreactRenderer } from '../addon/ui/preact/PreactRenderer.js';
+import '../addon/ui/preact/outlet.js';
+import { Container } from '../core/injection/Container.js';
+
+/**
+ * Mounts @uiController classes on a private HTTP server (ephemeral port) and
+ * exercises the real pipeline: middlewares/guards, validation, SSR and actions.
+ * Islands render as static SSR HTML (no client bundling needed for tests).
+ */
+class UiHarness {
+    container;
+    server;
+    baseUrl = '';
+    constructor(options) {
+        const child = container.createChildContainer();
+        child.register(Container, { useValue: child });
+        for (const [token, instance] of options.register ?? []) {
+            child.registerInstance(token, instance);
+        }
+        const rendererRegistry = child.resolve(UiRendererRegistry);
+        if (!rendererRegistry.hasDefault()) {
+            rendererRegistry.setDefault(new PreactRenderer());
+        }
+        this.container = child;
+        const httpServerProvider = new HttpServerProvider();
+        const expressProvider = new ExpressProvider(httpServerProvider);
+        registerUiControllers(options.controllers, { baseContainer: child, expressProvider });
+        this.server = httpServerProvider.getHttpServer();
+    }
+    static async create(options) {
+        const harness = new UiHarness(options);
+        await harness.listen();
+        return harness;
+    }
+    listen() {
+        return new Promise((resolve, reject) => {
+            this.server.once('error', reject);
+            this.server.listen(0, '127.0.0.1', () => {
+                const address = this.server.address();
+                if (!address || typeof address === 'string') {
+                    reject(new Error('UiHarness: could not determine server port'));
+                    return;
+                }
+                this.baseUrl = `http://127.0.0.1:${address.port}`;
+                resolve();
+            });
+        });
+    }
+    get url() {
+        return this.baseUrl;
+    }
+    /** GET a view; returns the rendered HTML document. */
+    get(path, options = {}) {
+        return this.request('GET', path, options);
+    }
+    /** POST to an @action route (e.g. "/my/ui/_action/addTodo"). */
+    action(path, body, options = {}) {
+        return this.request('POST', path, { ...options, body });
+    }
+    async request(method, path, options = {}) {
+        const url = new URL(path, this.baseUrl);
+        for (const [key, value] of Object.entries(options.query ?? {})) {
+            url.searchParams.set(key, value);
+        }
+        const headers = { ...options.headers };
+        let body;
+        if (options.body !== undefined) {
+            headers['Content-Type'] = headers['Content-Type'] ?? 'application/json';
+            body = JSON.stringify(options.body);
+        }
+        const response = await fetch(url, {
+            method: method.toUpperCase(),
+            headers,
+            body,
+            redirect: options.redirect ?? 'follow',
+        });
+        const text = await response.text();
+        return {
+            status: response.status,
+            text,
+            headers: response.headers,
+            json: () => (text ? JSON.parse(text) : null),
+        };
+    }
+    async close() {
+        await new Promise((resolve, reject) => {
+            this.server.close((err) => (err ? reject(err) : resolve()));
+        });
+    }
+}
+function createUiHarness(options) {
+    return UiHarness.create(options);
+}
+
+export { UiHarness, createUiHarness };

package/dist/src/ui/client.js

@@ -0,0 +1,6 @@
+export { getIslandMeta, isIsland, island, setIslandId } from '../feature/ui-controller/island/island.js';
+export { actionUrl, callAction } from '../feature/ui-controller/actions.js';
+export { Outlet } from '../addon/ui/preact/outlet.js';
+export { Fragment, cloneElement, createContext, h as createElement, createRef, h, isValidElement, toChildArray } from 'preact';
+export * from 'preact/hooks';
+export { Signal, batch, computed, createModel, effect, signal, action as signalAction, untracked, useComputed, useModel, useSignal, useSignalEffect } from '@preact/signals';

package/dist/src/ui/index.d.ts

@@ -0,0 +1,427 @@
+import { DependencyContainer } from 'tsyringe';
+import { Request, Response, Express } from 'express';
+import { Server } from 'node:http';
+import * as preact from 'preact';
+export { ComponentChild, ComponentChildren, Fragment, RefObject, VNode, cloneElement, createContext, h as createElement, createRef, h, isValidElement, toChildArray } from 'preact';
+export * from 'preact/hooks';
+export { Model, ModelConstructor, ReadonlySignal, Signal, batch, computed, createModel, effect, signal, action as signalAction, untracked, useComputed, useModel, useSignal, useSignalEffect } from '@preact/signals';
+
+type IConstructor<T> = new (...args: any[]) => T;
+
+interface IMiddleware {
+    handle(req: Request, res: Response, container: DependencyContainer): Promise<void>;
+}
+
+declare class HttpServerProvider {
+    server: Server | null;
+    private listening;
+    private logger;
+    getHttpServer(): Server;
+    listen(): void;
+}
+
+declare class ExpressProvider {
+    private httpServerProvider;
+    private expressApp;
+    private logger;
+    constructor(httpServerProvider: HttpServerProvider);
+    getExpress(): Express;
+    listen(): void;
+    private createExpress;
+}
+
+/** A resource to `<link rel="preload">` (font, critical image, …). */
+interface IPreloadLink {
+    href: string;
+    /** Destination: 'font' | 'image' | 'style' | 'script' | 'fetch' | … */
+    as: string;
+    /** MIME type, e.g. 'font/woff2'. Recommended so the preload matches the request. */
+    type?: string;
+    /**
+     * CORS mode. Fonts are always fetched cross-origin, so `as: 'font'` defaults to
+     * `true` (a bare `crossorigin`) — omitting it would fetch the font twice.
+     */
+    crossorigin?: boolean | 'anonymous' | 'use-credentials';
+    media?: string;
+}
+/** An origin to `<link rel="preconnect">` (e.g. a font CDN). */
+type IPreconnect = string | {
+    href: string;
+    crossorigin?: boolean;
+};
+/** Extra `<head>` resource hints rendered on full document loads. */
+interface IControllerHead {
+    /** Origins to open a connection to early (TLS handshake), e.g. a font host. */
+    preconnect?: IPreconnect[];
+    /** Resources to fetch early in parallel (fonts, hero image, …). */
+    preload?: IPreloadLink[];
+}
+interface IUiControllerConfig {
+    /** Base path every view/action of the controller is mounted under. */
+    path: string;
+    /** Middlewares (e.g. auth guards) applied to every view and action. */
+    middlewares?: IConstructor<IMiddleware>[];
+    /**
+     * Opt into client-side ("boosted") navigation between this controller's
+     * views: links within the controller's `path` are intercepted and swapped in
+     * without a full browser reload, backed by a stale-while-revalidate cache.
+     * Views still SSR normally and keep working without JS. Defaults to false.
+     */
+    app?: boolean;
+    /**
+     * Persistent app shell rendered once around every view of the controller. The
+     * layout renders an `<Outlet/>` where the current view goes; during boosted
+     * navigation only the outlet swaps, so the shell (and its islands) keep their
+     * state. A renderer component (e.g. a Preact function component).
+     */
+    layout?: unknown;
+    /**
+     * `<head>` resource hints (preconnect/preload) rendered on full document
+     * loads — the natural home for app-wide fonts, since the head persists across
+     * boosted navigation and is cached for the whole session.
+     */
+    head?: IControllerHead;
+}
+
+declare function uiController(config: string | IUiControllerConfig): (target: IConstructor<any>) => void;
+
+interface IViewConfig {
+    /** Sub-path appended to the controller path. Empty/omitted = controller index. */
+    path?: string;
+    /** Document <title> for this page. */
+    title?: string;
+    /** Extra <meta> tags rendered into the document head: name -> content. */
+    meta?: Record<string, string>;
+    /**
+     * Stale-while-revalidate hints for boosted navigation (`app: true`
+     * controllers). Only meaningful for the soft-nav client cache.
+     */
+    swr?: {
+        /**
+         * Seconds a cached fragment is considered fresh: within this window a
+         * revisit renders from cache without a background revalidation. Default 0
+         * (always revalidate in the background).
+         */
+        maxAge?: number;
+        /**
+         * Cheap revalidation tag (the SWR key). When provided, boosted-nav
+         * revalidation compares this against `If-None-Match` and can answer 304
+         * *without* running the view handler or SSR. Receives the request with
+         * body+query+params merged, so parameterized routes can (and should) key off
+         * their route params — e.g. `version: ({ id }) => docRevision(id)`.
+         * Return a short, deterministic string (a data timestamp or revision).
+         */
+        version?: (request: any) => string | Promise<string>;
+    };
+}
+
+declare function view(config?: string | IViewConfig): (target: object, propertyKey: string | symbol) => void;
+
+interface IActionConfig {
+    /** Sub-path of the action. Defaults to the method name. Mounted under `<controller>/_action/<path>`. */
+    path?: string;
+}
+
+declare function action(config?: string | IActionConfig): (target: object, propertyKey: string | symbol) => void;
+
+/**
+ * Attach a middleware (e.g. an auth guard) to a single @view or @action.
+ * Controller-wide middlewares can instead be declared on @uiController({ middlewares }).
+ */
+declare function uiMiddleware(middlewareConstructor: IConstructor<IMiddleware>): (target: object, propertyKey: string | symbol) => void;
+
+interface IUiControllerMetadata {
+    controllerConstructor: IConstructor<any>;
+    path: string;
+    middlewares: IConstructor<IMiddleware>[];
+    /** Whether this controller opts into client-side ("boosted") navigation. */
+    app?: boolean;
+    /** Persistent app-shell component rendered around every view (with an `<Outlet/>`). */
+    layout?: unknown;
+    /** `<head>` resource hints (preconnect/preload) for full document loads. */
+    head?: IControllerHead;
+}
+
+interface IViewMetadata {
+    controllerConstructor: IConstructor<any>;
+    functionName: string;
+    config?: IViewConfig;
+    paramsTypes: any[];
+}
+
+interface IActionMetadata {
+    controllerConstructor: IConstructor<any>;
+    functionName: string;
+    config?: IActionConfig;
+    paramsTypes: any[];
+}
+
+interface IUiMiddlewareMetadata {
+    controllerConstructor: IConstructor<any>;
+    functionName: string;
+    middlewareConstructor: IConstructor<IMiddleware>;
+}
+
+declare class UiControllerMetadataStore {
+    private controllers;
+    private views;
+    private actions;
+    private middlewares;
+    saveControllerMetadata(metadata: IUiControllerMetadata): void;
+    saveViewMetadata(metadata: IViewMetadata): void;
+    saveActionMetadata(metadata: IActionMetadata): void;
+    saveMiddlewareMetadata(metadata: IUiMiddlewareMetadata): void;
+    getAllUiControllerConstructors(): IConstructor<any>[];
+    private getController;
+    private collectMethodMiddlewares;
+    getControllerViewsInfo(controllerConstructor: IConstructor<any>): {
+        controllerConstructor: IConstructor<any>;
+        controller: IUiControllerMetadata;
+        middlewares: IUiMiddlewareMetadata[];
+        functionName: string;
+        config?: IViewConfig;
+        paramsTypes: any[];
+    }[];
+    getControllerActionsInfo(controllerConstructor: IConstructor<any>): {
+        controllerConstructor: IConstructor<any>;
+        controller: IUiControllerMetadata;
+        middlewares: IUiMiddlewareMetadata[];
+        functionName: string;
+        config?: IActionConfig;
+        paramsTypes: any[];
+    }[];
+}
+
+interface IRenderContext {
+    /** True while running under the dev server (enables hydration in dev, etc.). */
+    dev?: boolean;
+    /**
+     * Optional layout component to wrap the view in (the persistent app shell).
+     * The renderer places the view where the layout renders its `<Outlet/>`.
+     * Passed only for full-document loads; omitted for boosted-nav fragments so
+     * only the view (the outlet's content) is rendered.
+     */
+    layout?: unknown;
+}
+interface IRenderedIsland {
+    /** Stable island id (module-derived), used to load its client bundle. */
+    id: string;
+    /** Serializable props the island was rendered with, for client hydration. */
+    props: unknown;
+}
+interface IRenderResult {
+    /** Server-rendered HTML for the view body. */
+    html: string;
+    /** Islands encountered while rendering, in document order. */
+    islands: IRenderedIsland[];
+    /** Style hrefs (or inline CSS ids) the page depends on, if any. */
+    styles: string[];
+}
+interface IIslandEntryArgs {
+    /** Stable island id (also the client bundle's output name). */
+    id: string;
+    /** Absolute path to the island's source module (default export = island). */
+    importPath: string;
+}
+/** Renderer-specific knobs the island bundler needs to build client bundles. */
+interface IUiClientConfig {
+    /** Module the generated island entry imports its hydration `registerIsland` from. */
+    runtimeModule: string;
+    /** esbuild JSX settings for compiling islands on the client. */
+    esbuildJsx?: {
+        jsx?: 'automatic' | 'transform' | 'preserve';
+        jsxImportSource?: string;
+        jsxFactory?: string;
+        jsxFragmentFactory?: string;
+    };
+    /** Source of the client entry that registers one island for hydration. */
+    islandEntrySource(args: IIslandEntryArgs): string;
+}
+/**
+ * A pluggable UI rendering engine. The default implementation is Preact
+ * (`@wabot-dev/framework/ui`), but any framework can be adapted by implementing
+ * this interface and registering it in {@link UiRendererRegistry}.
+ */
+interface UiRenderer {
+    /** Unique id, e.g. "preact" or "react". */
+    readonly id: string;
+    /** Render a view's returned node tree to HTML, collecting island usage. */
+    renderToString(node: unknown, context?: IRenderContext): IRenderResult | Promise<IRenderResult>;
+    /** Bundling/hydration config. Required to ship interactive islands. */
+    readonly client?: IUiClientConfig;
+}
+
+declare class UiRendererRegistry {
+    private renderers;
+    private defaultRenderer;
+    /** Register a renderer. The first one registered becomes the default. */
+    register(renderer: UiRenderer): void;
+    /** Register a renderer and make it the default. */
+    setDefault(renderer: UiRenderer): void;
+    has(id: string): boolean;
+    hasDefault(): boolean;
+    get(id?: string): UiRenderer;
+}
+
+/**
+ * Marker attached to components wrapped with {@link island}. The UI renderer
+ * uses it to decide which components must hydrate on the client; the bundler
+ * uses {@link IslandMeta.id} (assigned from the `*.island.tsx` file location) to
+ * emit a per-island client bundle.
+ */
+declare const ISLAND_MARKER: unique symbol;
+interface IslandMeta {
+    /** The original component, rendered for SSR and hydrated on the client. */
+    component: (props: any) => any;
+    /** Human-readable name (component name unless overridden). */
+    name: string;
+    /** Stable bundle id, assigned during island discovery. Undefined until then. */
+    id?: string;
+}
+interface IslandComponent<P = any> {
+    (props: P): any;
+    [ISLAND_MARKER]: IslandMeta;
+}
+/**
+ * Mark a component as an interactive client "island". The component still
+ * renders on the server, but only islands ship JavaScript and hydrate in the
+ * browser. Islands must be the export of a `*.island.tsx` file so the bundler
+ * can give them a stable id.
+ *
+ *   // Counter.island.tsx
+ *   function Counter() { ... }
+ *   export default island(Counter)
+ */
+declare function island<P>(component: (props: P) => any, name?: string): IslandComponent<P>;
+declare function getIslandMeta(component: unknown): IslandMeta | undefined;
+declare function isIsland(component: unknown): boolean;
+/** Assign the stable bundle id to an island, done during island discovery. */
+declare function setIslandId(component: unknown, id: string): void;
+
+/**
+ * Serialize the props an island was rendered with so the client can hydrate it
+ * with the same data. Drops `children`/`ref`/`key` and any function-valued
+ * props (event handlers belong inside the island, not in its serialized props).
+ */
+declare function serializeProps(props: Record<string, unknown>): string;
+declare function deserializeProps(raw: string | undefined | null): Record<string, unknown>;
+
+interface IDiscoveredIsland {
+    /** Stable id derived from the file's project-relative path. */
+    id: string;
+    /** Absolute path to the island source module. */
+    importPath: string;
+    /** Project-relative posix path (the basis of the id). */
+    relPath: string;
+}
+/** Files matching this are treated as islands (default export wrapped with island()). */
+declare const ISLAND_FILE_PATTERN: RegExp;
+/** Deterministic, readable, collision-resistant id from a project-relative path. */
+declare function toIslandId(relPath: string): string;
+declare function isIslandFile(file: string): boolean;
+/**
+ * Discovers `*.island.tsx` modules, assigns each a stable id, and stamps that
+ * id onto the imported island component (ESM module singletons mean the view
+ * renders the same instance, so the renderer can read the id during SSR).
+ */
+declare class IslandRegistry {
+    private islands;
+    private logger;
+    discover(files: string[], cwd?: string): Promise<IDiscoveredIsland[]>;
+    register(island: IDiscoveredIsland): void;
+    list(): IDiscoveredIsland[];
+    get(id: string): IDiscoveredIsland | undefined;
+    get size(): number;
+}
+
+interface IDocumentOptions {
+    /** Server-rendered HTML placed inside <body>. */
+    bodyHtml: string;
+    /** Document title. */
+    title?: string;
+    /** <meta name=.. content=..> tags. */
+    meta?: Record<string, string>;
+    /** Stylesheet hrefs rendered as <link rel="stylesheet">. */
+    styles?: string[];
+    /** Extra <link> tags (preload/preconnect/…) as attribute maps. `true` => bare attribute. */
+    links?: Array<Record<string, string | boolean>>;
+    /** Module script srcs rendered as <script type="module">. */
+    scripts?: string[];
+    /** Raw HTML appended to <head> (e.g. inline bootstrap data). */
+    headHtml?: string;
+    /** Raw HTML appended to the end of <body> (e.g. dev live-reload snippet). */
+    bodyEndHtml?: string;
+    /** <html lang>. Defaults to "en". */
+    lang?: string;
+}
+/**
+ * Render the default HTML document shell around a view's body. Kept
+ * renderer-agnostic (plain string templating) so it works with any UiRenderer.
+ */
+declare function renderDocument(options: IDocumentOptions): string;
+
+declare const REDIRECT_MARKER: unique symbol;
+interface UiRedirect {
+    readonly [REDIRECT_MARKER]: true;
+    location: string;
+    status: number;
+}
+/**
+ * Return this from a @view or @action to send an HTTP redirect instead of
+ * rendering. Used for the post/redirect/get pattern after form actions.
+ */
+declare function redirect(location: string, status?: number): UiRedirect;
+declare function isRedirect(value: unknown): value is UiRedirect;
+
+/** Escape text for safe interpolation into HTML element content. */
+declare function escapeHtml(value: string): string;
+/** Escape a value for safe interpolation into a double-quoted HTML attribute. */
+declare function escapeAttr(value: string): string;
+
+/** Build the URL of an @action: `<controllerPath>/_action/<actionName>`. */
+declare function actionUrl(controllerPath: string, actionName: string): string;
+interface ICallActionOptions {
+    headers?: Record<string, string>;
+    signal?: AbortSignal;
+}
+/**
+ * POST JSON to an @action and return its JSON result. Throws on non-2xx with
+ * the server-provided error message. Intended for use from islands; plain
+ * <form action=…> posts also work for progressive enhancement.
+ */
+declare function callAction<T = unknown>(url: string, data?: unknown, options?: ICallActionOptions): Promise<T>;
+
+/** Page-level assets (scripts/styles) to inject, computed from the islands a view rendered. */
+interface IPageAssets {
+    scripts?: string[];
+    styles?: string[];
+    headHtml?: string;
+    bodyEndHtml?: string;
+    /** URL of the boosted-navigation runtime; injected on `app: true` pages. */
+    navScript?: string;
+}
+interface IRegisterUiControllersOptions {
+    baseContainer?: DependencyContainer;
+    expressProvider?: ExpressProvider;
+    /** Hook used by the bundler/dev server to inject island client bundles + CSS. */
+    pageAssets?: (islands: IRenderedIsland[]) => IPageAssets;
+}
+declare function registerUiControllers(controllers: IConstructor<any>[], options?: IRegisterUiControllersOptions): ExpressProvider;
+declare function runUiControllers(controllers: IConstructor<any>[], options?: IRegisterUiControllersOptions): void;
+
+/**
+ * Placeholder a controller `layout` renders where the current view goes. Emits a
+ * `<wabot-outlet>` host wrapping the view's server HTML; during boosted
+ * navigation only this element's content is swapped, so the surrounding shell
+ * (and its islands) keep their state.
+ *
+ *   function Layout() {
+ *     return <div class="app"><Nav /><main><Outlet /></main></div>
+ *   }
+ *   @uiController({ path: '/panel', app: true, layout: Layout })
+ */
+declare function Outlet(): preact.VNode<preact.Attributes & {
+    'data-wabot-outlet': string;
+}>;
+
+export { type IActionConfig, type IActionMetadata, type ICallActionOptions, type IControllerHead, type IDiscoveredIsland, type IDocumentOptions, type IIslandEntryArgs, type IPageAssets, type IPreconnect, type IPreloadLink, type IRegisterUiControllersOptions, type IRenderContext, type IRenderResult, type IRenderedIsland, ISLAND_FILE_PATTERN, ISLAND_MARKER, type IUiClientConfig, type IUiControllerConfig, type IUiControllerMetadata, type IUiMiddlewareMetadata, type IViewConfig, type IViewMetadata, type IslandComponent, type IslandMeta, IslandRegistry, Outlet, REDIRECT_MARKER, UiControllerMetadataStore, type UiRedirect, type UiRenderer, UiRendererRegistry, action, actionUrl, callAction, deserializeProps, escapeAttr, escapeHtml, getIslandMeta, isIsland, isIslandFile, isRedirect, island, redirect, registerUiControllers, renderDocument, runUiControllers, serializeProps, setIslandId, toIslandId, uiController, uiMiddleware, view };