Visualize scope tests in docs

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 → 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 → 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 → 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;

packages/cursorless-vscode/src/ide/vscode/VSCodeScopeVisualizer/VscodeFancyRangeHighlighter/generateDecorationsForCharacterRange/handleMultipleLines.ts → packages/common/src/scopeVisualizerUtil/generateDecorationsForCharacterRange/handleMultipleLines.ts

@@ -1,7 +1,7 @@
-import { Range } from "@cursorless/common";
+import { flatmap } from "itertools";
+import { Range } from "../..";
 import type { DecorationStyle, StyledRange } from "../decorationStyle.types";
 import { BorderStyle } from "../decorationStyle.types";
-import { flatmap } from "itertools";
 import type { LineInfo } from "./generateLineInfos";
 import { generateLineInfos } from "./generateLineInfos";
 

packages/cursorless-vscode/src/ide/vscode/VSCodeScopeVisualizer/VscodeFancyRangeHighlighter/generateDecorationsForLineRange.ts → packages/common/src/scopeVisualizerUtil/generateDecorationsForLineRange.ts

@@ -1,6 +1,5 @@
-import { Range } from "@cursorless/common";
-import type { StyledRange } from "./decorationStyle.types";
-import { BorderStyle } from "./decorationStyle.types";
+import { Range } from "../types/Range";
+import { BorderStyle, type StyledRange } from "./decorationStyle.types";
 
 export function* generateDecorationsForLineRange(
   startLine: number,

packages/common/src/util/blendColors.ts

@@ -0,0 +1,40 @@
+import tinycolor from "tinycolor2";
+
+/**
+ * Blends two colors together according to their alpha channels, with the top
+ * color rendered on top of the base color.
+ *
+ * Basd on https://gist.github.com/JordanDelcros/518396da1c13f75ee057
+ *
+ * @param base The color to render underneath
+ * @param top The color to render on top
+ * @returns A color that is a blend of the two colors, with the top color
+ * rendered on top of the base color
+ */
+export function blendColors(base: string, top: string): string {
+  const baseRgba = tinycolor(base).toRgb();
+  const topRgba = tinycolor(top).toRgb();
+  const blendedAlpha = 1 - (1 - topRgba.a) * (1 - baseRgba.a);
+
+  function interpolateChannel(channel: "r" | "g" | "b"): number {
+    return Math.round(
+      (topRgba[channel] * topRgba.a) / blendedAlpha +
+        (baseRgba[channel] * baseRgba.a * (1 - topRgba.a)) / blendedAlpha,
+    );
+  }
+
+  return tinycolor({
+    r: interpolateChannel("r"),
+    g: interpolateChannel("g"),
+    b: interpolateChannel("b"),
+    a: blendedAlpha,
+  }).toHex8String();
+}
+
+export function blendMultipleColors(colors: string[]): string {
+  let color = colors[0];
+  for (let i = 1; i < colors.length; i++) {
+    color = blendColors(color, colors[i]);
+  }
+  return color;
+}

packages/cursorless-neovim/src/registerCommands.ts

@@ -98,6 +98,7 @@ export async function registerCommands(
     // Scope visualizer
     ["cursorless.showScopeVisualizer"]: dummyCommandHandler,
     ["cursorless.hideScopeVisualizer"]: dummyCommandHandler,
+    ["cursorless.scopeVisualizer.openUrl"]: dummyCommandHandler,
 
     // Command history
     ["cursorless.analyzeCommandHistory"]: dummyCommandHandler,

packages/cursorless-org-docs/docusaurus.config.mts

@@ -146,7 +146,10 @@ const config: Config = {
       },
     ],
   ],
-  plugins: ["./src/plugins/tailwind-plugin.ts"],
+  plugins: [
+    "./src/plugins/tailwind-plugin.ts",
+    "./src/plugins/scope-tests-plugin.ts",
+  ],
 
   themeConfig: {
     navbar: {

packages/cursorless-org-docs/package.json

@@ -59,9 +59,11 @@
     "prism-react-renderer": "2.4.1",
     "react": "19.1.0",
     "react-dom": "19.1.0",
+    "shiki": "3.7.0",
     "unist-util-visit": "5.0.0"
   },
   "devDependencies": {
+    "@cursorless/node-common": "workspace:*",
     "@docusaurus/module-type-aliases": "3.8.1",
     "@docusaurus/types": "3.8.1",
     "@tailwindcss/postcss": "4.1.10",

packages/cursorless-org-docs/src/css/custom.css

@@ -46,7 +46,3 @@
 .pointer {
   cursor: pointer;
 }
-
-.facet-name {
-  font-weight: 600;
-}

packages/cursorless-org-docs/src/docs/components/Code.css

@@ -0,0 +1,66 @@
+.code-container {
+  position: relative;
+  width: 100%;
+  min-height: 50px;
+  counter-reset: line;
+}
+
+.code-container .shiki {
+  line-height: 1rem;
+}
+
+.code-container .line {
+  position: relative;
+  margin-left: 1.5rem;
+}
+
+.code-container .line::before {
+  content: counter(line);
+  counter-increment: line;
+  position: absolute;
+  left: -40px;
+  padding-left: 0.5em;
+  padding-right: 0.5em;
+  width: 1rem;
+  text-align: right;
+  height: 135%;
+  color: rgba(115, 138, 148, 0.4);
+  border-right: 1px solid rgba(115, 138, 148, 0.4);
+}
+
+.code-ws-symbol {
+  color: #666;
+}
+
+.code-copy-button,
+.code-container > .code-link {
+  display: none;
+  position: absolute;
+  top: 0.5em;
+  background-color: rgb(216, 222, 233);
+  border: none;
+  padding: 4px 8px;
+  border-radius: 4px;
+  cursor: pointer;
+  font-size: 0.75rem;
+  height: 1.75rem;
+}
+
+.code-container:hover .code-copy-button,
+.code-container:hover .code-link {
+  display: block;
+}
+
+.code-copy-button {
+  right: 7.5em;
+}
+
+.code-container > .code-link {
+  right: 0.5em;
+}
+
+.code-container > .code-link:before {
+  display: inline-block;
+  width: 1.25rem;
+  height: 0.75rem;
+}