toolroll 0.9.83 → 0.9.84

package/dist/settings-kit-script.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The settings kit's one script (docs/plans/settings-revamp.md §4), shipped as a page's functional script beside kit
+ * forms (settings-kit.ts). Without it every kit form works as today: the proof field shows inline and Save posts.
+ *
+ * With it, a kit form that asks for a proof:
+ * - moves its server-written proof field into the `<dialog>` inside the same form (the field never leaves the form);
+ * - opens the dialog on submit instead of posting, remembering the pressed button;
+ * - Confirm (its button, or Enter in the field) posts the form with that button (`requestSubmit(submitter)`, after the
+ *   submit event that asked has finished), so its name=value and every hidden term go along unchanged; Cancel (or
+ *   Escape) closes it and posts nothing, and focus returns to the button;
+ * - once a kit form posts, it is pending: further submits are dropped and its Save and Confirm are disabled (after the
+ *   post has taken their values), until the page is shown again or the post was cancelled — never on a timer;
+ * - asks for nothing when the proof was left out (Passwordless) — there is no dialog then — and shows the
+ *   identity-provider link when the sign-in swapped the field.
+ * Each section's Save bar names what changed. The script never reads or sets a field's value except to check that a
+ * required proof isn't empty; the server still proves everything.
+ */
+export declare const SETTINGS_KIT_SCRIPT = "(function(){\nif(window.__soKit)return;window.__soKit=1;\nvar d=document;d.documentElement.classList.add(\"kit-js\");\nfunction label(el){var l=el.labels&&el.labels[0];if(!l&&el.closest)l=el.closest(\"fieldset\")&&el.closest(\"fieldset\").querySelector(\"legend\");return l?(l.textContent||\"\").replace(/\\s+/g,\" \").trim():(el.name||\"\");}\nfunction prep(f){if(f.__kit)return;f.__kit=1;\nvar bar=f.querySelector(\"[data-kit-state]\");if(bar&&bar.textContent===\"\")bar.textContent=bar.getAttribute(\"data-idle\")||\"\";\nif(!f.hasAttribute(\"data-kit-step-up\"))return;\nvar dl=f.querySelector(\"[data-kit-dialog]\"),p=f.querySelector(\":scope>[data-kit-proof]\");\nif(!dl||!p||typeof dl.showModal!==\"function\"){f.removeAttribute(\"data-kit-step-up\");return;}\ndl.querySelector(\"[data-kit-slot]\").appendChild(p);\np.querySelectorAll(\"[required]\").forEach(function(i){i.removeAttribute(\"required\");i.setAttribute(\"data-kit-required\",\"\");});\ndl.addEventListener(\"close\",function(){if(f.__kitSent)return;var back=f.__kitBy||f.querySelector(\".kit-save\");if(back&&back.focus)back.focus();});}\nfunction scan(root){if(root.querySelectorAll)root.querySelectorAll(\"form.kit-form\").forEach(prep);}\nscan(d);\nif(typeof MutationObserver!==\"undefined\")new MutationObserver(function(list){list.forEach(function(m){m.addedNodes.forEach(function(n){if(n.nodeType===1){if(n.matches&&n.matches(\"form.kit-form\"))prep(n);scan(n);}});});}).observe(d.documentElement,{childList:true,subtree:true});\nfunction asks(dl){var slot=dl.querySelector(\"[data-kit-slot]\");return !!slot.querySelector(\"input:not([type=hidden]),a,.sso-step-up\");}\nfunction confirm(f){var dl=f.querySelector(\"[data-kit-dialog]\"),miss=null;\ndl.querySelectorAll(\"[data-kit-required]\").forEach(function(i){if(!miss&&i.value===\"\")miss=i;});\nif(miss){miss.setCustomValidity(\"Enter your password.\");miss.reportValidity();miss.focus();return;}\nvar by=f.__kitBy&&f.__kitBy.form===f?f.__kitBy:null;f.__kitSent=1;dl.close();\nsetTimeout(function(){f.__kitGo=1;try{by?f.requestSubmit(by):f.requestSubmit();}finally{f.__kitGo=0;}},0);}\nfunction buttons(f){return f.querySelectorAll(\".kit-save,[data-kit-confirm]\");}\nfunction release(f){f.__kitPending=0;f.__kitSent=0;buttons(f).forEach(function(b){b.disabled=false;});}\nfunction latch(f,e){f.__kitPending=1;setTimeout(function(){if(e.defaultPrevented){release(f);return;}\nbuttons(f).forEach(function(b){b.disabled=true;});},0);}\naddEventListener(\"pageshow\",function(){d.querySelectorAll(\"form.kit-form\").forEach(release);});\nd.addEventListener(\"submit\",function(e){var f=e.target;if(!f||!f.classList||!f.classList.contains(\"kit-form\"))return;prep(f);\nif(f.__kitPending){e.preventDefault();e.stopImmediatePropagation();return;}\nvar dl=f.hasAttribute(\"data-kit-step-up\")?f.querySelector(\"[data-kit-dialog]\"):null;\nif(f.__kitGo||!dl||!asks(dl)){latch(f,e);return;}\ne.preventDefault();e.stopImmediatePropagation();\nif(dl.open){confirm(f);return;}\nf.__kitBy=e.submitter||null;f.__kitSent=0;dl.showModal();\nvar first=dl.querySelector(\"[data-kit-slot] input:not([type=hidden]),[data-kit-slot] a\")||dl.querySelector(\"[data-kit-confirm]\");if(first)first.focus();},true);\nd.addEventListener(\"click\",function(e){var b=e.target&&e.target.closest?e.target.closest(\"[data-kit-confirm],[data-kit-cancel]\"):null;if(!b)return;\nvar dl=b.closest(\"[data-kit-dialog]\"),f=dl&&dl.closest(\"form\");if(!f)return;e.preventDefault();\nif(b.hasAttribute(\"data-kit-cancel\")){dl.close();return;}confirm(f);});\nd.addEventListener(\"input\",function(e){var t=e.target;if(t&&t.setCustomValidity&&t.hasAttribute&&t.hasAttribute(\"data-kit-required\"))t.setCustomValidity(\"\");},true);\nfunction changed(e){var t=e.target,f=t&&t.form;if(!f||!f.classList.contains(\"kit-form\")||t.closest(\"[data-kit-dialog]\")||t.type===\"hidden\")return;prep(f);\nvar bar=f.querySelector(\"[data-kit-save-bar]\"),state=f.querySelector(\"[data-kit-state]\");if(!bar||!state)return;\nf.__kitChanged=f.__kitChanged||[];var name=label(t);if(name&&f.__kitChanged.indexOf(name)<0)f.__kitChanged.push(name);\nbar.setAttribute(\"data-changed\",\"\");state.textContent=\"Changed: \"+f.__kitChanged.join(\", \");}\nd.addEventListener(\"input\",changed);d.addEventListener(\"change\",changed);\n})();";
+/** The pages that wear the settings frame: one column, no Crew sheet, a breadcrumb under Settings. Here (not in
+ * settings-kit.ts) so the browser bundle reads it without the server's form contracts. */
+export declare function isSettingsFrame(pathname: string): boolean;

