effect-browser 0.2.0-beta.8 → 0.3.0-beta.5

package/src/Moment.ts

@@ -0,0 +1,479 @@
+/**
+ * What a page showed, and what changed on it, over a window of time.
+ *
+ * A page's timeline has three tracks on its browser's host clock: its events, what visibly changed
+ * on it (`Change`), and its screencast frames. A `Window` holds the three from `since` to `until`,
+ * and says why a part it could not read is missing rather than fail. `Page.window` takes one, which
+ * can end in the past, at a frame a delayed consumer airs late, so that a line written now tells
+ * what its viewers will see. Its `account` says what was so at its end: how long the page had been
+ * still, which of its changes were still under way, and which had settled.
+ *
+ * A `Moment` is a window that ends at a picture of the page now: `capture` takes the picture, then
+ * the window up to it, and on request the page's outline. `toPrompt` turns a moment into one user
+ * message for any `effect/ai` call: a structured answer from `LanguageModel.generateObject`, a
+ * caption from `generateText`, or one turn of a `Chat` that follows moment after moment. It leads
+ * with what changed, news and what settled before what was still changing, as its account tells
+ * them apart, and names an action as what a change followed; as a step where changes followed it
+ * but none names it, or where its effect is drawn rather than written, as on a canvas, which only
+ * the screenshots show; and claims nothing of what changed where the record did not see, or of a
+ * part it could not read, which it names with why.
+ *
+ * Frames come from a running screencast, as far back as the browser's `frameHistory` keeps them.
+ * A moment's picture is the newest frame if it was painted after the page's latest input and at
+ * most 250 ms ago, else a new screenshot timed by its capture.
+ *
+ * @since 0.3.0
+ */
+import { Duration, Effect, Option, Result, Schema } from "effect";
+import { Prompt } from "effect/ai";
+
+import { BrowserError, InvalidRequest } from "./BrowserError.ts";
+import { type Action, BrowserEvent } from "./BrowserEvent.ts";
+import { type Change, Changes } from "./Change.ts";
+import { Frame } from "./Frame.ts";
+import { undispatched } from "./internal/page/context.ts";
+import { describe, named, quoted, where } from "./internal/timeline/words.ts";
+import type * as Page from "./Page.ts";
+import { Snapshot, type SnapshotOptions } from "./Snapshot.ts";
+
+/** A page's events, changes and frames over one window of its browser's host clock. */
+export class Window extends Schema.Class<Window>("effect-browser/Window")({
+  page: Schema.String,
+  /** Where the window starts, in host monotonic milliseconds on the owning browser’s clock. */
+  since: Schema.Finite,
+  /** Where it ends, never after it was taken. */
+  until: Schema.Finite,
+  /** The page's events after `since`, up to `until`, oldest first, without the input presentation track. */
+  events: Schema.Array(BrowserEvent),
+  /**
+   * What visibly changed after `since`, up to `until`; absent where `missing` says why. A page's
+   * first window starts its record, so the record sees none of it.
+   */
+  changes: Schema.optional(Changes),
+  /** Screencast frames painted from `since` to `until`, oldest first, as far back as kept. */
+  frames: Schema.Array(Frame),
+  /**
+   * Why each part that could not be read is missing: the read of its changes, by whatever
+   * operation failed there, or a moment's picture (`frame`) or outline (`snapshot`).
+   */
+  missing: Schema.Array(BrowserError),
+}) {}
+
+/**
+ * A window that ends at a picture of the page, its last frame, unless `missing` says why it has
+ * none. Its frames are a few, spread over the window, so that it still begins where it starts.
+ */
+export class Moment extends Window.extend<Moment>("effect-browser/Moment")({
+  /** The page's outline at the end of the window, when the capture asked for it. */
+  snapshot: Schema.optional(Snapshot),
+}) {}
+
+export interface CaptureOptions {
+  /**
+   * Where the window starts, as for `Page.window`: a previous window or moment, so that consecutive
+   * ones neither repeat nor miss an event or a change, or a `Duration` back from the picture.
+   * Defaults to 5 seconds.
+   */
+  readonly since?: Page.WindowOptions["since"] | undefined;
+  /** Frames to keep, at least 1, spread over the window and ending with the picture. Defaults to 2. */
+  readonly frames?: number | undefined;
+  /**
+   * Whether to take the page's outline at the end, or its options; `true` means 4,000 characters.
+   * Defaults to `false`: the frames and the timeline carry most moments, while an outline costs a
+   * round trip to the page and can double a moment's tokens.
+   */
+  readonly snapshot?: SnapshotOptions | boolean | undefined;
+  /** Show what fields hold in the moment's changes; a secret field still reads `••••`. */
+  readonly unmask?: boolean | undefined;
+}
+
+/** Pick `count` frames spread evenly over `frames`, always including the last. */
+const spread = (frames: ReadonlyArray<Frame>, count: number): ReadonlyArray<Frame> => {
+  if (frames.length <= count) return frames;
+  if (count <= 1) return frames.slice(-1);
+  const step = (frames.length - 1) / (count - 1);
+
+  return Array.from({ length: count }, (_, index) => frames[Math.round(index * step)]).filter(
+    (frame): frame is Frame => frame !== undefined,
+  );
+};
+
+export const capture = Effect.fn("Moment.capture")(function* (
+  page: Page.Page,
+  options: CaptureOptions = {},
+) {
+  const count = options.frames ?? 2;
+
+  if (!Number.isSafeInteger(count) || count < 1)
+    return yield* undispatched(
+      "moment",
+      new InvalidRequest({ detail: "frames must be a positive safe integer" }),
+    );
+  const outline = options.snapshot ?? false;
+
+  // The picture comes first, at no call with a running screencast, and the window ends at its
+  // paint, so its changes hold nothing it does not show; without one, the window ends now. The
+  // outline is taken alongside. What cannot be read is missing from the moment, not its end.
+  const { pictured, outlined } = yield* Effect.all(
+    {
+      pictured: Effect.result(page.frame({ after: "input" })).pipe(
+        Effect.flatMap((picture) =>
+          Effect.map(
+            page.window({
+              since: options.since ?? Duration.seconds(5),
+              until: Result.getOrUndefined(picture),
+              unmask: options.unmask,
+            }),
+            (window) => ({ window, picture }),
+          ),
+        ),
+      ),
+      outlined: Effect.result(
+        outline === false
+          ? Effect.void
+          : page.snapshot({ maxChars: 4000, ...(outline === true ? {} : outline) }),
+      ),
+    },
+    { concurrency: 2 },
+  );
+
+  const { window, picture } = pictured;
+  const shown = Result.getOrUndefined(picture);
+
+  return new Moment({
+    ...window,
+    frames: spread(
+      shown === undefined
+        ? window.frames
+        : [...window.frames.filter((frame) => frame !== shown), shown],
+      count,
+    ),
+    snapshot: Result.getOrUndefined(outlined) ?? undefined,
+    missing: [
+      ...window.missing,
+      ...Option.toArray(Result.getFailure(picture)),
+      ...Option.toArray(Result.getFailure(outlined)),
+    ],
+  });
+});
+
+/** A window's record of changes, if it saw any of the window: a page's first has none. */
+const recordOf = ({ changes }: Window) =>
+  changes !== undefined && changes.from < changes.until ? changes : undefined;
+
+/** What a window says of its page at its end: what was still in flux, and what had settled. */
+export interface Account {
+  /**
+   * How long, in milliseconds, the page had been still at the end: since the last change in view
+   * its record shows, or the last paint its screencast frames show, or else since the window, or
+   * its record, began. Undefined where neither could tell, with no record of the window and no
+   * painted frame: a screenshot shows the page, not when it last changed. Frames show paint only
+   * while a capture runs, and the record does not see a canvas, so a canvas that keeps drawing
+   * with no capture running reads as still.
+   */
+  readonly stillFor: number | undefined;
+  /**
+   * The changes still under way at the end: what kept changing, more than once in the window or
+   * already before it, and changed again within twice its own pace before the end.
+   */
+  readonly changing: ReadonlyArray<Change>;
+  /** Every other change, which shows what it settled at. */
+  readonly settled: ReadonlyArray<Change>;
+}
+
+/** Whether a change was still under way at `until`, by its own pace. */
+const underWay = (change: Change, until: number) => {
+  const pace =
+    change.count > 1
+      ? (change.at - change.startedAt) / (change.count - 1)
+      : change.earlier === undefined
+        ? undefined
+        : change.startedAt - change.earlier;
+
+  return pace !== undefined && until - change.at < 2 * pace;
+};
+
+/**
+ * An account of the window's page at its end: how long it had been still, and which of its
+ * changes were still under way and which had settled. A window whose record saw none of it has
+ * neither.
+ */
+export const account = (window: Window): Account => {
+  const record = recordOf(window);
+  const changes = record?.changes ?? [];
+
+  const stirred = [
+    ...changes.flatMap((change) => (change.kind === "title" ? [] : [change.at])),
+    ...window.frames.flatMap((frame) =>
+      frame.timing._tag === "BrowserPaint" ? [frame.hostTime] : [],
+    ),
+  ];
+
+  return {
+    stillFor:
+      record === undefined && stirred.length === 0
+        ? undefined
+        : window.until - Math.max(window.since, record?.from ?? window.since, ...stirred),
+    changing: changes.filter((change) => underWay(change, window.until)),
+    settled: changes.filter((change) => !underWay(change, window.until)),
+  };
+};
+
+const seconds = (moment: Moment, at: number) => `${((at - moment.until) / 1000).toFixed(1)}s`;
+
+const pointOf = (x: number | undefined, y: number | undefined) =>
+  x === undefined || y === undefined ? undefined : `(${Math.round(x)}, ${Math.round(y)})`;
+
+/**
+ * What an action acted on. Without a subject the action failed before finding it, and a ref it was
+ * given is left out: refs are reused, so the page's outline may give it to something else by now.
+ */
+const acted = (event: Action): string => {
+  const point = pointOf(event.x, event.y);
+
+  if (event.subject === undefined)
+    return event.target === undefined || /^e\d+$|"e\d+"/.test(event.target)
+      ? (point ?? "")
+      : event.target;
+  // A drag's point is where it ended.
+  if (event.to !== undefined)
+    return `${named(event.subject, undefined)} to ${named(event.to, point)}`;
+
+  return named(event.subject, point);
+};
+
+/**
+ * An action as a step: `click button "Pay"`. A failed one says only that: its error is advice for
+ * the caller that acted, which may name a ref, not a fact about the page.
+ */
+const step = (event: Action): string => {
+  const target = acted(event);
+  const text = event.text === undefined ? "" : JSON.stringify(event.text);
+
+  const what =
+    event.name === "type" && target !== ""
+      ? `${text} into ${target}`
+      : event.name === "select" && target !== ""
+        ? `${text} in ${target}`
+        : `${target} ${text}`;
+
+  return `${event.name} ${what}${event.ok ? "" : " (failed)"}`.replace(/\s+/g, " ").trim();
+};
+
+/** What is drawn rather than written, whose changes only the screenshots show. */
+const drawn = new Set(["canvas", "iframe", "video", "embed", "object", "svg"]);
+
+const onDrawn = (event: Action) =>
+  event.ok && event.subject !== undefined && drawn.has(event.subject.role ?? event.subject.tag);
+
+interface Line {
+  readonly at: number;
+  readonly rank: number;
+  readonly text: string;
+}
+
+/** At most this many lines of what happened; the least notable are counted, not listed. */
+const maxLines = 24;
+
+/**
+ * The changes as lines, news first, and the actions they name; cells of one column that changed
+ * together as one line. What kept changing says whether it still was at the moment, by its account.
+ */
+const changed = (moment: Moment, record: Changes) => {
+  const actions = moment.events.filter((event): event is Action => event._tag === "Action");
+  const named = new Set<Action>();
+  const changing = new Set(account(moment).changing);
+
+  const state = (change: Change) =>
+    changing.has(change)
+      ? ", still changing at the moment"
+      : change.count > 1 || change.earlier !== undefined
+        ? `, settled since ${seconds(moment, change.at)}`
+        : "";
+
+  // The action whose input a change followed: one that ran while the input arrived, give or take
+  // the clock's mapping, so input the library did not send names no action.
+  const cause = (change: Change) => {
+    const input = change.cause;
+
+    const action =
+      input === undefined
+        ? undefined
+        : actions.findLast((event) => event.startedAt <= input + 100 && event.at >= input - 100);
+
+    if (action === undefined) return "";
+    named.add(action);
+
+    return `, after ${step(action)}`;
+  };
+
+  const columns = Map.groupBy(
+    record.changes.filter(
+      (change) => change.kind === "text" && change.subject.context.column !== undefined,
+    ),
+    ({ subject: { context } }) => JSON.stringify([context.heading, context.column]),
+  );
+
+  const lines: Array<Line> = [];
+  const collapsed = new Set<Change>();
+
+  for (const [first, ...cells] of columns.values())
+    if (first !== undefined && cells.length >= 2) {
+      const still = [first, ...cells].filter((cell) => changing.has(cell)).length;
+
+      for (const cell of [first, ...cells]) collapsed.add(cell);
+      lines.push({
+        at: first.startedAt,
+        rank: still > 0 ? 3 : 2,
+        text: `${cells.length + 1} cells in column ${quoted(first.subject.context.column)}${where({ heading: first.subject.context.heading })} changed, such as ${describe(first, true)}${still > 0 ? `, ${still} still changing at the moment` : ""}`,
+      });
+    }
+  for (const change of record.changes)
+    if (!collapsed.has(change))
+      lines.push({
+        at: change.startedAt,
+        rank: changing.has(change) ? 3 : 2,
+        text: describe(change) + cause(change) + state(change),
+      });
+
+  return { lines, named };
+};
+
+/** What a part a moment could not read was, by the operation that failed: a window's one read is its changes. */
+const parts = new Map([
+  ["frame", "A picture of the moment"],
+  ["snapshot", "The page's outline"],
+]);
+
+/** The moment's changes and events as lines, most notable first when its changes are recorded. */
+const happened = (moment: Moment): ReadonlyArray<string> => {
+  const record = recordOf(moment);
+
+  const { lines, named } =
+    record === undefined
+      ? { lines: new Array<Line>(), named: new Set<Action>() }
+      : changed(moment, record);
+
+  // Whether anything but a field's own edit changed after an action began.
+  const followed = (event: Action) =>
+    record?.changes.some((change) => change.kind !== "value" && change.at > event.startedAt) ===
+    true;
+
+  // With a record, an action is told as a step where changes followed it and none names it, so a
+  // click whose effect a busy page leaves uncredited is not lost; where its effect is drawn; or
+  // where it started before the record began, as on the document a click opened. An attempt that
+  // nothing followed, a failed one, a hover and a scroll are left out.
+  const told = (event: Action) =>
+    !(event.ok && ["navigate", "back", "reload"].includes(event.name)) &&
+    (record === undefined ||
+      event.startedAt <= record.from ||
+      (event.ok &&
+        event.name !== "scroll" &&
+        (onDrawn(event) || (event.name !== "hover" && !named.has(event) && followed(event)))));
+
+  for (const event of moment.events)
+    if (event._tag === "Action" && event.page === moment.page && told(event))
+      lines.push({ at: event.at, rank: 4, text: step(event) });
+    else if (event._tag === "Navigated")
+      lines.push({
+        at: event.at,
+        rank: 0,
+        text: `${event.sameDocument ? "moved within the page" : "navigated"} to ${event.url}`,
+      });
+    else if (event._tag === "PageOpened")
+      lines.push({ at: event.at, rank: 0, text: `a tab opened at ${event.url}` });
+    else if (event._tag === "PageClosed")
+      lines.push({
+        at: event.at,
+        rank: 0,
+        text: `the tab ${event.cause === "crashed" ? "crashed" : "closed"}`,
+      });
+    else if (event._tag === "DialogShown")
+      lines.push({
+        at: event.at,
+        rank: 1,
+        text: `a dialog (${event.kind}) said ${JSON.stringify(event.message)}`,
+      });
+
+  const ordered = lines.toSorted((left, right) =>
+    record === undefined ? left.at - right.at : left.rank - right.rank || left.at - right.at,
+  );
+
+  const kept = ordered.slice(0, maxLines);
+  const drawing = moment.events.some((event) => event._tag === "Action" && onDrawn(event));
+  const begins = record === undefined ? moment.since : Math.max(moment.since, record.from);
+  const unread = moment.missing.some((error) => !parts.has(error.operation));
+
+  return [
+    ...kept.map((line) => `${seconds(moment, line.at)} ${line.text}`),
+    ...(ordered.length > maxLines ? [`…and ${ordered.length - maxLines} less notable`] : []),
+    ...(record === undefined
+      ? unread
+        ? []
+        : ["What changed on the page was not recorded."]
+      : record.changes.length > 0
+        ? []
+        : [
+            `No text in view changed${begins > moment.since ? ` after ${seconds(moment, begins)}` : ""}${drawing ? "; what is drawn, such as a canvas, shows only in the screenshots" : ""}.`,
+          ]),
+    ...(record !== undefined && record.dropped > 0
+      ? [
+          `The page changed too much to tell it all: at least ${record.dropped} changes are not told.`,
+        ]
+      : []),
+    ...(begins > moment.since
+      ? [`Changes before ${seconds(moment, begins)} are not all known.`]
+      : []),
+    ...moment.missing.map(
+      (error) =>
+        `${parts.get(error.operation) ?? "What changed on the page"} could not be read: ${error.reason.message}.`,
+    ),
+  ];
+};
+
+/**
+ * The moment as one user message: the page's outline when the moment has one, what changed, most
+ * notable first, what kept changing told as still changing at the moment or settled since when, by
+ * its account, with the actions that the changes followed, that changes followed though none
+ * names them, or that drew what only the screenshots show, what could not be read and why, and its
+ * frames captioned with their times, the last one "the moment" where it is the picture at its end.
+ * Give a model its task with `Prompt.setSystem`, and add what the caller knows about the page as
+ * more text.
+ */
+export const toPrompt = (moment: Moment): Prompt.Prompt => {
+  const count = moment.frames.length;
+  const last = count - 1;
+  const pictured = moment.frames.at(-1)?.hostTime === moment.until;
+
+  const following =
+    count === 1 ? "One screenshot follows" : `${count} screenshots follow, oldest first`;
+
+  return Prompt.fromMessages([
+    Prompt.makeMessage("user", {
+      content: [
+        Prompt.makePart("text", {
+          text: [
+            "One moment of a browser session. Rely only on what this material shows, and prefer concrete details: numbers, names, colours, positions and motion.",
+            "",
+            ...(moment.snapshot === undefined ? [] : [moment.snapshot.rendered, ""]),
+            `${recordOf(moment) === undefined ? "What happened" : "What changed, most notable first"} (seconds before the moment, over ${((moment.until - moment.since) / 1000).toFixed(1)}s):`,
+            ...happened(moment),
+            ...(count === 0
+              ? []
+              : [
+                  "",
+                  `${following}${pictured ? (count === 1 ? ": the moment itself." : "; the last one is the moment itself.") : "."}`,
+                ]),
+          ].join("\n"),
+        }),
+        ...moment.frames.flatMap((frame, index) => [
+          Prompt.makePart("text", {
+            text:
+              index === last && pictured ? "The moment:" : `${seconds(moment, frame.hostTime)}:`,
+          }),
+          Prompt.makePart("file", { mediaType: "image/jpeg", data: frame.data }),
+        ]),
+      ],
+    }),
+  ]);
+};

