@diagrammo/dgmo 0.8.17 → 0.8.19

package/docs/guide/how-dgmo-thinks.md

@@ -0,0 +1,277 @@
+# How DGMO Thinks
+
+A guide to the design principles behind the DGMO language. Understanding these themes will help you write diagrams faster and make better use of the language's features.
+
+---
+
+## Indent, Don't Repeat
+
+The most important pattern in DGMO: write the thing once, then indent what belongs to it beneath.
+
+Instead of repeating the source on every line:
+
+```dgmo-source
+// Verbose — repeats "API" three times
+API -routes-> UserService
+API -routes-> ProductService
+API -auth-> AuthService
+```
+
+Indent edges under their source:
+
+```dgmo-source
+// Concise — declare once, indent connections
+API
+  -routes-> UserService
+  -routes-> ProductService
+  -auth-> AuthService
+```
+
+This isn't just a shorthand — it's how DGMO thinks about ownership and hierarchy. The pattern shows up everywhere:
+
+- **Org charts and sitemaps** — indentation *is* the hierarchy
+- **Kanban** — cards indented under columns
+- **Gantt** — dependencies indented under tasks
+- **ER** — columns and relationships indented under tables
+- **Sequence** — participants indented under groups
+
+When you see indentation in DGMO, read it as "belongs to."
+
+---
+
+## Meaning First, Color Second
+
+When you want to make something red, your instinct might be to reach for a color suffix: `AuthService(red)`. That works for one-offs. But DGMO encourages a different approach for anything that carries meaning.
+
+**Tags** let you separate *what something means* from *how it looks*:
+
+```dgmo-source
+tag Priority alias p
+  Critical(red)
+  Normal(green)
+  Low(gray)
+
+API | p: Critical
+Cache | p: Low
+```
+
+Why go through this indirection?
+
+- **Colors become meaningful.** Red means "Critical," not just red. The legend self-documents.
+- **Palettes stay intact.** Switching from Nord to Dracula adjusts all your colors harmoniously. Direct hex codes would break this.
+- **Filtering works.** Tags are structured metadata — you can sort, hide, and group by them.
+- **One change updates everything.** Rename "Critical" to "Urgent" in one place, not fifty nodes.
+
+Use color suffixes `(red)` for quick visual accents. Use tags when color carries meaning you'd want in a legend.
+
+---
+
+## Name Things, Skip the Boilerplate
+
+DGMO infers as much as it can from names you're already writing.
+
+In sequence diagrams, the parser recognizes common names and gives them the right shape automatically:
+
+```dgmo-source
+Redis                // cache (cylinder, dashed)
+UserService          // service (rounded rectangle)
+Kafka                // queue (horizontal cylinder)
+User                 // actor (stick figure)
+WebApp               // frontend (monitor)
+```
+
+You only need `is a` when the name doesn't match a pattern:
+
+```dgmo-source
+Payments is a service       // "Payments" alone wouldn't infer
+Vault is a database         // "Vault" would infer as service
+```
+
+In flowcharts, arrow labels infer color:
+
+```dgmo-source
+<Valid?>
+  -yes-> [Process]          // automatically green
+  -no-> [Show Error]        // automatically red
+```
+
+The first declared tag group auto-activates. Chart types are detected from the first line. Org hierarchy comes from indentation alone.
+
+The principle: **name things sensibly and DGMO figures out the rest.** Override only when inference gets it wrong.
+
+---
+
+## Palette-Aware Colors
+
+When you write `(red)`, DGMO doesn't render `#ff0000`. It renders *the red from your active palette* — a shade that harmonizes with the other nine named colors in that palette.
+
+The allowed color names are: `red`, `orange`, `yellow`, `green`, `blue`, `purple`, `teal`, `cyan`, `gray`, `black`, `white`.
+
+That's the complete list. No hex codes, no CSS keywords, no custom colors. This is a deliberate constraint:
+
+- Every palette (Nord, Dracula, Catppuccin, Gruvbox, etc.) defines its own version of these eleven names
+- Switching palettes recolors your entire diagram coherently
+- Diagrams always look good regardless of which palette or theme is active
+- No one accidentally picks colors that clash or become invisible on certain backgrounds
+
+DGMO prioritizes *beautiful by default* over *total control.*
+
+---
+
+## Brackets Mean "Container"
+
+Wherever you see `[Name]`, something is being grouped:
+
+```dgmo-source
+[Backend]              // group in infra, boxes-and-lines, C4
+[To Do]                // column in kanban
+[Sprint 1]             // swimlane in gantt
+[Marketing]            // container in sitemap
+[Caribbean]            // category in scatter charts
+[Royal Navy]           // group in timeline
+```
+
+Content indented below the bracket line belongs to that group. Bracket grouping works in sequence, infra, flowchart, state, org, kanban, sitemap, gantt, boxes-and-lines, timeline, and scatter/bubble diagrams. When you see brackets, read them as "these things go together."
+
+Groups can have color suffixes and pipe metadata:
+
+```dgmo-source
+[Backend](blue) | team: Platform
+  API
+  Database
+  Cache
+```
+
+---
+
+## One Arrow Vocabulary
+
+DGMO uses the same small set of arrow patterns everywhere:
+
+| Pattern | Meaning | Example |
+|---------|---------|---------|
+| `->` | Synchronous / directed | `API -> Database` |
+| `~>` | Asynchronous | `API ~> Queue` |
+| `-label->` | Labeled edge | `-routes-> UserService` |
+| `~label~>` | Labeled async edge | `~notify~> Email` |
+| `-(color)->` | Colored edge | `-(red)-> Fallback` |
+| `<->` | Bidirectional | `A <-> B` |
+
+The label goes between the dashes (or tildes). Color goes in parens on the label. This works identically in sequence, infra, flowchart, C4, ER, class, sitemap, and boxes-and-lines diagrams.
+
+Learn it once, use it everywhere.
+
+---
+
+## Pipe Metadata: The Universal "And Also..."
+
+When you need to attach extra information to something, the pipe `|` syntax works on almost anything:
+
+```dgmo-source
+API | description: Main gateway, team: Platform
+API -routes-> UserService | frequency: High
+[Backend] | owner: Platform Team
+10bd Database Schema | p: Foundation, 80%
+1718-05 Blockade | p: Blackbeard
+Card Title | priority: High, assignee: Alice
+```
+
+Nodes, edges, groups, tasks, events, cards — if it exists in DGMO, you can probably pipe metadata onto it. The format is always `| key: value, key2: value2`.
+
+---
+
+## Describe Relationships, Not Layouts
+
+DGMO diagrams have no x/y coordinates, no manual positioning, no pixel-level control. You describe *what things are* and *how they connect*, and the layout engine handles placement.
+
+```dgmo-source
+// You write this
+CEO
+  CTO
+    Engineering
+    DevOps
+  CFO
+    Finance
+
+// DGMO handles the layout
+```
+
+This is a trade-off:
+
+- Diagrams reflow cleanly when content changes — add a node and everything adjusts
+- Version control diffs are meaningful (text changes, not coordinate noise)
+- You spend time on content, not dragging boxes around
+- But you don't get pixel-perfect placement
+
+If you find yourself wanting to control exact positions, you're probably fighting the tool. Instead, use groups, ordering, and direction options (`direction-tb`, `direction-lr`) to guide the layout.
+
+---
+
+## Options Are Simple Toggles
+
+Configuration goes at the top of the diagram as plain keywords:
+
+```dgmo-source
+gantt Product Launch
+start 2026-03-15
+today-marker
+critical-path
+no-dependencies
+active-tag Team
+```
+
+- **Boolean options**: bare keyword turns it on, `no-` prefix turns it off (`activations` / `no-activations`)
+- **Value options**: keyword followed by the value, space-separated (`start 2026-03-15`)
+- No YAML, no JSON, no nested config blocks
+- Options must appear before diagram content
+
+---
+
+## The Colon Rule
+
+Colons show up in exactly two situations:
+
+**1. Open-ended metadata** — when you're defining freeform key-value pairs:
+```dgmo-source
+API | description: Main gateway         // pipe metadata
+  role: Senior Engineer                 // org/C4 indented metadata
+```
+
+**2. Type separators** — where both sides can contain spaces and a delimiter is needed:
+```dgmo-source
++ name: string                          // class field type
++ sail(): void                          // class method return
+Trajectory(blue): -0.001*x^2 + 0.27*x  // function expression
+```
+
+**No colons anywhere else** — declarations, options, tags, data rows, arrows, groups, and comments are all colon-free:
+```dgmo-source
+bar Revenue by Quarter                  // declaration: no colon
+tag Team alias t                        // tag: no colon
+start 2026-03-15                        // option: no colon
+Gold 3500 4200 5100                     // data row: no colon
+id int pk                               // ER column: no colon
+latency-ms 50                           // infra property: no colon
+```
+
+The intuition: **if DGMO already knows what the fields are, spaces are enough. Colons appear only when you're defining something freeform or need an unambiguous separator.**
+
+---
+
+## One Diagram Per File
+
+The first line declares the chart type. There's no way to embed multiple diagrams in a single file. One file, one diagram, one clear purpose.
+
+```dgmo-source
+sequence Auth Flow
+// everything below is this one diagram
+```
+
+## Comments Are Full-Line Only
+
+```dgmo-source
+// This is a comment
+API -> Database  // This is NOT a comment — it's part of the line
+```
+
+Use `//` at the start of a line. There are no inline comments. `#` is not a comment character.

