@pinecall/dot 0.11.23 → 0.11.25

package/dist/server/questions.js

@@ -0,0 +1,136 @@
+/** What Jev is asked about what the visitor typed, and what its answers come to: the questions, the parts of the message a param is picked from, the decision. */
+//
+// Three questions on the same state, answered at once: what kind of thing they want (a walk, a thing
+// shown, a person's answer, nothing), which walk, which thing of the page. And one more for each param of
+// each walk: Jev cannot write, so a param in the visitor's words is a choice among the parts of what they
+// typed (`spans`), one to five words in a row, or none; a param of a list, a choice among its options.
+// So what fills a field is what the visitor wrote, never a word of the model's.
+import { namedIn } from "../wire/ask.js";
+import { valueOf } from "../wire/acts.js";
+export const MODEL = "~typesafe/jev-latest";
+export const THRESHOLD = 0.5;
+/** The most options a Choice takes. */
+export const MOST = 255;
+/** The most words a part of the message picked as a param holds. */
+const SPAN_WORDS = 5;
+/** The roles a visitor asks to be shown first, when a page has more things than a Choice takes. */
+const FIRST = ["region", "heading", "article", "group", "tab", "button", "link", "img", "form", "textbox", "combobox", "checkbox", "radio"];
+// A question is often a walk's to answer ("do you have a time on Thursday?" is a walk that searches the
+// times): what a walk does or finds wins over a person's words.
+const INTENTS = {
+    walk: "one of this page's walks does or finds what they ask, even asked as a question: a tour, a topic it covers, a search it runs, a form it fills",
+    show: "they want to see where one thing is on this page",
+    talk: "no walk of the page does it, and only a person can answer: advice on their own case, a problem, a complaint",
+    none: "it is not about this site, or nothing on this page answers it",
+};
+/** The things of the page the choice is among: every one with a name, the sections and headings first when there are too many. */
+export function thingsOf(page) {
+    const named = namedIn(page);
+    if (named.length <= MOST)
+        return named;
+    const rank = (role) => (FIRST.includes(role) ? FIRST.indexOf(role) : FIRST.length);
+    const kept = new Set([...named].sort((a, b) => rank(a.role) - rank(b.role)).slice(0, MOST));
+    return named.filter((thing) => kept.has(thing));
+}
+/**
+ * The parts of what the visitor typed a param can be: one to five words in a row, as written, without the
+ * commas and quotes around them. An email or a phone stays whole, being one word or two. The shorter first.
+ */
+export function spansOf(message) {
+    const words = [...message.matchAll(/\S+/g)].map((found) => ({ at: found.index, text: found[0] }));
+    const trimmed = (text) => text.replace(/^["'¿¡«“]+/, "").replace(/[,.;:!?"'»”]+$/, "");
+    const spans = [];
+    for (let size = 1; size <= SPAN_WORDS; size += 1) {
+        for (let from = 0; from + size <= words.length; from += 1) {
+            const first = words[from];
+            const last = words[from + size - 1];
+            if (first === undefined || last === undefined)
+                continue;
+            const span = trimmed(message.slice(first.at, last.at + last.text.length));
+            if (span !== "" && !spans.includes(span))
+                spans.push(span);
+        }
+    }
+    return spans.slice(0, MOST - 1);
+}
+/** The key a param's question is asked under: `param.<walk>.<name>`. */
+const keyOf = (walk, param) => `param.${walk}.${param}`;
+/** The request Jev is asked: the state, and the questions on it. */
+export function questionsOf(request, things, model = MODEL, spans = spansOf(request.message)) {
+    const walks = request.walks;
+    const intents = walks.length > 0 ? INTENTS : { show: INTENTS.show, talk: INTENTS.talk, none: INTENTS.none };
+    const state = [
+        `A visitor is on the page ${request.path} of a website and typed to its guide: "${request.message}"`,
+        "",
+        "The things on the page (role and name):",
+        ...things.map((thing) => `- ${thing.role} "${thing.name}"`),
+        ...(walks.length > 0 ? ["", "The page's guided walks:", ...walks.map((walk) => `- ${walk.title}${walk.when ? `: ${walk.when}` : ""}`)] : []),
+    ].join("\n");
+    const questions = {
+        intent: {
+            type: "choice",
+            instructions: walks.length > 0 ? "What does the visitor want the guide to do? Read the page's walks first: one that does or finds it is the answer." : "What does the visitor want the guide to do?",
+            criteria: intents,
+        },
+        target: {
+            type: "choice",
+            instructions: "Which one thing on the page is what they want to see, or best answers what they typed?",
+            criteria: Object.fromEntries(things.map((thing) => [thing.ref, `${thing.role} "${thing.name}"`])),
+        },
+    };
+    if (walks.length > 0) {
+        questions["walk"] = {
+            type: "choice",
+            instructions: "Which of the page's guided walks is about what they typed?",
+            criteria: Object.fromEntries(walks.map((walk) => [walk.name, `${walk.title}${walk.when ? `: ${walk.when}` : ""}`])),
+        };
+    }
+    for (const walk of walks) {
+        for (const [name, param] of Object.entries(walk.params ?? {})) {
+            const options = param.oneOf ?? Object.fromEntries(spans.map((span, at) => [`s${at}`, `"${span}"`]));
+            questions[keyOf(walk.name, name)] = {
+                type: "choice",
+                instructions: param.oneOf === undefined
+                    ? `If they want "${walk.title}": which part of what they typed is ${param.about}? "none" when they did not write it.`
+                    : `If they want "${walk.title}": which one is ${param.about}? "none" when they did not say.`,
+                criteria: { none: "they did not say", ...options },
+            };
+        }
+    }
+    return { model, state: [state], questions };
+}
+/**
+ * The one thing to do, from Jev's answers. To act (a walk or a thing shown) wins when the two together are
+ * more likely than not, and of the two the surer one; under `threshold` it does nothing rather than guess.
+ */
+export function decisionFrom(answers, threshold = THRESHOLD) {
+    const p = answers["intent"]?.probabilities ?? {};
+    const intent = answers["intent"]?.confidence ?? 0;
+    const walk = answers["walk"];
+    const target = answers["target"];
+    if ((p["walk"] ?? 0) + (p["show"] ?? 0) >= 0.5) {
+        const walking = (p["walk"] ?? 0) * (walk?.confidence ?? 0);
+        const showing = (p["show"] ?? 0) * (target?.confidence ?? 0);
+        if (walking >= showing && walk?.choice !== undefined && (walk.confidence ?? 0) >= threshold)
+            return { do: "walk", walk: walk.choice, confidence: walk.confidence ?? 0 };
+        if (target?.choice !== undefined && (target.confidence ?? 0) >= threshold)
+            return { do: "show", target: target.choice, confidence: target.confidence ?? 0 };
+        return { do: "none", confidence: intent };
+    }
+    return (p["talk"] ?? 0) >= (p["none"] ?? 0) ? { do: "talk", confidence: intent } : { do: "none", confidence: intent };
+}
+/** The params of the walk decided, each one Jev was sure of: the part of the message, or the option. */
+export function paramsFrom(answers, walk, spans, threshold = THRESHOLD) {
+    const values = {};
+    for (const [name, param] of Object.entries(walk.params ?? {})) {
+        const answer = answers[keyOf(walk.name, name)];
+        const choice = answer?.choice;
+        if (choice === undefined || choice === "none" || (answer?.confidence ?? 0) < threshold)
+            continue;
+        const value = param.oneOf === undefined ? spans[Number(choice.slice(1))] : choice in param.oneOf ? choice : undefined;
+        if (value !== undefined)
+            values[name] = valueOf(value);
+    }
+    return values;
+}
+//# sourceMappingURL=questions.js.map

package/dist/server/questions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"questions.js","sourceRoot":"","sources":["../../src/server/questions.ts"],"names":[],"mappings":"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"}

package/dist/server/saying.d.ts

@@ -0,0 +1,31 @@
+/** A sentence of a walk recorded when it is reached, once its slots are filled: the agent's voice, in real time, on the site's server. */
+import { type ExplainRequest, type NextLine, type NextRequest, type Note, type SaidAnswer, type SayRequest } from "../wire/ask.js";
+/** The agent whose voice records it, and the key the site's server holds for it. */
+export interface Voicing {
+    key: string;
+    agent: string;
+    /** Default `https://cloud.pinecall.io`. */
+    gateway?: string | undefined;
+    /** Which world the agent's walks and voice are read in: `sandbox` while it is held there. Default production. */
+    env?: "sandbox" | "production" | undefined;
+    /**
+     * Whether a page may have its own text read aloud (`{ read }`, a page read with `reading`): any text of 480
+     * characters said in the agent's voice. For a site whose door answers its own pages alone. Default no.
+     */
+    read?: boolean | undefined;
+    /** Whether a page may have an output explained by the agent's model (`{ explain }`): a model asked per output. Default no. */
+    explain?: boolean | undefined;
+    /** Whether a page may have the dot talk to a chat for a goal (`{ next }`): Pinecall's caller asked per turn. Default no. */
+    next?: boolean | undefined;
+}
+/** Record a walk's sentence with its slots filled, in the agent's voice. Throws when the sentence is not the walk's or a slot is empty. */
+export declare function recordSay(request: SayRequest, voicing: Voicing, ask?: typeof fetch): Promise<SaidAnswer>;
+/** A text of the page itself recorded in the agent's voice: a part of a page read aloud. Throws unless the voicing lets a page read. */
+export declare function recordRead(text: string, voicing: Voicing, ask?: typeof fetch): Promise<SaidAnswer>;
+/** An output explained by the agent's model, through the gateway: notes, each on one line of it. Throws unless the voicing lets a page explain. */
+export declare function explainOutput(request: ExplainRequest, voicing: Voicing, ask?: typeof fetch): Promise<{
+    notes: Note[];
+}>;
+/** The dot's next line on a chat it talks to for a goal: Pinecall's caller, through the gateway, playing it. Throws unless the voicing lets a page talk. */
+export declare function nextLine(request: NextRequest, voicing: Voicing, ask?: typeof fetch): Promise<NextLine>;
+//# sourceMappingURL=saying.d.ts.map

package/dist/server/saying.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"saying.d.ts","sourceRoot":"","sources":["../../src/server/saying.ts"],"names":[],"mappings":"AAAA,0IAA0I;AAS1I,OAAO,EAA+B,KAAK,cAAc,EAAE,KAAK,QAAQ,EAAE,KAAK,WAAW,EAAE,KAAK,IAAI,EAAE,KAAK,UAAU,EAAE,KAAK,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAGhK,oFAAoF;AACpF,MAAM,WAAW,OAAO;IACtB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,2CAA2C;IAC3C,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,iHAAiH;IACjH,GAAG,CAAC,EAAE,SAAS,GAAG,YAAY,GAAG,SAAS,CAAC;IAC3C;;;OAGG;IACH,IAAI,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC3B,8HAA8H;IAC9H,OAAO,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC9B,4HAA4H;IAC5H,IAAI,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CAC5B;AAuCD,2IAA2I;AAC3I,wBAAsB,SAAS,CAAC,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG,GAAE,OAAO,KAAa,GAAG,OAAO,CAAC,UAAU,CAAC,CAUrH;AAED,wIAAwI;AACxI,wBAAsB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG,GAAE,OAAO,KAAa,GAAG,OAAO,CAAC,UAAU,CAAC,CAK/G;AAED,mJAAmJ;AACnJ,wBAAsB,aAAa,CAAC,OAAO,EAAE,cAAc,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG,GAAE,OAAO,KAAa,GAAG,OAAO,CAAC;IAAE,KAAK,EAAE,IAAI,EAAE,CAAA;CAAE,CAAC,CAWpI;AAED,4JAA4J;AAC5J,wBAAsB,QAAQ,CAAC,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG,GAAE,OAAO,KAAa,GAAG,OAAO,CAAC,QAAQ,CAAC,CAmBnH"}

