Definition
Regions are defined below a--- separator at the bottom of a code fence:
Target Format by Block Type
Each block type has its own region target format:| Block Type | Format | Examples |
|---|---|---|
| Code | Line numbers, ranges | 2, 3-5, 1, 4-6, 9 |
| Data | Node/element IDs | head, n1, n2 |
| Diagram | Node IDs | api, db, cache |
| Math | Expression IDs | expr-0, expr-1 |
| Chart | X-axis labels | Q1, Feb |
| Preview | (varies) | Depends on content |
Code Block Regions
Line numbers:Data Block Regions
Target node/element IDs defined in the data structure. Array:Diagram Block Regions
Target node IDs from the diagram definition.Math Block Regions
Target auto-generated expression IDs (expr-0, expr-1, …).
Chart Block Regions
Target X-axis labels from the chart data.Naming Conventions
Semantic Names
Region names should describe the concept, not the position: Good:Naming Style
- Lowercase with hyphens:
return-val,check-condition,hash-step - Descriptive:
signature,loop-body,error-handling - Never positional: Not
line-3,top-part,section-2
Concept-Based Examples
Algorithm code:Usage in Triggers
Regions are referenced by name in triggers:Focus
Pulse
Annotate
Zoom
Flow
Trace
Draw
Pan
Edge Regions (Paths)
For graph-like visualizations (graphs, trees, diagrams), regions can target paths between nodes.Format
Paths are comma-separated node IDs. The renderer connects them with edges. Graph path:Usage with Flow/Trace/Draw
Flow (looping animation):Multi-Element Regions
Regions can target multiple elements for group operations.Code (multiple line ranges):
Data (multiple nodes):
Diagram (multiple services):
Region Best Practices
1. Define regions for every key concept
Before (no regions):2. Match region names to narration vocabulary
If your narration says “the initialization step,” name the regioninit, not setup or start.
If you say “the greedy choice,” name it greedy-choice, not decision or pick-step.
Consistency makes authoring faster — you don’t have to remember mappings.
3. Granularity matches explanation depth
If you only mention “the loop” once, one region is enough:4. Use multi-element regions for comparisons
Comparing left vs right subtrees:5. Keep path regions semantic
Good:TypeScript Definition
Fromsrc/types/lesson.ts:
regions field: