opencode-overclock 0.2.2 → 0.4.0

package/README.md

@@ -1,106 +1,303 @@
 # opencode-overclock
 
-Power-ups for [opencode](https://opencode.ai). Background tasks, scheduling, sandboxed bash, tool hooks, usage telemetry, checkpoints. Each = module, toggleable. Module dies when opencode ships native equal/better.
+The modular workflow suite and power-ups for [opencode](https://opencode.ai): background
+tasks, cron-style scheduling, quality-gate hooks, cost telemetry — and an ASCII companion.
 
-## Install
+Everything is a separate module you can turn off individually, so you can take one feature and
+ignore the rest. When opencode ships a native equivalent, the matching module goes away.
 
 ```sh
 opencode plugin opencode-overclock       # this project
-opencode plugin -g opencode-overclock    # global
+opencode plugin -g opencode-overclock    # every project
 ```
 
-Requires opencode >= 1.18.9.
+## What you get
+
+| Module      | What it does                                                                                                                                                  | Tools it adds                                       |
+| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- |
+| `tasks`     | Run shell commands in the background. The agent gets the result posted back into the session when they finish, and a nudge if one blocks on a prompt.         | `task_run` `task_status` `task_output` `task_kill`  |
+| `sched`     | Recurring prompts on a cron expression or an interval (`"5m"`). Survives restarts; an interval on the current session makes a loop.                           | `schedule_create` `schedule_list` `schedule_delete` |
+| `guard`     | Your own quality gates: run a command after the agent edits files, and feed failures back to it once the session goes idle. Built-in recipes & edit recovery. | —                                                   |
+| `recovery`  | Automatically heal provider errors (missing tool results, thinking block sequencing, context limit) and auto-resume sessions.                                 | —                                                   |
+| `truncator` | Context-protecting smart output truncation for high-volume tools (`task_output`, `bash`, `grep`, `glob`, `webfetch`) preserving header & tail diagnostics.    | —                                                   |
+| `usage`     | Per-day and per-session cost and token totals, collected from the event bus (accessible via TUI `/oc-usage`).                                                 | —                                                   |
+| `buddy`     | An ASCII pet next to the prompt that reacts to what the session is doing. Purely cosmetic.                                                                    | —                                                   |
+
+On top of the tools, the TUI side adds desktop notifications when a turn finishes or the agent
+needs you, plus `/oc-tasks`, `/oc-usage`, `/oc-schedules`, `/oc-buddy` (pet), `/oc-buddy-switch` (choose species), and `/oc-buddy-cycle` (next species).
 
-One package, two surfaces: the **server** plugin (tools + hooks) and the **TUI** plugin (notifications + slash commands). They register in _separate_ config files, so use the command above rather than editing config by hand — it writes both:
+**Please read this before installing:** overclock gives the agent the ability to run shell
+commands in the background (`task_run`) and to schedule recurring prompts (`schedule_create`).
+That is the point of the plugin, but it is worth an explicit yes rather than a surprise. It
+tells you what it enabled on a project's first run. The tool definitions cost roughly 800
+tokens of context.
+
+## Install
+
+The command at the top of this page is the reliable way to install, because one package ships
+**two** surfaces that register in two different config files:
 
 ```jsonc
-// opencode.json  -> server surface
+// opencode.json  -> server surface: the tools and hooks
 { "plugin": ["opencode-overclock"] }
-// tui.json       -> TUI surface  (omit this and notifications/slash commands silently never load)
+// tui.json       -> TUI surface: notifications, slash commands, the buddy
 { "plugin": ["opencode-overclock"] }
 ```
 
-Local dev: copy or symlink into `.opencode/plugins/` — see [Dev](#dev). Note that a plugin _path_ only works there; `plugin` array entries resolve by npm name from the registry, and an unpublished name fails silently.
+Adding only the `opencode.json` entry by hand is the most common mistake: the tools work and
+the notifications silently never load.
+
+Requires **opencode >= 1.18.4**. That floor comes from the buddy sprite, which renders against
+the `@opentui/solid` version opencode bundles from 1.18.4 onward. If you don't care about the
+buddy, the server surface alone works back to 1.15.11 — the first release where opencode calls
+a plugin's `dispose` hook, without which this plugin's timers and watchers are never cleaned up.
+
+## Configuration
+
+Everything is optional. With no options configured, overclock runs with sensible defaults: background
+tasks, cron-style scheduling, quality gates, usage telemetry, and the buddy are active immediately.
+
+Configure options directly in your project or global `opencode.json`:
+
+```jsonc
+{
+  "plugin": [
+    [
+      "opencode-overclock",
+      {
+        "tasks": { "killOnExit": true },
+        "guard": { "auto": true },
+      },
+    ],
+  ],
+}
+```
+
+To turn an individual feature off:
+
+```jsonc
+{
+  "plugin": [
+    [
+      "opencode-overclock",
+      {
+        "buddy": false,
+      },
+    ],
+  ],
+}
+```
+
+| Module           | Options                                                                                                          |
+| ---------------- | ---------------------------------------------------------------------------------------------------------------- |
+| `tasks`          | `killOnExit` bool · `stallDetection` bool · `stallThresholdMs` num · `stallCheckIntervalMs` num · `tmux` bool    |
+| `sched`          | `skipIfBusy` bool                                                                                                |
+| `guard`          | `hooks` array · `recipes` array (`["tsc", "eslint", "cargo", "ruff", "go"]`) · `auto` bool · `editRecovery` bool |
+| `recovery`       | `maxAttempts` num · `cooldownMs` num · `autoResume` bool                                                         |
+| `truncator`      | `maxChars` num · `tools` array · `headLines` num · `tailLines` num                                               |
+| `usage`, `buddy` | —                                                                                                                |
+
+### Quality gates (`guard`)
+
+Quality gates let you define automated feedback loops. Whenever the agent modifies code with `edit`
+or `write`, the guard runs your project's verification command in the background. If the command fails,
+the error output is automatically fed back into the session once the agent finishes its turn, prompting
+it to self-correct.
+
+Because verification commands vary by language and repository, configure hooks in your project's
+local `opencode.json`:
+
+#### Stack recipes
+
+##### TypeScript / JavaScript
+
+```jsonc
+{
+  "guard": {
+    "hooks": [
+      {
+        "name": "typecheck",
+        "tools": ["edit", "write"],
+        "pathFilter": "src/**/*.ts",
+        "run": "npm run typecheck",
+      },
+    ],
+  },
+}
+```
+
+##### Python (Ruff / Pytest)
+
+```jsonc
+{
+  "guard": {
+    "hooks": [
+      {
+        "name": "lint",
+        "tools": ["edit", "write"],
+        "pathFilter": "**/*.py",
+        "run": "ruff check .",
+      },
+    ],
+  },
+}
+```
+
+##### Rust (Cargo)
+
+```jsonc
+{
+  "guard": {
+    "hooks": [
+      {
+        "name": "cargo-check",
+        "tools": ["edit", "write"],
+        "pathFilter": "**/*.rs",
+        "run": "cargo check",
+      },
+    ],
+  },
+}
+```
+
+##### Go
+
+```jsonc
+{
+  "guard": {
+    "hooks": [
+      {
+        "name": "go-test",
+        "tools": ["edit", "write"],
+        "pathFilter": "**/*.go",
+        "run": "go test ./...",
+      },
+    ],
+  },
+}
+```
+
+##### Generic / Make
+
+```jsonc
+{
+  "guard": {
+    "hooks": [
+      {
+        "name": "check",
+        "tools": ["edit", "write"],
+        "run": "make check",
+      },
+    ],
+  },
+}
+```
+
+#### Hook options
+
+| Field        | Default     | Description                                                                   |
+| ------------ | ----------- | ----------------------------------------------------------------------------- |
+| `name`       | _required_  | Identifier displayed in failure reports                                       |
+| `tools`      | _required_  | Tools to trigger on, e.g. `["edit", "write"]`                                 |
+| `run`        | _required_  | Shell command to execute (receives `$GUARD_TOOL` and `$GUARD_FILE` in env)    |
+| `pathFilter` | `undefined` | Optional glob pattern to limit triggers to relevant files (e.g. `**/*.py`)    |
+| `mode`       | `"inject"`  | `"inject"` waits for the session to go idle; `"append"` reports immediately   |
+| `debounceMs` | `2000`      | Debounce duration for rapid successive edits                                  |
+| `timeoutMs`  | `60000`     | Execution timeout before killing the command                                  |
+| `maxDeferMs` | `300000`    | Maximum time `"inject"` will wait for an idle session before reporting anyway |
+| `onSuccess`  | `"silent"`  | `"silent"` or `"notify"`                                                      |
+
+### Restricting and remapping tool names
 
-## Config
+If your setup only accepts certain tool names, list them in `toolAllowlist`. Any tool whose
+name isn't permitted is withheld from the model rather than offered and refused:
+
+```jsonc
+{
+  "plugin": [
+    [
+      "opencode-overclock",
+      {
+        "toolAllowlist": ["task_run", "task_status", "schedule_create"],
+      },
+    ],
+  ],
+}
+```
 
-`.opencode/overclock.json` (optional, missing = defaults):
+`toolNames` maps this plugin's tools onto custom names you want the model to see:
 
-```json
+```jsonc
 {
-  "features": {
-    "tasks": true,
-    "sched": true,
-    "sandbox": { "net": false },
-    "guard": {
-      "hooks": [{ "name": "typecheck", "tools": ["edit", "write"], "run": "bun run typecheck" }]
-    }
-  }
+  "plugin": [
+    [
+      "opencode-overclock",
+      {
+        "toolNames": { "task_run": "run_background_task" },
+      },
+    ],
+  ],
 }
 ```
 
-`true`/`false` toggle. Object = on + options. Defaults: all on except sandbox; guard inert without `hooks`.
+### Running OpenCode V2 plugins on OpenCode V1
 
-Unknown keys, unknown feature names, and wrong option types are reported at startup with a
-"did you mean" — a typo like `killOnExist` would otherwise read as "not set" and silently
-run the default. Bad config never takes the plugin down; it falls back to defaults.
+OpenCode V1 distributions cannot natively load V2 plugins (which export `{ id, setup }` or `{ id, effect }` instead of a server function). Overclock provides an embedded V2 host engine that runs V2 plugins side-by-side with V1 tools:
 
-| Feature                | Options                                                                                         |
-| ---------------------- | ----------------------------------------------------------------------------------------------- |
-| `tasks`                | `killOnExit` bool · `stallDetection` bool · `stallThresholdMs` num · `stallCheckIntervalMs` num |
-| `sched`                | `skipIfBusy` bool                                                                               |
-| `sandbox`              | `net` bool                                                                                      |
-| `guard`                | `hooks` array                                                                                   |
-| `usage`, `checkpoints` | —                                                                                               |
-| `buddy`                | — (TUI surface; `features.buddy: false` hides it)                                               |
+```jsonc
+{
+  "plugin": [
+    [
+      "opencode-overclock",
+      {
+        "plugins": ["./plugins/custom-agent.ts", ["opencode-plugin-review", { "strict": true }]],
+      },
+    ],
+  ],
+}
+```
 
-Each `guard` hook takes `name` · `tools` (array) · `run` — plus optional `pathFilter` (glob),
-`mode` (`inject` default, or `append`), `debounceMs` (2000), `timeoutMs` (60000), `onSuccess`
-(`silent`/`notify`), and `maxDeferMs` (300000 — how long `inject` waits for an idle session
-before reporting anyway).
+Overclock synthesizes a spec-compliant `PluginContext`, adapting V2 domain transforms (`agent`, `command`, `catalog`, `reference`, `skill`, `aisdk`) to live V1 config and chat hooks while keeping all V1 power tools active.
 
-On a project's first run, overclock reports what it added. Worth knowing that installing it
-grants the agent **background shell execution** (`task_run`) and **recurring scheduling**
-(`schedule_create`). The tool definitions themselves cost ~800 tokens of context in total.
+Startup tells you what was renamed, what was withheld, and warns on collisions with opencode
+built-in tools. Descriptions mentioning a renamed tool are rewritten automatically.
 
-## Features
+## Notes on the TUI surface
 
-| Module        | Tools                                                      | Does                                                                                                                      |
-| ------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
-| `tasks`       | `task_run` `task_status` `task_output` `task_kill`         | background shell cmds; exit -> result posted back into session; stall watchdog nudges on interactive prompts              |
-| `sched`       | `schedule_create` `schedule_list` `schedule_delete`        | cron exprs or intervals ("5m"); interval + current session = loop; restart-safe                                           |
-| `sandbox`     | `bash_unsandboxed` (escape hatch)                          | bwrap-wrap every bash call: `/` ro, project + `/tmp` rw, net configurable. Opt-in                                         |
-| `guard`       | —                                                          | user hooks: after matching tool calls, run configured cmds (debounced), failures fed back to model once the session idles |
-| `usage`       | `usage_report`                                             | per-day + per-session cost/token telemetry off `message.updated` events                                                   |
-| `checkpoints` | `checkpoint_list` `checkpoint_revert` `checkpoint_restore` | session revert/unrevert over opencode's shadow-git snapshots; revert gated by permission ask                              |
-| `buddy`       | —                                                          | ASCII pet beside the prompt (TUI): hatches once per install, idles/blinks, reacts to session events; `/oc-buddy` pets it  |
+The TUI plugin sends a desktop notification (with sound) when a turn completes or the agent
+needs permission, asks a question, or errors — each individually switchable through plugin
+options (`notifyIdle`, `notifyPermission`, `notifyQuestion`, `notifyError`, `buddy` in `tui.json`).
+Its slash commands read the state files under `.opencode/overclock/`, so they work
+without going through the model.
 
-TUI plugin (`src/tui.ts`, separate surface): OS notifications on idle/permission/question/error via `attention.notify`, slash commands for tasks/usage/schedules off the `.opencode/overclock/` state mirrors, and the buddy (`src/buddy/`) in the prompt-right slots. The buddy rolls species/rarity/name/stats once (persisted in TUI kv), hides below 100 columns, and needs `@opentui/solid` resolvable at runtime -- if it isn't, the buddy silently sits this one out while the rest of the TUI plugin loads.
+The buddy hatches once per install with a random species, rarity and name, persists in the
+TUI's key-value store, hides itself below 100 columns, and needs `@opentui/solid` resolvable at
+runtime. If it isn't, the buddy quietly sits out and the rest of the TUI plugin still loads.
+Switch buddy on demand via `/oc-buddy-switch` (opens an interactive species picker or rolls a fresh companion)
+or `/oc-buddy-cycle` (advances directly to the next species in rotation).
 
-## Layout
+## Contributing
 
 ```
 src/
-  index.ts          entry: config -> init modules -> merge hooks
+  index.ts          entry: init enabled modules, merge hooks, hybrid V1/V2 export
   tui.ts            TUI plugin (notifications + slash commands), separate export
-  types.ts          FeatureModule contract
-  config.ts         config loader
-  merge.ts          hook composition (many modules, same hook -> sequential)
-  lib/              state dir + json, session inject + toast
-  features/         one file per module + registry
+  core/             types, lifecycle/hook merging, tool policy, capability summary, bridge
+  platform/         host adapters: process (exec/tmux), session (busy/inject/notify), storage (state/store), probe
+  buddy/            ASCII companion state, sprites, and TUI slot integration
+  v2/               embedded V2 plugin host, synthetic context, and dynamic loader
+  features/         feature modules (tasks, sched, guard, recovery, truncator, usage, buddy)
 test/               bun test
 ```
 
-## Add feature
-
-1. `src/features/<name>.ts`, export `FeatureModule`
-2. Register in `src/features/index.ts`
+Adding a feature:
 
-## Docs
+1. Write `src/features/<name>.ts` exporting a `FeatureModule`.
+2. Register it in `src/features/index.ts`.
 
-- [docs/opencode-plugin-surface.md](docs/opencode-plugin-surface.md) — opencode plugin/hook/event surface map + upstream drift watchlist (research)
-
-## Dev
+Background reading:
+[docs/opencode-plugin-surface.md](docs/opencode-plugin-surface.md) maps opencode's
+plugin/hook/event surface and tracks upstream drift.
 
 ```sh
 bun install
@@ -118,31 +315,38 @@ npm publish
 bun run verify:published    # runtime load, by name, from the registry
 ```
 
-`verify` cannot exercise the runtime load path — opencode resolves `plugin` entries by npm
-name from the registry, and a miss is silent. `verify:published` is the only check that
-proves an installed-from-npm session actually gets the tools; run it after every publish.
+`verify` can't exercise the runtime load path: opencode resolves `plugin` entries by npm name
+from the registry, and a miss is silent. `verify:published` is the only check that proves an
+installed-from-npm session actually gets the tools, so run it after every publish.
 
-### Live loop
+### Working on it locally
 
-`.opencode/plugins/dev.ts` re-exports `src/index.ts`, `dev-tui.ts` re-exports `src/tui.ts` -> opencode session in this repo runs both surfaces from source.
+`.opencode/plugins/dev.ts` re-exports `src/index.ts` and `dev-tui.ts` re-exports `src/tui.ts`,
+so an opencode session in this repo runs both surfaces from source. Note that only this
+auto-loaded directory accepts a path — `plugin` array entries resolve by npm name from the
+registry, and an unpublished name fails silently.
 
-1. `opencode` here. Plugin live.
-2. Edit `src/`. No hot reload -> restart opencode.
-3. State inspect: `.opencode/overclock/` (gitignored).
+1. Run `opencode` here. The plugin is live.
+2. Edit `src/`. There's no hot reload, so restart opencode.
+3. Inspect state under `.opencode/overclock/` (gitignored).
 
 Gotcha: if `~/.config/opencode/tui.json` also loads `opencode-overclock` from npm, that copy
-wins the `overclock-tui` id and the local dev TUI plugin (and any unpublished feature, e.g.
-the buddy) silently never loads. Remove the global entry while developing, or run with
-`XDG_CONFIG_HOME` pointed elsewhere.
+wins the `overclock-tui` id and your local dev TUI plugin (along with any unpublished feature)
+silently never loads. Remove the global entry while developing, or point `XDG_CONFIG_HOME`
+somewhere else.
 
-### Headless e2e
+### Headless end-to-end
 
 ```sh
-timeout 90 opencode run -m anthropic/claude-sonnet-5 "Use task_run to run 'echo hi' ..." < /dev/null
+timeout 90 opencode run -m <provider>/<model> "Use task_run to run 'echo hi' ..." < /dev/null
 ```
 
-Gotchas:
+- `< /dev/null` is required; an open stdin hangs.
+- A dev build can hang on exit after the work is done, so wrap it in `timeout` and judge by
+  artifacts (`.opencode/overclock/`, log tails) rather than the exit code.
+- Plugin stderr goes to `opencode run --print-logs` or `~/.local/share/opencode/log/`. Grep for
+  `[overclock]`.
+
+## License
 
-- `< /dev/null` required. Open stdin -> hang.
-- Dev build hang on exit AFTER work done -> wrap in `timeout`, judge by artifacts (`.opencode/overclock/`, log tails), not exit code.
-- Plugin stderr: `opencode run --print-logs` or `~/.local/share/opencode/log/`. Grep `[overclock]`.
+MIT

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "opencode-overclock",
-  "version": "0.2.2",
-  "description": "Power-ups for opencode: background tasks, scheduling, sandboxed bash, tool hooks, usage telemetry, checkpoints. Modular, toggleable.",
+  "version": "0.4.0",
+  "description": "Power-ups for opencode: background tasks, cron scheduling, quality-gate hooks, usage telemetry, and companion. Modular, toggleable.",
   "type": "module",
   "repository": {
     "type": "git",
@@ -35,7 +35,7 @@
     "prepublishOnly": "tsc --noEmit && bun test"
   },
   "engines": {
-    "opencode": ">=1.18.9"
+    "opencode": ">=1.18.4"
   },
   "dependencies": {
     "@opencode-ai/plugin": "1.18.9",

package/src/bridge.ts

@@ -0,0 +1 @@
+export { createHybridPlugin, type HybridPlugin, type HybridPluginDefinition } from "./core/bridge.ts"

package/src/buddy/companion.ts

@@ -1,4 +1,74 @@
-import { SPECIES, type Companion, type CompanionStats, type Rarity } from "./types.ts"
+import type { SpriteState } from "./sprites.ts"
+
+export const SPECIES = [
+  "cat",
+  "dog",
+  "bunny",
+  "owl",
+  "bat",
+  "penguin",
+  "duck",
+  "ghost",
+  "slime",
+] as const
+export type Species = (typeof SPECIES)[number]
+
+export type Rarity = "common" | "uncommon" | "rare" | "legendary"
+
+export interface CompanionStats {
+  patience: number
+  chaos: number
+  wisdom: number
+  snark: number
+}
+
+export interface Companion {
+  species: Species
+  rarity: Rarity
+  name: string
+  stats: CompanionStats
+  hatchedAt: number
+}
+
+export type ReactionKind = "done" | "error" | "permission" | "question" | "pet"
+
+/** Speech-bubble line + which face the sprite pulls while it shows. */
+export interface Reaction {
+  text: string
+  state: SpriteState
+}
+
+// Lines render into the sprite's 12-col effect row -- keep every line <= 12 chars.
+const POOLS: Record<ReactionKind, { lines: string[]; state: SpriteState }> = {
+  done: { lines: ["cooked", "ate that", "big W", "say less", "we ball"], state: "idle" },
+  error: { lines: ["bruh", "ur cooked", "skill issue", "aint no way", "big L"], state: "alarmed" },
+  permission: { lines: ["let me cook", "valid?", "we good?", "bet?", "vibe check"], state: "curious" },
+  question: { lines: ["wym?", "the move?", "u tell me", "spill", "hbu?"], state: "curious" },
+  pet: { lines: ["pookie!", "w rizz", "ur valid", "slay", "ily"], state: "pet" },
+}
+
+/** Pure: pick a random line for a reaction kind. */
+export function pickReaction(kind: ReactionKind, rng: () => number = Math.random): Reaction {
+  const pool = POOLS[kind]
+  return { text: pool.lines[Math.floor(rng() * pool.lines.length)]!, state: pool.state }
+}
+
+export interface ReactionGate {
+  /** True + arms the cooldown if enough time has passed since the last fire. */
+  tryFire(now?: number): boolean
+}
+
+/** Debounce for event-driven reactions -- keeps a busy session from spamming the bubble. */
+export function createReactionGate(cooldownMs = 8000): ReactionGate {
+  let last = -Infinity
+  return {
+    tryFire(now: number = Date.now()): boolean {
+      if (now - last < cooldownMs) return false
+      last = now
+      return true
+    },
+  }
+}
 
 const RARITY_WEIGHTS: { rarity: Rarity; weight: number }[] = [
   { rarity: "common", weight: 60 },
@@ -55,16 +125,45 @@ function rollStat(rng: () => number): number {
 }
 
 /**
- * Companions persist in TUI kv and outlive the sprite sheet, so an install that
- * hatched a species we have since retired would look it up and find no art. Move
- * it onto a species we still draw, keeping the identity that isn't the drawing:
- * same name, rarity, stats and hatch date. Returns undefined when nothing to do.
+ * Move companion onto an active species if its hatched species was retired.
  */
 export function migrateSpecies(c: Companion, rng: () => number = Math.random): Companion | undefined {
   if ((SPECIES as readonly string[]).includes(c.species)) return undefined
   return { ...c, species: pick(rng, SPECIES) }
 }
 
+/** Short character descriptions for each species based on their idle fidget. */
+export const SPECIES_DESCRIPTIONS: Record<Species, string> = {
+  cat: "tail flick",
+  dog: "ear perk",
+  bunny: "ear wiggle",
+  owl: "feather ruffle",
+  bat: "wing beat",
+  penguin: "waddle",
+  duck: "ripples",
+  ghost: "float",
+  slime: "squash",
+}
+
+/** Pure: formatted description for dialog options. */
+export function speciesDescription(species: Species, isCurrent = false): string {
+  const desc = SPECIES_DESCRIPTIONS[species] ?? species
+  return isCurrent ? `${desc} (current)` : desc
+}
+
+/** Move companion to a new species, preserving name, stats, and hatchedAt. */
+export function switchSpecies(c: Companion, species: Species): Companion {
+  if (!(SPECIES as readonly string[]).includes(species)) return c
+  return { ...c, species }
+}
+
+/** Pure: get the next species in the SPECIES rotation. */
+export function cycleSpecies(current: Species): Species {
+  const idx = SPECIES.indexOf(current)
+  if (idx === -1) return SPECIES[0]
+  return SPECIES[(idx + 1) % SPECIES.length]!
+}
+
 /** One-line card for the /oc-buddy toast. */
 export function describeCompanion(c: Companion): string {
   const s = c.stats

package/src/buddy/sprites.ts

@@ -1,4 +1,4 @@
-import type { Species } from "./types.ts"
+import type { Species } from "./companion.ts"
 
 /**
  * Every frame is padded to exactly SPRITE_WIDTH columns so animation never
@@ -35,8 +35,8 @@ interface SpeciesArt {
   /**
    * Which of the two poses a tick shows. Per-species on purpose: alternating
    * every tick reads as a strobe, and it makes every species move alike. A cat
-   * flicks its tail rarely, a dog wags nonstop, a dragon's wingbeat is slow and
-   * held at the top, a ghost never quite lands.
+   * flicks its tail rarely, a dog wags nonstop, a bat's wingbeat flutters rapidly,
+   * a ghost never quite lands.
    */
   beat: (t: number) => 0 | 1
 }
@@ -148,7 +148,7 @@ export function withBubble(frame: string, bubble: string | undefined): string {
 /** Pure: render one frame. `tick` drives idle fidget + blink; other states are static. */
 export function spriteFrame(species: Species, state: SpriteState, tick: number): string {
   const art = ART[species]
-  const t = ((tick % 1000) + 1000) % 1000
+  const t = Math.max(0, tick)
   const body = art.idle[art.beat(t)]!
   const rest = art.idle[0]!