@adecore/intelligent-ui 0.24.1 → 0.25.0

package/dist/catalog.d.ts

@@ -23,7 +23,11 @@ export declare const UI_GROUPS: {
     };
     readonly content: {
         readonly description: 'Include code, attachments and sources.';
-        readonly rules: 'Image accepts a chat attachment or generated="latest", never a URL or a local path.';
+        readonly rules: 'Image accepts a chat attachment or generated="latest", never a URL or a local path. Gallery and Compare take chat attachments too. The host says how to attach a file of your own.';
+    };
+    readonly places: {
+        readonly description: 'Show places on a map the host draws.';
+        readonly rules: 'Give lat and lon in decimal degrees, or an address the host looks up. Never a tile or map URL. The host chooses the map.';
     };
     readonly links: {
         readonly description: 'Refer to a host-owned resource.';
@@ -109,6 +113,31 @@ export declare const UI_CATALOG: {
         }, z.core.$strict>;
         readonly parent: 'Steps';
     };
+    readonly Timeline: {
+        readonly group: 'status';
+        readonly description: 'Events in time order.';
+        readonly schema: z.ZodObject<{}, z.core.$strict>;
+        readonly children: readonly ['Event'];
+        readonly count: {
+            readonly min: 1;
+        };
+    };
+    readonly Event: {
+        readonly group: 'status';
+        readonly description: 'One event at a time or date; children are the title.';
+        readonly schema: z.ZodObject<{
+            at: z.ZodString;
+            tone: z.ZodOptional<z.ZodEnum<{
+                danger: "danger";
+                info: "info";
+                neutral: "neutral";
+                success: "success";
+                warning: "warning";
+            }>>;
+            detail: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>;
+        readonly parent: 'Timeline';
+    };
     readonly Stats: {
         readonly group: 'data';
         readonly description: 'A small set of key numbers.';
@@ -232,6 +261,51 @@ export declare const UI_CATALOG: {
             alt: z.ZodOptional<z.ZodString>;
         }, z.core.$strict>;
     };
+    readonly Gallery: {
+        readonly group: 'content';
+        readonly description: 'A grid of images with captions; at most 24.';
+        readonly schema: z.ZodObject<{}, z.core.$strict>;
+        readonly children: readonly ['Image'];
+        readonly count: {
+            readonly min: 1;
+            readonly max: 24;
+        };
+    };
+    readonly Compare: {
+        readonly group: 'content';
+        readonly description: 'Two chat attachments in one frame with a handle to wipe between them; children are the caption.';
+        readonly schema: z.ZodObject<{
+            before: z.ZodString;
+            after: z.ZodString;
+            beforeLabel: z.ZodOptional<z.ZodString>;
+            afterLabel: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>;
+    };
+    readonly Map: {
+        readonly group: 'places';
+        readonly description: 'One to 50 places on a map the host draws, with a numbered list under it; bind value to let a person pick a place.';
+        readonly schema: z.ZodObject<{
+            value: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>;
+        }, z.core.$strict>;
+        readonly children: readonly ['Place'];
+        readonly binding: 'value';
+        readonly count: {
+            readonly min: 1;
+            readonly max: 50;
+        };
+    };
+    readonly Place: {
+        readonly group: 'places';
+        readonly description: 'One place by lat and lon, or by an address the host looks up; with both, the point the host finds for the address wins and lat and lon stand when it finds none. Children are the name.';
+        readonly schema: z.ZodObject<{
+            lat: z.ZodOptional<z.ZodNumber>;
+            lon: z.ZodOptional<z.ZodNumber>;
+            address: z.ZodOptional<z.ZodString>;
+            detail: z.ZodOptional<z.ZodString>;
+            value: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>;
+        }, z.core.$strict>;
+        readonly parent: 'Map';
+    };
     readonly Sources: {
         readonly group: 'content';
         readonly description: 'Numbered sources without preloading.';
@@ -322,13 +396,32 @@ export declare const UI_CATALOG: {
         readonly children: readonly ['Option'];
         readonly binding: 'value';
     };
+    readonly Select: {
+        readonly group: 'inputs';
+        readonly description: 'Choose one local value from a dropdown, for more or longer options than Segmented holds; the text beside its Options is its label.';
+        readonly schema: z.ZodObject<{
+            value: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>;
+        }, z.core.$strict>;
+        readonly children: readonly ['Option'];
+        readonly binding: 'value';
+    };
     readonly Option: {
         readonly group: 'inputs';
         readonly description: 'One local alternative.';
         readonly schema: z.ZodObject<{
             value: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>;
         }, z.core.$strict>;
-        readonly parent: 'Segmented';
+        readonly parent: readonly ['Segmented', 'Select'];
+    };
+    readonly TextField: {
+        readonly group: 'inputs';
+        readonly description: 'A line of local text up to maxLength characters (256 without one, at most 1024); children are the label.';
+        readonly schema: z.ZodObject<{
+            value: z.ZodString;
+            maxLength: z.ZodOptional<z.ZodNumber>;
+            placeholder: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>;
+        readonly binding: 'value';
     };
     readonly Button: {
         readonly group: 'inputs';
@@ -370,6 +463,7 @@ export declare const UI_CATALOG: {
         readonly parent: 'Choices';
     };
 };
+export type UiGroupName = keyof typeof UI_GROUPS;
 export type UiComponentName = keyof typeof UI_CATALOG;
 export type UiProps<Name extends UiComponentName> = z.infer<(typeof UI_CATALOG)[Name]['schema']>;
 export declare function isUiComponent(name: string): name is UiComponentName;

package/dist/catalog.js

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { parseUiEventTime } from './event-time.js';
 import { uiPropList } from './prop-list.js';
 export const UI_CATALOG_VERSION = 1;
 export const UiToneSchema = z.enum(['neutral', 'info', 'success', 'warning', 'danger']);
@@ -15,7 +16,11 @@ export const UI_GROUPS = {
     structure: { description: 'Organize distinct topics.', rules: 'Use Tabs for alternatives and Sections for independent topics.' },
     content: {
         description: 'Include code, attachments and sources.',
-        rules: 'Image accepts a chat attachment or generated="latest", never a URL or a local path.'
+        rules: 'Image accepts a chat attachment or generated="latest", never a URL or a local path. Gallery and Compare take chat attachments too. The host says how to attach a file of your own.'
+    },
+    places: {
+        description: 'Show places on a map the host draws.',
+        rules: 'Give lat and lon in decimal degrees, or an address the host looks up. Never a tile or map URL. The host chooses the map.'
     },
     links: { description: 'Refer to a host-owned resource.', rules: 'Targets are checked by the host. No arbitrary navigation or file reads.' },
     inputs: {
@@ -43,6 +48,17 @@ export const UI_CATALOG = {
         schema: z.strictObject({ state: z.enum(['done', 'running', 'pending', 'failed', 'skipped']), detail: text.optional() }),
         parent: 'Steps'
     },
+    Timeline: { group: 'status', description: 'Events in time order.', schema: empty, children: ['Event'], count: { min: 1 } },
+    Event: {
+        group: 'status',
+        description: 'One event at a time or date; children are the title.',
+        schema: z.strictObject({
+            at: text.refine((value) => parseUiEventTime(value) !== null, 'At must be HH:MM, YYYY-MM-DD or an ISO date-time.'),
+            tone,
+            detail: text.optional()
+        }),
+        parent: 'Timeline'
+    },
     Stats: { group: 'data', description: 'A small set of key numbers.', schema: empty, children: ['Stat'] },
     Stat: {
         group: 'data',
@@ -85,6 +101,34 @@ export const UI_CATALOG = {
             .strictObject({ attachment: name.optional(), generated: z.literal('latest').optional(), alt: text.optional() })
             .refine((props) => Boolean(props.attachment) !== Boolean(props.generated), 'Choose attachment or generated, exclusively.')
     },
+    Gallery: { group: 'content', description: 'A grid of images with captions; at most 24.', schema: empty, children: ['Image'], count: { min: 1, max: 24 } },
+    Compare: {
+        group: 'content',
+        description: 'Two chat attachments in one frame with a handle to wipe between them; children are the caption.',
+        schema: z.strictObject({ before: name, after: name, beforeLabel: text.optional(), afterLabel: text.optional() })
+    },
+    Map: {
+        group: 'places',
+        description: 'One to 50 places on a map the host draws, with a numbered list under it; bind value to let a person pick a place.',
+        schema: z.strictObject({ value: scalar.optional() }),
+        children: ['Place'],
+        binding: 'value',
+        count: { min: 1, max: 50 }
+    },
+    Place: {
+        group: 'places',
+        description: 'One place by lat and lon, or by an address the host looks up; with both, the point the host finds for the address wins and lat and lon stand when it finds none. Children are the name.',
+        schema: z
+            .strictObject({
+            lat: number.min(-90).max(90).optional(),
+            lon: number.min(-180).max(180).optional(),
+            address: text.max(512).optional(),
+            detail: text.optional(),
+            value: scalar.optional()
+        })
+            .refine((props) => (props.lat === undefined) === (props.lon === undefined) && (props.lat !== undefined || props.address !== undefined), 'Give lat with lon, or an address.'),
+        parent: 'Map'
+    },
     Sources: { group: 'content', description: 'Numbered sources without preloading.', schema: empty, children: ['Source'] },
     Source: {
         group: 'content',
@@ -118,7 +162,22 @@ export const UI_CATALOG = {
         binding: 'value'
     },
     Segmented: { group: 'inputs', description: 'Choose one local value.', schema: z.strictObject({ value: scalar }), children: ['Option'], binding: 'value' },
-    Option: { group: 'inputs', description: 'One local alternative.', schema: z.strictObject({ value: scalar }), parent: 'Segmented' },
+    Select: {
+        group: 'inputs',
+        description: 'Choose one local value from a dropdown, for more or longer options than Segmented holds; the text beside its Options is its label.',
+        schema: z.strictObject({ value: scalar }),
+        children: ['Option'],
+        binding: 'value'
+    },
+    Option: { group: 'inputs', description: 'One local alternative.', schema: z.strictObject({ value: scalar }), parent: ['Segmented', 'Select'] },
+    TextField: {
+        group: 'inputs',
+        description: 'A line of local text up to maxLength characters (256 without one, at most 1024); children are the label.',
+        schema: z
+            .strictObject({ value: text, maxLength: z.number().int().min(1).max(1024).optional(), placeholder: text.max(128).optional() })
+            .refine((props) => props.value.length <= (props.maxLength ?? 256), 'Value must not be longer than maxLength.'),
+        binding: 'value'
+    },
     Button: {
         group: 'inputs',
         description: 'Run one local state action when pressed; children are the label.',

package/dist/compiler.d.ts

@@ -12,6 +12,7 @@ export declare const UI_REPLY_LIMITS: {
 export declare const UI_HOST_LIMITS: {
     readonly queries: 8;
     readonly links: 64;
+    readonly places: 50;
     readonly refreshMilliseconds: 10000;
 };
 export declare function uiMayReferenceHost(text: string): boolean;

package/dist/compiler.js

@@ -2,14 +2,16 @@ import { safeKey, UI_LIMITS, UiBudget, UiFailure } from './budget.js';
 import { isUiComponent, UI_CATALOG, UI_CATALOG_VERSION } from './catalog.js';
 import { uiActionProp, uiActionTarget, uiLocalState } from './actions.js';
 import { uiNodeFallback, uiPlainText } from './fallback.js';
-import { evaluateUiExpression } from './expression.js';
+import { evaluateUiExpression, sameUiValue } from './expression.js';
 import { parseUiSyntax, uiDiagnostic } from './syntax.js';
 import {} from 'zod';
 // The info string a fence carries when the host names none of its own.
 export const UI_FENCE_LANGUAGE = 'ui';
 export const UI_REPLY_LIMITS = { blocks: 16, characters: 262144, nodes: 2048, milliseconds: 60 };
-// What a host reads for one block: its queries, its link targets and how often a visible block reads again.
-export const UI_HOST_LIMITS = { queries: 8, links: 64, refreshMilliseconds: 10_000 };
+// What a host reads for one block: its queries, its link targets, the places it looks up and how often a visible block reads again.
+export const UI_HOST_LIMITS = { queries: 8, links: 64, places: 50, refreshMilliseconds: 10_000 };
+/* A Place that names an address, whose tag may hold quoted text with a `>` before it. */
+const ADDRESSED_PLACE = /<Place\b(?:[^>"']|"[^"]*"|'[^']*')*?\baddress\s*=/;
 /* A cheap test for whether `text` may declare a query or name a link target, before anything is read for it. */
 export function uiMayReferenceHost(text) {
     if (text.includes('@Query')) {
@@ -18,7 +20,19 @@ export function uiMayReferenceHost(text) {
     const links = Object.entries(UI_CATALOG)
         .filter(([, entry]) => entry.group === 'links')
         .map(([name]) => name);
-    return new RegExp(`<(?:${links.join('|')})\\b`).test(text);
+    return new RegExp(`<(?:${links.join('|')})\\b`).test(text) || ADDRESSED_PLACE.test(text);
+}
+/* The children of a Map as its fallback numbers them: each Place that drew, also inside a Show or an Each, in order, and anything else as it is. */
+function numberedPlaces(children) {
+    let number = 0;
+    const visit = (nodes) => nodes
+        .map((child) => child.type === 'Place' && !child.error
+        ? `${++number}. ${child.fallback}`
+        : child.type === 'Show' || child.type === 'Each'
+            ? visit(child.children)
+            : child.fallback)
+        .join('');
+    return visit(children);
 }
 /* A spent budget ends the whole block; every other failure only marks the node or declaration it came from. */
 function rethrowBudget(error) {
@@ -79,6 +93,10 @@ function isConstant(expression) {
     }
 }
 const CHART_SERIES = 6;
+/* How many of its children's kind a container holds, the ones an Each or a Show will draw not counted. */
+function countChildren(children, kinds) {
+    return children.reduce((count, child) => count + (kinds.includes(child.type) ? 1 : 0) + (child.type === 'Show' || child.type === 'Each' ? countChildren(child.children, kinds) : 0), 0);
+}
 /* The keys besides `label` that hold a finite number in some row of a chart's data. */
 function chartSeries(data) {
     const keys = new Set();
@@ -158,8 +176,11 @@ export function compileUiBlock(source, options) {
                 throw new UiFailure('unknown_component', `Unknown component ${syntax.type}.`);
             }
             const entry = UI_CATALOG[syntax.type];
-            if ('parent' in entry && entry.parent !== parent) {
-                throw new UiFailure('invalid_parent', `${syntax.type} belongs inside ${entry.parent}.`);
+            if ('parent' in entry) {
+                const parents = [entry.parent].flat();
+                if (parent === undefined || !parents.includes(parent)) {
+                    throw new UiFailure('invalid_parent', `${syntax.type} belongs inside ${parents.join(' or ')}.`);
+                }
             }
             if (parent && isUiComponent(parent)) {
                 const container = UI_CATALOG[parent];
@@ -224,6 +245,15 @@ export function compileUiBlock(source, options) {
             if (!unresolved && syntax.complete && syntax.type === 'Chart' && chartSeries(evaluated.data) > CHART_SERIES) {
                 diagnose(new UiFailure('too_many_series', `Chart draws up to ${CHART_SERIES} numeric series; the rest are only in its values.`), syntax.start, syntax.end, syntax.id);
             }
+            if (syntax.complete && 'count' in entry) {
+                const counted = countChildren(syntax.children, entry.children);
+                const limit = entry.count;
+                if (counted < limit.min || (limit.max !== undefined && counted > limit.max)) {
+                    throw new UiFailure('invalid_props', limit.max === undefined
+                        ? `${syntax.type} needs at least ${limit.min} of ${entry.children.join(' or ')}.`
+                        : `${syntax.type} takes ${limit.min} to ${limit.max} of ${entry.children.join(' or ')}.`);
+                }
+            }
             // A Choice sends its label, so one without a label can never send; whether it closed is only known once final.
             if (syntax.type === 'Choice' && syntax.complete && !syntax.children.some(isLabelSource)) {
                 throw new UiFailure('invalid_props', 'A choice needs a visible label.');
@@ -243,7 +273,17 @@ export function compileUiBlock(source, options) {
         }
         const effectiveParent = syntax.type === 'Show' || syntax.type === 'Each' ? parent : syntax.type;
         node.children = syntax.children.map((child) => compile(child, depth + 1, effectiveParent));
-        const childText = node.children.map((child) => child.fallback).join('');
+        // A reader of the fallback has no control to look at, so the option a dropdown or a segmented control starts on says it is chosen.
+        const chosen = syntax.type === 'Select' || syntax.type === 'Segmented' ? fallbackProps.value : undefined;
+        const childText = syntax.type === 'Map'
+            ? numberedPlaces(node.children)
+            : node.children
+                .map((child) => syntax.type === 'Select' && child.type === '$text' && child.fallback.trim() !== ''
+                ? `${child.fallback.trim()}\n`
+                : chosen !== undefined && child.type === 'Option' && !child.error && sameUiValue(child.props.value, chosen)
+                    ? `${child.fallback.trimEnd()} (chosen)\n`
+                    : child.fallback)
+                .join('');
         node.fallback = uiNodeFallback(syntax.type, fallbackProps, childText);
         // A part drawn as its text keeps the words written inside it, also where its kind reads only props.
         if (node.error !== undefined && childText.trim() !== '' && !node.fallback.includes(childText.trim())) {

package/dist/event-time.d.ts

@@ -0,0 +1,6 @@
+export interface UiEventTime {
+    kind: 'time' | 'date' | 'datetime';
+    date: Date;
+    written: boolean;
+}
+export declare function parseUiEventTime(at: string): UiEventTime | null;

package/dist/event-time.js

@@ -0,0 +1,44 @@
+const EVENT_TIME = /^(?:(\d{2}):(\d{2})|(\d{4})-(\d{2})-(\d{2})(?:T(\d{2}):(\d{2})(?::(\d{2})(?:\.\d{1,9})?)?(Z|[+-]\d{2}:\d{2})?)?)$/;
+function validClock(hour, minute, second = 0) {
+    return hour <= 23 && minute <= 59 && second <= 59;
+}
+/* The minutes east of UTC that `Z` or `+02:00` stand for, or null for an offset no zone has: from -12:00 to +14:00. */
+function zoneOffset(zone) {
+    if (zone === 'Z') {
+        return 0;
+    }
+    const [hours, minutes] = [Number(zone.slice(1, 3)), Number(zone.slice(4, 6))];
+    const offset = (zone[0] === '-' ? -1 : 1) * (hours * 60 + minutes);
+    return minutes > 59 || offset < -12 * 60 || offset > 14 * 60 ? null : offset;
+}
+/* The moment an Event's `at` names, or null when it is no `HH:MM`, `YYYY-MM-DD` or ISO date-time with an optional offset. */
+export function parseUiEventTime(at) {
+    const match = EVENT_TIME.exec(at);
+    if (match === null) {
+        return null;
+    }
+    const [, clockHour, clockMinute, year, month, day, hour, minute, second, zone] = match.map((part) => part);
+    if (clockHour !== undefined) {
+        // The day is not shown for a time, so any day will do.
+        return validClock(Number(clockHour), Number(clockMinute))
+            ? { kind: 'time', date: new Date(Date.UTC(2000, 0, 1, Number(clockHour), Number(clockMinute))), written: true }
+            : null;
+    }
+    const [y, m, d] = [Number(year), Number(month), Number(day)];
+    const calendar = new Date(Date.UTC(y, m - 1, d));
+    if (calendar.getUTCFullYear() !== y || calendar.getUTCMonth() !== m - 1 || calendar.getUTCDate() !== d) {
+        return null;
+    }
+    if (hour === undefined) {
+        return { kind: 'date', date: calendar, written: true };
+    }
+    const [h, min, sec] = [Number(hour), Number(minute), Number(second ?? 0)];
+    if (!validClock(h, min, sec)) {
+        return null;
+    }
+    if (zone === undefined) {
+        return { kind: 'datetime', date: new Date(Date.UTC(y, m - 1, d, h, min, sec)), written: true };
+    }
+    const offset = zoneOffset(zone);
+    return offset === null ? null : { kind: 'datetime', date: new Date(Date.UTC(y, m - 1, d, h, min, sec) - offset * 60000), written: false };
+}

package/dist/fallback.js

@@ -18,6 +18,8 @@ export function uiNodeFallback(type, props, children) {
             return `${children.trimEnd()}${given(props.badge) ? ` (${uiPlainText(props.badge)})` : ''}\n`;
         case 'Step':
             return `${children.trimEnd()}${given(props.state) ? ` (${uiPlainText(props.state)})` : ''}${given(props.detail) ? `: ${uiPlainText(props.detail)}` : ''}\n`;
+        case 'Event':
+            return `${uiPlainText(props.at)} ${children.trimEnd()}${given(props.tone) ? ` (${uiPlainText(props.tone)})` : ''}${given(props.detail) ? `: ${uiPlainText(props.detail)}` : ''}\n`;
         case 'Progress':
             return given(props.value) ? `${children.trimEnd()}: ${uiPlainText(props.value)} of ${uiPlainText(props.max ?? 100)}\n` : `${children.trimEnd()}\n`;
         case 'Stat': {
@@ -38,6 +40,18 @@ export function uiNodeFallback(type, props, children) {
         }
         case 'Chart':
             return `${uiPlainText(props.data ?? [])}${given(props.unit) ? ` (${uiPlainText(props.unit)})` : ''}\n`;
+        case 'Compare':
+            return `[Compare: ${uiPlainText(props.beforeLabel || 'Before')} ${uiPlainText(props.before)}, ${uiPlainText(props.afterLabel || 'After')} ${uiPlainText(props.after)}]${children.trim() ? ` ${children.trim()}` : ''}\n`;
+        case 'Place': {
+            const point = given(props.lat) && given(props.lon) ? ` (${uiPlainText(props.lat)}, ${uiPlainText(props.lon)})` : '';
+            const address = given(props.address) ? `, ${uiPlainText(props.address)}` : '';
+            const detail = given(props.detail) ? `: ${uiPlainText(props.detail)}` : '';
+            // One line per place, so the numbering of its map counts places and not the lines of a name.
+            return `${children.trim()}${point}${address}${detail}`.replace(/\s+/g, ' ').trim() + '\n';
+        }
+        case 'Map':
+            // The places are numbered where the compiler joins them, since only it knows which of the children drew.
+            return children;
         case 'Image':
             return `[Image: ${uiPlainText(props.alt ?? props.attachment ?? props.generated ?? 'unavailable')}]${children}\n`;
     }

package/dist/index.d.ts

@@ -1,4 +1,5 @@
-export { UI_CATALOG, UI_CATALOG_VERSION, UI_GROUPS, UiToneSchema, isUiComponent, uiCatalogText, type UiComponentName, type UiProps, type UiTone } from './catalog.ts';
+export { UI_CATALOG, UI_CATALOG_VERSION, UI_GROUPS, UiToneSchema, isUiComponent, uiCatalogText, type UiComponentName, type UiGroupName, type UiProps, type UiTone } from './catalog.ts';
+export { parseUiEventTime, type UiEventTime } from './event-time.ts';
 export { UI_LIMITS, UiBudget, UiFailure, safeKey, type UiLimits } from './budget.ts';
 export { copyUiValue, evaluateUiExpression, parseUiExpression, sameUiValue, type UiExpression, type UiValue } from './expression.ts';
 export { parseUiSyntax, uiDiagnostic, type UiDiagnostic, type UiSyntax, type UiSyntaxNode } from './syntax.ts';
@@ -6,6 +7,7 @@ export { UI_FENCE_LANGUAGE, UI_HOST_LIMITS, UI_REPLY_LIMITS, UiCompiler, compile
 export { evaluateUiBlock, UiState, uiInputValues, resolveUiChoice, uiChoiceLabel, type UiChoiceSelection, type UiBinding, type UiEvaluation, type UiViewNode } from './runtime.ts';
 export { uiValidatedState, uiQueryArguments, uiQueryFallback } from './query.ts';
 export { UiNodeSchema, UiDiagnosticSchema, UiBlockSchema, UiBlocksSchema } from './protocol.ts';
-export { uiCompactCatalog, uiSessionNote, uiReferenceText, uiFallbackText, type UiTextOptions } from './text.ts';
+export { uiCompactCatalog, uiSessionNote, uiGroupReference, uiReferenceText, uiFallbackText, type UiTextOptions } from './text.ts';
 export { UI_STREAM_INTERVAL_MS, UiStream, type UiStreamClock, type UiStreamOptions, type UiStreamPreview } from './stream.ts';
+export { uiPlaceQueries, type UiPlaceQuery } from './places.ts';
 export { UiLinkTargetSchema, UiLinkResolutionSchema, uiLinkTargets, type UiLinkTarget, type UiLinkResolution } from './links.ts';

package/dist/index.js

@@ -1,4 +1,5 @@
 export { UI_CATALOG, UI_CATALOG_VERSION, UI_GROUPS, UiToneSchema, isUiComponent, uiCatalogText } from './catalog.js';
+export { parseUiEventTime } from './event-time.js';
 export { UI_LIMITS, UiBudget, UiFailure, safeKey } from './budget.js';
 export { copyUiValue, evaluateUiExpression, parseUiExpression, sameUiValue } from './expression.js';
 export { parseUiSyntax, uiDiagnostic } from './syntax.js';
@@ -6,6 +7,7 @@ export { UI_FENCE_LANGUAGE, UI_HOST_LIMITS, UI_REPLY_LIMITS, UiCompiler, compile
 export { evaluateUiBlock, UiState, uiInputValues, resolveUiChoice, uiChoiceLabel } from './runtime.js';
 export { uiValidatedState, uiQueryArguments, uiQueryFallback } from './query.js';
 export { UiNodeSchema, UiDiagnosticSchema, UiBlockSchema, UiBlocksSchema } from './protocol.js';
-export { uiCompactCatalog, uiSessionNote, uiReferenceText, uiFallbackText } from './text.js';
+export { uiCompactCatalog, uiSessionNote, uiGroupReference, uiReferenceText, uiFallbackText } from './text.js';
 export { UI_STREAM_INTERVAL_MS, UiStream } from './stream.js';
+export { uiPlaceQueries } from './places.js';
 export { UiLinkTargetSchema, UiLinkResolutionSchema, uiLinkTargets } from './links.js';

package/dist/inputs.js

@@ -9,9 +9,12 @@ export function uiCompiledNodes(nodes, into = new Map()) {
 }
 /* Whether a control's value is one its own visible options offer. */
 function offered(node) {
-    if (node.type === 'Segmented') {
+    if (node.type === 'Segmented' || node.type === 'Select') {
         return node.children.some((option) => option.type === 'Option' && !option.error && option.props.value === node.props.value);
     }
+    if (node.type === 'Map') {
+        return node.children.some((place) => place.type === 'Place' && !place.error && place.props.value === node.props.value);
+    }
     if (node.type === 'Checklist') {
         const options = node.children.filter((item) => item.type === 'Item' && !item.error).map((item) => item.props.value);
         return node.props.value.every((value) => options.includes(value));

package/dist/places.d.ts

@@ -0,0 +1,7 @@
+import type { UiLimits } from './budget.ts';
+import type { UiBlock } from './compiler.ts';
+export interface UiPlaceQuery {
+    address: string;
+    name: string;
+}
+export declare function uiPlaceQueries(block: UiBlock, input?: Readonly<Record<string, unknown>>, queries?: Readonly<Record<string, unknown>>, limits?: Partial<UiLimits>): Record<string, UiPlaceQuery>;

package/dist/places.js

@@ -0,0 +1,32 @@
+import { uiValidatedState } from './query.js';
+import { evaluateUiBlock } from './runtime.js';
+function nameOf(node) {
+    return node.children
+        .map((child) => (child.type === '$text' ? String(child.props.text ?? '') : nameOf(child)))
+        .join('')
+        .replace(/\s+/g, ' ')
+        .trim();
+}
+/*
+ * The complete, valid Places that give an address, by node id, as the block evaluates with `input` and the
+ * values of its `queries`. A place that also gives coordinates is looked up too: what the host finds for
+ * the address wins, and the coordinates stand when it finds nothing.
+ */
+export function uiPlaceQueries(block, input = {}, queries = {}, limits = {}) {
+    const state = uiValidatedState(block, input, queries, limits);
+    const places = Object.create(null);
+    const visit = (nodes) => {
+        for (const node of nodes) {
+            if (node.error || !node.complete) {
+                continue;
+            }
+            const { address } = node.props;
+            if (node.type === 'Place' && typeof address === 'string' && address.trim() !== '') {
+                places[node.id] = { address: address.trim(), name: nameOf(node) };
+            }
+            visit(node.children);
+        }
+    };
+    visit(evaluateUiBlock(block, state, limits).nodes);
+    return places;
+}

package/dist/runtime.d.ts

@@ -16,6 +16,7 @@ export interface UiViewNode<Props = Record<string, unknown>> {
     complete: boolean;
     fallback: string;
     error?: string;
+    omitted?: number;
     onAction?(): void;
 }
 export interface UiEvaluation {

package/dist/runtime.js

@@ -207,6 +207,23 @@ export function evaluateUiBlock(block, state = new UiState(block), limits = {})
                 };
             }
             view.children = children(node.children, variables, depth + 1, suffix);
+            if ('count' in entry) {
+                const limit = entry.count;
+                const kinds = entry.children;
+                const counted = view.children.filter((child) => kinds.includes(child.type)).length;
+                // What an Each or a Show drew is only known now, so the count the compiler checked on the source is checked again.
+                if (node.complete && counted < limit.min) {
+                    throw new UiFailure('invalid_props', `${node.type} needs at least ${limit.min} of ${kinds.join(' or ')}.`);
+                }
+                if (limit.max !== undefined && counted > limit.max) {
+                    let kept = 0;
+                    view.children = view.children.filter((child) => !kinds.includes(child.type) || ++kept <= limit.max);
+                    view.omitted = counted - limit.max;
+                    if (result.diagnostics.length < budget.limits.diagnostics) {
+                        result.diagnostics.push(uiDiagnostic(new UiFailure('too_many_children', `${node.type} shows its first ${limit.max} of ${kinds.join(' or ')}.`), node.start, node.end, node.id));
+                    }
+                }
+            }
             return [view];
         }
         catch (error) {

package/dist/text.d.ts

@@ -1,8 +1,12 @@
+import { type UiGroupName } from './catalog.ts';
 import { type UiBlock } from './compiler.ts';
 export declare function uiCompactCatalog(): string;
 export interface UiTextOptions {
     fenceLanguage?: string;
+    catalog?: 'props' | 'names';
+    detailHint?: string;
 }
-export declare function uiSessionNote({ fenceLanguage }?: UiTextOptions): string;
+export declare function uiSessionNote({ fenceLanguage, catalog, detailHint }?: UiTextOptions): string;
+export declare function uiGroupReference(group: UiGroupName): string;
 export declare function uiReferenceText({ fenceLanguage }?: UiTextOptions): string;
 export declare function uiFallbackText(text: string, blocks: readonly UiBlock[]): string;

package/dist/text.js

@@ -22,21 +22,30 @@ function uiExample(language) {
         '```'
     ].join('\n');
 }
-export function uiSessionNote({ fenceLanguage = UI_FENCE_LANGUAGE } = {}) {
-    return `${uiSyntax(fenceLanguage)} Prose outside. Only named catalog props, no styling. $name = literal JSON; input value={$name}; Button action={@Set($name, literal)}, {@Reset($name)} or {@Reset()} changes local state only; braced expressions: @Count, @Filter(list,row,predicate), @Sum, @Join, @Round. Show/Each control children. Choices are shortcuts after finished work that the person may ignore. When your turn would end waiting on the person (a missing fact, a decision, a go-ahead for work you would otherwise do), ask with your own question tool if you have one, otherwise in prose, never with Choices. Choice labels and precise context stay visible and send once. Image: attachment or generated="latest", never URL/path. No code execution. State resets on reload. Catalog (? means optional props): ${uiCompactCatalog()}\nExample:\n${uiExample(fenceLanguage)}\n`;
+function uiGroupComponents(group) {
+    return Object.entries(UI_CATALOG).filter(([, entry]) => entry.group === group);
+}
+/* One line per group with the names of its components, for a host that hands the props out per group. */
+function uiGroupNames(detailHint) {
+    const lines = Object.keys(UI_GROUPS).map((group) => `${group}: ${uiGroupComponents(group)
+        .map(([name]) => name)
+        .join(', ')}`);
+    return `Components by group${detailHint ? ` (${detailHint})` : ''}:\n${lines.join('\n')}`;
+}
+export function uiSessionNote({ fenceLanguage = UI_FENCE_LANGUAGE, catalog = 'props', detailHint } = {}) {
+    const components = catalog === 'names' ? uiGroupNames(detailHint) : `Catalog (? means optional props): ${uiCompactCatalog()}`;
+    return `${uiSyntax(fenceLanguage)} Prose outside. Only named catalog props, no styling. $name = literal JSON; input value={$name}; Button action={@Set($name, literal)}, {@Reset($name)} or {@Reset()} changes local state only; braced expressions: @Count, @Filter(list,row,predicate), @Sum, @Join, @Round. Show/Each control children. Choices are shortcuts after finished work that the person may ignore. When your turn would end waiting on the person (a missing fact, a decision, a go-ahead for work you would otherwise do), ask with your own question tool if you have one, otherwise in prose, never with Choices. Choice labels and precise context stay visible and send once. Image: attachment or generated="latest", never URL/path. No code execution. State resets on reload. ${components}\nExample:\n${uiExample(fenceLanguage)}\n`;
+}
+/* One group as the reference writes it: its description and rules, then every component with its props. */
+export function uiGroupReference(group) {
+    const components = uiGroupComponents(group).map(([name, entry]) => {
+        const props = uiPropList(entry).join(', ');
+        return `${name}: ${entry.description}${props ? ` Props: ${props}.` : ''}`;
+    });
+    return [UI_GROUPS[group].description, UI_GROUPS[group].rules, ...components].join('\n');
 }
 export function uiReferenceText({ fenceLanguage = UI_FENCE_LANGUAGE } = {}) {
-    const groups = Object.entries(UI_GROUPS)
-        .map(([group, definition]) => {
-        const components = Object.entries(UI_CATALOG)
-            .filter(([, entry]) => entry.group === group)
-            .map(([name, entry]) => {
-            const props = uiPropList(entry).join(', ');
-            return `${name}: ${entry.description}${props ? ` Props: ${props}.` : ''}`;
-        });
-        return [definition.description, definition.rules, ...components].join('\n');
-    })
-        .join('\n\n');
+    const groups = Object.keys(UI_GROUPS).map(uiGroupReference).join('\n\n');
     return `${uiSyntax(fenceLanguage)}\nExample:\n${uiExample(fenceLanguage)}\n\n${groups}`;
 }
 export function uiFallbackText(text, blocks) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adecore/intelligent-ui",
-  "version": "0.24.1",
+  "version": "0.25.0",
   "description": "A streaming UI catalog, compiler and bounded expression interpreter without a framework or DOM.",
   "license": "FSL-1.1-MIT",
   "author": "Bas Milius",
@@ -32,6 +32,11 @@
       "types": "./dist/links.d.ts",
       "default": "./dist/links.js"
     },
+    "./places": {
+      "source": "./src/places.ts",
+      "types": "./dist/places.d.ts",
+      "default": "./dist/places.js"
+    },
     "./query": {
       "source": "./src/query.ts",
       "types": "./dist/query.d.ts",
@@ -42,6 +47,11 @@
       "types": "./dist/catalog.d.ts",
       "default": "./dist/catalog.js"
     },
+    "./event-time": {
+      "source": "./src/event-time.ts",
+      "types": "./dist/event-time.d.ts",
+      "default": "./dist/event-time.js"
+    },
     "./budget": {
       "source": "./src/budget.ts",
       "types": "./dist/budget.d.ts",

package/src/catalog.ts

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { parseUiEventTime } from './event-time.ts';
 import { uiPropList } from './prop-list.ts';
 
 export const UI_CATALOG_VERSION = 1;
@@ -19,7 +20,11 @@ export const UI_GROUPS = {
     structure: { description: 'Organize distinct topics.', rules: 'Use Tabs for alternatives and Sections for independent topics.' },
     content: {
         description: 'Include code, attachments and sources.',
-        rules: 'Image accepts a chat attachment or generated="latest", never a URL or a local path.'
+        rules: 'Image accepts a chat attachment or generated="latest", never a URL or a local path. Gallery and Compare take chat attachments too. The host says how to attach a file of your own.'
+    },
+    places: {
+        description: 'Show places on a map the host draws.',
+        rules: 'Give lat and lon in decimal degrees, or an address the host looks up. Never a tile or map URL. The host chooses the map.'
     },
     links: { description: 'Refer to a host-owned resource.', rules: 'Targets are checked by the host. No arbitrary navigation or file reads.' },
     inputs: {
@@ -48,6 +53,17 @@ export const UI_CATALOG = {
         schema: z.strictObject({ state: z.enum(['done', 'running', 'pending', 'failed', 'skipped']), detail: text.optional() }),
         parent: 'Steps'
     },
+    Timeline: { group: 'status', description: 'Events in time order.', schema: empty, children: ['Event'], count: { min: 1 } },
+    Event: {
+        group: 'status',
+        description: 'One event at a time or date; children are the title.',
+        schema: z.strictObject({
+            at: text.refine((value) => parseUiEventTime(value) !== null, 'At must be HH:MM, YYYY-MM-DD or an ISO date-time.'),
+            tone,
+            detail: text.optional()
+        }),
+        parent: 'Timeline'
+    },
     Stats: { group: 'data', description: 'A small set of key numbers.', schema: empty, children: ['Stat'] },
     Stat: {
         group: 'data',
@@ -90,6 +106,38 @@ export const UI_CATALOG = {
             .strictObject({ attachment: name.optional(), generated: z.literal('latest').optional(), alt: text.optional() })
             .refine((props) => Boolean(props.attachment) !== Boolean(props.generated), 'Choose attachment or generated, exclusively.')
     },
+    Gallery: { group: 'content', description: 'A grid of images with captions; at most 24.', schema: empty, children: ['Image'], count: { min: 1, max: 24 } },
+    Compare: {
+        group: 'content',
+        description: 'Two chat attachments in one frame with a handle to wipe between them; children are the caption.',
+        schema: z.strictObject({ before: name, after: name, beforeLabel: text.optional(), afterLabel: text.optional() })
+    },
+    Map: {
+        group: 'places',
+        description: 'One to 50 places on a map the host draws, with a numbered list under it; bind value to let a person pick a place.',
+        schema: z.strictObject({ value: scalar.optional() }),
+        children: ['Place'],
+        binding: 'value',
+        count: { min: 1, max: 50 }
+    },
+    Place: {
+        group: 'places',
+        description:
+            'One place by lat and lon, or by an address the host looks up; with both, the point the host finds for the address wins and lat and lon stand when it finds none. Children are the name.',
+        schema: z
+            .strictObject({
+                lat: number.min(-90).max(90).optional(),
+                lon: number.min(-180).max(180).optional(),
+                address: text.max(512).optional(),
+                detail: text.optional(),
+                value: scalar.optional()
+            })
+            .refine(
+                (props) => (props.lat === undefined) === (props.lon === undefined) && (props.lat !== undefined || props.address !== undefined),
+                'Give lat with lon, or an address.'
+            ),
+        parent: 'Map'
+    },
     Sources: { group: 'content', description: 'Numbered sources without preloading.', schema: empty, children: ['Source'] },
     Source: {
         group: 'content',
@@ -123,7 +171,22 @@ export const UI_CATALOG = {
         binding: 'value'
     },
     Segmented: { group: 'inputs', description: 'Choose one local value.', schema: z.strictObject({ value: scalar }), children: ['Option'], binding: 'value' },
-    Option: { group: 'inputs', description: 'One local alternative.', schema: z.strictObject({ value: scalar }), parent: 'Segmented' },
+    Select: {
+        group: 'inputs',
+        description: 'Choose one local value from a dropdown, for more or longer options than Segmented holds; the text beside its Options is its label.',
+        schema: z.strictObject({ value: scalar }),
+        children: ['Option'],
+        binding: 'value'
+    },
+    Option: { group: 'inputs', description: 'One local alternative.', schema: z.strictObject({ value: scalar }), parent: ['Segmented', 'Select'] },
+    TextField: {
+        group: 'inputs',
+        description: 'A line of local text up to maxLength characters (256 without one, at most 1024); children are the label.',
+        schema: z
+            .strictObject({ value: text, maxLength: z.number().int().min(1).max(1024).optional(), placeholder: text.max(128).optional() })
+            .refine((props) => props.value.length <= (props.maxLength ?? 256), 'Value must not be longer than maxLength.'),
+        binding: 'value'
+    },
     Button: {
         group: 'inputs',
         description: 'Run one local state action when pressed; children are the label.',
@@ -145,6 +208,7 @@ export const UI_CATALOG = {
     }
 } as const;
 
+export type UiGroupName = keyof typeof UI_GROUPS;
 export type UiComponentName = keyof typeof UI_CATALOG;
 export type UiProps<Name extends UiComponentName> = z.infer<(typeof UI_CATALOG)[Name]['schema']>;
 

package/src/compiler.ts

@@ -2,7 +2,7 @@ import { safeKey, UI_LIMITS, UiBudget, UiFailure, type UiLimits } from './budget
 import { isUiComponent, UI_CATALOG, UI_CATALOG_VERSION } from './catalog.ts';
 import { uiActionProp, uiActionTarget, uiLocalState } from './actions.ts';
 import { uiNodeFallback, uiPlainText } from './fallback.ts';
-import { evaluateUiExpression, type UiExpression, type UiValue } from './expression.ts';
+import { evaluateUiExpression, sameUiValue, type UiExpression, type UiValue } from './expression.ts';
 import { parseUiSyntax, uiDiagnostic, type UiDiagnostic, type UiSyntaxNode } from './syntax.ts';
 import { type z } from 'zod';
 
@@ -11,8 +11,11 @@ export const UI_FENCE_LANGUAGE = 'ui';
 
 export const UI_REPLY_LIMITS = { blocks: 16, characters: 262144, nodes: 2048, milliseconds: 60 } as const;
 
-// What a host reads for one block: its queries, its link targets and how often a visible block reads again.
-export const UI_HOST_LIMITS = { queries: 8, links: 64, refreshMilliseconds: 10_000 } as const;
+// What a host reads for one block: its queries, its link targets, the places it looks up and how often a visible block reads again.
+export const UI_HOST_LIMITS = { queries: 8, links: 64, places: 50, refreshMilliseconds: 10_000 } as const;
+
+/* A Place that names an address, whose tag may hold quoted text with a `>` before it. */
+const ADDRESSED_PLACE = /<Place\b(?:[^>"']|"[^"]*"|'[^']*')*?\baddress\s*=/;
 
 /* A cheap test for whether `text` may declare a query or name a link target, before anything is read for it. */
 export function uiMayReferenceHost(text: string): boolean {
@@ -22,7 +25,23 @@ export function uiMayReferenceHost(text: string): boolean {
     const links = Object.entries(UI_CATALOG)
         .filter(([, entry]) => entry.group === 'links')
         .map(([name]) => name);
-    return new RegExp(`<(?:${links.join('|')})\\b`).test(text);
+    return new RegExp(`<(?:${links.join('|')})\\b`).test(text) || ADDRESSED_PLACE.test(text);
+}
+
+/* The children of a Map as its fallback numbers them: each Place that drew, also inside a Show or an Each, in order, and anything else as it is. */
+function numberedPlaces(children: readonly UiNode[]): string {
+    let number = 0;
+    const visit = (nodes: readonly UiNode[]): string =>
+        nodes
+            .map((child) =>
+                child.type === 'Place' && !child.error
+                    ? `${++number}. ${child.fallback}`
+                    : child.type === 'Show' || child.type === 'Each'
+                      ? visit(child.children)
+                      : child.fallback
+            )
+            .join('');
+    return visit(children);
 }
 
 export interface UiNode {
@@ -140,6 +159,15 @@ function isConstant(expression: UiExpression): boolean {
 
 const CHART_SERIES = 6;
 
+/* How many of its children's kind a container holds, the ones an Each or a Show will draw not counted. */
+function countChildren(children: readonly UiSyntaxNode[], kinds: readonly string[]): number {
+    return children.reduce(
+        (count, child) =>
+            count + (kinds.includes(child.type) ? 1 : 0) + (child.type === 'Show' || child.type === 'Each' ? countChildren(child.children, kinds) : 0),
+        0
+    );
+}
+
 /* The keys besides `label` that hold a finite number in some row of a chart's data. */
 function chartSeries(data: unknown): number {
     const keys = new Set<string>();
@@ -219,8 +247,11 @@ export function compileUiBlock(source: string, options: UiCompileOptions): UiBlo
                 throw new UiFailure('unknown_component', `Unknown component ${syntax.type}.`);
             }
             const entry = UI_CATALOG[syntax.type];
-            if ('parent' in entry && entry.parent !== parent) {
-                throw new UiFailure('invalid_parent', `${syntax.type} belongs inside ${entry.parent}.`);
+            if ('parent' in entry) {
+                const parents: readonly string[] = [entry.parent].flat();
+                if (parent === undefined || !parents.includes(parent)) {
+                    throw new UiFailure('invalid_parent', `${syntax.type} belongs inside ${parents.join(' or ')}.`);
+                }
             }
             if (parent && isUiComponent(parent)) {
                 const container = UI_CATALOG[parent];
@@ -290,6 +321,18 @@ export function compileUiBlock(source: string, options: UiCompileOptions): UiBlo
                     syntax.id
                 );
             }
+            if (syntax.complete && 'count' in entry) {
+                const counted = countChildren(syntax.children, entry.children);
+                const limit = entry.count as { min: number; max?: number };
+                if (counted < limit.min || (limit.max !== undefined && counted > limit.max)) {
+                    throw new UiFailure(
+                        'invalid_props',
+                        limit.max === undefined
+                            ? `${syntax.type} needs at least ${limit.min} of ${entry.children.join(' or ')}.`
+                            : `${syntax.type} takes ${limit.min} to ${limit.max} of ${entry.children.join(' or ')}.`
+                    );
+                }
+            }
             // A Choice sends its label, so one without a label can never send; whether it closed is only known once final.
             if (syntax.type === 'Choice' && syntax.complete && !syntax.children.some(isLabelSource)) {
                 throw new UiFailure('invalid_props', 'A choice needs a visible label.');
@@ -308,7 +351,20 @@ export function compileUiBlock(source: string, options: UiCompileOptions): UiBlo
         }
         const effectiveParent = syntax.type === 'Show' || syntax.type === 'Each' ? parent : syntax.type;
         node.children = syntax.children.map((child) => compile(child, depth + 1, effectiveParent));
-        const childText = node.children.map((child) => child.fallback).join('');
+        // A reader of the fallback has no control to look at, so the option a dropdown or a segmented control starts on says it is chosen.
+        const chosen = syntax.type === 'Select' || syntax.type === 'Segmented' ? fallbackProps.value : undefined;
+        const childText =
+            syntax.type === 'Map'
+                ? numberedPlaces(node.children)
+                : node.children
+                      .map((child) =>
+                          syntax.type === 'Select' && child.type === '$text' && child.fallback.trim() !== ''
+                              ? `${child.fallback.trim()}\n`
+                              : chosen !== undefined && child.type === 'Option' && !child.error && sameUiValue(child.props.value, chosen)
+                                ? `${child.fallback.trimEnd()} (chosen)\n`
+                                : child.fallback
+                      )
+                      .join('');
         node.fallback = uiNodeFallback(syntax.type, fallbackProps, childText);
         // A part drawn as its text keeps the words written inside it, also where its kind reads only props.
         if (node.error !== undefined && childText.trim() !== '' && !node.fallback.includes(childText.trim())) {

package/src/event-time.ts

@@ -0,0 +1,54 @@
+const EVENT_TIME = /^(?:(\d{2}):(\d{2})|(\d{4})-(\d{2})-(\d{2})(?:T(\d{2}):(\d{2})(?::(\d{2})(?:\.\d{1,9})?)?(Z|[+-]\d{2}:\d{2})?)?)$/;
+
+export interface UiEventTime {
+    kind: 'time' | 'date' | 'datetime';
+    date: Date;
+    // True when the text gave no offset: `date` then holds the parts as written in UTC, to be written in UTC, so no zone or clock change moves them. False is a real instant, to be written in the reader's zone.
+    written: boolean;
+}
+
+function validClock(hour: number, minute: number, second = 0): boolean {
+    return hour <= 23 && minute <= 59 && second <= 59;
+}
+
+/* The minutes east of UTC that `Z` or `+02:00` stand for, or null for an offset no zone has: from -12:00 to +14:00. */
+function zoneOffset(zone: string): number | null {
+    if (zone === 'Z') {
+        return 0;
+    }
+    const [hours, minutes] = [Number(zone.slice(1, 3)), Number(zone.slice(4, 6))];
+    const offset = (zone[0] === '-' ? -1 : 1) * (hours * 60 + minutes);
+    return minutes > 59 || offset < -12 * 60 || offset > 14 * 60 ? null : offset;
+}
+
+/* The moment an Event's `at` names, or null when it is no `HH:MM`, `YYYY-MM-DD` or ISO date-time with an optional offset. */
+export function parseUiEventTime(at: string): UiEventTime | null {
+    const match = EVENT_TIME.exec(at);
+    if (match === null) {
+        return null;
+    }
+    const [, clockHour, clockMinute, year, month, day, hour, minute, second, zone] = match.map((part) => part as string | undefined);
+    if (clockHour !== undefined) {
+        // The day is not shown for a time, so any day will do.
+        return validClock(Number(clockHour), Number(clockMinute))
+            ? { kind: 'time', date: new Date(Date.UTC(2000, 0, 1, Number(clockHour), Number(clockMinute))), written: true }
+            : null;
+    }
+    const [y, m, d] = [Number(year), Number(month), Number(day)];
+    const calendar = new Date(Date.UTC(y, m - 1, d));
+    if (calendar.getUTCFullYear() !== y || calendar.getUTCMonth() !== m - 1 || calendar.getUTCDate() !== d) {
+        return null;
+    }
+    if (hour === undefined) {
+        return { kind: 'date', date: calendar, written: true };
+    }
+    const [h, min, sec] = [Number(hour), Number(minute), Number(second ?? 0)];
+    if (!validClock(h, min, sec)) {
+        return null;
+    }
+    if (zone === undefined) {
+        return { kind: 'datetime', date: new Date(Date.UTC(y, m - 1, d, h, min, sec)), written: true };
+    }
+    const offset = zoneOffset(zone);
+    return offset === null ? null : { kind: 'datetime', date: new Date(Date.UTC(y, m - 1, d, h, min, sec) - offset * 60000), written: false };
+}

package/src/fallback.ts

@@ -20,6 +20,8 @@ export function uiNodeFallback(type: string, props: Readonly<Record<string, unkn
             return `${children.trimEnd()}${given(props.badge) ? ` (${uiPlainText(props.badge)})` : ''}\n`;
         case 'Step':
             return `${children.trimEnd()}${given(props.state) ? ` (${uiPlainText(props.state)})` : ''}${given(props.detail) ? `: ${uiPlainText(props.detail)}` : ''}\n`;
+        case 'Event':
+            return `${uiPlainText(props.at)} ${children.trimEnd()}${given(props.tone) ? ` (${uiPlainText(props.tone)})` : ''}${given(props.detail) ? `: ${uiPlainText(props.detail)}` : ''}\n`;
         case 'Progress':
             return given(props.value) ? `${children.trimEnd()}: ${uiPlainText(props.value)} of ${uiPlainText(props.max ?? 100)}\n` : `${children.trimEnd()}\n`;
         case 'Stat': {
@@ -40,6 +42,18 @@ export function uiNodeFallback(type: string, props: Readonly<Record<string, unkn
         }
         case 'Chart':
             return `${uiPlainText(props.data ?? [])}${given(props.unit) ? ` (${uiPlainText(props.unit)})` : ''}\n`;
+        case 'Compare':
+            return `[Compare: ${uiPlainText(props.beforeLabel || 'Before')} ${uiPlainText(props.before)}, ${uiPlainText(props.afterLabel || 'After')} ${uiPlainText(props.after)}]${children.trim() ? ` ${children.trim()}` : ''}\n`;
+        case 'Place': {
+            const point = given(props.lat) && given(props.lon) ? ` (${uiPlainText(props.lat)}, ${uiPlainText(props.lon)})` : '';
+            const address = given(props.address) ? `, ${uiPlainText(props.address)}` : '';
+            const detail = given(props.detail) ? `: ${uiPlainText(props.detail)}` : '';
+            // One line per place, so the numbering of its map counts places and not the lines of a name.
+            return `${children.trim()}${point}${address}${detail}`.replace(/\s+/g, ' ').trim() + '\n';
+        }
+        case 'Map':
+            // The places are numbered where the compiler joins them, since only it knows which of the children drew.
+            return children;
         case 'Image':
             return `[Image: ${uiPlainText(props.alt ?? props.attachment ?? props.generated ?? 'unavailable')}]${children}\n`;
     }

package/src/index.ts

@@ -6,9 +6,11 @@ export {
     isUiComponent,
     uiCatalogText,
     type UiComponentName,
+    type UiGroupName,
     type UiProps,
     type UiTone
 } from './catalog.ts';
+export { parseUiEventTime, type UiEventTime } from './event-time.ts';
 export { UI_LIMITS, UiBudget, UiFailure, safeKey, type UiLimits } from './budget.ts';
 export { copyUiValue, evaluateUiExpression, parseUiExpression, sameUiValue, type UiExpression, type UiValue } from './expression.ts';
 export { parseUiSyntax, uiDiagnostic, type UiDiagnostic, type UiSyntax, type UiSyntaxNode } from './syntax.ts';
@@ -41,7 +43,8 @@ export {
 } from './runtime.ts';
 export { uiValidatedState, uiQueryArguments, uiQueryFallback } from './query.ts';
 export { UiNodeSchema, UiDiagnosticSchema, UiBlockSchema, UiBlocksSchema } from './protocol.ts';
-export { uiCompactCatalog, uiSessionNote, uiReferenceText, uiFallbackText, type UiTextOptions } from './text.ts';
+export { uiCompactCatalog, uiSessionNote, uiGroupReference, uiReferenceText, uiFallbackText, type UiTextOptions } from './text.ts';
 export { UI_STREAM_INTERVAL_MS, UiStream, type UiStreamClock, type UiStreamOptions, type UiStreamPreview } from './stream.ts';
 
+export { uiPlaceQueries, type UiPlaceQuery } from './places.ts';
 export { UiLinkTargetSchema, UiLinkResolutionSchema, uiLinkTargets, type UiLinkTarget, type UiLinkResolution } from './links.ts';

package/src/inputs.ts

@@ -13,9 +13,12 @@ export function uiCompiledNodes(nodes: readonly UiNode[], into = new Map<string,
 
 /* Whether a control's value is one its own visible options offer. */
 function offered(node: UiViewNode): boolean {
-    if (node.type === 'Segmented') {
+    if (node.type === 'Segmented' || node.type === 'Select') {
         return node.children.some((option) => option.type === 'Option' && !option.error && option.props.value === node.props.value);
     }
+    if (node.type === 'Map') {
+        return node.children.some((place) => place.type === 'Place' && !place.error && place.props.value === node.props.value);
+    }
     if (node.type === 'Checklist') {
         const options = node.children.filter((item) => item.type === 'Item' && !item.error).map((item) => item.props.value);
         return (node.props.value as unknown[]).every((value) => options.includes(value));

package/src/places.ts

@@ -0,0 +1,47 @@
+import type { UiLimits } from './budget.ts';
+import type { UiBlock } from './compiler.ts';
+import { uiValidatedState } from './query.ts';
+import { evaluateUiBlock, type UiViewNode } from './runtime.ts';
+
+/* A place the agent named by an address, with the name it gave it, for a host to look up. */
+export interface UiPlaceQuery {
+    address: string;
+    name: string;
+}
+
+function nameOf(node: UiViewNode): string {
+    return node.children
+        .map((child) => (child.type === '$text' ? String(child.props.text ?? '') : nameOf(child)))
+        .join('')
+        .replace(/\s+/g, ' ')
+        .trim();
+}
+
+/*
+ * The complete, valid Places that give an address, by node id, as the block evaluates with `input` and the
+ * values of its `queries`. A place that also gives coordinates is looked up too: what the host finds for
+ * the address wins, and the coordinates stand when it finds nothing.
+ */
+export function uiPlaceQueries(
+    block: UiBlock,
+    input: Readonly<Record<string, unknown>> = {},
+    queries: Readonly<Record<string, unknown>> = {},
+    limits: Partial<UiLimits> = {}
+): Record<string, UiPlaceQuery> {
+    const state = uiValidatedState(block, input, queries, limits);
+    const places: Record<string, UiPlaceQuery> = Object.create(null);
+    const visit = (nodes: readonly UiViewNode[]) => {
+        for (const node of nodes) {
+            if (node.error || !node.complete) {
+                continue;
+            }
+            const { address } = node.props as { address?: string };
+            if (node.type === 'Place' && typeof address === 'string' && address.trim() !== '') {
+                places[node.id] = { address: address.trim(), name: nameOf(node) };
+            }
+            visit(node.children);
+        }
+    };
+    visit(evaluateUiBlock(block, state, limits).nodes);
+    return places;
+}

package/src/runtime.ts

@@ -21,6 +21,8 @@ export interface UiViewNode<Props = Record<string, unknown>> {
     complete: boolean;
     fallback: string;
     error?: string;
+    // How many children a container left out because it holds at most so many of its kind; absent when it left none out.
+    omitted?: number;
     // Runs the node's state action; present only on a component that has one.
     onAction?(): void;
 }
@@ -239,6 +241,30 @@ export function evaluateUiBlock(block: UiBlock, state = new UiState(block), limi
                 };
             }
             view.children = children(node.children, variables, depth + 1, suffix);
+            if ('count' in entry) {
+                const limit = entry.count as { min: number; max?: number };
+                const kinds = entry.children as readonly string[];
+                const counted = view.children.filter((child) => kinds.includes(child.type)).length;
+                // What an Each or a Show drew is only known now, so the count the compiler checked on the source is checked again.
+                if (node.complete && counted < limit.min) {
+                    throw new UiFailure('invalid_props', `${node.type} needs at least ${limit.min} of ${kinds.join(' or ')}.`);
+                }
+                if (limit.max !== undefined && counted > limit.max) {
+                    let kept = 0;
+                    view.children = view.children.filter((child) => !kinds.includes(child.type) || ++kept <= limit.max!);
+                    view.omitted = counted - limit.max;
+                    if (result.diagnostics.length < budget.limits.diagnostics) {
+                        result.diagnostics.push(
+                            uiDiagnostic(
+                                new UiFailure('too_many_children', `${node.type} shows its first ${limit.max} of ${kinds.join(' or ')}.`),
+                                node.start,
+                                node.end,
+                                node.id
+                            )
+                        );
+                    }
+                }
+            }
             return [view];
         } catch (error) {
             if (error instanceof UiFailure && error.code === 'budget_exceeded') {

package/src/text.ts

@@ -1,4 +1,4 @@
-import { UI_CATALOG, UI_GROUPS } from './catalog.ts';
+import { UI_CATALOG, UI_GROUPS, type UiGroupName } from './catalog.ts';
 import { uiPropList } from './prop-list.ts';
 import { UI_FENCE_LANGUAGE, type UiBlock } from './compiler.ts';
 
@@ -14,6 +14,10 @@ export function uiCompactCatalog(): string {
 export interface UiTextOptions {
     // The info string the host's compiler looks for; `UI_FENCE_LANGUAGE` without one.
     fenceLanguage?: string;
+    // What the session note lists: every component with its props, or only the names per group.
+    catalog?: 'props' | 'names';
+    // With `names`, how the agent gets the props of a group, in the host's own words.
+    detailHint?: string;
 }
 
 function uiSyntax(language: string): string {
@@ -31,22 +35,37 @@ function uiExample(language: string): string {
     ].join('\n');
 }
 
-export function uiSessionNote({ fenceLanguage = UI_FENCE_LANGUAGE }: UiTextOptions = {}): string {
-    return `${uiSyntax(fenceLanguage)} Prose outside. Only named catalog props, no styling. $name = literal JSON; input value={$name}; Button action={@Set($name, literal)}, {@Reset($name)} or {@Reset()} changes local state only; braced expressions: @Count, @Filter(list,row,predicate), @Sum, @Join, @Round. Show/Each control children. Choices are shortcuts after finished work that the person may ignore. When your turn would end waiting on the person (a missing fact, a decision, a go-ahead for work you would otherwise do), ask with your own question tool if you have one, otherwise in prose, never with Choices. Choice labels and precise context stay visible and send once. Image: attachment or generated="latest", never URL/path. No code execution. State resets on reload. Catalog (? means optional props): ${uiCompactCatalog()}\nExample:\n${uiExample(fenceLanguage)}\n`;
+function uiGroupComponents(group: string) {
+    return Object.entries(UI_CATALOG).filter(([, entry]) => entry.group === group);
+}
+
+/* One line per group with the names of its components, for a host that hands the props out per group. */
+function uiGroupNames(detailHint: string | undefined): string {
+    const lines = Object.keys(UI_GROUPS).map(
+        (group) =>
+            `${group}: ${uiGroupComponents(group)
+                .map(([name]) => name)
+                .join(', ')}`
+    );
+    return `Components by group${detailHint ? ` (${detailHint})` : ''}:\n${lines.join('\n')}`;
+}
+
+export function uiSessionNote({ fenceLanguage = UI_FENCE_LANGUAGE, catalog = 'props', detailHint }: UiTextOptions = {}): string {
+    const components = catalog === 'names' ? uiGroupNames(detailHint) : `Catalog (? means optional props): ${uiCompactCatalog()}`;
+    return `${uiSyntax(fenceLanguage)} Prose outside. Only named catalog props, no styling. $name = literal JSON; input value={$name}; Button action={@Set($name, literal)}, {@Reset($name)} or {@Reset()} changes local state only; braced expressions: @Count, @Filter(list,row,predicate), @Sum, @Join, @Round. Show/Each control children. Choices are shortcuts after finished work that the person may ignore. When your turn would end waiting on the person (a missing fact, a decision, a go-ahead for work you would otherwise do), ask with your own question tool if you have one, otherwise in prose, never with Choices. Choice labels and precise context stay visible and send once. Image: attachment or generated="latest", never URL/path. No code execution. State resets on reload. ${components}\nExample:\n${uiExample(fenceLanguage)}\n`;
+}
+
+/* One group as the reference writes it: its description and rules, then every component with its props. */
+export function uiGroupReference(group: UiGroupName): string {
+    const components = uiGroupComponents(group).map(([name, entry]) => {
+        const props = uiPropList(entry).join(', ');
+        return `${name}: ${entry.description}${props ? ` Props: ${props}.` : ''}`;
+    });
+    return [UI_GROUPS[group].description, UI_GROUPS[group].rules, ...components].join('\n');
 }
 
 export function uiReferenceText({ fenceLanguage = UI_FENCE_LANGUAGE }: UiTextOptions = {}): string {
-    const groups = Object.entries(UI_GROUPS)
-        .map(([group, definition]) => {
-            const components = Object.entries(UI_CATALOG)
-                .filter(([, entry]) => entry.group === group)
-                .map(([name, entry]) => {
-                    const props = uiPropList(entry).join(', ');
-                    return `${name}: ${entry.description}${props ? ` Props: ${props}.` : ''}`;
-                });
-            return [definition.description, definition.rules, ...components].join('\n');
-        })
-        .join('\n\n');
+    const groups = (Object.keys(UI_GROUPS) as UiGroupName[]).map(uiGroupReference).join('\n\n');
     return `${uiSyntax(fenceLanguage)}\nExample:\n${uiExample(fenceLanguage)}\n\n${groups}`;
 }