@north-light/crouter 0.3.191 → 0.3.193

package/dist/clients/inbox/tui/slots.d.ts

@@ -0,0 +1,32 @@
+import type { CommentAnchor, PageManifest, PageSlot, SlotResponse, TableConfig } from '../../../core/human/page-schema.js';
+import type { TuiState } from './types.js';
+export type SelectGroup = 'option' | 'card' | 'row' | 'column';
+export type ActionRow = {
+    kind: 'select';
+    group: SelectGroup;
+    id: string;
+    label: string;
+    description?: string;
+    shortcut?: string;
+    mode: 'single' | 'multi';
+} | {
+    kind: 'freetext';
+    label: string;
+} | {
+    kind: 'accept';
+    label: string;
+} | {
+    kind: 'edit';
+    label: string;
+};
+export declare function describeSlot(slot: PageSlot): string;
+/** False when the slot's response cannot be authored here: an unvalidated product kind, or a source-backed cards slot whose cards the terminal never sees. */
+export declare function terminalAnswerable(slot: PageSlot): boolean;
+export declare function slotActions(slot: PageSlot): ActionRow[];
+export declare function tableMarkdown(config: TableConfig): string;
+export declare function summarizeSlotResponse(slot: PageSlot, response: SlotResponse | undefined): string;
+export declare function slotAnswered(state: TuiState, slot: PageSlot): boolean;
+export declare function pageComplete(state: Pick<TuiState, 'manifest' | 'responses'>): boolean;
+export declare function commentIdFor(anchor: CommentAnchor): string;
+export declare function anchorLabel(slot: PageSlot, anchor: CommentAnchor): string;
+export declare function awaitsResponse(manifest: PageManifest): boolean;

package/dist/clients/inbox/tui/slots.js

