editor/AGENTS.md

AGENTS.md

System Intent & Context

This repository is a high-performance, rule-based block markdown editor built with Vue 3, TypeScript, and the Lezer parsing framework. Documents are structured as distinct, interactive Blocks rather than a single flat string. A 3-stage parsing pipeline bridges UI state down to ASTs, enabling real-time extraction of pages, references, task state, callouts, and inline decorations.

---

Monorepo Structure

apps/dev/          Development and testing sandbox (Vue 3 + Vite + TypeScript)
packages/editor/   Core headless engine — parsers, rule registries, composables, tests

Component flow:

apps/dev/src/pages/EditorView.vue
  └── apps/dev/src/components/Editor.vue
        └── packages/editor/src/components/Block.vue
              ├── packages/editor/src/composables/useMarkdownDecorations.ts
              │     └── packages/editor/src/lib/markdown-parser.ts
              │           └── packages/editor/src/lib/markdown-rules/engine.ts
              │                 ├── block-classifier.ts
              │                 ├── inline-rules.ts
              │                 └── block-rules.ts
              ├── packages/editor/src/composables/useBlockKeyboardHandlers.ts
              └── packages/editor/src/composables/usePatternPlugin.ts
                    └── Lezer Parser Engine

---

Parsing Pipeline

All syntax features flow through a 3-stage pipeline in packages/editor/src/lib/markdown-rules/engine.ts:

[Raw Block Content String]
       │
       ├── Phase 1: Block Classification   →  regex classifyBlock() on first line
       ├── Phase 1a: Priority Detection    →  separate from task state
       ├── Phase 2: Lezer AST Visitor      →  Inline Rules (Bold, Links, PageRef, Tags, Highlights)
       └── Phase 3: Property Extraction    →  Suffix Matcher (Key::Value)
       │
       ▼
[ParsedDecorations — unified output struct]

Unified Output Contract

export interface DecorationRange {
  type: "hidden" | "content"
  from: number
  to: number
  className?: string
}

export interface ParsedDecorations {
  content: (TokenDecoration | PageRefDecoration | BlockRefDecoration | TagDecoration | HighlightDecoration)[]
  properties: PropertyInfo[]
  blocks: BlockDecoration[]
}

Do not change this interface without updating both unit tests and block render cycles.

---

Supported Syntax

Task States and Priorities

