@keemakr/ui-sdk 1.5.0 → 1.6.0-dev-20261026112734

package/dist/negotiate.js

@@ -0,0 +1,1092 @@
+// ui-sdk negotiation (C1.6): what each client can draw, and the tree core sends it.
+//
+// A client parses the whole screen tree with the ui-sdk bundled in the @fsztpartners/sdk it was
+// built with, and throws on any node or value that parse does not know, so one newer node fails
+// the WHOLE screen. A client that parses a node may still have no renderer arm for it, so the node
+// vanishes without a sign. And a field its parse does not know is stripped without a sign, which
+// for a `confirm` or a `disabled` flag means a control that acts when it should ask or refuse.
+// Core is the only party that knows both the tree and the client (`X-Kee-Client`), so core
+// rewrites the tree before it answers:
+//   1. each node the client cannot draw becomes a `text` or `markdown` node every client draws;
+//   2. each feature it cannot draw is folded away or made safe (below);
+//   3. the result is checked against the schema that client REALLY parses with, a frozen copy of
+//      the published release (published/), and fitted to it (conform.ts).
+//
+// The node sets live here, not in core, so the testkit (`@keemakr/ui-sdk/testkit`)
+// checks a module's screens against exactly what core sends.
+//
+// Adding a node or a field kind: add it to the schema; the `current` snapshot follows it. Add it to
+// a client row only when that client's release draws it AND parses it. The lockstep test in core
+// (tests/sdk/ui-negotiation.test.ts) fails until the current snapshot matches KNOWN_NODE_TYPES,
+// until every node type has a fallback, and until every sample tree, negotiated for every row,
+// parses with that row's published schema with no safety field lost.
+import { foldTableCell, isNewerTableCell } from './cells.js';
+import { conformTree } from './conform.js';
+import { withoutScreenLinks } from './markdown-links.js';
+import { pageRangeLabel } from './pager.js';
+import { formatPlayhead, isSeekPress } from './player.js';
+import { stackedBarParts } from './stacked-bar.js';
+import { PUBLISHED_PARSERS } from './published/index.js';
+import { foldTabs, TABS_MAX_1_4_0 } from './tabs.js';
+/** The features ui-sdk 1.4.0 draws: every one but those added after it. */
+const FEATURES_1_4_0 = [
+    'breadcrumbs',
+    'button.disabled',
+    'section.row',
+    'form.field_kinds',
+    'form.confirm',
+];
+/** Every feature: what this package parses and core's own renderer draws. */
+const ALL_FEATURES = [
+    ...FEATURES_1_4_0,
+    'press.chat',
+    'form.radio',
+    'table.cells',
+    'header.meta',
+    'tabs.many',
+    'choice.action',
+    'markdown.links',
+    'form.disabled',
+    'press.seek',
+    'edit.inline',
+];
+/** The nodes of ui-sdk 1.1.0 and 1.2.0 (one schema). */
+const NODES_1_1_0 = [
+    'heading',
+    'text',
+    'markdown',
+    'stat',
+    'button',
+    'form',
+    'table',
+    'timeline',
+    'pending_request',
+    'pending_requests',
+    'choice_cards',
+    'progress',
+    'chart',
+    'section',
+    'tabs',
+];
+/** The nodes of the published ui-sdk 1.4.0: 1.1.0's, 1.3.0's five, and the twelve KEE-1009 blocks. */
+const NODES_1_4_0 = [
+    ...NODES_1_1_0,
+    'pagination',
+    'select',
+    'alert',
+    'details',
+    'timestamp',
+    'divider',
+    'board',
+    'link',
+    'tags',
+    'toggle',
+    'segmented',
+    'progress_bar',
+    'conversation',
+    'composer',
+    'calendar',
+    'image',
+    'video',
+];
+/**
+ * The nodes of this package: every published 1.4.0 node, and the ones added since. A node added
+ * here reaches a client only once a row below says that client draws it; until then it gets its
+ * fallback (`fallbackNode`).
+ */
+const NODES_CURRENT = [...NODES_1_4_0, 'stacked_bar', 'heatmap', 'audio'];
+/**
+ * Nodes a module may send that core draws itself before any client sees the tree: a `dataset`
+ * node becomes plain blocks from the module's rows (dataset-view.ts). No client parses them, so
+ * no snapshot lists them; one that reached negotiation undrawn gets its own fallback.
+ */
+export const CORE_DRAWN_NODE_TYPES = ['dataset'];
+/**
+ * What each schema a client can parse with admits. `1.1.0` and `1.4.0` are published releases
+ * (frozen copies in published/); `current` is this package, newer than any released app.
+ */
+export const UI_SDK_SNAPSHOTS = {
+    '1.1.0': { name: 'ui-sdk 1.1.0', nodes: NODES_1_1_0, features: [] },
+    '1.4.0': { name: 'ui-sdk 1.4.0', nodes: NODES_1_4_0, features: FEATURES_1_4_0 },
+    current: { name: 'ui-sdk (this package)', nodes: NODES_CURRENT, features: ALL_FEATURES },
+};
+/** The snapshot this package is. Core's own renderer draws all of it. */
+export const CURRENT_UI_SDK_SNAPSHOT = 'current';
+/**
+ * Every client release core negotiates for, oldest first per client. A client
+ * version below every row of its client gets the floor (ui-sdk 1.1.0).
+ *
+ * Checked 2026-10-20 against kee-clients' release tags and their lockfiles (which sdk, and so which
+ * ui-sdk, each build parses with) and their renderers.
+ */
+export const CLIENT_RELEASES = [
+    {
+        client: 'web',
+        since: '0.0.0',
+        parses: '1.4.0',
+        draws: { nodes: NODES_1_4_0, features: FEATURES_1_4_0 },
+        note: 'Web parses with @fsztpartners/sdk 3.5.0, which bundles ui-sdk 1.4.0, and draws every 1.4.0 ' +
+            'node (NewerBlocks.tsx, listed in its negotiated-nodes.ts), breadcrumbs, button.disabled, ' +
+            'row sections, the typed form fields and form confirms. Every web build before 0.2.0 ' +
+            'reports 0.1.0 (its package version, with the build after a "+"), so this row covers them ' +
+            'all: a tab still open on an older build keeps getting a screen it can parse.',
+    },
+    {
+        client: 'web',
+        since: '0.2.0',
+        parses: '1.4.0',
+        draws: { nodes: NODES_1_4_0, features: FEATURES_1_4_0 },
+        note: 'Web 0.2.0 (kee-clients #901) still pins @fsztpartners/sdk ^3.5.0, and its committed lockfile ' +
+            'installs 3.5.0, which bundles ui-sdk 1.4.0. Only a build that installs the @dev channel ' +
+            '(SDK_CHANNEL=dev) parses the current schema; a production build installs the lockfile. The ' +
+            'newest stable sdk (3.6.0, ui-sdk 1.5.0) still refuses string date bounds. So this row says ' +
+            'what every 0.2.0 build can parse: 1.4.0, with the folds (info and accent tones to the ' +
+            'nearest tone, string date bounds dropped; a screen time zone is kept on the wire, and a ' +
+            'build that parses 1.4.0 ignores it). Point a web row at `current` only once a stable sdk ' +
+            "carrying the current schema is in web's committed lockfile, and freeze that schema first " +
+            '(tests/sdk/ui-published-parsers.test.ts). kee-clients checks a frozen-lockfile build ' +
+            'against this row in CI. A dev-channel build says it parses the current schema instead, and ' +
+            'a non-production core sends it that (CHANNEL_BUILDS below); this row is unchanged by it.',
+    },
+    {
+        client: 'mobile',
+        since: '0.0.0',
+        parses: '1.1.0',
+        draws: { nodes: NODES_1_1_0, features: [] },
+        note: 'Mobile 0.2.0 (the staging build) parses with sdk 2.5.0, which bundles ui-sdk 1.1.0, and ' +
+            'draws its 15 nodes. Its parse drops a form submit confirm, and its renderer posts a form ' +
+            'without asking, so a form with a confirm reaches it as one calm line.',
+    },
+    {
+        client: 'mobile',
+        since: '0.2.3',
+        parses: '1.4.0',
+        draws: {
+            nodes: NODES_1_1_0,
+            features: ['breadcrumbs', 'button.disabled', 'form.field_kinds', 'form.confirm'],
+        },
+        note: 'Mobile 0.2.3 to 0.2.5 parse with sdk 3.5.0 (ui-sdk 1.4.0). The renderer draws the 15 nodes ' +
+            'of 1.1.0, breadcrumbs, disabled buttons (body, header and row actions), every form field ' +
+            'kind and the form confirms. It has no arm for the 1.4.0 blocks, so they get fallbacks. A ' +
+            "'row' section is drawn as a stack, so it is folded to one.",
+    },
+    {
+        client: 'desktop',
+        since: '0.0.0',
+        parses: '1.1.0',
+        draws: { nodes: NODES_1_1_0, features: [] },
+        note: 'Desktop renders no module screens (no desktop release through 0.3.15 calls the screen routes).',
+    },
+    {
+        client: 'extension',
+        since: '0.0.0',
+        parses: '1.1.0',
+        draws: { nodes: NODES_1_1_0, features: [] },
+        note: 'The extension renders no module screens; it gets the floor.',
+    },
+    {
+        client: 'cli',
+        since: '0.0.0',
+        parses: '1.1.0',
+        draws: { nodes: NODES_1_1_0, features: [] },
+        note: 'The CLI renders no module screens; it gets the floor.',
+    },
+];
+/** The floor: what every client that sends `X-Kee-Client` can take. */
+export const FLOOR_NODE_SET = {
+    ...UI_SDK_SNAPSHOTS['1.1.0'],
+    name: 'ui-sdk 1.1.0',
+    parses: '1.1.0',
+};
+/** The rows of one client, oldest first. */
+export function releasesOf(client, releases = CLIENT_RELEASES) {
+    return releases
+        .filter((row) => row.client === client)
+        .sort((a, b) => compareVersions(a.since, b.since));
+}
+/**
+ * What a client draws, from its `X-Kee-Client` platform and version: the newest
+ * row of that client whose `since` it has reached. An unknown platform, or a
+ * version below every row, gets the floor. A version core cannot read counts as
+ * 0.0.0: a client core cannot identify is treated as the oldest, never the newest.
+ */
+export function nodeSetForClient(platform, version, releases = CLIENT_RELEASES) {
+    const rows = releasesOf(platform, releases);
+    if (rows.length === 0)
+        return { ...FLOOR_NODE_SET, name: `${platform || 'unknown'} (floor)` };
+    // An unreadable version compares as 0.0.0: the oldest, never the newest.
+    const row = rows.filter((r) => compareVersions(r.since, version) <= 0).at(-1);
+    if (!row)
+        return { ...FLOOR_NODE_SET, name: `${platform} ${version} (floor)` };
+    return { name: `${platform} ${version || '?'}`, ...row.draws, parses: row.parses };
+}
+/** The build metadata identifier a build that parses the current schema adds to its version. */
+export const CURRENT_SCHEMA_CLAIM = 'ui-current';
+/**
+ * The schema claim in an `X-Kee-Client` value, or null. Read from the build metadata (after the
+ * `+`) only, so a claim never changes the version core compares, and a header without one, or
+ * with anything else, claims nothing.
+ */
+export function uiSchemaClaimOf(header) {
+    if (!header)
+        return null;
+    const version = header.slice(header.indexOf('/') + 1);
+    const plus = version.indexOf('+');
+    if (plus < 0)
+        return null;
+    const build = version
+        .slice(plus + 1)
+        .trim()
+        .split('.');
+    return build.includes(CURRENT_SCHEMA_CLAIM) ? 'current' : null;
+}
+/**
+ * The client builds core may send the current schema, when they claim it and core honours claims
+ * (core's own deployment decides that: src/lib/modules/ui-negotiation.ts). A client with no row
+ * here gets its release row whatever it claims.
+ */
+export const CHANNEL_BUILDS = [
+    {
+        client: 'web',
+        parses: 'current',
+        draws: { nodes: NODES_CURRENT, features: ALL_FEATURES },
+        note: 'A web build that installed the @dev channel (SDK_CHANNEL=dev, the dev deploy) parses with ' +
+            'the newest @dev sdk, which bundles this schema, and says so (`+<commit>.ui-current`). It ' +
+            'gets the screen as written, so new nodes and features can be tried on the dev web app ' +
+            'before a stable sdk carries them. A build from the committed lockfile never says it and ' +
+            'keeps its release row. kee-clients lists what its dev build draws (negotiated-nodes.ts).',
+    },
+];
+/**
+ * What a client draws, given the schema it claims. A `current` claim from a client with a channel
+ * build row gets that row; anything else gets `nodeSetForClient`, exactly as with no claim. A
+ * forged claim gets the forger a screen its own parser may refuse, nothing else: the tree is the
+ * same data for the same session, only less folded.
+ */
+export function nodeSetForClaim(platform, version, claim, builds = CHANNEL_BUILDS) {
+    const build = claim === 'current' ? builds.find((row) => row.client === platform) : undefined;
+    if (!build)
+        return nodeSetForClient(platform, version);
+    return {
+        name: `${platform} ${version || '?'} (${CURRENT_SCHEMA_CLAIM})`,
+        ...build.draws,
+        parses: build.parses,
+    };
+}
+/** The newest release row of a client: what a module targets when it names only the client. */
+export function latestRelease(client) {
+    const row = releasesOf(client).at(-1);
+    if (!row)
+        throw new Error(`no client release for "${client}"`);
+    return row;
+}
+const TEXT_MAX = 5000;
+const MARKDOWN_MAX = 20000;
+const CHILDREN_MAX = 100;
+/** The fallback for a node type that has no specific one: a sign that something is there. */
+export const GENERIC_FALLBACK_TEXT = 'Open this in the web app to see this part of the screen.';
+/**
+ * What stands in for a control that would act without its safety on this client: a form that
+ * would post without its confirm, a button that would press although it is disabled.
+ */
+export const SAFETY_FALLBACK_TEXT = 'Open this in the web app to finish this step.';
+/**
+ * The tree a client with `set` receives: every node it cannot draw replaced with
+ * `text` or `markdown`, every feature it cannot draw folded away. The result
+ * still validates against the ui-sdk schema. A tree that needs nothing is
+ * returned as the same object.
+ */
+export function negotiateTree(tree, set) {
+    const nodes = new Set(set.nodes);
+    const features = new Set(set.features);
+    const fallbacks = [];
+    // The zone the screen's times are drawn in (core fills in the Company's when the module named
+    // none). A stand-in line writes its times in it, read before a fit may take the field away.
+    const zone = tree.timeZone;
+    const visit = (original, path) => {
+        const loose = original;
+        if (!nodes.has(loose.type)) {
+            const replacement = fallbackNode(original, zone);
+            fallbacks.push({ path, type: loose.type, reason: 'node', as: replacement.type });
+            return replacement;
+        }
+        // A client that cannot open its chat, or move a recording, gets no control that offers to.
+        let node = features.has('press.chat')
+            ? original
+            : withoutPresses(original, path, fallbacks, isChatPress, 'press.chat');
+        if (node.type !== 'text' && !features.has('press.seek')) {
+            node = withoutSeeks(node, path, fallbacks);
+        }
+        if (node !== original && node.type === 'text')
+            return node;
+        // A client that draws no edit control gets the block read-only.
+        if (!features.has('edit.inline'))
+            node = withoutInlineEdit(node, path, fallbacks);
+        switch (node.type) {
+            case 'button':
+                if (node.disabled && !features.has('button.disabled')) {
+                    fallbacks.push({ path, type: 'button', reason: 'button.disabled', as: 'text' });
+                    return { type: 'text', value: clip(node.label, TEXT_MAX), muted: true };
+                }
+                return node;
+            case 'section': {
+                const children = visitAll(node.children, `${path}.children`);
+                let next = children === node.children ? node : { ...node, children };
+                if (node.layout === 'row' && !features.has('section.row')) {
+                    fallbacks.push({ path, type: 'section', reason: 'section.row', as: 'folded' });
+                    next = { ...next, layout: 'stack' };
+                }
+                return next;
+            }
+            case 'form': {
+                // A form whose send asks first must not reach a client that would post without asking.
+                const asks = !!node.submit.confirm || (node.secondary ?? []).some((send) => !!send.confirm);
+                if (asks && !features.has('form.confirm')) {
+                    fallbacks.push({ path, type: 'form', reason: 'form.confirm', as: 'text' });
+                    return { type: 'text', value: SAFETY_FALLBACK_TEXT, muted: true };
+                }
+                const form = features.has('form.disabled')
+                    ? node
+                    : foldDisabledSends(node, path, fallbacks);
+                if (form.type === 'text')
+                    return form;
+                const kinds = features.has('form.field_kinds');
+                const radio = features.has('form.radio');
+                if (kinds && radio)
+                    return form;
+                let changed = false;
+                const fields = form.fields.map((field, index) => {
+                    let next = field;
+                    const fold = (reason) => {
+                        changed = true;
+                        fallbacks.push({
+                            path: `${path}.fields[${index}]`,
+                            type: 'form',
+                            reason,
+                            as: 'folded',
+                        });
+                    };
+                    if (!radio && (next.kind === 'radio' || hasOptionExtras(next))) {
+                        next = foldChoiceField(next);
+                        fold('form.radio');
+                    }
+                    if (!kinds && !OLDER_FIELD_KINDS.has(next.kind)) {
+                        next = foldFormField(next);
+                        fold('form.field_kinds');
+                    }
+                    return next;
+                });
+                return changed ? { ...form, fields } : form;
+            }
+            case 'choice_cards':
+                return features.has('choice.action') ? node : foldChoiceActions(node, path, fallbacks);
+            case 'markdown': {
+                if (features.has('markdown.links'))
+                    return node;
+                const value = withoutScreenLinks(node.value);
+                if (value === node.value && node.links === undefined)
+                    return node;
+                fallbacks.push({ path, type: 'markdown', reason: 'markdown.links', as: 'folded' });
+                return { type: 'markdown', value };
+            }
+            case 'tabs': {
+                let changed = false;
+                const tabs = node.tabs.map((tab, index) => {
+                    const children = visitAll(tab.children, `${path}.tabs[${index}].children`);
+                    if (children === tab.children)
+                        return tab;
+                    changed = true;
+                    return { ...tab, children };
+                });
+                const visited = changed ? { ...node, tabs } : node;
+                if (visited.tabs.length > TABS_MAX_1_4_0 && !features.has('tabs.many')) {
+                    fallbacks.push({ path, type: 'tabs', reason: 'tabs.many', as: 'folded' });
+                    return foldTabs(visited);
+                }
+                return visited;
+            }
+            case 'table': {
+                const foldCells = !features.has('table.cells');
+                let changed = false;
+                const rows = node.rows.map((row, index) => {
+                    let next = row;
+                    if (foldCells) {
+                        let cellsChanged = false;
+                        const cells = Object.fromEntries(Object.entries(row.cells).map(([key, cell]) => {
+                            if (!isNewerTableCell(cell))
+                                return [key, cell];
+                            cellsChanged = true;
+                            fallbacks.push({
+                                path: `${path}.rows[${index}].cells.${key}`,
+                                type: 'table',
+                                reason: 'table.cells',
+                                as: 'folded',
+                            });
+                            return [key, foldTableCell(cell)];
+                        }));
+                        if (cellsChanged)
+                            next = { ...next, cells };
+                    }
+                    if (row.expand) {
+                        const children = visitAll(row.expand.children, `${path}.rows[${index}].expand.children`);
+                        if (children !== row.expand.children) {
+                            next = { ...next, expand: { children: children } };
+                        }
+                    }
+                    if (next !== row)
+                        changed = true;
+                    return next;
+                });
+                return changed ? { ...node, rows } : node;
+            }
+            default:
+                return node;
+        }
+    };
+    // Returns the same array when nothing in it changed, so an untouched tree is
+    // returned as the same object and costs no copy.
+    const visitAll = (list, path) => {
+        let changed = false;
+        const out = list.map((child, index) => {
+            const next = visit(child, `${path}[${index}]`);
+            if (next !== child)
+                changed = true;
+            return next;
+        });
+        return changed ? out : list;
+    };
+    let next = tree;
+    const children = visitAll(tree.children, 'children');
+    if (children !== tree.children)
+        next = { ...next, children };
+    if (tree.actions &&
+        (!features.has('button.disabled') || !features.has('press.chat') || !features.has('press.seek'))) {
+        // The header holds buttons only, so one the client cannot draw safely is dropped.
+        const kept = tree.actions.filter((action, index) => {
+            const reason = action.disabled && !features.has('button.disabled')
+                ? 'button.disabled'
+                : isChatPress(action.onPress) && !features.has('press.chat')
+                    ? 'press.chat'
+                    : isSeekPress(action.onPress) && !features.has('press.seek')
+                        ? 'press.seek'
+                        : null;
+            if (!reason)
+                return true;
+            fallbacks.push({ path: `actions[${index}]`, type: 'button', reason, as: 'dropped' });
+            return false;
+        });
+        if (kept.length !== tree.actions.length) {
+            next = { ...next, actions: kept };
+            if (kept.length === 0)
+                delete next.actions;
+        }
+    }
+    // Before the breadcrumbs fold, so a trail line (which says where the screen sits) lands above it.
+    if ((tree.badges || tree.meta) && !features.has('header.meta')) {
+        const line = headerFactsLine(tree, zone);
+        const kept = next.children.length < CHILDREN_MAX;
+        next = { ...next };
+        for (const field of ['badges', 'meta']) {
+            if (!tree[field])
+                continue;
+            delete next[field];
+            fallbacks.push({
+                path: field,
+                type: 'header',
+                reason: 'header.meta',
+                as: kept ? 'text' : 'dropped',
+            });
+        }
+        if (kept) {
+            next = { ...next, children: [{ type: 'text', value: line, muted: true }, ...next.children] };
+        }
+    }
+    if (tree.breadcrumbs && !features.has('breadcrumbs')) {
+        next = { ...next };
+        delete next.breadcrumbs;
+        // The crumbs say where the screen sits; keep that as one muted line above
+        // the content, when the tree has room for one more node.
+        const trail = tree.breadcrumbs.map((crumb) => crumb.label).join(' / ');
+        if (next.children.length < CHILDREN_MAX) {
+            next = {
+                ...next,
+                children: [{ type: 'text', value: clip(trail, TEXT_MAX), muted: true }, ...next.children],
+            };
+            fallbacks.push({
+                path: 'breadcrumbs',
+                type: 'breadcrumbs',
+                reason: 'breadcrumbs',
+                as: 'text',
+            });
+        }
+        else {
+            fallbacks.push({
+                path: 'breadcrumbs',
+                type: 'breadcrumbs',
+                reason: 'breadcrumbs',
+                as: 'dropped',
+            });
+        }
+    }
+    const negotiated = fallbacks.length > 0 ? next : tree;
+    if (!set.parses || set.parses === 'current')
+        return { tree: negotiated, fallbacks };
+    // Fit what is left to the schema this client really parses with (conform.ts).
+    const conformed = conformTree(negotiated, PUBLISHED_PARSERS[set.parses], {
+        fallback: (node) => fallbackNode(node, zone),
+        safetyText: SAFETY_FALLBACK_TEXT,
+        genericText: GENERIC_FALLBACK_TEXT,
+    });
+    if (conformed.fallbacks.length === 0)
+        return { tree: negotiated, fallbacks };
+    return {
+        tree: conformed.tree,
+        fallbacks: [...fallbacks, ...conformed.fallbacks],
+    };
+}
+/** True for a press that opens the chat with a prompt typed in. */
+export function isChatPress(press) {
+    return press?.kind === 'chat';
+}
+/**
+ * A form for a client that draws no disabled send (`form.disabled`): a disabled `secondary` is
+ * dropped, and a form whose `submit` is disabled becomes one calm line. Returns the same object
+ * when no send is disabled.
+ */
+export function foldDisabledSends(node, path, fallbacks) {
+    if (node.submit.disabled) {
+        fallbacks.push({ path, type: 'form', reason: 'form.disabled', as: 'text' });
+        return { type: 'text', value: SAFETY_FALLBACK_TEXT, muted: true };
+    }
+    if (!node.secondary?.some((send) => send.disabled))
+        return node;
+    const secondary = node.secondary.filter((send, index) => {
+        if (!send.disabled)
+            return true;
+        fallbacks.push({
+            path: `${path}.secondary[${index}]`,
+            type: 'form',
+            reason: 'form.disabled',
+            as: 'dropped',
+        });
+        return false;
+    });
+    return secondary.length > 0 ? { ...node, secondary } : omit(node, 'secondary');
+}
+/**
+ * Choice cards for a client that draws no card button (`choice.action`). A card with its own
+ * `onPress` keeps it and loses the button; a card with only the button gets the button's press as
+ * its own, so it can still be acted on (the button's label is not drawn). Returns the same object
+ * when no card has a button.
+ */
+export function foldChoiceActions(node, path, fallbacks) {
+    if (!node.choices.some((choice) => choice.action))
+        return node;
+    const choices = node.choices.map((choice, index) => {
+        if (!choice.action)
+            return choice;
+        const { action, ...rest } = choice;
+        const at = `${path}.choices[${index}]`;
+        if (rest.onPress) {
+            fallbacks.push({
+                path: `${at}.action`,
+                type: 'choice_cards',
+                reason: 'choice.action',
+                as: 'dropped',
+            });
+            return rest;
+        }
+        fallbacks.push({ path: at, type: 'choice_cards', reason: 'choice.action', as: 'folded' });
+        return { ...rest, onPress: action.onPress };
+    });
+    return { ...node, choices };
+}
+/**
+ * The node as a client that draws no edit control should get it (`edit.inline`): the same block,
+ * read-only. Drops `edit` from a `text`, `markdown` or `details` block and its items, and from each
+ * `table` column. Only the node's own fields; a row's expanded children are visited on their own.
+ * Returns the same object when there is nothing to take away.
+ */
+export function withoutInlineEdit(node, path, fallbacks) {
+    const fold = () => fallbacks.push({ path, type: node.type, reason: 'edit.inline', as: 'folded' });
+    switch (node.type) {
+        case 'text':
+        case 'markdown': {
+            if (!node.edit)
+                return node;
+            fold();
+            return omit(node, 'edit');
+        }
+        case 'details': {
+            if (!node.edit && !node.items.some((item) => item.edit))
+                return node;
+            fold();
+            const { edit: _edit, ...rest } = node;
+            void _edit;
+            return {
+                ...rest,
+                items: node.items.map((item) => (item.edit ? omit(item, 'edit') : item)),
+            };
+        }
+        case 'table': {
+            if (!node.columns.some((column) => column.edit))
+                return node;
+            fold();
+            return {
+                ...node,
+                columns: node.columns.map((column) => (column.edit ? omit(column, 'edit') : column)),
+            };
+        }
+        default:
+            return node;
+    }
+}
+/**
+ * The node as a client that cannot run one kind of press should get it: no control left on it that
+ * offers to (see `press.chat` and `press.seek` above). `matches` picks the presses to take away and
+ * `reason` is the feature the client lacks. Only the node's own presses; its child nodes are
+ * visited on their own. Returns the same object when there is nothing to take away.
+ */
+function withoutPresses(node, path, fallbacks, matches, reason) {
+    const dropped = (at, type, as = 'dropped') => fallbacks.push({ path: at, type, reason, as });
+    // A list of buttons without the ones the client cannot run, or the same list when none is.
+    const keepButtons = (list, at) => {
+        if (!list?.some((button) => matches(button.onPress)))
+            return list;
+        return list.filter((button, index) => {
+            if (!matches(button.onPress))
+                return true;
+            dropped(`${at}[${index}]`, 'button');
+            return false;
+        });
+    };
+    switch (node.type) {
+        case 'button':
+            if (!matches(node.onPress))
+                return node;
+            dropped(path, 'button', 'text');
+            return { type: 'text', value: clip(node.label, TEXT_MAX), muted: true };
+        case 'alert':
+            if (!node.action || !matches(node.action.onPress))
+                return node;
+            dropped(`${path}.action`, 'button');
+            return omit(node, 'action');
+        case 'image':
+            if (!matches(node.onPress))
+                return node;
+            dropped(`${path}.onPress`, 'image');
+            return omit(node, 'onPress');
+        case 'choice_cards': {
+            const chat = (choice) => matches(choice.onPress) || matches(choice.action?.onPress);
+            if (!node.choices.some(chat))
+                return node;
+            const choices = [];
+            node.choices.forEach((choice, index) => {
+                const at = `${path}.choices[${index}]`;
+                if (!chat(choice)) {
+                    choices.push(choice);
+                    return;
+                }
+                // Keep whichever of the card's press and its button the client can run.
+                let next = choice;
+                if (matches(next.onPress))
+                    next = omit(next, 'onPress');
+                if (matches(next.action?.onPress))
+                    next = omit(next, 'action');
+                if (!next.onPress && !next.action) {
+                    dropped(at, 'choice_cards');
+                    return;
+                }
+                dropped(next.onPress ? `${at}.action` : `${at}.onPress`, 'choice_cards');
+                choices.push(next);
+            });
+            if (choices.length > 0)
+                return { ...node, choices };
+            dropped(path, 'choice_cards', 'text');
+            const titles = node.choices.map((choice) => choice.title).join(', ');
+            return { type: 'text', value: clip(titles, TEXT_MAX), muted: true };
+        }
+        case 'board': {
+            let changed = false;
+            const columns = node.columns.map((column, c) => {
+                if (!column.cards.some((card) => matches(card.onPress)))
+                    return column;
+                changed = true;
+                const cards = column.cards.map((card, i) => {
+                    if (!matches(card.onPress))
+                        return card;
+                    dropped(`${path}.columns[${c}].cards[${i}].onPress`, 'board');
+                    return omit(card, 'onPress');
+                });
+                return { ...column, cards };
+            });
+            return changed ? { ...node, columns } : node;
+        }
+        case 'calendar': {
+            let changed = false;
+            const events = node.events.map((event, i) => {
+                const at = `${path}.events[${i}]`;
+                const actions = keepButtons(event.actions, `${at}.actions`);
+                const press = matches(event.onPress);
+                if (actions === event.actions && !press)
+                    return event;
+                changed = true;
+                if (press)
+                    dropped(`${at}.onPress`, 'calendar');
+                return withPresses(event, actions, press);
+            });
+            return changed ? { ...node, events } : node;
+        }
+        case 'table': {
+            let changed = false;
+            const rows = node.rows.map((row, i) => {
+                const at = `${path}.rows[${i}]`;
+                const actions = keepButtons(row.actions, `${at}.actions`);
+                const press = matches(row.onPress);
+                if (actions === row.actions && !press)
+                    return row;
+                changed = true;
+                if (press)
+                    dropped(`${at}.onPress`, 'table');
+                return withPresses(row, actions, press);
+            });
+            return changed ? { ...node, rows } : node;
+        }
+        default:
+            return node;
+    }
+}
+/**
+ * The node as a client that cannot move a recording should get it (`press.seek` above): no seek
+ * press, and each moment's or transcript turn's time written in front of its words. Returns the
+ * same object when there is nothing to change.
+ */
+function withoutSeeks(node, path, fallbacks) {
+    const next = withoutPresses(node, path, fallbacks, isSeekPress, 'press.seek');
+    const folded = (at, type) => fallbacks.push({ path: at, type, reason: 'press.seek', as: 'folded' });
+    const timed = (seconds, words, max) => clip(words ? `${formatPlayhead(seconds)} · ${words}` : formatPlayhead(seconds), max);
+    if (next.type === 'timeline') {
+        if (!next.items.some((item) => item.seek))
+            return next;
+        const items = next.items.map((item, i) => {
+            if (!item.seek)
+                return item;
+            folded(`${path}.items[${i}]`, 'timeline');
+            const { seek, ...rest } = item;
+            return { ...rest, label: timed(seek.at, item.label, 200) };
+        });
+        return { ...next, items };
+    }
+    if (next.type === 'conversation') {
+        if (!next.messages.some((message) => message.seek))
+            return next;
+        const messages = next.messages.map((message, i) => {
+            if (!message.seek)
+                return message;
+            folded(`${path}.messages[${i}]`, 'conversation');
+            const { seek, ...rest } = message;
+            return { ...rest, text: timed(seek.at, message.text, 5000) };
+        });
+        return { ...next, messages };
+    }
+    return next;
+}
+/** A copy of `value` without `key`. */
+function omit(value, key) {
+    const copy = { ...value };
+    delete copy[key];
+    return copy;
+}
+/** A row or entry with its kept buttons (none: no `actions`) and without its press when `drop`. */
+function withPresses(item, actions, drop) {
+    const next = { ...item, actions };
+    if (!actions || actions.length === 0)
+        delete next.actions;
+    if (drop)
+        delete next.onPress;
+    return next;
+}
+/** The form field kinds every client's parse knows (ui-sdk 1.1.0 onwards). */
+const OLDER_FIELD_KINDS = new Set(['text', 'textarea', 'select']);
+/** True when any option of the field carries a badge or a description. */
+function hasOptionExtras(field) {
+    return (field.options ?? []).some((o) => o.badge !== undefined || o.description !== undefined);
+}
+/**
+ * A radio, or a multiselect with option extras, for a client that draws neither (`form.radio`).
+ * A radio becomes a `select` with the same options and starting value, so it posts the same
+ * string. Each badge moves into its option's label, so "Recommended" still reaches the reader;
+ * each description is dropped, as a select has no line for it.
+ */
+export function foldChoiceField(field) {
+    const options = field.options?.map(({ badge, description: _description, ...option }) => badge ? { ...option, label: `${option.label} (${badge})` } : option);
+    return {
+        ...field,
+        ...(field.kind === 'radio' ? { kind: 'select' } : {}),
+        ...(options ? { options } : {}),
+    };
+}
+/**
+ * A form field of a kind the client's parse does not know, as the nearest kind it does. It keeps
+ * the label, the name and the starting value; what it posts becomes a string (the older kinds post
+ * strings), so a module that types its input must accept that from an older client.
+ *   number, date, datetime -> text (the value is already a string)
+ *   combobox, radio        -> select (the same options; typed text is not offered)
+ *   checkbox               -> select with "Yes" and "No"
+ *   multiselect            -> select, starting at the first chosen value
+ *   list                   -> textarea, one item per line
+ */
+export function foldFormField(field) {
+    const { values, checked, min: _min, max: _max, step: _step, ...rest } = field;
+    switch (field.kind) {
+        case 'number':
+        case 'date':
+        case 'datetime':
+            return { ...rest, kind: 'text' };
+        case 'combobox':
+            return { ...rest, kind: 'select' };
+        case 'radio':
+            return foldChoiceField({ ...rest, kind: 'radio' });
+        case 'checkbox':
+            return {
+                ...rest,
+                kind: 'select',
+                value: checked ? 'true' : 'false',
+                options: [
+                    { value: 'true', label: 'Yes' },
+                    { value: 'false', label: 'No' },
+                ],
+            };
+        case 'multiselect':
+            return {
+                ...rest,
+                kind: 'select',
+                ...(values?.[0] !== undefined ? { value: values[0] } : {}),
+            };
+        case 'list':
+            return {
+                ...rest,
+                kind: 'textarea',
+                ...(values && values.length > 0 ? { value: clip(values.join('\n'), 20000) } : {}),
+            };
+        default:
+            return field;
+    }
+}
+/**
+ * What a node becomes on a client that cannot draw it. It keeps what the node
+ * SAYS; it cannot keep what the node DOES, so a pager, a select or an alert's
+ * button is not pressable in the fallback. Times are written in `timeZone` (the
+ * screen's; a calendar's own wins), or in UTC when there is none.
+ */
+export function fallbackNode(node, timeZone) {
+    const n = node;
+    switch (n.type) {
+        case 'pagination':
+            return text(`Page ${n.page} of ${n.pageCount} · ${pageRangeLabel(n.page, n.pageSize, n.total)}`, true);
+        case 'select': {
+            if (n.multiple) {
+                const on = n.options.filter((option) => n.values?.includes(option.value));
+                return text(`${n.label}: ${on.length ? on.map((o) => o.label).join(', ') : 'any'}`, true);
+            }
+            const chosen = n.options.find((option) => option.value === n.value);
+            return text(`${n.label}: ${chosen ? chosen.label : 'not set'}`, true);
+        }
+        case 'alert': {
+            const tone = TONE_WORD[n.tone] ?? 'Note';
+            const head = n.title ? `**${tone}:** **${escapeMarkdown(n.title)}**` : `**${tone}:**`;
+            return markdown(`${head}\n\n${escapeMarkdown(n.text)}`);
+        }
+        case 'details': {
+            const lines = n.items.map((item) => `- **${escapeMarkdown(item.label)}:** ${escapeMarkdown(cellText(item.value, timeZone))}`);
+            const title = n.title ? `**${escapeMarkdown(n.title)}**\n\n` : '';
+            return markdown(`${title}${lines.join('\n')}`);
+        }
+        case 'timestamp': {
+            const when = formatMoment(n.value, n.style === 'date' ? 'date' : 'datetime', timeZone);
+            return text(n.label ? `${n.label} ${when}` : when, false);
+        }
+        case 'button':
+            return text(n.label, true);
+        case 'divider':
+            return markdown('---');
+        case 'link': {
+            const target = n.href ?? (typeof n.copy === 'string' ? n.copy : '');
+            return text(target ? `${n.label}: ${target}` : n.label, false);
+        }
+        case 'tags': {
+            const items = n.items.map((item) => item.label).join(', ');
+            return text(n.label ? `${n.label}: ${items}` : items, false);
+        }
+        case 'toggle':
+            return text(`${n.label}: ${n.value ? 'on' : 'off'}`, true);
+        case 'segmented': {
+            const chosen = n.options.find((option) => option.value === n.value);
+            return text(`${n.label}: ${chosen ? chosen.label : 'not set'}`, true);
+        }
+        case 'progress_bar':
+            return text(`${n.label}: ${n.valueLabel ?? `${n.value} of ${n.max}`}`, false);
+        case 'heatmap':
+            return heatmapFallback(n);
+        case 'stacked_bar':
+            return text(stackedBarParts(n).summary, false);
+        case 'board': {
+            const columns = n.columns.map((column) => {
+                const cards = column.cards.map((card) => `- ${escapeMarkdown(card.title)}`);
+                return `**${escapeMarkdown(column.label)}** (${column.cards.length})${cards.length ? `\n\n${cards.join('\n')}` : ''}`;
+            });
+            return markdown(columns.join('\n\n'));
+        }
+        case 'conversation': {
+            if (n.messages.length === 0)
+                return text(n.empty, true);
+            const lines = n.messages.map((message) => {
+                const who = message.author ?? (message.side === 'us' ? 'Us' : 'Them');
+                const when = message.at ? ` (${formatMoment(message.at, 'datetime', timeZone)})` : '';
+                return `**${escapeMarkdown(who)}**${when}: ${escapeMarkdown(message.text)}`;
+            });
+            return markdown(lines.join('\n\n'));
+        }
+        case 'composer':
+            return text(`${n.label}: open this in the web app to write here.`, true);
+        case 'calendar': {
+            if (n.events.length === 0)
+                return text(n.empty, true);
+            const zone = n.timeZone ?? timeZone;
+            const lines = n.events.map((event) => `- ${escapeMarkdown(event.title)}: ${formatMoment(event.start, 'datetime', zone)} to ${formatMoment(event.end, 'datetime', zone)}`);
+            return markdown(lines.join('\n'));
+        }
+        case 'image':
+            return text(n.alt ?? n.caption ?? 'An image', true);
+        case 'video':
+            return text(`Video: ${n.title}`, true);
+        case 'audio':
+            return text(`Audio: ${n.title}${n.duration ? `, ${formatPlayhead(n.duration)}` : ''}`, true);
+        case 'dataset':
+            return text('This list could not be shown here.', true);
+        default:
+            return text(GENERIC_FALLBACK_TEXT, true);
+    }
+}
+/** Columns a table holds in every published schema. */
+const TABLE_COLUMNS_MAX = 12;
+/**
+ * A heatmap without its shading: the same numbers as a plain table every client draws, the row
+ * labels in the first column. A cell with no data reads "-". A grid too wide for a table (more
+ * than 11 columns) becomes one markdown line per row.
+ */
+function heatmapFallback(n) {
+    const write = (value) => value === null ? '-' : clip(`${value}${n.valueSuffix ?? ''}`, 500);
+    if (n.columns.length < TABLE_COLUMNS_MAX) {
+        return {
+            type: 'table',
+            columns: [
+                { key: 'row', label: clip(n.title ?? n.rowHeader ?? '', 80) },
+                ...n.columns.map((label, i) => ({ key: `c${i}`, label: clip(label, 80) })),
+            ],
+            rows: n.rows.map((row, r) => ({
+                key: `r${r}`,
+                cells: Object.fromEntries([
+                    ['row', { kind: 'text', value: clip(row.label, 500) }],
+                    ...row.values.map((value, i) => [
+                        `c${i}`,
+                        { kind: 'text', value: write(value) },
+                    ]),
+                ]),
+            })),
+            empty: 'No data yet.',
+        };
+    }
+    const lines = n.rows.map((row) => {
+        const cells = row.values.map((value, i) => `${escapeMarkdown(n.columns[i] ?? '')} ${escapeMarkdown(write(value))}`);
+        return `- **${escapeMarkdown(row.label)}:** ${cells.join(', ')}`;
+    });
+    const title = n.title ? `**${escapeMarkdown(n.title)}**\n\n` : '';
+    return markdown(`${title}${lines.join('\n')}`);
+}
+const TONE_WORD = {
+    info: 'Note',
+    success: 'Success',
+    warning: 'Warning',
+    destructive: 'Error',
+};
+function cellText(cell, timeZone) {
+    return cell.kind === 'date' ? formatMoment(cell.value, 'datetime', timeZone) : cell.value;
+}
+/**
+ * The tree's `badges` and `meta` as one line, for a client that draws neither: the badge labels,
+ * then each fact as "label: value", joined with " · ". Dates are written in the screen's zone.
+ */
+function headerFactsLine(tree, timeZone) {
+    const parts = [
+        ...(tree.badges ?? []).map((badge) => badge.label),
+        ...(tree.meta ?? []).map((item) => `${item.label}: ${cellText(item.value, timeZone)}`),
+    ];
+    return clip(parts.join(' · '), TEXT_MAX);
+}
+/** A calendar day with no time ("2026-10-09"): the same day in every zone. */
+const DAY_ONLY = /^\d{4}-\d{2}-\d{2}$/;
+/**
+ * ISO 8601 → "2026-10-09 16:03 CEST" in the screen's zone, the way a person there reads it (or the
+ * date alone). Without a zone, or with one this runtime cannot format in: "2026-10-09 14:03 UTC".
+ */
+function formatMoment(iso, style, timeZone) {
+    if (style === 'date' && DAY_ONLY.test(iso))
+        return iso;
+    const date = new Date(iso);
+    if (Number.isNaN(date.getTime()))
+        return iso;
+    if (timeZone) {
+        try {
+            const parts = new Intl.DateTimeFormat('en-GB', {
+                timeZone,
+                year: 'numeric',
+                month: '2-digit',
+                day: '2-digit',
+                hour: '2-digit',
+                minute: '2-digit',
+                hourCycle: 'h23',
+                timeZoneName: 'short',
+            }).formatToParts(date);
+            const part = (type) => parts.find((p) => p.type === type)?.value ?? '';
+            const day = `${part('year')}-${part('month')}-${part('day')}`;
+            return style === 'date'
+                ? day
+                : `${day} ${part('hour')}:${part('minute')} ${part('timeZoneName')}`;
+        }
+        catch {
+            // A zone this runtime does not know: UTC, said as such, below.
+        }
+    }
+    const day = date.toISOString().slice(0, 10);
+    return style === 'date' ? day : `${day} ${date.toISOString().slice(11, 16)} UTC`;
+}
+function text(value, muted) {
+    return { type: 'text', value: clip(value, TEXT_MAX), muted };
+}
+function markdown(value) {
+    return { type: 'markdown', value: clip(value, MARKDOWN_MAX) };
+}
+function clip(value, max) {
+    return value.length <= max ? value : `${value.slice(0, max - 1)}…`;
+}
+/** Module text is plain text: escape it so it reads the same inside a markdown fallback. */
+export function escapeMarkdown(value) {
+    return value.replace(/[\\`*_{}[\]()#+\-.!|<>~]/g, (ch) => `\\${ch}`);
+}
+/** x.y.z with an optional leading `v`; build and pre-release suffixes are ignored. */
+function parseVersion(version) {
+    const m = /^v?(\d+)(?:\.(\d+))?(?:\.(\d+))?/.exec(version.trim());
+    if (!m)
+        return null;
+    return [Number(m[1]), Number(m[2] ?? 0), Number(m[3] ?? 0)];
+}
+function compareVersions(a, b) {
+    const pa = parseVersion(a) ?? [0, 0, 0];
+    const pb = parseVersion(b) ?? [0, 0, 0];
+    for (let i = 0; i < 3; i += 1) {
+        if (pa[i] !== pb[i])
+            return pa[i] < pb[i] ? -1 : 1;
+    }
+    return 0;
+}