@intentface/ui 0.0.0-stage → 0.7.0

package/dist/attachments/attachments.js

@@ -0,0 +1,121 @@
+"use client";
+// Headless attachments: generic structural parts, accept matching, and the
+// platform-default ingestion (a blob URL that doubles as the id — the
+// browser-native way to reference a picked File; override via
+// Composer.Attachments' create/destroy for upload-to-storage etc.). Policy
+// (accepted types, counts, sizes), media taxonomy, send serialization, and copy
+// are the consumer's. Card visuals belong to the styled layer.
+import { useEffect, useState } from "react";
+import { createPortal } from "react-dom";
+import { useRenderElement } from "../internal/render/useRenderElement.js";
+// ---------------------------------------------------------------------------
+// Default ingestion — platform-native, no policy: a picked File becomes an
+// item referencing it by blob URL. Overridable per composer (create/destroy).
+// ---------------------------------------------------------------------------
+// Every createObjectURL call mints a fresh `blob:<origin>/<uuid>`, so the URL
+// is also a unique id — even for the same File added twice.
+export const toAttachmentItem = (file) => {
+    const url = URL.createObjectURL(file);
+    return { id: url, url, filename: file.name, mediaType: file.type, fileSize: file.size };
+};
+export const revokeAttachmentUrl = (item) => {
+    if (item.url?.startsWith("blob:")) {
+        URL.revokeObjectURL(item.url);
+    }
+};
+export const revokeAllAttachmentUrls = (items) => {
+    for (const item of items) {
+        revokeAttachmentUrl(item);
+    }
+};
+// ---------------------------------------------------------------------------
+// Accept matching — standard HTML `accept` semantics.
+// ---------------------------------------------------------------------------
+export const matchesAccept = (file, accept) => {
+    if (!accept || accept.trim() === "") {
+        return true;
+    }
+    const patterns = accept
+        .split(",")
+        .map((pattern) => pattern.trim())
+        .filter(Boolean);
+    return patterns.some((pattern) => {
+        if (pattern.endsWith("/*")) {
+            const prefix = pattern.slice(0, -1);
+            return file.type.startsWith(prefix);
+        }
+        return file.type === pattern;
+    });
+};
+/**
+ * The tray container. Mount it only when there are items to show; it renders
+ * no layout of its own.
+ * Renders a `<div>` element.
+ */
+export const AttachmentsRoot = ({ className, render, style, ...elementProps }) => useRenderElement("div", { className, render, style }, { props: [{ "data-attachments": "" }, elementProps] });
+// Generic structural slot for one attachment. It carries no media taxonomy —
+// categorization (image/pdf/file, icons, thumbnails) belongs to the styled
+// layer, which reads the item's raw mediaType however it wants.
+/**
+ * One attachment, as a structural slot with no media taxonomy of its own.
+ * Read the item's `mediaType` and decide what an image or a PDF looks like.
+ * Renders a `<div>` element.
+ */
+export const AttachmentsItem = ({ className, render, style, ...elementProps }) => useRenderElement("div", { className, render, style }, { props: [{ "data-attachments-item": "" }, elementProps] });
+/**
+ * The removal affordance. Named "Remove attachment" by default, or
+ * "Remove {filename}" when `filename` is set, so a row of them does not
+ * announce identically.
+ * Renders a `<button>` element.
+ */
+export const AttachmentsRemove = ({ onRemove, filename, className, render, style, ...elementProps }) => useRenderElement("button", { className, render, style }, {
+    props: [
+        {
+            "aria-label": filename ? `Remove ${filename}` : "Remove attachment",
+            "data-attachments-remove": "",
+            onClick: onRemove,
+        },
+        elementProps,
+    ],
+});
+/**
+ * The drop overlay. `portalSelector` only moves where it renders (e.g. over an
+ * app shell region); where files can be dropped is `Composer.Attachments`'
+ * `globalDrop`, not this part.
+ * Renders a `<div>` element.
+ */
+export const AttachmentsDropzone = ({ visible = false, keepMounted = false, portalSelector, children, className, render, style, ...elementProps }) => {
+    const [portalTarget, setPortalTarget] = useState(null);
+    useEffect(() => {
+        if (!portalSelector)
+            return;
+        setPortalTarget(document.querySelector(portalSelector));
+    }, [portalSelector]);
+    const content = useRenderElement("div", { className, render, style }, {
+        enabled: visible || keepMounted,
+        state: { visible },
+        props: [{ "data-attachments-dropzone": "", children }, elementProps],
+    });
+    if (!content)
+        return null;
+    if (portalTarget)
+        return createPortal(content, portalTarget);
+    return content;
+};
+// role="alert" (assertive): a rejected pick/drop is a user-action failure that
+// should announce immediately. The copy inside stays the consumer's.
+/**
+ * The validation slot, as a live region: whatever appears inside announces
+ * immediately. Validation emits a code, never copy, so the message is yours.
+ * Renders a `<span>` element with `role="alert"`.
+ */
+export const AttachmentsError = ({ className, render, style, ...elementProps }) => useRenderElement("span", { className, render, style }, { props: [{ role: "alert", "data-attachments-error": "" }, elementProps] });
+/**
+ * The file-picker button, named "Add attachment" by default. The package owns
+ * no file input; wire this to your own.
+ * Renders a `<button>` element.
+ */
+export const AttachmentsTrigger = ({ className, render, style, ...elementProps }) => useRenderElement("button", { className, render, style }, {
+    // Default overridable name — the trigger is typically icon-only.
+    props: [{ "aria-label": "Add attachment", "data-attachments-trigger": "" }, elementProps],
+});

