nokeo08
d0528b4a92
Mermaid treats ';' as a statement separator, so the label 'lastPos (== start; re-sync)' terminated mid-line and the parser then expected an arrow (the 'Parse error on line 59' the preview showed). Removed the semicolon and, defensively, replaced 'Iterable<Point>' with plain text so the angle brackets aren't interpreted as an HTML tag in the rendered label.
89 lines
3.5 KiB
Markdown
89 lines
3.5 KiB
Markdown
# Execution: the happy path
|
|
|
|
This traces one full idle-triggered sweep that completes cleanly — the
|
|
"happy path" where the machine is idle long enough to fire, the configured
|
|
pattern runs to exhaustion, and no real user activity interrupts it.
|
|
|
|
For the module breakdown and the three seams (`device` / `strategies` /
|
|
`executor`), see the "How it works" section of the [README](../README.md).
|
|
|
|
```mermaid
|
|
sequenceDiagram
|
|
autonumber
|
|
participant Entry as move.ts
|
|
participant Keeper as runKeeper
|
|
participant Sim as simulateActivity
|
|
participant Strat as Strategy<br/>(e.g. line)
|
|
participant Exec as executePath
|
|
participant Dev as Device<br/>(nut.js)
|
|
|
|
Note over Entry: startup (args → config)
|
|
Entry->>Entry: parseCliArgs()
|
|
Entry->>Entry: loadConfigFile()
|
|
Entry->>Entry: resolveConfig(file, cli)
|
|
Entry->>Keeper: runKeeper(config)
|
|
|
|
Keeper->>Dev: createNutDevice()
|
|
Note right of Dev: sets mouse.config.autoDelayMs = 0
|
|
Keeper->>Keeper: log.info(banner)
|
|
Keeper->>Dev: getPosition()
|
|
Dev-->>Keeper: lastPos
|
|
Note over Keeper: lastActivity = now
|
|
|
|
loop every checkInterval (until idle long enough)
|
|
Keeper->>Dev: sleep(checkInterval)
|
|
Keeper->>Dev: getPosition()
|
|
Dev-->>Keeper: pos
|
|
Note over Keeper: pos == lastPos (no user movement)<br/>now - lastActivity ≥ moveInterval → fire
|
|
end
|
|
|
|
Keeper->>Sim: simulateActivity(config, log, dev)
|
|
Sim->>Dev: getPosition()
|
|
Dev-->>Sim: start
|
|
Sim->>Dev: width()
|
|
Dev-->>Sim: width
|
|
Sim->>Dev: height()
|
|
Dev-->>Sim: height
|
|
Note over Sim: strategy = STRATEGIES[config.pattern]<br/>ctx = { start, width, height, rng }
|
|
Sim->>Exec: executePath(strategy, ctx, dev, log, config)
|
|
|
|
Exec->>Strat: path(ctx)
|
|
Strat-->>Exec: iterable of Points
|
|
|
|
loop for each target point (clean run)
|
|
Exec->>Exec: resolveTarget(bounds, target) → point
|
|
Exec->>Dev: setPosition(point)
|
|
Exec->>Dev: sleep(stepDelay)
|
|
Exec->>Dev: getPosition()
|
|
Dev-->>Exec: current
|
|
Note over Exec: |current - point| ≤ 2px → not the user, continue
|
|
end
|
|
|
|
Note over Exec: path exhausted, no interruption
|
|
Exec->>Dev: setPosition(round(start))
|
|
Note right of Exec: restore cursor to origin
|
|
Exec-->>Sim: "completed"
|
|
Sim-->>Keeper: (done)
|
|
|
|
Keeper->>Dev: getPosition()
|
|
Dev-->>Keeper: lastPos (equals start, re-synced)
|
|
Note over Keeper: lastActivity = now<br/>loop continues
|
|
```
|
|
|
|
## Invariants this path relies on
|
|
|
|
- **`createNutDevice()` is the only nut.js touchpoint.** It disables nut.js's
|
|
100ms auto-delay so `executePath` owns cadence via `stepDelay`.
|
|
- **The strategy is pure.** `path(ctx)` yields ideal points from geometry
|
|
alone (`start` / `width` / `height` / `rng`); it never touches the device,
|
|
which is what makes every pattern unit-testable without a screen.
|
|
- **Every step re-reads the cursor** and compares it against the *commanded*
|
|
point (not the strategy's ideal, possibly fractional target) within a 2px
|
|
tolerance. On the happy path each check passes, so the loop runs to
|
|
exhaustion. A mismatch beyond tolerance is real user activity and returns
|
|
`"interrupted"` without restoring — the branch this diagram omits.
|
|
- **Clean completion restores the cursor to `round(start)`.** That is why the
|
|
follow-up `getPosition()` in `runKeeper` re-syncs `lastPos` to the origin as
|
|
a no-op, and the next idle check sees no net movement (so the synthetic
|
|
sweep is never mistaken for the user returning).
|