openui-telegram 0.0.0-stage → 1.0.0

package/dist/session.d.ts

@@ -0,0 +1,40 @@
+import { parseMessage } from '@openuidev/lang-core';
+import type { Library, ParseResult } from '@openuidev/lang-core';
+import { z } from 'zod';
+import { WidgetRuntime } from './runtime.js';
+import type { RuntimeOptions, WidgetComponent } from './runtime.js';
+/** Props stay inferred; all synchronization belongs to WidgetRuntime. */
+export declare function defineWidgetComponent<T extends z.ZodObject>(config: {
+    name: string;
+    description: string;
+    props: T;
+} & WidgetComponent<z.output<T>>): import("@openuidev/lang-core").DefinedComponent<T, WidgetComponent<any>>;
+export declare class WidgetSession {
+    readonly library: Library<WidgetComponent>;
+    readonly runtime: WidgetRuntime;
+    source: string;
+    message: ReturnType<typeof parseMessage>;
+    private parser;
+    private streamingParser;
+    private stream;
+    private complete;
+    constructor(library: Library<WidgetComponent>, source: string, options: RuntimeOptions);
+    update(source: string): ParseResult;
+    patch(patch: string): ParseResult;
+    push(chunk: string, complete?: boolean): ParseResult;
+    resetStream(): void;
+    get parts(): import("./message.js").ResponsePart[];
+    get diagnostics(): ({
+        code: import("@openuidev/lang-core").ValidationErrorCode;
+        component: string;
+        path: string;
+        message: string;
+        statementId?: string;
+        severity?: "warning";
+        source: 'parser';
+    } | import("./runtime.js").Diagnostic)[];
+    /** Stored context is deliberately opt-in, following the OpenUI message protocol. */
+    restoreContext(select: (context: unknown) => Parameters<WidgetRuntime['restore']>[0]): void;
+    dispose(): void;
+}
+export declare function createInterface(library: Library<WidgetComponent>, source: string, options: RuntimeOptions): WidgetSession;

package/dist/session.js

@@ -0,0 +1,71 @@
+import { createParser, createStreamingParser, defineComponent, mergeStatements, parseMessage, markReactive, isReactiveSchema } from '@openuidev/lang-core';
+import { z } from 'zod';
+import { WidgetRuntime, runtimeLibrary } from './runtime.js';
+import { responseParts } from './message.js';
+/** Props stay inferred; all synchronization belongs to WidgetRuntime. */
+export function defineWidgetComponent(config) {
+    const { name, description, props, ...component } = config;
+    let registered = props;
+    const shape = { ...props.shape };
+    for (const key of config.reactive ?? []) {
+        if (!Object.hasOwn(props.shape, key))
+            throw new TypeError(`Unknown reactive prop ${name}.${key}`);
+        shape[key] = props.shape[key].clone();
+        markReactive(shape[key]);
+    }
+    if (config.reactive?.length)
+        registered = props.clone({ ...props.def, shape }, { parent: true });
+    const reactive = Object.keys(registered.shape).filter(key => isReactiveSchema(registered.shape[key]));
+    if (reactive.length)
+        component.reactive = reactive;
+    return defineComponent({ name, description, props: registered, component });
+}
+export class WidgetSession {
+    library;
+    runtime;
+    source;
+    message;
+    parser;
+    streamingParser;
+    stream = '';
+    complete = true;
+    constructor(library, source, options) {
+        this.library = library;
+        this.parser = createParser(library.toJSONSchema(), library.root);
+        this.streamingParser = createStreamingParser(library.toJSONSchema(), library.root);
+        this.source = source;
+        this.message = parseMessage(source);
+        this.runtime = new WidgetRuntime(runtimeLibrary(library), this.parser.parse(this.message.content), options);
+    }
+    update(source) {
+        this.complete = true;
+        this.message = parseMessage(source);
+        this.source = source;
+        this.runtime.replace(this.parser.parse(this.message.content));
+        return this.runtime.parsed;
+    }
+    patch(patch) { return this.update(mergeStatements(this.message.content, parseMessage(patch).content)); }
+    push(chunk, complete = false) {
+        this.complete = complete;
+        this.stream += chunk;
+        this.message = parseMessage(this.stream, { streaming: !complete });
+        this.source = this.stream;
+        const result = this.streamingParser.set(this.message.content, complete);
+        this.runtime.replace(result);
+        return result;
+    }
+    resetStream() { this.stream = ''; }
+    get parts() { return responseParts(this.message.content); }
+    get diagnostics() {
+        return [...(this.complete ? this.runtime.parsed.meta.errors.map(e => ({ ...e, source: 'parser' })) : []),
+            ...this.runtime.diagnostics];
+    }
+    /** Stored context is deliberately opt-in, following the OpenUI message protocol. */
+    restoreContext(select) {
+        this.runtime.restore(select(this.message.context));
+    }
+    dispose() { this.runtime.dispose(); }
+}
+export function createInterface(library, source, options) {
+    return new WidgetSession(library, source, options);
+}

package/dist/transport.d.ts

