@sigrun/tui 0.1.0 → 0.1.1

package/dist/blocks/ext-transport.js

@@ -0,0 +1,165 @@
+/**
+ * The TUI's extension-surface transport (UI-blocks U3 Task 5): implements
+ * the shared `SurfaceTransport` contract over the U3 routes (spec §7.2)
+ * as the TUI's remote client. One transport = one surface instance
+ * (slug + id + params); the wire `k` (hashed instance key) keys the
+ * change-event routing in {@link ExtSurfaceHub}.
+ *
+ * Like the webui twin, every fetch carries `X-Sigrun-Stream` once the
+ * launcher hands the stream id in (the watcher entry's stream);
+ * `image()` rejects until U7 ships the route. The channel owns
+ * refreshMs cadence, the keepalive, and visibility gating (U2).
+ */
+import { createHash } from "node:crypto";
+import { instanceKey } from "@sigrun/shared/blocks";
+import { SigrunApiError } from "../api.js";
+/**
+ * The wire `k` for one surface instance (spec §7.3), Node flavor:
+ * `sha256(slug + "\0" + id + "\0" + key)` hex. The TUI's transport
+ * computes it synchronously (the WebCrypto twin in `@sigrun/shared/
+ * blocks` is async — DOM-only).
+ */
+export function surfaceKeyHash(slug, id, key) {
+    return createHash("sha256")
+        .update([slug, id, key].join("\u0000"))
+        .digest("hex");
+}
+/** The instance key for one transport's params (the default rule). */
+export function transportKey(options) {
+    return instanceKey(options.params ?? {});
+}
+/** The base path for one surface instance (`?params=` omitted when `{}`). */
+function surfacePath(options) {
+    const base = `/v1/ext/${encodeURIComponent(options.slug)}/surfaces/${encodeURIComponent(options.id)}`;
+    if (options.params === undefined || Object.keys(options.params).length === 0) {
+        return base;
+    }
+    return `${base}?params=${encodeURIComponent(JSON.stringify(options.params))}`;
+}
+function withQuery(path, key, value) {
+    return `${path}${path.includes("?") ? "&" : "?"}${key}=${value}`;
+}
+/** Create the TUI's extension-surface transport. */
+export function createExtSurfaceTransport(options) {
+    const doFetch = options.fetch ??
+        ((input, init) => globalThis.fetch(input, init));
+    const baseUrl = options.baseUrl.replace(/\/+$/, "");
+    const listeners = new Set();
+    // Mutable: a reconnect's new stream id lands via setStreamId — every
+    // fetch resolves the header at CALL time.
+    let streamId = options.streamId;
+    const headers = () => ({
+        accept: "application/json",
+        ...(options.user === undefined || options.user.trim() === ""
+            ? {}
+            : { "x-sigrun-user": options.user.trim() }),
+        ...(options.token === undefined || options.token.trim() === ""
+            ? {}
+            : { authorization: `Bearer ${options.token.trim()}` }),
+        ...(streamId === undefined
+            ? {}
+            : { "x-sigrun-stream": streamId }),
+    });
+    const get = async (path) => {
+        const response = await doFetch(`${baseUrl}${path}`, {
+            method: "GET",
+            headers: headers(),
+        });
+        if (!response.ok) {
+            throw new SigrunApiError("GET", path, response.status, await response.json().catch(() => undefined));
+        }
+        return (await response.json());
+    };
+    const transport = {
+        load() {
+            return get(surfacePath(options));
+        },
+        fetchData(since) {
+            const path = `${surfacePath(options)}/data`;
+            return get(since === undefined ? path : withQuery(path, "since", String(since)));
+        },
+        async act(body) {
+            const response = await doFetch(`${baseUrl}${surfacePath(options)}/actions`, {
+                method: "POST",
+                headers: { ...headers(), "content-type": "application/json" },
+                body: JSON.stringify({ ...body, params: options.params ?? {} }),
+            });
+            return (await response.json());
+        },
+        async upload(body) {
+            const base = surfacePath(options);
+            const path = withQuery(`${baseUrl}${base}/uploads/${encodeURIComponent(body.field)}/${encodeURIComponent(body.name)}`, "params", encodeURIComponent(JSON.stringify(options.params ?? {})));
+            const response = await doFetch(path, {
+                method: "PUT",
+                headers: { ...headers(), "content-type": "application/octet-stream" },
+                // SAFETY: Node's fetch types Uint8Array<ArrayBuffer> narrower
+                // than the Uint8Array<ArrayBufferLike> the wire body carries;
+                // the runtime accepts any ArrayBuffer view.
+                body: body.bytes,
+            });
+            return (await response.json());
+        },
+        image() {
+            return Promise.reject(new Error("ext surface image route ships with U7"));
+        },
+        onChanged(listener) {
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+    };
+    return {
+        transport,
+        setStreamId(next) {
+            streamId = next;
+        },
+    };
+}
+/**
+ * The change-event router (the launcher's dispatch seam): `attach`
+ * creates a transport whose `onChanged` subscribes into the hub under
+ * the instance's (slug, id, k); `dispatch` fans a `surface.changed`
+ * event out to the matching subscriptions only.
+ */
+export class ExtSurfaceHub {
+    #subscriptions = new Set();
+    /** Create a transport whose `onChanged` subscribes into this hub. */
+    attach(options, keyHash) {
+        const base = createExtSurfaceTransport(options);
+        const hub = this;
+        const transport = {
+            load: () => base.transport.load(),
+            fetchData: (since) => base.transport.fetchData(since),
+            act: (body) => base.transport.act(body),
+            upload: (body) => base.transport.upload(body),
+            image: (src, opts) => base.transport.image(src, opts),
+            onChanged(listener) {
+                const subscription = {
+                    slug: options.slug,
+                    id: options.id,
+                    keyHash,
+                    listener,
+                };
+                hub.#subscriptions.add(subscription);
+                return () => {
+                    hub.#subscriptions.delete(subscription);
+                };
+            },
+        };
+        return {
+            transport,
+            setStreamId: (next) => base.setStreamId(next),
+        };
+    }
+    /** Fire every subscription matching the event's (slug, id, k). */
+    dispatch(event) {
+        for (const subscription of this.#subscriptions) {
+            if (subscription.slug === event.slug &&
+                subscription.id === event.id &&
+                subscription.keyHash === event.k) {
+                subscription.listener({ rev: event.rev, treeRev: event.treeRev });
+            }
+        }
+    }
+}

package/dist/blocks/form/choice.d.ts

@@ -0,0 +1,54 @@
+/**
+ * The choice field (UI-blocks U2 Task 5, spec §5.6 — the port of U1's
+ * `ChoiceField.tsx` value rules): single value = the selected id; multi
+ * = the ids; `allowOther` adds a free-text row whose value is
+ * `{other: text}` (single) or the ids plus `{other: text}` as the last
+ * element (multi). The TUI shows the focused option's `preview`
+ * markdown BELOW the options (§5.6's TUI note) at every width. An
+ * `allowOther` field appends a final "Type something" row; typing on it
+ * edits the free text.
+ *
+ * v1 degradation note: `preview` renders via wrapPlain (plain wrapped
+ * text), not the markdown renderer — the preview stays one small
+ * dim block under the options.
+ */
+import type { ChoiceField, ChoiceOption, JsonValue } from "@sigrun/shared/blocks";
+import { type BlockCtx } from "../context.js";
+import { EditBuffer } from "./fields.js";
+/** The `allowOther` row label (spec §5.6; overridable via its label). */
+export declare const OTHER_ROW_DEFAULT = "Type something";
+/** The selected id list of a multi value (strings only — a trailing
+ *  `{other}` object is not an id). */
+export declare function optionIdList(value: JsonValue): readonly string[];
+/** The free text of an `{other}` value (single) or a trailing `{other}`
+ *  element (multi). */
+export declare function otherText(value: JsonValue): string;
+/** Resolve the option list (literal or binding). */
+export declare function choiceOptions(field: ChoiceField, ctx: BlockCtx): readonly ChoiceOption[];
+/** The per-field choice state: the option cursor and the other-text
+ *  editor (value round-trips through the owning form's values). */
+export declare class ChoiceState {
+    cursor: number;
+    other: EditBuffer;
+}
+/** The number of rows a choice renders: options plus the other row. */
+export declare function choiceRowCount(field: ChoiceField, ctx: BlockCtx): number;
+/** Render the option rows plus the preview of the focused option. */
+export declare function choiceLines(opts: {
+    field: ChoiceField;
+    ctx: BlockCtx;
+    width: number;
+    value: JsonValue;
+    state: ChoiceState;
+    focused: boolean;
+}): string[];
+/** The choice value after pressing Enter/Space on `row` (the option
+ *  cursor). Returns the next value, or `undefined` when the row is the
+ *  other row (text typing handles it) or nothing changed. */
+export declare function choiceActivate(field: ChoiceField, ctx: BlockCtx, value: JsonValue, row: number): JsonValue | undefined;
+/** The choice value after the other text changed (empty text clears). */
+export declare function choiceSetOther(field: ChoiceField, value: JsonValue, textValue: string): JsonValue;
+/** The review-line text of a choice value (the stepper's review step). */
+export declare function choiceValueText(field: ChoiceField, ctx: BlockCtx, value: JsonValue): string;
+/** Keep the cursor inside the row count. */
+export declare function clampChoiceCursor(field: ChoiceField, ctx: BlockCtx, state: ChoiceState): void;

package/dist/blocks/form/choice.js

@@ -0,0 +1,175 @@
+/**
+ * The choice field (UI-blocks U2 Task 5, spec §5.6 — the port of U1's
+ * `ChoiceField.tsx` value rules): single value = the selected id; multi
+ * = the ids; `allowOther` adds a free-text row whose value is
+ * `{other: text}` (single) or the ids plus `{other: text}` as the last
+ * element (multi). The TUI shows the focused option's `preview`
+ * markdown BELOW the options (§5.6's TUI note) at every width. An
+ * `allowOther` field appends a final "Type something" row; typing on it
+ * edits the free text.
+ *
+ * v1 degradation note: `preview` renders via wrapPlain (plain wrapped
+ * text), not the markdown renderer — the preview stays one small
+ * dim block under the options.
+ */
+import { bindRaw } from "../context.js";
+import { truncate, wrapPlain } from "../width.js";
+import { EditBuffer } from "./fields.js";
+/** The `allowOther` row label (spec §5.6; overridable via its label). */
+export const OTHER_ROW_DEFAULT = "Type something";
+/** The selected id list of a multi value (strings only — a trailing
+ *  `{other}` object is not an id). */
+export function optionIdList(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.filter((entry) => typeof entry === "string");
+}
+/** The free text of an `{other}` value (single) or a trailing `{other}`
+ *  element (multi). */
+export function otherText(value) {
+    if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+        const other = value.other;
+        if (typeof other === "string")
+            return other;
+    }
+    if (Array.isArray(value)) {
+        const last = value[value.length - 1];
+        if (typeof last === "object" && last !== null && !Array.isArray(last)) {
+            const other = last.other;
+            if (typeof other === "string")
+                return other;
+        }
+    }
+    return "";
+}
+/** Resolve the option list (literal or binding). */
+export function choiceOptions(field, ctx) {
+    const resolved = bindRaw(field.options, ctx);
+    if (!Array.isArray(resolved))
+        return [];
+    // The wire contract (§5.6) declares ChoiceOption entries; a malformed
+    // entry renders as its raw label text, never a throw.
+    return resolved;
+}
+/** The per-field choice state: the option cursor and the other-text
+ *  editor (value round-trips through the owning form's values). */
+export class ChoiceState {
+    cursor = 0;
+    other = new EditBuffer("");
+}
+/** The number of rows a choice renders: options plus the other row. */
+export function choiceRowCount(field, ctx) {
+    return choiceOptions(field, ctx).length + (field.allowOther !== undefined ? 1 : 0);
+}
+/** Render the option rows plus the preview of the focused option. */
+export function choiceLines(opts) {
+    const { field, ctx, width, value, state, focused } = opts;
+    const options = choiceOptions(field, ctx);
+    const multi = field.multi === true;
+    const ids = optionIdList(value);
+    const other = otherText(value);
+    const singleSelected = typeof value === "string" ? value : "";
+    const singleOther = typeof value === "object" && value !== null && !Array.isArray(value);
+    const unicode = ctx.unicode;
+    const lines = [];
+    const radioOn = unicode ? "(*)" : "(*)";
+    const radioOff = "( )";
+    const checkOn = unicode ? "[x]" : "[x]";
+    const checkOff = "[ ]";
+    options.forEach((option, index) => {
+        const cursor = focused && index === state.cursor ? "> " : "  ";
+        const box = multi
+            ? ids.includes(option.id)
+                ? checkOn
+                : checkOff
+            : singleSelected === option.id
+                ? radioOn
+                : radioOff;
+        const label = bindRaw(option.label, ctx);
+        const text = typeof label === "string" ? label : option.id;
+        const recommended = option.recommended === true ? (unicode ? " ★" : " *") : "";
+        let line = `${cursor}${box} ${text}${recommended}`;
+        const description = bindRaw(option.description, ctx);
+        if (typeof description === "string" && description !== "") {
+            line += ctx.theme.dim(` — ${description}`);
+        }
+        lines.push(truncate(line, width));
+    });
+    if (field.allowOther !== undefined) {
+        const index = options.length;
+        const cursor = focused && index === state.cursor ? "> " : "  ";
+        const selected = multi ? other !== "" : singleOther;
+        const box = multi ? (selected ? checkOn : checkOff) : selected ? radioOn : radioOff;
+        const rowLabel = field.allowOther.label ?? OTHER_ROW_DEFAULT;
+        const typed = selected ? other : focused && index === state.cursor ? state.other.text : "";
+        lines.push(truncate(`${cursor}${box} ${rowLabel}: ${typed}`, width));
+    }
+    // Preview BELOW the options (§5.6's TUI note) while an option is focused.
+    const focusedOption = options[state.cursor];
+    if (focused && focusedOption?.preview !== undefined && focusedOption.preview !== "") {
+        for (const line of wrapPlain(focusedOption.preview, Math.max(1, width - 2))) {
+            lines.push(ctx.theme.dim(`  ${line}`));
+        }
+    }
+    return lines;
+}
+/** The choice value after pressing Enter/Space on `row` (the option
+ *  cursor). Returns the next value, or `undefined` when the row is the
+ *  other row (text typing handles it) or nothing changed. */
+export function choiceActivate(field, ctx, value, row) {
+    const options = choiceOptions(field, ctx);
+    const multi = field.multi === true;
+    if (row >= options.length)
+        return undefined; // the other row
+    const option = options[row];
+    if (option === undefined)
+        return undefined;
+    if (!multi)
+        return option.id;
+    const current = optionIdList(value);
+    const other = otherText(value);
+    const otherPart = other !== "" ? [{ other }] : [];
+    if (current.includes(option.id)) {
+        return [...current.filter((id) => id !== option.id), ...otherPart];
+    }
+    return [...current, option.id, ...otherPart];
+}
+/** The choice value after the other text changed (empty text clears). */
+export function choiceSetOther(field, value, textValue) {
+    const multi = field.multi === true;
+    if (!multi) {
+        return textValue === "" ? "" : { other: textValue };
+    }
+    const current = optionIdList(value);
+    return textValue.trim() === ""
+        ? [...current]
+        : [...current, { other: textValue }];
+}
+/** The review-line text of a choice value (the stepper's review step). */
+export function choiceValueText(field, ctx, value) {
+    const options = choiceOptions(field, ctx);
+    const labelOf = (id) => {
+        const option = options.find((candidate) => candidate.id === id);
+        const label = option === undefined ? undefined : bindRaw(option.label, ctx);
+        return typeof label === "string" && label !== "" ? label : id;
+    };
+    if (field.multi === true) {
+        const parts = optionIdList(value).map(labelOf);
+        const other = otherText(value);
+        if (other !== "")
+            parts.push(other);
+        return parts.join(", ");
+    }
+    if (typeof value === "string")
+        return value === "" ? "" : labelOf(value);
+    const other = otherText(value);
+    return other;
+}
+/** Keep the cursor inside the row count. */
+export function clampChoiceCursor(field, ctx, state) {
+    const count = choiceRowCount(field, ctx);
+    if (state.cursor >= count)
+        state.cursor = Math.max(0, count - 1);
+    if (state.cursor < 0)
+        state.cursor = 0;
+}

