@pinecall/dot 0.11.23 → 0.11.25

package/README.md

@@ -1,7 +1,8 @@
 # @pinecall/dot
 
-> **An experiment.** The dot and its tutor are an add-on of Pinecall, not part of its core: their
-> API may change in any release.
+> **Experimental.** The dot and its tutor are an add-on of Pinecall, not part of its core, and they
+> are still being found: any of their API, attributes and messages may change or go in any release, a
+> patch one included. These pages are their only documentation, and they describe what is true today.
 
 The talking dot. A small face, a dot with eyes and a mouth, speaks with your agent's voice, moving
 its mouth with the sound frame by frame. As a tutor it becomes one more person on the page, with a
@@ -11,6 +12,9 @@ about, and the agent's prompt reads the page as it is now.
 It stands on [`@pinecall/room`](../room/README.md), which joins the call. The pinecall widget
 draws it with `<pinecall-widget look="dot">`, and with `look="dot" tutor` the tutor too.
 
+**To build a tutor, start with [Write a tutor agent](docs/write-a-tutor.md)**, step by step, and
+[Macros](docs/macros.md), the format of a guided walk. This page is the reference.
+
 | import | where it runs | what it gives you |
 |---|---|---|
 | `@pinecall/dot` | the page | `face()`, `tutor()`, and `Page`, the page as the agent reads it |
