From 58e28bdf772e0984e076e9816f32410d922baf68 Mon Sep 17 00:00:00 2001
From: Andreas Arvidsson <andreas.arvidsson87@gmail.com>
Date: Sun, 7 Sep 2025 09:05:37 +0200
Subject: [PATCH 1/5] Improved documentation regarding internal scopes

---
 data/scopeSupportFacetInfos.md                |  14 +--
 .../scopeSupportFacetInfos.ts                 |  69 ++++++------
 .../src/docs/components/ScopeVisualizer.tsx   | 104 ++++++++++--------
 3 files changed, 105 insertions(+), 82 deletions(-)

diff --git a/data/scopeSupportFacetInfos.md b/data/scopeSupportFacetInfos.md
index 14bab1773d..8f34e5c631 100644
--- a/data/scopeSupportFacetInfos.md
+++ b/data/scopeSupportFacetInfos.md
@@ -119,7 +119,7 @@
 
 ### disqualifyDelimiter
 
-- `disqualifyDelimiter` Used to disqualify a token from being treated as a surrounding pair delimiter. This will usually be operators containing `>` or `<`, eg `<`, `<=`, `->`, etc
+- `disqualifyDelimiter` Internally used to disqualify a token from being treated as a surrounding pair delimiter. This will usually be operators containing `>` or `<`, eg `<`, `<=`, `->`, etc.
 
 ### document
 
@@ -259,7 +259,7 @@
 
 ### pairDelimiter
 
-- `pairDelimiter` A pair delimiter, eg parentheses, brackets, braces, quotes, etc
+- `pairDelimiter` Internally used to add additional language specific surrounding pair delimiters in addition to the text based definitions. eg `r"`.
 
 ### paragraph
 
@@ -336,11 +336,11 @@
 
 ### textFragment
 
-- `textFragment.comment.block` Text fragment consisting of a block comment
-- `textFragment.comment.line` Text fragment consisting of a line comment
-- `textFragment.element` Text fragment consisting of a xml element interior
-- `textFragment.string.multiLine` Text fragment consisting of a multi-line string
-- `textFragment.string.singleLine` Text fragment consisting of a single-line string
+- `textFragment.comment.block` Internally used text fragment consisting of a block comment.
+- `textFragment.comment.line` Internally used text fragment consisting of a line comment.
+- `textFragment.element` Internally used text fragment consisting of a xml element interior.
+- `textFragment.string.multiLine` Internally used text fragment consisting of a multi-line string.
+- `textFragment.string.singleLine` Internally used text fragment consisting of a single-line string.
 
 ### token
 
diff --git a/packages/common/src/scopeSupportFacets/scopeSupportFacetInfos.ts b/packages/common/src/scopeSupportFacets/scopeSupportFacetInfos.ts
index 827f5c12ed..39c34a6aed 100644
--- a/packages/common/src/scopeSupportFacets/scopeSupportFacetInfos.ts
+++ b/packages/common/src/scopeSupportFacets/scopeSupportFacetInfos.ts
@@ -474,38 +474,6 @@ export const scopeSupportFacetInfos: Record<
     scopeType: "string",
   },
 
-  "textFragment.comment.line": {
-    description: "Text fragment consisting of a line comment",
-    scopeType: "textFragment",
-  },
-  "textFragment.comment.block": {
-    description: "Text fragment consisting of a block comment",
-    scopeType: "textFragment",
-  },
-  "textFragment.string.singleLine": {
-    description: "Text fragment consisting of a single-line string",
-    scopeType: "textFragment",
-  },
-  "textFragment.string.multiLine": {
-    description: "Text fragment consisting of a multi-line string",
-    scopeType: "textFragment",
-  },
-  "textFragment.element": {
-    description: "Text fragment consisting of a xml element interior",
-    scopeType: "textFragment",
-  },
-
-  disqualifyDelimiter: {
-    description:
-      "Used to disqualify a token from being treated as a surrounding pair delimiter. This will usually be operators containing `>` or `<`, eg `<`, `<=`, `->`, etc",
-    scopeType: "disqualifyDelimiter",
-  },
-  pairDelimiter: {
-    description:
-      "A pair delimiter, eg parentheses, brackets, braces, quotes, etc",
-    scopeType: "pairDelimiter",
-  },
-
   "branch.if": {
     description: "An if branch",
     scopeType: "branch",
@@ -1044,6 +1012,43 @@ export const scopeSupportFacetInfos: Record<
     description: "A unit in a css rule set",
     scopeType: "unit",
   },
