openui-telegram 0.0.0-stage → 1.0.1

package/dist/controller.d.ts

@@ -0,0 +1,42 @@
+import { WidgetRuntime } from './runtime.js';
+import type { SavedState } from './runtime.js';
+export interface WidgetFrame {
+    i: string;
+    v: number;
+    r: number;
+    h: string;
+    c: ReturnType<WidgetRuntime['clientRecords']>;
+    f: Record<string, unknown>;
+    l: Record<string, string>;
+    e: Record<string, Record<string, string>>;
+    /** CSS dependencies of the rendered components, including render-only components. */
+    s?: string[];
+}
+export type WidgetInput = [instance: string, version: number, revision: number, kind: 'a', action: string] | [
+    instance: string,
+    version: number,
+    revision: number,
+    kind: 'v',
+    field: string,
+    value: unknown
+];
+/** Persist together with the current session source and runtime state. */
+export interface WidgetCheckpoint {
+    instanceId: string;
+    version: number;
+    revision: number;
+    initialFrame?: WidgetFrame;
+}
+/** No Bot API, timers, retries or storage. The application routes a message to its controller. */
+export declare function createWidgetController(runtime: WidgetRuntime, options?: {
+    initialFrame?: WidgetFrame;
+    checkpoint?: WidgetCheckpoint;
+}): {
+    runtime: WidgetRuntime;
+    frame(): Promise<WidgetFrame>;
+    handle(data: string): Promise<boolean>;
+    encode(frame: WidgetFrame, base?: WidgetFrame | undefined): string;
+    save(): SavedState;
+    checkpoint(): WidgetCheckpoint;
+    dispose(): void;
+};

package/dist/controller.js

@@ -0,0 +1,61 @@
+import { WidgetRuntime } from './runtime.js';
+import { encodeTransport, utf8Bytes, TransportSizeError } from './transport.js';
+import { createWidgetUpdate } from './wire.js';
+/** No Bot API, timers, retries or storage. The application routes a message to its controller. */
+export function createWidgetController(runtime, options = {}) {
+    const saved = options.checkpoint;
+    if (saved && (options.initialFrame || saved.instanceId !== runtime.instanceId || saved.version !== runtime.version ||
+        !Number.isSafeInteger(saved.revision) || saved.revision < -1 || saved.initialFrame && saved.initialFrame.r > saved.revision))
+        throw new Error('Checkpoint does not match the runtime or delivery revision');
+    const initialFrame = saved?.initialFrame ?? options.initialFrame;
+    if (initialFrame && (initialFrame.i !== runtime.instanceId || initialFrame.v > runtime.version))
+        throw new Error('Bootstrap belongs to a different interface or newer program');
+    let revision = saved?.revision ?? initialFrame?.r ?? -1;
+    let busy = false;
+    return {
+        runtime,
+        async frame() {
+            const h = await runtime.render();
+            const styles = runtime.requiredStyles();
+            return { i: runtime.instanceId, v: runtime.version, r: ++revision, h,
+                c: runtime.clientRecords(), f: runtime.fieldValues(), e: runtime.formErrors(), l: runtime.nativeLinks,
+                ...(styles.length ? { s: styles } : {}) };
+        },
+        async handle(data) {
+            const bytes = utf8Bytes(data);
+            if (!bytes || bytes > 64)
+                throw new TransportSizeError('request', bytes, 64);
+            const input = JSON.parse(data);
+            if (!Array.isArray(input) || input[0] !== runtime.instanceId || input[1] !== runtime.version || input[2] !== revision)
+                throw new Error('Stale input or wrong interface instance/version');
+            if (busy)
+                throw new Error('An action is already executing; application controls delivery order');
+            busy = true;
+            try {
+                if (input[3] === 'a' && input.length === 5 && typeof input[4] === 'string')
+                    return await runtime.click(input[4]);
+                else if (input[3] === 'v' && input.length === 6 && typeof input[4] === 'string') {
+                    runtime.setFieldHandle(input[4], input[5]);
+                    return true;
+                }
+                else
+                    throw new Error('Invalid widget input');
+            }
+            finally {
+                busy = false;
+            }
+        },
+        encode(frame, base = initialFrame) {
+            if (!base)
+                return encodeTransport(frame, 'response');
+            const update = createWidgetUpdate(base, frame);
+            const delta = JSON.stringify(update), full = JSON.stringify(frame);
+            return encodeTransport(utf8Bytes(delta) < utf8Bytes(full) ? update : frame, 'response');
+        },
+        save() { return runtime.snapshot(); },
+        checkpoint() {
+            return structuredClone({ instanceId: runtime.instanceId, version: runtime.version, revision, initialFrame });
+        },
+        dispose() { runtime.dispose(); },
+    };
+}