@@ -37,19 +41,16 @@ talkButton.onclick = () => {
 // pip.close() takes it off the page.
 ```
 
-The face fills its element with one SVG: 64 px is a launcher, 240 px a hero. Two faces on one page
-are fine.
+The face fills its element with one SVG: 64 px is a launcher, 240 px a hero. Two faces on one page are fine.
 
 **Its shape and colour.** `face(host, call, { shape, color })`: `shape` is `circle` (the default),
-`squircle` or `blob`, and `color` any CSS colour (else the page's `--pc-face`). `reshape(shape)`
-changes it later, the body easing from one into the other. The body moves whole with the mood, its
-outline never bent: it bobs and leans in while it listens, more slowly while it thinks, and squashes
-with the voice while it speaks; still under `prefers-reduced-motion`. Nothing is drawn outside the
-body, no halo and no shadow, so it sits on any background. `tutor()` takes the same `shape` and `color`, which
-tints its pointer too.
+`squircle` or `blob`, and `color` any CSS colour (else the page's `--pc-face`). `reshape(shape)` changes it
+later, the body easing from one into the other. The body moves whole with the mood, its outline never bent: it
+bobs and leans in while it listens, more slowly while it thinks, and squashes with the voice while it speaks;
+still under `prefers-reduced-motion`. Nothing is drawn outside the body, no halo and no shadow, so it sits on
+any background. `tutor()` takes the same `shape` and `color`, which tints its pointer too.
 
-**How the mouth is read.** Everything happens in the browser, from the element the agent's voice
-plays in (`state.voice`):
+**How the mouth is read.** Everything happens in the browser, from the element the agent's voice plays in (`state.voice`):
 
 | step | what |
 |---|---|
@@ -90,33 +91,35 @@ pip = tutor(call, { label: "Talk to Pip", onClick: () => { pip.wake(); void call
 for the other), 58 px across (`--pc-dot-size`) and 14 px from the edges; touring, a pointer in its colour with the face beside the tip and what it says
 beside the face. It moves the way a hand moves a mouse:
 
-- **It aims at an element the way a person does.** It lands on the middle of the element's first
-  words, not of its box, and flies there on a minimum-jerk path with a slight arc, timed by the
-  distance.
+- **It aims at an element the way a person does.** It lands on the middle of the element's first words, not
+  of its box, and flies there on a minimum-jerk path with a slight arc, timed by the distance. Its words stay
+  on the screen on the way: out of its corner, the face and the bubble take the side that fits until the destination's side does.
 - **The pointer looks like the one the element asks for**: a hand on a link, an I-beam in a field.
 - **Hover looks real.** Every `:hover` rule of the site's own style sheets is mirrored onto
-  `[data-pc-hover]`, set on the element under the tip and its ancestors, and `pointerenter` and
-  `mouseenter` are sent for the site's code. A style sheet from another origin cannot be read and
-  keeps no hover.
-- **It scrolls the page eased**, until the element sits a little above the middle of the screen.
-- **A highlight dims the rest of the page** and follows the element as the page scrolls. "Here" is a
-  ring at the tip.
-
-**It never clicks, sends a form or opens another page for the visitor.** It shows where, and they do
-it. A form's fields it fills with what the visitor told it, typed letter by letter with the `input`
-and `change` events the site's code listens for, a list by the option that says it; the visitor
-presses its button. It never touches a password, a card number, a file or a hidden field.
+`[data-pc-hover]`, set on the element under the tip and its ancestors, and `pointerenter` and `mouseenter` are
+sent for the site's code. A style sheet from another origin cannot be read and keeps no hover.
+- **It scrolls the page eased**, until the element sits a little above the middle of the screen, below the
+  site's header (a fixed or sticky bar along the top, or the page's `scroll-padding-top`). A box that scrolls
+  inside the page is scrolled too, its own `scroll-padding-top` kept clear; anything not shown whole where
+  the visitor can see it is scrolled to before the pointer lands on it.
+- **A highlight dims the rest of the page** and follows the element as the page scrolls. "Here" rings the tip.
+
+**It never sends a form or opens another page for the visitor.** It shows where, and they do it. A
+form's fields it fills with what the visitor told it, typed letter by letter with the `input` and
+`change` events the site's code listens for, a list by the option that says it; the visitor presses
+its button. It never touches a password, a card number, a file or a hidden field. The one button it
+presses is one a walk the site wrote names (`press`): outside any form, or in a search form
+(`<search>`, `role="search"`); never a link, never a form that books, buys or signs up.
 
 **The conversation in writing, and the call's buttons.** The agent's words show beside the face,
-lit as its voice says them; the visitor's, what the agent heard, show in the corner as they speak
-and for `linger` ms after (2600 by default), one side at a time. `captions` chooses whose may show:
-`both` (default), `agent`, `caller` or `none`. During a call two buttons sit beside the corner:
-**CC**, which turns the words on and off for this visitor: off until they turn them on (kept in
-their browser's `localStorage`, and absent with `captions: "none"`), and **✕**, which hangs up (`call.leave()`). While a walk plays,
-CC sits there with **■**, which stops it. The buttons slide into the face's corner while it tours, and
-aside as it comes home. No words show while a
-window of code or a card is open: they would cover it. `words: { hangUp, captions, stop }` names them for a
-screen reader.
+lit as its voice says them; the visitor's, what the agent heard, show in the corner as they speak and for
+`linger` ms after (2600 by default), one side at a time. `captions` chooses whose may show: `both` (default),
+`agent`, `caller` or `none`. During a call two buttons sit beside the corner: **CC**, which turns the words on
+and off for this visitor: off until they turn them on (kept in their browser's `localStorage`, and absent with
+`captions: "none"`), and **✕**, which hangs up (`call.leave()`). While a walk plays, CC sits there with **■**,
+which stops it. The buttons slide into the face's corner while it tours, and aside as it comes home. No words
+show while a window of code or a card is open: they would cover it. `words: { hangUp, captions, stop }` names
+them for a screen reader.
 
 `take(data)` returns `true` for a message that was the tutor's (a cursor move, a macro step) and
 `false` for anything else, which stays the page's to draw.
@@ -141,16 +144,15 @@ screen reader.
   - region "Book your first visit" [ref=e18] (below)
 ```
 
-- **What is on the screen is there in full. A section out of view is one line**, its name and
-  `above` or `below`.
-- **Words in a box that is only layout are a line of text**, as a price in a `<div>`, as Playwright
-  says them.
+- **What is on the screen is there in full. A section out of view is one line**, its name and `above` or `below`.
+- **Words in a box that is only layout are a line of text**, as a price in a `<div>`, as Playwright says them.
+- **A name is the element's words with a space between its parts**, as a person reads them across:
+  `link "L la-espiga not held right now"`, never the parts run together.
 - **A ref is stable for the page's life**, and still names its element after a scroll took it off
   the screen.
 - **A field is its label and what it holds now**: `[value="Jordan Lee"]` or `[empty]`, a list's
-  choice and its `(options …)`, `[checked]` or `[unchecked]`, so the agent sees what the visitor
-  typed. Passwords, card numbers, and anything under `[data-pinecall-skip]` or `aria-hidden` are
-  left out.
+choice and its `(options …)`, `[checked]` or `[unchecked]`, so the agent sees what the visitor typed. Passwords,
+card numbers, and anything under `[data-pinecall-skip]` or `aria-hidden` are left out.
 - **What the site wrote for the agent to say is marked `[has a line]`** ([below](#lines-on-the-page)).
 
 The tutor sends it as `page.seen` when the call goes live, when a scroll stops, on a resize, when
@@ -183,9 +185,8 @@ A class that extends `Tutor` gets these:
   model calls them, while the words that name them play, and the model answers one only when it made
   it without a word; `runMacro` too, which starts on its own first words and ends on its own last ones.
 - **A move onto a thing waits for the page to say it ended** (`point`, `highlight`, `scrollTo`, three
-  seconds at most), and its result is that thing as the visitor now sees it, fenced as data: a
-  section that was one line below the fold comes back in full, its prices with it, for the model to
-  talk about.
+seconds at most), and its result is that thing as the visitor now sees it, fenced as data: a section that was
+one line below the fold comes back in full, its prices with it, for the model to talk about.
 - **`fill(field, text)` writes what the visitor said into a field**, after the agent asked for it,
   one field at a time; its result is the field as it now shows, and a field the page refused (a
   password, a list with no such option) is a tool error naming why. It never sends the form.
@@ -229,6 +230,10 @@ sentence the agent says as written, and each beat is a move run as its word is s
   never says.
 - **A model names a walk the way it heard it**: `runMacro("site tour")` runs `tour`, and an agent with one
   walk runs it whatever it is called (`walkNamed`).
+- **A macro can be a function** ([docs/macros.md](docs/macros.md#a-macro-as-a-function)): `params` it is
+  called with fill the `{slots}` of its sentences, and steps that act fill a field, press a search, wait
+  for its answer and read the table it drew (`{hit.Time}`). In a call the model passes the params; typed
+  to the dot, they are picked out of what the visitor wrote. A sentence with slots is recorded live.
 
 How a macro runs. `runMacro("tour")` sends each step on `pinecall.ui`, then says it. The page binds
 the step to the reply that follows and counts its words as the voice says them, the same word
@@ -249,9 +254,9 @@ widget's `walks` attribute) puts a small button beside the resting face. A click
 round it, four at a time (a small ⌄ under them shows the next ones), each a pill with its title and length; a pick plays it: the voice, the mouth moving with
 it, the words lit as said, each beat on its word, a ring round the face for how far it is. While it
 plays, the corner holds captions, pause and stop; a click on the face stops it too. No microphone is
-asked for. A section can offer its own walk: with `data-pinecall-walk="<macro>"` on it, as the page is
-scrolled to it that walk's pill shows alone beside the face for a few seconds, then goes; not during
-a call or a walk. The site can also draw its own button, `hidden`, and mark it
+asked for. A section can name its walk: with `data-pinecall-walk="<macro>"` on it, the menu, when it
+opens, marks the walk of the section the visitor is on (the one across the screen's middle) and opens on
+the page it stands on. The site can also draw its own button, `hidden`, and mark it
 `data-pinecall-play="<macro>"`: the tutor shows it while that walk can play, and a click plays it. A call opened afterwards tells the agent which walk
 was played and how far (`page.walked`), so it goes on from there rather than give it again.
 `onWalk` hears each start and end, for the page's own analytics.
@@ -281,26 +286,104 @@ chose. The card holds the last tool that finished with a view, until it is repla
 visitor's way to say something, never a way round the agent: nothing on it books or sends for them.
 With the widget, set `widget.views = { … }` on the element. Colours: `--pc-card` and `--pc-card-ink`.
 
+### Typing to the dot: one thing done, never a conversation
+
+`tutor(call, { ask })` puts a field in the walks' menu ("Ask me to show you…"). `ask(request)` is the
+site's door, on its own server. What the visitor types goes there with the page's path, its named
+things by ref and the walks of the page (`{ decide }`); the answer is one thing to do, and the dot does
+it with no call: it plays a walk, called with the params picked out of what was typed, or lights and
+points at a thing with its name beside the face. A question a person answers, or something not on the
+page, is never answered in the dot's words: the field says so, with a button that hands it to
+`onTalk(message)` (the site starts a call with it written in). The same door picks the row of a table a
+walk read (`{ row }`) and records a walk's sentence once its slots are filled (`{ say }`).
+
+```ts
+// the page
+tutor(call, { ask: (request) => fetch("/api/ask", { method: "POST", body: JSON.stringify(request) }).then((r) => r.json()) });
+
+// the site's server
+import { answer } from "@pinecall/dot/server";
+const answered = await answer(body, {
+  key: process.env.OPENROUTER_API_KEY,
+  voicing: { key: process.env.PINECALL_KEY, agent: "pip" }, // records sentences with slots in the agent's voice
+});
+```
+
+`answer()` asks Jev, TypeSafe's System One model, through OpenRouter's Decisions API: one request, its
+questions answered at once (what they want, which walk, which thing of the page, each param of each walk),
+each a choice among the options given, with probabilities. A param in the visitor's words is one of the
+parts of what they typed (one to five words in a row): what fills a field is what they wrote, never a word
+of the model's. A sentence with slots is read from the walks the agent published, never from the page, and
+recorded once per set of values (a line of 80 characters each). Jev cannot write a sentence or name a thing
+not on the page, and under its threshold (0.5) decides nothing rather than guess. The page's words and what
+the visitor typed go to OpenRouter and TypeSafe: a site says so in its privacy policy.
+
+### A page read aloud
+
+`tutor(call, { ask, reading: "Leer el capítulo" })` puts a first pill in the walks' menu that reads the page
+aloud in the agent's voice, with no call: what the site marks `data-pinecall-read` (a `<main>`, a section), its
+headings, paragraphs, items and captions in the page's order, as written, the part read lit and pointed at and
+the rest dimmed; a long one is read a few sentences at a time. Every part is asked of the door as the tutor
+mounts, three at a time, so the reading starts with no wait. A button marked `data-pinecall-press` is an
+example: reached, the pointer presses it (its value said first: `data-pinecall-press="Lo corro."`), the reading
+waits for what it controls (`aria-controls`, its output) to answer and not be `aria-busy`, then says its
+`data-pinecall-then` pointing at the output and reads the output line by line with notes: `data-pinecall-notes`
+names a list whose items each find a line of it (`data-pinecall-find`, a text in any case or `/a regex/`) and
+say what it means; the line is lit and pointed at, the output marked `data-pinecall-reading` meanwhile so the
+site can widen a box that scrolls. A note whose line is not there is left out. A field marked
+`data-pinecall-type` is typed with its value, the page's own example (a chat's question), and the
+`data-pinecall-press` after it sends it, in any form; an element that is no field (an editor) marked so is told
+each letter by `pinecall-typing` events the site takes with `preventDefault()`. A frame of the site's own (a
+chat in an iframe) is read in its place. A send button marked `data-pinecall-goal` is a chat the dot talks to:
+it asks the door for its line (`{ next }`: Pinecall's caller, with `voicing.next`), opens the chat by focusing
+its field (its greeting waited on while busy), says each line as it types it, sends it, reads aloud what the
+agent said and the tools it used (turns marked `data-pinecall-said`; a tool's said by its `data-pinecall-say`)
+until it has what it came for, the chat ends (a turn marked `end`) or forty turns pass, and the page goes on.
+Such a button in no form is a spoken call: the dot presses it, hears the greeting (`data-pinecall-heard` on the
+output: the agent and its tools are heard, not read; only the end is said) and says its lines into the call,
+each told to the output by a `pinecall-saying` event with its recording; `tutor.stop()` ends a reading. A page whose top was scrolled away is read from the first part still in view. A button
+marked `data-pinecall-explain` with no notes has its output explained by the door (`{ explain }`, with
+`voicing.explain`), the notes read in the place of its `data-pinecall-then`. `data-pinecall-quiet` is not read.
+An element with `data-pinecall-say` is said as that line instead, nothing inside it read again. `tutor.read()`
+starts it from a button of the site's own; while it plays, the corner holds back, pause, next and stop.
+
+Each part is recorded by the site's door when the reading reaches it, the next asked for while one plays (`{
+read: { text } }`), and the gateway keeps it: a page read twice costs nothing the second time. A door lets its
+pages be read only when it says so (`answer(body, { voicing: { …, read: true } })`): a page may then have any
+text of 480 characters said in the agent's voice, so a site gives it to its own pages alone.
+
+```html
+<main data-pinecall-read>
+  <h2>Cómo leer esto</h2>
+  <p>Cada comando está en un bloque con ▶ Run.</p>
+  <div class="block" data-pinecall-quiet>
+    <pre>pinecall whoami</pre>
+    <button aria-label="Run pinecall whoami" aria-controls="out-1" data-pinecall-press="Lo corro." data-pinecall-notes="notes-1">▶ Run</button>
+    <output id="out-1"></output>
+    <ol id="notes-1" hidden data-pinecall-skip>
+      <li data-pinecall-find="org lesson">Ahí está tu org, lesson.</li>
+      <li data-pinecall-find="/person's key/">Y es una key de persona.</li>
+    </ol>
+  </div>
+</main>
+```
+
 ### Lines on the page
 
-A walk can also live in the site's own markup, beside what it is about, so the HTML and what is
-said never drift apart:
+A walk can also live in the site's own markup, beside what it is about:
 
 ```html
 <section id="pricing" data-pinecall-say="Pricing is simple: three plans, and most families pick Family Care." data-pinecall-do="highlight">
 <article data-pinecall-say="Family Care covers up to four people for thirty-nine dollars a month." data-pinecall-order="2">
 ```
 
-- **`data-pinecall-say` is said as written**, with the move `data-pinecall-do` names (`point`
-  unless `highlight` or `scroll_to`), in `data-pinecall-order` and then in the page's order.
-- **One at a time**: `explain(what)` says the line of a thing marked `[has a line]`, the pointer on
-  it, when the visitor asks what it is; and during a call a ▶ shows at the top right of a marked
-  element under the visitor's mouse, which says it at once (`page.explain`).
-- **All of them**: the walk `page`, listed with the agent's macros, says every line in order.
-- **Said once.** The agent says a line through `say()`, so it is the turn's answer, in the history:
-  the model is not asked to answer it again, and the tool's result tells it the line is said.
-
-Only the site's markup is read: a line under `[data-pinecall-skip]` or `aria-hidden` is not.
+- **`data-pinecall-say` is said as written**, with the move `data-pinecall-do` names (`point` unless
+  `highlight` or `scroll_to`), in `data-pinecall-order` and then in the page's order; a line under
+  `[data-pinecall-skip]` or `aria-hidden` is not read.
+- **One at a time, or all**: `explain(what)` says the line of a thing marked `[has a line]`, the pointer
+  on it; during a call a ▶ at the top right of a marked element under the mouse says it at once
+  (`page.explain`); the walk `page`, listed with the agent's macros, says every line in order.
+- **Said once.** The agent says a line through `say()`: it is the turn's answer, in the history, never asked again.
 
 ## What the page and the agent say to each other
 
@@ -312,6 +395,5 @@ Only the site's markup is read: a line under `[data-pinecall-skip]` or `aria-hid
 | agent → page | `pinecall.ui` `{ type: "macro.step", macro, step, say, beats }` |
 | agent → page | `pinecall.ui` `{ type: "look" }`: what the page shows now, answered with `page.seen` |
 
-**Anybody can send what a browser sends.** The agent reads the page as the visitor's own words, and
-a site that shows other people's words (reviews, comments) puts them under `data-pinecall-skip`
-when the agent should not read them.
+**Anybody can send what a browser sends.** The agent reads the page as the visitor's own words: a site
+that shows other people's words (reviews, comments) puts them under `data-pinecall-skip`.

package/dist/agent/index.d.ts

@@ -1,4 +1,5 @@
 /** @pinecall/dot/agent: the agent's side of the dot tutor, for a class written with @pinecall/agents. */
-export { Tutor, macros, walkNamed } from "./tutor.js";
-export type { Action, Beat, Macro, MacroStep } from "../wire/index.js";
+export { Tutor } from "./tutor.js";
+export { macros, walkNamed } from "./walks.js";
+export type { Act, ActStep, Action, Beat, Macro, MacroStep, Param } from "../wire/index.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/agent/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/agent/index.ts"],"names":[],"mappings":"AAAA,yGAAyG;AAEzG,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AACtD,YAAY,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/agent/index.ts"],"names":[],"mappings":"AAAA,yGAAyG;AAEzG,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAC/C,YAAY,EAAE,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/agent/index.js

@@ -1,3 +1,4 @@
 /** @pinecall/dot/agent: the agent's side of the dot tutor, for a class written with @pinecall/agents. */
-export { Tutor, macros, walkNamed } from "./tutor.js";
+export { Tutor } from "./tutor.js";
+export { macros, walkNamed } from "./walks.js";
 //# sourceMappingURL=index.js.map

package/dist/agent/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/agent/index.ts"],"names":[],"mappings":"AAAA,yGAAyG;AAEzG,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/agent/index.ts"],"names":[],"mappings":"AAAA,yGAAyG;AAEzG,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC"}

package/dist/agent/tutor.d.ts

@@ -1,13 +1,6 @@
 /** The agent's side of the dot tutor: the visitor's page in its prompt, the pointer's tools, and the macros it was given. */
 import { Agent, type Call, type Child, type EventDeclarations, type EventMeta, type Serve } from "@pinecall/agents";
 import { type Line, type Macro } from "../wire/index.js";
-/**
- * The walk a model means by `asked`: the one so named, else the one whose name it says among its words
- * ("site tour" for `tour`), else the only one there is. A model names a walk the way it heard it.
- */
-export declare function walkNamed(walks: Record<string, Macro>, asked: string): Macro | undefined;
-/** Each macro file, checked: `macros({ tour })` with `import tour from "./macros/tour.json" with { type: "json" }`. */
-export declare function macros(files: Record<string, unknown>): Record<string, Macro>;
 export declare class Tutor extends Agent {
     static events: EventDeclarations;
     /** The guided walks this agent can give, by name. */
@@ -22,6 +15,8 @@ export declare class Tutor extends Agent {
     lines: Line[];
     /** The walk the visitor played with no call before this one, and how far: `"tour", all 5 sentences`. */
     walked: string;
+    /** The path of the visitor's page, as the page last said it; none, every walk is for it. */
+    path: string;
     /**
      * Before any call: each macro recorded in the agent's voice and published as `walks`, for the
      * page to play with no call. A sentence recorded before costs nothing, so this runs as it is again.
@@ -50,8 +45,15 @@ export declare class Tutor extends Agent {
     here(): string;
     /** Take your pointer back to your corner, when you are done showing. */
     home(): string;
-    /** Give one of your walks, by its name: each sentence said as written, your pointer moving on its words. */
-    runMacro(name: string): Promise<string>;
+    /** The walks for the page the visitor is on: those that name it, and those that name none. */
+    private macrosHere;
+    /** Give one of your walks, by its name, with the params it takes: each sentence said as written, your pointer moving on its words. */
+    runMacro(name: string, params?: Record<string, string>): Promise<string>;
+    /**
+     * A walk's act on the page: a field filled, a button pressed, the page waited on. A table read ends the
+     * walk's own words: what it shows is handed to the model, to answer the visitor from.
+     */
+    private acted;
     /** The site's lines, one by one: the pointer onto each element, then its line said as written. */
     private walkThePage;
     /** The pointer onto a line's element, then the line said: the turn's answer, kept in the history. */
@@ -60,7 +62,7 @@ export declare class Tutor extends Agent {
     private shown;
     /** Move onto `what`, wait for the page to say the move ended, and say what the visitor sees there. */
     private show;
-    /** Send a move and wait for the page to say it ended, three seconds at most; a move never answered ends with nothing known. */
+    /** Send a move and wait for the page to say it ended, three seconds at most (`within`); a move never answered ends with nothing known. */
     private moved;
     private move;
 }

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

@@ -1 +1 @@
-{"version":3,"file":"tutor.d.ts","sourceRoot":"","sources":["../../src/agent/tutor.ts"],"names":[],"mappings":"AAAA,6HAA6H;AAgB7H,OAAO,EAAE,KAAK,EAAiC,KAAK,IAAI,EAAE,KAAK,KAAK,EAAE,KAAK,iBAAiB,EAAE,KAAK,SAAS,EAAE,KAAK,KAAK,EAAoB,MAAM,kBAAkB,CAAC;AAErK,OAAO,EAAmH,KAAK,IAAI,EAAE,KAAK,KAAK,EAAiC,MAAM,kBAAkB,CAAC;AAgDzM;;;GAGG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,EAAE,KAAK,EAAE,MAAM,GAAG,KAAK,GAAG,SAAS,CAKxF;AAcD,uHAAuH;AACvH,wBAAgB,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAE5E;AAED,qBAAa,KAAM,SAAQ,KAAK;IAC9B,OAAgB,MAAM,EAAE,iBAAiB,CAMvC;IAEF,qDAAqD;IACrD,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAM;IAE1C,uEAAuE;IACvE,IAAI,SAAM;IACV,0DAA0D;IAC1D,OAAO,SAAM;IACb,0CAA0C;IAC1C,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,4GAA4G;IAC5G,KAAK,EAAE,IAAI,EAAE,CAAM;IACnB,wGAAwG;IACxG,MAAM,SAAM;IAEZ;;;OAGG;IACH,OAAsB,OAAO,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,CAuBzD;IAED,qHAAqH;IAC5G,MAAM,CAAC,KAAK,EAAE,IAAI,GAAG,OAAO,CAGpC;IAEQ,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,KAAK,EAAE,SAAS,GAAG,OAAO,CAavF;IAED,+GAA+G;IACtG,MAAM,IAAI,KAAK,CAEvB;IAED,6EAA6E;IAC7E,MAAM,IAAI,MAAM,CAuBf;IAED,8FAA8F;IAC9F,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAEnC;IAED,2FAA2F;IAC3F,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAEvC;IAED,8BAA8B;IAC9B,WAAW,IAAI,MAAM,CAEpB;IAED,wEAAwE;IACxE,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAEtC;IAED,oIAAoI;IAC9H,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAO3C;IAED,kJAAkJ;IAC5I,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CASvD;IAED,6EAA6E;IAC7E,IAAI,IAAI,MAAM,CAEb;IAED,wEAAwE;IACxE,IAAI,IAAI,MAAM,CAEb;IAED,4GAA4G;IACtG,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAoB5C;IAED,kGAAkG;YACpF,WAAW;IAgBzB,qGAAqG;YACvF,OAAO;IAQrB,wGAAwG;IACxG,OAAO,CAAC,KAAK;IAYb,sGAAsG;YACxF,IAAI;IAUlB,+HAA+H;IAC/H,OAAO,CAAC,KAAK;IAkBb,OAAO,CAAC,IAAI;CAIb"}
+{"version":3,"file":"tutor.d.ts","sourceRoot":"","sources":["../../src/agent/tutor.ts"],"names":[],"mappings":"AAAA,6HAA6H;AAkB7H,OAAO,EAAE,KAAK,EAAiC,KAAK,IAAI,EAAE,KAAK,KAAK,EAAE,KAAK,iBAAiB,EAAE,KAAK,SAAS,EAAE,KAAK,KAAK,EAAoB,MAAM,kBAAkB,CAAC;AAErK,OAAO,EAA8J,KAAK,IAAI,EAAE,KAAK,KAAK,EAAe,MAAM,kBAAkB,CAAC;AAiDlO,qBAAa,KAAM,SAAQ,KAAK;IAC9B,OAAgB,MAAM,EAAE,iBAAiB,CAMvC;IAEF,qDAAqD;IACrD,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAM;IAE1C,uEAAuE;IACvE,IAAI,SAAM;IACV,0DAA0D;IAC1D,OAAO,SAAM;IACb,0CAA0C;IAC1C,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,4GAA4G;IAC5G,KAAK,EAAE,IAAI,EAAE,CAAM;IACnB,wGAAwG;IACxG,MAAM,SAAM;IACZ,4FAA4F;IAC5F,IAAI,SAAM;IAEV;;;OAGG;IACH,OAAsB,OAAO,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,CAEzD;IAED,qHAAqH;IAC5G,MAAM,CAAC,KAAK,EAAE,IAAI,GAAG,OAAO,CAGpC;IAEQ,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,KAAK,EAAE,SAAS,GAAG,OAAO,CAcvF;IAED,+GAA+G;IACtG,MAAM,IAAI,KAAK,CAEvB;IAED,6EAA6E;IAC7E,MAAM,IAAI,MAAM,CAsBf;IAED,8FAA8F;IAC9F,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAEnC;IAED,2FAA2F;IAC3F,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAEvC;IAED,8BAA8B;IAC9B,WAAW,IAAI,MAAM,CAEpB;IAED,wEAAwE;IACxE,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAEtC;IAED,oIAAoI;IAC9H,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAO3C;IAED,kJAAkJ;IAC5I,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CASvD;IAED,6EAA6E;IAC7E,IAAI,IAAI,MAAM,CAEb;IAED,wEAAwE;IACxE,IAAI,IAAI,MAAM,CAEb;IAED,8FAA8F;IAC9F,OAAO,CAAC,UAAU;IAKlB,sIAAsI;IAChI,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,CAmC7E;IAED;;;OAGG;YACW,KAAK;IAuBnB,kGAAkG;YACpF,WAAW;IAgBzB,qGAAqG;YACvF,OAAO;IAQrB,wGAAwG;IACxG,OAAO,CAAC,KAAK;IAYb,sGAAsG;YACxF,IAAI;IAUlB,0IAA0I;IAC1I,OAAO,CAAC,KAAK;IAkBb,OAAO,CAAC,IAAI;CAIb"}