@nbtca/prompt 1.3.1 → 1.4.1

package/README.md

@@ -17,6 +17,50 @@ Or run directly:
 npx @nbtca/prompt
 ```
 
+## Personal timetable
+
+Prompt owns the school login and local session; `@nbtca/nbtcal` owns timetable
+normalization and ICS generation.
+
+For a persistent local session:
+
+```bash
+nbtca schedule login
+nbtca schedule terms
+nbtca schedule export --term=2026:3 --week-one=YYYY-MM-DD
+nbtca schedule logout
+```
+
+For a single run that neither reads nor saves a session (`--no-save` is an
+alias):
+
+```bash
+npx @nbtca/prompt schedule export --one-shot
+```
+
+Both the student id and password are masked in the terminal. The password is
+never saved. A persistent login stores only a masked account hint and the
+CookieJar in the user's state directory:
+
+- Unix/macOS default: `~/.local/state/nbtca/session.json`
+- Windows default: `%LOCALAPPDATA%/nbtca/session.json`
+- `$XDG_STATE_HOME` is honored when it is an absolute path
+
+On POSIX systems the directory is `0700` and the file is `0600`. `npx`, a local
+installation and a global installation therefore share the same state without
+depending on npm's disposable package cache. The session is a bearer secret;
+use `--one-shot` on shared machines and `schedule logout` when finished.
+Saved sessions use a sliding seven-day local expiry and are cleared immediately
+when the school reports that they have expired.
+
+JWXT currently returns week numbers and period times but not the first calendar
+date of a term. When no authoritative date map is available, Prompt asks for
+the first teaching Monday or accepts `--week-one=YYYY-MM-DD`. Confirm it against
+the official school calendar; Prompt will not guess. A slider or other browser
+challenge is also never bypassed—the CLI stops with an actionable message.
+Without an authoritative date map, the result is a base teaching-week schedule:
+holidays, make-up classes and temporary changes still require school notices.
+
 ## Documentation
 
 Project documentation has been moved to the GitHub Wiki.

package/SECURITY.md

@@ -0,0 +1,47 @@
+# Security Policy
+
+## School credentials
+
+Prompt sends the student id and an in-memory encrypted password only to the
+school's WebVPN/CAS login flow. It does not offer `--password`, password
+environment variables or credential files. Password and verification input is
+masked and is never written to preferences, state, cache, ICS or logs.
+
+If the school requests a slider, OTP, FIDO or another browser challenge, Prompt
+fails closed. It does not automate or bypass the challenge.
+
+## Authenticated transport
+
+Authentication redirects are restricted to exact HTTPS hosts and routes for
+the NingboTech WebVPN, authentication service and JWXT. CAS `service` and
+WebVPN `origin` parameters are validated against explicit callback routes.
+Caller-supplied `Cookie`, `Authorization` and `Host` headers are rejected.
+
+Errors expose only stable local codes and stages. Response bodies, redirect
+queries, cookies, encrypted passwords and underlying network error objects are
+not included in user-facing output.
+
+## Persisted session
+
+The optional persisted CookieJar is a bearer secret. It is stored under the
+user's state directory with a versioned schema, an atomic write, a `0700`
+directory and a `0600` file on POSIX systems. The saved account hint is masked,
+and Prompt never adds the full student id or password to the state schema. The
+opaque school cookies must still be treated as bearer secrets. Sessions have a
+sliding seven-day local expiry.
+
+Use `nbtca schedule logout` to clear it. Use `--one-shot` on a shared or
+untrusted computer so no session is read or written.
+
+## Timetable and ICS privacy
+
+Raw JWXT responses are processed in memory. Only timetable fields needed for
+normalization are passed to `@nbtca/nbtcal`; the student profile object is
+discarded. Generated ICS files can reveal a person's location and routine, so
+they are created with mode `0600` where supported and should not be uploaded to
+public or "secret-link" hosting.
+
+## Reporting vulnerabilities
+
+Use the repository's GitHub Security Advisory page. Do not include credentials,
+cookies, raw school responses or a personal ICS in a public issue.

package/dist/app/app.js

@@ -0,0 +1,202 @@
+import { ansi, ensureCursorRestored } from '../core/canvas.js';
+import { composeFrame, computeBodyRows } from './frame.js';
+import { routeGlobalKey } from './keys.js';
+import { renderHeader, renderFooter, HEADER_LINES, FOOTER_LINES } from './chrome.js';
+import { homeView } from './views/home.js';
+import { scheduleView } from './views/schedule.js';
+import { docsView } from './views/docs.js';
+import { eventsView } from './views/events.js';
+import { settingsView } from './views/settings.js';
+import { getAppTabs } from './tabs.js';
+/**
+ * Event-driven full-screen app loop. Owns the alt-screen + raw-mode lifecycle
+ * and composes every tab as a native `View` rendered in place. `ctx.runClassic`
+ * remains as a scoped escape hatch a view can call itself when a single action
+ * genuinely needs the real terminal (e.g. Docs handing off to glow/less to
+ * read a file) — the app loop no longer dispatches whole tabs through it.
+ *
+ * Resolves once the user quits (q / Ctrl+C / Esc from home). Terminal state
+ * (alt-screen, raw mode, cursor) is always restored before this resolves,
+ * on SIGINT, on process exit, and even if an unexpected error is thrown.
+ */
+export async function runApp() {
+    if (!process.stdin.isTTY || !process.stdout.isTTY)
+        return;
+    let view = 'home';
+    let scroll = 0;
+    let running = true;
+    let suspended = false;
+    const viewIds = getAppTabs().map((tab) => tab.id);
+    // Every tab is a native View rendered in place inside the alt-screen frame.
+    const nativeViews = {
+        home: homeView,
+        schedule: scheduleView,
+        docs: docsView,
+        events: eventsView,
+        settings: settingsView,
+    };
+    function size() {
+        return { rows: process.stdout.rows || 24, cols: process.stdout.columns || 80 };
+    }
+    const ctx = {
+        get size() { return size(); },
+        get bodyRows() { return computeBodyRows(size().rows, HEADER_LINES, FOOTER_LINES); },
+        rerender() { render(); },
+        resetScroll() { scroll = 0; },
+        runClassic(fn) { return runClassic(fn); },
+        quit() { quit(); },
+    };
+    function render() {
+        if (suspended || !running)
+            return;
+        const { rows, cols } = size();
+        const active = nativeViews[view];
+        const tabs = getAppTabs();
+        const header = renderHeader(tabs, view, cols);
+        const footer = renderFooter(view, cols, tabs.length, active?.footerHint?.(tabs.length, cols));
+        const body = active?.render(ctx) ?? [];
+        process.stdout.write(ansi.home + composeFrame(header, body, footer, rows, cols, scroll) + ansi.eraseDown);
+    }
+    function onKey(data) {
+        const key = data.toString();
+        if (key === '\x03') {
+            quit();
+            return;
+        } // Ctrl-C always quits, even mid-capture.
+        const active = nativeViews[view];
+        // Esc always reaches global routing, even while a view "captures" input
+        // for a focused field (login/search text entry). Without this carve-out,
+        // a view whose own Esc-handling doesn't escape its captured mode would
+        // trap the user on that tab with no way out except Ctrl-C (quitting the
+        // whole app). Esc must never be swallowed silently — it's the universal
+        // way out of anything.
+        if (active?.capturesInput?.() && key !== '\x1b') {
+            active.handleKey?.(key, ctx);
+            render();
+            return;
+        }
+        const g = routeGlobalKey(key, viewIds, view);
+        if (g.quit) {
+            quit();
+            return;
+        }
+        if (g.back) {
+            // Esc steps back one level within the view first (e.g. its week grid
+            // back to its own hub) — only once the view has nowhere left to step
+            // back to does Esc leave the tab for Home. Matches how k9s/lazygit
+            // treat Esc: back one level, not straight to the root.
+            if (active?.handleBack?.(ctx)) {
+                scroll = 0; // the new sub-view's content height has nothing to do with the old one's
+                render();
+                return;
+            }
+            view = 'home';
+            void nativeViews['home']?.load?.(ctx)?.catch(() => { });
+            render();
+            return;
+        }
+        if (g.switchTo) {
+            switchTo(g.switchTo);
+            return;
+        }
+        if (g.scrollBy) {
+            // fitBody (frame.ts) clamps this to [0, content.length - bodyRows]
+            // on every render regardless of what's requested here, so this never
+            // needs to know the current body's height to stay in bounds.
+            const page = Math.max(1, ctx.bodyRows - 2);
+            scroll = Math.max(0, scroll + g.scrollBy * page);
+            render();
+            return;
+        }
+        active?.handleKey?.(key, ctx);
+        render();
+    }
+    function enter() {
+        ensureCursorRestored();
+        process.stdout.write(ansi.enterAlt + ansi.hideCursor);
+        if (process.stdin.isTTY)
+            process.stdin.setRawMode(true);
+        process.stdin.resume();
+        process.stdin.on('data', onKey);
+    }
+    function leave() {
+        process.stdin.removeListener('data', onKey);
+        if (process.stdin.isTTY)
+            process.stdin.setRawMode(false);
+        process.stdout.write(ansi.showCursor + ansi.leaveAlt);
+        // `enter()` calls `stdin.resume()`; a resumed stdin stream keeps the
+        // Node event loop alive by design even with no listeners attached. The
+        // classic bridge calls `enter()` again right after, so pausing here is
+        // always safe — either it's about to be resumed, or the app is quitting
+        // for good and this is what lets the process actually exit.
+        process.stdin.pause();
+    }
+    function switchTo(id) {
+        scroll = 0;
+        view = id;
+        void nativeViews[id]?.load?.(ctx)?.catch(() => { });
+        render();
+    }
+    // A classic surface (currently only Docs' glow/less pager) owns its own
+    // raw-mode + rendering, so the app must fully leave() the alt-screen
+    // before invoking it and re-enter() after it returns.
+    async function runClassic(fn) {
+        suspended = true;
+        leave();
+        try {
+            await fn();
+        }
+        catch (err) {
+            // Classic surfaces are expected to surface their own errors, but if
+            // one throws anyway, don't swallow it silently: leave() has already
+            // restored cooked mode, so writing to stderr here is visible.
+            process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
+        }
+        enter();
+        suspended = false;
+        render();
+    }
+    function onResize() {
+        render();
+    }
+    function onExit() {
+        leave();
+    }
+    function onSigint() {
+        quit();
+        process.exit(0);
+    }
+    let resolveRun = () => { };
+    const done = new Promise((resolve) => {
+        resolveRun = resolve;
+    });
+    function quit() {
+        if (!running)
+            return;
+        running = false;
+        try {
+            leave();
+        }
+        finally {
+            process.stdout.removeListener('resize', onResize);
+            process.removeListener('exit', onExit);
+            process.removeListener('SIGINT', onSigint);
+            resolveRun();
+        }
+    }
+    process.on('exit', onExit);
+    process.stdout.on('resize', onResize);
+    process.once('SIGINT', onSigint);
+    try {
+        enter();
+        void nativeViews['home']?.load?.(ctx)?.catch(() => { });
+        render();
+        await done;
+    }
+    finally {
+        // Safety net: if we got here via an unexpected throw rather than quit(),
+        // make sure the terminal is restored and listeners don't leak.
+        if (running)
+            quit();
+    }
+}

package/dist/app/chrome.js

@@ -0,0 +1,104 @@
+import { type, space, glyph, brandMark } from '../core/theme.js';
+import { pickIcon } from '../core/icons.js';
+import { t } from '../i18n/index.js';
+import { visualWidth } from '../core/text.js';
+/** `renderHeader` always returns exactly this many lines (brand, tabs, rule). */
+export const HEADER_LINES = 3;
+/** `renderFooter` always returns exactly this many lines (rule, keyhints). */
+export const FOOTER_LINES = 2;
+function renderTabs(views, active, cols) {
+    const dot = pickIcon('·', '-');
+    const full = space.indent + views
+        .map((view) => view.id === active ? type.active(`[${view.title}]`) : type.hint(view.title))
+        .join(`  ${dot}  `);
+    if (visualWidth(full) <= cols)
+        return full;
+    const compact = space.indent + views
+        .map((view, index) => view.id === active
+        ? type.active(`[${index + 1} ${view.title}]`)
+        : type.hint(String(index + 1)))
+        .join(` ${dot} `);
+    if (visualWidth(compact) <= cols)
+        return compact;
+    return space.indent + views
+        .map((view, index) => view.id === active
+        ? type.active(`[${index + 1}]`)
+        : type.hint(String(index + 1)))
+        .join(' ');
+}
+// The header's persistent brand mark. A literal shrunk-down copy of the
+// emblem doesn't survive down to header height (verified: even the boldest
+// inner icon alone dissolves into noise below ~12 character-rows), so this
+// is a wordmark painted in the same gradient as the startup logo instead --
+// ties the two together by color, the one dimension that still reads at
+// one line tall, rather than attempting a shape reproduction this small
+// can't carry.
+export function renderHeader(views, active, cols) {
+    const brand = `${space.indent}${brandMark('nbtca')}`;
+    const tabs = renderTabs(views, active, cols);
+    const rule = space.indent + type.hint(glyph.rule().repeat(Math.max(1, cols - 6)));
+    return [brand, tabs, rule];
+}
+/** Shared footer hint for any view mode that captures all input (a focused
+ * text field or a modal-like list) — the only keys that still do something
+ * are Ctrl-C/Esc/Enter, so this is what every such view's `footerHint()`
+ * should return instead of each re-declaring an identical string. Digits/Tab
+ * are deliberately absent: while input is captured they're typed into the
+ * field, not routed to global tab-switching, so promising them would itself
+ * be the false-promise this hint exists to avoid. */
+export function fitFooterHint(cols, ...candidates) {
+    return candidates.find((candidate) => visualWidth(space.indent + candidate) <= cols)
+        ?? candidates[candidates.length - 1]
+        ?? '';
+}
+export function captureFooterHint(cols = Number.POSITIVE_INFINITY) {
+    const trans = t();
+    const dot = pickIcon('·', '-');
+    return fitFooterHint(cols, `Ctrl+C ${trans.common.exit}  ${dot}  Esc ${trans.common.back}  ${dot}  Enter ${trans.common.confirm}`, 'Ctrl+C Esc Enter', 'Ctrl+C Esc', 'Ctrl+C');
+}
+/** The "1-N / Tab" tab-switch prefix, factored out so a view's own
+ * `footerHint()` override can still include it accurately (tab count isn't
+ * knowable inside a view module otherwise) instead of either hardcoding a
+ * digit range that goes stale, or dropping a still-true promise entirely. */
+export function digitTabHint(tabCount) {
+    const dot = pickIcon('·', '-');
+    return tabCount > 1 ? `1-${tabCount} / Tab ${dot} ` : '';
+}
+/** Shared hint for a non-interactive state: digits/Tab still switch tabs,
+ * while move/open do nothing and must not be advertised. */
+export function passiveFooterHint(tabCount, cols = Number.POSITIVE_INFINITY) {
+    const trans = t();
+    const dot = pickIcon('·', '-');
+    const compactTabs = tabCount > 1 ? `1-${tabCount}/Tab ${dot} ` : '';
+    return fitFooterHint(cols, `${digitTabHint(tabCount)}Esc ${dot} q ${trans.menu.hintQuit}`, `${compactTabs}Esc ${dot} q`, `Esc ${dot} q`, 'q');
+}
+function interactiveFooterHint(tabCount, cols) {
+    const trans = t();
+    const dot = pickIcon('·', '-');
+    const fullTabs = digitTabHint(tabCount);
+    const compactTabs = tabCount > 1 ? `1-${tabCount}/Tab ${dot} ` : '';
+    const localFull = `${trans.menu.hintMove} ${dot} ${trans.menu.hintOpen} ${dot} Esc ${dot} q ${trans.menu.hintQuit}`;
+    const localCompact = `${trans.menu.hintMove} ${trans.menu.hintOpen} Esc q`;
+    const candidates = [
+        `${fullTabs}${localFull}`,
+        `${compactTabs}${localFull}`,
+        localFull,
+        `${compactTabs}${localCompact}`,
+        localCompact,
+        `${trans.menu.hintOpen} Esc q`,
+        `Esc ${dot} q`,
+        'q',
+    ];
+    return fitFooterHint(cols, ...candidates);
+}
+/** `overrideHint`: a view supplies this (via `View.footerHint()`) when the
+ * generic tab-switching hint would be false — e.g. while a text field has
+ * focus, digits/Tab/q are typed characters, not shortcuts, and only Ctrl-C/
+ * Esc/Enter actually do anything. The footer must never promise a key that
+ * doesn't work. */
+export function renderFooter(_active, cols, tabCount, overrideHint) {
+    const rule = space.indent + type.hint(glyph.rule().repeat(Math.max(1, cols - 6)));
+    const hintText = overrideHint ?? interactiveFooterHint(tabCount, cols);
+    const hint = space.indent + type.hint(hintText);
+    return [rule, hint];
+}

package/dist/app/fields/list-field.js

@@ -0,0 +1,174 @@
+import { renderMenu, renderMenuOption, nextIndex, parseKey, } from '../../core/components/menu.js';
+import { space, type } from '../../core/theme.js';
+import { pickIcon } from '../../core/icons.js';
+import { t, fmt } from '../../i18n/index.js';
+import { visualWidth, wrapAnsiToVisualWidth } from '../../core/text.js';
+/** A conservative rows-to-options budget for a ListField that fills a
+ * view's whole body (title + blank + up to N options + an optional
+ * more-indicator + footer). Reserves ~4 lines for that non-option chrome
+ * so the field never itself overflows `bodyRows`. */
+export function computeMaxVisible(bodyRows) {
+    return Math.max(3, bodyRows - 4);
+}
+function renderIndentedOutput(value, cols) {
+    const width = Number.isFinite(cols) ? Math.max(1, Math.floor(cols)) : Number.POSITIVE_INFINITY;
+    const indent = visualWidth(space.indent) < width ? space.indent : '';
+    const contentWidth = Math.max(1, width - visualWidth(indent));
+    return wrapAnsiToVisualWidth(value, contentWidth).map((line) => `${indent}${line}`);
+}
+/** Non-blocking equivalent of `runMenu`: a view holds one of these in its own
+ * state and drives it from the app loop's single stdin listener via
+ * `handleKey`, instead of `runMenu` attaching a second listener and blocking
+ * on a Promise. */
+export class ListField {
+    config;
+    index;
+    scrollTop = 0;
+    maxVisible;
+    constructor(config) {
+        this.config = config;
+        this.index = config.initialIndex ?? 0;
+        this.maxVisible = config.maxVisible;
+        this.clampScroll();
+    }
+    get selectedIndex() {
+        return this.index;
+    }
+    /** How many options this field actually has — lets a caller reserve
+     * exactly enough room for this specific menu instead of guessing a
+     * shared constant that's wrong for every menu of a different size. */
+    get optionCount() {
+        return this.config.options.length;
+    }
+    /** Updates the visible-row budget in place (re-clamping the scroll window
+     * so the selection stays visible) instead of losing the field's current
+     * selection/scroll by rebuilding it. Views call this from their own
+     * `render(ctx)` on every frame — cheap, and it's what keeps a field's
+     * window in sync with the *current* terminal size even though the field
+     * itself was constructed against whatever size was current at the time. */
+    setMaxVisible(maxVisible) {
+        this.maxVisible = maxVisible;
+        this.clampScroll();
+    }
+    render(maxRows = Number.POSITIVE_INFINITY, cols = Number.POSITIVE_INFINITY) {
+        const expanded = this.renderExpanded(cols);
+        if (!Number.isFinite(maxRows) || expanded.length <= maxRows)
+            return expanded;
+        return this.renderCompact(Math.max(0, Math.floor(maxRows)), cols);
+    }
+    renderExpanded(cols) {
+        const { title, options, footer } = this.config;
+        const maxVisible = this.maxVisible;
+        if (!maxVisible || options.length <= maxVisible) {
+            return renderMenu({ title, options, selectedIndex: this.index, footer }, cols).split('\n');
+        }
+        const visible = options.slice(this.scrollTop, this.scrollTop + maxVisible);
+        const lines = renderMenu({
+            title,
+            options: visible,
+            selectedIndex: this.index - this.scrollTop,
+        }, cols).split('\n');
+        const above = this.scrollTop;
+        const below = options.length - (this.scrollTop + visible.length);
+        if (above > 0 || below > 0) {
+            const trans = t();
+            const parts = [
+                above > 0 ? fmt(trans.common.moreAbove, { count: above }) : null,
+                below > 0 ? fmt(trans.common.moreBelow, { count: below }) : null,
+            ].filter((part) => part !== null);
+            lines.push(...renderIndentedOutput(type.hint(parts.join(`  ${pickIcon('·', '-')}  `)), cols));
+        }
+        if (footer)
+            lines.push('', ...renderIndentedOutput(type.hint(footer), cols));
+        return lines;
+    }
+    renderCompact(maxRows, cols) {
+        if (maxRows === 0)
+            return [];
+        const { title, options } = this.config;
+        if (options.length === 0) {
+            return title ? renderIndentedOutput(type.heading(title), cols).slice(0, maxRows) : [];
+        }
+        const labelWidth = options.reduce((width, option) => Math.max(width, visualWidth(option.label)), 0);
+        const optionGroups = options.map((option, index) => renderMenuOption(option, index === this.index, labelWidth, cols));
+        const selectedLines = optionGroups[this.index] ?? [];
+        const titleValue = options.length > 1
+            ? `${type.heading(title)}${type.hint(`  ${this.index + 1}/${options.length}`)}`
+            : type.heading(title);
+        const titleLines = title ? renderIndentedOutput(titleValue, cols) : [];
+        let header = [];
+        if (titleLines.length + 1 + selectedLines.length <= maxRows)
+            header = [...titleLines, ''];
+        else if (titleLines.length + selectedLines.length <= maxRows)
+            header = titleLines;
+        const optionBudget = maxRows - header.length;
+        if (selectedLines.length > optionBudget) {
+            return [...header, ...selectedLines.slice(0, optionBudget)];
+        }
+        let start = this.index;
+        let end = this.index + 1;
+        let usedRows = selectedLines.length;
+        const optionLimit = this.maxVisible ?? Number.POSITIVE_INFINITY;
+        while (end - start < optionLimit) {
+            const after = optionGroups[end];
+            if (after && usedRows + after.length <= optionBudget) {
+                usedRows += after.length;
+                end += 1;
+                continue;
+            }
+            const before = optionGroups[start - 1];
+            if (before && usedRows + before.length <= optionBudget) {
+                usedRows += before.length;
+                start -= 1;
+                continue;
+            }
+            break;
+        }
+        return [...header, ...optionGroups.slice(start, end).flat()];
+    }
+    handleKey(key) {
+        const parsed = parseKey(key);
+        if (parsed === 'cancel')
+            return { cancelled: true };
+        if (parsed === 'enter')
+            return { selected: this.config.options[this.index]?.value };
+        const next = nextIndex(this.index, parsed, this.config.options.length);
+        if (next !== this.index) {
+            this.index = next;
+            this.clampScroll();
+        }
+        return {};
+    }
+    /** Keeps `index` within [scrollTop, scrollTop + maxVisible) after any move
+     * or after maxVisible itself changes (e.g. a terminal resize). */
+    clampScroll() {
+        const maxVisible = this.maxVisible;
+        if (!maxVisible) {
+            this.scrollTop = 0;
+            return;
+        }
+        if (this.index < this.scrollTop)
+            this.scrollTop = this.index;
+        else if (this.index >= this.scrollTop + maxVisible)
+            this.scrollTop = this.index - maxVisible + 1;
+        // The window may also need to slide backward if it shrank enough that
+        // scrollTop..scrollTop+maxVisible now runs past the end of the list.
+        this.scrollTop = Math.max(0, Math.min(this.scrollTop, Math.max(0, this.config.options.length - maxVisible)));
+    }
+}
+export function renderListFieldWithContext(context, field, maxRows, cols = Number.POSITIVE_INFINITY) {
+    if (!Number.isFinite(maxRows))
+        return [...context, ...field.render(Number.POSITIVE_INFINITY, cols)];
+    const rows = Math.max(0, Math.floor(maxRows));
+    if (rows === 0)
+        return [];
+    const expanded = field.render(Number.POSITIVE_INFINITY, cols);
+    if (context.length + expanded.length <= rows)
+        return [...context, ...expanded];
+    if (expanded.length === 0)
+        return context.slice(0, rows);
+    const minimumFieldRows = Math.min(3, rows, expanded.length);
+    const contextRows = Math.min(context.length, rows - minimumFieldRows);
+    const fieldRows = rows - contextRows;
+    return [...context.slice(0, contextRows), ...field.render(fieldRows, cols)];
+}

package/dist/app/fields/text-field.js

@@ -0,0 +1,38 @@
+import { renderInput, applyInputEvent, parseInputData } from '../../core/components/text-input.js';
+/** Non-blocking equivalent of `runTextInput`/`runSecretInput`: a view holds
+ * one of these and drives it via `handleKey` from the app loop's single
+ * stdin listener. Does not touch vim-key activation — the owning view is
+ * responsible for `setVimKeysActive(false)` while a TextField is focused
+ * (mirrors what `runTextInput` already does for the blocking widget). */
+export class TextField {
+    config;
+    value = '';
+    constructor(config) {
+        this.config = config;
+    }
+    get currentValue() {
+        return this.value;
+    }
+    render(cols = Number.POSITIVE_INFINITY) {
+        return renderInput({
+            message: this.config.message,
+            value: this.value,
+            placeholder: this.config.placeholder,
+            secret: this.config.secret,
+            mask: this.config.mask,
+            cols,
+        }).split('\n');
+    }
+    handleKey(key) {
+        const ev = parseInputData(key);
+        if (ev.type === 'cancel')
+            return { cancelled: true };
+        if (ev.type === 'enter') {
+            if (this.value.length > 0 || this.config.allowEmpty === true)
+                return { submitted: this.value };
+            return {};
+        }
+        this.value = applyInputEvent(this.value, ev);
+        return {};
+    }
+}

package/dist/app/frame.js

@@ -0,0 +1,48 @@
+import { visualWidth } from '../core/text.js';
+export function clipToWidth(line, cols) {
+    if (visualWidth(line) <= cols)
+        return line;
+    let out = '';
+    let w = 0;
+    let i = 0;
+    while (i < line.length) {
+        const esc = line.slice(i).match(/^\x1b\[[0-9;]*m/);
+        if (esc) {
+            out += esc[0];
+            i += esc[0].length;
+            continue;
+        }
+        const cp = line.codePointAt(i);
+        const ch = String.fromCodePoint(cp);
+        const cw = visualWidth(ch);
+        if (w + cw > cols)
+            break;
+        out += ch;
+        w += cw;
+        i += ch.length;
+    }
+    return out + '\x1b[0m';
+}
+export function fitLine(line, cols) {
+    const clipped = visualWidth(line) > cols ? clipToWidth(line, cols) : line;
+    const pad = cols - visualWidth(clipped);
+    return pad > 0 ? clipped + ' '.repeat(pad) : clipped;
+}
+export function fitBody(lines, height, scroll, cols) {
+    const maxScroll = Math.max(0, lines.length - height);
+    const start = Math.max(0, Math.min(scroll, maxScroll));
+    const out = lines.slice(start, start + height).map((l) => fitLine(l, cols));
+    while (out.length < height)
+        out.push(' '.repeat(cols));
+    return out;
+}
+export function composeFrame(header, body, footer, rows, cols, scroll) {
+    const h = header.map((l) => fitLine(l, cols));
+    const f = footer.map((l) => fitLine(l, cols));
+    const bodyH = Math.max(0, rows - h.length - f.length);
+    const b = fitBody(body, bodyH, scroll, cols);
+    return [...h, ...b, ...f].slice(0, rows).join('\n');
+}
+export function computeBodyRows(rows, headerLines, footerLines) {
+    return Math.max(0, rows - headerLines - footerLines);
+}