Visualize scope tests in docs (#3016)

![image](https://github.com/user-attachments/assets/5e258b8e-2959-4843-865b-d585e170fc15)

Author: AndreasArvidsson

changelog/2025-07-scopeDocumentation.md

@@ -0,0 +1,6 @@
+---
+tags: [documentation]
+pullRequest: 3016
+---
+
+- Visualize scope tests in docs. Visualizes scope fixtures on [cursorless.org/docs/user/languages](https://www.cursorless.org/docs/user/languages).

package.json

@@ -51,6 +51,7 @@
   },
   "pnpm": {
     "patchedDependencies": {
+      "@shikijs/core": "patches/@shikijs__core.patch",
       "@types/[email protected]": "patches/@[email protected]",
       "[email protected]": "patches/[email protected]"
     }

packages/common/package.json

@@ -25,13 +25,16 @@
     "watch": "pnpm run --filter @cursorless/common --parallel '/^watch:.*/'"
   },
   "dependencies": {
+    "itertools": "2.4.1",
     "lodash-es": "4.17.21",
+    "tinycolor2": "1.6.0",
     "vscode-uri": "3.1.0"
   },
   "devDependencies": {
     "@types/js-yaml": "4.0.9",
     "@types/lodash-es": "4.17.12",
     "@types/mocha": "10.0.10",
+    "@types/tinycolor2": "1.4.6",
     "cross-spawn": "7.0.6",
     "fast-check": "4.1.1",
     "js-yaml": "4.1.0",

packages/common/src/cursorlessCommandIds.ts

@@ -54,6 +54,7 @@ export const cursorlessCommandIds = [
   "cursorless.toggleDecorations",
   "cursorless.showScopeVisualizer",
   "cursorless.hideScopeVisualizer",
+  "cursorless.scopeVisualizer.openUrl",
   "cursorless.tutorial.start",
   "cursorless.tutorial.next",
   "cursorless.tutorial.previous",
@@ -100,6 +101,7 @@ export const cursorlessCommandDescriptions: Record<
   ["cursorless.hideScopeVisualizer"]: new VisibleCommand(
     "Hide the scope visualizer",
   ),
+  ["cursorless.scopeVisualizer.openUrl"]: new VisibleCommand("Open in browser"),
   ["cursorless.analyzeCommandHistory"]: new VisibleCommand(
     "Analyze collected command history",
   ),

packages/common/src/index.ts

@@ -34,6 +34,10 @@ export * from "./scopeSupportFacets/languageScopeSupport";
 export * from "./scopeSupportFacets/PlaintextScopeSupportFacetInfos";
 export * from "./scopeSupportFacets/scopeSupportFacetInfos";
 export * from "./scopeSupportFacets/scopeSupportFacets.types";
+export * from "./scopeVisualizerUtil/decorationStyle.types";
+export * from "./scopeVisualizerUtil/decorationUtil";
+export * from "./scopeVisualizerUtil/generateDecorationsForCharacterRange";
+export * from "./scopeVisualizerUtil/generateDecorationsForLineRange";
 export * from "./StoredTargetKey";
 export * from "./testUtil/asyncSafety";
 export * from "./testUtil/extractTargetedMarks";
@@ -93,6 +97,7 @@ export * from "./types/Token";
 export * from "./types/TreeSitter";
 export * from "./types/tutorial.types";
 export * from "./util";
+export * from "./util/blendColors";
 export * from "./util/clientSupportsFallback";
 export * from "./util/CompositeKeyDefaultMap";
 export * from "./util/CompositeKeyMap";
@@ -105,7 +110,6 @@ export * from "./util/Notifier";
 export * from "./util/object";
 export * from "./util/omitByDeep";
 export * from "./util/prettifyLanguageName";
-export * from "./util/range";
 export * from "./util/regex";
 export * from "./util/selectionsEqual";
 export * from "./util/serializedMarksToTokenHats";

packages/common/src/scopeVisualizerUtil/decorationStyle.types.ts

@@ -0,0 +1,20 @@
+import type { Range } from "../types/Range";
+
+export interface StyledRange {
+  style: DecorationStyle;
+  range: Range;
+}
+
+export interface DecorationStyle {
+  top: BorderStyle;
+  bottom: BorderStyle;
+  left: BorderStyle;
+  right: BorderStyle;
+  isWholeLine?: boolean;
+}
+
+export enum BorderStyle {
+  porous = "dashed",
+  solid = "solid",
+  none = "none",
+}

packages/common/src/scopeVisualizerUtil/decorationUtil.ts

@@ -0,0 +1,48 @@
+import { BorderStyle } from "./decorationStyle.types";
+import type { DecorationStyle } from "./decorationStyle.types";
+
+export const BORDER_WIDTH = "1px";
+export const BORDER_RADIUS = "2px";
+
+export function getBorderStyle(borders: DecorationStyle): string {
+  return [borders.top, borders.right, borders.bottom, borders.left].join(" ");
+}
+
+export function getBorderColor(
+  solidColor: string,
+  porousColor: string,
+  borders: DecorationStyle,
+): string {
+  return [
+    borders.top === BorderStyle.solid ? solidColor : porousColor,
+    borders.right === BorderStyle.solid ? solidColor : porousColor,
+    borders.bottom === BorderStyle.solid ? solidColor : porousColor,
+    borders.left === BorderStyle.solid ? solidColor : porousColor,
+  ].join(" ");
+}
+
+export function getBorderRadius(borders: DecorationStyle): string {
+  return [
+    getSingleCornerBorderRadius(borders.top, borders.left),
+    getSingleCornerBorderRadius(borders.top, borders.right),
+    getSingleCornerBorderRadius(borders.bottom, borders.right),
+    getSingleCornerBorderRadius(borders.bottom, borders.left),
+  ].join(" ");
+}
+
+export function useSingleCornerBorderRadius(
+  side1: BorderStyle,
+  side2: BorderStyle,
+): boolean {
+  // We only round the corners if both sides are solid, as that makes them look
+  // more finished, whereas we want the dotted borders to look unfinished / cut
+  // off.
+  return side1 === BorderStyle.solid && side2 === BorderStyle.solid;
+}
+
+export function getSingleCornerBorderRadius(
+  side1: BorderStyle,
+  side2: BorderStyle,
+) {
+  return useSingleCornerBorderRadius(side1, side2) ? BORDER_RADIUS : "0px";
+}

packages/cursorless-vscode/src/ide/vscode/VSCodeScopeVisualizer/VscodeFancyRangeHighlighter/generateDecorationsForCharacterRange/generateDecorationsForCharacterRange.ts renamed to packages/common/src/scopeVisualizerUtil/generateDecorationsForCharacterRange/generateDecorationsForCharacterRange.ts

@@ -1,5 +1,4 @@
-import type { Range, TextEditor } from "@cursorless/common";
-import { getLineRanges } from "@cursorless/common";
+import type { Range } from "../../types/Range";
 import type { StyledRange } from "../decorationStyle.types";
 import { BorderStyle } from "../decorationStyle.types";
 import { handleMultipleLines } from "./handleMultipleLines";
@@ -10,7 +9,7 @@ import { handleMultipleLines } from "./handleMultipleLines";
  * that the range is visually distinct from adjacent ranges but looks continuous.
  */
 export function* generateDecorationsForCharacterRange(
-  editor: TextEditor,
+  getLineRanges: (range: Range) => Range[],
   range: Range,
 ): Iterable<StyledRange> {
   if (range.isSingleLine) {
@@ -26,5 +25,15 @@ export function* generateDecorationsForCharacterRange(
     return;
   }
 
-  yield* handleMultipleLines(getLineRanges(editor, range));
+  // A list of ranges, one for each line in the given range, with the first and
+  // last ranges trimmed to the start and end of the given range.
+  const lineRanges = getLineRanges(range);
+
+  lineRanges[0] = lineRanges[0].with(range.start);
+  lineRanges[lineRanges.length - 1] = lineRanges[lineRanges.length - 1].with(
+    undefined,
+    range.end,
+  );
+
+  yield* handleMultipleLines(lineRanges);
 }

packages/cursorless-vscode/src/ide/vscode/VSCodeScopeVisualizer/VscodeFancyRangeHighlighter/generateDecorationsForCharacterRange/generateLineInfos.ts renamed to packages/common/src/scopeVisualizerUtil/generateDecorationsForCharacterRange/generateLineInfos.ts

@@ -1,4 +1,4 @@
-import type { Range } from "@cursorless/common";
+import type { Range } from "../..";
 
 /**
  * Generates a line info for each line in the given range, which includes

packages/cursorless-vscode/src/ide/vscode/VSCodeScopeVisualizer/VscodeFancyRangeHighlighter/generateDecorationsForCharacterRange/handleMultipleLines.test.ts renamed to packages/common/src/scopeVisualizerUtil/generateDecorationsForCharacterRange/handleMultipleLines.test.ts

@@ -1,8 +1,8 @@
 import assert from "assert";
+import { map } from "itertools";
+import { Range } from "../..";
 import { BorderStyle } from "../decorationStyle.types";
 import { handleMultipleLines } from "./handleMultipleLines";
-import { Range } from "@cursorless/common";
-import { map } from "itertools";
 
 const solid = BorderStyle.solid;
 const porous = BorderStyle.porous;