package/dist/blocks/form/fields.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Form field chrome (UI-blocks U2 Task 5, spec §5.6): the shared field
+ * row (label, value editor line, help, error) and the text editors the
+ * simple fields (text, number, date, datetime) drive. The TUI editor is
+ * a single editable line: characters insert at the caret, Backspace
+ * deletes, arrows move the caret; the caret marker is `▏` (ASCII `|`
+ * with ctx.unicode false).
+ *
+ * The field row renders labels BESIDE fields at regular/wide and ABOVE
+ * them at compact (spec §12.3's form row) — the row decides from the
+ * render width.
+ *
+ * Editing keys are spoken directly by the form component (it owns the
+ * focus and routes input); the app-level keymaps are untouched (their
+ * `surface`-focus keys govern collections, not text editing).
+ */
+import type { Bindable, Field, JsonValue } from "@sigrun/shared/blocks";
+import { type BlockCtx } from "../context.js";
+/** The caret marker (spec §10.2's degradation rule). */
+export declare function caretGlyph(unicode: boolean): string;
+/** The width the label column takes at regular/wide (labels beside). */
+export declare const LABEL_CELLS = 20;
+/**
+ * A single-line text editor buffer: the value plus the caret. Shared
+ * by every text-shaped field (text, number raw, date, datetime,
+ * longtext non-code, choice's other text, list item editors).
+ */
+export declare class EditBuffer {
+    #private;
+    constructor(initial: string);
+    get text(): string;
+    get caret(): number;
+    /** Handle one input chunk; returns true when the key was an edit. */
+    input(data: string): boolean;
+    /** The displayed line with the caret marker inserted. */
+    render(unicode?: boolean): string;
+}
+/** A field's label/help resolved to text. */
+export declare function fieldLabel(field: Field, ctx: BlockCtx): string;
+/** The value's display text (the editor seed; numbers stringify). */
+export declare function valueText(value: JsonValue): string;
+/** Render a bindable to text (labels, help). */
+export declare function text(value: Bindable<string> | undefined, ctx: BlockCtx): string;
+/**
+ * The field-row chrome: label (beside at regular/wide, above at
+ * compact), the editor lines, then help and the error (client or the
+ * server field error, §5.6) under the field.
+ */
+export declare function fieldRowLines(opts: {
+    field: Field;
+    ctx: BlockCtx;
+    width: number;
+    /** The editor lines (the focused field's editor shows the caret). */
+    editor: readonly string[];
+    error?: string;
+}): string[];

package/dist/blocks/form/fields.js

@@ -0,0 +1,136 @@
+/**
+ * Form field chrome (UI-blocks U2 Task 5, spec §5.6): the shared field
+ * row (label, value editor line, help, error) and the text editors the
+ * simple fields (text, number, date, datetime) drive. The TUI editor is
+ * a single editable line: characters insert at the caret, Backspace
+ * deletes, arrows move the caret; the caret marker is `▏` (ASCII `|`
+ * with ctx.unicode false).
+ *
+ * The field row renders labels BESIDE fields at regular/wide and ABOVE
+ * them at compact (spec §12.3's form row) — the row decides from the
+ * render width.
+ *
+ * Editing keys are spoken directly by the form component (it owns the
+ * focus and routes input); the app-level keymaps are untouched (their
+ * `surface`-focus keys govern collections, not text editing).
+ */
+import { bindText } from "../context.js";
+import { truncate, widthClassOf, wrapPlain } from "../width.js";
+/** The caret marker (spec §10.2's degradation rule). */
+export function caretGlyph(unicode) {
+    return unicode ? "▏" : "|";
+}
+/** The width the label column takes at regular/wide (labels beside). */
+export const LABEL_CELLS = 20;
+/**
+ * A single-line text editor buffer: the value plus the caret. Shared
+ * by every text-shaped field (text, number raw, date, datetime,
+ * longtext non-code, choice's other text, list item editors).
+ */
+export class EditBuffer {
+    #text;
+    #caret;
+    constructor(initial) {
+        this.#text = initial;
+        this.#caret = initial.length;
+    }
+    get text() {
+        return this.#text;
+    }
+    get caret() {
+        return this.#caret;
+    }
+    /** Handle one input chunk; returns true when the key was an edit. */
+    input(data) {
+        if (data === "\x1b[D") {
+            // Left
+            if (this.#caret > 0)
+                this.#caret -= 1;
+            return true;
+        }
+        if (data === "\x1b[C") {
+            // Right
+            if (this.#caret < this.#text.length)
+                this.#caret += 1;
+            return true;
+        }
+        if (data === "\x7f" || data === "\b") {
+            if (this.#caret > 0) {
+                this.#text = this.#text.slice(0, this.#caret - 1) + this.#text.slice(this.#caret);
+                this.#caret -= 1;
+            }
+            return true;
+        }
+        // Printable input only (escape sequences and control keys are the
+        // form's navigation, not text).
+        if (data.length > 0 && !data.startsWith("\x1b") && !/[\x00-\x1f]/u.test(data)) {
+            this.#text = this.#text.slice(0, this.#caret) + data + this.#text.slice(this.#caret);
+            this.#caret += data.length;
+            return true;
+        }
+        return false;
+    }
+    /** The displayed line with the caret marker inserted. */
+    render(unicode = true) {
+        return (this.#text.slice(0, this.#caret) +
+            caretGlyph(unicode) +
+            this.#text.slice(this.#caret));
+    }
+}
+/** A field's label/help resolved to text. */
+export function fieldLabel(field, ctx) {
+    return bindText(field.label, ctx) || field.name;
+}
+/** The value's display text (the editor seed; numbers stringify). */
+export function valueText(value) {
+    if (typeof value === "string")
+        return value;
+    if (typeof value === "number" || typeof value === "boolean")
+        return String(value);
+    return "";
+}
+/** Render a bindable to text (labels, help). */
+export function text(value, ctx) {
+    return bindText(value, ctx);
+}
+/**
+ * The field-row chrome: label (beside at regular/wide, above at
+ * compact), the editor lines, then help and the error (client or the
+ * server field error, §5.6) under the field.
+ */
+export function fieldRowLines(opts) {
+    const { field, ctx, width } = opts;
+    const label = fieldLabel(field, ctx) + (field.required === true ? " *" : "");
+    const help = text(field.help, ctx);
+    const lines = [];
+    const beside = widthClassOf(width) !== "compact";
+    const labelText = truncate(label, beside ? LABEL_CELLS - 1 : width);
+    if (label !== "") {
+        if (beside) {
+            // Labels beside fields (§12.3): pad the label column, the
+            // editor line follows on the same row.
+            const first = opts.editor[0] ?? "";
+            lines.push(truncate(`${labelText.padEnd(LABEL_CELLS)}${first}`, width));
+            for (const extra of opts.editor.slice(1)) {
+                lines.push(truncate(`${" ".repeat(LABEL_CELLS)}${extra}`, width));
+            }
+        }
+        else {
+            lines.push(ctx.theme.bold(labelText));
+            for (const line of opts.editor)
+                lines.push(truncate(`  ${line}`, width));
+        }
+    }
+    else {
+        for (const line of opts.editor)
+            lines.push(truncate(line, width));
+    }
+    if (help !== "") {
+        for (const line of wrapPlain(help, width))
+            lines.push(ctx.theme.dim(line));
+    }
+    if (opts.error !== undefined && opts.error !== "") {
+        lines.push(ctx.theme.fg("bad")(truncate(opts.error, width)));
+    }
+    return lines;
+}

package/dist/blocks/form/file.d.ts

@@ -0,0 +1,61 @@
+/**
+ * The secret and file fields (UI-blocks U2 Task 5, spec §5.6).
+ *
+ * `secret` is write-only: it NEVER renders a value, only the bound
+ * status — `set (stored)` / `set (env)` / `not set` — and a masked
+ * editor (`•` per typed character; ASCII `*` with ctx.unicode false).
+ *
+ * `file` prompts for a path, checks `accept` (MIME patterns) and
+ * `maxBytes`, reads the file's bytes, dispatches `onUpload` (a
+ * `submit` action, turn false) with the file descriptor plus the base64
+ * bytes, and hands the bytes to the surface's upload seam
+ * (`uploadBytes`) when the host provides one (§7.2). A failed check
+ * shows its error under the field and dispatches nothing.
+ */
+import type { FileField, JsonObject, SecretField } from "@sigrun/shared/blocks";
+import { type BlockCtx } from "../context.js";
+/** The secret status text (spec §5.6's exact strings). */
+export declare function secretStatusText(status: unknown): string;
+/** The status line of a secret field: the bound status (the field's
+ *  name resolved against the form's bind, as U1's SecretField does). */
+export declare function secretStatusLine(field: SecretField, formBind: string, ctx: BlockCtx): string;
+/** The masked editor text: one dot per typed character. */
+export declare function maskText(textValue: string, unicode: boolean): string;
+/** Whether a file matches the accept patterns (comma-separated:
+ *  `image/*`, `image/png`, `.png`) — U1's `acceptsMime` rule, extended
+ *  with an extension fallback when the MIME guess is empty. */
+export declare function acceptsMime(accept: string | undefined, file: {
+    type: string;
+    name: string;
+}): boolean;
+/** The MIME guess from a file name ("" when unknown). */
+export declare function mimeOf(name: string): string;
+/** The outcome of a file pick (checks + read + dispatch shape). */
+export type FilePick = {
+    ok: true;
+    descriptor: {
+        name: string;
+        size: number;
+        type: string;
+    };
+    /** The raw bytes (the upload seam's payload). */
+    bytes: Uint8Array;
+    /** The descriptor plus base64 bytes (the dispatch payload's file). */
+    payloadFile: JsonObject;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Check `accept`/`maxBytes`, read the file and build the descriptor +
+ * payload. A failure answers `{ok: false, error}` and nothing else
+ * happens (no dispatch).
+ */
+export declare function pickFile(field: FileField, path: string, read?: (path: string) => Uint8Array, sizeOf?: (path: string) => number): FilePick;
+/** The per-field secret/file editor state (the path/masked buffer). */
+export declare class FileFieldState {
+    error: string | undefined;
+    uploaded: readonly string[];
+}
+/** The status line a file field shows after an upload. */
+export declare function fileStatusLine(state: FileFieldState, width: number): string | undefined;