package/dist/attachments/index.d.ts

@@ -0,0 +1,3 @@
+export type { AttachmentErrorCode, AttachmentItem, AttachmentsDropzoneProps, AttachmentsDropzoneState, AttachmentsErrorProps, AttachmentsItemProps, AttachmentsRemoveProps, AttachmentsRootProps, AttachmentsTriggerProps, } from "./attachments.js";
+export { matchesAccept, revokeAllAttachmentUrls, revokeAttachmentUrl, toAttachmentItem, } from "./attachments.js";
+export * as Attachments from "./index.parts.js";

package/dist/attachments/index.js

@@ -0,0 +1,3 @@
+// Public surface of @intentface/ui/attachments. No directive — see index.parts.ts.
+export { matchesAccept, revokeAllAttachmentUrls, revokeAttachmentUrl, toAttachmentItem, } from "./attachments.js";
+export * as Attachments from "./index.parts.js";

package/dist/attachments/index.parts.d.ts

@@ -0,0 +1 @@
+export { AttachmentsDropzone as Dropzone, AttachmentsError as Error, AttachmentsItem as Item, AttachmentsRemove as Remove, AttachmentsRoot as Root, AttachmentsTrigger as Trigger, } from "./attachments.js";

package/dist/attachments/index.parts.js

@@ -0,0 +1,5 @@
+// Part names for the `Attachments` namespace. Deliberately carries no
+// "use client" directive: this module and index.ts must stay server-resolvable
+// so a React Server Component can reach Attachments.Root and its siblings
+// through them. The directive lives one level down, on attachments.tsx.
+export { AttachmentsDropzone as Dropzone, AttachmentsError as Error, AttachmentsItem as Item, AttachmentsRemove as Remove, AttachmentsRoot as Root, AttachmentsTrigger as Trigger, } from "./attachments.js";

package/dist/chip/chip.d.ts

@@ -0,0 +1,45 @@
+import { type ReactElement, type ReactNode } from "react";
+import type { PrimitiveProps } from "../internal/primitive-props.js";
+type ChipPreviewProps = {
+    children: ReactNode;
+};
+/**
+ * Marker child whose content becomes the preview body. Renders nothing inline:
+ * `Chip.Root` inspects its children and routes this through
+ * `renderWithPreview`, so the package never owns a popup.
+ */
+export declare const ChipPreview: (_props: ChipPreviewProps) => ReactNode;
+export type ChipState = {
+    /** Opaque styling hook, surfaced as data-variant. */
+    variant: string | undefined;
+};
+export type ChipRootProps = PrimitiveProps<"span", ChipState> & {
+    variant?: string;
+    /**
+     * Called when a Chip.Preview child is present. Receives the rendered badge
+     * element and the preview content; compose your popup of choice around
+     * them. Without it, the preview content is ignored.
+     */
+    renderWithPreview?: (badge: ReactElement, preview: ReactNode) => ReactNode;
+};
+/**
+ * The inline token surface. Flows with the surrounding text rather than
+ * breaking the line box, and lifts a `Chip.Preview` child into whatever
+ * surface `renderWithPreview` builds.
+ * Renders a `<span>` element.
+ */
+export declare const ChipRoot: ({ variant, renderWithPreview, className, render, style, children, ...elementProps }: ChipRootProps) => string | number | bigint | boolean | ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | Iterable<ReactNode> | Promise<string | number | bigint | boolean | import("react").ReactPortal | ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | Iterable<ReactNode> | null | undefined> | null | undefined;
+export type ChipIconProps = PrimitiveProps<"span">;
+/**
+ * Leading inline icon, baseline-aligned to the label and `aria-hidden`, so
+ * decoration stays out of the chip's accessible name.
+ * Renders a `<span>` element.
+ */
+export declare const ChipIcon: ({ className, render, style, ...elementProps }: ChipIconProps) => ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;
+export type ChipLabelProps = PrimitiveProps<"span">;
+/**
+ * The chip's text, which reads as part of the sentence around it.
+ * Renders a `<span>` element.
+ */
+export declare const ChipLabel: ({ className, render, style, ...elementProps }: ChipLabelProps) => ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;
+export {};