package/dist/settings-kit-script.js

@@ -0,0 +1,67 @@
+/**
+ * The settings kit's one script (docs/plans/settings-revamp.md §4), shipped as a page's functional script beside kit
+ * forms (settings-kit.ts). Without it every kit form works as today: the proof field shows inline and Save posts.
+ *
+ * With it, a kit form that asks for a proof:
+ * - moves its server-written proof field into the `<dialog>` inside the same form (the field never leaves the form);
+ * - opens the dialog on submit instead of posting, remembering the pressed button;
+ * - Confirm (its button, or Enter in the field) posts the form with that button (`requestSubmit(submitter)`, after the
+ *   submit event that asked has finished), so its name=value and every hidden term go along unchanged; Cancel (or
+ *   Escape) closes it and posts nothing, and focus returns to the button;
+ * - once a kit form posts, it is pending: further submits are dropped and its Save and Confirm are disabled (after the
+ *   post has taken their values), until the page is shown again or the post was cancelled — never on a timer;
+ * - asks for nothing when the proof was left out (Passwordless) — there is no dialog then — and shows the
+ *   identity-provider link when the sign-in swapped the field.
+ * Each section's Save bar names what changed. The script never reads or sets a field's value except to check that a
+ * required proof isn't empty; the server still proves everything.
+ */
+export const SETTINGS_KIT_SCRIPT = `(function(){
+if(window.__soKit)return;window.__soKit=1;
+var d=document;d.documentElement.classList.add("kit-js");
+function label(el){var l=el.labels&&el.labels[0];if(!l&&el.closest)l=el.closest("fieldset")&&el.closest("fieldset").querySelector("legend");return l?(l.textContent||"").replace(/\\s+/g," ").trim():(el.name||"");}
+function prep(f){if(f.__kit)return;f.__kit=1;
+var bar=f.querySelector("[data-kit-state]");if(bar&&bar.textContent==="")bar.textContent=bar.getAttribute("data-idle")||"";
+if(!f.hasAttribute("data-kit-step-up"))return;
+var dl=f.querySelector("[data-kit-dialog]"),p=f.querySelector(":scope>[data-kit-proof]");
+if(!dl||!p||typeof dl.showModal!=="function"){f.removeAttribute("data-kit-step-up");return;}
+dl.querySelector("[data-kit-slot]").appendChild(p);
+p.querySelectorAll("[required]").forEach(function(i){i.removeAttribute("required");i.setAttribute("data-kit-required","");});
+dl.addEventListener("close",function(){if(f.__kitSent)return;var back=f.__kitBy||f.querySelector(".kit-save");if(back&&back.focus)back.focus();});}
+function scan(root){if(root.querySelectorAll)root.querySelectorAll("form.kit-form").forEach(prep);}
+scan(d);
+if(typeof MutationObserver!=="undefined")new MutationObserver(function(list){list.forEach(function(m){m.addedNodes.forEach(function(n){if(n.nodeType===1){if(n.matches&&n.matches("form.kit-form"))prep(n);scan(n);}});});}).observe(d.documentElement,{childList:true,subtree:true});
+function asks(dl){var slot=dl.querySelector("[data-kit-slot]");return !!slot.querySelector("input:not([type=hidden]),a,.sso-step-up");}
+function confirm(f){var dl=f.querySelector("[data-kit-dialog]"),miss=null;
+dl.querySelectorAll("[data-kit-required]").forEach(function(i){if(!miss&&i.value==="")miss=i;});
+if(miss){miss.setCustomValidity("Enter your password.");miss.reportValidity();miss.focus();return;}
+var by=f.__kitBy&&f.__kitBy.form===f?f.__kitBy:null;f.__kitSent=1;dl.close();
+setTimeout(function(){f.__kitGo=1;try{by?f.requestSubmit(by):f.requestSubmit();}finally{f.__kitGo=0;}},0);}
+function buttons(f){return f.querySelectorAll(".kit-save,[data-kit-confirm]");}
+function release(f){f.__kitPending=0;f.__kitSent=0;buttons(f).forEach(function(b){b.disabled=false;});}
+function latch(f,e){f.__kitPending=1;setTimeout(function(){if(e.defaultPrevented){release(f);return;}
+buttons(f).forEach(function(b){b.disabled=true;});},0);}
+addEventListener("pageshow",function(){d.querySelectorAll("form.kit-form").forEach(release);});
+d.addEventListener("submit",function(e){var f=e.target;if(!f||!f.classList||!f.classList.contains("kit-form"))return;prep(f);
+if(f.__kitPending){e.preventDefault();e.stopImmediatePropagation();return;}
+var dl=f.hasAttribute("data-kit-step-up")?f.querySelector("[data-kit-dialog]"):null;
+if(f.__kitGo||!dl||!asks(dl)){latch(f,e);return;}
+e.preventDefault();e.stopImmediatePropagation();
+if(dl.open){confirm(f);return;}
+f.__kitBy=e.submitter||null;f.__kitSent=0;dl.showModal();
+var first=dl.querySelector("[data-kit-slot] input:not([type=hidden]),[data-kit-slot] a")||dl.querySelector("[data-kit-confirm]");if(first)first.focus();},true);
+d.addEventListener("click",function(e){var b=e.target&&e.target.closest?e.target.closest("[data-kit-confirm],[data-kit-cancel]"):null;if(!b)return;
+var dl=b.closest("[data-kit-dialog]"),f=dl&&dl.closest("form");if(!f)return;e.preventDefault();
+if(b.hasAttribute("data-kit-cancel")){dl.close();return;}confirm(f);});
+d.addEventListener("input",function(e){var t=e.target;if(t&&t.setCustomValidity&&t.hasAttribute&&t.hasAttribute("data-kit-required"))t.setCustomValidity("");},true);
+function changed(e){var t=e.target,f=t&&t.form;if(!f||!f.classList.contains("kit-form")||t.closest("[data-kit-dialog]")||t.type==="hidden")return;prep(f);
+var bar=f.querySelector("[data-kit-save-bar]"),state=f.querySelector("[data-kit-state]");if(!bar||!state)return;
+f.__kitChanged=f.__kitChanged||[];var name=label(t);if(name&&f.__kitChanged.indexOf(name)<0)f.__kitChanged.push(name);
+bar.setAttribute("data-changed","");state.textContent="Changed: "+f.__kitChanged.join(", ");}
+d.addEventListener("input",changed);d.addEventListener("change",changed);
+})();`;
+/** The pages that wear the settings frame: one column, no Crew sheet, a breadcrumb under Settings. Here (not in
+ * settings-kit.ts) so the browser bundle reads it without the server's form contracts. */
+export function isSettingsFrame(pathname) {
+    return pathname === "/settings" || pathname.startsWith("/settings/") || pathname === "/setup" || pathname.startsWith("/setup/")
+        || pathname === "/people" || pathname === "/mode" || pathname === "/control" || pathname === "/spend";
+}

