Capture hat map in recorded tests. Render in docs.

packages/app-vscode/src/constructTestHelpers.ts

@@ -6,6 +6,7 @@ import type {
   HatTokenMap,
   IDE,
   NormalizedIDE,
+  ReadOnlyHatMap,
   ScopeProvider,
   SerializedMarks,
   StoredTargetKey,
@@ -64,6 +65,7 @@ export function constructTestHelpers(
       editor: TextEditor,
       ide: IDE,
       marks: SerializedMarks | undefined,
+      hatTokenMap: ReadOnlyHatMap | undefined,
     ): Promise<TestCaseSnapshot> {
       return takeSnapshot(
         storedTargets,
@@ -72,6 +74,7 @@ export function constructTestHelpers(
         editor,
         ide,
         marks,
+        hatTokenMap,
         undefined,
         undefined,
       );

packages/app-web-docs/src/docs/components/Code.css

@@ -125,15 +125,57 @@
   position: relative;
 }
 
-.code-hat-default::before {
+.code-hat::before {
   content: "";
   position: absolute;
   top: 0.15em;
   left: 50%;
   width: 0.3em;
   height: 0.3em;
   border-radius: 50%;
-  background-color: #b9b6cd;
   transform: translate(-50%, -100%);
   pointer-events: none;
 }
+
+.code-hat-default::before {
+  background-color: #b9b6cd;
+}
+
+.code-hat-blue::before {
+  background-color: #089ad3;
+}
+
+.code-hat-green::before {
+  background-color: #36b33f;
+}
+
+.code-hat-red::before {
+  background-color: #e02d28;
+}
+
+.code-hat-pink::before {
+  background-color: #e06caa;
+}
+
+.code-hat-yellow::before {
+  background-color: #e5c02c;
+}
+
+/* Code hat referenced */
+
+.code-hat-referenced::before {
+  animation: code-hat-referenced-pulse 2s ease-in-out infinite;
+}
+
+@keyframes code-hat-referenced-pulse {
+  50% {
+    background-color: var(--code-hat-referenced-color);
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .code-hat-referenced::before {
+    background-color: var(--code-hat-referenced-color);
+    animation: none;
+  }
+}

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

@@ -3,12 +3,16 @@ import type { Dispatch, JSX, ReactNode, SetStateAction } from "react";
 import { createContext, useContext, useMemo, useState } from "react";
 import type { DecorationItem } from "shiki";
 import type {
-  SelectionPlainObject,
-  SerializedMarks,
+  Position,
+  Selection,
   TestCaseSnapshot,
 } from "@cursorless/lib-common";
-import { plainObjectToSelection, splitKey } from "@cursorless/lib-common";
+import {
+  plainObjectToRange,
+  plainObjectToSelection,
+} from "@cursorless/lib-common";
 import { Code } from "./Code";
+import { highlightColors } from "./highlightColors";
 import type { RecordedTest } from "./types";
 
 interface RecordedTestVisualizerContextValue {
@@ -98,12 +102,17 @@ export function RecordedTestVisualizer({
     url: `https://github.com/cursorless-dev/cursorless/blob/main/resources/fixtures/recorded/docs/${path}`,
   };
 
+  const renderHats =
+    fixture.initialState.marks != null &&
+    Object.keys(fixture.initialState.marks).length > 0;
+
   return (
     <div className="row">
       <div className="col">
         Input
         <CodeState
           renderWhitespace={renderWhitespace}
+          renderHats={renderHats}
           languageId={languageId}
           link={link}
           state={initialState}
@@ -113,6 +122,7 @@ export function RecordedTestVisualizer({
         Output
         <CodeState
           renderWhitespace={renderWhitespace}
+          renderHats={renderHats}
           languageId={languageId}
           link={link}
           state={finalState}
@@ -124,6 +134,7 @@ export function RecordedTestVisualizer({
 
 interface CodeStateProps {
   renderWhitespace: boolean;
+  renderHats: boolean;
   languageId: string;
   link: {
     name: string;
@@ -134,16 +145,14 @@ interface CodeStateProps {
 
 function CodeState({
   renderWhitespace,
+  renderHats,
   languageId,
   link,
   state,
 }: CodeStateProps): JSX.Element {
   const decorations = useMemo(
-    () => [
-      ...state.selections.map(toDecoration),
-      ...toMarkDecorations(state.marks, state.documentContents),
-    ],
-    [state.selections, state.marks, state.documentContents],
+    () => toDecorations(state, renderHats),
+    [state, renderHats],
   );
   return (
     <>
@@ -166,9 +175,7 @@ function CodeState({
   );
 }
 
-function toDecoration(plainSelection: SelectionPlainObject): DecorationItem {
-  const selection = plainObjectToSelection(plainSelection);
-
+function toDecoration(selection: Selection): DecorationItem {
   const cursorClassName = selection.isReversed
     ? "code-cursor-before"
     : "code-cursor-after";
@@ -187,50 +194,81 @@ 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,
+function toDecorations(
+  state: TestCaseSnapshot,
+  renderHats: boolean,
+): DecorationItem[] {
+  const selections = state.selections.map(plainObjectToSelection);
+  const hatRanges = renderHats
+    ? (state.hatTokenMap ?? []).map(({ hatRange }) =>
+        plainObjectToRange(hatRange),
+      )
+    : [];
+
+  // Shiki rejects intersecting decorations. A zero-width cursor at the end of
+  // a hat range intersects the hat decoration, so render both on one wrapper.
+  // We only merge at the end because code-cursor-after recreates that exact
+  // boundary without competing with the hat's ::before pseudo-element.
+  const mergedCursorPositions = selections
+    .filter(
+      (selection) =>
+        selection.isEmpty &&
+        hatRanges.some(({ end }) => end.isEqual(selection.active)),
+    )
+    .map(({ active }) => active);
+
+  return [
+    // Omit cursors that the corresponding hat decoration will render instead.
+    ...selections
+      .filter(
+        (selection) =>
+          !selection.isEmpty ||
+          !mergedCursorPositions.some((position) =>
+            position.isEqual(selection.active),
+          ),
+      )
+      .map(toDecoration),
+    ...toHatDecorations(state, renderHats, mergedCursorPositions),
+  ];
+}
+
+function toHatDecorations(
+  state: TestCaseSnapshot,
+  renderHats: boolean,
+  mergedCursorPositions: readonly Position[],
 ): DecorationItem[] {
-  if (marks == null) {
+  if (!renderHats || state.hatTokenMap == null) {
     return [];
   }
 
-  const lines = documentContents.split(/\r?\n/u);
+  const markRanges = Object.values(state.marks ?? {}).map(plainObjectToRange);
 
-  return Object.entries(marks).map(([key, range]) => {
-    if (range.start.line !== range.end.line) {
-      throw new Error(`Mark ${key} spans multiple lines`);
-    }
+  return state.hatTokenMap.map(({ hatStyle, hatRange }) => {
+    const range = plainObjectToRange(hatRange);
+    const properties: DecorationItem["properties"] = {
+      className: ["code-hat", `code-hat-${hatStyle}`],
+    };
 
-    const line = lines[range.start.line];
+    const isReferenced = markRanges.some((markRange) =>
+      markRange.contains(range),
+    );
 
-    if (line == null) {
-      throw new Error(`Mark ${key} is outside the document`);
+    if (isReferenced) {
+      properties.className?.push("code-hat-referenced");
+      properties.style = `--code-hat-referenced-color: ${highlightColors.content.background};`;
     }
 
-    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`);
+    if (mergedCursorPositions.some((position) => position.isEqual(range.end))) {
+      // The hat uses ::before and the cursor uses ::after, allowing both
+      // visuals to share this wrapper without overlapping Shiki decorations.
+      properties.className?.push("code-cursor-after");
     }
 
     return {
-      start: { line: range.start.line, character: characterStart },
-      end: {
-        line: range.start.line,
-        character: characterStart + character.length,
-      },
+      start: hatRange.start,
+      end: hatRange.end,
       alwaysWrap: true,
-      properties: {
-        className: ["code-hat", `code-hat-${hatStyle}`],
-      },
+      properties,
     };
   });
 }

packages/lib-common/src/testUtil/TestCaseSnapshot.ts

@@ -3,6 +3,7 @@ import type {
   RangePlainObject,
   SelectionPlainObject,
   SerializedMarks,
+  SimpleTokenHat,
   TargetPlainObject,
 } from "../util/toPlainObject";
 
@@ -18,6 +19,7 @@ export interface TestCaseSnapshot extends MarkKeys {
   // https://github.com/cursorless-dev/cursorless/issues/160
   visibleRanges?: RangePlainObject[];
   marks?: SerializedMarks;
+  hatTokenMap?: SimpleTokenHat[];
   timeOffsetSeconds?: number;
 
   /**

packages/lib-common/src/testUtil/getSnapshotForComparison.ts

@@ -14,7 +14,8 @@ import type {
  *
  * @param finalState The final state of the test case; we only use this to
  * decide which fields we care about
- * @param readableHatMap The hat map for extractin the marks
+ * @param initialHatTokenMap The hat map for extractin the marks
+ * @param getFinalHatTokenMap Gets the hat map after the command has run
  * @param spyIde The spy IDE
  * @param takeSnapshot A function that takes a snapshot of the current state of
  * the editor
@@ -23,8 +24,9 @@ import type {
  */
 export async function getSnapshotForComparison(
   finalState: TestCaseSnapshot | undefined,
-  readableHatMap: ReadOnlyHatMap,
+  initialHatTokenMap: ReadOnlyHatMap,
   spyIde: SpyIDE,
+  getFinalHatTokenMap: () => Promise<ReadOnlyHatMap>,
   takeSnapshot: TestHelpers["takeSnapshot"],
 ): Promise<Exclude<TestCaseSnapshot, "visibleRanges">> {
   const excludeFields: ExcludableSnapshotField[] = [];
@@ -33,9 +35,15 @@ export async function getSnapshotForComparison(
     finalState?.marks == null
       ? undefined
       : marksToPlainObject(
-          extractTargetedMarks(Object.keys(finalState.marks), readableHatMap),
+          extractTargetedMarks(
+            Object.keys(finalState.marks),
+            initialHatTokenMap,
+          ),
         );
 
+  const finalHatTokenMap =
+    finalState?.hatTokenMap == null ? undefined : await getFinalHatTokenMap();
+
   if (finalState?.clipboard == null) {
     excludeFields.push("clipboard");
   }
@@ -61,6 +69,7 @@ export async function getSnapshotForComparison(
     editor,
     spyIde,
     marks,
+    finalHatTokenMap,
   );
 
   return resultState;

packages/lib-common/src/types/HatTokenMap.ts

@@ -1,5 +1,6 @@
 import type { HatStyleName } from "../ide/types/hatStyles.types";
 import type { Range } from "./Range";
+import type { TextEditor } from "./TextEditor";
 import type { Token } from "./Token";
 
 /**
@@ -18,6 +19,7 @@ export interface TokenHat {
 }
 
 export interface ReadOnlyHatMap {
+  getTokenHats(editor: TextEditor): readonly Readonly<TokenHat>[];
   getEntries(): readonly [string, Token][];
   getToken(hatStyle: HatStyleName, character: string): Token | undefined;
 }

packages/lib-common/src/types/TestHelpers.ts

@@ -6,7 +6,7 @@ import type {
   TestCaseSnapshot,
 } from "../testUtil/TestCaseSnapshot";
 import type { SerializedMarks, TargetPlainObject } from "../util/toPlainObject";
-import type { HatTokenMap } from "./HatTokenMap";
+import type { HatTokenMap, ReadOnlyHatMap } from "./HatTokenMap";
 import type { TextEditor } from "./TextEditor";
 
 export interface TestHelpers {
@@ -20,6 +20,7 @@ export interface TestHelpers {
     editor: TextEditor,
     ide: IDE,
     marks: SerializedMarks | undefined,
+    hatTokenMap: ReadOnlyHatMap | undefined,
   ): Promise<TestCaseSnapshot>;
 
   setStoredTarget(