package/dist/chip/chip.js

@@ -0,0 +1,43 @@
+"use client";
+// Headless inline chip. Renders an unstyled <span> flow-surface with
+// data-variant for styling hooks. Popups are not owned by this layer: a
+// Chip.Preview child is captured and handed to `renderWithPreview` so the
+// styled layer can compose its own hover-card/popover around the badge.
+// Every part supports the Base UI render prop.
+import { Children, isValidElement } from "react";
+import { useRenderElement } from "../internal/render/useRenderElement.js";
+/**
+ * Marker child whose content becomes the preview body. Renders nothing inline:
+ * `Chip.Root` inspects its children and routes this through
+ * `renderWithPreview`, so the package never owns a popup.
+ */
+export const ChipPreview = (_props) => null;
+/**
+ * The inline token surface. Flows with the surrounding text rather than
+ * breaking the line box, and lifts a `Chip.Preview` child into whatever
+ * surface `renderWithPreview` builds.
+ * Renders a `<span>` element.
+ */
+export const ChipRoot = ({ variant, renderWithPreview, className, render, style, children, ...elementProps }) => {
+    const childArray = Children.toArray(children);
+    const previewChild = childArray.find((child) => isValidElement(child) && child.type === ChipPreview);
+    const inlineChildren = childArray.filter((child) => !isValidElement(child) || child.type !== ChipPreview);
+    const badge = useRenderElement("span", { className, render, style }, {
+        state: { variant },
+        props: [{ "data-chip": "", children: inlineChildren }, elementProps],
+    });
+    if (!previewChild || !renderWithPreview)
+        return badge;
+    return renderWithPreview(badge, previewChild.props.children);
+};
+/**
+ * Leading inline icon, baseline-aligned to the label and `aria-hidden`, so
+ * decoration stays out of the chip's accessible name.
+ * Renders a `<span>` element.
+ */
+export const ChipIcon = ({ className, render, style, ...elementProps }) => useRenderElement("span", { className, render, style }, { props: [{ "aria-hidden": true, "data-chip-icon": "" }, elementProps] });
+/**
+ * The chip's text, which reads as part of the sentence around it.
+ * Renders a `<span>` element.
+ */
+export const ChipLabel = ({ className, render, style, ...elementProps }) => useRenderElement("span", { className, render, style }, { props: [{ "data-chip-label": "" }, elementProps] });

package/dist/chip/index.d.ts

@@ -0,0 +1,2 @@
+export type { ChipIconProps, ChipLabelProps, ChipRootProps, ChipState } from "./chip.js";
+export * as Chip from "./index.parts.js";

package/dist/chip/index.js

@@ -0,0 +1,2 @@
+// Public surface of @intentface/ui/chip. No "use client" — see index.parts.ts.
+export * as Chip from "./index.parts.js";

package/dist/chip/index.parts.d.ts

@@ -0,0 +1 @@
+export { ChipIcon as Icon, ChipLabel as Label, ChipPreview as Preview, ChipRoot as Root, } from "./chip.js";

package/dist/chip/index.parts.js