package/dist/settings-kit.d.ts

@@ -0,0 +1,137 @@
+/**
+ * The settings kit (docs/plans/settings-revamp.md §4): the frame's breadcrumb, and the pieces every settings page is
+ * rebuilt from — a section, its own sticky Save, the step-up dialog drawn from the action's own proof contract
+ * (settings-proofs.ts), field errors, secret inputs and choice groups. Server-rendered HTML that works without
+ * JavaScript; settings-kit-script.ts only turns the inline proof field into a dialog.
+ *
+ * Rules the helpers keep (and settings-kit.test.ts pins):
+ * - the proof field is written into the form's own server HTML, named as its handler reads it, labelled, and
+ *   `current-password`; so sensitivity (serve.ts sendScreen) and the identity-provider swap (ssoStepUps) still see it;
+ * - a step-up field renders through `reauth`, so Passwordless leaves it out exactly as today; a credential or typed
+ *   password field always renders;
+ * - a CSRF-only action renders no proof field and no dialog;
+ * - nothing here ever sets `value` on a proof or secret field;
+ * - handlers never read any of this: it only draws.
+ */
+import { type Html, type HtmlValue } from "./html.js";
+import { isSettingsFrame } from "./settings-kit-script.js";
+import { type ProofRow } from "./settings-proofs.js";
+export { isSettingsFrame };
+/** One breadcrumb: a link, or (the last) the page itself. */
+export type Crumb = {
+    label: string;
+    href: string | null;
+};
+/** The text of a page's first h1 (tags dropped, the common entities read), or null. */
+export declare function headingText(page: string): string | null;
+/** The breadcrumb for a settings-frame page: "Settings / <this page>", or nothing on the hub and outside the frame. */
+export declare function settingsCrumbs(pathname: string, title: string, page: string): Crumb[] | undefined;
+/** The project the sidebar's picker names: the session's saved selection while this person may still see it, else
+ * the page's own effective project, else none — checked against the visible project list, so a selection that
+ * outlived the ceiling is never sent to the page. */
+export declare function openProjectFor(saved: string | null, effective: string | null | undefined, visible: readonly {
+    path: string;
+}[]): string | null;
+/** The breadcrumb as server HTML (the page before scripts, and without them). */
+export declare function crumbsHtml(crumbs: readonly Crumb[]): Html;
+/** The password-manager opt-outs every secret input carries (a service's key is not the person's sign-in). */
+export declare const SECRET_OPT_OUTS: {
+    readonly "data-1p-ignore": true;
+    readonly "data-lpignore": "true";
+    readonly "data-bwignore": true;
+    readonly "data-form-type": "other";
+};
+/** A field's message under it: tied to the field with aria-describedby, announced, and the field focused. */
+export declare function fieldError(id: string, message: string): Html;
+export type TextField = {
+    id: string;
+    name: string;
+    label: string;
+    type?: "text" | "number" | "url" | "email";
+    /** What the person typed (kept after a validation error). Never a secret: secrets use secretInput. */
+    value?: string | null;
+    hint?: string;
+    error?: string | null;
+    attrs?: Readonly<Record<string, string | number | boolean | null | undefined>>;
+};
+/** A labelled text field; with an error it is aria-invalid, names its message and takes focus. */
+export declare function textField(field: TextField): Html;
+/** A secret that is not the person's own password (an API key, a bot token, a client secret): masked, never given a
+ * value, kept out of password managers. The field name is the handler's own wire name. */
+export declare function secretInput(field: {
+    id: string;
+    name: string;
+    label: string;
+    hint?: string;
+    required?: boolean;
+    error?: string | null;
+}): Html;
+/** A choice group: a fieldset with its legend, each option's detail tied to it. Nothing saves until Save. */
+export declare function choiceGroup(group: {
+    id: string;
+    name: string;
+    legend: string;
+    checked: string | null;
+    options: readonly {
+        value: string;
+        label: string;
+        detail?: string;
+    }[];
+    error?: string | null;
+}): Html;
+/** Proofs that only a password typed now satisfies: no Passwordless session and no identity-provider re-check. */
+export declare const typedOnly: (row: ProofRow) => boolean;
+/** The proof field a row's handler reads, as today's forms write it; empty for a CSRF-only row. A step-up field goes
+ * through `reauth` (Passwordless leaves it out); a credential or typed field always shows. A typed-only field carries
+ * `data-so-typed`, so the identity-provider swap leaves it a real password field (keepTypedFields). Never a value. */
+export declare function proofField(row: ProofRow, options?: {
+    label?: string;
+}): Html;
+/**
+ * The identity-provider swap (render-people.ts ssoStepUps) with typed-only proof fields kept: those handlers take only
+ * a password typed now, so the field must stay a real password input. The field is held out of the swap by its
+ * marker and put back as it was. Every other step-up field is swapped exactly as before.
+ */
+export declare function keepTypedFields<A extends unknown[]>(page: Html, swap: (page: Html, ...rest: A) => Html, ...rest: A): Html;
+/** How the dialog explains a proof that Passwordless doesn't cover, in words; null where nothing needs saying. */
+export declare function proofNote(row: ProofRow): string | null;
+export type StepUpForm = {
+    /** The proof inventory row this form posts under. */
+    proof: string;
+    /** The exact route (one of the row's). */
+    action: string;
+    /** Unique on the page: the form, its dialog and its section hang from it. */
+    id: string;
+    /** The section's own fields. */
+    body: HtmlValue;
+    /** Hidden terms posted back unchanged (nonce, digest, fingerprint, the shown project…). */
+    hidden?: Readonly<Record<string, string | number | null | undefined>>;
+    /** The Save bar's words before anything changes, and its button. */
+    save?: {
+        label?: string;
+        idle?: string;
+        name?: string;
+        value?: string;
+    };
+    /** What the dialog says the person is agreeing to (the action's own words by default). */
+    confirm?: string;
+};
+/**
+ * A section's form, posted to its existing route with its existing fields, and its sticky Save. When the row needs a
+ * proof, the proof field sits in the form's own HTML — inline (as today, which is how it works without JavaScript) and
+ * moved into a `<dialog>` inside the same form by settings-kit-script.ts, which opens it on submit, keeps the pressed
+ * button, and posts nothing on Cancel. The server still proves everything.
+ */
+export declare function stepUpForm(form: StepUpForm): Html;
+/** A section: a heading, a one-line state, a problem the handler sent back (role=alert), then its form. */
+export declare function kitSection(section: {
+    id: string;
+    title: string;
+    state?: HtmlValue;
+    problem?: string | null;
+    said?: string | null;
+    body: HtmlValue;
+}): Html;
+/** The kit's look: one 760px column, sections with no nested wells, the sticky Save, the dialog. The needs-you colour
+ * falls back to the warning token until S5 lands `--so-needs-you`. */
+export declare const SETTINGS_KIT_CSS: string;