package/dist/server/saying.js

@@ -0,0 +1,124 @@
+/** A sentence of a walk recorded when it is reached, once its slots are filled: the agent's voice, in real time, on the site's server. */
+//
+// A walk's sentence with `{slots}` cannot be recorded before the visitor says what fills them. The page
+// asks for it by the walk, the step and the values; the sentence itself is read from the walks the agent
+// published, never from the page, so a page asks the voice for the site's own sentences and nothing else:
+// what a visitor brings is the values, one line of 80 characters each. The gateway records each text once
+// and keeps it, so the same sentence with the same values costs nothing the second time.
+import { filled, slotsOf, valueOf } from "../wire/acts.js";
+import { MOST_HEARD, nextOf, notesOf } from "../wire/ask.js";
+import { walksDocument, walksOf } from "../wire/index.js";
+/** The most turns of its own a talk takes: the gateway's own ceiling on a caller's. */
+const MOST_TURNS = 40;
+const STYLE = "a person writing in a chat{language}: short turns, one or two lines, no narration";
+/** The longest output a page may have explained. */
+const LONGEST_EXPLAINED = 8000;
+/** The longest text a page may have read in one request. */
+const LONGEST_READ = 480;
+const GATEWAY = "https://cloud.pinecall.io";
+/** How long the walks a page reads are kept, in ms: as long as the gateway lets a page keep them. */
+const KEPT_MS = 60_000;
+const kept = new Map();
+async function walksAt(url, ask) {
+    const hit = kept.get(url);
+    if (hit !== undefined && Date.now() - hit.at < KEPT_MS)
+        return hit.walks;
+    const answer = await ask(url);
+    const walks = answer.ok ? walksOf(await answer.json()) : [];
+    kept.set(url, { at: Date.now(), walks });
+    return walks;
+}
+/** The live step a request names, in the walks published for its page or, failing them, the home's. */
+async function stepOf(request, voicing, ask) {
+    const base = `${(voicing.gateway ?? GATEWAY).replace(/\/+$/, "")}/v1/agents/${encodeURIComponent(voicing.agent)}/public/`;
+    const query = voicing.env === "sandbox" ? "?env=sandbox" : "";
+    for (const document of new Set([walksDocument(request.path), "walks"])) {
+        const walk = (await walksAt(`${base}${document}${query}`, ask)).find((one) => one.name === request.walk);
+        const step = walk?.steps[request.step];
+        if (step !== undefined && "live" in step)
+            return step;
+        if (walk !== undefined)
+            break;
+    }
+    throw new Error(`the walk ${request.walk} has no sentence to record at step ${request.step}`);
+}
+/** Record a walk's sentence with its slots filled, in the agent's voice. Throws when the sentence is not the walk's or a slot is empty. */
+export async function recordSay(request, voicing, ask = fetch) {
+    const step = await stepOf(request, voicing, ask);
+    const values = {};
+    for (const slot of slotsOf(step.say)) {
+        const value = request.values[slot];
+        if (typeof value === "string")
+            values[slot] = valueOf(value);
+    }
+    const text = filled(step.say, values);
+    if (text === null)
+        throw new Error(`the walk ${request.walk}'s step ${request.step} needs ${slotsOf(step.say).join(", ")}`);
+    return recorded(text, voicing, ask);
+}
+/** A text of the page itself recorded in the agent's voice: a part of a page read aloud. Throws unless the voicing lets a page read. */
+export async function recordRead(text, voicing, ask = fetch) {
+    if (voicing.read !== true)
+        throw new Error("this door reads no page aloud: give its voicing read: true");
+    const line = text.replace(/\s+/g, " ").trim();
+    if (line === "" || line.length > LONGEST_READ)
+        throw new Error(`a text read is 1 to ${LONGEST_READ} characters`);
+    return recorded(line, voicing, ask);
+}
+/** An output explained by the agent's model, through the gateway: notes, each on one line of it. Throws unless the voicing lets a page explain. */
+export async function explainOutput(request, voicing, ask = fetch) {
+    if (voicing.explain !== true)
+        throw new Error("this door explains no output: give its voicing explain: true");
+    const output = request.output.trim();
+    if (output === "" || output.length > LONGEST_EXPLAINED)
+        throw new Error(`an output explained is 1 to ${LONGEST_EXPLAINED} characters`);
+    const answer = await ask(`${(voicing.gateway ?? GATEWAY).replace(/\/+$/, "")}/v1/agents/${encodeURIComponent(voicing.agent)}/explain`, {
+        method: "POST",
+        headers: { authorization: `Bearer ${voicing.key}`, "content-type": "application/json", ...(voicing.env === undefined ? {} : { "pinecall-env": voicing.env }) },
+        body: JSON.stringify({ output, ...(request.command === undefined ? {} : { command: request.command.slice(0, 300) }), ...(request.language === undefined ? {} : { language: request.language }) }),
+    });
+    if (!answer.ok)
+        throw new Error(`the gateway explained nothing: ${answer.status}`);
+    return { notes: notesOf(await answer.json()) };
+}
+/** The dot's next line on a chat it talks to for a goal: Pinecall's caller, through the gateway, playing it. Throws unless the voicing lets a page talk. */
+export async function nextLine(request, voicing, ask = fetch) {
+    if (voicing.next !== true)
+        throw new Error("this door talks to no chat: give its voicing next: true");
+    const goal = request.goal.trim();
+    if (goal === "" || goal.length > 4000)
+        throw new Error("a goal talked for is 1 to 4000 characters");
+    const heard = request.heard.slice(-MOST_HEARD).map((turn) => ({ who: turn.who === "agent" ? "agent" : "caller", said: turn.said.slice(0, 4000) }));
+    const mine = heard.filter((turn) => turn.who === "caller").length;
+    const answer = await ask(`${(voicing.gateway ?? GATEWAY).replace(/\/+$/, "")}/v1/evals/caller`, {
+        method: "POST",
+        headers: { authorization: `Bearer ${voicing.key}`, "content-type": "application/json", ...(voicing.env === undefined ? {} : { "pinecall-env": voicing.env }) },
+        body: JSON.stringify({
+            persona: { goal, style: STYLE.replace("{language}", request.language === undefined ? "" : `, in the language "${request.language}"`) },
+            heard,
+            turns_left: Math.max(1, MOST_TURNS - mine),
+        }),
+    });
+    if (!answer.ok)
+        throw new Error(`the gateway said nothing: ${answer.status}`);
+    const line = nextOf(await answer.json());
+    if (line === null)
+        throw new Error("the gateway gave no line");
+    return line;
+}
+/** One text recorded by the gateway in the agent's voice, kept: the same text again costs nothing. */
+async function recorded(text, voicing, ask) {
+    const answer = await ask(`${(voicing.gateway ?? GATEWAY).replace(/\/+$/, "")}/v1/agents/${encodeURIComponent(voicing.agent)}/lines`, {
+        method: "POST",
+        headers: { authorization: `Bearer ${voicing.key}`, "content-type": "application/json", ...(voicing.env === undefined ? {} : { "pinecall-env": voicing.env }) },
+        body: JSON.stringify({ texts: [text] }),
+    });
+    if (!answer.ok)
+        throw new Error(`the gateway recorded nothing: ${answer.status}`);
+    const body = (await answer.json());
+    const line = body.lines?.[0];
+    if (line === undefined)
+        throw new Error("the gateway recorded nothing");
+    return { say: text, audio: line.url, durationMs: line.duration_ms, words: line.words.map((word) => ({ text: word.text, startMs: word.start_ms, endMs: word.end_ms })) };
+}
+//# sourceMappingURL=saying.js.map