package/docs/guide/registry.json

@@ -10,6 +10,7 @@
     { "slug": "index", "title": "Welcome", "group": "getting-started", "file": "index.md" },
     { "slug": "keyboard-shortcuts", "title": "Keyboard Shortcuts", "group": "getting-started", "file": "keyboard-shortcuts.md" },
     { "slug": "colors", "title": "Colors", "group": "getting-started", "file": "colors.md" },
+    { "slug": "how-dgmo-thinks", "title": "How DGMO Thinks", "group": "getting-started", "file": "how-dgmo-thinks.md" },
 
     { "slug": "chart-arc", "title": "Arc Diagram", "group": "software", "file": "chart-arc.md" },
     { "slug": "chart-boxes-and-lines", "title": "Boxes and Lines", "group": "software", "file": "chart-boxes-and-lines.md" },

package/gallery/fixtures/gantt-sprints.dgmo

@@ -0,0 +1,20 @@
+gantt Sprint Planning
+start 2026-03-01
+sprint-length 2w
+sprint-number 5
+sprint-start 2026-01-05
+
+[Design]
+  2s UX Research
+  1s Wireframes
+  1.5s Visual Design
+
+[Engineering]
+  3s Backend API
+  2s Frontend Build
+  0.5s Performance Tuning
+
+[QA]
+  1s Integration Testing
+  0.5s UAT
+  0d Release Candidate

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@diagrammo/dgmo",
-  "version": "0.8.17",
+  "version": "0.8.19",
   "description": "DGMO diagram markup language — parser, renderer, and color system",
   "license": "MIT",
   "type": "module",

