@unifedev/thread-pages 0.3.2 → 1.0.3

package/src/domain/submissions/parse.ts

@@ -0,0 +1,105 @@
+import { isRevision } from "../ids.ts";
+import { LIMITS } from "../limits.ts";
+import { UPLOAD_DIR, isSafeUploadName } from "../../pages/layout.ts";
+
+/** A form answer as the kernel delivers it. spec R4.12 */
+export type AnswerValue = string | string[] | boolean;
+
+export interface Answer {
+  readonly name: string;
+  readonly label: string;
+  readonly value: AnswerValue;
+}
+
+export interface SubmissionFile {
+  readonly field: string;
+  readonly name: string;
+  readonly path: string;
+  readonly sizeBytes: number;
+}
+
+export interface Submission {
+  readonly actionToken: string;
+  readonly submissionId: string;
+  readonly pageRevision: string;
+  readonly title: string;
+  readonly answers: readonly Answer[];
+  readonly files: readonly SubmissionFile[];
+}
+
+/** Parses and bounds a submission body; returns null when it is not one. spec R2.32 */
+export function parseSubmission(value: unknown): Submission | null {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const input = value as Record<string, unknown>;
+  if (
+    typeof input.actionToken !== "string" ||
+    input.actionToken.length === 0 ||
+    input.actionToken.length > LIMITS.tokenChars ||
+    typeof input.submissionId !== "string" ||
+    !/^[A-Za-z0-9._-]{1,128}$/.test(input.submissionId) ||
+    !isRevision(input.pageRevision) ||
+    typeof input.title !== "string" ||
+    input.title.length > 300 ||
+    !Array.isArray(input.answers) ||
+    input.answers.length > LIMITS.answersPerSubmission
+  ) {
+    return null;
+  }
+
+  const answers: Answer[] = [];
+  let total = input.title.length;
+  for (const raw of input.answers) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) return null;
+    const answer = raw as Record<string, unknown>;
+    if (typeof answer.name !== "string" || answer.name.length > 128 || typeof answer.label !== "string" || answer.label.length > 300) return null;
+    if (!isAnswerValue(answer.value)) return null;
+    total += answer.name.length + answer.label.length + valueLength(answer.value);
+    if (total > LIMITS.submissionBodyBytes) return null;
+    answers.push({ name: answer.name, label: answer.label, value: answer.value });
+  }
+
+  const files: SubmissionFile[] = [];
+  if (input.files !== undefined) {
+    if (!Array.isArray(input.files) || input.files.length > LIMITS.uploadsPerForm) return null;
+    for (const raw of input.files) {
+      if (!raw || typeof raw !== "object" || Array.isArray(raw)) return null;
+      const file = raw as Record<string, unknown>;
+      if (
+        typeof file.field !== "string" ||
+        file.field.length > 128 ||
+        typeof file.name !== "string" ||
+        !isSafeUploadName(file.name) ||
+        typeof file.path !== "string" ||
+        file.path !== `${UPLOAD_DIR}/${file.name}` ||
+        typeof file.sizeBytes !== "number" ||
+        !Number.isSafeInteger(file.sizeBytes) ||
+        file.sizeBytes < 0 ||
+        file.sizeBytes > LIMITS.uploadFileBytes
+      ) {
+        return null;
+      }
+      files.push({ field: file.field, name: file.name, path: file.path, sizeBytes: file.sizeBytes });
+    }
+  }
+
+  return {
+    actionToken: input.actionToken,
+    submissionId: input.submissionId,
+    pageRevision: input.pageRevision,
+    title: input.title,
+    answers,
+    files,
+  };
+}
+
+function isAnswerValue(value: unknown): value is AnswerValue {
+  if (typeof value === "boolean") return true;
+  if (typeof value === "string") return value.length <= LIMITS.answerValueChars;
+  return Array.isArray(value) && value.length <= LIMITS.answerListItems && value.every((item) => typeof item === "string" && item.length <= 2_000);
+}
+
+function valueLength(value: AnswerValue): number {
+  if (typeof value === "boolean") return 1;
+  if (typeof value === "string") return value.length;
+  return value.reduce((sum, item) => sum + item.length, 0);
+}

package/src/domain/tokens/action-token.ts

@@ -0,0 +1,52 @@
+import { isRevision, isSessionId } from "../ids.ts";
+import { LIMITS } from "../limits.ts";
+import { isRecord, lifetimeValid, openToken, signPayload } from "./mac.ts";
+
+/**
+ * The action token: authority to act as one page's owner session, for one
+ * page revision, for a bounded time. Held only by the shell, sent only in
+ * request bodies. spec R2.7–R2.10
+ */
+export interface ActionToken {
+  readonly v: 3;
+  readonly scope: "action";
+  readonly session: string;
+  readonly revision: string;
+  readonly iat: number;
+  readonly exp: number;
+}
+
+export function mintActionToken(args: { session: string; revision: string; now: number }, key: Uint8Array): { token: string; payload: ActionToken } {
+  const payload: ActionToken = {
+    v: 3,
+    scope: "action",
+    session: args.session,
+    revision: args.revision,
+    iat: args.now,
+    exp: args.now + LIMITS.actionTokenMs,
+  };
+  return { token: signPayload(payload, key), payload };
+}
+
+export function verifyActionToken(token: string, key: Uint8Array, now: number): ActionToken | null {
+  if (typeof token !== "string" || token.length === 0 || token.length > LIMITS.tokenChars) return null;
+  const payload = openToken(token, key);
+  if (!isRecord(payload)) return null;
+  if (
+    payload.v !== 3 ||
+    payload.scope !== "action" ||
+    !isSessionId(payload.session) ||
+    !isRevision(payload.revision) ||
+    !lifetimeValid({ iat: payload.iat, exp: payload.exp }, now, LIMITS.actionTokenMs)
+  ) {
+    return null;
+  }
+  return {
+    v: 3,
+    scope: "action",
+    session: payload.session,
+    revision: payload.revision,
+    iat: payload.iat as number,
+    exp: payload.exp as number,
+  };
+}

package/src/domain/tokens/confirmation.ts

