toolroll 0.9.104 → 0.9.105

package/dist/server/kit.js

@@ -1,17 +1,7 @@
-/**
- * The revamp kit for server pages: the same markup the React kit (src/browser/kit/) renders, as `Html`, so a
- * server page and a React view built from the kit look and behave alike. Rules: src/design/KIT.md. Look:
- * src/design/kit.css (served with console.css). Words and approval rules: src/design/kit.ts.
- *
- * Everything here escapes by construction (html.ts): strings are text, only `Html` is markup. Behaviour (the
- * composer growing, Stop, the keyboard, overlays, switches) comes from the workspace bundle's kit behaviour
- * (src/browser/kit/behavior.ts), which wires any kit markup the workspace places; every control here still works
- * as plain HTML without it.
- */
+import { advancedShownNow } from "../advanced-view.js";
 import { attributes, html, htmlString, joinHtml, passwordlessRendering, postForm } from "../html.js";
 import { KIT_ICONS, NOT_FOUND, SETTINGS_GROUPS, STATUS, STEP_ROW_WORDS, STEP_WORDS, stepRowBodyId, TIMING_WORDS, approvalAsk, chipOfHeadline, dur, needsWords, stepsFill, termsOf, timingBars, } from "../design/kit.js";
 const cls = (...names) => names.filter(Boolean).join(" ");