package/dist/settings-kit.js

@@ -0,0 +1,186 @@
+/**
+ * The settings kit (docs/plans/settings-revamp.md §4): the frame's breadcrumb, and the pieces every settings page is
+ * rebuilt from — a section, its own sticky Save, the step-up dialog drawn from the action's own proof contract
+ * (settings-proofs.ts), field errors, secret inputs and choice groups. Server-rendered HTML that works without
+ * JavaScript; settings-kit-script.ts only turns the inline proof field into a dialog.
+ *
+ * Rules the helpers keep (and settings-kit.test.ts pins):
+ * - the proof field is written into the form's own server HTML, named as its handler reads it, labelled, and
+ *   `current-password`; so sensitivity (serve.ts sendScreen) and the identity-provider swap (ssoStepUps) still see it;
+ * - a step-up field renders through `reauth`, so Passwordless leaves it out exactly as today; a credential or typed
+ *   password field always renders;
+ * - a CSRF-only action renders no proof field and no dialog;
+ * - nothing here ever sets `value` on a proof or secret field;
+ * - handlers never read any of this: it only draws.
+ */
+import { attributes, html, htmlString, joinHtml, postForm, reauth, replaceMarkup } from "./html.js";
+import { isSettingsFrame } from "./settings-kit-script.js";
+import { contractReads, PROOF_INVENTORY, proofRow } from "./settings-proofs.js";
+export { isSettingsFrame };
+const ENTITIES = { amp: "&", lt: "<", gt: ">", quot: '"', "#39": "'", "#x27": "'", nbsp: " " };
+/** The text of a page's first h1 (tags dropped, the common entities read), or null. */
+export function headingText(page) {
+    const found = /<h1\b[^>]*>([\s\S]*?)<\/h1>/i.exec(page);
+    if (found === null)
+        return null;
+    const text = found[1].replace(/<[^>]*>/g, "").replace(/&(amp|lt|gt|quot|#39|#x27|nbsp);/g, (_whole, name) => ENTITIES[name] ?? "").replace(/\s+/g, " ").trim();
+    return text === "" ? null : text.slice(0, 80);
+}
+/** The breadcrumb for a settings-frame page: "Settings / <this page>", or nothing on the hub and outside the frame. */
+export function settingsCrumbs(pathname, title, page) {
+    if (!isSettingsFrame(pathname) || pathname === "/settings")
+        return undefined;
+    const name = headingText(page) ?? (title.charAt(0).toUpperCase() + title.slice(1));
+    return [{ label: "Settings", href: "/settings" }, { label: name, href: null }];
+}
+/** The project the sidebar's picker names: the session's saved selection while this person may still see it, else
+ * the page's own effective project, else none — checked against the visible project list, so a selection that
+ * outlived the ceiling is never sent to the page. */
+export function openProjectFor(saved, effective, visible) {
+    return [saved, effective ?? null].find((path) => path !== null && visible.some(one => one.path === path)) ?? null;
+}
+/** The breadcrumb as server HTML (the page before scripts, and without them). */
+export function crumbsHtml(crumbs) {
+    return html `<nav class="kit-crumbs" aria-label="Breadcrumb"><ol>${crumbs.map(one => one.href === null
+        ? html `<li aria-current="page">${one.label}</li>`
+        : html `<li><a href="${one.href}">${one.label}</a></li>`)}</ol></nav>`;
+}
+// ---- fields --------------------------------------------------------------------------------------------------------
+/** The password-manager opt-outs every secret input carries (a service's key is not the person's sign-in). */
+export const SECRET_OPT_OUTS = { "data-1p-ignore": true, "data-lpignore": "true", "data-bwignore": true, "data-form-type": "other" };
+const errorId = (id) => `${id}-error`;
+/** A field's message under it: tied to the field with aria-describedby, announced, and the field focused. */
+export function fieldError(id, message) {
+    return html `<p class="kit-field-error" id="${errorId(id)}" role="alert">${message}</p>`;
+}
+/** A labelled text field; with an error it is aria-invalid, names its message and takes focus. */
+export function textField(field) {
+    const hint = field.hint === undefined ? null : `${field.id}-hint`;
+    const described = [hint, field.error ? errorId(field.id) : null].filter(Boolean).join(" ");
+    return html `<div class="kit-field"><label for="${field.id}">${field.label}</label>\
+${field.hint === undefined ? "" : html `<p class="kit-hint" id="${hint}">${field.hint}</p>`}\
+<input${attributes({ id: field.id, name: field.name, type: field.type ?? "text", value: field.value ?? null, ...(field.attrs ?? {}),
+        "aria-invalid": field.error ? "true" : null, "aria-describedby": described === "" ? null : described, autofocus: field.error ? true : null })}>\
+${field.error ? fieldError(field.id, field.error) : ""}</div>`;
+}
+/** A secret that is not the person's own password (an API key, a bot token, a client secret): masked, never given a
+ * value, kept out of password managers. The field name is the handler's own wire name. */
+export function secretInput(field) {
+    const described = [field.hint === undefined ? null : `${field.id}-hint`, field.error ? errorId(field.id) : null].filter(Boolean).join(" ");
+    return html `<div class="kit-field"><label for="${field.id}">${field.label}</label>\
+${field.hint === undefined ? "" : html `<p class="kit-hint" id="${field.id}-hint">${field.hint}</p>`}\
+<input${attributes({ id: field.id, name: field.name, type: "password", autocomplete: "off", spellcheck: "false", autocapitalize: "none", "data-so-secret": true, ...SECRET_OPT_OUTS,
+        required: field.required === true, "aria-invalid": field.error ? "true" : null, "aria-describedby": described === "" ? null : described, autofocus: field.error ? true : null })}>\
+${field.error ? fieldError(field.id, field.error) : ""}</div>`;
+}
+/** A choice group: a fieldset with its legend, each option's detail tied to it. Nothing saves until Save. */
+export function choiceGroup(group) {
+    return html `<fieldset class="kit-choices"${group.error ? html ` aria-describedby="${errorId(group.id)}"` : ""}><legend>${group.legend}</legend>\
+${group.options.map((one, at) => {
+        const id = `${group.id}-${at}`;
+        return html `<label class="kit-choice" for="${id}"><input${attributes({ type: "radio", id, name: group.name, value: one.value, checked: one.value === group.checked, "aria-describedby": one.detail === undefined ? null : `${id}-detail` })}>\
+<span>${one.label}</span>${one.detail === undefined ? "" : html `<span class="kit-choice-detail" id="${id}-detail">${one.detail}</span>`}</label>`;
+    })}${group.error ? fieldError(group.id, group.error) : ""}</fieldset>`;
+}
+// ---- proof ---------------------------------------------------------------------------------------------------------
+/** Proofs that only a password typed now satisfies: no Passwordless session and no identity-provider re-check. */
+export const typedOnly = (row) => row.proof === "typed-password" || row.proof === "typed-now-operator";
+/** The proof field a row's handler reads, as today's forms write it; empty for a CSRF-only row. A step-up field goes
+ * through `reauth` (Passwordless leaves it out); a credential or typed field always shows. A typed-only field carries
+ * `data-so-typed`, so the identity-provider swap leaves it a real password field (keepTypedFields). Never a value. */
+export function proofField(row, options = {}) {
+    if (row.field === null || row.proof === "none")
+        return html ``;
+    if (!contractReads(row, row.field))
+        throw new Error(`${row.id}: its form doesn't read ${row.field}`);
+    const label = options.label ?? "Your Toolroll password";
+    if (typedOnly(row))
+        return html `<label>${label}<input type="password" name="${row.field}" data-so-typed autocomplete="current-password" required></label>`;
+    const field = html `<label>${label}<input type="password" name="${row.field}" autocomplete="current-password" required></label>`;
+    return row.proof === "step-up" ? reauth(field) : field;
+}
+const TYPED_FIELD = /<input type="password" name="([a-z-]+)" data-so-typed autocomplete="current-password" required>/g;
+const HELD_FIELD = /<input type="password" name="([a-z-]+)" data-so-typed data-so-typed-held required>/g;
+/**
+ * The identity-provider swap (render-people.ts ssoStepUps) with typed-only proof fields kept: those handlers take only
+ * a password typed now, so the field must stay a real password input. The field is held out of the swap by its
+ * marker and put back as it was. Every other step-up field is swapped exactly as before.
+ */
+export function keepTypedFields(page, swap, ...rest) {
+    const held = replaceMarkup(page, TYPED_FIELD, (_whole, name) => html `<input type="password" name="${name}" data-so-typed data-so-typed-held required>`);
+    return replaceMarkup(swap(held, ...rest), HELD_FIELD, (_whole, name) => html `<input type="password" name="${name}" data-so-typed autocomplete="current-password" required>`);
+}
+/** The rows that share this row's route: one handler's variants. */
+const variantsOf = (row) => PROOF_INVENTORY.filter(one => one !== row && one.routes.some(route => row.routes.includes(route)));
+/** How the dialog explains a proof that Passwordless doesn't cover, in words; null where nothing needs saying. */
+export function proofNote(row) {
+    if (row.proof === "credential")
+        return "This changes a way in, so it always takes your password.";
+    if (row.proof === "typed-password")
+        return "This always takes your password, typed.";
+    if (row.proof === "typed-now-operator")
+        return "Widening this takes an instance operator's password, typed now.";
+    return null;
+}
+/**
+ * A section's form, posted to its existing route with its existing fields, and its sticky Save. When the row needs a
+ * proof, the proof field sits in the form's own HTML — inline (as today, which is how it works without JavaScript) and
+ * moved into a `<dialog>` inside the same form by settings-kit-script.ts, which opens it on submit, keeps the pressed
+ * button, and posts nothing on Cancel. The server still proves everything.
+ */
+export function stepUpForm(form) {
+    const row = proofRow(form.proof);
+    if (!row.routes.includes(form.action))
+        throw new Error(`${row.id} doesn't post to ${form.action}`);
+    const hidden = form.hidden ?? {};
+    for (const name of Object.keys(hidden))
+        if (row.field === name || row.secrets.includes(name))
+            throw new Error(`${row.id}: ${name} is never a hidden value`);
+    // The exact variant: its own selector must be in the hidden terms, and no other variant's may be.
+    if (row.select !== undefined && String(hidden[row.select.field] ?? "") !== row.select.value)
+        throw new Error(`${row.id} posts ${row.select.field}=${row.select.value}`);
+    for (const other of variantsOf(row))
+        if (other.select !== undefined && String(hidden[other.select.field] ?? "") === other.select.value)
+            throw new Error(`${form.action} with ${other.select.field}=${other.select.value} is ${other.id}, not ${row.id}`);
+    const proof = proofField(row);
+    const asks = htmlString(proof) !== "";
+    const note = proofNote(row);
+    const save = form.save ?? {};
+    const submit = html `<button${attributes({ type: "submit", class: "kit-save", name: save.name ?? null, value: save.value ?? null })}>${save.label ?? "Save"}</button>`;
+    const dialog = asks ? html `<dialog class="kit-dialog" id="${form.id}-dialog" aria-labelledby="${form.id}-dialog-title" data-kit-dialog>\
+<h2 id="${form.id}-dialog-title">Confirm it's you</h2><p class="kit-dialog-terms">${form.confirm ?? row.action}${row.when === undefined ? "" : html ` <span class="kit-hint">(${row.when})</span>`}</p>\
+${note === null ? "" : html `<p class="kit-hint">${note}</p>`}<div class="kit-dialog-slot" data-kit-slot></div>\
+<div class="kit-dialog-actions"><button type="button" class="kit-cancel" data-kit-cancel>Cancel</button><button type="button" class="kit-confirm" data-kit-confirm>${save.label ?? "Save"}</button></div></dialog>` : "";
+    return postForm(form.action, joinHtml([
+        form.body,
+        asks ? html `<div class="kit-proof" data-kit-proof>${proof}</div>` : "",
+        html `<div class="kit-save-bar" data-kit-save-bar><span class="kit-save-state" aria-live="polite" data-kit-state data-idle="${save.idle ?? "No changes"}"></span>${submit}</div>`,
+        dialog,
+    ]), { hidden, attrs: { id: form.id, class: "kit-form", "data-kit-form": row.id, "data-kit-step-up": asks ? "" : null } });
+}
+/** A section: a heading, a one-line state, a problem the handler sent back (role=alert), then its form. */
+export function kitSection(section) {
+    return html `<section class="kit-section" id="${section.id}" aria-labelledby="${section.id}-title"><h2 id="${section.id}-title">${section.title}</h2>\
+${section.state === undefined ? "" : html `<p class="kit-state">${section.state}</p>`}\
+${section.problem ? html `<p class="kit-problem" role="alert">${section.problem}</p>` : ""}\
+${section.said ? html `<p class="kit-said" role="status">${section.said}</p>` : ""}${section.body}</section>`;
+}
+/** The kit's look: one 760px column, sections with no nested wells, the sticky Save, the dialog. The needs-you colour
+ * falls back to the warning token until S5 lands `--so-needs-you`. */
+export const SETTINGS_KIT_CSS = ":root{--so-settings-width:760px}" +
+    ".kit-crumbs ol{display:flex;flex-wrap:wrap;align-items:center;gap:6px;margin:0;padding:0;list-style:none;font-size:14px;color:var(--so-muted)}" +
+    ".kit-crumbs li+li::before{content:'/';margin-right:6px;color:var(--so-muted)}.kit-crumbs a{color:var(--so-muted);text-decoration:none}.kit-crumbs a:hover{color:var(--so-ink);text-decoration:underline}" +
+    ".kit-crumbs [aria-current]{color:var(--so-ink);font-weight:600}" +
+    ".kit-section{margin:0 0 32px}.kit-section>h2{margin:0 0 4px;font-size:16px}.kit-state{margin:0 0 12px;color:var(--so-muted)}" +
+    ".kit-problem{margin:0 0 12px;padding:10px 12px;border:1px solid var(--so-danger);border-radius:8px;color:var(--so-danger)}.kit-said{margin:0 0 12px;color:var(--so-muted)}" +
+    ".kit-field{margin:0 0 14px}.kit-hint{margin:2px 0 0;font-size:13px;color:var(--so-muted)}" +
+    ".kit-field-error{margin:4px 0 0;font-size:13px;color:var(--so-danger)}.kit-field [aria-invalid=true]{border-color:var(--so-danger)}" +
+    ".kit-choices{margin:0 0 14px;padding:0;border:0}.kit-choices legend{padding:0;margin:0 0 6px;font-weight:600}" +
+    ".kit-choice{display:grid;grid-template-columns:auto 1fr;column-gap:10px;align-items:start;min-height:44px;padding:8px 0;margin:0}.kit-choice input{margin:3px 0 0}.kit-choice-detail{grid-column:2;font-size:13px;color:var(--so-muted)}" +
+    ".kit-save-bar{position:sticky;bottom:0;z-index:2;display:flex;align-items:center;justify-content:space-between;gap:12px;margin:16px 0 0;padding:10px 0;border-top:1px solid var(--so-line);background:var(--so-paper)}" +
+    ".kit-save-state{color:var(--so-muted);font-size:14px}.kit-save-bar[data-changed] .kit-save-state{color:var(--so-ink)}" +
+    ".kit-js .kit-form[data-kit-step-up]>.kit-proof{display:none}" +
+    ".kit-dialog{max-width:min(440px,calc(100vw - 32px));padding:20px;border:1px solid var(--so-line);border-radius:12px;background:var(--so-paper);color:var(--so-ink)}" +
+    ".kit-dialog::backdrop{background:rgb(0 0 0 / .35)}.kit-dialog h2{margin:0 0 6px;font-size:17px}.kit-dialog-slot .kit-proof{display:block}" +
+    ".kit-dialog-actions{display:flex;justify-content:flex-end;gap:8px;margin:16px 0 0}" +
+    "@media (max-width:900px){.kit-save-bar button,.kit-dialog-actions button,.kit-crumbs a{min-height:44px}.kit-crumbs a{display:inline-flex;align-items:center}}";

package/dist/settings-proofs.d.ts

@@ -0,0 +1,64 @@
+/**
+ * The settings proof inventory (docs/plans/settings-revamp.md §4): for every settings action, the proof its handler
+ * already asks for, as data. Only rendering code reads it (settings-kit.ts draws the step-up dialog from it); no
+ * handler does, and nothing here changes what a handler proves. `src/settings-kit.test.ts` pins every row against the
+ * form contracts (console-api.ts), the route table, and — for one row of each kind — the handler itself over HTTP.
+ *
+ * Proof kinds, as the handlers implement them (scope.ts, server/guards.ts):
+ * - `none`: the session and the form token (CSRF) only.
+ * - `step-up`: `authenticateApprover` — a password typed now; an empty field stands in under Passwordless (the
+ *   person's own live browser session) and for a one-use identity-provider re-check.
+ * - `credential`: `authenticateCredential` — a password typed now, or a one-use identity-provider re-check. Passwordless
+ *   never covers it.
+ * - `typed-password`: the handler checks the typed password itself (`authenticateAccount`, or an empty field refused
+ *   before the check). Neither Passwordless nor an identity-provider re-check stands in.
+ * - `typed-now-operator`: a password typed now by an instance operator (widening check access); not even a re-check.
+ */
+import { type ConsoleFormName } from "./contracts/console-api.js";
+export type ProofKind = "none" | "step-up" | "credential" | "typed-password" | "typed-now-operator";
+/** Who the route table admits (route-table.ts `role`); `handler` notes a narrower check the handler makes itself. */
+export type ProofRole = "any" | "approver" | "operator";
+export type ProofRow = {
+    /** Stable id the kit is called with. */
+    readonly id: string;
+    /** What the person is doing, in words. */
+    readonly action: string;
+    /** The exact POST paths. */
+    readonly routes: readonly string[];
+    /** The form contract its handler reads through. */
+    readonly form: ConsoleFormName;
+    /** The proof field's name, or null when none is read. */
+    readonly field: "password" | "token" | null;
+    readonly proof: ProofKind;
+    /** Only some submissions need the proof (the rest are `none`), in words. */
+    readonly when?: string;
+    /** Rows that share a route are variants of one handler, each with its own exact proof. A variant with `select`
+     * applies exactly when the form carries that hidden value (the kit refuses a form whose hidden terms pick another
+     * variant); a variant with `explicit` is named by the caller (a choice the server decides, like widening). */
+    readonly select?: {
+        readonly field: string;
+        readonly value: string;
+    };
+    readonly explicit?: true;
+    /** Under Passwordless, does an empty proof field pass? (`accepted` only for step-up.) */
+    readonly passwordless: "accepted" | "refused" | "n/a";
+    /** Does a one-use identity-provider re-check (empty field after "Confirm with …") pass? */
+    readonly sso: "accepted" | "refused" | "n/a";
+    readonly role: ProofRole;
+    /** A narrower standing the handler checks itself, in words. */
+    readonly handlerRole?: string;
+    /** Fields that hold a secret that is not the person's proof (never echoed, password managers kept out). */
+    readonly secrets: readonly string[];
+    /** Fields whose name reads like a credential but hold something else (an id, a bot token…). */
+    readonly notProof?: readonly string[];
+    /** Every term the handler requires besides the proof: hidden fields carried back unchanged (nonce, digest,
+     * fingerprint, the shown project, what a preview showed) and the fields that pick the target (repo, act). */
+    readonly terms: readonly string[];
+    /** Anything else the handler requires, in words. */
+    readonly note?: string;
+};
+export declare const PROOF_INVENTORY: readonly ProofRow[];
+/** One row by id; throws on an unknown id (a rendering bug, never a request's input). */
+export declare function proofRow(id: string): ProofRow;
+/** Whether the field a row names is one its form contract reads (used by the kit's own guard and the tests). */
+export declare function contractReads(row: ProofRow, field: string): boolean;