@@ -0,0 +1,99 @@
+import { isMethodName, isRequestId, isRevision, isSessionId } from "../ids.ts";
+import { fingerprint } from "../json/canonical.ts";
+import type { JsonValue } from "../json/strict-json.ts";
+import { LIMITS } from "../limits.ts";
+import { isRecord, lifetimeValid, openToken, signPayload } from "./mac.ts";
+
+/**
+ * A signed confirmation challenge for one confirmed capability call.
+ *
+ * Minted by the host with its own summary, shown by the trusted shell,
+ * returned unchanged, and verified before acting. Bound to one request id,
+ * method, canonical parameter fingerprint, page revision and session; short
+ * lived. spec R3.17–R3.21
+ */
+export interface ConfirmationChallenge {
+  readonly v: 3;
+  readonly scope: "confirm";
+  readonly session: string;
+  readonly revision: string;
+  readonly requestId: string;
+  readonly method: string;
+  readonly paramsHash: string;
+  readonly summary: string;
+  readonly iat: number;
+  readonly exp: number;
+}
+
+export interface ConfirmationBinding {
+  readonly session: string;
+  readonly revision: string;
+  readonly requestId: string;
+  readonly method: string;
+  readonly params: JsonValue;
+}
+
+export function paramsFingerprint(params: JsonValue): string {
+  return fingerprint(params);
+}
+
+export function mintChallenge(binding: ConfirmationBinding, summary: string, now: number, key: Uint8Array): { challenge: string; payload: ConfirmationChallenge } {
+  const bounded = summary.length <= LIMITS.summaryChars ? summary : `${summary.slice(0, LIMITS.summaryChars - 1)}…`;
+  const payload: ConfirmationChallenge = {
+    v: 3,
+    scope: "confirm",
+    session: binding.session,
+    revision: binding.revision,
+    requestId: binding.requestId,
+    method: binding.method,
+    paramsHash: paramsFingerprint(binding.params),
+    summary: bounded,
+    iat: now,
+    exp: now + LIMITS.confirmationMs,
+  };
+  return { challenge: signPayload(payload, key), payload };
+}
+
+export function openChallenge(challenge: string, key: Uint8Array, now: number): ConfirmationChallenge | null {
+  if (typeof challenge !== "string" || challenge.length === 0 || challenge.length > LIMITS.tokenChars) return null;
+  const payload = openToken(challenge, key);
+  if (!isRecord(payload)) return null;
+  if (
+    payload.v !== 3 ||
+    payload.scope !== "confirm" ||
+    !isSessionId(payload.session) ||
+    !isRevision(payload.revision) ||
+    !isRequestId(payload.requestId) ||
+    !isMethodName(payload.method) ||
+    !isRevision(payload.paramsHash) ||
+    typeof payload.summary !== "string" ||
+    payload.summary.length === 0 ||
+    payload.summary.length > LIMITS.summaryChars ||
+    !lifetimeValid({ iat: payload.iat, exp: payload.exp }, now, LIMITS.confirmationMs)
+  ) {
+    return null;
+  }
+  return {
+    v: 3,
+    scope: "confirm",
+    session: payload.session,
+    revision: payload.revision,
+    requestId: payload.requestId,
+    method: payload.method,
+    paramsHash: payload.paramsHash,
+    summary: payload.summary,
+    iat: payload.iat as number,
+    exp: payload.exp as number,
+  };
+}
+
+/** A challenge approves exactly one invocation: every bound field must match. */
+export function challengeMatches(challenge: ConfirmationChallenge, binding: ConfirmationBinding): boolean {
+  return (
+    challenge.session === binding.session &&
+    challenge.revision === binding.revision &&
+    challenge.requestId === binding.requestId &&
+    challenge.method === binding.method &&
+    challenge.paramsHash === paramsFingerprint(binding.params)
+  );
+}

package/src/domain/tokens/mac.ts

@@ -0,0 +1,50 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+
+/**
+ * Signed tokens: `<base64url(json)>.<base64url(hmac-sha256)>`, verified in
+ * constant time with a key only the host holds. spec R2.6
+ */
+export function signPayload(payload: unknown, key: Uint8Array): string {
+  const encoded = Buffer.from(JSON.stringify(payload), "utf8").toString("base64url");
+  return `${encoded}.${signature(encoded, key)}`;
+}
+
+/** Returns the decoded payload when the signature verifies, otherwise null. */
+export function openToken(token: string, key: Uint8Array): unknown | null {
+  const parts = token.split(".");
+  if (parts.length !== 2) return null;
+  const [encoded, supplied] = parts as [string, string];
+  if (!encoded || !supplied) return null;
+  try {
+    const expected = Buffer.from(signature(encoded, key), "ascii");
+    const given = Buffer.from(supplied, "ascii");
+    if (given.byteLength !== expected.byteLength) return null;
+    if (!timingSafeEqual(given, expected)) return null;
+    return JSON.parse(Buffer.from(encoded, "base64url").toString("utf8")) as unknown;
+  } catch {
+    return null;
+  }
+}
+
+function signature(encoded: string, key: Uint8Array): string {
+  return createHmac("sha256", key).update(encoded, "ascii").digest("base64url");
+}
+
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** A token lifetime check shared by every token kind. */
+export function lifetimeValid(payload: { iat: unknown; exp: unknown }, now: number, maxLifetimeMs: number): boolean {
+  const { iat, exp } = payload;
+  return (
+    typeof iat === "number" &&
+    Number.isSafeInteger(iat) &&
+    typeof exp === "number" &&
+    Number.isSafeInteger(exp) &&
+    iat <= now + 30_000 &&
+    exp > now &&
+    exp > iat &&
+    exp - iat <= maxLifetimeMs
+  );
+}

package/src/generated/kernel-runtime.ts

