Change the release advance model - breaking change in syntax

Author: alexboly

README.md

@@ -2,7 +2,7 @@
 
 Generate user story maps from markdown. Write your product spec as a readable
 document — personas, releases, activities, tasks, and stories — and render it
-as a styled HTML page.
+as a styled, interactive HTML page.
 
 ## Installation
 
@@ -19,6 +19,9 @@ storymap render mymap.md        # → mymap.html (same directory)
 storymap render mymap.md -o out # → out/mymap.html
 ```
 
+The output is a single self-contained HTML file. Local images referenced in
+story descriptions are embedded as base64 data URIs — no external files needed.
+
 **PDF output:** open the generated HTML in a browser and use print-to-PDF
 (Ctrl+P → Save as PDF). The HTML includes print-optimised CSS for landscape
 layout and color preservation.
@@ -27,7 +30,7 @@ layout and color preservation.
 
 A storymap file is a standard markdown document with three reserved top-level
 sections: `# Releases`, `# Personas`, and `# Map`. Any other `#` heading is
-treated as the document title (first one) or passed through to the output.
+treated as the document title (first one) or ignored.
 
 ```markdown
 # My Product
@@ -50,19 +53,15 @@ Margie manages a team of 8 and primarily uses the app on mobile.
 # Map
 ## User Management
 ### Authentication
-#### Sign in [status:: done] [persona:: Margie the Manager]
+#### Sign in [status:: done] [persona:: Margie the Manager] [release:: MVP]
 User can log in with email and password.
 
-> release Beta
-
-#### Password reset [status:: in-progress] [deadline:: 2026-03-01]
+#### Password reset [status:: in-progress] [deadline:: 2026-03-01] [release:: Beta]
 
 ### Profile
-#### Edit profile [status:: done]
-
-> release Beta
+#### Edit profile [status:: done] [release:: MVP]
 
-#### Upload avatar [status:: blocked]
+#### Upload avatar [status:: blocked] [release:: Beta]
 Blocked pending storage provider decision.
 ```
 
@@ -84,34 +83,36 @@ Section names are case-insensitive.
 #### Story        (card in a swimlane)
 ```
 
-Use `> release` on its own line to advance to the next release swimlane within
-a task. Annotate it for readability — anything after `release` is ignored:
+### Assigning stories to releases
+
+Use the `[release:: name]` field on each story to assign it to a release
+swimlane. The name must match a release defined in the `# Releases` section.
+Stories without a `[release::]` field are parsed but not shown in any swimlane.
 
 ```markdown
 ### Authentication
-#### Sign in          ← Release 1 (MVP)
-#### Remember me      ← Release 1 (MVP)
-> release Beta
-#### SSO              ← Release 2 (Beta)
-> release GA
-                      ← Release 3 empty for this task
+#### Sign in [status:: done] [release:: MVP]
+#### Remember me [status:: done] [release:: MVP]
+#### SSO [status:: not-started] [release:: Beta]
+#### SAML [status:: not-started] [release:: GA]
 ```
 
-Keep `> release` count consistent across all tasks — mismatched counts produce
-misaligned swimlane rows.
+This is more explicit than positional separators — each story carries its own
+release assignment regardless of order in the file.
 
 ### Story fields
 
 Stories support optional inline fields using `[key:: value]` syntax.
 Fields appear as badges on the rendered story card.
 
 ```markdown
-#### Story name [status:: done] [persona:: Margie the Manager] [deadline:: 2026-03-01]
+#### Story name [status:: done] [persona:: Margie the Manager] [deadline:: 2026-03-01] [release:: MVP]
 ```
 
 | Field | Values | Default |
 |---|---|---|
 | `status` | `not-started`, `in-progress`, `done`, `blocked` | `not-started` |
+| `release` | Release name from `# Releases` section | — |
 | `persona` | Any string matching a persona name | — |
 | `deadline` | ISO date `YYYY-MM-DD` | — |
 
@@ -120,8 +121,45 @@ Any other `[key:: value]` field is accepted and rendered as a badge.
 ### Story descriptions
 
 Markdown content following a `#### Story` heading and before the next heading