package/dist/server/saying.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"saying.js","sourceRoot":"","sources":["../../src/server/saying.ts"],"names":[],"mappings":"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"}

package/dist/tutor/acting.d.ts

@@ -0,0 +1,42 @@
+/** What a walk's acts do on the page with no call: a field filled, a button pressed, the page waited on, a table read; and a sentence with slots recorded. */
+import type { Page } from "../page/page.js";
+import { type DoorRequest, type ExplainRequest, type NextLine, type NextRequest, type Note } from "../wire/ask.js";
+import { type ActStep, type RecordedStep, type RecordedWalk, type Values } from "../wire/index.js";
+export interface ActingOptions {
+    document: Document;
+    page: Page;
+    /** Run `work` after the moves already queued. */
+    queued: <T>(work: () => Promise<T>) => Promise<T>;
+    /** The pointer onto an element; called inside the queue. */
+    point: (element: Element) => Promise<void>;
+    /** The ring at the pointer's tip. */
+    ring: () => void;
+    /** The visitor's words typed into a field, the pointer on it; called inside the queue. Paced to `ms` when given. Why it could not, or null. */
+    type: (element: Element, text: string, ms?: number) => Promise<string | null>;
+    /** The site's door; none, a sentence with slots is left out and the first row read. */
+    door?: ((request: DoorRequest) => Promise<unknown>) | undefined;
+}
+/** How long a wait waits when its step does not say, in ms. */
+export declare const WAIT_MS = 8000;
+export declare class Acting {
+    #private;
+    constructor(options: ActingOptions);
+    /** One act of a walk, after the moves queued before it: the values a read adds. */
+    act(step: ActStep, values: Values, message: string): Promise<Values>;
+    /** Press a button, the pointer on it first and a ring as it presses; the page is watched from now. Why it could not, or null. `forms`, a page read aloud's example, pressed in any form. */
+    press(element: Element, forms?: boolean): Promise<string | null>;
+    /** Words typed into a field, the pointer on it: a page read aloud's example. Why it could not, or null. */
+    type(element: Element, text: string, ms?: number): Promise<string | null>;
+    /** Wait for `target` to change, settle and not be busy, `ms` at most: true when it did. */
+    wait(target: () => Element | null, ms: number): Promise<boolean>;
+    /** A sentence with slots, recorded now by the site's door; null when it cannot be. */
+    voice(path: string, walk: RecordedWalk, at: number, values: Values): Promise<RecordedStep | null>;
+    /** An output explained by the site's door, the agent's model: its notes; none when the door gives none. */
+    explain(request: ExplainRequest): Promise<Note[]>;
+    /** The dot's next line on a chat it talks to for a goal, by the site's door; null when it gives none. */
+    next(request: NextRequest): Promise<NextLine | null>;
+    /** A text of the page, recorded now by the site's door in the agent's voice; null when it cannot be. */
+    read(text: string): Promise<RecordedStep | null>;
+    close(): void;
+}
+//# sourceMappingURL=acting.d.ts.map

