Visualize actions on the documentation page

CHANGELOG.md

@@ -2,6 +2,7 @@
 
 ## 2026
 
+- 2026-09-02: Visualize actions on the documentation page. ([#3330](https://github.com/cursorless-dev/cursorless/pull/3330))
 - 2026-09-01: Visualize modifiers on the documentation page. ([#3328](https://github.com/cursorless-dev/cursorless/pull/3328); [#3329](https://github.com/cursorless-dev/cursorless/pull/3329))
 - 2026-08-30: Overhauled the user documentation with generated and grouped action, modifier, and scope reference pages, richer descriptions and examples, dedicated paired-delimiter and target guides, and a streamlined landing page. ([#3303](https://github.com/cursorless-dev/cursorless/pull/3303); [#3304](https://github.com/cursorless-dev/cursorless/pull/3304); [#3305](https://github.com/cursorless-dev/cursorless/pull/3305); [#3306](https://github.com/cursorless-dev/cursorless/pull/3306); [#3307](https://github.com/cursorless-dev/cursorless/pull/3307); [#3308](https://github.com/cursorless-dev/cursorless/pull/3308); [#3309](https://github.com/cursorless-dev/cursorless/pull/3309); [#3310](https://github.com/cursorless-dev/cursorless/pull/3310); [#3311](https://github.com/cursorless-dev/cursorless/pull/3311); [#3312](https://github.com/cursorless-dev/cursorless/pull/3312); [#3313](https://github.com/cursorless-dev/cursorless/pull/3313); [#3314](https://github.com/cursorless-dev/cursorless/pull/3314); [#3315](https://github.com/cursorless-dev/cursorless/pull/3315); [#3316](https://github.com/cursorless-dev/cursorless/pull/3316))
 - 2026-05-03: Add support for if and for statements in Talon-script. [`#3274`](https://github.com/cursorless-dev/cursorless/pull/3274)

packages/app-web-docs/src/docs/components/RecordedTestVisualizer.tsx

@@ -141,19 +141,27 @@ function CodeState({
   const decorations = useMemo(
     () => [
       ...state.selections.map(toDecoration),
-      ...toMarkDecorations(state.marks),
+      ...toMarkDecorations(state.marks, state.documentContents),
     ],
-    [state.selections, state.marks],
+    [state.selections, state.marks, state.documentContents],
   );
   return (
-    <Code
-      link={link}
-      languageId={languageId}
-      renderWhitespace={renderWhitespace}
-      decorations={decorations}
-    >
-      {state.documentContents}
-    </Code>
+    <>
+      <Code
+        link={link}
+        languageId={languageId}
+        renderWhitespace={renderWhitespace}
+        decorations={decorations}
+      >
+        {state.documentContents}
+      </Code>
+      {state.clipboard != null && (
+        <div className="mt-2">
+          <strong>Clipboard:</strong>
+          &nbsp;<i>&quot;{state.clipboard}&quot;</i>
+        </div>
+      )}
+    </>
   );
 }
 
@@ -178,19 +186,46 @@ function toDecoration(plainSelection: SelectionPlainObject): DecorationItem {
   };
 }
 
+/**
+ * Converts serialized token marks to Shiki decorations around the first
+ * occurrence of each mark's decorated character within its token.
+ */
 function toMarkDecorations(
   marks: SerializedMarks | undefined,
+  documentContents: string,
 ): DecorationItem[] {
   if (marks == null) {
     return [];
   }
 
+  const lines = documentContents.split(/\r?\n/u);
+
   return Object.entries(marks).map(([key, range]) => {
-    const { hatStyle } = splitKey(key);
+    if (range.start.line !== range.end.line) {
+      throw new Error(`Mark ${key} spans multiple lines`);
+    }
+
+    const line = lines[range.start.line];
+
+    if (line == null) {
+      throw new Error(`Mark ${key} is outside the document`);
+    }
+
+    const { hatStyle, character } = splitKey(key);
+    const tokenText = line.slice(range.start.character, range.end.character);
+    const characterOffset = tokenText.indexOf(character);
+    const characterStart = range.start.character + characterOffset;
+
+    if (characterOffset === -1) {
+      throw new Error(`Mark ${key} does not occur in its token`);
+    }
 
     return {
-      start: range.start,
-      end: range.end,
+      start: { line: range.start.line, character: characterStart },
+      end: {
+        line: range.start.line,
+        character: characterStart + character.length,
+      },
       alwaysWrap: true,
       properties: {
         className: ["code-hat", `code-hat-${hatStyle}`],

packages/app-web-docs/src/docs/user/actions/addSelection.mdx

@@ -2,6 +2,8 @@
 sidebar_label: Append
 ---
 
+import { RecordedTestVisualizer, RecordedTestVisualizerOptions, RecordedTestVisualizerProvider } from "@site/src/docs/components/RecordedTestVisualizer";
+
 # Append (Add selection)
 
 Cursorless ID: `addSelection`
@@ -17,3 +19,15 @@ Default: `append`
 ## Examples
 
 - `"append blue air"` - Adds the token containing letter `a` with a blue hat to the current selections.
+
+## Visualization
+
+<RecordedTestVisualizerProvider>
+
+<RecordedTestVisualizerOptions />
+
+### `"append air"`
+
+<RecordedTestVisualizer fixtureName="docs/actions/addSelection" />
+
+</RecordedTestVisualizerProvider>

packages/app-web-docs/src/docs/user/actions/addSelectionAfter.mdx

@@ -2,6 +2,8 @@
 sidebar_label: Append post
 ---
 
+import { RecordedTestVisualizer, RecordedTestVisualizerOptions, RecordedTestVisualizerProvider } from "@site/src/docs/components/RecordedTestVisualizer";
+
 # Append post (Add selection after)
 
 Cursorless ID: `addSelectionAfter`
@@ -17,3 +19,15 @@ Default: `append post`
 ## Examples
 
 - `"append post blue air"` - Adds an empty selection after the token containing letter `a` with a blue hat.
+
+## Visualization
+
+<RecordedTestVisualizerProvider>
+
+<RecordedTestVisualizerOptions />
+
+### `"append post air"`
+
+<RecordedTestVisualizer fixtureName="docs/actions/addSelectionAfter" />
+
+</RecordedTestVisualizerProvider>

packages/app-web-docs/src/docs/user/actions/addSelectionBefore.mdx

@@ -2,6 +2,8 @@
 sidebar_label: Append pre
 ---
 
+import { RecordedTestVisualizer, RecordedTestVisualizerOptions, RecordedTestVisualizerProvider } from "@site/src/docs/components/RecordedTestVisualizer";
+
 # Append pre (Add selection before)
 
 Cursorless ID: `addSelectionBefore`
@@ -17,3 +19,15 @@ Default: `append pre`
 ## Examples
 
 - `"append pre blue air"` - Adds an empty selection before the token containing letter `a` with a blue hat.
+
+## Visualization
+
+<RecordedTestVisualizerProvider>
+
+<RecordedTestVisualizerOptions />
+
+### `"append pre air"`
+
+<RecordedTestVisualizer fixtureName="docs/actions/addSelectionBefore" />
+
+</RecordedTestVisualizerProvider>

packages/app-web-docs/src/docs/user/actions/applyFormatter.mdx

@@ -2,6 +2,8 @@
 sidebar_label: Format
 ---
 
+import { RecordedTestVisualizer, RecordedTestVisualizerOptions, RecordedTestVisualizerProvider } from "@site/src/docs/components/RecordedTestVisualizer";
+
 # Format (Apply formatter)
 
 Cursorless ID: `applyFormatter`
@@ -17,3 +19,23 @@ Default: `format`
 ## Examples
 
 - `"format camel at blue air"` - Reformats the token containing letter `a` with a blue hat as camel case.
+
+## Visualization
+
+<RecordedTestVisualizerProvider>
+
+<RecordedTestVisualizerOptions />
+
+### `"format camel at bat"`
+
+<RecordedTestVisualizer fixtureName="docs/actions/applyFormatter" />
+
+### `"format snake at bat"`
+
+<RecordedTestVisualizer fixtureName="docs/actions/applyFormatter2" />
+
+### `"format camel at line"`
+
+<RecordedTestVisualizer fixtureName="docs/actions/applyFormatter3" />
+
+</RecordedTestVisualizerProvider>

packages/app-web-docs/src/docs/user/actions/breakLine.mdx

@@ -2,6 +2,8 @@
 sidebar_label: Break
 ---
 
+import { RecordedTestVisualizer, RecordedTestVisualizerOptions, RecordedTestVisualizerProvider } from "@site/src/docs/components/RecordedTestVisualizer";
+
 # Break (Break line)
 
 Cursorless ID: `breakLine`
@@ -17,3 +19,15 @@ Default: `break`
 ## Examples
 
 - `"break blue air"` - Breaks the line before the token containing letter `a` with a blue hat.
+
+## Visualization
+
+<RecordedTestVisualizerProvider>
+
+<RecordedTestVisualizerOptions />
+
+### `"break air"`
+
+<RecordedTestVisualizer fixtureName="docs/actions/breakLine" />
+
+</RecordedTestVisualizerProvider>

packages/app-web-docs/src/docs/user/actions/callAsFunction.mdx

@@ -2,6 +2,8 @@
 sidebar_label: Call
 ---
 
+import { RecordedTestVisualizer, RecordedTestVisualizerOptions, RecordedTestVisualizerProvider } from "@site/src/docs/components/RecordedTestVisualizer";
+
 # Call (Call as function)
 
 Cursorless ID: `callAsFunction`
@@ -19,3 +21,23 @@ Default: `call`
 
 - `"call blue air"` - Inserts a call to the token containing letter `a` with a blue hat at the current selection.
 - `"call blue air on green bat"` - Inserts a call to the token containing letter `a` with a blue hat on the token containing letter `b` with a green hat.
+
+## Visualization
+
+<RecordedTestVisualizerProvider>
+
+<RecordedTestVisualizerOptions />
+
+### `"call air"`
+
+<RecordedTestVisualizer fixtureName="docs/actions/callAsFunction" />
+
+### `"call air"`
+
+<RecordedTestVisualizer fixtureName="docs/actions/callAsFunction2" />
+
+### `"call air on bat"`
+
+<RecordedTestVisualizer fixtureName="docs/actions/callAsFunction3" />
+
+</RecordedTestVisualizerProvider>

packages/app-web-docs/src/docs/user/actions/clearAndSetSelection.mdx

@@ -2,6 +2,8 @@
 sidebar_label: Change
 ---
 
+import { RecordedTestVisualizer, RecordedTestVisualizerOptions, RecordedTestVisualizerProvider } from "@site/src/docs/components/RecordedTestVisualizer";
+
 # Change
 
 Cursorless ID: `clearAndSetSelection`
@@ -18,3 +20,15 @@ Legacy: `clear`
 ## Examples
 
 - `"change blue air"` - Changes the token containing letter `a` with a blue hat by clearing it and leaving the cursor in its place.
+
+## Visualization
+
+<RecordedTestVisualizerProvider>
+
+<RecordedTestVisualizerOptions />
+
+### `"change air"`
+
+<RecordedTestVisualizer fixtureName="docs/actions/clearAndSetSelection" />
+
+</RecordedTestVisualizerProvider>

packages/app-web-docs/src/docs/user/actions/copyToClipboard.mdx

@@ -2,6 +2,8 @@
 sidebar_label: Copy
 ---
 
+import { RecordedTestVisualizer, RecordedTestVisualizerOptions, RecordedTestVisualizerProvider } from "@site/src/docs/components/RecordedTestVisualizer";
+
 # Copy (Copy to clipboard)
 
 Cursorless ID: `copyToClipboard`
@@ -17,3 +19,15 @@ Default: `copy`
 ## Examples
 
 - `"copy blue air"` - Copies the token containing letter `a` with a blue hat to the clipboard.
+
+## Visualization
+
+<RecordedTestVisualizerProvider>
+
+<RecordedTestVisualizerOptions />
+
+### `"copy line"`
+
+<RecordedTestVisualizer fixtureName="docs/actions/copyToClipboard" />
+
+</RecordedTestVisualizerProvider>

packages/app-web-docs/src/docs/user/actions/cutToClipboard.mdx

@@ -2,6 +2,8 @@
 sidebar_label: Carve
 ---
 
+import { RecordedTestVisualizer, RecordedTestVisualizerOptions, RecordedTestVisualizerProvider } from "@site/src/docs/components/RecordedTestVisualizer";
+
 # Carve (Cut to clipboard)
 
 Cursorless ID: `cutToClipboard`
@@ -17,3 +19,15 @@ Default: `carve`
 ## Examples
 
 - `"carve blue air"` - Cuts the token containing letter `a` with a blue hat to the clipboard.
+
+## Visualization
+
+<RecordedTestVisualizerProvider>
+
+<RecordedTestVisualizerOptions />
+
+### `"carve line"`
+
+<RecordedTestVisualizer fixtureName="docs/actions/cutToClipboard" />
+
+</RecordedTestVisualizerProvider>

packages/app-web-docs/src/docs/user/actions/decrement.mdx

@@ -2,6 +2,8 @@
 sidebar_label: Decrement
 ---
 
+import { RecordedTestVisualizer, RecordedTestVisualizerOptions, RecordedTestVisualizerProvider } from "@site/src/docs/components/RecordedTestVisualizer";
+
 # Decrement
 
 Cursorless ID: `decrement`
@@ -17,3 +19,23 @@ Default: `decrement`
 ## Examples
 
 - `"decrement blue five"` - Decrements the number at the token containing number `5` with a blue hat.
+
+## Visualization
+
+<RecordedTestVisualizerProvider>
+
+<RecordedTestVisualizerOptions />
+
+### `"decrement five"`
+
+<RecordedTestVisualizer fixtureName="docs/actions/decrement" />
+
+### `"decrement air"`
+
+<RecordedTestVisualizer fixtureName="docs/actions/decrement2" />
+
+### `"decrement line"`
+
+<RecordedTestVisualizer fixtureName="docs/actions/decrement3" />
+
+</RecordedTestVisualizerProvider>

packages/app-web-docs/src/docs/user/actions/deselect.mdx

@@ -2,6 +2,8 @@
 sidebar_label: Give
 ---
 
+import { RecordedTestVisualizer, RecordedTestVisualizerOptions, RecordedTestVisualizerProvider } from "@site/src/docs/components/RecordedTestVisualizer";
+
 # Give (Deselect)
 
 Cursorless ID: `deselect`
@@ -17,3 +19,15 @@ Default: `give`
 ## Examples
 
 - `"give blue air"` - Removes the token containing letter `a` with a blue hat from the current selections.
+
+## Visualization
+
+<RecordedTestVisualizerProvider>
+
+<RecordedTestVisualizerOptions />
+
+### `"give air"`
+
+<RecordedTestVisualizer fixtureName="docs/actions/deselect" />
+
+</RecordedTestVisualizerProvider>