@@ -0,0 +1,5 @@
+// Part names for the `Chip` namespace. Deliberately carries no "use client":
+// this module and index.ts must stay server-resolvable so a React Server
+// Component can reach Chip.Root / Chip.Label through them. The directive lives
+// one level down, on chip.tsx.
+export { ChipIcon as Icon, ChipLabel as Label, ChipPreview as Preview, ChipRoot as Root, } from "./chip.js";

package/dist/chip-markdown.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Opaque wire string. The styled layer owns the concrete union and narrows
+ * at its own boundary.
+ */
+export type ChipIconKey = string;
+export declare const CHIP_REF_PATTERN: RegExp;
+export type ChipData = {
+    prefix: string;
+    value: string;
+    label: string;
+    icon?: ChipIconKey;
+};
+export type ChipSegment = {
+    type: "text";
+    text: string;
+} | {
+    type: "chip";
+    label: string;
+    prefix: string;
+    value: string;
+    icon?: ChipIconKey;
+};
+export declare const escapeMarkdownLink: (input: string) => string;
+export declare const encodeChipMarkdown: (chip: ChipData) => string;
+export declare const parseChipSegments: (text: string) => ChipSegment[];

package/dist/chip-markdown.js

@@ -0,0 +1,54 @@
+// Wire format for inline chip references inside a message text part.
+// Shape: [Label](chip:prefix:value?icon=…). The icon rides along in the
+// token, so a rendered message reconstructs the chip from its own text
+// alone — no sidecar metadata array. Presentation that's derivable at render
+// time (e.g. a per-prefix variant) is the renderer's job, not wire data.
+// Every class excludes "[" so no group can consume past the next one — without
+// that this backtracks quadratically, and message text is untrusted.
+export const CHIP_REF_PATTERN = /\[([^[\]]+)\]\(chip:([^[:)]+):([^[)?]+)(?:\?([^[)]*))?\)/g;
+export const escapeMarkdownLink = (input) => input.replace(/[[\]()\\]/g, (match) => `\\${match}`);
+// Tolerate legacy/un-encoded values — a stray "%" would otherwise throw and
+// take the whole message render down with it.
+const safeDecode = (value) => {
+    try {
+        return decodeURIComponent(value);
+    }
+    catch {
+        return value;
+    }
+};
+export const encodeChipMarkdown = (chip) => {
+    const params = new URLSearchParams();
+    if (chip.icon)
+        params.set("icon", chip.icon);
+    const query = params.toString();
+    const value = encodeURIComponent(chip.value);
+    return `[${escapeMarkdownLink(chip.label)}](chip:${chip.prefix}:${value}${query ? `?${query}` : ""})`;
+};
+export const parseChipSegments = (text) => {
+    const segments = [];
+    let lastIndex = 0;
+    for (const match of text.matchAll(CHIP_REF_PATTERN)) {
+        const start = match.index;
+        if (start > lastIndex) {
+            segments.push({ type: "text", text: text.slice(lastIndex, start) });
+        }
+        const [token, label = "", prefix = "", rawValue = "", rawQuery] = match;
+        const params = new URLSearchParams(rawQuery ?? "");
+        const icon = params.get("icon");
+        segments.push({
+            type: "chip",
+            label,
+            prefix,
+            value: safeDecode(rawValue),
+            ...(icon ? { icon } : {}),
+        });
+        lastIndex = start + token.length;
+    }
+    if (lastIndex < text.length) {
+        segments.push({ type: "text", text: text.slice(lastIndex) });
+    }
+    return segments;
+};
+// Building editor nodes from these segments lives with the document model in
+// composer/segments.ts — this module is only the neutral wire format.

package/dist/composer/actions.d.ts