package/dist/dom.js

@@ -0,0 +1,72 @@
+/** Reconcile using native nodes. Unchanged nodes keep listeners, canvas contexts and local state. */
+const rendered = new WeakMap();
+const remember = (node, source) => {
+    rendered.set(node, source.cloneNode(true));
+    for (const [index, child] of Array.from(node.childNodes).entries())
+        remember(child, source.childNodes[index]);
+};
+/** Discard lifecycle-owned DOM before this boundary is reused by another instance. */
+export function restoreDOM(element) {
+    const source = rendered.get(element);
+    const replacement = source.cloneNode(true);
+    remember(replacement, source);
+    element.replaceWith(replacement);
+}
+export function reconcileDOM(root, html) {
+    const desired = root.ownerDocument.createElement('div');
+    desired.innerHTML = html;
+    const key = (node) => node.nodeType === 1 ?
+        node.getAttribute('data-oui-key') ?? node.getAttribute('data-oui-component') ??
+            node.getAttribute('data-oui-node') ?? node.getAttribute('id') : null;
+    const compatible = (a, b) => a.nodeType === b.nodeType &&
+        (a.nodeType !== 1 || a.tagName === b.tagName && a.namespaceURI === b.namespaceURI);
+    const morph = (a, b) => {
+        const previous = rendered.get(a);
+        if (previous?.isEqualNode(b))
+            return;
+        if (a.nodeType !== 1) {
+            if (a.nodeValue !== b.nodeValue)
+                a.nodeValue = b.nodeValue;
+            return;
+        }
+        const target = a, source = b;
+        const before = previous;
+        for (const attr of Array.from(before?.attributes ?? target.attributes))
+            if (!source.hasAttribute(attr.name))
+                target.removeAttribute(attr.name);
+        for (const attr of Array.from(source.attributes))
+            if (!before || before.getAttribute(attr.name) !== attr.value) {
+                if (attr.namespaceURI)
+                    target.setAttributeNS(attr.namespaceURI, attr.name, attr.value);
+                else
+                    target.setAttribute(attr.name, attr.value);
+            }
+        children(target, source);
+    };
+    const children = (target, source) => {
+        const old = Array.from(target.childNodes).filter(node => !rendered.has(target) || rendered.has(node)), used = new Set();
+        const keyed = new Map(old.filter(n => key(n) !== null).map(n => [key(n), n]));
+        for (const [index, desiredNode] of Array.from(source.childNodes).entries()) {
+            const nodeKey = key(desiredNode);
+            let node = nodeKey !== null ? keyed.get(nodeKey) : old.find(n => !used.has(n) && key(n) === null && compatible(n, desiredNode));
+            if (node && (used.has(node) || !compatible(node, desiredNode)))
+                node = undefined;
+            if (!node) {
+                node = desiredNode.cloneNode(true);
+                remember(node, desiredNode);
+            }
+            else
+                morph(node, desiredNode);
+            rendered.set(node, desiredNode.cloneNode(true));
+            used.add(node);
+            const at = target.childNodes[index] ?? null;
+            if (at !== node)
+                target.insertBefore(node, at);
+        }
+        for (const node of old)
+            if (!used.has(node))
+                target.removeChild(node);
+        rendered.set(target, source.cloneNode(true));
+    };
+    children(root, desired);
+}