-or `> release` separator is treated as the story description. Descriptions
-support standard markdown: bold, italics, links, lists.
+is treated as the story description. Descriptions support standard markdown:
+bold, italics, links, lists, and images.
+
+The first paragraph is always visible on the story card. Additional paragraphs
+(separated by a blank line) are shown only in Detail zoom level.
+
+```markdown
+#### Sign in [status:: done] [release:: MVP]
+User can log in with email and password.
+
+**Acceptance criteria:**
+- Given valid credentials, user is redirected to dashboard
+- Given invalid credentials, an error message is shown
+
+![wireframe](./screens/sign-in.png)
+```
+
+### Images
+
+Images in story descriptions and persona descriptions are embedded as base64
+data URIs in the output HTML, making the file fully self-contained. Paths are
+resolved relative to the source `.md` file. Remote URLs are left as-is.
+
+## Interactive HTML features
+
+The rendered HTML includes controls for navigating large maps:
+
+**Zoom levels** — three buttons in the sticky header:
+- **Overview** — story names only, compact layout
+- **Map** — story names, status badges, and first-paragraph descriptions
+- **Detail** — full descriptions and acceptance criteria expanded
+
+**Release focus** — a dropdown to highlight one release swimlane and dim
+the rest. Works independently of the zoom level.
+
+**Story Lens** — a toggle that enables click-to-zoom on individual story cards.
+When active, clicking a card expands it to ~40% of the viewport width with full
+details visible. Clicking outside collapses it. Stories in the focused release
+(if any) are the only ones that can be expanded.
 
 ## CLI reference
 
@@ -197,6 +235,8 @@ The template receives:
 | `status_colors` | `dict[str, str]` | Resolved status → hex color |
 | `ui_colors` | `dict[str, str]` | Resolved UI element → hex color |
 | `render_md` | `callable` | Render a markdown string to HTML |
+| `render_md_intro` | `callable` | Render first paragraph only |
+| `render_md_rest` | `callable` | Render everything after first paragraph |
 
 The `darken` filter is also available: `{{ color | darken }}`.
 
@@ -217,7 +257,7 @@ just test
 storymap/
 ├── model.py       — dataclasses and default color constants
 ├── parser.py      — markdown-it-py state machine parser
-├── renderer.py    — Jinja2 HTML renderer
+├── renderer.py    — Jinja2 HTML renderer with base64 image embedding
 ├── cli.py         — click CLI entry point
 └── templates/
     └── default.html.j2

sample.md

