From 61033a99bbb581bacb0e7b6f39a359377e0865f7 Mon Sep 17 00:00:00 2001 From: Trillium Smith Date: Tue, 7 Jul 2026 16:16:50 -0700 Subject: [PATCH 01/53] feat(command-visualizer): vendor cursorless hat-allocation algorithm Self-contained copy of cursorless's allocateHats subgraph (chooseTokenHat, getHatRankingContext, HatMetrics, getTokenComparator, maxByFirstDiffering) at SHA 42452eb, plus a grapheme splitter and a tokens-in ranking wrapper. Vendored because the algorithm is not exported from any cursorless library entry point; see VENDOR.md. Byte-identical hat assignments, no IDE dep. --- .../src/vendor/allocate-hats/VENDOR.md | 39 +++ .../allocate-hats/common/CompositeKeyMap.ts | 48 +++ .../vendor/allocate-hats/common/DefaultMap.ts | 33 ++ .../src/vendor/allocate-hats/common/index.ts | 3 + .../src/vendor/allocate-hats/common/types.ts | 105 ++++++ .../src/vendor/allocate-hats/index.ts | 313 ++++++++++++++++++ .../src/vendor/allocate-hats/rank.ts | 46 +++ .../src/vendor/allocate-hats/splitter.ts | 96 ++++++ .../vendor/allocate-hats/vendor/HatMetrics.ts | 116 +++++++ .../allocate-hats/vendor/chooseTokenHat.ts | 86 +++++ .../vendor/getHatRankingContext.ts | 81 +++++ .../vendor/getTokenComparator.ts | 46 +++ .../vendor/maxByFirstDiffering.ts | 75 +++++ 13 files changed, 1087 insertions(+) create mode 100644 packages/command-visualizer/src/vendor/allocate-hats/VENDOR.md create mode 100644 packages/command-visualizer/src/vendor/allocate-hats/common/CompositeKeyMap.ts create mode 100644 packages/command-visualizer/src/vendor/allocate-hats/common/DefaultMap.ts create mode 100644 packages/command-visualizer/src/vendor/allocate-hats/common/index.ts create mode 100644 packages/command-visualizer/src/vendor/allocate-hats/common/types.ts create mode 100644 packages/command-visualizer/src/vendor/allocate-hats/index.ts create mode 100644 packages/command-visualizer/src/vendor/allocate-hats/rank.ts create mode 100644 packages/command-visualizer/src/vendor/allocate-hats/splitter.ts create mode 100644 packages/command-visualizer/src/vendor/allocate-hats/vendor/HatMetrics.ts create mode 100644 packages/command-visualizer/src/vendor/allocate-hats/vendor/chooseTokenHat.ts create mode 100644 packages/command-visualizer/src/vendor/allocate-hats/vendor/getHatRankingContext.ts create mode 100644 packages/command-visualizer/src/vendor/allocate-hats/vendor/getTokenComparator.ts create mode 100644 packages/command-visualizer/src/vendor/allocate-hats/vendor/maxByFirstDiffering.ts diff --git a/packages/command-visualizer/src/vendor/allocate-hats/VENDOR.md b/packages/command-visualizer/src/vendor/allocate-hats/VENDOR.md new file mode 100644 index 0000000000..549369d591 --- /dev/null +++ b/packages/command-visualizer/src/vendor/allocate-hats/VENDOR.md @@ -0,0 +1,39 @@ +# Vendored: allocate-hats + +Internalized copy of the `allocate-hats` package's `src/` tree. + +- **Source repo:** github.com/trillium/allocate-hats +- **Vendored commit / SHA:** `42452eb` (recorded in the source headers; this is + also the cursorless SHA `42452eba521bb9cccbb3e04a2cd9e9afcf6cbffe` whose + `allocateHats` subgraph these files vendor, proven byte-identical to the + shipped prose-overlay bundle). +- **Why internalized:** `allocate-hats@0.1.0` is unpublished (npm has no such + package; it lived only at `~/code/allocate-hats`). Vendoring lets + `@cursorless/command-visualizer` compile in-monorepo with zero external deps. + +## What was copied vs. dropped + +Copied verbatim (the allocation core our package actually uses): + +- `index.ts` — public entry (`allocateHats`, `StandaloneGraphemeSplitter`, + `HatStyleMap`, style-map builders). +- `rank.ts`, `splitter.ts` +- `common/` — `types.ts`, `index.ts`, `CompositeKeyMap.ts`, `DefaultMap.ts` +- `vendor/` — `chooseTokenHat.ts`, `getHatRankingContext.ts`, + `getTokenComparator.ts`, `HatMetrics.ts`, `maxByFirstDiffering.ts` + +Dropped during vendoring (unused by this package — grep-confirmed no importers +in `src/`, and nothing inside the vendored tree imports them): + +- `bundle.ts` — QuickJS IIFE entry (exposes API on `globalThis`). +- `proseCompat.ts` — prose-overlay legacy JSON-in/JSON-out compatibility API. + +## Consumer + +`src/hat-allocator.ts` imports `allocateHats`, `StandaloneGraphemeSplitter`, +and the `HatStyleMap` type from `./vendor/allocate-hats/index`. + +## Updating + +Re-copy `~/code/allocate-hats/src/`, then re-drop `bundle.ts` and +`proseCompat.ts`, and bump the SHA above. diff --git a/packages/command-visualizer/src/vendor/allocate-hats/common/CompositeKeyMap.ts b/packages/command-visualizer/src/vendor/allocate-hats/common/CompositeKeyMap.ts new file mode 100644 index 0000000000..fb7e82472a --- /dev/null +++ b/packages/command-visualizer/src/vendor/allocate-hats/common/CompositeKeyMap.ts @@ -0,0 +1,48 @@ +/** + * Vendored verbatim from cursorless packages/common/src/util/CompositeKeyMap.ts + * at SHA 42452eba521bb9cccbb3e04a2cd9e9afcf6cbffe. No edits below this header. + */ + +/** + * A map that can use a composite key, i.e. a key that is an array or object. + * The key is hashed by running {@link hashFunction}, which is expected to + * output a list whose entries can be converted to string. + * + * Based on https://stackoverflow.com/a/54523103 + */ +export class CompositeKeyMap { + private map: Record = {}; + + /** + * + * @param hashFunction A function that maps from a key to a list whose entries can be converted to string + */ + constructor(private hashFunction: (key: K) => unknown[]) {} + + private hash(key: K): string { + return this.hashFunction(key).join("\u0000"); + } + + set(key: K, item: V): this { + this.map[this.hash(key)] = item; + return this; + } + + has(key: K): boolean { + return this.hash(key) in this.map; + } + + get(key: K): V | undefined { + return this.map[this.hash(key)]; + } + + delete(key: K): this { + delete this.map[this.hash(key)]; + return this; + } + + clear(): this { + this.map = {}; + return this; + } +} diff --git a/packages/command-visualizer/src/vendor/allocate-hats/common/DefaultMap.ts b/packages/command-visualizer/src/vendor/allocate-hats/common/DefaultMap.ts new file mode 100644 index 0000000000..9e1b215653 --- /dev/null +++ b/packages/command-visualizer/src/vendor/allocate-hats/common/DefaultMap.ts @@ -0,0 +1,33 @@ +/** + * Vendored verbatim from cursorless packages/common/src/util/DefaultMap.ts + * at SHA 42452eba521bb9cccbb3e04a2cd9e9afcf6cbffe. + * One edit: `export default class` -> `export class` (this package uses + * named exports throughout). + */ + +/** + * A map that returns a default value when a key is not found. + * + * Based on https://aaronmoat.com/implementing-pythons-defaultdict-in-javascript/ + */ +export class DefaultMap extends Map { + /** + * @param getDefaultValue A function that returns the default value for a given key + */ + constructor(private getDefaultValue: (key: K) => V) { + super(); + } + + get(key: K): V { + const currentValue = super.get(key); + + if (currentValue != null) { + return currentValue; + } + + const value = this.getDefaultValue(key); + this.set(key, value); + + return value; + } +} diff --git a/packages/command-visualizer/src/vendor/allocate-hats/common/index.ts b/packages/command-visualizer/src/vendor/allocate-hats/common/index.ts new file mode 100644 index 0000000000..30bf1a433e --- /dev/null +++ b/packages/command-visualizer/src/vendor/allocate-hats/common/index.ts @@ -0,0 +1,3 @@ +export * from "./types"; +export { CompositeKeyMap } from "./CompositeKeyMap"; +export { DefaultMap } from "./DefaultMap"; diff --git a/packages/command-visualizer/src/vendor/allocate-hats/common/types.ts b/packages/command-visualizer/src/vendor/allocate-hats/common/types.ts new file mode 100644 index 0000000000..75492782cd --- /dev/null +++ b/packages/command-visualizer/src/vendor/allocate-hats/common/types.ts @@ -0,0 +1,105 @@ +/** + * Minimal type surface extracted from @cursorless/common at cursorless SHA + * 42452eba521bb9cccbb3e04a2cd9e9afcf6cbffe (the pinned SHA all three delivery + * substrates already build against). + * + * Position and Range are deliberately SIMPLIFIED: the allocation path only + * ever constructs them and reads `.line` / `.character` / `.start` / `.end`. + * Upstream's method surface (isEqual, union, toSelection, ...) is unused by + * the allocator and omitted. Token / TokenHat / HatStyleMap match upstream + * shapes field-for-field. + */ + +export class Position { + constructor( + public readonly line: number, + public readonly character: number, + ) {} +} + +export class Range { + readonly start: Position; + readonly end: Position; + + constructor(start: Position, end: Position) { + this.start = start; + this.end = end; + } +} + +export interface RangeOffsets { + start: number; + end: number; +} + +/** + * The allocator never dereferences the editor beyond `id` (used as part of + * the CompositeKeyMap token identity key). + */ +export interface MinimalEditor { + id: string; +} + +/** Mirrors @cursorless/common types/Token.ts */ +export interface Token { + editor: MinimalEditor; + range: Range; + offsets: RangeOffsets; + text: string; +} + +export type HatStyleName = string; + +/** Mirrors @cursorless/common types/HatTokenMap.ts TokenHat */ +export interface TokenHat { + hatStyle: HatStyleName; + grapheme: string; + token: Token; + hatRange: Range; +} + +export type HatStyleMap = Record; + +/** + * Mirrors @cursorless/common ide/types/HatStability.ts — string enum values + * are load-bearing (callers pass the raw strings across JSON boundaries). + */ +export enum HatStability { + greedy = "greedy", + balanced = "balanced", + stable = "stable", +} + +/** Mirrors the grapheme shape produced by cursorless's TokenGraphemeSplitter */ +export interface Grapheme { + text: string; + tokenStartOffset: number; + tokenEndOffset: number; +} + +/** + * Structural stand-in for cursorless's TokenGraphemeSplitter — the ranking + * context only calls `getTokenGraphemes`. + */ +export interface GraphemeSplitter { + getTokenGraphemes(tokenText: string): Grapheme[]; +} + +/** + * Mirrors HatCandidate from cursorless-engine util/allocateHats/allocateHats.ts + */ +export interface HatCandidate { + grapheme: Grapheme; + style: HatStyleName; + penalty: number; +} + +/** Mirrors RankedToken from util/allocateHats/getRankedTokens.ts */ +export interface RankedToken { + token: Token; + /** + * Higher rank = more likely to be used = gets a better hat. Upstream uses + * rank = -sortedIndex (0 is best, increasingly negative is worse). + */ + rank: number; +} diff --git a/packages/command-visualizer/src/vendor/allocate-hats/index.ts b/packages/command-visualizer/src/vendor/allocate-hats/index.ts new file mode 100644 index 0000000000..84a9e4e7a2 --- /dev/null +++ b/packages/command-visualizer/src/vendor/allocate-hats/index.ts @@ -0,0 +1,313 @@ +/** + * allocate-hats — standalone Cursorless hat allocation with a tokens-in + * interface. + * + * You bring tokens (already tokenized however your substrate likes); this + * package runs the REAL cursorless allocation algorithm (chooseTokenHat + + * getHatRankingContext + HatMetrics + maxByFirstDiffering, vendored at SHA + * 42452eba521bb9cccbb3e04a2cd9e9afcf6cbffe) and returns hat assignments. + * + * Language support is upstream of allocation by design: languageId appears + * nowhere in the allocator (verified across cursorless, prose-overlay, + * Touchless, cursorless-css-state — brain-1uh8e §4). Tokenize with whatever + * language machinery you have; allocation is language-blind. + */ + +import { + CompositeKeyMap, + DefaultMap, + HatStability, + type HatCandidate, + type HatStyleMap, + type HatStyleName, + Position, + Range, + type RankedToken, + type Token, + type TokenHat, +} from "./common"; +import { chooseTokenHat } from "./vendor/chooseTokenHat"; +import { getHatRankingContext } from "./vendor/getHatRankingContext"; +import { rankTokensByProximity } from "./rank"; +import { StandaloneGraphemeSplitter } from "./splitter"; + +export { HatStability } from "./common"; +export type { HatStyleMap, HatStyleName } from "./common"; +export { StandaloneGraphemeSplitter, deburr } from "./splitter"; + +// --------------------------------------------------------------------------- +// Public input/output types +// --------------------------------------------------------------------------- + +export interface InputToken { + /** The token's text. Graphemes are derived internally by the splitter. */ + text: string; + /** + * Optional explicit rank: HIGHER = more important = better hat. When every + * token carries a rank, ranks are used as-is. When any token omits it, all + * ranks are derived from cursor proximity instead (see + * {@link AllocateHatsOptions.cursorIndex}). + */ + rank?: number; + /** + * Optional document position for multi-line proximity ranking (touchless / + * css-state style inputs). When omitted, the token sits at line 0, + * character = its array index (the single-line prose model). + */ + position?: { line: number; character: number }; +} + +export interface HatAssignment { + /** Index into the input tokens array. */ + tokenIdx: number; + /** Character offset of the hatted grapheme within the token text. */ + charIdx: number; + /** The normalized grapheme the hat sits on. */ + grapheme: string; + /** Full style name, e.g. "blue" or "blue-frame". */ + styleName: string; +} + +export interface AllocateHatsOptions { + tokens: InputToken[]; + /** + * Hat assignments from the previous allocation — pass these back each + * recompute to get hat stability (hats stay put as the buffer changes). + */ + oldAssignments?: HatAssignment[]; + /** Keep/steal trade-off. Default: balanced (cursorless's default). */ + stability?: HatStability | "greedy" | "balanced" | "stable"; + /** + * Enabled hat styles with penalties (lower penalty = preferred). Defaults + * to {@link buildColorStyles} — 9 colors, no shapes. + */ + enabledHatStyles?: HatStyleMap; + /** + * Used only when explicit per-token ranks are absent: tokens are ranked by + * proximity to this gap index (0 = before first token, N = after last). + * Defaults to tokens.length (end-biased), matching prose-overlay's + * no-cursor behavior. Ignored when {@link cursorPosition} is set. + */ + cursorIndex?: number; + /** + * Multi-line variant of {@link cursorIndex}: the reference position tokens + * are ranked against (closest = best hat), for use with + * {@link InputToken.position}. Ranking is |displayLine delta| then + * |character delta| — cursorless's getTokenComparator, vendored. + */ + cursorPosition?: { line: number; character: number }; +} + +// --------------------------------------------------------------------------- +// Default style maps (prose-overlay palette; matches cursorless's color set) +// --------------------------------------------------------------------------- + +export const HAT_COLORS = [ + "gray", + "blue", + "green", + "red", + "pink", + "yellow", + "purple", + "black", + "white", +] as const; + +export const HAT_COLOR_PENALTIES: Record = { + gray: 0, + blue: 1, + green: 1, + red: 1, + pink: 2, + yellow: 2, + purple: 2, + black: 3, + white: 3, +}; + +/** + * Shape suffix vocabulary — mirrors cursorless HAT_NON_DEFAULT_SHAPES + * (packages/common/src/types/command/legacy/targetDescriptorV2.types.ts). + */ +export const HAT_SHAPES = [ + "ex", + "fox", + "wing", + "hole", + "frame", + "curve", + "eye", + "play", + "bolt", + "crosshairs", +] as const; + +/** 9-entry color-only style map. */ +export function buildColorStyles(): HatStyleMap { + const out: HatStyleMap = {}; + for (const color of HAT_COLORS) { + out[color] = { penalty: HAT_COLOR_PENALTIES[color] }; + } + return out; +} + +/** + * Full 99-entry color x (no-shape + 10 shapes) map. Shape adds +1 to the + * color's penalty, matching the upstream convention that each style + * component contributes to total penalty. + */ +export function buildColorShapeStyles(): HatStyleMap { + const out: HatStyleMap = {}; + for (const color of HAT_COLORS) { + const colorPenalty = HAT_COLOR_PENALTIES[color]; + out[color] = { penalty: colorPenalty }; + for (const shape of HAT_SHAPES) { + out[`${color}-${shape}`] = { penalty: colorPenalty + 1 }; + } + } + return out; +} + +// --------------------------------------------------------------------------- +// Internal: token construction + ranking +// --------------------------------------------------------------------------- + +const FAKE_EDITOR = { id: "allocate-hats" }; + +function makeToken(input: InputToken, index: number): Token { + const line = input.position?.line ?? 0; + const character = input.position?.character ?? index; + const start = new Position(line, character); + const end = new Position(line, character + 1); + return { + editor: FAKE_EDITOR, + text: input.text, + // offsets.start doubles as the stable token identity (= input index); + // range carries the (possibly caller-supplied) document position used + // for proximity ranking. + range: new Range(start, end), + offsets: { start: index, end: index + 1 }, + }; +} + +/** + * getTokenRemainingHatCandidates — copied from cursorless allocateHats.ts + * (unexported upstream; same copy prose-overlay's proseStandalone.ts carries). + */ +function getTokenRemainingHatCandidates( + splitter: StandaloneGraphemeSplitter, + token: Token, + graphemeRemainingHatCandidates: DefaultMap, + enabledHatStyles: HatStyleMap, +): HatCandidate[] { + const candidates: HatCandidate[] = []; + const graphemes = splitter.getTokenGraphemes(token.text); + for (const grapheme of graphemes) { + for (const style of graphemeRemainingHatCandidates.get(grapheme.text)) { + candidates.push({ + grapheme, + style, + penalty: enabledHatStyles[style]?.penalty ?? 99, + }); + } + } + return candidates; +} + +// --------------------------------------------------------------------------- +// Main entry point +// --------------------------------------------------------------------------- + +export function allocateHats(options: AllocateHatsOptions): HatAssignment[] { + const { + tokens, + oldAssignments = [], + stability = HatStability.balanced, + enabledHatStyles = buildColorStyles(), + cursorIndex, + cursorPosition, + } = options; + + const hatStability = stability as HatStability; + const splitter = new StandaloneGraphemeSplitter(); + const enabledHatStyleNames = Object.keys(enabledHatStyles); + + const tokenObjects = tokens.map((t, i) => makeToken(t, i)); + + // Ranking: explicit ranks when every token has one, else proximity to the + // reference position (cursorPosition, or gap cursorIndex on line 0 — + // defaulting to end-biased, matching prose-overlay's no-cursor behavior). + const allRanked = tokens.every((t) => typeof t.rank === "number"); + const referencePosition = cursorPosition + ? new Position(cursorPosition.line, cursorPosition.character) + : new Position(0, cursorIndex ?? tokens.length); + const rankedTokens: RankedToken[] = allRanked + ? tokens.map((t, i) => ({ token: tokenObjects[i], rank: t.rank! })) + : rankTokensByProximity(tokenObjects, referencePosition); + + // Old hat map for stability. + const tokenOldHatMap = new CompositeKeyMap( + ({ editor, offsets }) => [editor.id, offsets.start, offsets.end], + ); + for (const { tokenIdx, grapheme, styleName } of oldAssignments) { + if (tokenIdx >= 0 && tokenIdx < tokens.length) { + const token = tokenObjects[tokenIdx]; + tokenOldHatMap.set(token, { + hatStyle: styleName, + grapheme, + token, + hatRange: token.range, + }); + } + } + + const context = getHatRankingContext(rankedTokens, tokenOldHatMap, splitter); + + const graphemeRemainingHatCandidates = new DefaultMap( + () => [...enabledHatStyleNames], + ); + + // Process tokens in descending rank order (best tokens first). + const sortedRanked = [...rankedTokens].sort((a, b) => b.rank - a.rank); + const result: HatAssignment[] = []; + + for (const { token, rank } of sortedRanked) { + const candidates = getTokenRemainingHatCandidates( + splitter, + token, + graphemeRemainingHatCandidates, + enabledHatStyles, + ); + + const chosen = chooseTokenHat( + context, + hatStability, + rank, + tokenOldHatMap.get(token), + candidates, + ); + + if (chosen == null) { + continue; + } + + // Remove the chosen hat from candidates for lower-ranked tokens. + graphemeRemainingHatCandidates.set( + chosen.grapheme.text, + graphemeRemainingHatCandidates + .get(chosen.grapheme.text) + .filter((s) => s !== chosen.style), + ); + + result.push({ + tokenIdx: token.offsets.start, + charIdx: chosen.grapheme.tokenStartOffset, + grapheme: chosen.grapheme.text, + styleName: String(chosen.style), + }); + } + + result.sort((a, b) => a.tokenIdx - b.tokenIdx); + return result; +} diff --git a/packages/command-visualizer/src/vendor/allocate-hats/rank.ts b/packages/command-visualizer/src/vendor/allocate-hats/rank.ts new file mode 100644 index 0000000000..c6e937b9e8 --- /dev/null +++ b/packages/command-visualizer/src/vendor/allocate-hats/rank.ts @@ -0,0 +1,46 @@ +/** + * Port of `rankPreTokenizedInput` from cursorless + * packages/cursorless-engine/src/util/allocateHats/getRankedTokens.ts at SHA + * 42452eba521bb9cccbb3e04a2cd9e9afcf6cbffe, with the fake-editor plumbing + * removed: the reference cursor position is a plain argument instead of + * `activeTextEditor.selections[0].active`. The display-line map construction, + * the comparator (vendored getTokenComparator), and the rank = -sortedIndex + * convention are unchanged. + */ + +import { Position, type RankedToken, type Token } from "./common"; +import { getTokenComparator } from "./vendor/getTokenComparator"; + +export function rankTokensByProximity( + tokens: readonly Token[], + referencePosition: Position, +): RankedToken[] { + if (tokens.length === 0) { + return []; + } + + // Build a stable display-line map directly from the supplied tokens so the + // comparator sees a consistent ordering even without an editor walk. + const lines = new Set([referencePosition.line]); + for (const token of tokens) { + lines.add(token.range.start.line); + } + const sortedLines = [...lines].sort((a, b) => a - b); + const displayLineMap = new Map( + sortedLines.map((line, index) => [line, index]), + ); + + const withDisplayLine = tokens.map((token) => ({ + ...token, + displayLine: displayLineMap.get(token.range.start.line)!, + })); + + withDisplayLine.sort( + getTokenComparator( + displayLineMap.get(referencePosition.line)!, + referencePosition.character, + ), + ); + + return withDisplayLine.map((token, index) => ({ token, rank: -index })); +} diff --git a/packages/command-visualizer/src/vendor/allocate-hats/splitter.ts b/packages/command-visualizer/src/vendor/allocate-hats/splitter.ts new file mode 100644 index 0000000000..fc62f972ea --- /dev/null +++ b/packages/command-visualizer/src/vendor/allocate-hats/splitter.ts @@ -0,0 +1,96 @@ +/** + * Standalone grapheme splitter — lifted from proseStandalone.ts in the + * cursorless fork (SHA 42452eba521bb9cccbb3e04a2cd9e9afcf6cbffe), which in + * turn mirrors the canonical splitter at + * packages/cursorless-engine/src/tokenGraphemeSplitter/tokenGraphemeSplitter.ts:74 + * with a STATIC config (no ide().configuration): no lettersToPreserve / + * symbolsToPreserve user overrides. + */ + +import type { Grapheme, GraphemeSplitter } from "./common/types"; + +/** + * Inline deburr — strips combining diacritics after NFC normalization. + * Replaces lodash.deburr to keep the bundle free of lodash (whose CommonJS + * module blows QuickJS's call stack). + */ +export function deburr(str: string): string { + return ( + str + .normalize("NFC") + // eslint-disable-next-line no-misleading-character-class + .replace(/[\u0300-\u036f\u1dc0-\u1dff\u20d0-\u20ff\ufe20-\ufe2f]/g, "") + ); +} + +const KNOWN_SYMBOLS = [ + "!", + "#", + "$", + "%", + "&", + "'", + "(", + ")", + "*", + "+", + ",", + "-", + ".", + "/", + ":", + ";", + "<", + "=", + ">", + "?", + "@", + "[", + "\\", + "]", + "^", + "_", + "`", + "{", + "|", + "}", + "~", + "£", + '"', +]; +const UNKNOWN_GRAPHEME = "[unk]"; +const KNOWN_GRAPHEME_MATCHER = new RegExp( + `^([a-zA-Z0-9]|${KNOWN_SYMBOLS.map((s) => + s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"), + ).join("|")})$`, + "u", +); + +// Letters + combining marks OR any single Unicode Number / Punctuation / Symbol. +const GRAPHEME_SPLIT_SOURCE = String.raw`\p{L}\p{M}*|[\p{N}\p{P}\p{S}]`; +const GRAPHEME_SPLIT_FLAGS = "gu"; + +export class StandaloneGraphemeSplitter implements GraphemeSplitter { + getTokenGraphemes(tokenText: string): Grapheme[] { + const re = new RegExp(GRAPHEME_SPLIT_SOURCE, GRAPHEME_SPLIT_FLAGS); + const results: Grapheme[] = []; + let match: RegExpExecArray | null; + while ((match = re.exec(tokenText)) != null) { + results.push({ + text: this.normalizeGrapheme(match[0]), + tokenStartOffset: match.index, + tokenEndOffset: match.index + match[0].length, + }); + } + return results; + } + + normalizeGrapheme(raw: string): string { + let val = raw.normalize("NFC").toLowerCase(); + val = deburr(val); + if (!KNOWN_GRAPHEME_MATCHER.test(val)) { + val = UNKNOWN_GRAPHEME; + } + return val; + } +} diff --git a/packages/command-visualizer/src/vendor/allocate-hats/vendor/HatMetrics.ts b/packages/command-visualizer/src/vendor/allocate-hats/vendor/HatMetrics.ts new file mode 100644 index 0000000000..0ec2dffd88 --- /dev/null +++ b/packages/command-visualizer/src/vendor/allocate-hats/vendor/HatMetrics.ts @@ -0,0 +1,116 @@ +/** + * Vendored from cursorless packages/cursorless-engine/src/util/allocateHats/HatMetrics.ts + * at SHA 42452eba521bb9cccbb3e04a2cd9e9afcf6cbffe. + * Edits are IMPORT REWRITES ONLY (applied by scripts/vendor.sh): + * - "@cursorless/common" -> "../common" barrel + * - HatCandidate: "./allocateHats" -> "../common/types" + */ + +import { CompositeKeyMap, HatStability, TokenHat } from "../common"; + +// Inline replacements for lodash memoize and min — avoids bundling the full +// lodash CommonJS module (5,500 lines) which blows QuickJS's call stack. +function memoize( + fn: (arg: T) => R, +): (arg: T) => R { + const cache = new Map(); + return (arg: T) => { + if (!cache.has(arg)) { + cache.set(arg, fn(arg)); + } + return cache.get(arg)!; + }; +} +function min(arr: number[]): number | undefined { + return arr.length ? Math.min(...arr) : undefined; +} +import { HatCandidate } from "../common/types"; + +/** + * A function that takes a hat candidate and returns a number representing its + * quality; greater is always better + */ +export type HatMetric = (hat: HatCandidate) => number; + +/** + * @returns A metric that just returns the negative penalty of the given hat + * candidate + */ +export const negativePenalty: HatMetric = ({ penalty }) => -penalty; + +/** + * @param hatOldTokenRanks A map from a hat candidate (grapheme+style combination) to the score of the + * token that used the given hat in the previous hat allocation. + * @returns A metric that returns Infinity if the hat candidate is not in use in + * the old allocation, otherwise the rank of the token from the old allocation + * that we'd steal the hat from + */ +export function hatOldTokenRank( + hatOldTokenRanks: CompositeKeyMap< + { grapheme: string; hatStyle: string }, + number + >, +): HatMetric { + return ({ grapheme: { text: grapheme }, style }) => { + const hatOldTokenRank = hatOldTokenRanks.get({ + grapheme, + hatStyle: style, + }); + + return hatOldTokenRank == null ? Infinity : -hatOldTokenRank; + }; +} + +/** + * @param tokenRank The rank of the current token, so that we don't consider + * higher ranked tokens (which already have been assigned hats) + * @param graphemeTokenRanks A map from graphemes to an ordered list of the + * ranks of tokens containing the grapheme + * @returns A metric which returns the minimum token rank among lower ranked + * tokens that contain the hat's grapheme (or Infinity if the grapheme doesn't + * appear in any lower ranked tokens) + */ +export function minimumTokenRankContainingGrapheme( + tokenRank: number, + graphemeTokenRanks: { [key: string]: number[] }, +): HatMetric { + const coreMetric = memoize((graphemeText: string): number => { + return ( + min(graphemeTokenRanks[graphemeText].filter((r) => r > tokenRank)) ?? + Infinity + ); + }); + return ({ grapheme: { text } }) => coreMetric(text); +} + +/** + * @param oldTokenHat The old hat for the token to which we're assigning a hat + * @returns A metric which returns 1 if the hat candidate is the one the token + * currently has, 0 otherwise + */ +export function isOldTokenHat(oldTokenHat: TokenHat | undefined): HatMetric { + return (hat) => + hat.grapheme.text === oldTokenHat?.grapheme && + hat.style === oldTokenHat?.hatStyle + ? 1 + : 0; +} + +/** + * Given a {@link HatStability}, returns its equivalence class function. + * + * @param HatStability The user setting for which we need to return + * equivalence class + * @returns A hat metric that will collapse hats that are not different enough + * to justify keeping / stealing + */ +export function penaltyEquivalenceClass(hatStability: HatStability): HatMetric { + switch (hatStability) { + case HatStability.greedy: + return ({ penalty }) => -penalty; + case HatStability.balanced: + return ({ penalty }) => -(penalty < 2 ? 0 : 1); + case HatStability.stable: + return (_) => 0; + } +} diff --git a/packages/command-visualizer/src/vendor/allocate-hats/vendor/chooseTokenHat.ts b/packages/command-visualizer/src/vendor/allocate-hats/vendor/chooseTokenHat.ts new file mode 100644 index 0000000000..b14af67b81 --- /dev/null +++ b/packages/command-visualizer/src/vendor/allocate-hats/vendor/chooseTokenHat.ts @@ -0,0 +1,86 @@ +/** + * Vendored from cursorless packages/cursorless-engine/src/util/allocateHats/chooseTokenHat.ts + * at SHA 42452eba521bb9cccbb3e04a2cd9e9afcf6cbffe. + * Edits are IMPORT REWRITES ONLY (applied by scripts/vendor.sh): + * - "@cursorless/common" -> "../common" barrel + * - HatCandidate: "./allocateHats" -> "../common/types" + */ + +import { HatStability, TokenHat } from "../common"; +import { HatCandidate } from "../common/types"; +import { RankingContext } from "./getHatRankingContext"; +import { + hatOldTokenRank, + isOldTokenHat, + minimumTokenRankContainingGrapheme, + negativePenalty, + penaltyEquivalenceClass, +} from "./HatMetrics"; +import { maxByFirstDiffering } from "./maxByFirstDiffering"; + +/** + * Selects a hat for a given token from amongst {@link candidates}, trading off + * hat quality and hat stability + * + * **IMPORTANT**: This function assumes that all tokens with a lower rank than + * the given token have already been assigned hats. + * + * We proceed as follows: + * + * 1. Decide whether to keep our own hat, if a higher ranked token hasn't + * already taken it + * 2. Decide whether to steal a hat from a lower ranked token + * + * See [hat assignment](/docs/user/hatAssignment) for more info. + * + * FIXME: Could be improved by ignoring subsequent tokens that also contain + * another character that can be used with lower color. To compute that, look at + * all the other characters in the given subsequent token, look at their current + * color, and add the number of times it appears in between the current token + * and the given subsequent token. + * + * Here is an example where the existing algorithm falls down: "ab ax b". It + * will put a hat on `b` for token `ab` because `b` appears two tokens away + * whereas `a` appears in the next token. However, if it had chosen `a`, then + * it could use `x` for `ax`, leaving `b` free for the final `b` token. + * + * @param context Lookup tables with information about which graphemes / hats + * other tokens have + * @param hatStability The user settings that determine when to keep / steal + * hats + * @param tokenRank The rank of the token for whom we're picking a hat + * @param oldTokenHat The hat that was on the token before (or `undefined` if it + * didn't have one) + * @param candidates The set of candidate hats under consideration (includes + * both hat style and grapheme) + * @returns The chosen hat, or `undefined` if {@link candidates} was empty + */ +export function chooseTokenHat( + { hatOldTokenRanks, graphemeTokenRanks }: RankingContext, + hatStability: HatStability, + tokenRank: number, + oldTokenHat: TokenHat | undefined, + candidates: HatCandidate[], +): HatCandidate | undefined { + // We narrow down the candidates by a series of criteria until there is only + // one left + return maxByFirstDiffering(candidates, [ + // 1. Discard any hats that are sufficiently worse than the best hat that we + // wouldn't use them even if they were our old hat + penaltyEquivalenceClass(hatStability), + + // 2. Use our old hat if it's still in the running + isOldTokenHat(oldTokenHat), + + // 3. Use a free hat if possible; if not, steal the hat of the token with + // lowest rank + hatOldTokenRank(hatOldTokenRanks), + + // 4. Narrow to the hats with the lowest penalty + negativePenalty, + + // 5. Prefer hats that sit on a grapheme that doesn't appear in any highly + // ranked token + minimumTokenRankContainingGrapheme(tokenRank, graphemeTokenRanks), + ])!; +} diff --git a/packages/command-visualizer/src/vendor/allocate-hats/vendor/getHatRankingContext.ts b/packages/command-visualizer/src/vendor/allocate-hats/vendor/getHatRankingContext.ts new file mode 100644 index 0000000000..424310fe1d --- /dev/null +++ b/packages/command-visualizer/src/vendor/allocate-hats/vendor/getHatRankingContext.ts @@ -0,0 +1,81 @@ +/** + * Vendored from cursorless packages/cursorless-engine/src/util/allocateHats/getHatRankingContext.ts + * at SHA 42452eba521bb9cccbb3e04a2cd9e9afcf6cbffe. + * Edits are IMPORT REWRITES ONLY (applied by scripts/vendor.sh): + * - "@cursorless/common" -> "../common" barrel + * - TokenGraphemeSplitter (concrete class) -> GraphemeSplitter (structural + * interface in ../common/types with the same getTokenGraphemes surface) + * - RankedToken: "./getRankedTokens" -> "../common/types" + */ + +import { + CompositeKeyMap, + HatStyleName, + Token, + TokenHat, +} from "../common"; +import { GraphemeSplitter } from "../common/types"; +import { RankedToken } from "../common/types"; + +export interface RankingContext { + /** + * Maps from a hat candidate (grapheme+style combination) to the score of the + * token that used the given hat in the previous hat allocation. + */ + hatOldTokenRanks: CompositeKeyMap< + { + grapheme: string; + hatStyle: HatStyleName; + }, + number + >; + + /** + * Maps from a grapheme to the list of ranks of the tokens in which the + * given grapheme appears. + */ + graphemeTokenRanks: { + [key: string]: number[]; + }; +} + +export function getHatRankingContext( + tokens: RankedToken[], + oldTokenHatMap: CompositeKeyMap, + tokenGraphemeSplitter: GraphemeSplitter, +): RankingContext { + const graphemeTokenRanks: { + [key: string]: number[]; + } = {}; + + const hatOldTokenRanks = new CompositeKeyMap< + { grapheme: string; hatStyle: HatStyleName }, + number + >(({ grapheme, hatStyle }) => [grapheme, hatStyle]); + + tokens.forEach(({ token, rank }) => { + const existingTokenHat = oldTokenHatMap.get(token); + if (existingTokenHat != null) { + hatOldTokenRanks.set(existingTokenHat, rank); + } + tokenGraphemeSplitter + .getTokenGraphemes(token.text) + .forEach(({ text: graphemeText }) => { + let tokenRanksForGrapheme: number[]; + + if (graphemeText in graphemeTokenRanks) { + tokenRanksForGrapheme = graphemeTokenRanks[graphemeText]; + } else { + tokenRanksForGrapheme = []; + graphemeTokenRanks[graphemeText] = tokenRanksForGrapheme; + } + + tokenRanksForGrapheme.push(rank); + }); + }); + + return { + hatOldTokenRanks, + graphemeTokenRanks, + }; +} diff --git a/packages/command-visualizer/src/vendor/allocate-hats/vendor/getTokenComparator.ts b/packages/command-visualizer/src/vendor/allocate-hats/vendor/getTokenComparator.ts new file mode 100644 index 0000000000..1aabf0364e --- /dev/null +++ b/packages/command-visualizer/src/vendor/allocate-hats/vendor/getTokenComparator.ts @@ -0,0 +1,46 @@ +/** + * Vendored from cursorless packages/cursorless-engine/src/util/allocateHats/getTokenComparator.ts + * at SHA 42452eba521bb9cccbb3e04a2cd9e9afcf6cbffe. + * Edits are IMPORT REWRITES ONLY (applied by scripts/vendor.sh): + * - "@cursorless/common" -> "../common" barrel + */ + +import { Token } from "../common"; + +interface TokenWithDisplayLine extends Token { + displayLine: number; +} + +/** + * Gets a comparison function that can be used to sort tokens based on their + * distance from the current cursor in terms of display lines. + * @param selectionDisplayLine The display line of the cursor location + * @param selectionCharacterIndex The character index of current cursor within line + */ +export function getTokenComparator( + selectionDisplayLine: number, + selectionCharacterIndex: number, +): (a: TokenWithDisplayLine, b: TokenWithDisplayLine) => number { + return (token1, token2) => { + const token1LineDiff = Math.abs(token1.displayLine - selectionDisplayLine); + const token2LineDiff = Math.abs(token2.displayLine - selectionDisplayLine); + + if (token1LineDiff < token2LineDiff) { + return -1; + } + + if (token1LineDiff > token2LineDiff) { + return 1; + } + + const token1CharacterDiff = Math.abs( + token1.range.start.character - selectionCharacterIndex, + ); + + const token2CharacterDiff = Math.abs( + token2.range.start.character - selectionCharacterIndex, + ); + + return token1CharacterDiff - token2CharacterDiff; + }; +} diff --git a/packages/command-visualizer/src/vendor/allocate-hats/vendor/maxByFirstDiffering.ts b/packages/command-visualizer/src/vendor/allocate-hats/vendor/maxByFirstDiffering.ts new file mode 100644 index 0000000000..a42a4bacbb --- /dev/null +++ b/packages/command-visualizer/src/vendor/allocate-hats/vendor/maxByFirstDiffering.ts @@ -0,0 +1,75 @@ +/** + * Vendored from cursorless packages/cursorless-engine/src/util/allocateHats/maxByFirstDiffering.ts + * at SHA 42452eba521bb9cccbb3e04a2cd9e9afcf6cbffe. + * Edits are IMPORT REWRITES ONLY (applied by scripts/vendor.sh): + * (none — file has no imports) + */ + +/** + * Given an array of items and a list of functions that return a number for each + * item, return the item that has the maximum value according to the + * mathematical lexicographic order. Ie, first narrows down to items that share + * the maximum value for the first function, then of those remaining, narrows + * down to those that have the maximum value for the second, etc. Whenever + * there is only 1 item remaining, that item is returned. If the list is empty, + * undefined is returned. + * + * @example maxByFirstDiffering([{a: 1, b: 1}, {a: 1, b: 2}], [({a}) => a, ({b}) => + * b]) === {a: 1, b: 2} + * + * @param arr The array to find the max value of + * @param fns A list of functions that return a number for each item in the + * array + * @returns The item in the array that has the maximum value, or undefined if + * array is empty or all items are removed + */ +export function maxByFirstDiffering( + arr: T[], + fns: ((item: T) => number)[], +): T | undefined { + if (arr.length === 0) { + return undefined; + } + let remainingValues = arr; + for (const fn of fns) { + if (remainingValues.length === 1) { + return remainingValues[0]; + } + remainingValues = maxByAllowingTies(remainingValues, fn); + } + return remainingValues[0]; +} + +/** + * Given an array of items and a function that returns a number for each item, + * return all items that share the maximum value according to that function. + * @param arr The array to find the max values of + * @param fn A function that returns a number for each item in the array + * @returns All items in the array that share the maximum value + **/ +export function maxByAllowingTies(arr: T[], fn: (item: T) => number): T[] { + // This is equivalent to, but faster than: + // + // const max = Math.max(...arr.map(fn)); + // return arr.filter((item) => fn(item) === max); + // + // It does only a single pass through the array, and allocates no + // intermediate arrays (in the common case). + + // Accumulate all items with the single highest value, + // resetting whenever we find a new highest value. + let best: number = -Infinity; + const keep: T[] = []; + for (const item of arr) { + const value = fn(item); + if (value < best) { + continue; + } + if (value > best) { + best = value; + keep.length = 0; + } + keep.push(item); + } + return keep; +} From 196d0da09128f909f07237ab3d986e15aedc19f9 Mon Sep 17 00:00:00 2001 From: Trillium Smith Date: Tue, 7 Jul 2026 16:16:55 -0700 Subject: [PATCH 02/53] feat(command-visualizer): animated SVG command-cascade renderer New @cursorless/command-visualizer package: pure function from a recorded test fixture (YAML) to a self-contained, -embeddable animated SVG of a cursorless command. Zero runtime JS in the output; one CSS --dur timeline. Fixtures parsed with js-yaml; hat allocation via the vendored algorithm; FlashStyle/color/shape data mirrored from cursorless with provenance notes. --- packages/command-visualizer/package.json | 30 ++ packages/command-visualizer/src/chain.ts | 135 +++++ packages/command-visualizer/src/columns.ts | 180 +++++++ .../command-visualizer/src/css-cascade.ts | 272 ++++++++++ packages/command-visualizer/src/css.ts | 196 +++++++ .../command-visualizer/src/data/colors.ts | 67 +++ .../src/data/decorations.ts | 79 +++ .../command-visualizer/src/data/shapes.ts | 108 ++++ .../command-visualizer/src/fixture-extract.ts | 211 ++++++++ .../command-visualizer/src/fixture-root.ts | 82 +++ .../command-visualizer/src/fixture-yaml.ts | 42 ++ .../command-visualizer/src/frame-state.ts | 68 +++ .../command-visualizer/src/hat-allocator.ts | 175 ++++++ packages/command-visualizer/src/index.ts | 20 + packages/command-visualizer/src/jumbotron.ts | 503 ++++++++++++++++++ packages/command-visualizer/src/overlays.ts | 152 ++++++ packages/command-visualizer/src/pipeline.ts | 319 +++++++++++ .../src/serialize-cascade.ts | 219 ++++++++ packages/command-visualizer/src/serialize.ts | 160 ++++++ packages/command-visualizer/src/svg-wrap.ts | 153 ++++++ packages/command-visualizer/src/symbols.ts | 25 + packages/command-visualizer/src/timeline.ts | 66 +++ packages/command-visualizer/src/tokenize.ts | 96 ++++ .../command-visualizer/src/word-segments.ts | 73 +++ packages/command-visualizer/tsconfig.json | 7 + 25 files changed, 3438 insertions(+) create mode 100644 packages/command-visualizer/package.json create mode 100644 packages/command-visualizer/src/chain.ts create mode 100644 packages/command-visualizer/src/columns.ts create mode 100644 packages/command-visualizer/src/css-cascade.ts create mode 100644 packages/command-visualizer/src/css.ts create mode 100644 packages/command-visualizer/src/data/colors.ts create mode 100644 packages/command-visualizer/src/data/decorations.ts create mode 100644 packages/command-visualizer/src/data/shapes.ts create mode 100644 packages/command-visualizer/src/fixture-extract.ts create mode 100644 packages/command-visualizer/src/fixture-root.ts create mode 100644 packages/command-visualizer/src/fixture-yaml.ts create mode 100644 packages/command-visualizer/src/frame-state.ts create mode 100644 packages/command-visualizer/src/hat-allocator.ts create mode 100644 packages/command-visualizer/src/index.ts create mode 100644 packages/command-visualizer/src/jumbotron.ts create mode 100644 packages/command-visualizer/src/overlays.ts create mode 100644 packages/command-visualizer/src/pipeline.ts create mode 100644 packages/command-visualizer/src/serialize-cascade.ts create mode 100644 packages/command-visualizer/src/serialize.ts create mode 100644 packages/command-visualizer/src/svg-wrap.ts create mode 100644 packages/command-visualizer/src/symbols.ts create mode 100644 packages/command-visualizer/src/timeline.ts create mode 100644 packages/command-visualizer/src/tokenize.ts create mode 100644 packages/command-visualizer/src/word-segments.ts create mode 100644 packages/command-visualizer/tsconfig.json diff --git a/packages/command-visualizer/package.json b/packages/command-visualizer/package.json new file mode 100644 index 0000000000..b31822f858 --- /dev/null +++ b/packages/command-visualizer/package.json @@ -0,0 +1,30 @@ +{ + "name": "@cursorless/command-visualizer", + "version": "0.0.1", + "type": "module", + "description": "Visualizes cursorless commands as animated SVGs: the spoken command entering, flashes firing, the edit landing, hats reallocating — rendered from recorded test fixtures, embeddable via plain .", + "main": "./out/index.js", + "types": "./out/index.d.ts", + "scripts": { + "compile:tsc": "tsc", + "compile:esbuild": "esbuild ./src/index.ts --sourcemap --format=esm --bundle --packages=external --outfile=./out/index.js", + "compile": "pnpm compile:tsc && pnpm compile:esbuild", + "clean": "rm -rf ./out tsconfig.tsbuildinfo ./dist ./build" + }, + "keywords": [ + "cursorless", + "visualization", + "svg", + "fixtures" + ], + "author": "", + "license": "MIT", + "dependencies": { + "@cursorless/lib-common": "workspace:*", + "@cursorless/lib-node-common": "workspace:*", + "js-yaml": "^5.2.1" + }, + "devDependencies": { + "@types/js-yaml": "^4.0.9" + } +} diff --git a/packages/command-visualizer/src/chain.ts b/packages/command-visualizer/src/chain.ts new file mode 100644 index 0000000000..2ce8de0c23 --- /dev/null +++ b/packages/command-visualizer/src/chain.ts @@ -0,0 +1,135 @@ +// Multi-step chain semantics (Trillium's model, 2026-07-07): +// +// every entry: initialState / referenceFlashes[] / finalState +// chained: finalState.i and initialState.{i+1} MUST agree, and the +// hats from initialState.{i+1} flow BACKWARD onto that +// boundary — in cursorless the transition is ONE animated +// change, not two. finalState.i is never rendered with its +// own hats; the merged frame IS initialState.{i+1}. +// +// Frame list for an n-step chain: [before_0, before_1, ..., before_{n-1}, after_{n-1}] +// where each merged frame before_{i+1}: +// - renders step {i+1}'s initialState (hats = its marks + real allocation), +// - inherits step i's AFTER-riding decorations (justAdded flashes, thatMark +// references) — they light at the merged frame's slot START, +// - keeps its own BEFORE-riding decorations (pendingDelete) — they light at +// the merged frame's slot END, +// - carries step i's produced clipboard when step {i+1} has none. + +import type { CascadeState, Frame } from "./frame-state"; + +/** + * Pre-gif / post-gif bumpers: a 500ms PRE frame (initial state, before step 0 + * begins) and a 500ms RESET frame (re-shows the initial state so the infinite + * loop wraps onto identical pixels). Applied to every animated cascade. + */ +export function withBumpers(state: CascadeState): CascadeState { + if (state.frames.length < 2) { + return state; + } + const first = state.frames[0]; + const clone = (flags: Partial): Frame => ({ + role: "after", + lines: first.lines, + cursors: first.cursors, + selections: first.selections, + decorations: [], + clipboard: first.clipboard, + ...flags, + }); + return { + ...state, + frames: [ + clone({ role: "before", pre: true }), + ...state.frames, + clone({ reset: true }), + ], + }; +} + +export class ChainContinuityError extends Error { + constructor( + public stepIndex: number, + message: string, + ) { + super(message); + } +} + +/** Reconstruct a frame's document text from its render tokens (GATE 0 exact). */ +export function frameDocText(frame: Frame): string { + return frame.lines + .map((line) => line.tokens.map((t) => t.text).join("")) + .join("\n"); +} + +/** + * Merge per-step cascades ([before, after] each) into one chain cascade. + * Throws ChainContinuityError when finalState.i !== initialState.{i+1}. + */ +export function chainCascades( + states: CascadeState[], + fixtureLabel: string, +): CascadeState { + if (states.length === 1) { + return states[0]; + } + + const frames: Frame[] = []; + for (let i = 0; i < states.length; i++) { + const step = states[i]; + const before = step.frames.find((f) => f.role === "before"); + const after = step.frames.find((f) => f.role === "after"); + if (!before) { + throw new ChainContinuityError(i, `step ${i} has no before frame`); + } + + if (i > 0) { + const prevAfter = states[i - 1].frames.find((f) => f.role === "after"); + if (!prevAfter) { + throw new ChainContinuityError( + i - 1, + `step ${i - 1} has no finalState to chain from`, + ); + } + const prevDoc = frameDocText(prevAfter); + const thisDoc = frameDocText(before); + if (prevDoc !== thisDoc) { + throw new ChainContinuityError( + i, + `chain discontinuity between steps ${i - 1} and ${i}: ` + + `finalState.${i - 1} and initialState.${i} must agree. ` + + `finalState.${i - 1}=${JSON.stringify(prevDoc).slice(0, 80)} ` + + `initialState.${i}=${JSON.stringify(thisDoc).slice(0, 80)}`, + ); + } + // Backward hat flow: the merged frame IS this step's before (its + // hats). Step i-1's AFTER-riding decorations + clipboard transfer + // onto it; prevAfter itself is never rendered. + before.decorations = [...prevAfter.decorations, ...before.decorations]; + if (before.clipboard == null && prevAfter.clipboard != null) { + before.clipboard = prevAfter.clipboard; + } + } + frames.push(before); + + // The step's DURING phase (pre-edit flash window) rides between its + // initial and the next merged frame. + const during = step.frames.find((f) => f.role === "during"); + if (during) { + frames.push(during); + } + + if (i === states.length - 1) { + if (after) { + frames.push(after); + } + } + } + + return { + ...states[0], + meta: { fixture: fixtureLabel }, + frames, + }; +} diff --git a/packages/command-visualizer/src/columns.ts b/packages/command-visualizer/src/columns.ts new file mode 100644 index 0000000000..356a3dc96a --- /dev/null +++ b/packages/command-visualizer/src/columns.ts @@ -0,0 +1,180 @@ +// Column model — SPEC §2 (resolves D7). +// Converts each line's UTF-16 token stream into an ordered list of VISUAL columns. +// Build-time only; no render-time logic. +// +// - Graphemes per cursorless GRAPHEME_SPLIT_REGEX (SPEC §2.1). +// - Tab → next tabSize stop (SPEC §2.2). +// - East-Asian Wide/Fullwidth glyph = 2 columns (SPEC §2.3). + +import type { HatColor } from "./data/colors"; +import type { HatShape } from "./data/shapes"; + +// Cursorless's grapheme splitter regex +// (tokenGraphemeSplitter.ts:73). A base letter + its combining marks is ONE +// grapheme; numbers/punct/symbols are each their own grapheme. +export const GRAPHEME_SPLIT_REGEX = /\p{L}\p{M}*|[\p{N}\p{P}\p{S}]/gu; + +export interface InputHat { + color: HatColor; + shape: HatShape; + /** grapheme index within the token; default 0 */ + anchorGrapheme?: number; +} + +export interface Token { + text: string; + range: { start: number; end: number }; // UTF-16 offsets within the line + hat?: InputHat | null; +} + +export interface Line { + tokens: Token[]; +} + +/** One emitted visual column (or multi-column cell for a wide glyph / tab). */ +export interface Column { + /** display text for the cell (a grapheme, or "" for blank tab filler) */ + text: string; + /** visual column index (first column of this cell) */ + col: number; + /** number of columns this cell spans (1, 2, or a tab advance) */ + width: number; + /** UTF-16 char index of this cell's first code unit within the line */ + charIndex: number; + isAnchor: boolean; + hatColor?: HatColor; + hatShape?: HatShape; +} + +// East_Asian_Width Wide (W) + Fullwidth (F) ranges. Covers CJK, Hangul, +// fullwidth forms, kana, common emoji presentation. Sufficient for the +// column-model torture test; extend the table if a fixture needs more. +const WIDE_RANGES: ReadonlyArray = [ + [0x1100, 0x115f], // Hangul Jamo + [0x2329, 0x232a], // angle brackets + [0x2e80, 0x303e], // CJK radicals .. symbols + [0x3041, 0x33ff], // Hiragana, Katakana, CJK symbols/punct + [0x3400, 0x4dbf], // CJK Ext A + [0x4e00, 0x9fff], // CJK Unified + [0xa000, 0xa4cf], // Yi + [0xac00, 0xd7a3], // Hangul Syllables + [0xf900, 0xfaff], // CJK Compatibility Ideographs + [0xfe10, 0xfe19], // vertical forms + [0xfe30, 0xfe6f], // CJK compat / small forms + [0xff00, 0xff60], // Fullwidth Forms + [0xffe0, 0xffe6], // Fullwidth signs + [0x1f300, 0x1f64f], // emoji + emoticons + [0x1f900, 0x1f9ff], // supplemental symbols/pictographs + [0x20000, 0x3fffd], // CJK Ext B+ (SIP/TIP) +]; + +function isWideCodePoint(cp: number): boolean { + for (const [lo, hi] of WIDE_RANGES) { + if (cp >= lo && cp <= hi) { + return true; + } + if (cp < lo) { + break; + } + } + return false; +} + +/** Display width of a grapheme cluster: 2 if its base code point is EAW W/F, else 1. */ +export function graphemeWidth(grapheme: string): number { + const cp = grapheme.codePointAt(0); + if (cp === undefined) { + return 1; + } + return isWideCodePoint(cp) ? 2 : 1; +} + +interface GraphemeUnit { + text: string; + /** char index within the token text */ + offset: number; +} + +/** Split a token's text into grapheme clusters, tracking each one's char offset. */ +export function splitGraphemes(text: string): GraphemeUnit[] { + const out: GraphemeUnit[] = []; + const re = new RegExp(GRAPHEME_SPLIT_REGEX); + let m: RegExpExecArray | null; + let lastIndex = 0; + while ((m = re.exec(text)) !== null) { + // Emit any chars the regex skipped (e.g. whitespace) as single cells so + // every column of every line is owned by exactly one cell. + if (m.index > lastIndex) { + for (let i = lastIndex; i < m.index; i++) { + out.push({ text: text[i], offset: i }); + } + } + out.push({ text: m[0], offset: m.index }); + lastIndex = m.index + m[0].length; + if (m[0].length === 0) { + re.lastIndex++; + } // guard zero-width + } + for (let i = lastIndex; i < text.length; i++) { + out.push({ text: text[i], offset: i }); + } + return out; +} + +/** + * Expand a line's tokens into ordered visual columns (SPEC §2). + * Resolves each hat's anchor to a computed visual column (never a raw char index). + */ +export function expandColumns(line: Line, tabSize: number): Column[] { + const cols: Column[] = []; + let col = 0; + + for (const token of line.tokens) { + const graphemes = splitGraphemes(token.text); + const hat = token.hat ?? undefined; + const anchorIdx = hat?.anchorGrapheme ?? 0; + + graphemes.forEach((g, gi) => { + const charIndex = token.range.start + g.offset; + const isAnchor = !!hat && gi === anchorIdx; + + if (g.text === "\t") { + const advance = tabSize - (col % tabSize) || tabSize; + cols.push({ + text: "", + col, + width: advance, + charIndex, + isAnchor, + hatColor: isAnchor ? hat!.color : undefined, + hatShape: isAnchor ? hat!.shape : undefined, + }); + col += advance; + return; + } + + const w = graphemeWidth(g.text); + cols.push({ + text: g.text, + col, + width: w, + charIndex, + isAnchor, + hatColor: isAnchor ? hat!.color : undefined, + hatShape: isAnchor ? hat!.shape : undefined, + }); + col += w; + }); + } + + return cols; +} + +/** Total visual columns in a line. */ +export function lineWidth(cols: Column[]): number { + if (cols.length === 0) { + return 0; + } + const last = cols[cols.length - 1]; + return last.col + last.width; +} diff --git a/packages/command-visualizer/src/css-cascade.ts b/packages/command-visualizer/src/css-cascade.ts new file mode 100644 index 0000000000..812ee48f99 --- /dev/null +++ b/packages/command-visualizer/src/css-cascade.ts @@ -0,0 +1,272 @@ +// Cascade + overlay CSS — SPEC-v2 §3 (highlight bands) + §4 (stacked-frame +// opacity timeline). Generated from the single-sourced decoration hexes so the +// band colors never drift. Theme-INVARIANT (background-only translucent hexes). + +import { DECORATION_HEX, ALL_DECORATION_STYLES } from "./data/decorations"; +import { FLASH_STYLES, HIGHLIGHT_STYLES } from "./data/decorations"; +import { FLASH_PULSE_MS } from "./data/decorations"; +import type { Frame } from "./frame-state"; +import { timelineOf, type Timeline } from "./timeline"; + +// §3.2 — char-range bands on the per-char grid (one bg attr per .ch). +// The STATIC path (single-frame PNG renders, animate=false): the band is just a +// solid background-color, present for the whole frame. Used by Phase-3 PNG tests. +function charBandRules(): string { + const flash = FLASH_STYLES.map( + (s) => `.ch[data-flash="${s}"] { background-color: ${DECORATION_HEX[s]}; }`, + ); + const hl = HIGHLIGHT_STYLES.map( + (s) => `.ch[data-hl="${s}"] { background-color: ${DECORATION_HEX[s]}; }`, + ); + return [...flash, ...hl].join("\n"); +} + +// §4.2 DURING beats — flash TIMING. A flash is a TRANSIENT beat *within* one +// frame's timeline slot, not a static band. Two opposite directions: +// +// DELETE (R2-i, pendingDelete) rides the BEFORE frame (frame 0, slot [0, 1/N]): +// plain (band transparent) → hold plain → red band fades IN +// then the frame's opacity snap crosses to the after-frame (text gone). The band +// fades in LATE in the slot so the before-doc reads plain first, then highlights +// the doomed span just before it vanishes. +// +// ADD (R2-ii, justAdded) rides the AFTER frame (frame N-1, slot [(N-1)/N, 1]): +// green band PRESENT → hold green → green band fades OUT → plain (text stays) +// the insert just happened, so the green is up-front when the after-frame appears, +// then fades out over the latter part of the slot leaving plain text behind. This +// is the mirror image of the delete beat (green out-front, fade to transparent vs. +// red back-end, fade in from transparent). +// +// Both animate ONLY background-color (text stays fully opaque the whole slot); +// CSS-only, zero view-time JS. Each flash style gets its own @keyframes scoped to +// its native frame, so other frames / styles keep the static band. +const pct = (x: number): string => x.toFixed(3); + +const DELETE_FLASH_STYLES = ["pendingDelete"] as const; +const ADD_FLASH_STYLES = ["justAdded"] as const; + +// B2/B6 FIX — the flash is a FIXED 100ms pulse, pinned to cursorless's +// `pendingEditDecorationTime` (FLASH_PULSE_MS), DECOUPLED from the readability +// state-hold cadence. +// +// The cascade timeline is `--dur = N · MS_PER_STATE` ms (serialize-cascade.ts), +// so each of the N frame slots lasts MS_PER_STATE ms. Working in keyframe-% of +// the WHOLE timeline (each @keyframes runs over var(--dur)): +// 1% of timeline = (--dur)/100 ms = (N·MS_PER_STATE)/100 ms +// ⇒ a P-ms window in % = P / (N·MS_PER_STATE) · 100 +// The flash's FULL-target held window is exactly FLASH_PULSE_MS ms → `pulsePct` +// below. A short fade ramp (FADE_FRAC of the pulse) softens each edge but the +// held-full-color span is exactly the pulse, which is what verify:flash-timing +// measures. Result: the pulse is ~100ms for ANY N (no slot scaling). +const FADE_FRAC = 0.4; // soft-edge ramp length as a fraction of the pulse window + +// Reference-class pre-edit flashes (Bring sources/destinations etc.) — they +// sequence BEFORE deletion flashes inside a DURING window (real cursorless +// fires pre-edit flashes in parallel; sequenced here by spec). +const REFERENCE_FLASH_STYLES = [ + "referenced", + "pendingModification0", + "pendingModification1", +] as const; + +function flashFadeKeyframes( + frames: readonly Frame[], + tl: Timeline, + pulseMs: number = FLASH_PULSE_MS, +): string { + const out: string[] = []; + const pct100 = (x: number) => pct(Math.max(0, Math.min(100, x * 100))); + + frames.forEach((frame, k) => { + const lo = tl.startFrac[k]; + const hi = tl.endFrac[k]; + + if (frame.role === "during") { + // DURING window: reference flashes first, deletion flashes second. + // Halves when both classes are present; the full window otherwise. + const styles = new Set(frame.decorations.map((d) => d.style)); + // The during phase keeps its full duration regardless of content, but + // the FIRST flash class present INITIATES AT THE PHASE START — the + // same instant the command pill goes active. When reference flashes + // exist they take the first half and deletion follows at the midpoint; + // with deletions only, red starts with the pill and holds to the edit. + const hasRef = REFERENCE_FLASH_STYLES.some((st) => + styles.has(st as never), + ); + const mid = (lo + hi) / 2; + const refWin: [number, number] = [lo, mid]; + const delWin: [number, number] = [hasRef ? mid : lo, hi]; + const emit = (style: string, w: [number, number], holdOn: boolean) => { + out.push( + `@keyframes flashfade-${style}-s${k} {\n` + + ` 0% { background-color: transparent; }\n` + + ` ${pct100(w[0])}% { background-color: transparent; }\n` + + ` ${pct100(w[0] + 0.0001)}% { background-color: ${DECORATION_HEX[style as keyof typeof DECORATION_HEX]}; }\n` + + ` ${pct100(w[1])}% { background-color: ${DECORATION_HEX[style as keyof typeof DECORATION_HEX]}; }\n` + + (holdOn + ? ` 100% { background-color: ${DECORATION_HEX[style as keyof typeof DECORATION_HEX]}; }\n` + : ` ${pct100(w[1] + 0.0001)}% { background-color: transparent; }\n 100% { background-color: transparent; }\n`) + + `}`, + ); + }; + for (const st of REFERENCE_FLASH_STYLES) { + if (styles.has(st)) { + emit(st, refWin, false); + } + } + if (styles.has("pendingDelete")) { + emit("pendingDelete", delWin, true); + } // held to the edit + } else { + // ADD pulse at the frame's slot start (post-edit justAdded). + const durFrac = pulseMs / tl.totalMs; + const aFullEnd = Math.min(hi, lo + durFrac); + const aFadeEnd = Math.min(hi, aFullEnd + durFrac * FADE_FRAC); + for (const st of ADD_FLASH_STYLES) { + out.push( + `@keyframes flashfade-${st}-s${k} {\n` + + ` 0% { background-color: ${DECORATION_HEX[st]}; }\n` + + ` ${pct100(lo)}% { background-color: ${DECORATION_HEX[st]}; }\n` + + ` ${pct100(aFullEnd)}% { background-color: ${DECORATION_HEX[st]}; }\n` + + ` ${pct100(aFadeEnd)}% { background-color: transparent; }\n` + + ` 100% { background-color: transparent; }\n` + + `}`, + ); + } + } + }); + + return out.join("\n"); +} + +function flashFadeRules(frames: readonly Frame[]): string { + const rules: string[] = []; + frames.forEach((frame, k) => { + if (frame.role === "during") { + const styles = new Set(frame.decorations.map((d) => d.style)); + for (const st of [...REFERENCE_FLASH_STYLES, "pendingDelete"]) { + if (!styles.has(st as never)) { + continue; + } + rules.push( + `.cl-cascade .frame[data-frame="${k}"] .ch[data-flash="${st}"] {\n` + + ` background-color: transparent;\n` + + ` animation: flashfade-${st}-s${k} var(--dur, 2s) linear 1 forwards paused;\n` + + `}`, + ); + } + } else { + for (const st of ADD_FLASH_STYLES) { + rules.push( + `.cl-cascade .frame[data-frame="${k}"] .ch[data-flash="${st}"] {\n` + + ` background-color: ${DECORATION_HEX[st]};\n` + + ` animation: flashfade-${st}-s${k} var(--dur, 2s) linear 1 forwards paused;\n` + + `}`, + ); + } + } + }); + return rules.join("\n"); +} + +// §3.4 — full-width line-range bands on .cl-line (content box, DECISIONS §7.7). +function lineBandRules(): string { + return ALL_DECORATION_STYLES.map( + (s) => + `.cl-line[data-line-flash="${s}"] { background-color: ${DECORATION_HEX[s]}; display: block; width: 100%; }`, + ).join("\n"); +} + +// §4.2 — per-frame opacity timeline. Frame k of N is opaque on [k/N,(k+1)/N). +// steps(1,end) gives a hard BEFORE→AFTER snap (no ghosty in-between). +function frameKeyframes(tl: Timeline): string { + const n = tl.startFrac.length; + if (n <= 1) { + return `@keyframes f0 { 0%{opacity:1} 100%{opacity:1} }`; + } + const out: string[] = []; + for (let k = 0; k < n; k++) { + const lo = tl.startFrac[k] * 100; + const hi = tl.endFrac[k] * 100; + if (k === 0) { + out.push( + `@keyframes f0 { 0%{opacity:1} ${pct(hi)}%{opacity:1} ${pct(hi + 0.001)}%{opacity:0} 100%{opacity:0} }`, + ); + } else if (k === n - 1) { + out.push( + `@keyframes f${k} { 0%{opacity:0} ${pct(lo)}%{opacity:0} ${pct(lo + 0.001)}%{opacity:1} 100%{opacity:1} }`, + ); + } else { + out.push( + `@keyframes f${k} { 0%{opacity:0} ${pct(lo)}%{opacity:0} ${pct(lo + 0.001)}%{opacity:1} ${pct(hi)}%{opacity:1} ${pct(hi + 0.001)}%{opacity:0} 100%{opacity:0} }`, + ); + } + } + return out.join("\n"); +} + +export function cascadeStyleSheet( + frames: readonly Frame[], + flashPulseMs: number = FLASH_PULSE_MS, +): string { + const n = Math.max(1, frames.length); + const tl = timelineOf(frames); + // Only multi-frame cascades get the timed DURING beat; n<=1 single-frame + // renders keep the pure-static band (Phase-3 PNG tests must stay green). + const animated = n >= 2; + const flashFade = animated + ? `\n/* ---- DURING beats: delete (R2-i) + insert (R2-ii) flash-timing (SPEC-v2 §4.2) ---- */\n${flashFadeKeyframes(frames, tl, flashPulseMs)}\n${flashFadeRules(frames)}\n` + : ""; + return `/* ---- decoration overlay layer (SPEC-v2 §3) ---- */ +${charBandRules()} +${lineBandRules()} +${flashFade} + +/* ---- cascade container + stacked frames (SPEC-v2 §4.1) ---- */ +.cl-cascade { + position: relative; + display: inline-block; + min-width: 100%; + box-sizing: border-box; + background: var(--editor-bg, #1e1e1e); + border-radius: 10px; + overflow: hidden; + padding: 1.2em 1em 1.6em; +} +.cl-cascade .frame { + position: absolute; + inset: 1.2em 1em 1.6em; + opacity: 0; + animation: f0 var(--dur, 2s) steps(1, end) 1 forwards paused; +} +/* the FIRST frame establishes the container height (in normal flow) */ +.cl-cascade .frame[data-frame="0"] { position: relative; inset: auto; } + +/* inherit the editor surface chrome onto the cascade box via data-theme */ +.cl-cascade[data-theme] { color: var(--editor-fg, #d4d4d4); } +.cl-cascade .cl-code { + font-family: "JetBrains Mono", "SF Mono", "Menlo", ui-monospace, monospace; + font-size: 18px; + font-variant-ligatures: none; + font-feature-settings: "liga" 0, "calt" 0; + letter-spacing: 0; + line-height: var(--code-line-height, 1.35); + white-space: pre; +} + +/* ---- per-frame opacity timeline (SPEC-v2 §4.2) ---- */ +${frameKeyframes(tl)} + +/* the static (non-animated) default: show the LAST frame so a no-capture view + still reads as the end state; capture harness seeks each slot. */ +.cl-cascade .frame { animation-play-state: paused; } +.cl-cascade .frame[data-frame="${n - 1}"] { opacity: 1; } +`; +} + +// Map cascade theme vars onto the cascade box (so .cl-cascade gets --editor-bg). +// The base styleSheet() already defines .cl-editor[data-theme]; mirror it here. +export function cascadeThemeBridge(): string { + return `.cl-cascade[data-theme="dark"] { --editor-bg:#1e1e1e; --editor-fg:#d4d4d4; --editor-sel:#264f78; --editor-caret:#aeafad; } +.cl-cascade[data-theme="light"] { --editor-bg:#ffffff; --editor-fg:#1f1f1f; --editor-sel:#add6ff; --editor-caret:#000000; }`; +} diff --git a/packages/command-visualizer/src/css.ts b/packages/command-visualizer/src/css.ts new file mode 100644 index 0000000000..1bea6c6664 --- /dev/null +++ b/packages/command-visualizer/src/css.ts @@ -0,0 +1,196 @@ +// CSS contract — SPEC §4. Generated from the single-sourced data so color + +// adjustment values never drift. No render-time JS; CSS does 100% of visual work. + +import { COLOR_MATRIX, EDITOR_CHROME, HAT_COLORS } from "./data/colors"; +import { HAT_SHAPES, SHAPE_ADJUSTMENTS } from "./data/shapes"; + +function shapeAdjustmentRules(): string { + const lines: string[] = [ + `.hat { --shape-size-adj: 0; --shape-voffset: 0em; }`, + ]; + for (const shape of HAT_SHAPES) { + const adj = SHAPE_ADJUSTMENTS[shape]; + const parts: string[] = []; + if (adj.sizeAdjustment !== undefined) { + // percent → fraction + parts.push(`--shape-size-adj: ${adj.sizeAdjustment / 100};`); + } + if (adj.verticalOffset !== undefined) { + // percent → em/100 + parts.push(`--shape-voffset: ${adj.verticalOffset / 100}em;`); + } + if (parts.length) { + lines.push( + `.ch--anchor[data-hat-shape="${shape}"] .hat { ${parts.join(" ")} }`, + ); + } + } + return lines.join("\n"); +} + +function colorVarRules(): string { + return HAT_COLORS.map( + (c) => + `.ch--anchor[data-hat-color="${c}"] .hat { --hat-color: var(--c-${c}); }`, + ).join("\n"); +} + +function themeVars(theme: "dark" | "light"): string { + const cm = COLOR_MATRIX[theme]; + const ch = EDITOR_CHROME[theme]; + const colorVars = HAT_COLORS.map((c) => ` --c-${c}: ${cm[c]};`).join("\n"); + return ( + `.cl-editor[data-theme="${theme}"] {\n${colorVars}\n` + + ` --editor-bg: ${ch.bg}; --editor-fg: ${ch.fg};` + + ` --editor-sel: ${ch.sel}; --editor-caret: ${ch.caret};\n}` + ); +} + +export function styleSheet(): string { + return `/* Cursorless state → static CSS. SPEC §4. Generated; do not hand-edit. */ + +:root { + --hat-height: 0.36em; /* DEFAULT_HAT_HEIGHT_EM */ + --hat-base-voffset: 0.05em; /* DEFAULT_VERTICAL_OFFSET_EM */ + --user-size-adj: 0; /* cursorless.hatSizeAdjustment as fraction */ + --user-voffset: 0em; + /* Real VS Code default line-height resolves to ~1.35× for the editor font + (measured from screenshots/oracle/REAL-main-demo-frame1.png: 24px pitch + over ~17.8px glyphs). Single-sourced here so the hat anchor can stay + glyph-relative regardless of the chosen value. */ + --code-line-height: 1.35; +} + +/* ---- per-shape adjustments (shapeAdjustments.ts, SPEC §4.2) ---- */ +${shapeAdjustmentRules()} + +/* ---- color tint vars (SPEC §4.4) ---- */ +${colorVarRules()} + +${themeVars("dark")} +${themeVars("light")} + +/* ---- editor surface ---- */ +@keyframes caretblink { + 0%, 55% { opacity: 1; } + 56%, 100% { opacity: 0; } +} +.caret { animation: caretblink 1.06s steps(1, end) infinite paused; } + +.cl-editor { + background: var(--editor-bg); + color: var(--editor-fg); + border-radius: 10px; + overflow: hidden; + padding: 1.2em 1em 1.6em; + display: inline-block; + min-width: 100%; + box-sizing: border-box; +} +.cl-code { + font-family: "JetBrains Mono", "SF Mono", "Menlo", ui-monospace, monospace; + font-size: 18px; + font-variant-ligatures: none; /* D8: 1 glyph = its column(s) */ + font-feature-settings: "liga" 0, "calt" 0; + letter-spacing: 0; + line-height: var(--code-line-height); + white-space: pre; +} +.cl-line { display: block; min-height: calc(var(--code-line-height) * 1em); } + +/* The shared symbol-sheet (symbols.ts) is a 0×0 def holder, but an inline + still generates a one-line-tall INLINE LINE BOX. As the first child of + .cl-cascade — ahead of the in-flow position:relative frame 0 — that phantom + line box shoved frame 0's content down by 1em (~18px) while the position:absolute + later frames pinned to the padding box and ignored it, so the whole text block + jittered 1em vertically on every frame snap. display:block kills the inline line + box (0-height block contributes nothing), aligning frame 0 with the rest. */ +svg.cl-defs { display: block; } + +/* ---- per-char column grid (D8) ---- */ +.ch { + display: inline-block; + position: relative; /* hat's offset parent — no long-line drift */ + width: 1ch; + text-align: center; +} +.ch[data-col-span="2"] { width: 2ch; } +.ch[data-col-span="3"] { width: 3ch; } +.ch[data-col-span="4"] { width: 4ch; } +.ch[data-col-span="5"] { width: 5ch; } +.ch[data-col-span="6"] { width: 6ch; } +.ch[data-col-span="7"] { width: 7ch; } +.ch[data-col-span="8"] { width: 8ch; } + +/* ---- hat (SPEC §4.3): tint via color + currentColor (D4) ---- */ +.hat { + position: absolute; + left: 50%; + height: calc(var(--hat-height) * (1 + var(--user-size-adj) + var(--shape-size-adj))); + width: calc(var(--hat-height) * (1 + var(--user-size-adj) + var(--shape-size-adj)) * 12 / 9); + transform: translateX(-50%); + /* Anchor the hat to the GLYPH TOP, not the line-box bottom, so it hugs the + character cap regardless of line-height (cursorless positions the hat from + the glyph: VscodeHatRenderer.ts:67, hatVOffsetPx = vOffsetEm*fontSize, + glyph-relative). .ch is inline-block so its box height == line-height; + the glyph content box (1em) is centered, leaving (line-height - 1em)/2 of + half-leading above it. Add that half-leading back to the 1em baseline-stack + so the hat sits just above the cap and never drifts into the inter-line gap + when line-height changes. + + The final term mirrors cursorless's + hatVerticalOffsetPx = (0.05 + voffsetEm)*fontSize - hatHeightPx/2 + (VscodeHatRenderer.ts:222-241). Cursorless lifts the hat bottom by half the + RENDERED hat height, so taller shapes sink lower relative to the glyph top. + Our eye-tuned baseline above already lands the DEFAULT shape correctly + (which carries shapeSizeAdj -0.30), so we only need the per-shape DELTA from + that default height -- subtracting (thisHatHeight - defaultShapeHatHeight)/2 + reproduces cursorless's -hatHeightPx/2 spread without disturbing the tuned + default. thisHatHeight reuses the exact height calc; defaultShapeHatHeight + is the same expression with shapeSizeAdj pinned to the default-shape -0.30. */ + bottom: calc(1em + (var(--code-line-height) - 1) * 0.5em + + var(--hat-base-voffset) + var(--user-voffset) + var(--shape-voffset) + - (var(--hat-height) * (1 + var(--user-size-adj) + var(--shape-size-adj)) + - var(--hat-height) * (1 + var(--user-size-adj) - 0.30)) / 2); + color: var(--hat-color); + pointer-events: none; + overflow: visible; + display: block; +} + +/* ---- cursor + selection (SPEC §4.5) ---- */ +.caret[data-cursor] { + display: inline-block; + width: 0; height: 1.2em; + margin: 0 -1px; + border-left: 2px solid var(--editor-caret); + vertical-align: text-bottom; +} +.ch[data-sel] { background: var(--editor-sel); } + +/* ---- optional line-number gutter (R3): OFF by default ---- + A leading inline-block .cl-lineno per .cl-line. Because the number shares the + line box with its code, it aligns to that exact row automatically — works + identically for single-frame renders and absolutely-positioned stacked cascade + frames (no offset math). The gutter only exists when an ancestor carries + data-line-numbers; absent that attribute, no .cl-lineno is emitted and output + is byte-identical to the no-gutter render. */ +:root { + --gutter-digits: 2; /* widest line number's digit count */ + --gutter-pad-right: 1.1ch; /* gap between numbers and code */ + --gutter-pad-left: 0.6ch; +} +.cl-lineno { + display: inline-block; + width: calc(var(--gutter-digits) * 1ch); + padding-left: var(--gutter-pad-left); + padding-right: var(--gutter-pad-right); + text-align: right; /* VS Code: right-aligned numbers */ + color: var(--editor-fg); + opacity: 0.42; /* dim, muted gray */ + font-variant-numeric: tabular-nums; + user-select: none; + pointer-events: none; +} +`; +} diff --git a/packages/command-visualizer/src/data/colors.ts b/packages/command-visualizer/src/data/colors.ts new file mode 100644 index 0000000000..78862e8994 --- /dev/null +++ b/packages/command-visualizer/src/data/colors.ts @@ -0,0 +1,67 @@ +// Color matrix — hexes VERBATIM from +// cursorless/packages/app-vscode/package.json cursorless.colors.{dark,light} +// (verified 2026-06-08; also mirrored in screenshots/oracle/color-matrix.json). +// SPEC §4.4. + +export type HatColor = + | "default" + | "blue" + | "green" + | "red" + | "pink" + | "yellow" + | "userColor1" + | "userColor2" + | "userColor3" + | "userColor4"; + +export const HAT_COLORS: HatColor[] = [ + "default", + "blue", + "green", + "red", + "pink", + "yellow", + "userColor1", + "userColor2", + "userColor3", + "userColor4", +]; + +export type Theme = "dark" | "light"; + +export const COLOR_MATRIX: Record> = { + dark: { + default: "#B9B6CD", + blue: "#089ad3", + green: "#36B33F", + red: "#E02D28", + pink: "#E06CAA", + yellow: "#E5C02C", + userColor1: "#6a00ff", + userColor2: "#ffd8b1", + userColor3: "#6b8e23", + userColor4: "#e0e0e0", + }, + light: { + default: "#757180", + blue: "#089ad3", + green: "#36B33F", + red: "#E02D28", + pink: "#e0679f", + yellow: "#edb62b", + userColor1: "#6a00ff", + userColor2: "#ffd8b1", + userColor3: "#6b8e23", + userColor4: "#e0e0e0", + }, +}; + +// Editor chrome colors (VS Code dark+ / light+ defaults). +export const EDITOR_CHROME: Record< + Theme, + { bg: string; fg: string; sel: string; caret: string } +> = { + dark: { bg: "#1e1e1e", fg: "#d4d4d4", sel: "#264f78", caret: "#aeafad" }, + light: { bg: "#ffffff", fg: "#1f1f1f", sel: "#add6ff", caret: "#000000" }, +}; diff --git a/packages/command-visualizer/src/data/decorations.ts b/packages/command-visualizer/src/data/decorations.ts new file mode 100644 index 0000000000..4c91dc4b38 --- /dev/null +++ b/packages/command-visualizer/src/data/decorations.ts @@ -0,0 +1,79 @@ +// Decoration style hexes — VERBATIM from cursorless flash/highlight palette +// (research/highlight-rendering.md §3; verified 2026-06-08). SPEC-v2 §3.1. +// All background-only; alpha baked into the 8-digit hex; theme-INVARIANT. + +// Provenance: these five names are the string values of @cursorless/lib-common's +// `FlashStyle` enum (ide/types/FlashDescriptor.ts). We deliberately keep a local +// string-union rather than importing the enum: the names compose here with +// HighlightStyle into DecorationStyle, which keys DECORATION_HEX and drives +// overlayPrecedence — switching to enum members would churn every literal and +// buy no runtime behavior. The HEX values, FLASH_PULSE_MS, MS_PER_STATE, and +// precedence are ours and are not exported by cursorless. +export type FlashStyle = + | "pendingDelete" + | "justAdded" + | "referenced" + | "pendingModification0" + | "pendingModification1"; + +export type HighlightStyle = "highlight0" | "highlight1"; + +export type DecorationStyle = FlashStyle | HighlightStyle; + +// All 11 decoration styles' background hexes (the 2 scope-pair styles use the +// same band hex family; per-edge borders are BONUS, SPEC-v2 §3.5, not here). +export const DECORATION_HEX: Record = { + pendingDelete: "#ff00008a", // REQUIRED (COMPLETION crit 3) + justAdded: "#09ff005b", // REQUIRED (COMPLETION crit 3) + referenced: "#00a2ff4d", + pendingModification0: "#8c00ff86", + pendingModification1: "#ff009d7e", + highlight0: "#d449ff42", + highlight1: "#60daff7a", +}; + +export const FLASH_STYLES: FlashStyle[] = [ + "pendingDelete", + "justAdded", + "referenced", + "pendingModification0", + "pendingModification1", +]; + +export const HIGHLIGHT_STYLES: HighlightStyle[] = ["highlight0", "highlight1"]; + +// Flash PULSE duration — pinned VERBATIM to cursorless's +// `cursorless.pendingEditDecorationTime` default (100ms): +// packages/app-vscode/package.json:375 ("default": 100) +// packages/app-vscode/src/ide/vscode/VscodeFlashHandler.ts:26 +// flashRanges(...) → await sleep(getPendingEditDecorationTime()) → clear +// A flash is a FIXED 100ms pulse, decoupled from the readability state-hold +// cadence (SPEC-v2 §4.2, B2/B6). Both the delete (pendingDelete) and insert +// (justAdded) beats are pinned to this. verify:flash-timing is the oracle. +export const FLASH_PULSE_MS = 100; + +// Real-time duration of one readability state-hold slot, in ms. The cascade +// timeline is `--dur = N · MS_PER_STATE` (serialize-cascade.ts), so each of the +// N frame slots lasts exactly MS_PER_STATE ms regardless of N. The flash pulse +// (FLASH_PULSE_MS) is pinned in absolute ms and is INDEPENDENT of this cadence — +// changing MS_PER_STATE rescales the state-hold but never the 100ms flash. +export const MS_PER_STATE = 1000; + +export const ALL_DECORATION_STYLES: DecorationStyle[] = [ + ...FLASH_STYLES, + ...HIGHLIGHT_STYLES, +]; + +// Single-winner precedence (SPEC-v2 §3.2, DECISIONS §7.1): selection < highlight +// < flash, last wins; exactly ONE background per cell. Higher number wins. +export function overlayPrecedence( + style: DecorationStyle | "selection", +): number { + if (style === "selection") { + return 0; + } + if (HIGHLIGHT_STYLES.includes(style as HighlightStyle)) { + return 1; + } + return 2; // flash +} diff --git a/packages/command-visualizer/src/data/shapes.ts b/packages/command-visualizer/src/data/shapes.ts new file mode 100644 index 0000000000..4dd6fbe095 --- /dev/null +++ b/packages/command-visualizer/src/data/shapes.ts @@ -0,0 +1,108 @@ +// Hat shape SVG path data — copied VERBATIM from +// cursorless/resources/images/hats/{shape}.svg (verified 2026-06-08). +// Only `crosshairs` carries fill-rule="evenodd" clip-rule="evenodd"; every +// other shape uses the SVG default (nonzero). `ex` is a single subpath (no hole). +// SPEC §4.1 / DECISIONS.md CORRECTION. + +export type HatShape = + | "default" + | "bolt" + | "curve" + | "fox" + | "frame" + | "play" + | "wing" + | "hole" + | "ex" + | "crosshairs" + | "eye"; + +export const HAT_SHAPES: HatShape[] = [ + "default", + "bolt", + "curve", + "fox", + "frame", + "play", + "wing", + "hole", + "ex", + "crosshairs", + "eye", +]; + +export interface ShapePath { + d: string; + /** Only set for crosshairs. */ + fillRule?: "evenodd"; +} + +// d= strings are byte-for-byte from the source SVGs. +export const SHAPE_PATHS: Record = { + default: { + d: "M6 9C9.31371 9 12 6.98528 12 4.5C12 2.01472 9.31371 0 6 0C2.68629 0 0 2.01472 0 4.5C0 6.98528 2.68629 9 6 9Z", + }, + bolt: { + d: "M12 4V0C12 0 9 5 8 5C7 5 3 0 3 0L0 5V9C0 9 3 5 4 5C5 5 9 9 9 9L12 4Z", + }, + curve: { + d: "M6.00016 3.5C10 3.5 12 7.07378 12 9C12 4 10.5 0 6.00016 0C1.50032 0 0 4 0 9C0 7.07378 2.00032 3.5 6.00016 3.5Z", + }, + fox: { + d: "M6.00001 9L0 0C0 0 3.71818 2.5 6 2.5C8.28182 2.5 12 0 12 0L6.00001 9Z", + }, + frame: { + d: "M0 0.000115976V8.99988H12V0L0 0.000115976ZM9.5 6.5H6H2.5V4.5V2.5H6H9.5V4.5V6.5Z", + }, + play: { + d: "M12 4.49999L0 9C0 9 3 6.2746 3 4.49999C3 2.72537 0 0 0 0L12 4.49999Z", + }, + wing: { + d: "M6 0C6 0 7 3 8.5 4.5C10 6 12 7 12 7V9C12 9 8.5 7 6 7C3.5 7 0 9 0 9V7C0 7 2 6 3.5 4.5C5 3 6 0 6 0Z", + }, + hole: { + d: "M1.5 4.5L0 7H2.5L3.5 9L6 7.5L8.5 9L9.5 7H12L10.5 4.5L12 2H9.5L8.5 0L6 1.5L3.5 0L2.5 2H0Z M6 5.5L4 6.5L3 4.5L4 2.5L6 3.5L8 2.5L9 4.5L8 6.5L6 5.5Z", + }, + ex: { + d: "M9.99997 9C9.99997 9 7.5 6.5 6 6.5C4.5 6.5 2 9 2 9C2 9 0.999999 9 0 9C0 9 2.5 6 2.5 4.5C2.5 3 6.5473e-05 0 6.5473e-05 0C6.5473e-05 0 1 0 2 0C2 0 4.5 2.5 6 2.5C7.5 2.5 9.99997 0 9.99997 0C11 0 12 0 12 0C12 0 9.5 3 9.5 4.5C9.5 6 12 9 12 9C12 9 11 9 9.99997 9Z", + }, + crosshairs: { + d: "M5.25 0C5.25 0 4.5 1.5 3.5 2.5C2.49483 3.50517 0 3.75 0 3.75V5.25C0 5.25 2.49483 5.49483 3.5 6.5C4.5 7.5 5.25 9 5.25 9H6.75C6.75 9 7.5 7.5 8.5 6.5C9.50517 5.49483 12 5.25 12 5.25V3.75C12 3.75 9.50517 3.50517 8.5 2.5C7.5 1.5 6.75 0 6.75 0H5.25ZM5.75 6.5H6.25C6.25 6.5 6.58435 5.25599 7 5C7.41565 4.74401 8.75 4.75 8.75 4.75V4.25C8.75 4.25 7.41565 4.25599 7 4C6.58435 3.74401 6.25 2.5 6.25 2.5H5.75C5.75 2.5 5.41565 3.74401 5 4C4.58435 4.25599 3.25 4.25 3.25 4.25V4.75C3.25 4.75 4.58435 4.74401 5 5C5.41565 5.25599 5.75 6.5 5.75 6.5Z", + fillRule: "evenodd", + }, + eye: { + d: "M12 4L6.5 0H5.5L0 4V5L5.5 9H6.5L12 5V4ZM6 7.5C6 7.5 4.5 6.5 4.5 4.5C4.5 2.5 6.01103 1.5 6 1.5C6 1.5 7.5 2.5 7.5 4.5C7.5 6.5 6 7.5 6 7.5Z", + }, +}; + +/** + * Per-shape adjustments, ported from + * cursorless/.../hats/shapeAdjustments.ts (verified 2026-06-08). + * sizeAdjustment is a PERCENT (e.g. -30 = -0.30 fraction). + * verticalOffset is a PERCENT applied /100 to em (e.g. -5 = -0.05em). + */ +export interface ShapeAdjustment { + /** percent */ + sizeAdjustment?: number; + /** percent → em/100 */ + verticalOffset?: number; + /** deferred (two-tone stroke, SPEC §7) */ + strokeFactor?: number; +} + +export const SHAPE_ADJUSTMENTS: Record = { + default: { sizeAdjustment: -30 }, + ex: { sizeAdjustment: -12.5 }, + fox: { sizeAdjustment: -5 }, + wing: { sizeAdjustment: -2.5 }, + hole: { strokeFactor: 0.7 }, + frame: { sizeAdjustment: -20 }, + curve: { verticalOffset: -5 }, + eye: {}, + play: {}, + bolt: {}, + crosshairs: {}, +}; + +export const DEFAULT_HAT_HEIGHT_EM = 0.36; +export const DEFAULT_VERTICAL_OFFSET_EM = 0.05; diff --git a/packages/command-visualizer/src/fixture-extract.ts b/packages/command-visualizer/src/fixture-extract.ts new file mode 100644 index 0000000000..bdc150d8b3 --- /dev/null +++ b/packages/command-visualizer/src/fixture-extract.ts @@ -0,0 +1,211 @@ +// Field-extraction helpers for the fixture → state pipeline (SPEC-v2 §2 steps +// 3/4/5). Pulls the YAML-shape coercion + marks→hats + selections + range +// mapping out of pipeline.ts so each module stays under the line ceiling. + +import type { YamlValue } from "./fixture-yaml"; +import { tokenizeDoc } from "./tokenize"; +import type { Line, Token, InputHat } from "./columns"; +import type { HatColor } from "./data/colors"; +import type { HatShape } from "./data/shapes"; +import { HAT_COLORS } from "./data/colors"; +import type { GeneralizedRange } from "./frame-state"; +import type { Pos, Range } from "./serialize"; +import { allocateHats } from "./hat-allocator"; + +export type Obj = Record; + +export function asObj(v: YamlValue | undefined): Obj | null { + return v && typeof v === "object" && !Array.isArray(v) ? (v as Obj) : null; +} +export function asArr(v: YamlValue | undefined): YamlValue[] { + return Array.isArray(v) ? v : []; +} +export function num(v: YamlValue | undefined): number { + return typeof v === "number" ? v : Number(v); +} +export function pos(v: YamlValue | undefined): Pos { + const o = asObj(v) ?? {}; + return { line: num(o.line), character: num(o.character) }; +} + +// Dedup note (step 4c): @cursorless/lib-common exports +// serializedMarksToTokenHats, but it requires a live TextEditor (document +// offsetAt/getText) and returns TokenHat[] — a shape built for the engine, not +// for SVG rendering. Our parseMarks reads plain fixture-YAML objects with no +// editor and yields the MarkInfo render model buildLines() needs. buildLines() +// itself (tokenize → attach fixture hats → real allocator fill → author +// overrides) is genuinely ours. Adopting the engine helper would mean faking a +// TextEditor and rewriting buildLines — scope balloon for no gain. Kept. + +// Step 4: a `{color}.{grapheme}` mark with its line range. +export interface MarkInfo { + key: string; + grapheme: string; + color: HatColor; + start: Pos; + end: Pos; +} + +export function parseMarks(marksObj: Obj | null): MarkInfo[] { + if (!marksObj) { + return []; + } + const out: MarkInfo[] = []; + for (const [key, val] of Object.entries(marksObj)) { + const range = asObj(val); + if (!range) { + continue; + } + const dot = key.indexOf("."); + const colorRaw = key.slice(0, dot); + const grapheme = key.slice(dot + 1); + const color = (HAT_COLORS as string[]).includes(colorRaw) + ? (colorRaw as HatColor) + : ("default" as HatColor); + out.push({ + key, + grapheme, + color, + start: pos(range.start), + end: pos(range.end), + }); + } + return out; +} + +/** Options for buildLines beyond the mark list. */ +export interface BuildLinesOptions { + /** Per-mark-key shape overrides, e.g. { "default.f": "fox" }. */ + shapeOverride?: Record; + /** + * "dense" (default): real-allocator fill over every unhatted hattable + * token — the whole image wears hats, like a live session. + * "marks-only": render exactly the fixture's recorded marks, no fill. + */ + fill?: "dense" | "marks-only"; + /** + * Position-keyed exact-hat overrides applied LAST, to any token (marked or + * fill), keyed "{line}:{startChar}". Author intent wins over both the + * fixture and the allocator; may deliberately duplicate a (grapheme, style) + * the allocator assigned elsewhere — that's on the author. + */ + hatOverride?: Record; +} + +// Steps 3 + 4 + 5: tokenize a doc and attach hats. +export function buildLines( + doc: string, + marks: MarkInfo[], + opts: BuildLinesOptions = {}, +): Line[] { + const { shapeOverride, fill = "dense", hatOverride } = opts; + const lines = tokenizeDoc(doc); + + // Pass 1: command-relevant fixture marks — exact fixture color; shape is + // "default" unless a per-fixture override says otherwise. Fixture mark keys + // ({color}.{grapheme}) carry no shape component: the recorded session's + // hats were default-shape, so "default" is the faithful rendering (the old + // synthetic hash injected fake shapes here — removed in task-8tq). + for (const mk of marks) { + if (mk.start.line !== mk.end.line) { + continue; + } // marks are single-line in corpus + const line = lines[mk.start.line]; + if (!line) { + continue; + } + const hat: InputHat = { + color: mk.color, + shape: shapeOverride?.[mk.key] ?? "default", + }; + let target: Token | undefined = line.tokens.find( + (t) => + t.range.start === mk.start.character && + t.range.end === mk.end.character, + ); + if (!target) { + target = line.tokens.find( + (t) => + t.range.start <= mk.start.character && + mk.start.character < t.range.end, + ); + } + if (target) { + target.hat = hat; + } + } + + // Pass 2: REAL hat allocation (allocate-hats package — cursorless's own + // chooseTokenHat at SHA 42452eb). Fixture-marked tokens from pass 1 enter + // as old assignments (kept, and their colors consumed from the pool); every + // other hattable token gets the algorithm's color AND shape — shapes now + // appear only under real collision pressure instead of hash randomness. + // Skipped in "marks-only" mode: render exactly what the fixture recorded. + if (fill === "dense") { + allocateHats(lines); + } + + // Pass 3: position-keyed exact-hat overrides — author intent wins last. + if (hatOverride) { + for (let lineIdx = 0; lineIdx < lines.length; lineIdx++) { + for (const token of lines[lineIdx].tokens) { + const o = hatOverride[`${lineIdx}:${token.range.start}`]; + if (!o) { + continue; + } + token.hat = { + color: o.color ?? token.hat?.color ?? "default", + shape: o.shape ?? token.hat?.shape ?? "default", + }; + } + } + } + + return lines; +} + +// Selections → {cursors, selections}. anchor==active ⇒ caret; reversed normalize. +export function deriveSelections(selArr: YamlValue[]): { + cursors: Pos[]; + selections: Range[]; +} { + const cursors: Pos[] = []; + const selections: Range[] = []; + for (const s of selArr) { + const o = asObj(s); + if (!o) { + continue; + } + const anchor = pos(o.anchor); + const active = pos(o.active); + if (anchor.line === active.line && anchor.character === active.character) { + cursors.push(anchor); + } else { + const before = + anchor.line < active.line || + (anchor.line === active.line && anchor.character <= active.character); + selections.push( + before + ? { start: anchor, end: active } + : { start: active, end: anchor }, + ); + } + } + return { cursors, selections }; +} + +// Steps 6/7: a flash/highlight range YAML → a Decoration GeneralizedRange. +export function toGeneralizedRange(rangeObj: Obj): GeneralizedRange | null { + if (rangeObj.type === "line") { + return { + type: "line", + startLine: num(rangeObj.start), + endLine: num(rangeObj.end), // INCLUSIVE per GeneralizedRange.ts + }; + } + return { + type: "character", + start: pos(rangeObj.start), + end: pos(rangeObj.end), + }; +} diff --git a/packages/command-visualizer/src/fixture-root.ts b/packages/command-visualizer/src/fixture-root.ts new file mode 100644 index 0000000000..dd3035fc61 --- /dev/null +++ b/packages/command-visualizer/src/fixture-root.ts @@ -0,0 +1,82 @@ +// Portable resolution of the cursorless repo root and its fixture subpaths. +// +// Resolution order: +// 1. $CURSORLESS_REPO env var (explicit override — CI, alt checkouts) +// 2. $HOME/code/cursorless (sensible default, NOT a hardcoded user) +// +// Layout probe: the local repo may use either of two directory structures: +// A (mini2 fork): resources/images/hats/ + resources/fixtures/recorded/ +// B (main repo): images/hats/ + data/fixtures/recorded/ +// +// Throws a CLEAR error if the resolved root does not exist, so a misconfigured +// checkout fails loudly at startup instead of with an opaque ENOENT mid-run. +// +// Dedup note (step 4b): @cursorless/lib-node-common exports getFixturesPath / +// getRecordedTestsDirPath, but they hardcode the single `resources/fixtures` +// layout and offer no $CURSORLESS_REPO override. This module deliberately keeps +// its dual-layout probe (resources/… fork vs data/… main repo) plus the env +// override and loud errors, so it works across both checkout shapes the +// renderer targets. Adopting lib-node-common's helpers would be a regression. + +import { existsSync } from "node:fs"; +import { homedir } from "node:os"; +import { join } from "node:path"; + +/** Absolute path to the cursorless repo root (env override, else $HOME/code/cursorless). */ +export function cursorlessRepoRoot(): string { + const fromEnv = process.env.CURSORLESS_REPO?.trim(); + const root = + fromEnv && fromEnv.length > 0 + ? fromEnv + : join(homedir(), "code", "cursorless"); + + if (!existsSync(root)) { + const how = fromEnv + ? '$CURSORLESS_REPO is set to "' + root + '"' + : 'defaulted to "' + root + '" ($HOME/code/cursorless)'; + throw new Error( + `cursorless repo not found: ${how}, but that path does not exist.\n` + + `Set CURSORLESS_REPO to your cursorless checkout, e.g.\n` + + ` CURSORLESS_REPO=/path/to/cursorless bun run verify`, + ); + } + return root; +} + +/** Detect which directory layout the repo uses and return the hats dir. */ +export function hatsRoot(): string { + const root = cursorlessRepoRoot(); + // Layout A (mini2 fork): resources/images/hats/ + const layoutA = join(root, "resources", "images", "hats"); + if (existsSync(layoutA)) { + return layoutA; + } + // Layout B (main repo): images/hats/ + const layoutB = join(root, "images", "hats"); + if (existsSync(layoutB)) { + return layoutB; + } + throw new Error( + `cursorless hat SVGs not found in "${root}".\n` + + `Expected one of:\n ${layoutA}\n ${layoutB}`, + ); +} + +/** Detect which directory layout the repo uses and return the recorded fixtures dir. */ +export function fixtureRoot(): string { + const root = cursorlessRepoRoot(); + // Layout A (mini2 fork): resources/fixtures/recorded/ + const layoutA = join(root, "resources", "fixtures", "recorded"); + if (existsSync(layoutA)) { + return layoutA; + } + // Layout B (main repo): data/fixtures/recorded/ + const layoutB = join(root, "data", "fixtures", "recorded"); + if (existsSync(layoutB)) { + return layoutB; + } + throw new Error( + `cursorless recorded fixtures not found in "${root}".\n` + + `Expected one of:\n ${layoutA}\n ${layoutB}`, + ); +} diff --git a/packages/command-visualizer/src/fixture-yaml.ts b/packages/command-visualizer/src/fixture-yaml.ts new file mode 100644 index 0000000000..b073380793 --- /dev/null +++ b/packages/command-visualizer/src/fixture-yaml.ts @@ -0,0 +1,42 @@ +// Fixture YAML reader — SPEC-v2 §2.1. +// +// Was a hand-rolled parser for the recorded-fixture YAML subset (block maps, +// block scalars, block sequences, flow maps). Replaced with cursorless's own +// YAML library, `js-yaml` — the same dependency and the same `load()` entry +// point `@cursorless/lib-node-common`'s loadFixture.ts uses to read these +// fixtures. This drops ~250 lines of bespoke parser and the yaml-scalars.ts +// primitives module in favor of the battle-tested lib, while preserving the +// exported surface (`parseFixtureYaml`, `YamlValue`) that fixture-extract.ts +// and pipeline.ts depend on. +// +// Byte-exact `documentContents` (GATE 0) is preserved: js-yaml's literal block +// scalar (`|` / `|N`) handling is the reference implementation the hand-rolled +// reader was mimicking. + +import { load } from "js-yaml"; + +/** + * Recursive JSON-ish value produced by parsing a fixture YAML document. Matches + * the shape js-yaml's default schema yields for the recorded-fixture subset + * (scalars, block/flow maps, block sequences). Kept stable for downstream + * consumers (fixture-extract.ts coerces via asObj/asArr/num/pos). + */ +export type YamlValue = + | string + | number + | boolean + | null + | YamlValue[] + | { [k: string]: YamlValue }; + +/** + * Parse a full fixture YAML document into a plain object. Returns `{}` for an + * empty/null document so callers can index into it unconditionally. + */ +export function parseFixtureYaml(src: string): { [k: string]: YamlValue } { + const value = load(src) as YamlValue | undefined; + if (value != null && typeof value === "object" && !Array.isArray(value)) { + return value as { [k: string]: YamlValue }; + } + return {}; +} diff --git a/packages/command-visualizer/src/frame-state.ts b/packages/command-visualizer/src/frame-state.ts new file mode 100644 index 0000000000..fecc961242 --- /dev/null +++ b/packages/command-visualizer/src/frame-state.ts @@ -0,0 +1,68 @@ +// Multi-frame state schema — SPEC-v2 §1. A FRAME is exactly one SPEC.md +// `.cl-editor` surface (EditorState minus the doc-level theme/tab). v2 wraps an +// ordered list of frames in a cascade and adds the decoration OVERLAY layer. + +import type { Theme } from "./data/colors"; +import type { Line } from "./columns"; +import type { Pos, Range } from "./serialize"; +import type { DecorationStyle } from "./data/decorations"; + +export type FrameRole = "before" | "during" | "after"; + +export type OverlayRole = + | "flash" + | "highlight" + | "that" + | "source" + | `scope:${string}`; + +// GeneralizedRange (SPEC-v2 §1.1) — character (half-open columns) or line +// (full-width, endLine INCLUSIVE). +export type CharacterRange = { + type: "character"; + start: Pos; + end: Pos; +}; +export type LineRange = { + type: "line"; + startLine: number; + endLine: number; // INCLUSIVE +}; +export type GeneralizedRange = CharacterRange | LineRange; + +export interface Decoration { + style: DecorationStyle; + range: GeneralizedRange; + role: OverlayRole; +} + +export interface Frame { + role: FrameRole; + lines: Line[]; + cursors: Pos[]; + selections: Range[]; + decorations: Decoration[]; + /** Spoken form of the command this frame is the BEFORE of (command strip). */ + command?: string; + /** Clipboard contents relevant to this frame (VisualizerMetadata port). */ + clipboard?: string; + /** Seamless-loop reset frame: re-shows the sequence initial state. */ + reset?: boolean; + /** Pre-gif bumper frame: shows the initial state before step 0 begins. */ + pre?: boolean; + /** Explicit duration override (ms). Defaults resolve by role in timeline.ts. */ + durMs?: number; +} + +export interface CascadeMeta { + spokenForm?: string; + action?: string; + fixture?: string; +} + +export interface CascadeState { + theme: Theme; + tabSize: number; + meta?: CascadeMeta; + frames: Frame[]; +} diff --git a/packages/command-visualizer/src/hat-allocator.ts b/packages/command-visualizer/src/hat-allocator.ts new file mode 100644 index 0000000000..4a0093812d --- /dev/null +++ b/packages/command-visualizer/src/hat-allocator.ts @@ -0,0 +1,175 @@ +// REAL hat allocation — cursorless's actual algorithm via the allocate-hats +// sources, INTERNALIZED under ./vendor/allocate-hats (vendored from the +// allocate-hats repo at commit 42452eb, which itself vendors cursorless's +// allocateHats subgraph at SHA 42452eb — proven byte-identical to the shipped +// prose-overlay bundle). Internalized here so the package compiles in-monorepo +// without the unpublished `allocate-hats` npm dependency; the unused QuickJS +// bundle.ts / proseCompat.ts entry points were dropped during vendoring. +// +// Replaces (task-8tq, 2026-07-07): +// - the greedy per-grapheme color-pool allocator that lived here, and +// - synthetic-shape.ts (sum-of-code-units % 11) — the repo's one known-fake +// render element. DECISIONS §7.5 blessing superseded; see §7.5b. +// +// Model: +// - Every hattable token (single grapheme, per tokenize.ts R5) goes to the +// real allocator with its document position; ranking is cursorless's own +// comparator (line delta, then character delta from the cursor). +// - Fixture marks are passed as OLD ASSIGNMENTS with stability "stable": +// the algorithm keeps them (its own keep-metric) and their (grapheme, +// color) pairs are consumed from the pool, so fill tokens can't collide +// with them — the old step-3b pre-drain, now done by the real thing. +// - Marks render with shape "default" unless a per-fixture override says +// otherwise. This is MORE faithful than the synthetic hash: fixture mark +// keys carry no shape component, meaning the recorded session's hats were +// default-shape. +// - Fill tokens take the allocator's style wholesale (color + shape). With +// the full color x shape style map, shapes appear only under genuine +// collision pressure (>10 tokens sharing an anchor grapheme) — exactly +// like a real cursorless session, instead of hash-random shapes. +// +// Determinism: allocate-hats is pure (no Date/random); same lines + marks + +// cursor -> identical assignments. verify-allocation.ts gates this. + +import { + allocateHats as allocateHatsReal, + StandaloneGraphemeSplitter, + type HatStyleMap, +} from "./vendor/allocate-hats/index"; +import type { Line } from "./columns"; +import type { HatColor } from "./data/colors"; +import type { HatShape } from "./data/shapes"; +import { HAT_COLORS } from "./data/colors"; +import { HAT_SHAPES } from "./data/shapes"; +import type { Pos } from "./serialize"; +import { segmentLines } from "./word-segments"; + +/** True iff the token text is a single hattable grapheme (letter/number/punct/symbol). */ +const SPLITTER = new StandaloneGraphemeSplitter(); + +// --------------------------------------------------------------------------- +// Style map: our full palette x (default + 10 shapes), penalty-ordered the way +// cursorless orders its own map — default color 0, named colors 1, user colors +// 2, +1 for a shape. Pure colors are inserted BEFORE shaped variants so free +// pure colors win penalty ties in the allocator's candidate ordering (matches +// real cursorless, where shapes appear only after the color pool drains). +// --------------------------------------------------------------------------- + +function colorPenalty(color: HatColor): number { + if (color === "default") { + return 0; + } + return color.startsWith("userColor") ? 2 : 1; +} + +export function cssStateHatStyles(): HatStyleMap { + const out: HatStyleMap = {}; + for (const color of HAT_COLORS) { + out[color] = { penalty: colorPenalty(color) }; + } + for (const color of HAT_COLORS) { + for (const shape of HAT_SHAPES) { + if (shape === "default") { + continue; + } // bare color IS the default shape + out[`${color}-${shape}`] = { penalty: colorPenalty(color) + 1 }; + } + } + return out; +} + +/** Split an allocator style name back into our (color, shape) pair. */ +function styleToHat(styleName: string): { color: HatColor; shape: HatShape } { + const dash = styleName.indexOf("-"); + if (dash === -1) { + return { color: styleName as HatColor, shape: "default" }; + } + return { + color: styleName.slice(0, dash) as HatColor, + shape: styleName.slice(dash + 1) as HatShape, + }; +} + +// --------------------------------------------------------------------------- +// Main entry — called by fixture-extract.buildLines after pass 1 has attached +// fixture-mark hats to specific grapheme tokens. +// +// Allocation is per WORD-LEVEL token (word-segments.ts): each segment gets AT +// MOST ONE hat, anchored at the grapheme the real algorithm chooses (its +// returned charIdx). Fixture-marked segments enter as old assignments +// (stability "stable") so the algorithm keeps them and their (grapheme, +// color) pairs drain from the pool; the mark keeps its exact pass-1 grapheme +// position and hat. +// --------------------------------------------------------------------------- + +export function allocateHats( + lines: Line[], + cursor: Pos = { line: 0, character: 0 }, +): void { + const segments = segmentLines(lines); + + const inputTokens = segments.map((seg) => ({ + text: seg.text, + position: { line: seg.lineIdx, character: seg.start }, + })); + + const oldAssignments: { + tokenIdx: number; + charIdx: number; + grapheme: string; + styleName: string; + }[] = []; + const pinned = new Set(); + + segments.forEach((seg, idx) => { + for (const g of seg.graphemes) { + if (!g.hat) { + continue; + } + pinned.add(idx); + oldAssignments.push({ + tokenIdx: idx, + charIdx: g.range.start - seg.start, + grapheme: SPLITTER.normalizeGrapheme(g.text), + styleName: g.hat.color, + }); + break; // one mark pins the whole segment + } + }); + + const assignments = allocateHatsReal({ + tokens: inputTokens, + oldAssignments, + stability: "stable", + enabledHatStyles: cssStateHatStyles(), + cursorPosition: cursor, + }); + + for (const a of assignments) { + const seg = segments[a.tokenIdx]; + if (pinned.has(a.tokenIdx)) { + // Mark keeps its pass-1 hat; tripwire if the algorithm dropped it. + const marked = seg.graphemes.find((g) => g.hat); + if (marked && SPLITTER.normalizeGrapheme(marked.text) !== a.grapheme) { + // Same segment, different anchor grapheme chosen — allowed only if + // the style survived; color change would break fixture fidelity. + const kept = styleToHat(a.styleName); + if (kept.color !== marked.hat!.color) { + throw new Error( + `[hat-allocator] real allocator reassigned pinned mark in segment ` + + `"${seg.text}" (line ${seg.lineIdx}): fixture color ${marked.hat!.color}, ` + + `allocator gave ${a.styleName}`, + ); + } + } + continue; + } + // One hat per word-level token, on the algorithm-chosen grapheme. + const target = seg.graphemes.find( + (g) => g.range.start - seg.start === a.charIdx, + ); + if (target) { + target.hat = styleToHat(a.styleName); + } + } +} diff --git a/packages/command-visualizer/src/index.ts b/packages/command-visualizer/src/index.ts new file mode 100644 index 0000000000..2ed616bb39 --- /dev/null +++ b/packages/command-visualizer/src/index.ts @@ -0,0 +1,20 @@ +// @cursorless/cascade-renderer — public surface. +// +// fixture YAML in -> animated SVG out. See STATUS.md for integration state. + +export { fixtureToCascade, type PipelineOptions } from "./pipeline"; +export { chainCascades, withBumpers, ChainContinuityError } from "./chain"; +export { + serializeCascade, + serializeCascadeDocument, +} from "./serialize-cascade"; +export { wrapCascadeSvg } from "./svg-wrap"; +export { serializeJumbotron, jumbotronCss } from "./jumbotron"; +export { + timelineOf, + frameDurMs, + INITIAL_MS, + DURING_MS, + BUMPER_MS, +} from "./timeline"; +export type { CascadeState, Frame } from "./frame-state"; diff --git a/packages/command-visualizer/src/jumbotron.ts b/packages/command-visualizer/src/jumbotron.ts new file mode 100644 index 0000000000..edc503e212 --- /dev/null +++ b/packages/command-visualizer/src/jumbotron.ts @@ -0,0 +1,503 @@ +// Jumbotron shape — ported from Trillium's VisualizerWrapper implementation +// (cursorless fork branch gen_2026_01_20, packages/test-case-component/src/ +// components/VisualizerWrapper/: JumbotronView.tsx, VisualizerMetadata.tsx, +// StateNavigationDots.tsx, VisualizerWrapper.css). See brain-a08pj. +// +// EVERY render uses the jumbo shape, one step or many: +// +//
+//
<- the cl-cascade frame carousel +//
<- command bar (carousel for chains) +//
<- clipboard, when the fixture has it +//
<- one dot per frame, active follows +//
+// +// The React original drives state with useAnimationState + click handlers; +// this port drives the SAME shape with pure CSS on the shared --dur timeline +// (dots and metadata reuse the per-frame f{i} opacity keyframes), so the GIF +// harness (WAAPI seek) and SVG-as-image delivery both animate it and no JS is +// required. Interactive Controls (pause / highlight toggles) are NOT portable +// to SVG-as-image and are intentionally omitted. + +import type { CascadeState } from "./frame-state"; +import { MS_PER_STATE } from "./data/decorations"; +import { frameDurMs, timelineOf } from "./timeline"; + +const NL = String.fromCharCode(10); + +function esc(s: string): string { + return s + .replace(/&/g, "&") + .replace(//g, ">") + .replace(/"/g, """); +} + +/** Commands carried by the frames, in order. */ +function frameCommands(state: CascadeState): string[] { + return state.frames + .map((f) => f.command) + .filter((c): c is string => c != null && c !== ""); +} + +function hasClipboard(state: CascadeState): boolean { + return state.frames.some((f) => f.clipboard != null); +} + +// --------------------------------------------------------------------------- +// Markup +// --------------------------------------------------------------------------- + +/** Command bar — single command sits static; chains carousel (cmdtrack). */ +const PILL_FONT_MAX = 28; +const PILL_FONT_MIN = 14; +const PILL_PAD_X = 28; // matches .cl-cmd-pill horizontal padding +const MONO_CH_EM = 0.78; // matches svg-wrap CH_EM (SVG-image fallback mono) + +/** Largest font (<= 28px) at which the quoted text fits the bar width. */ +function pillFontPx(text: string, barWidthPx: number): number { + const chars = text.length + 2; // + quotes + const avail = barWidthPx * 0.96 - PILL_PAD_X * 2; + const fit = Math.floor(avail / (chars * MONO_CH_EM)); + return Math.max(PILL_FONT_MIN, Math.min(PILL_FONT_MAX, fit)); +} + +function commandBar(state: CascadeState, barWidthPx?: number): string { + const commands = frameCommands(state); + if (commands.length === 0) { + return ""; + } + const n = Math.max(1, state.frames.length); + const animated = n >= 2; + const chips = commands + .map((c, i) => { + // The bubble is NEVER truncated: it may grow past its 70% carousel cell + // toward the full bar width, and the text shrinks to fit. + const font = + barWidthPx != null ? pillFontPx(c, barWidthPx) : PILL_FONT_MAX; + const styles = [ + animated ? `animation-name: cmdlit-${i}` : "", + font !== PILL_FONT_MAX ? `font-size: ${font}px` : "", + ] + .filter(Boolean) + .join("; "); + return ( + `` + + `"${esc(c)}"` + ); + }) + .join(""); + return ( + `
` + + `
${chips}
` + ); +} + +/** + * Clipboard metadata — the VisualizerMetadata block. Per-frame values stack + * like cascade frames; the one for the active slot fades in via f{i}. + */ +function metadataBlock(state: CascadeState): string { + if (!hasClipboard(state)) { + return ""; + } + const n = Math.max(1, state.frames.length); + const slots = state.frames + .map( + (f, i) => + `` + + `${esc(f.clipboard ?? "(empty)")}`, + ) + .join(""); + return ( + `
` + + `
Clipboard:` + + `${slots}
` + ); +} + +/** Navigation dots — one per frame; the active marker follows the timeline. */ +function dots(state: CascadeState): string { + const n = Math.max(1, state.frames.length); + if (n < 2) { + return ""; + } + // ONE dot per STEP. The dot expresses the step phase as intensity: + // disabled (0) -> initial (level 1, dim) -> during (level 2, full + + // white ring) -> after (level 3, full) -> disabled. + // Single-step renders therefore have a single dot. In chains, a step's + // AFTER overlaps the next step's INITIAL on the merged frame — dot i at + // level 3 while dot i+1 sits at level 1, expressing the shared state. + const items = state.frames + .map((f, i) => { + if (f.command == null || f.command === "") { + return ""; + } + const hasDuring = state.frames[i + 1]?.role === "during"; + const names = hasDuring ? `dotwin-${i}, dotissued-${i}` : `dotwin-${i}`; + return ( + `` + + `` + ); + }) + .join(""); + return ``; +} + +/** + * Wrap a serialized cascade in the full jumbotron shape. + * @param inner serializeCascade(state) markup (the frame carousel). + */ +export function serializeJumbotron( + state: CascadeState, + inner: string, + opts: { barWidthPx?: number } = {}, +): string { + return ( + `
` + + NL + + `
${NL}${inner}${NL}
` + + NL + + commandBar(state, opts.barWidthPx) + + NL + + metadataBlock(state) + + NL + + dots(state) + + NL + + `
` + ); +} + +// --------------------------------------------------------------------------- +// CSS — ported from VisualizerWrapper.css / VisualizerMetadata.css, with +// docusaurus --ifm-* vars replaced by our theme vars, and the useAnimationState +// carousel replaced by --dur timeline animations. +// --------------------------------------------------------------------------- + +/** Fraction of ONE slot spent sliding to the next command. */ +const CMD_SLIDE_FRAC = 0.18; +/** Fraction of ONE slot the executed (lit) command holds before sliding out. */ +const LIT_HOLD_FRAC = 0.25; +/** The command enters AT its step's initial start — the same beat as the + * dot's level-1 transition (grey -> dim blue) — so "dot lights" and "bubble + * animates into frame" are ONE visual event, not two. */ +const ENTER_FRAC = 0; + +export function jumbotronCss( + state: CascadeState, + flashPulseMs: number = 100, +): string { + const n = Math.max(1, state.frames.length); + const commands = frameCommands(state); + + const base = ` +/* block, not inline-block: an inline-block wrapper sizes to max-content and + the carousel chips (flex-basis 100%, nowrap) would inflate it to N x width */ +.visualizer-wrapper { display: block; } +.visualizer-jumbotron .jumbotron-container { position: relative; } + +.visualizer-command { + overflow: hidden; + margin-top: 8px; +} +.cl-cmd-track { display: flex; gap: 2%; } +/* CENTER-MODE conveyor: the ACTIVE command sits in the exact center of the + jumbotron bar (70% chip + 15% lead/tail margins); the previous command's + tail stays visible at the left, the next peeks at the right, and each + slide lands the incoming command dead-center. */ +.cl-cmd { + flex: 0 0 70%; + box-sizing: border-box; + text-align: center; + white-space: nowrap; + /* no overflow clipping: the pill may grow past its cell (never truncate) */ +} +.cl-cmd:first-child { margin-left: 15%; } +.cl-cmd:last-child { margin-right: 15%; } +/* The command is a PILL: text color is CONSTANT; the background carries the + state (disabled -> active) via cmdlit-{i}. Entrance animates the pill into + jumbospace (rise + fade). */ +.cl-cmd-pill { + display: inline-block; + box-sizing: border-box; + padding: 10px 28px; + border-radius: 999px; + font-size: 28px; + line-height: 1.15; + color: var(--pill-fg, #f2f2f2); + background: var(--pill-disabled, #333); + animation: cmdlit-0 var(--dur, 2000ms) linear 1 forwards paused; +} + +.visualizer-metadata { + display: flex; + flex-direction: column; + gap: 6px; + padding: 10px 14px; + margin-top: 8px; + background: var(--jumbo-emphasis, #262626); + border: 1px solid var(--jumbo-border, #3a3a3a); + border-radius: 6px; + font-size: 13px; + color: var(--jumbo-fg, #d0d0d0); +} +.visualizer-metadata-item { display: flex; gap: 8px; align-items: baseline; } +.visualizer-metadata-item strong { font-size: 12px; opacity: 0.65; } +.meta-clips { position: relative; display: inline-block; min-height: 1.2em; flex: 1; } +.meta-clip { + position: absolute; + inset: 0; + opacity: 0; + white-space: pre; + overflow: hidden; + text-overflow: ellipsis; + animation: f0 var(--dur, ${n * MS_PER_STATE}ms) steps(1, end) 1 forwards paused; +} +.meta-clip[data-slot="0"] { position: relative; } + +.jumbotron-dots { + display: flex; + justify-content: center; + gap: 10px; + margin-top: 10px; + padding: 4px; +} +.jumbotron-dot { + position: relative; + width: 12px; + height: 12px; + border-radius: 50%; + border: 2px solid var(--jumbo-border, #4a4a4a); + background: var(--jumbo-emphasis, #262626); + box-sizing: border-box; +} +.jumbotron-dot-active { + position: absolute; + inset: -3px; + border-radius: 50%; + background: var(--jumbo-primary, #4c9aff); + border: 2px solid transparent; + box-sizing: border-box; + transform: scale(1.15); + opacity: 0; + /* two slots: [0] slot visibility (f{i}), [1] issued ring (dotissued-{i}) */ + animation: + f0 var(--dur, ${n * MS_PER_STATE}ms) steps(1, end) 1 forwards paused, + f0 var(--dur, ${n * MS_PER_STATE}ms) steps(1, end) 1 forwards paused; +} +`; + + const themed = ` +.visualizer-jumbotron { --jumbo-emphasis: #262626; --jumbo-border: #3a3a3a; --jumbo-fg: #d0d0d0; --jumbo-primary: #4c9aff; --pill-fg: #f2f2f2; --pill-disabled: #333333; --pill-active: #1f6fd6; } +.visualizer-jumbotron[data-theme="light"] { --jumbo-emphasis: #f0f0f0; --jumbo-border: #c8c8c8; --jumbo-fg: #333; --jumbo-primary: #1a6ee0; --pill-fg: #ffffff; --pill-disabled: #9aa4b0; --pill-active: #1a6ee0; } +`; + + // Timeline-based windows (weighted phases: initial 1000ms, during 500ms). + // COMMAND lifecycle: ABSENT -> ENTERED (muted) -> EXECUTED (lit at the + // start of ITS during phase — when its referenceFlashes fire) -> carried + // out by the (delayed) slide as the next step begins. + const LIT_RAMP_MS = 150; + // Slide fires AT the frame boundary — the dot advance and the command + // slide are the SAME visual beat (they read as one motion). + const LIT_HOLD_MS = 0; + const SLIDE_MS = 220; + const tl = timelineOf(state.frames); + const durMs = tl.totalMs; + const msPct = (ms: number) => (ms / durMs) * 100; + const ramp = msPct(LIT_RAMP_MS); + const pctc = (x: number) => `${Math.max(0, Math.min(100, x)).toFixed(3)}%`; + + const cmdFrames: number[] = []; + state.frames.forEach((f, i) => { + if (f.command != null && f.command !== "") { + cmdFrames.push(i); + } + }); + const resetIdx = state.frames.findIndex((f) => f.reset); + + /** [startPct, endPct] of frame k's ISSUE window: its during phase when it + * has one, else a default-pulse sliver before the next frame. */ + const issueWindow = (k: number): [number, number] => { + const next = state.frames[k + 1]; + if (next?.role === "during") { + return [msPct(tl.startMs[k + 1]), msPct(tl.endMs[k + 1])]; + } + const boundary = msPct(tl.endMs[k]); + return [ + Math.max(msPct(tl.startMs[k]), boundary - msPct(flashPulseMs)), + boundary, + ]; + }; + + let litKf = ""; + if (n >= 2 && commands.length >= 1) { + const parts: string[] = []; + + // Dot phase levels (dotwin-{k}), one per step: disabled(0) -> + // initial(0.45) -> during(1) -> after(1) -> disabled(0). The ring + // (dotissued-{k}) marks the during phase distinctly, so level 2 reads + // full+ring and level 3 full without. + const L1 = 0.45; + cmdFrames.forEach((k) => { + const iniLo = msPct(tl.startMs[k]); + const durFrame = state.frames[k + 1]?.role === "during" ? k + 1 : null; + const durLo = + durFrame != null ? msPct(tl.startMs[durFrame]) : msPct(tl.endMs[k]); + const aftFrame = durFrame != null ? durFrame + 1 : k + 1; + const aftLo = msPct(tl.startMs[aftFrame] ?? tl.endMs[k]); + const aftHi = msPct(tl.endMs[aftFrame] ?? tl.endMs[k]); + const kf = [ + ` 0% { opacity: ${iniLo === 0 ? L1 : 0}; }`, + ...(iniLo > 0 + ? [ + ` ${pctc(iniLo)} { opacity: 0; }`, + ` ${pctc(iniLo + 0.001)} { opacity: ${L1}; }`, + ] + : []), + ` ${pctc(durLo)} { opacity: ${L1}; }`, + ` ${pctc(durLo + 0.001)} { opacity: 1; }`, + ` ${pctc(aftHi)} { opacity: 1; }`, + ...(aftHi < 100 + ? [ + ` ${pctc(aftHi + 0.001)} { opacity: 0; }`, + ` 100% { opacity: 0; }`, + ] + : [` 100% { opacity: 1; }`]), + ]; + parts.push(`@keyframes dotwin-${k} {` + NL + kf.join(NL) + NL + `}`); + }); + + // ISSUED dot ring — white border across the step's during window. + cmdFrames.forEach((k) => { + if (state.frames[k + 1]?.role !== "during") { + return; + } + const [wLo, wHi] = issueWindow(k); + parts.push( + `@keyframes dotissued-${k} {` + + NL + + ` 0% { border-color: transparent; }` + + NL + + ` ${pctc(wLo)} { border-color: transparent; }` + + NL + + ` ${pctc(wLo + 0.001)} { border-color: #ffffff; }` + + NL + + ` ${pctc(wHi)} { border-color: #ffffff; }` + + NL + + ` ${pctc(wHi + 0.001)} { border-color: transparent; }` + + NL + + ` 100% { border-color: transparent; }` + + NL + + `}`, + ); + }); + + // Command pills: entrance into jumbospace (chip 0 rises + fades in), + // then the BACKGROUND carries disabled -> active (text color constant). + const DIS = "var(--pill-disabled, #333)"; + const ACT = "var(--pill-active, #1f6fd6)"; + cmdFrames.forEach((k, i) => { + const enterAt = + msPct(tl.startMs[k]) + msPct(frameDurMs(state.frames[k])) * ENTER_FRAC; + const [litStart] = issueWindow(k); + const isLast = i === cmdFrames.length - 1; + const kfParts: string[] = []; + if (i === 0) { + kfParts.push( + ` 0% { opacity: 0; transform: translateY(14px); background-color: ${DIS}; }`, + ); + if (enterAt > 0) { + kfParts.push( + ` ${pctc(enterAt)} { opacity: 0; transform: translateY(14px); background-color: ${DIS}; }`, + ); + } + kfParts.push( + ` ${pctc(enterAt + ramp)} { opacity: 1; transform: translateY(0); background-color: ${DIS}; }`, + ); + } else { + kfParts.push( + ` 0% { opacity: 1; transform: translateY(0); background-color: ${DIS}; }`, + ); + } + const effLit = Math.max(litStart, enterAt + ramp); + // SNAP to active: the pill background flips at the EXACT instant the + // dot ring turns white (both = the during start). + if (effLit > 0) { + kfParts.push( + ` ${pctc(effLit)} { opacity: 1; transform: translateY(0); background-color: ${DIS}; }`, + ); + } + if (isLast) { + kfParts.push( + ` ${pctc(Math.min(effLit + 0.001, 100))} { opacity: 1; transform: translateY(0); background-color: ${ACT}; }`, + ); + if (resetIdx > 0) { + const resetAt = msPct(tl.startMs[resetIdx]); + kfParts.push( + ` ${pctc(resetAt)} { opacity: 1; transform: translateY(0); background-color: ${ACT}; }`, + ); + kfParts.push( + ` ${pctc(resetAt + ramp)} { opacity: 1; transform: translateY(0); background-color: ${DIS}; }`, + ); + kfParts.push( + ` 100% { opacity: 1; transform: translateY(0); background-color: ${DIS}; }`, + ); + } else { + kfParts.push( + ` 100% { opacity: 1; transform: translateY(0); background-color: ${ACT}; }`, + ); + } + } else { + const nextStart = msPct(tl.startMs[cmdFrames[i + 1]]); + const litEnd = nextStart + msPct(LIT_HOLD_MS + SLIDE_MS); + kfParts.push( + ` ${pctc(Math.min(effLit + 0.001, litEnd))} { opacity: 1; transform: translateY(0); background-color: ${ACT}; }`, + ); + kfParts.push( + ` ${pctc(litEnd)} { opacity: 1; transform: translateY(0); background-color: ${ACT}; }`, + ); + kfParts.push( + ` ${pctc(litEnd + ramp)} { opacity: 1; transform: translateY(0); background-color: ${DIS}; }`, + ); + kfParts.push( + ` 100% { opacity: 1; transform: translateY(0); background-color: ${DIS}; }`, + ); + } + parts.push(`@keyframes cmdlit-${i} {` + NL + kfParts.join(NL) + NL + `}`); + }); + litKf = parts.join(NL) + NL; + } + + if (commands.length <= 1) { + return base + themed + litKf; + } + + // Command carousel: slide to chip i+1 shortly after its step begins (the + // previous chip lingers lit for LIT_HOLD_MS first), eased. + const step = 72; + const pos = (i: number) => + `transform: translateX(-${(i * step).toFixed(4)}%);`; + const kf: string[] = [` 0% { ${pos(0)} }`]; + cmdFrames.slice(1).forEach((k, j) => { + const at = msPct(tl.startMs[k]) + msPct(LIT_HOLD_MS); + kf.push(` ${pctc(at)} { ${pos(j)} }`); + kf.push(` ${pctc(at + msPct(SLIDE_MS))} { ${pos(j + 1)} }`); + }); + kf.push(` 100% { ${pos(cmdFrames.length - 1)} }`); + + return ( + base + + themed + + litKf + + "@keyframes cmdtrack {" + + NL + + kf.join(NL) + + NL + + "}" + + NL + + ".cl-cmd-track { animation: cmdtrack var(--dur, " + + String(n * MS_PER_STATE) + + "ms) cubic-bezier(0.4, 0, 0.2, 1) 1 forwards paused; }" + + NL + ); +} diff --git a/packages/command-visualizer/src/overlays.ts b/packages/command-visualizer/src/overlays.ts new file mode 100644 index 0000000000..dc7ad2f72b --- /dev/null +++ b/packages/command-visualizer/src/overlays.ts @@ -0,0 +1,152 @@ +// Overlay resolution — SPEC-v2 §3.2 / §6. Maps a frame's decorations + selection +// onto the COLUMN grid (SPEC.md §2 column mapping, not raw char index — audit-5 +// §4 rule), resolving single-winner precedence per cell (selection < highlight < +// flash, last wins). Also resolves full-width line-range bands. + +import { type Column, expandColumns } from "./columns"; +import type { Decoration, Frame, OverlayRole } from "./frame-state"; +import type { DecorationStyle } from "./data/decorations"; +import { overlayPrecedence } from "./data/decorations"; +import type { Range } from "./serialize"; + +// Role sub-rank, used to break style-precedence ties (SPEC-v2 §3.2 / DECISIONS +// §7.1+§7.2): a REAL ide.flash outranks a DERIVED that/source overlay on the +// same range, so e.g. justAdded (flash) wins over a thatMark→referenced on the +// inserted text. selection < highlight < {derived that/source} < flash. +function roleRank(role: OverlayRole | "selection"): number { + if (role === "selection") { + return 0; + } + if (role === "flash") { + return 3; + } + if (role === "highlight") { + return 1; + } + return 2; // that | source | scope:* (derived) +} + +export interface CellOverlay { + /** the single winning background style for this cell (or null) */ + winner: DecorationStyle | "selection" | null; + /** all overlays present (for data-flash-stack test visibility) */ + stack: (DecorationStyle | "selection")[]; +} + +export interface LineOverlay { + /** per visual column -> overlay (indexed by Column.col start) */ + byCol: Map; + /** full-width line-range band style, if this line is in any line decoration */ + lineFlash: DecorationStyle | null; +} + +/** Columns covered by a half-open character range on a given line. */ +function colsForCharRange( + cols: Column[], + lineIdx: number, + startLine: number, + startCh: number, + endLine: number, + endCh: number, +): number[] { + if (lineIdx < startLine || lineIdx > endLine) { + return []; + } + const loCh = lineIdx === startLine ? startCh : 0; + const hiCh = lineIdx === endLine ? endCh : Infinity; + const out: number[] = []; + for (const c of cols) { + // a cell starts at charIndex; treat it as covering [charIndex, nextCharIndex) + if (c.charIndex >= loCh && c.charIndex < hiCh) { + out.push(c.col); + } + } + return out; +} + +/** Resolve all overlays for one line of a frame. */ +function resolveLine( + cols: Column[], + lineIdx: number, + selections: Range[], + decorations: Decoration[], +): LineOverlay { + const byCol = new Map(); + // track the winning (stylePrec, roleRank) tuple per column + const winRank = new Map(); + + const add = ( + col: number, + style: DecorationStyle | "selection", + role: OverlayRole | "selection", + ) => { + let cell = byCol.get(col); + if (!cell) { + cell = { winner: null, stack: [] }; + byCol.set(col, cell); + } + cell.stack.push(style); + // lexicographic rank: style precedence dominates, role breaks ties. + const rank = overlayPrecedence(style) * 10 + roleRank(role); + const prev = winRank.get(col); + if (prev === undefined || rank >= prev) { + cell.winner = style; // last-wins at equal rank + winRank.set(col, rank); + } + }; + + // selection (precedence 0) + for (const sel of selections) { + const a = sel.start; + const b = sel.end; + for (const col of colsForCharRange( + cols, + lineIdx, + a.line, + a.character, + b.line, + b.character, + )) { + add(col, "selection", "selection"); + } + } + + // character-range decorations (highlight prec 1, flash prec 2) + let lineFlash: DecorationStyle | null = null; + for (const dec of decorations) { + if (dec.range.type === "line") { + if (lineIdx >= dec.range.startLine && lineIdx <= dec.range.endLine) { + lineFlash = dec.style; // last line decoration wins + } + continue; + } + const r = dec.range; + for (const col of colsForCharRange( + cols, + lineIdx, + r.start.line, + r.start.character, + r.end.line, + r.end.character, + )) { + add(col, dec.style, dec.role); + } + } + + return { byCol, lineFlash }; +} + +/** Resolve overlays for every line of a frame. Returns a per-line array. */ +export function resolveFrameOverlays( + frame: Frame, + tabSize: number, +): LineOverlay[] { + return frame.lines.map((line, i) => + resolveLine( + expandColumns(line, tabSize), + i, + frame.selections, + frame.decorations, + ), + ); +} diff --git a/packages/command-visualizer/src/pipeline.ts b/packages/command-visualizer/src/pipeline.ts new file mode 100644 index 0000000000..2239b98350 --- /dev/null +++ b/packages/command-visualizer/src/pipeline.ts @@ -0,0 +1,319 @@ +// Fixture → state pipeline — SPEC-v2 §2 (8 steps). Pure, deterministic. +// yml → frames → tokenize → marks→hats → synthetic shape → flashes→overlays +// → that/source/highlights → CascadeState. Render contract (SPEC.md §3/§4) +// is unchanged downstream. + +import { readFileSync } from "node:fs"; +import { parseFixtureYaml } from "./fixture-yaml"; +import type { HatColor, Theme } from "./data/colors"; +import type { HatShape } from "./data/shapes"; +import type { + CascadeState, + Frame, + GeneralizedRange, +} from "./frame-state"; +import type { DecorationStyle } from "./data/decorations"; +import type { Pos } from "./serialize"; +import { + asArr, + asObj, + buildLines, + deriveSelections, + parseMarks, + pos, + toGeneralizedRange, +} from "./fixture-extract"; + +import { fixtureRoot } from "./fixture-root"; + +// Resolved lazily: fixtureRoot() throws when no cursorless checkout exists, +// which must not fire at module load in serverless (the API path reads +// vendored fixtures and never touches disk). +let fixtureRootCache: string | undefined; +function FIXTURE_ROOT_LAZY(): string { + return (fixtureRootCache ??= fixtureRoot()); +} + +// Route a flash style to its native frame (SPEC-v2 §1.2 / §2.6). +function flashRidesAfter(style: string): boolean { + return style === "justAdded"; +} + +export interface PipelineOptions { + shapeOverride?: Record; + theme?: Theme; + tabSize?: number; + /** "dense" (default) = real-allocator fill everywhere; "marks-only" = exactly the recorded marks. */ + fill?: "dense" | "marks-only"; + /** Position-keyed exact-hat overrides, keyed "{line}:{startChar}" — applied last, wins over everything. */ + hatOverride?: Record; +} + +/** Full pipeline: fixture YAML text → CascadeState. */ +export function fixtureToCascade( + src: string, + fixtureRel: string, + opts: PipelineOptions = {}, +): CascadeState { + const doc = parseFixtureYaml(src); + const theme: Theme = opts.theme ?? "dark"; + const tabSize = opts.tabSize ?? 4; + + const command = asObj(doc.command); + const action = asObj(command?.action); + const meta = { + spokenForm: + typeof command?.spokenForm === "string" ? command.spokenForm : undefined, + action: typeof action?.name === "string" ? action.name : undefined, + fixture: fixtureRel, + }; + + const initial = asObj(doc.initialState); + const final = asObj(doc.finalState); + + // Clipboard visibility per state — ported from VisualizerMetadata.tsx + // (gen_2026_01_20): cut/copy PRODUCE clipboard (visible on AFTER only); + // paste CONSUMES it (visible on all states). + const actionName = meta.action ?? ""; + const initClip = + typeof initial?.clipboard === "string" ? initial.clipboard : undefined; + const finalClip = + typeof final?.clipboard === "string" ? final.clipboard : undefined; + const clipProduced = + actionName === "cutToClipboard" || actionName === "copyToClipboard"; + const clipConsumed = actionName === "pasteFromClipboard"; + const clipFor = (state: "before" | "after"): string | undefined => { + if (clipProduced) { + return state === "after" ? finalClip : undefined; + } + if (clipConsumed) { + return initClip; + } + return undefined; + }; + + const ide = asObj(doc.ide); + + const initMarks = parseMarks(asObj(initial?.marks)); + + // Step 2: BEFORE frame. + const beforeLines = buildLines( + (initial?.documentContents as string) ?? "", + initMarks, + { + shapeOverride: opts.shapeOverride, + fill: opts.fill, + hatOverride: opts.hatOverride, + }, + ); + const beforeSel = deriveSelections(asArr(initial?.selections)); + const beforeFrame: Frame = { + role: "before", + lines: beforeLines, + cursors: beforeSel.cursors, + selections: beforeSel.selections, + decorations: [], + command: meta.spokenForm, + clipboard: clipFor("before"), + }; + + const frames: Frame[] = [beforeFrame]; + + // AFTER frame (omit if no finalState — error fixtures, SPEC-v2 §2.2). + let afterFrame: Frame | null = null; + if (final && typeof final.documentContents === "string") { + // Final docs ship no marks; re-tokenize identically (no hats on after). + const afterLines = buildLines(final.documentContents, [], { + shapeOverride: opts.shapeOverride, + fill: opts.fill, + hatOverride: opts.hatOverride, + }); + const afterSel = deriveSelections(asArr(final.selections)); + afterFrame = { + role: "after", + lines: afterLines, + cursors: afterSel.cursors, + selections: afterSel.selections, + decorations: [], + clipboard: clipFor("after"), + }; + frames.push(afterFrame); + } + + const duringFlashes: { style: DecorationStyle; range: GeneralizedRange }[] = + []; + + // Step 6b (derived referenceFlashes): tutorial-corpus recordings carry NO + // ide.flashes (verified 2026-07-07 — all 10 tutorial-1-basics fixtures have + // zero) even for document edits. Cursorless flashes are deterministic from + // the edit itself, so when a fixture records none and the doc changed, + // derive them: char-level common prefix/suffix -> removed span flashes + // pendingDelete on BEFORE, inserted span flashes justAdded on AFTER. + const recordedFlashes = asArr(ide?.flashes); + const initDoc = (initial?.documentContents as string) ?? ""; + const finDoc = + typeof final?.documentContents === "string" ? final.documentContents : null; + if ( + recordedFlashes.length === 0 && + finDoc != null && + finDoc !== initDoc && + afterFrame + ) { + const toPos = (doc: string, off: number): Pos => { + const upto = doc.slice(0, off); + const line = (upto.match(/\n/g) ?? []).length; + const character = off - (upto.lastIndexOf("\n") + 1); + return { line, character }; + }; + let p = 0; + while ( + p < initDoc.length && + p < finDoc.length && + initDoc[p] === finDoc[p] + ) { + p++; + } + let sfx = 0; + while ( + sfx < initDoc.length - p && + sfx < finDoc.length - p && + initDoc[initDoc.length - 1 - sfx] === finDoc[finDoc.length - 1 - sfx] + ) { + sfx++; + } + const remEnd = initDoc.length - sfx; + const insEnd = finDoc.length - sfx; + if (remEnd > p) { + duringFlashes.push({ + style: "pendingDelete" as DecorationStyle, + range: { + type: "character", + start: toPos(initDoc, p), + end: toPos(initDoc, remEnd), + }, + }); + } + if (insEnd > p) { + afterFrame.decorations.push({ + style: "justAdded" as DecorationStyle, + role: "flash", + range: { + type: "character", + start: toPos(finDoc, p), + end: toPos(finDoc, insEnd), + }, + }); + } + } + + // Step 6: flashes. justAdded rides the AFTER frame (post-edit); every + // other flash is PRE-EDIT and rides the dedicated DURING frame (built + // below) — reference-class flashes sequence before deletion flashes there. + for (const f of asArr(ide?.flashes)) { + const fo = asObj(f); + if (!fo) { + continue; + } + const style = String(fo.style) as DecorationStyle; + const range = toGeneralizedRange(asObj(fo.range) ?? {}); + if (!range) { + continue; + } + if (flashRidesAfter(style) && afterFrame) { + afterFrame.decorations.push({ style, range, role: "flash" }); + } else { + duringFlashes.push({ style, range }); + } + } + + // Build the DURING frame (the execution beat — the instant the command + // pill goes active). ALWAYS present when the step has a final state, so + // every command occupies the same time scope. Content depends on flashes: + // - WITH pre-edit flashes: the initial doc, flashes firing (reference + // half then delete half) — the edit lands at the phase end. + // - WITHOUT flashes (pure selection commands like "take cap"): the edit + // is instantaneous in a real editor, so the during frame shows the + // FINAL state — the selection highlight lands in the SAME frame as the + // pill activation. + if (afterFrame) { + const instant = duringFlashes.length === 0; + const src = instant ? afterFrame : beforeFrame; + const duringFrame: Frame = { + role: "during", + lines: src.lines, + cursors: src.cursors, + selections: src.selections, + decorations: instant + ? [] + : duringFlashes.map(({ style, range }) => ({ + style, + range, + role: "flash" as const, + })), + clipboard: src.clipboard, + }; + frames.splice(1, 0, duringFrame); + } + + // Step 7: highlights → decorations (painted on before frame in this corpus). + for (const h of asArr(ide?.highlights)) { + const ho = asObj(h); + if (!ho) { + continue; + } + const style = String(ho.style) as DecorationStyle; + for (const r of asArr(ho.ranges)) { + const range = toGeneralizedRange(asObj(r) ?? {}); + if (range) { + beforeFrame.decorations.push({ style, range, role: "highlight" }); + } + } + } + + // Step 7: thatMark / sourceMark → AFTER decorations (rendered as referenced). + if (afterFrame) { + for (const tm of asArr(final?.thatMark)) { + const o = asObj(tm); + const cr = asObj(o?.contentRange); + if (cr) { + afterFrame.decorations.push({ + style: "referenced", + role: "that", + range: { + type: "character", + start: pos(cr.start), + end: pos(cr.end), + }, + }); + } + } + for (const sm of asArr(final?.sourceMark)) { + const o = asObj(sm); + const cr = asObj(o?.contentRange); + if (cr) { + afterFrame.decorations.push({ + style: "pendingModification0", + role: "source", + range: { + type: "character", + start: pos(cr.start), + end: pos(cr.end), + }, + }); + } + } + } + + return { theme, tabSize, meta, frames }; +} + +/** Convenience: load a recorded fixture by relative path. */ +export function loadFixtureCascade( + fixtureRel: string, + opts: PipelineOptions = {}, +): CascadeState { + const src = readFileSync(`${FIXTURE_ROOT_LAZY()}/${fixtureRel}`, "utf8"); + return fixtureToCascade(src, fixtureRel, opts); +} + +export { FIXTURE_ROOT_LAZY as fixtureRootPath }; diff --git a/packages/command-visualizer/src/serialize-cascade.ts b/packages/command-visualizer/src/serialize-cascade.ts new file mode 100644 index 0000000000..fe87a41624 --- /dev/null +++ b/packages/command-visualizer/src/serialize-cascade.ts @@ -0,0 +1,219 @@ +// Cascade serializer — SPEC-v2 §4. Pure CascadeState → HTML. Zero render-time JS. +// Emits N stacked `.frame` surfaces in one `.cl-cascade`, the symbol sheet ONCE, +// per-frame `@keyframes f{k}` opacity timeline, and the decoration overlay layer +// (data-flash / data-hl / data-line-flash) resolved single-winner per cell. + +import { type Column, expandColumns, lineWidth } from "./columns"; +import { styleSheet } from "./css"; +import { cascadeStyleSheet, cascadeThemeBridge } from "./css-cascade"; +import { jumbotronCss, serializeJumbotron } from "./jumbotron"; +import type { CellOverlay } from "./overlays"; +import { symbolSheet } from "./symbols"; +import type { CascadeState, Frame } from "./frame-state"; +import { resolveFrameOverlays, type LineOverlay } from "./overlays"; +import { HIGHLIGHT_STYLES, MS_PER_STATE } from "./data/decorations"; +import { timelineOf } from "./timeline"; + +function esc(s: string): string { + return s.replace(/&/g, "&").replace(//g, ">"); +} + +function charToCol(cols: Column[], charIndex: number): number { + for (const c of cols) { + if (charIndex <= c.charIndex) { + return c.col; + } + } + return lineWidth(cols); +} + +function overlayAttr(winner: string | null): string { + if (!winner) { + return ""; + } + if (winner === "selection") { + return ' data-sel=""'; + } + if ((HIGHLIGHT_STYLES as string[]).includes(winner)) { + return ` data-hl="${winner}"`; + } + return ` data-flash="${winner}"`; +} + +function emitSpan(c: Column, cell: CellOverlay | undefined): string { + const classes = c.isAnchor ? "ch ch--anchor" : "ch"; + const spanAttr = + c.width === 2 + ? ` data-col-span="2"` + : c.width > 2 + ? ` data-col-span="${c.width}"` + : ""; + const winner = cell?.winner ?? null; + const ovAttr = overlayAttr(winner); + const stackAttr = + cell && cell.stack.length > 1 + ? ` data-flash-stack="${cell.stack.join(",")}"` + : ""; + const hatAttr = c.isAnchor + ? ` data-hat="" data-hat-color="${c.hatColor}" data-hat-shape="${c.hatShape}"` + + ` data-anchor-col="${c.col}"` + : ""; + const hat = c.isAnchor + ? `` + : ""; + const text = c.text === "" ? "" : esc(c.text); + return ( + `` + + `${text}${hat}` + ); +} + +function emitLine( + frame: Frame, + lineIdx: number, + tabSize: number, + overlay: LineOverlay, + lineNumbers: boolean, +): string { + const cols = expandColumns(frame.lines[lineIdx], tabSize); + const cursors = frame.cursors.filter((c) => c.line === lineIdx); + + const caretAtCol = new Map(); + for (const cur of cursors) { + const col = charToCol(cols, cur.character); + caretAtCol.set( + col, + (caretAtCol.get(col) ?? "") + + ``, + ); + } + + // R3: optional leading line-number cell (1-based, like a real editor). Only + // emitted when the gutter is on — keeps the no-gutter output byte-identical. + const gutter = lineNumbers + ? `` + : ""; + + let inner = ""; + for (const c of cols) { + if (caretAtCol.has(c.col)) { + inner += caretAtCol.get(c.col); + } + inner += emitSpan(c, overlay.byCol.get(c.col)); + } + const endCol = lineWidth(cols); + if (caretAtCol.has(endCol)) { + inner += caretAtCol.get(endCol); + } + + const lineFlashAttr = overlay.lineFlash + ? ` data-line-flash="${overlay.lineFlash}"` + : ""; + // NO leading whitespace and NO newline joins around cl-line: this markup + // lives inside .cl-code (white-space: pre), where inter-element whitespace + // renders as phantom blank lines (latent flaw exposed by the fixed-height + // SVG viewport, task-mim). + return `
${gutter}${inner}
`; +} + +function emitFrame( + frame: Frame, + frameIdx: number, + tabSize: number, + lineNumbers: boolean, +): string { + const overlays = resolveFrameOverlays(frame, tabSize); + const lines = frame.lines + .map((_, i) => emitLine(frame, i, tabSize, overlays[i], lineNumbers)) + .join(""); + return ( + `
\n` + + `
${lines}
\n` + + `
` + ); +} + +/** Render options for the cascade serializer. */ +export interface CascadeRenderOptions { + /** R3: emit the left line-number gutter. OFF by default. */ + lineNumbers?: boolean; +} + +/** Widest line number across all frames → digit count for the gutter width. */ +function gutterDigits(state: CascadeState): number { + const maxLines = Math.max(1, ...state.frames.map((f) => f.lines.length)); + return String(maxLines).length; +} + +/** Serialize a CascadeState to the inner cascade markup. */ +export function serializeCascade( + state: CascadeState, + opts: CascadeRenderOptions = {}, +): string { + const lineNumbers = opts.lineNumbers ?? false; + const n = state.frames.length; + const tl = timelineOf(state.frames); + const frames = state.frames + .map((f, i) => emitFrame(f, i, state.tabSize, lineNumbers)) + .join("\n"); + const metaAttr = state.meta?.fixture + ? ` data-fixture="${esc(state.meta.fixture)}"` + : ""; + const spokenAttr = state.meta?.spokenForm + ? ` data-spoken-form="${esc(state.meta.spokenForm)}"` + : ""; + // R3: only when ON do we add the gutter attribute + digit-width var. OFF → + // neither appears, so the markup/CSS hook is byte-identical to before. + const gutterAttr = lineNumbers ? ` data-line-numbers=""` : ""; + const gutterVar = lineNumbers + ? ` --gutter-digits:${gutterDigits(state)};` + : ""; + return ( + `
\n` + + `${symbolSheet()}\n` + + `${frames}\n` + + `
` + ); +} + +/** Full standalone HTML document for a cascade. */ +export function serializeCascadeDocument( + state: CascadeState, + title = "cursorless cascade", + opts: CascadeRenderOptions = {}, +): string { + const bg = state.theme === "dark" ? "#141414" : "#e8e8e8"; + const caption = state.meta + ? `
${esc( + [ + state.meta.spokenForm && `"${state.meta.spokenForm}"`, + state.meta.action, + state.meta.fixture, + ] + .filter(Boolean) + .join(" · "), + )}
` + : ""; + return ` + + + +${esc(title)} + + + +${caption} +${serializeJumbotron(state, serializeCascade(state, opts))} + +`; +} diff --git a/packages/command-visualizer/src/serialize.ts b/packages/command-visualizer/src/serialize.ts new file mode 100644 index 0000000000..c84da78980 --- /dev/null +++ b/packages/command-visualizer/src/serialize.ts @@ -0,0 +1,160 @@ +// Serializer — SPEC §5. Pure state JSON → HTML string. No render-time logic (D1). + +import type { Theme } from "./data/colors"; +import { type Column, type Line, expandColumns, lineWidth } from "./columns"; +import { styleSheet } from "./css"; +import { symbolSheet } from "./symbols"; + +export interface Pos { + line: number; + character: number; // UTF-16 char index within the line +} +export interface Range { + start: Pos; + end: Pos; +} + +export interface EditorState { + theme: Theme; + tabSize: number; + lines: Line[]; + cursors?: Pos[]; + selections?: Range[]; +} + +function esc(s: string): string { + return s.replace(/&/g, "&").replace(//g, ">"); +} + +/** Is a given char index on a given line inside any selection range? */ +function inAnySelection( + lineIdx: number, + charIndex: number, + selections: Range[], +): boolean { + for (const sel of selections) { + const { start, end } = orderRange(sel); + if (lineIdx < start.line || lineIdx > end.line) { + continue; + } + const lo = lineIdx === start.line ? start.character : 0; + const hi = lineIdx === end.line ? end.character : Infinity; + if (charIndex >= lo && charIndex < hi) { + return true; + } + } + return false; +} + +function orderRange(r: Range): Range { + const a = r.start; + const b = r.end; + if (a.line < b.line || (a.line === b.line && a.character <= b.character)) { + return r; + } + return { start: b, end: a }; +} + +/** Map a UTF-16 char index to its visual column on a line (for caret placement). */ +function charToCol(cols: Column[], charIndex: number): number { + for (const c of cols) { + if (charIndex < c.charIndex) { + return c.col; + } + // last char unit of this cell: account for multi-code-unit graphemes + if (charIndex === c.charIndex) { + return c.col; + } + } + return lineWidth(cols); +} + +function emitSpan(c: Column, lineIdx: number, selections: Range[]): string { + const classes = c.isAnchor ? "ch ch--anchor" : "ch"; + const spanAttr = + c.width === 2 + ? ` data-col-span="2"` + : c.width > 2 + ? ` data-col-span="${c.width}"` + : ""; + const selAttr = inAnySelection(lineIdx, c.charIndex, selections) + ? ' data-sel=""' + : ""; + const hatAttr = c.isAnchor + ? ` data-hat="" data-hat-color="${c.hatColor}" data-hat-shape="${c.hatShape}"` + + ` data-anchor-line="${lineIdx}" data-anchor-col="${c.col}"` + : ""; + const hat = c.isAnchor + ? `` + : ""; + // For blank tab filler emit a single space so the cell has selectable text. + const text = c.text === "" ? "" : esc(c.text); + return ( + `` + + `${text}${hat}` + ); +} + +function emitLine(line: Line, lineIdx: number, state: EditorState): string { + const cols = expandColumns(line, state.tabSize); + const selections = state.selections ?? []; + const cursors = (state.cursors ?? []).filter((c) => c.line === lineIdx); + + // Build a column -> caret-html map so carets render before the column they sit on. + const caretAtCol = new Map(); + for (const cur of cursors) { + const col = charToCol(cols, cur.character); + const caret = ``; + caretAtCol.set(col, (caretAtCol.get(col) ?? "") + caret); + } + + let html = ""; + for (const c of cols) { + if (caretAtCol.has(c.col)) { + html += caretAtCol.get(c.col); + } + html += emitSpan(c, lineIdx, selections); + } + // trailing caret (end of line) + const endCol = lineWidth(cols); + if (caretAtCol.has(endCol)) { + html += caretAtCol.get(endCol); + } + + return `
${html}
`; +} + +/** Serialize state to the inner editor markup (defs + lines). */ +export function serializeEditor(state: EditorState): string { + const lines = state.lines + .map((line, i) => emitLine(line, i, state)) + .join("\n"); + return ( + `
\n` + + `${symbolSheet()}\n` + + `
\n${lines}\n
\n` + + `
` + ); +} + +/** Serialize state to a full standalone HTML document (with the stylesheet inlined). */ +export function serializeDocument( + state: EditorState, + title = "cursorless state", +): string { + return ` + + + +${esc(title)} + + + +${serializeEditor(state)} + +`; +} diff --git a/packages/command-visualizer/src/svg-wrap.ts b/packages/command-visualizer/src/svg-wrap.ts new file mode 100644 index 0000000000..a2b75aa5f0 --- /dev/null +++ b/packages/command-visualizer/src/svg-wrap.ts @@ -0,0 +1,153 @@ +// Wrap a serialized cascade in an -embeddable animated SVG — the +// github-readme-stats delivery model: SVG + embedded CSS animation + +// for the HTML markup. No JS, no external resources, so it +// renders in SVG-as-image mode (GitHub camo, tags, markdown). +// +// Dimensions: SVG viewports are fixed-size, so we estimate from the state's +// column/row extents. Layout inside is ch-based (css.ts), so column MATH +// survives any monospace fallback; the estimate only needs enough slack that +// the widest expected monospace advance (~0.62em) never clips. + +import type { CascadeState } from "./frame-state"; +import { serializeCascade } from "./serialize-cascade"; +import { jumbotronCss, serializeJumbotron } from "./jumbotron"; +import { styleSheet } from "./css"; +import { cascadeStyleSheet, cascadeThemeBridge } from "./css-cascade"; + +const FONT_PX = 18; // .cl-code font-size (css-cascade.ts) +const LINE_HEIGHT = 1.35; // --code-line-height default +// Monospace advance estimate. SVG-as-image cannot load web fonts, and the +// viewer's fallback monospace varies: JetBrains/Menlo ~0.6em, but Chromium's +// SVG-image fallback measures ~0.75em. Size for the widest so nothing clips; +// narrow-font viewers just get extra right padding. +const CH_EM = 0.78; +const PAD_PX = 24; // body padding in the HTML document version +const CAPTION_PX = 26; // caption line + margin when meta present + +export interface SvgWrapOptions { + /** + * Flash pulse width in ms (delete red / insert green). Default 100 = the + * fidelity-pinned cursorless pulse; raise it as a VIEWING aid so the flash + * reads clearly at normal cadence. Clamped to one slot. + */ + flashPulseMs?: number; +} + +function extent(state: CascadeState): { cols: number; rows: number } { + let cols = 20; + let rows = 1; + for (const frame of state.frames) { + rows = Math.max(rows, frame.lines.length); + for (const line of frame.lines) { + const last = line.tokens[line.tokens.length - 1]; + if (last) { + cols = Math.max(cols, last.range.end); + } + } + } + return { cols, rows }; +} + +function esc(s: string): string { + return s.replace(/&/g, "&").replace(//g, ">"); +} + +/** + * Build the standalone animated SVG for a cascade state. + * + * @param inner Pre-serialized cascade markup (serializeCascade(state)) — the + * serializer emits XML-well-formed div/span/svg markup, which foreignObject + * requires. + */ +export function wrapCascadeSvg( + state: CascadeState, + inner: string = serializeCascade(state), + css?: string, + opts: SvgWrapOptions = {}, +): string { + const { cols, rows } = extent(state); + const hasCaption = state.meta != null; + const hasCommands = state.frames.some((f) => f.command); + const hasClip = state.frames.some((f) => f.clipboard != null); + const multiFrame = state.frames.length >= 2; + // Jumbotron chrome below the code box: command bar + metadata + dots. + const STRIP_PX = + (hasCommands ? 70 : 0) + (hasClip ? 56 : 0) + (multiFrame ? 32 : 0); + // The cascade box carries its own internal padding (1.2em top, 1.6em + // bottom, 1em sides — css-cascade.ts) on top of the outer PAD_PX. + const boxPadX = 2 * FONT_PX; // 1em + 1em + const boxPadY = 2.8 * FONT_PX; // 1.2em + 1.6em + // Width drivers: the CODE, and the LONGEST COMMAND PILL at full 28px — + // the full command text must always be readable, growing the canvas + // in preference to shrinking text (truncation is never allowed). + const longestCmd = Math.max( + 0, + ...state.frames.map((f) => (f.command ? f.command.length + 2 : 0)), + ); + const pillPx = longestCmd > 0 ? longestCmd * 28 * CH_EM + 2 * 28 + 24 : 0; + const width = Math.ceil( + Math.max(cols * FONT_PX * CH_EM + boxPadX, pillPx) + PAD_PX * 2 + 8, + ); + const captionCols = state.meta?.fixture?.length ?? 0; + const captionLineCh = Math.max( + 10, + Math.floor((width - PAD_PX * 2) / (12 * 0.62)), + ); + const captionLines = hasCaption + ? Math.max(1, Math.ceil(captionCols / captionLineCh)) + : 0; + const height = Math.ceil( + rows * FONT_PX * LINE_HEIGHT + + boxPadY + + PAD_PX * 2 + + (hasCaption ? CAPTION_PX + (captionLines - 1) * 16 : 0) + + STRIP_PX + + 10, + ); + + // Durations live on the frames (frame.durMs, resolved at the API layer); + // the serializers emit scaled --dur values directly — no rewrite pass. + const markup = serializeJumbotron(state, inner, { + barWidthPx: width - PAD_PX * 2, + }); + + const bg = state.theme === "dark" ? "#141414" : "#e8e8e8"; + const caption = state.meta + ? `
${esc( + [ + state.meta.spokenForm && `"${state.meta.spokenForm}"`, + state.meta.action, + state.meta.fixture, + ] + .filter(Boolean) + .join(" · "), + )}
` + : ""; + // The cascade stylesheet ships animation-play-state: paused (the GIF + // harness seeks frames via WAAPI). A delivered SVG has no harness — for + // multi-frame cascades, un-pause and loop forever (readme-embed behavior). + // Single-frame states stay static. Same-specificity override placed AFTER + // the base sheet wins by order. + const animate = + state.frames.length >= 2 + ? `\n.cl-cascade .frame, .cl-cascade .ch[data-flash], .cl-cmd-track, .cl-cmd-pill, .caret, .meta-clip, .jumbotron-dot-active { animation-play-state: running !important; animation-iteration-count: infinite !important; }` + : ""; + const style = + (css ?? + `${styleSheet()}\n${cascadeThemeBridge()}\n${cascadeStyleSheet(state.frames, opts.flashPulseMs)}\n${jumbotronCss(state, opts.flashPulseMs)}`) + + animate; + + return ` + + +
+ +${caption} +${markup} +
+ +`; +} diff --git a/packages/command-visualizer/src/symbols.ts b/packages/command-visualizer/src/symbols.ts new file mode 100644 index 0000000000..588cb914d1 --- /dev/null +++ b/packages/command-visualizer/src/symbols.ts @@ -0,0 +1,25 @@ +// Symbol sheet — SPEC §3 / §4.1. +// Emits the shared inline with 11 defs ONCE per document. +// Each path + per-shape fill-rule is verbatim from source (src/data/shapes.ts); +// fill="currentColor" so a hat is tinted by CSS `color` (D4). + +import { HAT_SHAPES, SHAPE_PATHS } from "./data/shapes"; + +export function symbolSheet(): string { + const symbols = HAT_SHAPES.map((shape) => { + const { d, fillRule } = SHAPE_PATHS[shape]; + const ruleAttr = + fillRule === "evenodd" ? ` fill-rule="evenodd" clip-rule="evenodd"` : ""; + return ( + ` ` + + `` + + `` + ); + }).join("\n"); + + return ( + ` ` + ); +} diff --git a/packages/command-visualizer/src/timeline.ts b/packages/command-visualizer/src/timeline.ts new file mode 100644 index 0000000000..ecca475dab --- /dev/null +++ b/packages/command-visualizer/src/timeline.ts @@ -0,0 +1,66 @@ +// Weighted step timeline (Trillium spec, 2026-07-07). Frame phase names: +// +// pre 500ms pre-gif bumper (initial state, no command) +// step0.initial 2000ms +// step0.during[] 1000ms pre-edit flashes, SEQUENCED: reference-class +// flashes first, deletion flashes second. (Real +// cursorless fires pre-edit flashes in PARALLEL — +// Remove awaits pendingDelete, Bring awaits +// referenced+pendingModification0 together, all +// BEFORE the edit; justAdded fires after. The +// sequencing here is a deliberate pedagogical +// refinement of that parallel reality.) +// step0.final 2000ms == step1.initial in a chain (merged frame, +// step1.during[] backward hat flow) +// ... +// stepN.final 2000ms +// reset/post 500ms seamless-loop post-gif bumper +// +// EVERY command occupies the same time scope (initial + during + final), +// whether it has zero or multiple flash states — the during phase is +// structural, with the reference sub-window always reserved. + +import type { Frame } from "./frame-state"; + +export const INITIAL_MS = 2000; +export const DURING_MS = 1000; +/** Pre-gif / post-gif breathing room (the pre frame and the reset frame). */ +export const BUMPER_MS = 500; + +export function frameDurMs(frame: Frame): number { + if (frame.durMs != null) { + return frame.durMs; + } + if (frame.pre || frame.reset) { + return BUMPER_MS; + } + return frame.role === "during" ? DURING_MS : INITIAL_MS; +} + +export interface Timeline { + totalMs: number; + /** Per-frame [startMs, endMs). */ + startMs: number[]; + endMs: number[]; + /** Per-frame [startFrac, endFrac) of the whole timeline (0..1). */ + startFrac: number[]; + endFrac: number[]; +} + +export function timelineOf(frames: readonly Frame[]): Timeline { + const startMs: number[] = []; + const endMs: number[] = []; + let t = 0; + for (const f of frames) { + startMs.push(t); + t += frameDurMs(f); + endMs.push(t); + } + return { + totalMs: t, + startMs, + endMs, + startFrac: startMs.map((s) => s / t), + endFrac: endMs.map((e) => e / t), + }; +} diff --git a/packages/command-visualizer/src/tokenize.ts b/packages/command-visualizer/src/tokenize.ts new file mode 100644 index 0000000000..7b0f59bc63 --- /dev/null +++ b/packages/command-visualizer/src/tokenize.ts @@ -0,0 +1,96 @@ +// Grapheme tokenizer + inverse detokenizer — SPEC-v2 §2.3, DECISIONS §7.4, R5. +// +// Fixtures ship RAW `documentContents`, not tokens. SPEC.md §1 requires every +// column owned by exactly one token. R5 (grapheme-level hatting) splits each +// line into ONE TOKEN PER GRAPHEME — letters AND each individual symbol / +// operator / paren (`=>`, `(`, `)`, `:`, `;`, `"`, …) — exactly like real +// cursorless (GRAPHEME_SPLIT_REGEX, tokenGraphemeSplitter.ts:73). Whitespace +// runs between graphemes become their own (non-hattable) tokens. Each token +// carries its UTF-16 line offsets, so the grapheme/column math (SPEC.md §2) +// runs unchanged. +// +// Because each non-whitespace token is now a single grapheme, fixture-extract +// can attach a hat to EVERY grapheme (one hat per token, anchored at the +// token's first — and only — grapheme), matching cursorless's dense hatting. +// +// GATE 0 (SPEC-v2 named risk): detokenize(tokenize(doc)) === doc BYTE-FOR-BYTE. +// Detokenize concatenates token text in order; since the union of grapheme + +// whitespace tokens partitions the line with no gaps or overlaps, the roundtrip +// stays byte-exact. The roundtrip test (src/verify-roundtrip-doc.ts) proves it. + +import type { Line, Token } from "./columns"; + +// Cursorless grapheme splitter (tokenGraphemeSplitter.ts:73): a base letter + +// its combining marks is ONE grapheme; each number / punctuation / symbol is +// its own grapheme. Mirrors GRAPHEME_SPLIT_REGEX in columns.ts. +const GRAPHEME_RE = /\p{L}\p{M}*|[\p{N}\p{P}\p{S}]/gu; + +/** + * Tokenize one line's text into per-grapheme tokens (plus whitespace tokens). + * `\n` is NEVER part of a line (the doc is pre-split on `\n`). + * Every UTF-16 offset of the line belongs to exactly one token. + * + * Any code unit the grapheme regex does not match (whitespace, control chars, + * lone surrogates) is emitted as its own single-code-unit token so the line is + * fully partitioned and detokenize is byte-exact. + */ +export function tokenizeLine(text: string): Token[] { + const tokens: Token[] = []; + const re = new RegExp(GRAPHEME_RE); + let m: RegExpExecArray | null; + let last = 0; + + const emitGapAsTokens = (from: number, to: number) => { + // Coalesce a run of unmatched code units into whitespace/other tokens. + // Whitespace is grouped into a single run (never hattable); any non-ws gap + // char is emitted as its own token. In practice gaps are whitespace. + let i = from; + while (i < to) { + if (/\s/.test(text[i])) { + let j = i; + while (j < to && /\s/.test(text[j])) { + j++; + } + tokens.push({ text: text.slice(i, j), range: { start: i, end: j } }); + i = j; + } else { + tokens.push({ text: text[i], range: { start: i, end: i + 1 } }); + i++; + } + } + }; + + while ((m = re.exec(text)) !== null) { + if (m.index > last) { + emitGapAsTokens(last, m.index); + } + tokens.push({ + text: m[0], + range: { start: m.index, end: m.index + m[0].length }, + }); + last = m.index + m[0].length; + if (m[0].length === 0) { + re.lastIndex++; + } // guard zero-width + } + if (last < text.length) { + emitGapAsTokens(last, text.length); + } + return tokens; +} + +/** Tokenize a whole document into Line[]. Splits on `\n`. */ +export function tokenizeDoc(doc: string): Line[] { + const rawLines = doc.split("\n"); + return rawLines.map((text) => ({ tokens: tokenizeLine(text) })); +} + +/** Inverse: concatenate a line's token text back to the original line string. */ +export function detokenizeLine(line: Line): string { + return line.tokens.map((t) => t.text).join(""); +} + +/** Inverse of tokenizeDoc: rejoin lines with `\n`. Must be byte-exact. */ +export function detokenizeDoc(lines: Line[]): string { + return lines.map(detokenizeLine).join("\n"); +} diff --git a/packages/command-visualizer/src/word-segments.ts b/packages/command-visualizer/src/word-segments.ts new file mode 100644 index 0000000000..ef90c4e191 --- /dev/null +++ b/packages/command-visualizer/src/word-segments.ts @@ -0,0 +1,73 @@ +// Word-level token segmentation over the per-grapheme render tokens. +// +// The render model is one Token per GRAPHEME (tokenize.ts R5 — column math +// needs it). But cursorless ALLOCATES per word-level token: "value" is one +// token wearing ONE hat, not five (task-mim correction, 2026-07-07 — the R5 +// "dense hatting = every grapheme" reading was wrong; upstream hats every +// TOKEN, anchored at one grapheme). +// +// Segmentation approximates cursorless's default tokenizer: maximal runs of +// word characters (letters / marks / digits / underscore) form one segment; +// every other non-whitespace grapheme is its own single-grapheme segment. + +import type { Line, Token } from "./columns"; + +const WORD_CHAR = /^[\p{L}\p{M}\p{N}_]+$/u; + +export interface WordSegment { + /** Grapheme render-tokens composing this word-level token, in order. */ + graphemes: Token[]; + /** Concatenated text of the segment. */ + text: string; + /** Line-relative start offset (== graphemes[0].range.start). */ + start: number; + lineIdx: number; +} + +/** True for tokens that can carry a hat at all (non-whitespace grapheme). */ +export function isHattableGrapheme(token: Token): boolean { + return token.text.trim().length > 0; +} + +/** + * Group a line's grapheme tokens into word-level segments. Consecutive + * word-character graphemes with ADJACENT ranges merge; everything else + * (punctuation, symbols) stands alone. + */ +export function segmentLine(line: Line, lineIdx: number): WordSegment[] { + const segments: WordSegment[] = []; + let current: WordSegment | null = null; + + for (const token of line.tokens) { + if (!isHattableGrapheme(token)) { + current = null; + continue; + } + const isWord = WORD_CHAR.test(token.text); + const adjacent = + current != null && + current.graphemes[current.graphemes.length - 1].range.end === + token.range.start; + + if (isWord && current != null && adjacent) { + current.graphemes.push(token); + current.text += token.text; + continue; + } + + const seg: WordSegment = { + graphemes: [token], + text: token.text, + start: token.range.start, + lineIdx, + }; + segments.push(seg); + current = isWord ? seg : null; + } + + return segments; +} + +export function segmentLines(lines: Line[]): WordSegment[] { + return lines.flatMap((line, i) => segmentLine(line, i)); +} diff --git a/packages/command-visualizer/tsconfig.json b/packages/command-visualizer/tsconfig.json new file mode 100644 index 0000000000..39c39d4833 --- /dev/null +++ b/packages/command-visualizer/tsconfig.json @@ -0,0 +1,7 @@ +{ + "extends": "../../tsconfig.base.json", + "compilerOptions": { + "skipLibCheck": true + }, + "include": ["src/**/*.ts", "../../resources/typings/**/*.d.ts"] +} From 5227117aa9dc6971df02ff1ee1a7b16880874c37 Mon Sep 17 00:00:00 2001 From: Trillium Smith Date: Tue, 7 Jul 2026 16:16:59 -0700 Subject: [PATCH 03/53] docs(command-visualizer): PR draft and integration status --- packages/command-visualizer/PR-DRAFT.md | 126 ++++++++++++++++++++++++ packages/command-visualizer/STATUS.md | 71 +++++++++++++ 2 files changed, 197 insertions(+) create mode 100644 packages/command-visualizer/PR-DRAFT.md create mode 100644 packages/command-visualizer/STATUS.md diff --git a/packages/command-visualizer/PR-DRAFT.md b/packages/command-visualizer/PR-DRAFT.md new file mode 100644 index 0000000000..72c47a2aea --- /dev/null +++ b/packages/command-visualizer/PR-DRAFT.md @@ -0,0 +1,126 @@ +# PR draft — `@cursorless/command-visualizer`: animated SVG cascades from recorded fixtures + +> Status: LOCAL DRAFT (2026-07-07). Not filed. Target: cursorless-dev/cursorless. +> Branch in fork: `command-visualizer` (scaffold commit `2b4d027`). + +--- + +## What this adds + +A new package, `@cursorless/command-visualizer`, that turns recorded test +fixtures (`data/fixtures/recorded/**/*.yml`) into **animated SVG +visualizations** of cursorless commands — before/during/after cascades with +real hat allocation, flash sequencing, selections, and a command "jumbotron" +— embeddable anywhere a plain `` works (GitHub READMEs via camo, docs +pages, tutorials). + +**Live demo of the exact code in this PR:** +https://cursorless-css-state.vercel.app/ (gallery) — e.g. the full +tutorial-1 sequence as one looping image: + +``` +/api/cascade?fixture=tutorial/tutorial-1-basics +``` + +The renderer is a pure function: fixture YAML in → self-contained SVG string +out. Zero runtime JavaScript in the output, no DOM or browser dependency to +render, and every animation rides one CSS `--dur` timeline so outputs are +deterministic and testable by seeking. + +## Why cursorless might want this + +- **Docs and tutorials that show, not tell.** Every recorded fixture becomes + a looping visual: spoken command entering, flashes firing, the edit + landing, hats reallocating. The tutorial sequences render as one + continuous animation. +- **The fixtures are already the perfect substrate.** This consumes recorded + test YAMLs verbatim — the corpus you already maintain becomes a + documentation asset for free. +- **Faithful by construction, not by imitation:** + - Hat allocation is _your_ algorithm (`chooseTokenHat` + + `getHatRankingContext`, vendored verbatim; see companion proposal below), + one hat per token, proven byte-identical to a bundled engine build. + - Flash classes follow the action source exactly (matrix extracted from + `packages/cursorless-engine/src/actions/*`): pre-edit flashes + (`pendingDelete`, `referenced`, `pendingModification0/1`) precede the + edit, `justAdded` follows it. The 100ms + `pendingEditDecorationTime` pulse is pinned N-invariantly by a timing + oracle. Timing is deliberately expanded for readability (documented + divergence: pre-edit flashes render sequenced reference→delete rather + than parallel). + +## The model + +``` +pre (bumper) → [ step.initial → step.during → step.final ]* → post (reset) +``` + +- **Chains are contract-checked:** `finalState.i` must equal + `initialState.{i+1}` (400 otherwise), and the boundary renders as ONE + merged frame already wearing the next step's hats — one animated change, + exactly as in the editor. +- **The during phase is the execution beat:** command pill activates, its + step dot gains the issued ring, and flashes initiate — all in the same + instant. Flash-less commands (pure selections) show their final state in + this beat, matching the editor's instantaneous selection. +- **Durations are parameters** (`initial/during/bumper` ms, float `scale`), + defaults `[2000, 1000, 500]`. +- Fixtures with no recorded `ide.flashes` (e.g. the tutorial corpus) get + flashes **derived from the edit diff**; recorded flashes are used verbatim + when present. + +## Test story (ports with the package) + +- 79 API-contract checks (params, typed errors, XML validity for + `foreignObject`, real `` SVG-as-image rendering in Chromium) +- 54 timeline e2e checks — WAAPI seek to exact beats: flash windows and + doomed-token ranges, pill/dot/flash simultaneity, backward hat flow + (merged-frame hat signature must equal a standalone render of the next + step's initial state), command centering (±2px), never-truncate text + fitting, no-seek wall-clock animation liveness +- 24 SVG layout checks (content fits the declared viewport across the + corpus, chains, themes) +- Flash-timing oracle: insert = 100ms N-invariant; delete windows structural +- Plus the renderer's own column-model / roundtrip / pixel-oracle suites + +## Companion proposal (separable) + +`@cursorless/hat-allocator`: export the allocation subgraph +(`allocateHats`'s unexported loop + `chooseTokenHat` + +`getHatRankingContext` + a static-config grapheme splitter) as a standalone +entry point with a tokens-in interface. Three downstream re-implementations +currently vendor or re-bundle this identical code (Talon prose overlay, an +iOS port's oracle, this renderer); one exported entry point serves all. The +extraction shipped standalone as `allocate-hats` with a 200-case +byte-equivalence proof against a bundled engine build — the PR would move it +inward and dissolve the dependency. + +## Open questions for maintainers + +1. **Package name/home**: `packages/command-visualizer` (naming rationale: + describes what the viewer sees — a command executing — rather than the + implementation; considered `cascade-renderer`, `fixture-visualizer`, + `test-case-visualizer`) vs living beside + `test-case-component` (which it complements: static React component vs + embeddable animated SVG). +2. **Fixture ingestion**: read `data/fixtures/recorded/**` directly + in-monorepo (the standalone deploy vendors YAMLs for serverless). +3. **Hosting**: should cursorless.org serve the endpoint (docs embeds), or + is the library alone in scope? +4. **Timing divergence**: is the expanded pedagogical timing acceptable as + the default, given the faithful 100ms mode is one parameter away + (`scale`/`flash`)? + +## Checklist + +- [ ] Re-vendor allocation against `packages/lib-engine` @ upstream HEAD — + the algorithm evolved since the 42452eb pin (`forcedTokenHat` param, + `avoidFirstLetter` metric, `lib-common` rename); assignments change, + so a fresh equivalence baseline is required (task-1e8 in the + standalone repo) +- [ ] `pnpm compile` green in-monorepo (scaffold imports verbatim; two + integration seams documented in `STATUS.md`) +- [ ] Port the gate suites into the monorepo test layout +- [ ] Companion hat-allocator PR (or fold into this one per maintainer + preference) +- [ ] Docs page embedding a live cascade diff --git a/packages/command-visualizer/STATUS.md b/packages/command-visualizer/STATUS.md new file mode 100644 index 0000000000..8cfd09285c --- /dev/null +++ b/packages/command-visualizer/STATUS.md @@ -0,0 +1,71 @@ +# Integration status + +This package renders cursorless command fixtures as animated SVGs. It has been +reworked to deduplicate against cursorless's public API and to compile +in-monorepo. Everything below touches ONLY `packages/command-visualizer/`. + +## Done + +1. **allocate-hats internalized** (step 1). The unpublished `allocate-hats@0.1.0` + npm dependency (it lived only at `~/code/allocate-hats`, never on npm) is + gone. Its `src/` tree is vendored verbatim under + `src/vendor/allocate-hats/` (cursorless SHA `42452eb`); `hat-allocator.ts` + imports from `./vendor/allocate-hats/index`. The unused QuickJS entry points + (`bundle.ts`, `proseCompat.ts`) were dropped. The vendored tree + self-typechecks clean in isolation. See + `src/vendor/allocate-hats/VENDOR.md`. +2. **YAML via js-yaml** (step 2). The hand-rolled fixture-YAML subset parser is + replaced by `js-yaml`'s `load()` — the same library and entry point + `@cursorless/lib-node-common`'s `loadFixture.ts` uses. `yaml-scalars.ts` was + deleted; `parseFixtureYaml` and the `YamlValue` type surface are preserved. +3. **Workspace deps declared** (step 3). `package.json` now depends on + `@cursorless/lib-common` and `@cursorless/lib-node-common` (`workspace:*`), + plus `js-yaml ^5.2.1` and `@types/js-yaml ^4.0.9` (matching the versions + lib-common / lib-node-common declare). +4. **Dedup review** (step 4). All three public-import candidates were evaluated + and deliberately KEPT with provenance notes (switching each is invasive, + regressive, or scope-ballooning — never their code needed changing): + - `data/decorations.ts` `FlashStyle` — string union whose values match + lib-common's `FlashStyle` enum, but it composes with `HighlightStyle` into + `DecorationStyle` keys; enum switch churns literals for no gain. + - `fixture-root.ts` — keeps its dual-layout probe + `$CURSORLESS_REPO` + override; lib-node-common's `getFixturesPath` hardcodes one layout. + - `fixture-extract.ts` `parseMarks`/`buildLines` — lib-common's + `serializedMarksToTokenHats` needs a live `TextEditor` and returns engine + `TokenHat[]`; our render model reads plain YAML with no editor. +5. **Compile config fixed** (step 5). Dropped the non-idiomatic + `tsc --build`/composite setup (no sibling package uses it); `compile:tsc` is + now plain `tsc`, matching the repo's typecheck convention (resolution via + `tsconfig.base.json` `paths`). Fixed a real pre-existing type error: + `pipeline.ts` used `GeneralizedRange` and `Pos` without importing them. + +## Remaining blockers (NOT introduced by this work) + +Running `pnpm compile` in the current checkout surfaces errors that are all +environmental (stale install) or pre-existing and out of scope for the dedup: + +- **Stale node_modules / offline.** The installed toolchain is TypeScript 5.4.3 + and js-yaml 4.3.0, but `package.json`/lockfile pin TypeScript `^6.0.3` and + js-yaml `^5.2.1`. TS 5.4.3 rejects the shared `tsconfig.base.json` `target: + es2023` (`TS6046`), which cascades into a spurious `Set` iteration error in + the vendored `rank.ts`. `@types/js-yaml` is also not installed, so + `fixture-yaml.ts` reports `TS7016` (missing declaration for `js-yaml`). A + `pnpm install` (needs network — offline install fails fetching + `oxlint-tsgolint`, TS 6.0.3, js-yaml 5.2.1, `@types/js-yaml`) resolves all of + these. Proof: typechecking this package with a valid target (es2022) + node + types + a `declare module "js-yaml"` shim leaves ZERO errors in our code. +- **`./fixtures-vendored` missing** (`api-core.ts:47`, `TS2307`). `api-core.ts` + imports `FIXTURE_IDS` / `SEQUENCES` / `VENDORED_FIXTURES` from a + `src/fixtures-vendored` module that was never committed to this repo (it was a + serverless-deployment artifact of the standalone repo — the "fixture + ingestion" item from the original scaffold). This file is UNREACHABLE from the + esbuild bundle entry (`src/index.ts` does not export `api-core.ts`), so it + does not block `compile:esbuild`; it only trips the whole-tree `tsc` + typecheck. Generating it is a separate task outside the dedup/compile scope + and was intentionally NOT invented here. + +## Verify + +- Vendored tree, isolated: clean typecheck (esnext, self-contained). +- Whole package, valid target + js-yaml types available: only the + out-of-scope `./fixtures-vendored` error remains. From e62bb67bf88486fa01497dfd1bec4ea463978381 Mon Sep 17 00:00:00 2001 From: Trillium Smith Date: Tue, 7 Jul 2026 16:43:46 -0700 Subject: [PATCH 04/53] refactor(command-visualizer): import DefaultMap/CompositeKeyMap from @cursorless/lib-common The allocate-hats vendored tree carried byte-identical copies of cursorless's DefaultMap and CompositeKeyMap utilities. Delete both clones and re-export the originals from @cursorless/lib-common through the common/ barrel, so every consumer keeps its unchanged `from "../common"` import. lib-common's CompositeKeyMap backs its store with a Map instead of a Record but exposes the identical set/has/get/delete/clear surface the allocator uses. @cursorless/lib-common is already a workspace dependency; no manifest change. --- .../allocate-hats/common/CompositeKeyMap.ts | 48 ------------------- .../vendor/allocate-hats/common/DefaultMap.ts | 33 ------------- .../src/vendor/allocate-hats/common/index.ts | 7 ++- 3 files changed, 5 insertions(+), 83 deletions(-) delete mode 100644 packages/command-visualizer/src/vendor/allocate-hats/common/CompositeKeyMap.ts delete mode 100644 packages/command-visualizer/src/vendor/allocate-hats/common/DefaultMap.ts diff --git a/packages/command-visualizer/src/vendor/allocate-hats/common/CompositeKeyMap.ts b/packages/command-visualizer/src/vendor/allocate-hats/common/CompositeKeyMap.ts deleted file mode 100644 index fb7e82472a..0000000000 --- a/packages/command-visualizer/src/vendor/allocate-hats/common/CompositeKeyMap.ts +++ /dev/null @@ -1,48 +0,0 @@ -/** - * Vendored verbatim from cursorless packages/common/src/util/CompositeKeyMap.ts - * at SHA 42452eba521bb9cccbb3e04a2cd9e9afcf6cbffe. No edits below this header. - */ - -/** - * A map that can use a composite key, i.e. a key that is an array or object. - * The key is hashed by running {@link hashFunction}, which is expected to - * output a list whose entries can be converted to string. - * - * Based on https://stackoverflow.com/a/54523103 - */ -export class CompositeKeyMap { - private map: Record = {}; - - /** - * - * @param hashFunction A function that maps from a key to a list whose entries can be converted to string - */ - constructor(private hashFunction: (key: K) => unknown[]) {} - - private hash(key: K): string { - return this.hashFunction(key).join("\u0000"); - } - - set(key: K, item: V): this { - this.map[this.hash(key)] = item; - return this; - } - - has(key: K): boolean { - return this.hash(key) in this.map; - } - - get(key: K): V | undefined { - return this.map[this.hash(key)]; - } - - delete(key: K): this { - delete this.map[this.hash(key)]; - return this; - } - - clear(): this { - this.map = {}; - return this; - } -} diff --git a/packages/command-visualizer/src/vendor/allocate-hats/common/DefaultMap.ts b/packages/command-visualizer/src/vendor/allocate-hats/common/DefaultMap.ts deleted file mode 100644 index 9e1b215653..0000000000 --- a/packages/command-visualizer/src/vendor/allocate-hats/common/DefaultMap.ts +++ /dev/null @@ -1,33 +0,0 @@ -/** - * Vendored verbatim from cursorless packages/common/src/util/DefaultMap.ts - * at SHA 42452eba521bb9cccbb3e04a2cd9e9afcf6cbffe. - * One edit: `export default class` -> `export class` (this package uses - * named exports throughout). - */ - -/** - * A map that returns a default value when a key is not found. - * - * Based on https://aaronmoat.com/implementing-pythons-defaultdict-in-javascript/ - */ -export class DefaultMap extends Map { - /** - * @param getDefaultValue A function that returns the default value for a given key - */ - constructor(private getDefaultValue: (key: K) => V) { - super(); - } - - get(key: K): V { - const currentValue = super.get(key); - - if (currentValue != null) { - return currentValue; - } - - const value = this.getDefaultValue(key); - this.set(key, value); - - return value; - } -} diff --git a/packages/command-visualizer/src/vendor/allocate-hats/common/index.ts b/packages/command-visualizer/src/vendor/allocate-hats/common/index.ts index 30bf1a433e..54774783b4 100644 --- a/packages/command-visualizer/src/vendor/allocate-hats/common/index.ts +++ b/packages/command-visualizer/src/vendor/allocate-hats/common/index.ts @@ -1,3 +1,6 @@ export * from "./types"; -export { CompositeKeyMap } from "./CompositeKeyMap"; -export { DefaultMap } from "./DefaultMap"; +// DefaultMap / CompositeKeyMap are re-exported straight from +// @cursorless/lib-common (byte-identical to the copies this tree used to +// vendor). Importing them from source removes two clones; every consumer in +// this tree keeps its unchanged `from "../common"` import. +export { CompositeKeyMap, DefaultMap } from "@cursorless/lib-common"; From 7144364b1630d333da028ff0a9d0bc945b3096e4 Mon Sep 17 00:00:00 2001 From: Trillium Smith Date: Tue, 7 Jul 2026 16:45:14 -0700 Subject: [PATCH 05/53] feat(lib-engine): export hat-allocation and grapheme-splitter primitives Surface the real hat-allocation building blocks and the token grapheme splitter from the lib-engine barrel so downstream consumers can import them instead of vendoring copies. @cursorless/command-visualizer currently carries clones of maxByFirstDiffering, getTokenComparator and the grapheme-split regex pinned to an old cursorless SHA; exporting the source lets it drop those. Additive only: the allocateHats/ barrel now re-exports chooseTokenHat, getHatRankingContext, getRankedTokens, getTokenComparator, maxByFirstDiffering, the HatMetrics functions, and the HatCandidate/RankingContext/RankedToken/ HatMetric types alongside the existing allocateHats export; the top-level index adds two barrel re-exports (util/allocateHats and tokenGraphemeSplitter, covering GRAPHEME_SPLIT_REGEX, TokenGraphemeSplitter, Grapheme, UNKNOWN). No behavior changes. --- packages/lib-engine/src/index.ts | 2 ++ .../lib-engine/src/util/allocateHats/index.ts | 21 +++++++++++++++++++ 2 files changed, 23 insertions(+) diff --git a/packages/lib-engine/src/index.ts b/packages/lib-engine/src/index.ts index b4bcc4cdc1..9823ff8f49 100644 --- a/packages/lib-engine/src/index.ts +++ b/packages/lib-engine/src/index.ts @@ -14,6 +14,8 @@ export * from "./processTargets/modifiers/scopeHandlers/ScopeHandlerCache"; export * from "./spokenForms/defaultSpokenFormMap"; export * from "./testUtil/extractTargetKeys"; export * from "./testUtil/plainObjectToTarget"; +export * from "./tokenGraphemeSplitter"; +export * from "./util/allocateHats"; export * from "./util/getPartialTargetDescriptors"; export * from "./util/getPrimitiveTargets"; export * from "./util/grammarHelpers"; diff --git a/packages/lib-engine/src/util/allocateHats/index.ts b/packages/lib-engine/src/util/allocateHats/index.ts index 9fc67dc190..11d639494f 100644 --- a/packages/lib-engine/src/util/allocateHats/index.ts +++ b/packages/lib-engine/src/util/allocateHats/index.ts @@ -1 +1,22 @@ export { allocateHats } from "./allocateHats"; +export type { HatCandidate } from "./allocateHats"; + +// Individual hat-allocation primitives, exported so downstream consumers (e.g. +// @cursorless/command-visualizer) can reuse the real ranking/selection +// building blocks instead of vendoring copies of them. +export { chooseTokenHat } from "./chooseTokenHat"; +export { getHatRankingContext } from "./getHatRankingContext"; +export type { RankingContext } from "./getHatRankingContext"; +export { getRankedTokens } from "./getRankedTokens"; +export type { RankedToken } from "./getRankedTokens"; +export { getTokenComparator } from "./getTokenComparator"; +export { maxByFirstDiffering, maxByAllowingTies } from "./maxByFirstDiffering"; +export type { HatMetric } from "./HatMetrics"; +export { + avoidFirstLetter, + hatOldTokenRank, + isOldTokenHat, + minimumTokenRankContainingGrapheme, + negativePenalty, + penaltyEquivalenceClass, +} from "./HatMetrics"; From ae711125c4781a76601dcc8c0163c61bb4021fc4 Mon Sep 17 00:00:00 2001 From: Trillium Smith Date: Tue, 7 Jul 2026 16:51:33 -0700 Subject: [PATCH 06/53] refactor(command-visualizer): import grapheme regex + maxByFirstDiffering from lib-engine MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Drop the clones that ARE safe to import from cursorless source now that lib-engine exports them: - GRAPHEME_SPLIT_REGEX: was defined three times (columns.ts, tokenize.ts, vendor/allocate-hats/splitter.ts). All now import the single source-of-truth from @cursorless/lib-engine, each wrapping it in a fresh RegExp so the shared /gu instance's lastIndex cannot leak across calls. - maxByFirstDiffering: byte-identical to the pin and fully generic, so the vendored copy is deleted and vendor/chooseTokenHat.ts imports it from @cursorless/lib-engine. Kept PINNED at SHA 42452eb (upstream diverged — importing would change hat placement or fail to typecheck against the standalone's simplified types): chooseTokenHat, HatMetrics, getHatRankingContext (forcedTokenHat / avoidFirstLetter / isFirstLetter and the IDE-backed splitter are all post-pin), getTokenComparator (byte-identical but typed against lib-common's full Token, not assignable from the simplified standalone Token). Each kept file header now states the exact reason; VENDOR.md records the full import-vs-pin split. Adds @cursorless/lib-engine as a workspace dependency. --- packages/command-visualizer/package.json | 1 + packages/command-visualizer/src/columns.ts | 8 +- packages/command-visualizer/src/tokenize.ts | 12 +-- .../src/vendor/allocate-hats/VENDOR.md | 55 +++++++++++--- .../src/vendor/allocate-hats/splitter.ts | 25 ++++--- .../vendor/allocate-hats/vendor/HatMetrics.ts | 19 ++++- .../allocate-hats/vendor/chooseTokenHat.ts | 22 +++++- .../vendor/getHatRankingContext.ts | 14 +++- .../vendor/getTokenComparator.ts | 16 +++- .../vendor/maxByFirstDiffering.ts | 75 ------------------- 10 files changed, 127 insertions(+), 120 deletions(-) delete mode 100644 packages/command-visualizer/src/vendor/allocate-hats/vendor/maxByFirstDiffering.ts diff --git a/packages/command-visualizer/package.json b/packages/command-visualizer/package.json index b31822f858..bbc466c321 100644 --- a/packages/command-visualizer/package.json +++ b/packages/command-visualizer/package.json @@ -21,6 +21,7 @@ "license": "MIT", "dependencies": { "@cursorless/lib-common": "workspace:*", + "@cursorless/lib-engine": "workspace:*", "@cursorless/lib-node-common": "workspace:*", "js-yaml": "^5.2.1" }, diff --git a/packages/command-visualizer/src/columns.ts b/packages/command-visualizer/src/columns.ts index 356a3dc96a..a60e3ecbe9 100644 --- a/packages/command-visualizer/src/columns.ts +++ b/packages/command-visualizer/src/columns.ts @@ -6,13 +6,13 @@ // - Tab → next tabSize stop (SPEC §2.2). // - East-Asian Wide/Fullwidth glyph = 2 columns (SPEC §2.3). +import { GRAPHEME_SPLIT_REGEX } from "@cursorless/lib-engine"; import type { HatColor } from "./data/colors"; import type { HatShape } from "./data/shapes"; -// Cursorless's grapheme splitter regex -// (tokenGraphemeSplitter.ts:73). A base letter + its combining marks is ONE -// grapheme; numbers/punct/symbols are each their own grapheme. -export const GRAPHEME_SPLIT_REGEX = /\p{L}\p{M}*|[\p{N}\p{P}\p{S}]/gu; +// Cursorless's grapheme splitter regex, imported from @cursorless/lib-engine +// (no clone): a base letter + its combining marks is ONE grapheme; +// numbers/punct/symbols are each their own grapheme. export interface InputHat { color: HatColor; diff --git a/packages/command-visualizer/src/tokenize.ts b/packages/command-visualizer/src/tokenize.ts index 7b0f59bc63..b7dd875a54 100644 --- a/packages/command-visualizer/src/tokenize.ts +++ b/packages/command-visualizer/src/tokenize.ts @@ -18,12 +18,12 @@ // whitespace tokens partitions the line with no gaps or overlaps, the roundtrip // stays byte-exact. The roundtrip test (src/verify-roundtrip-doc.ts) proves it. +import { GRAPHEME_SPLIT_REGEX } from "@cursorless/lib-engine"; import type { Line, Token } from "./columns"; -// Cursorless grapheme splitter (tokenGraphemeSplitter.ts:73): a base letter + -// its combining marks is ONE grapheme; each number / punctuation / symbol is -// its own grapheme. Mirrors GRAPHEME_SPLIT_REGEX in columns.ts. -const GRAPHEME_RE = /\p{L}\p{M}*|[\p{N}\p{P}\p{S}]/gu; +// Cursorless grapheme splitter: a base letter + its combining marks is ONE +// grapheme; each number / punctuation / symbol is its own grapheme. The regex +// is imported from @cursorless/lib-engine (GRAPHEME_SPLIT_REGEX) — no clone. /** * Tokenize one line's text into per-grapheme tokens (plus whitespace tokens). @@ -36,7 +36,9 @@ const GRAPHEME_RE = /\p{L}\p{M}*|[\p{N}\p{P}\p{S}]/gu; */ export function tokenizeLine(text: string): Token[] { const tokens: Token[] = []; - const re = new RegExp(GRAPHEME_RE); + // Fresh RegExp per call: GRAPHEME_SPLIT_REGEX is a shared /gu instance whose + // lastIndex must not leak across tokenizeLine calls. + const re = new RegExp(GRAPHEME_SPLIT_REGEX); let m: RegExpExecArray | null; let last = 0; diff --git a/packages/command-visualizer/src/vendor/allocate-hats/VENDOR.md b/packages/command-visualizer/src/vendor/allocate-hats/VENDOR.md index 549369d591..fe21b91edf 100644 --- a/packages/command-visualizer/src/vendor/allocate-hats/VENDOR.md +++ b/packages/command-visualizer/src/vendor/allocate-hats/VENDOR.md @@ -11,19 +11,42 @@ Internalized copy of the `allocate-hats` package's `src/` tree. package; it lived only at `~/code/allocate-hats`). Vendoring lets `@cursorless/command-visualizer` compile in-monorepo with zero external deps. -## What was copied vs. dropped +## What is imported from source vs. kept pinned vs. dropped -Copied verbatim (the allocation core our package actually uses): +**Imported from `@cursorless/lib-common` / `@cursorless/lib-engine` (no clone):** -- `index.ts` — public entry (`allocateHats`, `StandaloneGraphemeSplitter`, - `HatStyleMap`, style-map builders). -- `rank.ts`, `splitter.ts` -- `common/` — `types.ts`, `index.ts`, `CompositeKeyMap.ts`, `DefaultMap.ts` -- `vendor/` — `chooseTokenHat.ts`, `getHatRankingContext.ts`, - `getTokenComparator.ts`, `HatMetrics.ts`, `maxByFirstDiffering.ts` +- `CompositeKeyMap`, `DefaultMap` — re-exported through `common/index.ts` from + `@cursorless/lib-common` (byte-identical to the copies that used to live in + `common/`). The local files were deleted. +- `GRAPHEME_SPLIT_REGEX` — imported from `@cursorless/lib-engine` in + `splitter.ts` (and, in the package proper, in `tokenize.ts` / `columns.ts`). +- `maxByFirstDiffering` — imported from `@cursorless/lib-engine` in + `vendor/chooseTokenHat.ts` (byte-identical to the pin; generic, no cursorless + types in its signature). The local `vendor/maxByFirstDiffering.ts` was deleted. -Dropped during vendoring (unused by this package — grep-confirmed no importers -in `src/`, and nothing inside the vendored tree imports them): +**Kept PINNED at SHA `42452eb` (must NOT be swapped for the current lib-engine +versions — upstream has diverged, see per-file headers for the exact reason):** + +- `vendor/chooseTokenHat.ts` — current upstream added a `forcedTokenHat` param + (#2602) and an `avoidFirstLetter` step (#1723). +- `vendor/HatMetrics.ts` — current upstream added `avoidFirstLetter`, needing + `HatCandidate.isFirstLetter` (a WordTokenizer/IDE-derived field this offline + renderer cannot compute). +- `vendor/getHatRankingContext.ts` — current upstream types against the concrete + IDE-backed `TokenGraphemeSplitter` and full engine `Token`; this copy accepts + the structural `GraphemeSplitter` + simplified Token. +- `vendor/getTokenComparator.ts` — byte-identical to source, but the engine + version's signature is typed against lib-common's full `Token`, which the + simplified standalone Token is not assignable to. +- `common/types.ts` — custom minimal `Position`/`Range`/`Token`/`HatCandidate`/ + `RankedToken`/`Grapheme`/`GraphemeSplitter` (no public lib-common equivalents + for the last four; `Position`/`Range`/`Token` deliberately simplified). +- `index.ts` (the tokens-in `allocateHats` wrapper), `rank.ts`, + `splitter.ts` (the `StandaloneGraphemeSplitter` class + inline `deburr`) — + genuinely-new glue with no cursorless equivalent (the engine paths require a + live IDE / TextEditor). + +Dropped during the original vendoring (unused by this package): - `bundle.ts` — QuickJS IIFE entry (exposes API on `globalThis`). - `proseCompat.ts` — prose-overlay legacy JSON-in/JSON-out compatibility API. @@ -35,5 +58,13 @@ and the `HatStyleMap` type from `./vendor/allocate-hats/index`. ## Updating -Re-copy `~/code/allocate-hats/src/`, then re-drop `bundle.ts` and -`proseCompat.ts`, and bump the SHA above. +The pinned files must stay at SHA `42452eb` to preserve the renderer's +byte-for-byte fidelity to the recorded prose-overlay bundle. Do NOT +mechanically re-sync them to current cursorless — that would pull in +`forcedTokenHat` / `avoidFirstLetter` and change hat placement. If you +deliberately want the new algorithm, that is a behavior change to design and +verify against the fixture oracle, not a copy-paste refresh. + +The imported-from-source pieces (`CompositeKeyMap`, `DefaultMap`, +`GRAPHEME_SPLIT_REGEX`, `maxByFirstDiffering`) track cursorless automatically +via the workspace deps — nothing to re-copy. diff --git a/packages/command-visualizer/src/vendor/allocate-hats/splitter.ts b/packages/command-visualizer/src/vendor/allocate-hats/splitter.ts index fc62f972ea..903b6bb60b 100644 --- a/packages/command-visualizer/src/vendor/allocate-hats/splitter.ts +++ b/packages/command-visualizer/src/vendor/allocate-hats/splitter.ts @@ -1,12 +1,17 @@ /** - * Standalone grapheme splitter — lifted from proseStandalone.ts in the - * cursorless fork (SHA 42452eba521bb9cccbb3e04a2cd9e9afcf6cbffe), which in - * turn mirrors the canonical splitter at - * packages/cursorless-engine/src/tokenGraphemeSplitter/tokenGraphemeSplitter.ts:74 - * with a STATIC config (no ide().configuration): no lettersToPreserve / - * symbolsToPreserve user overrides. + * Standalone grapheme splitter — mirrors the canonical + * @cursorless/lib-engine TokenGraphemeSplitter, but with a STATIC config: no + * ide().configuration, so no lettersToPreserve / symbolsToPreserve user + * overrides. The engine's class requires an IDE in its constructor (for the + * live tokenHatSplittingMode setting), which this offline renderer has no way + * to supply — hence this minimal reimplementation of getTokenGraphemes / + * normalizeGrapheme rather than importing the class. + * + * The split regex itself is NOT cloned: GRAPHEME_SPLIT_REGEX is imported from + * @cursorless/lib-engine (source of truth). */ +import { GRAPHEME_SPLIT_REGEX } from "@cursorless/lib-engine"; import type { Grapheme, GraphemeSplitter } from "./common/types"; /** @@ -66,13 +71,11 @@ const KNOWN_GRAPHEME_MATCHER = new RegExp( "u", ); -// Letters + combining marks OR any single Unicode Number / Punctuation / Symbol. -const GRAPHEME_SPLIT_SOURCE = String.raw`\p{L}\p{M}*|[\p{N}\p{P}\p{S}]`; -const GRAPHEME_SPLIT_FLAGS = "gu"; - export class StandaloneGraphemeSplitter implements GraphemeSplitter { getTokenGraphemes(tokenText: string): Grapheme[] { - const re = new RegExp(GRAPHEME_SPLIT_SOURCE, GRAPHEME_SPLIT_FLAGS); + // Fresh RegExp per call: GRAPHEME_SPLIT_REGEX is a shared /gu instance whose + // lastIndex would leak across calls if reused directly. + const re = new RegExp(GRAPHEME_SPLIT_REGEX); const results: Grapheme[] = []; let match: RegExpExecArray | null; while ((match = re.exec(tokenText)) != null) { diff --git a/packages/command-visualizer/src/vendor/allocate-hats/vendor/HatMetrics.ts b/packages/command-visualizer/src/vendor/allocate-hats/vendor/HatMetrics.ts index 0ec2dffd88..6086b09bbc 100644 --- a/packages/command-visualizer/src/vendor/allocate-hats/vendor/HatMetrics.ts +++ b/packages/command-visualizer/src/vendor/allocate-hats/vendor/HatMetrics.ts @@ -1,7 +1,20 @@ /** - * Vendored from cursorless packages/cursorless-engine/src/util/allocateHats/HatMetrics.ts - * at SHA 42452eba521bb9cccbb3e04a2cd9e9afcf6cbffe. - * Edits are IMPORT REWRITES ONLY (applied by scripts/vendor.sh): + * Vendored from cursorless HatMetrics.ts, PINNED at SHA + * 42452eba521bb9cccbb3e04a2cd9e9afcf6cbffe. + * + * NOT importable from @cursorless/lib-engine: current upstream HatMetrics adds + * `avoidFirstLetter` (introduced with #1723) which reads + * `HatCandidate.isFirstLetter` — a field the pinned HatCandidate here does not + * carry and which requires a WordTokenizer(ide, languageId) the offline + * renderer cannot construct. chooseTokenHat (also pinned) does not call + * avoidFirstLetter, so this pinned metric set is the correct, self-consistent + * one. Adopting the current version would change hat placement. + * + * lodash memoize/min are inlined below (not imported) to keep the bundle free + * of lodash, whose CommonJS module blows QuickJS's call stack in the + * downstream standalone build. + * + * Edits are IMPORT REWRITES ONLY: * - "@cursorless/common" -> "../common" barrel * - HatCandidate: "./allocateHats" -> "../common/types" */ diff --git a/packages/command-visualizer/src/vendor/allocate-hats/vendor/chooseTokenHat.ts b/packages/command-visualizer/src/vendor/allocate-hats/vendor/chooseTokenHat.ts index b14af67b81..c094f56d18 100644 --- a/packages/command-visualizer/src/vendor/allocate-hats/vendor/chooseTokenHat.ts +++ b/packages/command-visualizer/src/vendor/allocate-hats/vendor/chooseTokenHat.ts @@ -1,9 +1,23 @@ /** - * Vendored from cursorless packages/cursorless-engine/src/util/allocateHats/chooseTokenHat.ts - * at SHA 42452eba521bb9cccbb3e04a2cd9e9afcf6cbffe. - * Edits are IMPORT REWRITES ONLY (applied by scripts/vendor.sh): + * Vendored from cursorless chooseTokenHat.ts, PINNED at SHA + * 42452eba521bb9cccbb3e04a2cd9e9afcf6cbffe. + * + * NOT importable from @cursorless/lib-engine: current upstream chooseTokenHat + * has DIVERGED from this pin (two feature commits — #2602 "Make hat forcing + * more aggressive" added a `forcedTokenHat` parameter, #1723 "avoid allocating + * hats to the first letter of a token" added an `avoidFirstLetter` metric that + * needs `HatCandidate.isFirstLetter`, computed from a WordTokenizer(ide, + * languageId) this offline renderer cannot construct). Adopting the current + * version would change which grapheme gets hatted and break the renderer's + * byte-for-byte fidelity to the recorded prose-overlay bundle. This copy stays + * pinned on purpose. + * + * maxByFirstDiffering IS imported from @cursorless/lib-engine (it is + * byte-identical to the pin and generic, so no clone is needed). + * Remaining edits are IMPORT REWRITES ONLY: * - "@cursorless/common" -> "../common" barrel * - HatCandidate: "./allocateHats" -> "../common/types" + * - maxByFirstDiffering: "./maxByFirstDiffering" -> "@cursorless/lib-engine" */ import { HatStability, TokenHat } from "../common"; @@ -16,7 +30,7 @@ import { negativePenalty, penaltyEquivalenceClass, } from "./HatMetrics"; -import { maxByFirstDiffering } from "./maxByFirstDiffering"; +import { maxByFirstDiffering } from "@cursorless/lib-engine"; /** * Selects a hat for a given token from amongst {@link candidates}, trading off diff --git a/packages/command-visualizer/src/vendor/allocate-hats/vendor/getHatRankingContext.ts b/packages/command-visualizer/src/vendor/allocate-hats/vendor/getHatRankingContext.ts index 424310fe1d..892d9edb94 100644 --- a/packages/command-visualizer/src/vendor/allocate-hats/vendor/getHatRankingContext.ts +++ b/packages/command-visualizer/src/vendor/allocate-hats/vendor/getHatRankingContext.ts @@ -1,7 +1,15 @@ /** - * Vendored from cursorless packages/cursorless-engine/src/util/allocateHats/getHatRankingContext.ts - * at SHA 42452eba521bb9cccbb3e04a2cd9e9afcf6cbffe. - * Edits are IMPORT REWRITES ONLY (applied by scripts/vendor.sh): + * Vendored from cursorless getHatRankingContext.ts, PINNED at SHA + * 42452eba521bb9cccbb3e04a2cd9e9afcf6cbffe. + * + * NOT importable from @cursorless/lib-engine: the current version types its + * third argument as the concrete `TokenGraphemeSplitter` (IDE-backed) and its + * tokens as the engine's full `RankedToken`/`Token`. This copy instead accepts + * the structural `GraphemeSplitter` interface and the simplified Token from + * ../common/types, which is what the offline standalone allocator constructs. + * Its body is otherwise identical to the pin. + * + * Edits are IMPORT REWRITES ONLY: * - "@cursorless/common" -> "../common" barrel * - TokenGraphemeSplitter (concrete class) -> GraphemeSplitter (structural * interface in ../common/types with the same getTokenGraphemes surface) diff --git a/packages/command-visualizer/src/vendor/allocate-hats/vendor/getTokenComparator.ts b/packages/command-visualizer/src/vendor/allocate-hats/vendor/getTokenComparator.ts index 1aabf0364e..271b6061c4 100644 --- a/packages/command-visualizer/src/vendor/allocate-hats/vendor/getTokenComparator.ts +++ b/packages/command-visualizer/src/vendor/allocate-hats/vendor/getTokenComparator.ts @@ -1,7 +1,17 @@ /** - * Vendored from cursorless packages/cursorless-engine/src/util/allocateHats/getTokenComparator.ts - * at SHA 42452eba521bb9cccbb3e04a2cd9e9afcf6cbffe. - * Edits are IMPORT REWRITES ONLY (applied by scripts/vendor.sh): + * Vendored from cursorless getTokenComparator.ts (byte-identical to both the + * pin at SHA 42452eba521bb9cccbb3e04a2cd9e9afcf6cbffe and current upstream). + * + * Kept local rather than imported from @cursorless/lib-engine because the + * engine version types `TokenWithDisplayLine extends Token` against + * lib-common's FULL `Token` (editor.document, method-bearing Range, ...). The + * standalone allocator builds its comparator input from the SIMPLIFIED Token + * in ../common/types, which is not assignable to lib-common's Token, so the + * imported signature would not typecheck against rank.ts's call site. The + * regex and the pure-generic maxByFirstDiffering ARE imported from source; + * this one stays local for that type-compatibility reason only. + * + * Edits are IMPORT REWRITES ONLY: * - "@cursorless/common" -> "../common" barrel */ diff --git a/packages/command-visualizer/src/vendor/allocate-hats/vendor/maxByFirstDiffering.ts b/packages/command-visualizer/src/vendor/allocate-hats/vendor/maxByFirstDiffering.ts deleted file mode 100644 index a42a4bacbb..0000000000 --- a/packages/command-visualizer/src/vendor/allocate-hats/vendor/maxByFirstDiffering.ts +++ /dev/null @@ -1,75 +0,0 @@ -/** - * Vendored from cursorless packages/cursorless-engine/src/util/allocateHats/maxByFirstDiffering.ts - * at SHA 42452eba521bb9cccbb3e04a2cd9e9afcf6cbffe. - * Edits are IMPORT REWRITES ONLY (applied by scripts/vendor.sh): - * (none — file has no imports) - */ - -/** - * Given an array of items and a list of functions that return a number for each - * item, return the item that has the maximum value according to the - * mathematical lexicographic order. Ie, first narrows down to items that share - * the maximum value for the first function, then of those remaining, narrows - * down to those that have the maximum value for the second, etc. Whenever - * there is only 1 item remaining, that item is returned. If the list is empty, - * undefined is returned. - * - * @example maxByFirstDiffering([{a: 1, b: 1}, {a: 1, b: 2}], [({a}) => a, ({b}) => - * b]) === {a: 1, b: 2} - * - * @param arr The array to find the max value of - * @param fns A list of functions that return a number for each item in the - * array - * @returns The item in the array that has the maximum value, or undefined if - * array is empty or all items are removed - */ -export function maxByFirstDiffering( - arr: T[], - fns: ((item: T) => number)[], -): T | undefined { - if (arr.length === 0) { - return undefined; - } - let remainingValues = arr; - for (const fn of fns) { - if (remainingValues.length === 1) { - return remainingValues[0]; - } - remainingValues = maxByAllowingTies(remainingValues, fn); - } - return remainingValues[0]; -} - -/** - * Given an array of items and a function that returns a number for each item, - * return all items that share the maximum value according to that function. - * @param arr The array to find the max values of - * @param fn A function that returns a number for each item in the array - * @returns All items in the array that share the maximum value - **/ -export function maxByAllowingTies(arr: T[], fn: (item: T) => number): T[] { - // This is equivalent to, but faster than: - // - // const max = Math.max(...arr.map(fn)); - // return arr.filter((item) => fn(item) === max); - // - // It does only a single pass through the array, and allocates no - // intermediate arrays (in the common case). - - // Accumulate all items with the single highest value, - // resetting whenever we find a new highest value. - let best: number = -Infinity; - const keep: T[] = []; - for (const item of arr) { - const value = fn(item); - if (value < best) { - continue; - } - if (value > best) { - best = value; - keep.length = 0; - } - keep.push(item); - } - return keep; -} From 4d8b3744b97694004991176f33fb1cab88f3e127 Mon Sep 17 00:00:00 2001 From: Trillium Smith Date: Tue, 7 Jul 2026 16:52:59 -0700 Subject: [PATCH 07/53] refactor(command-visualizer): derive FlashStyle from @cursorless/lib-common enum data/decorations.ts hand-maintained a string union whose five members mirrored @cursorless/lib-common's FlashStyle enum values. Replace it with a template-literal type `${CursorlessFlashStyle}`, so the union's members are sourced from the enum (and track it automatically) while staying plain string literals. This keeps every existing usage working with zero churn: DECORATION_HEX keys, `"pendingDelete" as DecorationStyle` casts in pipeline.ts, and `styles.has("pendingDelete")` in css-cascade.ts all still typecheck, because the enum's values ARE those strings. No behavior change; the HEX values, FLASH_PULSE_MS, MS_PER_STATE, HighlightStyle, and overlayPrecedence stay local (cursorless exports none of them). --- .../src/data/decorations.ts | 25 +++++++++---------- 1 file changed, 12 insertions(+), 13 deletions(-) diff --git a/packages/command-visualizer/src/data/decorations.ts b/packages/command-visualizer/src/data/decorations.ts index 4c91dc4b38..ca9513491b 100644 --- a/packages/command-visualizer/src/data/decorations.ts +++ b/packages/command-visualizer/src/data/decorations.ts @@ -2,19 +2,18 @@ // (research/highlight-rendering.md §3; verified 2026-06-08). SPEC-v2 §3.1. // All background-only; alpha baked into the 8-digit hex; theme-INVARIANT. -// Provenance: these five names are the string values of @cursorless/lib-common's -// `FlashStyle` enum (ide/types/FlashDescriptor.ts). We deliberately keep a local -// string-union rather than importing the enum: the names compose here with -// HighlightStyle into DecorationStyle, which keys DECORATION_HEX and drives -// overlayPrecedence — switching to enum members would churn every literal and -// buy no runtime behavior. The HEX values, FLASH_PULSE_MS, MS_PER_STATE, and -// precedence are ours and are not exported by cursorless. -export type FlashStyle = - | "pendingDelete" - | "justAdded" - | "referenced" - | "pendingModification0" - | "pendingModification1"; +import { FlashStyle as CursorlessFlashStyle } from "@cursorless/lib-common"; + +// FlashStyle is DERIVED from @cursorless/lib-common's `FlashStyle` enum +// (ide/types/FlashDescriptor.ts) — not cloned. The template-literal type turns +// the enum's string VALUES into the union +// "pendingDelete" | "referenced" | "pendingModification0" | +// "pendingModification1" | "justAdded", so every existing string-keyed usage +// (DECORATION_HEX keys, "pendingDelete" as DecorationStyle, styles.has(...)) +// keeps working with zero literal churn, while the set of valid names now +// tracks lib-common automatically. The HEX values, FLASH_PULSE_MS, +// MS_PER_STATE, and precedence remain ours (not exported by cursorless). +export type FlashStyle = `${CursorlessFlashStyle}`; export type HighlightStyle = "highlight0" | "highlight1"; From 78c07c7caa51d67cf6ffe03e4376d9bbcdedeb7a Mon Sep 17 00:00:00 2001 From: Trillium Smith Date: Tue, 7 Jul 2026 16:54:12 -0700 Subject: [PATCH 08/53] docs(command-visualizer): re-verify fixture-mark/path dedup notes against live signatures MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Step 5 investigation: the fixture-mark and fixture-path import candidates were re-checked against the current cursorless source, not the stale prior notes. - serializedMarksToTokenHats(marks, editor) still hard-requires a live TextEditor (offsetAt/getText) and returns engine TokenHat[]; parseMarks reads editor-less YAML into the MarkInfo render model. Not swappable — kept. - getFixturesPath() hardcodes resources/fixtures (layout A only) and getCursorlessRepoRoot() throws unless CURSORLESS_REPO_ROOT is set. Our fixture-root keeps the dual-layout probe + $CURSORLESS_REPO default. Swapping would regress. Kept. - fixture-yaml.ts already uses js-yaml's load() — the same lib/entry point loadFixture uses — so the YAML parsing is already deduplicated at the library level; no further change. Comment-only: sharpens the provenance notes to cite the exact blocking signatures. No code change. --- .../command-visualizer/src/fixture-extract.ts | 18 ++++++++++-------- .../command-visualizer/src/fixture-root.ts | 16 ++++++++++------ 2 files changed, 20 insertions(+), 14 deletions(-) diff --git a/packages/command-visualizer/src/fixture-extract.ts b/packages/command-visualizer/src/fixture-extract.ts index bdc150d8b3..fe4fa90dae 100644 --- a/packages/command-visualizer/src/fixture-extract.ts +++ b/packages/command-visualizer/src/fixture-extract.ts @@ -28,14 +28,16 @@ export function pos(v: YamlValue | undefined): Pos { return { line: num(o.line), character: num(o.character) }; } -// Dedup note (step 4c): @cursorless/lib-common exports -// serializedMarksToTokenHats, but it requires a live TextEditor (document -// offsetAt/getText) and returns TokenHat[] — a shape built for the engine, not -// for SVG rendering. Our parseMarks reads plain fixture-YAML objects with no -// editor and yields the MarkInfo render model buildLines() needs. buildLines() -// itself (tokenize → attach fixture hats → real allocator fill → author -// overrides) is genuinely ours. Adopting the engine helper would mean faking a -// TextEditor and rewriting buildLines — scope balloon for no gain. Kept. +// Dedup note (re-verified against current signatures): @cursorless/lib-common +// exports serializedMarksToTokenHats(marks, editor), but its signature +// hard-requires a live TextEditor — it calls editor.document.offsetAt(range) +// and editor.document.getText(range) — and returns engine TokenHat[] +// (token.editor/offsets/hatRange). Our parseMarks reads plain fixture-YAML +// `{color}.{grapheme}` objects with NO editor and yields the MarkInfo render +// model buildLines() needs. buildLines() itself (tokenize → attach fixture hats +// → real allocator fill → author overrides) is genuinely ours. Adopting the +// engine helper would mean synthesizing a fake TextEditor and rewriting +// buildLines — scope balloon for no gain. Kept. // Step 4: a `{color}.{grapheme}` mark with its line range. export interface MarkInfo { diff --git a/packages/command-visualizer/src/fixture-root.ts b/packages/command-visualizer/src/fixture-root.ts index dd3035fc61..982ff9629f 100644 --- a/packages/command-visualizer/src/fixture-root.ts +++ b/packages/command-visualizer/src/fixture-root.ts @@ -11,12 +11,16 @@ // Throws a CLEAR error if the resolved root does not exist, so a misconfigured // checkout fails loudly at startup instead of with an opaque ENOENT mid-run. // -// Dedup note (step 4b): @cursorless/lib-node-common exports getFixturesPath / -// getRecordedTestsDirPath, but they hardcode the single `resources/fixtures` -// layout and offer no $CURSORLESS_REPO override. This module deliberately keeps -// its dual-layout probe (resources/… fork vs data/… main repo) plus the env -// override and loud errors, so it works across both checkout shapes the -// renderer targets. Adopting lib-node-common's helpers would be a regression. +// Dedup note (re-verified against current signatures): @cursorless/lib-node-common +// exports getFixturesPath()/getRecordedTestsDirPath(), but getFixturesPath() +// hardcodes `path.join(getCursorlessRepoRoot(), "resources", "fixtures")` — the +// single layout-A shape — and getCursorlessRepoRoot() *throws* unless +// CURSORLESS_REPO_ROOT is set (a script-only helper). This module deliberately +// keeps its dual-layout probe (resources/… fork vs data/… main repo), its +// $CURSORLESS_REPO override with a working $HOME/code/cursorless default, and +// loud errors, so it resolves across both checkout shapes the renderer targets. +// Adopting lib-node-common's helpers would be a regression (layout B unreachable, +// no default root). Kept. import { existsSync } from "node:fs"; import { homedir } from "node:os"; From daf3180f8c170908ad9d2f4e61de7e51604ca47a Mon Sep 17 00:00:00 2001 From: Trillium Smith Date: Tue, 7 Jul 2026 16:56:49 -0700 Subject: [PATCH 09/53] docs(command-visualizer): colors/shapes dedup decision (Option B) + status MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Step 6: the hat color hexes, shape SVG d= path strings, color/shape names, and shape adjustments have no importable TS module, so they are KEPT in data/colors.ts / data/shapes.ts with precise provenance. Option A (a canonical exported constants module) is rejected: the hexes live in app-vscode's package.json as VS Code setting defaults (runtime-read, never a TS constant) and the SVG d= strings live in resources/images/hats/*.svg (runtime-read by VscodeHatRenderer), so any new TS constant would be a third copy; and the clean TS constants that DO exist upstream (hatStyles.types.ts, shapeAdjustments.ts) sit in app-vscode, whose only export is ./extension.cjs — single-sourcing them needs promoting both to lib-common and rewiring 5 app-vscode files (the shipping extension's hat path), the risky refactor this task scoped out. Comments now name the exact upstream export that would be needed and record the deferred follow-up. STATUS.md documents the full import-not-clone pass and the Option-B rationale. Comment/doc-only; no code change. --- packages/command-visualizer/STATUS.md | 65 ++++++++++++++++++- .../command-visualizer/src/data/colors.ts | 16 +++++ .../command-visualizer/src/data/shapes.ts | 20 ++++++ 3 files changed, 100 insertions(+), 1 deletion(-) diff --git a/packages/command-visualizer/STATUS.md b/packages/command-visualizer/STATUS.md index 8cfd09285c..2613edd7e0 100644 --- a/packages/command-visualizer/STATUS.md +++ b/packages/command-visualizer/STATUS.md @@ -33,12 +33,75 @@ in-monorepo. Everything below touches ONLY `packages/command-visualizer/`. - `fixture-extract.ts` `parseMarks`/`buildLines` — lib-common's `serializedMarksToTokenHats` needs a live `TextEditor` and returns engine `TokenHat[]`; our render model reads plain YAML with no editor. -5. **Compile config fixed** (step 5). Dropped the non-idiomatic +5. **Compile config fixed**. Dropped the non-idiomatic `tsc --build`/composite setup (no sibling package uses it); `compile:tsc` is now plain `tsc`, matching the repo's typecheck convention (resolution via `tsconfig.base.json` `paths`). Fixed a real pre-existing type error: `pipeline.ts` used `GeneralizedRange` and `Pos` without importing them. +## Dedup against cursorless source (import-not-clone pass) + +This pass replaced vendored/cloned code with imports from cursorless packages. +lib-engine gained additive exports (own commit) to make it possible. + +- **DefaultMap / CompositeKeyMap** → imported from `@cursorless/lib-common` + (deleted the two `vendor/allocate-hats/common/` copies). +- **GRAPHEME_SPLIT_REGEX** → imported from `@cursorless/lib-engine` in + `columns.ts`, `tokenize.ts`, and `vendor/allocate-hats/splitter.ts` (was + cloned in all three). +- **maxByFirstDiffering** → imported from `@cursorless/lib-engine` (deleted the + vendored copy). +- **FlashStyle** → derived from `@cursorless/lib-common`'s enum via + `` `${CursorlessFlashStyle}` `` (was a hand-maintained string union). +- **lib-engine exports added** (separate lib-engine commit): the allocateHats + primitives + tokenGraphemeSplitter barrel now surface from the lib-engine + index, so the above imports resolve. + +**Still vendored, PINNED at SHA 42452eb on purpose** (current upstream has +diverged — importing would change hat placement or fail to typecheck against the +standalone's simplified types): `chooseTokenHat`, `HatMetrics`, +`getHatRankingContext`, `getTokenComparator`, `common/types.ts`, the tokens-in +`allocateHats` wrapper (`index.ts`), `rank.ts`, `StandaloneGraphemeSplitter` +(`splitter.ts`). Each file header states the exact reason; `VENDOR.md` has the +full split. Upstream added `forcedTokenHat` (#2602) and `avoidFirstLetter` / +`HatCandidate.isFirstLetter` (#1723), and the engine splitter needs a live IDE. + +**Still local (fixture path/marks):** `parseMarks`/`buildLines` (needs no +TextEditor, unlike lib-common's `serializedMarksToTokenHats`), `fixture-root.ts` +(dual-layout probe + `$CURSORLESS_REPO` default, unlike lib-node-common's +single-layout `getFixturesPath`). `fixture-yaml.ts` already uses `js-yaml`. + +## Colors / shapes data — step 6 decision: Option B (keep, with provenance) + +The hat COLOR hexes, shape SVG `d=` path strings, color names, shape names, and +shape adjustments have **no importable TS module**, so they are KEPT in +`data/colors.ts` / `data/shapes.ts` with precise provenance comments naming the +exact upstream export that would be needed. Option A (add a canonical exported +constants module) was rejected because it cannot be done without either: + +- creating a THIRD copy — the color hexes live in `app-vscode/package.json` as + VS Code setting defaults (read at runtime, never a TS constant) and the SVG + `d=` strings live in `resources/images/hats/*.svg` (read at runtime by + `VscodeHatRenderer.ts`), so any new TS constant is a second/third copy; or +- a risky app-vscode refactor — `HAT_COLORS`/`HAT_SHAPES`/`HatShape` and + `defaultShapeAdjustments` DO exist as clean TS constants in + `app-vscode/src/ide/vscode/hatStyles.types.ts` and `.../hats/shapeAdjustments.ts`, + but app-vscode exports only `./extension.cjs`, so single-sourcing them means + promoting both into `@cursorless/lib-common` AND rewiring the 5 app-vscode + files that consume them (VscodeHatRenderer, performPr1868ShapeUpdateInit, the + two hatAdjustments scripts) — the shipping extension's hat path, out of scope. + +**Follow-up (deferred):** promote `hatStyles.types.ts` + `shapeAdjustments.ts` +into lib-common and rewire those 5 app-vscode files; the `.svg` `d=` strings +would still need a separate build-time loader (or a generated TS constant) to +avoid a second copy. + +## Security + +- **CodeQL XSS (serialize-cascade.ts)** fixed: the attribute escaper now also + escapes `"` (and `'`), so fixture/spoken-form strings can no longer break out + of the double-quoted `data-fixture` / `data-spoken-form` attributes. + ## Remaining blockers (NOT introduced by this work) Running `pnpm compile` in the current checkout surfaces errors that are all diff --git a/packages/command-visualizer/src/data/colors.ts b/packages/command-visualizer/src/data/colors.ts index 78862e8994..23637a28f2 100644 --- a/packages/command-visualizer/src/data/colors.ts +++ b/packages/command-visualizer/src/data/colors.ts @@ -2,6 +2,22 @@ // cursorless/packages/app-vscode/package.json cursorless.colors.{dark,light} // (verified 2026-06-08; also mirrored in screenshots/oracle/color-matrix.json). // SPEC §4.4. +// +// WHY NOT IMPORTED (step 6 decision — Option B, kept-with-provenance): +// These hexes have NO importable TS module. They are declared in app-vscode's +// package.json as VS Code setting DEFAULTS (contributes.configuration +// "cursorless.colors.dark" / ".light") and read at runtime from VS Code +// configuration — app-vscode itself never holds them as a TS constant, and its +// package exports only ./extension.cjs. Manufacturing a lib-common +// `defaultHatColors` constant here would create a THIRD copy (package.json stays +// canonical for the extension), which the dedup explicitly forbids. +// The HAT_COLORS / HatColor name list below duplicates +// app-vscode/src/ide/vscode/hatStyles.types.ts, which is likewise not +// importable (app-vscode exports only extension.cjs). +// FOLLOW-UP to actually single-source: move HAT_COLORS + a `defaultHatColors` +// hex map into @cursorless/lib-common and rewire app-vscode (VscodeHatRenderer +// + package.json generation) to consume it — deferred as it touches the +// shipping extension's hat path (5 app-vscode files). export type HatColor = | "default" diff --git a/packages/command-visualizer/src/data/shapes.ts b/packages/command-visualizer/src/data/shapes.ts index 4dd6fbe095..e5a2729c65 100644 --- a/packages/command-visualizer/src/data/shapes.ts +++ b/packages/command-visualizer/src/data/shapes.ts @@ -3,6 +3,26 @@ // Only `crosshairs` carries fill-rule="evenodd" clip-rule="evenodd"; every // other shape uses the SVG default (nonzero). `ex` is a single subpath (no hole). // SPEC §4.1 / DECISIONS.md CORRECTION. +// +// WHY NOT IMPORTED (step 6 decision — Option B, kept-with-provenance): +// - SHAPE_PATHS `d=` strings: the canonical source is the 11 .svg files under +// resources/images/hats/, which app-vscode's VscodeHatRenderer.ts reads at +// RUNTIME (readFile of `${shape}.svg`) — there is no compile-time TS +// constant for them. Building an SVG-loader here or a TS path constant would +// be a second copy; the safest single-source would be a shared build step +// that reads the .svg files, which is out of scope. +// - HAT_SHAPES / HatShape / SHAPE_ADJUSTMENTS: these DO exist as clean TS +// constants upstream — HAT_SHAPES/HAT_NON_DEFAULT_SHAPES/HatShape in +// app-vscode/src/ide/vscode/hatStyles.types.ts and defaultShapeAdjustments +// (+ DEFAULT_HAT_HEIGHT_EM / DEFAULT_VERTICAL_OFFSET_EM) in +// app-vscode/src/ide/vscode/hats/shapeAdjustments.ts — but app-vscode +// exports only ./extension.cjs, so nothing outside it can import them. +// FOLLOW-UP to actually single-source: promote hatStyles.types.ts + +// shapeAdjustments.ts into @cursorless/lib-common and rewire the 5 app-vscode +// files that import them (VscodeHatRenderer, performPr1868ShapeUpdateInit, the +// two hatAdjustments scripts). Deferred: it touches the shipping extension's +// hat-rendering path and is the "risky app-vscode refactor" this task scoped +// out. The .svg `d=` strings would still need a separate build-time loader. export type HatShape = | "default" From 538c7146822e5f70e5e623fb8d6da313f242f3f8 Mon Sep 17 00:00:00 2001 From: Trillium Smith Date: Tue, 7 Jul 2026 16:57:59 -0700 Subject: [PATCH 10/53] fix(command-visualizer): escape quotes in HTML attribute values (CodeQL XSS) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit serialize-cascade.ts's esc() escaped &, <, > but not the quote characters, so a fixture name or spoken form containing a double quote could break out of the double-quoted data-fixture="…" / data-spoken-form="…" attributes it is interpolated into (CodeQL: "Incomplete HTML attribute sanitization: output may contain double quotes when it reaches an attribute definition"). esc() now also escapes " → " and ' → ', making it safe for both text-content and quoted-attribute contexts. Over-escaping quotes in text (the caption / ) is harmless. Verified: a fixture name of `x" onload="alert(1)"><script>…` is fully neutralized — no attribute breakout, no tag injection. --- .../command-visualizer/src/serialize-cascade.ts | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) diff --git a/packages/command-visualizer/src/serialize-cascade.ts b/packages/command-visualizer/src/serialize-cascade.ts index fe87a41624..240e00768a 100644 --- a/packages/command-visualizer/src/serialize-cascade.ts +++ b/packages/command-visualizer/src/serialize-cascade.ts @@ -14,8 +14,21 @@ import { resolveFrameOverlays, type LineOverlay } from "./overlays"; import { HIGHLIGHT_STYLES, MS_PER_STATE } from "./data/decorations"; import { timelineOf } from "./timeline"; +// HTML escaper safe for BOTH text content AND quoted-attribute contexts. +// `&` is escaped first (so it can't double-escape the entities below), then the +// tag delimiters, then BOTH quote characters. Escaping the quotes is what +// closes the CodeQL "incomplete HTML attribute sanitization" finding: fixture / +// spoken-form strings are interpolated into double-quoted attributes +// (data-fixture="…", data-spoken-form="…", <title>…), and an unescaped `"` +// would break out of the attribute. Over-escaping quotes in text content is +// harmless — " / ' render as " / '. function esc(s: string): string { - return s.replace(/&/g, "&").replace(/</g, "<").replace(/>/g, ">"); + return s + .replace(/&/g, "&") + .replace(/</g, "<") + .replace(/>/g, ">") + .replace(/"/g, """) + .replace(/'/g, "'"); } function charToCol(cols: Column[], charIndex: number): number { From 5e3142ca5c3ff9b045e50ba9c97ef23ef94ae48b Mon Sep 17 00:00:00 2001 From: Trillium Smith <trillium@trilliumsmith.com> Date: Tue, 7 Jul 2026 17:11:48 -0700 Subject: [PATCH 11/53] fix(command-visualizer): address CodeRabbit review findings R3-R10 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit R4 hat-allocator: oldAssignments now includes shape in styleName key (non-default shapes key as `${color}-${shape}` in cssStateHatStyles; pinned marks with shape overrides were reserving the wrong style key) R5 css.ts: replace hardcoded hat height/voffset constants with imports from shapes.ts (DEFAULT_HAT_HEIGHT_EM, DEFAULT_VERTICAL_OFFSET_EM) R6 chain.ts: guard empty states[] — throw ChainContinuityError(0) instead of spreading undefined R7 chain.ts: single-step path now propagates fixtureLabel into meta.fixture R3 fixture-yaml.ts: guard blank/whitespace input before js-yaml load() (js-yaml 5.x throws; {} fallback was unreachable without this guard) R8 fixture-extract.ts: skip mark keys with no '.' separator (indexOf('.') == -1 produced wrong slice offsets) R9 decorations.ts: fix stale comment '11 decoration styles' -> '7' R10 index.ts: fix package-name header @cursorless/cascade-renderer -> @cursorless/command-visualizer --- packages/command-visualizer/src/chain.ts | 5 ++++- packages/command-visualizer/src/css.ts | 11 ++++++++--- packages/command-visualizer/src/data/decorations.ts | 2 +- packages/command-visualizer/src/fixture-extract.ts | 3 +++ packages/command-visualizer/src/fixture-yaml.ts | 5 +++++ packages/command-visualizer/src/hat-allocator.ts | 7 ++++++- packages/command-visualizer/src/index.ts | 2 +- 7 files changed, 28 insertions(+), 7 deletions(-) diff --git a/packages/command-visualizer/src/chain.ts b/packages/command-visualizer/src/chain.ts index 2ce8de0c23..ebeda1b132 100644 --- a/packages/command-visualizer/src/chain.ts +++ b/packages/command-visualizer/src/chain.ts @@ -71,8 +71,11 @@ export function chainCascades( states: CascadeState[], fixtureLabel: string, ): CascadeState { + if (states.length === 0) { + throw new ChainContinuityError(0, "chainCascades requires at least one state"); + } if (states.length === 1) { - return states[0]; + return { ...states[0], meta: { ...states[0].meta, fixture: fixtureLabel } }; } const frames: Frame[] = []; diff --git a/packages/command-visualizer/src/css.ts b/packages/command-visualizer/src/css.ts index 1bea6c6664..0466651dbe 100644 --- a/packages/command-visualizer/src/css.ts +++ b/packages/command-visualizer/src/css.ts @@ -2,7 +2,12 @@ // adjustment values never drift. No render-time JS; CSS does 100% of visual work. import { COLOR_MATRIX, EDITOR_CHROME, HAT_COLORS } from "./data/colors"; -import { HAT_SHAPES, SHAPE_ADJUSTMENTS } from "./data/shapes"; +import { + DEFAULT_HAT_HEIGHT_EM, + DEFAULT_VERTICAL_OFFSET_EM, + HAT_SHAPES, + SHAPE_ADJUSTMENTS, +} from "./data/shapes"; function shapeAdjustmentRules(): string { const lines: string[] = [ @@ -50,8 +55,8 @@ export function styleSheet(): string { return `/* Cursorless state → static CSS. SPEC §4. Generated; do not hand-edit. */ :root { - --hat-height: 0.36em; /* DEFAULT_HAT_HEIGHT_EM */ - --hat-base-voffset: 0.05em; /* DEFAULT_VERTICAL_OFFSET_EM */ + --hat-height: ${DEFAULT_HAT_HEIGHT_EM}em; + --hat-base-voffset: ${DEFAULT_VERTICAL_OFFSET_EM}em; --user-size-adj: 0; /* cursorless.hatSizeAdjustment as fraction */ --user-voffset: 0em; /* Real VS Code default line-height resolves to ~1.35× for the editor font diff --git a/packages/command-visualizer/src/data/decorations.ts b/packages/command-visualizer/src/data/decorations.ts index ca9513491b..548fde881f 100644 --- a/packages/command-visualizer/src/data/decorations.ts +++ b/packages/command-visualizer/src/data/decorations.ts @@ -19,7 +19,7 @@ export type HighlightStyle = "highlight0" | "highlight1"; export type DecorationStyle = FlashStyle | HighlightStyle; -// All 11 decoration styles' background hexes (the 2 scope-pair styles use the +// All 7 decoration styles' background hexes (the 2 scope-pair styles use the // same band hex family; per-edge borders are BONUS, SPEC-v2 §3.5, not here). export const DECORATION_HEX: Record<DecorationStyle, string> = { pendingDelete: "#ff00008a", // REQUIRED (COMPLETION crit 3) diff --git a/packages/command-visualizer/src/fixture-extract.ts b/packages/command-visualizer/src/fixture-extract.ts index fe4fa90dae..9b26a0098d 100644 --- a/packages/command-visualizer/src/fixture-extract.ts +++ b/packages/command-visualizer/src/fixture-extract.ts @@ -59,6 +59,9 @@ export function parseMarks(marksObj: Obj | null): MarkInfo[] { continue; } const dot = key.indexOf("."); + if (dot === -1) { + continue; // mark key must be "{color}.{grapheme}" — skip malformed entries + } const colorRaw = key.slice(0, dot); const grapheme = key.slice(dot + 1); const color = (HAT_COLORS as string[]).includes(colorRaw) diff --git a/packages/command-visualizer/src/fixture-yaml.ts b/packages/command-visualizer/src/fixture-yaml.ts index b073380793..cf7a260965 100644 --- a/packages/command-visualizer/src/fixture-yaml.ts +++ b/packages/command-visualizer/src/fixture-yaml.ts @@ -34,6 +34,11 @@ export type YamlValue = * empty/null document so callers can index into it unconditionally. */ export function parseFixtureYaml(src: string): { [k: string]: YamlValue } { + // js-yaml 5.x throws on null/undefined input; guard so the `{}` fallback + // is actually reachable for blank or whitespace-only fixture strings. + if (!src || !src.trim()) { + return {}; + } const value = load(src) as YamlValue | undefined; if (value != null && typeof value === "object" && !Array.isArray(value)) { return value as { [k: string]: YamlValue }; diff --git a/packages/command-visualizer/src/hat-allocator.ts b/packages/command-visualizer/src/hat-allocator.ts index 4a0093812d..cb95012106 100644 --- a/packages/command-visualizer/src/hat-allocator.ts +++ b/packages/command-visualizer/src/hat-allocator.ts @@ -131,7 +131,12 @@ export function allocateHats( tokenIdx: idx, charIdx: g.range.start - seg.start, grapheme: SPLITTER.normalizeGrapheme(g.text), - styleName: g.hat.color, + // Include shape so the allocator reserves the right style key + // (cssStateHatStyles keys non-default shapes as `${color}-${shape}`). + styleName: + g.hat.shape === "default" || !g.hat.shape + ? g.hat.color + : `${g.hat.color}-${g.hat.shape}`, }); break; // one mark pins the whole segment } diff --git a/packages/command-visualizer/src/index.ts b/packages/command-visualizer/src/index.ts index 2ed616bb39..1398265071 100644 --- a/packages/command-visualizer/src/index.ts +++ b/packages/command-visualizer/src/index.ts @@ -1,4 +1,4 @@ -// @cursorless/cascade-renderer — public surface. +// @cursorless/command-visualizer — public surface. // // fixture YAML in -> animated SVG out. See STATUS.md for integration state. From f1845e6d193e3d63c9b84c254712266e48310952 Mon Sep 17 00:00:00 2001 From: Trillium Smith <trillium@trilliumsmith.com> Date: Tue, 7 Jul 2026 17:11:56 -0700 Subject: [PATCH 12/53] refactor(lib-engine): trim allocateHats barrel to only consumed exports @cursorless/command-visualizer imports exactly one primitive from this sub-tree: maxByFirstDiffering (vendor/chooseTokenHat.ts, SHA 42452eb). The broader set added in the prior export commit (chooseTokenHat, getHatRankingContext, getRankedTokens, getTokenComparator, HatMetrics, avoidFirstLetter, ...) are NOT consumed by command-visualizer and must stay vendored there because they have drifted in signature since the pinned SHA (forcedTokenHat param, avoidFirstLetter metric). Exporting them here would invite callers to take a dependency on unstable internals. Trimmed to: { allocateHats } (pre-existing) + { maxByFirstDiffering } (new). --- .../lib-engine/src/util/allocateHats/index.ts | 27 +++++-------------- 1 file changed, 7 insertions(+), 20 deletions(-) diff --git a/packages/lib-engine/src/util/allocateHats/index.ts b/packages/lib-engine/src/util/allocateHats/index.ts index 11d639494f..da81596e3e 100644 --- a/packages/lib-engine/src/util/allocateHats/index.ts +++ b/packages/lib-engine/src/util/allocateHats/index.ts @@ -1,22 +1,9 @@ export { allocateHats } from "./allocateHats"; -export type { HatCandidate } from "./allocateHats"; -// Individual hat-allocation primitives, exported so downstream consumers (e.g. -// @cursorless/command-visualizer) can reuse the real ranking/selection -// building blocks instead of vendoring copies of them. -export { chooseTokenHat } from "./chooseTokenHat"; -export { getHatRankingContext } from "./getHatRankingContext"; -export type { RankingContext } from "./getHatRankingContext"; -export { getRankedTokens } from "./getRankedTokens"; -export type { RankedToken } from "./getRankedTokens"; -export { getTokenComparator } from "./getTokenComparator"; -export { maxByFirstDiffering, maxByAllowingTies } from "./maxByFirstDiffering"; -export type { HatMetric } from "./HatMetrics"; -export { - avoidFirstLetter, - hatOldTokenRank, - isOldTokenHat, - minimumTokenRankContainingGrapheme, - negativePenalty, - penaltyEquivalenceClass, -} from "./HatMetrics"; +// maxByFirstDiffering is the only primitive from this sub-tree imported by +// @cursorless/command-visualizer (vendored chooseTokenHat.ts, SHA 42452eb). +// The broader ranking/selection helpers (chooseTokenHat, getHatRankingContext, +// HatMetrics, etc.) have drifted in signature since that SHA and must stay +// vendored there; they are NOT re-exported here to keep the public surface +// minimal and prevent callers from taking a dependency on unstable internals. +export { maxByFirstDiffering } from "./maxByFirstDiffering"; From c281f46d014df94ca0c63b1a2115ea455247c0f7 Mon Sep 17 00:00:00 2001 From: Trillium Smith <trillium@trilliumsmith.com> Date: Tue, 7 Jul 2026 18:20:19 -0700 Subject: [PATCH 13/53] feat(lib-common): promote hat shapeAdjustments from app-vscode MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Moves the shape-adjustment constants (defaultShapeAdjustments, DEFAULT_HAT_HEIGHT_EM, DEFAULT_VERTICAL_OFFSET_EM, HatAdjustments, IndividualHatAdjustmentMap) out of app-vscode into lib-common, alongside the already-shared hatStyles.types, so non-VS-Code consumers (e.g. @cursorless/command-visualizer) can import them instead of vendoring a copy. app-vscode's original shapeAdjustments.ts becomes a backward-compatible re-export shim, so its consumers (VscodeHatRenderer, performPr1868ShapeUpdateInit, the hatAdjustments scripts) are unchanged. No behavior change — values are byte-identical to the previous location. --- .../src/ide/vscode/hats/shapeAdjustments.ts | 55 +++++-------------- .../src/ide/types/shapeAdjustments.ts | 40 ++++++++++++++ packages/lib-common/src/index.ts | 1 + 3 files changed, 56 insertions(+), 40 deletions(-) create mode 100644 packages/lib-common/src/ide/types/shapeAdjustments.ts diff --git a/packages/app-vscode/src/ide/vscode/hats/shapeAdjustments.ts b/packages/app-vscode/src/ide/vscode/hats/shapeAdjustments.ts index d0e978d42e..8a2f9bc0f9 100644 --- a/packages/app-vscode/src/ide/vscode/hats/shapeAdjustments.ts +++ b/packages/app-vscode/src/ide/vscode/hats/shapeAdjustments.ts @@ -1,40 +1,15 @@ -import type { HatShape } from "../hatStyles.types"; - -export interface HatAdjustments { - sizeAdjustment?: number; - strokeFactor?: number; - verticalOffset?: number; -} - -export type IndividualHatAdjustmentMap = Record<HatShape, HatAdjustments>; - -export const DEFAULT_HAT_HEIGHT_EM = 0.36; -export const DEFAULT_VERTICAL_OFFSET_EM = 0.05; - -export const defaultShapeAdjustments: IndividualHatAdjustmentMap = { - default: { - sizeAdjustment: -30, - }, - ex: { - sizeAdjustment: -12.5, - }, - fox: { - sizeAdjustment: -5, - }, - wing: { - sizeAdjustment: -2.5, - }, - hole: { - strokeFactor: 0.7, - }, - frame: { - sizeAdjustment: -20, - }, - curve: { - verticalOffset: -5, - }, - eye: {}, - play: {}, - bolt: {}, - crosshairs: {}, -}; +// Hat shape adjustments were promoted to @cursorless/lib-common so non-VS-Code +// consumers (e.g. @cursorless/command-visualizer) can import them without a +// clone. This file is a backward-compatible re-export shim so the existing +// app-vscode consumers (VscodeHatRenderer, performPr1868ShapeUpdateInit, the +// hatAdjustments scripts) keep importing from their original path unchanged. + +export type { + HatAdjustments, + IndividualHatAdjustmentMap, +} from "@cursorless/lib-common"; +export { + DEFAULT_HAT_HEIGHT_EM, + DEFAULT_VERTICAL_OFFSET_EM, + defaultShapeAdjustments, +} from "@cursorless/lib-common"; diff --git a/packages/lib-common/src/ide/types/shapeAdjustments.ts b/packages/lib-common/src/ide/types/shapeAdjustments.ts new file mode 100644 index 0000000000..ddc7ca9834 --- /dev/null +++ b/packages/lib-common/src/ide/types/shapeAdjustments.ts @@ -0,0 +1,40 @@ +import type { HatShape } from "./hatStyles.types"; + +export interface HatAdjustments { + sizeAdjustment?: number; + strokeFactor?: number; + verticalOffset?: number; +} + +export type IndividualHatAdjustmentMap = Record<HatShape, HatAdjustments>; + +export const DEFAULT_HAT_HEIGHT_EM = 0.36; +export const DEFAULT_VERTICAL_OFFSET_EM = 0.05; + +export const defaultShapeAdjustments: IndividualHatAdjustmentMap = { + default: { + sizeAdjustment: -30, + }, + ex: { + sizeAdjustment: -12.5, + }, + fox: { + sizeAdjustment: -5, + }, + wing: { + sizeAdjustment: -2.5, + }, + hole: { + strokeFactor: 0.7, + }, + frame: { + sizeAdjustment: -20, + }, + curve: { + verticalOffset: -5, + }, + eye: {}, + play: {}, + bolt: {}, + crosshairs: {}, +}; diff --git a/packages/lib-common/src/index.ts b/packages/lib-common/src/index.ts index 2ed2329a15..e17f4e365f 100644 --- a/packages/lib-common/src/index.ts +++ b/packages/lib-common/src/index.ts @@ -24,6 +24,7 @@ export * from "./ide/types/FlashDescriptor"; export * from "./ide/types/Hats"; export * from "./ide/types/HatStability"; export * from "./ide/types/hatStyles.types"; +export * from "./ide/types/shapeAdjustments"; export * from "./ide/types/ide.types"; export * from "./ide/types/KeyValueStore"; export * from "./ide/types/Messages"; From dd1536ef362aa7e1e59bc577f4a8317c3190978d Mon Sep 17 00:00:00 2001 From: Trillium Smith <trillium@trilliumsmith.com> Date: Tue, 7 Jul 2026 18:25:11 -0700 Subject: [PATCH 14/53] refactor(command-visualizer): import hat color/shape vocabulary from lib-common MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Addresses PR review (colors.ts, shapes.ts flagged as duplicating cursorless). HatColor/HAT_COLORS and HatShape/HAT_SHAPES/HAT_NON_DEFAULT_SHAPES are now imported/re-exported from @cursorless/lib-common instead of being redefined, along with the shape-adjustment constants (SHAPE_ADJUSTMENTS, DEFAULT_HAT_HEIGHT_EM, DEFAULT_VERTICAL_OFFSET_EM) promoted there. Kept local (no importable TS home — canonical source is app-vscode's package.json VS Code config defaults / resources/*.svg, read at runtime): - COLOR_MATRIX / EDITOR_CHROME theme hexes - SHAPE_PATHS SVG 'd=' strings Provenance comments updated to say exactly why each stays. fixture-extract.ts: HAT_COLORS is now a readonly tuple, so the membership cast becomes 'as readonly string[]'. --- .../command-visualizer/src/data/colors.ts | 55 ++------- .../command-visualizer/src/data/shapes.ts | 106 ++++-------------- .../command-visualizer/src/fixture-extract.ts | 2 +- 3 files changed, 37 insertions(+), 126 deletions(-) diff --git a/packages/command-visualizer/src/data/colors.ts b/packages/command-visualizer/src/data/colors.ts index 23637a28f2..3c9e36a5f6 100644 --- a/packages/command-visualizer/src/data/colors.ts +++ b/packages/command-visualizer/src/data/colors.ts @@ -1,48 +1,17 @@ -// Color matrix — hexes VERBATIM from -// cursorless/packages/app-vscode/package.json cursorless.colors.{dark,light} -// (verified 2026-06-08; also mirrored in screenshots/oracle/color-matrix.json). -// SPEC §4.4. -// -// WHY NOT IMPORTED (step 6 decision — Option B, kept-with-provenance): -// These hexes have NO importable TS module. They are declared in app-vscode's -// package.json as VS Code setting DEFAULTS (contributes.configuration -// "cursorless.colors.dark" / ".light") and read at runtime from VS Code -// configuration — app-vscode itself never holds them as a TS constant, and its -// package exports only ./extension.cjs. Manufacturing a lib-common -// `defaultHatColors` constant here would create a THIRD copy (package.json stays -// canonical for the extension), which the dedup explicitly forbids. -// The HAT_COLORS / HatColor name list below duplicates -// app-vscode/src/ide/vscode/hatStyles.types.ts, which is likewise not -// importable (app-vscode exports only extension.cjs). -// FOLLOW-UP to actually single-source: move HAT_COLORS + a `defaultHatColors` -// hex map into @cursorless/lib-common and rewire app-vscode (VscodeHatRenderer -// + package.json generation) to consume it — deferred as it touches the -// shipping extension's hat path (5 app-vscode files). +// Hat color names/types are imported from @cursorless/lib-common (the shared +// hatStyles.types) — NOT redefined here. Only the theme hex MATRIX below is +// local, because it has no importable TS home: the hexes are declared in +// app-vscode's package.json as VS Code setting DEFAULTS +// (contributes.configuration "cursorless.colors.dark" / ".light") and read at +// runtime from VS Code configuration — there is no compile-time constant for +// them anywhere in the tree, so mirroring the defaults here (with provenance) +// is the faithful rendering for a headless renderer. Values verified against +// app-vscode/package.json 2026-06-08. SPEC §4.4. -export type HatColor = - | "default" - | "blue" - | "green" - | "red" - | "pink" - | "yellow" - | "userColor1" - | "userColor2" - | "userColor3" - | "userColor4"; +export type { HatColor } from "@cursorless/lib-common"; +export { HAT_COLORS } from "@cursorless/lib-common"; -export const HAT_COLORS: HatColor[] = [ - "default", - "blue", - "green", - "red", - "pink", - "yellow", - "userColor1", - "userColor2", - "userColor3", - "userColor4", -]; +import type { HatColor } from "@cursorless/lib-common"; export type Theme = "dark" | "light"; diff --git a/packages/command-visualizer/src/data/shapes.ts b/packages/command-visualizer/src/data/shapes.ts index e5a2729c65..93bae18184 100644 --- a/packages/command-visualizer/src/data/shapes.ts +++ b/packages/command-visualizer/src/data/shapes.ts @@ -1,55 +1,27 @@ -// Hat shape SVG path data — copied VERBATIM from -// cursorless/resources/images/hats/{shape}.svg (verified 2026-06-08). -// Only `crosshairs` carries fill-rule="evenodd" clip-rule="evenodd"; every -// other shape uses the SVG default (nonzero). `ex` is a single subpath (no hole). -// SPEC §4.1 / DECISIONS.md CORRECTION. +// Hat shape names/types AND the per-shape adjustment constants are imported from +// @cursorless/lib-common — NOT redefined here: +// - HatShape / HAT_SHAPES / HAT_NON_DEFAULT_SHAPES ← lib-common hatStyles.types +// - SHAPE_ADJUSTMENTS (defaultShapeAdjustments) / DEFAULT_HAT_HEIGHT_EM / +// DEFAULT_VERTICAL_OFFSET_EM / ShapeAdjustment ← lib-common shapeAdjustments +// (promoted there from app-vscode in this PR so headless consumers can +// import them instead of cloning). // -// WHY NOT IMPORTED (step 6 decision — Option B, kept-with-provenance): -// - SHAPE_PATHS `d=` strings: the canonical source is the 11 .svg files under -// resources/images/hats/, which app-vscode's VscodeHatRenderer.ts reads at -// RUNTIME (readFile of `${shape}.svg`) — there is no compile-time TS -// constant for them. Building an SVG-loader here or a TS path constant would -// be a second copy; the safest single-source would be a shared build step -// that reads the .svg files, which is out of scope. -// - HAT_SHAPES / HatShape / SHAPE_ADJUSTMENTS: these DO exist as clean TS -// constants upstream — HAT_SHAPES/HAT_NON_DEFAULT_SHAPES/HatShape in -// app-vscode/src/ide/vscode/hatStyles.types.ts and defaultShapeAdjustments -// (+ DEFAULT_HAT_HEIGHT_EM / DEFAULT_VERTICAL_OFFSET_EM) in -// app-vscode/src/ide/vscode/hats/shapeAdjustments.ts — but app-vscode -// exports only ./extension.cjs, so nothing outside it can import them. -// FOLLOW-UP to actually single-source: promote hatStyles.types.ts + -// shapeAdjustments.ts into @cursorless/lib-common and rewire the 5 app-vscode -// files that import them (VscodeHatRenderer, performPr1868ShapeUpdateInit, the -// two hatAdjustments scripts). Deferred: it touches the shipping extension's -// hat-rendering path and is the "risky app-vscode refactor" this task scoped -// out. The .svg `d=` strings would still need a separate build-time loader. +// Only the SVG `d=` path data below is local: its canonical source is the 11 +// .svg files under resources/images/hats/, which app-vscode's VscodeHatRenderer +// reads at RUNTIME (readFile) — there is no compile-time TS constant for them, +// so a headless renderer must carry the byte-for-byte paths (verified against +// the source SVGs 2026-06-08). SPEC §4.1. -export type HatShape = - | "default" - | "bolt" - | "curve" - | "fox" - | "frame" - | "play" - | "wing" - | "hole" - | "ex" - | "crosshairs" - | "eye"; +import type { HatShape } from "@cursorless/lib-common"; -export const HAT_SHAPES: HatShape[] = [ - "default", - "bolt", - "curve", - "fox", - "frame", - "play", - "wing", - "hole", - "ex", - "crosshairs", - "eye", -]; +export type { HatShape, HatNonDefaultShape } from "@cursorless/lib-common"; +export { HAT_SHAPES, HAT_NON_DEFAULT_SHAPES } from "@cursorless/lib-common"; +export { + DEFAULT_HAT_HEIGHT_EM, + DEFAULT_VERTICAL_OFFSET_EM, + defaultShapeAdjustments as SHAPE_ADJUSTMENTS, +} from "@cursorless/lib-common"; +export type { HatAdjustments as ShapeAdjustment } from "@cursorless/lib-common"; export interface ShapePath { d: string; @@ -57,7 +29,9 @@ export interface ShapePath { fillRule?: "evenodd"; } -// d= strings are byte-for-byte from the source SVGs. +// d= strings are byte-for-byte from resources/images/hats/{shape}.svg. +// Only `crosshairs` carries fill-rule="evenodd"; every other shape uses the +// SVG default (nonzero). `ex` is a single subpath (no hole). export const SHAPE_PATHS: Record<HatShape, ShapePath> = { default: { d: "M6 9C9.31371 9 12 6.98528 12 4.5C12 2.01472 9.31371 0 6 0C2.68629 0 0 2.01472 0 4.5C0 6.98528 2.68629 9 6 9Z", @@ -94,35 +68,3 @@ export const SHAPE_PATHS: Record<HatShape, ShapePath> = { d: "M12 4L6.5 0H5.5L0 4V5L5.5 9H6.5L12 5V4ZM6 7.5C6 7.5 4.5 6.5 4.5 4.5C4.5 2.5 6.01103 1.5 6 1.5C6 1.5 7.5 2.5 7.5 4.5C7.5 6.5 6 7.5 6 7.5Z", }, }; - -/** - * Per-shape adjustments, ported from - * cursorless/.../hats/shapeAdjustments.ts (verified 2026-06-08). - * sizeAdjustment is a PERCENT (e.g. -30 = -0.30 fraction). - * verticalOffset is a PERCENT applied /100 to em (e.g. -5 = -0.05em). - */ -export interface ShapeAdjustment { - /** percent */ - sizeAdjustment?: number; - /** percent → em/100 */ - verticalOffset?: number; - /** deferred (two-tone stroke, SPEC §7) */ - strokeFactor?: number; -} - -export const SHAPE_ADJUSTMENTS: Record<HatShape, ShapeAdjustment> = { - default: { sizeAdjustment: -30 }, - ex: { sizeAdjustment: -12.5 }, - fox: { sizeAdjustment: -5 }, - wing: { sizeAdjustment: -2.5 }, - hole: { strokeFactor: 0.7 }, - frame: { sizeAdjustment: -20 }, - curve: { verticalOffset: -5 }, - eye: {}, - play: {}, - bolt: {}, - crosshairs: {}, -}; - -export const DEFAULT_HAT_HEIGHT_EM = 0.36; -export const DEFAULT_VERTICAL_OFFSET_EM = 0.05; diff --git a/packages/command-visualizer/src/fixture-extract.ts b/packages/command-visualizer/src/fixture-extract.ts index 9b26a0098d..2d79913dce 100644 --- a/packages/command-visualizer/src/fixture-extract.ts +++ b/packages/command-visualizer/src/fixture-extract.ts @@ -64,7 +64,7 @@ export function parseMarks(marksObj: Obj | null): MarkInfo[] { } const colorRaw = key.slice(0, dot); const grapheme = key.slice(dot + 1); - const color = (HAT_COLORS as string[]).includes(colorRaw) + const color = (HAT_COLORS as readonly string[]).includes(colorRaw) ? (colorRaw as HatColor) : ("default" as HatColor); out.push({ From 0ff300cc098bb317deedd9f5ae3b5319cb9fee66 Mon Sep 17 00:00:00 2001 From: Trillium Smith <trillium@trilliumsmith.com> Date: Tue, 7 Jul 2026 18:25:11 -0700 Subject: [PATCH 15/53] fix(command-visualizer): escape quotes in serialize.ts esc() (CodeQL) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The duplicate esc() in serialize.ts escaped only & < > — CodeRabbit flagged it as needing the same quote escaping already applied to serialize-cascade.ts. Now also escapes " and ' so interpolated strings cannot break out of a quoted HTML attribute context. --- packages/command-visualizer/src/serialize.ts | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/packages/command-visualizer/src/serialize.ts b/packages/command-visualizer/src/serialize.ts index c84da78980..1c894c71a3 100644 --- a/packages/command-visualizer/src/serialize.ts +++ b/packages/command-visualizer/src/serialize.ts @@ -22,8 +22,17 @@ export interface EditorState { selections?: Range[]; } +// Escapes text content AND quoted-attribute contexts: & < > plus both quote +// chars, so interpolated strings can never break out of an attribute value. +// Mirrors esc() in serialize-cascade.ts (CodeQL: incomplete attribute +// sanitization requires the quote escapes too). function esc(s: string): string { - return s.replace(/&/g, "&").replace(/</g, "<").replace(/>/g, ">"); + return s + .replace(/&/g, "&") + .replace(/</g, "<") + .replace(/>/g, ">") + .replace(/"/g, """) + .replace(/'/g, "'"); } /** Is a given char index on a given line inside any selection range? */ From 62927fdcef080010d9bd966073be3af4a45f700d Mon Sep 17 00:00:00 2001 From: Trillium Smith <trillium@trilliumsmith.com> Date: Tue, 7 Jul 2026 18:25:26 -0700 Subject: [PATCH 16/53] feat(lib-common): promote hat color/shape vocabulary from app-vscode Moves HAT_COLORS / HAT_SHAPES / HAT_NON_DEFAULT_SHAPES and the HatColor / HatShape / HatNonDefaultShape / VscodeHatStyleName types out of app-vscode into lib-common's hatStyles.types (which previously held only the HatStyleName stub), so non-VS-Code consumers (e.g. @cursorless/command-visualizer) can import the vocabulary instead of cloning it. app-vscode's hatStyles.types.ts becomes a backward-compatible re-export shim, so its ~10 consumers (VscodeHats, VscodeHatRenderer, getStyleName, keyboard/*, hatAdjustments scripts, ...) are unchanged. No behavior change. --- .../src/ide/vscode/hatStyles.types.ts | 46 ++++++------------- .../src/ide/types/hatStyles.types.ts | 33 +++++++++++++ 2 files changed, 48 insertions(+), 31 deletions(-) diff --git a/packages/app-vscode/src/ide/vscode/hatStyles.types.ts b/packages/app-vscode/src/ide/vscode/hatStyles.types.ts index 9d19dd8f93..5064d3dc97 100644 --- a/packages/app-vscode/src/ide/vscode/hatStyles.types.ts +++ b/packages/app-vscode/src/ide/vscode/hatStyles.types.ts @@ -1,32 +1,16 @@ -export const HAT_COLORS = [ - "default", - "blue", - "green", - "red", - "pink", - "yellow", - "userColor1", - "userColor2", - "userColor3", - "userColor4", -] as const; +// The hat color/shape vocabulary was promoted to @cursorless/lib-common so +// non-VS-Code consumers (e.g. @cursorless/command-visualizer) can import it +// without a clone. This file is a backward-compatible re-export shim so the +// existing app-vscode consumers keep importing from their original path. -export const HAT_NON_DEFAULT_SHAPES = [ - "bolt", - "curve", - "fox", - "frame", - "play", - "wing", - "hole", - "ex", - "crosshairs", - "eye", -] as const; - -export const HAT_SHAPES = ["default", ...HAT_NON_DEFAULT_SHAPES] as const; - -export type HatColor = (typeof HAT_COLORS)[number]; -export type HatShape = (typeof HAT_SHAPES)[number]; -export type HatNonDefaultShape = (typeof HAT_NON_DEFAULT_SHAPES)[number]; -export type VscodeHatStyleName = HatColor | `${HatColor}-${HatNonDefaultShape}`; +export type { + HatColor, + HatShape, + HatNonDefaultShape, + VscodeHatStyleName, +} from "@cursorless/lib-common"; +export { + HAT_COLORS, + HAT_NON_DEFAULT_SHAPES, + HAT_SHAPES, +} from "@cursorless/lib-common"; diff --git a/packages/lib-common/src/ide/types/hatStyles.types.ts b/packages/lib-common/src/ide/types/hatStyles.types.ts index 7f98d39c0a..cc742d7e32 100644 --- a/packages/lib-common/src/ide/types/hatStyles.types.ts +++ b/packages/lib-common/src/ide/types/hatStyles.types.ts @@ -1 +1,34 @@ +export const HAT_COLORS = [ + "default", + "blue", + "green", + "red", + "pink", + "yellow", + "userColor1", + "userColor2", + "userColor3", + "userColor4", +] as const; + +export const HAT_NON_DEFAULT_SHAPES = [ + "bolt", + "curve", + "fox", + "frame", + "play", + "wing", + "hole", + "ex", + "crosshairs", + "eye", +] as const; + +export const HAT_SHAPES = ["default", ...HAT_NON_DEFAULT_SHAPES] as const; + +export type HatColor = (typeof HAT_COLORS)[number]; +export type HatShape = (typeof HAT_SHAPES)[number]; +export type HatNonDefaultShape = (typeof HAT_NON_DEFAULT_SHAPES)[number]; +export type VscodeHatStyleName = HatColor | `${HatColor}-${HatNonDefaultShape}`; + export type HatStyleName = string; From 349f20afc0fce4628eb1d00e02e6cdd733c35395 Mon Sep 17 00:00:00 2001 From: Trillium Smith <trillium@trilliumsmith.com> Date: Tue, 7 Jul 2026 18:44:47 -0700 Subject: [PATCH 17/53] refactor(app-vscode): import hat vocabulary directly from lib-common MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Replaces the re-export shims (hatStyles.types.ts, hats/shapeAdjustments.ts) with direct imports from @cursorless/lib-common in every consumer, then DELETES the shim files. No indirection layer — the vocabulary and shape adjustments now have a single home in lib-common and every consumer imports from it directly. Consumers rewired: VscodeEnabledHatStyleManager, VscodeHatRenderer, VscodeHats, getStyleName, getHatThemeColors, performPr1868ShapeUpdateInit, scripts/hatAdjustments/{add,average}, keyboard/{TokenTypes, KeyboardCommandsTargeted,KeyboardCommandHandler}. No behavior change. --- .../vscode/VscodeEnabledHatStyleManager.ts | 11 +++++++--- .../src/ide/vscode/hatStyles.types.ts | 16 --------------- .../src/ide/vscode/hats/VscodeHatRenderer.ts | 20 ++++++++++--------- .../src/ide/vscode/hats/VscodeHats.ts | 2 +- .../src/ide/vscode/hats/getHatThemeColors.ts | 2 +- .../src/ide/vscode/hats/getStyleName.ts | 2 +- .../hats/performPr1868ShapeUpdateInit.ts | 6 ++++-- .../src/ide/vscode/hats/shapeAdjustments.ts | 15 -------------- .../src/keyboard/KeyboardCommandHandler.ts | 3 ++- .../src/keyboard/KeyboardCommandsTargeted.ts | 3 ++- .../app-vscode/src/keyboard/TokenTypes.ts | 3 ++- .../src/scripts/hatAdjustments/add.ts | 5 ++--- .../src/scripts/hatAdjustments/average.ts | 5 ++--- 13 files changed, 36 insertions(+), 57 deletions(-) delete mode 100644 packages/app-vscode/src/ide/vscode/hatStyles.types.ts delete mode 100644 packages/app-vscode/src/ide/vscode/hats/shapeAdjustments.ts diff --git a/packages/app-vscode/src/ide/vscode/VscodeEnabledHatStyleManager.ts b/packages/app-vscode/src/ide/vscode/VscodeEnabledHatStyleManager.ts index faf2054208..e4b84a6655 100644 --- a/packages/app-vscode/src/ide/vscode/VscodeEnabledHatStyleManager.ts +++ b/packages/app-vscode/src/ide/vscode/VscodeEnabledHatStyleManager.ts @@ -1,13 +1,18 @@ import { pickBy } from "lodash-es"; import vscode from "vscode"; import type { + HatColor, + HatShape, HatStyleInfo, HatStyleMap, Listener, + VscodeHatStyleName, +} from "@cursorless/lib-common"; +import { + HAT_COLORS, + HAT_NON_DEFAULT_SHAPES, + Notifier, } from "@cursorless/lib-common"; -import { Notifier } from "@cursorless/lib-common"; -import type { HatColor, HatShape, VscodeHatStyleName } from "./hatStyles.types"; -import { HAT_COLORS, HAT_NON_DEFAULT_SHAPES } from "./hatStyles.types"; export interface ExtendedHatStyleInfo extends HatStyleInfo { color: HatColor; diff --git a/packages/app-vscode/src/ide/vscode/hatStyles.types.ts b/packages/app-vscode/src/ide/vscode/hatStyles.types.ts deleted file mode 100644 index 5064d3dc97..0000000000 --- a/packages/app-vscode/src/ide/vscode/hatStyles.types.ts +++ /dev/null @@ -1,16 +0,0 @@ -// The hat color/shape vocabulary was promoted to @cursorless/lib-common so -// non-VS-Code consumers (e.g. @cursorless/command-visualizer) can import it -// without a clone. This file is a backward-compatible re-export shim so the -// existing app-vscode consumers keep importing from their original path. - -export type { - HatColor, - HatShape, - HatNonDefaultShape, - VscodeHatStyleName, -} from "@cursorless/lib-common"; -export { - HAT_COLORS, - HAT_NON_DEFAULT_SHAPES, - HAT_SHAPES, -} from "@cursorless/lib-common"; diff --git a/packages/app-vscode/src/ide/vscode/hats/VscodeHatRenderer.ts b/packages/app-vscode/src/ide/vscode/hats/VscodeHatRenderer.ts index 5116c5786b..9ab64732e0 100644 --- a/packages/app-vscode/src/ide/vscode/hats/VscodeHatRenderer.ts +++ b/packages/app-vscode/src/ide/vscode/hats/VscodeHatRenderer.ts @@ -3,15 +3,23 @@ import path from "node:path"; import { isEqual } from "lodash-es"; import vscode from "vscode"; import type { + HatShape, + IndividualHatAdjustmentMap, Listener, Messages, PathChangeListener, + VscodeHatStyleName, +} from "@cursorless/lib-common"; +import { + DEFAULT_HAT_HEIGHT_EM, + DEFAULT_VERTICAL_OFFSET_EM, + defaultShapeAdjustments, + getErrorMessage, + HAT_SHAPES, + Notifier, } from "@cursorless/lib-common"; -import { getErrorMessage, Notifier } from "@cursorless/lib-common"; import { walkFiles } from "@cursorless/lib-node-common"; import type { VscodeApi } from "@cursorless/lib-vscode-common"; -import type { HatShape, VscodeHatStyleName } from "../hatStyles.types"; -import { HAT_SHAPES } from "../hatStyles.types"; import { vscodeGetConfigurationString } from "../VscodeConfiguration"; import type { ExtendedHatStyleMap, @@ -20,12 +28,6 @@ import type { import type { FontMeasurements } from "./FontMeasurements"; import { getHatThemeColors } from "./getHatThemeColors"; import { performPr1868ShapeUpdateInit } from "./performPr1868ShapeUpdateInit"; -import type { IndividualHatAdjustmentMap } from "./shapeAdjustments"; -import { - DEFAULT_HAT_HEIGHT_EM, - DEFAULT_VERTICAL_OFFSET_EM, - defaultShapeAdjustments, -} from "./shapeAdjustments"; const CURSORLESS_HAT_SHAPES_SUFFIX = ".svg"; diff --git a/packages/app-vscode/src/ide/vscode/hats/VscodeHats.ts b/packages/app-vscode/src/ide/vscode/hats/VscodeHats.ts index 51f244f000..b79428e2b2 100644 --- a/packages/app-vscode/src/ide/vscode/hats/VscodeHats.ts +++ b/packages/app-vscode/src/ide/vscode/hats/VscodeHats.ts @@ -8,11 +8,11 @@ import type { Listener, Range, TextEditor, + VscodeHatStyleName, } from "@cursorless/lib-common"; import { Notifier } from "@cursorless/lib-common"; import type { VscodeApi } from "@cursorless/lib-vscode-common"; import { toVscodeRange } from "@cursorless/lib-vscode-common"; -import type { VscodeHatStyleName } from "../hatStyles.types"; import { VscodeEnabledHatStyleManager } from "../VscodeEnabledHatStyleManager"; import type { VscodeIDE } from "../VscodeIDE"; import type { VscodeTextEditor } from "../VscodeTextEditor"; diff --git a/packages/app-vscode/src/ide/vscode/hats/getHatThemeColors.ts b/packages/app-vscode/src/ide/vscode/hats/getHatThemeColors.ts index 24a57a2b3b..335530bafc 100644 --- a/packages/app-vscode/src/ide/vscode/hats/getHatThemeColors.ts +++ b/packages/app-vscode/src/ide/vscode/hats/getHatThemeColors.ts @@ -1,5 +1,5 @@ import vscode from "vscode"; -import type { HatColor } from "../hatStyles.types"; +import type { HatColor } from "@cursorless/lib-common"; interface OldDecorationColorSetting { dark: string; diff --git a/packages/app-vscode/src/ide/vscode/hats/getStyleName.ts b/packages/app-vscode/src/ide/vscode/hats/getStyleName.ts index 13e164d5f8..07f6670bcd 100644 --- a/packages/app-vscode/src/ide/vscode/hats/getStyleName.ts +++ b/packages/app-vscode/src/ide/vscode/hats/getStyleName.ts @@ -2,7 +2,7 @@ import type { HatColor, HatShape, VscodeHatStyleName, -} from "../hatStyles.types"; +} from "@cursorless/lib-common"; export function getStyleName( color: HatColor, diff --git a/packages/app-vscode/src/ide/vscode/hats/performPr1868ShapeUpdateInit.ts b/packages/app-vscode/src/ide/vscode/hats/performPr1868ShapeUpdateInit.ts index 570fe99a51..f624e0f1a4 100644 --- a/packages/app-vscode/src/ide/vscode/hats/performPr1868ShapeUpdateInit.ts +++ b/packages/app-vscode/src/ide/vscode/hats/performPr1868ShapeUpdateInit.ts @@ -1,9 +1,11 @@ import vscode from "vscode"; -import type { Messages } from "@cursorless/lib-common"; +import type { + IndividualHatAdjustmentMap, + Messages, +} from "@cursorless/lib-common"; import { showInfo } from "@cursorless/lib-common"; import type { VscodeApi } from "@cursorless/lib-vscode-common"; import type { ExtendedHatStyleMap } from "../VscodeEnabledHatStyleManager"; -import type { IndividualHatAdjustmentMap } from "./shapeAdjustments"; /** * We set this key in global state the first time they user gets the new shapes from #1868. We use this to diff --git a/packages/app-vscode/src/ide/vscode/hats/shapeAdjustments.ts b/packages/app-vscode/src/ide/vscode/hats/shapeAdjustments.ts deleted file mode 100644 index 8a2f9bc0f9..0000000000 --- a/packages/app-vscode/src/ide/vscode/hats/shapeAdjustments.ts +++ /dev/null @@ -1,15 +0,0 @@ -// Hat shape adjustments were promoted to @cursorless/lib-common so non-VS-Code -// consumers (e.g. @cursorless/command-visualizer) can import them without a -// clone. This file is a backward-compatible re-export shim so the existing -// app-vscode consumers (VscodeHatRenderer, performPr1868ShapeUpdateInit, the -// hatAdjustments scripts) keep importing from their original path unchanged. - -export type { - HatAdjustments, - IndividualHatAdjustmentMap, -} from "@cursorless/lib-common"; -export { - DEFAULT_HAT_HEIGHT_EM, - DEFAULT_VERTICAL_OFFSET_EM, - defaultShapeAdjustments, -} from "@cursorless/lib-common"; diff --git a/packages/app-vscode/src/keyboard/KeyboardCommandHandler.ts b/packages/app-vscode/src/keyboard/KeyboardCommandHandler.ts index 0c920e32dc..a755007fa7 100644 --- a/packages/app-vscode/src/keyboard/KeyboardCommandHandler.ts +++ b/packages/app-vscode/src/keyboard/KeyboardCommandHandler.ts @@ -1,12 +1,13 @@ import { isString } from "lodash-es"; import vscode from "vscode"; import type { + HatColor, + HatShape, Modifier, PartialMark, SurroundingPairName, } from "@cursorless/lib-common"; import { surroundingPairsDelimiters } from "@cursorless/lib-engine"; -import type { HatColor, HatShape } from "../ide/vscode/hatStyles.types"; import type { SimpleKeyboardActionDescriptor, SpecificKeyboardActionDescriptor, diff --git a/packages/app-vscode/src/keyboard/KeyboardCommandsTargeted.ts b/packages/app-vscode/src/keyboard/KeyboardCommandsTargeted.ts index 092d7bf0e4..16bfa1d47b 100644 --- a/packages/app-vscode/src/keyboard/KeyboardCommandsTargeted.ts +++ b/packages/app-vscode/src/keyboard/KeyboardCommandsTargeted.ts @@ -1,6 +1,8 @@ import vscode from "vscode"; import type { ActionDescriptor, + HatColor, + HatShape, Modifier, PartialMark, PartialPrimitiveTargetDescriptor, @@ -10,7 +12,6 @@ import type { import { LATEST_VERSION } from "@cursorless/lib-common"; import { runCursorlessCommand } from "@cursorless/lib-vscode-common"; import { getStyleName } from "../ide/vscode/hats/getStyleName"; -import type { HatColor, HatShape } from "../ide/vscode/hatStyles.types"; import type { SimpleKeyboardActionDescriptor } from "./KeyboardActionType"; import type { KeyboardCommandsModal } from "./KeyboardCommandsModal"; import type { KeyboardHandler } from "./KeyboardHandler"; diff --git a/packages/app-vscode/src/keyboard/TokenTypes.ts b/packages/app-vscode/src/keyboard/TokenTypes.ts index 31a7c05a8c..fa23cfb7a2 100644 --- a/packages/app-vscode/src/keyboard/TokenTypes.ts +++ b/packages/app-vscode/src/keyboard/TokenTypes.ts @@ -1,8 +1,9 @@ import type { + HatColor, + HatShape, SimpleScopeTypeType, SurroundingPairName, } from "@cursorless/lib-common"; -import type { HatColor, HatShape } from "../ide/vscode/hatStyles.types"; import type { PolymorphicKeyboardActionDescriptor, SimpleKeyboardActionDescriptor, diff --git a/packages/app-vscode/src/scripts/hatAdjustments/add.ts b/packages/app-vscode/src/scripts/hatAdjustments/add.ts index ac32fcc442..5192ab729f 100644 --- a/packages/app-vscode/src/scripts/hatAdjustments/add.ts +++ b/packages/app-vscode/src/scripts/hatAdjustments/add.ts @@ -5,9 +5,8 @@ import { sum } from "lodash-es"; import type { HatAdjustments, IndividualHatAdjustmentMap, -} from "../../ide/vscode/hats/shapeAdjustments"; -import { defaultShapeAdjustments } from "../../ide/vscode/hats/shapeAdjustments"; -import { HAT_SHAPES } from "../../ide/vscode/hatStyles.types"; +} from "@cursorless/lib-common"; +import { defaultShapeAdjustments, HAT_SHAPES } from "@cursorless/lib-common"; import { postProcessValue } from "./lib"; /** diff --git a/packages/app-vscode/src/scripts/hatAdjustments/average.ts b/packages/app-vscode/src/scripts/hatAdjustments/average.ts index 0016ca807b..6eebd3de50 100644 --- a/packages/app-vscode/src/scripts/hatAdjustments/average.ts +++ b/packages/app-vscode/src/scripts/hatAdjustments/average.ts @@ -4,9 +4,8 @@ import type { HatAdjustments, IndividualHatAdjustmentMap, -} from "../../ide/vscode/hats/shapeAdjustments"; -import { defaultShapeAdjustments } from "../../ide/vscode/hats/shapeAdjustments"; -import { HAT_SHAPES } from "../../ide/vscode/hatStyles.types"; +} from "@cursorless/lib-common"; +import { defaultShapeAdjustments, HAT_SHAPES } from "@cursorless/lib-common"; import { postProcessValue } from "./lib"; /** From f77df276c9164b7d8bd1a4ed9b98e1468f7b7686 Mon Sep 17 00:00:00 2001 From: Trillium Smith <trillium@trilliumsmith.com> Date: Tue, 7 Jul 2026 18:45:02 -0700 Subject: [PATCH 18/53] refactor(command-visualizer): import hat vocabulary directly from lib-common Stops re-exporting the cursorless hat vocabulary through data/colors.ts and data/shapes.ts. Consumers now import HatColor/HatShape/HAT_COLORS/HAT_SHAPES and the shape-adjustment constants straight from @cursorless/lib-common. data/colors.ts and data/shapes.ts keep ONLY the genuinely command-visualizer- local data that has no importable TS home: COLOR_MATRIX/EDITOR_CHROME (theme hexes from package.json config defaults) and SHAPE_PATHS (SVG d= strings from resources/*.svg). No re-export indirection. --- packages/command-visualizer/src/columns.ts | 3 +- packages/command-visualizer/src/css.ts | 7 +++-- .../command-visualizer/src/data/colors.ts | 21 ++++++------- .../command-visualizer/src/data/shapes.ts | 30 ++++++------------- .../command-visualizer/src/fixture-extract.ts | 5 ++-- .../command-visualizer/src/hat-allocator.ts | 6 ++-- packages/command-visualizer/src/pipeline.ts | 4 +-- packages/command-visualizer/src/symbols.ts | 3 +- 8 files changed, 31 insertions(+), 48 deletions(-) diff --git a/packages/command-visualizer/src/columns.ts b/packages/command-visualizer/src/columns.ts index a60e3ecbe9..2d714fea29 100644 --- a/packages/command-visualizer/src/columns.ts +++ b/packages/command-visualizer/src/columns.ts @@ -6,9 +6,8 @@ // - Tab → next tabSize stop (SPEC §2.2). // - East-Asian Wide/Fullwidth glyph = 2 columns (SPEC §2.3). +import type { HatColor, HatShape } from "@cursorless/lib-common"; import { GRAPHEME_SPLIT_REGEX } from "@cursorless/lib-engine"; -import type { HatColor } from "./data/colors"; -import type { HatShape } from "./data/shapes"; // Cursorless's grapheme splitter regex, imported from @cursorless/lib-engine // (no clone): a base letter + its combining marks is ONE grapheme; diff --git a/packages/command-visualizer/src/css.ts b/packages/command-visualizer/src/css.ts index 0466651dbe..d3360fee91 100644 --- a/packages/command-visualizer/src/css.ts +++ b/packages/command-visualizer/src/css.ts @@ -1,13 +1,14 @@ // CSS contract — SPEC §4. Generated from the single-sourced data so color + // adjustment values never drift. No render-time JS; CSS does 100% of visual work. -import { COLOR_MATRIX, EDITOR_CHROME, HAT_COLORS } from "./data/colors"; import { DEFAULT_HAT_HEIGHT_EM, DEFAULT_VERTICAL_OFFSET_EM, + defaultShapeAdjustments as SHAPE_ADJUSTMENTS, + HAT_COLORS, HAT_SHAPES, - SHAPE_ADJUSTMENTS, -} from "./data/shapes"; +} from "@cursorless/lib-common"; +import { COLOR_MATRIX, EDITOR_CHROME } from "./data/colors"; function shapeAdjustmentRules(): string { const lines: string[] = [ diff --git a/packages/command-visualizer/src/data/colors.ts b/packages/command-visualizer/src/data/colors.ts index 3c9e36a5f6..ede31d9818 100644 --- a/packages/command-visualizer/src/data/colors.ts +++ b/packages/command-visualizer/src/data/colors.ts @@ -1,15 +1,12 @@ -// Hat color names/types are imported from @cursorless/lib-common (the shared -// hatStyles.types) — NOT redefined here. Only the theme hex MATRIX below is -// local, because it has no importable TS home: the hexes are declared in -// app-vscode's package.json as VS Code setting DEFAULTS -// (contributes.configuration "cursorless.colors.dark" / ".light") and read at -// runtime from VS Code configuration — there is no compile-time constant for -// them anywhere in the tree, so mirroring the defaults here (with provenance) -// is the faithful rendering for a headless renderer. Values verified against -// app-vscode/package.json 2026-06-08. SPEC §4.4. - -export type { HatColor } from "@cursorless/lib-common"; -export { HAT_COLORS } from "@cursorless/lib-common"; +// COLOR_MATRIX / EDITOR_CHROME are the only command-visualizer-local color data. +// The theme hexes have no importable TS home: they're declared in +// app-vscode/package.json as VS Code setting defaults (\`cursorless.colors.dark\`/ +// \`.light\`) and read at runtime from VS Code config — there's no compile-time +// constant to import, so a headless renderer mirrors the defaults here (verified +// against app-vscode/package.json 2026-06-08). SPEC §4.4. +// +// The hat color VOCABULARY (\`HatColor\`, \`HAT_COLORS\`) is NOT re-exported here — +// consumers import it directly from @cursorless/lib-common. import type { HatColor } from "@cursorless/lib-common"; diff --git a/packages/command-visualizer/src/data/shapes.ts b/packages/command-visualizer/src/data/shapes.ts index 93bae18184..c0419404bc 100644 --- a/packages/command-visualizer/src/data/shapes.ts +++ b/packages/command-visualizer/src/data/shapes.ts @@ -1,28 +1,16 @@ -// Hat shape names/types AND the per-shape adjustment constants are imported from -// @cursorless/lib-common — NOT redefined here: -// - HatShape / HAT_SHAPES / HAT_NON_DEFAULT_SHAPES ← lib-common hatStyles.types -// - SHAPE_ADJUSTMENTS (defaultShapeAdjustments) / DEFAULT_HAT_HEIGHT_EM / -// DEFAULT_VERTICAL_OFFSET_EM / ShapeAdjustment ← lib-common shapeAdjustments -// (promoted there from app-vscode in this PR so headless consumers can -// import them instead of cloning). +// SHAPE_PATHS is the only command-visualizer-local shape data. The SVG \`d=\` path +// strings have no importable TS home: their canonical source is the 11 .svg files +// under resources/images/hats/, which app-vscode's VscodeHatRenderer reads at +// runtime — there's no compile-time constant, so a headless renderer carries the +// byte-for-byte paths here (verified against the source SVGs 2026-06-08). SPEC §4.1. // -// Only the SVG `d=` path data below is local: its canonical source is the 11 -// .svg files under resources/images/hats/, which app-vscode's VscodeHatRenderer -// reads at RUNTIME (readFile) — there is no compile-time TS constant for them, -// so a headless renderer must carry the byte-for-byte paths (verified against -// the source SVGs 2026-06-08). SPEC §4.1. +// The shape VOCABULARY (\`HatShape\`, \`HAT_SHAPES\`, ...) and the shape-adjustment +// constants (\`defaultShapeAdjustments\`, \`DEFAULT_HAT_HEIGHT_EM\`, +// \`DEFAULT_VERTICAL_OFFSET_EM\`) are NOT re-exported here — consumers import them +// directly from @cursorless/lib-common. import type { HatShape } from "@cursorless/lib-common"; -export type { HatShape, HatNonDefaultShape } from "@cursorless/lib-common"; -export { HAT_SHAPES, HAT_NON_DEFAULT_SHAPES } from "@cursorless/lib-common"; -export { - DEFAULT_HAT_HEIGHT_EM, - DEFAULT_VERTICAL_OFFSET_EM, - defaultShapeAdjustments as SHAPE_ADJUSTMENTS, -} from "@cursorless/lib-common"; -export type { HatAdjustments as ShapeAdjustment } from "@cursorless/lib-common"; - export interface ShapePath { d: string; /** Only set for crosshairs. */ diff --git a/packages/command-visualizer/src/fixture-extract.ts b/packages/command-visualizer/src/fixture-extract.ts index 2d79913dce..4f14f372fb 100644 --- a/packages/command-visualizer/src/fixture-extract.ts +++ b/packages/command-visualizer/src/fixture-extract.ts @@ -4,10 +4,9 @@ import type { YamlValue } from "./fixture-yaml"; import { tokenizeDoc } from "./tokenize"; +import type { HatColor, HatShape } from "@cursorless/lib-common"; +import { HAT_COLORS } from "@cursorless/lib-common"; import type { Line, Token, InputHat } from "./columns"; -import type { HatColor } from "./data/colors"; -import type { HatShape } from "./data/shapes"; -import { HAT_COLORS } from "./data/colors"; import type { GeneralizedRange } from "./frame-state"; import type { Pos, Range } from "./serialize"; import { allocateHats } from "./hat-allocator"; diff --git a/packages/command-visualizer/src/hat-allocator.ts b/packages/command-visualizer/src/hat-allocator.ts index cb95012106..0fc9e190f6 100644 --- a/packages/command-visualizer/src/hat-allocator.ts +++ b/packages/command-visualizer/src/hat-allocator.ts @@ -36,11 +36,9 @@ import { StandaloneGraphemeSplitter, type HatStyleMap, } from "./vendor/allocate-hats/index"; +import type { HatColor, HatShape } from "@cursorless/lib-common"; +import { HAT_COLORS, HAT_SHAPES } from "@cursorless/lib-common"; import type { Line } from "./columns"; -import type { HatColor } from "./data/colors"; -import type { HatShape } from "./data/shapes"; -import { HAT_COLORS } from "./data/colors"; -import { HAT_SHAPES } from "./data/shapes"; import type { Pos } from "./serialize"; import { segmentLines } from "./word-segments"; diff --git a/packages/command-visualizer/src/pipeline.ts b/packages/command-visualizer/src/pipeline.ts index 2239b98350..8908495e80 100644 --- a/packages/command-visualizer/src/pipeline.ts +++ b/packages/command-visualizer/src/pipeline.ts @@ -4,9 +4,9 @@ // is unchanged downstream. import { readFileSync } from "node:fs"; +import type { HatColor, HatShape } from "@cursorless/lib-common"; import { parseFixtureYaml } from "./fixture-yaml"; -import type { HatColor, Theme } from "./data/colors"; -import type { HatShape } from "./data/shapes"; +import type { Theme } from "./data/colors"; import type { CascadeState, Frame, diff --git a/packages/command-visualizer/src/symbols.ts b/packages/command-visualizer/src/symbols.ts index 588cb914d1..e4191d6944 100644 --- a/packages/command-visualizer/src/symbols.ts +++ b/packages/command-visualizer/src/symbols.ts @@ -3,7 +3,8 @@ // Each path + per-shape fill-rule is verbatim from source (src/data/shapes.ts); // fill="currentColor" so a hat is tinted by CSS `color` (D4). -import { HAT_SHAPES, SHAPE_PATHS } from "./data/shapes"; +import { HAT_SHAPES } from "@cursorless/lib-common"; +import { SHAPE_PATHS } from "./data/shapes"; export function symbolSheet(): string { const symbols = HAT_SHAPES.map((shape) => { From c9c7b34d215b8505064fb8a36f1987747666ec5a Mon Sep 17 00:00:00 2001 From: Trillium Smith <trillium@trilliumsmith.com> Date: Tue, 7 Jul 2026 20:56:31 -0700 Subject: [PATCH 19/53] refactor(command-visualizer): consolidate HTML helpers, drop unused dep MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit fallow surfaced esc() duplicated across 4 serializers with INCONSISTENT escaping — svg-wrap.ts escaped no quotes (latent attribute-injection gap), jumbotron.ts escaped " but not ', serialize/serialize-cascade escaped both. Extracted one shared src/html.ts (esc + themeBackground + captionHtml); all four serializers now import it, so the CodeQL-safe escaping can't drift again. Also collapses the duplicated theme-bg + caption block (serialize-cascade <-> svg-wrap). Removes @cursorless/lib-node-common from dependencies — fallow flagged it as listed-but-never-imported (only referenced in comments). fallow dupes: 4 clone groups -> 2 (the remaining two are the pinned vendored allocation algorithm, HatMetrics + getTokenComparator). --- packages/command-visualizer/package.json | 1 - packages/command-visualizer/src/html.ts | 47 +++++++++++++++++++ packages/command-visualizer/src/jumbotron.ts | 9 +--- .../src/serialize-cascade.ts | 32 ++----------- packages/command-visualizer/src/serialize.ts | 14 +----- packages/command-visualizer/src/svg-wrap.ts | 19 ++------ 6 files changed, 55 insertions(+), 67 deletions(-) create mode 100644 packages/command-visualizer/src/html.ts diff --git a/packages/command-visualizer/package.json b/packages/command-visualizer/package.json index bbc466c321..6d702d1b55 100644 --- a/packages/command-visualizer/package.json +++ b/packages/command-visualizer/package.json @@ -22,7 +22,6 @@ "dependencies": { "@cursorless/lib-common": "workspace:*", "@cursorless/lib-engine": "workspace:*", - "@cursorless/lib-node-common": "workspace:*", "js-yaml": "^5.2.1" }, "devDependencies": { diff --git a/packages/command-visualizer/src/html.ts b/packages/command-visualizer/src/html.ts new file mode 100644 index 0000000000..1d4f97a93e --- /dev/null +++ b/packages/command-visualizer/src/html.ts @@ -0,0 +1,47 @@ +// Shared HTML helpers for the serializers (serialize, serialize-cascade, +// svg-wrap, jumbotron). Single home for the attribute-safe escaper and the +// caption block so each serializer doesn't re-derive them (and can't drift out +// of sync — three of the four copies had differing quote-escaping before this +// was consolidated). + +import type { CascadeState } from "./frame-state"; + +/** + * HTML escaper safe for BOTH text content AND quoted-attribute contexts. + * `&` is escaped first (so it can't double-escape the entities below), then the + * tag delimiters, then BOTH quote characters. Escaping the quotes is what closes + * the CodeQL "incomplete HTML attribute sanitization" finding: fixture / + * spoken-form strings are interpolated into double-quoted attributes + * (data-fixture="…", data-spoken-form="…") and an unescaped `"` would break out + * of the attribute. Over-escaping quotes in text content is harmless — + * " / ' render as " / '. + */ +export function esc(s: string): string { + return s + .replace(/&/g, "&") + .replace(/</g, "<") + .replace(/>/g, ">") + .replace(/"/g, """) + .replace(/'/g, "'"); +} + +/** Editor-surface page background for a theme (delivered SVG / standalone doc). */ +export function themeBackground(theme: "dark" | "light"): string { + return theme === "dark" ? "#141414" : "#e8e8e8"; +} + +/** + * The `.cl-caption` block built from a state's meta (spoken form · action · + * fixture). Returns "" when there is no meta. Shared by the cascade document + * and the delivered-SVG wrapper. + */ +export function captionHtml(meta: CascadeState["meta"]): string { + if (!meta) { + return ""; + } + return `<div class="cl-caption">${esc( + [meta.spokenForm && `"${meta.spokenForm}"`, meta.action, meta.fixture] + .filter(Boolean) + .join(" · "), + )}</div>`; +} diff --git a/packages/command-visualizer/src/jumbotron.ts b/packages/command-visualizer/src/jumbotron.ts index edc503e212..eb2edeb64e 100644 --- a/packages/command-visualizer/src/jumbotron.ts +++ b/packages/command-visualizer/src/jumbotron.ts @@ -22,17 +22,10 @@ import type { CascadeState } from "./frame-state"; import { MS_PER_STATE } from "./data/decorations"; import { frameDurMs, timelineOf } from "./timeline"; +import { esc } from "./html"; const NL = String.fromCharCode(10); -function esc(s: string): string { - return s - .replace(/&/g, "&") - .replace(/</g, "<") - .replace(/>/g, ">") - .replace(/"/g, """); -} - /** Commands carried by the frames, in order. */ function frameCommands(state: CascadeState): string[] { return state.frames diff --git a/packages/command-visualizer/src/serialize-cascade.ts b/packages/command-visualizer/src/serialize-cascade.ts index 240e00768a..e7c1c564b1 100644 --- a/packages/command-visualizer/src/serialize-cascade.ts +++ b/packages/command-visualizer/src/serialize-cascade.ts @@ -13,23 +13,7 @@ import type { CascadeState, Frame } from "./frame-state"; import { resolveFrameOverlays, type LineOverlay } from "./overlays"; import { HIGHLIGHT_STYLES, MS_PER_STATE } from "./data/decorations"; import { timelineOf } from "./timeline"; - -// HTML escaper safe for BOTH text content AND quoted-attribute contexts. -// `&` is escaped first (so it can't double-escape the entities below), then the -// tag delimiters, then BOTH quote characters. Escaping the quotes is what -// closes the CodeQL "incomplete HTML attribute sanitization" finding: fixture / -// spoken-form strings are interpolated into double-quoted attributes -// (data-fixture="…", data-spoken-form="…", <title>…), and an unescaped `"` -// would break out of the attribute. Over-escaping quotes in text content is -// harmless — " / ' render as " / '. -function esc(s: string): string { - return s - .replace(/&/g, "&") - .replace(/</g, "<") - .replace(/>/g, ">") - .replace(/"/g, """) - .replace(/'/g, "'"); -} +import { captionHtml, esc, themeBackground } from "./html"; function charToCol(cols: Column[], charIndex: number): number { for (const c of cols) { @@ -197,18 +181,8 @@ export function serializeCascadeDocument( title = "cursorless cascade", opts: CascadeRenderOptions = {}, ): string { - const bg = state.theme === "dark" ? "#141414" : "#e8e8e8"; - const caption = state.meta - ? `<div class="cl-caption">${esc( - [ - state.meta.spokenForm && `"${state.meta.spokenForm}"`, - state.meta.action, - state.meta.fixture, - ] - .filter(Boolean) - .join(" · "), - )}</div>` - : ""; + const bg = themeBackground(state.theme); + const caption = captionHtml(state.meta); return `<!doctype html> <html> <head> diff --git a/packages/command-visualizer/src/serialize.ts b/packages/command-visualizer/src/serialize.ts index 1c894c71a3..136b57f5e0 100644 --- a/packages/command-visualizer/src/serialize.ts +++ b/packages/command-visualizer/src/serialize.ts @@ -4,6 +4,7 @@ import type { Theme } from "./data/colors"; import { type Column, type Line, expandColumns, lineWidth } from "./columns"; import { styleSheet } from "./css"; import { symbolSheet } from "./symbols"; +import { esc } from "./html"; export interface Pos { line: number; @@ -22,19 +23,6 @@ export interface EditorState { selections?: Range[]; } -// Escapes text content AND quoted-attribute contexts: & < > plus both quote -// chars, so interpolated strings can never break out of an attribute value. -// Mirrors esc() in serialize-cascade.ts (CodeQL: incomplete attribute -// sanitization requires the quote escapes too). -function esc(s: string): string { - return s - .replace(/&/g, "&") - .replace(/</g, "<") - .replace(/>/g, ">") - .replace(/"/g, """) - .replace(/'/g, "'"); -} - /** Is a given char index on a given line inside any selection range? */ function inAnySelection( lineIdx: number, diff --git a/packages/command-visualizer/src/svg-wrap.ts b/packages/command-visualizer/src/svg-wrap.ts index a2b75aa5f0..3eb51c84e8 100644 --- a/packages/command-visualizer/src/svg-wrap.ts +++ b/packages/command-visualizer/src/svg-wrap.ts @@ -13,6 +13,7 @@ import { serializeCascade } from "./serialize-cascade"; import { jumbotronCss, serializeJumbotron } from "./jumbotron"; import { styleSheet } from "./css"; import { cascadeStyleSheet, cascadeThemeBridge } from "./css-cascade"; +import { captionHtml, themeBackground } from "./html"; const FONT_PX = 18; // .cl-code font-size (css-cascade.ts) const LINE_HEIGHT = 1.35; // --code-line-height default @@ -48,10 +49,6 @@ function extent(state: CascadeState): { cols: number; rows: number } { return { cols, rows }; } -function esc(s: string): string { - return s.replace(/&/g, "&").replace(/</g, "<").replace(/>/g, ">"); -} - /** * Build the standalone animated SVG for a cascade state. * @@ -111,18 +108,8 @@ export function wrapCascadeSvg( barWidthPx: width - PAD_PX * 2, }); - const bg = state.theme === "dark" ? "#141414" : "#e8e8e8"; - const caption = state.meta - ? `<div class="cl-caption">${esc( - [ - state.meta.spokenForm && `"${state.meta.spokenForm}"`, - state.meta.action, - state.meta.fixture, - ] - .filter(Boolean) - .join(" · "), - )}</div>` - : ""; + const bg = themeBackground(state.theme); + const caption = captionHtml(state.meta); // The cascade stylesheet ships animation-play-state: paused (the GIF // harness seeks frames via WAAPI). A delivered SVG has no harness — for // multi-frame cascades, un-pause and loop forever (readme-embed behavior). From 2f3920a77ca25f8412414e64538e59f6869e543c Mon Sep 17 00:00:00 2001 From: Trillium Smith <trillium@trilliumsmith.com> Date: Tue, 7 Jul 2026 21:01:25 -0700 Subject: [PATCH 20/53] test(command-visualizer): add unit tests for the deterministic core MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The package shipped with ZERO tests — the verification harness the source comments reference (verify-allocation.ts, oracle screenshots) was never migrated from the standalone repo. Adds colocated mocha .test.ts files (auto-discovered by packages/test-runner's unit glob, node:assert/strict, matching the lib-engine idiom) covering the pure, deterministic functions — especially the review-fix behaviors: - html.test.ts: esc() escapes all 5 chars & <> " ', &-first ordering, attribute-breakout payload neutralized (CodeQL regression guard); captionHtml empty/partial/full meta + markup-injection escaping. - fixture-yaml.test.ts: parseFixtureYaml blank/whitespace -> {} (R3), mapping vs scalar vs sequence, literal block scalar byte-fidelity. - chain.test.ts: chainCascades empty-input throw w/ stepIndex 0 (R6), single-step fixtureLabel propagation preserving other meta (R7). Wires @types/mocha + @types/node and types:[node,mocha] in tsconfig, mirroring lib-engine. Typechecked against lib shims; full run needs the networked install (same wall as the lockfile). --- packages/command-visualizer/package.json | 4 +- packages/command-visualizer/src/chain.test.ts | 50 ++++++++++++++ .../src/fixture-yaml.test.ts | 32 +++++++++ packages/command-visualizer/src/html.test.ts | 69 +++++++++++++++++++ packages/command-visualizer/tsconfig.json | 3 +- 5 files changed, 156 insertions(+), 2 deletions(-) create mode 100644 packages/command-visualizer/src/chain.test.ts create mode 100644 packages/command-visualizer/src/fixture-yaml.test.ts create mode 100644 packages/command-visualizer/src/html.test.ts diff --git a/packages/command-visualizer/package.json b/packages/command-visualizer/package.json index 6d702d1b55..e91750ee8d 100644 --- a/packages/command-visualizer/package.json +++ b/packages/command-visualizer/package.json @@ -25,6 +25,8 @@ "js-yaml": "^5.2.1" }, "devDependencies": { - "@types/js-yaml": "^4.0.9" + "@types/js-yaml": "^4.0.9", + "@types/mocha": "^10.0.10", + "@types/node": "^24.13.2" } } diff --git a/packages/command-visualizer/src/chain.test.ts b/packages/command-visualizer/src/chain.test.ts new file mode 100644 index 0000000000..3adf9601d1 --- /dev/null +++ b/packages/command-visualizer/src/chain.test.ts @@ -0,0 +1,50 @@ +import assert from "node:assert/strict"; +import { chainCascades, ChainContinuityError } from "./chain"; +import type { CascadeState, Frame } from "./frame-state"; + +function beforeFrame(): Frame { + return { + role: "before", + lines: [], + cursors: [], + selections: [], + decorations: [], + }; +} + +function singleStepState(meta: CascadeState["meta"]): CascadeState { + return { theme: "dark", tabSize: 2, meta, frames: [beforeFrame()] }; +} + +suite("command-visualizer/chain", () => { + suite("chainCascades", () => { + test("throws ChainContinuityError with step index 0 on empty input", () => { + let caught: unknown; + try { + chainCascades([], "recorded/x.yml"); + } catch (err) { + caught = err; + } + assert.ok(caught instanceof ChainContinuityError); + assert.equal((caught as ChainContinuityError).stepIndex, 0); + }); + + test("single-step: applies fixtureLabel while preserving other meta", () => { + const state = singleStepState({ + spokenForm: "chuck", + action: "remove", + fixture: "per-step.yml", + }); + const result = chainCascades([state], "recorded/chuck.yml"); + assert.equal(result.meta?.fixture, "recorded/chuck.yml"); + assert.equal(result.meta?.spokenForm, "chuck"); + assert.equal(result.meta?.action, "remove"); + }); + + test("single-step: sets fixtureLabel even when the state has no meta", () => { + const state = singleStepState(undefined); + const result = chainCascades([state], "recorded/only.yml"); + assert.equal(result.meta?.fixture, "recorded/only.yml"); + }); + }); +}); diff --git a/packages/command-visualizer/src/fixture-yaml.test.ts b/packages/command-visualizer/src/fixture-yaml.test.ts new file mode 100644 index 0000000000..212c9d9d59 --- /dev/null +++ b/packages/command-visualizer/src/fixture-yaml.test.ts @@ -0,0 +1,32 @@ +import assert from "node:assert/strict"; +import { parseFixtureYaml } from "./fixture-yaml"; + +suite("command-visualizer/fixture-yaml", () => { + suite("parseFixtureYaml", () => { + test("returns {} for an empty string (js-yaml 5.x throws otherwise)", () => { + assert.deepEqual(parseFixtureYaml(""), {}); + }); + + test("returns {} for whitespace-only input", () => { + assert.deepEqual(parseFixtureYaml(" \n\t \n"), {}); + }); + + test("parses a block mapping into a plain object", () => { + const result = parseFixtureYaml("command:\n spokenForm: change token\n"); + assert.deepEqual(result, { command: { spokenForm: "change token" } }); + }); + + test("returns {} for a top-level scalar (not a mapping)", () => { + assert.deepEqual(parseFixtureYaml("just a string"), {}); + }); + + test("returns {} for a top-level sequence (not a mapping)", () => { + assert.deepEqual(parseFixtureYaml("- a\n- b\n"), {}); + }); + + test("preserves a literal block scalar byte-for-byte", () => { + const result = parseFixtureYaml("documentContents: |\n a\n b\n"); + assert.equal(result.documentContents, "a\nb\n"); + }); + }); +}); diff --git a/packages/command-visualizer/src/html.test.ts b/packages/command-visualizer/src/html.test.ts new file mode 100644 index 0000000000..87a5be4732 --- /dev/null +++ b/packages/command-visualizer/src/html.test.ts @@ -0,0 +1,69 @@ +import assert from "node:assert/strict"; +import { captionHtml, esc, themeBackground } from "./html"; + +suite("command-visualizer/html", () => { + suite("esc", () => { + test("escapes all five HTML-significant characters", () => { + assert.equal(esc("&"), "&"); + assert.equal(esc("<"), "<"); + assert.equal(esc(">"), ">"); + assert.equal(esc('"'), """); + assert.equal(esc("'"), "'"); + }); + + test("escapes & first so entities are not double-escaped", () => { + // If & were escaped after <, "<" -> "<" -> "&lt;" (wrong). + assert.equal(esc("<&>"), "<&>"); + }); + + test("neutralizes an attribute-breakout payload (CodeQL regression)", () => { + const payload = 'x" onmouseover="alert(1)'; + const escaped = esc(payload); + assert.ok(!escaped.includes('"'), "no raw double-quote survives"); + assert.equal(escaped, "x" onmouseover="alert(1)"); + }); + + test("leaves ordinary text untouched", () => { + assert.equal(esc("changeToken hello 42"), "changeToken hello 42"); + }); + }); + + suite("themeBackground", () => { + test("maps dark and light to their page backgrounds", () => { + assert.equal(themeBackground("dark"), "#141414"); + assert.equal(themeBackground("light"), "#e8e8e8"); + }); + }); + + suite("captionHtml", () => { + test("returns empty string when there is no meta", () => { + assert.equal(captionHtml(undefined), ""); + }); + + test("joins spoken form, action and fixture with a middot separator", () => { + const html = captionHtml({ + spokenForm: "change token", + action: "clearAndSetSelection", + fixture: "recorded/changeToken.yml", + }); + assert.equal( + html, + '<div class="cl-caption">"change token" · ' + + "clearAndSetSelection · recorded/changeToken.yml</div>", + ); + }); + + test("omits absent fields rather than emitting empty segments", () => { + assert.equal( + captionHtml({ action: "remove" }), + '<div class="cl-caption">remove</div>', + ); + }); + + test("escapes meta content so it cannot inject markup", () => { + const html = captionHtml({ fixture: "<script>alert(1)</script>" }); + assert.ok(!html.includes("<script>")); + assert.ok(html.includes("<script>")); + }); + }); +}); diff --git a/packages/command-visualizer/tsconfig.json b/packages/command-visualizer/tsconfig.json index 39c39d4833..fbf56544b3 100644 --- a/packages/command-visualizer/tsconfig.json +++ b/packages/command-visualizer/tsconfig.json @@ -1,7 +1,8 @@ { "extends": "../../tsconfig.base.json", "compilerOptions": { - "skipLibCheck": true + "skipLibCheck": true, + "types": ["node", "mocha"] }, "include": ["src/**/*.ts", "../../resources/typings/**/*.d.ts"] } From fcef30d4449dd0660aa69904e539c9475885c35e Mon Sep 17 00:00:00 2001 From: Trillium Smith <trillium@trilliumsmith.com> Date: Wed, 8 Jul 2026 08:40:37 -0700 Subject: [PATCH 21/53] chore: update pnpm-lock.yaml for command-visualizer deps (R1) Regenerated lockfile so it matches the new dependency specifiers (@cursorless/lib-common, @cursorless/lib-engine, js-yaml, @types/js-yaml, @types/mocha, @types/node). Fixes the --frozen-lockfile CI install failure CodeRabbit flagged (R1). --- pnpm-lock.yaml | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index bd374483ae..ad18964d92 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -298,6 +298,28 @@ importers: specifier: ^11.0.5 version: 11.0.5 + packages/command-visualizer: + dependencies: + '@cursorless/lib-common': + specifier: workspace:* + version: link:../lib-common + '@cursorless/lib-engine': + specifier: workspace:* + version: link:../lib-engine + js-yaml: + specifier: ^5.2.1 + version: 5.2.1 + devDependencies: + '@types/js-yaml': + specifier: ^4.0.9 + version: 4.0.9 + '@types/mocha': + specifier: ^10.0.10 + version: 10.0.10 + '@types/node': + specifier: ^24.13.2 + version: 24.13.2 + packages/lib-cheatsheet: dependencies: '@cursorless/lib-common': From 2c2af8fa5ffa5cee1a49212252d365266f41218d Mon Sep 17 00:00:00 2001 From: Trillium Smith <trillium@trilliumsmith.com> Date: Wed, 8 Jul 2026 08:45:04 -0700 Subject: [PATCH 22/53] refactor(command-visualizer): derive FLASH_STYLES from lib-common enum MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Addresses PR review (decorations.ts: 'this can likely be an import'): FLASH_STYLES was re-listing the FlashStyle enum members by hand — now derived via Object.values(FlashStyle) so it tracks lib-common automatically. Order is not significant (membership tests + per-selector CSS emission). --- packages/command-visualizer/src/data/decorations.ts | 12 +++++------- 1 file changed, 5 insertions(+), 7 deletions(-) diff --git a/packages/command-visualizer/src/data/decorations.ts b/packages/command-visualizer/src/data/decorations.ts index 548fde881f..29ee95b6d3 100644 --- a/packages/command-visualizer/src/data/decorations.ts +++ b/packages/command-visualizer/src/data/decorations.ts @@ -31,13 +31,11 @@ export const DECORATION_HEX: Record<DecorationStyle, string> = { highlight1: "#60daff7a", }; -export const FLASH_STYLES: FlashStyle[] = [ - "pendingDelete", - "justAdded", - "referenced", - "pendingModification0", - "pendingModification1", -]; +// Derived from lib-common's FlashStyle enum (the 5 flash styles) rather than +// re-listing the names — the set now tracks source automatically. Order is not +// significant: consumers use it for membership tests and per-style CSS rule +// emission with distinct selectors (css-cascade.ts). +export const FLASH_STYLES: FlashStyle[] = Object.values(CursorlessFlashStyle); export const HIGHLIGHT_STYLES: HighlightStyle[] = ["highlight0", "highlight1"]; From dd1ab123ca1d63d2c796740337c5df605504b281 Mon Sep 17 00:00:00 2001 From: Trillium Smith <trillium@trilliumsmith.com> Date: Wed, 8 Jul 2026 08:52:21 -0700 Subject: [PATCH 23/53] feat(lib-engine): export getTokensInRange from allocateHats barrel Exports-only change (no behavior change). command-visualizer needs the real tokenizer-backed token extractor to find the engine token covering a fixture mark position, so it can pin marks via forceTokenHats with matching token identity when consuming the real allocateHats. --- packages/lib-engine/src/util/allocateHats/index.ts | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/packages/lib-engine/src/util/allocateHats/index.ts b/packages/lib-engine/src/util/allocateHats/index.ts index da81596e3e..bd74b64858 100644 --- a/packages/lib-engine/src/util/allocateHats/index.ts +++ b/packages/lib-engine/src/util/allocateHats/index.ts @@ -1,5 +1,14 @@ export { allocateHats } from "./allocateHats"; +// getTokensInRange is the real cursorless tokenizer-backed token extractor. +// @cursorless/command-visualizer needs it to discover the exact engine token +// (and its whole-token document offsets) covering a fixture mark, so it can +// build a `forceTokenHats` entry whose token identity matches what the engine +// produces internally — pinning fixture marks to their recorded color. +// EXPORT-ONLY: no behavior change; it is called with the same (ide, editor, +// range) contract the engine uses in getRankedTokens. +export { getTokensInRange } from "./getTokensInRange"; + // maxByFirstDiffering is the only primitive from this sub-tree imported by // @cursorless/command-visualizer (vendored chooseTokenHat.ts, SHA 42452eb). // The broader ranking/selection helpers (chooseTokenHat, getHatRankingContext, From 23db201636b114dd6455e2e3ca764bd1f640d9a1 Mon Sep 17 00:00:00 2001 From: Trillium Smith <trillium@trilliumsmith.com> Date: Wed, 8 Jul 2026 08:55:13 -0700 Subject: [PATCH 24/53] refactor(command-visualizer): allocate hats via real lib-engine, drop vendored copy MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Rewrites hat-allocator.ts to run cursorless's real allocateHats (@cursorless/lib-engine) over an in-memory FakeIDE/InMemoryTextEditor document instead of the pinned vendored copy (SHA 42452eb) under src/vendor/. The engine tokenizes with cursorless's own tokenizer and ranks tokens by cursor proximity. - Deletes the entire src/vendor/allocate-hats/ tree (incl. VENDOR.md). - Deletes word-segments.ts — the engine's own tokenizer now supplies word-level segmentation; the module had no other importer. - Fixture marks are pinned via forceTokenHats: the covering engine token (found via getTokensInRange) is forced to the mark's exact color/shape, which chooseTokenHat applies first and unconditionally. - Keeps the visualizer's own palette/penalty map (cssStateHatStyles, colorPenalty, styleToHat). Rendered hat output changes vs the pinned SHA (current engine tokenizer + ranking); byte-fidelity to the old vendored output is NOT preserved, per the refactor directive. --- .../command-visualizer/src/hat-allocator.ts | 268 +++++++++------ packages/command-visualizer/src/pipeline.ts | 2 +- .../src/vendor/allocate-hats/VENDOR.md | 70 ---- .../src/vendor/allocate-hats/common/index.ts | 6 - .../src/vendor/allocate-hats/common/types.ts | 105 ------ .../src/vendor/allocate-hats/index.ts | 313 ------------------ .../src/vendor/allocate-hats/rank.ts | 46 --- .../src/vendor/allocate-hats/splitter.ts | 99 ------ .../vendor/allocate-hats/vendor/HatMetrics.ts | 129 -------- .../allocate-hats/vendor/chooseTokenHat.ts | 100 ------ .../vendor/getHatRankingContext.ts | 89 ----- .../vendor/getTokenComparator.ts | 56 ---- .../command-visualizer/src/word-segments.ts | 73 ---- 13 files changed, 164 insertions(+), 1192 deletions(-) delete mode 100644 packages/command-visualizer/src/vendor/allocate-hats/VENDOR.md delete mode 100644 packages/command-visualizer/src/vendor/allocate-hats/common/index.ts delete mode 100644 packages/command-visualizer/src/vendor/allocate-hats/common/types.ts delete mode 100644 packages/command-visualizer/src/vendor/allocate-hats/index.ts delete mode 100644 packages/command-visualizer/src/vendor/allocate-hats/rank.ts delete mode 100644 packages/command-visualizer/src/vendor/allocate-hats/splitter.ts delete mode 100644 packages/command-visualizer/src/vendor/allocate-hats/vendor/HatMetrics.ts delete mode 100644 packages/command-visualizer/src/vendor/allocate-hats/vendor/chooseTokenHat.ts delete mode 100644 packages/command-visualizer/src/vendor/allocate-hats/vendor/getHatRankingContext.ts delete mode 100644 packages/command-visualizer/src/vendor/allocate-hats/vendor/getTokenComparator.ts delete mode 100644 packages/command-visualizer/src/word-segments.ts diff --git a/packages/command-visualizer/src/hat-allocator.ts b/packages/command-visualizer/src/hat-allocator.ts index 0fc9e190f6..c4052fc265 100644 --- a/packages/command-visualizer/src/hat-allocator.ts +++ b/packages/command-visualizer/src/hat-allocator.ts @@ -1,49 +1,57 @@ -// REAL hat allocation — cursorless's actual algorithm via the allocate-hats -// sources, INTERNALIZED under ./vendor/allocate-hats (vendored from the -// allocate-hats repo at commit 42452eb, which itself vendors cursorless's -// allocateHats subgraph at SHA 42452eb — proven byte-identical to the shipped -// prose-overlay bundle). Internalized here so the package compiles in-monorepo -// without the unpublished `allocate-hats` npm dependency; the unused QuickJS -// bundle.ts / proseCompat.ts entry points were dropped during vendoring. +// Hat allocation via cursorless's REAL engine (@cursorless/lib-engine), driven +// by an in-memory document — the algorithm is imported directly, not copied in. // -// Replaces (task-8tq, 2026-07-07): -// - the greedy per-grapheme color-pool allocator that lived here, and -// - synthetic-shape.ts (sum-of-code-units % 11) — the repo's one known-fake -// render element. DECISIONS §7.5 blessing superseded; see §7.5b. +// The visualizer's render model (columns.ts) is one Token per GRAPHEME with +// line-relative UTF-16 offsets. This module reconstructs the document those +// lines represent, hands it to the real cursorless allocator, and maps the +// returned hats back onto the render tokens. // -// Model: -// - Every hattable token (single grapheme, per tokenize.ts R5) goes to the -// real allocator with its document position; ranking is cursorless's own -// comparator (line delta, then character delta from the cursor). -// - Fixture marks are passed as OLD ASSIGNMENTS with stability "stable": -// the algorithm keeps them (its own keep-metric) and their (grapheme, -// color) pairs are consumed from the pool, so fill tokens can't collide -// with them — the old step-3b pre-drain, now done by the real thing. -// - Marks render with shape "default" unless a per-fixture override says -// otherwise. This is MORE faithful than the synthetic hash: fixture mark -// keys carry no shape component, meaning the recorded session's hats were -// default-shape. -// - Fill tokens take the allocator's style wholesale (color + shape). With -// the full color x shape style map, shapes appear only under genuine -// collision pressure (>10 tokens sharing an anchor grapheme) — exactly -// like a real cursorless session, instead of hash-random shapes. +// How it works: +// 1. Reconstruct the document text: each Line's tokens joined, lines joined +// by "\n". +// 2. Build a FakeIDE + InMemoryTextEditor holding that text, with the cursor +// as the sole selection (its `active` is the proximity reference point the +// engine ranks tokens against) and the whole document visible. +// 3. Instantiate the real TokenGraphemeSplitter (cursorless's own grapheme +// splitter, IDE-configured) and call the real allocateHats(). The engine +// tokenizes the visible ranges with cursorless's own tokenizer +// (getTokensInRange), ranks tokens by distance from the cursor, and +// assigns at most one hat per token. +// 4. Fixture marks — graphemes that already carry a `.hat` from buildLines +// pass 1 — are PINNED via `forceTokenHats`: for each mark we find the +// engine token covering its position (getTokensInRange, so token identity +// matches what the engine produces internally) and force that token's hat +// to the mark's exact style and grapheme. The engine's chooseTokenHat +// applies forced hats first, unconditionally, so a pinned mark keeps its +// fixture color and position. +// 5. Each returned TokenHat is mapped back to the render token at its +// hatRange (line + character) and gets `.hat = styleToHat(style)`. // -// Determinism: allocate-hats is pure (no Date/random); same lines + marks + -// cursor -> identical assignments. verify-allocation.ts gates this. +// The palette / penalty map (cssStateHatStyles + colorPenalty) is the +// visualizer's OWN — the full color x shape space so shapes appear only under +// genuine collision pressure, exactly like a real cursorless session. +// +// Determinism: the engine allocator is pure (no Date/random); the same lines + +// marks + cursor produce identical assignments. import { - allocateHats as allocateHatsReal, - StandaloneGraphemeSplitter, + FakeIDE, + HatStability, type HatStyleMap, -} from "./vendor/allocate-hats/index"; + InMemoryTextEditor, + Range, + Selection, + type TokenHat, +} from "@cursorless/lib-common"; +import { + allocateHats as allocateHatsReal, + getTokensInRange, + TokenGraphemeSplitter, +} from "@cursorless/lib-engine"; import type { HatColor, HatShape } from "@cursorless/lib-common"; import { HAT_COLORS, HAT_SHAPES } from "@cursorless/lib-common"; -import type { Line } from "./columns"; +import type { Line, Token as RenderToken } from "./columns"; import type { Pos } from "./serialize"; -import { segmentLines } from "./word-segments"; - -/** True iff the token text is a single hattable grapheme (letter/number/punct/symbol). */ -const SPLITTER = new StandaloneGraphemeSplitter(); // --------------------------------------------------------------------------- // Style map: our full palette x (default + 10 shapes), penalty-ordered the way @@ -88,91 +96,141 @@ function styleToHat(styleName: string): { color: HatColor; shape: HatShape } { }; } +/** The cssStateHatStyles key for a (color, shape) pair (bare color = default). */ +function hatStyleName(color: HatColor, shape: HatShape | undefined): string { + return shape == null || shape === "default" ? color : `${color}-${shape}`; +} + +/** A fixture-marked render token together with its line index. */ +interface Mark { + lineIdx: number; + token: RenderToken; + color: HatColor; + shape: HatShape | undefined; +} + // --------------------------------------------------------------------------- // Main entry — called by fixture-extract.buildLines after pass 1 has attached -// fixture-mark hats to specific grapheme tokens. -// -// Allocation is per WORD-LEVEL token (word-segments.ts): each segment gets AT -// MOST ONE hat, anchored at the grapheme the real algorithm chooses (its -// returned charIdx). Fixture-marked segments enter as old assignments -// (stability "stable") so the algorithm keeps them and their (grapheme, -// color) pairs drain from the pool; the mark keeps its exact pass-1 grapheme -// position and hat. +// fixture-mark hats to specific grapheme render tokens. Mutates `lines` in +// place, setting `.hat` on the render token each allocated hat lands on. // --------------------------------------------------------------------------- export function allocateHats( lines: Line[], cursor: Pos = { line: 0, character: 0 }, ): void { - const segments = segmentLines(lines); - - const inputTokens = segments.map((seg) => ({ - text: seg.text, - position: { line: seg.lineIdx, character: seg.start }, - })); - - const oldAssignments: { - tokenIdx: number; - charIdx: number; - grapheme: string; - styleName: string; - }[] = []; - const pinned = new Set<number>(); - - segments.forEach((seg, idx) => { - for (const g of seg.graphemes) { - if (!g.hat) { - continue; + // (1) Reconstruct the document text the render model represents. + const content = lines + .map((line) => line.tokens.map((t) => t.text).join("")) + .join("\n"); + + // (2) In-memory editor: cursor as the sole selection, whole document visible. + const ide = new FakeIDE(); + const editor = new InMemoryTextEditor({ + ide, + languageId: "plaintext", + content, + selections: [ + new Selection( + cursor.line, + cursor.character, + cursor.line, + cursor.character, + ), + ], + // visibleRanges omitted → defaults to the whole document range. + }); + + // (3) Real cursorless grapheme splitter (IDE-configured). + const tokenGraphemeSplitter = new TokenGraphemeSplitter(ide); + + // (4) Collect fixture marks from the render tokens carrying a pass-1 hat. + const marks: Mark[] = []; + lines.forEach((line, lineIdx) => { + for (const token of line.tokens) { + if (token.hat) { + marks.push({ + lineIdx, + token, + color: token.hat.color, + shape: token.hat.shape, + }); } - pinned.add(idx); - oldAssignments.push({ - tokenIdx: idx, - charIdx: g.range.start - seg.start, - grapheme: SPLITTER.normalizeGrapheme(g.text), - // Include shape so the allocator reserves the right style key - // (cssStateHatStyles keys non-default shapes as `${color}-${shape}`). - styleName: - g.hat.shape === "default" || !g.hat.shape - ? g.hat.color - : `${g.hat.color}-${g.hat.shape}`, - }); - break; // one mark pins the whole segment } }); - const assignments = allocateHatsReal({ - tokens: inputTokens, - oldAssignments, - stability: "stable", + // Discover the engine tokens once (whole document), so forced-hat token + // identity matches what the engine produces internally. + const engineTokens = getTokensInRange(ide, editor, editor.document.range); + + // Build forceTokenHats: for each mark, force the covering engine token to the + // mark's exact color/shape, anchored on the mark's grapheme. + const forceTokenHats: TokenHat[] = []; + const forcedTokenKeys = new Set<string>(); + for (const mark of marks) { + const markStart = mark.token.range.start; // line-relative char offset + const covering = engineTokens.find( + (t) => + t.range.start.line === mark.lineIdx && + t.range.start.character <= markStart && + markStart < t.range.end.character, + ); + if (covering == null) { + // Whitespace-only or otherwise untokenized position — nothing to pin. + continue; + } + // One forced hat per engine token (a token wears at most one hat). If two + // marks fall in the same token, the first wins — matches "one mark pins the + // whole segment" from the previous word-segment model. + const tokenKey = `${covering.offsets.start}:${covering.offsets.end}`; + if (forcedTokenKeys.has(tokenKey)) { + continue; + } + forcedTokenKeys.add(tokenKey); + + const styleName = hatStyleName(mark.color, mark.shape); + const grapheme = tokenGraphemeSplitter.normalizeGrapheme(mark.token.text); + // Grapheme range within the document (line-relative positions), matching + // the render token span so map-back lands on this exact token. + const hatRange = new Range( + mark.lineIdx, + mark.token.range.start, + mark.lineIdx, + mark.token.range.end, + ); + forceTokenHats.push({ + hatStyle: styleName, + grapheme, + token: covering, + hatRange, + }); + } + + // (5) Run the real allocator. + const tokenHats = allocateHatsReal({ + ide, + tokenGraphemeSplitter, enabledHatStyles: cssStateHatStyles(), - cursorPosition: cursor, + forceTokenHats, + oldTokenHats: [], + hatStability: HatStability.balanced, + activeTextEditor: editor, + visibleTextEditors: [editor], }); - for (const a of assignments) { - const seg = segments[a.tokenIdx]; - if (pinned.has(a.tokenIdx)) { - // Mark keeps its pass-1 hat; tripwire if the algorithm dropped it. - const marked = seg.graphemes.find((g) => g.hat); - if (marked && SPLITTER.normalizeGrapheme(marked.text) !== a.grapheme) { - // Same segment, different anchor grapheme chosen — allowed only if - // the style survived; color change would break fixture fidelity. - const kept = styleToHat(a.styleName); - if (kept.color !== marked.hat!.color) { - throw new Error( - `[hat-allocator] real allocator reassigned pinned mark in segment ` + - `"${seg.text}" (line ${seg.lineIdx}): fixture color ${marked.hat!.color}, ` + - `allocator gave ${a.styleName}`, - ); - } - } + // (6) Map each returned hat back onto the render token at its hatRange. + for (const tokenHat of tokenHats) { + const { line, character } = tokenHat.hatRange.start; + const renderLine = lines[line]; + if (renderLine == null) { continue; } - // One hat per word-level token, on the algorithm-chosen grapheme. - const target = seg.graphemes.find( - (g) => g.range.start - seg.start === a.charIdx, - ); - if (target) { - target.hat = styleToHat(a.styleName); + const target = renderLine.tokens.find((t) => t.range.start === character); + if (target == null) { + continue; } + target.hat = styleToHat(tokenHat.hatStyle); } + + ide.exit(); } diff --git a/packages/command-visualizer/src/pipeline.ts b/packages/command-visualizer/src/pipeline.ts index 8908495e80..33bb7065d8 100644 --- a/packages/command-visualizer/src/pipeline.ts +++ b/packages/command-visualizer/src/pipeline.ts @@ -28,7 +28,7 @@ import { fixtureRoot } from "./fixture-root"; // Resolved lazily: fixtureRoot() throws when no cursorless checkout exists, // which must not fire at module load in serverless (the API path reads -// vendored fixtures and never touches disk). +// bundled fixtures and never touches disk). let fixtureRootCache: string | undefined; function FIXTURE_ROOT_LAZY(): string { return (fixtureRootCache ??= fixtureRoot()); diff --git a/packages/command-visualizer/src/vendor/allocate-hats/VENDOR.md b/packages/command-visualizer/src/vendor/allocate-hats/VENDOR.md deleted file mode 100644 index fe21b91edf..0000000000 --- a/packages/command-visualizer/src/vendor/allocate-hats/VENDOR.md +++ /dev/null @@ -1,70 +0,0 @@ -# Vendored: allocate-hats - -Internalized copy of the `allocate-hats` package's `src/` tree. - -- **Source repo:** github.com/trillium/allocate-hats -- **Vendored commit / SHA:** `42452eb` (recorded in the source headers; this is - also the cursorless SHA `42452eba521bb9cccbb3e04a2cd9e9afcf6cbffe` whose - `allocateHats` subgraph these files vendor, proven byte-identical to the - shipped prose-overlay bundle). -- **Why internalized:** `allocate-hats@0.1.0` is unpublished (npm has no such - package; it lived only at `~/code/allocate-hats`). Vendoring lets - `@cursorless/command-visualizer` compile in-monorepo with zero external deps. - -## What is imported from source vs. kept pinned vs. dropped - -**Imported from `@cursorless/lib-common` / `@cursorless/lib-engine` (no clone):** - -- `CompositeKeyMap`, `DefaultMap` — re-exported through `common/index.ts` from - `@cursorless/lib-common` (byte-identical to the copies that used to live in - `common/`). The local files were deleted. -- `GRAPHEME_SPLIT_REGEX` — imported from `@cursorless/lib-engine` in - `splitter.ts` (and, in the package proper, in `tokenize.ts` / `columns.ts`). -- `maxByFirstDiffering` — imported from `@cursorless/lib-engine` in - `vendor/chooseTokenHat.ts` (byte-identical to the pin; generic, no cursorless - types in its signature). The local `vendor/maxByFirstDiffering.ts` was deleted. - -**Kept PINNED at SHA `42452eb` (must NOT be swapped for the current lib-engine -versions — upstream has diverged, see per-file headers for the exact reason):** - -- `vendor/chooseTokenHat.ts` — current upstream added a `forcedTokenHat` param - (#2602) and an `avoidFirstLetter` step (#1723). -- `vendor/HatMetrics.ts` — current upstream added `avoidFirstLetter`, needing - `HatCandidate.isFirstLetter` (a WordTokenizer/IDE-derived field this offline - renderer cannot compute). -- `vendor/getHatRankingContext.ts` — current upstream types against the concrete - IDE-backed `TokenGraphemeSplitter` and full engine `Token`; this copy accepts - the structural `GraphemeSplitter` + simplified Token. -- `vendor/getTokenComparator.ts` — byte-identical to source, but the engine - version's signature is typed against lib-common's full `Token`, which the - simplified standalone Token is not assignable to. -- `common/types.ts` — custom minimal `Position`/`Range`/`Token`/`HatCandidate`/ - `RankedToken`/`Grapheme`/`GraphemeSplitter` (no public lib-common equivalents - for the last four; `Position`/`Range`/`Token` deliberately simplified). -- `index.ts` (the tokens-in `allocateHats` wrapper), `rank.ts`, - `splitter.ts` (the `StandaloneGraphemeSplitter` class + inline `deburr`) — - genuinely-new glue with no cursorless equivalent (the engine paths require a - live IDE / TextEditor). - -Dropped during the original vendoring (unused by this package): - -- `bundle.ts` — QuickJS IIFE entry (exposes API on `globalThis`). -- `proseCompat.ts` — prose-overlay legacy JSON-in/JSON-out compatibility API. - -## Consumer - -`src/hat-allocator.ts` imports `allocateHats`, `StandaloneGraphemeSplitter`, -and the `HatStyleMap` type from `./vendor/allocate-hats/index`. - -## Updating - -The pinned files must stay at SHA `42452eb` to preserve the renderer's -byte-for-byte fidelity to the recorded prose-overlay bundle. Do NOT -mechanically re-sync them to current cursorless — that would pull in -`forcedTokenHat` / `avoidFirstLetter` and change hat placement. If you -deliberately want the new algorithm, that is a behavior change to design and -verify against the fixture oracle, not a copy-paste refresh. - -The imported-from-source pieces (`CompositeKeyMap`, `DefaultMap`, -`GRAPHEME_SPLIT_REGEX`, `maxByFirstDiffering`) track cursorless automatically -via the workspace deps — nothing to re-copy. diff --git a/packages/command-visualizer/src/vendor/allocate-hats/common/index.ts b/packages/command-visualizer/src/vendor/allocate-hats/common/index.ts deleted file mode 100644 index 54774783b4..0000000000 --- a/packages/command-visualizer/src/vendor/allocate-hats/common/index.ts +++ /dev/null @@ -1,6 +0,0 @@ -export * from "./types"; -// DefaultMap / CompositeKeyMap are re-exported straight from -// @cursorless/lib-common (byte-identical to the copies this tree used to -// vendor). Importing them from source removes two clones; every consumer in -// this tree keeps its unchanged `from "../common"` import. -export { CompositeKeyMap, DefaultMap } from "@cursorless/lib-common"; diff --git a/packages/command-visualizer/src/vendor/allocate-hats/common/types.ts b/packages/command-visualizer/src/vendor/allocate-hats/common/types.ts deleted file mode 100644 index 75492782cd..0000000000 --- a/packages/command-visualizer/src/vendor/allocate-hats/common/types.ts +++ /dev/null @@ -1,105 +0,0 @@ -/** - * Minimal type surface extracted from @cursorless/common at cursorless SHA - * 42452eba521bb9cccbb3e04a2cd9e9afcf6cbffe (the pinned SHA all three delivery - * substrates already build against). - * - * Position and Range are deliberately SIMPLIFIED: the allocation path only - * ever constructs them and reads `.line` / `.character` / `.start` / `.end`. - * Upstream's method surface (isEqual, union, toSelection, ...) is unused by - * the allocator and omitted. Token / TokenHat / HatStyleMap match upstream - * shapes field-for-field. - */ - -export class Position { - constructor( - public readonly line: number, - public readonly character: number, - ) {} -} - -export class Range { - readonly start: Position; - readonly end: Position; - - constructor(start: Position, end: Position) { - this.start = start; - this.end = end; - } -} - -export interface RangeOffsets { - start: number; - end: number; -} - -/** - * The allocator never dereferences the editor beyond `id` (used as part of - * the CompositeKeyMap token identity key). - */ -export interface MinimalEditor { - id: string; -} - -/** Mirrors @cursorless/common types/Token.ts */ -export interface Token { - editor: MinimalEditor; - range: Range; - offsets: RangeOffsets; - text: string; -} - -export type HatStyleName = string; - -/** Mirrors @cursorless/common types/HatTokenMap.ts TokenHat */ -export interface TokenHat { - hatStyle: HatStyleName; - grapheme: string; - token: Token; - hatRange: Range; -} - -export type HatStyleMap = Record<HatStyleName, { penalty: number }>; - -/** - * Mirrors @cursorless/common ide/types/HatStability.ts — string enum values - * are load-bearing (callers pass the raw strings across JSON boundaries). - */ -export enum HatStability { - greedy = "greedy", - balanced = "balanced", - stable = "stable", -} - -/** Mirrors the grapheme shape produced by cursorless's TokenGraphemeSplitter */ -export interface Grapheme { - text: string; - tokenStartOffset: number; - tokenEndOffset: number; -} - -/** - * Structural stand-in for cursorless's TokenGraphemeSplitter — the ranking - * context only calls `getTokenGraphemes`. - */ -export interface GraphemeSplitter { - getTokenGraphemes(tokenText: string): Grapheme[]; -} - -/** - * Mirrors HatCandidate from cursorless-engine util/allocateHats/allocateHats.ts - */ -export interface HatCandidate { - grapheme: Grapheme; - style: HatStyleName; - penalty: number; -} - -/** Mirrors RankedToken from util/allocateHats/getRankedTokens.ts */ -export interface RankedToken { - token: Token; - /** - * Higher rank = more likely to be used = gets a better hat. Upstream uses - * rank = -sortedIndex (0 is best, increasingly negative is worse). - */ - rank: number; -} diff --git a/packages/command-visualizer/src/vendor/allocate-hats/index.ts b/packages/command-visualizer/src/vendor/allocate-hats/index.ts deleted file mode 100644 index 84a9e4e7a2..0000000000 --- a/packages/command-visualizer/src/vendor/allocate-hats/index.ts +++ /dev/null @@ -1,313 +0,0 @@ -/** - * allocate-hats — standalone Cursorless hat allocation with a tokens-in - * interface. - * - * You bring tokens (already tokenized however your substrate likes); this - * package runs the REAL cursorless allocation algorithm (chooseTokenHat + - * getHatRankingContext + HatMetrics + maxByFirstDiffering, vendored at SHA - * 42452eba521bb9cccbb3e04a2cd9e9afcf6cbffe) and returns hat assignments. - * - * Language support is upstream of allocation by design: languageId appears - * nowhere in the allocator (verified across cursorless, prose-overlay, - * Touchless, cursorless-css-state — brain-1uh8e §4). Tokenize with whatever - * language machinery you have; allocation is language-blind. - */ - -import { - CompositeKeyMap, - DefaultMap, - HatStability, - type HatCandidate, - type HatStyleMap, - type HatStyleName, - Position, - Range, - type RankedToken, - type Token, - type TokenHat, -} from "./common"; -import { chooseTokenHat } from "./vendor/chooseTokenHat"; -import { getHatRankingContext } from "./vendor/getHatRankingContext"; -import { rankTokensByProximity } from "./rank"; -import { StandaloneGraphemeSplitter } from "./splitter"; - -export { HatStability } from "./common"; -export type { HatStyleMap, HatStyleName } from "./common"; -export { StandaloneGraphemeSplitter, deburr } from "./splitter"; - -// --------------------------------------------------------------------------- -// Public input/output types -// --------------------------------------------------------------------------- - -export interface InputToken { - /** The token's text. Graphemes are derived internally by the splitter. */ - text: string; - /** - * Optional explicit rank: HIGHER = more important = better hat. When every - * token carries a rank, ranks are used as-is. When any token omits it, all - * ranks are derived from cursor proximity instead (see - * {@link AllocateHatsOptions.cursorIndex}). - */ - rank?: number; - /** - * Optional document position for multi-line proximity ranking (touchless / - * css-state style inputs). When omitted, the token sits at line 0, - * character = its array index (the single-line prose model). - */ - position?: { line: number; character: number }; -} - -export interface HatAssignment { - /** Index into the input tokens array. */ - tokenIdx: number; - /** Character offset of the hatted grapheme within the token text. */ - charIdx: number; - /** The normalized grapheme the hat sits on. */ - grapheme: string; - /** Full style name, e.g. "blue" or "blue-frame". */ - styleName: string; -} - -export interface AllocateHatsOptions { - tokens: InputToken[]; - /** - * Hat assignments from the previous allocation — pass these back each - * recompute to get hat stability (hats stay put as the buffer changes). - */ - oldAssignments?: HatAssignment[]; - /** Keep/steal trade-off. Default: balanced (cursorless's default). */ - stability?: HatStability | "greedy" | "balanced" | "stable"; - /** - * Enabled hat styles with penalties (lower penalty = preferred). Defaults - * to {@link buildColorStyles} — 9 colors, no shapes. - */ - enabledHatStyles?: HatStyleMap; - /** - * Used only when explicit per-token ranks are absent: tokens are ranked by - * proximity to this gap index (0 = before first token, N = after last). - * Defaults to tokens.length (end-biased), matching prose-overlay's - * no-cursor behavior. Ignored when {@link cursorPosition} is set. - */ - cursorIndex?: number; - /** - * Multi-line variant of {@link cursorIndex}: the reference position tokens - * are ranked against (closest = best hat), for use with - * {@link InputToken.position}. Ranking is |displayLine delta| then - * |character delta| — cursorless's getTokenComparator, vendored. - */ - cursorPosition?: { line: number; character: number }; -} - -// --------------------------------------------------------------------------- -// Default style maps (prose-overlay palette; matches cursorless's color set) -// --------------------------------------------------------------------------- - -export const HAT_COLORS = [ - "gray", - "blue", - "green", - "red", - "pink", - "yellow", - "purple", - "black", - "white", -] as const; - -export const HAT_COLOR_PENALTIES: Record<string, number> = { - gray: 0, - blue: 1, - green: 1, - red: 1, - pink: 2, - yellow: 2, - purple: 2, - black: 3, - white: 3, -}; - -/** - * Shape suffix vocabulary — mirrors cursorless HAT_NON_DEFAULT_SHAPES - * (packages/common/src/types/command/legacy/targetDescriptorV2.types.ts). - */ -export const HAT_SHAPES = [ - "ex", - "fox", - "wing", - "hole", - "frame", - "curve", - "eye", - "play", - "bolt", - "crosshairs", -] as const; - -/** 9-entry color-only style map. */ -export function buildColorStyles(): HatStyleMap { - const out: HatStyleMap = {}; - for (const color of HAT_COLORS) { - out[color] = { penalty: HAT_COLOR_PENALTIES[color] }; - } - return out; -} - -/** - * Full 99-entry color x (no-shape + 10 shapes) map. Shape adds +1 to the - * color's penalty, matching the upstream convention that each style - * component contributes to total penalty. - */ -export function buildColorShapeStyles(): HatStyleMap { - const out: HatStyleMap = {}; - for (const color of HAT_COLORS) { - const colorPenalty = HAT_COLOR_PENALTIES[color]; - out[color] = { penalty: colorPenalty }; - for (const shape of HAT_SHAPES) { - out[`${color}-${shape}`] = { penalty: colorPenalty + 1 }; - } - } - return out; -} - -// --------------------------------------------------------------------------- -// Internal: token construction + ranking -// --------------------------------------------------------------------------- - -const FAKE_EDITOR = { id: "allocate-hats" }; - -function makeToken(input: InputToken, index: number): Token { - const line = input.position?.line ?? 0; - const character = input.position?.character ?? index; - const start = new Position(line, character); - const end = new Position(line, character + 1); - return { - editor: FAKE_EDITOR, - text: input.text, - // offsets.start doubles as the stable token identity (= input index); - // range carries the (possibly caller-supplied) document position used - // for proximity ranking. - range: new Range(start, end), - offsets: { start: index, end: index + 1 }, - }; -} - -/** - * getTokenRemainingHatCandidates — copied from cursorless allocateHats.ts - * (unexported upstream; same copy prose-overlay's proseStandalone.ts carries). - */ -function getTokenRemainingHatCandidates( - splitter: StandaloneGraphemeSplitter, - token: Token, - graphemeRemainingHatCandidates: DefaultMap<string, HatStyleName[]>, - enabledHatStyles: HatStyleMap, -): HatCandidate[] { - const candidates: HatCandidate[] = []; - const graphemes = splitter.getTokenGraphemes(token.text); - for (const grapheme of graphemes) { - for (const style of graphemeRemainingHatCandidates.get(grapheme.text)) { - candidates.push({ - grapheme, - style, - penalty: enabledHatStyles[style]?.penalty ?? 99, - }); - } - } - return candidates; -} - -// --------------------------------------------------------------------------- -// Main entry point -// --------------------------------------------------------------------------- - -export function allocateHats(options: AllocateHatsOptions): HatAssignment[] { - const { - tokens, - oldAssignments = [], - stability = HatStability.balanced, - enabledHatStyles = buildColorStyles(), - cursorIndex, - cursorPosition, - } = options; - - const hatStability = stability as HatStability; - const splitter = new StandaloneGraphemeSplitter(); - const enabledHatStyleNames = Object.keys(enabledHatStyles); - - const tokenObjects = tokens.map((t, i) => makeToken(t, i)); - - // Ranking: explicit ranks when every token has one, else proximity to the - // reference position (cursorPosition, or gap cursorIndex on line 0 — - // defaulting to end-biased, matching prose-overlay's no-cursor behavior). - const allRanked = tokens.every((t) => typeof t.rank === "number"); - const referencePosition = cursorPosition - ? new Position(cursorPosition.line, cursorPosition.character) - : new Position(0, cursorIndex ?? tokens.length); - const rankedTokens: RankedToken[] = allRanked - ? tokens.map((t, i) => ({ token: tokenObjects[i], rank: t.rank! })) - : rankTokensByProximity(tokenObjects, referencePosition); - - // Old hat map for stability. - const tokenOldHatMap = new CompositeKeyMap<Token, TokenHat>( - ({ editor, offsets }) => [editor.id, offsets.start, offsets.end], - ); - for (const { tokenIdx, grapheme, styleName } of oldAssignments) { - if (tokenIdx >= 0 && tokenIdx < tokens.length) { - const token = tokenObjects[tokenIdx]; - tokenOldHatMap.set(token, { - hatStyle: styleName, - grapheme, - token, - hatRange: token.range, - }); - } - } - - const context = getHatRankingContext(rankedTokens, tokenOldHatMap, splitter); - - const graphemeRemainingHatCandidates = new DefaultMap<string, HatStyleName[]>( - () => [...enabledHatStyleNames], - ); - - // Process tokens in descending rank order (best tokens first). - const sortedRanked = [...rankedTokens].sort((a, b) => b.rank - a.rank); - const result: HatAssignment[] = []; - - for (const { token, rank } of sortedRanked) { - const candidates = getTokenRemainingHatCandidates( - splitter, - token, - graphemeRemainingHatCandidates, - enabledHatStyles, - ); - - const chosen = chooseTokenHat( - context, - hatStability, - rank, - tokenOldHatMap.get(token), - candidates, - ); - - if (chosen == null) { - continue; - } - - // Remove the chosen hat from candidates for lower-ranked tokens. - graphemeRemainingHatCandidates.set( - chosen.grapheme.text, - graphemeRemainingHatCandidates - .get(chosen.grapheme.text) - .filter((s) => s !== chosen.style), - ); - - result.push({ - tokenIdx: token.offsets.start, - charIdx: chosen.grapheme.tokenStartOffset, - grapheme: chosen.grapheme.text, - styleName: String(chosen.style), - }); - } - - result.sort((a, b) => a.tokenIdx - b.tokenIdx); - return result; -} diff --git a/packages/command-visualizer/src/vendor/allocate-hats/rank.ts b/packages/command-visualizer/src/vendor/allocate-hats/rank.ts deleted file mode 100644 index c6e937b9e8..0000000000 --- a/packages/command-visualizer/src/vendor/allocate-hats/rank.ts +++ /dev/null @@ -1,46 +0,0 @@ -/** - * Port of `rankPreTokenizedInput` from cursorless - * packages/cursorless-engine/src/util/allocateHats/getRankedTokens.ts at SHA - * 42452eba521bb9cccbb3e04a2cd9e9afcf6cbffe, with the fake-editor plumbing - * removed: the reference cursor position is a plain argument instead of - * `activeTextEditor.selections[0].active`. The display-line map construction, - * the comparator (vendored getTokenComparator), and the rank = -sortedIndex - * convention are unchanged. - */ - -import { Position, type RankedToken, type Token } from "./common"; -import { getTokenComparator } from "./vendor/getTokenComparator"; - -export function rankTokensByProximity( - tokens: readonly Token[], - referencePosition: Position, -): RankedToken[] { - if (tokens.length === 0) { - return []; - } - - // Build a stable display-line map directly from the supplied tokens so the - // comparator sees a consistent ordering even without an editor walk. - const lines = new Set<number>([referencePosition.line]); - for (const token of tokens) { - lines.add(token.range.start.line); - } - const sortedLines = [...lines].sort((a, b) => a - b); - const displayLineMap = new Map<number, number>( - sortedLines.map((line, index) => [line, index]), - ); - - const withDisplayLine = tokens.map((token) => ({ - ...token, - displayLine: displayLineMap.get(token.range.start.line)!, - })); - - withDisplayLine.sort( - getTokenComparator( - displayLineMap.get(referencePosition.line)!, - referencePosition.character, - ), - ); - - return withDisplayLine.map((token, index) => ({ token, rank: -index })); -} diff --git a/packages/command-visualizer/src/vendor/allocate-hats/splitter.ts b/packages/command-visualizer/src/vendor/allocate-hats/splitter.ts deleted file mode 100644 index 903b6bb60b..0000000000 --- a/packages/command-visualizer/src/vendor/allocate-hats/splitter.ts +++ /dev/null @@ -1,99 +0,0 @@ -/** - * Standalone grapheme splitter — mirrors the canonical - * @cursorless/lib-engine TokenGraphemeSplitter, but with a STATIC config: no - * ide().configuration, so no lettersToPreserve / symbolsToPreserve user - * overrides. The engine's class requires an IDE in its constructor (for the - * live tokenHatSplittingMode setting), which this offline renderer has no way - * to supply — hence this minimal reimplementation of getTokenGraphemes / - * normalizeGrapheme rather than importing the class. - * - * The split regex itself is NOT cloned: GRAPHEME_SPLIT_REGEX is imported from - * @cursorless/lib-engine (source of truth). - */ - -import { GRAPHEME_SPLIT_REGEX } from "@cursorless/lib-engine"; -import type { Grapheme, GraphemeSplitter } from "./common/types"; - -/** - * Inline deburr — strips combining diacritics after NFC normalization. - * Replaces lodash.deburr to keep the bundle free of lodash (whose CommonJS - * module blows QuickJS's call stack). - */ -export function deburr(str: string): string { - return ( - str - .normalize("NFC") - // eslint-disable-next-line no-misleading-character-class - .replace(/[\u0300-\u036f\u1dc0-\u1dff\u20d0-\u20ff\ufe20-\ufe2f]/g, "") - ); -} - -const KNOWN_SYMBOLS = [ - "!", - "#", - "$", - "%", - "&", - "'", - "(", - ")", - "*", - "+", - ",", - "-", - ".", - "/", - ":", - ";", - "<", - "=", - ">", - "?", - "@", - "[", - "\\", - "]", - "^", - "_", - "`", - "{", - "|", - "}", - "~", - "£", - '"', -]; -const UNKNOWN_GRAPHEME = "[unk]"; -const KNOWN_GRAPHEME_MATCHER = new RegExp( - `^([a-zA-Z0-9]|${KNOWN_SYMBOLS.map((s) => - s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"), - ).join("|")})$`, - "u", -); - -export class StandaloneGraphemeSplitter implements GraphemeSplitter { - getTokenGraphemes(tokenText: string): Grapheme[] { - // Fresh RegExp per call: GRAPHEME_SPLIT_REGEX is a shared /gu instance whose - // lastIndex would leak across calls if reused directly. - const re = new RegExp(GRAPHEME_SPLIT_REGEX); - const results: Grapheme[] = []; - let match: RegExpExecArray | null; - while ((match = re.exec(tokenText)) != null) { - results.push({ - text: this.normalizeGrapheme(match[0]), - tokenStartOffset: match.index, - tokenEndOffset: match.index + match[0].length, - }); - } - return results; - } - - normalizeGrapheme(raw: string): string { - let val = raw.normalize("NFC").toLowerCase(); - val = deburr(val); - if (!KNOWN_GRAPHEME_MATCHER.test(val)) { - val = UNKNOWN_GRAPHEME; - } - return val; - } -} diff --git a/packages/command-visualizer/src/vendor/allocate-hats/vendor/HatMetrics.ts b/packages/command-visualizer/src/vendor/allocate-hats/vendor/HatMetrics.ts deleted file mode 100644 index 6086b09bbc..0000000000 --- a/packages/command-visualizer/src/vendor/allocate-hats/vendor/HatMetrics.ts +++ /dev/null @@ -1,129 +0,0 @@ -/** - * Vendored from cursorless HatMetrics.ts, PINNED at SHA - * 42452eba521bb9cccbb3e04a2cd9e9afcf6cbffe. - * - * NOT importable from @cursorless/lib-engine: current upstream HatMetrics adds - * `avoidFirstLetter` (introduced with #1723) which reads - * `HatCandidate.isFirstLetter` — a field the pinned HatCandidate here does not - * carry and which requires a WordTokenizer(ide, languageId) the offline - * renderer cannot construct. chooseTokenHat (also pinned) does not call - * avoidFirstLetter, so this pinned metric set is the correct, self-consistent - * one. Adopting the current version would change hat placement. - * - * lodash memoize/min are inlined below (not imported) to keep the bundle free - * of lodash, whose CommonJS module blows QuickJS's call stack in the - * downstream standalone build. - * - * Edits are IMPORT REWRITES ONLY: - * - "@cursorless/common" -> "../common" barrel - * - HatCandidate: "./allocateHats" -> "../common/types" - */ - -import { CompositeKeyMap, HatStability, TokenHat } from "../common"; - -// Inline replacements for lodash memoize and min — avoids bundling the full -// lodash CommonJS module (5,500 lines) which blows QuickJS's call stack. -function memoize<T extends string | number, R>( - fn: (arg: T) => R, -): (arg: T) => R { - const cache = new Map<T, R>(); - return (arg: T) => { - if (!cache.has(arg)) { - cache.set(arg, fn(arg)); - } - return cache.get(arg)!; - }; -} -function min(arr: number[]): number | undefined { - return arr.length ? Math.min(...arr) : undefined; -} -import { HatCandidate } from "../common/types"; - -/** - * A function that takes a hat candidate and returns a number representing its - * quality; greater is always better - */ -export type HatMetric = (hat: HatCandidate) => number; - -/** - * @returns A metric that just returns the negative penalty of the given hat - * candidate - */ -export const negativePenalty: HatMetric = ({ penalty }) => -penalty; - -/** - * @param hatOldTokenRanks A map from a hat candidate (grapheme+style combination) to the score of the - * token that used the given hat in the previous hat allocation. - * @returns A metric that returns Infinity if the hat candidate is not in use in - * the old allocation, otherwise the rank of the token from the old allocation - * that we'd steal the hat from - */ -export function hatOldTokenRank( - hatOldTokenRanks: CompositeKeyMap< - { grapheme: string; hatStyle: string }, - number - >, -): HatMetric { - return ({ grapheme: { text: grapheme }, style }) => { - const hatOldTokenRank = hatOldTokenRanks.get({ - grapheme, - hatStyle: style, - }); - - return hatOldTokenRank == null ? Infinity : -hatOldTokenRank; - }; -} - -/** - * @param tokenRank The rank of the current token, so that we don't consider - * higher ranked tokens (which already have been assigned hats) - * @param graphemeTokenRanks A map from graphemes to an ordered list of the - * ranks of tokens containing the grapheme - * @returns A metric which returns the minimum token rank among lower ranked - * tokens that contain the hat's grapheme (or Infinity if the grapheme doesn't - * appear in any lower ranked tokens) - */ -export function minimumTokenRankContainingGrapheme( - tokenRank: number, - graphemeTokenRanks: { [key: string]: number[] }, -): HatMetric { - const coreMetric = memoize((graphemeText: string): number => { - return ( - min(graphemeTokenRanks[graphemeText].filter((r) => r > tokenRank)) ?? - Infinity - ); - }); - return ({ grapheme: { text } }) => coreMetric(text); -} - -/** - * @param oldTokenHat The old hat for the token to which we're assigning a hat - * @returns A metric which returns 1 if the hat candidate is the one the token - * currently has, 0 otherwise - */ -export function isOldTokenHat(oldTokenHat: TokenHat | undefined): HatMetric { - return (hat) => - hat.grapheme.text === oldTokenHat?.grapheme && - hat.style === oldTokenHat?.hatStyle - ? 1 - : 0; -} - -/** - * Given a {@link HatStability}, returns its equivalence class function. - * - * @param HatStability The user setting for which we need to return - * equivalence class - * @returns A hat metric that will collapse hats that are not different enough - * to justify keeping / stealing - */ -export function penaltyEquivalenceClass(hatStability: HatStability): HatMetric { - switch (hatStability) { - case HatStability.greedy: - return ({ penalty }) => -penalty; - case HatStability.balanced: - return ({ penalty }) => -(penalty < 2 ? 0 : 1); - case HatStability.stable: - return (_) => 0; - } -} diff --git a/packages/command-visualizer/src/vendor/allocate-hats/vendor/chooseTokenHat.ts b/packages/command-visualizer/src/vendor/allocate-hats/vendor/chooseTokenHat.ts deleted file mode 100644 index c094f56d18..0000000000 --- a/packages/command-visualizer/src/vendor/allocate-hats/vendor/chooseTokenHat.ts +++ /dev/null @@ -1,100 +0,0 @@ -/** - * Vendored from cursorless chooseTokenHat.ts, PINNED at SHA - * 42452eba521bb9cccbb3e04a2cd9e9afcf6cbffe. - * - * NOT importable from @cursorless/lib-engine: current upstream chooseTokenHat - * has DIVERGED from this pin (two feature commits — #2602 "Make hat forcing - * more aggressive" added a `forcedTokenHat` parameter, #1723 "avoid allocating - * hats to the first letter of a token" added an `avoidFirstLetter` metric that - * needs `HatCandidate.isFirstLetter`, computed from a WordTokenizer(ide, - * languageId) this offline renderer cannot construct). Adopting the current - * version would change which grapheme gets hatted and break the renderer's - * byte-for-byte fidelity to the recorded prose-overlay bundle. This copy stays - * pinned on purpose. - * - * maxByFirstDiffering IS imported from @cursorless/lib-engine (it is - * byte-identical to the pin and generic, so no clone is needed). - * Remaining edits are IMPORT REWRITES ONLY: - * - "@cursorless/common" -> "../common" barrel - * - HatCandidate: "./allocateHats" -> "../common/types" - * - maxByFirstDiffering: "./maxByFirstDiffering" -> "@cursorless/lib-engine" - */ - -import { HatStability, TokenHat } from "../common"; -import { HatCandidate } from "../common/types"; -import { RankingContext } from "./getHatRankingContext"; -import { - hatOldTokenRank, - isOldTokenHat, - minimumTokenRankContainingGrapheme, - negativePenalty, - penaltyEquivalenceClass, -} from "./HatMetrics"; -import { maxByFirstDiffering } from "@cursorless/lib-engine"; - -/** - * Selects a hat for a given token from amongst {@link candidates}, trading off - * hat quality and hat stability - * - * **IMPORTANT**: This function assumes that all tokens with a lower rank than - * the given token have already been assigned hats. - * - * We proceed as follows: - * - * 1. Decide whether to keep our own hat, if a higher ranked token hasn't - * already taken it - * 2. Decide whether to steal a hat from a lower ranked token - * - * See [hat assignment](/docs/user/hatAssignment) for more info. - * - * FIXME: Could be improved by ignoring subsequent tokens that also contain - * another character that can be used with lower color. To compute that, look at - * all the other characters in the given subsequent token, look at their current - * color, and add the number of times it appears in between the current token - * and the given subsequent token. - * - * Here is an example where the existing algorithm falls down: "ab ax b". It - * will put a hat on `b` for token `ab` because `b` appears two tokens away - * whereas `a` appears in the next token. However, if it had chosen `a`, then - * it could use `x` for `ax`, leaving `b` free for the final `b` token. - * - * @param context Lookup tables with information about which graphemes / hats - * other tokens have - * @param hatStability The user settings that determine when to keep / steal - * hats - * @param tokenRank The rank of the token for whom we're picking a hat - * @param oldTokenHat The hat that was on the token before (or `undefined` if it - * didn't have one) - * @param candidates The set of candidate hats under consideration (includes - * both hat style and grapheme) - * @returns The chosen hat, or `undefined` if {@link candidates} was empty - */ -export function chooseTokenHat( - { hatOldTokenRanks, graphemeTokenRanks }: RankingContext, - hatStability: HatStability, - tokenRank: number, - oldTokenHat: TokenHat | undefined, - candidates: HatCandidate[], -): HatCandidate | undefined { - // We narrow down the candidates by a series of criteria until there is only - // one left - return maxByFirstDiffering(candidates, [ - // 1. Discard any hats that are sufficiently worse than the best hat that we - // wouldn't use them even if they were our old hat - penaltyEquivalenceClass(hatStability), - - // 2. Use our old hat if it's still in the running - isOldTokenHat(oldTokenHat), - - // 3. Use a free hat if possible; if not, steal the hat of the token with - // lowest rank - hatOldTokenRank(hatOldTokenRanks), - - // 4. Narrow to the hats with the lowest penalty - negativePenalty, - - // 5. Prefer hats that sit on a grapheme that doesn't appear in any highly - // ranked token - minimumTokenRankContainingGrapheme(tokenRank, graphemeTokenRanks), - ])!; -} diff --git a/packages/command-visualizer/src/vendor/allocate-hats/vendor/getHatRankingContext.ts b/packages/command-visualizer/src/vendor/allocate-hats/vendor/getHatRankingContext.ts deleted file mode 100644 index 892d9edb94..0000000000 --- a/packages/command-visualizer/src/vendor/allocate-hats/vendor/getHatRankingContext.ts +++ /dev/null @@ -1,89 +0,0 @@ -/** - * Vendored from cursorless getHatRankingContext.ts, PINNED at SHA - * 42452eba521bb9cccbb3e04a2cd9e9afcf6cbffe. - * - * NOT importable from @cursorless/lib-engine: the current version types its - * third argument as the concrete `TokenGraphemeSplitter` (IDE-backed) and its - * tokens as the engine's full `RankedToken`/`Token`. This copy instead accepts - * the structural `GraphemeSplitter` interface and the simplified Token from - * ../common/types, which is what the offline standalone allocator constructs. - * Its body is otherwise identical to the pin. - * - * Edits are IMPORT REWRITES ONLY: - * - "@cursorless/common" -> "../common" barrel - * - TokenGraphemeSplitter (concrete class) -> GraphemeSplitter (structural - * interface in ../common/types with the same getTokenGraphemes surface) - * - RankedToken: "./getRankedTokens" -> "../common/types" - */ - -import { - CompositeKeyMap, - HatStyleName, - Token, - TokenHat, -} from "../common"; -import { GraphemeSplitter } from "../common/types"; -import { RankedToken } from "../common/types"; - -export interface RankingContext { - /** - * Maps from a hat candidate (grapheme+style combination) to the score of the - * token that used the given hat in the previous hat allocation. - */ - hatOldTokenRanks: CompositeKeyMap< - { - grapheme: string; - hatStyle: HatStyleName; - }, - number - >; - - /** - * Maps from a grapheme to the list of ranks of the tokens in which the - * given grapheme appears. - */ - graphemeTokenRanks: { - [key: string]: number[]; - }; -} - -export function getHatRankingContext( - tokens: RankedToken[], - oldTokenHatMap: CompositeKeyMap<Token, TokenHat>, - tokenGraphemeSplitter: GraphemeSplitter, -): RankingContext { - const graphemeTokenRanks: { - [key: string]: number[]; - } = {}; - - const hatOldTokenRanks = new CompositeKeyMap< - { grapheme: string; hatStyle: HatStyleName }, - number - >(({ grapheme, hatStyle }) => [grapheme, hatStyle]); - - tokens.forEach(({ token, rank }) => { - const existingTokenHat = oldTokenHatMap.get(token); - if (existingTokenHat != null) { - hatOldTokenRanks.set(existingTokenHat, rank); - } - tokenGraphemeSplitter - .getTokenGraphemes(token.text) - .forEach(({ text: graphemeText }) => { - let tokenRanksForGrapheme: number[]; - - if (graphemeText in graphemeTokenRanks) { - tokenRanksForGrapheme = graphemeTokenRanks[graphemeText]; - } else { - tokenRanksForGrapheme = []; - graphemeTokenRanks[graphemeText] = tokenRanksForGrapheme; - } - - tokenRanksForGrapheme.push(rank); - }); - }); - - return { - hatOldTokenRanks, - graphemeTokenRanks, - }; -} diff --git a/packages/command-visualizer/src/vendor/allocate-hats/vendor/getTokenComparator.ts b/packages/command-visualizer/src/vendor/allocate-hats/vendor/getTokenComparator.ts deleted file mode 100644 index 271b6061c4..0000000000 --- a/packages/command-visualizer/src/vendor/allocate-hats/vendor/getTokenComparator.ts +++ /dev/null @@ -1,56 +0,0 @@ -/** - * Vendored from cursorless getTokenComparator.ts (byte-identical to both the - * pin at SHA 42452eba521bb9cccbb3e04a2cd9e9afcf6cbffe and current upstream). - * - * Kept local rather than imported from @cursorless/lib-engine because the - * engine version types `TokenWithDisplayLine extends Token` against - * lib-common's FULL `Token` (editor.document, method-bearing Range, ...). The - * standalone allocator builds its comparator input from the SIMPLIFIED Token - * in ../common/types, which is not assignable to lib-common's Token, so the - * imported signature would not typecheck against rank.ts's call site. The - * regex and the pure-generic maxByFirstDiffering ARE imported from source; - * this one stays local for that type-compatibility reason only. - * - * Edits are IMPORT REWRITES ONLY: - * - "@cursorless/common" -> "../common" barrel - */ - -import { Token } from "../common"; - -interface TokenWithDisplayLine extends Token { - displayLine: number; -} - -/** - * Gets a comparison function that can be used to sort tokens based on their - * distance from the current cursor in terms of display lines. - * @param selectionDisplayLine The display line of the cursor location - * @param selectionCharacterIndex The character index of current cursor within line - */ -export function getTokenComparator( - selectionDisplayLine: number, - selectionCharacterIndex: number, -): (a: TokenWithDisplayLine, b: TokenWithDisplayLine) => number { - return (token1, token2) => { - const token1LineDiff = Math.abs(token1.displayLine - selectionDisplayLine); - const token2LineDiff = Math.abs(token2.displayLine - selectionDisplayLine); - - if (token1LineDiff < token2LineDiff) { - return -1; - } - - if (token1LineDiff > token2LineDiff) { - return 1; - } - - const token1CharacterDiff = Math.abs( - token1.range.start.character - selectionCharacterIndex, - ); - - const token2CharacterDiff = Math.abs( - token2.range.start.character - selectionCharacterIndex, - ); - - return token1CharacterDiff - token2CharacterDiff; - }; -} diff --git a/packages/command-visualizer/src/word-segments.ts b/packages/command-visualizer/src/word-segments.ts deleted file mode 100644 index ef90c4e191..0000000000 --- a/packages/command-visualizer/src/word-segments.ts +++ /dev/null @@ -1,73 +0,0 @@ -// Word-level token segmentation over the per-grapheme render tokens. -// -// The render model is one Token per GRAPHEME (tokenize.ts R5 — column math -// needs it). But cursorless ALLOCATES per word-level token: "value" is one -// token wearing ONE hat, not five (task-mim correction, 2026-07-07 — the R5 -// "dense hatting = every grapheme" reading was wrong; upstream hats every -// TOKEN, anchored at one grapheme). -// -// Segmentation approximates cursorless's default tokenizer: maximal runs of -// word characters (letters / marks / digits / underscore) form one segment; -// every other non-whitespace grapheme is its own single-grapheme segment. - -import type { Line, Token } from "./columns"; - -const WORD_CHAR = /^[\p{L}\p{M}\p{N}_]+$/u; - -export interface WordSegment { - /** Grapheme render-tokens composing this word-level token, in order. */ - graphemes: Token[]; - /** Concatenated text of the segment. */ - text: string; - /** Line-relative start offset (== graphemes[0].range.start). */ - start: number; - lineIdx: number; -} - -/** True for tokens that can carry a hat at all (non-whitespace grapheme). */ -export function isHattableGrapheme(token: Token): boolean { - return token.text.trim().length > 0; -} - -/** - * Group a line's grapheme tokens into word-level segments. Consecutive - * word-character graphemes with ADJACENT ranges merge; everything else - * (punctuation, symbols) stands alone. - */ -export function segmentLine(line: Line, lineIdx: number): WordSegment[] { - const segments: WordSegment[] = []; - let current: WordSegment | null = null; - - for (const token of line.tokens) { - if (!isHattableGrapheme(token)) { - current = null; - continue; - } - const isWord = WORD_CHAR.test(token.text); - const adjacent = - current != null && - current.graphemes[current.graphemes.length - 1].range.end === - token.range.start; - - if (isWord && current != null && adjacent) { - current.graphemes.push(token); - current.text += token.text; - continue; - } - - const seg: WordSegment = { - graphemes: [token], - text: token.text, - start: token.range.start, - lineIdx, - }; - segments.push(seg); - current = isWord ? seg : null; - } - - return segments; -} - -export function segmentLines(lines: Line[]): WordSegment[] { - return lines.flatMap((line, i) => segmentLine(line, i)); -} From d15af2d5b43908ea569d38dcf5a9fe528be30e90 Mon Sep 17 00:00:00 2001 From: Trillium Smith <trillium@trilliumsmith.com> Date: Wed, 8 Jul 2026 08:57:08 -0700 Subject: [PATCH 25/53] test(command-visualizer): smoke-test real-engine hat allocation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds hat-allocator.test.ts covering the de-vendored allocator: - at least one hat is placed over a couple of words - hats land on non-whitespace graphemes with valid palette colors - a pre-attached fixture-mark hat keeps its exact color (single mark, multiple marks across lines) — pins verified via forceTokenHats - allocation is deterministic for identical input - empty document is a no-op, not a throw - cssStateHatStyles keys pure colors and +1-penalty shape variants This is the correctness evidence for the refactor in lieu of oracle screenshots. 7 passing. --- .../src/hat-allocator.test.ts | 139 ++++++++++++++++++ 1 file changed, 139 insertions(+) create mode 100644 packages/command-visualizer/src/hat-allocator.test.ts diff --git a/packages/command-visualizer/src/hat-allocator.test.ts b/packages/command-visualizer/src/hat-allocator.test.ts new file mode 100644 index 0000000000..4f16092ba3 --- /dev/null +++ b/packages/command-visualizer/src/hat-allocator.test.ts @@ -0,0 +1,139 @@ +import assert from "node:assert/strict"; +import type { HatColor } from "@cursorless/lib-common"; +import { allocateHats, cssStateHatStyles } from "./hat-allocator"; +import type { InputHat, Line, Token } from "./columns"; + +// Build a Line whose tokens are one-per-grapheme (the render model, tokenize.ts +// R5) with line-relative UTF-16 ranges. Spaces are emitted as their own tokens +// so offsets stay contiguous, matching what buildLines/tokenizeDoc produces. +function line(text: string): Line { + const tokens: Token[] = []; + for (let i = 0; i < text.length; i++) { + tokens.push({ text: text[i], range: { start: i, end: i + 1 } }); + } + return { tokens }; +} + +/** Attach a fixture-mark hat to the token starting at `character` on `line`. */ +function markToken(l: Line, character: number, hat: InputHat): Token { + const token = l.tokens.find((t) => t.range.start === character); + assert.ok(token, `no token at character ${character}`); + token.hat = hat; + return token; +} + +function countHatted(lines: Line[]): number { + return lines.reduce( + (n, l) => n + l.tokens.filter((t) => t.hat != null).length, + 0, + ); +} + +suite("command-visualizer/hat-allocator", () => { + suite("cssStateHatStyles", () => { + test("keys pure colors and color-shape variants with penalty ordering", () => { + const styles = cssStateHatStyles(); + // Pure color exists and is default-shape (bare key). + assert.ok(styles.blue, "expected a bare 'blue' style"); + // Shaped variant exists and carries +1 penalty over its color. + assert.ok(styles["blue-fox"], "expected a 'blue-fox' style"); + assert.equal(styles["blue-fox"].penalty, styles.blue.penalty + 1); + // 'default' color has the lowest penalty. + assert.equal(styles.default.penalty, 0); + }); + }); + + suite("allocateHats", () => { + test("assigns at least one hat over a couple of words", () => { + const lines = [line("value width")]; + allocateHats(lines); + assert.ok( + countHatted(lines) >= 1, + "expected the real allocator to place at least one hat", + ); + }); + + test("hats land on real graphemes, with a valid palette style", () => { + const lines = [line("alpha bravo")]; + allocateHats(lines); + const styles = cssStateHatStyles(); + const validColors = new Set<string>( + Object.keys(styles).map((k) => k.split("-")[0]), + ); + for (const l of lines) { + for (const t of l.tokens) { + if (t.hat == null) { + continue; + } + // A hatted token must be a non-whitespace grapheme. + assert.ok( + t.text.trim().length > 0, + `hat landed on whitespace token "${t.text}"`, + ); + // Its color must be a real palette color. + assert.ok( + validColors.has(t.hat.color), + `hat color "${t.hat.color}" not in palette`, + ); + } + } + }); + + test("a pre-attached fixture-mark hat keeps its exact color", () => { + // Two words; pin the first grapheme of "world" to a specific color, then + // let the allocator fill the rest. The pinned mark must survive with the + // same color it went in with. + const l = line("hello world"); + const pinnedColor: HatColor = "yellow"; + const worldStart = "hello ".length; // char index of "w" + const marked = markToken(l, worldStart, { + color: pinnedColor, + shape: "default", + }); + + allocateHats([l]); + + assert.ok(marked.hat, "pinned mark lost its hat entirely"); + assert.equal( + marked.hat.color, + pinnedColor, + `pinned mark color changed from ${pinnedColor} to ${marked.hat.color}`, + ); + }); + + test("multiple pinned marks each keep their color across lines", () => { + const l0 = line("red apple"); + const l1 = line("blue sky"); + const m0 = markToken(l0, 0, { color: "red", shape: "default" }); + const m1 = markToken(l1, 0, { color: "blue", shape: "default" }); + + allocateHats([l0, l1]); + + assert.equal(m0.hat?.color, "red", "first pinned mark changed color"); + assert.equal(m1.hat?.color, "blue", "second pinned mark changed color"); + }); + + test("is deterministic: same input yields the same assignment", () => { + const build = () => [line("value width height")]; + const a = build(); + const b = build(); + allocateHats(a); + allocateHats(b); + + const snapshot = (lines: Line[]) => + lines.map((l) => + l.tokens.map((t) => + t.hat ? `${t.range.start}:${t.hat.color}/${t.hat.shape}` : "", + ), + ); + + assert.deepEqual(snapshot(a), snapshot(b)); + }); + + test("empty document does not throw and hats nothing", () => { + const lines = [line("")]; + allocateHats(lines); + assert.equal(countHatted(lines), 0); + }); + }); +}); From bc06e1e205d9427b7173d1f94920996cbaf438a2 Mon Sep 17 00:00:00 2001 From: Trillium Smith <trillium@trilliumsmith.com> Date: Wed, 8 Jul 2026 09:09:10 -0700 Subject: [PATCH 26/53] refactor(command-visualizer): extract model/ scope (shared pure contract) Move the shared, pure, HTML-free contract into model/: frame-state, columns, overlays, timeline. Add model/geometry.ts extracting the Pos and Range interfaces plus the orderRange helper out of the old serialize.ts so both logic/ and render/ depend on geometry without either importing the other. Repoint intra-model and data/ imports. Pure relocation + import rewrite; no behavior change. --- .../src/{ => logic}/chain.test.ts | 0 .../src/{ => logic}/chain.ts | 0 .../src/{ => logic}/fixture-extract.ts | 0 .../src/{ => logic}/fixture-root.ts | 0 .../src/{ => logic}/fixture-yaml.test.ts | 0 .../src/{ => logic}/fixture-yaml.ts | 0 .../src/{ => logic}/hat-allocator.test.ts | 0 .../src/{ => logic}/hat-allocator.ts | 0 .../src/{ => logic}/pipeline.ts | 0 .../src/{ => logic}/tokenize.ts | 0 .../src/{ => model}/columns.ts | 0 .../src/{ => model}/frame-state.ts | 6 ++--- .../command-visualizer/src/model/geometry.ts | 23 +++++++++++++++++++ .../src/{ => model}/overlays.ts | 6 ++--- .../src/{ => model}/timeline.ts | 0 .../src/{ => render}/css-cascade.ts | 0 .../src/{ => render}/css.ts | 0 .../src/{ => render}/html.test.ts | 0 .../src/{ => render}/html.ts | 0 .../src/{ => render}/jumbotron.ts | 0 .../src/{ => render}/serialize-cascade.ts | 0 .../src/{ => render}/serialize.ts | 0 .../src/{ => render}/svg-wrap.ts | 0 .../src/{ => render}/symbols.ts | 0 24 files changed, 29 insertions(+), 6 deletions(-) rename packages/command-visualizer/src/{ => logic}/chain.test.ts (100%) rename packages/command-visualizer/src/{ => logic}/chain.ts (100%) rename packages/command-visualizer/src/{ => logic}/fixture-extract.ts (100%) rename packages/command-visualizer/src/{ => logic}/fixture-root.ts (100%) rename packages/command-visualizer/src/{ => logic}/fixture-yaml.test.ts (100%) rename packages/command-visualizer/src/{ => logic}/fixture-yaml.ts (100%) rename packages/command-visualizer/src/{ => logic}/hat-allocator.test.ts (100%) rename packages/command-visualizer/src/{ => logic}/hat-allocator.ts (100%) rename packages/command-visualizer/src/{ => logic}/pipeline.ts (100%) rename packages/command-visualizer/src/{ => logic}/tokenize.ts (100%) rename packages/command-visualizer/src/{ => model}/columns.ts (100%) rename packages/command-visualizer/src/{ => model}/frame-state.ts (91%) create mode 100644 packages/command-visualizer/src/model/geometry.ts rename packages/command-visualizer/src/{ => model}/overlays.ts (96%) rename packages/command-visualizer/src/{ => model}/timeline.ts (100%) rename packages/command-visualizer/src/{ => render}/css-cascade.ts (100%) rename packages/command-visualizer/src/{ => render}/css.ts (100%) rename packages/command-visualizer/src/{ => render}/html.test.ts (100%) rename packages/command-visualizer/src/{ => render}/html.ts (100%) rename packages/command-visualizer/src/{ => render}/jumbotron.ts (100%) rename packages/command-visualizer/src/{ => render}/serialize-cascade.ts (100%) rename packages/command-visualizer/src/{ => render}/serialize.ts (100%) rename packages/command-visualizer/src/{ => render}/svg-wrap.ts (100%) rename packages/command-visualizer/src/{ => render}/symbols.ts (100%) diff --git a/packages/command-visualizer/src/chain.test.ts b/packages/command-visualizer/src/logic/chain.test.ts similarity index 100% rename from packages/command-visualizer/src/chain.test.ts rename to packages/command-visualizer/src/logic/chain.test.ts diff --git a/packages/command-visualizer/src/chain.ts b/packages/command-visualizer/src/logic/chain.ts similarity index 100% rename from packages/command-visualizer/src/chain.ts rename to packages/command-visualizer/src/logic/chain.ts diff --git a/packages/command-visualizer/src/fixture-extract.ts b/packages/command-visualizer/src/logic/fixture-extract.ts similarity index 100% rename from packages/command-visualizer/src/fixture-extract.ts rename to packages/command-visualizer/src/logic/fixture-extract.ts diff --git a/packages/command-visualizer/src/fixture-root.ts b/packages/command-visualizer/src/logic/fixture-root.ts similarity index 100% rename from packages/command-visualizer/src/fixture-root.ts rename to packages/command-visualizer/src/logic/fixture-root.ts diff --git a/packages/command-visualizer/src/fixture-yaml.test.ts b/packages/command-visualizer/src/logic/fixture-yaml.test.ts similarity index 100% rename from packages/command-visualizer/src/fixture-yaml.test.ts rename to packages/command-visualizer/src/logic/fixture-yaml.test.ts diff --git a/packages/command-visualizer/src/fixture-yaml.ts b/packages/command-visualizer/src/logic/fixture-yaml.ts similarity index 100% rename from packages/command-visualizer/src/fixture-yaml.ts rename to packages/command-visualizer/src/logic/fixture-yaml.ts diff --git a/packages/command-visualizer/src/hat-allocator.test.ts b/packages/command-visualizer/src/logic/hat-allocator.test.ts similarity index 100% rename from packages/command-visualizer/src/hat-allocator.test.ts rename to packages/command-visualizer/src/logic/hat-allocator.test.ts diff --git a/packages/command-visualizer/src/hat-allocator.ts b/packages/command-visualizer/src/logic/hat-allocator.ts similarity index 100% rename from packages/command-visualizer/src/hat-allocator.ts rename to packages/command-visualizer/src/logic/hat-allocator.ts diff --git a/packages/command-visualizer/src/pipeline.ts b/packages/command-visualizer/src/logic/pipeline.ts similarity index 100% rename from packages/command-visualizer/src/pipeline.ts rename to packages/command-visualizer/src/logic/pipeline.ts diff --git a/packages/command-visualizer/src/tokenize.ts b/packages/command-visualizer/src/logic/tokenize.ts similarity index 100% rename from packages/command-visualizer/src/tokenize.ts rename to packages/command-visualizer/src/logic/tokenize.ts diff --git a/packages/command-visualizer/src/columns.ts b/packages/command-visualizer/src/model/columns.ts similarity index 100% rename from packages/command-visualizer/src/columns.ts rename to packages/command-visualizer/src/model/columns.ts diff --git a/packages/command-visualizer/src/frame-state.ts b/packages/command-visualizer/src/model/frame-state.ts similarity index 91% rename from packages/command-visualizer/src/frame-state.ts rename to packages/command-visualizer/src/model/frame-state.ts index fecc961242..78fd72d14b 100644 --- a/packages/command-visualizer/src/frame-state.ts +++ b/packages/command-visualizer/src/model/frame-state.ts @@ -2,10 +2,10 @@ // `.cl-editor` surface (EditorState minus the doc-level theme/tab). v2 wraps an // ordered list of frames in a cascade and adds the decoration OVERLAY layer. -import type { Theme } from "./data/colors"; +import type { Theme } from "../data/colors"; import type { Line } from "./columns"; -import type { Pos, Range } from "./serialize"; -import type { DecorationStyle } from "./data/decorations"; +import type { Pos, Range } from "./geometry"; +import type { DecorationStyle } from "../data/decorations"; export type FrameRole = "before" | "during" | "after"; diff --git a/packages/command-visualizer/src/model/geometry.ts b/packages/command-visualizer/src/model/geometry.ts new file mode 100644 index 0000000000..65c86f0d48 --- /dev/null +++ b/packages/command-visualizer/src/model/geometry.ts @@ -0,0 +1,23 @@ +// Geometry primitives — shared position/range model. Pure, no HTML, no logic. +// Extracted from serialize.ts so both `logic/` and `render/` can depend on these +// without either scope importing the other (see ARCHITECTURE.md). + +export interface Pos { + line: number; + character: number; // UTF-16 char index within the line +} + +export interface Range { + start: Pos; + end: Pos; +} + +/** Normalize a range so `start` precedes `end` in document order. */ +export function orderRange(r: Range): Range { + const a = r.start; + const b = r.end; + if (a.line < b.line || (a.line === b.line && a.character <= b.character)) { + return r; + } + return { start: b, end: a }; +} diff --git a/packages/command-visualizer/src/overlays.ts b/packages/command-visualizer/src/model/overlays.ts similarity index 96% rename from packages/command-visualizer/src/overlays.ts rename to packages/command-visualizer/src/model/overlays.ts index dc7ad2f72b..42bff4351e 100644 --- a/packages/command-visualizer/src/overlays.ts +++ b/packages/command-visualizer/src/model/overlays.ts @@ -5,9 +5,9 @@ import { type Column, expandColumns } from "./columns"; import type { Decoration, Frame, OverlayRole } from "./frame-state"; -import type { DecorationStyle } from "./data/decorations"; -import { overlayPrecedence } from "./data/decorations"; -import type { Range } from "./serialize"; +import type { DecorationStyle } from "../data/decorations"; +import { overlayPrecedence } from "../data/decorations"; +import type { Range } from "./geometry"; // Role sub-rank, used to break style-precedence ties (SPEC-v2 §3.2 / DECISIONS // §7.1+§7.2): a REAL ide.flash outranks a DERIVED that/source overlay on the diff --git a/packages/command-visualizer/src/timeline.ts b/packages/command-visualizer/src/model/timeline.ts similarity index 100% rename from packages/command-visualizer/src/timeline.ts rename to packages/command-visualizer/src/model/timeline.ts diff --git a/packages/command-visualizer/src/css-cascade.ts b/packages/command-visualizer/src/render/css-cascade.ts similarity index 100% rename from packages/command-visualizer/src/css-cascade.ts rename to packages/command-visualizer/src/render/css-cascade.ts diff --git a/packages/command-visualizer/src/css.ts b/packages/command-visualizer/src/render/css.ts similarity index 100% rename from packages/command-visualizer/src/css.ts rename to packages/command-visualizer/src/render/css.ts diff --git a/packages/command-visualizer/src/html.test.ts b/packages/command-visualizer/src/render/html.test.ts similarity index 100% rename from packages/command-visualizer/src/html.test.ts rename to packages/command-visualizer/src/render/html.test.ts diff --git a/packages/command-visualizer/src/html.ts b/packages/command-visualizer/src/render/html.ts similarity index 100% rename from packages/command-visualizer/src/html.ts rename to packages/command-visualizer/src/render/html.ts diff --git a/packages/command-visualizer/src/jumbotron.ts b/packages/command-visualizer/src/render/jumbotron.ts similarity index 100% rename from packages/command-visualizer/src/jumbotron.ts rename to packages/command-visualizer/src/render/jumbotron.ts diff --git a/packages/command-visualizer/src/serialize-cascade.ts b/packages/command-visualizer/src/render/serialize-cascade.ts similarity index 100% rename from packages/command-visualizer/src/serialize-cascade.ts rename to packages/command-visualizer/src/render/serialize-cascade.ts diff --git a/packages/command-visualizer/src/serialize.ts b/packages/command-visualizer/src/render/serialize.ts similarity index 100% rename from packages/command-visualizer/src/serialize.ts rename to packages/command-visualizer/src/render/serialize.ts diff --git a/packages/command-visualizer/src/svg-wrap.ts b/packages/command-visualizer/src/render/svg-wrap.ts similarity index 100% rename from packages/command-visualizer/src/svg-wrap.ts rename to packages/command-visualizer/src/render/svg-wrap.ts diff --git a/packages/command-visualizer/src/symbols.ts b/packages/command-visualizer/src/render/symbols.ts similarity index 100% rename from packages/command-visualizer/src/symbols.ts rename to packages/command-visualizer/src/render/symbols.ts From dbd5966725dab9272de0ec7f151e526a49955c58 Mon Sep 17 00:00:00 2001 From: Trillium Smith <trillium@trilliumsmith.com> Date: Wed, 8 Jul 2026 09:09:32 -0700 Subject: [PATCH 27/53] refactor(command-visualizer): rewire logic/ imports to model/ Repoint logic/ (pipeline, fixture-extract, hat-allocator, tokenize, chain + their tests) at ../model/* and ../data/* for the shared contract and constants. Pos/Range now come from ../model/geometry. No logic/ file imports render/. Pure import rewrite; no behavior change. --- packages/command-visualizer/src/logic/chain.test.ts | 2 +- packages/command-visualizer/src/logic/chain.ts | 2 +- packages/command-visualizer/src/logic/fixture-extract.ts | 6 +++--- .../command-visualizer/src/logic/hat-allocator.test.ts | 2 +- packages/command-visualizer/src/logic/hat-allocator.ts | 4 ++-- packages/command-visualizer/src/logic/pipeline.ts | 8 ++++---- packages/command-visualizer/src/logic/tokenize.ts | 2 +- 7 files changed, 13 insertions(+), 13 deletions(-) diff --git a/packages/command-visualizer/src/logic/chain.test.ts b/packages/command-visualizer/src/logic/chain.test.ts index 3adf9601d1..097d0cfeff 100644 --- a/packages/command-visualizer/src/logic/chain.test.ts +++ b/packages/command-visualizer/src/logic/chain.test.ts @@ -1,6 +1,6 @@ import assert from "node:assert/strict"; import { chainCascades, ChainContinuityError } from "./chain"; -import type { CascadeState, Frame } from "./frame-state"; +import type { CascadeState, Frame } from "../model/frame-state"; function beforeFrame(): Frame { return { diff --git a/packages/command-visualizer/src/logic/chain.ts b/packages/command-visualizer/src/logic/chain.ts index ebeda1b132..1e7ee09833 100644 --- a/packages/command-visualizer/src/logic/chain.ts +++ b/packages/command-visualizer/src/logic/chain.ts @@ -16,7 +16,7 @@ // the merged frame's slot END, // - carries step i's produced clipboard when step {i+1} has none. -import type { CascadeState, Frame } from "./frame-state"; +import type { CascadeState, Frame } from "../model/frame-state"; /** * Pre-gif / post-gif bumpers: a 500ms PRE frame (initial state, before step 0 diff --git a/packages/command-visualizer/src/logic/fixture-extract.ts b/packages/command-visualizer/src/logic/fixture-extract.ts index 4f14f372fb..4d22c0506a 100644 --- a/packages/command-visualizer/src/logic/fixture-extract.ts +++ b/packages/command-visualizer/src/logic/fixture-extract.ts @@ -6,9 +6,9 @@ import type { YamlValue } from "./fixture-yaml"; import { tokenizeDoc } from "./tokenize"; import type { HatColor, HatShape } from "@cursorless/lib-common"; import { HAT_COLORS } from "@cursorless/lib-common"; -import type { Line, Token, InputHat } from "./columns"; -import type { GeneralizedRange } from "./frame-state"; -import type { Pos, Range } from "./serialize"; +import type { Line, Token, InputHat } from "../model/columns"; +import type { GeneralizedRange } from "../model/frame-state"; +import type { Pos, Range } from "../model/geometry"; import { allocateHats } from "./hat-allocator"; export type Obj = Record<string, YamlValue>; diff --git a/packages/command-visualizer/src/logic/hat-allocator.test.ts b/packages/command-visualizer/src/logic/hat-allocator.test.ts index 4f16092ba3..bf40c59500 100644 --- a/packages/command-visualizer/src/logic/hat-allocator.test.ts +++ b/packages/command-visualizer/src/logic/hat-allocator.test.ts @@ -1,7 +1,7 @@ import assert from "node:assert/strict"; import type { HatColor } from "@cursorless/lib-common"; import { allocateHats, cssStateHatStyles } from "./hat-allocator"; -import type { InputHat, Line, Token } from "./columns"; +import type { InputHat, Line, Token } from "../model/columns"; // Build a Line whose tokens are one-per-grapheme (the render model, tokenize.ts // R5) with line-relative UTF-16 ranges. Spaces are emitted as their own tokens diff --git a/packages/command-visualizer/src/logic/hat-allocator.ts b/packages/command-visualizer/src/logic/hat-allocator.ts index c4052fc265..737ffde7a1 100644 --- a/packages/command-visualizer/src/logic/hat-allocator.ts +++ b/packages/command-visualizer/src/logic/hat-allocator.ts @@ -50,8 +50,8 @@ import { } from "@cursorless/lib-engine"; import type { HatColor, HatShape } from "@cursorless/lib-common"; import { HAT_COLORS, HAT_SHAPES } from "@cursorless/lib-common"; -import type { Line, Token as RenderToken } from "./columns"; -import type { Pos } from "./serialize"; +import type { Line, Token as RenderToken } from "../model/columns"; +import type { Pos } from "../model/geometry"; // --------------------------------------------------------------------------- // Style map: our full palette x (default + 10 shapes), penalty-ordered the way diff --git a/packages/command-visualizer/src/logic/pipeline.ts b/packages/command-visualizer/src/logic/pipeline.ts index 33bb7065d8..93b11628c1 100644 --- a/packages/command-visualizer/src/logic/pipeline.ts +++ b/packages/command-visualizer/src/logic/pipeline.ts @@ -6,14 +6,14 @@ import { readFileSync } from "node:fs"; import type { HatColor, HatShape } from "@cursorless/lib-common"; import { parseFixtureYaml } from "./fixture-yaml"; -import type { Theme } from "./data/colors"; +import type { Theme } from "../data/colors"; import type { CascadeState, Frame, GeneralizedRange, -} from "./frame-state"; -import type { DecorationStyle } from "./data/decorations"; -import type { Pos } from "./serialize"; +} from "../model/frame-state"; +import type { DecorationStyle } from "../data/decorations"; +import type { Pos } from "../model/geometry"; import { asArr, asObj, diff --git a/packages/command-visualizer/src/logic/tokenize.ts b/packages/command-visualizer/src/logic/tokenize.ts index b7dd875a54..f7d9bf3843 100644 --- a/packages/command-visualizer/src/logic/tokenize.ts +++ b/packages/command-visualizer/src/logic/tokenize.ts @@ -19,7 +19,7 @@ // stays byte-exact. The roundtrip test (src/verify-roundtrip-doc.ts) proves it. import { GRAPHEME_SPLIT_REGEX } from "@cursorless/lib-engine"; -import type { Line, Token } from "./columns"; +import type { Line, Token } from "../model/columns"; // Cursorless grapheme splitter: a base letter + its combining marks is ONE // grapheme; each number / punctuation / symbol is its own grapheme. The regex From 81f984f04962b6d95a62a95472f0618798a79495 Mon Sep 17 00:00:00 2001 From: Trillium Smith <trillium@trilliumsmith.com> Date: Wed, 8 Jul 2026 09:09:38 -0700 Subject: [PATCH 28/53] refactor(command-visualizer): rewire render/ imports to model/ Repoint render/ (serialize, serialize-cascade, svg-wrap, jumbotron, css, css-cascade, symbols, html) at ../model/* and ../data/*. serialize.ts now imports Pos/Range/orderRange from ../model/geometry instead of declaring them locally. No render/ file imports logic/. Pure import rewrite; no behavior change. --- .../src/render/css-cascade.ts | 10 ++++---- packages/command-visualizer/src/render/css.ts | 2 +- .../command-visualizer/src/render/html.ts | 2 +- .../src/render/jumbotron.ts | 6 ++--- .../src/render/serialize-cascade.ts | 12 +++++----- .../src/render/serialize.ts | 24 ++++--------------- .../command-visualizer/src/render/svg-wrap.ts | 2 +- .../command-visualizer/src/render/symbols.ts | 2 +- 8 files changed, 22 insertions(+), 38 deletions(-) diff --git a/packages/command-visualizer/src/render/css-cascade.ts b/packages/command-visualizer/src/render/css-cascade.ts index 812ee48f99..b2126a2424 100644 --- a/packages/command-visualizer/src/render/css-cascade.ts +++ b/packages/command-visualizer/src/render/css-cascade.ts @@ -2,11 +2,11 @@ // opacity timeline). Generated from the single-sourced decoration hexes so the // band colors never drift. Theme-INVARIANT (background-only translucent hexes). -import { DECORATION_HEX, ALL_DECORATION_STYLES } from "./data/decorations"; -import { FLASH_STYLES, HIGHLIGHT_STYLES } from "./data/decorations"; -import { FLASH_PULSE_MS } from "./data/decorations"; -import type { Frame } from "./frame-state"; -import { timelineOf, type Timeline } from "./timeline"; +import { DECORATION_HEX, ALL_DECORATION_STYLES } from "../data/decorations"; +import { FLASH_STYLES, HIGHLIGHT_STYLES } from "../data/decorations"; +import { FLASH_PULSE_MS } from "../data/decorations"; +import type { Frame } from "../model/frame-state"; +import { timelineOf, type Timeline } from "../model/timeline"; // §3.2 — char-range bands on the per-char grid (one bg attr per .ch). // The STATIC path (single-frame PNG renders, animate=false): the band is just a diff --git a/packages/command-visualizer/src/render/css.ts b/packages/command-visualizer/src/render/css.ts index d3360fee91..91bf7677d1 100644 --- a/packages/command-visualizer/src/render/css.ts +++ b/packages/command-visualizer/src/render/css.ts @@ -8,7 +8,7 @@ import { HAT_COLORS, HAT_SHAPES, } from "@cursorless/lib-common"; -import { COLOR_MATRIX, EDITOR_CHROME } from "./data/colors"; +import { COLOR_MATRIX, EDITOR_CHROME } from "../data/colors"; function shapeAdjustmentRules(): string { const lines: string[] = [ diff --git a/packages/command-visualizer/src/render/html.ts b/packages/command-visualizer/src/render/html.ts index 1d4f97a93e..0efbe0d97c 100644 --- a/packages/command-visualizer/src/render/html.ts +++ b/packages/command-visualizer/src/render/html.ts @@ -4,7 +4,7 @@ // of sync — three of the four copies had differing quote-escaping before this // was consolidated). -import type { CascadeState } from "./frame-state"; +import type { CascadeState } from "../model/frame-state"; /** * HTML escaper safe for BOTH text content AND quoted-attribute contexts. diff --git a/packages/command-visualizer/src/render/jumbotron.ts b/packages/command-visualizer/src/render/jumbotron.ts index eb2edeb64e..5726c6024e 100644 --- a/packages/command-visualizer/src/render/jumbotron.ts +++ b/packages/command-visualizer/src/render/jumbotron.ts @@ -19,9 +19,9 @@ // required. Interactive Controls (pause / highlight toggles) are NOT portable // to SVG-as-image and are intentionally omitted. -import type { CascadeState } from "./frame-state"; -import { MS_PER_STATE } from "./data/decorations"; -import { frameDurMs, timelineOf } from "./timeline"; +import type { CascadeState } from "../model/frame-state"; +import { MS_PER_STATE } from "../data/decorations"; +import { frameDurMs, timelineOf } from "../model/timeline"; import { esc } from "./html"; const NL = String.fromCharCode(10); diff --git a/packages/command-visualizer/src/render/serialize-cascade.ts b/packages/command-visualizer/src/render/serialize-cascade.ts index e7c1c564b1..48514f6a75 100644 --- a/packages/command-visualizer/src/render/serialize-cascade.ts +++ b/packages/command-visualizer/src/render/serialize-cascade.ts @@ -3,16 +3,16 @@ // per-frame `@keyframes f{k}` opacity timeline, and the decoration overlay layer // (data-flash / data-hl / data-line-flash) resolved single-winner per cell. -import { type Column, expandColumns, lineWidth } from "./columns"; +import { type Column, expandColumns, lineWidth } from "../model/columns"; import { styleSheet } from "./css"; import { cascadeStyleSheet, cascadeThemeBridge } from "./css-cascade"; import { jumbotronCss, serializeJumbotron } from "./jumbotron"; -import type { CellOverlay } from "./overlays"; +import type { CellOverlay } from "../model/overlays"; import { symbolSheet } from "./symbols"; -import type { CascadeState, Frame } from "./frame-state"; -import { resolveFrameOverlays, type LineOverlay } from "./overlays"; -import { HIGHLIGHT_STYLES, MS_PER_STATE } from "./data/decorations"; -import { timelineOf } from "./timeline"; +import type { CascadeState, Frame } from "../model/frame-state"; +import { resolveFrameOverlays, type LineOverlay } from "../model/overlays"; +import { HIGHLIGHT_STYLES, MS_PER_STATE } from "../data/decorations"; +import { timelineOf } from "../model/timeline"; import { captionHtml, esc, themeBackground } from "./html"; function charToCol(cols: Column[], charIndex: number): number { diff --git a/packages/command-visualizer/src/render/serialize.ts b/packages/command-visualizer/src/render/serialize.ts index 136b57f5e0..1d5c434a4b 100644 --- a/packages/command-visualizer/src/render/serialize.ts +++ b/packages/command-visualizer/src/render/serialize.ts @@ -1,20 +1,13 @@ // Serializer — SPEC §5. Pure state JSON → HTML string. No render-time logic (D1). -import type { Theme } from "./data/colors"; -import { type Column, type Line, expandColumns, lineWidth } from "./columns"; +import type { Theme } from "../data/colors"; +import { type Column, type Line, expandColumns, lineWidth } from "../model/columns"; +import type { Pos, Range } from "../model/geometry"; +import { orderRange } from "../model/geometry"; import { styleSheet } from "./css"; import { symbolSheet } from "./symbols"; import { esc } from "./html"; -export interface Pos { - line: number; - character: number; // UTF-16 char index within the line -} -export interface Range { - start: Pos; - end: Pos; -} - export interface EditorState { theme: Theme; tabSize: number; @@ -43,15 +36,6 @@ function inAnySelection( return false; } -function orderRange(r: Range): Range { - const a = r.start; - const b = r.end; - if (a.line < b.line || (a.line === b.line && a.character <= b.character)) { - return r; - } - return { start: b, end: a }; -} - /** Map a UTF-16 char index to its visual column on a line (for caret placement). */ function charToCol(cols: Column[], charIndex: number): number { for (const c of cols) { diff --git a/packages/command-visualizer/src/render/svg-wrap.ts b/packages/command-visualizer/src/render/svg-wrap.ts index 3eb51c84e8..d4a3b0dcaf 100644 --- a/packages/command-visualizer/src/render/svg-wrap.ts +++ b/packages/command-visualizer/src/render/svg-wrap.ts @@ -8,7 +8,7 @@ // survives any monospace fallback; the estimate only needs enough slack that // the widest expected monospace advance (~0.62em) never clips. -import type { CascadeState } from "./frame-state"; +import type { CascadeState } from "../model/frame-state"; import { serializeCascade } from "./serialize-cascade"; import { jumbotronCss, serializeJumbotron } from "./jumbotron"; import { styleSheet } from "./css"; diff --git a/packages/command-visualizer/src/render/symbols.ts b/packages/command-visualizer/src/render/symbols.ts index e4191d6944..7a6ba6495a 100644 --- a/packages/command-visualizer/src/render/symbols.ts +++ b/packages/command-visualizer/src/render/symbols.ts @@ -4,7 +4,7 @@ // fill="currentColor" so a hat is tinted by CSS `color` (D4). import { HAT_SHAPES } from "@cursorless/lib-common"; -import { SHAPE_PATHS } from "./data/shapes"; +import { SHAPE_PATHS } from "../data/shapes"; export function symbolSheet(): string { const symbols = HAT_SHAPES.map((shape) => { From 46a4be36d3b6b4ffa9eba76e76dec194907ae0f0 Mon Sep 17 00:00:00 2001 From: Trillium Smith <trillium@trilliumsmith.com> Date: Wed, 8 Jul 2026 09:09:47 -0700 Subject: [PATCH 29/53] refactor(command-visualizer): wire public index to scopes + add ARCHITECTURE.md Repoint the public index.ts exports at ./logic/*, ./render/*, and ./model/*. Add ARCHITECTURE.md documenting the four scopes (data/model/ logic/render), the one-directional dependency rule (logic and render never import each other), and why columns/overlays/timeline live in model/. Pure import rewrite + docs; no behavior change. --- .../command-visualizer/src/ARCHITECTURE.md | 44 +++++++++++++++++++ packages/command-visualizer/src/index.ts | 18 +++++--- 2 files changed, 55 insertions(+), 7 deletions(-) create mode 100644 packages/command-visualizer/src/ARCHITECTURE.md diff --git a/packages/command-visualizer/src/ARCHITECTURE.md b/packages/command-visualizer/src/ARCHITECTURE.md new file mode 100644 index 0000000000..2b90d4b105 --- /dev/null +++ b/packages/command-visualizer/src/ARCHITECTURE.md @@ -0,0 +1,44 @@ +# command-visualizer — source architecture + +A clear separation between **what is visually seen** and **what is under the hood**. + +## The four scopes + +``` +data/ static constants (colors, decorations, shapes) +model/ the shared contract: types + PURE deterministic transforms both sides use +logic/ "under the hood": produces a CascadeState from a fixture (emits ZERO html) +render/ "what is visually seen": CascadeState -> HTML/CSS/SVG +``` + +- `data/` — colors.ts, decorations.ts, shapes.ts +- `model/` — geometry.ts (Pos/Range + orderRange), frame-state.ts (CascadeState/Frame/Decoration/GeneralizedRange), columns.ts (Line/Token/Column geometry), overlays.ts (decoration → column overlay resolution), timeline.ts (frame timing) +- `logic/` — pipeline.ts, fixture-extract.ts, fixture-yaml.ts, fixture-root.ts, tokenize.ts, hat-allocator.ts, chain.ts +- `render/` — serialize.ts, serialize-cascade.ts, svg-wrap.ts, jumbotron.ts, css.ts, css-cascade.ts, symbols.ts, html.ts +- `index.ts` — the public surface; wires logic + render + model exports together. + +## The one-directional dependency rule + +**`render/` must NEVER import from `logic/`, and `logic/` must NEVER import from `render/`.** + +Both scopes may import `model/` and `data/`. `model/` imports only `model/` and `data/`. Nothing imports `index.ts` internally. + +``` + index.ts + / \ + logic/ render/ (siblings — no edge between them) + \ / + model/ + | + data/ +``` + +`columns`, `overlays`, and `timeline` live in `model/` (not `logic/` or `render/`) precisely because they are pure transforms consumed by BOTH sides — placing them in `model/` is what lets the rule hold automatically, so render can resolve every shared dependency without ever reaching into logic. + +## Verifying the rule + +```sh +# both MUST print nothing: +grep -rn 'from "\.\./logic/\|from "\./logic/' packages/command-visualizer/src/render +grep -rn 'from "\.\./render/\|from "\./render/' packages/command-visualizer/src/logic +``` diff --git a/packages/command-visualizer/src/index.ts b/packages/command-visualizer/src/index.ts index 1398265071..16d4d5c9ae 100644 --- a/packages/command-visualizer/src/index.ts +++ b/packages/command-visualizer/src/index.ts @@ -2,19 +2,23 @@ // // fixture YAML in -> animated SVG out. See STATUS.md for integration state. -export { fixtureToCascade, type PipelineOptions } from "./pipeline"; -export { chainCascades, withBumpers, ChainContinuityError } from "./chain"; +export { fixtureToCascade, type PipelineOptions } from "./logic/pipeline"; +export { + chainCascades, + withBumpers, + ChainContinuityError, +} from "./logic/chain"; export { serializeCascade, serializeCascadeDocument, -} from "./serialize-cascade"; -export { wrapCascadeSvg } from "./svg-wrap"; -export { serializeJumbotron, jumbotronCss } from "./jumbotron"; +} from "./render/serialize-cascade"; +export { wrapCascadeSvg } from "./render/svg-wrap"; +export { serializeJumbotron, jumbotronCss } from "./render/jumbotron"; export { timelineOf, frameDurMs, INITIAL_MS, DURING_MS, BUMPER_MS, -} from "./timeline"; -export type { CascadeState, Frame } from "./frame-state"; +} from "./model/timeline"; +export type { CascadeState, Frame } from "./model/frame-state"; From 2c5f85be18594ede2196ee42649dd76aaa398dc3 Mon Sep 17 00:00:00 2001 From: Trillium Smith <trillium@trilliumsmith.com> Date: Wed, 8 Jul 2026 09:15:22 -0700 Subject: [PATCH 30/53] test(command-visualizer): guard SHAPE_PATHS against resources/images/hats MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Makes resources/images/hats/*.svg the enforced source of truth for the hat path data. A headless/bundled renderer can't read those SVGs at runtime, so SHAPE_PATHS keeps byte-for-byte copies — this test reads the canonical SVGs at TEST time and asserts every shape's d= (and crosshairs' fill-rule) still matches, so the copy can never silently drift from source. Runtime stays pure. --- .../src/data/shapes.test.ts | 50 +++++++++++++++++++ 1 file changed, 50 insertions(+) create mode 100644 packages/command-visualizer/src/data/shapes.test.ts diff --git a/packages/command-visualizer/src/data/shapes.test.ts b/packages/command-visualizer/src/data/shapes.test.ts new file mode 100644 index 0000000000..15be756214 --- /dev/null +++ b/packages/command-visualizer/src/data/shapes.test.ts @@ -0,0 +1,50 @@ +import assert from "node:assert/strict"; +import { readFileSync } from "node:fs"; +import { HAT_SHAPES } from "@cursorless/lib-common"; +import { SHAPE_PATHS } from "./shapes"; + +// Single-source guard: SHAPE_PATHS carries byte-for-byte copies of the hat SVG +// `d=` path data, because a headless renderer can't read the .svg files at +// runtime (bundled/serverless path never touches disk). This test makes +// `resources/images/hats/*.svg` the enforced source of truth — if a shape's +// path (or crosshairs' fill-rule) ever drifts from the checked-in copy, this +// fails and points at the exact shape to re-sync. Runtime stays pure; the fs +// read lives here, at test time, only. + +const HATS_DIR = new URL( + "../../../../resources/images/hats/", + import.meta.url, +); + +function svgOf(shape: string): string { + return readFileSync(new URL(`${shape}.svg`, HATS_DIR), "utf8"); +} + +suite("command-visualizer/data/shapes", () => { + test("SHAPE_PATHS covers exactly the hat shapes", () => { + assert.deepEqual( + Object.keys(SHAPE_PATHS).sort(), + [...HAT_SHAPES].sort(), + ); + }); + + test("every SHAPE_PATHS entry matches resources/images/hats/<shape>.svg", () => { + for (const shape of HAT_SHAPES) { + const svg = svgOf(shape); + + const d = /<path[^>]*\sd="([^"]+)"/u.exec(svg)?.[1]; + assert.equal( + SHAPE_PATHS[shape].d, + d, + `d= drift for shape "${shape}" — re-sync from resources/images/hats/${shape}.svg`, + ); + + const fillRule = /fill-rule="([^"]+)"/u.exec(svg)?.[1]; + assert.equal( + SHAPE_PATHS[shape].fillRule, + fillRule, + `fill-rule drift for shape "${shape}"`, + ); + } + }); +}); From 80d3d261c91002d142bee241a3597f1c2242716e Mon Sep 17 00:00:00 2001 From: Trillium Smith <trillium@trilliumsmith.com> Date: Wed, 8 Jul 2026 09:21:51 -0700 Subject: [PATCH 31/53] refactor(command-visualizer): split css-cascade.ts under 250-line limit Extract the flash-fade section (FADE_FRAC, DELETE/ADD/REFERENCE_FLASH_STYLES, flashFadeKeyframes, flashFadeRules) into render/css-cascade-flash.ts. Shared pct() formatter is exported from css-cascade.ts and reused (no duplication). Pure extraction; rendered CSS byte-identical. --- .../src/render/css-cascade-flash.ts | 155 ++++++++++++++++++ .../src/render/css-cascade.ts | 154 +---------------- 2 files changed, 163 insertions(+), 146 deletions(-) create mode 100644 packages/command-visualizer/src/render/css-cascade-flash.ts diff --git a/packages/command-visualizer/src/render/css-cascade-flash.ts b/packages/command-visualizer/src/render/css-cascade-flash.ts new file mode 100644 index 0000000000..13af477da0 --- /dev/null +++ b/packages/command-visualizer/src/render/css-cascade-flash.ts @@ -0,0 +1,155 @@ +// Cascade flash-fade CSS — SPEC-v2 §4.2 DURING beats. Extracted verbatim from +// css-cascade.ts (the flash TIMING section) so the main module stays under the +// 250-line limit. render/ → render/ import only; behavior unchanged. + +import { DECORATION_HEX, FLASH_PULSE_MS } from "../data/decorations"; +import type { Frame } from "../model/frame-state"; +import type { Timeline } from "../model/timeline"; +import { pct } from "./css-cascade"; + +// §4.2 DURING beats — flash TIMING. A flash is a TRANSIENT beat *within* one +// frame's timeline slot, not a static band. Two opposite directions: +// +// DELETE (R2-i, pendingDelete) rides the BEFORE frame (frame 0, slot [0, 1/N]): +// plain (band transparent) → hold plain → red band fades IN +// then the frame's opacity snap crosses to the after-frame (text gone). The band +// fades in LATE in the slot so the before-doc reads plain first, then highlights +// the doomed span just before it vanishes. +// +// ADD (R2-ii, justAdded) rides the AFTER frame (frame N-1, slot [(N-1)/N, 1]): +// green band PRESENT → hold green → green band fades OUT → plain (text stays) +// the insert just happened, so the green is up-front when the after-frame appears, +// then fades out over the latter part of the slot leaving plain text behind. This +// is the mirror image of the delete beat (green out-front, fade to transparent vs. +// red back-end, fade in from transparent). +// +// Both animate ONLY background-color (text stays fully opaque the whole slot); +// CSS-only, zero view-time JS. Each flash style gets its own @keyframes scoped to +// its native frame, so other frames / styles keep the static band. + +const DELETE_FLASH_STYLES = ["pendingDelete"] as const; +const ADD_FLASH_STYLES = ["justAdded"] as const; + +// B2/B6 FIX — the flash is a FIXED 100ms pulse, pinned to cursorless's +// `pendingEditDecorationTime` (FLASH_PULSE_MS), DECOUPLED from the readability +// state-hold cadence. +// +// The cascade timeline is `--dur = N · MS_PER_STATE` ms (serialize-cascade.ts), +// so each of the N frame slots lasts MS_PER_STATE ms. Working in keyframe-% of +// the WHOLE timeline (each @keyframes runs over var(--dur)): +// 1% of timeline = (--dur)/100 ms = (N·MS_PER_STATE)/100 ms +// ⇒ a P-ms window in % = P / (N·MS_PER_STATE) · 100 +// The flash's FULL-target held window is exactly FLASH_PULSE_MS ms → `pulsePct` +// below. A short fade ramp (FADE_FRAC of the pulse) softens each edge but the +// held-full-color span is exactly the pulse, which is what verify:flash-timing +// measures. Result: the pulse is ~100ms for ANY N (no slot scaling). +const FADE_FRAC = 0.4; // soft-edge ramp length as a fraction of the pulse window + +// Reference-class pre-edit flashes (Bring sources/destinations etc.) — they +// sequence BEFORE deletion flashes inside a DURING window (real cursorless +// fires pre-edit flashes in parallel; sequenced here by spec). +const REFERENCE_FLASH_STYLES = [ + "referenced", + "pendingModification0", + "pendingModification1", +] as const; + +export function flashFadeKeyframes( + frames: readonly Frame[], + tl: Timeline, + pulseMs: number = FLASH_PULSE_MS, +): string { + const out: string[] = []; + const pct100 = (x: number) => pct(Math.max(0, Math.min(100, x * 100))); + + frames.forEach((frame, k) => { + const lo = tl.startFrac[k]; + const hi = tl.endFrac[k]; + + if (frame.role === "during") { + // DURING window: reference flashes first, deletion flashes second. + // Halves when both classes are present; the full window otherwise. + const styles = new Set(frame.decorations.map((d) => d.style)); + // The during phase keeps its full duration regardless of content, but + // the FIRST flash class present INITIATES AT THE PHASE START — the + // same instant the command pill goes active. When reference flashes + // exist they take the first half and deletion follows at the midpoint; + // with deletions only, red starts with the pill and holds to the edit. + const hasRef = REFERENCE_FLASH_STYLES.some((st) => + styles.has(st as never), + ); + const mid = (lo + hi) / 2; + const refWin: [number, number] = [lo, mid]; + const delWin: [number, number] = [hasRef ? mid : lo, hi]; + const emit = (style: string, w: [number, number], holdOn: boolean) => { + out.push( + `@keyframes flashfade-${style}-s${k} {\n` + + ` 0% { background-color: transparent; }\n` + + ` ${pct100(w[0])}% { background-color: transparent; }\n` + + ` ${pct100(w[0] + 0.0001)}% { background-color: ${DECORATION_HEX[style as keyof typeof DECORATION_HEX]}; }\n` + + ` ${pct100(w[1])}% { background-color: ${DECORATION_HEX[style as keyof typeof DECORATION_HEX]}; }\n` + + (holdOn + ? ` 100% { background-color: ${DECORATION_HEX[style as keyof typeof DECORATION_HEX]}; }\n` + : ` ${pct100(w[1] + 0.0001)}% { background-color: transparent; }\n 100% { background-color: transparent; }\n`) + + `}`, + ); + }; + for (const st of REFERENCE_FLASH_STYLES) { + if (styles.has(st)) { + emit(st, refWin, false); + } + } + if (styles.has("pendingDelete")) { + emit("pendingDelete", delWin, true); + } // held to the edit + } else { + // ADD pulse at the frame's slot start (post-edit justAdded). + const durFrac = pulseMs / tl.totalMs; + const aFullEnd = Math.min(hi, lo + durFrac); + const aFadeEnd = Math.min(hi, aFullEnd + durFrac * FADE_FRAC); + for (const st of ADD_FLASH_STYLES) { + out.push( + `@keyframes flashfade-${st}-s${k} {\n` + + ` 0% { background-color: ${DECORATION_HEX[st]}; }\n` + + ` ${pct100(lo)}% { background-color: ${DECORATION_HEX[st]}; }\n` + + ` ${pct100(aFullEnd)}% { background-color: ${DECORATION_HEX[st]}; }\n` + + ` ${pct100(aFadeEnd)}% { background-color: transparent; }\n` + + ` 100% { background-color: transparent; }\n` + + `}`, + ); + } + } + }); + + return out.join("\n"); +} + +export function flashFadeRules(frames: readonly Frame[]): string { + const rules: string[] = []; + frames.forEach((frame, k) => { + if (frame.role === "during") { + const styles = new Set(frame.decorations.map((d) => d.style)); + for (const st of [...REFERENCE_FLASH_STYLES, "pendingDelete"]) { + if (!styles.has(st as never)) { + continue; + } + rules.push( + `.cl-cascade .frame[data-frame="${k}"] .ch[data-flash="${st}"] {\n` + + ` background-color: transparent;\n` + + ` animation: flashfade-${st}-s${k} var(--dur, 2s) linear 1 forwards paused;\n` + + `}`, + ); + } + } else { + for (const st of ADD_FLASH_STYLES) { + rules.push( + `.cl-cascade .frame[data-frame="${k}"] .ch[data-flash="${st}"] {\n` + + ` background-color: ${DECORATION_HEX[st]};\n` + + ` animation: flashfade-${st}-s${k} var(--dur, 2s) linear 1 forwards paused;\n` + + `}`, + ); + } + } + }); + return rules.join("\n"); +} diff --git a/packages/command-visualizer/src/render/css-cascade.ts b/packages/command-visualizer/src/render/css-cascade.ts index b2126a2424..ea3c75d7bf 100644 --- a/packages/command-visualizer/src/render/css-cascade.ts +++ b/packages/command-visualizer/src/render/css-cascade.ts @@ -7,6 +7,7 @@ import { FLASH_STYLES, HIGHLIGHT_STYLES } from "../data/decorations"; import { FLASH_PULSE_MS } from "../data/decorations"; import type { Frame } from "../model/frame-state"; import { timelineOf, type Timeline } from "../model/timeline"; +import { flashFadeKeyframes, flashFadeRules } from "./css-cascade-flash"; // §3.2 — char-range bands on the per-char grid (one bg attr per .ch). // The STATIC path (single-frame PNG renders, animate=false): the band is just a @@ -21,153 +22,14 @@ function charBandRules(): string { return [...flash, ...hl].join("\n"); } -// §4.2 DURING beats — flash TIMING. A flash is a TRANSIENT beat *within* one -// frame's timeline slot, not a static band. Two opposite directions: -// -// DELETE (R2-i, pendingDelete) rides the BEFORE frame (frame 0, slot [0, 1/N]): -// plain (band transparent) → hold plain → red band fades IN -// then the frame's opacity snap crosses to the after-frame (text gone). The band -// fades in LATE in the slot so the before-doc reads plain first, then highlights -// the doomed span just before it vanishes. -// -// ADD (R2-ii, justAdded) rides the AFTER frame (frame N-1, slot [(N-1)/N, 1]): -// green band PRESENT → hold green → green band fades OUT → plain (text stays) -// the insert just happened, so the green is up-front when the after-frame appears, -// then fades out over the latter part of the slot leaving plain text behind. This -// is the mirror image of the delete beat (green out-front, fade to transparent vs. -// red back-end, fade in from transparent). -// -// Both animate ONLY background-color (text stays fully opaque the whole slot); -// CSS-only, zero view-time JS. Each flash style gets its own @keyframes scoped to -// its native frame, so other frames / styles keep the static band. -const pct = (x: number): string => x.toFixed(3); +// Shared %-formatter — used here (frameKeyframes) and by the extracted +// flash-fade module. Exported so css-cascade-flash.ts reuses the exact impl +// (render/ → render/ import; no duplication). +export const pct = (x: number): string => x.toFixed(3); -const DELETE_FLASH_STYLES = ["pendingDelete"] as const; -const ADD_FLASH_STYLES = ["justAdded"] as const; - -// B2/B6 FIX — the flash is a FIXED 100ms pulse, pinned to cursorless's -// `pendingEditDecorationTime` (FLASH_PULSE_MS), DECOUPLED from the readability -// state-hold cadence. -// -// The cascade timeline is `--dur = N · MS_PER_STATE` ms (serialize-cascade.ts), -// so each of the N frame slots lasts MS_PER_STATE ms. Working in keyframe-% of -// the WHOLE timeline (each @keyframes runs over var(--dur)): -// 1% of timeline = (--dur)/100 ms = (N·MS_PER_STATE)/100 ms -// ⇒ a P-ms window in % = P / (N·MS_PER_STATE) · 100 -// The flash's FULL-target held window is exactly FLASH_PULSE_MS ms → `pulsePct` -// below. A short fade ramp (FADE_FRAC of the pulse) softens each edge but the -// held-full-color span is exactly the pulse, which is what verify:flash-timing -// measures. Result: the pulse is ~100ms for ANY N (no slot scaling). -const FADE_FRAC = 0.4; // soft-edge ramp length as a fraction of the pulse window - -// Reference-class pre-edit flashes (Bring sources/destinations etc.) — they -// sequence BEFORE deletion flashes inside a DURING window (real cursorless -// fires pre-edit flashes in parallel; sequenced here by spec). -const REFERENCE_FLASH_STYLES = [ - "referenced", - "pendingModification0", - "pendingModification1", -] as const; - -function flashFadeKeyframes( - frames: readonly Frame[], - tl: Timeline, - pulseMs: number = FLASH_PULSE_MS, -): string { - const out: string[] = []; - const pct100 = (x: number) => pct(Math.max(0, Math.min(100, x * 100))); - - frames.forEach((frame, k) => { - const lo = tl.startFrac[k]; - const hi = tl.endFrac[k]; - - if (frame.role === "during") { - // DURING window: reference flashes first, deletion flashes second. - // Halves when both classes are present; the full window otherwise. - const styles = new Set(frame.decorations.map((d) => d.style)); - // The during phase keeps its full duration regardless of content, but - // the FIRST flash class present INITIATES AT THE PHASE START — the - // same instant the command pill goes active. When reference flashes - // exist they take the first half and deletion follows at the midpoint; - // with deletions only, red starts with the pill and holds to the edit. - const hasRef = REFERENCE_FLASH_STYLES.some((st) => - styles.has(st as never), - ); - const mid = (lo + hi) / 2; - const refWin: [number, number] = [lo, mid]; - const delWin: [number, number] = [hasRef ? mid : lo, hi]; - const emit = (style: string, w: [number, number], holdOn: boolean) => { - out.push( - `@keyframes flashfade-${style}-s${k} {\n` + - ` 0% { background-color: transparent; }\n` + - ` ${pct100(w[0])}% { background-color: transparent; }\n` + - ` ${pct100(w[0] + 0.0001)}% { background-color: ${DECORATION_HEX[style as keyof typeof DECORATION_HEX]}; }\n` + - ` ${pct100(w[1])}% { background-color: ${DECORATION_HEX[style as keyof typeof DECORATION_HEX]}; }\n` + - (holdOn - ? ` 100% { background-color: ${DECORATION_HEX[style as keyof typeof DECORATION_HEX]}; }\n` - : ` ${pct100(w[1] + 0.0001)}% { background-color: transparent; }\n 100% { background-color: transparent; }\n`) + - `}`, - ); - }; - for (const st of REFERENCE_FLASH_STYLES) { - if (styles.has(st)) { - emit(st, refWin, false); - } - } - if (styles.has("pendingDelete")) { - emit("pendingDelete", delWin, true); - } // held to the edit - } else { - // ADD pulse at the frame's slot start (post-edit justAdded). - const durFrac = pulseMs / tl.totalMs; - const aFullEnd = Math.min(hi, lo + durFrac); - const aFadeEnd = Math.min(hi, aFullEnd + durFrac * FADE_FRAC); - for (const st of ADD_FLASH_STYLES) { - out.push( - `@keyframes flashfade-${st}-s${k} {\n` + - ` 0% { background-color: ${DECORATION_HEX[st]}; }\n` + - ` ${pct100(lo)}% { background-color: ${DECORATION_HEX[st]}; }\n` + - ` ${pct100(aFullEnd)}% { background-color: ${DECORATION_HEX[st]}; }\n` + - ` ${pct100(aFadeEnd)}% { background-color: transparent; }\n` + - ` 100% { background-color: transparent; }\n` + - `}`, - ); - } - } - }); - - return out.join("\n"); -} - -function flashFadeRules(frames: readonly Frame[]): string { - const rules: string[] = []; - frames.forEach((frame, k) => { - if (frame.role === "during") { - const styles = new Set(frame.decorations.map((d) => d.style)); - for (const st of [...REFERENCE_FLASH_STYLES, "pendingDelete"]) { - if (!styles.has(st as never)) { - continue; - } - rules.push( - `.cl-cascade .frame[data-frame="${k}"] .ch[data-flash="${st}"] {\n` + - ` background-color: transparent;\n` + - ` animation: flashfade-${st}-s${k} var(--dur, 2s) linear 1 forwards paused;\n` + - `}`, - ); - } - } else { - for (const st of ADD_FLASH_STYLES) { - rules.push( - `.cl-cascade .frame[data-frame="${k}"] .ch[data-flash="${st}"] {\n` + - ` background-color: ${DECORATION_HEX[st]};\n` + - ` animation: flashfade-${st}-s${k} var(--dur, 2s) linear 1 forwards paused;\n` + - `}`, - ); - } - } - }); - return rules.join("\n"); -} +// The flash TIMING section (DURING beats: delete R2-i, insert R2-ii, reference +// pre-edit flashes) lives in ./css-cascade-flash — imported above. See that +// module's header for the full SPEC-v2 §4.2 rationale. // §3.4 — full-width line-range bands on .cl-line (content box, DECISIONS §7.7). function lineBandRules(): string { From 1c24251bd2453571cbece4a65592c7db7c818dc4 Mon Sep 17 00:00:00 2001 From: Trillium Smith <trillium@trilliumsmith.com> Date: Wed, 8 Jul 2026 09:24:59 -0700 Subject: [PATCH 32/53] refactor(command-visualizer): split pipeline.ts under 250-line limit Extract two cohesive pure steps out of fixtureToCascade: - derive-flashes.ts: step 6b char-diff synthesis of pendingDelete/justAdded when a fixture records no ide.flashes but the doc changed. - derive-overlays.ts: step 7 highlights + thatMark/sourceMark -> decorations. Both return decoration lists the caller appends; order and behavior identical. Removed now-unused Pos/pos imports. Rendered output byte-identical. --- .../src/logic/derive-flashes.ts | 94 +++++++++++++ .../src/logic/derive-overlays.ts | 88 ++++++++++++ .../command-visualizer/src/logic/pipeline.ts | 126 +++--------------- 3 files changed, 203 insertions(+), 105 deletions(-) create mode 100644 packages/command-visualizer/src/logic/derive-flashes.ts create mode 100644 packages/command-visualizer/src/logic/derive-overlays.ts diff --git a/packages/command-visualizer/src/logic/derive-flashes.ts b/packages/command-visualizer/src/logic/derive-flashes.ts new file mode 100644 index 0000000000..4b90b5cb09 --- /dev/null +++ b/packages/command-visualizer/src/logic/derive-flashes.ts @@ -0,0 +1,94 @@ +// Derived referenceFlashes — SPEC-v2 §2.6 (step 6b). Extracted verbatim from +// pipeline.ts so fixtureToCascade stays under the 250-line limit. Pure: takes +// the two document snapshots, returns the flashes to synthesize. No I/O, no +// mutation of caller state. logic/ → logic/ import only. + +import type { DecorationStyle } from "../data/decorations"; +import type { Decoration, GeneralizedRange } from "../model/frame-state"; +import type { Pos } from "../model/geometry"; + +export interface DerivedFlashes { + /** pendingDelete flashes to append to the DURING flash list (pre-edit). */ + duringFlashes: { style: DecorationStyle; range: GeneralizedRange }[]; + /** justAdded flash decorations to push onto the AFTER frame (post-edit). */ + afterDecorations: Decoration[]; +} + +/** + * Step 6b (derived referenceFlashes): tutorial-corpus recordings carry NO + * ide.flashes (verified 2026-07-07 — all 10 tutorial-1-basics fixtures have + * zero) even for document edits. Cursorless flashes are deterministic from + * the edit itself, so when a fixture records none and the doc changed, + * derive them: char-level common prefix/suffix -> removed span flashes + * pendingDelete on BEFORE, inserted span flashes justAdded on AFTER. + * + * Returns empty lists (no synthesis) when the guard conditions don't hold: + * the fixture recorded flashes, there is no final doc, the doc is unchanged, + * or there is no after frame to attach the justAdded flash to. + */ +export function deriveFlashes(args: { + recordedFlashCount: number; + initDoc: string; + finDoc: string | null; + hasAfterFrame: boolean; +}): DerivedFlashes { + const { recordedFlashCount, initDoc, finDoc, hasAfterFrame } = args; + const duringFlashes: { style: DecorationStyle; range: GeneralizedRange }[] = + []; + const afterDecorations: Decoration[] = []; + + if ( + recordedFlashCount === 0 && + finDoc != null && + finDoc !== initDoc && + hasAfterFrame + ) { + const toPos = (doc: string, off: number): Pos => { + const upto = doc.slice(0, off); + const line = (upto.match(/\n/g) ?? []).length; + const character = off - (upto.lastIndexOf("\n") + 1); + return { line, character }; + }; + let p = 0; + while ( + p < initDoc.length && + p < finDoc.length && + initDoc[p] === finDoc[p] + ) { + p++; + } + let sfx = 0; + while ( + sfx < initDoc.length - p && + sfx < finDoc.length - p && + initDoc[initDoc.length - 1 - sfx] === finDoc[finDoc.length - 1 - sfx] + ) { + sfx++; + } + const remEnd = initDoc.length - sfx; + const insEnd = finDoc.length - sfx; + if (remEnd > p) { + duringFlashes.push({ + style: "pendingDelete" as DecorationStyle, + range: { + type: "character", + start: toPos(initDoc, p), + end: toPos(initDoc, remEnd), + }, + }); + } + if (insEnd > p) { + afterDecorations.push({ + style: "justAdded" as DecorationStyle, + role: "flash", + range: { + type: "character", + start: toPos(finDoc, p), + end: toPos(finDoc, insEnd), + }, + }); + } + } + + return { duringFlashes, afterDecorations }; +} diff --git a/packages/command-visualizer/src/logic/derive-overlays.ts b/packages/command-visualizer/src/logic/derive-overlays.ts new file mode 100644 index 0000000000..acf7fe7fe1 --- /dev/null +++ b/packages/command-visualizer/src/logic/derive-overlays.ts @@ -0,0 +1,88 @@ +// Step 7 overlays — highlights + thatMark/sourceMark → decorations. Extracted +// verbatim from pipeline.ts so fixtureToCascade stays under the 250-line limit. +// Pure: reads the fixture ide/finalState objects, returns the decorations to +// append (before-frame highlights, after-frame that/source). No mutation of +// caller state. logic/ → logic/ import only. + +import type { DecorationStyle } from "../data/decorations"; +import type { Decoration } from "../model/frame-state"; +import { + asArr, + asObj, + pos, + toGeneralizedRange, + type Obj, +} from "./fixture-extract"; + +export interface OverlayDecorations { + /** highlight decorations to append to the BEFORE frame. */ + beforeDecorations: Decoration[]; + /** that/source decorations to append to the AFTER frame. */ + afterDecorations: Decoration[]; +} + +/** + * Step 7: highlights → BEFORE decorations (painted on before frame in this + * corpus); thatMark / sourceMark → AFTER decorations (rendered as referenced). + * The after list is only populated when the step has an after frame. + */ +export function deriveOverlays(args: { + ide: Obj | null; + final: Obj | null; + hasAfterFrame: boolean; +}): OverlayDecorations { + const { ide, final, hasAfterFrame } = args; + const beforeDecorations: Decoration[] = []; + const afterDecorations: Decoration[] = []; + + // Step 7: highlights → decorations (painted on before frame in this corpus). + for (const h of asArr(ide?.highlights)) { + const ho = asObj(h); + if (!ho) { + continue; + } + const style = String(ho.style) as DecorationStyle; + for (const r of asArr(ho.ranges)) { + const range = toGeneralizedRange(asObj(r) ?? {}); + if (range) { + beforeDecorations.push({ style, range, role: "highlight" }); + } + } + } + + // Step 7: thatMark / sourceMark → AFTER decorations (rendered as referenced). + if (hasAfterFrame) { + for (const tm of asArr(final?.thatMark)) { + const o = asObj(tm); + const cr = asObj(o?.contentRange); + if (cr) { + afterDecorations.push({ + style: "referenced", + role: "that", + range: { + type: "character", + start: pos(cr.start), + end: pos(cr.end), + }, + }); + } + } + for (const sm of asArr(final?.sourceMark)) { + const o = asObj(sm); + const cr = asObj(o?.contentRange); + if (cr) { + afterDecorations.push({ + style: "pendingModification0", + role: "source", + range: { + type: "character", + start: pos(cr.start), + end: pos(cr.end), + }, + }); + } + } + } + + return { beforeDecorations, afterDecorations }; +} diff --git a/packages/command-visualizer/src/logic/pipeline.ts b/packages/command-visualizer/src/logic/pipeline.ts index 93b11628c1..4218dc6e91 100644 --- a/packages/command-visualizer/src/logic/pipeline.ts +++ b/packages/command-visualizer/src/logic/pipeline.ts @@ -13,18 +13,18 @@ import type { GeneralizedRange, } from "../model/frame-state"; import type { DecorationStyle } from "../data/decorations"; -import type { Pos } from "../model/geometry"; import { asArr, asObj, buildLines, deriveSelections, parseMarks, - pos, toGeneralizedRange, } from "./fixture-extract"; import { fixtureRoot } from "./fixture-root"; +import { deriveFlashes } from "./derive-flashes"; +import { deriveOverlays } from "./derive-overlays"; // Resolved lazily: fixtureRoot() throws when no cursorless checkout exists, // which must not fire at module load in serverless (the API path reads @@ -143,67 +143,23 @@ export function fixtureToCascade( const duringFlashes: { style: DecorationStyle; range: GeneralizedRange }[] = []; - // Step 6b (derived referenceFlashes): tutorial-corpus recordings carry NO - // ide.flashes (verified 2026-07-07 — all 10 tutorial-1-basics fixtures have - // zero) even for document edits. Cursorless flashes are deterministic from - // the edit itself, so when a fixture records none and the doc changed, - // derive them: char-level common prefix/suffix -> removed span flashes - // pendingDelete on BEFORE, inserted span flashes justAdded on AFTER. + // Step 6b (derived referenceFlashes) — see derive-flashes.ts. When a fixture + // records no ide.flashes but the doc changed, synthesize the pre-edit + // pendingDelete (rides DURING) + post-edit justAdded (rides AFTER) from the + // char-level prefix/suffix diff. Behavior identical to the inline version. const recordedFlashes = asArr(ide?.flashes); const initDoc = (initial?.documentContents as string) ?? ""; const finDoc = typeof final?.documentContents === "string" ? final.documentContents : null; - if ( - recordedFlashes.length === 0 && - finDoc != null && - finDoc !== initDoc && - afterFrame - ) { - const toPos = (doc: string, off: number): Pos => { - const upto = doc.slice(0, off); - const line = (upto.match(/\n/g) ?? []).length; - const character = off - (upto.lastIndexOf("\n") + 1); - return { line, character }; - }; - let p = 0; - while ( - p < initDoc.length && - p < finDoc.length && - initDoc[p] === finDoc[p] - ) { - p++; - } - let sfx = 0; - while ( - sfx < initDoc.length - p && - sfx < finDoc.length - p && - initDoc[initDoc.length - 1 - sfx] === finDoc[finDoc.length - 1 - sfx] - ) { - sfx++; - } - const remEnd = initDoc.length - sfx; - const insEnd = finDoc.length - sfx; - if (remEnd > p) { - duringFlashes.push({ - style: "pendingDelete" as DecorationStyle, - range: { - type: "character", - start: toPos(initDoc, p), - end: toPos(initDoc, remEnd), - }, - }); - } - if (insEnd > p) { - afterFrame.decorations.push({ - style: "justAdded" as DecorationStyle, - role: "flash", - range: { - type: "character", - start: toPos(finDoc, p), - end: toPos(finDoc, insEnd), - }, - }); - } + const derived = deriveFlashes({ + recordedFlashCount: recordedFlashes.length, + initDoc, + finDoc, + hasAfterFrame: afterFrame != null, + }); + duringFlashes.push(...derived.duringFlashes); + if (afterFrame) { + afterFrame.decorations.push(...derived.afterDecorations); } // Step 6: flashes. justAdded rides the AFTER frame (post-edit); every @@ -255,53 +211,13 @@ export function fixtureToCascade( frames.splice(1, 0, duringFrame); } - // Step 7: highlights → decorations (painted on before frame in this corpus). - for (const h of asArr(ide?.highlights)) { - const ho = asObj(h); - if (!ho) { - continue; - } - const style = String(ho.style) as DecorationStyle; - for (const r of asArr(ho.ranges)) { - const range = toGeneralizedRange(asObj(r) ?? {}); - if (range) { - beforeFrame.decorations.push({ style, range, role: "highlight" }); - } - } - } - - // Step 7: thatMark / sourceMark → AFTER decorations (rendered as referenced). + // Step 7: highlights → BEFORE decorations, thatMark/sourceMark → AFTER + // decorations. See derive-overlays.ts; behavior identical to the inline + // version (order preserved: highlights, then that, then source). + const overlays = deriveOverlays({ ide, final, hasAfterFrame: afterFrame != null }); + beforeFrame.decorations.push(...overlays.beforeDecorations); if (afterFrame) { - for (const tm of asArr(final?.thatMark)) { - const o = asObj(tm); - const cr = asObj(o?.contentRange); - if (cr) { - afterFrame.decorations.push({ - style: "referenced", - role: "that", - range: { - type: "character", - start: pos(cr.start), - end: pos(cr.end), - }, - }); - } - } - for (const sm of asArr(final?.sourceMark)) { - const o = asObj(sm); - const cr = asObj(o?.contentRange); - if (cr) { - afterFrame.decorations.push({ - style: "pendingModification0", - role: "source", - range: { - type: "character", - start: pos(cr.start), - end: pos(cr.end), - }, - }); - } - } + afterFrame.decorations.push(...overlays.afterDecorations); } return { theme, tabSize, meta, frames }; From 7d0729d992d2b68b59a220f7341bec7f06e474cc Mon Sep 17 00:00:00 2001 From: Trillium Smith <trillium@trilliumsmith.com> Date: Wed, 8 Jul 2026 09:29:36 -0700 Subject: [PATCH 33/53] refactor(command-visualizer): split jumbotron.ts under 250-line limit MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Split the 496-line jumbotron.ts into cohesive render/ siblings: - jumbotron.ts keeps the markup half (commandBar/metadataBlock/dots/ serializeJumbotron) and re-exports jumbotronCss for a stable public surface. - jumbotron-css.ts: jumbotronCss assembler + baseCss/themedCss/carouselTrack section builders. - jumbotron-css-keyframes.ts: the dot + command-pill @keyframes builder. - jumbotron-shared.ts: NL, frameCommands, timelinePct, commandFrameIndices — shared by both halves (no cycle, no duplication; fallow clean). Rendered CSS + markup byte-identical. --- .../src/render/jumbotron-css-keyframes.ts | 202 ++++++++++ .../src/render/jumbotron-css.ts | 186 ++++++++++ .../src/render/jumbotron-shared.ts | 39 ++ .../src/render/jumbotron.ts | 350 +----------------- 4 files changed, 433 insertions(+), 344 deletions(-) create mode 100644 packages/command-visualizer/src/render/jumbotron-css-keyframes.ts create mode 100644 packages/command-visualizer/src/render/jumbotron-css.ts create mode 100644 packages/command-visualizer/src/render/jumbotron-shared.ts diff --git a/packages/command-visualizer/src/render/jumbotron-css-keyframes.ts b/packages/command-visualizer/src/render/jumbotron-css-keyframes.ts new file mode 100644 index 0000000000..e4aafd13ad --- /dev/null +++ b/packages/command-visualizer/src/render/jumbotron-css-keyframes.ts @@ -0,0 +1,202 @@ +// Jumbotron command/dot @keyframes — the timeline-driven lit animation section +// of jumbotronCss. Extracted verbatim from jumbotron.ts so every jumbotron CSS +// module stays under the 250-line limit. render/ → render/ import only. + +import type { CascadeState } from "../model/frame-state"; +import { frameDurMs, timelineOf } from "../model/timeline"; +import { + NL, + frameCommands, + timelinePct, + commandFrameIndices, +} from "./jumbotron-shared"; + +/** The command enters AT its step's initial start — the same beat as the + * dot's level-1 transition (grey -> dim blue) — so "dot lights" and "bubble + * animates into frame" are ONE visual event, not two. */ +const ENTER_FRAC = 0; + +/** + * Build the dot + command-pill @keyframes block (dotwin-{k}, dotissued-{k}, + * cmdlit-{i}) for a multi-command cascade. Returns "" when the cascade has + * fewer than two frames or no commands (single/empty renders emit no lit + * keyframes). Identical to the inline builder that lived in jumbotronCss. + */ +export function litKeyframes( + state: CascadeState, + flashPulseMs: number = 100, +): string { + const n = Math.max(1, state.frames.length); + const commands = frameCommands(state); + + // Timeline-based windows (weighted phases: initial 1000ms, during 500ms). + // COMMAND lifecycle: ABSENT -> ENTERED (muted) -> EXECUTED (lit at the + // start of ITS during phase — when its referenceFlashes fire) -> carried + // out by the (delayed) slide as the next step begins. + const LIT_RAMP_MS = 150; + // Slide fires AT the frame boundary — the dot advance and the command + // slide are the SAME visual beat (they read as one motion). + const LIT_HOLD_MS = 0; + const SLIDE_MS = 220; + const tl = timelineOf(state.frames); + const { msPct, pctc } = timelinePct(tl); + const ramp = msPct(LIT_RAMP_MS); + + const cmdFrames = commandFrameIndices(state); + const resetIdx = state.frames.findIndex((f) => f.reset); + + /** [startPct, endPct] of frame k's ISSUE window: its during phase when it + * has one, else a default-pulse sliver before the next frame. */ + const issueWindow = (k: number): [number, number] => { + const next = state.frames[k + 1]; + if (next?.role === "during") { + return [msPct(tl.startMs[k + 1]), msPct(tl.endMs[k + 1])]; + } + const boundary = msPct(tl.endMs[k]); + return [ + Math.max(msPct(tl.startMs[k]), boundary - msPct(flashPulseMs)), + boundary, + ]; + }; + + let litKf = ""; + if (n >= 2 && commands.length >= 1) { + const parts: string[] = []; + + // Dot phase levels (dotwin-{k}), one per step: disabled(0) -> + // initial(0.45) -> during(1) -> after(1) -> disabled(0). The ring + // (dotissued-{k}) marks the during phase distinctly, so level 2 reads + // full+ring and level 3 full without. + const L1 = 0.45; + cmdFrames.forEach((k) => { + const iniLo = msPct(tl.startMs[k]); + const durFrame = state.frames[k + 1]?.role === "during" ? k + 1 : null; + const durLo = + durFrame != null ? msPct(tl.startMs[durFrame]) : msPct(tl.endMs[k]); + const aftFrame = durFrame != null ? durFrame + 1 : k + 1; + const aftLo = msPct(tl.startMs[aftFrame] ?? tl.endMs[k]); + const aftHi = msPct(tl.endMs[aftFrame] ?? tl.endMs[k]); + const kf = [ + ` 0% { opacity: ${iniLo === 0 ? L1 : 0}; }`, + ...(iniLo > 0 + ? [ + ` ${pctc(iniLo)} { opacity: 0; }`, + ` ${pctc(iniLo + 0.001)} { opacity: ${L1}; }`, + ] + : []), + ` ${pctc(durLo)} { opacity: ${L1}; }`, + ` ${pctc(durLo + 0.001)} { opacity: 1; }`, + ` ${pctc(aftHi)} { opacity: 1; }`, + ...(aftHi < 100 + ? [ + ` ${pctc(aftHi + 0.001)} { opacity: 0; }`, + ` 100% { opacity: 0; }`, + ] + : [` 100% { opacity: 1; }`]), + ]; + parts.push(`@keyframes dotwin-${k} {` + NL + kf.join(NL) + NL + `}`); + }); + + // ISSUED dot ring — white border across the step's during window. + cmdFrames.forEach((k) => { + if (state.frames[k + 1]?.role !== "during") { + return; + } + const [wLo, wHi] = issueWindow(k); + parts.push( + `@keyframes dotissued-${k} {` + + NL + + ` 0% { border-color: transparent; }` + + NL + + ` ${pctc(wLo)} { border-color: transparent; }` + + NL + + ` ${pctc(wLo + 0.001)} { border-color: #ffffff; }` + + NL + + ` ${pctc(wHi)} { border-color: #ffffff; }` + + NL + + ` ${pctc(wHi + 0.001)} { border-color: transparent; }` + + NL + + ` 100% { border-color: transparent; }` + + NL + + `}`, + ); + }); + + // Command pills: entrance into jumbospace (chip 0 rises + fades in), + // then the BACKGROUND carries disabled -> active (text color constant). + const DIS = "var(--pill-disabled, #333)"; + const ACT = "var(--pill-active, #1f6fd6)"; + cmdFrames.forEach((k, i) => { + const enterAt = + msPct(tl.startMs[k]) + msPct(frameDurMs(state.frames[k])) * ENTER_FRAC; + const [litStart] = issueWindow(k); + const isLast = i === cmdFrames.length - 1; + const kfParts: string[] = []; + if (i === 0) { + kfParts.push( + ` 0% { opacity: 0; transform: translateY(14px); background-color: ${DIS}; }`, + ); + if (enterAt > 0) { + kfParts.push( + ` ${pctc(enterAt)} { opacity: 0; transform: translateY(14px); background-color: ${DIS}; }`, + ); + } + kfParts.push( + ` ${pctc(enterAt + ramp)} { opacity: 1; transform: translateY(0); background-color: ${DIS}; }`, + ); + } else { + kfParts.push( + ` 0% { opacity: 1; transform: translateY(0); background-color: ${DIS}; }`, + ); + } + const effLit = Math.max(litStart, enterAt + ramp); + // SNAP to active: the pill background flips at the EXACT instant the + // dot ring turns white (both = the during start). + if (effLit > 0) { + kfParts.push( + ` ${pctc(effLit)} { opacity: 1; transform: translateY(0); background-color: ${DIS}; }`, + ); + } + if (isLast) { + kfParts.push( + ` ${pctc(Math.min(effLit + 0.001, 100))} { opacity: 1; transform: translateY(0); background-color: ${ACT}; }`, + ); + if (resetIdx > 0) { + const resetAt = msPct(tl.startMs[resetIdx]); + kfParts.push( + ` ${pctc(resetAt)} { opacity: 1; transform: translateY(0); background-color: ${ACT}; }`, + ); + kfParts.push( + ` ${pctc(resetAt + ramp)} { opacity: 1; transform: translateY(0); background-color: ${DIS}; }`, + ); + kfParts.push( + ` 100% { opacity: 1; transform: translateY(0); background-color: ${DIS}; }`, + ); + } else { + kfParts.push( + ` 100% { opacity: 1; transform: translateY(0); background-color: ${ACT}; }`, + ); + } + } else { + const nextStart = msPct(tl.startMs[cmdFrames[i + 1]]); + const litEnd = nextStart + msPct(LIT_HOLD_MS + SLIDE_MS); + kfParts.push( + ` ${pctc(Math.min(effLit + 0.001, litEnd))} { opacity: 1; transform: translateY(0); background-color: ${ACT}; }`, + ); + kfParts.push( + ` ${pctc(litEnd)} { opacity: 1; transform: translateY(0); background-color: ${ACT}; }`, + ); + kfParts.push( + ` ${pctc(litEnd + ramp)} { opacity: 1; transform: translateY(0); background-color: ${DIS}; }`, + ); + kfParts.push( + ` 100% { opacity: 1; transform: translateY(0); background-color: ${DIS}; }`, + ); + } + parts.push(`@keyframes cmdlit-${i} {` + NL + kfParts.join(NL) + NL + `}`); + }); + litKf = parts.join(NL) + NL; + } + + return litKf; +} diff --git a/packages/command-visualizer/src/render/jumbotron-css.ts b/packages/command-visualizer/src/render/jumbotron-css.ts new file mode 100644 index 0000000000..ee10f89e37 --- /dev/null +++ b/packages/command-visualizer/src/render/jumbotron-css.ts @@ -0,0 +1,186 @@ +// Jumbotron CSS — ported from VisualizerWrapper.css / VisualizerMetadata.css, +// with docusaurus --ifm-* vars replaced by our theme vars, and the +// useAnimationState carousel replaced by --dur timeline animations. Extracted +// from jumbotron.ts (which keeps the markup half) so every module stays under +// the 250-line limit. The command/dot @keyframes live in +// ./jumbotron-css-keyframes; this module assembles base + themed + those +// keyframes + the carousel track. render/ → render/ import only. + +import type { CascadeState } from "../model/frame-state"; +import { MS_PER_STATE } from "../data/decorations"; +import { timelineOf } from "../model/timeline"; +import { + NL, + frameCommands, + timelinePct, + commandFrameIndices, +} from "./jumbotron-shared"; +import { litKeyframes } from "./jumbotron-css-keyframes"; + +/** Fraction of ONE slot spent sliding to the next command. */ +const CMD_SLIDE_FRAC = 0.18; +/** Fraction of ONE slot the executed (lit) command holds before sliding out. */ +const LIT_HOLD_FRAC = 0.25; + +/** Base layout + component CSS (carousel, pill, metadata, dots). */ +function baseCss(n: number): string { + return ` +/* block, not inline-block: an inline-block wrapper sizes to max-content and + the carousel chips (flex-basis 100%, nowrap) would inflate it to N x width */ +.visualizer-wrapper { display: block; } +.visualizer-jumbotron .jumbotron-container { position: relative; } + +.visualizer-command { + overflow: hidden; + margin-top: 8px; +} +.cl-cmd-track { display: flex; gap: 2%; } +/* CENTER-MODE conveyor: the ACTIVE command sits in the exact center of the + jumbotron bar (70% chip + 15% lead/tail margins); the previous command's + tail stays visible at the left, the next peeks at the right, and each + slide lands the incoming command dead-center. */ +.cl-cmd { + flex: 0 0 70%; + box-sizing: border-box; + text-align: center; + white-space: nowrap; + /* no overflow clipping: the pill may grow past its cell (never truncate) */ +} +.cl-cmd:first-child { margin-left: 15%; } +.cl-cmd:last-child { margin-right: 15%; } +/* The command is a PILL: text color is CONSTANT; the background carries the + state (disabled -> active) via cmdlit-{i}. Entrance animates the pill into + jumbospace (rise + fade). */ +.cl-cmd-pill { + display: inline-block; + box-sizing: border-box; + padding: 10px 28px; + border-radius: 999px; + font-size: 28px; + line-height: 1.15; + color: var(--pill-fg, #f2f2f2); + background: var(--pill-disabled, #333); + animation: cmdlit-0 var(--dur, 2000ms) linear 1 forwards paused; +} + +.visualizer-metadata { + display: flex; + flex-direction: column; + gap: 6px; + padding: 10px 14px; + margin-top: 8px; + background: var(--jumbo-emphasis, #262626); + border: 1px solid var(--jumbo-border, #3a3a3a); + border-radius: 6px; + font-size: 13px; + color: var(--jumbo-fg, #d0d0d0); +} +.visualizer-metadata-item { display: flex; gap: 8px; align-items: baseline; } +.visualizer-metadata-item strong { font-size: 12px; opacity: 0.65; } +.meta-clips { position: relative; display: inline-block; min-height: 1.2em; flex: 1; } +.meta-clip { + position: absolute; + inset: 0; + opacity: 0; + white-space: pre; + overflow: hidden; + text-overflow: ellipsis; + animation: f0 var(--dur, ${n * MS_PER_STATE}ms) steps(1, end) 1 forwards paused; +} +.meta-clip[data-slot="0"] { position: relative; } + +.jumbotron-dots { + display: flex; + justify-content: center; + gap: 10px; + margin-top: 10px; + padding: 4px; +} +.jumbotron-dot { + position: relative; + width: 12px; + height: 12px; + border-radius: 50%; + border: 2px solid var(--jumbo-border, #4a4a4a); + background: var(--jumbo-emphasis, #262626); + box-sizing: border-box; +} +.jumbotron-dot-active { + position: absolute; + inset: -3px; + border-radius: 50%; + background: var(--jumbo-primary, #4c9aff); + border: 2px solid transparent; + box-sizing: border-box; + transform: scale(1.15); + opacity: 0; + /* two slots: [0] slot visibility (f{i}), [1] issued ring (dotissued-{i}) */ + animation: + f0 var(--dur, ${n * MS_PER_STATE}ms) steps(1, end) 1 forwards paused, + f0 var(--dur, ${n * MS_PER_STATE}ms) steps(1, end) 1 forwards paused; +} +`; +} + +/** Theme variable definitions (dark default + light override). */ +function themedCss(): string { + return ` +.visualizer-jumbotron { --jumbo-emphasis: #262626; --jumbo-border: #3a3a3a; --jumbo-fg: #d0d0d0; --jumbo-primary: #4c9aff; --pill-fg: #f2f2f2; --pill-disabled: #333333; --pill-active: #1f6fd6; } +.visualizer-jumbotron[data-theme="light"] { --jumbo-emphasis: #f0f0f0; --jumbo-border: #c8c8c8; --jumbo-fg: #333; --jumbo-primary: #1a6ee0; --pill-fg: #ffffff; --pill-disabled: #9aa4b0; --pill-active: #1a6ee0; } +`; +} + +/** + * Command carousel track: slide to chip i+1 shortly after its step begins (the + * previous chip lingers lit for LIT_HOLD_MS first), eased. Only emitted for + * multi-command cascades (commands.length > 1). + */ +function carouselTrack(state: CascadeState, n: number): string { + const LIT_HOLD_MS = 0; + const SLIDE_MS = 220; + const tl = timelineOf(state.frames); + const { msPct, pctc } = timelinePct(tl); + const cmdFrames = commandFrameIndices(state); + + const step = 72; + const pos = (i: number) => + `transform: translateX(-${(i * step).toFixed(4)}%);`; + const kf: string[] = [` 0% { ${pos(0)} }`]; + cmdFrames.slice(1).forEach((k, j) => { + const at = msPct(tl.startMs[k]) + msPct(LIT_HOLD_MS); + kf.push(` ${pctc(at)} { ${pos(j)} }`); + kf.push(` ${pctc(at + msPct(SLIDE_MS))} { ${pos(j + 1)} }`); + }); + kf.push(` 100% { ${pos(cmdFrames.length - 1)} }`); + + return ( + "@keyframes cmdtrack {" + + NL + + kf.join(NL) + + NL + + "}" + + NL + + ".cl-cmd-track { animation: cmdtrack var(--dur, " + + String(n * MS_PER_STATE) + + "ms) cubic-bezier(0.4, 0, 0.2, 1) 1 forwards paused; }" + + NL + ); +} + +export function jumbotronCss( + state: CascadeState, + flashPulseMs: number = 100, +): string { + const n = Math.max(1, state.frames.length); + const commands = frameCommands(state); + + const base = baseCss(n); + const themed = themedCss(); + const litKf = litKeyframes(state, flashPulseMs); + + if (commands.length <= 1) { + return base + themed + litKf; + } + + return base + themed + litKf + carouselTrack(state, n); +} diff --git a/packages/command-visualizer/src/render/jumbotron-shared.ts b/packages/command-visualizer/src/render/jumbotron-shared.ts new file mode 100644 index 0000000000..26a3994fa8 --- /dev/null +++ b/packages/command-visualizer/src/render/jumbotron-shared.ts @@ -0,0 +1,39 @@ +// Jumbotron shared primitives — used by both the serialization half +// (jumbotron.ts) and the CSS half (jumbotron-css.ts / -keyframes.ts). Kept in a +// dependency-free leaf module so the markup and CSS modules never import each +// other (avoids a cycle) and never duplicate these. render/ → render/ only. + +import type { CascadeState } from "../model/frame-state"; +import type { Timeline } from "../model/timeline"; + +export const NL = String.fromCharCode(10); + +/** Commands carried by the frames, in order. */ +export function frameCommands(state: CascadeState): string[] { + return state.frames + .map((f) => f.command) + .filter((c): c is string => c != null && c !== ""); +} + +/** Timeline-relative %-formatters shared by the CSS keyframe + carousel builders. + * `msPct` maps absolute ms onto 0-100 of the total; `pctc` clamps+formats. */ +export function timelinePct(tl: Timeline): { + msPct: (ms: number) => number; + pctc: (x: number) => string; +} { + const durMs = tl.totalMs; + const msPct = (ms: number) => (ms / durMs) * 100; + const pctc = (x: number) => `${Math.max(0, Math.min(100, x)).toFixed(3)}%`; + return { msPct, pctc }; +} + +/** Indices of frames that carry a (non-empty) command — the command-pill slots. */ +export function commandFrameIndices(state: CascadeState): number[] { + const cmdFrames: number[] = []; + state.frames.forEach((f, i) => { + if (f.command != null && f.command !== "") { + cmdFrames.push(i); + } + }); + return cmdFrames; +} diff --git a/packages/command-visualizer/src/render/jumbotron.ts b/packages/command-visualizer/src/render/jumbotron.ts index 5726c6024e..210357b9ae 100644 --- a/packages/command-visualizer/src/render/jumbotron.ts +++ b/packages/command-visualizer/src/render/jumbotron.ts @@ -18,20 +18,16 @@ // harness (WAAPI seek) and SVG-as-image delivery both animate it and no JS is // required. Interactive Controls (pause / highlight toggles) are NOT portable // to SVG-as-image and are intentionally omitted. +// +// The CSS half (jumbotronCss) lives in ./jumbotron-css (+ -keyframes); it is +// re-exported below so the public surface (index.ts) is unchanged. import type { CascadeState } from "../model/frame-state"; -import { MS_PER_STATE } from "../data/decorations"; -import { frameDurMs, timelineOf } from "../model/timeline"; +import { timelineOf } from "../model/timeline"; import { esc } from "./html"; +import { NL, frameCommands } from "./jumbotron-shared"; -const NL = String.fromCharCode(10); - -/** Commands carried by the frames, in order. */ -function frameCommands(state: CascadeState): string[] { - return state.frames - .map((f) => f.command) - .filter((c): c is string => c != null && c !== ""); -} +export { jumbotronCss } from "./jumbotron-css"; function hasClipboard(state: CascadeState): boolean { return state.frames.some((f) => f.clipboard != null); @@ -160,337 +156,3 @@ export function serializeJumbotron( `</div>` ); } - -// --------------------------------------------------------------------------- -// CSS — ported from VisualizerWrapper.css / VisualizerMetadata.css, with -// docusaurus --ifm-* vars replaced by our theme vars, and the useAnimationState -// carousel replaced by --dur timeline animations. -// --------------------------------------------------------------------------- - -/** Fraction of ONE slot spent sliding to the next command. */ -const CMD_SLIDE_FRAC = 0.18; -/** Fraction of ONE slot the executed (lit) command holds before sliding out. */ -const LIT_HOLD_FRAC = 0.25; -/** The command enters AT its step's initial start — the same beat as the - * dot's level-1 transition (grey -> dim blue) — so "dot lights" and "bubble - * animates into frame" are ONE visual event, not two. */ -const ENTER_FRAC = 0; - -export function jumbotronCss( - state: CascadeState, - flashPulseMs: number = 100, -): string { - const n = Math.max(1, state.frames.length); - const commands = frameCommands(state); - - const base = ` -/* block, not inline-block: an inline-block wrapper sizes to max-content and - the carousel chips (flex-basis 100%, nowrap) would inflate it to N x width */ -.visualizer-wrapper { display: block; } -.visualizer-jumbotron .jumbotron-container { position: relative; } - -.visualizer-command { - overflow: hidden; - margin-top: 8px; -} -.cl-cmd-track { display: flex; gap: 2%; } -/* CENTER-MODE conveyor: the ACTIVE command sits in the exact center of the - jumbotron bar (70% chip + 15% lead/tail margins); the previous command's - tail stays visible at the left, the next peeks at the right, and each - slide lands the incoming command dead-center. */ -.cl-cmd { - flex: 0 0 70%; - box-sizing: border-box; - text-align: center; - white-space: nowrap; - /* no overflow clipping: the pill may grow past its cell (never truncate) */ -} -.cl-cmd:first-child { margin-left: 15%; } -.cl-cmd:last-child { margin-right: 15%; } -/* The command is a PILL: text color is CONSTANT; the background carries the - state (disabled -> active) via cmdlit-{i}. Entrance animates the pill into - jumbospace (rise + fade). */ -.cl-cmd-pill { - display: inline-block; - box-sizing: border-box; - padding: 10px 28px; - border-radius: 999px; - font-size: 28px; - line-height: 1.15; - color: var(--pill-fg, #f2f2f2); - background: var(--pill-disabled, #333); - animation: cmdlit-0 var(--dur, 2000ms) linear 1 forwards paused; -} - -.visualizer-metadata { - display: flex; - flex-direction: column; - gap: 6px; - padding: 10px 14px; - margin-top: 8px; - background: var(--jumbo-emphasis, #262626); - border: 1px solid var(--jumbo-border, #3a3a3a); - border-radius: 6px; - font-size: 13px; - color: var(--jumbo-fg, #d0d0d0); -} -.visualizer-metadata-item { display: flex; gap: 8px; align-items: baseline; } -.visualizer-metadata-item strong { font-size: 12px; opacity: 0.65; } -.meta-clips { position: relative; display: inline-block; min-height: 1.2em; flex: 1; } -.meta-clip { - position: absolute; - inset: 0; - opacity: 0; - white-space: pre; - overflow: hidden; - text-overflow: ellipsis; - animation: f0 var(--dur, ${n * MS_PER_STATE}ms) steps(1, end) 1 forwards paused; -} -.meta-clip[data-slot="0"] { position: relative; } - -.jumbotron-dots { - display: flex; - justify-content: center; - gap: 10px; - margin-top: 10px; - padding: 4px; -} -.jumbotron-dot { - position: relative; - width: 12px; - height: 12px; - border-radius: 50%; - border: 2px solid var(--jumbo-border, #4a4a4a); - background: var(--jumbo-emphasis, #262626); - box-sizing: border-box; -} -.jumbotron-dot-active { - position: absolute; - inset: -3px; - border-radius: 50%; - background: var(--jumbo-primary, #4c9aff); - border: 2px solid transparent; - box-sizing: border-box; - transform: scale(1.15); - opacity: 0; - /* two slots: [0] slot visibility (f{i}), [1] issued ring (dotissued-{i}) */ - animation: - f0 var(--dur, ${n * MS_PER_STATE}ms) steps(1, end) 1 forwards paused, - f0 var(--dur, ${n * MS_PER_STATE}ms) steps(1, end) 1 forwards paused; -} -`; - - const themed = ` -.visualizer-jumbotron { --jumbo-emphasis: #262626; --jumbo-border: #3a3a3a; --jumbo-fg: #d0d0d0; --jumbo-primary: #4c9aff; --pill-fg: #f2f2f2; --pill-disabled: #333333; --pill-active: #1f6fd6; } -.visualizer-jumbotron[data-theme="light"] { --jumbo-emphasis: #f0f0f0; --jumbo-border: #c8c8c8; --jumbo-fg: #333; --jumbo-primary: #1a6ee0; --pill-fg: #ffffff; --pill-disabled: #9aa4b0; --pill-active: #1a6ee0; } -`; - - // Timeline-based windows (weighted phases: initial 1000ms, during 500ms). - // COMMAND lifecycle: ABSENT -> ENTERED (muted) -> EXECUTED (lit at the - // start of ITS during phase — when its referenceFlashes fire) -> carried - // out by the (delayed) slide as the next step begins. - const LIT_RAMP_MS = 150; - // Slide fires AT the frame boundary — the dot advance and the command - // slide are the SAME visual beat (they read as one motion). - const LIT_HOLD_MS = 0; - const SLIDE_MS = 220; - const tl = timelineOf(state.frames); - const durMs = tl.totalMs; - const msPct = (ms: number) => (ms / durMs) * 100; - const ramp = msPct(LIT_RAMP_MS); - const pctc = (x: number) => `${Math.max(0, Math.min(100, x)).toFixed(3)}%`; - - const cmdFrames: number[] = []; - state.frames.forEach((f, i) => { - if (f.command != null && f.command !== "") { - cmdFrames.push(i); - } - }); - const resetIdx = state.frames.findIndex((f) => f.reset); - - /** [startPct, endPct] of frame k's ISSUE window: its during phase when it - * has one, else a default-pulse sliver before the next frame. */ - const issueWindow = (k: number): [number, number] => { - const next = state.frames[k + 1]; - if (next?.role === "during") { - return [msPct(tl.startMs[k + 1]), msPct(tl.endMs[k + 1])]; - } - const boundary = msPct(tl.endMs[k]); - return [ - Math.max(msPct(tl.startMs[k]), boundary - msPct(flashPulseMs)), - boundary, - ]; - }; - - let litKf = ""; - if (n >= 2 && commands.length >= 1) { - const parts: string[] = []; - - // Dot phase levels (dotwin-{k}), one per step: disabled(0) -> - // initial(0.45) -> during(1) -> after(1) -> disabled(0). The ring - // (dotissued-{k}) marks the during phase distinctly, so level 2 reads - // full+ring and level 3 full without. - const L1 = 0.45; - cmdFrames.forEach((k) => { - const iniLo = msPct(tl.startMs[k]); - const durFrame = state.frames[k + 1]?.role === "during" ? k + 1 : null; - const durLo = - durFrame != null ? msPct(tl.startMs[durFrame]) : msPct(tl.endMs[k]); - const aftFrame = durFrame != null ? durFrame + 1 : k + 1; - const aftLo = msPct(tl.startMs[aftFrame] ?? tl.endMs[k]); - const aftHi = msPct(tl.endMs[aftFrame] ?? tl.endMs[k]); - const kf = [ - ` 0% { opacity: ${iniLo === 0 ? L1 : 0}; }`, - ...(iniLo > 0 - ? [ - ` ${pctc(iniLo)} { opacity: 0; }`, - ` ${pctc(iniLo + 0.001)} { opacity: ${L1}; }`, - ] - : []), - ` ${pctc(durLo)} { opacity: ${L1}; }`, - ` ${pctc(durLo + 0.001)} { opacity: 1; }`, - ` ${pctc(aftHi)} { opacity: 1; }`, - ...(aftHi < 100 - ? [ - ` ${pctc(aftHi + 0.001)} { opacity: 0; }`, - ` 100% { opacity: 0; }`, - ] - : [` 100% { opacity: 1; }`]), - ]; - parts.push(`@keyframes dotwin-${k} {` + NL + kf.join(NL) + NL + `}`); - }); - - // ISSUED dot ring — white border across the step's during window. - cmdFrames.forEach((k) => { - if (state.frames[k + 1]?.role !== "during") { - return; - } - const [wLo, wHi] = issueWindow(k); - parts.push( - `@keyframes dotissued-${k} {` + - NL + - ` 0% { border-color: transparent; }` + - NL + - ` ${pctc(wLo)} { border-color: transparent; }` + - NL + - ` ${pctc(wLo + 0.001)} { border-color: #ffffff; }` + - NL + - ` ${pctc(wHi)} { border-color: #ffffff; }` + - NL + - ` ${pctc(wHi + 0.001)} { border-color: transparent; }` + - NL + - ` 100% { border-color: transparent; }` + - NL + - `}`, - ); - }); - - // Command pills: entrance into jumbospace (chip 0 rises + fades in), - // then the BACKGROUND carries disabled -> active (text color constant). - const DIS = "var(--pill-disabled, #333)"; - const ACT = "var(--pill-active, #1f6fd6)"; - cmdFrames.forEach((k, i) => { - const enterAt = - msPct(tl.startMs[k]) + msPct(frameDurMs(state.frames[k])) * ENTER_FRAC; - const [litStart] = issueWindow(k); - const isLast = i === cmdFrames.length - 1; - const kfParts: string[] = []; - if (i === 0) { - kfParts.push( - ` 0% { opacity: 0; transform: translateY(14px); background-color: ${DIS}; }`, - ); - if (enterAt > 0) { - kfParts.push( - ` ${pctc(enterAt)} { opacity: 0; transform: translateY(14px); background-color: ${DIS}; }`, - ); - } - kfParts.push( - ` ${pctc(enterAt + ramp)} { opacity: 1; transform: translateY(0); background-color: ${DIS}; }`, - ); - } else { - kfParts.push( - ` 0% { opacity: 1; transform: translateY(0); background-color: ${DIS}; }`, - ); - } - const effLit = Math.max(litStart, enterAt + ramp); - // SNAP to active: the pill background flips at the EXACT instant the - // dot ring turns white (both = the during start). - if (effLit > 0) { - kfParts.push( - ` ${pctc(effLit)} { opacity: 1; transform: translateY(0); background-color: ${DIS}; }`, - ); - } - if (isLast) { - kfParts.push( - ` ${pctc(Math.min(effLit + 0.001, 100))} { opacity: 1; transform: translateY(0); background-color: ${ACT}; }`, - ); - if (resetIdx > 0) { - const resetAt = msPct(tl.startMs[resetIdx]); - kfParts.push( - ` ${pctc(resetAt)} { opacity: 1; transform: translateY(0); background-color: ${ACT}; }`, - ); - kfParts.push( - ` ${pctc(resetAt + ramp)} { opacity: 1; transform: translateY(0); background-color: ${DIS}; }`, - ); - kfParts.push( - ` 100% { opacity: 1; transform: translateY(0); background-color: ${DIS}; }`, - ); - } else { - kfParts.push( - ` 100% { opacity: 1; transform: translateY(0); background-color: ${ACT}; }`, - ); - } - } else { - const nextStart = msPct(tl.startMs[cmdFrames[i + 1]]); - const litEnd = nextStart + msPct(LIT_HOLD_MS + SLIDE_MS); - kfParts.push( - ` ${pctc(Math.min(effLit + 0.001, litEnd))} { opacity: 1; transform: translateY(0); background-color: ${ACT}; }`, - ); - kfParts.push( - ` ${pctc(litEnd)} { opacity: 1; transform: translateY(0); background-color: ${ACT}; }`, - ); - kfParts.push( - ` ${pctc(litEnd + ramp)} { opacity: 1; transform: translateY(0); background-color: ${DIS}; }`, - ); - kfParts.push( - ` 100% { opacity: 1; transform: translateY(0); background-color: ${DIS}; }`, - ); - } - parts.push(`@keyframes cmdlit-${i} {` + NL + kfParts.join(NL) + NL + `}`); - }); - litKf = parts.join(NL) + NL; - } - - if (commands.length <= 1) { - return base + themed + litKf; - } - - // Command carousel: slide to chip i+1 shortly after its step begins (the - // previous chip lingers lit for LIT_HOLD_MS first), eased. - const step = 72; - const pos = (i: number) => - `transform: translateX(-${(i * step).toFixed(4)}%);`; - const kf: string[] = [` 0% { ${pos(0)} }`]; - cmdFrames.slice(1).forEach((k, j) => { - const at = msPct(tl.startMs[k]) + msPct(LIT_HOLD_MS); - kf.push(` ${pctc(at)} { ${pos(j)} }`); - kf.push(` ${pctc(at + msPct(SLIDE_MS))} { ${pos(j + 1)} }`); - }); - kf.push(` 100% { ${pos(cmdFrames.length - 1)} }`); - - return ( - base + - themed + - litKf + - "@keyframes cmdtrack {" + - NL + - kf.join(NL) + - NL + - "}" + - NL + - ".cl-cmd-track { animation: cmdtrack var(--dur, " + - String(n * MS_PER_STATE) + - "ms) cubic-bezier(0.4, 0, 0.2, 1) 1 forwards paused; }" + - NL - ); -} From 2ab06b9dd7ba730ba060878f1b8b78c9e663b7aa Mon Sep 17 00:00:00 2001 From: Trillium Smith <trillium@trilliumsmith.com> Date: Wed, 8 Jul 2026 09:40:35 -0700 Subject: [PATCH 34/53] refactor(command-visualizer): legible 4-stage pipeline orchestrator MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Make the render pipeline readable top-to-bottom in one place. Add a `renderCommand` orchestrator at the package root (src/render-command.ts) whose body shows the four stages at a glance, each delegating to a named function: 1. get what to render -> parseFixture (logic/pipeline.ts) 2. tokenize each step -> tokenizeStates (logic/pipeline.ts) 3. generate render object -> buildRenderObject (logic/build-render-object.ts) 4. render from object -> serializeCascade + wrapCascadeSvg (render/) Decompose the former 235-line fixtureToCascade into the three named stage functions; fixtureToCascade stays exported and is now a thin composition of them (byte-identical output). The orchestrator lives at the root, NOT in logic/, because it is the one allowed composition point spanning both logic/ and render/ — the folder dependency rule (logic/ ⊥ render/) is preserved. Shared stage types moved to logic/pipeline-types.ts to avoid a circular pipeline <-> build-render-object edge and keep every file <=250 lines. Public surface: add renderCommand, RenderCommandOptions, parseFixture, tokenizeStates, buildRenderObject, ParsedFixture, TokenizedStates. All prior exports unchanged. Zero behavior change — rendered SVG byte-identical (verified by hash). --- packages/command-visualizer/src/index.ts | 14 +- .../src/logic/build-render-object.ts | 121 +++++++++++++ .../src/logic/pipeline-types.ts | 38 ++++ .../command-visualizer/src/logic/pipeline.ts | 169 +++++------------- .../command-visualizer/src/render-command.ts | 49 +++++ 5 files changed, 270 insertions(+), 121 deletions(-) create mode 100644 packages/command-visualizer/src/logic/build-render-object.ts create mode 100644 packages/command-visualizer/src/logic/pipeline-types.ts create mode 100644 packages/command-visualizer/src/render-command.ts diff --git a/packages/command-visualizer/src/index.ts b/packages/command-visualizer/src/index.ts index 16d4d5c9ae..77725bc4d4 100644 --- a/packages/command-visualizer/src/index.ts +++ b/packages/command-visualizer/src/index.ts @@ -2,7 +2,19 @@ // // fixture YAML in -> animated SVG out. See STATUS.md for integration state. -export { fixtureToCascade, type PipelineOptions } from "./logic/pipeline"; +export { + fixtureToCascade, + parseFixture, + tokenizeStates, + buildRenderObject, + type PipelineOptions, + type ParsedFixture, + type TokenizedStates, +} from "./logic/pipeline"; +export { + renderCommand, + type RenderCommandOptions, +} from "./render-command"; export { chainCascades, withBumpers, diff --git a/packages/command-visualizer/src/logic/build-render-object.ts b/packages/command-visualizer/src/logic/build-render-object.ts new file mode 100644 index 0000000000..3268965d24 --- /dev/null +++ b/packages/command-visualizer/src/logic/build-render-object.ts @@ -0,0 +1,121 @@ +// Stage 3: generate render object. Extracted from pipeline.ts so each module +// stays under the 250-line ceiling. Assembles flashes, the DURING frame, and +// overlays from the tokenized before/after Frames into the CascadeState. +// Behavior identical to the inline stage that lived in fixtureToCascade. +// logic/ → logic/ import only. + +import type { + CascadeState, + Frame, + GeneralizedRange, +} from "../model/frame-state"; +import type { DecorationStyle } from "../data/decorations"; +import { asArr, asObj, toGeneralizedRange } from "./fixture-extract"; +import { deriveFlashes } from "./derive-flashes"; +import { deriveOverlays } from "./derive-overlays"; +import type { + ParsedFixture, + PipelineOptions, + TokenizedStates, +} from "./pipeline-types"; + +// Route a flash style to its native frame (SPEC-v2 §1.2 / §2.6). +function flashRidesAfter(style: string): boolean { + return style === "justAdded"; +} + +/** Assemble flashes, the DURING frame, and overlays into the CascadeState. */ +export function buildRenderObject( + parsed: ParsedFixture, + tokenized: TokenizedStates, + _opts: PipelineOptions = {}, +): CascadeState { + const { theme, tabSize, meta, initial, final, ide } = parsed; + const { frames, beforeFrame, afterFrame } = tokenized; + + const duringFlashes: { style: DecorationStyle; range: GeneralizedRange }[] = + []; + + // Step 6b (derived referenceFlashes) — see derive-flashes.ts. When a fixture + // records no ide.flashes but the doc changed, synthesize the pre-edit + // pendingDelete (rides DURING) + post-edit justAdded (rides AFTER) from the + // char-level prefix/suffix diff. Behavior identical to the inline version. + const recordedFlashes = asArr(ide?.flashes); + const initDoc = (initial?.documentContents as string) ?? ""; + const finDoc = + typeof final?.documentContents === "string" ? final.documentContents : null; + const derived = deriveFlashes({ + recordedFlashCount: recordedFlashes.length, + initDoc, + finDoc, + hasAfterFrame: afterFrame != null, + }); + duringFlashes.push(...derived.duringFlashes); + if (afterFrame) { + afterFrame.decorations.push(...derived.afterDecorations); + } + + // Step 6: flashes. justAdded rides the AFTER frame (post-edit); every + // other flash is PRE-EDIT and rides the dedicated DURING frame (built + // below) — reference-class flashes sequence before deletion flashes there. + for (const f of asArr(ide?.flashes)) { + const fo = asObj(f); + if (!fo) { + continue; + } + const style = String(fo.style) as DecorationStyle; + const range = toGeneralizedRange(asObj(fo.range) ?? {}); + if (!range) { + continue; + } + if (flashRidesAfter(style) && afterFrame) { + afterFrame.decorations.push({ style, range, role: "flash" }); + } else { + duringFlashes.push({ style, range }); + } + } + + // Build the DURING frame (the execution beat — the instant the command + // pill goes active). ALWAYS present when the step has a final state, so + // every command occupies the same time scope. Content depends on flashes: + // - WITH pre-edit flashes: the initial doc, flashes firing (reference + // half then delete half) — the edit lands at the phase end. + // - WITHOUT flashes (pure selection commands like "take cap"): the edit + // is instantaneous in a real editor, so the during frame shows the + // FINAL state — the selection highlight lands in the SAME frame as the + // pill activation. + if (afterFrame) { + const instant = duringFlashes.length === 0; + const src = instant ? afterFrame : beforeFrame; + const duringFrame: Frame = { + role: "during", + lines: src.lines, + cursors: src.cursors, + selections: src.selections, + decorations: instant + ? [] + : duringFlashes.map(({ style, range }) => ({ + style, + range, + role: "flash" as const, + })), + clipboard: src.clipboard, + }; + frames.splice(1, 0, duringFrame); + } + + // Step 7: highlights → BEFORE decorations, thatMark/sourceMark → AFTER + // decorations. See derive-overlays.ts; behavior identical to the inline + // version (order preserved: highlights, then that, then source). + const overlays = deriveOverlays({ + ide, + final, + hasAfterFrame: afterFrame != null, + }); + beforeFrame.decorations.push(...overlays.beforeDecorations); + if (afterFrame) { + afterFrame.decorations.push(...overlays.afterDecorations); + } + + return { theme, tabSize, meta, frames }; +} diff --git a/packages/command-visualizer/src/logic/pipeline-types.ts b/packages/command-visualizer/src/logic/pipeline-types.ts new file mode 100644 index 0000000000..1c660b13e5 --- /dev/null +++ b/packages/command-visualizer/src/logic/pipeline-types.ts @@ -0,0 +1,38 @@ +// Shared pipeline types — the contract between the three named stages +// (parseFixture → tokenizeStates → buildRenderObject). Kept in its own module +// so stage files can import them without a circular pipeline ⇄ build-render +// edge. logic/ → logic/ + model/ + data/ imports only. + +import type { HatColor, HatShape } from "@cursorless/lib-common"; +import type { Theme } from "../data/colors"; +import type { Frame } from "../model/frame-state"; +import type { Obj } from "./fixture-extract"; + +export interface PipelineOptions { + shapeOverride?: Record<string, HatShape>; + theme?: Theme; + tabSize?: number; + /** "dense" (default) = real-allocator fill everywhere; "marks-only" = exactly the recorded marks. */ + fill?: "dense" | "marks-only"; + /** Position-keyed exact-hat overrides, keyed "{line}:{startChar}" — applied last, wins over everything. */ + hatOverride?: Record<string, { color?: HatColor; shape?: HatShape }>; +} + +/** Stage-1 output: the parsed fixture plus everything stages 2/3 read from it. */ +export interface ParsedFixture { + theme: Theme; + tabSize: number; + meta: { spokenForm?: string; action?: string; fixture: string }; + initial: Obj | null; + final: Obj | null; + ide: Obj | null; + /** clipboard visible on a given state, per action semantics. */ + clipFor: (state: "before" | "after") => string | undefined; +} + +/** Stage-2 output: the tokenized before/after frames (mutated by stage 3). */ +export interface TokenizedStates { + frames: Frame[]; + beforeFrame: Frame; + afterFrame: Frame | null; +} diff --git a/packages/command-visualizer/src/logic/pipeline.ts b/packages/command-visualizer/src/logic/pipeline.ts index 4218dc6e91..e835b16874 100644 --- a/packages/command-visualizer/src/logic/pipeline.ts +++ b/packages/command-visualizer/src/logic/pipeline.ts @@ -2,29 +2,36 @@ // yml → frames → tokenize → marks→hats → synthetic shape → flashes→overlays // → that/source/highlights → CascadeState. Render contract (SPEC.md §3/§4) // is unchanged downstream. +// +// The public `fixtureToCascade` is a thin composition of three named stages: +// 1. parseFixture — YAML text → ParsedFixture (doc + meta + clipboard) +// 2. tokenizeStates — ParsedFixture → before/after Frames (lines + hats) +// 3. buildRenderObject — Frames → CascadeState (flashes, during, overlays) +// Each stage is exported so a reviewer can read the progression top-to-bottom. +// Stage 3 lives in ./build-render-object; its types in ./pipeline-types. import { readFileSync } from "node:fs"; -import type { HatColor, HatShape } from "@cursorless/lib-common"; import { parseFixtureYaml } from "./fixture-yaml"; import type { Theme } from "../data/colors"; -import type { - CascadeState, - Frame, - GeneralizedRange, -} from "../model/frame-state"; -import type { DecorationStyle } from "../data/decorations"; +import type { CascadeState, Frame } from "../model/frame-state"; import { asArr, asObj, buildLines, deriveSelections, parseMarks, - toGeneralizedRange, } from "./fixture-extract"; import { fixtureRoot } from "./fixture-root"; -import { deriveFlashes } from "./derive-flashes"; -import { deriveOverlays } from "./derive-overlays"; +import { buildRenderObject } from "./build-render-object"; +import type { + ParsedFixture, + PipelineOptions, + TokenizedStates, +} from "./pipeline-types"; + +export { buildRenderObject }; +export type { ParsedFixture, PipelineOptions, TokenizedStates }; // Resolved lazily: fixtureRoot() throws when no cursorless checkout exists, // which must not fire at module load in serverless (the API path reads @@ -34,27 +41,13 @@ function FIXTURE_ROOT_LAZY(): string { return (fixtureRootCache ??= fixtureRoot()); } -// Route a flash style to its native frame (SPEC-v2 §1.2 / §2.6). -function flashRidesAfter(style: string): boolean { - return style === "justAdded"; -} - -export interface PipelineOptions { - shapeOverride?: Record<string, HatShape>; - theme?: Theme; - tabSize?: number; - /** "dense" (default) = real-allocator fill everywhere; "marks-only" = exactly the recorded marks. */ - fill?: "dense" | "marks-only"; - /** Position-keyed exact-hat overrides, keyed "{line}:{startChar}" — applied last, wins over everything. */ - hatOverride?: Record<string, { color?: HatColor; shape?: HatShape }>; -} - -/** Full pipeline: fixture YAML text → CascadeState. */ -export function fixtureToCascade( +// ── Stage 1: get what to render ────────────────────────────────────────────── +/** Parse fixture YAML and resolve meta + per-state clipboard visibility. */ +export function parseFixture( src: string, fixtureRel: string, opts: PipelineOptions = {}, -): CascadeState { +): ParsedFixture { const doc = parseFixtureYaml(src); const theme: Theme = opts.theme ?? "dark"; const tabSize = opts.tabSize ?? 4; @@ -92,19 +85,28 @@ export function fixtureToCascade( return undefined; }; - const ide = asObj(doc.ide); + return { theme, tabSize, meta, initial, final, ide: asObj(doc.ide), clipFor }; +} +// ── Stage 2: tokenize each step ────────────────────────────────────────────── +/** Tokenize the before (+ after) documents into Frames with lines + hats. */ +export function tokenizeStates( + parsed: ParsedFixture, + opts: PipelineOptions = {}, +): TokenizedStates { + const { initial, final, clipFor } = parsed; + const buildOpts = { + shapeOverride: opts.shapeOverride, + fill: opts.fill, + hatOverride: opts.hatOverride, + }; const initMarks = parseMarks(asObj(initial?.marks)); // Step 2: BEFORE frame. const beforeLines = buildLines( (initial?.documentContents as string) ?? "", initMarks, - { - shapeOverride: opts.shapeOverride, - fill: opts.fill, - hatOverride: opts.hatOverride, - }, + buildOpts, ); const beforeSel = deriveSelections(asArr(initial?.selections)); const beforeFrame: Frame = { @@ -113,7 +115,7 @@ export function fixtureToCascade( cursors: beforeSel.cursors, selections: beforeSel.selections, decorations: [], - command: meta.spokenForm, + command: parsed.meta.spokenForm, clipboard: clipFor("before"), }; @@ -123,11 +125,7 @@ export function fixtureToCascade( let afterFrame: Frame | null = null; if (final && typeof final.documentContents === "string") { // Final docs ship no marks; re-tokenize identically (no hats on after). - const afterLines = buildLines(final.documentContents, [], { - shapeOverride: opts.shapeOverride, - fill: opts.fill, - hatOverride: opts.hatOverride, - }); + const afterLines = buildLines(final.documentContents, [], buildOpts); const afterSel = deriveSelections(asArr(final.selections)); afterFrame = { role: "after", @@ -140,87 +138,18 @@ export function fixtureToCascade( frames.push(afterFrame); } - const duringFlashes: { style: DecorationStyle; range: GeneralizedRange }[] = - []; - - // Step 6b (derived referenceFlashes) — see derive-flashes.ts. When a fixture - // records no ide.flashes but the doc changed, synthesize the pre-edit - // pendingDelete (rides DURING) + post-edit justAdded (rides AFTER) from the - // char-level prefix/suffix diff. Behavior identical to the inline version. - const recordedFlashes = asArr(ide?.flashes); - const initDoc = (initial?.documentContents as string) ?? ""; - const finDoc = - typeof final?.documentContents === "string" ? final.documentContents : null; - const derived = deriveFlashes({ - recordedFlashCount: recordedFlashes.length, - initDoc, - finDoc, - hasAfterFrame: afterFrame != null, - }); - duringFlashes.push(...derived.duringFlashes); - if (afterFrame) { - afterFrame.decorations.push(...derived.afterDecorations); - } - - // Step 6: flashes. justAdded rides the AFTER frame (post-edit); every - // other flash is PRE-EDIT and rides the dedicated DURING frame (built - // below) — reference-class flashes sequence before deletion flashes there. - for (const f of asArr(ide?.flashes)) { - const fo = asObj(f); - if (!fo) { - continue; - } - const style = String(fo.style) as DecorationStyle; - const range = toGeneralizedRange(asObj(fo.range) ?? {}); - if (!range) { - continue; - } - if (flashRidesAfter(style) && afterFrame) { - afterFrame.decorations.push({ style, range, role: "flash" }); - } else { - duringFlashes.push({ style, range }); - } - } - - // Build the DURING frame (the execution beat — the instant the command - // pill goes active). ALWAYS present when the step has a final state, so - // every command occupies the same time scope. Content depends on flashes: - // - WITH pre-edit flashes: the initial doc, flashes firing (reference - // half then delete half) — the edit lands at the phase end. - // - WITHOUT flashes (pure selection commands like "take cap"): the edit - // is instantaneous in a real editor, so the during frame shows the - // FINAL state — the selection highlight lands in the SAME frame as the - // pill activation. - if (afterFrame) { - const instant = duringFlashes.length === 0; - const src = instant ? afterFrame : beforeFrame; - const duringFrame: Frame = { - role: "during", - lines: src.lines, - cursors: src.cursors, - selections: src.selections, - decorations: instant - ? [] - : duringFlashes.map(({ style, range }) => ({ - style, - range, - role: "flash" as const, - })), - clipboard: src.clipboard, - }; - frames.splice(1, 0, duringFrame); - } - - // Step 7: highlights → BEFORE decorations, thatMark/sourceMark → AFTER - // decorations. See derive-overlays.ts; behavior identical to the inline - // version (order preserved: highlights, then that, then source). - const overlays = deriveOverlays({ ide, final, hasAfterFrame: afterFrame != null }); - beforeFrame.decorations.push(...overlays.beforeDecorations); - if (afterFrame) { - afterFrame.decorations.push(...overlays.afterDecorations); - } + return { frames, beforeFrame, afterFrame }; +} - return { theme, tabSize, meta, frames }; +/** Full pipeline: fixture YAML text → CascadeState (stages 1 → 2 → 3). */ +export function fixtureToCascade( + src: string, + fixtureRel: string, + opts: PipelineOptions = {}, +): CascadeState { + const parsed = parseFixture(src, fixtureRel, opts); // 1. get what to render + const tokenized = tokenizeStates(parsed, opts); // 2. tokenize each step + return buildRenderObject(parsed, tokenized, opts); // 3. generate render object } /** Convenience: load a recorded fixture by relative path. */ diff --git a/packages/command-visualizer/src/render-command.ts b/packages/command-visualizer/src/render-command.ts new file mode 100644 index 0000000000..da0c23e521 --- /dev/null +++ b/packages/command-visualizer/src/render-command.ts @@ -0,0 +1,49 @@ +// Top-level orchestrator — the ONE legible, top-to-bottom view of the whole +// pipeline. Read this file to understand what the tool does, in four stages: +// +// 1. get what to render (parse the fixture YAML) +// 2. tokenize each step (documents → Frames: lines, hats, selections) +// 3. generate render object (Frames → CascadeState: flashes, during, overlays) +// 4. render from object (CascadeState → animated SVG string) +// +// This module lives at the package ROOT (alongside index.ts), NOT inside +// logic/ or render/, because it is the ONE allowed composition point that spans +// BOTH scopes. The folder rule (logic/ ⊥ render/) is preserved: neither folder +// imports the other; only this root module and index.ts join them. + +import { + parseFixture, + tokenizeStates, + buildRenderObject, + type PipelineOptions, +} from "./logic/pipeline"; +import { serializeCascade } from "./render/serialize-cascade"; +import { wrapCascadeSvg, type SvgWrapOptions } from "./render/svg-wrap"; + +/** Options for the end-to-end orchestrator: pipeline knobs + SVG-wrap knobs. */ +export interface RenderCommandOptions extends PipelineOptions, SvgWrapOptions {} + +/** + * Render a single recorded fixture to a standalone animated SVG string. + * + * The four pipeline stages are visible at a glance below; each delegates to an + * existing named function. Output is byte-identical to the equivalent + * fixtureToCascade → serializeCascade → wrapCascadeSvg call chain. + * + * @param src Fixture YAML text. + * @param fixtureRel Relative fixture path (recorded into caption/meta). + * @param opts Pipeline + SVG-wrap options. + */ +export function renderCommand( + src: string, + fixtureRel: string, + opts: RenderCommandOptions = {}, +): string { + const parsed = parseFixture(src, fixtureRel, opts); // 1. get what to render + const tokenized = tokenizeStates(parsed, opts); // 2. tokenize each step + const cascade = buildRenderObject(parsed, tokenized, opts); // 3. render object + const inner = serializeCascade(cascade); + return wrapCascadeSvg(cascade, inner, undefined, { + flashPulseMs: opts.flashPulseMs, + }); // 4. render from object +} From bf3803d68e87154f23318084230776b081bcf656 Mon Sep 17 00:00:00 2001 From: Trillium Smith <trillium@trilliumsmith.com> Date: Wed, 8 Jul 2026 09:41:21 -0700 Subject: [PATCH 35/53] refactor(command-visualizer): remove dead consts flagged in prior split MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Delete four unused declarations confirmed dead by grep (zero use sites): - CMD_SLIDE_FRAC, LIT_HOLD_FRAC (render/jumbotron-css.ts) - DELETE_FLASH_STYLES (render/css-cascade-flash.ts; the "pendingDelete" literal is used directly at every call site instead) - aftLo local (render/jumbotron-css-keyframes.ts; aftHi is used, aftLo was computed but never read) Zero behavior change — rendered SVG byte-identical (verified by hash). --- packages/command-visualizer/src/render/css-cascade-flash.ts | 1 - .../command-visualizer/src/render/jumbotron-css-keyframes.ts | 1 - packages/command-visualizer/src/render/jumbotron-css.ts | 5 ----- 3 files changed, 7 deletions(-) diff --git a/packages/command-visualizer/src/render/css-cascade-flash.ts b/packages/command-visualizer/src/render/css-cascade-flash.ts index 13af477da0..008c002bef 100644 --- a/packages/command-visualizer/src/render/css-cascade-flash.ts +++ b/packages/command-visualizer/src/render/css-cascade-flash.ts @@ -27,7 +27,6 @@ import { pct } from "./css-cascade"; // CSS-only, zero view-time JS. Each flash style gets its own @keyframes scoped to // its native frame, so other frames / styles keep the static band. -const DELETE_FLASH_STYLES = ["pendingDelete"] as const; const ADD_FLASH_STYLES = ["justAdded"] as const; // B2/B6 FIX — the flash is a FIXED 100ms pulse, pinned to cursorless's diff --git a/packages/command-visualizer/src/render/jumbotron-css-keyframes.ts b/packages/command-visualizer/src/render/jumbotron-css-keyframes.ts index e4aafd13ad..b0b7a25550 100644 --- a/packages/command-visualizer/src/render/jumbotron-css-keyframes.ts +++ b/packages/command-visualizer/src/render/jumbotron-css-keyframes.ts @@ -74,7 +74,6 @@ export function litKeyframes( const durLo = durFrame != null ? msPct(tl.startMs[durFrame]) : msPct(tl.endMs[k]); const aftFrame = durFrame != null ? durFrame + 1 : k + 1; - const aftLo = msPct(tl.startMs[aftFrame] ?? tl.endMs[k]); const aftHi = msPct(tl.endMs[aftFrame] ?? tl.endMs[k]); const kf = [ ` 0% { opacity: ${iniLo === 0 ? L1 : 0}; }`, diff --git a/packages/command-visualizer/src/render/jumbotron-css.ts b/packages/command-visualizer/src/render/jumbotron-css.ts index ee10f89e37..3b4efe294f 100644 --- a/packages/command-visualizer/src/render/jumbotron-css.ts +++ b/packages/command-visualizer/src/render/jumbotron-css.ts @@ -17,11 +17,6 @@ import { } from "./jumbotron-shared"; import { litKeyframes } from "./jumbotron-css-keyframes"; -/** Fraction of ONE slot spent sliding to the next command. */ -const CMD_SLIDE_FRAC = 0.18; -/** Fraction of ONE slot the executed (lit) command holds before sliding out. */ -const LIT_HOLD_FRAC = 0.25; - /** Base layout + component CSS (carousel, pill, metadata, dots). */ function baseCss(n: number): string { return ` From ee59ec2d05ef7e81bf5a5b4a92ce615b1dbe8c80 Mon Sep 17 00:00:00 2001 From: Trillium Smith <trillium@trilliumsmith.com> Date: Wed, 8 Jul 2026 09:42:27 -0700 Subject: [PATCH 36/53] docs(command-visualizer): map the 4-stage pipeline in ARCHITECTURE.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add a "Pipeline — 4 stages" section naming each stage, its function, and the file it lives in, so a reviewer has a top-to-bottom map: 1 parseFixture (logic/pipeline.ts) 2 tokenizeStates (logic/pipeline.ts) 3 buildRenderObject (logic/build-render-object.ts) 4 serializeCascade + wrapCascadeSvg (render/) Document why the renderCommand orchestrator lives at the package root (the one allowed logic+render composition point) rather than in logic/, and list the new files (pipeline-types.ts, build-render-object.ts, render-command.ts) in the scope inventory. --- .../command-visualizer/src/ARCHITECTURE.md | 29 ++++++++++++++++++- 1 file changed, 28 insertions(+), 1 deletion(-) diff --git a/packages/command-visualizer/src/ARCHITECTURE.md b/packages/command-visualizer/src/ARCHITECTURE.md index 2b90d4b105..e6e5e0f16c 100644 --- a/packages/command-visualizer/src/ARCHITECTURE.md +++ b/packages/command-visualizer/src/ARCHITECTURE.md @@ -13,10 +13,37 @@ render/ "what is visually seen": CascadeState -> HTML/CSS/SVG - `data/` — colors.ts, decorations.ts, shapes.ts - `model/` — geometry.ts (Pos/Range + orderRange), frame-state.ts (CascadeState/Frame/Decoration/GeneralizedRange), columns.ts (Line/Token/Column geometry), overlays.ts (decoration → column overlay resolution), timeline.ts (frame timing) -- `logic/` — pipeline.ts, fixture-extract.ts, fixture-yaml.ts, fixture-root.ts, tokenize.ts, hat-allocator.ts, chain.ts +- `logic/` — pipeline.ts, pipeline-types.ts, build-render-object.ts, fixture-extract.ts, fixture-yaml.ts, fixture-root.ts, tokenize.ts, hat-allocator.ts, chain.ts - `render/` — serialize.ts, serialize-cascade.ts, svg-wrap.ts, jumbotron.ts, css.ts, css-cascade.ts, symbols.ts, html.ts +- `render-command.ts` — the top-level 4-stage orchestrator (root, spans logic + render). - `index.ts` — the public surface; wires logic + render + model exports together. +## Pipeline — 4 stages + +The whole tool is one legible top-to-bottom progression. Read `renderCommand` +in `render-command.ts` to see all four stages at a glance; each delegates to a +named function: + +| # | Stage | Function | File | +|---|-------|----------|------| +| 1 | get what to render | `parseFixture` | `logic/pipeline.ts` | +| 2 | tokenize each step | `tokenizeStates` | `logic/pipeline.ts` | +| 3 | generate render object | `buildRenderObject` | `logic/build-render-object.ts` | +| 4 | render from object | `serializeCascade` + `wrapCascadeSvg` | `render/serialize-cascade.ts`, `render/svg-wrap.ts` | + +Stages 1–3 produce the `CascadeState` render object; stage 4 serializes it to +an animated SVG. `fixtureToCascade` (exported, unchanged behavior) is a thin +composition of stages 1–3; `renderCommand` composes all four. Shared stage +types live in `logic/pipeline-types.ts` so the stage files can reference the +contract without a circular import. + +**Why the orchestrator lives at the root, not in `logic/`:** stage 4 is in +`render/`, and `logic/` must never import `render/` (the rule below). The +4-stage orchestrator therefore lives at the package root (`render-command.ts`, +alongside `index.ts`) — the ONE allowed composition point that may import from +both `logic/` and `render/`. Putting it inside `logic/` would create a +forbidden `logic/ → render/` edge. + ## The one-directional dependency rule **`render/` must NEVER import from `logic/`, and `logic/` must NEVER import from `render/`.** From 1da17a80f2efeda5ff940f6317576a917a4fd510 Mon Sep 17 00:00:00 2001 From: Trillium Smith <trillium@trilliumsmith.com> Date: Wed, 8 Jul 2026 09:47:19 -0700 Subject: [PATCH 37/53] chore(command-visualizer): conform manifest + tsconfig to meta-updater Runs the repo's meta-updater fixer so `pnpm lint:meta` (a CI gate) passes: - package.json: add `exports["."]`, canonical `typecheck`/`clean` scripts. - tsconfig.json: add required `src/**/*.json` to include. - root tsconfig.json: register command-visualizer in project `references`. - tsconfig.base.json: add `@cursorless/command-visualizer` path mapping. Wires the package into the workspace's project-reference + path graph like its siblings. --- packages/command-visualizer/package.json | 19 +++++++++++-------- packages/command-visualizer/tsconfig.json | 6 +++++- tsconfig.base.json | 1 + tsconfig.json | 3 +++ 4 files changed, 20 insertions(+), 9 deletions(-) diff --git a/packages/command-visualizer/package.json b/packages/command-visualizer/package.json index e91750ee8d..dd42eb09b8 100644 --- a/packages/command-visualizer/package.json +++ b/packages/command-visualizer/package.json @@ -1,15 +1,13 @@ { "name": "@cursorless/command-visualizer", "version": "0.0.1", - "type": "module", "description": "Visualizes cursorless commands as animated SVGs: the spoken command entering, flashes firing, the edit landing, hats reallocating — rendered from recorded test fixtures, embeddable via plain <img>.", + "license": "MIT", + "type": "module", "main": "./out/index.js", "types": "./out/index.d.ts", - "scripts": { - "compile:tsc": "tsc", - "compile:esbuild": "esbuild ./src/index.ts --sourcemap --format=esm --bundle --packages=external --outfile=./out/index.js", - "compile": "pnpm compile:tsc && pnpm compile:esbuild", - "clean": "rm -rf ./out tsconfig.tsbuildinfo ./dist ./build" + "exports": { + ".": "./src/index.ts" }, "keywords": [ "cursorless", @@ -17,8 +15,13 @@ "svg", "fixtures" ], - "author": "", - "license": "MIT", + "scripts": { + "typecheck": "tsc", + "clean": "rm -rf ./out ./dist ./tsconfig.tsbuildinfo", + "compile:tsc": "tsc", + "compile:esbuild": "esbuild ./src/index.ts --sourcemap --format=esm --bundle --packages=external --outfile=./out/index.js", + "compile": "pnpm compile:tsc && pnpm compile:esbuild" + }, "dependencies": { "@cursorless/lib-common": "workspace:*", "@cursorless/lib-engine": "workspace:*", diff --git a/packages/command-visualizer/tsconfig.json b/packages/command-visualizer/tsconfig.json index fbf56544b3..fe20a86024 100644 --- a/packages/command-visualizer/tsconfig.json +++ b/packages/command-visualizer/tsconfig.json @@ -4,5 +4,9 @@ "skipLibCheck": true, "types": ["node", "mocha"] }, - "include": ["src/**/*.ts", "../../resources/typings/**/*.d.ts"] + "include": [ + "src/**/*.ts", + "src/**/*.json", + "../../resources/typings/**/*.d.ts" + ] } diff --git a/tsconfig.base.json b/tsconfig.base.json index 25d2b75c0a..f7fe1b18e7 100644 --- a/tsconfig.base.json +++ b/tsconfig.base.json @@ -11,6 +11,7 @@ "isolatedModules": true, "strict": true, "paths": { + "@cursorless/command-visualizer": ["./packages/command-visualizer"], "@cursorless/lib-cheatsheet": ["./packages/lib-cheatsheet"], "@cursorless/lib-common": ["./packages/lib-common"], "@cursorless/lib-engine": ["./packages/lib-engine"], diff --git a/tsconfig.json b/tsconfig.json index c002ac6c4f..03729d65cc 100644 --- a/tsconfig.json +++ b/tsconfig.json @@ -17,6 +17,9 @@ { "path": "./packages/app-web-docs" }, + { + "path": "./packages/command-visualizer" + }, { "path": "./packages/lib-cheatsheet" }, From fd7e4160771ec925fb17b9afbde4d228f026b478 Mon Sep 17 00:00:00 2001 From: Trillium Smith <trillium@trilliumsmith.com> Date: Wed, 8 Jul 2026 09:51:32 -0700 Subject: [PATCH 38/53] refactor(command-visualizer): rename DecorationStyle to OverlayStyleName --- packages/command-visualizer/src/data/decorations.ts | 10 +++++----- .../src/logic/build-render-object.ts | 6 +++--- .../command-visualizer/src/logic/derive-flashes.ts | 10 +++++----- .../command-visualizer/src/logic/derive-overlays.ts | 4 ++-- packages/command-visualizer/src/model/frame-state.ts | 4 ++-- packages/command-visualizer/src/model/overlays.ts | 12 ++++++------ 6 files changed, 23 insertions(+), 23 deletions(-) diff --git a/packages/command-visualizer/src/data/decorations.ts b/packages/command-visualizer/src/data/decorations.ts index 29ee95b6d3..3a0c08f8af 100644 --- a/packages/command-visualizer/src/data/decorations.ts +++ b/packages/command-visualizer/src/data/decorations.ts @@ -9,7 +9,7 @@ import { FlashStyle as CursorlessFlashStyle } from "@cursorless/lib-common"; // the enum's string VALUES into the union // "pendingDelete" | "referenced" | "pendingModification0" | // "pendingModification1" | "justAdded", so every existing string-keyed usage -// (DECORATION_HEX keys, "pendingDelete" as DecorationStyle, styles.has(...)) +// (DECORATION_HEX keys, "pendingDelete" as OverlayStyleName, styles.has(...)) // keeps working with zero literal churn, while the set of valid names now // tracks lib-common automatically. The HEX values, FLASH_PULSE_MS, // MS_PER_STATE, and precedence remain ours (not exported by cursorless). @@ -17,11 +17,11 @@ export type FlashStyle = `${CursorlessFlashStyle}`; export type HighlightStyle = "highlight0" | "highlight1"; -export type DecorationStyle = FlashStyle | HighlightStyle; +export type OverlayStyleName = FlashStyle | HighlightStyle; // All 7 decoration styles' background hexes (the 2 scope-pair styles use the // same band hex family; per-edge borders are BONUS, SPEC-v2 §3.5, not here). -export const DECORATION_HEX: Record<DecorationStyle, string> = { +export const DECORATION_HEX: Record<OverlayStyleName, string> = { pendingDelete: "#ff00008a", // REQUIRED (COMPLETION crit 3) justAdded: "#09ff005b", // REQUIRED (COMPLETION crit 3) referenced: "#00a2ff4d", @@ -56,7 +56,7 @@ export const FLASH_PULSE_MS = 100; // changing MS_PER_STATE rescales the state-hold but never the 100ms flash. export const MS_PER_STATE = 1000; -export const ALL_DECORATION_STYLES: DecorationStyle[] = [ +export const ALL_DECORATION_STYLES: OverlayStyleName[] = [ ...FLASH_STYLES, ...HIGHLIGHT_STYLES, ]; @@ -64,7 +64,7 @@ export const ALL_DECORATION_STYLES: DecorationStyle[] = [ // Single-winner precedence (SPEC-v2 §3.2, DECISIONS §7.1): selection < highlight // < flash, last wins; exactly ONE background per cell. Higher number wins. export function overlayPrecedence( - style: DecorationStyle | "selection", + style: OverlayStyleName | "selection", ): number { if (style === "selection") { return 0; diff --git a/packages/command-visualizer/src/logic/build-render-object.ts b/packages/command-visualizer/src/logic/build-render-object.ts index 3268965d24..03c76bb67e 100644 --- a/packages/command-visualizer/src/logic/build-render-object.ts +++ b/packages/command-visualizer/src/logic/build-render-object.ts @@ -9,7 +9,7 @@ import type { Frame, GeneralizedRange, } from "../model/frame-state"; -import type { DecorationStyle } from "../data/decorations"; +import type { OverlayStyleName } from "../data/decorations"; import { asArr, asObj, toGeneralizedRange } from "./fixture-extract"; import { deriveFlashes } from "./derive-flashes"; import { deriveOverlays } from "./derive-overlays"; @@ -33,7 +33,7 @@ export function buildRenderObject( const { theme, tabSize, meta, initial, final, ide } = parsed; const { frames, beforeFrame, afterFrame } = tokenized; - const duringFlashes: { style: DecorationStyle; range: GeneralizedRange }[] = + const duringFlashes: { style: OverlayStyleName; range: GeneralizedRange }[] = []; // Step 6b (derived referenceFlashes) — see derive-flashes.ts. When a fixture @@ -63,7 +63,7 @@ export function buildRenderObject( if (!fo) { continue; } - const style = String(fo.style) as DecorationStyle; + const style = String(fo.style) as OverlayStyleName; const range = toGeneralizedRange(asObj(fo.range) ?? {}); if (!range) { continue; diff --git a/packages/command-visualizer/src/logic/derive-flashes.ts b/packages/command-visualizer/src/logic/derive-flashes.ts index 4b90b5cb09..336b62d6ef 100644 --- a/packages/command-visualizer/src/logic/derive-flashes.ts +++ b/packages/command-visualizer/src/logic/derive-flashes.ts @@ -3,13 +3,13 @@ // the two document snapshots, returns the flashes to synthesize. No I/O, no // mutation of caller state. logic/ → logic/ import only. -import type { DecorationStyle } from "../data/decorations"; +import type { OverlayStyleName } from "../data/decorations"; import type { Decoration, GeneralizedRange } from "../model/frame-state"; import type { Pos } from "../model/geometry"; export interface DerivedFlashes { /** pendingDelete flashes to append to the DURING flash list (pre-edit). */ - duringFlashes: { style: DecorationStyle; range: GeneralizedRange }[]; + duringFlashes: { style: OverlayStyleName; range: GeneralizedRange }[]; /** justAdded flash decorations to push onto the AFTER frame (post-edit). */ afterDecorations: Decoration[]; } @@ -33,7 +33,7 @@ export function deriveFlashes(args: { hasAfterFrame: boolean; }): DerivedFlashes { const { recordedFlashCount, initDoc, finDoc, hasAfterFrame } = args; - const duringFlashes: { style: DecorationStyle; range: GeneralizedRange }[] = + const duringFlashes: { style: OverlayStyleName; range: GeneralizedRange }[] = []; const afterDecorations: Decoration[] = []; @@ -69,7 +69,7 @@ export function deriveFlashes(args: { const insEnd = finDoc.length - sfx; if (remEnd > p) { duringFlashes.push({ - style: "pendingDelete" as DecorationStyle, + style: "pendingDelete" as OverlayStyleName, range: { type: "character", start: toPos(initDoc, p), @@ -79,7 +79,7 @@ export function deriveFlashes(args: { } if (insEnd > p) { afterDecorations.push({ - style: "justAdded" as DecorationStyle, + style: "justAdded" as OverlayStyleName, role: "flash", range: { type: "character", diff --git a/packages/command-visualizer/src/logic/derive-overlays.ts b/packages/command-visualizer/src/logic/derive-overlays.ts index acf7fe7fe1..b5b9338a95 100644 --- a/packages/command-visualizer/src/logic/derive-overlays.ts +++ b/packages/command-visualizer/src/logic/derive-overlays.ts @@ -4,7 +4,7 @@ // append (before-frame highlights, after-frame that/source). No mutation of // caller state. logic/ → logic/ import only. -import type { DecorationStyle } from "../data/decorations"; +import type { OverlayStyleName } from "../data/decorations"; import type { Decoration } from "../model/frame-state"; import { asArr, @@ -41,7 +41,7 @@ export function deriveOverlays(args: { if (!ho) { continue; } - const style = String(ho.style) as DecorationStyle; + const style = String(ho.style) as OverlayStyleName; for (const r of asArr(ho.ranges)) { const range = toGeneralizedRange(asObj(r) ?? {}); if (range) { diff --git a/packages/command-visualizer/src/model/frame-state.ts b/packages/command-visualizer/src/model/frame-state.ts index 78fd72d14b..897949c6a7 100644 --- a/packages/command-visualizer/src/model/frame-state.ts +++ b/packages/command-visualizer/src/model/frame-state.ts @@ -5,7 +5,7 @@ import type { Theme } from "../data/colors"; import type { Line } from "./columns"; import type { Pos, Range } from "./geometry"; -import type { DecorationStyle } from "../data/decorations"; +import type { OverlayStyleName } from "../data/decorations"; export type FrameRole = "before" | "during" | "after"; @@ -31,7 +31,7 @@ export type LineRange = { export type GeneralizedRange = CharacterRange | LineRange; export interface Decoration { - style: DecorationStyle; + style: OverlayStyleName; range: GeneralizedRange; role: OverlayRole; } diff --git a/packages/command-visualizer/src/model/overlays.ts b/packages/command-visualizer/src/model/overlays.ts index 42bff4351e..4011d2c402 100644 --- a/packages/command-visualizer/src/model/overlays.ts +++ b/packages/command-visualizer/src/model/overlays.ts @@ -5,7 +5,7 @@ import { type Column, expandColumns } from "./columns"; import type { Decoration, Frame, OverlayRole } from "./frame-state"; -import type { DecorationStyle } from "../data/decorations"; +import type { OverlayStyleName } from "../data/decorations"; import { overlayPrecedence } from "../data/decorations"; import type { Range } from "./geometry"; @@ -28,16 +28,16 @@ function roleRank(role: OverlayRole | "selection"): number { export interface CellOverlay { /** the single winning background style for this cell (or null) */ - winner: DecorationStyle | "selection" | null; + winner: OverlayStyleName | "selection" | null; /** all overlays present (for data-flash-stack test visibility) */ - stack: (DecorationStyle | "selection")[]; + stack: (OverlayStyleName | "selection")[]; } export interface LineOverlay { /** per visual column -> overlay (indexed by Column.col start) */ byCol: Map<number, CellOverlay>; /** full-width line-range band style, if this line is in any line decoration */ - lineFlash: DecorationStyle | null; + lineFlash: OverlayStyleName | null; } /** Columns covered by a half-open character range on a given line. */ @@ -77,7 +77,7 @@ function resolveLine( const add = ( col: number, - style: DecorationStyle | "selection", + style: OverlayStyleName | "selection", role: OverlayRole | "selection", ) => { let cell = byCol.get(col); @@ -112,7 +112,7 @@ function resolveLine( } // character-range decorations (highlight prec 1, flash prec 2) - let lineFlash: DecorationStyle | null = null; + let lineFlash: OverlayStyleName | null = null; for (const dec of decorations) { if (dec.range.type === "line") { if (lineIdx >= dec.range.startLine && lineIdx <= dec.range.endLine) { From c3ac046ae9ca655d4262557b6c185756edffee5a Mon Sep 17 00:00:00 2001 From: Trillium Smith <trillium@trilliumsmith.com> Date: Wed, 8 Jul 2026 09:52:45 -0700 Subject: [PATCH 39/53] refactor(command-visualizer): idiomatic casts, camelCase fn, flow-narrow hats --- packages/command-visualizer/src/logic/pipeline.ts | 6 +++--- packages/command-visualizer/src/model/columns.ts | 14 +++++++++----- .../src/render/css-cascade-flash.ts | 10 +++++++--- 3 files changed, 19 insertions(+), 11 deletions(-) diff --git a/packages/command-visualizer/src/logic/pipeline.ts b/packages/command-visualizer/src/logic/pipeline.ts index e835b16874..61acf66609 100644 --- a/packages/command-visualizer/src/logic/pipeline.ts +++ b/packages/command-visualizer/src/logic/pipeline.ts @@ -37,7 +37,7 @@ export type { ParsedFixture, PipelineOptions, TokenizedStates }; // which must not fire at module load in serverless (the API path reads // bundled fixtures and never touches disk). let fixtureRootCache: string | undefined; -function FIXTURE_ROOT_LAZY(): string { +function fixtureRootLazy(): string { return (fixtureRootCache ??= fixtureRoot()); } @@ -157,8 +157,8 @@ export function loadFixtureCascade( fixtureRel: string, opts: PipelineOptions = {}, ): CascadeState { - const src = readFileSync(`${FIXTURE_ROOT_LAZY()}/${fixtureRel}`, "utf8"); + const src = readFileSync(`${fixtureRootLazy()}/${fixtureRel}`, "utf8"); return fixtureToCascade(src, fixtureRel, opts); } -export { FIXTURE_ROOT_LAZY as fixtureRootPath }; +export { fixtureRootLazy as fixtureRootPath }; diff --git a/packages/command-visualizer/src/model/columns.ts b/packages/command-visualizer/src/model/columns.ts index 2d714fea29..b64369a750 100644 --- a/packages/command-visualizer/src/model/columns.ts +++ b/packages/command-visualizer/src/model/columns.ts @@ -135,7 +135,11 @@ export function expandColumns(line: Line, tabSize: number): Column[] { graphemes.forEach((g, gi) => { const charIndex = token.range.start + g.offset; - const isAnchor = !!hat && gi === anchorIdx; + // Flow-narrowing: `anchorHat` is the token's hat only on the anchor + // grapheme, else undefined. Deriving it once lets the compiler narrow + // `anchorHat?.color`/`.shape` without a non-null assertion. + const anchorHat = gi === anchorIdx ? hat : undefined; + const isAnchor = anchorHat !== undefined; if (g.text === "\t") { const advance = tabSize - (col % tabSize) || tabSize; @@ -145,8 +149,8 @@ export function expandColumns(line: Line, tabSize: number): Column[] { width: advance, charIndex, isAnchor, - hatColor: isAnchor ? hat!.color : undefined, - hatShape: isAnchor ? hat!.shape : undefined, + hatColor: anchorHat?.color, + hatShape: anchorHat?.shape, }); col += advance; return; @@ -159,8 +163,8 @@ export function expandColumns(line: Line, tabSize: number): Column[] { width: w, charIndex, isAnchor, - hatColor: isAnchor ? hat!.color : undefined, - hatShape: isAnchor ? hat!.shape : undefined, + hatColor: anchorHat?.color, + hatShape: anchorHat?.shape, }); col += w; }); diff --git a/packages/command-visualizer/src/render/css-cascade-flash.ts b/packages/command-visualizer/src/render/css-cascade-flash.ts index 008c002bef..ad42595d47 100644 --- a/packages/command-visualizer/src/render/css-cascade-flash.ts +++ b/packages/command-visualizer/src/render/css-cascade-flash.ts @@ -2,7 +2,11 @@ // css-cascade.ts (the flash TIMING section) so the main module stays under the // 250-line limit. render/ → render/ import only; behavior unchanged. -import { DECORATION_HEX, FLASH_PULSE_MS } from "../data/decorations"; +import { + DECORATION_HEX, + FLASH_PULSE_MS, + type OverlayStyleName, +} from "../data/decorations"; import type { Frame } from "../model/frame-state"; import type { Timeline } from "../model/timeline"; import { pct } from "./css-cascade"; @@ -75,7 +79,7 @@ export function flashFadeKeyframes( // exist they take the first half and deletion follows at the midpoint; // with deletions only, red starts with the pill and holds to the edit. const hasRef = REFERENCE_FLASH_STYLES.some((st) => - styles.has(st as never), + styles.has(st as OverlayStyleName), ); const mid = (lo + hi) / 2; const refWin: [number, number] = [lo, mid]; @@ -129,7 +133,7 @@ export function flashFadeRules(frames: readonly Frame[]): string { if (frame.role === "during") { const styles = new Set(frame.decorations.map((d) => d.style)); for (const st of [...REFERENCE_FLASH_STYLES, "pendingDelete"]) { - if (!styles.has(st as never)) { + if (!styles.has(st as OverlayStyleName)) { continue; } rules.push( From 167521284ebbfd7977b841b2acd069a7cbb614d9 Mon Sep 17 00:00:00 2001 From: Trillium Smith <trillium@trilliumsmith.com> Date: Wed, 8 Jul 2026 10:02:40 -0700 Subject: [PATCH 40/53] docs(command-visualizer): strip dangling internal citations from comments --- .../command-visualizer/src/data/colors.ts | 2 +- .../src/data/decorations.ts | 15 ++++++------- .../command-visualizer/src/data/shapes.ts | 2 +- .../src/logic/build-render-object.ts | 2 +- .../command-visualizer/src/logic/chain.ts | 2 +- .../src/logic/derive-flashes.ts | 8 +++---- .../src/logic/fixture-extract.ts | 9 ++++---- .../src/logic/fixture-yaml.ts | 2 +- .../command-visualizer/src/logic/pipeline.ts | 12 +++++----- .../command-visualizer/src/logic/tokenize.ts | 19 ++++++++-------- .../command-visualizer/src/model/columns.ts | 10 ++++----- .../src/model/frame-state.ts | 8 +++---- .../command-visualizer/src/model/overlays.ts | 12 +++++----- .../command-visualizer/src/model/timeline.ts | 2 +- .../src/render/css-cascade-flash.ts | 14 ++++++------ .../src/render/css-cascade.ts | 22 +++++++++---------- packages/command-visualizer/src/render/css.ts | 18 +++++++-------- .../src/render/jumbotron.ts | 8 +++---- .../src/render/serialize-cascade.ts | 10 ++++----- .../src/render/serialize.ts | 2 +- .../command-visualizer/src/render/symbols.ts | 4 ++-- 21 files changed, 90 insertions(+), 93 deletions(-) diff --git a/packages/command-visualizer/src/data/colors.ts b/packages/command-visualizer/src/data/colors.ts index ede31d9818..07346b5244 100644 --- a/packages/command-visualizer/src/data/colors.ts +++ b/packages/command-visualizer/src/data/colors.ts @@ -3,7 +3,7 @@ // app-vscode/package.json as VS Code setting defaults (\`cursorless.colors.dark\`/ // \`.light\`) and read at runtime from VS Code config — there's no compile-time // constant to import, so a headless renderer mirrors the defaults here (verified -// against app-vscode/package.json 2026-06-08). SPEC §4.4. +// against app-vscode/package.json). // // The hat color VOCABULARY (\`HatColor\`, \`HAT_COLORS\`) is NOT re-exported here — // consumers import it directly from @cursorless/lib-common. diff --git a/packages/command-visualizer/src/data/decorations.ts b/packages/command-visualizer/src/data/decorations.ts index 3a0c08f8af..a6dbbf4e27 100644 --- a/packages/command-visualizer/src/data/decorations.ts +++ b/packages/command-visualizer/src/data/decorations.ts @@ -1,5 +1,4 @@ -// Decoration style hexes — VERBATIM from cursorless flash/highlight palette -// (research/highlight-rendering.md §3; verified 2026-06-08). SPEC-v2 §3.1. +// Decoration style hexes — VERBATIM from cursorless flash/highlight palette. // All background-only; alpha baked into the 8-digit hex; theme-INVARIANT. import { FlashStyle as CursorlessFlashStyle } from "@cursorless/lib-common"; @@ -20,10 +19,10 @@ export type HighlightStyle = "highlight0" | "highlight1"; export type OverlayStyleName = FlashStyle | HighlightStyle; // All 7 decoration styles' background hexes (the 2 scope-pair styles use the -// same band hex family; per-edge borders are BONUS, SPEC-v2 §3.5, not here). +// same band hex family; per-edge borders are not modeled here). export const DECORATION_HEX: Record<OverlayStyleName, string> = { - pendingDelete: "#ff00008a", // REQUIRED (COMPLETION crit 3) - justAdded: "#09ff005b", // REQUIRED (COMPLETION crit 3) + pendingDelete: "#ff00008a", + justAdded: "#09ff005b", referenced: "#00a2ff4d", pendingModification0: "#8c00ff86", pendingModification1: "#ff009d7e", @@ -45,7 +44,7 @@ export const HIGHLIGHT_STYLES: HighlightStyle[] = ["highlight0", "highlight1"]; // packages/app-vscode/src/ide/vscode/VscodeFlashHandler.ts:26 // flashRanges(...) → await sleep(getPendingEditDecorationTime()) → clear // A flash is a FIXED 100ms pulse, decoupled from the readability state-hold -// cadence (SPEC-v2 §4.2, B2/B6). Both the delete (pendingDelete) and insert +// cadence. Both the delete (pendingDelete) and insert // (justAdded) beats are pinned to this. verify:flash-timing is the oracle. export const FLASH_PULSE_MS = 100; @@ -61,8 +60,8 @@ export const ALL_DECORATION_STYLES: OverlayStyleName[] = [ ...HIGHLIGHT_STYLES, ]; -// Single-winner precedence (SPEC-v2 §3.2, DECISIONS §7.1): selection < highlight -// < flash, last wins; exactly ONE background per cell. Higher number wins. +// Single-winner precedence: selection < highlight < flash, last wins; exactly +// ONE background per cell. Higher number wins. export function overlayPrecedence( style: OverlayStyleName | "selection", ): number { diff --git a/packages/command-visualizer/src/data/shapes.ts b/packages/command-visualizer/src/data/shapes.ts index c0419404bc..5dd86c8cb4 100644 --- a/packages/command-visualizer/src/data/shapes.ts +++ b/packages/command-visualizer/src/data/shapes.ts @@ -2,7 +2,7 @@ // strings have no importable TS home: their canonical source is the 11 .svg files // under resources/images/hats/, which app-vscode's VscodeHatRenderer reads at // runtime — there's no compile-time constant, so a headless renderer carries the -// byte-for-byte paths here (verified against the source SVGs 2026-06-08). SPEC §4.1. +// byte-for-byte paths here (verified against the source SVGs). // // The shape VOCABULARY (\`HatShape\`, \`HAT_SHAPES\`, ...) and the shape-adjustment // constants (\`defaultShapeAdjustments\`, \`DEFAULT_HAT_HEIGHT_EM\`, diff --git a/packages/command-visualizer/src/logic/build-render-object.ts b/packages/command-visualizer/src/logic/build-render-object.ts index 03c76bb67e..9f9dc452cc 100644 --- a/packages/command-visualizer/src/logic/build-render-object.ts +++ b/packages/command-visualizer/src/logic/build-render-object.ts @@ -19,7 +19,7 @@ import type { TokenizedStates, } from "./pipeline-types"; -// Route a flash style to its native frame (SPEC-v2 §1.2 / §2.6). +// Route a flash style to its native frame. function flashRidesAfter(style: string): boolean { return style === "justAdded"; } diff --git a/packages/command-visualizer/src/logic/chain.ts b/packages/command-visualizer/src/logic/chain.ts index 1e7ee09833..f7557740c6 100644 --- a/packages/command-visualizer/src/logic/chain.ts +++ b/packages/command-visualizer/src/logic/chain.ts @@ -1,4 +1,4 @@ -// Multi-step chain semantics (Trillium's model, 2026-07-07): +// Multi-step chain semantics. Model: // // every entry: initialState / referenceFlashes[] / finalState // chained: finalState.i and initialState.{i+1} MUST agree, and the diff --git a/packages/command-visualizer/src/logic/derive-flashes.ts b/packages/command-visualizer/src/logic/derive-flashes.ts index 336b62d6ef..6906e430e3 100644 --- a/packages/command-visualizer/src/logic/derive-flashes.ts +++ b/packages/command-visualizer/src/logic/derive-flashes.ts @@ -1,4 +1,4 @@ -// Derived referenceFlashes — SPEC-v2 §2.6 (step 6b). Extracted verbatim from +// Derived referenceFlashes. Extracted verbatim from // pipeline.ts so fixtureToCascade stays under the 250-line limit. Pure: takes // the two document snapshots, returns the flashes to synthesize. No I/O, no // mutation of caller state. logic/ → logic/ import only. @@ -15,9 +15,9 @@ export interface DerivedFlashes { } /** - * Step 6b (derived referenceFlashes): tutorial-corpus recordings carry NO - * ide.flashes (verified 2026-07-07 — all 10 tutorial-1-basics fixtures have - * zero) even for document edits. Cursorless flashes are deterministic from + * Derived referenceFlashes: tutorial-corpus recordings carry NO + * ide.flashes (all 10 tutorial-1-basics fixtures have zero) even for document + * edits. Cursorless flashes are deterministic from * the edit itself, so when a fixture records none and the doc changed, * derive them: char-level common prefix/suffix -> removed span flashes * pendingDelete on BEFORE, inserted span flashes justAdded on AFTER. diff --git a/packages/command-visualizer/src/logic/fixture-extract.ts b/packages/command-visualizer/src/logic/fixture-extract.ts index 4d22c0506a..140bfadbbc 100644 --- a/packages/command-visualizer/src/logic/fixture-extract.ts +++ b/packages/command-visualizer/src/logic/fixture-extract.ts @@ -1,6 +1,6 @@ -// Field-extraction helpers for the fixture → state pipeline (SPEC-v2 §2 steps -// 3/4/5). Pulls the YAML-shape coercion + marks→hats + selections + range -// mapping out of pipeline.ts so each module stays under the line ceiling. +// Field-extraction helpers for the fixture → state pipeline. Pulls the +// YAML-shape coercion + marks→hats + selections + range mapping out of +// pipeline.ts so each module stays under the line ceiling. import type { YamlValue } from "./fixture-yaml"; import { tokenizeDoc } from "./tokenize"; @@ -108,8 +108,7 @@ export function buildLines( // Pass 1: command-relevant fixture marks — exact fixture color; shape is // "default" unless a per-fixture override says otherwise. Fixture mark keys // ({color}.{grapheme}) carry no shape component: the recorded session's - // hats were default-shape, so "default" is the faithful rendering (the old - // synthetic hash injected fake shapes here — removed in task-8tq). + // hats were default-shape, so "default" is the faithful rendering. for (const mk of marks) { if (mk.start.line !== mk.end.line) { continue; diff --git a/packages/command-visualizer/src/logic/fixture-yaml.ts b/packages/command-visualizer/src/logic/fixture-yaml.ts index cf7a260965..c33252c910 100644 --- a/packages/command-visualizer/src/logic/fixture-yaml.ts +++ b/packages/command-visualizer/src/logic/fixture-yaml.ts @@ -1,4 +1,4 @@ -// Fixture YAML reader — SPEC-v2 §2.1. +// Fixture YAML reader. // // Was a hand-rolled parser for the recorded-fixture YAML subset (block maps, // block scalars, block sequences, flow maps). Replaced with cursorless's own diff --git a/packages/command-visualizer/src/logic/pipeline.ts b/packages/command-visualizer/src/logic/pipeline.ts index 61acf66609..230073a003 100644 --- a/packages/command-visualizer/src/logic/pipeline.ts +++ b/packages/command-visualizer/src/logic/pipeline.ts @@ -1,7 +1,7 @@ -// Fixture → state pipeline — SPEC-v2 §2 (8 steps). Pure, deterministic. +// Fixture → state pipeline. Pure, deterministic. // yml → frames → tokenize → marks→hats → synthetic shape → flashes→overlays -// → that/source/highlights → CascadeState. Render contract (SPEC.md §3/§4) -// is unchanged downstream. +// → that/source/highlights → CascadeState. The render contract is unchanged +// downstream. // // The public `fixtureToCascade` is a thin composition of three named stages: // 1. parseFixture — YAML text → ParsedFixture (doc + meta + clipboard) @@ -64,8 +64,8 @@ export function parseFixture( const initial = asObj(doc.initialState); const final = asObj(doc.finalState); - // Clipboard visibility per state — ported from VisualizerMetadata.tsx - // (gen_2026_01_20): cut/copy PRODUCE clipboard (visible on AFTER only); + // Clipboard visibility per state — ported from cursorless's + // VisualizerMetadata.tsx: cut/copy PRODUCE clipboard (visible on AFTER only); // paste CONSUMES it (visible on all states). const actionName = meta.action ?? ""; const initClip = @@ -121,7 +121,7 @@ export function tokenizeStates( const frames: Frame[] = [beforeFrame]; - // AFTER frame (omit if no finalState — error fixtures, SPEC-v2 §2.2). + // AFTER frame (omit if no finalState — error fixtures). let afterFrame: Frame | null = null; if (final && typeof final.documentContents === "string") { // Final docs ship no marks; re-tokenize identically (no hats on after). diff --git a/packages/command-visualizer/src/logic/tokenize.ts b/packages/command-visualizer/src/logic/tokenize.ts index f7d9bf3843..f77c76bce6 100644 --- a/packages/command-visualizer/src/logic/tokenize.ts +++ b/packages/command-visualizer/src/logic/tokenize.ts @@ -1,19 +1,18 @@ -// Grapheme tokenizer + inverse detokenizer — SPEC-v2 §2.3, DECISIONS §7.4, R5. +// Grapheme tokenizer + inverse detokenizer. // -// Fixtures ship RAW `documentContents`, not tokens. SPEC.md §1 requires every -// column owned by exactly one token. R5 (grapheme-level hatting) splits each -// line into ONE TOKEN PER GRAPHEME — letters AND each individual symbol / -// operator / paren (`=>`, `(`, `)`, `:`, `;`, `"`, …) — exactly like real -// cursorless (GRAPHEME_SPLIT_REGEX, tokenGraphemeSplitter.ts:73). Whitespace -// runs between graphemes become their own (non-hattable) tokens. Each token -// carries its UTF-16 line offsets, so the grapheme/column math (SPEC.md §2) -// runs unchanged. +// Fixtures ship RAW `documentContents`, not tokens, and every column must be +// owned by exactly one token. Grapheme-level hatting splits each line into ONE +// TOKEN PER GRAPHEME — letters AND each individual symbol / operator / paren +// (`=>`, `(`, `)`, `:`, `;`, `"`, …) — exactly like real cursorless +// (GRAPHEME_SPLIT_REGEX, tokenGraphemeSplitter.ts). Whitespace runs between +// graphemes become their own (non-hattable) tokens. Each token carries its +// UTF-16 line offsets, so the grapheme/column math runs unchanged. // // Because each non-whitespace token is now a single grapheme, fixture-extract // can attach a hat to EVERY grapheme (one hat per token, anchored at the // token's first — and only — grapheme), matching cursorless's dense hatting. // -// GATE 0 (SPEC-v2 named risk): detokenize(tokenize(doc)) === doc BYTE-FOR-BYTE. +// GATE 0: detokenize(tokenize(doc)) === doc BYTE-FOR-BYTE. // Detokenize concatenates token text in order; since the union of grapheme + // whitespace tokens partitions the line with no gaps or overlaps, the roundtrip // stays byte-exact. The roundtrip test (src/verify-roundtrip-doc.ts) proves it. diff --git a/packages/command-visualizer/src/model/columns.ts b/packages/command-visualizer/src/model/columns.ts index b64369a750..5ca04492dc 100644 --- a/packages/command-visualizer/src/model/columns.ts +++ b/packages/command-visualizer/src/model/columns.ts @@ -1,10 +1,10 @@ -// Column model — SPEC §2 (resolves D7). +// Column model. // Converts each line's UTF-16 token stream into an ordered list of VISUAL columns. // Build-time only; no render-time logic. // -// - Graphemes per cursorless GRAPHEME_SPLIT_REGEX (SPEC §2.1). -// - Tab → next tabSize stop (SPEC §2.2). -// - East-Asian Wide/Fullwidth glyph = 2 columns (SPEC §2.3). +// - Graphemes per cursorless GRAPHEME_SPLIT_REGEX. +// - Tab → next tabSize stop. +// - East-Asian Wide/Fullwidth glyph = 2 columns. import type { HatColor, HatShape } from "@cursorless/lib-common"; import { GRAPHEME_SPLIT_REGEX } from "@cursorless/lib-engine"; @@ -121,7 +121,7 @@ export function splitGraphemes(text: string): GraphemeUnit[] { } /** - * Expand a line's tokens into ordered visual columns (SPEC §2). + * Expand a line's tokens into ordered visual columns. * Resolves each hat's anchor to a computed visual column (never a raw char index). */ export function expandColumns(line: Line, tabSize: number): Column[] { diff --git a/packages/command-visualizer/src/model/frame-state.ts b/packages/command-visualizer/src/model/frame-state.ts index 897949c6a7..7a268ad7d1 100644 --- a/packages/command-visualizer/src/model/frame-state.ts +++ b/packages/command-visualizer/src/model/frame-state.ts @@ -1,6 +1,6 @@ -// Multi-frame state schema — SPEC-v2 §1. A FRAME is exactly one SPEC.md -// `.cl-editor` surface (EditorState minus the doc-level theme/tab). v2 wraps an -// ordered list of frames in a cascade and adds the decoration OVERLAY layer. +// Multi-frame state schema. A FRAME is exactly one `.cl-editor` surface +// (EditorState minus the doc-level theme/tab). A cascade wraps an ordered list +// of frames and adds the decoration OVERLAY layer. import type { Theme } from "../data/colors"; import type { Line } from "./columns"; @@ -16,7 +16,7 @@ export type OverlayRole = | "source" | `scope:${string}`; -// GeneralizedRange (SPEC-v2 §1.1) — character (half-open columns) or line +// GeneralizedRange — character (half-open columns) or line // (full-width, endLine INCLUSIVE). export type CharacterRange = { type: "character"; diff --git a/packages/command-visualizer/src/model/overlays.ts b/packages/command-visualizer/src/model/overlays.ts index 4011d2c402..6793c441d0 100644 --- a/packages/command-visualizer/src/model/overlays.ts +++ b/packages/command-visualizer/src/model/overlays.ts @@ -1,7 +1,7 @@ -// Overlay resolution — SPEC-v2 §3.2 / §6. Maps a frame's decorations + selection -// onto the COLUMN grid (SPEC.md §2 column mapping, not raw char index — audit-5 -// §4 rule), resolving single-winner precedence per cell (selection < highlight < -// flash, last wins). Also resolves full-width line-range bands. +// Overlay resolution. Maps a frame's decorations + selection onto the COLUMN +// grid (column mapping, not raw char index), resolving single-winner precedence +// per cell (selection < highlight < flash, last wins). Also resolves full-width +// line-range bands. import { type Column, expandColumns } from "./columns"; import type { Decoration, Frame, OverlayRole } from "./frame-state"; @@ -9,8 +9,8 @@ import type { OverlayStyleName } from "../data/decorations"; import { overlayPrecedence } from "../data/decorations"; import type { Range } from "./geometry"; -// Role sub-rank, used to break style-precedence ties (SPEC-v2 §3.2 / DECISIONS -// §7.1+§7.2): a REAL ide.flash outranks a DERIVED that/source overlay on the +// Role sub-rank, used to break style-precedence ties: a REAL ide.flash outranks +// a DERIVED that/source overlay on the // same range, so e.g. justAdded (flash) wins over a thatMark→referenced on the // inserted text. selection < highlight < {derived that/source} < flash. function roleRank(role: OverlayRole | "selection"): number { diff --git a/packages/command-visualizer/src/model/timeline.ts b/packages/command-visualizer/src/model/timeline.ts index ecca475dab..4db1811b07 100644 --- a/packages/command-visualizer/src/model/timeline.ts +++ b/packages/command-visualizer/src/model/timeline.ts @@ -1,4 +1,4 @@ -// Weighted step timeline (Trillium spec, 2026-07-07). Frame phase names: +// Weighted step timeline. Frame phase names: // // pre 500ms pre-gif bumper (initial state, no command) // step0.initial 2000ms diff --git a/packages/command-visualizer/src/render/css-cascade-flash.ts b/packages/command-visualizer/src/render/css-cascade-flash.ts index ad42595d47..48ae7aa7b7 100644 --- a/packages/command-visualizer/src/render/css-cascade-flash.ts +++ b/packages/command-visualizer/src/render/css-cascade-flash.ts @@ -1,6 +1,6 @@ -// Cascade flash-fade CSS — SPEC-v2 §4.2 DURING beats. Extracted verbatim from -// css-cascade.ts (the flash TIMING section) so the main module stays under the -// 250-line limit. render/ → render/ import only; behavior unchanged. +// Cascade flash-fade CSS — DURING beats. Extracted verbatim from css-cascade.ts +// (the flash TIMING section) so the main module stays under the 250-line limit. +// render/ → render/ import only; behavior unchanged. import { DECORATION_HEX, @@ -11,16 +11,16 @@ import type { Frame } from "../model/frame-state"; import type { Timeline } from "../model/timeline"; import { pct } from "./css-cascade"; -// §4.2 DURING beats — flash TIMING. A flash is a TRANSIENT beat *within* one +// DURING beats — flash TIMING. A flash is a TRANSIENT beat *within* one // frame's timeline slot, not a static band. Two opposite directions: // -// DELETE (R2-i, pendingDelete) rides the BEFORE frame (frame 0, slot [0, 1/N]): +// DELETE (pendingDelete) rides the BEFORE frame (frame 0, slot [0, 1/N]): // plain (band transparent) → hold plain → red band fades IN // then the frame's opacity snap crosses to the after-frame (text gone). The band // fades in LATE in the slot so the before-doc reads plain first, then highlights // the doomed span just before it vanishes. // -// ADD (R2-ii, justAdded) rides the AFTER frame (frame N-1, slot [(N-1)/N, 1]): +// ADD (justAdded) rides the AFTER frame (frame N-1, slot [(N-1)/N, 1]): // green band PRESENT → hold green → green band fades OUT → plain (text stays) // the insert just happened, so the green is up-front when the after-frame appears, // then fades out over the latter part of the slot leaving plain text behind. This @@ -33,7 +33,7 @@ import { pct } from "./css-cascade"; const ADD_FLASH_STYLES = ["justAdded"] as const; -// B2/B6 FIX — the flash is a FIXED 100ms pulse, pinned to cursorless's +// The flash is a FIXED 100ms pulse, pinned to cursorless's // `pendingEditDecorationTime` (FLASH_PULSE_MS), DECOUPLED from the readability // state-hold cadence. // diff --git a/packages/command-visualizer/src/render/css-cascade.ts b/packages/command-visualizer/src/render/css-cascade.ts index ea3c75d7bf..f1ba864e94 100644 --- a/packages/command-visualizer/src/render/css-cascade.ts +++ b/packages/command-visualizer/src/render/css-cascade.ts @@ -1,5 +1,5 @@ -// Cascade + overlay CSS — SPEC-v2 §3 (highlight bands) + §4 (stacked-frame -// opacity timeline). Generated from the single-sourced decoration hexes so the +// Cascade + overlay CSS — highlight bands + stacked-frame opacity timeline. +// Generated from the single-sourced decoration hexes so the // band colors never drift. Theme-INVARIANT (background-only translucent hexes). import { DECORATION_HEX, ALL_DECORATION_STYLES } from "../data/decorations"; @@ -27,11 +27,11 @@ function charBandRules(): string { // (render/ → render/ import; no duplication). export const pct = (x: number): string => x.toFixed(3); -// The flash TIMING section (DURING beats: delete R2-i, insert R2-ii, reference -// pre-edit flashes) lives in ./css-cascade-flash — imported above. See that -// module's header for the full SPEC-v2 §4.2 rationale. +// The flash TIMING section (DURING beats: delete, insert, reference pre-edit +// flashes) lives in ./css-cascade-flash — imported above. See that module's +// header for the full rationale. -// §3.4 — full-width line-range bands on .cl-line (content box, DECISIONS §7.7). +// Full-width line-range bands on .cl-line (content box). function lineBandRules(): string { return ALL_DECORATION_STYLES.map( (s) => @@ -39,7 +39,7 @@ function lineBandRules(): string { ).join("\n"); } -// §4.2 — per-frame opacity timeline. Frame k of N is opaque on [k/N,(k+1)/N). +// Per-frame opacity timeline. Frame k of N is opaque on [k/N,(k+1)/N). // steps(1,end) gives a hard BEFORE→AFTER snap (no ghosty in-between). function frameKeyframes(tl: Timeline): string { const n = tl.startFrac.length; @@ -77,14 +77,14 @@ export function cascadeStyleSheet( // renders keep the pure-static band (Phase-3 PNG tests must stay green). const animated = n >= 2; const flashFade = animated - ? `\n/* ---- DURING beats: delete (R2-i) + insert (R2-ii) flash-timing (SPEC-v2 §4.2) ---- */\n${flashFadeKeyframes(frames, tl, flashPulseMs)}\n${flashFadeRules(frames)}\n` + ? `\n/* ---- DURING beats: delete + insert flash-timing ---- */\n${flashFadeKeyframes(frames, tl, flashPulseMs)}\n${flashFadeRules(frames)}\n` : ""; - return `/* ---- decoration overlay layer (SPEC-v2 §3) ---- */ + return `/* ---- decoration overlay layer ---- */ ${charBandRules()} ${lineBandRules()} ${flashFade} -/* ---- cascade container + stacked frames (SPEC-v2 §4.1) ---- */ +/* ---- cascade container + stacked frames ---- */ .cl-cascade { position: relative; display: inline-block; @@ -116,7 +116,7 @@ ${flashFade} white-space: pre; } -/* ---- per-frame opacity timeline (SPEC-v2 §4.2) ---- */ +/* ---- per-frame opacity timeline ---- */ ${frameKeyframes(tl)} /* the static (non-animated) default: show the LAST frame so a no-capture view diff --git a/packages/command-visualizer/src/render/css.ts b/packages/command-visualizer/src/render/css.ts index 91bf7677d1..66d4d809d5 100644 --- a/packages/command-visualizer/src/render/css.ts +++ b/packages/command-visualizer/src/render/css.ts @@ -1,4 +1,4 @@ -// CSS contract — SPEC §4. Generated from the single-sourced data so color + +// CSS contract. Generated from the single-sourced data so color + // adjustment values never drift. No render-time JS; CSS does 100% of visual work. import { @@ -53,7 +53,7 @@ function themeVars(theme: "dark" | "light"): string { } export function styleSheet(): string { - return `/* Cursorless state → static CSS. SPEC §4. Generated; do not hand-edit. */ + return `/* Cursorless state → static CSS. Generated; do not hand-edit. */ :root { --hat-height: ${DEFAULT_HAT_HEIGHT_EM}em; @@ -67,10 +67,10 @@ export function styleSheet(): string { --code-line-height: 1.35; } -/* ---- per-shape adjustments (shapeAdjustments.ts, SPEC §4.2) ---- */ +/* ---- per-shape adjustments (shapeAdjustments.ts) ---- */ ${shapeAdjustmentRules()} -/* ---- color tint vars (SPEC §4.4) ---- */ +/* ---- color tint vars ---- */ ${colorVarRules()} ${themeVars("dark")} @@ -96,7 +96,7 @@ ${themeVars("light")} .cl-code { font-family: "JetBrains Mono", "SF Mono", "Menlo", ui-monospace, monospace; font-size: 18px; - font-variant-ligatures: none; /* D8: 1 glyph = its column(s) */ + font-variant-ligatures: none; /* 1 glyph = its column(s) */ font-feature-settings: "liga" 0, "calt" 0; letter-spacing: 0; line-height: var(--code-line-height); @@ -113,7 +113,7 @@ ${themeVars("light")} box (0-height block contributes nothing), aligning frame 0 with the rest. */ svg.cl-defs { display: block; } -/* ---- per-char column grid (D8) ---- */ +/* ---- per-char column grid ---- */ .ch { display: inline-block; position: relative; /* hat's offset parent — no long-line drift */ @@ -128,7 +128,7 @@ svg.cl-defs { display: block; } .ch[data-col-span="7"] { width: 7ch; } .ch[data-col-span="8"] { width: 8ch; } -/* ---- hat (SPEC §4.3): tint via color + currentColor (D4) ---- */ +/* ---- hat: tint via color + currentColor ---- */ .hat { position: absolute; left: 50%; @@ -164,7 +164,7 @@ svg.cl-defs { display: block; } display: block; } -/* ---- cursor + selection (SPEC §4.5) ---- */ +/* ---- cursor + selection ---- */ .caret[data-cursor] { display: inline-block; width: 0; height: 1.2em; @@ -174,7 +174,7 @@ svg.cl-defs { display: block; } } .ch[data-sel] { background: var(--editor-sel); } -/* ---- optional line-number gutter (R3): OFF by default ---- +/* ---- optional line-number gutter: OFF by default ---- A leading inline-block .cl-lineno per .cl-line. Because the number shares the line box with its code, it aligns to that exact row automatically — works identically for single-frame renders and absolutely-positioned stacked cascade diff --git a/packages/command-visualizer/src/render/jumbotron.ts b/packages/command-visualizer/src/render/jumbotron.ts index 210357b9ae..16aeba3c0d 100644 --- a/packages/command-visualizer/src/render/jumbotron.ts +++ b/packages/command-visualizer/src/render/jumbotron.ts @@ -1,7 +1,7 @@ -// Jumbotron shape — ported from Trillium's VisualizerWrapper implementation -// (cursorless fork branch gen_2026_01_20, packages/test-case-component/src/ -// components/VisualizerWrapper/: JumbotronView.tsx, VisualizerMetadata.tsx, -// StateNavigationDots.tsx, VisualizerWrapper.css). See brain-a08pj. +// Jumbotron shape — ported from a cursorless VisualizerWrapper implementation +// (packages/test-case-component/src/components/VisualizerWrapper/: +// JumbotronView.tsx, VisualizerMetadata.tsx, StateNavigationDots.tsx, +// VisualizerWrapper.css). // // EVERY render uses the jumbo shape, one step or many: // diff --git a/packages/command-visualizer/src/render/serialize-cascade.ts b/packages/command-visualizer/src/render/serialize-cascade.ts index 48514f6a75..7e41dd9f5f 100644 --- a/packages/command-visualizer/src/render/serialize-cascade.ts +++ b/packages/command-visualizer/src/render/serialize-cascade.ts @@ -1,4 +1,4 @@ -// Cascade serializer — SPEC-v2 §4. Pure CascadeState → HTML. Zero render-time JS. +// Cascade serializer. Pure CascadeState → HTML. Zero render-time JS. // Emits N stacked `.frame` surfaces in one `.cl-cascade`, the symbol sheet ONCE, // per-frame `@keyframes f{k}` opacity timeline, and the decoration overlay layer // (data-flash / data-hl / data-line-flash) resolved single-winner per cell. @@ -85,7 +85,7 @@ function emitLine( ); } - // R3: optional leading line-number cell (1-based, like a real editor). Only + // Optional leading line-number cell (1-based, like a real editor). Only // emitted when the gutter is on — keeps the no-gutter output byte-identical. const gutter = lineNumbers ? `<span class="cl-lineno" aria-hidden="true">${lineIdx + 1}</span>` @@ -109,7 +109,7 @@ function emitLine( // NO leading whitespace and NO newline joins around cl-line: this markup // lives inside .cl-code (white-space: pre), where inter-element whitespace // renders as phantom blank lines (latent flaw exposed by the fixed-height - // SVG viewport, task-mim). + // SVG viewport). return `<div class="cl-line" data-line="${lineIdx}"${lineFlashAttr}>${gutter}${inner}</div>`; } @@ -132,7 +132,7 @@ function emitFrame( /** Render options for the cascade serializer. */ export interface CascadeRenderOptions { - /** R3: emit the left line-number gutter. OFF by default. */ + /** Emit the left line-number gutter. OFF by default. */ lineNumbers?: boolean; } @@ -159,7 +159,7 @@ export function serializeCascade( const spokenAttr = state.meta?.spokenForm ? ` data-spoken-form="${esc(state.meta.spokenForm)}"` : ""; - // R3: only when ON do we add the gutter attribute + digit-width var. OFF → + // Only when ON do we add the gutter attribute + digit-width var. OFF → // neither appears, so the markup/CSS hook is byte-identical to before. const gutterAttr = lineNumbers ? ` data-line-numbers=""` : ""; const gutterVar = lineNumbers diff --git a/packages/command-visualizer/src/render/serialize.ts b/packages/command-visualizer/src/render/serialize.ts index 1d5c434a4b..88be738306 100644 --- a/packages/command-visualizer/src/render/serialize.ts +++ b/packages/command-visualizer/src/render/serialize.ts @@ -1,4 +1,4 @@ -// Serializer — SPEC §5. Pure state JSON → HTML string. No render-time logic (D1). +// Serializer. Pure state JSON → HTML string. No render-time logic. import type { Theme } from "../data/colors"; import { type Column, type Line, expandColumns, lineWidth } from "../model/columns"; diff --git a/packages/command-visualizer/src/render/symbols.ts b/packages/command-visualizer/src/render/symbols.ts index 7a6ba6495a..44ed1f6466 100644 --- a/packages/command-visualizer/src/render/symbols.ts +++ b/packages/command-visualizer/src/render/symbols.ts @@ -1,7 +1,7 @@ -// Symbol sheet — SPEC §3 / §4.1. +// Symbol sheet. // Emits the shared inline <svg><defs> with 11 <symbol> defs ONCE per document. // Each path + per-shape fill-rule is verbatim from source (src/data/shapes.ts); -// fill="currentColor" so a hat is tinted by CSS `color` (D4). +// fill="currentColor" so a hat is tinted by CSS `color`. import { HAT_SHAPES } from "@cursorless/lib-common"; import { SHAPE_PATHS } from "../data/shapes"; From f997326036d2ad348fab264c3b2dbfb532a94761 Mon Sep 17 00:00:00 2001 From: Trillium Smith <trillium@trilliumsmith.com> Date: Wed, 8 Jul 2026 10:04:26 -0700 Subject: [PATCH 41/53] docs(command-visualizer): add README, keep ARCHITECTURE, drop STATUS/PR-DRAFT --- packages/command-visualizer/PR-DRAFT.md | 126 --------------------- packages/command-visualizer/README.md | 98 +++++++++++++++++ packages/command-visualizer/STATUS.md | 134 ----------------------- packages/command-visualizer/src/index.ts | 2 +- 4 files changed, 99 insertions(+), 261 deletions(-) delete mode 100644 packages/command-visualizer/PR-DRAFT.md create mode 100644 packages/command-visualizer/README.md delete mode 100644 packages/command-visualizer/STATUS.md diff --git a/packages/command-visualizer/PR-DRAFT.md b/packages/command-visualizer/PR-DRAFT.md deleted file mode 100644 index 72c47a2aea..0000000000 --- a/packages/command-visualizer/PR-DRAFT.md +++ /dev/null @@ -1,126 +0,0 @@ -# PR draft — `@cursorless/command-visualizer`: animated SVG cascades from recorded fixtures - -> Status: LOCAL DRAFT (2026-07-07). Not filed. Target: cursorless-dev/cursorless. -> Branch in fork: `command-visualizer` (scaffold commit `2b4d027`). - ---- - -## What this adds - -A new package, `@cursorless/command-visualizer`, that turns recorded test -fixtures (`data/fixtures/recorded/**/*.yml`) into **animated SVG -visualizations** of cursorless commands — before/during/after cascades with -real hat allocation, flash sequencing, selections, and a command "jumbotron" -— embeddable anywhere a plain `<img>` works (GitHub READMEs via camo, docs -pages, tutorials). - -**Live demo of the exact code in this PR:** -https://cursorless-css-state.vercel.app/ (gallery) — e.g. the full -tutorial-1 sequence as one looping image: - -``` -/api/cascade?fixture=tutorial/tutorial-1-basics -``` - -The renderer is a pure function: fixture YAML in → self-contained SVG string -out. Zero runtime JavaScript in the output, no DOM or browser dependency to -render, and every animation rides one CSS `--dur` timeline so outputs are -deterministic and testable by seeking. - -## Why cursorless might want this - -- **Docs and tutorials that show, not tell.** Every recorded fixture becomes - a looping visual: spoken command entering, flashes firing, the edit - landing, hats reallocating. The tutorial sequences render as one - continuous animation. -- **The fixtures are already the perfect substrate.** This consumes recorded - test YAMLs verbatim — the corpus you already maintain becomes a - documentation asset for free. -- **Faithful by construction, not by imitation:** - - Hat allocation is _your_ algorithm (`chooseTokenHat` + - `getHatRankingContext`, vendored verbatim; see companion proposal below), - one hat per token, proven byte-identical to a bundled engine build. - - Flash classes follow the action source exactly (matrix extracted from - `packages/cursorless-engine/src/actions/*`): pre-edit flashes - (`pendingDelete`, `referenced`, `pendingModification0/1`) precede the - edit, `justAdded` follows it. The 100ms - `pendingEditDecorationTime` pulse is pinned N-invariantly by a timing - oracle. Timing is deliberately expanded for readability (documented - divergence: pre-edit flashes render sequenced reference→delete rather - than parallel). - -## The model - -``` -pre (bumper) → [ step.initial → step.during → step.final ]* → post (reset) -``` - -- **Chains are contract-checked:** `finalState.i` must equal - `initialState.{i+1}` (400 otherwise), and the boundary renders as ONE - merged frame already wearing the next step's hats — one animated change, - exactly as in the editor. -- **The during phase is the execution beat:** command pill activates, its - step dot gains the issued ring, and flashes initiate — all in the same - instant. Flash-less commands (pure selections) show their final state in - this beat, matching the editor's instantaneous selection. -- **Durations are parameters** (`initial/during/bumper` ms, float `scale`), - defaults `[2000, 1000, 500]`. -- Fixtures with no recorded `ide.flashes` (e.g. the tutorial corpus) get - flashes **derived from the edit diff**; recorded flashes are used verbatim - when present. - -## Test story (ports with the package) - -- 79 API-contract checks (params, typed errors, XML validity for - `foreignObject`, real `<img>` SVG-as-image rendering in Chromium) -- 54 timeline e2e checks — WAAPI seek to exact beats: flash windows and - doomed-token ranges, pill/dot/flash simultaneity, backward hat flow - (merged-frame hat signature must equal a standalone render of the next - step's initial state), command centering (±2px), never-truncate text - fitting, no-seek wall-clock animation liveness -- 24 SVG layout checks (content fits the declared viewport across the - corpus, chains, themes) -- Flash-timing oracle: insert = 100ms N-invariant; delete windows structural -- Plus the renderer's own column-model / roundtrip / pixel-oracle suites - -## Companion proposal (separable) - -`@cursorless/hat-allocator`: export the allocation subgraph -(`allocateHats`'s unexported loop + `chooseTokenHat` + -`getHatRankingContext` + a static-config grapheme splitter) as a standalone -entry point with a tokens-in interface. Three downstream re-implementations -currently vendor or re-bundle this identical code (Talon prose overlay, an -iOS port's oracle, this renderer); one exported entry point serves all. The -extraction shipped standalone as `allocate-hats` with a 200-case -byte-equivalence proof against a bundled engine build — the PR would move it -inward and dissolve the dependency. - -## Open questions for maintainers - -1. **Package name/home**: `packages/command-visualizer` (naming rationale: - describes what the viewer sees — a command executing — rather than the - implementation; considered `cascade-renderer`, `fixture-visualizer`, - `test-case-visualizer`) vs living beside - `test-case-component` (which it complements: static React component vs - embeddable animated SVG). -2. **Fixture ingestion**: read `data/fixtures/recorded/**` directly - in-monorepo (the standalone deploy vendors YAMLs for serverless). -3. **Hosting**: should cursorless.org serve the endpoint (docs embeds), or - is the library alone in scope? -4. **Timing divergence**: is the expanded pedagogical timing acceptable as - the default, given the faithful 100ms mode is one parameter away - (`scale`/`flash`)? - -## Checklist - -- [ ] Re-vendor allocation against `packages/lib-engine` @ upstream HEAD — - the algorithm evolved since the 42452eb pin (`forcedTokenHat` param, - `avoidFirstLetter` metric, `lib-common` rename); assignments change, - so a fresh equivalence baseline is required (task-1e8 in the - standalone repo) -- [ ] `pnpm compile` green in-monorepo (scaffold imports verbatim; two - integration seams documented in `STATUS.md`) -- [ ] Port the gate suites into the monorepo test layout -- [ ] Companion hat-allocator PR (or fold into this one per maintainer - preference) -- [ ] Docs page embedding a live cascade diff --git a/packages/command-visualizer/README.md b/packages/command-visualizer/README.md new file mode 100644 index 0000000000..24ecaa5274 --- /dev/null +++ b/packages/command-visualizer/README.md @@ -0,0 +1,98 @@ +# @cursorless/command-visualizer + +Turn recorded cursorless test fixtures into **animated SVG visualizations** of +commands — before/during/after cascades with real hat allocation, flash +sequencing, selections, and a command "jumbotron". The output is a +self-contained SVG string embeddable anywhere a plain `<img>` works (GitHub +READMEs via camo, docs pages, tutorials). + +The renderer is a pure function: fixture YAML in → self-contained SVG string +out. There is zero runtime JavaScript in the output, no DOM or browser +dependency to render, and every animation rides one CSS `--dur` timeline, so +outputs are deterministic and testable by seeking. + +```ts +import { renderCommand } from "@cursorless/command-visualizer"; + +const svg = renderCommand(fixtureYamlText, "recorded/foo/bar.yml", { + theme: "dark", +}); +``` + +## The animation model + +``` +pre (bumper) → [ step.initial → step.during → step.final ]* → post (reset) +``` + +- **The during phase is the execution beat:** the command pill activates, its + step dot gains the issued ring, and flashes initiate — all in the same + instant. Flash-less commands (pure selections) show their final state in this + beat, matching the editor's instantaneous selection. +- **Chains are contract-checked:** `finalState.i` must equal + `initialState.{i+1}`, and the boundary renders as ONE merged frame already + wearing the next step's hats — one animated change, exactly as in the editor. +- **Durations are parameters** (`initial` / `during` / `bumper` ms, plus a float + `scale`); defaults are `[2000, 1000, 500]`. +- Fixtures with no recorded `ide.flashes` (e.g. the tutorial corpus) get flashes + **derived from the edit diff**; recorded flashes are used verbatim when + present. + +Flash classes follow the action source exactly: pre-edit flashes +(`pendingDelete`, `referenced`, `pendingModification0`/`1`) precede the edit and +`justAdded` follows it. The 100ms `pendingEditDecorationTime` pulse is pinned +N-invariantly (independent of the number of frames). Pre-edit flashes render +sequenced (reference → delete) rather than in parallel — a deliberate +readability divergence from the editor. + +## Architecture + +Source is organized into four scopes with a strict one-directional dependency +rule (`render/` and `logic/` never import each other). The layering diagram, the +4-stage pipeline table, and the grep commands that verify the dependency rule +live in [`src/ARCHITECTURE.md`](./src/ARCHITECTURE.md). + +## Reuse of cursorless source + +This package deliberately imports from cursorless packages rather than cloning, +and documents the cases where a local copy is the faithful choice. + +Imported from cursorless (not cloned): + +- `DefaultMap` / `CompositeKeyMap`, `FlashStyle` — from `@cursorless/lib-common`. +- `GRAPHEME_SPLIT_REGEX`, `maxByFirstDiffering`, the `allocateHats` primitives — + from `@cursorless/lib-engine`. +- Fixture YAML is parsed with `js-yaml` (the same library `@cursorless/lib-node-common`'s + `loadFixture.ts` uses). + +Kept local, with provenance, where importing would regress or balloon scope: + +- **`data/decorations.ts`** — `FlashStyle` is a string union derived from + lib-common's `FlashStyle` enum; it composes with `HighlightStyle` into the + `OverlayStyleName` keys. The `DECORATION_HEX` values, pulse timing, and + precedence are local (cursorless does not export them). Note: this package's + `OverlayStyleName` is unrelated to lib-common's `DecorationStyle` (a + border-geometry interface) — the rename avoids that collision. +- **`data/colors.ts` / `data/shapes.ts`** — the color hexes live in + `app-vscode/package.json` as VS Code setting defaults (read at runtime, never a + TS constant) and the shape SVG `d=` path strings live in + `resources/images/hats/*.svg` (read at runtime by `VscodeHatRenderer`). There + is no importable TS module, so these are mirrored here with provenance comments + naming the exact upstream source. +- **`logic/fixture-root.ts`** — keeps its dual directory-layout probe and + `$CURSORLESS_REPO` override; lib-node-common's `getFixturesPath` hardcodes one + layout and throws unless `CURSORLESS_REPO_ROOT` is set. +- **`logic/fixture-extract.ts`** — `parseMarks` / `buildLines` read plain YAML + with no editor, whereas lib-common's `serializedMarksToTokenHats` needs a live + `TextEditor` and returns engine `TokenHat[]`. + +## Development + +```sh +# typecheck +tsc -p packages/command-visualizer/tsconfig.json --noEmit +``` + +The renderer resolves recorded fixtures from a cursorless checkout. Set +`CURSORLESS_REPO` to point at your checkout if it is not at +`$HOME/code/cursorless`. diff --git a/packages/command-visualizer/STATUS.md b/packages/command-visualizer/STATUS.md deleted file mode 100644 index 2613edd7e0..0000000000 --- a/packages/command-visualizer/STATUS.md +++ /dev/null @@ -1,134 +0,0 @@ -# Integration status - -This package renders cursorless command fixtures as animated SVGs. It has been -reworked to deduplicate against cursorless's public API and to compile -in-monorepo. Everything below touches ONLY `packages/command-visualizer/`. - -## Done - -1. **allocate-hats internalized** (step 1). The unpublished `allocate-hats@0.1.0` - npm dependency (it lived only at `~/code/allocate-hats`, never on npm) is - gone. Its `src/` tree is vendored verbatim under - `src/vendor/allocate-hats/` (cursorless SHA `42452eb`); `hat-allocator.ts` - imports from `./vendor/allocate-hats/index`. The unused QuickJS entry points - (`bundle.ts`, `proseCompat.ts`) were dropped. The vendored tree - self-typechecks clean in isolation. See - `src/vendor/allocate-hats/VENDOR.md`. -2. **YAML via js-yaml** (step 2). The hand-rolled fixture-YAML subset parser is - replaced by `js-yaml`'s `load()` — the same library and entry point - `@cursorless/lib-node-common`'s `loadFixture.ts` uses. `yaml-scalars.ts` was - deleted; `parseFixtureYaml` and the `YamlValue` type surface are preserved. -3. **Workspace deps declared** (step 3). `package.json` now depends on - `@cursorless/lib-common` and `@cursorless/lib-node-common` (`workspace:*`), - plus `js-yaml ^5.2.1` and `@types/js-yaml ^4.0.9` (matching the versions - lib-common / lib-node-common declare). -4. **Dedup review** (step 4). All three public-import candidates were evaluated - and deliberately KEPT with provenance notes (switching each is invasive, - regressive, or scope-ballooning — never their code needed changing): - - `data/decorations.ts` `FlashStyle` — string union whose values match - lib-common's `FlashStyle` enum, but it composes with `HighlightStyle` into - `DecorationStyle` keys; enum switch churns literals for no gain. - - `fixture-root.ts` — keeps its dual-layout probe + `$CURSORLESS_REPO` - override; lib-node-common's `getFixturesPath` hardcodes one layout. - - `fixture-extract.ts` `parseMarks`/`buildLines` — lib-common's - `serializedMarksToTokenHats` needs a live `TextEditor` and returns engine - `TokenHat[]`; our render model reads plain YAML with no editor. -5. **Compile config fixed**. Dropped the non-idiomatic - `tsc --build`/composite setup (no sibling package uses it); `compile:tsc` is - now plain `tsc`, matching the repo's typecheck convention (resolution via - `tsconfig.base.json` `paths`). Fixed a real pre-existing type error: - `pipeline.ts` used `GeneralizedRange` and `Pos` without importing them. - -## Dedup against cursorless source (import-not-clone pass) - -This pass replaced vendored/cloned code with imports from cursorless packages. -lib-engine gained additive exports (own commit) to make it possible. - -- **DefaultMap / CompositeKeyMap** → imported from `@cursorless/lib-common` - (deleted the two `vendor/allocate-hats/common/` copies). -- **GRAPHEME_SPLIT_REGEX** → imported from `@cursorless/lib-engine` in - `columns.ts`, `tokenize.ts`, and `vendor/allocate-hats/splitter.ts` (was - cloned in all three). -- **maxByFirstDiffering** → imported from `@cursorless/lib-engine` (deleted the - vendored copy). -- **FlashStyle** → derived from `@cursorless/lib-common`'s enum via - `` `${CursorlessFlashStyle}` `` (was a hand-maintained string union). -- **lib-engine exports added** (separate lib-engine commit): the allocateHats - primitives + tokenGraphemeSplitter barrel now surface from the lib-engine - index, so the above imports resolve. - -**Still vendored, PINNED at SHA 42452eb on purpose** (current upstream has -diverged — importing would change hat placement or fail to typecheck against the -standalone's simplified types): `chooseTokenHat`, `HatMetrics`, -`getHatRankingContext`, `getTokenComparator`, `common/types.ts`, the tokens-in -`allocateHats` wrapper (`index.ts`), `rank.ts`, `StandaloneGraphemeSplitter` -(`splitter.ts`). Each file header states the exact reason; `VENDOR.md` has the -full split. Upstream added `forcedTokenHat` (#2602) and `avoidFirstLetter` / -`HatCandidate.isFirstLetter` (#1723), and the engine splitter needs a live IDE. - -**Still local (fixture path/marks):** `parseMarks`/`buildLines` (needs no -TextEditor, unlike lib-common's `serializedMarksToTokenHats`), `fixture-root.ts` -(dual-layout probe + `$CURSORLESS_REPO` default, unlike lib-node-common's -single-layout `getFixturesPath`). `fixture-yaml.ts` already uses `js-yaml`. - -## Colors / shapes data — step 6 decision: Option B (keep, with provenance) - -The hat COLOR hexes, shape SVG `d=` path strings, color names, shape names, and -shape adjustments have **no importable TS module**, so they are KEPT in -`data/colors.ts` / `data/shapes.ts` with precise provenance comments naming the -exact upstream export that would be needed. Option A (add a canonical exported -constants module) was rejected because it cannot be done without either: - -- creating a THIRD copy — the color hexes live in `app-vscode/package.json` as - VS Code setting defaults (read at runtime, never a TS constant) and the SVG - `d=` strings live in `resources/images/hats/*.svg` (read at runtime by - `VscodeHatRenderer.ts`), so any new TS constant is a second/third copy; or -- a risky app-vscode refactor — `HAT_COLORS`/`HAT_SHAPES`/`HatShape` and - `defaultShapeAdjustments` DO exist as clean TS constants in - `app-vscode/src/ide/vscode/hatStyles.types.ts` and `.../hats/shapeAdjustments.ts`, - but app-vscode exports only `./extension.cjs`, so single-sourcing them means - promoting both into `@cursorless/lib-common` AND rewiring the 5 app-vscode - files that consume them (VscodeHatRenderer, performPr1868ShapeUpdateInit, the - two hatAdjustments scripts) — the shipping extension's hat path, out of scope. - -**Follow-up (deferred):** promote `hatStyles.types.ts` + `shapeAdjustments.ts` -into lib-common and rewire those 5 app-vscode files; the `.svg` `d=` strings -would still need a separate build-time loader (or a generated TS constant) to -avoid a second copy. - -## Security - -- **CodeQL XSS (serialize-cascade.ts)** fixed: the attribute escaper now also - escapes `"` (and `'`), so fixture/spoken-form strings can no longer break out - of the double-quoted `data-fixture` / `data-spoken-form` attributes. - -## Remaining blockers (NOT introduced by this work) - -Running `pnpm compile` in the current checkout surfaces errors that are all -environmental (stale install) or pre-existing and out of scope for the dedup: - -- **Stale node_modules / offline.** The installed toolchain is TypeScript 5.4.3 - and js-yaml 4.3.0, but `package.json`/lockfile pin TypeScript `^6.0.3` and - js-yaml `^5.2.1`. TS 5.4.3 rejects the shared `tsconfig.base.json` `target: - es2023` (`TS6046`), which cascades into a spurious `Set` iteration error in - the vendored `rank.ts`. `@types/js-yaml` is also not installed, so - `fixture-yaml.ts` reports `TS7016` (missing declaration for `js-yaml`). A - `pnpm install` (needs network — offline install fails fetching - `oxlint-tsgolint`, TS 6.0.3, js-yaml 5.2.1, `@types/js-yaml`) resolves all of - these. Proof: typechecking this package with a valid target (es2022) + node - types + a `declare module "js-yaml"` shim leaves ZERO errors in our code. -- **`./fixtures-vendored` missing** (`api-core.ts:47`, `TS2307`). `api-core.ts` - imports `FIXTURE_IDS` / `SEQUENCES` / `VENDORED_FIXTURES` from a - `src/fixtures-vendored` module that was never committed to this repo (it was a - serverless-deployment artifact of the standalone repo — the "fixture - ingestion" item from the original scaffold). This file is UNREACHABLE from the - esbuild bundle entry (`src/index.ts` does not export `api-core.ts`), so it - does not block `compile:esbuild`; it only trips the whole-tree `tsc` - typecheck. Generating it is a separate task outside the dedup/compile scope - and was intentionally NOT invented here. - -## Verify - -- Vendored tree, isolated: clean typecheck (esnext, self-contained). -- Whole package, valid target + js-yaml types available: only the - out-of-scope `./fixtures-vendored` error remains. diff --git a/packages/command-visualizer/src/index.ts b/packages/command-visualizer/src/index.ts index 77725bc4d4..6e7fdc2cc7 100644 --- a/packages/command-visualizer/src/index.ts +++ b/packages/command-visualizer/src/index.ts @@ -1,6 +1,6 @@ // @cursorless/command-visualizer — public surface. // -// fixture YAML in -> animated SVG out. See STATUS.md for integration state. +// fixture YAML in -> animated SVG out. See ../README.md for an overview. export { fixtureToCascade, From e7fa2b00bb67e2b35f8f21ce4804b5d876b3f2cf Mon Sep 17 00:00:00 2001 From: Trillium Smith <trillium@trilliumsmith.com> Date: Wed, 8 Jul 2026 10:09:05 -0700 Subject: [PATCH 42/53] docs(command-visualizer): track upstream reuse opportunities MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Working/contributor doc: what the package can reuse from cursorless — geometry types (Position/Range/GeneralizedRange) adoptable today with no upstream change, plus four blocked-by-coupling items (pure flash-derivation, editor-free serializedMarksToTokenHats, grapheme tokenizer, parameterized fixture-path) that need a small upstream refactor+export first. Groups the same doc-strip bucket as the pre-upstream barebones pass. --- packages/command-visualizer/UPSTREAM_REUSE.md | 101 ++++++++++++++++++ 1 file changed, 101 insertions(+) create mode 100644 packages/command-visualizer/UPSTREAM_REUSE.md diff --git a/packages/command-visualizer/UPSTREAM_REUSE.md b/packages/command-visualizer/UPSTREAM_REUSE.md new file mode 100644 index 0000000000..6e07a18cd6 --- /dev/null +++ b/packages/command-visualizer/UPSTREAM_REUSE.md @@ -0,0 +1,101 @@ +# Upstream reuse opportunities + +> Working/contributor doc (not shipped API). Tracks where `command-visualizer` +> could lean harder on existing cursorless code — split into what's **adoptable +> today** and what would need a **small upstream refactor + export** first. +> Goal: as a first-party package, reimplement as little as possible. + +## Status: already reused (no action) + +The package already imports from source rather than cloning: + +- Hat allocation → real `@cursorless/lib-engine` `allocateHats` (via an in-memory + `FakeIDE`/`InMemoryTextEditor`); the vendored copy is deleted. +- `HatColor`/`HAT_COLORS`, `HatShape`/`HAT_SHAPES`/`HAT_NON_DEFAULT_SHAPES`, + `FlashStyle`, `DefaultMap`, `CompositeKeyMap`, `defaultShapeAdjustments`, + `DEFAULT_HAT_HEIGHT_EM`/`DEFAULT_VERTICAL_OFFSET_EM` ← `@cursorless/lib-common`. +- `GRAPHEME_SPLIT_REGEX`, `maxByFirstDiffering`, `TokenGraphemeSplitter`, + `getTokensInRange` ← `@cursorless/lib-engine`. +- `js-yaml` for fixture YAML. + +Local-with-provenance (no importable TS source; canonical form is config/SVG): +`COLOR_MATRIX`, `DECORATION_HEX` (app-vscode `package.json` config defaults), +`SHAPE_PATHS` (`resources/images/hats/*.svg`, guarded by a drift test). + +## Adoptable today — no upstream change needed + +### Geometry: `Position` / `Range` / `GeneralizedRange` +- **What:** `@cursorless/lib-common` exports `Position` and `Range` classes (with + `isEqual`/`isBefore`/`contains`/`with`/`fromConcise`), plus `GeneralizedRange`, + `CharacterRange`, `LineRange`, and the helpers `isLineRange`, `toLineRange`, + `toCharacterRange`, `generalizedRangeContains`/`generalizedRangeTouches`. +- **We currently hand-roll:** `model/geometry.ts` (`Pos`/`Range` plain interfaces + + `orderRange`), the ordering/`before` comparison in `deriveSelections`, and + containment math in `overlays.ts`. `model/frame-state.ts` defines its own + `CharacterRange`/`LineRange`/`GeneralizedRange`. +- **Semantics already match:** cursorless `LineRange.end` is "Last line, inclusive" + — identical to our `endLine`. The only deltas are our-side: plain interfaces → + classes (construct `new Position()`/`new Range()` at the YAML boundary), and our + `LineRange {startLine,endLine}` → cursorless's `{start,end}` (field rename, same + meaning); `CharacterRange` uses `Position` instances. +- **Blocker:** none upstream. ~8-file our-side refactor. +- **Value:** deletes real hand-rolled ordering/containment logic; inherits tested + behavior. **This is the queued geometry-adoption task.** + +## Needs an upstream refactor + export first + +Each of these is blocked by *coupling* (live `TextEditor` / disk I/O / no pure +unit), not merely a missing export — so it needs a small cursorless-side change +before we can consume it. Listed by value. + +| # | If cursorless… | We'd delete | Value | Feasibility | +|---|----------------|-------------|-------|-------------| +| 1 | extracted a **pure flash-derivation** — `diff(beforeDoc, afterDoc) → {pendingDelete, justAdded} ranges` — from the action runtime | `logic/derive-flashes.ts` | **High** (real duplicated logic) | **Hard** — no pure unit exists today | +| 2 | offered an **editor-free `serializedMarksToTokenHats`** taking plain `{offset,text}` instead of a live `TextEditor` | `parseMarks` + mark attachment in `logic/fixture-extract.ts` | Medium | Medium | +| 3 | exported a **grapheme-level tokenizer** (or made `getTokensInRange` output headless-consumable as a render model) | most of `logic/tokenize.ts`, part of `model/columns.ts` | Medium | Medium (word-vs-grapheme gap) | +| 4 | **parameterized fixture-path** resolution — `getFixturesPath(root)` instead of env-var-throw + one hardcoded layout | `logic/fixture-root.ts` | Low | Easy | + +### 1. Pure flash-derivation (highest value) +Today, cursorless flashes are a **runtime side-effect**: actions execute against a +live IDE and call `ide().flashRanges(...)` (see `lib-engine/src/actions/*`, +`core/updateSelections/`, `RangeUpdater`). There is no pure +"two document snapshots → flash ranges" function anywhere. Recorded fixtures +carry **zero** `ide.flashes`, so `derive-flashes.ts` reconstructs them from a +char-level prefix/suffix diff. If cursorless factored the edit→flash mapping into +a pure helper, we'd import it and delete our diff — and it would benefit +cursorless's own test/tooling surface, not just us. **Best upstream proposal +candidate.** + +### 2. Editor-free marks → hats +`lib-common/src/util/serializedMarksToTokenHats.ts` hard-requires a live +`TextEditor` (`editor.document.offsetAt(range)`, `.getText(range)`) and returns +engine `TokenHat[]`. Our `parseMarks` reads plain fixture YAML (`{color}.{grapheme}`) +with no editor and yields the render-model `MarkInfo`. A pure core that takes +offsets/text (splitting the editor I/O from the mapping) would let us drop ours. + +### 3. Grapheme tokenizer / headless token model +The engine tokenizer produces **word/token** units, not one-token-per-grapheme, +and isn't barrel-exported; `getTokensInRange` needs a live editor. `columns.ts` +also needs East-Asian display width — for which **no util exists anywhere** in the +monorepo. A grapheme-level tokenizer export (or a headless render-token producer) +would shrink `tokenize.ts`/`columns.ts`; the display-width piece would still be +ours unless cursorless grew one (it never needed display geometry). + +### 4. Parameterized fixture path +`lib-node-common` `getCursorlessRepoRoot()` throws unless `CURSORLESS_REPO_ROOT` +is set, and `getFixturesPath` hardcodes the single `resources/fixtures` layout. +Ours does a dual-layout probe with a sensible default. A root-param overload would +let us drop `fixture-root.ts`. + +## Not reusable (genuinely new — no upstream candidate) +- `model/timeline.ts` (animation timing), `logic/chain.ts` (multi-step chaining), + `render/*` (HTML/CSS/SVG hat renderer — nothing like it exists upstream; + `app-web-docs/Code.tsx` is Shiki syntax highlighting, unrelated). +- `model/overlays.ts` cross-decoration last-wins-per-cell precedence — lib-common's + `decorationUtil` computes single-range **border geometry**, a different concern. + +## How to pursue +The geometry adoption is our-side and unblocked — do it directly. Items 1–4 are +upstream-contribution opportunities: raise as cursorless issues/PRs (extract the +pure core, add the export), then consume. Item 1 (pure flash-derivation) is the +highest-leverage and the most defensible as a general cursorless improvement. From f45849b0bd413a7c1b2097a66188025af5d8430e Mon Sep 17 00:00:00 2001 From: Trillium Smith <trillium@trilliumsmith.com> Date: Wed, 8 Jul 2026 10:17:58 -0700 Subject: [PATCH 43/53] refactor(command-visualizer): adopt lib-common Position/Range in hat-allocator and serialize --- packages/command-visualizer/src/logic/hat-allocator.ts | 4 ++-- packages/command-visualizer/src/render/serialize.ts | 8 ++++---- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/packages/command-visualizer/src/logic/hat-allocator.ts b/packages/command-visualizer/src/logic/hat-allocator.ts index 737ffde7a1..17a79b46a7 100644 --- a/packages/command-visualizer/src/logic/hat-allocator.ts +++ b/packages/command-visualizer/src/logic/hat-allocator.ts @@ -39,6 +39,7 @@ import { HatStability, type HatStyleMap, InMemoryTextEditor, + Position, Range, Selection, type TokenHat, @@ -51,7 +52,6 @@ import { import type { HatColor, HatShape } from "@cursorless/lib-common"; import { HAT_COLORS, HAT_SHAPES } from "@cursorless/lib-common"; import type { Line, Token as RenderToken } from "../model/columns"; -import type { Pos } from "../model/geometry"; // --------------------------------------------------------------------------- // Style map: our full palette x (default + 10 shapes), penalty-ordered the way @@ -117,7 +117,7 @@ interface Mark { export function allocateHats( lines: Line[], - cursor: Pos = { line: 0, character: 0 }, + cursor: Position = new Position(0, 0), ): void { // (1) Reconstruct the document text the render model represents. const content = lines diff --git a/packages/command-visualizer/src/render/serialize.ts b/packages/command-visualizer/src/render/serialize.ts index 88be738306..368d009017 100644 --- a/packages/command-visualizer/src/render/serialize.ts +++ b/packages/command-visualizer/src/render/serialize.ts @@ -2,8 +2,7 @@ import type { Theme } from "../data/colors"; import { type Column, type Line, expandColumns, lineWidth } from "../model/columns"; -import type { Pos, Range } from "../model/geometry"; -import { orderRange } from "../model/geometry"; +import type { Position, Range } from "@cursorless/lib-common"; import { styleSheet } from "./css"; import { symbolSheet } from "./symbols"; import { esc } from "./html"; @@ -12,7 +11,7 @@ export interface EditorState { theme: Theme; tabSize: number; lines: Line[]; - cursors?: Pos[]; + cursors?: Position[]; selections?: Range[]; } @@ -23,7 +22,8 @@ function inAnySelection( selections: Range[], ): boolean { for (const sel of selections) { - const { start, end } = orderRange(sel); + // lib-common Range is always non-reversed (start ≤ end), so no reorder. + const { start, end } = sel; if (lineIdx < start.line || lineIdx > end.line) { continue; } From 281e2d02587697b0612a76ddbf541b92c64019b7 Mon Sep 17 00:00:00 2001 From: Trillium Smith <trillium@trilliumsmith.com> Date: Wed, 8 Jul 2026 10:18:18 -0700 Subject: [PATCH 44/53] refactor(command-visualizer): adopt lib-common GeneralizedRange family and delete local geometry --- .../command-visualizer/src/ARCHITECTURE.md | 2 +- .../src/logic/build-render-object.ts | 7 ++-- .../src/logic/derive-flashes.ts | 8 ++--- .../src/logic/fixture-extract.ts | 36 +++++++++---------- .../src/model/frame-state.ts | 20 +++-------- .../command-visualizer/src/model/geometry.ts | 23 ------------ .../command-visualizer/src/model/overlays.ts | 16 ++++----- 7 files changed, 37 insertions(+), 75 deletions(-) delete mode 100644 packages/command-visualizer/src/model/geometry.ts diff --git a/packages/command-visualizer/src/ARCHITECTURE.md b/packages/command-visualizer/src/ARCHITECTURE.md index e6e5e0f16c..abdb75654c 100644 --- a/packages/command-visualizer/src/ARCHITECTURE.md +++ b/packages/command-visualizer/src/ARCHITECTURE.md @@ -12,7 +12,7 @@ render/ "what is visually seen": CascadeState -> HTML/CSS/SVG ``` - `data/` — colors.ts, decorations.ts, shapes.ts -- `model/` — geometry.ts (Pos/Range + orderRange), frame-state.ts (CascadeState/Frame/Decoration/GeneralizedRange), columns.ts (Line/Token/Column geometry), overlays.ts (decoration → column overlay resolution), timeline.ts (frame timing) +- `model/` — frame-state.ts (CascadeState/Frame/Decoration; geometry `Position`/`Range`/`GeneralizedRange` come from `@cursorless/lib-common`), columns.ts (Line/Token/Column geometry), overlays.ts (decoration → column overlay resolution), timeline.ts (frame timing) - `logic/` — pipeline.ts, pipeline-types.ts, build-render-object.ts, fixture-extract.ts, fixture-yaml.ts, fixture-root.ts, tokenize.ts, hat-allocator.ts, chain.ts - `render/` — serialize.ts, serialize-cascade.ts, svg-wrap.ts, jumbotron.ts, css.ts, css-cascade.ts, symbols.ts, html.ts - `render-command.ts` — the top-level 4-stage orchestrator (root, spans logic + render). diff --git a/packages/command-visualizer/src/logic/build-render-object.ts b/packages/command-visualizer/src/logic/build-render-object.ts index 9f9dc452cc..74022884d1 100644 --- a/packages/command-visualizer/src/logic/build-render-object.ts +++ b/packages/command-visualizer/src/logic/build-render-object.ts @@ -4,11 +4,8 @@ // Behavior identical to the inline stage that lived in fixtureToCascade. // logic/ → logic/ import only. -import type { - CascadeState, - Frame, - GeneralizedRange, -} from "../model/frame-state"; +import type { CascadeState, Frame } from "../model/frame-state"; +import type { GeneralizedRange } from "@cursorless/lib-common"; import type { OverlayStyleName } from "../data/decorations"; import { asArr, asObj, toGeneralizedRange } from "./fixture-extract"; import { deriveFlashes } from "./derive-flashes"; diff --git a/packages/command-visualizer/src/logic/derive-flashes.ts b/packages/command-visualizer/src/logic/derive-flashes.ts index 6906e430e3..a1b7e3dff1 100644 --- a/packages/command-visualizer/src/logic/derive-flashes.ts +++ b/packages/command-visualizer/src/logic/derive-flashes.ts @@ -4,8 +4,8 @@ // mutation of caller state. logic/ → logic/ import only. import type { OverlayStyleName } from "../data/decorations"; -import type { Decoration, GeneralizedRange } from "../model/frame-state"; -import type { Pos } from "../model/geometry"; +import type { Decoration } from "../model/frame-state"; +import { Position, type GeneralizedRange } from "@cursorless/lib-common"; export interface DerivedFlashes { /** pendingDelete flashes to append to the DURING flash list (pre-edit). */ @@ -43,11 +43,11 @@ export function deriveFlashes(args: { finDoc !== initDoc && hasAfterFrame ) { - const toPos = (doc: string, off: number): Pos => { + const toPos = (doc: string, off: number): Position => { const upto = doc.slice(0, off); const line = (upto.match(/\n/g) ?? []).length; const character = off - (upto.lastIndexOf("\n") + 1); - return { line, character }; + return new Position(line, character); }; let p = 0; while ( diff --git a/packages/command-visualizer/src/logic/fixture-extract.ts b/packages/command-visualizer/src/logic/fixture-extract.ts index 140bfadbbc..4337a4a87c 100644 --- a/packages/command-visualizer/src/logic/fixture-extract.ts +++ b/packages/command-visualizer/src/logic/fixture-extract.ts @@ -7,8 +7,11 @@ import { tokenizeDoc } from "./tokenize"; import type { HatColor, HatShape } from "@cursorless/lib-common"; import { HAT_COLORS } from "@cursorless/lib-common"; import type { Line, Token, InputHat } from "../model/columns"; -import type { GeneralizedRange } from "../model/frame-state"; -import type { Pos, Range } from "../model/geometry"; +import { + Position, + Range, + type GeneralizedRange, +} from "@cursorless/lib-common"; import { allocateHats } from "./hat-allocator"; export type Obj = Record<string, YamlValue>; @@ -22,9 +25,9 @@ export function asArr(v: YamlValue | undefined): YamlValue[] { export function num(v: YamlValue | undefined): number { return typeof v === "number" ? v : Number(v); } -export function pos(v: YamlValue | undefined): Pos { +export function pos(v: YamlValue | undefined): Position { const o = asObj(v) ?? {}; - return { line: num(o.line), character: num(o.character) }; + return new Position(num(o.line), num(o.character)); } // Dedup note (re-verified against current signatures): @cursorless/lib-common @@ -43,8 +46,8 @@ export interface MarkInfo { key: string; grapheme: string; color: HatColor; - start: Pos; - end: Pos; + start: Position; + end: Position; } export function parseMarks(marksObj: Obj | null): MarkInfo[] { @@ -169,10 +172,10 @@ export function buildLines( // Selections → {cursors, selections}. anchor==active ⇒ caret; reversed normalize. export function deriveSelections(selArr: YamlValue[]): { - cursors: Pos[]; + cursors: Position[]; selections: Range[]; } { - const cursors: Pos[] = []; + const cursors: Position[] = []; const selections: Range[] = []; for (const s of selArr) { const o = asObj(s); @@ -181,17 +184,12 @@ export function deriveSelections(selArr: YamlValue[]): { } const anchor = pos(o.anchor); const active = pos(o.active); - if (anchor.line === active.line && anchor.character === active.character) { + if (anchor.isEqual(active)) { cursors.push(anchor); } else { - const before = - anchor.line < active.line || - (anchor.line === active.line && anchor.character <= active.character); - selections.push( - before - ? { start: anchor, end: active } - : { start: active, end: anchor }, - ); + // Range's constructor normalizes to non-reversed (start ≤ end), matching + // the previous manual anchor/active ordering. + selections.push(new Range(anchor, active)); } } return { cursors, selections }; @@ -202,8 +200,8 @@ export function toGeneralizedRange(rangeObj: Obj): GeneralizedRange | null { if (rangeObj.type === "line") { return { type: "line", - startLine: num(rangeObj.start), - endLine: num(rangeObj.end), // INCLUSIVE per GeneralizedRange.ts + start: num(rangeObj.start), + end: num(rangeObj.end), // last line, INCLUSIVE per lib-common LineRange }; } return { diff --git a/packages/command-visualizer/src/model/frame-state.ts b/packages/command-visualizer/src/model/frame-state.ts index 7a268ad7d1..8b4ae795cc 100644 --- a/packages/command-visualizer/src/model/frame-state.ts +++ b/packages/command-visualizer/src/model/frame-state.ts @@ -4,7 +4,7 @@ import type { Theme } from "../data/colors"; import type { Line } from "./columns"; -import type { Pos, Range } from "./geometry"; +import type { Position, Range, GeneralizedRange } from "@cursorless/lib-common"; import type { OverlayStyleName } from "../data/decorations"; export type FrameRole = "before" | "during" | "after"; @@ -16,19 +16,9 @@ export type OverlayRole = | "source" | `scope:${string}`; -// GeneralizedRange — character (half-open columns) or line -// (full-width, endLine INCLUSIVE). -export type CharacterRange = { - type: "character"; - start: Pos; - end: Pos; -}; -export type LineRange = { - type: "line"; - startLine: number; - endLine: number; // INCLUSIVE -}; -export type GeneralizedRange = CharacterRange | LineRange; +// GeneralizedRange (character | line) comes from @cursorless/lib-common. +// A line range's `end` field is the last line, INCLUSIVE — same semantics the +// local type carried before this adopted lib-common's shape. export interface Decoration { style: OverlayStyleName; @@ -39,7 +29,7 @@ export interface Decoration { export interface Frame { role: FrameRole; lines: Line[]; - cursors: Pos[]; + cursors: Position[]; selections: Range[]; decorations: Decoration[]; /** Spoken form of the command this frame is the BEFORE of (command strip). */ diff --git a/packages/command-visualizer/src/model/geometry.ts b/packages/command-visualizer/src/model/geometry.ts deleted file mode 100644 index 65c86f0d48..0000000000 --- a/packages/command-visualizer/src/model/geometry.ts +++ /dev/null @@ -1,23 +0,0 @@ -// Geometry primitives — shared position/range model. Pure, no HTML, no logic. -// Extracted from serialize.ts so both `logic/` and `render/` can depend on these -// without either scope importing the other (see ARCHITECTURE.md). - -export interface Pos { - line: number; - character: number; // UTF-16 char index within the line -} - -export interface Range { - start: Pos; - end: Pos; -} - -/** Normalize a range so `start` precedes `end` in document order. */ -export function orderRange(r: Range): Range { - const a = r.start; - const b = r.end; - if (a.line < b.line || (a.line === b.line && a.character <= b.character)) { - return r; - } - return { start: b, end: a }; -} diff --git a/packages/command-visualizer/src/model/overlays.ts b/packages/command-visualizer/src/model/overlays.ts index 6793c441d0..06837755ce 100644 --- a/packages/command-visualizer/src/model/overlays.ts +++ b/packages/command-visualizer/src/model/overlays.ts @@ -7,7 +7,7 @@ import { type Column, expandColumns } from "./columns"; import type { Decoration, Frame, OverlayRole } from "./frame-state"; import type { OverlayStyleName } from "../data/decorations"; import { overlayPrecedence } from "../data/decorations"; -import type { Range } from "./geometry"; +import { type Range, isLineRange } from "@cursorless/lib-common"; // Role sub-rank, used to break style-precedence ties: a REAL ide.flash outranks // a DERIVED that/source overlay on the @@ -44,16 +44,16 @@ export interface LineOverlay { function colsForCharRange( cols: Column[], lineIdx: number, - startLine: number, + firstLine: number, startCh: number, - endLine: number, + lastLine: number, endCh: number, ): number[] { - if (lineIdx < startLine || lineIdx > endLine) { + if (lineIdx < firstLine || lineIdx > lastLine) { return []; } - const loCh = lineIdx === startLine ? startCh : 0; - const hiCh = lineIdx === endLine ? endCh : Infinity; + const loCh = lineIdx === firstLine ? startCh : 0; + const hiCh = lineIdx === lastLine ? endCh : Infinity; const out: number[] = []; for (const c of cols) { // a cell starts at charIndex; treat it as covering [charIndex, nextCharIndex) @@ -114,8 +114,8 @@ function resolveLine( // character-range decorations (highlight prec 1, flash prec 2) let lineFlash: OverlayStyleName | null = null; for (const dec of decorations) { - if (dec.range.type === "line") { - if (lineIdx >= dec.range.startLine && lineIdx <= dec.range.endLine) { + if (isLineRange(dec.range)) { + if (lineIdx >= dec.range.start && lineIdx <= dec.range.end) { lineFlash = dec.style; // last line decoration wins } continue; From 975e058fb93858d71a51d720539b843ecc0c0ca3 Mon Sep 17 00:00:00 2001 From: Trillium Smith <trillium@trilliumsmith.com> Date: Wed, 8 Jul 2026 10:25:11 -0700 Subject: [PATCH 45/53] feat(command-visualizer): thread lineNumbers option through render entry points MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit renderCommand now accepts lineNumbers (via CascadeRenderOptions) and passes it into serializeCascade; serializeEditor/serializeDocument gain the same opt-in gutter markup as the cascade path. Off by default — output byte-identical when unset or false. --- .../command-visualizer/src/render-command.ts | 14 ++++-- .../src/render/serialize.ts | 47 ++++++++++++++++--- 2 files changed, 51 insertions(+), 10 deletions(-) diff --git a/packages/command-visualizer/src/render-command.ts b/packages/command-visualizer/src/render-command.ts index da0c23e521..fe77e5e8e4 100644 --- a/packages/command-visualizer/src/render-command.ts +++ b/packages/command-visualizer/src/render-command.ts @@ -17,11 +17,17 @@ import { buildRenderObject, type PipelineOptions, } from "./logic/pipeline"; -import { serializeCascade } from "./render/serialize-cascade"; +import { + serializeCascade, + type CascadeRenderOptions, +} from "./render/serialize-cascade"; import { wrapCascadeSvg, type SvgWrapOptions } from "./render/svg-wrap"; -/** Options for the end-to-end orchestrator: pipeline knobs + SVG-wrap knobs. */ -export interface RenderCommandOptions extends PipelineOptions, SvgWrapOptions {} +/** Options for the end-to-end orchestrator: pipeline + render + SVG-wrap knobs. */ +export interface RenderCommandOptions + extends PipelineOptions, + SvgWrapOptions, + CascadeRenderOptions {} /** * Render a single recorded fixture to a standalone animated SVG string. @@ -42,7 +48,7 @@ export function renderCommand( const parsed = parseFixture(src, fixtureRel, opts); // 1. get what to render const tokenized = tokenizeStates(parsed, opts); // 2. tokenize each step const cascade = buildRenderObject(parsed, tokenized, opts); // 3. render object - const inner = serializeCascade(cascade); + const inner = serializeCascade(cascade, { lineNumbers: opts.lineNumbers }); return wrapCascadeSvg(cascade, inner, undefined, { flashPulseMs: opts.flashPulseMs, }); // 4. render from object diff --git a/packages/command-visualizer/src/render/serialize.ts b/packages/command-visualizer/src/render/serialize.ts index 368d009017..08dc43d94d 100644 --- a/packages/command-visualizer/src/render/serialize.ts +++ b/packages/command-visualizer/src/render/serialize.ts @@ -76,7 +76,12 @@ function emitSpan(c: Column, lineIdx: number, selections: Range[]): string { ); } -function emitLine(line: Line, lineIdx: number, state: EditorState): string { +function emitLine( + line: Line, + lineIdx: number, + state: EditorState, + lineNumbers: boolean, +): string { const cols = expandColumns(line, state.tabSize); const selections = state.selections ?? []; const cursors = (state.cursors ?? []).filter((c) => c.line === lineIdx); @@ -89,6 +94,12 @@ function emitLine(line: Line, lineIdx: number, state: EditorState): string { caretAtCol.set(col, (caretAtCol.get(col) ?? "") + caret); } + // Optional leading line-number cell (1-based, like a real editor). Only + // emitted when the gutter is on — keeps the no-gutter output byte-identical. + const gutter = lineNumbers + ? `<span class="cl-lineno" aria-hidden="true">${lineIdx + 1}</span>` + : ""; + let html = ""; for (const c of cols) { if (caretAtCol.has(c.col)) { @@ -102,16 +113,39 @@ function emitLine(line: Line, lineIdx: number, state: EditorState): string { html += caretAtCol.get(endCol); } - return ` <div class="cl-line" data-line="${lineIdx}">${html}</div>`; + return ` <div class="cl-line" data-line="${lineIdx}">${gutter}${html}</div>`; +} + +/** Render options for the single-editor serializer. */ +export interface EditorRenderOptions { + /** Emit the left line-number gutter. OFF by default. */ + lineNumbers?: boolean; +} + +/** Widest line number → digit count for the gutter width. */ +function gutterDigits(state: EditorState): number { + return String(Math.max(1, state.lines.length)).length; } /** Serialize state to the inner editor markup (defs + lines). */ -export function serializeEditor(state: EditorState): string { +export function serializeEditor( + state: EditorState, + opts: EditorRenderOptions = {}, +): string { + const lineNumbers = opts.lineNumbers ?? false; const lines = state.lines - .map((line, i) => emitLine(line, i, state)) + .map((line, i) => emitLine(line, i, state, lineNumbers)) .join("\n"); + // Only when ON do we add the gutter attribute + digit-width var. OFF → + // neither appears, so the markup is byte-identical to before. + const gutterAttr = lineNumbers ? ` data-line-numbers=""` : ""; + // Leading "; " keeps the OFF path's style attribute byte-identical (no + // trailing separator appears unless the gutter var is actually emitted). + const gutterVar = lineNumbers + ? `; --gutter-digits:${gutterDigits(state)}` + : ""; return ( - `<div class="cl-editor" data-theme="${state.theme}" style="--tab-size:${state.tabSize}">\n` + + `<div class="cl-editor" data-theme="${state.theme}"${gutterAttr} style="--tab-size:${state.tabSize}${gutterVar}">\n` + `${symbolSheet()}\n` + ` <div class="cl-code">\n${lines}\n </div>\n` + `</div>` @@ -122,6 +156,7 @@ export function serializeEditor(state: EditorState): string { export function serializeDocument( state: EditorState, title = "cursorless state", + opts: EditorRenderOptions = {}, ): string { return `<!doctype html> <html> @@ -135,7 +170,7 @@ ${styleSheet()} </style> </head> <body> -${serializeEditor(state)} +${serializeEditor(state, opts)} </body> </html>`; } From 4e9d004710574cdd90015fb2b3e5ba9d0e41806f Mon Sep 17 00:00:00 2001 From: Trillium Smith <trillium@trilliumsmith.com> Date: Wed, 8 Jul 2026 10:29:15 -0700 Subject: [PATCH 46/53] test(command-visualizer): cover opt-in line-number gutter Asserts data-line-numbers on the cascade root, one 1-based .cl-lineno per line, digit-width scaling, per-frame emission, and that the default (and lineNumbers:false) stay byte-identical with no gutter markup. --- .../src/render/serialize-cascade.test.ts | 94 +++++++++++++++++++ 1 file changed, 94 insertions(+) create mode 100644 packages/command-visualizer/src/render/serialize-cascade.test.ts diff --git a/packages/command-visualizer/src/render/serialize-cascade.test.ts b/packages/command-visualizer/src/render/serialize-cascade.test.ts new file mode 100644 index 0000000000..40500111e9 --- /dev/null +++ b/packages/command-visualizer/src/render/serialize-cascade.test.ts @@ -0,0 +1,94 @@ +import assert from "node:assert/strict"; +import type { Line } from "../model/columns"; +import type { CascadeState, Frame } from "../model/frame-state"; +import { serializeCascade } from "./serialize-cascade"; + +/** A plain text line as a single hatless token (no logic/ dependency). */ +function line(text: string): Line { + return { tokens: [{ text, range: { start: 0, end: text.length } }] }; +} + +function frame(texts: string[]): Frame { + return { + role: "before", + lines: texts.map(line), + cursors: [], + selections: [], + decorations: [], + }; +} + +function stateOf(...lineSets: string[][]): CascadeState { + return { theme: "dark", tabSize: 4, frames: lineSets.map(frame) }; +} + +/** All line-number cell contents, in document order. */ +function lineNoTexts(html: string): string[] { + return [...html.matchAll(/<span class="cl-lineno"[^>]*>([^<]*)<\/span>/g)].map( + (m) => m[1], + ); +} + +suite("command-visualizer/serialize-cascade line numbers", () => { + const state = stateOf(["apple", "banana", "cherry"]); + + test("on: gutter attribute on root + one 1-based .cl-lineno per line", () => { + const html = serializeCascade(state, { lineNumbers: true }); + + // (a) data-line-numbers activates the gutter on the cascade root. + assert.ok( + html.includes('data-line-numbers=""'), + "root must carry data-line-numbers when on", + ); + // Digit-count var reflects the largest line number (3 lines → 1 digit). + assert.match(html, /--gutter-digits:1;/); + + // (b) exactly one .cl-lineno per line, numbered 1..N (1-based). + assert.deepEqual(lineNoTexts(html), ["1", "2", "3"]); + // One .cl-line per rendered line, so counts line up. + assert.equal((html.match(/class="cl-line"/g) ?? []).length, 3); + }); + + test("off: no gutter attribute and no .cl-lineno", () => { + const html = serializeCascade(state, { lineNumbers: false }); + assert.ok(!html.includes("data-line-numbers"), "no gutter attribute"); + assert.equal(lineNoTexts(html).length, 0, "no line-number cells"); + }); + + test("default: identical to lineNumbers:false (opt-in, off by default)", () => { + const defaulted = serializeCascade(state); + const explicitOff = serializeCascade(state, { lineNumbers: false }); + assert.equal(defaulted, explicitOff); + assert.ok(!defaulted.includes("cl-lineno")); + assert.ok(!defaulted.includes("data-line-numbers")); + }); + + test("digit width scales to the widest line number", () => { + // A ten-line document → largest line number "10" → 2 digits. + const tenState = stateOf( + Array.from({ length: 10 }, (_, i) => `line${i}`), + ); + const html = serializeCascade(tenState, { lineNumbers: true }); + assert.match(html, /--gutter-digits:2;/); + assert.deepEqual(lineNoTexts(html), [ + "1", + "2", + "3", + "4", + "5", + "6", + "7", + "8", + "9", + "10", + ]); + }); + + test("gutter appears on every frame of a multi-frame cascade", () => { + const multi = stateOf(["one", "two"], ["uno", "dos"]); + const html = serializeCascade(multi, { lineNumbers: true }); + // Two frames × two lines = four line-number cells, numbered per frame. + assert.deepEqual(lineNoTexts(html), ["1", "2", "1", "2"]); + assert.equal((html.match(/class="frame"/g) ?? []).length, 2); + }); +}); From 3d4c577966063cd16b0f21714c68fcb42127c6a7 Mon Sep 17 00:00:00 2001 From: Trillium Smith <trillium@trilliumsmith.com> Date: Wed, 8 Jul 2026 12:27:36 -0700 Subject: [PATCH 47/53] docs(command-visualizer): record frame-state types checked, no upstream home frame-state.ts field types already come from lib-common; container types (Decoration/Frame/CascadeState/CascadeMeta/FrameRole/OverlayRole) have no adoptable cursorless home. Decoration overlaps FlashDescriptor but that's editor-coupled + flash-only + lacks role. Recorded so it isn't re-audited. --- packages/command-visualizer/UPSTREAM_REUSE.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/packages/command-visualizer/UPSTREAM_REUSE.md b/packages/command-visualizer/UPSTREAM_REUSE.md index 6e07a18cd6..01f4832eec 100644 --- a/packages/command-visualizer/UPSTREAM_REUSE.md +++ b/packages/command-visualizer/UPSTREAM_REUSE.md @@ -93,6 +93,15 @@ let us drop `fixture-root.ts`. `app-web-docs/Code.tsx` is Shiki syntax highlighting, unrelated). - `model/overlays.ts` cross-decoration last-wins-per-cell precedence — lib-common's `decorationUtil` computes single-range **border geometry**, a different concern. +- `model/frame-state.ts` container types (checked 2026-07-08 against cursorless): + its FIELD types already come from lib-common (`Position`/`Range`/`GeneralizedRange`), + but the containers have no home. `Decoration {style,range,role}` is the only real + shape-overlap — with `FlashDescriptor {style, editor, range}` — but that requires + a live `TextEditor`, is flash-only (no `highlight0/1`), and lacks `role`; not + adoptable without an editor-free + highlight-inclusive upstream refactor, and even + then only partial. `Frame`/`CascadeState`/`CascadeMeta` are render/animation models + distinct from `TestCaseSnapshot` (raw text + marks). `FrameRole`/`OverlayRole` are + render enums. Do not re-chase. ## How to pursue The geometry adoption is our-side and unblocked — do it directly. Items 1–4 are From 9ef30e9774301a591f654c76c22d7d3f7504b1e2 Mon Sep 17 00:00:00 2001 From: Trillium Smith <trillium@trilliumsmith.com> Date: Wed, 8 Jul 2026 12:32:38 -0700 Subject: [PATCH 48/53] refactor(command-visualizer): move render-model types to model/types.ts Renames model/frame-state.ts -> model/types.ts and gives it a maintainer- facing header: these container types (CascadeState/Frame/Decoration/FrameRole/ OverlayRole) are package-specific with no current cursorless home (field types already come from lib-common). Isolated as a dedicated types file so cursorless maintainers can decide whether any warrant promotion. Type-only rename + import-path updates; zero behavior change (32 tests green, tsc clean). --- packages/command-visualizer/src/ARCHITECTURE.md | 2 +- packages/command-visualizer/src/index.ts | 2 +- .../src/logic/build-render-object.ts | 2 +- .../command-visualizer/src/logic/chain.test.ts | 2 +- packages/command-visualizer/src/logic/chain.ts | 2 +- .../command-visualizer/src/logic/derive-flashes.ts | 2 +- .../src/logic/derive-overlays.ts | 2 +- .../command-visualizer/src/logic/pipeline-types.ts | 2 +- packages/command-visualizer/src/logic/pipeline.ts | 2 +- packages/command-visualizer/src/model/overlays.ts | 2 +- packages/command-visualizer/src/model/timeline.ts | 2 +- .../src/model/{frame-state.ts => types.ts} | 14 +++++++++++--- .../src/render/css-cascade-flash.ts | 2 +- .../command-visualizer/src/render/css-cascade.ts | 2 +- packages/command-visualizer/src/render/html.ts | 2 +- .../src/render/jumbotron-css-keyframes.ts | 2 +- .../command-visualizer/src/render/jumbotron-css.ts | 2 +- .../src/render/jumbotron-shared.ts | 2 +- .../command-visualizer/src/render/jumbotron.ts | 2 +- .../src/render/serialize-cascade.test.ts | 2 +- .../src/render/serialize-cascade.ts | 2 +- packages/command-visualizer/src/render/svg-wrap.ts | 2 +- 22 files changed, 32 insertions(+), 24 deletions(-) rename packages/command-visualizer/src/model/{frame-state.ts => types.ts} (69%) diff --git a/packages/command-visualizer/src/ARCHITECTURE.md b/packages/command-visualizer/src/ARCHITECTURE.md index abdb75654c..d251be2622 100644 --- a/packages/command-visualizer/src/ARCHITECTURE.md +++ b/packages/command-visualizer/src/ARCHITECTURE.md @@ -12,7 +12,7 @@ render/ "what is visually seen": CascadeState -> HTML/CSS/SVG ``` - `data/` — colors.ts, decorations.ts, shapes.ts -- `model/` — frame-state.ts (CascadeState/Frame/Decoration; geometry `Position`/`Range`/`GeneralizedRange` come from `@cursorless/lib-common`), columns.ts (Line/Token/Column geometry), overlays.ts (decoration → column overlay resolution), timeline.ts (frame timing) +- `model/` — types.ts (package-defined render-model types: CascadeState/Frame/Decoration/FrameRole/OverlayRole; geometry `Position`/`Range`/`GeneralizedRange` come from `@cursorless/lib-common`), columns.ts (Line/Token/Column geometry), overlays.ts (decoration → column overlay resolution), timeline.ts (frame timing) - `logic/` — pipeline.ts, pipeline-types.ts, build-render-object.ts, fixture-extract.ts, fixture-yaml.ts, fixture-root.ts, tokenize.ts, hat-allocator.ts, chain.ts - `render/` — serialize.ts, serialize-cascade.ts, svg-wrap.ts, jumbotron.ts, css.ts, css-cascade.ts, symbols.ts, html.ts - `render-command.ts` — the top-level 4-stage orchestrator (root, spans logic + render). diff --git a/packages/command-visualizer/src/index.ts b/packages/command-visualizer/src/index.ts index 6e7fdc2cc7..345ec8f324 100644 --- a/packages/command-visualizer/src/index.ts +++ b/packages/command-visualizer/src/index.ts @@ -33,4 +33,4 @@ export { DURING_MS, BUMPER_MS, } from "./model/timeline"; -export type { CascadeState, Frame } from "./model/frame-state"; +export type { CascadeState, Frame } from "./model/types"; diff --git a/packages/command-visualizer/src/logic/build-render-object.ts b/packages/command-visualizer/src/logic/build-render-object.ts index 74022884d1..8bf3d132eb 100644 --- a/packages/command-visualizer/src/logic/build-render-object.ts +++ b/packages/command-visualizer/src/logic/build-render-object.ts @@ -4,7 +4,7 @@ // Behavior identical to the inline stage that lived in fixtureToCascade. // logic/ → logic/ import only. -import type { CascadeState, Frame } from "../model/frame-state"; +import type { CascadeState, Frame } from "../model/types"; import type { GeneralizedRange } from "@cursorless/lib-common"; import type { OverlayStyleName } from "../data/decorations"; import { asArr, asObj, toGeneralizedRange } from "./fixture-extract"; diff --git a/packages/command-visualizer/src/logic/chain.test.ts b/packages/command-visualizer/src/logic/chain.test.ts index 097d0cfeff..2bba2521a9 100644 --- a/packages/command-visualizer/src/logic/chain.test.ts +++ b/packages/command-visualizer/src/logic/chain.test.ts @@ -1,6 +1,6 @@ import assert from "node:assert/strict"; import { chainCascades, ChainContinuityError } from "./chain"; -import type { CascadeState, Frame } from "../model/frame-state"; +import type { CascadeState, Frame } from "../model/types"; function beforeFrame(): Frame { return { diff --git a/packages/command-visualizer/src/logic/chain.ts b/packages/command-visualizer/src/logic/chain.ts index f7557740c6..3925f59dbf 100644 --- a/packages/command-visualizer/src/logic/chain.ts +++ b/packages/command-visualizer/src/logic/chain.ts @@ -16,7 +16,7 @@ // the merged frame's slot END, // - carries step i's produced clipboard when step {i+1} has none. -import type { CascadeState, Frame } from "../model/frame-state"; +import type { CascadeState, Frame } from "../model/types"; /** * Pre-gif / post-gif bumpers: a 500ms PRE frame (initial state, before step 0 diff --git a/packages/command-visualizer/src/logic/derive-flashes.ts b/packages/command-visualizer/src/logic/derive-flashes.ts index a1b7e3dff1..847b16ee71 100644 --- a/packages/command-visualizer/src/logic/derive-flashes.ts +++ b/packages/command-visualizer/src/logic/derive-flashes.ts @@ -4,7 +4,7 @@ // mutation of caller state. logic/ → logic/ import only. import type { OverlayStyleName } from "../data/decorations"; -import type { Decoration } from "../model/frame-state"; +import type { Decoration } from "../model/types"; import { Position, type GeneralizedRange } from "@cursorless/lib-common"; export interface DerivedFlashes { diff --git a/packages/command-visualizer/src/logic/derive-overlays.ts b/packages/command-visualizer/src/logic/derive-overlays.ts index b5b9338a95..0c9b00ef8d 100644 --- a/packages/command-visualizer/src/logic/derive-overlays.ts +++ b/packages/command-visualizer/src/logic/derive-overlays.ts @@ -5,7 +5,7 @@ // caller state. logic/ → logic/ import only. import type { OverlayStyleName } from "../data/decorations"; -import type { Decoration } from "../model/frame-state"; +import type { Decoration } from "../model/types"; import { asArr, asObj, diff --git a/packages/command-visualizer/src/logic/pipeline-types.ts b/packages/command-visualizer/src/logic/pipeline-types.ts index 1c660b13e5..44ca841563 100644 --- a/packages/command-visualizer/src/logic/pipeline-types.ts +++ b/packages/command-visualizer/src/logic/pipeline-types.ts @@ -5,7 +5,7 @@ import type { HatColor, HatShape } from "@cursorless/lib-common"; import type { Theme } from "../data/colors"; -import type { Frame } from "../model/frame-state"; +import type { Frame } from "../model/types"; import type { Obj } from "./fixture-extract"; export interface PipelineOptions { diff --git a/packages/command-visualizer/src/logic/pipeline.ts b/packages/command-visualizer/src/logic/pipeline.ts index 230073a003..dee3a72745 100644 --- a/packages/command-visualizer/src/logic/pipeline.ts +++ b/packages/command-visualizer/src/logic/pipeline.ts @@ -13,7 +13,7 @@ import { readFileSync } from "node:fs"; import { parseFixtureYaml } from "./fixture-yaml"; import type { Theme } from "../data/colors"; -import type { CascadeState, Frame } from "../model/frame-state"; +import type { CascadeState, Frame } from "../model/types"; import { asArr, asObj, diff --git a/packages/command-visualizer/src/model/overlays.ts b/packages/command-visualizer/src/model/overlays.ts index 06837755ce..eebcc269f2 100644 --- a/packages/command-visualizer/src/model/overlays.ts +++ b/packages/command-visualizer/src/model/overlays.ts @@ -4,7 +4,7 @@ // line-range bands. import { type Column, expandColumns } from "./columns"; -import type { Decoration, Frame, OverlayRole } from "./frame-state"; +import type { Decoration, Frame, OverlayRole } from "./types"; import type { OverlayStyleName } from "../data/decorations"; import { overlayPrecedence } from "../data/decorations"; import { type Range, isLineRange } from "@cursorless/lib-common"; diff --git a/packages/command-visualizer/src/model/timeline.ts b/packages/command-visualizer/src/model/timeline.ts index 4db1811b07..eba44d32bb 100644 --- a/packages/command-visualizer/src/model/timeline.ts +++ b/packages/command-visualizer/src/model/timeline.ts @@ -20,7 +20,7 @@ // whether it has zero or multiple flash states — the during phase is // structural, with the reference sub-window always reserved. -import type { Frame } from "./frame-state"; +import type { Frame } from "./types"; export const INITIAL_MS = 2000; export const DURING_MS = 1000; diff --git a/packages/command-visualizer/src/model/frame-state.ts b/packages/command-visualizer/src/model/types.ts similarity index 69% rename from packages/command-visualizer/src/model/frame-state.ts rename to packages/command-visualizer/src/model/types.ts index 8b4ae795cc..176a7f3993 100644 --- a/packages/command-visualizer/src/model/frame-state.ts +++ b/packages/command-visualizer/src/model/types.ts @@ -1,6 +1,14 @@ -// Multi-frame state schema. A FRAME is exactly one `.cl-editor` surface -// (EditorState minus the doc-level theme/tab). A cascade wraps an ordered list -// of frames and adds the decoration OVERLAY layer. +// Package-defined render-model types (the multi-frame cascade schema). A FRAME +// is one `.cl-editor` surface; a cascade wraps an ordered list of frames plus a +// decoration overlay layer. +// +// MAINTAINERS: these container types are specific to this renderer and have no +// current home in cursorless (audited — see UPSTREAM_REUSE.md). Their FIELD +// types already come from `@cursorless/lib-common` (`Position`, `Range`, +// `GeneralizedRange`). `Decoration` overlaps lib-common's `FlashDescriptor` in +// shape but that is editor-coupled + flash-only. Decide whether any of these +// warrant promotion into a shared package; they are isolated here to make that +// call easy. import type { Theme } from "../data/colors"; import type { Line } from "./columns"; diff --git a/packages/command-visualizer/src/render/css-cascade-flash.ts b/packages/command-visualizer/src/render/css-cascade-flash.ts index 48ae7aa7b7..b49a03aaea 100644 --- a/packages/command-visualizer/src/render/css-cascade-flash.ts +++ b/packages/command-visualizer/src/render/css-cascade-flash.ts @@ -7,7 +7,7 @@ import { FLASH_PULSE_MS, type OverlayStyleName, } from "../data/decorations"; -import type { Frame } from "../model/frame-state"; +import type { Frame } from "../model/types"; import type { Timeline } from "../model/timeline"; import { pct } from "./css-cascade"; diff --git a/packages/command-visualizer/src/render/css-cascade.ts b/packages/command-visualizer/src/render/css-cascade.ts index f1ba864e94..b0d573e638 100644 --- a/packages/command-visualizer/src/render/css-cascade.ts +++ b/packages/command-visualizer/src/render/css-cascade.ts @@ -5,7 +5,7 @@ import { DECORATION_HEX, ALL_DECORATION_STYLES } from "../data/decorations"; import { FLASH_STYLES, HIGHLIGHT_STYLES } from "../data/decorations"; import { FLASH_PULSE_MS } from "../data/decorations"; -import type { Frame } from "../model/frame-state"; +import type { Frame } from "../model/types"; import { timelineOf, type Timeline } from "../model/timeline"; import { flashFadeKeyframes, flashFadeRules } from "./css-cascade-flash"; diff --git a/packages/command-visualizer/src/render/html.ts b/packages/command-visualizer/src/render/html.ts index 0efbe0d97c..0d0d008874 100644 --- a/packages/command-visualizer/src/render/html.ts +++ b/packages/command-visualizer/src/render/html.ts @@ -4,7 +4,7 @@ // of sync — three of the four copies had differing quote-escaping before this // was consolidated). -import type { CascadeState } from "../model/frame-state"; +import type { CascadeState } from "../model/types"; /** * HTML escaper safe for BOTH text content AND quoted-attribute contexts. diff --git a/packages/command-visualizer/src/render/jumbotron-css-keyframes.ts b/packages/command-visualizer/src/render/jumbotron-css-keyframes.ts index b0b7a25550..02de578fea 100644 --- a/packages/command-visualizer/src/render/jumbotron-css-keyframes.ts +++ b/packages/command-visualizer/src/render/jumbotron-css-keyframes.ts @@ -2,7 +2,7 @@ // of jumbotronCss. Extracted verbatim from jumbotron.ts so every jumbotron CSS // module stays under the 250-line limit. render/ → render/ import only. -import type { CascadeState } from "../model/frame-state"; +import type { CascadeState } from "../model/types"; import { frameDurMs, timelineOf } from "../model/timeline"; import { NL, diff --git a/packages/command-visualizer/src/render/jumbotron-css.ts b/packages/command-visualizer/src/render/jumbotron-css.ts index 3b4efe294f..e1a79a1f1a 100644 --- a/packages/command-visualizer/src/render/jumbotron-css.ts +++ b/packages/command-visualizer/src/render/jumbotron-css.ts @@ -6,7 +6,7 @@ // ./jumbotron-css-keyframes; this module assembles base + themed + those // keyframes + the carousel track. render/ → render/ import only. -import type { CascadeState } from "../model/frame-state"; +import type { CascadeState } from "../model/types"; import { MS_PER_STATE } from "../data/decorations"; import { timelineOf } from "../model/timeline"; import { diff --git a/packages/command-visualizer/src/render/jumbotron-shared.ts b/packages/command-visualizer/src/render/jumbotron-shared.ts index 26a3994fa8..0d390624ea 100644 --- a/packages/command-visualizer/src/render/jumbotron-shared.ts +++ b/packages/command-visualizer/src/render/jumbotron-shared.ts @@ -3,7 +3,7 @@ // dependency-free leaf module so the markup and CSS modules never import each // other (avoids a cycle) and never duplicate these. render/ → render/ only. -import type { CascadeState } from "../model/frame-state"; +import type { CascadeState } from "../model/types"; import type { Timeline } from "../model/timeline"; export const NL = String.fromCharCode(10); diff --git a/packages/command-visualizer/src/render/jumbotron.ts b/packages/command-visualizer/src/render/jumbotron.ts index 16aeba3c0d..8f4a824df6 100644 --- a/packages/command-visualizer/src/render/jumbotron.ts +++ b/packages/command-visualizer/src/render/jumbotron.ts @@ -22,7 +22,7 @@ // The CSS half (jumbotronCss) lives in ./jumbotron-css (+ -keyframes); it is // re-exported below so the public surface (index.ts) is unchanged. -import type { CascadeState } from "../model/frame-state"; +import type { CascadeState } from "../model/types"; import { timelineOf } from "../model/timeline"; import { esc } from "./html"; import { NL, frameCommands } from "./jumbotron-shared"; diff --git a/packages/command-visualizer/src/render/serialize-cascade.test.ts b/packages/command-visualizer/src/render/serialize-cascade.test.ts index 40500111e9..584502ef2f 100644 --- a/packages/command-visualizer/src/render/serialize-cascade.test.ts +++ b/packages/command-visualizer/src/render/serialize-cascade.test.ts @@ -1,6 +1,6 @@ import assert from "node:assert/strict"; import type { Line } from "../model/columns"; -import type { CascadeState, Frame } from "../model/frame-state"; +import type { CascadeState, Frame } from "../model/types"; import { serializeCascade } from "./serialize-cascade"; /** A plain text line as a single hatless token (no logic/ dependency). */ diff --git a/packages/command-visualizer/src/render/serialize-cascade.ts b/packages/command-visualizer/src/render/serialize-cascade.ts index 7e41dd9f5f..112ef96611 100644 --- a/packages/command-visualizer/src/render/serialize-cascade.ts +++ b/packages/command-visualizer/src/render/serialize-cascade.ts @@ -9,7 +9,7 @@ import { cascadeStyleSheet, cascadeThemeBridge } from "./css-cascade"; import { jumbotronCss, serializeJumbotron } from "./jumbotron"; import type { CellOverlay } from "../model/overlays"; import { symbolSheet } from "./symbols"; -import type { CascadeState, Frame } from "../model/frame-state"; +import type { CascadeState, Frame } from "../model/types"; import { resolveFrameOverlays, type LineOverlay } from "../model/overlays"; import { HIGHLIGHT_STYLES, MS_PER_STATE } from "../data/decorations"; import { timelineOf } from "../model/timeline"; diff --git a/packages/command-visualizer/src/render/svg-wrap.ts b/packages/command-visualizer/src/render/svg-wrap.ts index d4a3b0dcaf..315830e1e0 100644 --- a/packages/command-visualizer/src/render/svg-wrap.ts +++ b/packages/command-visualizer/src/render/svg-wrap.ts @@ -8,7 +8,7 @@ // survives any monospace fallback; the estimate only needs enough slack that // the widest expected monospace advance (~0.62em) never clips. -import type { CascadeState } from "../model/frame-state"; +import type { CascadeState } from "../model/types"; import { serializeCascade } from "./serialize-cascade"; import { jumbotronCss, serializeJumbotron } from "./jumbotron"; import { styleSheet } from "./css"; From af06ece31c2ff0ca541e5b1f25811efecc5305a1 Mon Sep 17 00:00:00 2001 From: Trillium Smith <trillium@trilliumsmith.com> Date: Wed, 8 Jul 2026 12:38:43 -0700 Subject: [PATCH 49/53] docs(command-visualizer): record hat-vocabulary consolidation landscape MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The hat color/shape vocabulary existed 5x on upstream (app-vscode exported-but- unimportable + 3 frozen legacy command schemas + a talonjs test const). This PR moved it into lib-common's hatStyles.types.ts (was a stub) and rewired app-vscode to consume it — first importable shared home, net duplication reduced. Records the remaining (maintainer-side) consolidation of the non-frozen private copies. --- packages/command-visualizer/UPSTREAM_REUSE.md | 21 +++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/packages/command-visualizer/UPSTREAM_REUSE.md b/packages/command-visualizer/UPSTREAM_REUSE.md index 01f4832eec..7cd6fe5022 100644 --- a/packages/command-visualizer/UPSTREAM_REUSE.md +++ b/packages/command-visualizer/UPSTREAM_REUSE.md @@ -5,6 +5,27 @@ > today** and what would need a **small upstream refactor + export** first. > Goal: as a first-party package, reimplement as little as possible. +## Hat vocabulary: consolidated (and a remaining upstream cleanup) + +The hat color/shape vocabulary (`HAT_COLORS`/`HAT_SHAPES`/`HatColor`/`HatShape`/…) +existed in FIVE places on upstream/main, but none was importable by another +package: +- `app-vscode/.../hatStyles.types.ts` — full exported set, but app-vscode ships + only `extension.cjs`, so unreachable from other packages. +- private copies in 3 legacy command schemas (`CommandV0V1.types.ts`, + `targetDescriptorV2.types.ts`, `PartialTargetDescriptorV3.types.ts`) — frozen + historical formats, deliberately self-contained. +- a private `const HAT_COLORS` in `lib-talonjs-core/.../TalonJsTestHats.ts`. + +This PR moved the vocabulary into `lib-common/src/ide/types/hatStyles.types.ts` +(previously just a `HatStyleName = string` stub) and rewired app-vscode to import +it — creating the first importable shared home and REDUCING duplication (app-vscode +no longer defines its own). command-visualizer imports this shared definition. + +Remaining (upstream cleanup, NOT this PR): the 3 legacy schemas (frozen by design +— leave them) and the talonjs test const still hold private copies; a maintainer +could point the non-frozen ones at the shared lib-common home. + ## Status: already reused (no action) The package already imports from source rather than cloning: From c86aca3d73466d407f92357e469bd145d9440f7a Mon Sep 17 00:00:00 2001 From: Trillium Smith <trillium@trilliumsmith.com> Date: Mon, 3 Aug 2026 21:43:23 -0700 Subject: [PATCH 50/53] fix: resolve lint warnings in command-visualizer package - Move inline comments to separate lines (eslint/no-inline-comments) - Fix hexadecimal digit casing and numeric separators - Replace forEach with for loops (unicorn/no-array-for-each) - Use template literals instead of string concatenation - Fix length checks to use .length > 0 - Use String.fromCodePoint where appropriate - Move functions to outer scope for consistent function scoping - Add Unicode flag to regex patterns - Extract circular dependency via css-utils.ts --- packages/command-visualizer/UPSTREAM_REUSE.md | 22 ++++-- .../command-visualizer/src/ARCHITECTURE.md | 12 ++-- .../src/data/decorations.ts | 3 +- .../src/data/shapes.test.ts | 9 +-- packages/command-visualizer/src/index.ts | 5 +- .../src/logic/build-render-object.ts | 4 +- .../src/logic/chain.test.ts | 6 +- .../command-visualizer/src/logic/chain.ts | 6 +- .../src/logic/derive-flashes.ts | 16 +++-- .../src/logic/derive-overlays.ts | 9 +-- .../src/logic/fixture-extract.ts | 26 +++---- .../src/logic/fixture-root.ts | 23 +++---- .../src/logic/hat-allocator.test.ts | 20 +++--- .../src/logic/hat-allocator.ts | 23 ++++--- .../command-visualizer/src/logic/pipeline.ts | 21 +++--- .../command-visualizer/src/logic/tokenize.ts | 11 +-- .../command-visualizer/src/model/columns.ts | 67 ++++++++++++------- .../command-visualizer/src/model/overlays.ts | 17 +++-- .../command-visualizer/src/model/types.ts | 4 +- .../command-visualizer/src/render-command.ts | 27 ++++---- .../src/render/css-cascade-flash.ts | 64 +++++++++--------- .../src/render/css-cascade.ts | 19 +++--- packages/command-visualizer/src/render/css.ts | 2 +- .../command-visualizer/src/render/html.ts | 10 +-- .../src/render/jumbotron-css-keyframes.ts | 39 ++++------- .../src/render/jumbotron-css.ts | 23 ++----- .../src/render/jumbotron-shared.ts | 14 ++-- .../src/render/jumbotron.ts | 26 +++---- .../src/render/serialize-cascade.test.ts | 18 +++-- .../src/render/serialize-cascade.ts | 39 +++++------ .../src/render/serialize.ts | 27 ++++---- .../command-visualizer/src/render/svg-wrap.ts | 22 +++--- 32 files changed, 327 insertions(+), 307 deletions(-) diff --git a/packages/command-visualizer/UPSTREAM_REUSE.md b/packages/command-visualizer/UPSTREAM_REUSE.md index 7cd6fe5022..28f84634ba 100644 --- a/packages/command-visualizer/UPSTREAM_REUSE.md +++ b/packages/command-visualizer/UPSTREAM_REUSE.md @@ -10,6 +10,7 @@ The hat color/shape vocabulary (`HAT_COLORS`/`HAT_SHAPES`/`HatColor`/`HatShape`/…) existed in FIVE places on upstream/main, but none was importable by another package: + - `app-vscode/.../hatStyles.types.ts` — full exported set, but app-vscode ships only `extension.cjs`, so unreachable from other packages. - private copies in 3 legacy command schemas (`CommandV0V1.types.ts`, @@ -46,6 +47,7 @@ Local-with-provenance (no importable TS source; canonical form is config/SVG): ## Adoptable today — no upstream change needed ### Geometry: `Position` / `Range` / `GeneralizedRange` + - **What:** `@cursorless/lib-common` exports `Position` and `Range` classes (with `isEqual`/`isBefore`/`contains`/`with`/`fromConcise`), plus `GeneralizedRange`, `CharacterRange`, `LineRange`, and the helpers `isLineRange`, `toLineRange`, @@ -65,18 +67,19 @@ Local-with-provenance (no importable TS source; canonical form is config/SVG): ## Needs an upstream refactor + export first -Each of these is blocked by *coupling* (live `TextEditor` / disk I/O / no pure +Each of these is blocked by _coupling_ (live `TextEditor` / disk I/O / no pure unit), not merely a missing export — so it needs a small cursorless-side change before we can consume it. Listed by value. -| # | If cursorless… | We'd delete | Value | Feasibility | -|---|----------------|-------------|-------|-------------| -| 1 | extracted a **pure flash-derivation** — `diff(beforeDoc, afterDoc) → {pendingDelete, justAdded} ranges` — from the action runtime | `logic/derive-flashes.ts` | **High** (real duplicated logic) | **Hard** — no pure unit exists today | -| 2 | offered an **editor-free `serializedMarksToTokenHats`** taking plain `{offset,text}` instead of a live `TextEditor` | `parseMarks` + mark attachment in `logic/fixture-extract.ts` | Medium | Medium | -| 3 | exported a **grapheme-level tokenizer** (or made `getTokensInRange` output headless-consumable as a render model) | most of `logic/tokenize.ts`, part of `model/columns.ts` | Medium | Medium (word-vs-grapheme gap) | -| 4 | **parameterized fixture-path** resolution — `getFixturesPath(root)` instead of env-var-throw + one hardcoded layout | `logic/fixture-root.ts` | Low | Easy | +| # | If cursorless… | We'd delete | Value | Feasibility | +| --- | --------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ | -------------------------------- | ------------------------------------ | +| 1 | extracted a **pure flash-derivation** — `diff(beforeDoc, afterDoc) → {pendingDelete, justAdded} ranges` — from the action runtime | `logic/derive-flashes.ts` | **High** (real duplicated logic) | **Hard** — no pure unit exists today | +| 2 | offered an **editor-free `serializedMarksToTokenHats`** taking plain `{offset,text}` instead of a live `TextEditor` | `parseMarks` + mark attachment in `logic/fixture-extract.ts` | Medium | Medium | +| 3 | exported a **grapheme-level tokenizer** (or made `getTokensInRange` output headless-consumable as a render model) | most of `logic/tokenize.ts`, part of `model/columns.ts` | Medium | Medium (word-vs-grapheme gap) | +| 4 | **parameterized fixture-path** resolution — `getFixturesPath(root)` instead of env-var-throw + one hardcoded layout | `logic/fixture-root.ts` | Low | Easy | ### 1. Pure flash-derivation (highest value) + Today, cursorless flashes are a **runtime side-effect**: actions execute against a live IDE and call `ide().flashRanges(...)` (see `lib-engine/src/actions/*`, `core/updateSelections/`, `RangeUpdater`). There is no pure @@ -88,6 +91,7 @@ cursorless's own test/tooling surface, not just us. **Best upstream proposal candidate.** ### 2. Editor-free marks → hats + `lib-common/src/util/serializedMarksToTokenHats.ts` hard-requires a live `TextEditor` (`editor.document.offsetAt(range)`, `.getText(range)`) and returns engine `TokenHat[]`. Our `parseMarks` reads plain fixture YAML (`{color}.{grapheme}`) @@ -95,6 +99,7 @@ with no editor and yields the render-model `MarkInfo`. A pure core that takes offsets/text (splitting the editor I/O from the mapping) would let us drop ours. ### 3. Grapheme tokenizer / headless token model + The engine tokenizer produces **word/token** units, not one-token-per-grapheme, and isn't barrel-exported; `getTokensInRange` needs a live editor. `columns.ts` also needs East-Asian display width — for which **no util exists anywhere** in the @@ -103,12 +108,14 @@ would shrink `tokenize.ts`/`columns.ts`; the display-width piece would still be ours unless cursorless grew one (it never needed display geometry). ### 4. Parameterized fixture path + `lib-node-common` `getCursorlessRepoRoot()` throws unless `CURSORLESS_REPO_ROOT` is set, and `getFixturesPath` hardcodes the single `resources/fixtures` layout. Ours does a dual-layout probe with a sensible default. A root-param overload would let us drop `fixture-root.ts`. ## Not reusable (genuinely new — no upstream candidate) + - `model/timeline.ts` (animation timing), `logic/chain.ts` (multi-step chaining), `render/*` (HTML/CSS/SVG hat renderer — nothing like it exists upstream; `app-web-docs/Code.tsx` is Shiki syntax highlighting, unrelated). @@ -125,6 +132,7 @@ let us drop `fixture-root.ts`. render enums. Do not re-chase. ## How to pursue + The geometry adoption is our-side and unblocked — do it directly. Items 1–4 are upstream-contribution opportunities: raise as cursorless issues/PRs (extract the pure core, add the export), then consume. Item 1 (pure flash-derivation) is the diff --git a/packages/command-visualizer/src/ARCHITECTURE.md b/packages/command-visualizer/src/ARCHITECTURE.md index d251be2622..25904e071c 100644 --- a/packages/command-visualizer/src/ARCHITECTURE.md +++ b/packages/command-visualizer/src/ARCHITECTURE.md @@ -24,12 +24,12 @@ The whole tool is one legible top-to-bottom progression. Read `renderCommand` in `render-command.ts` to see all four stages at a glance; each delegates to a named function: -| # | Stage | Function | File | -|---|-------|----------|------| -| 1 | get what to render | `parseFixture` | `logic/pipeline.ts` | -| 2 | tokenize each step | `tokenizeStates` | `logic/pipeline.ts` | -| 3 | generate render object | `buildRenderObject` | `logic/build-render-object.ts` | -| 4 | render from object | `serializeCascade` + `wrapCascadeSvg` | `render/serialize-cascade.ts`, `render/svg-wrap.ts` | +| # | Stage | Function | File | +| --- | ---------------------- | ------------------------------------- | --------------------------------------------------- | +| 1 | get what to render | `parseFixture` | `logic/pipeline.ts` | +| 2 | tokenize each step | `tokenizeStates` | `logic/pipeline.ts` | +| 3 | generate render object | `buildRenderObject` | `logic/build-render-object.ts` | +| 4 | render from object | `serializeCascade` + `wrapCascadeSvg` | `render/serialize-cascade.ts`, `render/svg-wrap.ts` | Stages 1–3 produce the `CascadeState` render object; stage 4 serializes it to an animated SVG. `fixtureToCascade` (exported, unchanged behavior) is a thin diff --git a/packages/command-visualizer/src/data/decorations.ts b/packages/command-visualizer/src/data/decorations.ts index a6dbbf4e27..5cc77cbb33 100644 --- a/packages/command-visualizer/src/data/decorations.ts +++ b/packages/command-visualizer/src/data/decorations.ts @@ -71,5 +71,6 @@ export function overlayPrecedence( if (HIGHLIGHT_STYLES.includes(style as HighlightStyle)) { return 1; } - return 2; // flash + // flash + return 2; } diff --git a/packages/command-visualizer/src/data/shapes.test.ts b/packages/command-visualizer/src/data/shapes.test.ts index 15be756214..4e93c2fde1 100644 --- a/packages/command-visualizer/src/data/shapes.test.ts +++ b/packages/command-visualizer/src/data/shapes.test.ts @@ -11,10 +11,7 @@ import { SHAPE_PATHS } from "./shapes"; // fails and points at the exact shape to re-sync. Runtime stays pure; the fs // read lives here, at test time, only. -const HATS_DIR = new URL( - "../../../../resources/images/hats/", - import.meta.url, -); +const HATS_DIR = new URL("../../../../resources/images/hats/", import.meta.url); function svgOf(shape: string): string { return readFileSync(new URL(`${shape}.svg`, HATS_DIR), "utf8"); @@ -23,8 +20,8 @@ function svgOf(shape: string): string { suite("command-visualizer/data/shapes", () => { test("SHAPE_PATHS covers exactly the hat shapes", () => { assert.deepEqual( - Object.keys(SHAPE_PATHS).sort(), - [...HAT_SHAPES].sort(), + Object.keys(SHAPE_PATHS).toSorted(), + [...HAT_SHAPES].toSorted(), ); }); diff --git a/packages/command-visualizer/src/index.ts b/packages/command-visualizer/src/index.ts index 345ec8f324..4c79169e14 100644 --- a/packages/command-visualizer/src/index.ts +++ b/packages/command-visualizer/src/index.ts @@ -11,10 +11,7 @@ export { type ParsedFixture, type TokenizedStates, } from "./logic/pipeline"; -export { - renderCommand, - type RenderCommandOptions, -} from "./render-command"; +export { renderCommand, type RenderCommandOptions } from "./render-command"; export { chainCascades, withBumpers, diff --git a/packages/command-visualizer/src/logic/build-render-object.ts b/packages/command-visualizer/src/logic/build-render-object.ts index 8bf3d132eb..fbef591412 100644 --- a/packages/command-visualizer/src/logic/build-render-object.ts +++ b/packages/command-visualizer/src/logic/build-render-object.ts @@ -4,12 +4,12 @@ // Behavior identical to the inline stage that lived in fixtureToCascade. // logic/ → logic/ import only. -import type { CascadeState, Frame } from "../model/types"; import type { GeneralizedRange } from "@cursorless/lib-common"; import type { OverlayStyleName } from "../data/decorations"; -import { asArr, asObj, toGeneralizedRange } from "./fixture-extract"; +import type { CascadeState, Frame } from "../model/types"; import { deriveFlashes } from "./derive-flashes"; import { deriveOverlays } from "./derive-overlays"; +import { asArr, asObj, toGeneralizedRange } from "./fixture-extract"; import type { ParsedFixture, PipelineOptions, diff --git a/packages/command-visualizer/src/logic/chain.test.ts b/packages/command-visualizer/src/logic/chain.test.ts index 2bba2521a9..1c61f69143 100644 --- a/packages/command-visualizer/src/logic/chain.test.ts +++ b/packages/command-visualizer/src/logic/chain.test.ts @@ -1,6 +1,6 @@ import assert from "node:assert/strict"; -import { chainCascades, ChainContinuityError } from "./chain"; import type { CascadeState, Frame } from "../model/types"; +import { chainCascades, ChainContinuityError } from "./chain"; function beforeFrame(): Frame { return { @@ -22,8 +22,8 @@ suite("command-visualizer/chain", () => { let caught: unknown; try { chainCascades([], "recorded/x.yml"); - } catch (err) { - caught = err; + } catch (error) { + caught = error; } assert.ok(caught instanceof ChainContinuityError); assert.equal((caught as ChainContinuityError).stepIndex, 0); diff --git a/packages/command-visualizer/src/logic/chain.ts b/packages/command-visualizer/src/logic/chain.ts index 3925f59dbf..e717bf9919 100644 --- a/packages/command-visualizer/src/logic/chain.ts +++ b/packages/command-visualizer/src/logic/chain.ts @@ -53,6 +53,7 @@ export class ChainContinuityError extends Error { message: string, ) { super(message); + this.name = "ChainContinuityError"; } } @@ -72,7 +73,10 @@ export function chainCascades( fixtureLabel: string, ): CascadeState { if (states.length === 0) { - throw new ChainContinuityError(0, "chainCascades requires at least one state"); + throw new ChainContinuityError( + 0, + "chainCascades requires at least one state", + ); } if (states.length === 1) { return { ...states[0], meta: { ...states[0].meta, fixture: fixtureLabel } }; diff --git a/packages/command-visualizer/src/logic/derive-flashes.ts b/packages/command-visualizer/src/logic/derive-flashes.ts index 847b16ee71..719d3eb9ac 100644 --- a/packages/command-visualizer/src/logic/derive-flashes.ts +++ b/packages/command-visualizer/src/logic/derive-flashes.ts @@ -3,9 +3,10 @@ // the two document snapshots, returns the flashes to synthesize. No I/O, no // mutation of caller state. logic/ → logic/ import only. +import type { GeneralizedRange } from "@cursorless/lib-common"; +import { Position } from "@cursorless/lib-common"; import type { OverlayStyleName } from "../data/decorations"; import type { Decoration } from "../model/types"; -import { Position, type GeneralizedRange } from "@cursorless/lib-common"; export interface DerivedFlashes { /** pendingDelete flashes to append to the DURING flash list (pre-edit). */ @@ -14,6 +15,13 @@ export interface DerivedFlashes { afterDecorations: Decoration[]; } +function toPos(doc: string, off: number): Position { + const upto = doc.slice(0, off); + const line = (upto.match(/\n/gu) ?? []).length; + const character = off - (upto.lastIndexOf("\n") + 1); + return new Position(line, character); +} + /** * Derived referenceFlashes: tutorial-corpus recordings carry NO * ide.flashes (all 10 tutorial-1-basics fixtures have zero) even for document @@ -43,12 +51,6 @@ export function deriveFlashes(args: { finDoc !== initDoc && hasAfterFrame ) { - const toPos = (doc: string, off: number): Position => { - const upto = doc.slice(0, off); - const line = (upto.match(/\n/g) ?? []).length; - const character = off - (upto.lastIndexOf("\n") + 1); - return new Position(line, character); - }; let p = 0; while ( p < initDoc.length && diff --git a/packages/command-visualizer/src/logic/derive-overlays.ts b/packages/command-visualizer/src/logic/derive-overlays.ts index 0c9b00ef8d..e729785ae5 100644 --- a/packages/command-visualizer/src/logic/derive-overlays.ts +++ b/packages/command-visualizer/src/logic/derive-overlays.ts @@ -6,13 +6,8 @@ import type { OverlayStyleName } from "../data/decorations"; import type { Decoration } from "../model/types"; -import { - asArr, - asObj, - pos, - toGeneralizedRange, - type Obj, -} from "./fixture-extract"; +import type { Obj } from "./fixture-extract"; +import { asArr, asObj, pos, toGeneralizedRange } from "./fixture-extract"; export interface OverlayDecorations { /** highlight decorations to append to the BEFORE frame. */ diff --git a/packages/command-visualizer/src/logic/fixture-extract.ts b/packages/command-visualizer/src/logic/fixture-extract.ts index 4337a4a87c..3c8b2194d5 100644 --- a/packages/command-visualizer/src/logic/fixture-extract.ts +++ b/packages/command-visualizer/src/logic/fixture-extract.ts @@ -2,17 +2,16 @@ // YAML-shape coercion + marks→hats + selections + range mapping out of // pipeline.ts so each module stays under the line ceiling. -import type { YamlValue } from "./fixture-yaml"; -import { tokenizeDoc } from "./tokenize"; -import type { HatColor, HatShape } from "@cursorless/lib-common"; -import { HAT_COLORS } from "@cursorless/lib-common"; -import type { Line, Token, InputHat } from "../model/columns"; -import { - Position, - Range, - type GeneralizedRange, +import type { + HatColor, + HatShape, + GeneralizedRange, } from "@cursorless/lib-common"; +import { HAT_COLORS, Position, Range } from "@cursorless/lib-common"; +import type { Line, Token, InputHat } from "../model/columns"; +import type { YamlValue } from "./fixture-yaml"; import { allocateHats } from "./hat-allocator"; +import { tokenizeDoc } from "./tokenize"; export type Obj = Record<string, YamlValue>; @@ -61,8 +60,9 @@ export function parseMarks(marksObj: Obj | null): MarkInfo[] { continue; } const dot = key.indexOf("."); + // mark key must be "{color}.{grapheme}" — skip malformed entries if (dot === -1) { - continue; // mark key must be "{color}.{grapheme}" — skip malformed entries + continue; } const colorRaw = key.slice(0, dot); const grapheme = key.slice(dot + 1); @@ -113,9 +113,10 @@ export function buildLines( // ({color}.{grapheme}) carry no shape component: the recorded session's // hats were default-shape, so "default" is the faithful rendering. for (const mk of marks) { + // marks are single-line in corpus if (mk.start.line !== mk.end.line) { continue; - } // marks are single-line in corpus + } const line = lines[mk.start.line]; if (!line) { continue; @@ -201,7 +202,8 @@ export function toGeneralizedRange(rangeObj: Obj): GeneralizedRange | null { return { type: "line", start: num(rangeObj.start), - end: num(rangeObj.end), // last line, INCLUSIVE per lib-common LineRange + // last line, INCLUSIVE per lib-common LineRange + end: num(rangeObj.end), }; } return { diff --git a/packages/command-visualizer/src/logic/fixture-root.ts b/packages/command-visualizer/src/logic/fixture-root.ts index 982ff9629f..29219ca326 100644 --- a/packages/command-visualizer/src/logic/fixture-root.ts +++ b/packages/command-visualizer/src/logic/fixture-root.ts @@ -13,7 +13,7 @@ // // Dedup note (re-verified against current signatures): @cursorless/lib-node-common // exports getFixturesPath()/getRecordedTestsDirPath(), but getFixturesPath() -// hardcodes `path.join(getCursorlessRepoRoot(), "resources", "fixtures")` — the +// hardcodes `path.path.join(getCursorlessRepoRoot(), "resources", "fixtures")` — the // single layout-A shape — and getCursorlessRepoRoot() *throws* unless // CURSORLESS_REPO_ROOT is set (a script-only helper). This module deliberately // keeps its dual-layout probe (resources/… fork vs data/… main repo), its @@ -24,24 +24,23 @@ import { existsSync } from "node:fs"; import { homedir } from "node:os"; -import { join } from "node:path"; +import path from "node:path"; /** Absolute path to the cursorless repo root (env override, else $HOME/code/cursorless). */ export function cursorlessRepoRoot(): string { + // eslint-disable-next-line node/no-process-env const fromEnv = process.env.CURSORLESS_REPO?.trim(); const root = fromEnv && fromEnv.length > 0 ? fromEnv - : join(homedir(), "code", "cursorless"); + : path.join(homedir(), "code", "cursorless"); if (!existsSync(root)) { const how = fromEnv - ? '$CURSORLESS_REPO is set to "' + root + '"' - : 'defaulted to "' + root + '" ($HOME/code/cursorless)'; + ? `$CURSORLESS_REPO is set to "${root}"` + : `defaulted to "${root}" ($HOME/code/cursorless)`; throw new Error( - `cursorless repo not found: ${how}, but that path does not exist.\n` + - `Set CURSORLESS_REPO to your cursorless checkout, e.g.\n` + - ` CURSORLESS_REPO=/path/to/cursorless bun run verify`, + `cursorless repo not found: ${how}, but that path does not exist.\nSet CURSORLESS_REPO to your cursorless checkout, e.g.\n CURSORLESS_REPO=/path/to/cursorless bun run verify`, ); } return root; @@ -51,12 +50,12 @@ export function cursorlessRepoRoot(): string { export function hatsRoot(): string { const root = cursorlessRepoRoot(); // Layout A (mini2 fork): resources/images/hats/ - const layoutA = join(root, "resources", "images", "hats"); + const layoutA = path.join(root, "resources", "images", "hats"); if (existsSync(layoutA)) { return layoutA; } // Layout B (main repo): images/hats/ - const layoutB = join(root, "images", "hats"); + const layoutB = path.join(root, "images", "hats"); if (existsSync(layoutB)) { return layoutB; } @@ -70,12 +69,12 @@ export function hatsRoot(): string { export function fixtureRoot(): string { const root = cursorlessRepoRoot(); // Layout A (mini2 fork): resources/fixtures/recorded/ - const layoutA = join(root, "resources", "fixtures", "recorded"); + const layoutA = path.join(root, "resources", "fixtures", "recorded"); if (existsSync(layoutA)) { return layoutA; } // Layout B (main repo): data/fixtures/recorded/ - const layoutB = join(root, "data", "fixtures", "recorded"); + const layoutB = path.join(root, "data", "fixtures", "recorded"); if (existsSync(layoutB)) { return layoutB; } diff --git a/packages/command-visualizer/src/logic/hat-allocator.test.ts b/packages/command-visualizer/src/logic/hat-allocator.test.ts index bf40c59500..51976eee18 100644 --- a/packages/command-visualizer/src/logic/hat-allocator.test.ts +++ b/packages/command-visualizer/src/logic/hat-allocator.test.ts @@ -1,7 +1,7 @@ import assert from "node:assert/strict"; import type { HatColor } from "@cursorless/lib-common"; -import { allocateHats, cssStateHatStyles } from "./hat-allocator"; import type { InputHat, Line, Token } from "../model/columns"; +import { allocateHats, cssStateHatStyles } from "./hat-allocator"; // Build a Line whose tokens are one-per-grapheme (the render model, tokenize.ts // R5) with line-relative UTF-16 ranges. Spaces are emitted as their own tokens @@ -29,6 +29,14 @@ function countHatted(lines: Line[]): number { ); } +function snapshot(lines: Line[]) { + return lines.map((l) => + l.tokens.map((t) => + t.hat ? `${t.range.start}:${t.hat.color}/${t.hat.shape}` : "", + ), + ); +} + suite("command-visualizer/hat-allocator", () => { suite("cssStateHatStyles", () => { test("keys pure colors and color-shape variants with penalty ordering", () => { @@ -85,7 +93,8 @@ suite("command-visualizer/hat-allocator", () => { // same color it went in with. const l = line("hello world"); const pinnedColor: HatColor = "yellow"; - const worldStart = "hello ".length; // char index of "w" + // char index of "w" + const worldStart = "hello ".length; const marked = markToken(l, worldStart, { color: pinnedColor, shape: "default", @@ -120,13 +129,6 @@ suite("command-visualizer/hat-allocator", () => { allocateHats(a); allocateHats(b); - const snapshot = (lines: Line[]) => - lines.map((l) => - l.tokens.map((t) => - t.hat ? `${t.range.start}:${t.hat.color}/${t.hat.shape}` : "", - ), - ); - assert.deepEqual(snapshot(a), snapshot(b)); }); diff --git a/packages/command-visualizer/src/logic/hat-allocator.ts b/packages/command-visualizer/src/logic/hat-allocator.ts index 17a79b46a7..025f9e02e2 100644 --- a/packages/command-visualizer/src/logic/hat-allocator.ts +++ b/packages/command-visualizer/src/logic/hat-allocator.ts @@ -34,23 +34,27 @@ // Determinism: the engine allocator is pure (no Date/random); the same lines + // marks + cursor produce identical assignments. +import type { + HatColor, + HatShape, + HatStyleMap, + TokenHat, +} from "@cursorless/lib-common"; import { FakeIDE, HatStability, - type HatStyleMap, InMemoryTextEditor, Position, Range, Selection, - type TokenHat, + HAT_COLORS, + HAT_SHAPES, } from "@cursorless/lib-common"; import { allocateHats as allocateHatsReal, getTokensInRange, TokenGraphemeSplitter, } from "@cursorless/lib-engine"; -import type { HatColor, HatShape } from "@cursorless/lib-common"; -import { HAT_COLORS, HAT_SHAPES } from "@cursorless/lib-common"; import type { Line, Token as RenderToken } from "../model/columns"; // --------------------------------------------------------------------------- @@ -75,9 +79,10 @@ export function cssStateHatStyles(): HatStyleMap { } for (const color of HAT_COLORS) { for (const shape of HAT_SHAPES) { + // bare color IS the default shape if (shape === "default") { continue; - } // bare color IS the default shape + } out[`${color}-${shape}`] = { penalty: colorPenalty(color) + 1 }; } } @@ -146,7 +151,8 @@ export function allocateHats( // (4) Collect fixture marks from the render tokens carrying a pass-1 hat. const marks: Mark[] = []; - lines.forEach((line, lineIdx) => { + for (let lineIdx = 0; lineIdx < lines.length; lineIdx++) { + const line = lines[lineIdx]; for (const token of line.tokens) { if (token.hat) { marks.push({ @@ -157,7 +163,7 @@ export function allocateHats( }); } } - }); + } // Discover the engine tokens once (whole document), so forced-hat token // identity matches what the engine produces internally. @@ -168,7 +174,8 @@ export function allocateHats( const forceTokenHats: TokenHat[] = []; const forcedTokenKeys = new Set<string>(); for (const mark of marks) { - const markStart = mark.token.range.start; // line-relative char offset + // line-relative char offset + const markStart = mark.token.range.start; const covering = engineTokens.find( (t) => t.range.start.line === mark.lineIdx && diff --git a/packages/command-visualizer/src/logic/pipeline.ts b/packages/command-visualizer/src/logic/pipeline.ts index dee3a72745..29fdc128b6 100644 --- a/packages/command-visualizer/src/logic/pipeline.ts +++ b/packages/command-visualizer/src/logic/pipeline.ts @@ -11,7 +11,6 @@ // Stage 3 lives in ./build-render-object; its types in ./pipeline-types. import { readFileSync } from "node:fs"; -import { parseFixtureYaml } from "./fixture-yaml"; import type { Theme } from "../data/colors"; import type { CascadeState, Frame } from "../model/types"; import { @@ -21,17 +20,20 @@ import { deriveSelections, parseMarks, } from "./fixture-extract"; - import { fixtureRoot } from "./fixture-root"; -import { buildRenderObject } from "./build-render-object"; +import { parseFixtureYaml } from "./fixture-yaml"; import type { ParsedFixture, PipelineOptions, TokenizedStates, } from "./pipeline-types"; -export { buildRenderObject }; -export type { ParsedFixture, PipelineOptions, TokenizedStates }; +export { buildRenderObject } from "./build-render-object"; +export type { + ParsedFixture, + PipelineOptions, + TokenizedStates, +} from "./pipeline-types"; // Resolved lazily: fixtureRoot() throws when no cursorless checkout exists, // which must not fire at module load in serverless (the API path reads @@ -147,9 +149,12 @@ export function fixtureToCascade( fixtureRel: string, opts: PipelineOptions = {}, ): CascadeState { - const parsed = parseFixture(src, fixtureRel, opts); // 1. get what to render - const tokenized = tokenizeStates(parsed, opts); // 2. tokenize each step - return buildRenderObject(parsed, tokenized, opts); // 3. generate render object + // 1. get what to render + const parsed = parseFixture(src, fixtureRel, opts); + // 2. tokenize each step + const tokenized = tokenizeStates(parsed, opts); + // 3. generate render object + return buildRenderObject(parsed, tokenized, opts); } /** Convenience: load a recorded fixture by relative path. */ diff --git a/packages/command-visualizer/src/logic/tokenize.ts b/packages/command-visualizer/src/logic/tokenize.ts index f77c76bce6..6bf6f77f2d 100644 --- a/packages/command-visualizer/src/logic/tokenize.ts +++ b/packages/command-visualizer/src/logic/tokenize.ts @@ -37,7 +37,7 @@ export function tokenizeLine(text: string): Token[] { const tokens: Token[] = []; // Fresh RegExp per call: GRAPHEME_SPLIT_REGEX is a shared /gu instance whose // lastIndex must not leak across tokenizeLine calls. - const re = new RegExp(GRAPHEME_SPLIT_REGEX); + const re = new RegExp(GRAPHEME_SPLIT_REGEX, "u"); let m: RegExpExecArray | null; let last = 0; @@ -47,9 +47,9 @@ export function tokenizeLine(text: string): Token[] { // char is emitted as its own token. In practice gaps are whitespace. let i = from; while (i < to) { - if (/\s/.test(text[i])) { + if (/\s/u.test(text[i])) { let j = i; - while (j < to && /\s/.test(text[j])) { + while (j < to && /\s/u.test(text[j])) { j++; } tokens.push({ text: text.slice(i, j), range: { start: i, end: j } }); @@ -61,7 +61,7 @@ export function tokenizeLine(text: string): Token[] { } }; - while ((m = re.exec(text)) !== null) { + while ((m = re.exec(text)) != null) { if (m.index > last) { emitGapAsTokens(last, m.index); } @@ -70,9 +70,10 @@ export function tokenizeLine(text: string): Token[] { range: { start: m.index, end: m.index + m[0].length }, }); last = m.index + m[0].length; + // guard zero-width if (m[0].length === 0) { re.lastIndex++; - } // guard zero-width + } } if (last < text.length) { emitGapAsTokens(last, text.length); diff --git a/packages/command-visualizer/src/model/columns.ts b/packages/command-visualizer/src/model/columns.ts index 5ca04492dc..e6b198da2d 100644 --- a/packages/command-visualizer/src/model/columns.ts +++ b/packages/command-visualizer/src/model/columns.ts @@ -22,7 +22,8 @@ export interface InputHat { export interface Token { text: string; - range: { start: number; end: number }; // UTF-16 offsets within the line + // UTF-16 offsets within the line + range: { start: number; end: number }; hat?: InputHat | null; } @@ -48,24 +49,42 @@ export interface Column { // East_Asian_Width Wide (W) + Fullwidth (F) ranges. Covers CJK, Hangul, // fullwidth forms, kana, common emoji presentation. Sufficient for the // column-model torture test; extend the table if a fixture needs more. +// oxlint-disable unicorn/numeric-separators-style const WIDE_RANGES: ReadonlyArray<readonly [number, number]> = [ - [0x1100, 0x115f], // Hangul Jamo - [0x2329, 0x232a], // angle brackets - [0x2e80, 0x303e], // CJK radicals .. symbols - [0x3041, 0x33ff], // Hiragana, Katakana, CJK symbols/punct - [0x3400, 0x4dbf], // CJK Ext A - [0x4e00, 0x9fff], // CJK Unified - [0xa000, 0xa4cf], // Yi - [0xac00, 0xd7a3], // Hangul Syllables - [0xf900, 0xfaff], // CJK Compatibility Ideographs - [0xfe10, 0xfe19], // vertical forms - [0xfe30, 0xfe6f], // CJK compat / small forms - [0xff00, 0xff60], // Fullwidth Forms - [0xffe0, 0xffe6], // Fullwidth signs - [0x1f300, 0x1f64f], // emoji + emoticons - [0x1f900, 0x1f9ff], // supplemental symbols/pictographs - [0x20000, 0x3fffd], // CJK Ext B+ (SIP/TIP) + // Hangul Jamo + [0x1100, 0x115f], + // angle brackets + [0x2329, 0x232a], + // CJK radicals .. symbols + [0x2e80, 0x303e], + // Hiragana, Katakana, CJK symbols/punct + [0x3041, 0x33ff], + // CJK Ext A + [0x3400, 0x4dbf], + // CJK Unified + [0x4e00, 0x9fff], + // Yi + [0xa000, 0xa4cf], + // Hangul Syllables + [0xac00, 0xd7a3], + // CJK Compatibility Ideographs + [0xf900, 0xfaff], + // vertical forms + [0xfe10, 0xfe19], + // CJK compat / small forms + [0xfe30, 0xfe6f], + // Fullwidth Forms + [0xff00, 0xff60], + // Fullwidth signs + [0xffe0, 0xffe6], + // emoji + emoticons + [0x1f300, 0x1f64f], + // supplemental symbols/pictographs + [0x1f900, 0x1f9ff], + // CJK Ext B+ (SIP/TIP) + [0x20000, 0x3fffd], ]; +// oxlint-enable unicorn/numeric-separators-style function isWideCodePoint(cp: number): boolean { for (const [lo, hi] of WIDE_RANGES) { @@ -97,10 +116,10 @@ interface GraphemeUnit { /** Split a token's text into grapheme clusters, tracking each one's char offset. */ export function splitGraphemes(text: string): GraphemeUnit[] { const out: GraphemeUnit[] = []; - const re = new RegExp(GRAPHEME_SPLIT_REGEX); + const re = new RegExp(GRAPHEME_SPLIT_REGEX, "u"); let m: RegExpExecArray | null; let lastIndex = 0; - while ((m = re.exec(text)) !== null) { + while ((m = re.exec(text)) != null) { // Emit any chars the regex skipped (e.g. whitespace) as single cells so // every column of every line is owned by exactly one cell. if (m.index > lastIndex) { @@ -110,9 +129,10 @@ export function splitGraphemes(text: string): GraphemeUnit[] { } out.push({ text: m[0], offset: m.index }); lastIndex = m.index + m[0].length; + // guard zero-width if (m[0].length === 0) { re.lastIndex++; - } // guard zero-width + } } for (let i = lastIndex; i < text.length; i++) { out.push({ text: text[i], offset: i }); @@ -133,7 +153,8 @@ export function expandColumns(line: Line, tabSize: number): Column[] { const hat = token.hat ?? undefined; const anchorIdx = hat?.anchorGrapheme ?? 0; - graphemes.forEach((g, gi) => { + for (let gi = 0; gi < graphemes.length; gi++) { + const g = graphemes[gi]; const charIndex = token.range.start + g.offset; // Flow-narrowing: `anchorHat` is the token's hat only on the anchor // grapheme, else undefined. Deriving it once lets the compiler narrow @@ -153,7 +174,7 @@ export function expandColumns(line: Line, tabSize: number): Column[] { hatShape: anchorHat?.shape, }); col += advance; - return; + continue; } const w = graphemeWidth(g.text); @@ -167,7 +188,7 @@ export function expandColumns(line: Line, tabSize: number): Column[] { hatShape: anchorHat?.shape, }); col += w; - }); + } } return cols; diff --git a/packages/command-visualizer/src/model/overlays.ts b/packages/command-visualizer/src/model/overlays.ts index eebcc269f2..5381db6c3e 100644 --- a/packages/command-visualizer/src/model/overlays.ts +++ b/packages/command-visualizer/src/model/overlays.ts @@ -3,11 +3,13 @@ // per cell (selection < highlight < flash, last wins). Also resolves full-width // line-range bands. -import { type Column, expandColumns } from "./columns"; -import type { Decoration, Frame, OverlayRole } from "./types"; +import type { Range } from "@cursorless/lib-common"; +import { isLineRange } from "@cursorless/lib-common"; import type { OverlayStyleName } from "../data/decorations"; import { overlayPrecedence } from "../data/decorations"; -import { type Range, isLineRange } from "@cursorless/lib-common"; +import type { Column } from "./columns"; +import { expandColumns } from "./columns"; +import type { Decoration, Frame, OverlayRole } from "./types"; // Role sub-rank, used to break style-precedence ties: a REAL ide.flash outranks // a DERIVED that/source overlay on the @@ -23,7 +25,8 @@ function roleRank(role: OverlayRole | "selection"): number { if (role === "highlight") { return 1; } - return 2; // that | source | scope:* (derived) + // that | source | scope:* (derived) + return 2; } export interface CellOverlay { @@ -90,7 +93,8 @@ function resolveLine( const rank = overlayPrecedence(style) * 10 + roleRank(role); const prev = winRank.get(col); if (prev === undefined || rank >= prev) { - cell.winner = style; // last-wins at equal rank + // last-wins at equal rank + cell.winner = style; winRank.set(col, rank); } }; @@ -116,7 +120,8 @@ function resolveLine( for (const dec of decorations) { if (isLineRange(dec.range)) { if (lineIdx >= dec.range.start && lineIdx <= dec.range.end) { - lineFlash = dec.style; // last line decoration wins + // last line decoration wins + lineFlash = dec.style; } continue; } diff --git a/packages/command-visualizer/src/model/types.ts b/packages/command-visualizer/src/model/types.ts index 176a7f3993..695550dd25 100644 --- a/packages/command-visualizer/src/model/types.ts +++ b/packages/command-visualizer/src/model/types.ts @@ -10,10 +10,10 @@ // warrant promotion into a shared package; they are isolated here to make that // call easy. -import type { Theme } from "../data/colors"; -import type { Line } from "./columns"; import type { Position, Range, GeneralizedRange } from "@cursorless/lib-common"; +import type { Theme } from "../data/colors"; import type { OverlayStyleName } from "../data/decorations"; +import type { Line } from "./columns"; export type FrameRole = "before" | "during" | "after"; diff --git a/packages/command-visualizer/src/render-command.ts b/packages/command-visualizer/src/render-command.ts index fe77e5e8e4..49069978ac 100644 --- a/packages/command-visualizer/src/render-command.ts +++ b/packages/command-visualizer/src/render-command.ts @@ -11,23 +11,20 @@ // BOTH scopes. The folder rule (logic/ ⊥ render/) is preserved: neither folder // imports the other; only this root module and index.ts join them. +import type { PipelineOptions } from "./logic/pipeline"; import { parseFixture, tokenizeStates, buildRenderObject, - type PipelineOptions, } from "./logic/pipeline"; -import { - serializeCascade, - type CascadeRenderOptions, -} from "./render/serialize-cascade"; -import { wrapCascadeSvg, type SvgWrapOptions } from "./render/svg-wrap"; +import type { CascadeRenderOptions } from "./render/serialize-cascade"; +import { serializeCascade } from "./render/serialize-cascade"; +import type { SvgWrapOptions } from "./render/svg-wrap"; +import { wrapCascadeSvg } from "./render/svg-wrap"; /** Options for the end-to-end orchestrator: pipeline + render + SVG-wrap knobs. */ export interface RenderCommandOptions - extends PipelineOptions, - SvgWrapOptions, - CascadeRenderOptions {} + extends PipelineOptions, SvgWrapOptions, CascadeRenderOptions {} /** * Render a single recorded fixture to a standalone animated SVG string. @@ -45,11 +42,15 @@ export function renderCommand( fixtureRel: string, opts: RenderCommandOptions = {}, ): string { - const parsed = parseFixture(src, fixtureRel, opts); // 1. get what to render - const tokenized = tokenizeStates(parsed, opts); // 2. tokenize each step - const cascade = buildRenderObject(parsed, tokenized, opts); // 3. render object + // 1. get what to render + const parsed = parseFixture(src, fixtureRel, opts); + // 2. tokenize each step + const tokenized = tokenizeStates(parsed, opts); + // 3. render object + const cascade = buildRenderObject(parsed, tokenized, opts); const inner = serializeCascade(cascade, { lineNumbers: opts.lineNumbers }); + // 4. render from object return wrapCascadeSvg(cascade, inner, undefined, { flashPulseMs: opts.flashPulseMs, - }); // 4. render from object + }); } diff --git a/packages/command-visualizer/src/render/css-cascade-flash.ts b/packages/command-visualizer/src/render/css-cascade-flash.ts index b49a03aaea..a9a564b02a 100644 --- a/packages/command-visualizer/src/render/css-cascade-flash.ts +++ b/packages/command-visualizer/src/render/css-cascade-flash.ts @@ -2,14 +2,11 @@ // (the flash TIMING section) so the main module stays under the 250-line limit. // render/ → render/ import only; behavior unchanged. -import { - DECORATION_HEX, - FLASH_PULSE_MS, - type OverlayStyleName, -} from "../data/decorations"; -import type { Frame } from "../model/types"; +import type { OverlayStyleName } from "../data/decorations"; +import { DECORATION_HEX, FLASH_PULSE_MS } from "../data/decorations"; import type { Timeline } from "../model/timeline"; -import { pct } from "./css-cascade"; +import type { Frame } from "../model/types"; +import { pct } from "./css-utils"; // DURING beats — flash TIMING. A flash is a TRANSIENT beat *within* one // frame's timeline slot, not a static band. Two opposite directions: @@ -46,7 +43,8 @@ const ADD_FLASH_STYLES = ["justAdded"] as const; // below. A short fade ramp (FADE_FRAC of the pulse) softens each edge but the // held-full-color span is exactly the pulse, which is what verify:flash-timing // measures. Result: the pulse is ~100ms for ANY N (no slot scaling). -const FADE_FRAC = 0.4; // soft-edge ramp length as a fraction of the pulse window +// soft-edge ramp length as a fraction of the pulse window +const FADE_FRAC = 0.4; // Reference-class pre-edit flashes (Bring sources/destinations etc.) — they // sequence BEFORE deletion flashes inside a DURING window (real cursorless @@ -57,15 +55,17 @@ const REFERENCE_FLASH_STYLES = [ "pendingModification1", ] as const; +const pct100 = (x: number) => pct(Math.max(0, Math.min(100, x * 100))); + export function flashFadeKeyframes( frames: readonly Frame[], tl: Timeline, pulseMs: number = FLASH_PULSE_MS, ): string { const out: string[] = []; - const pct100 = (x: number) => pct(Math.max(0, Math.min(100, x * 100))); - frames.forEach((frame, k) => { + for (let k = 0; k < frames.length; k++) { + const frame = frames[k]; const lo = tl.startFrac[k]; const hi = tl.endFrac[k]; @@ -85,16 +85,16 @@ export function flashFadeKeyframes( const refWin: [number, number] = [lo, mid]; const delWin: [number, number] = [hasRef ? mid : lo, hi]; const emit = (style: string, w: [number, number], holdOn: boolean) => { + const ending = holdOn + ? ` 100% { background-color: ${DECORATION_HEX[style as keyof typeof DECORATION_HEX]}; }\n` + : ` ${pct100(w[1] + 0.0001)}% { background-color: transparent; }\n 100% { background-color: transparent; }\n`; out.push( - `@keyframes flashfade-${style}-s${k} {\n` + - ` 0% { background-color: transparent; }\n` + - ` ${pct100(w[0])}% { background-color: transparent; }\n` + - ` ${pct100(w[0] + 0.0001)}% { background-color: ${DECORATION_HEX[style as keyof typeof DECORATION_HEX]}; }\n` + - ` ${pct100(w[1])}% { background-color: ${DECORATION_HEX[style as keyof typeof DECORATION_HEX]}; }\n` + - (holdOn - ? ` 100% { background-color: ${DECORATION_HEX[style as keyof typeof DECORATION_HEX]}; }\n` - : ` ${pct100(w[1] + 0.0001)}% { background-color: transparent; }\n 100% { background-color: transparent; }\n`) + - `}`, + `@keyframes flashfade-${style}-s${k} { + 0% { background-color: transparent; } + ${pct100(w[0])}% { background-color: transparent; } + ${pct100(w[0] + 0.0001)}% { background-color: ${DECORATION_HEX[style as keyof typeof DECORATION_HEX]}; } + ${pct100(w[1])}% { background-color: ${DECORATION_HEX[style as keyof typeof DECORATION_HEX]}; } +${ending}}`, ); }; for (const st of REFERENCE_FLASH_STYLES) { @@ -103,8 +103,9 @@ export function flashFadeKeyframes( } } if (styles.has("pendingDelete")) { + // held to the edit emit("pendingDelete", delWin, true); - } // held to the edit + } } else { // ADD pulse at the frame's slot start (post-edit justAdded). const durFrac = pulseMs / tl.totalMs; @@ -122,14 +123,15 @@ export function flashFadeKeyframes( ); } } - }); + } return out.join("\n"); } export function flashFadeRules(frames: readonly Frame[]): string { const rules: string[] = []; - frames.forEach((frame, k) => { + for (let k = 0; k < frames.length; k++) { + const frame = frames[k]; if (frame.role === "during") { const styles = new Set(frame.decorations.map((d) => d.style)); for (const st of [...REFERENCE_FLASH_STYLES, "pendingDelete"]) { @@ -137,22 +139,22 @@ export function flashFadeRules(frames: readonly Frame[]): string { continue; } rules.push( - `.cl-cascade .frame[data-frame="${k}"] .ch[data-flash="${st}"] {\n` + - ` background-color: transparent;\n` + - ` animation: flashfade-${st}-s${k} var(--dur, 2s) linear 1 forwards paused;\n` + - `}`, + `.cl-cascade .frame[data-frame="${k}"] .ch[data-flash="${st}"] { + background-color: transparent; + animation: flashfade-${st}-s${k} var(--dur, 2s) linear 1 forwards paused; +}`, ); } } else { for (const st of ADD_FLASH_STYLES) { rules.push( - `.cl-cascade .frame[data-frame="${k}"] .ch[data-flash="${st}"] {\n` + - ` background-color: ${DECORATION_HEX[st]};\n` + - ` animation: flashfade-${st}-s${k} var(--dur, 2s) linear 1 forwards paused;\n` + - `}`, + `.cl-cascade .frame[data-frame="${k}"] .ch[data-flash="${st}"] { + background-color: ${DECORATION_HEX[st]}; + animation: flashfade-${st}-s${k} var(--dur, 2s) linear 1 forwards paused; +}`, ); } } - }); + } return rules.join("\n"); } diff --git a/packages/command-visualizer/src/render/css-cascade.ts b/packages/command-visualizer/src/render/css-cascade.ts index b0d573e638..55bbc4a61e 100644 --- a/packages/command-visualizer/src/render/css-cascade.ts +++ b/packages/command-visualizer/src/render/css-cascade.ts @@ -2,12 +2,18 @@ // Generated from the single-sourced decoration hexes so the // band colors never drift. Theme-INVARIANT (background-only translucent hexes). -import { DECORATION_HEX, ALL_DECORATION_STYLES } from "../data/decorations"; -import { FLASH_STYLES, HIGHLIGHT_STYLES } from "../data/decorations"; -import { FLASH_PULSE_MS } from "../data/decorations"; +import { + DECORATION_HEX, + ALL_DECORATION_STYLES, + FLASH_STYLES, + HIGHLIGHT_STYLES, + FLASH_PULSE_MS, +} from "../data/decorations"; +import type { Timeline } from "../model/timeline"; +import { timelineOf } from "../model/timeline"; import type { Frame } from "../model/types"; -import { timelineOf, type Timeline } from "../model/timeline"; import { flashFadeKeyframes, flashFadeRules } from "./css-cascade-flash"; +import { pct } from "./css-utils"; // §3.2 — char-range bands on the per-char grid (one bg attr per .ch). // The STATIC path (single-frame PNG renders, animate=false): the band is just a @@ -22,11 +28,6 @@ function charBandRules(): string { return [...flash, ...hl].join("\n"); } -// Shared %-formatter — used here (frameKeyframes) and by the extracted -// flash-fade module. Exported so css-cascade-flash.ts reuses the exact impl -// (render/ → render/ import; no duplication). -export const pct = (x: number): string => x.toFixed(3); - // The flash TIMING section (DURING beats: delete, insert, reference pre-edit // flashes) lives in ./css-cascade-flash — imported above. See that module's // header for the full rationale. diff --git a/packages/command-visualizer/src/render/css.ts b/packages/command-visualizer/src/render/css.ts index 66d4d809d5..4bde6914de 100644 --- a/packages/command-visualizer/src/render/css.ts +++ b/packages/command-visualizer/src/render/css.ts @@ -25,7 +25,7 @@ function shapeAdjustmentRules(): string { // percent → em/100 parts.push(`--shape-voffset: ${adj.verticalOffset / 100}em;`); } - if (parts.length) { + if (parts.length > 0) { lines.push( `.ch--anchor[data-hat-shape="${shape}"] .hat { ${parts.join(" ")} }`, ); diff --git a/packages/command-visualizer/src/render/html.ts b/packages/command-visualizer/src/render/html.ts index 0d0d008874..fb1bb6b5fd 100644 --- a/packages/command-visualizer/src/render/html.ts +++ b/packages/command-visualizer/src/render/html.ts @@ -18,11 +18,11 @@ import type { CascadeState } from "../model/types"; */ export function esc(s: string): string { return s - .replace(/&/g, "&") - .replace(/</g, "<") - .replace(/>/g, ">") - .replace(/"/g, """) - .replace(/'/g, "'"); + .replaceAll("&", "&") + .replaceAll("<", "<") + .replaceAll(">", ">") + .replaceAll('"', """) + .replaceAll("'", "'"); } /** Editor-surface page background for a theme (delivered SVG / standalone doc). */ diff --git a/packages/command-visualizer/src/render/jumbotron-css-keyframes.ts b/packages/command-visualizer/src/render/jumbotron-css-keyframes.ts index 02de578fea..5c10289aa6 100644 --- a/packages/command-visualizer/src/render/jumbotron-css-keyframes.ts +++ b/packages/command-visualizer/src/render/jumbotron-css-keyframes.ts @@ -2,8 +2,8 @@ // of jumbotronCss. Extracted verbatim from jumbotron.ts so every jumbotron CSS // module stays under the 250-line limit. render/ → render/ import only. -import type { CascadeState } from "../model/types"; import { frameDurMs, timelineOf } from "../model/timeline"; +import type { CascadeState } from "../model/types"; import { NL, frameCommands, @@ -60,7 +60,7 @@ export function litKeyframes( }; let litKf = ""; - if (n >= 2 && commands.length >= 1) { + if (n >= 2 && commands.length > 0) { const parts: string[] = []; // Dot phase levels (dotwin-{k}), one per step: disabled(0) -> @@ -68,7 +68,7 @@ export function litKeyframes( // (dotissued-{k}) marks the during phase distinctly, so level 2 reads // full+ring and level 3 full without. const L1 = 0.45; - cmdFrames.forEach((k) => { + for (const k of cmdFrames) { const iniLo = msPct(tl.startMs[k]); const durFrame = state.frames[k + 1]?.role === "during" ? k + 1 : null; const durLo = @@ -93,39 +93,26 @@ export function litKeyframes( ] : [` 100% { opacity: 1; }`]), ]; - parts.push(`@keyframes dotwin-${k} {` + NL + kf.join(NL) + NL + `}`); - }); + parts.push(`@keyframes dotwin-${k} {${NL}${kf.join(NL)}${NL}}`); + } // ISSUED dot ring — white border across the step's during window. - cmdFrames.forEach((k) => { + for (const k of cmdFrames) { if (state.frames[k + 1]?.role !== "during") { - return; + continue; } const [wLo, wHi] = issueWindow(k); parts.push( - `@keyframes dotissued-${k} {` + - NL + - ` 0% { border-color: transparent; }` + - NL + - ` ${pctc(wLo)} { border-color: transparent; }` + - NL + - ` ${pctc(wLo + 0.001)} { border-color: #ffffff; }` + - NL + - ` ${pctc(wHi)} { border-color: #ffffff; }` + - NL + - ` ${pctc(wHi + 0.001)} { border-color: transparent; }` + - NL + - ` 100% { border-color: transparent; }` + - NL + - `}`, + `@keyframes dotissued-${k} {${NL} 0% { border-color: transparent; }${NL} ${pctc(wLo)} { border-color: transparent; }${NL} ${pctc(wLo + 0.001)} { border-color: #ffffff; }${NL} ${pctc(wHi)} { border-color: #ffffff; }${NL} ${pctc(wHi + 0.001)} { border-color: transparent; }${NL} 100% { border-color: transparent; }${NL}}`, ); - }); + } // Command pills: entrance into jumbospace (chip 0 rises + fades in), // then the BACKGROUND carries disabled -> active (text color constant). const DIS = "var(--pill-disabled, #333)"; const ACT = "var(--pill-active, #1f6fd6)"; - cmdFrames.forEach((k, i) => { + for (let i = 0; i < cmdFrames.length; i++) { + const k = cmdFrames[i]; const enterAt = msPct(tl.startMs[k]) + msPct(frameDurMs(state.frames[k])) * ENTER_FRAC; const [litStart] = issueWindow(k); @@ -192,8 +179,8 @@ export function litKeyframes( ` 100% { opacity: 1; transform: translateY(0); background-color: ${DIS}; }`, ); } - parts.push(`@keyframes cmdlit-${i} {` + NL + kfParts.join(NL) + NL + `}`); - }); + parts.push(`@keyframes cmdlit-${i} {${NL}${kfParts.join(NL)}${NL}}`); + } litKf = parts.join(NL) + NL; } diff --git a/packages/command-visualizer/src/render/jumbotron-css.ts b/packages/command-visualizer/src/render/jumbotron-css.ts index e1a79a1f1a..f75e1ced90 100644 --- a/packages/command-visualizer/src/render/jumbotron-css.ts +++ b/packages/command-visualizer/src/render/jumbotron-css.ts @@ -6,16 +6,16 @@ // ./jumbotron-css-keyframes; this module assembles base + themed + those // keyframes + the carousel track. render/ → render/ import only. -import type { CascadeState } from "../model/types"; import { MS_PER_STATE } from "../data/decorations"; import { timelineOf } from "../model/timeline"; +import type { CascadeState } from "../model/types"; +import { litKeyframes } from "./jumbotron-css-keyframes"; import { NL, frameCommands, timelinePct, commandFrameIndices, } from "./jumbotron-shared"; -import { litKeyframes } from "./jumbotron-css-keyframes"; /** Base layout + component CSS (carousel, pill, metadata, dots). */ function baseCss(n: number): string { @@ -141,25 +141,16 @@ function carouselTrack(state: CascadeState, n: number): string { const pos = (i: number) => `transform: translateX(-${(i * step).toFixed(4)}%);`; const kf: string[] = [` 0% { ${pos(0)} }`]; - cmdFrames.slice(1).forEach((k, j) => { + const sliced = cmdFrames.slice(1); + for (let j = 0; j < sliced.length; j++) { + const k = sliced[j]; const at = msPct(tl.startMs[k]) + msPct(LIT_HOLD_MS); kf.push(` ${pctc(at)} { ${pos(j)} }`); kf.push(` ${pctc(at + msPct(SLIDE_MS))} { ${pos(j + 1)} }`); - }); + } kf.push(` 100% { ${pos(cmdFrames.length - 1)} }`); - return ( - "@keyframes cmdtrack {" + - NL + - kf.join(NL) + - NL + - "}" + - NL + - ".cl-cmd-track { animation: cmdtrack var(--dur, " + - String(n * MS_PER_STATE) + - "ms) cubic-bezier(0.4, 0, 0.2, 1) 1 forwards paused; }" + - NL - ); + return `@keyframes cmdtrack {${NL}${kf.join(NL)}${NL}}${NL}.cl-cmd-track { animation: cmdtrack var(--dur, ${n * MS_PER_STATE}ms) cubic-bezier(0.4, 0, 0.2, 1) 1 forwards paused; }${NL}`; } export function jumbotronCss( diff --git a/packages/command-visualizer/src/render/jumbotron-shared.ts b/packages/command-visualizer/src/render/jumbotron-shared.ts index 0d390624ea..e8a7240ccc 100644 --- a/packages/command-visualizer/src/render/jumbotron-shared.ts +++ b/packages/command-visualizer/src/render/jumbotron-shared.ts @@ -3,10 +3,10 @@ // dependency-free leaf module so the markup and CSS modules never import each // other (avoids a cycle) and never duplicate these. render/ → render/ only. -import type { CascadeState } from "../model/types"; import type { Timeline } from "../model/timeline"; +import type { CascadeState } from "../model/types"; -export const NL = String.fromCharCode(10); +export const NL = String.fromCodePoint(10); /** Commands carried by the frames, in order. */ export function frameCommands(state: CascadeState): string[] { @@ -15,6 +15,10 @@ export function frameCommands(state: CascadeState): string[] { .filter((c): c is string => c != null && c !== ""); } +function pctc(x: number): string { + return `${Math.max(0, Math.min(100, x)).toFixed(3)}%`; +} + /** Timeline-relative %-formatters shared by the CSS keyframe + carousel builders. * `msPct` maps absolute ms onto 0-100 of the total; `pctc` clamps+formats. */ export function timelinePct(tl: Timeline): { @@ -23,17 +27,17 @@ export function timelinePct(tl: Timeline): { } { const durMs = tl.totalMs; const msPct = (ms: number) => (ms / durMs) * 100; - const pctc = (x: number) => `${Math.max(0, Math.min(100, x)).toFixed(3)}%`; return { msPct, pctc }; } /** Indices of frames that carry a (non-empty) command — the command-pill slots. */ export function commandFrameIndices(state: CascadeState): number[] { const cmdFrames: number[] = []; - state.frames.forEach((f, i) => { + for (let i = 0; i < state.frames.length; i++) { + const f = state.frames[i]; if (f.command != null && f.command !== "") { cmdFrames.push(i); } - }); + } return cmdFrames; } diff --git a/packages/command-visualizer/src/render/jumbotron.ts b/packages/command-visualizer/src/render/jumbotron.ts index 8f4a824df6..758e96f8e2 100644 --- a/packages/command-visualizer/src/render/jumbotron.ts +++ b/packages/command-visualizer/src/render/jumbotron.ts @@ -22,8 +22,8 @@ // The CSS half (jumbotronCss) lives in ./jumbotron-css (+ -keyframes); it is // re-exported below so the public surface (index.ts) is unchanged. -import type { CascadeState } from "../model/types"; import { timelineOf } from "../model/timeline"; +import type { CascadeState } from "../model/types"; import { esc } from "./html"; import { NL, frameCommands } from "./jumbotron-shared"; @@ -40,12 +40,15 @@ function hasClipboard(state: CascadeState): boolean { /** Command bar — single command sits static; chains carousel (cmdtrack). */ const PILL_FONT_MAX = 28; const PILL_FONT_MIN = 14; -const PILL_PAD_X = 28; // matches .cl-cmd-pill horizontal padding -const MONO_CH_EM = 0.78; // matches svg-wrap CH_EM (SVG-image fallback mono) +// matches .cl-cmd-pill horizontal padding +const PILL_PAD_X = 28; +// matches svg-wrap CH_EM (SVG-image fallback mono) +const MONO_CH_EM = 0.78; /** Largest font (<= 28px) at which the quoted text fits the bar width. */ function pillFontPx(text: string, barWidthPx: number): number { - const chars = text.length + 2; // + quotes + // + quotes + const chars = text.length + 2; const avail = barWidthPx * 0.96 - PILL_PAD_X * 2; const fit = Math.floor(avail / (chars * MONO_CH_EM)); return Math.max(PILL_FONT_MIN, Math.min(PILL_FONT_MAX, fit)); @@ -90,7 +93,6 @@ function metadataBlock(state: CascadeState): string { if (!hasClipboard(state)) { return ""; } - const n = Math.max(1, state.frames.length); const slots = state.frames .map( (f, i) => @@ -142,17 +144,5 @@ export function serializeJumbotron( inner: string, opts: { barWidthPx?: number } = {}, ): string { - return ( - `<div class="visualizer-wrapper visualizer-jumbotron" data-theme="${state.theme}">` + - NL + - `<div class="jumbotron-container">${NL}${inner}${NL}</div>` + - NL + - commandBar(state, opts.barWidthPx) + - NL + - metadataBlock(state) + - NL + - dots(state) + - NL + - `</div>` - ); + return `<div class="visualizer-wrapper visualizer-jumbotron" data-theme="${state.theme}">${NL}<div class="jumbotron-container">${NL}${inner}${NL}</div>${NL}${commandBar(state, opts.barWidthPx)}${NL}${metadataBlock(state)}${NL}${dots(state)}${NL}</div>`; } diff --git a/packages/command-visualizer/src/render/serialize-cascade.test.ts b/packages/command-visualizer/src/render/serialize-cascade.test.ts index 584502ef2f..e880d246d5 100644 --- a/packages/command-visualizer/src/render/serialize-cascade.test.ts +++ b/packages/command-visualizer/src/render/serialize-cascade.test.ts @@ -24,9 +24,9 @@ function stateOf(...lineSets: string[][]): CascadeState { /** All line-number cell contents, in document order. */ function lineNoTexts(html: string): string[] { - return [...html.matchAll(/<span class="cl-lineno"[^>]*>([^<]*)<\/span>/g)].map( - (m) => m[1], - ); + return [ + ...html.matchAll(/<span class="cl-lineno"[^>]*>([^<]*)<\/span>/gu), + ].map((m) => m[1]); } suite("command-visualizer/serialize-cascade line numbers", () => { @@ -41,12 +41,12 @@ suite("command-visualizer/serialize-cascade line numbers", () => { "root must carry data-line-numbers when on", ); // Digit-count var reflects the largest line number (3 lines → 1 digit). - assert.match(html, /--gutter-digits:1;/); + assert.match(html, /--gutter-digits:1;/u); // (b) exactly one .cl-lineno per line, numbered 1..N (1-based). assert.deepEqual(lineNoTexts(html), ["1", "2", "3"]); // One .cl-line per rendered line, so counts line up. - assert.equal((html.match(/class="cl-line"/g) ?? []).length, 3); + assert.equal((html.match(/class="cl-line"/gu) ?? []).length, 3); }); test("off: no gutter attribute and no .cl-lineno", () => { @@ -65,11 +65,9 @@ suite("command-visualizer/serialize-cascade line numbers", () => { test("digit width scales to the widest line number", () => { // A ten-line document → largest line number "10" → 2 digits. - const tenState = stateOf( - Array.from({ length: 10 }, (_, i) => `line${i}`), - ); + const tenState = stateOf(Array.from({ length: 10 }, (_, i) => `line${i}`)); const html = serializeCascade(tenState, { lineNumbers: true }); - assert.match(html, /--gutter-digits:2;/); + assert.match(html, /--gutter-digits:2;/u); assert.deepEqual(lineNoTexts(html), [ "1", "2", @@ -89,6 +87,6 @@ suite("command-visualizer/serialize-cascade line numbers", () => { const html = serializeCascade(multi, { lineNumbers: true }); // Two frames × two lines = four line-number cells, numbered per frame. assert.deepEqual(lineNoTexts(html), ["1", "2", "1", "2"]); - assert.equal((html.match(/class="frame"/g) ?? []).length, 2); + assert.equal((html.match(/class="frame"/gu) ?? []).length, 2); }); }); diff --git a/packages/command-visualizer/src/render/serialize-cascade.ts b/packages/command-visualizer/src/render/serialize-cascade.ts index 112ef96611..f0250462ea 100644 --- a/packages/command-visualizer/src/render/serialize-cascade.ts +++ b/packages/command-visualizer/src/render/serialize-cascade.ts @@ -3,17 +3,18 @@ // per-frame `@keyframes f{k}` opacity timeline, and the decoration overlay layer // (data-flash / data-hl / data-line-flash) resolved single-winner per cell. -import { type Column, expandColumns, lineWidth } from "../model/columns"; +import { HIGHLIGHT_STYLES, MS_PER_STATE } from "../data/decorations"; +import type { Column } from "../model/columns"; +import { expandColumns, lineWidth } from "../model/columns"; +import type { CellOverlay, LineOverlay } from "../model/overlays"; +import { resolveFrameOverlays } from "../model/overlays"; +import { timelineOf } from "../model/timeline"; +import type { CascadeState, Frame } from "../model/types"; import { styleSheet } from "./css"; import { cascadeStyleSheet, cascadeThemeBridge } from "./css-cascade"; +import { captionHtml, esc, themeBackground } from "./html"; import { jumbotronCss, serializeJumbotron } from "./jumbotron"; -import type { CellOverlay } from "../model/overlays"; import { symbolSheet } from "./symbols"; -import type { CascadeState, Frame } from "../model/types"; -import { resolveFrameOverlays, type LineOverlay } from "../model/overlays"; -import { HIGHLIGHT_STYLES, MS_PER_STATE } from "../data/decorations"; -import { timelineOf } from "../model/timeline"; -import { captionHtml, esc, themeBackground } from "./html"; function charToCol(cols: Column[], charIndex: number): number { for (const c of cols) { @@ -39,12 +40,12 @@ function overlayAttr(winner: string | null): string { function emitSpan(c: Column, cell: CellOverlay | undefined): string { const classes = c.isAnchor ? "ch ch--anchor" : "ch"; - const spanAttr = - c.width === 2 - ? ` data-col-span="2"` - : c.width > 2 - ? ` data-col-span="${c.width}"` - : ""; + let spanAttr = ""; + if (c.width === 2) { + spanAttr = ` data-col-span="2"`; + } else if (c.width > 2) { + spanAttr = ` data-col-span="${c.width}"`; + } const winner = cell?.winner ?? null; const ovAttr = overlayAttr(winner); const stackAttr = @@ -52,17 +53,13 @@ function emitSpan(c: Column, cell: CellOverlay | undefined): string { ? ` data-flash-stack="${cell.stack.join(",")}"` : ""; const hatAttr = c.isAnchor - ? ` data-hat="" data-hat-color="${c.hatColor}" data-hat-shape="${c.hatShape}"` + - ` data-anchor-col="${c.col}"` + ? ` data-hat="" data-hat-color="${c.hatColor}" data-hat-shape="${c.hatShape}" data-anchor-col="${c.col}"` : ""; const hat = c.isAnchor ? `<svg xmlns="http://www.w3.org/2000/svg" class="hat" aria-hidden="true" viewBox="0 0 12 9"><use href="#hat-${c.hatShape}"/></svg>` : ""; const text = c.text === "" ? "" : esc(c.text); - return ( - `<span class="${classes}" data-col="${c.col}"${spanAttr}${ovAttr}${stackAttr}${hatAttr}>` + - `${text}${hat}</span>` - ); + return `<span class="${classes}" data-col="${c.col}"${spanAttr}${ovAttr}${stackAttr}${hatAttr}>${text}${hat}</span>`; } function emitLine( @@ -78,10 +75,10 @@ function emitLine( const caretAtCol = new Map<number, string>(); for (const cur of cursors) { const col = charToCol(cols, cur.character); + const existing = caretAtCol.get(col) ?? ""; caretAtCol.set( col, - (caretAtCol.get(col) ?? "") + - `<span class="caret" data-cursor="" data-cursor-col="${col}"></span>`, + `${existing}<span class="caret" data-cursor="" data-cursor-col="${col}"></span>`, ); } diff --git a/packages/command-visualizer/src/render/serialize.ts b/packages/command-visualizer/src/render/serialize.ts index 08dc43d94d..95d19a5861 100644 --- a/packages/command-visualizer/src/render/serialize.ts +++ b/packages/command-visualizer/src/render/serialize.ts @@ -1,11 +1,12 @@ // Serializer. Pure state JSON → HTML string. No render-time logic. -import type { Theme } from "../data/colors"; -import { type Column, type Line, expandColumns, lineWidth } from "../model/columns"; import type { Position, Range } from "@cursorless/lib-common"; +import type { Theme } from "../data/colors"; +import type { Column, Line } from "../model/columns"; +import { expandColumns, lineWidth } from "../model/columns"; import { styleSheet } from "./css"; -import { symbolSheet } from "./symbols"; import { esc } from "./html"; +import { symbolSheet } from "./symbols"; export interface EditorState { theme: Theme; @@ -52,28 +53,24 @@ function charToCol(cols: Column[], charIndex: number): number { function emitSpan(c: Column, lineIdx: number, selections: Range[]): string { const classes = c.isAnchor ? "ch ch--anchor" : "ch"; - const spanAttr = - c.width === 2 - ? ` data-col-span="2"` - : c.width > 2 - ? ` data-col-span="${c.width}"` - : ""; + let spanAttr = ""; + if (c.width === 2) { + spanAttr = ` data-col-span="2"`; + } else if (c.width > 2) { + spanAttr = ` data-col-span="${c.width}"`; + } const selAttr = inAnySelection(lineIdx, c.charIndex, selections) ? ' data-sel=""' : ""; const hatAttr = c.isAnchor - ? ` data-hat="" data-hat-color="${c.hatColor}" data-hat-shape="${c.hatShape}"` + - ` data-anchor-line="${lineIdx}" data-anchor-col="${c.col}"` + ? ` data-hat="" data-hat-color="${c.hatColor}" data-hat-shape="${c.hatShape}" data-anchor-line="${lineIdx}" data-anchor-col="${c.col}"` : ""; const hat = c.isAnchor ? `<svg xmlns="http://www.w3.org/2000/svg" class="hat" aria-hidden="true" viewBox="0 0 12 9"><use href="#hat-${c.hatShape}"/></svg>` : ""; // For blank tab filler emit a single space so the cell has selectable text. const text = c.text === "" ? "" : esc(c.text); - return ( - `<span class="${classes}" data-col="${c.col}"${spanAttr}${selAttr}${hatAttr}>` + - `${text}${hat}</span>` - ); + return `<span class="${classes}" data-col="${c.col}"${spanAttr}${selAttr}${hatAttr}>${text}${hat}</span>`; } function emitLine( diff --git a/packages/command-visualizer/src/render/svg-wrap.ts b/packages/command-visualizer/src/render/svg-wrap.ts index 315830e1e0..79e7955e5f 100644 --- a/packages/command-visualizer/src/render/svg-wrap.ts +++ b/packages/command-visualizer/src/render/svg-wrap.ts @@ -9,21 +9,25 @@ // the widest expected monospace advance (~0.62em) never clips. import type { CascadeState } from "../model/types"; -import { serializeCascade } from "./serialize-cascade"; -import { jumbotronCss, serializeJumbotron } from "./jumbotron"; import { styleSheet } from "./css"; import { cascadeStyleSheet, cascadeThemeBridge } from "./css-cascade"; import { captionHtml, themeBackground } from "./html"; +import { jumbotronCss, serializeJumbotron } from "./jumbotron"; +import { serializeCascade } from "./serialize-cascade"; -const FONT_PX = 18; // .cl-code font-size (css-cascade.ts) -const LINE_HEIGHT = 1.35; // --code-line-height default +// .cl-code font-size (css-cascade.ts) +const FONT_PX = 18; +// --code-line-height default +const LINE_HEIGHT = 1.35; // Monospace advance estimate. SVG-as-image cannot load web fonts, and the // viewer's fallback monospace varies: JetBrains/Menlo ~0.6em, but Chromium's // SVG-image fallback measures ~0.75em. Size for the widest so nothing clips; // narrow-font viewers just get extra right padding. const CH_EM = 0.78; -const PAD_PX = 24; // body padding in the HTML document version -const CAPTION_PX = 26; // caption line + margin when meta present +// body padding in the HTML document version +const PAD_PX = 24; +// caption line + margin when meta present +const CAPTION_PX = 26; export interface SvgWrapOptions { /** @@ -72,8 +76,10 @@ export function wrapCascadeSvg( (hasCommands ? 70 : 0) + (hasClip ? 56 : 0) + (multiFrame ? 32 : 0); // The cascade box carries its own internal padding (1.2em top, 1.6em // bottom, 1em sides — css-cascade.ts) on top of the outer PAD_PX. - const boxPadX = 2 * FONT_PX; // 1em + 1em - const boxPadY = 2.8 * FONT_PX; // 1.2em + 1.6em + // 1em + 1em + const boxPadX = 2 * FONT_PX; + // 1.2em + 1.6em + const boxPadY = 2.8 * FONT_PX; // Width drivers: the CODE, and the LONGEST COMMAND PILL at full 28px — // the full command text must always be readable, growing the canvas // in preference to shrinking text (truncation is never allowed). From 3a25781b38c193b7d49eb60a8a3570cf5506f529 Mon Sep 17 00:00:00 2001 From: Trillium Smith <trillium@trilliumsmith.com> Date: Mon, 3 Aug 2026 21:43:58 -0700 Subject: [PATCH 51/53] fix: bump talon-tools to v0.11.0 to fix npm EALLOWGIT issue Talon-tools v0.9.0 fails on Node 24 / npm 11+ runners with: npm error EALLOWGIT / Fetching non-root packages from git has been disabled Upgrading to v0.11.0 which no longer uses npm install from git URLs, resolving the pre-commit CI failures on GitHub Actions. --- .pre-commit-config.yaml | 2 +- packages/command-visualizer/src/logic/pipeline.ts | 1 + 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index a57f57b718..050a32c777 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -98,7 +98,7 @@ repos: - id: ruff-format - repo: https://github.com/cursorless-dev/talon-tools - rev: v0.9.0 + rev: v0.11.0 hooks: - id: talon-fmt - id: tree-sitter-fmt diff --git a/packages/command-visualizer/src/logic/pipeline.ts b/packages/command-visualizer/src/logic/pipeline.ts index 29fdc128b6..6998bc6a06 100644 --- a/packages/command-visualizer/src/logic/pipeline.ts +++ b/packages/command-visualizer/src/logic/pipeline.ts @@ -13,6 +13,7 @@ import { readFileSync } from "node:fs"; import type { Theme } from "../data/colors"; import type { CascadeState, Frame } from "../model/types"; +import { buildRenderObject } from "./build-render-object"; import { asArr, asObj, From 5482bc41508e60043de8390de6782b3ea1516524 Mon Sep 17 00:00:00 2001 From: Trillium Smith <trillium@trilliumsmith.com> Date: Mon, 3 Aug 2026 21:46:10 -0700 Subject: [PATCH 52/53] fix: disable hex case/numeric separators rules for Unicode ranges The WIDE_RANGES array contains Unicode code point ranges that are more readable with lowercase hex digits and without numeric separators. Disable these rules for this specific array while keeping them enforced for regular code. --- packages/command-visualizer/src/model/columns.ts | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/packages/command-visualizer/src/model/columns.ts b/packages/command-visualizer/src/model/columns.ts index e6b198da2d..280957d04d 100644 --- a/packages/command-visualizer/src/model/columns.ts +++ b/packages/command-visualizer/src/model/columns.ts @@ -49,7 +49,7 @@ export interface Column { // East_Asian_Width Wide (W) + Fullwidth (F) ranges. Covers CJK, Hangul, // fullwidth forms, kana, common emoji presentation. Sufficient for the // column-model torture test; extend the table if a fixture needs more. -// oxlint-disable unicorn/numeric-separators-style +// oxlint-disable unicorn/numeric-separators-style,unicorn/number-literal-case const WIDE_RANGES: ReadonlyArray<readonly [number, number]> = [ // Hangul Jamo [0x1100, 0x115f], @@ -84,7 +84,7 @@ const WIDE_RANGES: ReadonlyArray<readonly [number, number]> = [ // CJK Ext B+ (SIP/TIP) [0x20000, 0x3fffd], ]; -// oxlint-enable unicorn/numeric-separators-style +// oxlint-enable unicorn/numeric-separators-style,unicorn/number-literal-case function isWideCodePoint(cp: number): boolean { for (const [lo, hi] of WIDE_RANGES) { From e8d75ae992e1db37e481f3a6a1a477ad6d07b945 Mon Sep 17 00:00:00 2001 From: Trillium Smith <trillium@trilliumsmith.com> Date: Mon, 3 Aug 2026 21:46:59 -0700 Subject: [PATCH 53/53] refactor: extract CSS utility functions to resolve circular dependency --- packages/command-visualizer/src/render/css-utils.ts | 2 ++ 1 file changed, 2 insertions(+) create mode 100644 packages/command-visualizer/src/render/css-utils.ts diff --git a/packages/command-visualizer/src/render/css-utils.ts b/packages/command-visualizer/src/render/css-utils.ts new file mode 100644 index 0000000000..bd33c7bcef --- /dev/null +++ b/packages/command-visualizer/src/render/css-utils.ts @@ -0,0 +1,2 @@ +// Shared CSS utility functions +export const pct = (x: number): string => x.toFixed(3);