+
+  // Internal scope facets
+
+  "textFragment.comment.line": {
+    description: "Internally used text fragment consisting of a line comment.",
+    scopeType: "textFragment",
+  },
+  "textFragment.comment.block": {
+    description: "Internally used text fragment consisting of a block comment.",
+    scopeType: "textFragment",
+  },
+  "textFragment.string.singleLine": {
+    description:
+      "Internally used text fragment consisting of a single-line string.",
+    scopeType: "textFragment",
+  },
+  "textFragment.string.multiLine": {
+    description:
+      "Internally used text fragment consisting of a multi-line string.",
+    scopeType: "textFragment",
+  },
+  "textFragment.element": {
+    description:
+      "Internally used text fragment consisting of a xml element interior.",
+    scopeType: "textFragment",
+  },
+
+  disqualifyDelimiter: {
+    description:
+      "Internally used to disqualify a token from being treated as a surrounding pair delimiter. This will usually be operators containing `>` or `<`, eg `<`, `<=`, `->`, etc.",
+    scopeType: "disqualifyDelimiter",
+  },
+  pairDelimiter: {
+    description:
+      'Internally used to add additional language specific surrounding pair delimiters in addition to the text based definitions. eg `r"`.',
+    scopeType: "pairDelimiter",
+  },
 };
 
 function documentIter(
diff --git a/packages/cursorless-org-docs/src/docs/components/ScopeVisualizer.tsx b/packages/cursorless-org-docs/src/docs/components/ScopeVisualizer.tsx
index d264b3c33e..c37c09958f 100644
--- a/packages/cursorless-org-docs/src/docs/components/ScopeVisualizer.tsx
+++ b/packages/cursorless-org-docs/src/docs/components/ScopeVisualizer.tsx
@@ -52,6 +52,24 @@ export function ScopeVisualizer({ languageId, scopeTypeType }: Props) {
     scopeTypeType != null,
   );
 
+  const renderPublicScopesHeader = () => {
+    return <H2>Scopes</H2>;
+  };
+
+  const renderInternalScopesHeader = () => {
+    return (
+      <>
+        <H2>Internal scopes</H2>
+
+        <p>
+          The following are internal scopes. They are not intended for user
+          interaction or spoken use. These scopes exist solely for internal
+          Cursorless functionality.
+        </p>
+      </>
+    );
+  };
+
   const renderOptions = () => {
     return (
       <div className="mb-4">
@@ -76,61 +94,61 @@ export function ScopeVisualizer({ languageId, scopeTypeType }: Props) {
     );
   };
 
-  const renderInternalScopes = () => {
-    if (scopes.internal.length === 0) {
-      return null;
-    }
-    return (
-      <>
-        <H2>Internal scopes</H2>
-
-        {languageId && (
-          <p>
-            The following are internal scopes. They are not intended for user
-            interaction or spoken use. These scopes exist solely for internal
-            Cursorless functionality.
-          </p>
-        )}
-
-        {scopes.internal.map((scope) =>
-          renderScope(
-            languageId,
-            scopeTypeType,
-            rangeType,
-            renderWhitespace,
-            scope,
-          ),
-        )}
-      </>
+  const renderScopes = (scopes: Scope[]) => {
+    return scopes.map((scope) =>
+      renderScope(
+        languageId,
+        scopeTypeType,
+        rangeType,
+        renderWhitespace,
+        scope,
+      ),
     );
   };
 
-  return (
-    <>
-      <H2>Scopes</H2>
+  // Specific language. Public scopes followed by (optional) internal scopes.
+  if (languageId != null) {
+    return (
+      <>
+        {renderPublicScopesHeader()}
 
-      {languageId && (
         <p>
           Below are visualizations of all our scope tests for this language.
           These were created primarily for testing purposes rather than as
           documentation. There are quite a few, and they may feel a bit
           overwhelming from a documentation standpoint.
         </p>
-      )}
 
-      {renderOptions()}
+        {renderOptions()}
+        {renderScopes(scopes.public)}
 
-      {scopes.public.map((scope) =>
-        renderScope(
-          languageId,
-          scopeTypeType,
-          rangeType,
-          renderWhitespace,
-          scope,
-        ),
-      )}
+        {scopes.internal.length > 0 && (
+          <>
+            {renderInternalScopesHeader()}
+            {renderScopes(scopes.internal)}
+          </>
+        )}
+      </>
+    );
+  }
 
-      {renderInternalScopes()}
+  // Specific public scope
+  if (scopes.public.length > 0) {
+    return (
+      <>
+        {renderPublicScopesHeader()}
+        {renderOptions()}
+        {renderScopes(scopes.public)}
+      </>
+    );
+  }
+
+  // Specific internal scope
+  return (
+    <>
+      {renderInternalScopesHeader()}
+      {renderOptions()}
+      {renderScopes(scopes.internal)}
     </>
   );
 }
@@ -295,7 +313,7 @@ function getScopeFixtures(
     .forEach((scope) => {
       scope.facets.sort(facetComparator);
       scope.facets.forEach((f) => f.fixtures.sort(nameComparator));
-      if (scopeTypeType == null && isScopeInternal(scope.scopeTypeType)) {
+      if (isScopeInternal(scope.scopeTypeType)) {
         result.internal.push(scope);
       } else {
         result.public.push(scope);

From 9cb97bd7689a65203d0a53ec82e0bea48c413e0e Mon Sep 17 00:00:00 2001
From: Andreas Arvidsson <andreas.arvidsson87@gmail.com>
Date: Sun, 7 Sep 2025 09:06:55 +0200
Subject: [PATCH 2/5] Removed period

---
 .../src/scopeSupportFacets/scopeSupportFacetInfos.ts   | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/packages/common/src/scopeSupportFacets/scopeSupportFacetInfos.ts b/packages/common/src/scopeSupportFacets/scopeSupportFacetInfos.ts
index 39c34a6aed..224ff19eb9 100644
--- a/packages/common/src/scopeSupportFacets/scopeSupportFacetInfos.ts
+++ b/packages/common/src/scopeSupportFacets/scopeSupportFacetInfos.ts
@@ -1016,26 +1016,26 @@ export const scopeSupportFacetInfos: Record<
   // Internal scope facets
 
   "textFragment.comment.line": {
-    description: "Internally used text fragment consisting of a line comment.",
+    description: "Internally used text fragment consisting of a line comment",
     scopeType: "textFragment",
   },
   "textFragment.comment.block": {
-    description: "Internally used text fragment consisting of a block comment.",
+    description: "Internally used text fragment consisting of a block comment",
     scopeType: "textFragment",
   },
   "textFragment.string.singleLine": {
     description:
-      "Internally used text fragment consisting of a single-line string.",
+      "Internally used text fragment consisting of a single-line string",
     scopeType: "textFragment",
   },
   "textFragment.string.multiLine": {
     description:
-      "Internally used text fragment consisting of a multi-line string.",
+      "Internally used text fragment consisting of a multi-line string",
     scopeType: "textFragment",
   },
   "textFragment.element": {
     description:
-      "Internally used text fragment consisting of a xml element interior.",
+      "Internally used text fragment consisting of a xml element interior",
     scopeType: "textFragment",
   },
 

From 2712b9b73dffced8f75773db99147cb5a1fcec08 Mon Sep 17 00:00:00 2001
From: Andreas Arvidsson <andreas.arvidsson87@gmail.com>
Date: Sun, 7 Sep 2025 09:10:39 +0200
Subject: [PATCH 3/5] Fix meta

---
 data/scopeSupportFacetInfos.md | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/data/scopeSupportFacetInfos.md b/data/scopeSupportFacetInfos.md
index 8f34e5c631..aa92ff1fb7 100644
--- a/data/scopeSupportFacetInfos.md
+++ b/data/scopeSupportFacetInfos.md
@@ -336,11 +336,11 @@
 
 ### textFragment
 
-- `textFragment.comment.block` Internally used text fragment consisting of a block comment.
-- `textFragment.comment.line` Internally used text fragment consisting of a line comment.
-- `textFragment.element` Internally used text fragment consisting of a xml element interior.
-- `textFragment.string.multiLine` Internally used text fragment consisting of a multi-line string.
-- `textFragment.string.singleLine` Internally used text fragment consisting of a single-line string.
+- `textFragment.comment.block` Internally used text fragment consisting of a block comment
+- `textFragment.comment.line` Internally used text fragment consisting of a line comment
+- `textFragment.element` Internally used text fragment consisting of a xml element interior
+- `textFragment.string.multiLine` Internally used text fragment consisting of a multi-line string
+- `textFragment.string.singleLine` Internally used text fragment consisting of a single-line string
 
 ### token
 

From adfbcacfa78434e8b6adee9ab28d38b380cd05e1 Mon Sep 17 00:00:00 2001
From: Andreas Arvidsson <andreas.arvidsson87@gmail.com>
Date: Sun, 7 Sep 2025 09:14:39 +0200
Subject: [PATCH 4/5] move paragraph

---
 .../src/docs/components/ScopeVisualizer.tsx                    | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/packages/cursorless-org-docs/src/docs/components/ScopeVisualizer.tsx b/packages/cursorless-org-docs/src/docs/components/ScopeVisualizer.tsx
index c37c09958f..f3ca6f6e33 100644
--- a/packages/cursorless-org-docs/src/docs/components/ScopeVisualizer.tsx
+++ b/packages/cursorless-org-docs/src/docs/components/ScopeVisualizer.tsx
@@ -110,8 +110,6 @@ export function ScopeVisualizer({ languageId, scopeTypeType }: Props) {
   if (languageId != null) {
     return (
       <>
-        {renderPublicScopesHeader()}
-
         <p>
           Below are visualizations of all our scope tests for this language.
           These were created primarily for testing purposes rather than as
@@ -119,6 +117,7 @@ export function ScopeVisualizer({ languageId, scopeTypeType }: Props) {
           overwhelming from a documentation standpoint.
         </p>
 
+        {renderPublicScopesHeader()}
         {renderOptions()}
         {renderScopes(scopes.public)}
 

From dd157fea08cea8718b6a592c437fa79f70a3438e Mon Sep 17 00:00:00 2001
From: Andreas Arvidsson <andreas.arvidsson87@gmail.com>
Date: Sun, 7 Sep 2025 09:21:25 +0200
Subject: [PATCH 5/5] fix link scrolling to header

---
 packages/cursorless-org-docs/src/docs/components/Header.css | 3 +++
 packages/cursorless-org-docs/src/docs/components/Header.tsx | 4 ++--
 2 files changed, 5 insertions(+), 2 deletions(-)
 create mode 100644 packages/cursorless-org-docs/src/docs/components/Header.css

diff --git a/packages/cursorless-org-docs/src/docs/components/Header.css b/packages/cursorless-org-docs/src/docs/components/Header.css
new file mode 100644
index 0000000000..544981480c
--- /dev/null
+++ b/packages/cursorless-org-docs/src/docs/components/Header.css
@@ -0,0 +1,3 @@
+.anchor-with-sticky-navbar {
+  scroll-margin-top: calc(var(--ifm-navbar-height) + 0.5rem);
+}
diff --git a/packages/cursorless-org-docs/src/docs/components/Header.tsx b/packages/cursorless-org-docs/src/docs/components/Header.tsx
index eba90b11b0..f01ea95d4f 100644
--- a/packages/cursorless-org-docs/src/docs/components/Header.tsx
+++ b/packages/cursorless-org-docs/src/docs/components/Header.tsx
@@ -1,5 +1,6 @@
 import { uriEncodeHashId } from "@cursorless/common";
 import React from "react";
+import "./Header.css";
 
 interface Props {
   className?: string;
@@ -35,8 +36,7 @@ function renderHeader(
       id={encodedId}
       title={title}
       className={
-        "scope-header anchorWithStickyNavbar_IncK" +
-        (className ? " " + className : "")
+        "anchor-with-sticky-navbar" + (className ? " " + className : "")
       }
     >
       {children}