@@ -0,0 +1,3 @@
+// Generated by scripts/build-runtime.mjs from src/runtime/kernel/main.ts.
+// Do not edit; run `npm run build:runtime`.
+export const KERNEL_RUNTIME = "\"use strict\";(()=>{var ee=Object.defineProperty;var te=(e,t,n)=>t in e?ee(e,t,{enumerable:!0,configurable:!0,writable:!0,value:n}):e[t]=n;var F=(e,t,n)=>te(e,typeof t!=\"symbol\"?t+\"\":t,n);var v=Object.freeze({entryDocumentBytes:5242880,uploadFileBytes:25165824,uploadsPerForm:8,submissionBodyBytes:65536,answersPerSubmission:64,answerValueChars:8e3,answerListItems:64,capabilityPayloadBytes:65536,capabilityJsonDepth:16,capabilityJsonNodes:1e4,promptChars:32768,resultTextBytes:65536,titleChars:240,storageValueBytes:32768,storageKeyChars:128,snapshotDefault:100,snapshotMax:200,activityDefault:8,activityMax:20,actionTokenMs:72e5,confirmationMs:12e4,selectionTokenMs:6e5,selectionTokens:32,idempotencyRecords:512,idempotencyMs:3e5,ratePerMinute:120,rateConcurrent:8,shellPollMs:1e4,watchDefaultMs:8e3,watchMinMs:2e3,watchMaxMs:3e5,offlineCopyBytes:204800,offlineCacheEntries:32,offlineCacheBytes:8388608,requestIdChars:96,methodNameChars:96,tokenChars:4096,errorMessageChars:512,summaryChars:512,projectsMax:200,providersMax:64,modelsPerProvider:64});var A=[\"invalid_json\",\"invalid_request\",\"invalid_params\",\"invalid_response\",\"request_too_large\",\"response_too_large\",\"unsupported_version\",\"unknown_method\",\"stale_page\",\"confirmation_required\",\"confirmation_invalid\",\"cancelled\",\"not_found\",\"conflict\",\"unavailable\",\"rate_limited\",\"handler_error\",\"invalid_result\"],he=new Set(A);var ye=Object.freeze({noPage:\"This session has no page yet. Run `bb thread-page init` in the session first.\",ineligible:\"Only visible root sessions have pages.\",pageTooLarge:`The page's entry document is larger than ${v.entryDocumentBytes/(1024*1024)} MiB and was not served.`,unavailable:\"The page's source is unreachable. Reconnect its host and try again.\",staleCopy:\"The source host is offline; this cached page is read-only.\",stalePage:\"This page changed; reload it before responding.\",handler:\"Could not execute the page action.\",rateLimited:\"Too many requests from this page; try again shortly.\",invalidSession:\"A valid session id is required.\",tokenInvalid:\"This page session is invalid or expired; reload the page.\"});var I=1,B=1,ne=new Set(A);function w(e){return typeof e==\"object\"&&e!==null&&!Array.isArray(e)}function _(e,t){return Object.keys(e).length===t.length&&t.every(o=>Object.prototype.hasOwnProperty.call(e,o))}function q(e,t){if(!w(e)||e.v!==B||typeof e.id!=\"string\"||typeof e.ok!=\"boolean\"||t!==void 0&&e.id!==t)return!1;if(e.ok===!0)return _(e,[\"v\",\"id\",\"ok\",\"result\"]);if(!_(e,[\"v\",\"id\",\"ok\",\"error\"])||!w(e.error))return!1;let n=e.error;return _(n,[\"code\",\"message\"])&&typeof n.code==\"string\"&&ne.has(n.code)&&typeof n.message==\"string\"&&n.message.length>0&&n.message.length<=512}function N(e){let t=e?.getAttribute(\"data-config\");if(!t)throw new Error(\"Thread Page runtime: configuration is missing\");return JSON.parse(t)}function re(e,t,n){let o=e.getAttribute(\"href\");if(o===null)return{kind:\"default\"};if(o.startsWith(\"#\"))return{kind:\"default\"};let s;try{s=new URL(o,n??t)}catch{return{kind:\"block\"}}return s.protocol!==\"http:\"&&s.protocol!==\"https:\"?{kind:\"block\"}:n&&s.href.startsWith(n)?{kind:\"default\"}:e.hasAttribute(\"download\")?{kind:\"default\"}:{kind:\"external\",url:s.href,label:(e.textContent||\"\").replace(/\\s+/g,\" \").trim().slice(0,160)}}function U(e,t){e.addEventListener(\"click\",n=>{if(n.defaultPrevented||n.button!==0)return;let s=n.target?.closest?.(\"a[href]\");if(!s)return;let u=e.querySelector(\"base\")?.getAttribute(\"href\")??null,l=u?new URL(u,e.baseURI).href:null,a=re(s,e.baseURI,l);a.kind!==\"default\"&&(n.preventDefault(),a.kind===\"external\"&&t(a.url,a.label))},!0)}function K(e,t){let n=Object.freeze({version:1,invoke:t.invoke,watch:t.watch,setDirty:t.setDirty});Object.defineProperty(e,\"threadPage\",{value:n,writable:!1,configurable:!1,enumerable:!0})}var T=class extends Error{constructor(n,o){super(o);F(this,\"code\");this.name=\"ThreadPageError\",this.code=n,Object.defineProperty(this,\"code\",{value:n,enumerable:!0,writable:!1})}};function j(e,t){let n=new Map,o=[],s=null,u=0;function l(){return u+=1,`tp-${typeof crypto<\"u\"&&typeof crypto.randomUUID==\"function\"?crypto.randomUUID():`${Date.now()}-${u}`}`}function a(m){let p=n.get(m);if(!(!p||!s))try{s(p.request)}catch(h){n.delete(m),p.reject(new T(\"invalid_request\",h instanceof Error?h.message:\"The request could not be sent\"))}}function f(m,p){return new Promise((h,y)=>{if(typeof m!=\"string\"){y(new T(\"invalid_request\",\"A method name is required\"));return}let b=l(),r={v:B,id:b,method:m,params:p===void 0?null:p,pageRevision:e};n.set(b,{request:r,resolve:h,reject:y}),s?a(b):o.push(b)})}function g(m,p,h,y){if(typeof h!=\"function\")throw new TypeError(\"Thread Page watch needs a listener\");let b=y?.intervalMs,r=typeof b==\"number\"&&Number.isFinite(b)?Math.max(v.watchMinMs,Math.min(v.watchMaxMs,Math.round(b))):v.watchDefaultMs,i=!1,c=!1,d=null;function E(x){i||(d!==null&&clearTimeout(d),d=setTimeout(k,x))}async function k(){if(d=null,!(i||c||t.visibilityState===\"hidden\")){c=!0;try{let x=await f(m,p);i||h(x,null)}catch(x){i||h(void 0,x)}finally{c=!1,i||E(r)}}}function R(){i||(t.visibilityState===\"hidden\"?(d!==null&&clearTimeout(d),d=null):E(0))}return t.addEventListener(\"visibilitychange\",R),E(0),()=>{i||(i=!0,d!==null&&clearTimeout(d),d=null,t.removeEventListener(\"visibilitychange\",R))}}return{invoke:f,watch:g,attach(m){for(s=m;o.length>0;){let p=o.shift();p&&a(p)}},receive(m){if(typeof m!=\"object\"||m===null)return!1;let p=m.id;if(typeof p!=\"string\")return!1;let h=n.get(p);if(!h)return!1;if(n.delete(p),!q(m,p))return h.reject(new T(\"invalid_response\",\"The Thread Page bridge returned an invalid response\")),!0;let y=m;return y.ok?h.resolve(y.result):h.reject(new T(y.error.code,y.error.message)),!0}}}function z(e){let t=new Map,n=0,o=!1,s=!1;function u(){let l=o||t.size>0;l!==s&&(s=l,e(l))}return{isDirty:()=>s,markForm(l){return n+=1,t.set(l,n),u(),n},versionOf:l=>t.get(l),clearForm(l,a){a!==void 0&&t.get(l)===a&&(t.delete(l),u())},setCustom(l){o=l===!0,u()}}}var oe=\"input,textarea,select,button,option,small,output,[data-thread-page-range],[data-thread-page-status]\";function H(e){if(!e)return\"\";let t=e.cloneNode(!0);for(let n of Array.from(t.querySelectorAll(oe)))n.remove();return(t.textContent||\"\").replace(/\\s+/g,\" \").trim()}function ie(e,t){let n=t.getAttribute(\"data-label\");if(n&&n.trim())return n.trim();let o=t.closest(\"fieldset\");if(o){let l=H(o.querySelector(\"legend\"));if(l)return l}let s=t.getAttribute(\"aria-label\");if(s&&s.trim())return s.trim();let u=t.closest(\"label\");if(u){let l=H(u);if(l)return l}if(t.id){let l=e.ownerDocument,a=Array.from(l.querySelectorAll(\"label[for]\")).find(g=>g.htmlFor===t.id),f=H(a??null);if(f)return f}return t.name}var se=new Set([\"button\",\"submit\",\"reset\",\"image\",\"file\"]);function ae(e){return Array.from(e.elements).filter(t=>{let n=t;return typeof n.name==\"string\"&&n.name.length>0&&!n.disabled&&\"type\"in n})}function $(e,t){let n=ae(e),o=[],s=new Set;if(t&&(C(t)===\"button\"||C(t)===\"input\")){let u=t,l=u.value||(u.textContent||\"\").trim();o.push({name:u.name||\"action\",label:\"Action\",value:l}),u.name&&s.add(u.name)}for(let u of n){let l=u.name,a=String(u.type||\"\").toLowerCase();if(s.has(l)||se.has(a))continue;s.add(l);let f=n.filter(g=>g.name===l);o.push({name:l,label:ie(e,u),value:le(u,f,a)})}return o}function C(e){return e.tagName.toLowerCase()}function le(e,t,n){if(n===\"checkbox\"){let o=t.filter(s=>C(s)===\"input\");return o.length===1?o[0]?.checked===!0:o.filter(s=>s.checked).map(s=>s.value)}if(n===\"radio\"){let o=t.find(s=>C(s)===\"input\"&&s.checked);return o?o.value:\"\"}return C(e)===\"select\"&&e.multiple?Array.from(e.selectedOptions).map(o=>o.value):t.length>1?t.map(o=>String(o.value??\"\")):String(e.value??\"\")}var ue=\"data-thread-page-manual\",V=\"data-thread-page-status\",de=\"data-thread-page-range\";function L(e){return e.hasAttribute(ue)}function S(e){let t=[];return\"tagName\"in e&&e.tagName.toLowerCase()===\"form\"&&t.push(e),\"querySelectorAll\"in e&&t.push(...Array.from(e.querySelectorAll(\"form\"))),t.filter(n=>!L(n))}function M(e){let t=e.querySelector(`[${V}]`);return t||(t=e.ownerDocument.createElement(\"p\"),t.setAttribute(V,\"\"),t.setAttribute(\"role\",\"status\"),e.appendChild(t)),t}var G=new WeakSet;function W(e){e.noValidate=!0;for(let t of Array.from(e.querySelectorAll('input[type=\"range\"]'))){if(G.has(t))continue;G.add(t);let n=e.ownerDocument.createElement(\"output\");n.setAttribute(de,\"\");let o=()=>{n.textContent=String(t.value)};t.addEventListener(\"input\",o),o(),t.insertAdjacentElement(\"afterend\",n)}}function P(e){return Array.from(e.querySelectorAll(\"input,textarea,select,button,fieldset\"))}function ce(e){let t=[];for(let n of Array.from(e.querySelectorAll('input[type=\"file\"]')))if(!n.disabled)for(let o of Array.from(n.files??[])){if(t.length>=v.uploadsPerForm)return t;t.push({field:n.name||\"file\",file:o})}return t}function Z(e){let t=[];for(let n of P(e))n.disabled||(n.disabled=!0,t.push(n));return t}function D(e){for(let t of e)t.disabled=!1}function me(e){let t=e.getAttribute(\"data-title\");return t&&t.trim()?t.trim().slice(0,300):(e.ownerDocument.querySelector(\"h1\")?.textContent||\"\").trim().slice(0,300)||\"Thread Page\"}function J(e,t,n){return{submissionId:n,form:e,title:me(e),answers:$(e,t),files:ce(e)}}var X=\"data-thread-page-offline\",O=\"Offline copy \\u2014 responses are disabled until the source host reconnects.\";function Y(e,t){let n=new Set,o=t;function s(){if(!e.body)return;let a=e.querySelector(`[${X}=\"host\"]`);o&&!a?(a=e.createElement(\"aside\"),a.setAttribute(X,\"host\"),a.setAttribute(\"role\",\"status\"),a.setAttribute(\"style\",\"position:relative;z-index:2147483647;margin:0;padding:.75rem 1rem;border-bottom:1px solid currentColor;font:600 14px/1.4 system-ui,sans-serif;background:Canvas;color:CanvasText\"),a.textContent=O,e.body.insertBefore(a,e.body.firstChild)):!o&&a&&a.remove()}function u(a){for(let f of S(a)){for(let g of P(f))g.disabled||(g.disabled=!0,n.add(g));M(f).textContent=O}}function l(){for(let a of n)a.disabled=!1;n.clear();for(let a of S(e)){let f=M(a);f.textContent===O&&(f.textContent=\"\")}}return{isReadOnly:()=>o,apply(a){o=a,a?u(e):l(),s()},prepare(a){o&&u(a),s()}}}function Q(e,t){let n=e.document,o=null,s=new Map,u=new WeakSet;function l(r){if(!o)return!1;try{return o.postMessage(r),!0}catch{return!1}}let a=z(r=>{l({kind:r?\"thread-page:dirty\":\"thread-page:clean\"})}),f=j(t.pageRevision,n),g=Y(n,t.stale);K(e,{version:1,invoke:(r,i)=>f.invoke(r,i),watch:(r,i,c,d)=>f.watch(r,i,c,d),setDirty:r=>a.setCustom(r!==!1)});function m(r){for(let i of S(r))W(i);g.prepare(r)}m(n),n.readyState===\"loading\"&&n.addEventListener(\"DOMContentLoaded\",()=>m(n),{once:!0}),typeof e.MutationObserver==\"function\"&&n.documentElement&&new e.MutationObserver(i=>{for(let c of i)for(let d of Array.from(c.addedNodes))d.nodeType===1&&m(d)}).observe(n.documentElement,{childList:!0,subtree:!0});function p(r){let c=r.target?.closest?.(\"form\");!c||L(c)||a.markForm(c)}n.addEventListener(\"input\",p,!0),n.addEventListener(\"change\",p,!0),n.addEventListener(\"submit\",r=>{let i=r.target;if(!i||i.tagName?.toLowerCase()!==\"form\"||L(i)||(r.preventDefault(),g.isReadOnly()||u.has(i)))return;let c=`sub-${Date.now().toString(36)}-${Math.random().toString(36).slice(2,10)}`,d=i,E=J(d,r.submitter??null,c),k={form:d,disabled:[],dirtyVersion:a.versionOf(d)};s.set(c,k),u.add(d),M(d).textContent=E.files.length>0?\"Uploading\\u2026\":\"Sending\\u2026\",k.disabled=Z(d),l({kind:\"thread-page:submit\",submissionId:c,title:E.title,answers:E.answers,files:E.files})||(s.delete(c),u.delete(d),D(k.disabled),M(d).textContent=\"Page connection is not ready; try again in a moment.\")},!0),U(n,(r,i)=>{f.invoke(\"navigation.openExternal\",i?{url:r,label:i}:{url:r}).catch(()=>{})});function h(r){if(w(r)){if(r.kind===\"thread-page:source-state\"){g.apply(r.stale===!0);return}if(r.kind===\"thread-page:submit-progress\"){let i=typeof r.submissionId==\"string\"?s.get(r.submissionId):void 0;i&&(M(i.form).textContent=String(r.message??\"Working\\u2026\").slice(0,160));return}if(r.kind===\"thread-page:submit-result\"){let i=typeof r.submissionId==\"string\"?s.get(r.submissionId):void 0;if(!i)return;s.delete(r.submissionId),u.delete(i.form);let c=r.ok===!0;M(i.form).textContent=c?String(r.message??\"Sent\").slice(0,160):String(r.error??\"Could not send\").slice(0,160),D(i.disabled),g.isReadOnly()&&g.apply(!0),c&&a.clearForm(i.form,i.dirtyVersion);return}f.receive(r)}}function y(r){o=r,r.onmessage=i=>h(i.data),r.start?.(),f.attach(i=>{r.postMessage(i)}),a.isDirty()&&l({kind:\"thread-page:dirty\"})}function b(r){if(o||r.source!==e.parent)return;let i=r.data;if(!w(i)||i.kind!==\"thread-page:connect\"||i.version!==I||!r.ports||r.ports.length!==1)return;r.stopImmediatePropagation();let c=r.ports[0];c&&y(c)}return e.addEventListener(\"message\",b,!0),t.stale&&g.apply(!0),e.parent.postMessage({kind:\"thread-page:ready\",version:I},\"*\"),{deliver:r=>h(r),connect:r=>y(r)}}Q(window,N(document.currentScript));})();";