-// ---- text and icons ---------------------------------------------------------------------------------------------
 export function icon(name, small = false) {
     const shapes = KIT_ICONS[name].map(shape => shape[0] === "path" ? html `<path${attributes(shape[1])}/>` : shape[0] === "circle" ? html `<circle${attributes(shape[1])}/>` : html `<rect${attributes(shape[1])}/>`);
     return html `<svg class="${cls("k-i", small && "k-i-sm")}" viewBox="0 0 24 24" aria-hidden="true" focusable="false">${shapes}</svg>`;
@@ -25,45 +15,34 @@ export function btn(label, options = {}) {
         return html `<a class="${className}" href="${options.href}"${attributes({ ...named, ...options.attrs })}>${face}</a>`;
     return html `<button class="${className}" type="${options.type ?? "button"}"${attributes({ ...named, ...options.attrs })}>${face}</button>`;
 }
-// ---- status -----------------------------------------------------------------------------------------------------
 export function chip(word, tone = "", options = {}) {
     return html `<span class="${cls("k-chip", tone, options.dot === false && "nodot")}">${word}</span>`;
 }
-/** One of the five status words in its tone. */
 export const status = (key) => chip(STATUS[key].word, STATUS[key].tone);
-/** A task's headline (task-status.ts) as its chip. */
 export function headlineChip(headline) {
     const { word, tone } = chipOfHeadline(headline);
     return chip(word, tone);
 }
-/** A count pill: ink only for a Needs-you count; zero is muted. */
 export function count(n, options = {}) {
     return html `<span class="${cls("k-count", options.ink && n > 0 && "ink", n === 0 && "zero")}">${n}</span>`;
 }
-/** Sections of one object as addresses: a <nav> of links, the current one aria-current="page". */
 export function linkTabs(label, current, items) {
     return html `<nav class="k-tabs" aria-label="${label}">${items.map(item => html `<a href="${item.href}"${item.key === current ? html ` aria-current="page"` : ""}>${item.label}${item.count ?? ""}</a>`)}</nav>`;
 }
-/** Filters or views of a list as addresses: the segmented track. */
 export function segLinks(label, current, items) {
     return html `<nav class="k-seg" aria-label="${label}">${items.map(item => html `<a href="${item.href}"${item.key === current ? html ` aria-current="page"` : ""}>${item.label}${item.count ?? ""}</a>`)}</nav>`;
 }
-/** Filters or views as addresses with icons (List / Board): each item an icon, its label read aloud. */
 export function iconSegLinks(label, current, items) {
     return html `<nav class="k-seg k-seg-icons" aria-label="${label}">${items.map(item => html `<a href="${item.href}" aria-label="${item.label}" title="${item.label}"${item.key === current ? html ` aria-current="page"` : ""}>${icon(item.icon)}</a>`)}</nav>`;
 }
-/** A list's text filter (the workspace narrows the rows on the page as it is typed; without it, a GET form). */
 export function filterInput(options) {
     return html `<label class="k-filter">${icon("search", true)}<input type="search"${attributes({ name: options.name, value: options.value, placeholder: options.placeholder ?? options.label, "aria-label": options.label })}></label>`;
 }
-// ---- fields -----------------------------------------------------------------------------------------------------
-/** A field: label, control, one hint line, and the error slot tied to the control (aria-describedby). */
 export function field(options) {
     return html `<div class="k-field"><label class="k-label" for="${options.id}">${options.label}</label>${options.control}\
 ${options.hint ? html `<p class="k-hint" id="${options.id}-hint">${options.hint}</p>` : ""}\
 <span class="k-err" id="${options.id}-err" role="alert">${options.error ?? ""}</span></div>`;
 }
-/** A text input; `error` marks it invalid and points it at its error line. */
 export function input(options) {
     const describedBy = [options.hint && `${options.id}-hint`, `${options.id}-err`].filter(Boolean).join(" ");
     return html `<input class="k-input" id="${options.id}" name="${options.name}" type="${options.type ?? "text"}"${attributes({ value: options.value, "aria-invalid": options.error ? "true" : undefined, "aria-describedby": describedBy, ...options.attrs })}>`;
@@ -71,9 +50,6 @@ export function input(options) {
 export function textarea(options) {
     return html `<textarea class="k-textarea" id="${options.id}" name="${options.name}" rows="${options.rows ?? 3}"${attributes({ "aria-invalid": options.error ? "true" : undefined, "aria-describedby": `${options.id}-err`, ...options.attrs })}>${options.value ?? ""}</textarea>`;
 }
-/** A native select in the field family, with the chevron: 36px, `sm` 28px in a toolbar, 44px and 16px text on a phone.
- * `chip` draws it as a composer's filled pill (a project inside the message box): still a native select, so it works
- * without script. */
 export function select(options) {
     const opts = options.items.map(item => {
         const [value, label] = typeof item === "string" ? [item, item] : item;
@@ -81,85 +57,56 @@ export function select(options) {
     });
     return html `<span class="${cls("k-selw", options.sm && "sm", options.wide && "wide", options.chip && "k-selw-chip")}"><select class="k-sel"${attributes({ id: options.id, name: options.name, "aria-label": options.label, ...options.attrs })}>${opts}</select></span>`;
 }
-/** An on/off setting in a form: a checkbox with role=switch and a visible label (posts `name=on` when on). */
 export function switchInput(options) {
     return html `<label class="k-switch"><input class="k-switch-input" type="checkbox" role="switch" id="${options.id}" name="${options.name}"${options.on ? html ` checked` : ""}${attributes(options.attrs ?? {})}><span class="k-trk" aria-hidden="true"></span><span>${options.label}</span></label>`;
 }
-/** An on/off choice inside a composer, drawn as a filled pill chip whose mark fills when on: a checkbox with
- * role=switch (posts `name=value` when on), so it works without script. Its longer words go under the box (`note`). */
 export function toggleChip(options) {
     return html `<label class="k-tchip"><input class="k-switch-input" type="checkbox" role="switch" id="${options.id}" name="${options.name}"${options.on ? html ` checked` : ""}${attributes(options.attrs ?? {})}><span class="k-tchip-mark" aria-hidden="true"></span><span>${options.label}</span></label>`;
 }
-/** Two columns: label and one muted line | the control. `inline` keeps the control beside the label on a phone. */
 export function formRow(label, hint, control, variant = "") {
     return html `<div class="${cls("k-frow", variant)}"><div class="k-frow-l"><span class="k-frow-t">${label}</span>${hint ? html `<span class="k-frow-h">${hint}</span>` : ""}</div><div class="k-frow-c">${control}</div></div>`;
 }
-/** Radio cards: one choice from a few, each with a bold label and one muted line. */
 export function radios(options) {
     return html `<fieldset class="k-radios"><legend class="k-sr">${options.legend}</legend>${options.items.map(item => html `<label class="k-opt"><input type="radio" name="${options.name}" value="${item.value}"${item.value === options.current ? html ` checked` : ""}><span><b>${item.label}</b>${item.text ? html `<span>${item.text}</span>` : ""}</span>${item.tag ?? ""}</label>`)}</fieldset>`;
 }
-// ---- blocks -----------------------------------------------------------------------------------------------------
 export const acts = (...buttons) => html `<div class="k-acts">${buttons}</div>`;
 export function facts(rows) {
     return html `<dl class="k-facts">${rows.map(([key, value]) => html `<dt>${key}</dt><dd>${value}</dd>`)}</dl>`;
 }
 export const note = (text) => html `<p class="k-note">${text}</p>`;
-/** A refusal or problem, where it happened (role=alert): what went wrong and what didn't change. */
 export const notice = (text) => html `<p class="k-notice" role="alert">${icon("alert", true)}<span>${text}</span></p>`;
-/** One neutral system line (a builder offline, an update): not a failure, never the needs-you mark. */
 export const infoLine = (text) => html `<p class="k-notice info">${text}</p>`;
 export function empty(options) {
     return html `<div class="k-empty"><p class="k-empty-t">${options.title}</p>${options.text ? html `<p class="k-empty-x">${options.text}</p>` : ""}${options.action ?? ""}</div>`;
 }
-/** A disclosure for secondary detail. */
 export const disclose = (summary, body, open = false) => html `<details class="k-disclose"${open ? html ` open` : ""}><summary>${summary}</summary>${body}</details>`;
-// ---- lists ------------------------------------------------------------------------------------------------------
-/** A group heading with its count; `right` puts one quiet tool at its end. */
 export const group = (label, n, right) => html `<h2 class="k-grp">${label}${n ?? ""}${right ? html `<span class="k-grow"></span>${right}` : ""}</h2>`;
-/** A list row: chip · title (the whole row is the link) · one muted line · meta · one action, always in one column. */
 export function row(options) {
-    // No href: a thing with no page of its own (a computer); its title is text and its action is the way in.
     const title = options.href === undefined ? html `<span class="k-row-t">${options.title}</span>` : html `<a class="k-row-t" href="${options.href}">${options.title}</a>`;
     return html `<div class="${cls("k-row", options.wait && "wait", options.href === undefined && "k-row-static")}"${attributes(options.attrs ?? {})}><span class="k-row-c">${options.chip}</span>\
 ${title}<span class="k-row-d">${options.desc ?? ""}</span>\
 <span class="k-row-m">${options.meta ?? ""}</span><span class="k-row-a">${options.action ?? ""}</span>${options.message ? html `<div class="k-row-msg">${options.message}</div>` : ""}</div>`;
 }
-// ---- page headers -----------------------------------------------------------------------------------------------
-/** The phone header: back (or nothing), the title, one trailing action. Hidden at a desk. */
 export function phoneHeader(title, options = {}) {
     return html `<header class="k-ph">${options.back ? btn("Back", { variant: "ghost", iconOnly: "back", href: options.back }) : ""}<p class="k-ph-t">${title}</p>${options.trailing ?? ""}</header>`;
 }
-/** A list page's header: the phone header and the desk top bar (title · muted context · spacer · tools). */
 export function pageHeader(title, options = {}) {
     const phone = phoneHeader(options.phoneTitle ?? title, { ...(options.back ? { back: options.back } : {}), ...(options.trailing ? { trailing: options.trailing } : {}) });
     return html `${phone}<div class="k-tb"><h1>${title}</h1>${options.ctx ? html `<span class="k-tb-ctx">${options.ctx}</span>` : ""}${options.right ? html `<span class="k-grow"></span>${options.right}` : ""}</div>`;
 }
-/** A reading page's header: a back link, the one h1, a meta line. `same` when the phone header already shows the
- * title: the h1 stays for assistive tech and is drawn once. */
 export function docHeader(options) {
     return html `${options.back ? html `<a class="k-backlink" href="${options.back[0]}">${icon("back", true)}${options.back[1]}</a>` : ""}\
 <header class="k-dh"><div><h1${options.same ? html ` class="k-same"` : ""}>${options.title}</h1>${options.meta ? html `<p class="k-dh-meta">${options.meta}</p>` : ""}</div>${options.right ?? ""}</header>`;
 }
 export const doc = (...parts) => html `<div class="k-doc">${parts}</div>`;
-// ---- approval ---------------------------------------------------------------------------------------------------
-/** The four fixed slots: status (chip + heading) · supporting text · actions · terms, plus the error slot. The same
- * slots in every state (waiting, approved, automatic, refused), so nothing moves. `body`: the choice the act takes
- * (radio cards, a note), between the text and the actions. */
 export function slots(options) {
     return html `<section class="${cls("k-slots", options.wait && "wait")}"${attributes(options.attrs ?? {})}><div class="k-slot-status">${options.status}</div>\
 <p class="k-slot-text">${options.text}</p>${options.body === undefined ? "" : html `<div class="k-slot-body">${options.body}</div>`}<div class="k-slot-acts k-acts">${options.acts}</div><p class="k-slot-terms">${options.terms}</p>\
 <div class="k-slot-err">${options.err ? notice(options.err) : ""}</div></section>`;
 }
-/** This request's approval facts: Passwordless as the request sees it, plus what the page read for this act. */
 export function approvalFactsNow(read = { remembered: false }) {
     return { ...read, passwordless: passwordlessRendering() };
 }
-/**
- * The control that approves one act, inside its slots: a POST form with the act's button and, only when the rules
- * say so, the password field (name `token`, as every ceremony reads it). Automatic approval renders nothing to
- * press. The page decides only what it shows: the server proves the person, the freshness and the scope again
- * when the form arrives.
- */
 export function approveForm(options) {
     const ask = approvalAsk(options.kind, options.facts);
     if (ask === "automatic")
@@ -169,27 +116,20 @@ export function approveForm(options) {
         ? html `<div class="k-reauth k-field"><label class="k-label" for="${fieldId}">Your password</label><input class="k-input" id="${fieldId}" type="password" name="token" autocomplete="current-password" required></div>`
         : html ``;
     const button = btn(options.label, { variant: options.primary === false ? "outline" : "primary", type: "submit", ...(options.docked ? { docked: true } : {}) });
-    // An approval is made inside a signed-in request: its CSRF field is not optional, whatever a caller passes.
     if (options.form !== undefined && "signedOut" in options.form)
         throw new Error("approveForm: an approval form always carries the request's CSRF field");
-    // The k-approve class is GuardedHtml's stale-approval marker: a caller's classes join it, never replace it.
     const extra = options.form?.attrs ?? {};
     const classes = ["k-approve", ...(typeof extra["class"] === "string" ? extra["class"].split(/\s+/).filter(name => name !== "" && name !== "k-approve") : [])].join(" ");
     const formOptions = { ...options.form, attrs: { ...extra, class: classes, "data-approval-kind": options.kind } };
     return postForm(options.action, html `${options.before ?? ""}${password}<div class="k-acts">${button}</div>`, formOptions);
 }
-/** The terms line for an act, from the same rules. */
 export const approvalTerms = (kind, facts) => termsOf(kind, facts);
-/** Waits that aren't tasks, on their own page (a spend limit, a failed backup): one ink outline, a count, items
- * split by hairlines, each with its one action. They never join the global Needs-you count. */
 export function needsPanel(items, label = "Needs you") {
     if (items.length === 0)
         return html ``;
     return html `<section class="k-needs" aria-label="${label}"><h2 class="k-needs-h">${label} ${count(items.length, { ink: true })}</h2>\
 ${items.map(item => html `<div class="k-needs-item"><div><b>${item.title}</b>${item.text ? html `<p>${item.text}</p>` : ""}</div>${item.action ? html `<div class="k-acts">${item.action}</div>` : ""}</div>`)}</section>`;
 }
-// ---- timing -----------------------------------------------------------------------------------------------------
-/** A run's steps on one elapsed-time axis (Release, a flow's run, a pull request's checks). */
 export function timing(options) {
     const bars = timingBars(options.rows, options.scale);
     const mark = (st) => st === "wait" ? html `<span class="k-wd"></span>` : st === "q" ? html `<span class="k-qd"></span>` : st === "run" ? html `<span class="k-rund"></span>` : icon(st === "ok" ? "check" : "x", true);
@@ -205,34 +145,28 @@ export function timing(options) {
 <div class="k-timing-b"><div class="k-crow head" aria-hidden="true"><span></span><span>${options.head ?? "Step"}</span><span class="k-crow-lane">Elapsed time</span><span>Status</span><span class="k-crow-s">Time</span></div>${rows}</div>\
 <div class="k-timing-f">${options.foot ?? ""}</div></section>`;
 }
-// ---- progress line and board -----------------------------------------------------------------------------------
-/** A few named steps on one line, filled up to where the work is. */
 export function steps(items, label = "Progress") {
     return html `<ol class="k-steps" aria-label="${label}" style="--k-n:${items.length};--k-fill:${stepsFill(items).toFixed(3)}"><span class="k-steps-fill" aria-hidden="true"></span>\
 ${items.map(step => html `<li class="k-step ${step.state}"${step.state === "now" || step.state === "live" || step.state === "failed" ? html ` aria-current="step"` : ""} aria-label="${step.label}: ${STEP_WORDS[step.state]}${step.sub ? `, ${step.sub}` : ""}"><b aria-hidden="true"></b><span class="k-step-l" aria-hidden="true">${step.label}</span><span class="k-step-s" aria-hidden="true">${step.sub ?? ""}</span></li>`)}</ol>`;
 }
-/** The board's columns; on a phone one at a time (`on`). */
 export const board = (label, ...columns) => html `<div class="k-board" role="region" aria-label="${label}">${columns}</div>`;
 export function boardCol(options) {
     return html `<section class="${cls("k-col", options.on && "on")}" aria-label="${options.label}"><h2 class="${cls("k-col-h", options.needs && "needs")}">${options.label}${options.count ?? ""}</h2>\
 ${options.cards.length > 0 ? options.cards : html `<p class="k-col-e">${options.empty}</p>`}</section>`;
 }
 export const card = (options) => html `<a class="k-card" href="${options.href}"><span class="k-card-t">${options.title}</span><span class="k-card-m">${options.meta}</span></a>`;
-// ---- pages ------------------------------------------------------------------------------------------------------
-/** The not-found page, inside the shell: what was asked for and two ways on. */
 export function notFound(path, options = {}) {
     return html `${pageHeader("Not found")}<div class="k-nf">${empty({
         title: options.title ?? NOT_FOUND.title(path), text: options.text ?? NOT_FOUND.text,
         action: acts(btn("Go to Home", { sm: true, href: "/" }), btn("Open Tasks", { sm: true, variant: "ghost", href: "/tasks" })),
     })}</div>`;
 }
-/** The Settings frame: Overview and the eight groups, a desk breadcrumb, a phone back header, one column. */
 export function settingsShell(options) {
     const flags = options.flags ?? {};
     const own = SETTINGS_GROUPS.find(([, slug]) => slug === options.group);
     const hub = options.group === "hub" || own === undefined;
     const nav = html `<a class="k-nav k-nav-top" href="/settings"${hub ? html ` aria-current="page"` : ""}><span class="k-nav-l">Overview</span></a>\
-${SETTINGS_GROUPS.map(([label, slug, href]) => html `<a class="k-nav" href="${href}"${slug === options.group ? html ` aria-current="page"` : ""}><span class="k-nav-l">${label}</span>${flags[slug] ? html `<span class="k-nav-flag" aria-hidden="true"></span><span class="k-sr"> (needs you)</span>` : ""}</a>`)}`;
+${SETTINGS_GROUPS.filter(([, slug]) => slug !== "spend" || advancedShownNow()).map(([label, slug, href]) => html `<a class="k-nav" href="${href}"${slug === options.group ? html ` aria-current="page"` : ""}><span class="k-nav-l">${label}</span>${flags[slug] ? html `<span class="k-nav-flag" aria-hidden="true"></span><span class="k-sr"> (needs you)</span>` : ""}</a>`)}`;
     const back = options.back ?? (hub ? undefined : options.sub ? own[2] : "/settings");
     const crumbs = hub ? html `` : options.sub
         ? html `<nav class="k-tb-ctx k-crumbs" aria-label="Breadcrumb"><a href="${own[2]}">${own[0]}</a><span class="k-sep" aria-hidden="true">/</span><b aria-current="page">${options.title}</b></nav>`
@@ -240,22 +174,12 @@ ${SETTINGS_GROUPS.map(([label, slug, href]) => html `<a class="k-nav" href="${hr
     return html `${phoneHeader(hub ? "Settings" : options.title, back ? { back } : {})}<div class="k-tb"><h1>Settings</h1>${crumbs}</div>\
 <div class="k-settings"><nav class="k-snav" aria-label="Settings">${nav}</nav><div class="k-sbody"><header><h2 class="${hub ? "k-sr" : "k-same"}">${options.title}</h2>${options.lead ? html `<p>${options.lead}</p>` : ""}</header>${options.body}</div></div>`;
 }
-// ---- composer ---------------------------------------------------------------------------------------------------
-/** The round send, an arrow up; with `stop` it carries its Stop twin (the composer's .working class swaps them).
- * `gate` (a message box) marks it aria-disabled while the box is empty. */
 export function sendButton(options = {}) {
     const label = options.label ?? "Send";
     const gated = options.gate === true && options.empty !== false;
     return html `<span class="k-send-slot"><button class="k-send" type="submit" aria-label="${label}" title="${label}"${attributes({ name: options.name, "data-gate": options.gate ? "1" : undefined, "aria-disabled": gated ? "true" : undefined, ...options.attrs })}>${icon("send")}</button>\
 ${options.stop ? html `<button class="k-send k-stop" type="button" aria-label="${options.stop.label ?? "Stop"}" title="${options.stop.label ?? "Stop"}"${attributes(options.stop.attrs ?? {})}>${icon("stop")}</button>` : ""}</span>`;
 }
-/**
- * The message box: one filled rounded object, the textarea grows from `rows` to `maxRows` lines then scrolls,
- * one bottom row inside (+ menu, the project as a filled pill chip, toggle chips, the round send); its note and its
- * refusal sit under the box (all inside `.k-composer-field`). Textarea
- * `<id>-text` (named `name`), refusal slot `<id>-err`, chosen project a hidden input `<id>-project` (named
- * `projectName`). A refused send keeps the words in the box with the reason in the error slot.
- */
 export function composer(options) {
     const value = options.value ?? "";
     const textId = `${options.id}-text`;
@@ -272,9 +196,6 @@ export function composer(options) {
 <div class="k-composer-bar">${plus}${project}${options.before ?? ""}<span class="k-grow"></span>${options.send}</div></div>\
 ${options.note ? html `<p class="k-note k-composer-note">${options.note}</p>` : ""}<div class="k-composer-err k-err" id="${options.id}-err" role="alert">${options.error ?? ""}</div></div>`;
 }
-/** A floating panel, hidden until its trigger (`overlayTrigger`) opens it: role=dialog, a labelled Close, Escape
- * and the scrim close it, Tab stays inside, focus returns to the trigger. A popover and a menu become a bottom
- * sheet on a phone. */
 export function overlay(options) {
     const titleId = `${options.id}-title`;
     const close = btn("Close", { variant: "ghost", iconOnly: "x", sm: options.kind === "popover" || options.kind === "menu", attrs: { "data-k-close": "" } });
@@ -288,30 +209,18 @@ export function overlay(options) {
     const inner = options.kind === "drawer" ? html `${head}<div class="k-drawer-b">${body}</div>` : options.kind === "sheet" ? html `${head}<div class="k-sheet-b">${body}</div>` : html `${head}${body}`;
     return html `<div class="${className}" id="${options.id}" role="dialog" aria-modal="true" aria-labelledby="${titleId}" data-k-overlay="${options.kind}" tabindex="-1" hidden>${inner}</div>`;
 }
-/** The button that opens an overlay. */
 export function overlayTrigger(label, overlayId, options = {}) {
     return btn(label, { ...options, attrs: { "data-k-open": overlayId, "aria-haspopup": "dialog", "aria-controls": overlayId, ...options.attrs } });
 }
-// ---- phone dock -------------------------------------------------------------------------------------------------
-/** The phone dock: this screen's one primary (the same act the card hides on a phone). */
 export function dock(primary) {
     return primary === null ? html `` : html `<div class="k-dock"><div class="k-dock-primary">${primary}</div></div>`;
 }
-/** Several kit parts joined. */
 export const parts = (...values) => joinHtml(values);
-// ---- pages outside the shell (Wave E) ---------------------------------------------------------------------------
-/**
- * A page outside the shell (sign in, the first account, an invite, signed out, an error): the brand, one narrow
- * column with the one h1, then an optional foot line under a hairline. `brand` is the product mark (chrome.ts
- * BRAND_HTML). These pages carry no script: everything on them works as plain HTML.
- */
 export function outPage(options) {
     return html `<div class="k-out"><div class="k-out-c"><a class="k-out-brand" href="${options.brandHref ?? "/"}">${options.brand}</a>\
 <h1>${options.title}</h1>${options.note ? html `<p class="k-out-note" role="status">${options.note}</p>` : ""}${options.sub ? html `<p class="k-out-sub">${options.sub}</p>` : ""}${options.body ?? ""}</div>\
 ${options.foot ? html `<p class="k-out-f">${options.foot}</p>` : ""}</div>`;
 }
-/** A form field outside the shell: label, input, one hint line, and its error line (the field is aria-invalid, described
- * by both and focused when the error is about it). The error is a server's refusal; nothing here validates. */
 export function outField(options) {
     const describedBy = [options.hint ? `${options.id}-hint` : null, options.error ? `${options.id}-err` : null].filter(Boolean).join(" ");
     const control = html `<input class="k-input" id="${options.id}" name="${options.name}" type="${options.type ?? "text"}"${attributes({
@@ -320,9 +229,6 @@ export function outField(options) {
     return html `<div class="k-field"><label class="k-label" for="${options.id}">${options.label}</label>${control}\
 ${options.hint ? html `<p class="k-hint" id="${options.id}-hint">${options.hint}</p>` : ""}${options.error ? html `<p class="k-err" id="${options.id}-err" role="alert">${options.error}</p>` : ""}</div>`;
 }
-/** The steps of one object as the page itself (a task: Plan · Approval · Build · Checks · Ready): an ordered list, a
- * marker on a rail, the label, one sentence and a time per row, and the row's body under it. The current row is
- * `aria-current="step"`. Same markup as `KStepRows`. */
 export function stepRows(items, label = "Steps") {
     return html `<ol class="k-steprows" aria-label="${label}">${items.map(item => {
         const hasBody = item.body !== undefined && htmlString(html `${item.body}`) !== "";
@@ -336,10 +242,6 @@ ${item.at ? html `<time class="k-steprow-time k-num" datetime="${item.at}">${ite
             : html `<div class="k-steprow-head">${head}</div>`}${hasBody ? html `<div class="k-steprow-body" id="${id}"${item.open ? "" : html ` hidden`}>${item.body}</div>` : ""}</div></li>`;
     })}</ol>`;
 }
-// ---- the work -----------------------------------------------------------------------------------------------------
-/** The work's frame (KIT.md "The work"): a header (the title, who is working with a blue dot while it runs, Close), the
- * body that scrolls, and the message box at the foot. The records themselves are followed live by the workspace
- * (`KWork` and `useConversation`); a page without script shows what `body` holds. Same markup as `KWork`. */
 export function work(options) {
     const who = options.who === undefined || htmlString(html `${options.who}`) === "" ? ""
         : html `<p class="k-work-who">${options.live ? html `<span class="k-work-dot" aria-hidden="true"></span>` : ""}<span>${options.who}</span></p>`;
@@ -349,8 +251,6 @@ export function work(options) {
 <header class="k-work-head"><div class="k-work-title"><h2 id="${options.id}-h">${options.title}</h2>${who}</div>${close}</header>\
 <div class="k-work-body" data-agent-scroll="">${options.body ?? ""}</div>${foot}</aside>`;
 }
-/** A short list of steps: a mark, the step and one line, its one action. Done steps read muted with a check; a step
- * being checked shows a static ring (running state never animates). The state is also said in words. */
 export function checklist(steps, label = "Steps") {
     const word = { done: "Done", open: "Not done", checking: "Checking" };
     return html `<ol class="k-check" aria-label="${label}">${steps.map(step => html `<li class="${cls("k-check-row", step.state === "done" && "done")}" data-step="${step.key}">\
@@ -358,41 +258,29 @@ export function checklist(steps, label = "Steps") {
 <span class="k-check-t"><b>${step.title}</b><span>${step.text}</span><span class="k-sr">${word[step.state]}</span></span>\
 <span class="k-check-a">${step.state === "done" ? "" : step.action ?? ""}</span></li>`)}</ol>`;
 }
-// ---- ideas (Wave E) ---------------------------------------------------------------------------------------------
-/** Ideas that draft words into a composer: each is a link that opens the page with the words in the box (no script),
- * and with the kit behaviour it adds them to the box in place (`data-k-draft`, `data-k-into` = the composer id). */
 export function ideas(options) {
     if (options.items.length === 0)
         return html ``;
     return html `<section class="k-sec"><h3>${options.label}</h3><div class="k-ideas">${options.items.map(item => html `<a class="k-btn k-btn-outline k-idea" href="${item.href}" data-k-draft="${item.draft}" data-k-into="${options.into}">${item.label}</a>`)}</div></section>`;
 }
-// ---- settings pages (wave D) ------------------------------------------------------------------------------------
-/** A settings section: its heading (with an optional muted state after it), one muted lead line, then its rows.
- * No nested wells. `id` is also the anchor other pages link to. */
 export function settingsSection(options) {
     const head = `${options.id}-h`;
     return html `<section class="k-ssec" id="${options.id}" aria-labelledby="${head}"><div class="k-secthead"><h3 id="${head}">${options.title}\
 ${options.state ? html `<span class="k-ssec-state">${options.state}</span>` : ""}</h3>${options.right ?? ""}</div>\
 ${options.lead ? html `<p class="k-ssec-lead">${options.lead}</p>` : ""}${options.body}</section>`;
 }
-/** One row that opens a settings page: icon, title (with "1 item needs you" when something waits), one status line,
- * anything on the right, a chevron. The whole row is the link. */
 export function settingsLink(options) {
     const flag = options.needs ? html `<span class="k-sflag">${needsWords(options.needs)}</span>` : "";
     return html `<a class="${cls("k-slink", !options.icon && "noico")}" href="${options.href}">${options.icon ? icon(options.icon) : ""}\
 <span class="k-sl"><span class="k-sl-t"><span>${options.title}</span>${flag}</span>${options.status ? html `<span class="k-sl-h">${options.status}</span>` : ""}</span>\
 <span class="k-slink-r">${options.right ?? ""}</span><span class="k-chev" aria-hidden="true"></span></a>`;
 }
-/** A list of settings links under a section heading ("In this group"), or the overview's unlabelled list. */
 export function settingsLinks(title, links, options = {}) {
     return html `<section class="k-ssec"${title === null ? html ` aria-label="${options.label ?? "All settings"}"` : ""}>${title === null ? "" : html `<div class="k-secthead"><h3>${title}</h3></div>`}\
 <div class="k-slinks">${links}</div></section>`;
 }
-/** A record row (a session, a token, a person, a device, a provider): title and one muted line · when · one action,
- * and anything opened under it (a form, a refusal). */
 export function settingsRecord(options) {
     return html `<div class="k-srec"${attributes(options.attrs ?? {})}><div class="k-sl"><span class="k-sl-t">${options.title}</span>${options.sub ? html `<span class="k-sl-h">${options.sub}</span>` : ""}</div>\
 <span class="k-srec-when">${options.when ?? ""}</span><span class="k-srec-a">${options.action ?? ""}</span>${options.more ? html `<div class="k-srec-more">${options.more}</div>` : ""}</div>`;
 }
-/** A command or path to copy by hand: monospace, selectable. */
 export const codeLine = (text) => html `<code class="k-scode">${text}</code>`;

package/dist/server/last-checks.js

@@ -4,12 +4,10 @@ export class LastChecks {
     known(key) {
         return this.answers.get(key) ?? null;
     }
-    /** Whether the last answer is older than `everyMs` (or missing). */
     due(key, everyMs, now = Date.now()) {
         const last = this.answers.get(key);
         return last === undefined || now - last.at >= everyMs;
     }
-    /** Run the check (one at a time per key) and keep its answer. */
     run(key, check) {
         const pending = this.running.get(key);
         if (pending !== undefined)

package/dist/server/live.js

@@ -12,19 +12,15 @@ import { adapterPolicy } from "./route-policy.js";
 import { requestContext } from "./request-context.js";
 import { createAgentsLiveRooms } from "./agents-live-room.js";
 import { leadTilesFor } from "./agents-live-lead.js";
-/** A page asks for a few rooms at once: its workspace, what it shows, its conversation. */
 export const LIVE_ROOMS_PER_PAGE = 6;
 const ROOM_NAME = /^(workspace|task|flow|chat|team|agent|summary|agents-live)(?::([^?]{1,400}))?(?:\?([^#]{0,600}))?$/;
-/** At most one workspace nudge a second: a burst of writes is one re-read, the first heard at once. */
 const WORKSPACE_SETTLE_MS = 1_000;
-/** A running reply's preview: at most one snapshot every 80 ms; the last one always goes out. */
 const TURN_SETTLE_MS = 80;
 function chatSnapshot(turn) {
     const view = turn.reply?.view() ?? { phase: "working", status: LIVE_STATUS.thinking };
     const steps = (turn.reply?.tools() ?? []).map(calls => ({ tools: calls.map(call => call.label), toolCalls: calls }));
     return { steps, phase: view.phase, status: turn.done ? "" : turn.reply?.status() ?? LIVE_STATUS.thinking, text: view.phase === "writing" ? view.text : "", done: turn.done, ok: turn.ok };
 }
-/** A room's name, read strictly: anything else is not a room. */
 export function parseLiveRoom(name) {
     const match = ROOM_NAME.exec(name);
     if (match === null)
@@ -63,13 +59,10 @@ export function parseLiveRoom(name) {
     }
     return null;
 }
-/** The same session, still signed in, from the cookie and the account (never this request's context): a live room's and
- * a live terminal's re-proof. Null when it was signed out, ended elsewhere, revoked, rotated or re-roled. */
 export function rereadBrowser(runtime, request, who) {
     const again = runtime.identify(request, false);
     if (again?.via !== "cookie" || again.name !== who.name || again.session.generation !== who.session.generation)
         return null;
-    // The in-memory session may still exist after another process ends the saved session.
     const hash = runtime.sessions.hashOf(again.session);
     const saved = hash === null ? null : runtime.store.webSession(hash), account = runtime.store.accountOf(again.name);
     if (saved === null || account === null || account.revokedAt !== null || account.generation !== again.session.generation
@@ -80,18 +73,12 @@ export function rereadBrowser(runtime, request, who) {
 const json = (response, status, value) => respond(response, status, "application/json", JSON.stringify(value));
 export function createLiveHandlers(runtime, live) {
     const { store, identify, liveCeiling, familyOf, taskRooms, flowRooms, clock, leadPrincipal, taskChatFocus, chatScopeOf, liveTurns, team, visible } = runtime;
-    // The reader's workspace: one room for everyone, nudged by any meaningful write or a clock-bound lapse.
     const workspaceRooms = createLiveRooms(() => `${live.workspaceRevision.current()}:${live.workspaceRevision.expiresAt(clock())}`, null, { bus: live.bus, minIntervalMs: WORKSPACE_SETTLE_MS });
-    // The reader's project states, per account AND scope: the fingerprint IS the snapshot, so each `change` carries it
-    // (`at`). Every delivery re-proves the viewer's scope, so a snapshot read for a wider scope (a cached one, a held
-    // one, one a newcomer would be handed on joining) never reaches a narrowed reader: it hears `gone` instead. Reads
-    // settle: a burst of writes is one read, while every signal still re-proves at once.
     const summaryKey = (account, scope) => JSON.stringify([account, scope]);
     const summaryRooms = createLiveRooms(key => {
         const [account, scope] = JSON.parse(key);
         return live.projectSummaryFor(account, scope);
     }, null, { bus: live.bus, minIntervalMs: WORKSPACE_SETTLE_MS, readSettleMs: WORKSPACE_SETTLE_MS });
-    // A team audience is per actor (and per token): its key carries who reads, the room keeps how to read as them.
     const teamActors = new Map();
     const teamRooms = createLiveRooms(key => {
         const actor = teamActors.get(key);
@@ -99,10 +86,7 @@ export function createLiveHandlers(runtime, live) {
         return cursor === null ? null : String(cursor);
     }, null, { bus: live.bus });
     const chatViewers = new Set();
-    // One agent's open view (Agents board): what it shows, keyed by the exact run.
     const agentRooms = createLiveRooms(run => agentRunFingerprint(store, run), null, { bus: live.bus });
-    // The Live grid: one room per viewer and scope, watching only (no lease, no seen mark).
-    // Each Live page's own lead tiles, read as its viewer's saved session now (a page's room key carries the page).
     const liveLeads = new Map();
     const agentsLive = createAgentsLiveRooms({ store, bus: live.bus, evidenceRoot: runtime.evidenceRoot, localRunner: runtime.options.localRunner, clock, visible,
         leads: key => liveLeads.get(key)?.() ?? null, forget: key => liveLeads.delete(key) });
@@ -113,16 +97,13 @@ export function createLiveHandlers(runtime, live) {
         try {
             valid = viewer.valid(thread);
         }
-        catch { /* Failed proof stops this room. */ }
+        catch { }
         if (!valid) {
             viewer.connection.send(viewer.room, "gone");
             viewer.connection.refuse(() => viewer.leave());
         }
         return valid;
     }
-    /** A running reply for one viewer's thread: snapshots while it runs, then the last one. Every snapshot goes through
-     * one serialized sender (live-reply.ts): one in flight, the newest waiting, standing re-proved before each, and the
-     * last one only after the sender has closed, so no preview lands after it. */
     function follow(viewer, thread) {
         if (!admitted(viewer, thread))
             return;
@@ -145,14 +126,12 @@ export function createLiveHandlers(runtime, live) {
         viewer.detach = stop;
         sender.offer(chatSnapshot(turn));
     }
-    /** A reply starts on a thread: whoever has that conversation open follows it. */
     function turnStarted(thread) {
         for (const viewer of chatViewers) {
             if (admitted(viewer) && store.liveLeadThreadFor(viewer.name, viewer.scope)?.id === thread)
                 follow(viewer, thread);
         }
     }
-    /** The actor a team stream reads as, and how it is proved again while open. */
     function teamActorOf(request, who) {
         const account = store.accountOf(who.name);
         if (account === null || account.revokedAt !== null)
@@ -163,7 +142,6 @@ export function createLiveHandlers(runtime, live) {
         }
         const principal = who.principal;
         if (principal !== undefined) {
-            // An API token is re-proved against the store every time: unrevoked, unexpired, inside its project limit.
             const actor = { name: principal.account, generation: principal.generation, principal };
             return { actor, key: principal.tokenId, valid: () => {
                     const again = reproveRemote(store, principal, clock());
@@ -173,7 +151,6 @@ export function createLiveHandlers(runtime, live) {
                     return true;
                 } };
         }
-        // A password bearer is proved again once TEAM_PASSWORD_REVERIFY_MS has passed since it last was.
         const actor = { name: who.name, generation: who.generation };
         let provedAt = clock().getTime();
         return { actor, key: "password", valid: () => {
@@ -203,7 +180,6 @@ export function createLiveHandlers(runtime, live) {
         const rooms = names.map(name => ({ name, room: parseLiveRoom(name) }));
         if (rooms.some(one => one.room === null) || rooms.filter(one => one.room?.kind === "agent").length > 1 || rooms.filter(one => one.room?.kind === "workspace").length > 1 || rooms.filter(one => one.room?.kind === "chat").length > 1 || rooms.filter(one => one.room?.kind === "team").length > 1 || rooms.filter(one => one.room?.kind === "summary").length > 1 || rooms.filter(one => one.room?.kind === "agents-live").length > 1)
             return json(response, 400, { error: "room" });
-        // Admit every room before the stream opens, with the answers each page's own stream gave.
         const joins = [];
         let refusedJoin = false;
         for (const { name, room } of rooms) {
@@ -230,7 +206,6 @@ export function createLiveHandlers(runtime, live) {
                 const signedIn = sameBrowser(request, browser);
                 const valid = () => signedIn() && live.projectScopeFor(who.name) === scope;
                 joins.push(connection => {
-                    // Proved before the room is made or read: an invalid viewer never causes a look at a file.
                     let ok = false;
                     try {
                         ok = valid();
@@ -243,7 +218,6 @@ export function createLiveHandlers(runtime, live) {
                         refusedJoin = true;
                         return;
                     }
-                    // Each page's own room (its key carries this connection): a newcomer is never handed a digest computed earlier.
                     const key = agentsLive.keyOf(who.name, scope, randomBytes(9).toString("hex"));
                     liveLeads.set(key, () => { const again = readBrowser(request, browser); return again === null ? null : leadTilesFor(runtime, again); });
                     agentsLive.rooms.join(key, { name: who.name, room: name, connection, valid });
@@ -256,7 +230,6 @@ export function createLiveHandlers(runtime, live) {
                     return json(response, 404, { error: "task" });
                 const repo = family.root.repo, root = family.root.id, signedIn = sameBrowser(request, browser);
                 joins.push(connection => taskRooms.join(root, { name: who.name, room: name, connection,
-                    // A sign-out or a narrowed account stops it.
                     valid: () => signedIn() && rowVisible(liveCeiling(), repo) && store.accountCanAccess(who.name, repo) }));
             }
             else if (room.kind === "agent") {
@@ -265,10 +238,7 @@ export function createLiveHandlers(runtime, live) {
                 const repo = run === null ? null : store.refForId(run.taskRef)?.repo ?? null;
                 if (run === null || repo === null || !visible(repo) || !store.accountCanAccess(who.name, repo))
                     return json(response, 404, { error: "run" });
-                // A repair is its build's own activity: its room is the build's.
                 const signedIn = sameBrowser(request, browser), runId = boardRunOf(store, run.id);
-                // The watch lease (agent-board.ts watchingAgent) is held by the shell's keyed POST /agents/watch on each keep-alive
-                // and released on unload (easy-start N1): this stream only reads, so a stolen cookie can't hold one to quiet pings.
                 joins.push(connection => {
                     agentRooms.join(runId, { name: who.name, room: name, connection,
                         valid: () => signedIn() && rowVisible(liveCeiling(), repo) && store.accountCanAccess(who.name, repo) });
@@ -304,7 +274,6 @@ export function createLiveHandlers(runtime, live) {
                     if (principal === null)
                         return false;
                     const thread = store.liveLeadThreadFor(again.name, scope);
-                    // Even the default lead room is bound to the projects admitted when its thread opened.
                     if (thread !== null && thread.ceilingDigest !== principal.ceilingDigest)
                         return false;
                     if (expectedThread !== undefined && thread?.id !== expectedThread)
@@ -347,8 +316,6 @@ export function createLiveHandlers(runtime, live) {
                     return json(response, 403, initial);
                 const key = JSON.stringify([proved.actor.name, proved.actor.generation, proved.key, room.conversation ?? ""]);
                 teamActors.set(key, proved.actor);
-                // The token or session proves itself again, then reads the room as it now stands: a narrowed project limit or a
-                // lost membership is a lost room. The room's cursor reads as the latest proof.
                 const valid = () => {
                     if (!proved.valid())
                         return false;
@@ -361,11 +328,9 @@ export function createLiveHandlers(runtime, live) {
         response.writeHead(200, { "content-type": "text/event-stream", "cache-control": "no-store", "x-content-type-options": "nosniff", "x-accel-buffering": "no" });
         response.flushHeaders();
         const connection = new LiveConnection(response);
-        // Each join below adds its room before the next speaks; a chat room alone keeps the stream open too.
         for (const join of joins)
             if (connection.open)
                 join(connection);
-        // A page whose only room was refused at its join ends now (`ended`), its keep-alive stopped, not left open.
         if (refusedJoin && connection.rooms === 0)
             connection.refuse(() => connection.close());
         request.once("close", () => connection.close());

package/dist/server/merge-ready-view.js

@@ -1,12 +1,6 @@
-/** The task page's "Can I merge?" panel (docs/plans/plain-toolroll.md P1.6): the checklist (merge-checklist.ts) with
- * each blocker's act as the form this page already posts for it. Run checks is the Checks row's own post; Retry is the
- * failed box's own requeue (the page shows it only where that box would); Ask the agent to fix is Send back: the same
- * post to /r/<build>/comment with intent=revise that the result's Send back makes, its note prefilled with the blocker
- * and editable, sealing the same saved notes. Only a signed-in approver gets the forms; anyone else reads the rows. */
 import { randomBytes } from "node:crypto";
 import { checklistFromAssignment } from "../merge-checklist.js";
 import { isRevisionFeedback, revisionBatchOf, revisionSourceOf } from "../result-review.js";
-/** The panel for a task page, or null when there is no result to merge yet. */
 export function mergeReadyViewOf(store, taskId, assignment, who, runChecks, returnTo) {
     if (assignment == null || assignment.receipt === null)
         return null;