package/src/Motion.ts

@@ -0,0 +1,166 @@
+/**
+ * Pointer motion as a complete, bounded schedule, independent of browser input and transport. A
+ * presenter takes a planner as a value: `lognormal` here, or another, such as recorded strokes.
+ *
+ * @since 0.3.0
+ */
+import { Effect, Random, Schema } from "effect";
+
+export const maximumSamples = 2048;
+export const maximumDurationMillis = 5000;
+
+export const Point = Schema.Struct({ x: Schema.Finite, y: Schema.Finite });
+export type Point = typeof Point.Type;
+
+export const Sample = Schema.Struct({
+  x: Schema.Finite,
+  y: Schema.Finite,
+  afterMillis: Schema.Finite.check(
+    Schema.isGreaterThanOrEqualTo(0),
+    Schema.isLessThanOrEqualTo(maximumDurationMillis),
+  ),
+});
+
+export type Sample = typeof Sample.Type;
+
+/** A complete glide: 1 to 2,048 samples whose offsets never decrease. */
+export const Plan = Schema.Array(Sample).check(
+  Schema.isBetweenLength(1, maximumSamples),
+  Schema.makeFilter(
+    (samples) =>
+      samples.every(
+        (sample, index) => sample.afterMillis >= (samples[index - 1]?.afterMillis ?? 0),
+      ),
+    { expected: "nondecreasing sample offsets" },
+  ),
+);
+
+export type Plan = typeof Plan.Type;
+
+export interface Service {
+  /**
+   * Offsets start when the performer publishes the plan, before its first input. The browser
+   * decodes the result as a `Plan` whose last sample must be exactly `to`. Glide time has a budget
+   * of its own, outside the browser's `actionTimeout`, so a drag may glide twice for 5 seconds.
+   */
+  readonly plan: (from: Point, to: Point) => Effect.Effect<ReadonlyArray<Sample>>;
+}
+
+// These are the research's tuned two-stroke parameters. Width scaling was not evaluated, so the
+// model keeps its 40px reference width rather than implying measured target-size behavior.
+const tuning = {
+  intercept: 115.8,
+  slope: 291.8,
+  durationSigma: 0.407,
+  amplitude: 0.989,
+  amplitudeSigma: 0.138,
+  lateral: 0.0934,
+  primaryDuration: 0.512,
+  correctionDuration: 0.586,
+  overlap: 0.452,
+  sigmaLow: 0.155,
+  sigmaHigh: 0.53,
+} as const;
+
+const sampleMillis = 16.7;
+
+const normal = Effect.gen(function* () {
+  const radius = Math.sqrt(-2 * Math.log(1 - (yield* Random.next)));
+
+  return radius * Math.cos(2 * Math.PI * (yield* Random.next));
+});
+
+// Abramowitz-Stegun 7.1.26 supplies erf without another runtime dependency (error < 1.5e-7).
+const erf = (value: number) => {
+  const x = Math.abs(value);
+  const t = 1 / (1 + 0.3275911 * x);
+
+  const polynomial =
+    ((((1.061405429 * t - 1.453152027) * t + 1.421413741) * t - 0.284496736) * t + 0.254829592) * t;
+
+  return Math.sign(value) * (1 - polynomial * Math.exp(-x * x));
+};
+
+const cumulative = (time: number, onset: number, mu: number, sigma: number) =>
+  time <= onset ? 0 : (1 + erf((Math.log(time - onset) - mu) / (sigma * Math.SQRT2))) / 2;
+
+const plan: Service["plan"] = Effect.fnUntraced(function* (from, to) {
+  // Work in normalized coordinates so finite extreme inputs cannot overflow the displacement.
+  const scale = Math.max(1, Math.abs(from.x), Math.abs(from.y), Math.abs(to.x), Math.abs(to.y));
+  const startX = from.x / scale;
+  const startY = from.y / scale;
+  const deltaX = to.x / scale - startX;
+  const deltaY = to.y / scale - startY;
+  const distance = Math.hypot(deltaX, deltaY);
+
+  if (distance * scale < 2) return [{ ...to, afterMillis: 0 }];
+  const unitX = deltaX / distance;
+  const unitY = deltaY / distance;
+
+  const drawnDuration =
+    (tuning.intercept + tuning.slope * Math.log2(1 + distance * (scale / 40))) *
+    Math.exp((yield* normal) * tuning.durationSigma);
+
+  const endFactor = Math.max(
+    tuning.primaryDuration,
+    tuning.overlap * tuning.primaryDuration + tuning.correctionDuration,
+  );
+
+  // Bound the duration before evaluating either stroke: dropping a sampled tail would remove
+  // its homing correction. The last regular 16.7ms sample remains inside the public time bound.
+  const lastRegularSample = Math.floor(maximumDurationMillis / sampleMillis) * sampleMillis;
+  const duration = Math.min(drawnDuration, lastRegularSample / endFactor);
+  const amplitude = distance * (tuning.amplitude + (yield* normal) * tuning.amplitudeSigma);
+  const angle = ((yield* normal) * Math.PI) / 60;
+  const primaryX = amplitude * (unitX * Math.cos(angle) - unitY * Math.sin(angle));
+  const primaryY = amplitude * (unitY * Math.cos(angle) + unitX * Math.sin(angle));
+  const sigma1 = yield* Random.nextBetween(tuning.sigmaLow, tuning.sigmaHigh);
+  const primaryDuration = tuning.primaryDuration * duration;
+  const mu1 = Math.log(primaryDuration / (Math.exp(3 * sigma1) - Math.exp(-3 * sigma1)));
+  const onset1 = -Math.exp(mu1 - 3 * sigma1);
+  const sigma2 = yield* Random.nextBetween(tuning.sigmaLow, tuning.sigmaHigh);
+  const correctionDuration = tuning.correctionDuration * duration;
+  const mu2 = Math.log(correctionDuration / (Math.exp(3 * sigma2) - Math.exp(-3 * sigma2)));
+  const onset2 = tuning.overlap * primaryDuration - Math.exp(mu2 - 3 * sigma2);
+  const end = Math.max(primaryDuration, onset2 + Math.exp(mu2 + 3 * sigma2));
+  const centered = Math.max(Number.EPSILON, yield* Random.next) - 0.5;
+
+  const lateral =
+    -tuning.lateral * Math.sign(centered) * Math.log(1 - 2 * Math.abs(centered)) * distance;
+
+  const count = Math.min(
+    Math.ceil(end / sampleMillis),
+    Math.floor(lastRegularSample / sampleMillis),
+  );
+
+  const samples: Array<Sample> = [];
+  let last: Point = from;
+
+  const coordinate = (value: number) =>
+    Math.round(Math.max(-Number.MAX_VALUE, Math.min(Number.MAX_VALUE, value * scale)));
+
+  for (let index = 0; index < count; index++) {
+    const afterMillis = index * sampleMillis;
+    const first = cumulative(afterMillis, onset1, mu1, sigma1);
+    const second = cumulative(afterMillis, onset2, mu2, sigma2);
+    const bend = lateral * Math.sin(Math.PI * first);
+    const x = coordinate(startX + primaryX * first + (deltaX - primaryX) * second - unitY * bend);
+    const y = coordinate(startY + primaryY * first + (deltaY - primaryY) * second + unitX * bend);
+
+    // A pointer that stays on its pixel reports nothing; the model's timing is unchanged.
+    if (x === last.x && y === last.y) continue;
+    last = { x, y };
+    samples.push({ x, y, afterMillis });
+  }
+
+  // The exact destination always lands at the model's end, even if a dwell precedes it.
+  samples.push({ ...to, afterMillis: count * sampleMillis });
+
+  return samples;
+});
+
+/**
+ * The research's tuned two-stroke sigma-lognormal model: a fast stroke toward the target and a
+ * slower one that homes in on it, with a little bend, drawn from `Random`.
+ */
+export const lognormal: Service = { plan };