Positron Notebooks

Positron Notebooks Development

Purpose

Provides specialized knowledge and workflows for developing Positron Notebooks, a feature-flagged React-based notebook editor that coexists with VS Code's standard notebook experience.

When to Use This Skill

Load this skill when working on:

• Notebook cell behavior (execution, rendering, editing)
• Selection and focus management
• Context key system for notebooks
• Cell action commands and menus
• Notebook-kernel integration
• Output rendering and webviews
• E2E or unit tests for notebooks
• Debugging notebook issues

Quick Start

Validate Setup Before Starting

# Run validation script
./scripts/validate_setup.sh

Or manually check:

# Verify build daemons are running (required)
ps aux | grep -E "npm.*watch-(client|extensions)d" | grep -v grep

Enable Positron Notebooks for Testing

Add to settings.json:

{
	"positron.notebook.enabled": true,
	"workbench.editorAssociations": {
		"*.ipynb": "workbench.editor.positronNotebook"
	}
}

Restart Positron after changing feature flag.

Development Workflows

Adding a New Cell Command

1. Register command in src/vs/workbench/contrib/positronNotebook/browser/positronNotebook.contribution.ts 2. Add context key conditions (when-clauses) 3. Optionally add to menu or keybinding registry 4. Implement handler to access notebook instance and cells

See references/common-patterns.md for code examples.

Fixing a Cell Execution Bug

1. Start debugging task in VS Code (F5) 2. Set breakpoint in PositronNotebookInstance.ts:executeCell() 3. Open notebook and trigger execution 4. Check:

• Is kernel selected?
• Is previous execution cancelled?
• Are execution events firing?
• Does runtime session exist?

See references/debugging-guide.md for detailed strategies.

Debugging Selection/Focus Issues

1. Inspect context keys: Command Palette → "Developer: Inspect Context Keys" 2. Check selection machine state in selectionMachine.ts 3. Verify DOM focus with browser DevTools (document.activeElement) 4. Add logging to selection events and state transitions

See references/debugging-guide.md for common issues and solutions.

Running Tests

# Run all notebook E2E tests
./scripts/test_notebooks.sh

# Run specific test
./scripts/test_notebooks.sh "cell execution"

# Or use Playwright directly
npx playwright test test/e2e/tests/notebook/<test-name>.test.ts --project e2e-electron --reporter list

Searching Notebook Code

# Find code patterns
./scripts/find_notebook_code.sh "executeCell"
./scripts/find_notebook_code.sh "selectionMachine"

Core Files to Know

Primary entry point:

• src/vs/workbench/contrib/positronNotebook/browser/positronNotebook.contribution.ts - Command registration, editor resolver

Central logic:

• src/vs/workbench/contrib/positronNotebook/browser/PositronNotebookInstance.ts - Most non-UI logic, state management

React UI:

• src/vs/workbench/contrib/positronNotebook/browser/PositronNotebookEditor.tsx - Root component
• src/vs/workbench/contrib/positronNotebook/browser/notebookCells/ - Cell components

State systems:

• src/vs/workbench/contrib/positronNotebook/browser/selectionMachine.ts - Selection FSM
• src/vs/workbench/contrib/positronNotebook/browser/ContextKeysManager.ts - Context keys

Cell models:

• src/vs/workbench/contrib/positronNotebook/browser/PositronNotebookCells/ - Cell implementations

Key Architecture Principles

1. Feature-flagged - Coexists with VS Code notebooks, feature flag required 2. Observable-based - React UI driven by VS Code observables 3. Shared infrastructure - Reuses VS Code's notebook models, kernels, execution 4. One webview per output - Each output gets its own webview (vs single webview) 5. Context key scoped - Cell context keys scoped to cell DOM subtree

Progressive Documentation

For detailed information, read the bundled reference docs:

• `references/architecture.md` - Component details, integration points, execution flow
• `references/debugging-guide.md` - Debugging strategies, common issues, testing workflows
• `references/common-patterns.md` - Code examples for commands, observables, React components

Full architecture document available at: src/vs/workbench/contrib/positronNotebook/docs/positron_notebooks_architecture.md

Helper Scripts

Located in scripts/:

• `validate_setup.sh` - Check build daemons and file paths
• `test_notebooks.sh` - Run notebook E2E tests with optional pattern
• `find_notebook_code.sh` - Search for code patterns in notebook files

Common Tasks

Task: Add execution status indicator to cell

Steps: 1. Read references/common-patterns.md for observable patterns 2. Add state observable to cell model 3. Create React component consuming observable 4. Integrate into cell component tree

Task: Fix context keys not updating

Steps: 1. Read references/debugging-guide.md for context key issues 2. Check ContextKeysManager.ts for key setting logic 3. Verify scoping (cell-level keys scoped to cell DOM) 4. Use "Inspect Context Keys" to validate

Task: Debug cell not executing

Steps: 1. Read references/debugging-guide.md for execution debugging 2. Use VS Code debug task (F5) with breakpoints 3. Check kernel selection, runtime session, execution service 4. Monitor execution state changes via log service

Task: Understand selection state machine

Steps: 1. Read references/architecture.md for selection FSM overview 2. Check selectionMachine.ts for states and transitions 3. Add logging to transitions 4. Test selection events in debugger

Important Constraints

• Upstream compatibility: Prefer new files over modifying existing VS Code files
• Feature flag respect: Check usingPositronNotebooks() when needed
• No virtualization: All cells render (performance consideration for large notebooks)
• Webview lifecycle: Each output has own webview, coordinate mounting carefully

Self-Maintenance

Update Triggers

Update this skill when encountering:

• File paths that don't exist → Search for new location, update paths
• New patterns discovered → Add to references/common-patterns.md
• Bug fixes revealing insights → Add to references/debugging-guide.md
• Architecture changes → Update references/architecture.md and main doc

Update Process

1. Identify what changed (path, pattern, bug fix, architecture) 2. Update relevant file (SKILL.md or references/) 3. Verify all file paths still exist with ./scripts/validate_setup.sh 4. If architecture-significant, also update: src/vs/workbench/contrib/positronNotebook/docs/positron_notebooks_architecture.md

Path Validation

Before using any file path from this skill:

# Verify path exists
ls -la <path-from-skill>

# If wrong, search for correct location
find . -name "<filename>" | grep -v node_modules

Update skill with corrected path and add note about change.

Getting Help

For deeper understanding: 1. Start with relevant reference doc (references/) 2. Check main architecture doc (docs/positron_notebooks_architecture.md) 3. Use helper scripts for validation and searching 4. Set breakpoints and use VS Code debugging

This skill maintains lean, procedural guidance. Detailed technical information lives in progressive disclosure layers (references/ and main architecture doc).