@north-light/cli 0.0.0 → 0.3.414

package/dist/core/human/feedback.d.ts

@@ -0,0 +1,62 @@
+import { z } from 'zod';
+export declare const PAGE_FEEDBACK_SCHEMA: "crtr.page-feedback/v1";
+/** The path is a presentation projection, not the feedback authority. */
+export declare function pageFeedbackPath(dir: string): string;
+declare const pageFeedbackCommentSchema: z.ZodObject<{
+    id: z.ZodString;
+    quote: z.ZodString;
+    context: z.ZodOptional<z.ZodString>;
+    note: z.ZodString;
+    status: z.ZodEnum<{
+        open: "open";
+        resolved: "resolved";
+    }>;
+    createdAt: z.ZodString;
+    resolvedAt: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+declare const pageFeedbackSchema: z.ZodObject<{
+    schema: z.ZodLiteral<"crtr.page-feedback/v1">;
+    companionNodeId: z.ZodOptional<z.ZodString>;
+    firstCommentedSha256: z.ZodOptional<z.ZodString>;
+    comments: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        quote: z.ZodString;
+        context: z.ZodOptional<z.ZodString>;
+        note: z.ZodString;
+        status: z.ZodEnum<{
+            open: "open";
+            resolved: "resolved";
+        }>;
+        createdAt: z.ZodString;
+        resolvedAt: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type PageFeedbackComment = z.infer<typeof pageFeedbackCommentSchema>;
+export type PageFeedback = z.infer<typeof pageFeedbackSchema>;
+/** Read page feedback from the request row. */
+export declare function readPageFeedback(dir: string): PageFeedback;
+export interface CreatePageFeedbackCommentInput {
+    quote: string;
+    context?: string;
+    note: string;
+    companionNodeId?: string;
+    firstCommentedSha256?: string;
+}
+export interface PageFeedbackMutation {
+    comment: PageFeedbackComment;
+    feedback: PageFeedback;
+}
+export declare class PageTicketTerminalError extends Error {
+    constructor();
+}
+export declare class UnknownPageFeedbackCommentError extends Error {
+    constructor(commentId: string);
+}
+export declare class PageFeedbackCommentAlreadyResolvedError extends Error {
+    constructor(commentId: string);
+}
+/** Append feedback in the request transaction; terminal rows reject it. */
+export declare function createPageFeedbackComment(dir: string, input: CreatePageFeedbackCommentInput): PageFeedbackMutation;
+/** Resolve one feedback comment in the request transaction. */
+export declare function resolvePageFeedbackComment(dir: string, commentId: string): PageFeedbackMutation;
+export {};

package/dist/core/human/feedback.js

@@ -0,0 +1 @@
+var h=Object.defineProperty;var r=(t,e)=>h(t,"name",{value:e,configurable:!0});import{prepared as c}from"../sqlite-statements.js";import{randomUUID as b}from"node:crypto";import{z as n}from"zod";import{withCanvasWrite as p}from"../canvas/db.js";import{getRequestByDirectory as w}from"./requests.js";const _="crtr.page-feedback/v1";function D(t){return`${t}/feedback-comments.json`}r(D,"pageFeedbackPath");const S=n.object({id:n.string().min(1),quote:n.string().min(1),context:n.string().optional(),note:n.string().min(1),status:n.enum(["open","resolved"]),createdAt:n.string().datetime({offset:!0}),resolvedAt:n.string().datetime({offset:!0}).optional()}).strict(),E=n.object({schema:n.literal(_),companionNodeId:n.string().min(1).optional(),firstCommentedSha256:n.string().min(1).optional(),comments:n.array(S)}).strict();function k(){return{schema:_,comments:[]}}r(k,"emptyFeedback");function u(t){const e=w(t);if(e===null||e.kind!=="page")throw new Error(`unknown page request directory: ${t}`);return e}r(u,"requestForDirectory");function f(t){if(t.feedback_json===null)return t.companion_node_id===null?k():{...k(),companionNodeId:t.companion_node_id};try{return E.parse(JSON.parse(t.feedback_json))}catch(e){throw new Error(`page feedback is malformed for ${t.request_id}`,{cause:e})}}r(f,"feedback");function I(t){return f(u(t))}r(I,"readPageFeedback");class l extends Error{static{r(this,"PageTicketTerminalError")}constructor(){super("ticket already has a terminal outcome")}}class q extends Error{static{r(this,"UnknownPageFeedbackCommentError")}constructor(e){super(`no feedback comment ${e} on this ticket`)}}class x extends Error{static{r(this,"PageFeedbackCommentAlreadyResolvedError")}constructor(e){super(`feedback comment ${e} is already resolved`)}}function N(t,e){const a=u(t);return p(i=>{const s=c(i,"SELECT * FROM human_requests WHERE request_id = ?").get(a.request_id);if(s===void 0)throw new Error(`human request disappeared: ${a.request_id}`);if(s.state!=="open")throw new l;const m={...a,feedback_json:s.feedback_json,companion_node_id:s.companion_node_id},o=f(m);o.companionNodeId===void 0&&e.companionNodeId!==void 0&&(o.companionNodeId=e.companionNodeId,e.firstCommentedSha256!==void 0&&(o.firstCommentedSha256=e.firstCommentedSha256));const d={id:b(),quote:e.quote,...e.context===void 0?{}:{context:e.context},note:e.note,status:"open",createdAt:new Date().toISOString()};return o.comments.push(d),E.parse(o),c(i,"UPDATE human_requests SET feedback_json = ?, companion_node_id = COALESCE(companion_node_id, ?), updated_at = ? WHERE request_id = ?").run(JSON.stringify(o),o.companionNodeId??null,new Date().toISOString(),a.request_id),{comment:d,feedback:o}})}r(N,"createPageFeedbackComment");function O(t,e){const a=u(t);return p(i=>{const s=c(i,"SELECT * FROM human_requests WHERE request_id = ?").get(a.request_id);if(s===void 0)throw new Error(`human request disappeared: ${a.request_id}`);if(s.state!=="open")throw new l;const m={...a,feedback_json:s.feedback_json,companion_node_id:s.companion_node_id},o=f(m),d=o.comments.find(g=>g.id===e);if(d===void 0)throw new q(e);if(d.status==="resolved")throw new x(e);return d.status="resolved",d.resolvedAt=new Date().toISOString(),c(i,"UPDATE human_requests SET feedback_json = ?, updated_at = ? WHERE request_id = ?").run(JSON.stringify(o),new Date().toISOString(),a.request_id),{comment:d,feedback:o}})}r(O,"resolvePageFeedbackComment");export{_ as PAGE_FEEDBACK_SCHEMA,x as PageFeedbackCommentAlreadyResolvedError,l as PageTicketTerminalError,q as UnknownPageFeedbackCommentError,N as createPageFeedbackComment,D as pageFeedbackPath,I as readPageFeedback,O as resolvePageFeedbackComment};

package/dist/core/human/page-authoring.d.ts

@@ -0,0 +1,30 @@
+import type { ProductPageComponents } from '../../types.js';
+import type { PageDelivery, PageManifest, PageSource } from './page-schema.js';
+/** One validated page, ready for the daemon to publish. */
+export interface PreparedPage {
+    /** The authored source, verbatim, as the request's `document`. */
+    document: string;
+    /** The compiled CommonJS module the Gateway evaluates for JSX pages. */
+    module?: string;
+    manifest: PageManifest;
+}
+export interface PreparePageSourceOptions {
+    /** `jsx` carries .tsx semantics; `html` is a complete document. */
+    dialect: 'jsx' | 'html';
+    /** The complete authored page text, inline. */
+    document: string;
+    source?: PageSource;
+    productKinds?: ProductPageComponents;
+    delivery?: PageDelivery;
+}
+export interface PreparePageOptions {
+    /** The authored page source. */
+    sourceFile: string;
+    source?: PageSource;
+    productKinds?: ProductPageComponents;
+    delivery?: PageDelivery;
+}
+/** Validate one authored page document into a transportable request. */
+export declare function preparePageSource(opts: PreparePageSourceOptions): PreparedPage;
+/** Validate one authored page source file without reading or writing canvas state. */
+export declare function preparePage(opts: PreparePageOptions): PreparedPage;

package/dist/core/human/page-authoring.js

@@ -0,0 +1 @@
+var c=Object.defineProperty;var r=(e,t)=>c(e,"name",{value:t,configurable:!0});import{existsSync as m,readFileSync as u}from"node:fs";import{compilePage as o,deriveHtmlPageManifest as l,derivePageManifestFromDocument as d,PageAuthoringError as n}from"./page.js";function a(e){const t={...e.source??{},emittedAt:e.source?.emittedAt??new Date().toISOString()},i=e.delivery??{placement:"inline",inbox:!1,reply:!1};return e.dialect==="html"?{document:e.document,manifest:l(e.document,t,i)}:{document:e.document,module:o(e.document),manifest:d(e.document,e.productKinds??[],t,i)}}r(a,"preparePageSource");function h(e){const t=/\.html?$/i.test(e.sourceFile);if(!t&&!e.sourceFile.endsWith(".tsx"))throw new n(`page source file must be .tsx, .html, or .htm: ${e.sourceFile}`);if(!m(e.sourceFile))throw new n(`page source file does not exist: ${e.sourceFile}`);return a({...e,dialect:t?"html":"jsx",document:u(e.sourceFile,"utf8")})}r(h,"preparePage");export{h as preparePage,a as preparePageSource};

package/dist/core/human/page-catalog.d.ts

@@ -0,0 +1,57 @@
+import type { PageComponentRegistration, ProductPageComponents } from '../../types.js';
+/** The page component kinds crtr validates and renders itself. */
+export declare const BUILTIN_PAGE_KINDS: readonly ["options", "text", "table", "cards", "chart"];
+export declare const STRUCTURAL_PAGE_KINDS: readonly ["page", "step"];
+export interface PageComponentCatalogEntry {
+    kind: string;
+    tag: string;
+    description: string;
+    useWhen: string;
+    doc?: string;
+    builtin: boolean;
+    structural: boolean;
+}
+/** The JSX component name a registered kind is authored as. Registry names reach page
+ *  code as JS identifiers, so a hyphenated kind is authored in its PascalCase form
+ *  (`worker-card` → `<WorkerCard>`); the registered kind string is what travels on
+ *  the wire. */
+export declare function pageComponentTag(kind: string): string;
+/** The built-in component kind each authored JSX component name maps to. */
+export declare const BUILTIN_KIND_BY_TAG: Readonly<Record<string, string>>;
+/** Every JSX identifier reserved by the built-in page registry, including structure. */
+export declare const BUILTIN_PAGE_COMPONENT_TAGS: ReadonlySet<string>;
+/** The shadcn display set a page may compose with. These carry no response and never
+ *  appear in the page manifest; they are in scope so an authored page can lay its
+ *  content out. */
+export declare const DISPLAY_PAGE_COMPONENT_TAGS: ReadonlySet<string>;
+/** Normalize legacy kind strings and documented product component registrations.
+ *  `label` names the source in every error message — the default is a scope
+ *  `config.json` block; a plugin contribution passes its own plugin-named
+ *  label so a bad registration points at the package that shipped it. */
+export declare function normalizePageComponents(raw: unknown, label?: string): PageComponentRegistration[];
+/** One contributing source of product page components: a scope's own
+ *  `config.json` block, or one installed plugin's manifest contributions. */
+export interface PageComponentLayer {
+    /** How this source is named in a collision error, e.g. `plugin "acme"`. */
+    origin: string;
+    components: readonly PageComponentRegistration[];
+}
+/** Concatenate every contributing layer into one active catalog, rejecting a
+ *  kind — or a derived JSX tag — that two sources both register. There is no
+ *  precedence here on purpose: two sources claiming one component kind is an
+ *  authoring defect, and silently letting either win would ship a page component
+ *  bound to a renderer nobody chose. Each layer's own entries are already
+ *  validated by `normalizePageComponents`; this is the cross-source gate. */
+export declare function mergePageComponentLayers(layers: readonly PageComponentLayer[]): PageComponentRegistration[];
+/** STRICT install-time validation of a plugin-declared `page_components` block
+ *  — the loud counterpart to a read path that must never ship a half-valid
+ *  catalog. Returns one human-readable reason per defect; empty = valid. Used
+ *  by the archive-bundle validator and by source plugin installs. */
+export declare function invalidPageComponentsReasons(raw: unknown): string[];
+/** Names-only projection for page validation and rendering consumers. */
+export declare function pageComponentKinds(components: readonly PageComponentRegistration[]): string[];
+/** Full built-in + product catalog for CLI discovery. */
+export declare function pageComponentCatalog(components: readonly PageComponentRegistration[]): PageComponentCatalogEntry[];
+/** Whether crtr or the product catalog registers a page component kind. */
+export declare function productPageComponent(kind: string, components: ProductPageComponents): PageComponentRegistration | undefined;
+export declare function isRegisteredPageKind(kind: string, productComponents: ProductPageComponents): boolean;

package/dist/core/human/page-catalog.js

@@ -0,0 +1 @@
+var $=Object.defineProperty;var s=(t,e)=>$(t,"name",{value:e,configurable:!0});const k=["options","text","table","cards","chart"],T=["page","step"],b=/^[a-z][a-z0-9-]{0,63}$/,w=new Set(k),h=[{kind:"page",tag:"Page",description:"the page itself: title, subtitle, and every step it contains",useWhen:"use as the single root element every page returns",builtin:!0,structural:!0},{kind:"step",tag:"Step",description:"one step inside a Page",useWhen:"use for each step the user sees and completes in sequence",builtin:!0,structural:!0},{kind:"options",tag:"UserQuestion",description:"known alternatives with single or multiple selection",useWhen:"use when the user picks among known alternatives, optionally with freetext",builtin:!0,structural:!1},{kind:"text",tag:"UserText",description:"writing surface whose answer is the text the user hands back",useWhen:"use when you need prose from the user \u2014 a value they write, or a draft they revise; prose they only read is a plain element",builtin:!0,structural:!1},{kind:"table",tag:"UserTable",description:"rows and columns with optional selection",useWhen:"use when structured records are easiest to compare in rows and columns",builtin:!0,structural:!1},{kind:"cards",tag:"UserCards",description:"visual records with optional selection",useWhen:"use when the user compares or picks richer items than a compact option list can carry",builtin:!0,structural:!1},{kind:"chart",tag:"Chart",description:"line, bar, or area data visualization",useWhen:"use when shape, trend, or magnitude matters more than exact tabular values",builtin:!0,structural:!1}];function l(t){return t.split("-").map(e=>e===""?"":`${e[0].toUpperCase()}${e.slice(1)}`).join("")}s(l,"pageComponentTag");const S=Object.fromEntries(h.filter(t=>!t.structural).map(t=>[t.tag,t.kind])),y=new Set(h.map(t=>t.tag)),_=new Set(["Card","CardHeader","CardTitle","CardDescription","CardContent","CardFooter","CardAction","Badge","Button","Separator","Progress","Alert","AlertTitle","AlertDescription","Table","TableHeader","TableBody","TableFooter","TableRow","TableHead","TableCell","TableCaption","Tabs","TabsList","TabsTrigger","TabsContent","Accordion","AccordionItem","AccordionTrigger","AccordionContent"]);function p(t){try{const e=JSON.stringify(t);return e===void 0?String(t):e}catch{return String(t)}}s(p,"describeEntry");function g(t,e,a,c){if(t!==void 0){if(typeof t!="string"||t.trim()==="")throw new Error(`${a}[${c}].${e} must be a non-empty string; received ${p(t)}`);return t.trim()}}s(g,"optionalText");function C(t,e="page_components"){if(t===void 0)return[];if(!Array.isArray(t))throw new Error(`${e} must be an array; received ${p(t)}`);const a=new Set,c=new Set;return t.map((r,n)=>{let u;if(typeof r=="string")u={kind:r.trim()};else if(r!==null&&typeof r=="object"&&!Array.isArray(r)){const o=r,f=Object.keys(o).filter(m=>!["kind","description","useWhen","doc","display"].includes(m));if(f.length>0)throw new Error(`${e}[${n}] has unknown field(s): ${f.join(", ")}`);if(typeof o.kind!="string")throw new Error(`${e}[${n}].kind must be a string; offending entry: ${p(r)}`);if(o.display!==void 0&&typeof o.display!="boolean")throw new Error(`${e}[${n}].display must be a boolean; offending entry: ${p(r)}`);u={kind:o.kind.trim(),...g(o.description,"description",e,n)===void 0?{}:{description:g(o.description,"description",e,n)},...g(o.useWhen,"useWhen",e,n)===void 0?{}:{useWhen:g(o.useWhen,"useWhen",e,n)},...g(o.doc,"doc",e,n)===void 0?{}:{doc:g(o.doc,"doc",e,n)},...o.display===!0?{display:!0}:{}}}else throw new Error(`${e}[${n}] must be a string or component object; offending entry: ${p(r)}`);const i=u.kind;if(!b.test(i))throw new Error(`${e}[${n}] has invalid page kind ${p(i)}; expected /^[a-z][a-z0-9-]{0,63}$/`);if(w.has(i)||T.includes(i))throw new Error(`${e}[${n}] collides with built-in page kind "${i}"`);if(a.has(i))throw new Error(`${e}[${n}] duplicates page kind "${i}"`);const d=l(i);if(y.has(d))throw new Error(`${e}[${n}] kind "${i}" derives JSX tag "${d}", which collides with a built-in page component`);if(c.has(d))throw new Error(`${e}[${n}] kind "${i}" derives JSX tag "${d}", which duplicates another product page component`);return a.add(i),c.add(d),u})}s(C,"normalizePageComponents");function P(t){const e=new Map,a=new Map,c=[];for(const r of t)for(const n of r.components){const u=e.get(n.kind);if(u!==void 0)throw new Error(`page component kind "${n.kind}" is registered by both ${u} and ${r.origin}`);const i=l(n.kind),d=a.get(i);if(d!==void 0)throw new Error(`page component kind "${n.kind}" (${r.origin}) derives JSX tag "${i}", which duplicates kind "${d.kind}" from ${d.origin}`);e.set(n.kind,r.origin),a.set(i,{kind:n.kind,origin:r.origin}),c.push(n)}return c}s(P,"mergePageComponentLayers");function I(t){try{return C(t),[]}catch(e){return[e instanceof Error?e.message:String(e)]}}s(I,"invalidPageComponentsReasons");function N(t){return t.map(e=>e.kind)}s(N,"pageComponentKinds");function W(t){return[...h,...t.map(e=>({kind:e.kind,tag:l(e.kind),description:e.description??"product-registered page component",useWhen:e.useWhen??"use when the product component matches the structured UI the user needs",...e.doc===void 0?{}:{doc:e.doc},builtin:!1,structural:!1}))]}s(W,"pageComponentCatalog");function E(t,e){return e.find(a=>a.kind===t)}s(E,"productPageComponent");function U(t,e){return w.has(t)||E(t,e)!==void 0}s(U,"isRegisteredPageKind");export{S as BUILTIN_KIND_BY_TAG,y as BUILTIN_PAGE_COMPONENT_TAGS,k as BUILTIN_PAGE_KINDS,_ as DISPLAY_PAGE_COMPONENT_TAGS,T as STRUCTURAL_PAGE_KINDS,I as invalidPageComponentsReasons,U as isRegisteredPageKind,P as mergePageComponentLayers,C as normalizePageComponents,W as pageComponentCatalog,N as pageComponentKinds,l as pageComponentTag,E as productPageComponent};

package/dist/core/human/page-errors.d.ts

@@ -0,0 +1,4 @@
+/** A page failed authoring or validation; the caller can report it as bad page input. */
+export declare class PageAuthoringError extends Error {
+    constructor(message: string);
+}

package/dist/core/human/page-errors.js

@@ -0,0 +1 @@
+var t=Object.defineProperty;var e=(o,r)=>t(o,"name",{value:r,configurable:!0});class n extends Error{static{e(this,"PageAuthoringError")}constructor(r){super(r),this.name="PageAuthoringError"}}export{n as PageAuthoringError};

package/dist/core/human/page-eval.d.ts

@@ -0,0 +1,25 @@
+/** One node in the rendered tree. Helper components are expanded before this point. */
+export type PageNode = PageElementNode | PageTextNode;
+export interface PageElementNode {
+    kind: 'element';
+    /** Registry component (`UserQuestion`), display component (`Card`), or plain element (`div`). */
+    tag: string;
+    props: Record<string, unknown>;
+    children: PageNode[];
+}
+export interface PageTextNode {
+    kind: 'text';
+    text: string;
+}
+/** Evaluate the compiled page module and return the element tree its default export renders.
+ *
+ *  Each in-scope component name is bound to itself, so `<UserQuestion>` renders as the tag
+ *  string `"UserQuestion"`. A name outside that set is not defined, and the page fails with
+ *  the reference error rather than rendering a component the host does not have. */
+export declare function evaluatePageTree(code: string, tags: Iterable<string>): PageNode[];
+/** Keep only what can cross the wire. A manifest is JSON, so handlers and undefined values
+ *  are dropped rather than rejected — a click handler is legitimate authoring, it simply has
+ *  no meaning to a host reading the manifest. The round-trip also rebuilds the props in this
+ *  realm: values born in the vm carry that realm's prototypes, which prototype-sensitive
+ *  comparisons reject. */
+export declare function jsonProps(props: Record<string, unknown>): Record<string, unknown>;

package/dist/core/human/page-eval.js

@@ -0,0 +1 @@
+var E=Object.defineProperty;var n=(r,t)=>E(r,"name",{value:t,configurable:!0});import l from"node:vm";import{PageAuthoringError as o}from"./page-errors.js";const m=2e3,S=64,w=Symbol("page.fragment");function b(){let r;const t=n(()=>r,"callable");return r=new Proxy(t,{get:n(()=>r,"get"),apply:n(()=>r,"apply")}),r}n(b,"hostStub");function _(){return{createElement:n((t,s,...a)=>{const{key:d,ref:i,...f}=s??{},e=a.flat(1/0);return typeof t=="function"?t({...f,...e.length===0?{}:{children:e}}):{$page_element:!0,type:t,props:f,children:e}},"createElement"),Fragment:w,useState:n(t=>[typeof t=="function"?t():t,()=>{}],"useState"),useReducer:n((t,s)=>[s,()=>{}],"useReducer"),useMemo:n(t=>t(),"useMemo"),useCallback:n(t=>t,"useCallback"),useRef:n(t=>({current:t}),"useRef"),useEffect:n(()=>{},"useEffect"),useLayoutEffect:n(()=>{},"useLayoutEffect"),useId:n(()=>"page-id","useId")}}n(_,"stubReact");function k(r){return typeof r=="object"&&r!==null&&r.$page_element===!0}n(k,"isRawElement");function I(r,t){const s={},a={React:_(),module:{exports:s},exports:s,console:{log:n(()=>{},"log"),warn:n(()=>{},"warn"),error:n(()=>{},"error"),info:n(()=>{},"info"),debug:n(()=>{},"debug")},usePageHost:b()};for(const e of t)a[e]=e;const d=Date.now()+m;let i;try{if(l.createContext(a),new l.Script(r,{filename:"page.tsx"}).runInContext(a,{timeout:m}),typeof a.module.exports.default!="function")throw new o("page module must `export default` a component function");i=new l.Script("(module.exports.default)({})",{filename:"page.tsx"}).runInContext(a,{timeout:m})}catch(e){if(e instanceof o)throw e;const c=e instanceof Error?e.message:String(e);throw new o(`page failed while rendering: ${c}`)}if(typeof i?.then=="function")throw new o("page component is async; a page renders synchronously");const f=n((e,c)=>{if(e==null||typeof e=="boolean")return[];if(c>S)throw new o("page nests deeper than a page can render; check for a component that renders itself");if(Date.now()>d)throw new o("page took too long to render; check for a component that never finishes");if(typeof e=="string"||typeof e=="number")return[{kind:"text",text:String(e)}];if(Array.isArray(e))return e.flatMap(g=>f(g,c+1));if(!k(e))return[];const{type:p,props:h,children:y}=e,u=[...f(h.children,c+1),...y.flatMap(g=>f(g,c+1))];if(p===w||typeof p!="string")return u;const{children:M,...x}=h;return[{kind:"element",tag:p,props:x,children:u}]},"normalize");try{return f(i,0)}catch(e){if(e instanceof o)throw e;const c=e instanceof Error?e.message:String(e);throw new o(`page failed while rendering: ${c}`)}}n(I,"evaluatePageTree");function T(r){try{return JSON.parse(JSON.stringify(r))}catch(t){const s=t instanceof Error?t.message:String(t);throw new o(`page prop cannot cross the wire: ${s}`)}}n(T,"jsonProps");export{I as evaluatePageTree,T as jsonProps};

package/dist/core/human/page-html-markdown.d.ts

@@ -0,0 +1,8 @@
+/** An HTML page's document projected to markdown, so a terminal reader sees the
+ *  page's actual content instead of a placeholder line. HTML pages are authored
+ *  for a browser surface and carry no slots, so this is a reading projection
+ *  only — layout, styling, and scripting are dropped, and what survives is the
+ *  prose, headings, lists, links, code, and table cells the author wrote. */
+/** Project one authored HTML document to markdown. Never throws: a document
+ *  this cannot make sense of yields whatever text it did find, down to ''. */
+export declare function projectHtmlDocumentMarkdown(document: string): string;

package/dist/core/human/page-html-markdown.js

@@ -0,0 +1,8 @@
+var A=Object.defineProperty;var f=(o,e)=>A(o,"name",{value:e,configurable:!0});const C=new Set(["script","style","head","template","noscript","svg","iframe","object"]),S=new Set(["address","article","aside","blockquote","details","dialog","div","dl","fieldset","figcaption","figure","footer","form","header","main","nav","p","section","summary","table","tbody","tfoot","thead","video"]),q=new Set(["area","base","br","col","embed","hr","img","input","link","meta","param","source","track","wbr"]),T={amp:"&",lt:"<",gt:">",quot:'"',apos:"'",nbsp:" ",mdash:"\u2014",ndash:"\u2013",hellip:"\u2026",rsquo:"\u2019",lsquo:"\u2018",rdquo:"\u201D",ldquo:"\u201C"},D=/<!--[\s\S]*?-->|<!\[CDATA\[[\s\S]*?\]\]>|<![^>]*>|<(\/?)([a-zA-Z][^\s/>]*)((?:"[^"]*"|'[^']*'|[^>])*?)\/?>/g,I=/([^\s=/>]+)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'>]+)))?/g;function k(o){return o.replace(/&(#x?[0-9a-fA-F]+|[a-zA-Z][a-zA-Z0-9]*);/g,(e,i)=>{if(i.startsWith("#")){const s=i[1]==="x"||i[1]==="X"?Number.parseInt(i.slice(2),16):Number.parseInt(i.slice(1),10);return Number.isFinite(s)&&s>0&&s<=1114111?String.fromCodePoint(s):e}return T[i.toLowerCase()]??e})}f(k,"decode");function O(o){const e=new Map;for(const i of o.matchAll(I))e.set(i[1].toLowerCase(),k(i[2]??i[3]??i[4]??""));return e}f(O,"attrsOf");function N(o){const e=[];let i=0;for(const s of o.matchAll(D))s.index>i&&e.push({kind:"text",text:o.slice(i,s.index)}),i=s.index+s[0].length,s[2]!==void 0&&e.push({kind:"tag",name:s[2].toLowerCase(),closing:s[1]==="/",selfClosing:s[0].endsWith("/>"),attrs:O(s[3]??"")});return i<o.length&&e.push({kind:"text",text:o.slice(i)}),e}f(N,"tokenize");function x(o){return o.replace(/([\\`*_[\]<>#])/g,"\\$1")}f(x,"escapeText");class v{static{f(this,"Sink")}buffers=[""];write(e){this.buffers[this.buffers.length-1]+=e}get top(){return this.buffers[this.buffers.length-1]}set top(e){this.buffers[this.buffers.length-1]=e}push(){this.buffers.push("")}pop(){return this.buffers.length>1?this.buffers.pop():""}get nested(){return this.buffers.length>1}line(){this.top=this.top.replace(/[ \t]+$/,""),this.top!==""&&!this.top.endsWith(`
+`)&&this.write(`
+`)}block(){this.top=this.top.replace(/[ \t\n]+$/,""),this.top!==""&&this.write(`
+
+`)}done(){return this.buffers.join("").replace(/\n{3,}/g,`
+
+`).replace(/[ \t]+\n/g,`
+`).trim()}}function L(o){const e=new v,i=[],s=[],c=[];let u=0,h=!1,p=!1,l=0;const $=f(()=>"  ".repeat(Math.max(0,i.length-1)),"indent");for(const a of N(o)){if(a.kind==="text"){if(c.length>0)continue;if(u>0){e.write(a.text);continue}const n=k(a.text).replace(/\s+/g," ");if(n.trim()===""){/\s/.test(n)&&e.write(" ");continue}e.write(x(n));continue}const{name:t,closing:r,attrs:d}=a;if(C.has(t)){if(r){const n=c.lastIndexOf(t);n>=0&&(c.length=n)}else a.selfClosing||c.push(t);continue}if(c.length>0)continue;const g=/^h([1-6])$/.exec(t);if(g!==null){e.block(),r||e.write(`${"#".repeat(Number(g[1]))} `);continue}if(t==="pre"){r?(u=Math.max(0,u-1),e.line(),e.write("```"),e.block()):(e.block(),e.write("```\n"),u++);continue}if(t==="br"){e.line();continue}if(t==="hr"){e.block(),e.write("---"),e.block();continue}if(t==="ul"||t==="ol"){r?i.pop():(e.block(),i.push({ordered:t==="ol",index:0})),r&&e.block();continue}if(t==="li"){if(r)continue;const n=i[i.length-1];e.line(),n===void 0?e.write("- "):(n.index++,e.write(`${$()}${n.ordered?`${n.index}. `:"- "}`));continue}if(t==="dt"||t==="dd"){e.line(),r||e.write(t==="dt"?"":"  ");continue}if(t==="tr"){r?(e.write(l>0?" |":""),p&&l>0&&(e.line(),e.write(`|${" --- |".repeat(l)}`)),e.line()):(e.line(),p=!1,l=0);continue}if(t==="td"||t==="th"){if(r){if(!h)continue;h=!1,e.write(e.pop().replace(/\s+/g," ").trim())}else t==="th"&&(p=!0),l++,e.write(l===1?"| ":" | "),e.push(),h=!0;continue}if(t==="a"){if(r){if(s.length===0)continue;const w=s.pop();if(w===null)continue;const m=e.pop().replace(/\s+/g," ").trim();m!==""&&e.write(`[${m}](${w})`);continue}const n=d.get("href"),b=n!==void 0&&n!==""&&!n.startsWith("#");s.push(b?n:null),b&&e.push();continue}if(t==="code"&&u===0){e.write("`");continue}if(t==="strong"||t==="b"){e.write("**");continue}if(t==="em"||t==="i"){e.write("*");continue}if(t==="img"){const n=d.get("alt");n!==void 0&&n!==""&&e.write(x(n));continue}if(t==="blockquote"){e.block(),r||e.write("> ");continue}if(S.has(t)&&!q.has(t)){e.block();continue}}return e.done()}f(L,"projectHtmlDocumentMarkdown");export{L as projectHtmlDocumentMarkdown};

package/dist/core/human/page-markdown.d.ts

@@ -0,0 +1,3 @@
+import type { PageManifest } from './page-schema.js';
+/** Project the authored display JSX only. Manifest slots remain the authoritative terminal rendering for questions, inputs, charts, and product components. */
+export declare function projectPageDisplayMarkdown(document: string, manifest: PageManifest): string;

package/dist/core/human/page-markdown.js

@@ -0,0 +1,17 @@
+var w=Object.defineProperty;var o=(n,r)=>w(n,"name",{value:r,configurable:!0});import{BUILTIN_KIND_BY_TAG as P,BUILTIN_PAGE_COMPONENT_TAGS as S,DISPLAY_PAGE_COMPONENT_TAGS as _,pageComponentTag as j}from"./page-catalog.js";import{evaluatePageTree as v}from"./page-eval.js";import{PageAuthoringError as I}from"./page-errors.js";import{compilePage as N}from"./page.js";const M=new Set(Object.keys(P)),B=new Set(["Page","Step","Card","CardHeader","CardTitle","CardDescription","CardContent","CardFooter","CardAction","Separator","Progress","Alert","AlertTitle","AlertDescription","Table","TableHeader","TableBody","TableFooter","TableRow","TableHead","TableCell","TableCaption","Tabs","TabsList","TabsTrigger","TabsContent","Accordion","AccordionItem","AccordionTrigger","AccordionContent","address","article","aside","blockquote","details","dialog","div","dl","dt","dd","fieldset","figcaption","figure","footer","form","h1","h2","h3","h4","h5","h6","header","hr","li","main","nav","ol","p","pre","section","summary","table","thead","tbody","tfoot","tr","th","td","ul"]);function p(n){return n.kind==="element"}o(p,"isElement");function T(n){return n.replace(/\s+/g," ").replace(/([\\`*_[\]<>#])/g,"\\$1")}o(T,"markdownText");function i(n){return n.replace(/[ \t]+\n/g,`
+`).replace(/\n[ \t]+/g,`
+`).trim()}o(i,"cleanInline");function y(n,r){let t="";for(const e of n){if(!p(e)){t+=e.text;continue}r.slotTags.has(e.tag)||(t+=y(e.children,r))}return t}o(y,"rawText");function D(n){const r=n.replace(/\s+/g," ").trim();if(r==="")return"";const t=Math.max(0,...[...r.matchAll(/`+/g)].map(a=>a[0].length)),e="`".repeat(t+1),s=/^`|`$|^ | $/.test(r)?" ":"";return`${e}${s}${r}${s}${e}`}o(D,"inlineCode");function g(n,r){let t="";for(const e of n){if(!p(e)){t+=T(e.text);continue}if(r.slotTags.has(e.tag))continue;const s=o(()=>g(e.children,r),"body");switch(e.tag){case"br":t+=`
+`;break;case"code":t+=D(y(e.children,r));break;case"strong":case"b":{const a=i(s());a!==""&&(t+=`**${a}**`);break}case"em":case"i":{const a=i(s());a!==""&&(t+=`*${a}*`);break}case"del":case"s":{const a=i(s());a!==""&&(t+=`~~${a}~~`);break}case"a":{const a=i(s()),c=e.props.href;t+=typeof c=="string"&&c!==""?`[${a===""?T(c):a}](${c.replace(/([\\()])/g,"\\$1")})`:a;break}case"img":{const a=typeof e.props.alt=="string"?T(e.props.alt):"image",c=e.props.src;t+=typeof c=="string"&&c!==""?`![${a}](${c.replace(/([\\()])/g,"\\$1")})`:a;break}case"Badge":{const a=i(s());a!==""&&(t+=`**${a}**`);break}default:t+=s()}}return t}o(g,"inline");function C(n){return n.split(`
+`).map(r=>r===""?">":`> ${r}`).join(`
+`)}o(C,"quote");function G(n){const r=[n.props.className],t=n.children.find(e=>p(e)&&e.tag==="code");t!==void 0&&r.push(t.props.className);for(const e of r){if(typeof e!="string")continue;const s=/(?:^|\s)language-([A-Za-z0-9_+-]+)/.exec(e)?.[1];if(s!==void 0)return s}return""}o(G,"languageFor");function O(n,r){const t=y(n.children,r).replace(/^\n/,"").replace(/\n$/,"");if(t==="")return"";const e=Math.max(0,...[...t.matchAll(/`+/g)].map(a=>a[0].length)),s="`".repeat(Math.max(3,e+1));return`${s}${G(n)}
+${t}
+${s}`}o(O,"codeBlock");function k(n,r,t){return n.children.filter(s=>p(s)&&s.tag==="li").map((s,a)=>{const c=r?`${a+1}.`:"-",u=A(s.children,t);if(u==="")return"";const f=" ".repeat(c.length+1);return u.split(`
+`).map((m,$)=>$===0?`${c} ${m}`:m===""?"":`${f}${m}`).join(`
+`)}).filter(s=>s!=="").join(`
+`)}o(k,"list");function x(n,r){const t=[];let e="";const s=o(d=>{for(const l of d)if(!(!p(l)||r.slotTags.has(l.tag))){if(l.tag==="TableCaption"||l.tag==="caption"){e=i(g(l.children,r));continue}if(l.tag==="TableRow"||l.tag==="tr"){const b=l.children.filter(h=>p(h)&&["TableHead","TableCell","th","td"].includes(h.tag));b.length>0&&t.push({header:b.every(h=>h.tag==="TableHead"||h.tag==="th"),cells:b.map(h=>i(g(h.children,r)).replaceAll("|","\\|").replaceAll(`
+`,"<br>"))});continue}s(l.children)}},"visit");if(s(n.children),t.length===0)return A(n.children,r);const a=t.findIndex(d=>d.header),c=a===-1?t[0]:t[a],u=t.filter((d,l)=>l!==(a===-1?0:a)),f=Math.max(c.cells.length,...u.map(d=>d.cells.length)),m=o(d=>Array.from({length:f},(l,b)=>d[b]??""),"cells"),$=[`| ${m(c.cells).join(" | ")} |`,`| ${Array.from({length:f},()=>"---").join(" | ")} |`,...u.map(d=>`| ${m(d.cells).join(" | ")} |`)];return e!==""&&$.push("",`*${e}*`),$.join(`
+`)}o(x,"table");function E(n,r){if(r.slotTags.has(n.tag))return"";const t=o(()=>A(n.children,r),"contents");switch(n.tag){case"Page":return t();case"Step":{const e=n.props.title,s=t();return[typeof e=="string"&&e.trim()!==""?`## ${T(e.trim())}`:"",s].filter(c=>c!=="").join(`
+
+`)}case"p":return i(g(n.children,r));case"h1":case"h2":case"h3":case"h4":case"h5":case"h6":{const e=i(g(n.children,r)),s=Math.min(6,Number(n.tag[1])+1);return e===""?"":`${"#".repeat(s)} ${e}`}case"ul":return k(n,!1,r);case"ol":return k(n,!0,r);case"li":return i(t());case"pre":return O(n,r);case"blockquote":return C(t());case"hr":case"Separator":return"---";case"CardTitle":case"AlertTitle":{const e=i(g(n.children,r));return e===""?"":`**${e}**`}case"CardDescription":return i(g(n.children,r));case"Alert":{const e=t();return e===""?"":C(e)}case"AlertDescription":return t();case"Table":case"table":return x(n,r);case"TableRow":case"TableHead":case"TableCell":case"tr":case"th":case"td":return i(g(n.children,r));case"TabsTrigger":case"AccordionTrigger":case"summary":case"dt":{const e=i(g(n.children,r));return e===""?"":`**${e}**`}case"Progress":{const e=t(),s=n.props.value;return e!==""?e:typeof s=="number"||typeof s=="string"?`Progress: ${T(String(s))}%`:""}default:return t()}}o(E,"block");function A(n,r){const t=[];let e="";const s=o(()=>{const a=i(e);e="",a!==""&&t.push(a)},"flush");for(const a of n){if(!p(a)||!r.slotTags.has(a.tag)&&!B.has(a.tag)){e+=p(a)?g([a],r):T(a.text);continue}s();const c=E(a,r).trim();c!==""&&t.push(c)}return s(),t.join(`
+
+`)}o(A,"flow");function K(n,r){if(r.dialect!=="jsx")return"";const t=new Set(r.slots.filter(u=>u.unvalidated===!0).map(u=>j(u.kind))),e=[...S,..._,...t],s=v(N(n),e),a=[],c=o(u=>{for(const f of u)p(f)&&(f.tag==="Page"&&a.push(f),c(f.children))},"collect");if(c(s),a.length!==1)throw new I(`page display projection expected one <Page> element; found ${a.length}`);return A(a[0].children,{slotTags:new Set([...M,...t])}).trim()}o(K,"projectPageDisplayMarkdown");export{K as projectPageDisplayMarkdown};

package/dist/core/human/page-schema.d.ts

@@ -0,0 +1,289 @@
+import { z } from 'zod';
+import { BUILTIN_PAGE_KINDS } from './page-catalog.js';
+import type { ProductPageComponents } from '../../types.js';
+export declare const PAGE_SLOT_ID_PATTERN: RegExp;
+export declare const pageCommentAnchorSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"option">;
+    optionId: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"row">;
+    rowId: z.ZodString;
+}, z.core.$strict>], "kind">;
+export type PageCommentAnchor = z.infer<typeof pageCommentAnchorSchema>;
+export declare const commentSchema: z.ZodObject<{
+    id: z.ZodString;
+    anchor: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"option">;
+        optionId: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"row">;
+        rowId: z.ZodString;
+    }, z.core.$strict>], "kind">;
+    text: z.ZodString;
+}, z.core.$strict>;
+export type Comment = z.infer<typeof commentSchema>;
+export declare const optionSchema: z.ZodObject<{
+    id: z.ZodString;
+    label: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    recommended: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;
+export declare const optionsConfigSchema: z.ZodObject<{
+    label: z.ZodOptional<z.ZodString>;
+    body: z.ZodOptional<z.ZodString>;
+    options: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        label: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        recommended: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>>;
+    mode: z.ZodEnum<{
+        single: "single";
+        multi: "multi";
+    }>;
+    required: z.ZodOptional<z.ZodBoolean>;
+    allowFreetext: z.ZodOptional<z.ZodBoolean>;
+    freetextLabel: z.ZodOptional<z.ZodString>;
+    freetextPlaceholder: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type OptionsConfig = z.infer<typeof optionsConfigSchema>;
+export declare const optionsResponseSchema: z.ZodObject<{
+    selectedOptionIds: z.ZodArray<z.ZodString>;
+    comments: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        anchor: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            kind: z.ZodLiteral<"option">;
+            optionId: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"row">;
+            rowId: z.ZodString;
+        }, z.core.$strict>], "kind">;
+        text: z.ZodString;
+    }, z.core.$strict>>;
+    freetext: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type OptionsResponse = z.infer<typeof optionsResponseSchema>;
+export declare const textConfigSchema: z.ZodObject<{
+    label: z.ZodOptional<z.ZodString>;
+    initialText: z.ZodString;
+    placeholder: z.ZodOptional<z.ZodString>;
+    singleLine: z.ZodOptional<z.ZodBoolean>;
+    required: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;
+export type TextConfig = z.infer<typeof textConfigSchema>;
+export declare const textResponseSchema: z.ZodObject<{
+    text: z.ZodString;
+    edited: z.ZodBoolean;
+}, z.core.$strict>;
+export type TextResponse = z.infer<typeof textResponseSchema>;
+export declare const tableColumnSchema: z.ZodObject<{
+    id: z.ZodString;
+    label: z.ZodString;
+    align: z.ZodOptional<z.ZodEnum<{
+        left: "left";
+        right: "right";
+    }>>;
+    mono: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;
+export declare const tableCellSchema: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>;
+export declare const tableRowSchema: z.ZodObject<{
+    id: z.ZodString;
+    cells: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>;
+}, z.core.$strict>;
+export declare const tableRowsSchema: z.ZodArray<z.ZodObject<{
+    id: z.ZodString;
+    cells: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>;
+}, z.core.$strict>>;
+/** Table config: its data is always embedded. */
+export declare const tableConfigSchema: z.ZodObject<{
+    label: z.ZodOptional<z.ZodString>;
+    body: z.ZodOptional<z.ZodString>;
+    columns: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        label: z.ZodString;
+        align: z.ZodOptional<z.ZodEnum<{
+            left: "left";
+            right: "right";
+        }>>;
+        mono: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>>;
+    rows: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        cells: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>;
+    }, z.core.$strict>>>;
+    rowSelect: z.ZodDefault<z.ZodEnum<{
+        none: "none";
+        single: "single";
+        multi: "multi";
+    }>>;
+    columnSelect: z.ZodDefault<z.ZodEnum<{
+        none: "none";
+        single: "single";
+        multi: "multi";
+    }>>;
+    required: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;
+export type TableConfig = z.infer<typeof tableConfigSchema>;
+export declare const tableResponseSchema: z.ZodObject<{
+    selectedRowIds: z.ZodArray<z.ZodString>;
+    selectedColumnIds: z.ZodArray<z.ZodString>;
+    comments: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        anchor: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            kind: z.ZodLiteral<"option">;
+            optionId: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"row">;
+            rowId: z.ZodString;
+        }, z.core.$strict>], "kind">;
+        text: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type TableResponse = z.infer<typeof tableResponseSchema>;
+export declare const cardSchema: z.ZodObject<{
+    id: z.ZodString;
+    title: z.ZodString;
+    subtitle: z.ZodOptional<z.ZodString>;
+    body: z.ZodOptional<z.ZodString>;
+    tag: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export declare const cardsSchema: z.ZodArray<z.ZodObject<{
+    id: z.ZodString;
+    title: z.ZodString;
+    subtitle: z.ZodOptional<z.ZodString>;
+    body: z.ZodOptional<z.ZodString>;
+    tag: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>>;
+/** Cards config: its data is always embedded. */
+export declare const cardsConfigSchema: z.ZodObject<{
+    label: z.ZodOptional<z.ZodString>;
+    body: z.ZodOptional<z.ZodString>;
+    cards: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        title: z.ZodString;
+        subtitle: z.ZodOptional<z.ZodString>;
+        body: z.ZodOptional<z.ZodString>;
+        tag: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>>;
+    mode: z.ZodEnum<{
+        single: "single";
+        multi: "multi";
+    }>;
+    columns: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<2>, z.ZodLiteral<3>]>>;
+    required: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;
+export type CardsConfig = z.infer<typeof cardsConfigSchema>;
+export declare const cardsResponseSchema: z.ZodObject<{
+    selectedCardIds: z.ZodArray<z.ZodString>;
+}, z.core.$strict>;
+export type CardsResponse = z.infer<typeof cardsResponseSchema>;
+export declare const chartSeriesSchema: z.ZodObject<{
+    field: z.ZodString;
+    label: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export declare const chartDataRowsSchema: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+/** Chart config: its data is always embedded. */
+export declare const chartConfigSchema: z.ZodObject<{
+    kind: z.ZodEnum<{
+        line: "line";
+        bar: "bar";
+        area: "area";
+    }>;
+    x: z.ZodString;
+    y: z.ZodArray<z.ZodObject<{
+        field: z.ZodString;
+        label: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    title: z.ZodOptional<z.ZodString>;
+    data: z.ZodOptional<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+}, z.core.$strict>;
+export type ChartConfig = z.infer<typeof chartConfigSchema>;
+export type SlotConfig = OptionsConfig | TextConfig | TableConfig | CardsConfig | ChartConfig | Record<string, unknown>;
+export type SlotResponse = OptionsResponse | TextResponse | TableResponse | CardsResponse | Record<string, unknown>;
+export interface PageSlot {
+    id?: string;
+    kind: string;
+    step: number;
+    config: SlotConfig;
+    unvalidated?: true;
+    /** Product registration declares this component display-only, so it carries no response. */
+    display?: true;
+}
+export interface PageSource {
+    sessionName?: string;
+    askedBy?: string;
+    emittedAt?: string;
+    profileName?: string;
+    nodeId?: string;
+}
+export interface PageDelivery {
+    placement: 'inline' | 'panel';
+    inbox: boolean;
+    /** Routing only: whether an answer travels back to a resident agent's bridge. Never whether the page can be answered — {@link pageAwaitsResponse} decides that. */
+    reply: boolean;
+}
+export interface PageManifest {
+    schema: 'crtr.page/v2';
+    dialect: 'jsx' | 'html';
+    title: string;
+    subtitle?: string;
+    delivery: PageDelivery;
+    document: 'page.tsx' | 'page.html';
+    steps: number;
+    slots: PageSlot[];
+    source?: PageSource;
+}
+export declare const pageDeliverySchema: z.ZodObject<{
+    placement: z.ZodEnum<{
+        inline: "inline";
+        panel: "panel";
+    }>;
+    inbox: z.ZodBoolean;
+    reply: z.ZodBoolean;
+}, z.core.$strict>;
+export declare const BUILTIN_PAGE_CONFIG_SCHEMAS: Record<(typeof BUILTIN_PAGE_KINDS)[number], z.ZodType>;
+export declare const BUILTIN_PAGE_RESPONSE_SCHEMAS: Partial<Record<(typeof BUILTIN_PAGE_KINDS)[number], z.ZodType>>;
+export declare function issueText(error: z.ZodError): string;
+/** One question's recommended option, named well enough for a list row to draw it without reading the page. */
+export interface RecommendedOption {
+    slotId: string;
+    optionId: string;
+    label: string;
+}
+/**
+ * What one keypress on an inbox row publishes. `responses` is a complete, already-valid
+ * final response map, so the surface that sends it never assembles or interprets one.
+ * `kind` carries the semantic only — the words shown to a person belong to the surface.
+ */
+export interface PageFastAction {
+    kind: 'answer' | 'acknowledge';
+    responses: PageResponses;
+}
+/**
+ * The two independent overview facts: what a row displays, and what it can publish.
+ * A page can recommend without being fast-settleable — a recommendation beside a sibling
+ * input is still worth showing, but only the page itself can answer the rest of it.
+ */
+export interface PageOverviewActions {
+    recommendedOptions: RecommendedOption[];
+    fastAction?: PageFastAction;
+}
+/** Derive both overview facts from a manifest alone. Pure: no ticket state, no second read. */
+export declare function pageOverviewActions(manifest: PageManifest): PageOverviewActions;
+/** Whether this page is waiting on a person: it asks something, or an agent bridge is parked on its reply. */
+export declare function pageAwaitsResponse(manifest: PageManifest): boolean;
+/** The canonical response-bearing predicate used by every page consumer. */
+export declare function isResponseBearingSlot(slot: PageSlot): boolean;
+/** Validate a persisted manifest. Publish-time validation made its slots authoritative, so reads do not resolve a component catalog. */
+export declare function validatePageManifest(parsed: unknown): PageManifest;
+/** Validate a manifest derived from an authored page, where the display flag comes from the registration rather than the source. */
+export declare function validateAuthoredPageManifest(parsed: unknown, productComponents?: ProductPageComponents): PageManifest;
+export declare function createPageManifestSchema(): z.ZodType<PageManifest>;
+export declare const pageManifestSchema: z.ZodType<PageManifest, unknown, z.core.$ZodTypeInternals<PageManifest, unknown>>;
+export type PageResponses = Record<string, SlotResponse>;
+/** A picker's minimum: authored `required` wins, else the mode's own reading of an empty answer. */
+export declare function optionsRequired(config: OptionsConfig): boolean;
+/** Validate a complete final response map. */
+export declare function validatePageResponses(manifest: PageManifest, responses: unknown): PageResponses;
+/** Validate an autosaved response map, permitting omitted response-bearing components. */
+export declare function validatePartialPageResponses(manifest: PageManifest, responses: unknown): PageResponses;

package/dist/core/human/page-schema.js

@@ -0,0 +1 @@
+var q=Object.defineProperty;var c=(t,o)=>q(t,"name",{value:o,configurable:!0});import{z as e}from"zod";import{BUILTIN_PAGE_KINDS as P,productPageComponent as A}from"./page-catalog.js";const O=/^[A-Za-z0-9_-]{1,64}$/,_=e.string().regex(O,{error:"slot id must match /^[A-Za-z0-9_-]{1,64}$/"}),p=e.string().min(1),k=e.enum(["none","single","multi"]),w=e.record(e.string(),e.unknown());function m(t,o,s){const i=new Set;t.forEach((r,d)=>{i.has(r.id)&&o.addIssue({code:"custom",path:[d,"id"],message:`duplicate ${s} id "${r.id}"`}),i.add(r.id)})}c(m,"uniqueIds");const M=e.discriminatedUnion("kind",[e.object({kind:e.literal("option"),optionId:p}).strict(),e.object({kind:e.literal("row"),rowId:p}).strict()]),x=e.object({id:e.string().min(1),anchor:M,text:e.string()}).strict(),N=e.object({id:p,label:e.string().min(1),description:e.string().optional(),recommended:e.boolean().optional()}).strict(),T=e.object({label:e.string().optional(),body:e.string().optional(),options:e.array(N).min(1).superRefine((t,o)=>m(t,o,"option")),mode:e.enum(["single","multi"]),required:e.boolean().optional(),allowFreetext:e.boolean().optional(),freetextLabel:e.string().optional(),freetextPlaceholder:e.string().optional()}).strict().superRefine((t,o)=>{const s=t.options.filter(i=>i.recommended===!0);s.length>1&&o.addIssue({code:"custom",path:["options"],message:`at most one option may be recommended, but ${s.length} are`})}),I=e.object({selectedOptionIds:e.array(p),comments:e.array(x),freetext:e.string().optional()}).strict(),F=e.object({label:e.string().optional(),initialText:e.string(),placeholder:e.string().optional(),singleLine:e.boolean().optional(),required:e.boolean().optional()}).strict(),S=e.object({text:e.string(),edited:e.boolean()}).strict(),L=e.object({id:p,label:e.string().min(1),align:e.enum(["left","right"]).optional(),mono:e.boolean().optional()}).strict(),B=e.union([e.string(),e.number(),e.boolean(),e.null()]),G=e.object({id:p,cells:e.record(e.string(),B)}).strict(),U=e.array(G).superRefine((t,o)=>m(t,o,"row")),z={label:e.string().optional(),body:e.string().optional(),columns:e.array(L).min(1).superRefine((t,o)=>m(t,o,"column")),rows:U.optional(),rowSelect:k.default("none"),columnSelect:k.default("none"),required:e.boolean().optional()},D=e.object(z).strict(),y=e.object({selectedRowIds:e.array(p),selectedColumnIds:e.array(p),comments:e.array(x)}).strict(),H=e.object({id:p,title:e.string().min(1),subtitle:e.string().optional(),body:e.string().optional(),tag:e.string().optional()}).strict(),Z=e.array(H).superRefine((t,o)=>m(t,o,"card")),K={label:e.string().optional(),body:e.string().optional(),cards:Z.optional(),mode:e.enum(["single","multi"]),columns:e.union([e.literal(2),e.literal(3)]).optional(),required:e.boolean().optional()},J=e.object(K).strict(),E=e.object({selectedCardIds:e.array(p)}).strict(),Q=e.object({field:e.string().min(1),label:e.string().optional()}).strict(),V=e.array(e.record(e.string(),e.unknown())),W={kind:e.enum(["line","bar","area"]),x:e.string().min(1),y:e.array(Q).min(1),title:e.string().optional(),data:V.optional()},X=e.object(W).strict(),Y=e.object({sessionName:e.string().optional(),askedBy:e.string().optional(),emittedAt:e.string().datetime({offset:!0}).optional(),profileName:e.string().optional(),nodeId:e.string().optional()}).strict(),ee=e.object({placement:e.enum(["inline","panel"]),inbox:e.boolean(),reply:e.boolean()}).strict(),te=e.object({id:_.optional(),kind:e.string().min(1),step:e.number().int().nonnegative(),config:w,unvalidated:e.literal(!0).optional(),display:e.literal(!0).optional()}).strict(),ne=e.object({schema:e.literal("crtr.page/v2"),dialect:e.enum(["jsx","html"]),title:e.string().trim().min(1),subtitle:e.string().optional(),delivery:ee,document:e.enum(["page.tsx","page.html"]),steps:e.number().int().positive(),slots:e.array(te),source:Y.optional()}).strict().superRefine((t,o)=>{t.dialect==="jsx"!=(t.document==="page.tsx")&&o.addIssue({code:"custom",path:["document"],message:"document must agree with dialect"}),t.dialect==="html"&&(t.steps!==1||t.slots.length!==0)&&o.addIssue({code:"custom",path:["slots"],message:"HTML pages have exactly one step and no slots"})}),oe={options:T,text:F,table:D,cards:J,chart:X},le={options:I,text:S,table:y,cards:E};function f(t){return t.issues.map(o=>`${o.path.length===0?"value":o.path.join(".")}: ${o.message}`).join("; ")}c(f,"issueText");function pe(t){const o=[];for(const d of t.slots){if(d.kind!=="options"||d.id===void 0)continue;const n=d.config.options.find(a=>a.recommended===!0);n!==void 0&&o.push({slotId:d.id,optionId:n.id,label:n.label})}if(t.delivery.placement!=="panel")return{recommendedOptions:o};const s=t.slots.filter(g);if(s.length===0)return{recommendedOptions:o,fastAction:{kind:"acknowledge",responses:{}}};if(s.length>1)return{recommendedOptions:o};const i=s[0],r=o.find(d=>d.slotId===i.id);return i.kind!=="options"||r===void 0?{recommendedOptions:o}:{recommendedOptions:o,fastAction:{kind:"answer",responses:{[i.id]:{selectedOptionIds:[r.optionId],comments:[]}}}}}c(pe,"pageOverviewActions");function ue(t){return t.delivery.reply||t.slots.some(g)}c(ue,"pageAwaitsResponse");function g(t){if(t.display===!0)return!1;if(t.unvalidated===!0||t.kind==="options"||t.kind==="text"||t.kind==="cards")return!0;if(t.kind!=="table")return!1;const o=t.config;return(o.rowSelect??"none")!=="none"||(o.columnSelect??"none")!=="none"}c(g,"isResponseBearingSlot");function v(t,o,s){const i=ne.parse(t);if(!s&&i.dialect==="html")return i;const r=new Set,d=i.slots.map((n,a)=>{if(n.step>=i.steps)throw new Error(`slot ${n.id===void 0?`#${a}`:`"${n.id}"`} has step ${n.step}, outside page steps ${i.steps}`);let l;if(P.includes(n.kind)){if(n.unvalidated===!0)throw new Error(`built-in slot kind "${n.kind}" cannot be unvalidated`);if(n.display===!0)throw new Error(`built-in slot kind "${n.kind}" cannot set display: true`);const u=oe[n.kind].safeParse(n.config);if(!u.success)throw new Error(`invalid config for slot ${n.id===void 0?`#${a}`:`"${n.id}"`} (${n.kind}): ${f(u.error)}`);if(s&&n.kind==="options"){const b=u.data,$=n.id===void 0?`#${a}`:`"${n.id}"`;if((b.label??"").trim()==="")throw new Error(`slot ${$} (options): label is required \u2014 the question itself, drawn as the bold first line`);if((b.body??"").trim()==="")throw new Error(`slot ${$} (options): body is required \u2014 the context under the question a label cannot carry`)}l={...n.id===void 0?{}:{id:n.id},kind:n.kind,step:n.step,config:u.data}}else{const u=o===void 0?void 0:A(n.kind,o);if(s&&u===void 0)throw new Error(`unregistered page slot kind "${n.kind}" at slot #${a}`);if(n.unvalidated!==!0)throw new Error(`registered page slot kind "${n.kind}" must set unvalidated: true`);if(!s)l={...n.id===void 0?{}:{id:n.id},kind:n.kind,step:n.step,config:n.config,unvalidated:!0,...n.display===!0?{display:!0}:{}};else{if(n.display===!0&&u?.display!==!0)throw new Error(`non-display page slot kind "${n.kind}" cannot set display: true`);l={...n.id===void 0?{}:{id:n.id},kind:n.kind,step:n.step,config:n.config,unvalidated:!0,...u?.display===!0?{display:!0}:{}}}}if(g(l)&&l.id===void 0)throw new Error(l.unvalidated===!0?`product slot kind "${l.kind}" at slot #${a} requires an id prop`:`response-bearing slot kind "${l.kind}" at slot #${a} requires an id prop`);if(l.id!==void 0){if(r.has(l.id))throw new Error(`duplicate slot id "${l.id}"`);r.add(l.id)}return l});return{...i,slots:d}}c(v,"validateManifest");function j(t){return v(t,void 0,!1)}c(j,"validatePageManifest");function fe(t,o=[]){return v(t,o,!0)}c(fe,"validateAuthoredPageManifest");function ie(){return e.custom(t=>{try{return j(t),!0}catch{return!1}},{error:"invalid page manifest"}).transform(t=>j(t))}c(ie,"createPageManifestSchema");const me=ie();function h(t,o,s){if(new Set(t).size!==t.length)throw new Error(`slot "${o}" has duplicate id in ${s}`)}c(h,"assertUnique");function C(t,o){const s=t.config;for(const i of o){const r=i.anchor;if(t.kind==="options"&&r.kind==="option"){if(!s.options.some(d=>d.id===r.optionId))throw new Error(`slot "${t.id}" comment names unknown option id "${r.optionId}"`);continue}if(t.kind==="table"&&r.kind==="row"){if(!(s.rows??[]).some(d=>d.id===r.rowId))throw new Error(`slot "${t.id}" comment names unknown row id "${r.rowId}"`);continue}throw new Error(`slot "${t.id}" does not allow comment anchor kind "${r.kind}"`)}}c(C,"validateComments");function re(t){return t.required??t.mode==="single"}c(re,"optionsRequired");function se(t,o){if(t.unvalidated===!0){const s=w.safeParse(o);if(!s.success)throw new Error(`response for unvalidated slot "${t.id}" must be an object`);return s.data}if(t.kind==="options"){const s=I.safeParse(o);if(!s.success)throw new Error(`invalid response for slot "${t.id}": ${f(s.error)}`);const i=s.data,r=t.config;h(i.selectedOptionIds,t.id,"selectedOptionIds");for(const n of i.selectedOptionIds)if(!r.options.some(a=>a.id===n))throw new Error(`slot "${t.id}" selects unknown option id "${n}"`);if(i.freetext!==void 0&&r.allowFreetext!==!0)throw new Error(`slot "${t.id}" does not allow freetext`);if(r.mode==="single"&&i.selectedOptionIds.length>1)throw new Error(`slot "${t.id}" is single-select but received ${i.selectedOptionIds.length} option ids`);const d=r.allowFreetext===!0&&(i.freetext?.trim()??"")!=="";if(re(r)){if(r.mode==="single"&&i.selectedOptionIds.length!==1&&!d)throw new Error(`single-select slot "${t.id}" requires exactly one selection or nonempty allowed freetext`);if(r.mode==="multi"&&i.selectedOptionIds.length===0&&i.comments.length===0&&!d)throw new Error(`multi-select slot "${t.id}" requires a selection, comment, or nonempty allowed freetext`)}return C(t,i.comments),i}if(t.kind==="text"){const s=S.safeParse(o);if(!s.success)throw new Error(`invalid response for slot "${t.id}": ${f(s.error)}`);if(t.config.required===!0&&s.data.text.trim()==="")throw new Error(`slot "${t.id}" is required and was left empty`);return s.data}if(t.kind==="table"){const s=y.safeParse(o);if(!s.success)throw new Error(`invalid response for slot "${t.id}": ${f(s.error)}`);const i=s.data,r=t.config;h(i.selectedRowIds,t.id,"selectedRowIds"),h(i.selectedColumnIds,t.id,"selectedColumnIds");const d=new Set((r.rows??[]).map(a=>a.id)),n=new Set(r.columns.map(a=>a.id));for(const a of i.selectedRowIds)if(!d.has(a))throw new Error(`slot "${t.id}" selects unknown row id "${a}"`);for(const a of i.selectedColumnIds)if(!n.has(a))throw new Error(`slot "${t.id}" selects unknown column id "${a}"`);if(r.required===!0&&i.selectedRowIds.length===0&&i.selectedColumnIds.length===0)throw new Error(`slot "${t.id}" is required and nothing is selected`);if(r.rowSelect==="none"&&i.selectedRowIds.length>0||r.rowSelect==="single"&&i.selectedRowIds.length>1)throw new Error(`slot "${t.id}" response violates row select mode "${r.rowSelect}"`);if(r.columnSelect==="none"&&i.selectedColumnIds.length>0||r.columnSelect==="single"&&i.selectedColumnIds.length>1)throw new Error(`slot "${t.id}" response violates column select mode "${r.columnSelect}"`);return C(t,i.comments),i}if(t.kind==="cards"){const s=E.safeParse(o);if(!s.success)throw new Error(`invalid response for slot "${t.id}": ${f(s.error)}`);const i=s.data,r=t.config;h(i.selectedCardIds,t.id,"selectedCardIds");for(const d of i.selectedCardIds)if(!(r.cards??[]).some(n=>n.id===d))throw new Error(`slot "${t.id}" selects unknown card id "${d}"`);if(r.mode==="single"&&i.selectedCardIds.length>1)throw new Error(`slot "${t.id}" is single-select but received ${i.selectedCardIds.length} card ids`);if(r.required===!0&&i.selectedCardIds.length===0)throw new Error(`slot "${t.id}" is required and nothing is selected`);return i}throw new Error(`slot "${t.id}" kind "${t.kind}" does not accept a response`)}c(se,"parseResponse");function R(t,o,s){const i=w.safeParse(o);if(!i.success)throw new Error("page responses must be an object keyed by slot id");const r=new Map(t.slots.filter(g).map(n=>[n.id,n])),d={};for(const[n,a]of Object.entries(i.data)){const l=r.get(n);if(l===void 0)throw new Error(`response names unknown or non-response-bearing slot id "${n}"`);d[n]=se(l,a)}if(!s){for(const n of r.keys())if(!(n in d))throw new Error(`final page response is missing response-bearing slot id "${n}"`)}return d}c(R,"validateResponses");function ge(t,o){return R(t,o,!1)}c(ge,"validatePageResponses");function he(t,o){return R(t,o,!0)}c(he,"validatePartialPageResponses");export{oe as BUILTIN_PAGE_CONFIG_SCHEMAS,le as BUILTIN_PAGE_RESPONSE_SCHEMAS,O as PAGE_SLOT_ID_PATTERN,H as cardSchema,J as cardsConfigSchema,E as cardsResponseSchema,Z as cardsSchema,X as chartConfigSchema,V as chartDataRowsSchema,Q as chartSeriesSchema,x as commentSchema,ie as createPageManifestSchema,g as isResponseBearingSlot,f as issueText,N as optionSchema,T as optionsConfigSchema,re as optionsRequired,I as optionsResponseSchema,ue as pageAwaitsResponse,M as pageCommentAnchorSchema,ee as pageDeliverySchema,me as pageManifestSchema,pe as pageOverviewActions,B as tableCellSchema,L as tableColumnSchema,D as tableConfigSchema,y as tableResponseSchema,G as tableRowSchema,U as tableRowsSchema,F as textConfigSchema,S as textResponseSchema,fe as validateAuthoredPageManifest,j as validatePageManifest,ge as validatePageResponses,he as validatePartialPageResponses};

package/dist/core/human/page-synth.d.ts

@@ -0,0 +1,7 @@
+/** Build a complete TSX page from title, subtitle, and body for internal producers. */
+export declare function synthesizedPageDocument(title: string, subtitle: string, body: string, responseBearing: boolean): string;
+/** Materialize an internally generated document into a private temp dir; the caller removes it after submission. */
+export declare function writeSynthesizedPage(document: string): {
+    dir: string;
+    path: string;
+};