package/dist/tutor/acting.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"acting.d.ts","sourceRoot":"","sources":["../../src/tutor/acting.ts"],"names":[],"mappings":"AAAA,8JAA8J;AAS9J,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAC;AAI5C,OAAO,EAAkC,KAAK,WAAW,EAAE,KAAK,cAAc,EAAE,KAAK,QAAQ,EAAE,KAAK,WAAW,EAAE,KAAK,IAAI,EAAE,MAAM,gBAAgB,CAAC;AACnJ,OAAO,EAA4B,KAAK,OAAO,EAAiB,KAAK,YAAY,EAAE,KAAK,YAAY,EAAgB,KAAK,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAE1J,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,QAAQ,CAAC;IACnB,IAAI,EAAE,IAAI,CAAC;IACX,iDAAiD;IACjD,MAAM,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;IAClD,4DAA4D;IAC5D,KAAK,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3C,qCAAqC;IACrC,IAAI,EAAE,MAAM,IAAI,CAAC;IACjB,+IAA+I;IAC/I,IAAI,EAAE,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC9E,uFAAuF;IACvF,IAAI,CAAC,EAAE,CAAC,CAAC,OAAO,EAAE,WAAW,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC;CACjE;AAED,+DAA+D;AAC/D,eAAO,MAAM,OAAO,OAAO,CAAC;AAO5B,qBAAa,MAAM;;IAMjB,YAAY,OAAO,EAAE,aAAa,EAEjC;IAED,mFAAmF;IACnF,GAAG,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAmBnE;IAED,4LAA4L;IACtL,KAAK,CAAC,OAAO,EAAE,OAAO,EAAE,KAAK,UAAQ,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAKnE;IAED,2GAA2G;IAC3G,IAAI,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAExE;IAED,2FAA2F;IAC3F,IAAI,CAAC,MAAM,EAAE,MAAM,OAAO,GAAG,IAAI,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAkB/D;IAED,sFAAsF;IAChF,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,YAAY,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CAUtG;IAED,2GAA2G;IACrG,OAAO,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC,CAItD;IAED,yGAAyG;IACnG,IAAI,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CAIzD;IAED,wGAAwG;IAClG,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CAKrD;IAED,KAAK,IAAI,IAAI,CAEZ;CAoDF"}