@@ -0,0 +1,156 @@
+import { isResponseBearingSlot, validatePageResponses, validatePartialPageResponses } from '../../../core/human/page-schema.js';
+const RESERVED = new Set(['c', 'r', 'e', 'a', 'n', 'p', 'q', 'j', 'k', 'u', 'd', ' ']);
+export function describeSlot(slot) {
+    if (slot.unvalidated === true)
+        return slot.kind;
+    if (slot.kind === 'options')
+        return 'Options';
+    if (slot.kind === 'text')
+        return 'Text';
+    if (slot.kind === 'table')
+        return slot.config.caption ?? 'Table';
+    if (slot.kind === 'cards')
+        return 'Cards';
+    if (slot.kind === 'chart')
+        return 'Chart';
+    return slot.kind;
+}
+/** False when the slot's response cannot be authored here: an unvalidated product kind, or a source-backed cards slot whose cards the terminal never sees. */
+export function terminalAnswerable(slot) {
+    if (slot.unvalidated === true)
+        return false;
+    if (slot.kind === 'cards' && slot.config.cards === undefined)
+        return false;
+    return true;
+}
+export function slotActions(slot) {
+    if (!terminalAnswerable(slot))
+        return [];
+    let rows = [];
+    if (slot.kind === 'options') {
+        const config = slot.config;
+        rows = config.options.map((option) => ({ kind: 'select', group: 'option', id: option.id, label: option.label, ...(option.description === undefined ? {} : { description: option.description }), mode: config.mode }));
+        if (config.allowFreetext === true)
+            rows.push({ kind: 'freetext', label: config.freetextLabel ?? 'Other' });
+    }
+    else if (slot.kind === 'cards') {
+        const config = slot.config;
+        rows = (config.cards ?? []).map((card) => ({ kind: 'select', group: 'card', id: card.id, label: card.subtitle === undefined ? card.title : `${card.title} — ${card.subtitle}`, ...(card.body === undefined ? {} : { description: card.body }), mode: config.mode }));
+    }
+    else if (slot.kind === 'text') {
+        if (slot.config.editable === true)
+            rows.push({ kind: 'edit', label: 'Edit' });
+        rows.push({ kind: 'accept', label: 'Accept as-is' });
+    }
+    else if (slot.kind === 'table') {
+        const config = slot.config;
+        if (config.rowSelect !== 'none') {
+            const first = config.columns[0];
+            rows.push(...(config.rows ?? []).map((row) => ({ kind: 'select', group: 'row', id: row.id, label: first === undefined ? row.id : String(row.cells[first.id] ?? row.id), mode: config.rowSelect })));
+        }
+        if (config.columnSelect !== 'none')
+            rows.push(...config.columns.map((column) => ({ kind: 'select', group: 'column', id: column.id, label: column.label, mode: config.columnSelect })));
+    }
+    const used = new Set();
+    return rows.map((row) => {
+        if (row.kind !== 'select')
+            return row;
+        let shortcut;
+        for (const letter of [...row.label.toLowerCase()].filter((c) => /[a-z]/.test(c))) {
+            if (!used.has(letter) && !RESERVED.has(letter)) {
+                shortcut = letter;
+                break;
+            }
+        }
+        if (shortcut === undefined)
+            for (let d = 1; d <= 9; d++)
+                if (!used.has(String(d))) {
+                    shortcut = String(d);
+                    break;
+                }
+        if (shortcut !== undefined)
+            used.add(shortcut);
+        return { ...row, ...(shortcut === undefined ? {} : { shortcut }) };
+    });
+}
+function escapeCell(value, mono = false) {
+    if (value === null || value === undefined)
+        return '';
+    const text = String(value).replaceAll('|', '\\|').replaceAll('\n', '<br>');
+    return mono && text !== '' ? `\`${text.replaceAll('`', '\\`')}\`` : text;
+}
+export function tableMarkdown(config) {
+    const header = `| ${config.columns.map((column) => escapeCell(column.label)).join(' | ')} |`;
+    const divider = `| ${config.columns.map((column) => column.align === 'right' ? '---:' : '---').join(' | ')} |`;
+    return [header, divider, ...(config.rows ?? []).map((row) => `| ${config.columns.map((column) => escapeCell(row.cells[column.id], column.mono === true)).join(' | ')} |`)].join('\n');
+}
+export function summarizeSlotResponse(slot, response) {
+    if (response === undefined)
+        return isResponseBearingSlot(slot) ? 'unanswered' : 'display';
+    if (slot.kind === 'options') {
+        const r = response;
+        const labels = slot.config.options.filter((o) => r.selectedOptionIds.includes(o.id)).map((o) => o.label);
+        if ((r.freetext?.trim() ?? '') !== '')
+            labels.push(r.freetext.trim());
+        return labels.join(', ') || (r.comments.length > 0 ? `${r.comments.length} comment${r.comments.length === 1 ? '' : 's'}` : 'answered');
+    }
+    if (slot.kind === 'cards') {
+        const r = response;
+        return slot.config.cards?.filter((c) => r.selectedCardIds.includes(c.id)).map((c) => c.title).join(', ') || 'answered';
+    }
+    if (slot.kind === 'table') {
+        const r = response;
+        return `${r.selectedRowIds.length} row${r.selectedRowIds.length === 1 ? '' : 's'}, ${r.selectedColumnIds.length} column${r.selectedColumnIds.length === 1 ? '' : 's'}`;
+    }
+    if (slot.kind === 'text')
+        return response.edited ? 'edited' : 'accepted';
+    return 'answered';
+}
+export function slotAnswered(state, slot) {
+    if (!terminalAnswerable(slot) || slot.id === undefined || !state.responses.has(slot.id))
+        return false;
+    try {
+        validatePartialPageResponses(state.manifest, { [slot.id]: state.responses.get(slot.id) });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function pageComplete(state) {
+    if (state.manifest.slots.some((slot) => isResponseBearingSlot(slot) && !terminalAnswerable(slot)))
+        return false;
+    try {
+        validatePageResponses(state.manifest, Object.fromEntries(state.responses));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function commentIdFor(anchor) {
+    switch (anchor.kind) {
+        case 'whole': return 'whole';
+        case 'option': return `option:${anchor.optionId}`;
+        case 'card': return `card:${anchor.cardId}`;
+        case 'row': return `row:${anchor.rowId}`;
+        case 'column': return `column:${anchor.columnId}`;
+        case 'range': return `range:${anchor.start}:${anchor.end}`;
+    }
+}
+export function anchorLabel(slot, anchor) {
+    if (anchor.kind === 'whole')
+        return describeSlot(slot);
+    if (anchor.kind === 'option')
+        return slot.config.options.find((x) => x.id === anchor.optionId)?.label ?? anchor.optionId;
+    if (anchor.kind === 'card')
+        return slot.config.cards?.find((x) => x.id === anchor.cardId)?.title ?? anchor.cardId;
+    if (anchor.kind === 'row')
+        return slot.config.rows?.find((x) => x.id === anchor.rowId)?.id ?? anchor.rowId;
+    if (anchor.kind === 'column')
+        return slot.config.columns.find((x) => x.id === anchor.columnId)?.label ?? anchor.columnId;
+    return anchor.quote;
+}
+export function awaitsResponse(manifest) {
+    return manifest.slots.some(isResponseBearingSlot);
+}

package/dist/clients/inbox/tui/types.d.ts

@@ -1,22 +1,31 @@
 import type { Key } from './keys.js';
-import type { Deck, Interaction, InteractionResponse } from '../../../core/human/types.js';
+import type { CommentAnchor, PageManifest, PageResponses, PageSlot, SlotResponse } from '../../../core/human/page-schema.js';
+import type { PageSourceProjection } from '../../../core/human/page.js';
 export type Phase = 'overview' | 'item-review' | 'final';
 export type InputMode = null | {
     kind: 'comment';
     buffer: string;
     cursor: number;
-    selectedOptionId?: string;
+    anchor?: CommentAnchor;
 } | {
     kind: 'freetext';
     buffer: string;
     cursor: number;
+} | {
+    kind: 'text';
+    buffer: string;
+    cursor: number;
 };
 export interface TuiState {
     phase: Phase;
     currentIndex: number;
-    interactions: Interaction[];
-    responses: Map<string, InteractionResponse>;
-    preAnsweredIds: Set<string>;
+    manifest: PageManifest;
+    slots: PageSlot[];
+    overviewProse: string[];
+    slotProse: Map<number, string[]>;
+    finalProse: string[];
+    responses: Map<string, SlotResponse>;
+    productKinds: string[];
     inputMode: InputMode;
     selectedAction: number;
     bodyMode: 'question';
@@ -32,13 +41,15 @@ export interface TuiState {
     persist?: () => void;
 }
 export interface MountedPanelOpts {
-    deck: Deck;
-    progressPath?: string;
-    onEditorRequest?: () => void;
+    manifest: PageManifest;
+    projection: PageSourceProjection;
+    productKinds?: string[];
+    initialResponses?: PageResponses | null;
     cols: number;
     rows: number;
-    onProgress?: (responses: InteractionResponse[]) => void;
-    onComplete?: (responses: InteractionResponse[]) => void;
+    onEditorRequest?: () => void;
+    onProgress?: (responses: PageResponses) => void;
+    onComplete?: (responses: PageResponses) => void;
     onExit?: () => void;
     onDirty?: () => void;
 }
@@ -47,11 +58,12 @@ export interface MountedPanel {
     render(): string[];
     handleResize(cols: number, rows: number): string[];
     unmount(): void;
-    loadDeck(deck: Deck, opts?: {
-        progressPath?: string;
+    loadPage(manifest: PageManifest, projection: PageSourceProjection, opts?: {
+        initialResponses?: PageResponses | null;
+        productKinds?: string[];
     }): void;
     canAcceptHostKeys(): boolean;
-    atDeckTop(): boolean;
+    atPageTop(): boolean;
     getInputBuffer(): string | undefined;
     setInputBuffer(text: string): void;
 }

package/dist/clients/inbox/tui.js

@@ -8,8 +8,8 @@ function ansiColor(text, color) {
         default: return text;
     }
 }
-export const KIND_ICON = { notify: '✉', decision: '◆', context: '✎', error: '⚠', review: '▤' };
-export const KIND_COLOR = { notify: 'gray', decision: 'cyan', context: 'cyan', error: 'red', review: 'yellow' };
+export const KIND_ICON = { notify: '✉', decision: '◆', context: '✎', error: '⚠', review: '▤', display: '✉', rich: '▣', interactive: '◆' };
+export const KIND_COLOR = { notify: 'gray', decision: 'cyan', context: 'cyan', error: 'red', review: 'yellow', display: 'gray', rich: 'cyan', interactive: 'cyan' };
 export function formatTimeAgo(iso) {
     const minutes = Math.floor((Date.now() - new Date(iso).getTime()) / 60000);
     if (minutes >= 60)
@@ -35,7 +35,9 @@ export function buildInboxLines(items, width, selectedIndex, height = Number.MAX
     return lines;
 }
 function buildItemLines(item, index, selectedIndex, contentWidth) {
-    const kind = item.kind === 'deck' ? item.interactionKind ?? 'decision' : 'review';
+    const kind = item.kind === 'page'
+        ? item.awaitsResponse === false ? 'display' : item.dialect === 'html' ? 'rich' : 'interactive'
+        : item.kind;
     const icon = KIND_ICON[kind] ?? '·';
     // The inbox is a title-first triage surface. Origin details remain available
     // after opening a ticket, rather than consuming the list's scarce row width.

package/dist/commands/attention.js

@@ -1,7 +1,7 @@
 // `crtr canvas attention` — aggregate pending human tickets across the canvas.
 //
-// A pending "ticket" is any humanloop interaction awaiting a human: a deck,
-// notification, or anchored review. Each lives in its human bridge node
+// A pending "ticket" is any humanloop interaction awaiting a human: a page or
+// an anchored review. Each lives in its human bridge node
 // directory and is attributed through that bridge's parent relation. This
 // subtree surfaces a direct node projection; cwd is display metadata only.
 //

package/dist/commands/human/doc.js

@@ -1,17 +1,20 @@
-import { existsSync, readFileSync } from 'node:fs';
-import { resolve } from 'node:path';
+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { tmpdir } from 'node:os';
 import { defineBranch, defineLeaf } from '../../core/command.js';
 import { InputError } from '../../core/io.js';
+import { readConfig } from '../../core/config.js';
+import { derivePageManifest } from '../../core/human/page.js';
 import { checkMarkdown, renderMarkdown } from '../../core/termrender/termrender.js';
-function markdownSource(input, context) {
+function documentSource(input, context) {
     const path = input['path'];
     const body = input['body'];
     const stdinProvided = context?.providedParams.has('body') === true;
     if (path === undefined && !stdinProvided) {
         throw new InputError({
             error: 'missing_parameter',
-            message: 'provide exactly one markdown source: PATH or stdin',
-            next: 'Run `crtr human doc check -h` or `crtr human doc render -h` and provide a path or pipe markdown on stdin.',
+            message: 'provide exactly one document source: PATH or stdin',
+            next: 'Run `crtr human doc check -h` or `crtr human doc render -h` and provide a path or pipe a document on stdin.',
         });
     }
     if (path !== undefined && path !== '-' && stdinProvided && body.trim() !== '') {
@@ -19,51 +22,94 @@ function markdownSource(input, context) {
             error: 'bad_invocation',
             message: 'both a positional path and piped stdin were provided',
             field: 'path, body',
-            next: 'Pass exactly one markdown source: either PATH or piped stdin, not both.',
+            next: 'Pass exactly one document source: either PATH or piped stdin, not both.',
         });
     }
     if (path === undefined || path === '-')
-        return body;
+        return { body };
     const abs = resolve(path);
     if (!existsSync(abs)) {
         throw new InputError({
             error: 'file_not_found',
             message: `file not found: ${abs}`,
             field: 'path',
-            next: 'Provide a path to an existing markdown file, or pipe markdown on stdin.',
+            next: 'Provide a path to an existing markdown or HTML file, or pipe a document on stdin.',
         });
     }
-    return readFileSync(abs, 'utf8');
+    return { body: readFileSync(abs, 'utf8'), path: abs };
+}
+function markdownSource(input, context) {
+    return documentSource(input, context).body;
+}
+function pageDialect(source) {
+    const extension = source.path?.toLowerCase();
+    if (extension?.endsWith('.html') || extension?.endsWith('.htm'))
+        return 'html';
+    if (/^\s*<!doctype\b/i.test(source.body) || /^\s*<html(?:\s|>)/i.test(source.body))
+        return 'html';
+    if (source.body.startsWith('---'))
+        return 'md';
+    return undefined;
+}
+function checkPage(source, dialect) {
+    const config = readConfig('user');
+    if (dialect === 'html' && !config.html_pages) {
+        return { ok: false, error: 'HTML page validation requires the user-scope html_pages capability flag to be enabled (html_pages is false).' };
+    }
+    let tempDir;
+    try {
+        const sourcePath = source.path ?? (() => {
+            tempDir = mkdtempSync(join(tmpdir(), 'crtr-human-doc-'));
+            const path = join(tempDir, dialect === 'html' ? 'page.html' : 'page.md');
+            writeFileSync(path, source.body, 'utf8');
+            return path;
+        })();
+        derivePageManifest(sourcePath, dialect, config.page_components);
+        return { ok: true };
+    }
+    catch (error) {
+        return { ok: false, error: error instanceof Error ? error.message : String(error) };
+    }
+    finally {
+        if (tempDir !== undefined)
+            rmSync(tempDir, { recursive: true, force: true });
+    }
 }
 const humanDocCheck = defineLeaf({
     name: 'check',
-    description: 'validate a directive-flavored markdown body',
-    whenToUse: 'validating a deck or review body before submitting it.',
+    description: 'validate a directive-flavored markdown body or page source',
+    whenToUse: 'validating a page source or review body before submitting it.',
     help: {
         name: 'human doc check',
-        summary: 'validate directive-flavored markdown through the pinned managed renderer',
-        guide: 'The pinned renderer runs from a private managed venv and is not on PATH, so this is the only way to validate a deck or review body before submitting it.',
+        summary: 'validate directive-flavored markdown or a page through the managed renderer and page schemas',
+        guide: 'Plain markdown is checked by the pinned renderer. A file with page front matter or an HTML document is parsed as a page; HTML page validation requires the user-scope html_pages capability flag.',
         params: [
-            { kind: 'positional', name: 'path', type: 'path', required: false, constraint: 'Markdown file to validate. Provide exactly one of PATH or stdin; use - to read stdin.' },
-            { kind: 'stdin', name: 'body', required: false, constraint: 'Markdown to validate. Provide exactly one of piped stdin or PATH.' },
+            { kind: 'positional', name: 'path', type: 'path', required: false, constraint: 'Markdown or HTML file to validate. Files ending in .html/.htm, HTML documents beginning with a doctype or <html, and markdown beginning with --- front matter are checked as pages. Provide exactly one of PATH or stdin; use - to read stdin.' },
+            { kind: 'stdin', name: 'body', required: false, constraint: 'Markdown or HTML to validate. Provide exactly one of piped stdin or PATH.' },
         ],
         output: [
             { name: 'ok', type: 'boolean', required: true, constraint: 'True when the markdown is valid.' },
-            { name: 'error', type: 'string', required: false, constraint: 'The renderer validation error when ok is false.' },
+            { name: 'error', type: 'string', required: false, constraint: 'The renderer or page-parser validation error when ok is false.' },
         ],
         outputKind: 'object',
-        effects: ['Read-only: invokes the private managed renderer to validate the supplied body.'],
+        effects: ['Read-only: invokes the private managed renderer or page parser to validate the supplied document.'],
+    },
+    run: async (input, context) => {
+        const source = documentSource(input, context);
+        const dialect = pageDialect(source);
+        if (dialect !== undefined)
+            return checkPage(source, dialect);
+        return checkMarkdown(source.body);
     },
-    run: async (input, context) => checkMarkdown(markdownSource(input, context)),
 });
 const humanDocRender = defineLeaf({
     name: 'render',
     description: 'render a directive-flavored markdown body',
-    whenToUse: 'previewing how a deck or review body renders before submitting it.',
+    whenToUse: 'previewing how a page or review body renders before submitting it.',
     help: {
         name: 'human doc render',
         summary: 'render directive-flavored markdown through the pinned managed renderer',
-        guide: 'The pinned renderer runs from a private managed venv and is not on PATH, so this is the only way to render a deck or review body before submitting it.',
+        guide: 'The pinned renderer runs from a private managed venv and is not on PATH, so this is the only way to render a page or review body before submitting it.',
         params: [
             { kind: 'positional', name: 'path', type: 'path', required: false, constraint: 'Markdown file to render. Provide exactly one of PATH or stdin; use - to read stdin.' },
             { kind: 'stdin', name: 'body', required: false, constraint: 'Markdown to render. Provide exactly one of piped stdin or PATH.' },

package/dist/commands/human/prompts.d.ts

@@ -1,12 +1,12 @@
-import type { DeckSource } from '../../core/human/types.js';
+import type { PageSource } from '../../core/human/page-schema.js';
 /** Provenance for crouter tickets. Ticket *identity* comes from the bridge node
  * directory, never ticket data; `nodeId` carries the originating node so a
  * consumer can relate a ticket back to whatever that node belongs to, and
  * `sessionName` is a presentation label only. Review tickets already stamp
- * `nodeId` the same way (`core/review/realize.ts`), so decks match them.
+ * `nodeId` the same way (`core/review/realize.ts`), so pages match them.
  * `nodeId` is stamped even when the daemon is unreachable — losing the label is
  * survivable, losing machine attribution is not. */
-export declare function sourceStamp(): Promise<DeckSource>;
+export declare function sourceStamp(): Promise<PageSource>;
 export declare const humanAsk: import("../../core/command.js").LeafDef;
 export declare const humanNotify: import("../../core/command.js").LeafDef;
 export declare const humanShow: import("../../core/command.js").LeafDef;