Source Code Annotator

A Val Town val for viewing annotated source code with interactive features including syntax highlighting, hover effects, and explanatory popups.

• Syntax Highlighting: Automatic syntax highlighting using Prism.js for multiple languages
• Interactive Hover: Hover over code blocks to highlight the smallest logical containing block
• Click Explanations: Click on highlighted blocks to see detailed explanations in a popup
• Extensible: Override default functions with custom implementations via query parameters

Visit the val URL without any path to see usage instructions and examples:

https://your-val-url.web.val.run/

This will display an interactive usage page with:

• Feature overview and quick start guide
• Live example links you can click to try
• Documentation links to the README and examples
• Supported languages and customization options

Visit your val URL with the path to the source code you want to annotate:

https://your-val-url.web.val.run/{username}/{valname}@{version}/{filename}

Example:

https://your-val-url.web.val.run/nbbaier/sqliteExplorerApp@100-main/main.tsx

This will fetch the source from https://esm.town/v/nbbaier/sqliteExplorerApp@100-main/main.tsx and display it with annotations.

You can override the default functionality by providing custom val URLs as query parameters:

?syntaxHighlighter=https://your-custom-highlighter.web.val.run

Your custom syntax highlighter should accept POST requests with:

{
  "code": "source code string",
  "language": "javascript|typescript|python|etc"
}

And return HTML with syntax-highlighted code.

?blockDetector=https://your-custom-detector.web.val.run

Your custom block detector should accept POST requests with:

{
  "code": "source code string",
  "line": 10,
  "column": 5
}

And return JSON with:

{
  "start": 8,
  "end": 15,
  "type": "function|class|control|statement"
}

?blockExplainer=https://your-custom-explainer.web.val.run

Your custom block explainer should accept POST requests with:

{
  "code": "source code string",
  "blockInfo": {
    "start": 8,
    "end": 15,
    "type": "function"
  }
}

And return plain text or HTML explanation.

https://your-val-url.web.val.run/nbbaier/sqliteExplorerApp@100-main/main.tsx?blockExplainer=https://my-ai-explainer.web.val.run&syntaxHighlighter=https://my-custom-highlighter.web.val.run

The val automatically detects language from file extensions:

• .ts, .tsx → TypeScript
• .js, .jsx → JavaScript
• .py → Python
• .rs → Rust
• .go → Go
• .java → Java
• .cpp, .cc, .cxx → C++
• .c → C
• .css → CSS
• .html → HTML
• .json → JSON
• .md → Markdown

The default block detector uses simple heuristics to identify:

1. Function blocks: Lines containing function or =>
2. Class blocks: Lines containing class
3. Control blocks: Lines containing if, for, or while
4. Statement blocks: Individual statements (fallback)

1. URL Parsing: Extracts the val path from the URL
2. Source Fetching: Fetches source code from https://esm.town/v/{path}
3. Language Detection: Determines language from file extension
4. Syntax Highlighting: Applies syntax highlighting using Prism.js
5. Interactive Layer: Adds mouse event handlers for hover and click interactions
6. Block Detection: Calculates logical code blocks based on cursor position
7. Explanations: Generates explanations for clicked blocks

The val is structured with three main pluggable functions:

• defaultSyntaxHighlighter(): Handles code syntax highlighting
• defaultBlockDetector(): Identifies logical code blocks
• defaultBlockExplainer(): Generates explanations for code blocks

Each function can be replaced with custom implementations via query parameters, making the system highly extensible.

• Returns 404 if the source URL cannot be fetched
• Returns 400 for invalid path formats
• Returns 500 for other errors with error messages
• Client-side errors are logged to console

The project includes several example custom functions to demonstrate extensibility:

Uses OpenAI to generate detailed explanations of code blocks. Requires OPENAI_API_KEY environment variable.

Usage:

?blockExplainer=https://your-val-url.web.val.run/examples/ai-explainer.ts

Provides more sophisticated block detection with support for:

• Functions, classes, interfaces
• Objects and arrays
• Control structures
• Import/export blocks
• Comments (single and multi-line)

Usage:

?blockDetector=https://your-val-url.web.val.run/examples/enhanced-detector.ts

Enhanced syntax highlighting with:

• Complexity indicators for each line
• Visual complexity color coding
• Hover effects
• Custom styling

Usage:

?syntaxHighlighter=https://your-val-url.web.val.run/examples/custom-highlighter.ts

https://your-val-url.web.val.run/nbbaier/sqliteExplorerApp@100-main/main.tsx?blockDetector=https://your-val-url.web.val.run/examples/enhanced-detector.ts&blockExplainer=https://your-val-url.web.val.run/examples/ai-explainer.ts&syntaxHighlighter=https://your-val-url.web.val.run/examples/custom-highlighter.ts

• Modern browsers with ES6+ support
• Requires JavaScript enabled for interactive features
• Responsive design works on desktop and mobile