package/dist/tutor/acting.js

@@ -0,0 +1,180 @@
+/** What a walk's acts do on the page with no call: a field filled, a button pressed, the page waited on, a table read; and a sentence with slots recorded. */
+//
+// Each act runs after the pointer's moves queued before it, as a person does one thing after another.
+// A press is watched: a wait after it ends when the thing it waits on has changed and then stayed still a
+// moment, and says it is not busy (`aria-busy`): a search answered and drawn. Or at its time. A read takes the rows of a table as a person reads them, by
+// its header's words, and the row that best answers what the visitor typed, which the site's door picks;
+// with nothing typed, or no answer, the first. A sentence with slots is recorded by the site's door when
+// it is reached: the door reads the sentence from the agent's walks, and the page sends only the values.
+import { nameOf } from "../page/roles.js";
+import { framesIn, isElement } from "../pointer/frames.js";
+import { press } from "../pointer/pressing.js";
+import { nextOf, notesOf, rowOf, saidOf } from "../wire/ask.js";
+import { filled, slotsOf, valueOf } from "../wire/index.js";
+/** How long a wait waits when its step does not say, in ms. */
+export const WAIT_MS = 8000;
+/** How long the page must stay still after it changed for a wait to end, in ms. */
+const QUIET_MS = 300;
+const LOOK_MS = 100;
+/** The most changes kept between a press and its wait. */
+const KEPT = 500;
+export class Acting {
+    #options;
+    #observer = null;
+    /** What changed since the press, and when. */
+    #changes = [];
+    constructor(options) {
+        this.#options = options;
+    }
+    /** One act of a walk, after the moves queued before it: the values a read adds. */
+    act(step, values, message) {
+        return this.#options.queued(async () => {
+            if ("fill" in step) {
+                const text = filled(step.with, values);
+                const field = this.#named(step.fill, ["textbox", "combobox"]);
+                if (text !== null && field !== null)
+                    await this.#options.type(field, text);
+                return {};
+            }
+            if ("press" in step) {
+                const button = this.#named(step.press, ["button"]);
+                if (button !== null)
+                    await this.press(button);
+                return {};
+            }
+            if ("wait" in step) {
+                await this.wait(() => this.#named(step.wait), step.ms ?? WAIT_MS);
+                return {};
+            }
+            return this.#read(step, message);
+        });
+    }
+    /** Press a button, the pointer on it first and a ring as it presses; the page is watched from now. Why it could not, or null. `forms`, a page read aloud's example, pressed in any form. */
+    async press(element, forms = false) {
+        await this.#options.point(element);
+        this.#options.ring();
+        this.#watch();
+        return press(element, forms);
+    }
+    /** Words typed into a field, the pointer on it: a page read aloud's example. Why it could not, or null. */
+    type(element, text, ms) {
+        return this.#options.type(element, text, ms);
+    }
+    /** Wait for `target` to change, settle and not be busy, `ms` at most: true when it did. */
+    wait(target, ms) {
+        const started = performance.now();
+        // A wait with no press before it watches from now.
+        if (this.#observer === null)
+            this.#watch();
+        const waited = new Promise((done) => {
+            const look = () => {
+                const now = performance.now();
+                const element = target();
+                const changed = element === null ? [] : this.#changes.filter((change) => element.contains(change.node));
+                const last = changed.at(-1)?.at ?? 0;
+                const busy = element?.closest("[aria-busy=true]") != null || element?.querySelector("[aria-busy=true]") != null;
+                if (changed.length > 0 && now - last >= QUIET_MS && !busy)
+                    return done(true);
+                if (now - started >= ms)
+                    return done(false);
+                setTimeout(look, LOOK_MS);
+            };
+            look();
+        });
+        return waited.finally(() => this.#stop());
+    }
+    /** A sentence with slots, recorded now by the site's door; null when it cannot be. */
+    async voice(path, walk, at, values) {
+        const step = walk.steps[at];
+        const door = this.#options.door;
+        if (door === undefined || step === undefined || !("live" in step))
+            return null;
+        const live = step;
+        const asked = Object.fromEntries(slotsOf(live.say).flatMap((slot) => (values[slot] === undefined ? [] : [[slot, values[slot]]])));
+        const said = saidOf(await door({ say: { path, walk: walk.name, step: at, values: asked } }).catch(() => null));
+        if (said === null)
+            return null;
+        const { live: _live, ...shown } = live;
+        return { ...shown, say: said.say, audio: said.audio, durationMs: said.durationMs, words: said.words };
+    }
+    /** An output explained by the site's door, the agent's model: its notes; none when the door gives none. */
+    async explain(request) {
+        const door = this.#options.door;
+        if (door === undefined)
+            return [];
+        return notesOf(await door({ explain: request }).catch(() => null));
+    }
+    /** The dot's next line on a chat it talks to for a goal, by the site's door; null when it gives none. */
+    async next(request) {
+        const door = this.#options.door;
+        if (door === undefined)
+            return null;
+        return nextOf(await door({ next: request }).catch(() => null));
+    }
+    /** A text of the page, recorded now by the site's door in the agent's voice; null when it cannot be. */
+    async read(text) {
+        const door = this.#options.door;
+        if (door === undefined)
+            return null;
+        const said = saidOf(await door({ read: { text } }).catch(() => null));
+        return said === null ? null : { say: said.say, audio: said.audio, durationMs: said.durationMs, words: said.words, beats: [] };
+    }
+    close() {
+        this.#stop();
+    }
+    /** The first thing of one of `roles` the page names so, on the screen or not. */
+    #named(name, roles) {
+        const ref = this.#options.page.named(name, roles);
+        return ref === null ? null : this.#options.page.element(ref);
+    }
+    /** The table the step names, its rows by their header's words, and one row's cells as the step's values. */
+    async #read(step, message) {
+        const named = this.#named(step.read);
+        const table = named === null ? null : named.matches("table") ? named : named.querySelector("table");
+        if (table === null)
+            return {};
+        const all = [...table.querySelectorAll("tr")];
+        const headers = [...(all.find((row) => row.querySelector("td") === null)?.children ?? [])].map((cell) => valueOf(cell.textContent ?? ""));
+        const rows = all.filter((row) => row.querySelector("td") !== null);
+        if (rows.length === 0)
+            return {};
+        const names = rows.map((row) => nameOf(row, "row"));
+        let at = 0;
+        if (step.row === "best" && message !== "" && this.#options.door !== undefined) {
+            at = rowOf(await this.#options.door({ row: { message, rows: names } }).catch(() => null)) ?? 0;
+        }
+        const row = rows[at] ?? rows[0];
+        if (row === undefined)
+            return {};
+        const values = { [step.as]: names[at] ?? "" };
+        [...row.children].forEach((cell, column) => {
+            const header = headers[column];
+            if (header !== undefined && header !== "")
+                values[`${step.as}.${header}`] = valueOf(cell.textContent ?? "");
+        });
+        return values;
+    }
+    /** Count what changes on the page from now, the tutor's own layer left out. */
+    #watch() {
+        this.#changes = [];
+        if (this.#observer !== null)
+            return;
+        const ours = (node) => (isElement(node) ? node : node.parentElement)?.closest("[data-pinecall-skip]") != null;
+        this.#observer = new MutationObserver((records) => {
+            const at = performance.now();
+            for (const record of records)
+                if (!ours(record.target))
+                    this.#changes.push({ node: record.target, at });
+            this.#changes.splice(0, Math.max(0, this.#changes.length - KEPT));
+        });
+        // The page, and the pages of the site's own frames in it: a chat in a frame answers there.
+        for (const page of [this.#options.document, ...framesIn(this.#options.document)]) {
+            this.#observer.observe(page.body, { subtree: true, childList: true, characterData: true, attributes: true });
+        }
+    }
+    #stop() {
+        this.#observer?.disconnect();
+        this.#observer = null;
+    }
+}
+//# sourceMappingURL=acting.js.map

