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).