@bhsd/codemirror-stickyscroll 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zulfazli (Fazelllyyy)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,135 @@
+# @bhsd/codemirror-stickyscroll
+
+> VS Code / Monaco-style **sticky scroll** (sticky lines) for [CodeMirror 6](https://codemirror.net/).
+
+<p align="center">
+  <img src="preview/image.png" alt="Sticky Scroll Preview" width="750" />
+</p>
+
+This is a fork of [@fazelstudio/codemirror-stickyscroll](https://github.com/fazel-studio/codemirror-stickyscroll).
+
+Sticky lines keep the *opening* lines of the enclosing scopes (function, class,
+if/loop blocks, …) pinned at the top of the editor while you scroll — exactly
+like VS Code's sticky scroll, but built **purely as an external CodeMirror 6
+extension** (no fork of `@codemirror/*`).
+
+## Features
+
+- **Per-pixel updates** — a native `scroll` listener + `requestAnimationFrame`
+  throttle keeps the bar glued to the scroll position; no "jumpy" updates.
+- **Click-to-jump with margin compensation** — clicking a sticky line scrolls
+  the target line to the top *plus* the current bar height, so the line you
+  jump to is never hidden behind the bar. Keyboard (`Enter`/`Space`) + `role="button"` for a11y.
+- **Reuses the consumer's theme** — the bar re-highlights lines through the
+  *active* highlight styles of the editor (`highlightingFor`), or clones the
+  already-rendered DOM line when available. The package **never** registers its
+  own `syntaxHighlighting(...)`.
+- **Language-agnostic** — detection is based on `foldable()` from
+  `@codemirror/language` (the fold services / fold node props that every
+  `@codemirror/lang-*` already registers). It includes a smart, generic denylist
+  that works across multiple languages (JS/TS, Python, Rust, Go, etc.) out of the box,
+  and gracefully handles data languages like JSON.
+- **Gutter alignment, horizontal sync, RTL, resize-proof** — line numbers are
+  aligned with the real gutter (width tracked via `ResizeObserver`), the bar
+  follows horizontal scroll, and it reacts to font/zoom/resize changes.
+- **Zero runtime deps** — peer dependencies only.
+
+## Installation
+
+```bash
+npm install @bhsd/codemirror-stickyscroll
+```
+
+The following are **peer dependencies** (already present in any project that
+has a working CodeMirror 6 editor):
+
+| Package | Minimum |
+| --- | --- |
+| `@codemirror/view` | ^6.0.0 |
+| `@codemirror/state` | ^6.0.0 |
+| `@codemirror/language` | ^6.0.0 |
+| `@lezer/common` | ^1.0.0 |
+| `@lezer/highlight` | ^1.0.0 |
+
+## API
+
+### `stickyScroll(options?: StickyScrollOptions): Extension`
+
+```ts
+interface StickyScrollOptions {
+  /** Maximum sticky lines shown at once (dynamically clamped to ~40% of editor height). Default: 4 */
+  maxStickyLines?: number;
+  /** Minimum lines a scope must span to become sticky. Default: 2 */
+  minBlockLines?: number;
+  /**
+   * Denylist predicate: return true to never pin a foldable node of that type.
+   * Defaults to `defaultExcludeNode` (imports + data literals + comments).
+   * It uses exact node names for JS/TS and generic regex patterns for other
+   * languages, while automatically bypassing the literal denylist for JSON.
+   */
+  excludeNode?: (nodeName: string, langName: string | undefined) => boolean;
+  /** Extra HighlightStyle merged in when a line is re-highlighted from scratch. */
+  highlightStyle?: HighlightStyle;
+  /** Called after a sticky line is clicked (after the jump is dispatched). */
+  onLineClick?: (lineNumber: number) => void;
+  /** Extra CSS class(es) for the bar container. */
+  class?: string;
+}
+```
+
+### Re-exports
+
+```ts
+import {
+  stickyScroll,
+  stickyScrollFacet,        // the configuration Facet (compose/override per instance)
+  defaultExcludeNode,       // default denylist implementation
+  makeStickyScrollConfig,   // merge options with defaults
+  stickyScrollBaseTheme,    // layout-only base theme (no token colors)
+  type StickyScrollOptions,
+  type StickyLine,
+} from "@bhsd/codemirror-stickyscroll";
+```
+
+## Styling
+
+The bar is layout-only by default and always follows the **editor's own theme**
+(token colors, background). You can restyle it with CSS.
+
+Per-row hooks:
+
+| Class | Purpose |
+| --- | --- |
+| `.cm-stickyscroll-container` | the overlay bar |
+| `.cm-stickyscroll-line` | one breadcrumb row |
+| `.cm-stickyscroll-line:hover` | hover highlight |
+| `.cm-stickyscroll-line.cm-stickyscroll-current` | block containing the cursor |
+| `.cm-stickyscroll-gutter` | line-number cell |
+| `.cm-stickyscroll-text` | code column (horizontally synced) |
+
+## How it works
+
+1. **Detect the top line** — `view.lineBlockAtHeight(scrollTop - documentTop)`.
+2. **Walk the syntax tree** — from `syntaxTree(state).resolveInner(topPos, 0)`
+   up through `node.parent`.
+3. **A scope qualifies when** its opening line is *foldable*
+   (`foldable(state, line.from, line.to)` from `@codemirror/language`), its fold
+   anchor node is not denylisted, and it spans ≥ `minBlockLines`.
+4. **Render** — a `ViewPlugin` owns an absolutely-positioned overlay
+   (`position: absolute; top: 0` inside `view.dom`), updated per-frame from the
+   native `scroll` event; line numbers align with the real gutter; token colors
+   come from the consumer's active highlighters.
+
+The DOM overlay (rather than the Panel API / `showPanel`) is what makes the bar
+behave like Monaco: it never pushes the content down (no reflow) and it can be
+updated per-pixel, which panels cannot (panels only re-render on `ViewUpdate`,
+not on pure scroll).
+
+## Language support
+
+Works out of the box with any `@codemirror/lang-*` (or community grammar) that
+registers folding — JS/TS, Rust, Python, Java, Go, C#, etc.
+
+## License
+
+MIT — © Zulfazli (Fazelllyyy) · [https://github.com/fazelllyyy](https://github.com/fazelllyyy)

package/dist/compute.d.ts

@@ -0,0 +1,7 @@
+import type { EditorView } from "@codemirror/view";
+import type { StickyScrollConfig } from "./facet";
+import type { StickyLine } from "./types";
+/**
+ * Compute the sticky context for the current scroll position (viewport top).
+ */
+export declare function getStickyContext(view: EditorView, config: StickyScrollConfig): StickyLine[];

package/dist/compute.js

@@ -0,0 +1,168 @@
+import { ensureSyntaxTree, foldNodeProp, foldService, language, syntaxTree } from "@codemirror/language";
+/**
+ * Milliseconds of synchronous parse work we are allowed to spend per sticky
+ * update when the committed syntax tree has not caught up with the viewport
+ * yet (large files / big scroll jumps). The background parser keeps working
+ * between frames and commits its results, so this only accelerates the first
+ * reveal; once the tree covers the position the cost is O(1).
+ */
+const PARSE_TIMEOUT = 25;
+/**
+ * Return the best syntax tree we can answer a query at `pos` with right now.
+ *
+ * When the committed tree already covers `pos`, it is used directly (cheap).
+ * Otherwise we synchronously advance the parser for a bounded amount of time
+ * and use the extended tree if it reached `pos`, falling back to the committed
+ * tree otherwise (the background parser commits the rest shortly after).
+ *
+ * This is what keeps the sticky bar correct on files with thousands of lines:
+ * without it, `syntaxTree(state)` still holds a stale, short parse right after
+ * a scroll jump, and the ancestor walk would clamp to the document root and
+ * return no sticky lines at all.
+ */
+function treeUpTo(state, pos) {
+    var _a;
+    const committed = syntaxTree(state);
+    if (committed.length >= pos)
+        return committed;
+    return (_a = ensureSyntaxTree(state, pos, PARSE_TIMEOUT)) !== null && _a !== void 0 ? _a : committed;
+}
+/**
+ * Compute the sticky context for the current scroll position (viewport top).
+ */
+export function getStickyContext(view, config) {
+    const state = view.state;
+    const lang = state.facet(language);
+    if (!lang)
+        return [];
+    const tree = syntaxTree(state);
+    if (tree.length === 0)
+        return [];
+    // Calculate the document-relative Y of the top edge of the visible viewport.
+    // `view.documentTop` is the client Y of the document's top edge.
+    // The viewport's top client Y is `scrollDOM.getBoundingClientRect().top`.
+    const clientTop = view.scrollDOM.getBoundingClientRect().top;
+    let y = clientTop - view.documentTop;
+    if (y < 0)
+        y = 0;
+    const topBlock = view.lineBlockAtHeight(y);
+    if (topBlock.from > state.doc.length)
+        return [];
+    // Make sure the parser has covered at least the whole rendered range before
+    // walking ancestors, so deeply-scrolled positions in big files resolve to
+    // real scopes instead of the (clamped) document root.
+    const upto = Math.min(view.viewport.to, state.doc.length);
+    const parseTree = treeUpTo(state, upto);
+    // Dynamic clamp: limit sticky bar to max ~40% of the editor height
+    const lineHeight = Math.round(view.defaultLineHeight) || 16;
+    const maxDynamic = Math.max(1, Math.floor(view.scrollDOM.clientHeight * 0.4 / lineHeight));
+    const maxSticky = Math.min(config.maxStickyLines, maxDynamic);
+    return getStickyContextForRange(view, topBlock.from, config, parseTree, maxSticky);
+}
+/**
+ * Pure version of the algorithm.
+ *
+ * `tree` is optional and defaults to the committed syntax tree; pass an
+ * already-extended tree (see `getStickyContext`) to compute against a parse
+ * that is known to cover `fromPos`.
+ */
+function getStickyContextForRange({ state, viewport }, fromPos, config, t, maxSticky) {
+    const lang = state.facet(language);
+    if (!lang)
+        return [];
+    if (t.length === 0)
+        return [];
+    const doc = state.doc;
+    if (fromPos > doc.length)
+        return [];
+    const topLineNumber = doc.lineAt(fromPos).number;
+    const minBlockLines = config.minBlockLines;
+    const exclude = config.excludeNode;
+    const langName = lang.name;
+    const found = [];
+    const services = state.facet(foldService);
+    if (services.length === 0) {
+        let node = t.resolveInner(fromPos, 0);
+        while (node) {
+            if (!node.type.isTop && node.from < node.to && node.to <= doc.length) {
+                const prop = node.type.prop(foldNodeProp);
+                if (prop) {
+                    const foldRange = prop(node, state);
+                    if (foldRange) {
+                        // Find the semantic owner of this foldable block
+                        let owner = node;
+                        if (node.parent && !node.parent.type.isTop && !node.parent.type.prop(foldNodeProp)) {
+                            owner = node.parent;
+                        }
+                        const open = doc.lineAt(owner.from);
+                        const openLine = open.number;
+                        // Opening line must already be scrolled out above the viewport, and must not be blank.
+                        if (openLine < topLineNumber && open.text.trim() !== "") {
+                            // The denylist describes *foldable* node types (data literals,
+                            // comments, imports). `owner` may be a wrapper (e.g.
+                            // VariableDeclaration wrapping an ObjectExpression), so evaluate
+                            // against the foldable node's own type name.
+                            const typeName = node.name;
+                            if (!exclude(typeName, langName, owner.name)) {
+                                // A scope only counts as "over" once its full semantic end has
+                                // passed, so measure from `owner.to` (e.g. the whole try/catch or
+                                // if/else statement) instead of just the foldable block. This is
+                                // what delays the slide-away until the real closing brace.
+                                const close = doc.lineAt(Math.min(owner.to, doc.length));
+                                const closeLine = close.number;
+                                if (closeLine - openLine + 1 >= minBlockLines && closeLine >= topLineNumber) {
+                                    found.push({
+                                        lineNumber: openLine,
+                                        from: open.from,
+                                        to: open.to,
+                                        text: open.text,
+                                        nodeFrom: owner.from,
+                                        nodeTo: owner.to,
+                                    });
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+            node = node.parent;
+        }
+    }
+    else {
+        for (let openLine = topLineNumber - 1; openLine > 0; openLine--) {
+            const open = doc.line(openLine);
+            if (open.to < viewport.from)
+                break;
+            const ownerName = open.text.trim();
+            if (!exclude(undefined, langName, ownerName)) {
+                for (const service of services) {
+                    const foldRange = service(state, open.from, open.to);
+                    if (foldRange) {
+                        const nodeTo = Math.min(foldRange.to, doc.length);
+                        const close = doc.lineAt(nodeTo);
+                        const closeLine = close.number;
+                        if (closeLine - openLine + 1 >= minBlockLines && closeLine >= topLineNumber) {
+                            found.push({
+                                lineNumber: openLine,
+                                from: open.from,
+                                to: open.to,
+                                text: open.text,
+                                nodeFrom: foldRange.from,
+                                nodeTo,
+                            });
+                        }
+                    }
+                }
+            }
+        }
+    }
+    // `found` is collected innermost → outermost. Reverse to outermost → innermost,
+    // dedup by opening line (keep the outermost node on that line), then cap.
+    found.reverse();
+    const dedup = new Map();
+    for (const line of found) {
+        if (!dedup.has(line.lineNumber))
+            dedup.set(line.lineNumber, line);
+    }
+    return Array.from(dedup.values()).slice(0, maxSticky);
+}

package/dist/facet.d.ts

@@ -0,0 +1,47 @@
+import { Facet } from "@codemirror/state";
+/**
+ * Public options accepted by `stickyScroll()`.
+ *
+ * All fields are optional; defaults are documented below.
+ */
+export interface StickyScrollOptions {
+    /** Maximum sticky lines shown at once. Default: 4 */
+    maxStickyLines?: number;
+    /** Minimum number of lines a scope must span before it becomes sticky. Default: 6 */
+    minBlockLines?: number;
+    /**
+     * Denylist predicate. When it returns `true` for a foldable syntax node,
+     * that node is never turned into a sticky line, although it could be folded.
+     * Defaults to `defaultExcludeNode`, which excludes imports and data
+     * literals — exact node names for JS/TS, best-effort name-pattern
+     * matching for other grammars. Override for fine-tuning, especially for
+     * a specific non-JS/TS language.
+     */
+    excludeNode?: (nodeName?: string, langName?: string, ownerName?: string) => boolean;
+    /** Extra CSS class(es) applied to the sticky bar container. */
+    class?: string;
+}
+/** Resolved configuration produced by `stickyScrollFacet`. */
+export interface StickyScrollConfig extends Required<Pick<StickyScrollOptions, "maxStickyLines" | "minBlockLines" | "excludeNode">> {
+    class?: string | undefined;
+}
+/**
+ * Default denylist (see §4.3 of the design doc): nodes that *are* foldable but
+ * semantically are not navigation scopes worth pinning (imports, big data
+ * literals, comment blocks).
+ *
+ * Precise for JS/TS out of the box (`JS_TS_DENYLIST`); best-effort pattern
+ * match for everything else. Override via `StickyScrollOptions.excludeNode`
+ * for a language you need exact behavior on.
+ */
+export declare const defaultExcludeNode: (nodeName?: string, langName?: string, ownerName?: string) => boolean;
+/** Merge partial options with built-in defaults. */
+export declare function makeStickyScrollConfig(options?: StickyScrollOptions): StickyScrollConfig;
+/**
+ * The facet carrying the sticky-scroll configuration.
+ *
+ * Multiple `stickyScroll()` instances compose; the *last* registered value wins
+ * (override semantics). Consumers may always read/override it per-instance via
+ * `stickyScrollFacet.of(...)`.
+ */
+export declare const stickyScrollFacet: Facet<StickyScrollOptions, StickyScrollConfig>;

package/dist/facet.js

@@ -0,0 +1,81 @@
+import { Facet } from "@codemirror/state";
+/**
+ * Exact node names we know for certain, verified against the JS/TS Lezer
+ * grammar (`@codemirror/lang-javascript`). Kept as an explicit set (rather
+ * than folded into the pattern fallback below) because these are the names
+ * we can vouch for precisely.
+ */
+const JS_TS_DENYLIST = new Set([
+    "ImportDeclaration",
+    "ImportStatement",
+    "ObjectExpression",
+    "ObjectLiteral",
+    "ArrayExpression",
+    "ArrayLiteral",
+    "ObjectPattern",
+    "Comment",
+    "LineComment",
+    "BlockComment",
+    "DocComment",
+]);
+/**
+ * Best-effort fallback for grammars we don't special-case above (Python,
+ * Rust, Go, CSS, ...). Every Lezer grammar names its nodes independently, so
+ * there is no single exact list that covers all of them — but most `lang-*`
+ * packages follow a similar naming convention for the three categories that
+ * matter here (data literals, comments, import/use declarations). These
+ * patterns catch that convention on a best-effort basis; they will not be
+ * 100% precise for every language, but they degrade gracefully (a miss just
+ * means the node isn't excluded, not a crash or a wrong result elsewhere).
+ * For languages where precision matters, pass a language-specific
+ * `excludeNode` via `StickyScrollOptions`.
+ */
+const LITERAL_NODE_PATTERN = /^(?:Object|Array|List|Dict(?:ionary)?|Set|Record|Map|Tuple)(?:Expression|Literal|Pattern)?$/;
+const IMPORT_NODE_PATTERN = /^(?:Import|Use)(?:Declaration|Statement|Item|Spec)?$/;
+/**
+ * Default denylist (see §4.3 of the design doc): nodes that *are* foldable but
+ * semantically are not navigation scopes worth pinning (imports, big data
+ * literals, comment blocks).
+ *
+ * Precise for JS/TS out of the box (`JS_TS_DENYLIST`); best-effort pattern
+ * match for everything else. Override via `StickyScrollOptions.excludeNode`
+ * for a language you need exact behavior on.
+ */
+export const defaultExcludeNode = (nodeName, langName, ownerName) => {
+    // In pure data languages like JSON, we DO NOT exclude objects/arrays.
+    // Because the entire JSON file consists of Objects/Arrays, excluding them
+    // would completely disable sticky scroll for the file.
+    if (langName === "json" || langName === "jsonc") {
+        return ownerName !== "Property" || nodeName.endsWith("Comment");
+    }
+    // DO NOT exclude in stream-base languages.
+    if (nodeName === undefined)
+        return false;
+    return (JS_TS_DENYLIST.has(nodeName) ||
+        nodeName.endsWith("Comment") ||
+        LITERAL_NODE_PATTERN.test(nodeName) ||
+        IMPORT_NODE_PATTERN.test(nodeName));
+};
+const DEFAULT_MAX_STICKY_LINES = 4;
+const DEFAULT_MIN_BLOCK_LINES = 6;
+/** Merge partial options with built-in defaults. */
+export function makeStickyScrollConfig(options) {
+    var _a, _b, _c;
+    return {
+        maxStickyLines: (_a = options === null || options === void 0 ? void 0 : options.maxStickyLines) !== null && _a !== void 0 ? _a : DEFAULT_MAX_STICKY_LINES,
+        minBlockLines: (_b = options === null || options === void 0 ? void 0 : options.minBlockLines) !== null && _b !== void 0 ? _b : DEFAULT_MIN_BLOCK_LINES,
+        excludeNode: (_c = options === null || options === void 0 ? void 0 : options.excludeNode) !== null && _c !== void 0 ? _c : defaultExcludeNode,
+        class: options === null || options === void 0 ? void 0 : options.class,
+    };
+}
+/**
+ * The facet carrying the sticky-scroll configuration.
+ *
+ * Multiple `stickyScroll()` instances compose; the *last* registered value wins
+ * (override semantics). Consumers may always read/override it per-instance via
+ * `stickyScrollFacet.of(...)`.
+ */
+export const stickyScrollFacet = Facet.define({
+    compare: (a, b) => a === b,
+    combine: (values) => makeStickyScrollConfig(values[values.length - 1]),
+});

package/dist/index.d.ts

@@ -0,0 +1,23 @@
+import type { Extension } from "@codemirror/state";
+import { type StickyScrollOptions } from "./facet";
+export type { StickyLine } from "./types";
+export type { StickyScrollOptions, StickyScrollConfig } from "./facet";
+export { stickyScrollFacet, defaultExcludeNode, makeStickyScrollConfig } from "./facet";
+export { stickyScrollBaseTheme } from "./theme";
+/**
+ * Add Monaco/VS Code-style sticky scroll to a CodeMirror 6 editor.
+ *
+ * ```ts
+ * import { stickyScroll } from "@fazelstudio/codemirror-stickyscroll";
+ *
+ * const view = new EditorView({
+ *   extensions: [basicSetup, javascript(), stickyScroll({ maxStickyLines: 4 })],
+ *   parent: el,
+ * });
+ * ```
+ *
+ * Note: the returned array deliberately does NOT contain any
+ * `syntaxHighlighting(...)` — token colors always come from the consumer's own
+ * theme (§4.4).
+ */
+export declare function stickyScroll(options?: StickyScrollOptions): Extension;

package/dist/index.js

@@ -0,0 +1,24 @@
+import { stickyScrollFacet } from "./facet";
+import { scrollStickyPlugin } from "./plugin";
+import { stickyScrollBaseTheme } from "./theme";
+export { stickyScrollFacet, defaultExcludeNode, makeStickyScrollConfig } from "./facet";
+export { stickyScrollBaseTheme } from "./theme";
+/**
+ * Add Monaco/VS Code-style sticky scroll to a CodeMirror 6 editor.
+ *
+ * ```ts
+ * import { stickyScroll } from "@fazelstudio/codemirror-stickyscroll";
+ *
+ * const view = new EditorView({
+ *   extensions: [basicSetup, javascript(), stickyScroll({ maxStickyLines: 4 })],
+ *   parent: el,
+ * });
+ * ```
+ *
+ * Note: the returned array deliberately does NOT contain any
+ * `syntaxHighlighting(...)` — token colors always come from the consumer's own
+ * theme (§4.4).
+ */
+export function stickyScroll(options = {}) {
+    return [stickyScrollFacet.of(options), stickyScrollBaseTheme, scrollStickyPlugin];
+}

package/dist/plugin.d.ts

@@ -0,0 +1,62 @@
+import { EditorView, ViewPlugin, type ViewUpdate } from "@codemirror/view";
+import type { StickyLine } from "./types";
+declare class StickyScrollPlugin {
+    private readonly dom;
+    private readonly inner;
+    private readonly view;
+    private config;
+    private readonly cache;
+    private rafHandle;
+    private observer;
+    private gutterObserver;
+    private gutterMutationObserver;
+    private gutterMetrics;
+    private currentHeight;
+    private lastLineKey;
+    get lineHeight(): number;
+    constructor(view: EditorView);
+    clearCache(): void;
+    update(update: ViewUpdate): void;
+    destroy(): void;
+    private onScroll;
+    private request;
+    private render;
+    private hide;
+    /**
+     * Rebuild all row DOM nodes (called only when line numbers change).
+     * We clear the inner wrapper and build fresh — no stale DOM element issues.
+     */
+    private buildRows;
+    /**
+     * Update per-frame attributes WITHOUT rebuilding DOM.
+     * Called every frame when the line-set is unchanged.
+     */
+    private updateRowAttrs;
+    /**
+     * Build a single sticky row element.
+     *
+     * The gutter overlay mirrors the real editor gutter column-by-column:
+     *   .cm-stickyscroll-gutter  (position:absolute, width = total gutter width)
+     */
+    private makeRow;
+    setClass(row: HTMLDivElement, line: StickyLine): void;
+    setWidth(row: HTMLDivElement, gutter: HTMLDivElement): void;
+    setHeight(ele: HTMLDivElement): void;
+    setTransform(code: HTMLDivElement): void;
+    /**
+     * Resolve the sticky bar's background to a GUARANTEED-opaque color that
+     * matches the editor's effective backdrop.
+     *
+     *   1. Walk the real ancestor chain (contentDOM → … → <html>) and return the
+     *      first opaque color, skipping fully transparent AND semi-transparent
+     *      layers (a semi-transparent ancestor is only used as a last resort).
+     *   2. Fall back to a dark/light hex default.
+     *
+     * This makes it impossible for the sticky bar to end up see-through, exactly
+     * like Monaco's sticky widget which always paints a solid background.
+     */
+    private resolveBackground;
+    private detectBg;
+}
+export declare const scrollStickyPlugin: ViewPlugin<StickyScrollPlugin, undefined>;
+export {};

package/dist/plugin.js

@@ -0,0 +1,333 @@
+import { language, syntaxTree } from "@codemirror/language";
+import { Direction, EditorView, ViewPlugin } from "@codemirror/view";
+import { getStickyContext } from "./compute";
+import { stickyScrollFacet } from "./facet";
+import { renderLineCode } from "./render";
+// ─────────────────────────────────────────────────────────────────────────────
+// Utilities
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Alpha channel of a computed `background-color`, or `null` when the color has
+ * no alpha channel (hex / named / `rgb(...)` → fully opaque).
+ */
+function alphaOf(bg) {
+    if (!bg || bg === "transparent")
+        return 0;
+    const m = /rgba?\(([^)]*)\)/.exec(bg);
+    if (!m)
+        return 1;
+    const parts = m[1].split(",");
+    if (parts.length === 4) {
+        const a = parseFloat(parts[3]);
+        return Number.isNaN(a) ? 1 : a;
+    }
+    return 1;
+}
+function measureGutters(view) {
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-type-assertion
+    const guttersEl = view.dom.querySelector(".cm-gutters");
+    if (!guttersEl)
+        return { totalWidth: 0, columns: [] };
+    const totalWidth = guttersEl.offsetWidth;
+    const columns = Array.from(guttersEl.children, (child) => ({
+        width: child.offsetWidth,
+        className: child.className
+    }));
+    return { totalWidth, columns };
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// VSCode/Monaco-style sticky scroll implementation
+//
+// Reference: stickyScrollWidget.ts + stickyScrollController.ts
+//
+//  State has two key values:
+//    • startLineNumbers[]     — the N sticky lines to show (outermost → innermost)
+//    • lastLineRelativePosition — NEGATIVE in VSCode; how many px the LAST
+//                                 (innermost) line has been pushed UP by the
+//                                 approaching section break. Range (−lineHeight, 0].
+//
+//  DOM layout (widget):
+//    rootDomNode (.sticky-widget)          overflow:hidden; height set per-frame
+//      sticky-widget-lines                 the rows, absolutely positioned
+//        row × N                           each row has an explicit `top`
+// ─────────────────────────────────────────────────────────────────────────────
+class StickyScrollPlugin {
+    get lineHeight() {
+        return Math.round(this.view.defaultLineHeight) || 16;
+    }
+    constructor(view) {
+        this.cache = new Map();
+        this.rafHandle = null;
+        this.observer = null;
+        this.gutterObserver = null;
+        this.gutterMutationObserver = null;
+        this.gutterMetrics = { totalWidth: 0, columns: [] };
+        this.currentHeight = 0;
+        this.lastLineKey = "";
+        this.onScroll = () => this.request();
+        this.view = view;
+        this.config = view.state.facet(stickyScrollFacet);
+        // Outer container — clips content, fixed at top of editor.
+        this.dom = document.createElement("div");
+        this.dom.className =
+            "cm-stickyscroll-container" +
+                (this.config.class ? ` ${this.config.class}` : "");
+        // Inner wrapper — holds the rows; each row is laid out in normal flow and
+        // the container clips at its bottom edge (VSCode slide-away).
+        this.inner = document.createElement("div");
+        this.inner.className = "cm-stickyscroll-inner";
+        this.dom.appendChild(this.inner);
+        view.dom.appendChild(this.dom);
+        view.scrollDOM.addEventListener("scroll", this.onScroll, { passive: true });
+        this.observer = new ResizeObserver(this.onScroll);
+        this.observer.observe(view.dom);
+        const gutterEl = view.dom.querySelector(".cm-gutters");
+        if (gutterEl) {
+            this.gutterObserver = new ResizeObserver(this.onScroll);
+            this.gutterObserver.observe(gutterEl);
+            this.gutterMutationObserver = new MutationObserver(() => {
+                this.clearCache();
+                this.request();
+            });
+            this.gutterMutationObserver.observe(gutterEl, { childList: true });
+        }
+        this.request();
+    }
+    clearCache() {
+        this.cache.clear();
+        this.lastLineKey = "";
+    }
+    update(update) {
+        const configChanged = update.state.facet(stickyScrollFacet) !== update.startState.facet(stickyScrollFacet);
+        this.config = update.state.facet(stickyScrollFacet);
+        const contentChanged = configChanged ||
+            update.docChanged ||
+            syntaxTree(update.startState) !== syntaxTree(update.state);
+        if (contentChanged) {
+            this.clearCache();
+        }
+        if (contentChanged ||
+            update.viewportChanged ||
+            update.geometryChanged ||
+            update.selectionSet ||
+            update.startState.facet(language) !== update.state.facet(language)) {
+            this.request();
+        }
+    }
+    destroy() {
+        var _a, _b;
+        if (this.rafHandle !== null)
+            cancelAnimationFrame(this.rafHandle);
+        this.view.scrollDOM.removeEventListener("scroll", this.onScroll);
+        (_a = this.observer) === null || _a === void 0 ? void 0 : _a.disconnect();
+        (_b = this.gutterObserver) === null || _b === void 0 ? void 0 : _b.disconnect();
+        this.dom.remove();
+        this.cache.clear();
+    }
+    request() {
+        if (this.rafHandle !== null)
+            return;
+        this.rafHandle = requestAnimationFrame(() => {
+            try {
+                this.render();
+            }
+            catch (e) {
+                console.warn("[codemirror-stickyscroll]", e);
+            }
+            this.rafHandle = null;
+        });
+    }
+    // ─────────────────────────────────────────────────────────────────────────
+    // Main render — called every animation frame on scroll
+    // ─────────────────────────────────────────────────────────────────────────
+    render() {
+        const view = this.view;
+        // ── Measure ─────────────────────────────────────────────────────────────
+        this.gutterMetrics = measureGutters(view);
+        // ── Background (match active theme) ─────────────────────────────────────
+        // Always opaque (Monaco's sticky widget never lets the code show through).
+        this.dom.style.backgroundColor = this.resolveBackground();
+        // ── Compute sticky context ───────────────────────────────────────────────
+        const lines = getStickyContext(view, this.config);
+        if (!lines.length) {
+            this.hide();
+            return;
+        }
+        // ── Rebuild rows when line-set changes ───────────────────────────────────
+        const lineKey = lines.map((l) => l.lineNumber).join("|");
+        if (lineKey !== this.lastLineKey) {
+            this.lastLineKey = lineKey;
+            this.buildRows(lines);
+        }
+        const lh = this.lineHeight;
+        const totalLines = lines.length;
+        // ── Apply layout math ────────────────────────────────────────────────────
+        //
+        // The container clips via overflow:hidden; we never translate the whole
+        // stack — that would make the OUTERMOST line disappear first, unlike VSCode.
+        const containerHeight = totalLines * lh;
+        this.currentHeight = containerHeight;
+        this.dom.style.height = `${containerHeight}px`;
+        this.dom.style.display = "";
+        // Apply per-frame row attributes (gutter metrics, scrollLeft and highlight).
+        this.updateRowAttrs(lines);
+        this.dom.dir = view.textDirection === Direction.RTL ? "rtl" : "ltr";
+        this.inner.style.lineHeight = `${lh}px`;
+    }
+    // ─────────────────────────────────────────────────────────────────────────
+    // DOM management
+    // ─────────────────────────────────────────────────────────────────────────
+    hide() {
+        this.dom.style.display = "none";
+        this.currentHeight = 0;
+        // Do NOT clear this.inner — keep rows for fast reuse on next show.
+    }
+    /**
+     * Rebuild all row DOM nodes (called only when line numbers change).
+     * We clear the inner wrapper and build fresh — no stale DOM element issues.
+     */
+    buildRows(lines) {
+        this.inner.textContent = ""; // Remove all children cleanly
+        for (const line of lines) {
+            this.inner.appendChild(this.makeRow(line));
+        }
+    }
+    /**
+     * Update per-frame attributes WITHOUT rebuilding DOM.
+     * Called every frame when the line-set is unchanged.
+     */
+    updateRowAttrs(lines) {
+        const gm = this.gutterMetrics;
+        const rowEls = this.inner.children;
+        for (let i = 0; i < lines.length && i < rowEls.length; i++) {
+            const line = lines[i];
+            const row = rowEls[i];
+            this.setHeight(row);
+            this.setClass(row, line);
+            const gutter = row.firstElementChild;
+            this.setWidth(row, gutter);
+            this.setHeight(gutter);
+            const cols = gutter.children;
+            for (let c = 0; c < gm.columns.length && c < cols.length; c++) {
+                cols[c].style.width = `${gm.columns[c].width}px`;
+            }
+            const code = row.lastElementChild;
+            this.setTransform(code);
+        }
+    }
+    /**
+     * Build a single sticky row element.
+     *
+     * The gutter overlay mirrors the real editor gutter column-by-column:
+     *   .cm-stickyscroll-gutter  (position:absolute, width = total gutter width)
+     */
+    makeRow(line) {
+        const view = this.view;
+        const gm = this.gutterMetrics;
+        // Row
+        const row = document.createElement("div");
+        row.className = "cm-stickyscroll-line";
+        this.setClass(row, line);
+        row.setAttribute("role", "button");
+        row.setAttribute("tabindex", "0");
+        row.setAttribute("aria-label", `Go to line ${line.lineNumber}`);
+        this.setHeight(row);
+        // Gutter overlay container
+        const gutter = document.createElement("div");
+        gutter.className = "cm-stickyscroll-gutter";
+        this.setWidth(row, gutter);
+        this.setHeight(gutter);
+        if (gm.columns.length) {
+            gm.columns.forEach((colMetrics) => {
+                const col = document.createElement("div");
+                // Reuse the exact same classes so any custom user CSS (like Notron's .cm-lineNumbers .cm-gutterElement) matches!
+                col.className = colMetrics.className;
+                col.style.width = `${colMetrics.width}px`;
+                if (colMetrics.className.includes("cm-lineNumbers")) {
+                    // Wrap in cm-gutterElement to perfectly match the DOM structure of CM6's line numbers.
+                    const el = document.createElement("div");
+                    el.className = "cm-gutterElement";
+                    el.textContent = String(line.lineNumber);
+                    col.appendChild(el);
+                }
+                gutter.appendChild(col);
+            });
+        }
+        // Code span
+        const code = renderLineCode(view, line, this.cache);
+        this.setTransform(code);
+        row.appendChild(gutter);
+        row.appendChild(code);
+        // Click / keyboard
+        const jump = (e) => {
+            e.preventDefault();
+            e.stopPropagation();
+            view.dispatch({
+                selection: { anchor: line.from },
+                effects: EditorView.scrollIntoView(line.from, {
+                    y: "start",
+                    yMargin: this.currentHeight + 4,
+                }),
+            });
+            view.focus();
+        };
+        row.addEventListener("click", jump);
+        row.addEventListener("keydown", (ev) => {
+            if (ev.key === "Enter" || ev.key === " ")
+                jump(ev);
+        });
+        return row;
+    }
+    setClass(row, line) {
+        const head = this.view.state.selection.main.head;
+        row.classList.toggle("cm-stickyscroll-current", head >= line.nodeFrom && head <= line.nodeTo);
+    }
+    setWidth(row, gutter) {
+        const gw = this.gutterMetrics.totalWidth;
+        row.style.paddingInlineStart = `${gw}px`;
+        gutter.style.width = `${gw}px`;
+    }
+    setHeight(ele) {
+        const lh = this.lineHeight;
+        ele.style.height = `${lh}px`;
+    }
+    setTransform(code) {
+        const scrollX = this.view.scrollDOM.scrollLeft;
+        code.style.transform = scrollX > 0 ? `translateX(${-scrollX}px)` : "";
+    }
+    /**
+     * Resolve the sticky bar's background to a GUARANTEED-opaque color that
+     * matches the editor's effective backdrop.
+     *
+     *   1. Walk the real ancestor chain (contentDOM → … → <html>) and return the
+     *      first opaque color, skipping fully transparent AND semi-transparent
+     *      layers (a semi-transparent ancestor is only used as a last resort).
+     *   2. Fall back to a dark/light hex default.
+     *
+     * This makes it impossible for the sticky bar to end up see-through, exactly
+     * like Monaco's sticky widget which always paints a solid background.
+     */
+    resolveBackground() {
+        const detected = this.detectBg();
+        if (detected)
+            return detected;
+        const isDark = this.view.dom.classList.contains("cm-dark");
+        return isDark ? "#1e1e1e" : "#fff";
+    }
+    detectBg() {
+        let semiTransparent = null;
+        let el = this.view.contentDOM;
+        while (el) {
+            const bg = getComputedStyle(el).backgroundColor;
+            const alpha = alphaOf(bg);
+            if (alpha > 0) {
+                if (alpha >= 1)
+                    return bg;
+                semiTransparent = semiTransparent || bg;
+            }
+            el = el.parentElement;
+        }
+        return semiTransparent;
+    }
+}
+export const scrollStickyPlugin = ViewPlugin.fromClass(StickyScrollPlugin, {});

package/dist/render.d.ts

@@ -0,0 +1,22 @@
+import type { EditorView } from "@codemirror/view";
+import type { StickyLine } from "./types";
+/** Cache of rendered code elements keyed by opening line number. */
+export type RowCache = Map<number, {
+    text: string;
+    el: HTMLDivElement;
+}>;
+/**
+ * Build (or return cached) a `<div class="cm-stickyscroll-code">` element
+ * containing the syntax-highlighted code for one opening line (§4.4 / §4.6b).
+ *
+ * Priority:
+ *  1. Deep-clone the live CM6 `.cm-line` element when it is in the viewport —
+ *     token classes (`.tok-*`) are reused verbatim, guaranteed theme-accurate.
+ *  2. Re-highlight via the consumer's active `HighlightStyle`(s) using
+ *     `highlightingFor()` — never our own color palette.
+ *  3. Plain-text fallback (leading whitespace/indentation preserved).
+ *
+ * Results are cached by `(lineNumber, text)` so unchanged lines are free.
+ * The cache must be cleared externally when the syntax tree or config changes.
+ */
+export declare function renderLineCode(view: EditorView, line: StickyLine, cache: RowCache): HTMLDivElement;

package/dist/render.js

@@ -0,0 +1,140 @@
+import { highlightingFor, language } from "@codemirror/language";
+import { highlightTree } from "@lezer/highlight";
+import { syntaxTree } from "@codemirror/language";
+// ---------------------------------------------------------------------------
+// Internal: consumer-theme-aware Highlighter
+// ---------------------------------------------------------------------------
+/**
+ * Resolves highlight classes from the *active* styles in the consumer's
+ * EditorState (§4.4) — not from any palette bundled with this package.
+ */
+class StateHighlighter {
+    constructor(state, topNodeType) {
+        this.state = state;
+        this.topNodeType = topNodeType;
+    }
+    style(tags) {
+        return highlightingFor(this.state, tags, this.topNodeType);
+    }
+    scope() {
+        return true;
+    }
+}
+// ---------------------------------------------------------------------------
+// Internal: find the live `.cm-line` DOM element for a document line
+// ---------------------------------------------------------------------------
+function findRenderedLineElement(view, lineNumber) {
+    const lineFrom = view.state.doc.line(lineNumber).from;
+    // Only lines that are actually rendered in the DOM can be cloned. Anything
+    // outside `view.viewport` (visible area + render margin) must fall back to
+    // re-highlighting, never to a position-clamped lookup.
+    if (lineFrom < view.viewport.from || lineFrom > view.viewport.to)
+        return null;
+    // `domAtPos` maps a document position to its exact DOM node, so it is immune
+    // to index misalignment between `viewportLineBlocks` and `querySelectorAll`.
+    // (Block widgets, placeholder lines and render-margin lines make those two
+    // lists diverge, which previously caused wrong — blank / comment / `}` —
+    // line text to be cloned into the sticky bar.)
+    let dom;
+    try {
+        dom = view.domAtPos(lineFrom, 1);
+    }
+    catch {
+        return null;
+    }
+    let el = dom.node instanceof HTMLElement ? dom.node : dom.node.parentElement;
+    while (el && !el.classList.contains("cm-line"))
+        el = el.parentElement;
+    return el;
+}
+// ---------------------------------------------------------------------------
+// Public: renderLineCode
+// ---------------------------------------------------------------------------
+/**
+ * Build (or return cached) a `<div class="cm-stickyscroll-code">` element
+ * containing the syntax-highlighted code for one opening line (§4.4 / §4.6b).
+ *
+ * Priority:
+ *  1. Deep-clone the live CM6 `.cm-line` element when it is in the viewport —
+ *     token classes (`.tok-*`) are reused verbatim, guaranteed theme-accurate.
+ *  2. Re-highlight via the consumer's active `HighlightStyle`(s) using
+ *     `highlightingFor()` — never our own color palette.
+ *  3. Plain-text fallback (leading whitespace/indentation preserved).
+ *
+ * Results are cached by `(lineNumber, text)` so unchanged lines are free.
+ * The cache must be cleared externally when the syntax tree or config changes.
+ */
+export function renderLineCode(view, line, cache) {
+    // Cache hit.
+    const hit = cache.get(line.lineNumber);
+    if (hit && hit.text === line.text)
+        return hit.el;
+    const makeSpan = (child) => {
+        const s = document.createElement("div");
+        s.className = "cm-stickyscroll-code";
+        if (child)
+            s.appendChild(child);
+        else
+            s.textContent = line.text; // plain text, indentation preserved
+        return s;
+    };
+    // ── Strategy 1: clone the live viewport DOM line ─────────────────────────
+    const rendered = findRenderedLineElement(view, line.lineNumber);
+    // Ensure we don't clone empty virtual DOM placeholders that CM uses during fast scrolls.
+    if (rendered && rendered.textContent !== "") {
+        const frag = document.createDocumentFragment();
+        for (const child of rendered.childNodes) {
+            frag.appendChild(child.cloneNode(true));
+        }
+        const el = makeSpan(frag);
+        cache.set(line.lineNumber, { text: line.text, el });
+        return el;
+    }
+    // ── Strategy 2: re-highlight from the consumer's active HighlightStyle(s) ─
+    const lang = view.state.facet(language);
+    if (lang) {
+        try {
+            const tree = syntaxTree(view.state);
+            const topType = tree.type;
+            const highlighters = [new StateHighlighter(view.state, topType)];
+            const out = document.createElement("div");
+            out.className = "cm-stickyscroll-code";
+            let last = line.from;
+            highlightTree(tree, highlighters, (from, to, cls) => {
+                const start = Math.max(last, from);
+                const end = Math.min(line.to, to);
+                if (start >= end)
+                    return;
+                if (start > last) {
+                    out.appendChild(document.createTextNode(line.text.slice(last - line.from, start - line.from)));
+                }
+                if (cls) {
+                    const tok = document.createElement("span");
+                    tok.className = cls;
+                    tok.textContent = line.text.slice(start - line.from, end - line.from);
+                    out.appendChild(tok);
+                }
+                else {
+                    out.appendChild(document.createTextNode(line.text.slice(start - line.from, end - line.from)));
+                }
+                last = end;
+            }, line.from, line.to);
+            // Trailing unstyled text.
+            if (last < line.to) {
+                out.appendChild(document.createTextNode(line.text.slice(last - line.from)));
+            }
+            // Only cache when we produced actual content.
+            if (out.childNodes.length > 0) {
+                cache.set(line.lineNumber, { text: line.text, el: out });
+                return out;
+            }
+        }
+        catch {
+            // Fall through to plain text.
+        }
+    }
+    // ── Strategy 3: plain text ────────────────────────────────────────────────
+    const el = makeSpan();
+    cache.set(line.lineNumber, { text: line.text, el });
+    return el;
+}

package/dist/theme.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Cosmetic-only theme for the sticky bar.
+ *
+ * ALL sizing (height, lineHeight, padding, overflow, position, display,
+ * transform) is set via inline style by plugin.ts — matching Monaco's exact
+ * approach of updating styles imperatively on every scroll event.
+ *
+ * This file only provides:
+ *  1. Background color fallback (JS overrides immediately with actual editor bg)
+ *  2. Current-scope highlight
+ *  3. Gutter cosmetics (color, opacity)
+ *  4. Dark-mode override for background fallback
+ *
+ * ⛔ Do NOT add: height, lineHeight, overflow, display, padding, margin,
+ *    position, transform to .cm-stickyscroll-line or .cm-stickyscroll-inner.
+ *    Plugin.ts owns those — any CSS here will conflict.
+ * ⛔ Do NOT add syntaxHighlighting — token colors come from the consumer's theme.
+ */
+export declare const stickyScrollBaseTheme: import("@codemirror/state").Extension;

package/dist/theme.js

@@ -0,0 +1,73 @@
+import { EditorView } from "@codemirror/view";
+/**
+ * Cosmetic-only theme for the sticky bar.
+ *
+ * ALL sizing (height, lineHeight, padding, overflow, position, display,
+ * transform) is set via inline style by plugin.ts — matching Monaco's exact
+ * approach of updating styles imperatively on every scroll event.
+ *
+ * This file only provides:
+ *  1. Background color fallback (JS overrides immediately with actual editor bg)
+ *  2. Current-scope highlight
+ *  3. Gutter cosmetics (color, opacity)
+ *  4. Dark-mode override for background fallback
+ *
+ * ⛔ Do NOT add: height, lineHeight, overflow, display, padding, margin,
+ *    position, transform to .cm-stickyscroll-line or .cm-stickyscroll-inner.
+ *    Plugin.ts owns those — any CSS here will conflict.
+ * ⛔ Do NOT add syntaxHighlighting — token colors come from the consumer's theme.
+ */
+export const stickyScrollBaseTheme = EditorView.baseTheme({
+    // Container background fallback — JS overrides with exact editor color.
+    ".cm-stickyscroll-container": {
+        position: "absolute",
+        top: 0,
+        left: 0,
+        right: 0,
+        zIndex: 10,
+        overflow: "hidden",
+        boxSizing: "border-box",
+        fontFamily: "monospace",
+        tabSize: 4,
+        borderBottom: "1px solid rgba(128,128,128,.2)",
+        boxShadow: "0 2px 4px var(--cm-stickyscroll-shadow)",
+    },
+    "&light .cm-stickyscroll-container": {
+        "--cm-stickyscroll-shadow": "rgba(0,0,0,.12)",
+    },
+    "&dark .cm-stickyscroll-container": {
+        "--cm-stickyscroll-shadow": "rgba(255,255,255,.12)",
+    },
+    ".cm-stickyscroll-line": {
+        position: "relative",
+        overflow: "hidden",
+        whiteSpace: "pre",
+        boxSizing: "border-box",
+        cursor: "pointer",
+        // Current scope indicator (left accent bar — same as VSCode).
+        "&.cm-stickyscroll-current": {
+            backgroundColor: "rgba(128,128,128,.07)",
+            boxShadow: "inset 3px 0 0 #4b9edd",
+        },
+        "&:hover": {
+            backgroundColor: "rgba(128,128,128,.09)",
+        },
+    },
+    // Gutter cosmetics — position/size are inline from plugin.ts.
+    ".cm-stickyscroll-gutter": {
+        position: "absolute",
+        top: 0,
+        insetInlineStart: 0,
+        zIndex: 1,
+        display: "flex",
+        alignItems: "stretch",
+        boxSizing: "border-box",
+        WebkitUserSelect: "none",
+        userSelect: "none",
+        borderInlineEnd: "1px solid rgba(128,128,128,.18)",
+        opacity: 0.55,
+    },
+    ".cm-stickyscroll-code": {
+        padding: "0 2px 0 6px",
+    },
+});

package/dist/types.d.ts

@@ -0,0 +1,21 @@
+/**
+ * A single sticky breadcrumb row shown in the sticky bar.
+ *
+ * Each entry describes the *opening line* of a scope block (function, class,
+ * if/loop block, ...) whose opening line has scrolled out above the viewport
+ * while its closing line is still at/below the viewport.
+ */
+export interface StickyLine {
+    /** 1-based line number of the opening line. */
+    lineNumber: number;
+    /** Position of the start of the opening line. Used for click-to-jump + selection. */
+    from: number;
+    /** Position of the end of the opening line. */
+    to: number;
+    /** Full text of the opening line (leading indentation preserved). */
+    text: string;
+    /** Start position of the whole foldable scope node (e.g. `function` keyword). */
+    nodeFrom: number;
+    /** End position of the whole foldable scope node (e.g. closing brace). */
+    nodeTo: number;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,52 @@
+{
+	"name": "@bhsd/codemirror-stickyscroll",
+	"version": "0.1.0",
+	"description": "VS Code / Monaco-style sticky scroll (sticky lines) extension for CodeMirror 6",
+	"keywords": [
+		"codemirror",
+		"sticky"
+	],
+	"homepage": "https://github.com/bhsd-harry/stickyscroll#readme",
+	"bugs": {
+		"url": "https://github.com/bhsd-harry/stickyscroll/issues"
+	},
+	"license": "MIT",
+	"contributors": [
+		"[Zulfazli (Fazelllyyy)](https://github.com/fazelllyyy)",
+		"Bhsd"
+	],
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/bhsd-harry/codemirror-stickyscroll.git"
+	},
+	"type": "module",
+	"files": [
+		"/dist/"
+	],
+	"main": "dist/index.js",
+	"types": "dist/index.d.ts",
+	"sideEffects": false,
+	"scripts": {
+		"prepublishOnly": "npm run build",
+		"lint:ts": "tsc --noEmit && eslint --cache .",
+		"lint:md": "markdownlint-cli2 '**/*.md'",
+		"lint:css": "stylelint --cache '**/*.css'",
+		"lint": "npm run lint:ts && npm run lint:css && npm run lint:md",
+		"build": "tsc && eslint --no-inline-config --no-config-lookup -c eslint.dist.js dist/*.js"
+	},
+	"peerDependencies": {
+		"@codemirror/language": "^6.3.0",
+		"@codemirror/state": "^6.0.0",
+		"@codemirror/view": "^6.0.0"
+	},
+	"devDependencies": {
+		"@bhsd/code-standard": "^4.1.0",
+		"@codemirror/language": "^6.12.4",
+		"@codemirror/state": "^6.7.1",
+		"@codemirror/view": "^6.43.9",
+		"eslint": "^10.9.1",
+		"markdownlint-cli2": "^0.23.2",
+		"stylelint": "^17.14.1",
+		"typescript": "^6.0.3"
+	}
+}