openui-telegram 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pavel Voronin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,107 @@
-# Temporary Holding Version
+# OpenUI Telegram
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Compile OpenUI templates and data into HTML for Telegram Widgets. Define your components, choose a static snapshot or an updatable widget, then send the resulting HTML through your bot.
+
+Requires Node.js **22.15+, 24 or 26 LTS**, Zod 4 and `@openuidev/lang-core` 1.1.0.
+
+```sh
+npm install openui-telegram @openuidev/lang-core zod
+```
+
+## Static HTML
+
+```ts
+import { z } from 'zod';
+import { createLibrary } from '@openuidev/lang-core';
+import {
+  compileWidget, defineWidgetComponent,
+  createInterface, createWidgetController,
+} from 'openui-telegram';
+
+const Text = defineWidgetComponent({
+  name: 'Text', description: 'Text',
+  props: z.object({ value: z.string() }),
+  render: ({ props, text }) => `<p>${text(props.value)}</p>`,
+});
+const library = createLibrary({ components: [Text] });
+const source = '$amount = 0\nroot = Text("Total: " + $amount)';
+const initialState = { state: { $amount: 1200 }, forms: {} };
+
+const card = await compileWidget({
+  mode: 'static', library, source, initialState,
+});
+// card.html contains "Total: 1200", with no library JavaScript.
+```
+
+`mode` is required. In `static`, `$variables` and expressions are evaluated once during compilation. Actions and browser lifecycle hooks produce error diagnostics. Queries use supplied saved results or defaults; compilation never calls tools.
+
+Before sending HTML, check `diagnostics` for errors and `fits` for Telegram's document limits. `measurement` reports actual byte sizes and remaining space. Components return trusted HTML; use `text(value)` to escape data.
+
+## Updatable widgets
+
+Using the same library and template:
+
+```ts
+const widget = await compileWidget({
+  mode: 'updatable', instanceId: 'order', library, source, initialState,
+});
+const session = createInterface(library, source, {
+  instanceId: 'order', initialState: widget.initialData.state,
+});
+const controller = createWidgetController(session.runtime, {
+  initialFrame: widget.initialData.frame,
+});
+
+// Send widget.html once. Deliver this string as Telegram chat_data:
+const chatData = controller.encode(await controller.frame());
+
+// Later, change application state and deliver the next chat_data:
+session.runtime.setState('$amount', 1500);
+const nextChatData = controller.encode(await controller.frame());
+
+// In your handler for a widget request routed to this instance:
+async function handleRequest(requestData: string) {
+  const completed = await controller.handle(requestData);
+  const data = controller.encode(await controller.frame());
+  return { completed, data }; // Deliver data to Telegram and answer the request.
+}
+
+// When the application no longer needs this widget:
+// controller.dispose();
+```
+
+`updatable` includes a compact client; OpenUI executes in your application. Plain HTML updates need no `clientEntry`. Your application owns the bot, request authorization, delivery and storage. Use a unique instance ID of 1–32 ASCII letters, digits, `_` or `-`, and serialize requests and frame delivery for each instance.
+
+- Pass `onOperation: async ({ tool, args }) => ...` to `createInterface` to execute queries and mutations. `onAction` handles custom actions and conversation events. Subscribe with `session.runtime.subscribe(callback)` to deliver asynchronous query results without waiting for another tap.
+- `session.update(source)` replaces a program; `session.patch(source)` edits it while retaining unaffected state and operations. `session.push(chunk, complete)` accepts streamed source.
+- To resume an existing message, persist `session.source`, `controller.save()` and `controller.checkpoint()` together. Restore the same instance ID/program version and pass the checkpoint to the new controller; see the [restart recipe](https://github.com/pavel-voronin/openui-telegram/blob/main/examples/README.md#restart-and-delivery). Saved mutations are not replayed.
+
+Working examples: [static HTML](https://github.com/pavel-voronin/openui-telegram/blob/main/examples/hello.ts) and [static/updatable cards](https://github.com/pavel-voronin/openui-telegram/blob/main/examples/cards.ts).
+
+Try `npm run demo:simple` for a counter or `npm run demo:full` for the capability gallery. Both run locally without credentials. [Demo instructions](https://github.com/pavel-voronin/openui-telegram/blob/main/examples/README.md) also cover sending them through a real Telegram bot.
+
+## Components and browser hooks
+
+`defineWidgetComponent` infers props from its Zod schema. Its `render` context provides `text`, `renderNode` for children, `action` for a delegated button attribute, and `field`/`form` for values and validation. Mark bound props with `reactive: ['value']` and register fields during `render`.
+
+For browser behavior such as canvas drawing or pointer controls, add `mount(context)` and/or `update(context)`. They receive the DOM `element` and current props. `context.on(target, event, listener)` manages listeners; `mount` may return a cleanup function. Lifecycle components must render one root element.
+
+Put these implementations in a module exporting `components`, use the same implementations in your component definitions, and pass that module's path as `clientEntry`. See [browser-components.ts](https://github.com/pavel-voronin/openui-telegram/blob/main/examples/browser-components.ts). Keep Zod schemas in the application. Browser helpers are exported from `openui-telegram/client`. Reconciliation applies changes to server-rendered content while preserving locally added DOM and unchanged client-modified attributes; removed roots still dispose their resources.
+
+The compiler includes the client capabilities and component CSS reachable from the initial program, including conditional branches. Reserve hooks and styles needed by later patches with `clientComponents: ['Chart']`, or use `clientSpecialization: false` to retain the full client, registry and styles. An update requiring unreserved hooks or component CSS is rejected before changing the visible frame. The compiler's `css` option is always global. Adding browser code or unreserved styles after sending requires a new widget.
+
+## Telegram limits
+
+HTML must fit **both 32,768 bytes uncompressed and 4,096 bytes compressed**; requests are limited to **64 bytes** and state/answers to **1,024 bytes**. Oversized documents produce diagnostics; oversized encoded updates throw `TransportSizeError`. Delivering a larger view requires an explicit new widget; see the [overflow example](https://github.com/pavel-voronin/openui-telegram/blob/main/examples/README.md#oversized-updates). `fits` checks size only; `unsupported-element` diagnoses known removed tags in initial HTML. Diagnostics do not certify CSS, dynamic DOM or sandbox behavior: test your UI in Telegram.
+
+Inline scripts, styles and assets: widgets cannot fetch network resources. Native keyboard inputs are unavailable. Links must open synchronously from a tap; links after asynchronous work are rejected. Updatable interactions require your application and a Telegram round trip. The built-in client consumes `chatData`, not shared `publicData`. Telegram currently enables production widgets only in private bot chats; other contexts require its test server. This package is ESM-only.
+
+See the [Telegram Widget documentation](https://core.telegram.org/bots/widgets) and [OpenUI language documentation](https://www.openui.com/docs/openui-lang/specification).
+
+## Development
+
+Run `npm ci` and `npm run check`. This builds the library and examples, checks types, runs tests with mandatory 100% line/branch/function coverage, and installs the packed library in a separate consumer project. Package verification needs registry access; compilation and unit tests need no credentials or network.
+
+Source is in `src/`, tests in `test/`, and examples in `examples/`. `npm run build` cleans and regenerates `dist/`. Keep generated output uncommitted and add focused tests for behavior changes. CI runs the same checks on Linux and Windows for supported Node versions, including the minimum 22.15.0 and 24.0.0. CI also runs weekly on Sunday at 20:00 UTC, checking the latest releases in each supported Node branch. See [CHANGELOG.md](https://github.com/pavel-voronin/openui-telegram/blob/main/CHANGELOG.md) for release notes.
+
+Stable releases publish to npm after all CI checks pass when a pushed tag matches `v<package.json version>`. A manual Actions run checks publication with `--dry-run` and never publishes. After the first authenticated publish, configure an npm [trusted publisher](https://docs.npmjs.com/trusted-publishers/) for owner `pavel-voronin`, repository `openui-telegram`, workflow `ci.yml`, no environment, with direct `npm publish` allowed. Later releases use OIDC without an npm token.

package/dist/client-features.js

@@ -0,0 +1,9 @@
+// Full public browser/local client. The compiler replaces these constants only
+// inside a widget bundle, after inspecting its bundled lifecycle callbacks.
+export const CLIENT_LIFECYCLE = true;
+export const CLIENT_FIELDS = true;
+export const CLIENT_FORMS = true;
+export const CLIENT_MOUNT = true;
+export const CLIENT_CLEANUPS = true;
+export const CLIENT_EVENTS = true;
+export const CLIENT_TEXT = true;

package/dist/client-text.d.ts

@@ -0,0 +1 @@
+export declare function text(value: unknown): string;

package/dist/client-text.js

@@ -0,0 +1,6 @@
+// Kept free of language runtime imports so the compact driver stays self-contained.
+export function text(value) {
+    return String(value ?? '').replace(/[&<>"']/g, c => ({
+        '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;',
+    })[c]);
+}

package/dist/client.d.ts

@@ -0,0 +1,16 @@
+import type { WidgetFrame, WidgetInput } from './controller.js';
+import type { WidgetComponent } from './runtime.js';
+import type { WidgetUpdate } from './wire-apply.js';
+export { text } from './client-text.js';
+/** The compiler supplies availableStyles; standalone adapters own their CSS unless they supply this manifest. */
+export declare function mountWidgetClient(initial: WidgetFrame, components: Record<string, WidgetComponent>, options?: {
+    root: HTMLElement;
+    request(input: WidgetInput): Promise<WidgetFrame | WidgetUpdate>;
+    openUrl?(url: string): void;
+    onDiagnostic?(diagnostic: unknown): void;
+}, availableStyles?: readonly string[]): {
+    apply: (update: WidgetFrame | WidgetUpdate) => boolean;
+    errors: unknown[];
+    readonly current: WidgetFrame;
+    dispose(): void;
+};

package/dist/client.js

@@ -0,0 +1,196 @@
+import { text } from './client-text.js';
+import { applyWidgetUpdate } from './wire-apply.js';
+import { reconcileDOM, restoreDOM } from './dom.js';
+import { CLIENT_LIFECYCLE, CLIENT_FIELDS, CLIENT_FORMS, CLIENT_MOUNT, CLIENT_CLEANUPS, CLIENT_EVENTS, CLIENT_TEXT } from './client-features.js';
+export { text } from './client-text.js';
+/** The compiler supplies availableStyles; standalone adapters own their CSS unless they supply this manifest. */
+export function mountWidgetClient(initial, components, options, availableStyles) {
+    const env = options ? undefined : globalThis.TelegramWidget, host = options ?? globalThis.OpenUIHost;
+    const root = options?.root ?? document.getElementById('openui-root');
+    let frame = initial, stopped = false;
+    const resources = CLIENT_LIFECYCLE ? new Map() : undefined;
+    const errors = [];
+    const error = (e) => { errors.push(e); host?.onDiagnostic?.({ source: 'transport', code: 'client-error', message: String(e) }); };
+    const dispose = (id) => {
+        const resource = resources.get(id);
+        resources.delete(id);
+        if (CLIENT_CLEANUPS)
+            for (const cleanup of resource.cleanup.reverse()) {
+                try {
+                    cleanup();
+                }
+                catch (e) {
+                    error(e);
+                }
+            }
+        restoreDOM(resource.element);
+    };
+    const request = (input) => {
+        const data = JSON.stringify(input);
+        const bytes = encodeURIComponent(data).replace(/%[0-9A-F]{2}/g, 'x').length;
+        if (bytes > 64) {
+            error(new Error(`Request has ${bytes} bytes, limit is 64`));
+            return;
+        }
+        try {
+            const result = env ? env.request(data).then((answer) => answer.result && JSON.parse(answer.result)) : host?.request(input);
+            Promise.resolve(result).then(update => { if (update)
+                apply(update); }).catch(error);
+        }
+        catch (e) {
+            error(e);
+        }
+    };
+    const draw = () => {
+        if (CLIENT_LIFECYCLE)
+            for (const [id, resource] of resources)
+                if (!frame.c[id] || frame.c[id].type !== resource.type)
+                    dispose(id);
+        reconcileDOM(root, frame.h);
+        if (CLIENT_LIFECYCLE)
+            for (const [id, record] of Object.entries(frame.c)) {
+                const implementation = components[record.type], element = root.querySelector(`[data-oui-component="${id}"]`);
+                if (!element || !implementation) {
+                    error(new Error(`Missing lifecycle implementation or root: ${record.type}`));
+                    continue;
+                }
+                let resource = resources.get(id);
+                if (resource && resource.element !== element) {
+                    dispose(id);
+                    resource = undefined;
+                }
+                const fresh = !resource;
+                if (!resource) {
+                    const cleanup = CLIENT_CLEANUPS ? [] : undefined;
+                    const context = {
+                        id, props: {}, statementId: record.statementId, scope: record.scope, element,
+                        ...(CLIENT_TEXT ? { text } : {}),
+                        ...(CLIENT_FIELDS ? { field: (name, _binding, options) => {
+                                const scope = options?.scope ?? context.scope ?? '';
+                                const slot = frame.c[id]?.fields?.findIndex(field => field.name === name && field.scope === scope) ?? -1;
+                                if (slot < 0)
+                                    throw new Error('Register component fields during render before using lifecycle hooks');
+                                const current = () => {
+                                    const field = frame.c[id]?.fields?.find(field => field.name === name && field.scope === scope) ?? frame.c[id]?.fields?.[slot];
+                                    if (!field)
+                                        throw new Error('Field is no longer registered');
+                                    return field;
+                                };
+                                return {
+                                    get name() { return current().name; },
+                                    get isReactive() { return current().reactive; },
+                                    get value() { const field = current(); return frame.f[`${field.scope}\0${field.name}`]; },
+                                    setValue(value) {
+                                        const field = current();
+                                        request([frame.i, frame.v, frame.r, 'v', field.handle, value]);
+                                    },
+                                };
+                            } } : {}),
+                        ...(CLIENT_FORMS ? { form: (scope = context.scope ?? '') => ({
+                                values: Object.fromEntries(Object.entries(frame.f).filter(([key]) => key.startsWith(`${scope}\0`))
+                                    .map(([key, value]) => [key.slice(scope.length + 1), value])), errors: Object.hasOwn(frame.e, scope) ? frame.e[scope] : {},
+                            }) } : {}),
+                        ...(CLIENT_EVENTS ? { on(target, event, handler) {
+                                target.addEventListener(event, handler);
+                                cleanup.push(() => target.removeEventListener(event, handler));
+                            } } : {}),
+                    };
+                    resource = { element, type: record.type, context, ...(CLIENT_CLEANUPS ? { cleanup } : {}), signature: '' };
+                    resources.set(id, resource);
+                }
+                // Keep the props object live for listeners installed by mount().
+                const props = resource.context.props;
+                for (const key of Object.keys(props))
+                    if (!Object.prototype.hasOwnProperty.call(record.props, key))
+                        delete props[key];
+                Object.assign(props, record.props);
+                resource.context.scope = record.scope;
+                resource.context.statementId = record.statementId;
+                const signature = JSON.stringify([record.props, frame.f, frame.e, record.scope]);
+                try {
+                    if (CLIENT_MOUNT && fresh) {
+                        const cleanup = implementation.mount?.(resource.context);
+                        if (cleanup)
+                            resource.cleanup.push(cleanup);
+                    }
+                    if (fresh || signature !== resource.signature)
+                        implementation.update?.(resource.context);
+                    resource.signature = signature;
+                }
+                catch (e) {
+                    error(e);
+                }
+            }
+        if (CLIENT_LIFECYCLE)
+            for (const [id, resource] of resources)
+                if (!root.contains(resource.element))
+                    dispose(id);
+    };
+    const apply = (update) => {
+        if (stopped || update.i !== frame.i || update.v < frame.v || update.v === frame.v && update.r <= frame.r)
+            return false;
+        const base = 'd' in update && update.b[0] === initial.v && update.b[1] === initial.r ? initial : frame;
+        const next = 'd' in update ? applyWidgetUpdate(base, update) : update;
+        for (const name of next.s ?? [])
+            if (availableStyles && !availableStyles.includes(name))
+                throw new Error(`Styles for ${name} need a new widget; reserve them with clientComponents before compilation`);
+        for (const record of Object.values(next.c))
+            if (!CLIENT_LIFECYCLE || !components[record.type])
+                throw new Error(`Component ${record.type} needs a new widget; reserve it with clientComponents before compilation`);
+        frame = next;
+        draw();
+        return true;
+    };
+    const changed = () => { try {
+        if (env.chatData)
+            apply(JSON.parse(env.chatData));
+    }
+    catch (e) {
+        error(e);
+    } };
+    const click = (event) => {
+        let node = event.target;
+        while (node && node !== root) {
+            const action = node.getAttribute('data-oui-action');
+            if (action !== null) {
+                const link = frame.l[action];
+                if (link) {
+                    try {
+                        if (env) {
+                            const telegram = /^https:\/\/(?:t\.me|telegram\.me|telegram\.dog)(?::443)?(?=[/?#]|$)/i.exec(link);
+                            if (telegram)
+                                env.openTelegramLink('https://t.me' + link.slice(telegram[0].length));
+                            else
+                                env.openLink(link);
+                        }
+                        else
+                            host?.openUrl?.(link);
+                    }
+                    catch (e) {
+                        error(e);
+                    }
+                }
+                else
+                    request([frame.i, frame.v, frame.r, 'a', action]);
+                return;
+            }
+            node = node.parentElement;
+        }
+    };
+    root.addEventListener('click', click);
+    env?.onEvent('chatDataChanged', changed);
+    draw();
+    if (env)
+        changed();
+    env?.ready?.();
+    return { apply, errors, get current() { return frame; },
+        dispose() {
+            stopped = true;
+            if (CLIENT_LIFECYCLE)
+                for (const id of [...resources.keys()])
+                    dispose(id);
+            root.removeEventListener('click', click);
+            env?.offEvent('chatDataChanged', changed);
+        },
+    };
+}

package/dist/compiler.d.ts

@@ -0,0 +1,94 @@
+import type { Library } from '@openuidev/lang-core';
+import type { Diagnostic, RuntimeOptions, WidgetComponent } from './runtime.js';
+import type { WidgetClientFeatures } from './host-client-bundle.js';
+interface CompileBase extends Omit<RuntimeOptions, 'instanceId'> {
+    library: Library<WidgetComponent>;
+    source: string;
+    /** Module exporting components (WidgetComponent map) with client lifecycle implementations.
+     * Keep schemas on the host; this module and every imported resource are bundled inline. */
+    clientEntry?: string;
+    /** Default true: include only reachable lifecycle implementations/services. */
+    clientSpecialization?: boolean;
+    /** Reserve additional lifecycle components for later program updates/patches. */
+    clientComponents?: string[];
+    css?: string;
+}
+export type CompileOptions = CompileBase & ({
+    mode: 'static';
+    instanceId?: string;
+} | {
+    mode: 'updatable';
+    instanceId: string;
+});
+export declare function compileWidget(options: CompileOptions): Promise<{
+    mode: "static" | "updatable";
+    html: string;
+    initialData: {
+        instanceId: string;
+        version: number;
+        program: import("@openuidev/lang-core").ParseResult;
+        state: import("./runtime.js").SavedState;
+        frame: import("./controller.js").WidgetFrame;
+        clientFeatures: WidgetClientFeatures | undefined;
+    };
+    diagnostics: Diagnostic[];
+    measurement: {
+        html: {
+            bytes: number;
+            limit: number;
+            accuracy: string;
+        };
+        compressedHtml: {
+            bytes: number;
+            limit: number;
+            accuracy: string;
+        };
+        clientRuntime: {
+            bytes: number;
+            compressedBytes: number;
+            accuracy: string;
+            scope: string;
+            containsLanguageRuntime: boolean;
+        };
+        headroom: {
+            htmlBytes: number;
+            compressedHtmlBytes: number;
+            accuracy: string;
+            note: string;
+        };
+        initialData: {
+            bytes: number;
+            accuracy: string;
+        };
+        transportFrame: {
+            bytes: number;
+            limit: number;
+            accuracy: string;
+            encoding: string;
+            required: boolean;
+        };
+        fullFrame: {
+            bytes: number;
+            accuracy: string;
+        };
+        client: {
+            accuracy: string;
+            checks: string[];
+        };
+    };
+    fits: boolean;
+    profile: {
+        readonly profile: 1;
+        readonly documentationChecked: '2026-11-11';
+        readonly openui: '1.1.0';
+        readonly language: '1.0 (inherits 0.5)';
+        readonly html: 32768;
+        readonly compressedHtml: 4096;
+        readonly request: 64;
+        readonly response: 1024;
+        readonly state: 1024;
+    };
+    message: import("@openuidev/lang-core").ParsedMessage;
+    parts: import("./message.js").ResponsePart[];
+}>;
+export {};

package/dist/compiler.js

@@ -0,0 +1,157 @@
+import { build } from 'esbuild';
+import { fileURLToPath } from 'node:url';
+import { deflateSync } from 'node:zlib';
+import { resolve } from 'node:path';
+import { createInterface } from './session.js';
+import { TELEGRAM_PROFILE } from './transport.js';
+import { createWidgetController } from './controller.js';
+import { responseParts } from './message.js';
+import { createWidgetUpdate } from './wire.js';
+import { javascriptData } from './javascript-data.js';
+import { hostClientPlugin, widgetClientFeatures } from './host-client-bundle.js';
+const scriptJSON = javascriptData;
+/** Inspect markup, skipping comments and raw script/style content. Not a sandbox validator. */
+function unsupportedElements(html) {
+    const forbidden = new Set(('input select textarea option optgroup fieldset legend datalist output progress meter dialog audio video source track ' +
+        'iframe frame frameset object embed link meta base portal template slot math ruby rt rp center font big tt strike nobr').split(' '));
+    const found = new Set();
+    const tokens = /<!--[\s\S]*?(?:-->|$)|<\/?([a-z][\w:-]*)\b(?:[^"'<>]|"[^"]*"|'[^']*')*>/gi;
+    let match;
+    while ((match = tokens.exec(html))) {
+        const tag = match[1]?.toLowerCase();
+        if (!tag)
+            continue;
+        const closing = match[0].startsWith('</');
+        if (closing)
+            continue;
+        if (forbidden.has(tag))
+            found.add(tag);
+        if (tag === 'script' || tag === 'style') {
+            const close = new RegExp(`</${tag}\\s*>`, 'gi');
+            close.lastIndex = tokens.lastIndex;
+            if (!close.exec(html))
+                break;
+            tokens.lastIndex = close.lastIndex;
+        }
+    }
+    return [...found];
+}
+export async function compileWidget(options) {
+    if (options.mode !== 'static' && options.mode !== 'updatable')
+        throw new TypeError('mode must be "static" or "updatable"');
+    if (options.mode === 'updatable' && !options.instanceId)
+        throw new TypeError('updatable mode requires instanceId');
+    const instanceId = options.instanceId ?? 'static';
+    if (!/^[a-zA-Z0-9_-]{1,32}$/.test(instanceId))
+        throw new TypeError('instanceId must be 1–32 ASCII letters, digits, _ or -');
+    const clientPath = options.clientEntry ? resolve(options.clientEntry) : undefined;
+    const diagnostics = [];
+    // Compilation never performs external operations. Queries still expose their defaults.
+    const session = createInterface(options.library, options.source, {
+        instanceId, version: options.version, initialState: options.initialState,
+        validators: options.validators,
+        executeQueries: false,
+        onDiagnostic: d => diagnostics.push(d),
+    });
+    try {
+        const parsed = session.runtime.parsed;
+        const frame = await createWidgetController(session.runtime).frame();
+        const initialHtml = frame.h;
+        diagnostics.push(...parsed.meta.errors.map(error => ({ ...error, source: 'parser' })));
+        if (parsed.meta.incomplete)
+            diagnostics.push({ source: 'parser', code: 'incomplete', message: 'Program is incomplete' });
+        for (const statementId of parsed.meta.unresolved)
+            diagnostics.push({ source: 'parser', code: 'unresolved', statementId, message: `Unresolved reference: ${statementId}` });
+        const initialData = { instanceId, version: options.version ?? 1,
+            program: parsed, state: session.runtime.snapshot(), frame, clientFeatures: undefined };
+        const needsClient = options.mode === 'updatable';
+        if (!needsClient) {
+            if (session.runtime.hasActions)
+                diagnostics.push({ source: 'compiler', code: 'static-action',
+                    message: 'Static HTML cannot execute OpenUI actions. Use mode: "updatable" for interactive controls.' });
+            for (const component of new Set(Object.values(frame.c).map(record => record.type)))
+                diagnostics.push({
+                    source: 'compiler', code: 'static-client-hook', component,
+                    message: `${component} requires client mount/update hooks. Use mode: "updatable" or a render-only component.`
+                });
+            if (parsed.queryStatements.length)
+                diagnostics.push({ source: 'compiler', code: 'static-query-snapshot', severity: 'warning',
+                    message: 'Static compilation does not execute tools or deliver later Query results; it renders supplied saved results or query defaults.' });
+            if (options.clientComponents?.length || options.clientSpecialization === false)
+                diagnostics.push({ source: 'compiler', code: 'static-client-options',
+                    message: 'Client capabilities cannot be enabled in mode: "static". Use mode: "updatable".' });
+        }
+        const selected = widgetClientFeatures(parsed, options.library, Object.values(frame.c).map(record => record.type), needsClient ? options.clientComponents : undefined, !needsClient || options.clientSpecialization !== false);
+        const hostFeatures = needsClient ? selected : undefined;
+        initialData.clientFeatures = hostFeatures;
+        let javascript = '';
+        let clientRuntime = { bytes: 0, compressedBytes: 0, accuracy: 'standalone-exact',
+            scope: 'Library client only; excludes components and bootstrap. Compression is not additive.', containsLanguageRuntime: false };
+        const requiresEntry = !!hostFeatures?.components.length;
+        if (needsClient && (!requiresEntry || clientPath)) {
+            const bootstrap = `
+        import { mountWidgetClient } from ${JSON.stringify(fileURLToPath(new URL('./client.js', import.meta.url)))};
+        ${!clientPath ? 'const components = {};' : hostFeatures.specialized ? `import {components as clientComponents} from ${JSON.stringify(clientPath)};
+          const components = {${hostFeatures.components.map(name => `${scriptJSON(name)}:clientComponents[${scriptJSON(name)}]`).join(',')}};` :
+                `import { components } from ${JSON.stringify(clientPath)};`}
+        globalThis.OpenUIWidget = mountWidgetClient(${scriptJSON(frame)}, components, undefined, ${scriptJSON(hostFeatures.styles)});
+        globalThis.addEventListener('pagehide', () => globalThis.OpenUIWidget.dispose());
+      `;
+            const bundled = await build({ stdin: { contents: bootstrap, resolveDir: process.cwd(), loader: 'js' },
+                bundle: true, write: false, format: 'iife', platform: 'browser', minify: true, target: 'es2023',
+                legalComments: 'none', metafile: true, plugins: [hostClientPlugin(hostFeatures, options.clientEntry)] });
+            javascript = bundled.outputFiles[0].text;
+            {
+                const service = await build({ stdin: { contents: `import {mountWidgetClient} from ${JSON.stringify(fileURLToPath(new URL('./client.js', import.meta.url)))}; globalThis.OpenUIClient=mountWidgetClient;`,
+                        resolveDir: process.cwd(), loader: 'js' }, bundle: true, write: false, format: 'iife', platform: 'browser',
+                    minify: true, target: 'es2023', metafile: true,
+                    plugins: [hostClientPlugin(hostFeatures, options.clientEntry)] });
+                const code = service.outputFiles[0].text;
+                clientRuntime = { ...clientRuntime, bytes: Buffer.byteLength(code), compressedBytes: deflateSync(code, { level: 9 }).length,
+                    containsLanguageRuntime: Object.keys(service.metafile.inputs).some(path => path.includes('@openuidev/lang-core')) };
+            }
+            if (Object.values(bundled.metafile.outputs).some(output => output.imports.length))
+                throw new Error('Widget bundle must not retain external imports');
+        }
+        else if (needsClient)
+            diagnostics.push({ source: 'compiler', code: 'client-entry-required',
+                message: `Supply clientEntry for client component implementations: ${hostFeatures.components.join(', ')}. Plain updatable HTML needs no clientEntry.` });
+        const css = (options.css ?? '') + selected.styles.map(name => options.library.components[name].component.css).join('\n');
+        if (/<\/style/i.test(css))
+            throw new Error('CSS must not contain a closing style tag');
+        const html = `<!doctype html><html><head><meta charset="utf-8"><style>${css}</style></head><body><div id="openui-root">${initialHtml}</div>${javascript ? `<script>${javascript.replace(/<\/script/gi, '<\\/script')}</script>` : ''}</body></html>`;
+        const measurement = {
+            html: { bytes: Buffer.byteLength(html), limit: 32768, accuracy: 'exact' },
+            compressedHtml: { bytes: deflateSync(html, { level: 9 }).length, limit: 4096, accuracy: 'exact' },
+            clientRuntime,
+            headroom: { htmlBytes: 32768 - Buffer.byteLength(html), compressedHtmlBytes: 4096 - deflateSync(html, { level: 9 }).length,
+                accuracy: 'exact', note: 'Remaining whole-document limits; not a guarantee for any particular added content.' },
+            initialData: { bytes: Buffer.byteLength(JSON.stringify(initialData)), accuracy: 'exact' },
+            transportFrame: { bytes: Buffer.byteLength(JSON.stringify(createWidgetUpdate(frame, { ...frame, r: frame.r + 1 }))),
+                limit: 1024, accuracy: 'exact', encoding: 'delta-from-bootstrap',
+                required: needsClient },
+            fullFrame: { bytes: Buffer.byteLength(JSON.stringify(frame)), accuracy: 'exact' },
+            client: { accuracy: 'client-only', checks: ['DOM nodes', 'CPU', 'memory', 'canvas', 'layout', 'gestures'] },
+        };
+        for (const [field, measured] of Object.entries(measurement))
+            if ('limit' in measured && measured.bytes > measured.limit &&
+                (!('required' in measured) || measured.required))
+                diagnostics.push({ source: field === 'transportFrame' ? 'transport' : 'platform', code: 'size-limit', path: field,
+                    message: `${field}: ${measured.bytes} bytes exceeds Telegram's ${measured.limit}-byte limit` });
+        if (html.includes('\0'))
+            diagnostics.push({ source: 'platform', code: 'invalid-html', message: 'Telegram forbids NUL in HTML' });
+        for (const tag of unsupportedElements(initialHtml))
+            diagnostics.push({ source: 'platform', code: 'unsupported-element', path: tag,
+                message: `Telegram profile 1 removes <${tag}>. Use supported HTML or component-defined pointer controls.` });
+        if (/<script\b[^>]*\bsrc\s*=|<link\b[^>]*\bhref\s*=|(?:src\s*=\s*["']?|url\(\s*["']?)https?:|@import\b/i.test(html))
+            diagnostics.push({ source: 'platform', code: 'network-resource',
+                message: 'Telegram does not load network resources. Inline scripts, CSS and data: resources instead.' });
+        const fits = measurement.html.bytes <= measurement.html.limit &&
+            measurement.compressedHtml.bytes <= measurement.compressedHtml.limit;
+        return { mode: options.mode, html, initialData, diagnostics, measurement, fits, profile: TELEGRAM_PROFILE,
+            message: session.message, parts: responseParts(session.message.content) };
+    }
+    finally {
+        session.dispose();
+    }
+}