package/src/generated/shell-runtime.ts

@@ -0,0 +1,3 @@
+// Generated by scripts/build-runtime.mjs from src/runtime/shell/main.ts.
+// Do not edit; run `npm run build:runtime`.
+export const SHELL_RUNTIME = "\"use strict\";(()=>{var M=Object.freeze({entryDocumentBytes:5242880,uploadFileBytes:25165824,uploadsPerForm:8,submissionBodyBytes:65536,answersPerSubmission:64,answerValueChars:8e3,answerListItems:64,capabilityPayloadBytes:65536,capabilityJsonDepth:16,capabilityJsonNodes:1e4,promptChars:32768,resultTextBytes:65536,titleChars:240,storageValueBytes:32768,storageKeyChars:128,snapshotDefault:100,snapshotMax:200,activityDefault:8,activityMax:20,actionTokenMs:72e5,confirmationMs:12e4,selectionTokenMs:6e5,selectionTokens:32,idempotencyRecords:512,idempotencyMs:3e5,ratePerMinute:120,rateConcurrent:8,shellPollMs:1e4,watchDefaultMs:8e3,watchMinMs:2e3,watchMaxMs:3e5,offlineCopyBytes:204800,offlineCacheEntries:32,offlineCacheBytes:8388608,requestIdChars:96,methodNameChars:96,tokenChars:4096,errorMessageChars:512,summaryChars:512,projectsMax:200,providersMax:64,modelsPerProvider:64});var x=[\"invalid_json\",\"invalid_request\",\"invalid_params\",\"invalid_response\",\"request_too_large\",\"response_too_large\",\"unsupported_version\",\"unknown_method\",\"stale_page\",\"confirmation_required\",\"confirmation_invalid\",\"cancelled\",\"not_found\",\"conflict\",\"unavailable\",\"rate_limited\",\"handler_error\",\"invalid_result\"],Y=new Set(x);var Q=Object.freeze({noPage:\"This session has no page yet. Run `bb thread-page init` in the session first.\",ineligible:\"Only visible root sessions have pages.\",pageTooLarge:`The page's entry document is larger than ${M.entryDocumentBytes/(1024*1024)} MiB and was not served.`,unavailable:\"The page's source is unreachable. Reconnect its host and try again.\",staleCopy:\"The source host is offline; this cached page is read-only.\",stalePage:\"This page changed; reload it before responding.\",handler:\"Could not execute the page action.\",rateLimited:\"Too many requests from this page; try again shortly.\",invalidSession:\"A valid session id is required.\",tokenInvalid:\"This page session is invalid or expired; reload the page.\"});var E=1,_=1,$=new Set(x),j=/^[A-Za-z0-9][A-Za-z0-9._:-]{0,95}$/,F=/^[a-z][a-zA-Z0-9]*(?:\\.[a-z][a-zA-Z0-9]*)+$/;function b(e){return typeof e==\"object\"&&e!==null&&!Array.isArray(e)}function R(e,t){return Object.keys(e).length===t.length&&t.every(l=>Object.prototype.hasOwnProperty.call(e,l))}function C(e){return typeof e==\"string\"&&j.test(e)}function T(e,t){return b(e)&&R(e,[\"v\",\"id\",\"method\",\"params\",\"pageRevision\"])&&e.v===_&&C(e.id)&&typeof e.method==\"string\"&&e.method.length>=3&&e.method.length<=96&&F.test(e.method)&&e.pageRevision===t}function B(e,t){if(!b(e)||e.v!==_||typeof e.id!=\"string\"||typeof e.ok!=\"boolean\"||t!==void 0&&e.id!==t)return!1;if(e.ok===!0)return R(e,[\"v\",\"id\",\"ok\",\"result\"]);if(!R(e,[\"v\",\"id\",\"ok\",\"error\"])||!b(e.error))return!1;let o=e.error;return R(o,[\"code\",\"message\"])&&typeof o.code==\"string\"&&$.has(o.code)&&typeof o.message==\"string\"&&o.message.length>0&&o.message.length<=512}function w(e,t,o){return{v:1,id:C(e)?e:\"invalid\",ok:!1,error:{code:t,message:o.slice(0,512)||\"Request failed\"}}}function P(e){let t=e?.getAttribute(\"data-config\");if(!t)throw new Error(\"Thread Page runtime: configuration is missing\");return JSON.parse(t)}function D(e){let t=e.querySelector(\"p\"),o=e.querySelector('button[value=\"cancel\"]'),l=e.querySelector('button[value=\"confirm\"]'),c=null,d;function p(g){let y=c;if(c=null,g&&d)try{d()}catch{}d=void 0,e.open&&e.close(),y?.(g)}return o?.addEventListener(\"click\",g=>{g.preventDefault(),p(!1)}),l?.addEventListener(\"click\",g=>{g.preventDefault(),p(!0)}),e.addEventListener(\"cancel\",g=>{g.preventDefault(),p(!1)}),e.addEventListener(\"close\",()=>{c&&p(!1)}),{confirm(g,y){return new Promise(m=>{if(c&&p(!1),t&&(t.textContent=g),c=m,d=y,typeof e.showModal==\"function\")try{e.showModal()}catch{p(!1)}else p(!1)})}}}function O(e){let t=null;return{inPlace(o){e.location.assign(o)},reserveWindow(){try{if(t=e.open(\"\",\"_blank\"),t)try{t.opener=null}catch{}}catch{t=null}},external(o){let l=t;if(t=null,l&&!l.closed)try{l.location.href=o;return}catch{try{l.close()}catch{}}e.location.assign(o)},release(){let o=t;t=null;try{o?.close()}catch{}}}}function A(e,t,o,l=e.fetch.bind(e)){let c=`\"${t.pageRevision}\"`,d=!1,p=!1,g=!1,y=t.stale,m=null,v=null;function k(s){m!==null&&clearTimeout(m),m=null,!(p||e.document.visibilityState!==\"visible\")&&(m=setTimeout(()=>{m=null,i()},s))}function r(){m!==null&&clearTimeout(m),m=null,v?.abort(),v=null}function n(){d?(o.setStatus(\"Page changed \\u2014 reload when ready\",!0),o.showReload(!0)):o.reloadView()}async function i(){if(!(p||g||e.document.visibilityState!==\"visible\")){if(Date.now()>=t.expiresAt-3e4){p=!0,d?(o.setStatus(\"Session expiring \\u2014 reload when ready\",!0),o.showReload(!0)):o.reloadView();return}g=!0,v=new AbortController;try{let s=await l(t.documentUrl,{method:\"GET\",credentials:\"same-origin\",cache:\"no-store\",headers:{\"if-none-match\":c},signal:v.signal});if(s.status===401||s.status===403){p=!0,o.setStatus(\"Session expired \\u2014 reload this page\",!0),o.showReload(!0);return}if(!s.ok&&s.status!==304){o.setStatus(\"Page unavailable\",!0);return}let f=s.headers.get(\"x-thread-page-stale\")===\"true\";o.setWorking(s.headers.get(\"x-thread-page-activity\")===\"working\"),f!==y&&(y=f,o.onStaleChanged(f)),o.setStatus(f?\"Offline copy \\u2014 read-only\":\"\",f);let u=s.headers.get(\"etag\");u&&u!==c&&(c=u,n())}catch(s){s instanceof DOMException&&s.name===\"AbortError\"||o.setStatus(\"Cannot check for updates\",!0)}finally{v=null,g=!1,k(t.pollMs)}}}return e.document.addEventListener(\"visibilitychange\",()=>{e.document.visibilityState===\"visible\"?k(0):r()}),{start:()=>k(t.pollMs),setDirty:s=>{d=s},pollNow:()=>i(),isStopped:()=>p}}function I(e){let{config:t,confirmer:o,navigator:l}=e,c=e.fetchImpl??fetch;function d(r,n){r.postMessage(n)}async function p(r){return(await c(t.bridgeUrl,{method:\"POST\",credentials:\"same-origin\",cache:\"no-store\",headers:{\"content-type\":\"application/json\"},body:JSON.stringify(r)})).json().catch(()=>null)}function g(r){return!b(r)||r.kind!==\"page\"&&r.kind!==\"host\"&&r.kind!==\"external\"||typeof r.url!=\"string\"||r.kind===\"external\"&&!/^https?:\\/\\//i.test(r.url)||r.kind!==\"external\"&&!r.url.startsWith(\"/\")?null:{kind:r.kind,url:r.url}}function y(r,n,i){if(!b(i)||!B(i.response,n.id)){d(r,w(n.id,\"invalid_response\",\"The Thread Page bridge returned an invalid response\"));return}let s=i.navigate===void 0?null:g(i.navigate);if(i.response.ok&&s){d(r,i.response),s.kind===\"external\"?l.external(s.url):l.inPlace(s.url);return}l.release(),d(r,i.response)}async function m(r,n){try{let i=await p({actionToken:t.actionToken,request:n});if(b(i)&&b(i.confirm)){let s=i.confirm;if(typeof s.challenge!=\"string\"||typeof s.summary!=\"string\"||s.requestId!==n.id){d(r,w(n.id,\"invalid_response\",\"The Thread Page bridge returned an invalid confirmation\"));return}let f=n.method===\"navigation.openExternal\";if(!await o.confirm(s.summary,f?()=>l.reserveWindow():void 0)){d(r,w(n.id,\"cancelled\",\"You declined this action\"));return}let a=await p({actionToken:t.actionToken,request:n,confirmation:s.challenge});y(r,n,a);return}y(r,n,i)}catch(i){l.release(),d(r,w(n.id,\"unavailable\",i instanceof Error?i.message:\"The Thread Page bridge is unavailable\"))}}async function v(r){let n=r.file;if(!n||typeof n.size!=\"number\")throw new Error(\"Attachment is not a file\");let i=n.name||\"file\";if(n.size<=0)throw new Error(`Attachment ${i} is empty`);if(n.size>t.maxUploadBytes)throw new Error(`Attachment ${i} is larger than ${Math.round(t.maxUploadBytes/(1024*1024))} MiB`);let s=await V(n),f=await c(t.uploadUrl,{method:\"POST\",credentials:\"same-origin\",cache:\"no-store\",headers:{\"content-type\":\"application/json\"},body:JSON.stringify({actionToken:t.actionToken,pageRevision:t.pageRevision,name:i,content:s})}),u=await f.json().catch(()=>null);if(!f.ok||!u||u.ok!==!0||typeof u.name!=\"string\"||typeof u.path!=\"string\"||typeof u.sizeBytes!=\"number\")throw new Error(u&&typeof u.message==\"string\"&&u.message||`Upload failed (${f.status})`);return{field:String(r.field||\"file\").slice(0,128),name:u.name,path:u.path,sizeBytes:u.sizeBytes}}async function k(r,n){let i=typeof n.submissionId==\"string\"?n.submissionId:\"\";try{let s=(Array.isArray(n.files)?n.files:[]).slice(0,t.maxUploads),f=[];for(let S=0;S<s.length;S+=1)d(r,{kind:\"thread-page:submit-progress\",submissionId:i,message:`Uploading ${S+1} of ${s.length}\\u2026`}),f.push(await v(s[S]));f.length>0&&d(r,{kind:\"thread-page:submit-progress\",submissionId:i,message:\"Sending\\u2026\"});let u=await c(t.submitUrl,{method:\"POST\",credentials:\"same-origin\",cache:\"no-store\",headers:{\"content-type\":\"application/json\"},body:JSON.stringify({actionToken:t.actionToken,submissionId:i,pageRevision:t.pageRevision,title:n.title,answers:n.answers,files:f})}),a=await u.json().catch(()=>({ok:!1,message:\"Invalid server response\"})),h=u.ok&&a.ok===!0;d(r,{kind:\"thread-page:submit-result\",submissionId:i,ok:h,message:typeof a.delivery==\"string\"?`Sent (${a.delivery})`:\"Sent\",error:typeof a.message==\"string\"?a.message:`Request failed (${u.status})`})}catch(s){d(r,{kind:\"thread-page:submit-result\",submissionId:i,ok:!1,error:s instanceof Error?s.message:\"Request failed\"})}}return{handle(r,n){if(b(n)){if(n.kind===\"thread-page:dirty\"){e.onDirty(!0);return}if(n.kind===\"thread-page:clean\"){e.onDirty(!1);return}if(n.kind===\"thread-page:submit\"){k(r,n);return}if(!T(n,t.pageRevision)){d(r,w(n.id,\"invalid_request\",\"Invalid Thread Page bridge request\"));return}m(r,n)}}}}async function V(e){let t=new Uint8Array(await e.arrayBuffer()),o=\"\",l=32768;for(let c=0;c<t.length;c+=l)o+=String.fromCharCode.apply(null,Array.from(t.subarray(c,c+l)));return btoa(o)}function L(e,t,o,l){let{frame:c,status:d,work:p,reload:g,dialog:y}=o,m=null,v=!0,k=t.stale,n=A(e,t,{setStatus(a,h){d.textContent=a,d.dataset.tone=h?\"warn\":\"\"},setWorking(a){p.dataset.visible=a&&t.workingLabel?\"true\":\"false\"},showReload(a){g.dataset.visible=a?\"true\":\"false\"},onStaleChanged(a){k=a,m?.postMessage({kind:\"thread-page:source-state\",stale:a})},reloadView(){e.location.reload()}},l),i=O(e),s=D(y),f=I({config:t,confirmer:s,navigator:i,onDirty:a=>n.setDirty(a),...l?{fetchImpl:l}:{}});function u(){let a=new e.MessageChannel,h=a.port1;m=h,h.onmessage=S=>f.handle(h,S.data),h.start?.(),c.contentWindow?.postMessage({kind:\"thread-page:connect\",version:E},\"*\",[a.port2]),h.postMessage({kind:\"thread-page:source-state\",stale:k})}return e.addEventListener(\"message\",a=>{if(!v||a.origin!==\"null\"||a.source!==c.contentWindow)return;let h=a.data;!b(h)||h.kind!==\"thread-page:ready\"||h.version!==E||(v=!1,u())}),g.addEventListener(\"click\",()=>e.location.reload()),c.src=t.documentUrl,n.start(),{poller:n}}var W=P(document.currentScript),q=document.querySelector(\"iframe\"),N=document.querySelector(\"[data-shell-status]\"),U=document.querySelector(\"[data-shell-working]\"),H=document.querySelector(\"[data-shell-reload]\"),z=document.querySelector(\"dialog\");if(!q||!N||!U||!H||!z)throw new Error(\"Thread Page shell: chrome is incomplete\");L(window,W,{frame:q,status:N,work:U,reload:H,dialog:z});})();";

package/src/host/contract.ts

@@ -0,0 +1,65 @@
+import type { JsonValue } from "../domain/json/strict-json.ts";
+import type {
+  ActivityItem,
+  Delivery,
+  FileContent,
+  HostLogger,
+  ProjectRecord,
+  ProviderChoice,
+  SendMode,
+  SessionListQuery,
+  SessionRecord,
+  StartSessionArgs,
+  StorageLocation,
+  WriteOutcome,
+} from "./types.ts";
+
+/**
+ * What a host must provide for Thread Pages to run on it. spec 08
+ *
+ * bb implements this in src/bb. Everything above the domain talks to this
+ * interface and nothing else, so a second host is one new package.
+ */
+export interface SessionHost {
+  readonly sessions: {
+    /** null when the session does not exist. */
+    get(id: string): Promise<SessionRecord | null>;
+    list(query: SessionListQuery): Promise<SessionRecord[]>;
+    send(id: string, text: string, mode: SendMode): Promise<{ delivery: Delivery }>;
+    start(args: StartSessionArgs): Promise<{ id: string }>;
+    stop(id: string): Promise<void>;
+    archive(id: string): Promise<void>;
+    /** Sets the reader's read mark; returns the mark afterwards. */
+    markRead(id: string, read: boolean): Promise<{ unread: boolean }>;
+    activity(id: string, limit: number): Promise<ActivityItem[]>;
+    storage(id: string): Promise<StorageLocation>;
+  };
+  readonly projects: {
+    list(): Promise<ProjectRecord[]>;
+    /** Opens the host's native folder picker; null when cancelled. */
+    browse(hostId: string): Promise<{ path: string; hostName: string } | null>;
+    create(args: { name: string; hostId: string; path: string }): Promise<ProjectRecord>;
+  };
+  readonly providers: {
+    /** Throws when the host cannot enumerate; never returns an empty list to mean that. spec R5.15 */
+    list(): Promise<ProviderChoice[]>;
+  };
+  readonly files: {
+    /** null when the file does not exist. Throws `unavailable` when the host cannot be reached. */
+    read(location: StorageLocation, relativePath: string): Promise<FileContent | null>;
+    /** `exists` when `onlyIfAbsent` is set and the file is already there. */
+    write(location: StorageLocation, relativePath: string, bytes: Uint8Array, options: { onlyIfAbsent: boolean }): Promise<WriteOutcome>;
+    /** Which of the given absolute paths exist on a host, in one batched call where possible. */
+    exist(hostId: string, absolutePaths: readonly string[]): Promise<Record<string, boolean>>;
+  };
+  readonly kv: {
+    get(key: string): Promise<JsonValue | undefined>;
+    set(key: string, value: JsonValue): Promise<void>;
+    delete(key: string): Promise<void>;
+  };
+  readonly origin: {
+    /** The externally reachable origin (scheme + authority), or null when local-only. */
+    public(): Promise<string | null>;
+  };
+  readonly log: HostLogger;
+}

package/src/host/types.ts

@@ -0,0 +1,89 @@
+import type { SessionState } from "../domain/capabilities/specs.ts";
+
+/**
+ * The host's things, projected into the product's vocabulary. Nothing here is
+ * shaped like a particular host's API. spec 08
+ */
+export interface SessionRecord {
+  readonly id: string;
+  readonly title: string;
+  readonly projectId: string | null;
+  readonly state: SessionState;
+  readonly visibility: "visible" | "hidden";
+  readonly parentId: string | null;
+  readonly forkOfId: string | null;
+  readonly archived: boolean;
+  readonly deleted: boolean;
+  readonly updatedAtMs: number;
+  /** When the session last asked for the reader's attention (a turn ended, a question). */
+  readonly attentionAtMs: number;
+  /** Whether the reader has not looked since the last attention. */
+  readonly unread: boolean;
+  /** The host's environment identity for `sessions.start` reuse; never shown to a page. */
+  readonly environmentId: string | null;
+}
+
+export interface SessionListQuery {
+  readonly projectId?: string;
+  readonly archived: boolean;
+  /** Only sessions without a parent, the way the host's own sidebar lists them. */
+  readonly rootsOnly: boolean;
+  readonly offset: number;
+  readonly limit: number;
+}
+
+export type SendMode = "queue" | "steer";
+export type Delivery = "started" | "queued" | "steered";
+
+export interface StartSessionArgs {
+  readonly projectId: string;
+  readonly prompt: string;
+  readonly title?: string;
+  readonly providerId?: string;
+  readonly model?: string;
+  readonly reasoningLevel?: string;
+  readonly environment: { readonly kind: "project-default" } | { readonly kind: "reuse"; readonly environmentId: string };
+}
+
+export interface ActivityItem {
+  readonly kind: string;
+  readonly done: boolean;
+  readonly atMs: number;
+  readonly label: string;
+  readonly text: string;
+}
+
+export interface ProjectRecord {
+  readonly id: string;
+  readonly name: string;
+  readonly kind: "standard" | "personal";
+  /** Host id of the project's default source; needed to open a picker there. */
+  readonly hostId: string | null;
+}
+
+export interface ProviderChoice {
+  readonly id: string;
+  readonly displayName: string;
+  readonly available: boolean;
+  readonly models: readonly { readonly id: string; readonly displayName: string; readonly isDefault: boolean; readonly reasoningLevels: readonly string[] }[];
+}
+
+export interface StorageLocation {
+  readonly hostId: string;
+  readonly rootPath: string;
+}
+
+export interface FileContent {
+  readonly bytes: Uint8Array;
+  readonly sha256: string;
+  readonly modifiedAtMs: number | null;
+}
+
+export type WriteOutcome = "written" | "exists";
+
+export interface HostLogger {
+  debug(message: string): void;
+  info(message: string): void;
+  warn(message: string): void;
+  error(message: string): void;
+}