TODO Fix the critical focus bug [#A]
└──┘                            └──┘
status                          priority

• Valid states: TODO, DOING, DONE, LATER, NOW, WAITING, CANCELLED
• State progression: TODO → DOING → DONE (linear). LATER, NOW, WAITING, CANCELLED are orthogonal.
• Valid priorities: [#A], [#B], [#C] — independent of task state.

Obsidian-Style Elements

Syntax	Example
Page reference	[[Page Name]] or [[Real Page\|Display Name]]
Block reference	((block-id-1234))
Callout	> [!NOTE] Description text
Property	author:: John Doe

Valid callout types: NOTE, WARNING, TIP, DANGER, INFO

---

Technology Stack

Layer	Technology	Rule
Framework	Vue 3 (Composition API, <script setup>)	Use composables for local state slices (e.g. useBlockKeyboardHandlers).
Type Safety	TypeScript (strict: true)	No implicit any. Use strict sum-types for internal configs like TaskState.
AST Parsing	@lezer/common / Lezer	Prefer specific SyntaxNode targeting over brute-force regex on blocks.
Formatting	Biome	Run biome check before committing.
Testing	Vitest	Run vitest run to verify. Every new rule must have a mirror test.

---

How to Add a New Rule

Follow these steps exactly. Do not deviate from this pattern.

1. Identify the pipeline stage.

• Inline syntax (spans within a line, e.g. bold, links) → InlineRule (defined as MarkdownRule<unknown>)
• Line/block syntax (whole-line patterns, e.g. headings, blockquotes) → BlockRule
• Key-value extraction → add to parseProperties() in engine.ts

2. Implement a self-contained factory function in the appropriate file under packages/editor/src/lib/markdown-rules/. Do not modify MarkdownRuleEngine.parse().

// Example: a minimal InlineRule factory (add to inline-rules.ts)
function createMyInlineRule(): MarkdownRule<unknown> {
  return {
    name: "my-rule",
    // Lezer node type(s) this rule targets
    nodeTypes: ["MyNode"],
    match(node) {
      return node.type.name === "MyNode"
    },
    run(node, ctx) {
      return [{
        type: "content",
        from: node.from,
        to: node.to,
        className: "my-decoration",
      }]
    },
  }
}

3. Register it in the MarkdownRuleEngine constructor in engine.ts.

constructor() {
  this.inlineRules = [
    ...createInlineRules(),
    createMyInlineRule(), // ← add here
  ]
}

4. Write a mirror test in packages/editor/src/lib/__tests__/markdown-parser.test.ts. Follow the existing pattern:

describe("MyInlineRule", () => {
  it("decorates correctly", () => {
    const result = engine.parse("some ~example~ text")
    expect(result.content).toContainEqual({
      type: "content",
      from: 5,
      to: 12,
      className: "my-decoration",
    })
  })
})

5. Verify cursor behavior. For any rule with hidden ranges (e.g. delimiters that hide when cursor is inside): confirm that from/to offsets are computed relative to the block's document offset, not the raw fragment string. Check the existing createDelimitedRule implementation as the reference.

6. Run checks.

biome check packages/editor/src/lib/markdown-rules/
vitest run

Both must pass before the change is complete.

---

Cursor Behavior — Hidden vs. Content Ranges

Decorations alternate between hidden (delimiters) and content (payload). For example, in **bold**:

• Positions 0–1 (**) → hidden when cursor is inside content (positions 2–5)
• Positions 2–5 (bold) → content
• Positions 6–7 (**) → hidden when cursor is inside content

Rules:

• hidden ranges disappear from view when the cursor is inside the enclosing content range.
• content ranges are always visible.
• Never update extraction slices without verifying that cursor offset tracking remains accurate for both the hidden and content segments.

---

Debug Logging

A namespace-based logger system in packages/editor/src/lib/logger.ts.

Enabling logs

Method	Example
Global (all blocks)	localStorage.setItem("editor:debug", "*")
By namespace	localStorage.setItem("editor:debug", "CodeBlockView,Block.Enter")
Per component instance	<EditorBlock debug="CodeBlockView,Block.Enter" />

After setting, refresh and open DevTools console. Namespaces set via the debug prop are scoped to that component instance and its descendants. The localStorage setting applies globally.

Available namespaces

Namespace	Source File	What it logs	Level
Block	Block.vue	Content changes, paste classification, external syncs	debug
CodeBlockView	useCodeBlockView.ts	Constructor, language detection, CM6↔PM sync, fence deletion conversion	info/debug
Block.Enter	useBlockKeyboardHandlers.ts	Enter keystroke detection, fence match results	debug
ContentModel	content-model.ts	contentToDoc/docToContent input/output sizes, node type breakdown	debug
AutoClose	auto-close-plugin.ts	Triple-backtick, bold, and italic auto-close rule triggers	info
Decorations	useMarkdownDecorations.ts	Cache hit/miss ratio, decoration count per build	debug
PatternPlugin	usePatternPlugin.ts	Pattern detection session open/update/close transitions	info
ParseEngine	engine.ts	Parse duration, rule match counts	debug

Adding logs to new code

import { createLogger } from "@/lib/logger"
const log = createLogger("MyFeature")
log.debug("only visible with filter enabled")
log.info("visible by default")
log.warn("always visible")
log.error("always visible")

For component-aware filtering (respects the debug prop), pass the filter string from the component:

// In a composable factory:
export function createMyThing(componentFilter?: string) {
  const log = createLogger("MyFeature", componentFilter)
  // ...
}

// In Block.vue:
createMyThing(props.debug)

Log levels

• info — notable events (auto-close triggered, code block created, pattern opened)
• debug — high-frequency events (every keystroke sync, decoration rebuild, paste classification)
• warn / error — unexpected states, always visible

If console output is too noisy, filter to info+: localStorage.setItem("editor:debug", "*") and set min level via configureDebug({ minLevel: "info" }) in DevTools.

---

Auto-Close Plugin

Defined in packages/editor/src/lib/auto-close-plugin.ts. A ProseMirror Plugin that intercepts text input (handleTextInput) and backspace (handleDOMEvents.keydown) to auto-close bracket pairs, toggle delimiters, and create code blocks.

Factories

Factory	Purpose	Returns
createPairRule(open, close, opts?)	Brackets (), [], {}, "", ''	AutoCloseRule
createToggleRule(delimiter, opts?)	Multi-char toggles **, ~~	AutoCloseRule

createPairRule behavior

• Auto-close: typing ( inserts () with cursor between
• Skip-over: typing ) when next char is ) moves cursor past it (only when no text selected)
• Wrap selection: typing ( with selected text wraps it as (selected) with cursor after )
• Delete-pair: Backspace between () deletes both characters
• Context option: regex filters when auto-close fires (e.g. " only after whitespace/structural chars)

createToggleRule behavior

• Requires multi-character delimiter (**, ~~, not * or ~)
• Typing the last character of the delimiter when prefix already present inserts delimiter pair, cursor between
• Word boundary: optional wordBoundary: true prevents mid-word triggering

Structural rules (built-in)

Rule	Trigger	Action
tripleBacktickRule	`at paragraph start on third `	Replaces paragraph with code_block node, cursor after opening fence
doubleAsteriskRule	** (via createToggleRule)	Inserts ****, cursor between
doubleTildeRule	~~ (via createToggleRule)	Inserts ~~~~, cursor between
singleUnderscoreRule	_ at word boundary	Inserts __, cursor between; no auto-close mid-word

Registration

In Block.vue, pass rules to autoClosePlugin([...]) in the EditorState's plugins array. Rules are evaluated in order; the first matching rule handles the event.

---

Performance Constraints

• Target < 16ms per parse cycle (60fps budget). The parser runs on every keystroke in focused Block.vue instances.
• visitTree processes each Lezer node exactly once. Do not introduce nested tree walks.
• Avoid allocations inside hot paths — reuse range objects where possible.

---

Critical Constraints

Read-only packed files. Aggregated repo views from tools like Repomix or workspace-pack are transport-only. Never write output targeting packed container files. Always emit changes to original source paths under apps/ or packages/.

Rule isolation. Never modify MarkdownRuleEngine.parse() to add syntax support. New syntax belongs in a new InlineRule or BlockRule factory, registered in the constructor.

Test coverage is required. A rule without a mirror test in __tests__/markdown-parser.test.ts is not complete.

Strict types. Do not introduce any. If a type is genuinely unknown, model it explicitly with a discriminated union or unknown with a type guard.