@@ -0,0 +1,35 @@
+import type { PrimitiveProps } from "../internal/primitive-props.js";
+export type ComposerContextWindowState = {
+    /** Open (data-open) while the strip has content and no panel is active. */
+    open: boolean;
+};
+export type ComposerContextWindowProps = PrimitiveProps<"div", ComposerContextWindowState>;
+export declare const ComposerContextWindow: ({ children, className, render, style, ...elementProps }: ComposerContextWindowProps) => import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;
+export type ComposerActionsProps = PrimitiveProps<"div">;
+export declare const ComposerActions: ({ className, render, style, ...elementProps }: ComposerActionsProps) => import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;
+export type UseComposerSubmitOptions = {
+    isGenerating?: boolean;
+    onStop?: () => void;
+    disabled?: boolean;
+};
+export type ComposerSubmitState = {
+    /** "button" while generating (click stops), "submit" otherwise. */
+    type: "button" | "submit";
+    disabled: boolean;
+    isGenerating: boolean;
+};
+/**
+ * Send↔stop behavior: auto-disables while empty or submitting, flips the
+ * button type while generating, and aborts on Escape inside this composer
+ * (unless something closer — the command list — already handled it).
+ */
+export declare const useComposerSubmit: ({ isGenerating, onStop, disabled, }: UseComposerSubmitOptions) => ComposerSubmitState;
+export type ComposerSubmitButtonState = {
+    /** Present as data-generating while the stop affordance is active. */
+    generating: boolean;
+};
+export type ComposerSubmitProps = PrimitiveProps<"button", ComposerSubmitButtonState> & {
+    isGenerating?: boolean;
+    onStop?: () => void;
+};
+export declare const ComposerSubmit: ({ disabled, isGenerating, onStop, onClick, className, render, style, ...elementProps }: ComposerSubmitProps) => import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;

package/dist/composer/actions.js

@@ -0,0 +1,76 @@
+"use client";
+// Composer.ContextWindow / Actions / Submit. ContextWindow is content-driven
+// like the panels — open (data-open / data-closed) while it has content and no
+// panel is active, yielding to an active panel. Submit owns the send↔stop
+// behavior via useComposerSubmit and renders a plain button — the styled layer
+// applies the same hook to its own button component.
+import { Children, useEffect } from "react";
+import { useRenderElement } from "../internal/render/useRenderElement.js";
+import { openStateMapping } from "../internal/state-mappings.js";
+import { useAsRef } from "./internals.js";
+import { useComposer, useComposerContextStore } from "./store.js";
+export const ComposerContextWindow = ({ children, className, render, style, ...elementProps }) => {
+    // Yield while any native panel is active — the strip slides back out once they
+    // close. (Union of the native slices; no central registry.)
+    const anyPanelActive = useComposer((composer) => composer.commands.active || composer.askUser.active);
+    const hasContent = Children.toArray(children).length > 0;
+    const open = hasContent && !anyPanelActive;
+    return useRenderElement("div", { className, render, style }, {
+        state: { open },
+        stateAttributesMapping: openStateMapping,
+        props: [{ "data-composer-context-window": "", children }, elementProps],
+    });
+};
+export const ComposerActions = ({ className, render, style, ...elementProps }) => useRenderElement("div", { className, render, style }, { props: [{ "data-composer-actions": "" }, elementProps] });
+/**
+ * Send↔stop behavior: auto-disables while empty or submitting, flips the
+ * button type while generating, and aborts on Escape inside this composer
+ * (unless something closer — the command list — already handled it).
+ */
+export const useComposerSubmit = ({ isGenerating = false, onStop, disabled, }) => {
+    const hasContent = useComposer((composer) => composer.textarea.hasContent);
+    const isSubmitting = useComposer((composer) => composer.isSubmitting);
+    const attachments = useComposer((composer) => composer.attachments);
+    // While generating, hand the stop to Composer.Root, which calls it on Escape.
+    const store = useComposerContextStore();
+    const onStopRef = useAsRef(onStop);
+    // Without an onStop there is nothing to stop, so Escape stays free for surfaces around it.
+    const hasOnStop = onStop !== undefined;
+    useEffect(() => {
+        if (!isGenerating || !hasOnStop)
+            return;
+        const stopGenerating = () => onStopRef.current?.();
+        store.stopGeneratingRef.current = stopGenerating;
+        return () => {
+            if (store.stopGeneratingRef.current !== stopGenerating)
+                return;
+            store.stopGeneratingRef.current = null;
+        };
+    }, [isGenerating, hasOnStop, store]);
+    const autoDisabled = disabled ?? ((!hasContent && attachments.items.length === 0) || isSubmitting);
+    return {
+        type: isGenerating ? "button" : "submit",
+        disabled: isGenerating ? false : autoDisabled,
+        isGenerating,
+    };
+};
+export const ComposerSubmit = ({ disabled, isGenerating = false, onStop, onClick, className, render, style, ...elementProps }) => {
+    const submit = useComposerSubmit({ isGenerating, onStop, disabled });
+    return useRenderElement("button", { className, render, style }, {
+        state: { generating: isGenerating },
+        props: [
+            {
+                type: submit.type,
+                "data-composer-submit": "",
+                // Default overridable names for the (typically icon-only) morphing
+                // control — both states announce, not just the stop affordance.
+                "aria-label": isGenerating ? "Stop generating" : "Send message",
+                disabled: submit.disabled,
+                // Replaces (not chains) the consumer's onClick while generating —
+                // a stop click must never fall through to submit handlers.
+                onClick: isGenerating ? () => onStop?.() : onClick,
+            },
+            elementProps,
+        ],
+    });
+};