package/src/pages/layout.ts

@@ -0,0 +1,65 @@
+/**
+ * Where a page lives. spec 01 §Storage, RW-3
+ *
+ * The page root is the session's storage directory itself. The entry document
+ * is `index.html`; reader uploads land in `uploads/` under host-generated
+ * names. Everything else in the root is the page's own site.
+ */
+export const ENTRY_FILE = "index.html";
+export const UPLOAD_DIR = "uploads";
+/** The prototype's entry file, recognised only to tell an agent about it. */
+export const LEGACY_ENTRY_FILE = "thread-page.html";
+
+const UPLOAD_NAME = /^[0-9]{8}-[0-9]{6}-[a-f0-9]{6}-[A-Za-z0-9][A-Za-z0-9._-]{0,79}$/;
+
+export function joinPath(root: string, ...segments: string[]): string {
+  const base = root.replace(/[\\/]+$/, "");
+  return [base, ...segments].join("/");
+}
+
+export function entryPath(root: string): string {
+  return joinPath(root, ENTRY_FILE);
+}
+
+export function legacyEntryPath(root: string): string {
+  return joinPath(root, LEGACY_ENTRY_FILE);
+}
+
+export function uploadPath(root: string, name: string): string {
+  if (!isSafeUploadName(name)) throw new Error("Unsafe upload name");
+  return joinPath(root, UPLOAD_DIR, name);
+}
+
+/** The reader's filename reduced to a safe suffix; the host chooses the rest. spec R4.21 */
+export function sanitizeUploadSuffix(raw: string): string {
+  let decoded = raw;
+  try {
+    decoded = decodeURIComponent(raw);
+  } catch {
+    decoded = raw;
+  }
+  const base = decoded.split(/[\\/]/).pop() ?? "";
+  const cleaned = base.replace(/[^A-Za-z0-9._-]/g, "_").replace(/^[._-]+/, "");
+  return cleaned.slice(0, 80) || "upload";
+}
+
+/** `YYYYMMDD-HHMMSS-<6 hex>-<suffix>`; never taken from the reader. spec R4.21 */
+export function uploadFileName(originalName: string, now: number, randomHex: string): string {
+  const stamp = new Date(now).toISOString().replace(/[-:]/g, "").replace(/\..+$/, "").replace("T", "-");
+  const name = `${stamp}-${randomHex.slice(0, 6)}-${sanitizeUploadSuffix(originalName)}`;
+  if (!isSafeUploadName(name)) throw new Error("Generated upload name is invalid");
+  return name;
+}
+
+export function isSafeUploadName(name: string): boolean {
+  return UPLOAD_NAME.test(name) && !name.includes("..");
+}
+
+/**
+ * A relative path inside the page root: no absolute paths, no `.`/`..`/empty
+ * segments, no backslashes, no NUL. spec R1.4
+ */
+export function isSafeRelativePath(path: string): boolean {
+  if (path.length === 0 || path.length > 1024 || path.includes("\0") || path.includes("\\") || path.startsWith("/")) return false;
+  return path.split("/").every((segment) => segment.length > 0 && segment !== "." && segment !== "..");
+}