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

package/dist/markdown-links.js

@@ -0,0 +1,99 @@
+// UI-20 (Covalent): a word inside markdown that opens a screen of the same module. The morning
+// brief says "[Northside Surgical](screen:northside) is at risk", and the account name opens
+// that account's screen.
+//
+// The markdown names a REF only. What the ref opens is the node's own `links` map, a normal
+// navigate press the module wrote beside the text and the schema checked like any other press:
+//
+//   { type: 'markdown',
+//     value: '[Northside Surgical](screen:northside) is at risk.',
+//     links: { northside: { kind: 'navigate', screen: 'account', params: { id: 'acc_9' } } } }
+//
+// So the markdown itself can never carry a screen name, params or a URL that opens anything. A
+// `screen:` link whose ref is not in the map is drawn as its words, plain text. Every other link
+// (https, mailto) is drawn exactly as before.
+/** The scheme a link to a screen is written with: `[words](screen:ref)`. */
+export const SCREEN_LINK_SCHEME = 'screen:';
+/** The most refs one markdown node's `links` map holds. */
+export const MARKDOWN_LINKS_MAX = 50;
+/** A ref: the same lowercase slug as an action or a screen key. */
+const REF = /^[a-z][a-z0-9_-]{0,63}$/;
+/**
+ * True for any link written with the `screen:` scheme, in any case and with any spaces around
+ * it. A renderer never hands such a link to the browser or the phone as a URL: it is either a
+ * ref in the node's map (a press) or plain text.
+ */
+export function isScreenLink(href) {
+    return typeof href === 'string' && href.trim().toLowerCase().startsWith(SCREEN_LINK_SCHEME);
+}
+/** The ref a `screen:` link names, or null when it is not exactly `screen:<slug>`. */
+export function screenLinkRef(href) {
+    if (typeof href !== 'string' || !href.startsWith(SCREEN_LINK_SCHEME))
+        return null;
+    const ref = href.slice(SCREEN_LINK_SCHEME.length);
+    return REF.test(ref) ? ref : null;
+}
+/**
+ * The press a `screen:` link opens: the entry of `links` its ref names, or null. Only the map's
+ * own entries count (never `constructor` or anything else an object inherits), and only an entry
+ * that is a navigate press, so a renderer that is handed a loosely typed map still opens nothing
+ * else. Null means: draw the link's words as plain text.
+ */
+export function resolveScreenLink(href, links) {
+    const ref = screenLinkRef(href);
+    if (!ref || !links || typeof links !== 'object')
+        return null;
+    if (!Object.prototype.hasOwnProperty.call(links, ref))
+        return null;
+    const press = links[ref];
+    return press && typeof press === 'object' && press.kind === 'navigate' ? press : null;
+}
+// ── the fold for a client that does not draw them ────────────────────────────
+/** Fenced code and inline code: left as written, a `screen:` inside code is code. */
+const CODE = /(```[\s\S]*?(?:```|$)|~~~[\s\S]*?(?:~~~|$)|`[^`\n]*`)/;
+/** The scheme, case-insensitive, as a regex source. */
+const SCHEME = '[sS][cC][rR][eE][eE][nN]:';
+/** `[words](screen:ref)`, `[words](<screen:ref>)`, with or without a title. */
+const INLINE = new RegExp(String.raw `\[((?:\\.|[^\[\]\\\n])*)\]\(\s*(?:<\s*${SCHEME}[^>\n]*>|${SCHEME}[^\s)]*)(?:\s+(?:"[^"\n]*"|'[^'\n]*'|\([^)\n]*\)))?\s*\)`, 'g');
+/** `<screen:ref>`: an autolink, drawn as its ref. */
+const AUTOLINK = new RegExp(String.raw `<${SCHEME}([^\s<>]*)>`, 'g');
+/** `[label]: screen:ref`, a reference definition, on a line of its own. */
+const DEFINITION = new RegExp(String.raw `^ {0,3}\[((?:\\.|[^\[\]\\\n])+)\]:[ \t]*(?:<${SCHEME}[^>\n]*>|${SCHEME}\S*)(?:[ \t]+(?:"[^"\n]*"|'[^'\n]*'|\([^)\n]*\)))?[ \t]*(?:\n|$)`, 'gm');
+/** How CommonMark matches a reference label: case-folded, inner spaces collapsed. */
+const labelKey = (label) => label.trim().replace(/\s+/g, ' ').toLowerCase();
+/**
+ * The markdown with every `screen:` link turned into its words, for a client that does not draw
+ * them (negotiate.ts, `markdown.links`). An older renderer would draw such a link as a broken link
+ * or as the raw `[words](screen:ref)`; this way it reads as the sentence the module wrote. Inline
+ * links, autolinks and reference definitions (with the links that use them) are folded; code is
+ * left as written. Pure; returns the same string when there is nothing to fold.
+ */
+export function withoutScreenLinks(value) {
+    if (!/screen:/i.test(value))
+        return value;
+    const parts = value.split(CODE);
+    // Reference labels whose definition points at a screen, from the prose parts only.
+    const labels = new Set();
+    for (let i = 0; i < parts.length; i += 2) {
+        for (const m of parts[i].matchAll(DEFINITION))
+            labels.add(labelKey(m[1]));
+    }
+    const folded = parts.map((part, i) => {
+        if (i % 2 === 1)
+            return part;
+        let next = part
+            .replace(DEFINITION, '')
+            .replace(INLINE, (_all, words) => words)
+            .replace(AUTOLINK, (_all, ref) => ref);
+        if (labels.size > 0) {
+            // [words][label], [label][] and [label], for a label defined as a screen link above.
+            next = next.replace(/\[((?:\\.|[^\[\]\\\n])*)\](?:\[((?:\\.|[^\[\]\\\n])*)\])?(?!\(|:)/g, (all, words, label) => {
+                const key = labelKey(label === undefined || label === '' ? words : label);
+                return labels.has(key) ? words : all;
+            });
+        }
+        return next;
+    });
+    const out = folded.join('');
+    return out === value ? value : out;
+}

package/dist/media.js

@@ -1,4 +1,4 @@
-// Module-side helpers for the `image` and `video` blocks. A module serves its
+// Module-side helpers for the `image`, `video` and `audio` blocks. A module serves its
 // media at GET /screens/media/<path> in its screens channel, after verifying the
 // capability grant exactly as its load and action routes do. Core fetches from
 // there and passes on only these types, so a module that labels a file with
@@ -14,6 +14,12 @@ export const MEDIA_CONTENT_TYPES = {
     avif: 'image/avif',
     mp4: 'video/mp4',
     webm: 'video/webm',
+    mp3: 'audio/mpeg',
+    m4a: 'audio/mp4',
+    ogg: 'audio/ogg',
+    oga: 'audio/ogg',
+    wav: 'audio/wav',
+    weba: 'audio/webm',
     vtt: 'text/vtt',
 };
 /** The Content-Type to serve a media path with, or null when core would refuse it. */

package/dist/negotiate.d.ts

@@ -0,0 +1,302 @@
+import type { ChatPress, ScreenRootNode, ScreenTree } from './schema.js';
+/**
+ * Tree features below the node level that a client may or may not draw.
+ *
+ *   - `breadcrumbs`: drawn as a trail. Without it, one muted line.
+ *   - `button.disabled`: a disabled button is drawn disabled and refuses the press. Without it, a
+ *     disabled button becomes muted text and a disabled header action is dropped.
+ *   - `section.row`: NEWER ENUM VALUE `layout: 'row'`. Without it, `stack`.
+ *   - `form.field_kinds`: the field kinds added after 1.2.0 (`number`, `date`, `datetime`,
+ *     `checkbox`, `multiselect`, `combobox`, `list`). Without it, `text`, `select` or `textarea`.
+ *   - `form.confirm`: the client asks `submit.confirm` (and a `secondary` send's `confirm`) before
+ *     the form posts. Without it, a form that carries one becomes one calm line, so nothing posts
+ *     without asking.
+ *   - `press.chat`: a `chat` press opens the client's chat with the prompt typed in, never sent.
+ *     Without it, nothing offers to open the chat: a body button with one becomes its label as
+ *     muted text, a header, row, calendar entry or alert button with one is dropped, and a row,
+ *     card, entry or image keeps its place but is no longer pressable. A choice with one is
+ *     dropped, and choices with nothing left become one line of their titles.
+ *   - `form.radio`: the `radio` field kind and an option's `badge` and `description` (newer than
+ *     any published release; core's own renderer draws them). Without it, a radio is a `select`
+ *     with the same options and value, so the reader can still answer; a badge goes into its
+ *     option's label ("Acme (Recommended)"); a description is dropped.
+ *   - `table.cells`: the `sparkline` and `meter` table cells and a `text` or `badge` cell's
+ *     `secondary` line (newer than any published release; core's own renderer draws them).
+ *     Without it, a sparkline is a text cell with its label, a meter one with its value label,
+ *     and the second line is dropped (cells.ts `foldTableCell`).
+ *   - `header.meta`: the tree's `badges` beside the title and `meta` facts under it (newer than
+ *     any published release; core's own renderer draws them). An older parse strips both without
+ *     a sign, so without it they become one muted line first in the body ("At risk · Tier 1 ·
+ *     ARR: $1.2M · Renewal: 15 Mar 2027"), where the breadcrumbs fold puts its own line above.
+ *   - `tabs.many`: a strip of up to 10 tabs (newer than any published release, which takes 6).
+ *     Without it, the first five stay tabs and a sixth, "More", holds the rest as titled sections
+ *     in order (tabs.ts `foldTabs`). A strip's `param` needs no feature: a parse that predates it
+ *     strips it, and the strip keeps its open tab as local state, as it always did.
+ *   - `choice.action`: a choice card's own button (`action`), and a card with no `onPress` (newer
+ *     than any published release; core's own renderer draws them). Without it, a card that has
+ *     its own `onPress` keeps it and loses the button; a card with only the button becomes a card
+ *     whose press is the button's, so every card can still be acted on. The card's `tone` and
+ *     `badge`, a timeline item's `icon`, `tone` and `actor`, and a badge's `dot` are new optional
+ *     keys: an older parse strips them and draws the rest, so they need no fold.
+ *   - `markdown.links`: a markdown node's `links` map, and the `[words](screen:ref)` links in its
+ *     text that open a screen through it (newer than any published release; core's own renderer
+ *     draws them). Without it, each `screen:` link becomes its words as plain text and the map is
+ *     dropped (markdown-links.ts `withoutScreenLinks`), so an older renderer draws the sentence
+ *     the module wrote, never a broken link or the raw `[words](screen:ref)`. https links stay.
+ *   - `form.disabled`: a form send (`submit` or a `secondary`) that is `disabled`, with its
+ *     `disabledReason` (newer than any published release; core's own renderer draws them). An
+ *     older parse strips `disabled` and would post the send, so without it a disabled `secondary`
+ *     is dropped, and a form whose `submit` is disabled becomes one calm line (`submit` is
+ *     required, and promoting a `secondary` would change what Enter posts). A reason on an
+ *     enabled send means nothing and is left for the parse to strip.
+ *   - `press.seek`: a `seek` press moves an `audio` or `video` playhead on the same screen, and a
+ *     timeline item's or conversation turn's `seek` draws its time as a button that does the same
+ *     (newer than any published release; core's own renderer draws them). Without it, each seek
+ *     press goes exactly as a chat press does without `press.chat` (a body button becomes its
+ *     label as muted text, a header, row, entry or alert button is dropped, a row, card, entry or
+ *     image stays but is no longer pressable), and a moment's or turn's time is written in front
+ *     of its words ("4:10 · Allergies discussed"), so the reader still learns where it is. A
+ *     video's `key` is a new optional key an older parse strips; nothing on such a client names it.
+ *   - `edit.inline`: an `edit` on a `text`, `markdown` or `details` block (and on its items), or on
+ *     a `table` column, drawn as a pencil that turns the block into a field in place (newer than
+ *     any published release; core's own renderer draws it). An older parse strips it, so the block
+ *     would draw read-only anyway; core drops it on purpose all the same (`withoutInlineEdit`), so
+ *     a client never gets half an edit (a column's options without its action, say) and the
+ *     fallback list says the block was made read-only. The data is all still there.
+ */
+export type UiFeature = 'breadcrumbs' | 'button.disabled' | 'section.row' | 'form.field_kinds' | 'form.confirm' | 'press.chat' | 'form.radio' | 'table.cells' | 'header.meta' | 'tabs.many' | 'choice.action' | 'markdown.links' | 'form.disabled' | 'press.seek' | 'edit.inline';
+/** The node types and features one ui-sdk release, or one client, draws. */
+export interface NodeSet {
+    /** For messages: "ui-sdk 1.4.0", "mobile 0.2.5". */
+    name: string;
+    nodes: readonly string[];
+    features: readonly UiFeature[];
+    /**
+     * The published schema the client parses with. Its tree is fitted to it (conform.ts). Absent, or
+     * `current`, means this package's own schema: nothing to fit.
+     */
+    parses?: UiSdkSnapshot;
+}
+/**
+ * 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 declare const CORE_DRAWN_NODE_TYPES: readonly ["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 declare const UI_SDK_SNAPSHOTS: {
+    readonly '1.1.0': {
+        readonly name: "ui-sdk 1.1.0";
+        readonly nodes: readonly ["heading", "text", "markdown", "stat", "button", "form", "table", "timeline", "pending_request", "pending_requests", "choice_cards", "progress", "chart", "section", "tabs"];
+        readonly features: readonly [];
+    };
+    readonly '1.4.0': {
+        readonly name: "ui-sdk 1.4.0";
+        readonly nodes: readonly ["heading", "text", "markdown", "stat", "button", "form", "table", "timeline", "pending_request", "pending_requests", "choice_cards", "progress", "chart", "section", "tabs", "pagination", "select", "alert", "details", "timestamp", "divider", "board", "link", "tags", "toggle", "segmented", "progress_bar", "conversation", "composer", "calendar", "image", "video"];
+        readonly features: readonly ["breadcrumbs", "button.disabled", "section.row", "form.field_kinds", "form.confirm"];
+    };
+    readonly current: {
+        readonly name: "ui-sdk (this package)";
+        readonly nodes: readonly ["heading", "text", "markdown", "stat", "button", "form", "table", "timeline", "pending_request", "pending_requests", "choice_cards", "progress", "chart", "section", "tabs", "pagination", "select", "alert", "details", "timestamp", "divider", "board", "link", "tags", "toggle", "segmented", "progress_bar", "conversation", "composer", "calendar", "image", "video", "stacked_bar", "heatmap", "audio"];
+        readonly features: readonly ["breadcrumbs", "button.disabled", "section.row", "form.field_kinds", "form.confirm", "press.chat", "form.radio", "table.cells", "header.meta", "tabs.many", "choice.action", "markdown.links", "form.disabled", "press.seek", "edit.inline"];
+    };
+};
+export type UiSdkSnapshot = keyof typeof UI_SDK_SNAPSHOTS;
+/** The snapshot this package is. Core's own renderer draws all of it. */
+export declare const CURRENT_UI_SDK_SNAPSHOT: UiSdkSnapshot;
+/** The clients that send `X-Kee-Client`. Same names as core's ClientPlatform. */
+export type ClientTarget = 'web' | 'mobile' | 'desktop' | 'extension' | 'cli';
+export interface ClientRelease {
+    client: ClientTarget;
+    /** The first client version (x.y.z) this row applies to. */
+    since: string;
+    /** The schema this release parses with: the ui-sdk inside the sdk it was built with. */
+    parses: UiSdkSnapshot;
+    /** What its renderer draws: always within `parses`. */
+    draws: Omit<NodeSet, 'name' | 'parses'>;
+    /** Why the row says what it says. */
+    note: string;
+}
+/**
+ * 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 declare const CLIENT_RELEASES: readonly ClientRelease[];
+/** The floor: what every client that sends `X-Kee-Client` can take. */
+export declare const FLOOR_NODE_SET: NodeSet;
+/** The rows of one client, oldest first. */
+export declare function releasesOf(client: string, releases?: readonly ClientRelease[]): ClientRelease[];
+/**
+ * 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 declare function nodeSetForClient(platform: string, version: string, releases?: readonly ClientRelease[]): NodeSet;
+/**
+ * What a client build says about the schema it parses, in the build metadata of its
+ * `X-Kee-Client` version: `web/0.2.0+abc1234.ui-current`. Only a build that installed the @dev
+ * sdk channel says it, because only that install parses the current schema (the web row note
+ * above). A build from the committed lockfile says nothing, so its header is unchanged.
+ */
+export type UiSchemaClaim = 'current';
+/** The build metadata identifier a build that parses the current schema adds to its version. */
+export declare 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 declare function uiSchemaClaimOf(header: string | null | undefined): UiSchemaClaim | null;
+/** What a channel build of a client parses and draws, when it claims the current schema. */
+export interface ChannelBuild {
+    client: ClientTarget;
+    parses: UiSdkSnapshot;
+    draws: Omit<NodeSet, 'name' | 'parses'>;
+    note: string;
+}
+/**
+ * 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 declare const CHANNEL_BUILDS: readonly ChannelBuild[];
+/**
+ * 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 declare function nodeSetForClaim(platform: string, version: string, claim: UiSchemaClaim | null, builds?: readonly ChannelBuild[]): NodeSet;
+/** The newest release row of a client: what a module targets when it names only the client. */
+export declare function latestRelease(client: ClientTarget): ClientRelease;
+/** One node core replaced, or one header action it dropped. */
+export interface Fallback {
+    /** Where it was, as a property path: `children[2].children[0]`, `actions[1]`, `breadcrumbs`. */
+    path: string;
+    /** The node type (or `breadcrumbs`, or `header` for badges and meta) the client cannot draw. */
+    type: string;
+    /**
+     * Why: the node type is not drawn, a feature of it is not, the client's published schema
+     * refuses something in it (`parse`), or that schema would strip a `confirm` or a `disabled`
+     * flag from a control it keeps (`safety`).
+     */
+    reason: 'node' | UiFeature | 'parse' | 'safety';
+    /**
+     * What took its place. A header action can only be dropped: the header holds buttons only. A
+     * newer enum value is `folded`: the node stays, with the nearest value the client knows. A
+     * heatmap becomes a `table` of the same numbers.
+     */
+    as: 'text' | 'markdown' | 'table' | 'dropped' | 'folded';
+}
+export interface NegotiatedTree {
+    tree: ScreenTree;
+    fallbacks: Fallback[];
+}
+/** The fallback for a node type that has no specific one: a sign that something is there. */
+export declare 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 declare 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 declare function negotiateTree(tree: ScreenTree, set: NodeSet): NegotiatedTree;
+/** True for a press that opens the chat with a prompt typed in. */
+export declare function isChatPress(press: {
+    kind: string;
+} | undefined): press is ChatPress;
+type ChoiceCardsNode = Extract<ScreenRootNode, {
+    type: 'choice_cards';
+}>;
+/**
+ * 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 declare function foldDisabledSends(node: FormNode, path: string, fallbacks: Fallback[]): FormNode | {
+    type: 'text';
+    value: string;
+    muted: true;
+};
+/**
+ * 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 declare function foldChoiceActions(node: ChoiceCardsNode, path: string, fallbacks: Fallback[]): ChoiceCardsNode;
+/**
+ * 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 declare function withoutInlineEdit(node: ScreenRootNode, path: string, fallbacks: Fallback[]): ScreenRootNode;
+type FormNode = Extract<ScreenRootNode, {
+    type: 'form';
+}>;
+type FormField = FormNode['fields'][number];
+/**
+ * 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 declare function foldChoiceField(field: FormField): FormField;
+/**
+ * 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 declare function foldFormField(field: FormField): FormField;
+type FallbackNode = {
+    type: 'text';
+    value: string;
+    muted: boolean;
+} | {
+    type: 'markdown';
+    value: string;
+} | {
+    type: 'table';
+    columns: Array<{
+        key: string;
+        label: string;
+    }>;
+    rows: Array<{
+        key: string;
+        cells: Record<string, {
+            kind: 'text';
+            value: string;
+        }>;
+    }>;
+    empty: string;
+};
+/**
+ * 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 declare function fallbackNode(node: ScreenRootNode | {
+    type: string;
+}, timeZone?: string): FallbackNode;
+/** Module text is plain text: escape it so it reads the same inside a markdown fallback. */
+export declare function escapeMarkdown(value: string): string;
+export {};