@@ -0,0 +1,37 @@
+import type { SavedState } from './runtime.js';
+export declare const TELEGRAM_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;
+};
+export declare function utf8Bytes(value: string): number;
+export declare class TransportSizeError extends RangeError {
+    readonly field: string;
+    readonly bytes: number;
+    readonly limit: number;
+    constructor(field: string, bytes: number, limit: number);
+}
+export declare function encodeTransport(value: unknown, field: 'request' | 'response' | 'state'): string;
+export interface StateUpdate {
+    instanceId: string;
+    version: number;
+    revision: number;
+    state: SavedState;
+}
+export interface TelegramEnvironment {
+    request(data: string): Promise<{
+        result: string | null;
+    }>;
+    chatData: string | null;
+    onEvent(event: string, handler: () => void): void;
+    offEvent(event: string, handler: () => void): void;
+    openLink(url: string): void;
+    openTelegramLink(url: string): void;
+    ready?(): void;
+}

package/dist/transport.js

@@ -0,0 +1,34 @@
+const REQUEST_LIMIT = 64, RESPONSE_LIMIT = 1024;
+export const TELEGRAM_PROFILE = {
+    profile: 1, documentationChecked: '2026-11-11', openui: '1.1.0', language: '1.0 (inherits 0.5)',
+    html: 32768, compressedHtml: 4096, request: REQUEST_LIMIT, response: RESPONSE_LIMIT, state: RESPONSE_LIMIT,
+};
+// QuickJS does not need TextEncoder for byte accounting.
+export function utf8Bytes(value) {
+    let bytes = 0;
+    for (const c of value) {
+        const cp = c.codePointAt(0);
+        bytes += cp < 0x80 ? 1 : cp < 0x800 ? 2 : cp < 0x10000 ? 3 : 4;
+    }
+    return bytes;
+}
+export class TransportSizeError extends RangeError {
+    field;
+    bytes;
+    limit;
+    constructor(field, bytes, limit) {
+        super(`${field} is ${bytes} UTF-8 bytes; Telegram allows ${limit}`);
+        this.field = field;
+        this.bytes = bytes;
+        this.limit = limit;
+    }
+}
+export function encodeTransport(value, field) {
+    const result = JSON.stringify(value);
+    if (result === undefined)
+        throw new TypeError('Transport value must be JSON serializable');
+    const size = utf8Bytes(result), limit = field === 'request' ? REQUEST_LIMIT : RESPONSE_LIMIT;
+    if (size > limit)
+        throw new TransportSizeError(field, size, limit);
+    return result;
+}

package/dist/wire-apply.d.ts

@@ -0,0 +1,17 @@
+import type { WidgetFrame } from './controller.js';
+export type FrameChange = [0, string[], unknown] | [1, string[]] | [2, string[], [number, number, string][]] | [
+    3,
+    string[],
+    number,
+    number,
+    unknown[]
+];
+export interface WidgetUpdate {
+    i: string;
+    v: number;
+    r: number;
+    b: [version: number, revision: number];
+    d: FrameChange[];
+}
+/** Apply atomically against the exact base, including when a patch changes the program version. */
+export declare function applyWidgetUpdate(base: WidgetFrame, update: WidgetUpdate): WidgetFrame;

package/dist/wire-apply.js

@@ -0,0 +1,48 @@
+/** Apply atomically against the exact base, including when a patch changes the program version. */
+export function applyWidgetUpdate(base, update) {
+    if (update.i !== base.i || update.b[0] !== base.v || update.b[1] !== base.r)
+        throw new Error('Update requires a different base frame');
+    if (update.v < base.v || update.v === base.v && update.r <= base.r)
+        throw new Error('Obsolete frame update');
+    const result = JSON.parse(JSON.stringify(base));
+    for (const change of update.d) {
+        const [kind, path] = change;
+        if (!path.length || !['h', 'c', 'f', 'e', 'l', 's'].includes(path[0]))
+            throw new Error('Invalid update path');
+        let parent = result;
+        for (const key of path.slice(0, -1)) {
+            if (!parent || typeof parent !== 'object' || !Object.prototype.hasOwnProperty.call(parent, key))
+                throw new Error('Missing update parent');
+            parent = parent[key];
+        }
+        const key = path[path.length - 1];
+        if (kind === 3) {
+            if (!Array.isArray(parent[key]))
+                throw new Error('Array update requires an array');
+            const [, , start, remove, items] = change;
+            if (!Number.isInteger(start) || !Number.isInteger(remove) || start < 0 || remove < 0 || start + remove > parent[key].length)
+                throw new Error('Invalid array update range');
+            parent[key].splice(start, remove, ...items);
+        }
+        else if (kind === 1)
+            delete parent[key];
+        else {
+            let value = change[2];
+            if (kind === 2) {
+                if (typeof parent[key] !== 'string')
+                    throw new Error('Text update requires a string');
+                let text = parent[key];
+                for (const [offset, remove, insert] of [...change[2]].reverse()) {
+                    if (!Number.isInteger(offset) || !Number.isInteger(remove) || offset < 0 || remove < 0 || offset + remove > text.length)
+                        throw new Error('Invalid text update range');
+                    text = text.slice(0, offset) + insert + text.slice(offset + remove);
+                }
+                value = text;
+            }
+            Object.defineProperty(parent, key, { value, enumerable: true, configurable: true, writable: true });
+        }
+    }
+    result.v = update.v;
+    result.r = update.r;
+    return result;
+}