package/dist/host-client-bundle.d.ts

@@ -0,0 +1,19 @@
+import type { Plugin } from 'esbuild';
+import type { Library, ParseResult } from '@openuidev/lang-core';
+import type { WidgetComponent } from './runtime.js';
+export interface WidgetClientFeatures {
+    specialized: boolean;
+    /** Bundled lifecycle implementations; render-only components run in the application. */
+    components: string[];
+    /** Component styles retained for the initial program and explicitly reserved patches. */
+    styles: string[];
+    lifecycle: boolean;
+    fields: boolean;
+    forms: boolean;
+    mount: boolean;
+    events: boolean;
+    text: boolean;
+}
+export declare function widgetClientFeatures(parsed: ParseResult, library: Library<WidgetComponent>, initialTypes: string[], extra?: string[], specialized?: boolean): WidgetClientFeatures;
+/** Only widget bundles are transformed; application implementations remain intact. */
+export declare function hostClientPlugin(features: WidgetClientFeatures, entry?: string): Plugin;

package/dist/host-client-bundle.js

@@ -0,0 +1,183 @@
+import { parse } from 'acorn';
+import { readFile } from 'node:fs/promises';
+import { resolve, extname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { transform } from 'esbuild';
+/** Unknown callback shapes retain the full context, including aliases/rest/arguments. */
+function contextServices(callback) {
+    const full = { fields: true, forms: true, events: true, text: true }, empty = { fields: false, forms: false, events: false, text: false };
+    if (!callback)
+        return empty;
+    let fn;
+    const source = callback.toString();
+    if (/\barguments\b/.test(source))
+        return full;
+    try {
+        fn = parse(`(${source})`, { ecmaVersion: 'latest' }).body[0].expression;
+    }
+    catch {
+        try {
+            fn = parse(`({${source}})`, { ecmaVersion: 'latest' }).body[0].expression.properties[0].value;
+        }
+        catch {
+            return full;
+        }
+    }
+    const parameter = fn.params[0];
+    if (!parameter)
+        return empty;
+    if (parameter.type !== 'ObjectPattern' || parameter.properties.some((p) => p.type === 'RestElement'))
+        return full;
+    const keys = parameter.properties.map((p) => p.computed ? null : p.key.name ?? p.key.value);
+    return keys.includes(null) ? full : { fields: keys.includes('field'), forms: keys.includes('form'), events: keys.includes('on'), text: keys.includes('text') };
+}
+export function widgetClientFeatures(parsed, library, initialTypes, extra = [], specialized = true) {
+    const names = new Set([...initialTypes, ...extra]);
+    for (const name of extra)
+        if (!Object.hasOwn(library.components, name))
+            throw new TypeError(`Unknown client component ${name}`);
+    const schema = library.toJSONSchema();
+    let opaque = false;
+    const visit = (value) => {
+        if (!value || typeof value !== 'object')
+            return;
+        if (value.type === 'element')
+            names.add(value.typeName);
+        if (value.k === 'Comp') {
+            if (Object.hasOwn(library.components, value.name))
+                names.add(value.name);
+            // A custom function returning arbitrary data may manufacture elements.
+            const returns = schema.functions?.[value.name]?.returns;
+            if (Object.hasOwn(library.functions ?? {}, value.name) && !['string', 'number', 'boolean', 'null', 'integer'].includes(returns?.type))
+                opaque = true;
+        }
+        for (const child of Object.values(value))
+            if (Array.isArray(child))
+                child.forEach(visit);
+            else
+                visit(child);
+    };
+    visit(parsed);
+    if (['StateRef', 'RuntimeRef'].includes(parsed.rootExpression?.k ?? ''))
+        opaque = true;
+    if (!specialized || opaque)
+        Object.keys(library.components).forEach(name => names.add(name));
+    const components = [...names].filter(name => {
+        const component = library.components[name]?.component;
+        return component?.mount || component?.update;
+    }).sort();
+    let fields = !specialized, forms = !specialized, events = !specialized, text = !specialized;
+    for (const name of components)
+        for (const callback of [library.components[name].component.mount, library.components[name].component.update]) {
+            const services = contextServices(callback);
+            fields ||= services.fields;
+            forms ||= services.forms;
+            events ||= services.events;
+            text ||= services.text;
+        }
+    const styles = [...names].filter(name => library.components[name]?.component?.css).sort();
+    return { specialized, components, styles, lifecycle: !specialized || components.length > 0, fields, forms, events, text,
+        mount: !specialized || components.some(name => !!library.components[name].component.mount) };
+}
+const pure = (node) => !!node && (['Literal', 'FunctionExpression', 'ArrowFunctionExpression'].includes(node.type) ||
+    node.type === 'ArrayExpression' && node.elements.every((n) => !n || pure(n)) ||
+    node.type === 'ObjectExpression' && node.properties.every((p) => p.type === 'Property' && !p.computed && p.kind === 'init' && pure(p.value)));
+const usesReceiver = (node) => !!node && typeof node === 'object' &&
+    (node.type === 'ThisExpression' || Object.values(node).some(value => Array.isArray(value) ? value.some(usesReceiver) : usesReceiver(value)));
+/** Only widget bundles are transformed; application implementations remain intact. */
+export function hostClientPlugin(features, entry) {
+    return { name: 'widget-client-specialization', setup(build) {
+            build.onLoad({ filter: /[\\/]client\.js$/ }, async ({ path }) => {
+                if (resolve(path) !== resolve(fileURLToPath(new URL('./client.js', import.meta.url))))
+                    return;
+                const source = await readFile(path, 'utf8');
+                const ast = parse(source, { ecmaVersion: 'latest', sourceType: 'module' });
+                const values = { CLIENT_LIFECYCLE: features.lifecycle, CLIENT_FIELDS: features.fields, CLIENT_FORMS: features.forms,
+                    CLIENT_MOUNT: features.mount, CLIENT_CLEANUPS: features.mount || features.events, CLIENT_EVENTS: features.events, CLIENT_TEXT: features.text };
+                const edits = [];
+                const visit = (node) => {
+                    if (!node || typeof node !== 'object')
+                        return;
+                    if (node.type === 'ImportDeclaration' && node.source.value === './client-features.js') {
+                        edits.push({ start: node.start, end: node.end, text: '' });
+                        return;
+                    }
+                    if (node.type === 'Identifier' && Object.hasOwn(values, node.name)) {
+                        edits.push({ start: node.start, end: node.end, text: String(values[node.name]) });
+                        return;
+                    }
+                    for (const value of Object.values(node))
+                        if (Array.isArray(value))
+                            value.forEach(visit);
+                        else if (value && typeof value === 'object')
+                            visit(value);
+                };
+                visit(ast);
+                let contents = source;
+                for (const edit of edits.sort((a, b) => b.start - a.start))
+                    contents = contents.slice(0, edit.start) + edit.text + contents.slice(edit.end);
+                return { contents, loader: 'js' };
+            });
+            if (!features.specialized || !entry)
+                return;
+            build.onLoad({ filter: /\.[cm]?[jt]sx?$/ }, async ({ path }) => {
+                if (resolve(path) !== resolve(entry))
+                    return;
+                const original = await readFile(path, 'utf8');
+                const extension = extname(path);
+                const loader = extension === '.tsx' ? 'tsx' : extension === '.jsx' ? 'jsx' : /\.[cm]?ts$/.test(extension) ? 'ts' : 'js';
+                const source = (await transform(original, { loader, target: 'es2023' })).code;
+                const ast = parse(source, { ecmaVersion: 'latest', sourceType: 'module' });
+                // The registry may be used as an internal dependency (including computed
+                // lookups). Keep that module intact rather than break a callback/helper.
+                let registryUsed = false;
+                const references = (node, parent) => {
+                    if (!node || typeof node !== 'object')
+                        return;
+                    if (node.type === 'Identifier' && node.name === 'components' &&
+                        !(parent?.type === 'VariableDeclarator' && parent.id === node) && parent?.type !== 'ExportSpecifier' &&
+                        !(parent?.type === 'Property' && parent.key === node && !parent.computed && !parent.shorthand))
+                        registryUsed = true;
+                    for (const value of Object.values(node))
+                        if (Array.isArray(value))
+                            value.forEach(child => references(child, node));
+                        else if (value && typeof value === 'object')
+                            references(value, node);
+                };
+                references(ast);
+                if (registryUsed)
+                    return { contents: source, loader: 'js' };
+                const edits = [];
+                for (const top of ast.body) {
+                    const declaration = top.declaration ?? top;
+                    if (declaration.type !== 'VariableDeclaration' || declaration.kind !== 'const')
+                        continue;
+                    for (const item of declaration.declarations) {
+                        if (item.id.name !== 'components' || item.init?.type !== 'ObjectExpression')
+                            continue;
+                        const properties = item.init.properties.filter((property) => {
+                            if (property.type !== 'Property' || property.computed || property.kind !== 'init')
+                                return true;
+                            const name = property.key.name ?? property.key.value;
+                            return features.components.includes(name) || !pure(property.value);
+                        }).map((property) => {
+                            if (property.type !== 'Property' || property.value.type !== 'ObjectExpression')
+                                return source.slice(property.start, property.end);
+                            if (property.value.properties.some((p) => p.type === 'Property' &&
+                                ['mount', 'update'].includes(p.key.name ?? p.key.value) && usesReceiver(p.value)))
+                                return source.slice(property.start, property.end);
+                            const body = property.value.properties.filter((p) => p.type !== 'Property' || p.computed ||
+                                !['render', 'css', 'reactive'].includes(p.key.name ?? p.key.value) || !pure(p.value));
+                            return source.slice(property.start, property.value.start) + '{' + body.map((p) => source.slice(p.start, p.end)).join(',') + '}';
+                        });
+                        edits.push({ start: item.init.start, end: item.init.end, text: '{' + properties.join(',') + '}' });
+                    }
+                }
+                let contents = source;
+                // A module has at most one top-level const binding named components.
+                for (const edit of edits)
+                    contents = contents.slice(0, edit.start) + edit.text + contents.slice(edit.end);
+                return { contents, loader: 'js' };
+            });
+        } };
+}

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+export { compileWidget } from './compiler.js';
+export type { CompileOptions } from './compiler.js';
+export type { WidgetClientFeatures } from './host-client-bundle.js';
+export { createInterface, defineWidgetComponent, WidgetSession } from './session.js';
+export { WidgetRuntime, runtimeLibrary, text } from './runtime.js';
+export type { Diagnostic, Operation, OperationReply, SavedState, ComponentContext, ClientContext, WidgetComponent, RuntimeLibrary, RuntimeOptions, FieldDescriptor } from './runtime.js';
+export { TELEGRAM_PROFILE, TransportSizeError, encodeTransport, utf8Bytes } from './transport.js';
+export type { StateUpdate, TelegramEnvironment } from './transport.js';
+export { createWidgetController } from './controller.js';
+export type { WidgetFrame, WidgetInput, WidgetCheckpoint } from './controller.js';
+export { responseParts } from './message.js';
+export type { ResponsePart } from './message.js';
+export { createWidgetUpdate } from './wire.js';
+export { applyWidgetUpdate } from './wire-apply.js';
+export type { WidgetUpdate, FrameChange } from './wire-apply.js';

package/dist/index.js

@@ -0,0 +1,8 @@
+export { compileWidget } from './compiler.js';
+export { createInterface, defineWidgetComponent, WidgetSession } from './session.js';
+export { WidgetRuntime, runtimeLibrary, text } from './runtime.js';
+export { TELEGRAM_PROFILE, TransportSizeError, encodeTransport, utf8Bytes } from './transport.js';
+export { createWidgetController } from './controller.js';
+export { responseParts } from './message.js';
+export { createWidgetUpdate } from './wire.js';
+export { applyWidgetUpdate } from './wire-apply.js';

package/dist/javascript-data.js

@@ -0,0 +1,39 @@
+/** Emit data literals, never executable input strings. Unlike JSON syntax used as
+ * JavaScript, computed __proto__ keys preserve own properties without changing prototypes. */
+export function javascriptData(value, ancestors = new Set()) {
+    if (value === null)
+        return 'null';
+    if (value === undefined)
+        return 'void 0';
+    if (typeof value === 'string')
+        return JSON.stringify(value).replace(/</g, '\\u003c').replace(/\u2028/g, '\\u2028').replace(/\u2029/g, '\\u2029');
+    if (typeof value === 'boolean')
+        return String(value);
+    if (typeof value === 'number')
+        return Object.is(value, -0) ? '-0' : String(value);
+    if (typeof value !== 'object' || ancestors.has(value))
+        throw new TypeError('Bootstrap data must be acyclic data values');
+    if (Object.getOwnPropertySymbols(value).length)
+        throw new TypeError('Symbol properties cannot be embedded');
+    ancestors.add(value);
+    try {
+        if (Array.isArray(value)) {
+            const elements = Array.from({ length: value.length }, (_, i) => Object.hasOwn(value, i) ? javascriptData(value[i], ancestors) : '');
+            return '[' + elements.join(',') + (value.length && !Object.hasOwn(value, value.length - 1) ? ',' : '') + ']';
+        }
+        const prototype = Object.getPrototypeOf(value);
+        if (prototype !== null && prototype !== Object.prototype)
+            throw new TypeError('Bootstrap objects must be plain data');
+        const properties = Object.entries(Object.getOwnPropertyDescriptors(value)).map(([key, descriptor]) => {
+            if (!('value' in descriptor))
+                throw new TypeError('Accessor properties cannot be embedded');
+            const name = key === '__proto__' ? `[${javascriptData(key)}]` : javascriptData(key);
+            return `${name}:${javascriptData(descriptor.value, ancestors)}`;
+        });
+        const object = '{' + properties.join(',') + '}';
+        return prototype === null ? `Object.assign(Object.create(null),${object})` : object;
+    }
+    finally {
+        ancestors.delete(value);
+    }
+}

package/dist/message.d.ts

@@ -0,0 +1,10 @@
+export interface ResponsePart {
+    kind: 'text' | 'code';
+    language?: string;
+    content: string;
+    raw: string;
+    complete: boolean;
+}
+/** Preserve prose and code separately. Language parsing still goes through upstream,
+ * using the original content, not a reconstruction of these presentation segments. */
+export declare function responseParts(content: string): ResponsePart[];

package/dist/message.js

@@ -0,0 +1,44 @@
+/** Preserve prose and code separately. Language parsing still goes through upstream,
+ * using the original content, not a reconstruction of these presentation segments. */
+export function responseParts(content) {
+    const parts = [];
+    let raw = '', body = '', language, fenced = false, quoted = false;
+    const flush = (complete) => {
+        if (raw)
+            parts.push({ kind: fenced ? 'code' : 'text', language, content: fenced ? body : raw, raw, complete });
+        raw = '';
+        body = '';
+    };
+    for (const line of content.match(/[^\n]*\n|[^\n]+$/g) ?? []) {
+        const fence = !quoted && /^[ \t]*```[ \t]*([\w.+-]*)[ \t]*(.*?)[ \t]*\r?\n?$/.exec(line);
+        if (fence) {
+            if (fenced) {
+                raw += line;
+                flush(true);
+                fenced = false;
+                language = undefined;
+            }
+            else {
+                flush(true);
+                fenced = true;
+                language = fence[1];
+                raw = line;
+                body = fence[2] ? fence[2] + '\n' : '';
+            }
+        }
+        else {
+            raw += line;
+            if (fenced) {
+                body += line;
+                for (let i = 0; i < line.length; i++) {
+                    if (line[i] === '\\' && quoted)
+                        i++;
+                    else if (line[i] === '"')
+                        quoted = !quoted;
+                }
+            }
+        }
+    }
+    flush(!fenced);
+    return parts;
+}