package/dist/composer/ask-user-machine.d.ts

@@ -0,0 +1,52 @@
+import type { AskUserQuestion, ComposerAnswerEntry } from "./types.js";
+export type AnswerEntry = {
+    selected: Set<string>;
+    freeText: string;
+};
+export type AskUserState = {
+    step: number;
+    answers: Map<number, AnswerEntry>;
+};
+export declare const INITIAL_ASK_USER_STATE: AskUserState;
+export type AskUserEffect = {
+    type: "clear-input";
+} | {
+    type: "set-input-text";
+    text: string;
+} | {
+    type: "focus-input";
+} | {
+    type: "focus-options";
+} | {
+    type: "reset-highlight";
+} | {
+    type: "submit-answers";
+    answers: ComposerAnswerEntry[];
+};
+export type AskUserAction = {
+    type: "toggle-option";
+    label: string;
+} | {
+    type: "select-option";
+    label: string;
+} | {
+    type: "clear-selections";
+} | {
+    type: "continue-step";
+    freeText: string;
+} | {
+    type: "dismiss-step";
+} | {
+    type: "step-back";
+    currentText: string;
+} | {
+    type: "step-forward";
+    currentText: string;
+};
+export type AskUserTransition = {
+    next: AskUserState;
+    effects: AskUserEffect[];
+};
+export declare const compileAnswers: (state: AskUserState, questions: AskUserQuestion[]) => ComposerAnswerEntry[];
+export declare const isLastStep: (state: AskUserState, questions: AskUserQuestion[]) => boolean;
+export declare const transitionAskUser: (state: AskUserState, questions: AskUserQuestion[], action: AskUserAction) => AskUserTransition;

package/dist/composer/ask-user-machine.js