package/dist/tutor/acting.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"acting.js","sourceRoot":"","sources":["../../src/tutor/acting.ts"],"names":[],"mappings":"AAAA,8JAA8J;AAC9J,EAAE;AACF,sGAAsG;AACtG,0GAA0G;AAC1G,0JAA0J;AAC1J,yGAAyG;AACzG,yGAAyG;AACzG,yGAAyG;AAGzG,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAC1C,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,EAAE,KAAK,EAAE,MAAM,wBAAwB,CAAC;AAC/C,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAqF,MAAM,gBAAgB,CAAC;AACnJ,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAgG,MAAM,kBAAkB,CAAC;AAiB1J,+DAA+D;AAC/D,MAAM,CAAC,MAAM,OAAO,GAAG,IAAI,CAAC;AAC5B,mFAAmF;AACnF,MAAM,QAAQ,GAAG,GAAG,CAAC;AACrB,MAAM,OAAO,GAAG,GAAG,CAAC;AACpB,0DAA0D;AAC1D,MAAM,IAAI,GAAG,GAAG,CAAC;AAEjB,MAAM,OAAO,MAAM;IACR,QAAQ,CAAgB;IACjC,SAAS,GAA4B,IAAI,CAAC;IAC1C,8CAA8C;IAC9C,QAAQ,GAAiC,EAAE,CAAC;IAE5C,YAAY,OAAsB;QAChC,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC;IAC1B,CAAC;IAED,mFAAmF;IACnF,GAAG,CAAC,IAAa,EAAE,MAAc,EAAE,OAAe;QAChD,OAAO,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,KAAK,IAAI,EAAE;YACrC,IAAI,MAAM,IAAI,IAAI,EAAE,CAAC;gBACnB,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;gBACvC,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,SAAS,EAAE,UAAU,CAAC,CAAC,CAAC;gBAC9D,IAAI,IAAI,KAAK,IAAI,IAAI,KAAK,KAAK,IAAI;oBAAE,MAAM,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;gBAC3E,OAAO,EAAE,CAAC;YACZ,CAAC;YACD,IAAI,OAAO,IAAI,IAAI,EAAE,CAAC;gBACpB,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,QAAQ,CAAC,CAAC,CAAC;gBACnD,IAAI,MAAM,KAAK,IAAI;oBAAE,MAAM,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;gBAC9C,OAAO,EAAE,CAAC;YACZ,CAAC;YACD,IAAI,MAAM,IAAI,IAAI,EAAE,CAAC;gBACnB,MAAM,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC,EAAE,IAAI,OAAO,CAAC,CAAC;gBAClE,OAAO,EAAE,CAAC;YACZ,CAAC;YACD,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;QACnC,CAAC,CAAC,CAAC;IACL,CAAC;IAED,4LAA4L;IAC5L,KAAK,CAAC,KAAK,CAAC,OAAgB,EAAE,KAAK,GAAG,KAAK;QACzC,MAAM,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QACnC,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC;QACrB,IAAI,CAAC,MAAM,EAAE,CAAC;QACd,OAAO,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;IAC/B,CAAC;IAED,2GAA2G;IAC3G,IAAI,CAAC,OAAgB,EAAE,IAAY,EAAE,EAAW;QAC9C,OAAO,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC;IAC/C,CAAC;IAED,2FAA2F;IAC3F,IAAI,CAAC,MAA4B,EAAE,EAAU;QAC3C,MAAM,OAAO,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC;QAClC,mDAAmD;QACnD,IAAI,IAAI,CAAC,SAAS,KAAK,IAAI;YAAE,IAAI,CAAC,MAAM,EAAE,CAAC;QAC3C,MAAM,MAAM,GAAG,IAAI,OAAO,CAAU,CAAC,IAAI,EAAE,EAAE;YAC3C,MAAM,IAAI,GAAG,GAAS,EAAE;gBACtB,MAAM,GAAG,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC;gBAC9B,MAAM,OAAO,GAAG,MAAM,EAAE,CAAC;gBACzB,MAAM,OAAO,GAAG,OAAO,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC;gBACxG,MAAM,IAAI,GAAG,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC;gBACrC,MAAM,IAAI,GAAG,OAAO,EAAE,OAAO,CAAC,kBAAkB,CAAC,IAAI,IAAI,IAAI,OAAO,EAAE,aAAa,CAAC,kBAAkB,CAAC,IAAI,IAAI,CAAC;gBAChH,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,IAAI,GAAG,GAAG,IAAI,IAAI,QAAQ,IAAI,CAAC,IAAI;oBAAE,OAAO,IAAI,CAAC,IAAI,CAAC,CAAC;gBAC7E,IAAI,GAAG,GAAG,OAAO,IAAI,EAAE;oBAAE,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC;gBAC5C,UAAU,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;YAC5B,CAAC,CAAC;YACF,IAAI,EAAE,CAAC;QACT,CAAC,CAAC,CAAC;QACH,OAAO,MAAM,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC;IAC5C,CAAC;IAED,sFAAsF;IACtF,KAAK,CAAC,KAAK,CAAC,IAAY,EAAE,IAAkB,EAAE,EAAU,EAAE,MAAc;QACtE,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QAC5B,MAAM,IAAI,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC;QAChC,IAAI,IAAI,KAAK,SAAS,IAAI,IAAI,KAAK,SAAS,IAAI,CAAC,CAAC,MAAM,IAAI,IAAI,CAAC;YAAE,OAAO,IAAI,CAAC;QAC/E,MAAM,IAAI,GAAa,IAAI,CAAC;QAC5B,MAAM,KAAK,GAAG,MAAM,CAAC,WAAW,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAClI,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,IAAI,CAAC,EAAE,GAAG,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC;QAC/G,IAAI,IAAI,KAAK,IAAI;YAAE,OAAO,IAAI,CAAC;QAC/B,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,KAAK,EAAE,GAAG,IAAI,CAAC;QACvC,OAAO,EAAE,GAAG,KAAK,EAAE,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,UAAU,EAAE,IAAI,CAAC,UAAU,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC;IACxG,CAAC;IAED,2GAA2G;IAC3G,KAAK,CAAC,OAAO,CAAC,OAAuB;QACnC,MAAM,IAAI,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC;QAChC,IAAI,IAAI,KAAK,SAAS;YAAE,OAAO,EAAE,CAAC;QAClC,OAAO,OAAO,CAAC,MAAM,IAAI,CAAC,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC;IACrE,CAAC;IAED,yGAAyG;IACzG,KAAK,CAAC,IAAI,CAAC,OAAoB;QAC7B,MAAM,IAAI,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC;QAChC,IAAI,IAAI,KAAK,SAAS;YAAE,OAAO,IAAI,CAAC;QACpC,OAAO,MAAM,CAAC,MAAM,IAAI,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC;IACjE,CAAC;IAED,wGAAwG;IACxG,KAAK,CAAC,IAAI,CAAC,IAAY;QACrB,MAAM,IAAI,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC;QAChC,IAAI,IAAI,KAAK,SAAS;YAAE,OAAO,IAAI,CAAC;QACpC,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,IAAI,CAAC,EAAE,IAAI,EAAE,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC;QACtE,OAAO,IAAI,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,UAAU,EAAE,IAAI,CAAC,UAAU,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC;IAChI,CAAC;IAED,KAAK;QACH,IAAI,CAAC,KAAK,EAAE,CAAC;IACf,CAAC;IAED,iFAAiF;IACjF,MAAM,CAAC,IAAY,EAAE,KAAyB;QAC5C,MAAM,GAAG,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;QAClD,OAAO,GAAG,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IAC/D,CAAC;IAED,4GAA4G;IAC5G,KAAK,CAAC,KAAK,CAAC,IAAa,EAAE,OAAe;QACxC,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACrC,MAAM,KAAK,GAAG,KAAK,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC;QACpG,IAAI,KAAK,KAAK,IAAI;YAAE,OAAO,EAAE,CAAC;QAC9B,MAAM,GAAG,GAAG,CAAC,GAAG,KAAK,CAAC,gBAAgB,CAAC,IAAI,CAAC,CAAC,CAAC;QAC9C,MAAM,OAAO,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,aAAa,CAAC,IAAI,CAAC,KAAK,IAAI,CAAC,EAAE,QAAQ,IAAI,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,WAAW,IAAI,EAAE,CAAC,CAAC,CAAC;QAC1I,MAAM,IAAI,GAAG,GAAG,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,aAAa,CAAC,IAAI,CAAC,KAAK,IAAI,CAAC,CAAC;QACnE,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,EAAE,CAAC;QACjC,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC,CAAC;QACpD,IAAI,EAAE,GAAG,CAAC,CAAC;QACX,IAAI,IAAI,CAAC,GAAG,KAAK,MAAM,IAAI,OAAO,KAAK,EAAE,IAAI,IAAI,CAAC,QAAQ,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;YAC9E,EAAE,GAAG,KAAK,CAAC,MAAM,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC;QACjG,CAAC;QACD,MAAM,GAAG,GAAG,IAAI,CAAC,EAAE,CAAC,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC;QAChC,IAAI,GAAG,KAAK,SAAS;YAAE,OAAO,EAAE,CAAC;QACjC,MAAM,MAAM,GAAW,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC;QACtD,CAAC,GAAG,GAAG,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE;YACzC,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;YAC/B,IAAI,MAAM,KAAK,SAAS,IAAI,MAAM,KAAK,EAAE;gBAAE,MAAM,CAAC,GAAG,IAAI,CAAC,EAAE,IAAI,MAAM,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,WAAW,IAAI,EAAE,CAAC,CAAC;QAC9G,CAAC,CAAC,CAAC;QACH,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,+EAA+E;IAC/E,MAAM;QACJ,IAAI,CAAC,QAAQ,GAAG,EAAE,CAAC;QACnB,IAAI,IAAI,CAAC,SAAS,KAAK,IAAI;YAAE,OAAO;QACpC,MAAM,IAAI,GAAG,CAAC,IAAU,EAAW,EAAE,CAAC,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,EAAE,OAAO,CAAC,sBAAsB,CAAC,IAAI,IAAI,CAAC;QAC7H,IAAI,CAAC,SAAS,GAAG,IAAI,gBAAgB,CAAC,CAAC,OAAO,EAAE,EAAE;YAChD,MAAM,EAAE,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC;YAC7B,KAAK,MAAM,MAAM,IAAI,OAAO;gBAAE,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC;oBAAE,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,EAAE,EAAE,CAAC,CAAC;YACxG,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,QAAQ,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC,CAAC;QACpE,CAAC,CAAC,CAAC;QACH,2FAA2F;QAC3F,KAAK,MAAM,IAAI,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,QAAQ,EAAE,GAAG,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,EAAE,CAAC;YACjF,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC,CAAC;QAC/G,CAAC;IACH,CAAC;IAED,KAAK;QACH,IAAI,CAAC,SAAS,EAAE,UAAU,EAAE,CAAC;QAC7B,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC;IACxB,CAAC;CACF"}

