cursorless-dev · trillium · Jul 7, 2026 · Jul 7, 2026 · Jul 7, 2026 · Jul 7, 2026
@@ -98,7 +98,7 @@ repos:
       - id: ruff-format
 
   - repo: https://github.com/cursorless-dev/talon-tools
-    rev: v0.9.0
+    rev: v0.11.0
     hooks:
       - id: talon-fmt
       - id: tree-sitter-fmt

@@ -1,13 +1,18 @@
 import { pickBy } from "lodash-es";
 import vscode from "vscode";
 import type {
+  HatColor,
+  HatShape,
   HatStyleInfo,
   HatStyleMap,
   Listener,
+  VscodeHatStyleName,
+} from "@cursorless/lib-common";
+import {
+  HAT_COLORS,
+  HAT_NON_DEFAULT_SHAPES,
+  Notifier,
 } from "@cursorless/lib-common";
-import { Notifier } from "@cursorless/lib-common";
-import type { HatColor, HatShape, VscodeHatStyleName } from "./hatStyles.types";
-import { HAT_COLORS, HAT_NON_DEFAULT_SHAPES } from "./hatStyles.types";
 
 export interface ExtendedHatStyleInfo extends HatStyleInfo {
   color: HatColor;

@@ -3,15 +3,23 @@ import path from "node:path";
 import { isEqual } from "lodash-es";
 import vscode from "vscode";
 import type {
+  HatShape,
+  IndividualHatAdjustmentMap,
   Listener,
   Messages,
   PathChangeListener,
+  VscodeHatStyleName,
+} from "@cursorless/lib-common";
+import {
+  DEFAULT_HAT_HEIGHT_EM,
+  DEFAULT_VERTICAL_OFFSET_EM,
+  defaultShapeAdjustments,
+  getErrorMessage,
+  HAT_SHAPES,
+  Notifier,
 } from "@cursorless/lib-common";
-import { getErrorMessage, Notifier } from "@cursorless/lib-common";
 import { walkFiles } from "@cursorless/lib-node-common";
 import type { VscodeApi } from "@cursorless/lib-vscode-common";
-import type { HatShape, VscodeHatStyleName } from "../hatStyles.types";
-import { HAT_SHAPES } from "../hatStyles.types";
 import { vscodeGetConfigurationString } from "../VscodeConfiguration";
 import type {
   ExtendedHatStyleMap,
@@ -20,12 +28,6 @@ import type {
 import type { FontMeasurements } from "./FontMeasurements";
 import { getHatThemeColors } from "./getHatThemeColors";
 import { performPr1868ShapeUpdateInit } from "./performPr1868ShapeUpdateInit";
-import type { IndividualHatAdjustmentMap } from "./shapeAdjustments";
-import {
-  DEFAULT_HAT_HEIGHT_EM,
-  DEFAULT_VERTICAL_OFFSET_EM,
-  defaultShapeAdjustments,
-} from "./shapeAdjustments";
 
 const CURSORLESS_HAT_SHAPES_SUFFIX = ".svg";
 

@@ -8,11 +8,11 @@ import type {
   Listener,
   Range,
   TextEditor,
+  VscodeHatStyleName,
 } from "@cursorless/lib-common";
 import { Notifier } from "@cursorless/lib-common";
 import type { VscodeApi } from "@cursorless/lib-vscode-common";
 import { toVscodeRange } from "@cursorless/lib-vscode-common";
-import type { VscodeHatStyleName } from "../hatStyles.types";
 import { VscodeEnabledHatStyleManager } from "../VscodeEnabledHatStyleManager";
 import type { VscodeIDE } from "../VscodeIDE";
 import type { VscodeTextEditor } from "../VscodeTextEditor";

@@ -1,5 +1,5 @@
 import vscode from "vscode";
-import type { HatColor } from "../hatStyles.types";
+import type { HatColor } from "@cursorless/lib-common";
 
 interface OldDecorationColorSetting {
   dark: string;

@@ -2,7 +2,7 @@ import type {
   HatColor,
   HatShape,
   VscodeHatStyleName,
-} from "../hatStyles.types";
+} from "@cursorless/lib-common";
 
 export function getStyleName(
   color: HatColor,

@@ -1,9 +1,11 @@
 import vscode from "vscode";
-import type { Messages } from "@cursorless/lib-common";
+import type {
+  IndividualHatAdjustmentMap,
+  Messages,
+} from "@cursorless/lib-common";
 import { showInfo } from "@cursorless/lib-common";
 import type { VscodeApi } from "@cursorless/lib-vscode-common";
 import type { ExtendedHatStyleMap } from "../VscodeEnabledHatStyleManager";
-import type { IndividualHatAdjustmentMap } from "./shapeAdjustments";
 
 /**
  * We set this key in global state the first time they user gets the new shapes from #1868. We use this to

@@ -1,12 +1,13 @@
 import { isString } from "lodash-es";
 import vscode from "vscode";
 import type {
+  HatColor,
+  HatShape,
   Modifier,
   PartialMark,
   SurroundingPairName,
 } from "@cursorless/lib-common";
 import { surroundingPairsDelimiters } from "@cursorless/lib-engine";
-import type { HatColor, HatShape } from "../ide/vscode/hatStyles.types";
 import type {
   SimpleKeyboardActionDescriptor,
   SpecificKeyboardActionDescriptor,

@@ -1,6 +1,8 @@
 import vscode from "vscode";
 import type {
   ActionDescriptor,
+  HatColor,
+  HatShape,
   Modifier,
   PartialMark,
   PartialPrimitiveTargetDescriptor,
@@ -10,7 +12,6 @@ import type {
 import { LATEST_VERSION } from "@cursorless/lib-common";
 import { runCursorlessCommand } from "@cursorless/lib-vscode-common";
 import { getStyleName } from "../ide/vscode/hats/getStyleName";
-import type { HatColor, HatShape } from "../ide/vscode/hatStyles.types";
 import type { SimpleKeyboardActionDescriptor } from "./KeyboardActionType";
 import type { KeyboardCommandsModal } from "./KeyboardCommandsModal";
 import type { KeyboardHandler } from "./KeyboardHandler";

@@ -1,8 +1,9 @@
 import type {
+  HatColor,
+  HatShape,
   SimpleScopeTypeType,
   SurroundingPairName,
 } from "@cursorless/lib-common";
-import type { HatColor, HatShape } from "../ide/vscode/hatStyles.types";
 import type {
   PolymorphicKeyboardActionDescriptor,
   SimpleKeyboardActionDescriptor,

@@ -5,9 +5,8 @@ import { sum } from "lodash-es";
 import type {
   HatAdjustments,
   IndividualHatAdjustmentMap,
-} from "../../ide/vscode/hats/shapeAdjustments";
-import { defaultShapeAdjustments } from "../../ide/vscode/hats/shapeAdjustments";
-import { HAT_SHAPES } from "../../ide/vscode/hatStyles.types";
+} from "@cursorless/lib-common";
+import { defaultShapeAdjustments, HAT_SHAPES } from "@cursorless/lib-common";
 import { postProcessValue } from "./lib";
 
 /**

@@ -4,9 +4,8 @@
 import type {
   HatAdjustments,
   IndividualHatAdjustmentMap,
-} from "../../ide/vscode/hats/shapeAdjustments";
-import { defaultShapeAdjustments } from "../../ide/vscode/hats/shapeAdjustments";
-import { HAT_SHAPES } from "../../ide/vscode/hatStyles.types";
+} from "@cursorless/lib-common";
+import { defaultShapeAdjustments, HAT_SHAPES } from "@cursorless/lib-common";
 import { postProcessValue } from "./lib";
 
 /**

@@ -0,0 +1,98 @@
+# @cursorless/command-visualizer
+
+Turn recorded cursorless test fixtures into **animated SVG visualizations** of
+commands — before/during/after cascades with real hat allocation, flash
+sequencing, selections, and a command "jumbotron". The output is a
+self-contained SVG string embeddable anywhere a plain `<img>` works (GitHub
+READMEs via camo, docs pages, tutorials).
+
+The renderer is a pure function: fixture YAML in → self-contained SVG string
+out. There is zero runtime JavaScript in the output, no DOM or browser
+dependency to render, and every animation rides one CSS `--dur` timeline, so
+outputs are deterministic and testable by seeking.
+
+```ts
+import { renderCommand } from "@cursorless/command-visualizer";
+
+const svg = renderCommand(fixtureYamlText, "recorded/foo/bar.yml", {
+  theme: "dark",
+});
+```
+
+## The animation model
+
+```
+pre (bumper) → [ step.initial → step.during → step.final ]* → post (reset)
+```
+
+- **The during phase is the execution beat:** the command pill activates, its
+  step dot gains the issued ring, and flashes initiate — all in the same
+  instant. Flash-less commands (pure selections) show their final state in this
+  beat, matching the editor's instantaneous selection.
+- **Chains are contract-checked:** `finalState.i` must equal
+  `initialState.{i+1}`, and the boundary renders as ONE merged frame already
+  wearing the next step's hats — one animated change, exactly as in the editor.
+- **Durations are parameters** (`initial` / `during` / `bumper` ms, plus a float
+  `scale`); defaults are `[2000, 1000, 500]`.
+- Fixtures with no recorded `ide.flashes` (e.g. the tutorial corpus) get flashes
+  **derived from the edit diff**; recorded flashes are used verbatim when
+  present.
+
+Flash classes follow the action source exactly: pre-edit flashes
+(`pendingDelete`, `referenced`, `pendingModification0`/`1`) precede the edit and
+`justAdded` follows it. The 100ms `pendingEditDecorationTime` pulse is pinned
+N-invariantly (independent of the number of frames). Pre-edit flashes render
+sequenced (reference → delete) rather than in parallel — a deliberate
+readability divergence from the editor.
+
+## Architecture
+
+Source is organized into four scopes with a strict one-directional dependency
+rule (`render/` and `logic/` never import each other). The layering diagram, the
+4-stage pipeline table, and the grep commands that verify the dependency rule
+live in [`src/ARCHITECTURE.md`](./src/ARCHITECTURE.md).
+
+## Reuse of cursorless source
+
+This package deliberately imports from cursorless packages rather than cloning,
+and documents the cases where a local copy is the faithful choice.
+
+Imported from cursorless (not cloned):
+
+- `DefaultMap` / `CompositeKeyMap`, `FlashStyle` — from `@cursorless/lib-common`.
+- `GRAPHEME_SPLIT_REGEX`, `maxByFirstDiffering`, the `allocateHats` primitives —
+  from `@cursorless/lib-engine`.
+- Fixture YAML is parsed with `js-yaml` (the same library `@cursorless/lib-node-common`'s
+  `loadFixture.ts` uses).
+
+Kept local, with provenance, where importing would regress or balloon scope:
+
+- **`data/decorations.ts`** — `FlashStyle` is a string union derived from
+  lib-common's `FlashStyle` enum; it composes with `HighlightStyle` into the
+  `OverlayStyleName` keys. The `DECORATION_HEX` values, pulse timing, and
+  precedence are local (cursorless does not export them). Note: this package's
+  `OverlayStyleName` is unrelated to lib-common's `DecorationStyle` (a
+  border-geometry interface) — the rename avoids that collision.
+- **`data/colors.ts` / `data/shapes.ts`** — the color hexes live in
+  `app-vscode/package.json` as VS Code setting defaults (read at runtime, never a
+  TS constant) and the shape SVG `d=` path strings live in
+  `resources/images/hats/*.svg` (read at runtime by `VscodeHatRenderer`). There
+  is no importable TS module, so these are mirrored here with provenance comments
+  naming the exact upstream source.
+- **`logic/fixture-root.ts`** — keeps its dual directory-layout probe and
+  `$CURSORLESS_REPO` override; lib-node-common's `getFixturesPath` hardcodes one
+  layout and throws unless `CURSORLESS_REPO_ROOT` is set.
+- **`logic/fixture-extract.ts`** — `parseMarks` / `buildLines` read plain YAML
+  with no editor, whereas lib-common's `serializedMarksToTokenHats` needs a live
+  `TextEditor` and returns engine `TokenHat[]`.
+
+## Development
+
+```sh
+# typecheck
+tsc -p packages/command-visualizer/tsconfig.json --noEmit
+```
+
+The renderer resolves recorded fixtures from a cursorless checkout. Set
+`CURSORLESS_REPO` to point at your checkout if it is not at
+`$HOME/code/cursorless`.