package/src/colors.ts

@@ -70,7 +70,7 @@ export function isRecognizedColorName(name: string): boolean {
 /**
  * Resolves a recognized color name to its hex value for the active palette
  * (falling back to the built-in Nord defaults). Returns `null` for any
- * unrecognized input — including hex codes, CSS keywords like `black`,
+ * unrecognized input — including hex codes, CSS keywords like `pink`,
  * and typos. Callers MUST treat `null` as a parse error and emit a
  * diagnostic; do not silently fall back to the raw input.
  */

package/src/editor/dgmo.grammar

@@ -27,7 +27,7 @@ contentPart {
   SyncArrow { "->" }
   AsyncArrow { "~>" }
 
-  Duration { $[0-9]+ ("." $[0-9]+)? ("min" | "bd" | "h" | "d" | "w" | "m" | "q" | "y") "?"? }
+  Duration { $[0-9]+ ("." $[0-9]+)? ("min" | "bd" | "h" | "d" | "w" | "m" | "q" | "y" | "s") "?"? }
   DateLiteral { $[0-9] $[0-9] $[0-9] $[0-9] "-" $[0-9] $[0-9] ("-" $[0-9] $[0-9])? }
   Percentage { $[0-9]+ ("." $[0-9]+)? "%" }
   Number { $[0-9]+ ("." $[0-9]+)? }

package/src/editor/dgmo.grammar.js

@@ -10,7 +10,7 @@ export const parser = LRParser.deserialize({
   maxTerm: 40,
   skippedNodes: [0],
   repeatNodeCount: 2,
-  tokenData: "9q~RxOX#oXY#tYZ$PZp#opq#tqt#oux#oxy$Uyz$tz{${{|%S|}%Z}!O%b!O!P#o!P!Q%q!Q![&b![!],v!]!^#o!^!_,}!_!`-U!`!a-c!a!b-j!b!c#o!c!}-q!}#O0w#O#P#o#P#Q0|#Q#R#o#R#S-q#S#T#o#T#[-q#[#]1T#]#o-q#o#p#o#p#q9T#q#r#o#r#s9[#s;'S#o;'S;=`9k<%lO#o~#tOq~~#yQv~XY#tpq#t~$UOw~~$]Qc~q~}!O$c#T#o$c~$fRyz$o}!O$c#T#o$c~$tOg~~${Od~q~~%SOn~q~~%ZOk~q~~%bOj~q~~%iPl~q~!`!a%l~%qOX~~%vPq~!P!Q%y~&OSV~OY%yZ;'S%y;'S;=`&[<%lO%y~&_P;=`<%l%y~&iY^~q~uv'X!O!P'^!Q![(z#U#V(U#W#X([#[#]([#a#b(i#e#f([#k#l([#m#n([~'^O]~~'aP!Q!['d~'iX^~uv'X!Q!['d#U#V(U#W#X([#[#]([#a#b(i#e#f([#k#l([#m#n([~(XP#W#X([~(aPZ~!a!b(d~(iOZ~~(nQZ~!a!b(d#]#^(t~(wP#b#c([~)PY^~uv'X!O!P'^!Q![)o#U#V(U#W#X([#[#]([#a#b(i#e#f([#k#l([#m#n([~)tY^~uv'X!O!P'^!Q![*d#U#V(U#W#X([#[#]([#a#b(i#e#f([#k#l([#m#n([~*iZ^~uv'X}!O+[!O!P'^!Q![,R#U#V(U#W#X([#[#]([#a#b(i#e#f([#k#l([#m#n([~+_P!Q![+b~+eP!Q![+h~+mP[~}!O+p~+sP!Q![+v~+yP!Q![+|~,RO[~~,WY^~uv'X!O!P'^!Q![,R#U#V(U#W#X([#[#]([#a#b(i#e#f([#k#l([#m#n([~,}Oi~q~~-UOe~q~~-ZPq~!_!`-^~-cO_~~-jOf~q~~-qOo~q~~-x_p~q~qr.wst.wvw.wwx.w{|.w}!O/{!O!P.w!P!Q.w!Q![.w!_!`.w!a!b.w!b!c.w!c!}.w#R#S.w#T#o.w~.|_p~qr.wst.wvw.wwx.w{|.w}!O/{!O!P.w!P!Q.w!Q![.w!_!`.w!a!b.w!b!c.w!c!}.w#R#S.w#T#o.w~0O]qr.wst.wvw.wwx.w{|.w!O!P.w!P!Q.w!_!`.w!a!b.w!b!c.w!c!}.w#R#S.w#T#o.w~0|Oa~~1TOb~q~~1[ap~q~qr.wst.wvw.wwx.w{|.w}!O/{!O!P.w!P!Q.w!Q![.w!_!`.w!a!b.w!b!c.w!c!}.w#R#S.w#T#h.w#h#i2a#i#o.w~2fap~qr.wst.wvw.wwx.w{|.w}!O/{!O!P.w!P!Q.w!Q![.w!_!`.w!a!b.w!b!c.w!c!}.w#R#S.w#T#h.w#h#i3k#i#o.w~3pap~qr.wst.wvw.wwx.w{|.w}!O/{!O!P.w!P!Q.w!Q![.w!_!`.w!a!b.w!b!c.w!c!}.w#R#S.w#T#d.w#d#e4u#e#o.w~4zbp~qr.wst.wvw.wwx.w{|.w}!O/{!O!P.w!P!Q.w!Q![.w![!]6S!_!`.w!a!b.w!b!c.w!c!}.w#R#S.w#T#g.w#g#h7|#h#o.w~6VP!P!Q6Y~6]P!P!Q6`~6cYOX7RZp7Rqy7Rz|7R}!`7R!a#P7R#Q#p7R#q;'S7R;'S;=`7v<%lO7R~7WY`~OX7RZp7Rqy7Rz|7R}!`7R!a#P7R#Q#p7R#q;'S7R;'S;=`7v<%lO7R~7yP;=`<%l7R~8R`p~qr.wst.wvw.wwx.w{|.w}!O/{!O!P.w!P!Q.w!Q![.w![!]6S!_!`.w!a!b.w!b!c.w!c!}.w#R#S.w#T#o.w~9[Oh~q~~9cPm~q~!`!a9f~9kOY~~9nP;=`<%l#o",
+  tokenData: ":T~RxOX#oXY#tYZ$PZp#opq#tqt#oux#oxy$Uyz$tz{${{|%S|}%Z}!O%b!O!P#o!P!Q%q!Q![&b![!]-Y!]!^#o!^!_-a!_!`-h!`!a-u!a!b-|!b!c#o!c!}.T!}#O1Z#O#P#o#P#Q1`#Q#R#o#R#S.T#S#T#o#T#[.T#[#]1g#]#o.T#o#p#o#p#q9g#q#r#o#r#s9n#s;'S#o;'S;=`9}<%lO#o~#tOq~~#yQv~XY#tpq#t~$UOw~~$]Qc~q~}!O$c#T#o$c~$fRyz$o}!O$c#T#o$c~$tOg~~${Od~q~~%SOn~q~~%ZOk~q~~%bOj~q~~%iPl~q~!`!a%l~%qOX~~%vPq~!P!Q%y~&OSV~OY%yZ;'S%y;'S;=`&[<%lO%y~&_P;=`<%l%y~&iZ^~q~uv'[!O!P'a!Q![)Q#U#V([#W#X(b#[#](b#a#b(o#e#f(b#g#h(b#k#l(b#m#n(b~'aO]~~'dP!Q!['g~'lY^~uv'[!Q!['g#U#V([#W#X(b#[#](b#a#b(o#e#f(b#g#h(b#k#l(b#m#n(b~(_P#W#X(b~(gPZ~!a!b(j~(oOZ~~(tQZ~!a!b(j#]#^(z~(}P#b#c(b~)VZ^~uv'[!O!P'a!Q![)x#U#V([#W#X(b#[#](b#a#b(o#e#f(b#g#h(b#k#l(b#m#n(b~)}Z^~uv'[!O!P'a!Q![*p#U#V([#W#X(b#[#](b#a#b(o#e#f(b#g#h(b#k#l(b#m#n(b~*u[^~uv'[}!O+k!O!P'a!Q![,b#U#V([#W#X(b#[#](b#a#b(o#e#f(b#g#h(b#k#l(b#m#n(b~+nP!Q![+q~+tP!Q![+w~+|P[~}!O,P~,SP!Q![,V~,YP!Q![,]~,bO[~~,gZ^~uv'[!O!P'a!Q![,b#U#V([#W#X(b#[#](b#a#b(o#e#f(b#g#h(b#k#l(b#m#n(b~-aOi~q~~-hOe~q~~-mPq~!_!`-p~-uO_~~-|Of~q~~.TOo~q~~.[_p~q~qr/Zst/Zvw/Zwx/Z{|/Z}!O0_!O!P/Z!P!Q/Z!Q![/Z!_!`/Z!a!b/Z!b!c/Z!c!}/Z#R#S/Z#T#o/Z~/`_p~qr/Zst/Zvw/Zwx/Z{|/Z}!O0_!O!P/Z!P!Q/Z!Q![/Z!_!`/Z!a!b/Z!b!c/Z!c!}/Z#R#S/Z#T#o/Z~0b]qr/Zst/Zvw/Zwx/Z{|/Z!O!P/Z!P!Q/Z!_!`/Z!a!b/Z!b!c/Z!c!}/Z#R#S/Z#T#o/Z~1`Oa~~1gOb~q~~1nap~q~qr/Zst/Zvw/Zwx/Z{|/Z}!O0_!O!P/Z!P!Q/Z!Q![/Z!_!`/Z!a!b/Z!b!c/Z!c!}/Z#R#S/Z#T#h/Z#h#i2s#i#o/Z~2xap~qr/Zst/Zvw/Zwx/Z{|/Z}!O0_!O!P/Z!P!Q/Z!Q![/Z!_!`/Z!a!b/Z!b!c/Z!c!}/Z#R#S/Z#T#h/Z#h#i3}#i#o/Z~4Sap~qr/Zst/Zvw/Zwx/Z{|/Z}!O0_!O!P/Z!P!Q/Z!Q![/Z!_!`/Z!a!b/Z!b!c/Z!c!}/Z#R#S/Z#T#d/Z#d#e5X#e#o/Z~5^bp~qr/Zst/Zvw/Zwx/Z{|/Z}!O0_!O!P/Z!P!Q/Z!Q![/Z![!]6f!_!`/Z!a!b/Z!b!c/Z!c!}/Z#R#S/Z#T#g/Z#g#h8`#h#o/Z~6iP!P!Q6l~6oP!P!Q6r~6uYOX7eZp7eqy7ez|7e}!`7e!a#P7e#Q#p7e#q;'S7e;'S;=`8Y<%lO7e~7jY`~OX7eZp7eqy7ez|7e}!`7e!a#P7e#Q#p7e#q;'S7e;'S;=`8Y<%lO7e~8]P;=`<%l7e~8e`p~qr/Zst/Zvw/Zwx/Z{|/Z}!O0_!O!P/Z!P!Q/Z!Q![/Z![!]6f!_!`/Z!a!b/Z!b!c/Z!c!}/Z#R#S/Z#T#o/Z~9nOh~q~~9uPm~q~!`!a9x~9}OY~~:QP;=`<%l#o",
   tokenizers: [0],
   topRules: {"Document":[0,6]},
   specialized: [{term: 32, get: (value, stack) => (specializeKeyword(value, stack) << 1), external: specializeKeyword}],

package/src/gantt/calculator.ts

@@ -17,7 +17,10 @@ import type {
   GanttTask,
   GanttGroup,
   GanttHolidays,
+  GanttOptions,
+  Duration,
   ResolvedSchedule,
+  ResolvedSprint,
   ResolvedGroup,
   Offset,
 } from './types';
@@ -52,6 +55,7 @@ export function calculateSchedule(parsed: ParsedGantt): ResolvedSchedule {
     tagGroups: parsed.tagGroups,
     eras: parsed.eras,
     markers: parsed.markers,
+    sprints: [],
     options: parsed.options,
     diagnostics,
     error: parsed.error,
@@ -85,6 +89,12 @@ export function calculateSchedule(parsed: ParsedGantt): ResolvedSchedule {
     projectStart = new Date(2000, 0, 1);
   }
 
+  // ── Sprint config ──────────────────────────────────────
+
+  const sprintOpts = parsed.options.sprintLength
+    ? { sprintLength: parsed.options.sprintLength }
+    : undefined;
+
   // ── Dep offset storage ─────────────────────────────────
 
   const depOffsetMap = new Map<string, Offset>();
@@ -208,7 +218,8 @@ export function calculateSchedule(parsed: ParsedGantt): ResolvedSchedule {
             depOffset.duration,
             parsed.holidays,
             holidaySet,
-            depOffset.direction
+            depOffset.direction,
+            sprintOpts
           );
         }
 
@@ -225,7 +236,8 @@ export function calculateSchedule(parsed: ParsedGantt): ResolvedSchedule {
         task.offset.duration,
         parsed.holidays,
         holidaySet,
-        task.offset.direction
+        task.offset.direction,
+        sprintOpts
       );
       if (start.getTime() < projectStart.getTime()) {
         warn(
@@ -273,7 +285,9 @@ export function calculateSchedule(parsed: ParsedGantt): ResolvedSchedule {
           start,
           task.duration,
           parsed.holidays,
-          holidaySet
+          holidaySet,
+          1,
+          sprintOpts
         );
       }
     } else {
@@ -294,7 +308,8 @@ export function calculateSchedule(parsed: ParsedGantt): ResolvedSchedule {
         taskMap,
         depOffsetMap,
         parsed.holidays,
-        holidaySet
+        holidaySet,
+        sprintOpts
       )
     : new Set<string>();
 
@@ -347,6 +362,29 @@ export function calculateSchedule(parsed: ParsedGantt): ResolvedSchedule {
     result.endDate = maxDate;
   }
 
+  // ── Generate sprint bands ──────────────────────────────
+
+  if (
+    parsed.options.sprintMode &&
+    parsed.options.sprintLength &&
+    result.tasks.length > 0
+  ) {
+    result.sprints = generateSprintBands(
+      parsed.options,
+      result.startDate,
+      result.endDate,
+      projectStart
+    );
+
+    // Extend chart range to include the last sprint's end so it doesn't clip
+    if (result.sprints.length > 0) {
+      const lastSprintEnd = result.sprints[result.sprints.length - 1].endDate;
+      if (lastSprintEnd.getTime() > result.endDate.getTime()) {
+        result.endDate = lastSprintEnd;
+      }
+    }
+  }
+
   // ── Warnings ────────────────────────────────────────────
 
   // Missing parallel warning: 2+ top-level groups without parallel wrapper
@@ -613,7 +651,8 @@ function computeCriticalPath(
   taskMap: Map<string, TaskNode>,
   depOffsetMap: Map<string, Offset>,
   holidays: GanttHolidays,
-  holidaySet: Set<string>
+  holidaySet: Set<string>,
+  sprintOpts?: { sprintLength?: Duration }
 ): Set<string> {
   if (sortedIds.length === 0) return new Set();
 
@@ -660,7 +699,8 @@ function computeCriticalPath(
             succTask.offset.duration,
             holidays,
             holidaySet,
-            reverseDir
+            reverseDir,
+            sprintOpts
           );
           succLS = adjusted.getTime();
         }
@@ -674,7 +714,8 @@ function computeCriticalPath(
             depOffset.duration,
             holidays,
             holidaySet,
-            reverseDir
+            reverseDir,
+            sprintOpts
           );
           succLS = adjusted.getTime();
         }
@@ -769,6 +810,78 @@ function buildResolvedGroups(
   }
 }
 
+// ── Sprint band generation ──────────────────────────────────
+
+function generateSprintBands(
+  options: GanttOptions,
+  chartStart: Date,
+  chartEnd: Date,
+  projectStart: Date
+): ResolvedSprint[] {
+  const sprintLength = options.sprintLength!;
+  const sprintNumber = options.sprintNumber ?? 1;
+
+  // Determine anchor date: sprint-start or chart start or today
+  let anchorDate: Date;
+  if (options.sprintStart) {
+    anchorDate = new Date(options.sprintStart + 'T00:00:00');
+  } else if (options.start) {
+    anchorDate = new Date(projectStart);
+  } else {
+    const now = new Date();
+    anchorDate = new Date(now.getFullYear(), now.getMonth(), now.getDate());
+  }
+  anchorDate.setHours(0, 0, 0, 0);
+
+  // Sprint length in whole days (parser ensures only d/w with integer day result)
+  const sprintDays = Math.round(
+    sprintLength.amount * (sprintLength.unit === 'w' ? 7 : 1)
+  );
+  if (sprintDays <= 0) return []; // defensive guard
+
+  // Bail if anchor date is invalid (e.g. sprint-start 2026-13-45)
+  if (Number.isNaN(anchorDate.getTime())) return [];
+
+  // Calculate which sprint chartStart falls in, relative to the anchor
+  const chartStartTime = new Date(chartStart);
+  chartStartTime.setHours(0, 0, 0, 0);
+  const chartEndTime = new Date(chartEnd);
+  chartEndTime.setHours(0, 0, 0, 0);
+
+  const msPerDay = 86400000;
+  const dayDiff = Math.floor(
+    (chartStartTime.getTime() - anchorDate.getTime()) / msPerDay
+  );
+  // Floor division: which sprint index (from anchor) does chartStart fall in?
+  const startSprintIndex = Math.floor(dayDiff / sprintDays);
+
+  const sprints: ResolvedSprint[] = [];
+  const maxSprints = 1000; // safety guard against infinite loops
+
+  // Generate sprints that overlap with [chartStart, chartEnd]
+  // Sprint at index i (relative to anchor) has number: sprintNumber + i
+  for (let i = startSprintIndex; sprints.length < maxSprints; i++) {
+    const sprintStartDate = new Date(anchorDate);
+    sprintStartDate.setDate(sprintStartDate.getDate() + i * sprintDays);
+    sprintStartDate.setHours(0, 0, 0, 0);
+
+    const sprintEndDate = new Date(sprintStartDate);
+    sprintEndDate.setDate(sprintEndDate.getDate() + sprintDays);
+    sprintEndDate.setHours(0, 0, 0, 0);
+
+    // Stop when sprint start is past chart end
+    if (sprintStartDate.getTime() >= chartEndTime.getTime() + msPerDay) break;
+
+    sprints.push({
+      number: sprintNumber + i,
+      startDate: sprintStartDate,
+      endDate: sprintEndDate,
+    });
+  }
+
+  return sprints;
+}
+
 // ── Utility ─────────────────────────────────────────────────
 
 function formatDate(d: Date): string {