package/dist/wire.d.ts

@@ -0,0 +1,3 @@
+import type { WidgetFrame } from './controller.js';
+import type { WidgetUpdate } from './wire-apply.js';
+export declare function createWidgetUpdate(base: WidgetFrame, next: WidgetFrame): WidgetUpdate;

package/dist/wire.js

@@ -0,0 +1,68 @@
+import { diffChars } from 'diff';
+import { utf8Bytes } from './transport.js';
+export function createWidgetUpdate(base, next) {
+    if (base.i !== next.i)
+        throw new Error('Cannot diff different interface instances');
+    const changes = [];
+    const diff = (a, b, path) => {
+        if (JSON.stringify(a) === JSON.stringify(b))
+            return;
+        if (typeof a === 'string' && typeof b === 'string') {
+            let offset = 0, edit;
+            const edits = [];
+            for (const part of diffChars(a, b)) {
+                if (!part.added && !part.removed) {
+                    offset += part.value.length;
+                    edit = undefined;
+                    continue;
+                }
+                if (!edit) {
+                    edit = [offset, 0, ''];
+                    edits.push(edit);
+                }
+                if (part.removed) {
+                    edit[1] += part.value.length;
+                    offset += part.value.length;
+                }
+                else
+                    edit[2] += part.value;
+            }
+            const delta = [2, path, edits], replacement = [0, path, b];
+            changes.push(utf8Bytes(JSON.stringify(delta)) < utf8Bytes(JSON.stringify(replacement)) ? delta : replacement);
+        }
+        else if (Array.isArray(a) && Array.isArray(b)) {
+            if (a.length === b.length) {
+                for (let i = 0; i < a.length; i++)
+                    diff(a[i], b[i], [...path, String(i)]);
+            }
+            else {
+                let start = 0, end = 0;
+                while (start < Math.min(a.length, b.length) && JSON.stringify(a[start]) === JSON.stringify(b[start]))
+                    start++;
+                while (end < Math.min(a.length, b.length) - start && JSON.stringify(a[a.length - 1 - end]) === JSON.stringify(b[b.length - 1 - end]))
+                    end++;
+                changes.push([3, path, start, a.length - start - end, b.slice(start, b.length - end)]);
+            }
+        }
+        else if (a && b && typeof a === 'object' && typeof b === 'object' && !Array.isArray(a) && !Array.isArray(b)) {
+            for (const key of Object.keys(a))
+                if (!Object.hasOwn(b, key))
+                    changes.push([1, [...path, key]]);
+            for (const key of Object.keys(b)) {
+                if (!Object.hasOwn(a, key))
+                    changes.push([0, [...path, key], b[key]]);
+                else
+                    diff(a[key], b[key], [...path, key]);
+            }
+        }
+        else
+            changes.push([0, path, b]);
+    };
+    for (const key of ['h', 'c', 'f', 'e', 'l', 's']) {
+        if (base[key] !== undefined && next[key] === undefined)
+            changes.push([1, [key]]);
+        else
+            diff(base[key], next[key], [key]);
+    }
+    return { i: next.i, v: next.v, r: next.r, b: [base.v, base.r], d: changes };
+}

package/package.json

@@ -1,6 +1,60 @@
 {
   "name": "openui-telegram",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "type": "module",
+  "description": "Compile OpenUI Lang into self-contained Telegram widgets with an application-owned runtime and transport",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "engines": {
+    "node": "^22.15.0 || ^24.0.0 || ^26.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pavel-voronin/openui-telegram.git"
+  },
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./client": {
+      "types": "./dist/client.d.ts",
+      "import": "./dist/client.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "typecheck": "npm run build && node scripts/build.mjs --support",
+    "test": "npm run typecheck && node --experimental-test-module-mocks --test test/*.test.js",
+    "test:coverage": "npm run typecheck && node --experimental-test-coverage --experimental-test-module-mocks --test-coverage-include=dist/** --test-coverage-lines=100 --test-coverage-branches=100 --test-coverage-functions=100 --test test/*.test.js",
+    "check:package": "node scripts/check-package.mjs",
+    "check": "npm run test:coverage && npm run check:package",
+    "demo:simple": "npm run typecheck && node examples/demo-server.mjs simple",
+    "demo:full": "npm run typecheck && node examples/demo-server.mjs full",
+    "demo:telegram": "npm run typecheck && node examples/telegram.mjs",
+    "prepare": "npm run build",
+    "prepack": "npm run build"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.5",
+    "linkedom": "^0.18.15",
+    "typescript": "^7.0.2",
+    "zod": "^4.6.7"
+  },
+  "dependencies": {
+    "@openuidev/lang-core": "1.1.0",
+    "acorn": "^8.19.0",
+    "diff": "^9.0.0",
+    "esbuild": "^0.25.12"
+  },
+  "peerDependencies": {
+    "zod": "^4.0.0"
+  }
+}