@@ -0,0 +1,164 @@
+// Ask-user — pure state machine for the questionnaire flow. State is a current
+// step plus a map of per-step answers; every transition is an immutable map
+// operation, so the store only owns the state cell and the effect execution.
+export const INITIAL_ASK_USER_STATE = {
+    step: 0,
+    answers: new Map(),
+};
+// ---------------------------------------------------------------------------
+// Answer helpers — immutable operations on the per-step answer map, plus the
+// projection/query the store reads.
+// ---------------------------------------------------------------------------
+const emptyEntry = () => ({
+    selected: new Set(),
+    freeText: "",
+});
+const cloneAnswers = (source) => new Map(source);
+// Record `text` as the step's free-text answer. Single-select treats text and
+// a chosen option as mutually exclusive, so any selection is dropped;
+// multi-select keeps existing selections alongside the text. Empty text is a
+// no-op (returns an untouched clone).
+const writeFreeText = (answers, step, text, multiSelect) => {
+    const next = cloneAnswers(answers);
+    if (text.length === 0)
+        return next;
+    const previous = next.get(step) ?? emptyEntry();
+    next.set(step, {
+        selected: multiSelect ? previous.selected : new Set(),
+        freeText: text,
+    });
+    return next;
+};
+// Remove the step's entry entirely (skip / dismiss).
+const skipStep = (answers, step) => {
+    const next = cloneAnswers(answers);
+    next.delete(step);
+    return next;
+};
+// Toggle an option on the step's entry. Multi-select toggles membership and
+// keeps free text; single-select replaces both (option and text are mutually
+// exclusive).
+const toggleAnswer = (answers, step, label, multiSelect) => {
+    const next = cloneAnswers(answers);
+    const previous = next.get(step) ?? emptyEntry();
+    const selected = new Set(previous.selected);
+    if (multiSelect) {
+        if (selected.has(label))
+            selected.delete(label);
+        else
+            selected.add(label);
+    }
+    else {
+        selected.clear();
+        selected.add(label);
+    }
+    next.set(step, { selected, freeText: multiSelect ? previous.freeText : "" });
+    return next;
+};
+// Project the collected answers onto the public ComposerAnswerEntry union, one
+// entry per question in order. The chosen branch encodes the invariant:
+// single-select carries `option` *or* `text`; multi-select carries both;
+// an unanswered question is bare `{ question }`.
+export const compileAnswers = (state, questions) => questions.map(({ question, multiSelect }, index) => {
+    const entry = state.answers.get(index);
+    if (!entry)
+        return { question };
+    const selected = [...entry.selected];
+    const text = entry.freeText.trim();
+    if (multiSelect) {
+        if (selected.length === 0 && text === "")
+            return { question };
+        return { question, options: selected, text };
+    }
+    const firstSelected = selected[0];
+    if (firstSelected !== undefined)
+        return { question, option: firstSelected };
+    if (text !== "")
+        return { question, text };
+    return { question };
+});
+export const isLastStep = (state, questions) => state.step >= questions.length - 1;
+// ---------------------------------------------------------------------------
+// Transitions — the decide half of the flow: map an action onto the next state
+// plus the effects to run. transitionAskUser is the single entry point.
+// ---------------------------------------------------------------------------
+// Commit `nextAnswers`, advance one step, and reset the input — then either
+// arm the next question (blurred, highlight reset) or compile and submit on
+// the last step (input focused for the follow-up message).
+const advanceStep = (state, questions, nextAnswers) => {
+    const next = { step: state.step + 1, answers: nextAnswers };
+    if (state.step < questions.length - 1) {
+        return {
+            next,
+            effects: [{ type: "clear-input" }, { type: "reset-highlight" }, { type: "focus-options" }],
+        };
+    }
+    return {
+        next,
+        effects: [
+            { type: "clear-input" },
+            { type: "submit-answers", answers: compileAnswers(next, questions) },
+            { type: "focus-input" },
+        ],
+    };
+};
+// Navigate to `targetStep`, preserving any in-progress free text on the step
+// being left and restoring the target step's saved text into the input.
+const transitionToStep = (state, targetStep, currentText) => {
+    if (targetStep === state.step)
+        return { next: state, effects: [] };
+    const trimmed = currentText.trim();
+    const answers = cloneAnswers(state.answers);
+    if (trimmed.length > 0) {
+        const previous = answers.get(state.step) ?? emptyEntry();
+        answers.set(state.step, { ...previous, freeText: trimmed });
+    }
+    const next = { step: targetStep, answers };
+    return {
+        next,
+        effects: [
+            { type: "set-input-text", text: answers.get(targetStep)?.freeText ?? "" },
+            { type: "reset-highlight" },
+            { type: "focus-options" },
+        ],
+    };
+};
+// The decide half of the ask-user flow, mirroring interpretAskUserKey: map an
+// action onto the next state plus the effects to run. Composed actions
+// (select-option = toggle + advance) resolve atomically here, so no caller
+// ever chains transitions across a stale state snapshot.
+export const transitionAskUser = (state, questions, action) => {
+    const multiSelect = !!questions[state.step]?.multiSelect;
+    switch (action.type) {
+        case "toggle-option":
+            return {
+                next: {
+                    ...state,
+                    answers: toggleAnswer(state.answers, state.step, action.label, multiSelect),
+                },
+                effects: multiSelect ? [] : [{ type: "clear-input" }],
+            };
+        case "select-option": {
+            const toggled = toggleAnswer(state.answers, state.step, action.label, multiSelect);
+            if (multiSelect)
+                return { next: { ...state, answers: toggled }, effects: [] };
+            return advanceStep(state, questions, toggled);
+        }
+        case "clear-selections": {
+            const previous = state.answers.get(state.step);
+            if (!previous || previous.selected.size === 0)
+                return { next: state, effects: [] };
+            const answers = cloneAnswers(state.answers);
+            answers.set(state.step, { selected: new Set(), freeText: previous.freeText });
+            return { next: { ...state, answers }, effects: [] };
+        }
+        case "continue-step":
+            return advanceStep(state, questions, writeFreeText(state.answers, state.step, action.freeText.trim(), multiSelect));
+        case "dismiss-step":
+            return advanceStep(state, questions, skipStep(state.answers, state.step));
+        case "step-back":
+            return transitionToStep(state, Math.max(0, state.step - 1), action.currentText);
+        case "step-forward":
+            return transitionToStep(state, Math.min(questions.length - 1, state.step + 1), action.currentText);
+    }
+};