How an agent moves on the page, so that the people can follow it: it goes to where it works, presses, drags and lets go, and clicks, as a hand would. Only where it goes is sent, once for each gesture; each browser draws the way there on its own page, and the agent waits as long as that takes before its change lands.
A gesture's target is a place of a document, in the document's own terms
(%{"doc" => "notebook:7/body", "at" => at}: a caret, a node, a cell),
or an element of the app's page that it named (%{"anchor" => "edit"},
the element with data-issho-anchor="edit"). Components' tools move
their agents with it; an app's own tools too:
# An app's tool: the agent goes to the button, clicks it, then acts.
:ok = Issho.Motion.click(participant, %{"anchor" => "new-page"})
{:ok, page} = Pages.create(...)When it moves
An agent moves only for someone who can see it. Each browser of the room says what it shows (the page in the foreground, the documents of its components on the screen, whether its person wants motion): when no person of the room shows the target, or none wants motion, the agent is there at once. A browser that says nothing, or a person who follows the agent, counts as watching: the agent rather moves for no one than skips someone who looks.
Time
A gesture takes flight milliseconds to another document or element,
step within the same one (each browser fits its own way into it).
A tool call has a budget: its gestures together never take longer, the
later ones shorter, then at once.
config :issho, Issho.Motion,
travel: true, # false: agents are there at once, everywhere
flight: 450,
step: 300,
click: 150, # the moment on a click before what it does
budget: 3_000 # the most a tool call's gestures take, togetherA component may move its agents or not (Kotoba's, Masu's and Hakushi's
travel); this one setting turns motion off for all of them.
Summary
Types
A gesture: :move to go there, :press and :release around a :drag, :click, and :navigate (navigate/2).
Where a gesture goes: a place of a document, or an element of the page.
Functions
Goes to a target and clicks it: the people see it ring.
Selects as a drag does: pressed at from, let go at to (a range of
the same document), in two gestures.
Goes to a target. Options: :gesture (:move), :place (whether a
document's target is also the agent's place, its selection there:
true), :travel (a component's own setting: true), and :block, the
component's own keys of the target's document that change with the
gesture, in the same message (a canvas's cursor and selection, under
the document in blocks: Issho.Awareness). :aware is the same for
Issho's own top-level keys.
Goes to another page of the app, by its path ("/pages/2"): the people
who follow the agent go there too, their browsers as if they had
followed a link. It does not change the rooms the agent is in: to work
in the documents of that page, it joins its room. Only a path of the app
(starting with a single /) goes.
A moment on a target, before what the agent does there, so that the
people see what will change: taken only when someone sees it, within
the tool call's budget. Options: :travel.
Whether agents move at all (config :issho, Issho.Motion, travel: false turns it off).
Whether anyone of the room may see the agent go to a target, and wants to: a person whose browser shows it (its page in the foreground, and for a document's target, the document's component on the screen), whose browser says nothing of what it shows, or who follows the agent.
Runs a function with the time budget of a tool call: the gestures it
makes together never take longer. Issho.Tools runs each tool so.
Types
@type gesture() :: :move | :press | :drag | :release | :click | :navigate
A gesture: :move to go there, :press and :release around a :drag, :click, and :navigate (navigate/2).
Where a gesture goes: a place of a document, or an element of the page.
Functions
@spec click(GenServer.server(), target(), keyword()) :: :ok | {:error, term()}
Goes to a target and clicks it: the people see it ring.
@spec drag(GenServer.server(), target(), target(), keyword()) :: :ok | {:error, term()}
Selects as a drag does: pressed at from, let go at to (a range of
the same document), in two gestures.
@spec go(GenServer.server(), target(), keyword()) :: :ok | {:error, term()}
Goes to a target. Options: :gesture (:move), :place (whether a
document's target is also the agent's place, its selection there:
true), :travel (a component's own setting: true), and :block, the
component's own keys of the target's document that change with the
gesture, in the same message (a canvas's cursor and selection, under
the document in blocks: Issho.Awareness). :aware is the same for
Issho's own top-level keys.
@spec pause(GenServer.server(), target(), non_neg_integer(), keyword()) :: :ok
A moment on a target, before what the agent does there, so that the
people see what will change: taken only when someone sees it, within
the tool call's budget. Options: :travel.
@spec travel?() :: boolean()
Whether agents move at all (config :issho, Issho.Motion, travel: false turns it off).
@spec watched?(GenServer.server(), target()) :: boolean()
Whether anyone of the room may see the agent go to a target, and wants to: a person whose browser shows it (its page in the foreground, and for a document's target, the document's component on the screen), whose browser says nothing of what it shows, or who follows the agent.
@spec within(non_neg_integer() | nil, (-> result)) :: result when result: term()
Runs a function with the time budget of a tool call: the gestures it
makes together never take longer. Issho.Tools runs each tool so.