@@ -89,20 +89,18 @@ New user can register with email and password.
 Includes email verification flow.
 See [issue #12](https://github.com/org/repo/issues/12)
 
-> release MVP
 
-#### Register via SSO [status:: in-progress] [persona:: Dave the Developer] [deadline:: 2026-04-15]
+#### Register via SSO [status:: in-progress] [persona:: Dave the Developer] [deadline:: 2026-04-15] [release:: MVP]
 Support Google and Microsoft OAuth providers.
 See [issue #34](https://github.com/org/repo/issues/34)
 
-> release Beta
 
-#### Register via SAML [status:: not-started] [persona:: Margie the Manager] [deadline:: 2026-09-01]
+#### Register via SAML [status:: not-started] [persona:: Margie the Manager] [deadline:: 2026-09-01] [release:: Beta]
 Enterprise SAML 2.0 support for large customers.
 
 ### Authentication
 
-#### Sign in [status:: done]
+#### Sign in [status:: done] [release:: Beta]
 Standard email/password login with remember-me option.
 
 **Acceptance criteria:**
@@ -111,20 +109,17 @@ Standard email/password login with remember-me option.
 - Given "remember me" checked, session persists for 30 days
 - Given 5 failed attempts, account is temporarily locked
 
-> release GA
 
-#### Forgot password [status:: done]
+#### Forgot password [status:: done] [release:: GA]
 Password reset via email token.
 See [issue #15](https://github.com/org/repo/issues/15)
 
-> release MVP
 
-#### MFA via TOTP [status:: in-progress] [deadline:: 2026-04-30]
+#### MFA via TOTP [status:: in-progress] [deadline:: 2026-04-30] [release:: MVP]
 Time-based one-time password support (Google Authenticator, Authy).
 
-> release Beta
 
-#### MFA via SMS [status:: not-started] [deadline:: 2026-09-01]
+#### MFA via SMS [status:: not-started] [deadline:: 2026-09-01] [release:: Beta]
 SMS-based one-time password as an alternative to TOTP.
 
 **Acceptance criteria:**
@@ -135,83 +130,73 @@ SMS-based one-time password as an alternative to TOTP.
 
 ### Profile
 
-#### View and edit profile [status:: done] [persona:: Nina the New User]
+#### View and edit profile [status:: done] [persona:: Nina the New User] [release:: Beta]
 User can view and update their display name, email, and bio.
 
 **Acceptance criteria:**
 - Changes are saved on submit with a success toast
 - Email change triggers a re-verification flow
 - Invalid fields show inline validation errors
 
-> release GA
 
-#### Upload avatar [status:: blocked] [persona:: Nina the New User]
+#### Upload avatar [status:: blocked] [persona:: Nina the New User] [release:: GA]
 Blocked pending storage provider decision.
 See [JIRA-456](https://jira.example.com/browse/JIRA-456)
 
-> release MVP
 
-#### Delete account [status:: not-started] [deadline:: 2026-09-01]
+#### Delete account [status:: not-started] [deadline:: 2026-09-01] [release:: MVP]
 Must comply with GDPR right-to-erasure requirements.
 See [issue #78](https://github.com/org/repo/issues/78)
 
 ## Reporting
 
 ### Dashboard
 
-#### View project summary [status:: done] [persona:: Margie the Manager]
+#### View project summary [status:: done] [persona:: Margie the Manager] [release:: MVP]
 High-level status cards showing release progress.
 
-> release Beta
 
-#### Filter by release [status:: in-progress] [persona:: Margie the Manager] [deadline:: 2026-04-15]
+#### Filter by release [status:: in-progress] [persona:: Margie the Manager] [deadline:: 2026-04-15] [release:: Beta]
 
-> release GA
 
-#### Filter by persona [status:: not-started] [deadline:: 2026-06-01]
+#### Filter by persona [status:: not-started] [deadline:: 2026-06-01] [release:: GA]
 
-#### Filter by status [status:: not-started] [deadline:: 2026-06-01]
+#### Filter by status [status:: not-started] [deadline:: 2026-06-01] [release:: GA]
 
 ### Export
 
-#### Export to PDF [status:: in-progress] [persona:: Margie the Manager] [deadline:: 2026-04-30]
+#### Export to PDF [status:: in-progress] [persona:: Margie the Manager] [deadline:: 2026-04-30] [release:: GA]
 One-click PDF export of the current story map view.
 
-> release MVP
 
-#### Export to CSV [status:: not-started] [persona:: Dave the Developer] [deadline:: 2026-06-01]
+#### Export to CSV [status:: not-started] [persona:: Dave the Developer] [deadline:: 2026-06-01] [release:: MVP]
 Machine-readable export for backlog import into Jira or GitHub.
 
-> release Beta
 
-#### Export to PNG [status:: not-started] [deadline:: 2026-09-01]
+#### Export to PNG [status:: not-started] [deadline:: 2026-09-01] [release:: Beta]
 
 ## Notifications
 
 ### Email Notifications
 
-#### Notify on story status change [status:: not-started] [persona:: Margie the Manager]
+#### Notify on story status change [status:: not-started] [persona:: Margie the Manager] [release:: Beta]
 
-> release GA
 
-#### Daily digest [status:: not-started] [persona:: Margie the Manager] [deadline:: 2026-06-01]
+#### Daily digest [status:: not-started] [persona:: Margie the Manager] [deadline:: 2026-06-01] [release:: GA]
 Optional daily summary email of changes since last digest.
 
-> release MVP
 
-#### Notify on blocked stories [status:: not-started] [deadline:: 2026-09-01]
+#### Notify on blocked stories [status:: not-started] [deadline:: 2026-09-01] [release:: MVP]
 Alert assigned persona when a story is marked as blocked.
 
 ### In-app Notifications
 
-#### Show notification badge [status:: blocked]
+#### Show notification badge [status:: blocked] [release:: MVP]
 Blocked by front-end architecture decision on state management.
 See [issue #99](https://github.com/org/repo/issues/99)
 
-> release Beta
 
-#### Mark notifications as read [status:: not-started] [deadline:: 2026-06-01]
+#### Mark notifications as read [status:: not-started] [deadline:: 2026-06-01] [release:: Beta]
 
-> release GA
 
-#### Notification preferences [status:: not-started] [deadline:: 2026-09-01]
+#### Notification preferences [status:: not-started] [deadline:: 2026-09-01] [release:: GA]

storymap/cli.py

@@ -37,13 +37,13 @@
     ### Task              — column
     #### Story [key:: val] — card; supported fields:
                              [status:: not-started | in-progress | done | blocked]
+                             [release:: Release Name]   ← assigns story to a swimlane
                              [persona:: Persona Name]
                              [deadline:: YYYY-MM-DD]
 
-  Use > release on its own line to advance to the next release swimlane.
-  You can annotate it for readability — the text after "release" is ignored:
-    > release Beta
-    > release end of sprint 3
+  Each story is assigned to a release swimlane via [release:: name].
+  The name must match a release defined in # Releases.
+  Stories without a [release::] field are parsed but not shown in any swimlane.
 -->
 
 # My Product
@@ -75,17 +75,15 @@
 
 ### Main Task
 
-#### First story [status:: done] [persona:: Alice the User]
+#### First story [status:: done] [persona:: Alice the User] [release:: MVP]
 Describe what this story delivers.
 
-> release Beta
-
-#### Second story [status:: in-progress] [deadline:: 2026-06-01]
+#### Second story [status:: in-progress] [deadline:: 2026-06-01] [release:: Beta]
 Describe what this story delivers.
 
 ### Another Task
 
-#### A story [status:: not-started]
+#### A story [status:: not-started] [release:: MVP]
 """
 
 
@@ -194,6 +192,7 @@ def render(
             template_path=template_path,
             status_colors=status_colors or None,
             ui_colors=ui_colors or None,
+            source_dir=input_file.parent,
         )
     except Exception as e:
         raise click.ClickException(f"Failed to render: {e}")