package/dist/tutor/aloud.d.ts

@@ -0,0 +1,50 @@
+/** One reading under way: each part recorded as it is reached, the examples pressed, typed and talked to, the outputs explained; and what a reading takes from the tutor. */
+import { type ExplainRequest, type NextLine, type NextRequest, type Note } from "../wire/ask.js";
+import type { RecordedStep } from "../wire/index.js";
+import type { Acting } from "./acting.js";
+import { type Reading } from "./reading.js";
+/** What reading a page takes from the tutor. */
+export interface ReadingOptions {
+    /** A text recorded in the agent's voice, by the site's door; null when it was not. */
+    record: (text: string) => Promise<RecordedStep | null>;
+    /** The part being read lit and pointed at, the rest dimmed; null puts the light out. */
+    light: (element: Element | null) => void;
+    /** An example pressed, and what it controls waited on until it answered. */
+    press: (element: Element) => Promise<void>;
+    /** The page's own example typed into a field, the pointer on it; paced to `ms`, the recording said meanwhile. */
+    type?: ((element: Element, text: string, ms?: number) => Promise<void>) | undefined;
+    /** An output explained by the site's door: notes on its lines; none when the door gives none. */
+    explain?: ((request: ExplainRequest) => Promise<Note[]>) | undefined;
+    /** The dot's next line on a chat it talks to for a goal, by the site's door; null when it gives none. */
+    next?: ((request: NextRequest) => Promise<NextLine | null>) | undefined;
+    /** A chat talked to opened before its first line: its field focused, and its output waited on while it says it is busy (a greeting coming). */
+    open?: ((field: Element, output: Element) => Promise<void>) | undefined;
+    /** A spoken call's output waited on while it says it is busy: the agent answering what the dot said into it. */
+    settle?: ((output: Element) => Promise<void>) | undefined;
+}
+/** One reading under way: each part recorded when it is reached, the next one asked for while one plays. */
+export declare class ReadAloud {
+    #private;
+    readonly reading: Reading;
+    constructor(reading: Reading, options: ReadingOptions);
+    /** The `at`th step recorded, and the next sentence asked for, so it is there when this one ends; a note whose line is not in the output, none. */
+    voice(at: number): Promise<RecordedStep | null>;
+    /** The `at`th step, an example: typed into a field; a turn of a talk; or pressed, waited on, and its output explained by the door when the page notes nothing on it. */
+    act(at: number): Promise<void>;
+    /** The `at`th step starts: its part lit and pointed at, an output's line by its note; -1, the reading is over. */
+    shows(at: number): void;
+}
+/** How long a part that could not be recorded waits before it is asked again, each time, in ms: a door that just came up (a machine booting) answers within these. */
+export declare const RECORD_AGAIN_MS: number[];
+/**
+ * What a reading takes, from the tutor's acts and moves: each part recorded by the site's door, the part read
+ * lit and pointed at (`light`), and an example pressed, then what it controls (its output) waited on until it
+ * answered and is not busy.
+ */
+export declare function readingWith(title: string, acting: Acting, moves: {
+    light: (element: Element | null) => void;
+    queued: <T>(work: () => Promise<T>) => Promise<T>;
+}): {
+    title: string;
+} & ReadingOptions;
+//# sourceMappingURL=aloud.d.ts.map