r-markdown-cli 0.1.0 → 0.1.2

package/dist/themes/default.css

@@ -548,28 +548,68 @@ body[data-rmd-theme] {
 
 .rmd-timeline-horizontal ol {
   display: flex;
+  flex-wrap: nowrap;
   overflow-x: auto;
-  gap: 20px;
-  padding-bottom: 10px;
+  overflow-y: hidden;
+  gap: 24px;
+  padding-bottom: 12px;
+  /* Treat the ol as a horizontal scroll viewport with explicit snap so
+     each @item lines up nicely when the user scrolls. */
+  scroll-snap-type: x proximity;
+  scrollbar-width: thin;
 }
 
 .rmd-timeline-horizontal .rmd-timeline-item {
-  flex: 0 0 auto;
-  min-width: 200px;
+  /* Cap each item to a predictable width so a single overflowing item
+     can't squeeze siblings out of the visible viewport. Long prose
+     wraps inside the box; the user scrolls horizontally to see the
+     next item. */
+  flex: 0 0 240px;
+  width: 240px;
+  max-width: 240px;
   position: relative;
   padding-top: 28px;
+  scroll-snap-align: start;
+  /* Prevent runaway content (long URLs, code, CJK without spaces) from
+     widening the flex item beyond its declared basis. */
+  min-width: 0;
+  overflow-wrap: anywhere;
+  word-break: break-word;
+}
+
+.rmd-timeline-horizontal .rmd-timeline-content {
+  /* Belt-and-suspenders: cap inner content too, in case authors nest
+     wide blocks (chart, table) inside a timeline item. */
+  max-width: 100%;
+  overflow-wrap: anywhere;
+}
+
+.rmd-timeline-horizontal .rmd-timeline-content pre,
+.rmd-timeline-horizontal .rmd-timeline-content img,
+.rmd-timeline-horizontal .rmd-timeline-content table {
+  max-width: 100%;
 }
 
-.rmd-timeline-horizontal ol::before {
+/* The connector line is drawn per-item (::after) so that it scrolls with
+   the items inside the overflow:auto container. The previous ol::before
+   approach anchored the line to the visible viewport, which made the
+   line stay put while items scrolled past — broken for any timeline
+   wider than the viewport. */
+.rmd-timeline-horizontal .rmd-timeline-item::after {
   position: absolute;
   top: 5px;
-  left: 0;
-  right: 0;
+  left: 6px;
+  /* Extend across the 24px gap to meet the next item's dot. */
+  right: calc(-24px + 6px);
   height: 2px;
   background: var(--rmd-color-line);
   content: "";
 }
 
+.rmd-timeline-horizontal .rmd-timeline-item:last-child::after {
+  display: none;
+}
+
 .rmd-timeline-horizontal .rmd-timeline-item::before {
   position: absolute;
   top: 0;

package/dist/themes/notion-like.css

@@ -548,28 +548,68 @@ body[data-rmd-theme] {
 
 .rmd-timeline-horizontal ol {
   display: flex;
+  flex-wrap: nowrap;
   overflow-x: auto;
-  gap: 20px;
-  padding-bottom: 10px;
+  overflow-y: hidden;
+  gap: 24px;
+  padding-bottom: 12px;
+  /* Treat the ol as a horizontal scroll viewport with explicit snap so
+     each @item lines up nicely when the user scrolls. */
+  scroll-snap-type: x proximity;
+  scrollbar-width: thin;
 }
 
 .rmd-timeline-horizontal .rmd-timeline-item {
-  flex: 0 0 auto;
-  min-width: 200px;
+  /* Cap each item to a predictable width so a single overflowing item
+     can't squeeze siblings out of the visible viewport. Long prose
+     wraps inside the box; the user scrolls horizontally to see the
+     next item. */
+  flex: 0 0 240px;
+  width: 240px;
+  max-width: 240px;
   position: relative;
   padding-top: 28px;
+  scroll-snap-align: start;
+  /* Prevent runaway content (long URLs, code, CJK without spaces) from
+     widening the flex item beyond its declared basis. */
+  min-width: 0;
+  overflow-wrap: anywhere;
+  word-break: break-word;
 }
 
-.rmd-timeline-horizontal ol::before {
+.rmd-timeline-horizontal .rmd-timeline-content {
+  /* Belt-and-suspenders: cap inner content too, in case authors nest
+     wide blocks (chart, table) inside a timeline item. */
+  max-width: 100%;
+  overflow-wrap: anywhere;
+}
+
+.rmd-timeline-horizontal .rmd-timeline-content pre,
+.rmd-timeline-horizontal .rmd-timeline-content img,
+.rmd-timeline-horizontal .rmd-timeline-content table {
+  max-width: 100%;
+}
+
+/* The connector line is drawn per-item (::after) so that it scrolls with
+   the items inside the overflow:auto container. The previous ol::before
+   approach anchored the line to the visible viewport, which made the
+   line stay put while items scrolled past — broken for any timeline
+   wider than the viewport. */
+.rmd-timeline-horizontal .rmd-timeline-item::after {
   position: absolute;
   top: 5px;
-  left: 0;
-  right: 0;
+  left: 6px;
+  /* Extend across the 24px gap to meet the next item's dot. */
+  right: calc(-24px + 6px);
   height: 2px;
   background: var(--rmd-color-line);
   content: "";
 }
 
+.rmd-timeline-horizontal .rmd-timeline-item:last-child::after {
+  display: none;
+}
+
 .rmd-timeline-horizontal .rmd-timeline-item::before {
   position: absolute;
   top: 0;

package/dist/themes/paper.css

@@ -548,28 +548,68 @@ body[data-rmd-theme] {
 
 .rmd-timeline-horizontal ol {
   display: flex;
+  flex-wrap: nowrap;
   overflow-x: auto;
-  gap: 20px;
-  padding-bottom: 10px;
+  overflow-y: hidden;
+  gap: 24px;
+  padding-bottom: 12px;
+  /* Treat the ol as a horizontal scroll viewport with explicit snap so
+     each @item lines up nicely when the user scrolls. */
+  scroll-snap-type: x proximity;
+  scrollbar-width: thin;
 }
 
 .rmd-timeline-horizontal .rmd-timeline-item {
-  flex: 0 0 auto;
-  min-width: 200px;
+  /* Cap each item to a predictable width so a single overflowing item
+     can't squeeze siblings out of the visible viewport. Long prose
+     wraps inside the box; the user scrolls horizontally to see the
+     next item. */
+  flex: 0 0 240px;
+  width: 240px;
+  max-width: 240px;
   position: relative;
   padding-top: 28px;
+  scroll-snap-align: start;
+  /* Prevent runaway content (long URLs, code, CJK without spaces) from
+     widening the flex item beyond its declared basis. */
+  min-width: 0;
+  overflow-wrap: anywhere;
+  word-break: break-word;
 }
 
-.rmd-timeline-horizontal ol::before {
+.rmd-timeline-horizontal .rmd-timeline-content {
+  /* Belt-and-suspenders: cap inner content too, in case authors nest
+     wide blocks (chart, table) inside a timeline item. */
+  max-width: 100%;
+  overflow-wrap: anywhere;
+}
+
+.rmd-timeline-horizontal .rmd-timeline-content pre,
+.rmd-timeline-horizontal .rmd-timeline-content img,
+.rmd-timeline-horizontal .rmd-timeline-content table {
+  max-width: 100%;
+}
+
+/* The connector line is drawn per-item (::after) so that it scrolls with
+   the items inside the overflow:auto container. The previous ol::before
+   approach anchored the line to the visible viewport, which made the
+   line stay put while items scrolled past — broken for any timeline
+   wider than the viewport. */
+.rmd-timeline-horizontal .rmd-timeline-item::after {
   position: absolute;
   top: 5px;
-  left: 0;
-  right: 0;
+  left: 6px;
+  /* Extend across the 24px gap to meet the next item's dot. */
+  right: calc(-24px + 6px);
   height: 2px;
   background: var(--rmd-color-line);
   content: "";
 }
 
+.rmd-timeline-horizontal .rmd-timeline-item:last-child::after {
+  display: none;
+}
+
 .rmd-timeline-horizontal .rmd-timeline-item::before {
   position: absolute;
   top: 0;

package/dist/themes/tech-dark.css

@@ -548,28 +548,68 @@ body[data-rmd-theme] {
 
 .rmd-timeline-horizontal ol {
   display: flex;
+  flex-wrap: nowrap;
   overflow-x: auto;
-  gap: 20px;
-  padding-bottom: 10px;
+  overflow-y: hidden;
+  gap: 24px;
+  padding-bottom: 12px;
+  /* Treat the ol as a horizontal scroll viewport with explicit snap so
+     each @item lines up nicely when the user scrolls. */
+  scroll-snap-type: x proximity;
+  scrollbar-width: thin;
 }
 
 .rmd-timeline-horizontal .rmd-timeline-item {
-  flex: 0 0 auto;
-  min-width: 200px;
+  /* Cap each item to a predictable width so a single overflowing item
+     can't squeeze siblings out of the visible viewport. Long prose
+     wraps inside the box; the user scrolls horizontally to see the
+     next item. */
+  flex: 0 0 240px;
+  width: 240px;
+  max-width: 240px;
   position: relative;
   padding-top: 28px;
+  scroll-snap-align: start;
+  /* Prevent runaway content (long URLs, code, CJK without spaces) from
+     widening the flex item beyond its declared basis. */
+  min-width: 0;
+  overflow-wrap: anywhere;
+  word-break: break-word;
 }
 
-.rmd-timeline-horizontal ol::before {
+.rmd-timeline-horizontal .rmd-timeline-content {
+  /* Belt-and-suspenders: cap inner content too, in case authors nest
+     wide blocks (chart, table) inside a timeline item. */
+  max-width: 100%;
+  overflow-wrap: anywhere;
+}
+
+.rmd-timeline-horizontal .rmd-timeline-content pre,
+.rmd-timeline-horizontal .rmd-timeline-content img,
+.rmd-timeline-horizontal .rmd-timeline-content table {
+  max-width: 100%;
+}
+
+/* The connector line is drawn per-item (::after) so that it scrolls with
+   the items inside the overflow:auto container. The previous ol::before
+   approach anchored the line to the visible viewport, which made the
+   line stay put while items scrolled past — broken for any timeline
+   wider than the viewport. */
+.rmd-timeline-horizontal .rmd-timeline-item::after {
   position: absolute;
   top: 5px;
-  left: 0;
-  right: 0;
+  left: 6px;
+  /* Extend across the 24px gap to meet the next item's dot. */
+  right: calc(-24px + 6px);
   height: 2px;
   background: var(--rmd-color-line);
   content: "";
 }
 
+.rmd-timeline-horizontal .rmd-timeline-item:last-child::after {
+  display: none;
+}
+
 .rmd-timeline-horizontal .rmd-timeline-item::before {
   position: absolute;
   top: 0;

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "r-markdown-cli",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "type": "module",
   "bin": {
     "rmd": "dist/cli.js"
   },
   "files": [
     "dist",
+    "skills",
     "README.md"
   ],
   "workspaces": [

package/skills/claude/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: rich-markdown
+description: Generate Rich Markdown (.rmd) source and self-contained interactive HTML artifacts. Use when the user asks for rmd, Rich Markdown, rich interactive Markdown, token-efficient rich docs, shareable AI documents, charts, sliders, copy/export blocks, flow diagrams, timelines, kanban boards, collapsible details, carousels, embeds, math blocks, comparison reports, PR explainers, tunable prototypes, project status reports, or any rich document that should remain readable as Markdown but render as a polished interactive HTML page.
+---
+
+# Rich Markdown
+
+Use this skill when the user wants a rich, readable, interactive document
+instead of plain Markdown or hand-written HTML. The local renderer
+(`packages/cli`) turns `.rmd` source into a self-contained HTML artifact that
+renders in Claude's chat / desktop sandbox, in any browser, or as an offline file.
+
+## Why .rmd over plain Markdown or HTML
+
+- Source stays close to Markdown — diff-friendly, AI-friendly, low-token.
+- The renderer adds charts, layouts, sliders, exports, flows, timelines, etc.
+  without forcing you to write SVG/CSS/JS.
+- One source file, one self-contained HTML. No external assets needed for
+  Claude-rendered artifacts.
+
+## Output Choice (decide before writing)
+
+| User intent | What to produce |
+|---|---|
+| Wants source only | `.rmd` file, no HTML build |
+| Wants something to view / share / archive | `.rmd` + `--mode self-contained` HTML |
+| Wants smallest artifact + has network | `.rmd` + `--mode cdn` HTML |
+| Wants inspectable assets they can host themselves | `.rmd` + `--mode split` directory |
+| Wants to demo locally during the session | `rmd open` preview server |
+
+When unsure, default to source `.rmd` plus a `self-contained` HTML build.
+
+## Workflow
+
+1. Decide the smallest useful block set from `references/blocks.md`. Use
+   plain Markdown for narrative; use `:::` blocks only when they add density,
+   structure, or interaction.
+
+2. Write the `.rmd` file. Always include a YAML frontmatter with at least
+   `title`. Suggested location: `examples/<short-name>.rmd`.
+
+3. Validate the source with the Bash tool:
+
+   ```bash
+   npm run rmd -- validate path/to/doc.rmd
+   ```
+
+   If validation fails, fix the source. Do not return a file that fails
+   validation.
+
+4. Build the artifact:
+
+   ```bash
+   # Default: single self-contained HTML
+   npm run rmd -- build path/to/doc.rmd --mode self-contained --out path/to/doc.html
+
+   # CDN-loaded variant (small artifact, requires network at view time)
+   npm run rmd -- build path/to/doc.rmd --mode cdn --version 0.1.0 --out path/to/doc.html
+
+   # Split directory (HTML + JS + CSS as separate files)
+   npm run rmd -- build path/to/doc.rmd --mode split --out path/to/dist/index.html
+   ```
+
+5. (Optional) Local preview during the session:
+
+   ```bash
+   npm run rmd -- open path/to/doc.rmd --port 0 --host 127.0.0.1 --no-open true
+   ```
+
+   The CLI prints the bound URL. Use `--no-open true` so the agent does not
+   try to launch a desktop browser.
+
+6. Return the generated HTML file path to the user. If self-contained, the
+   file alone is the deliverable.
+
+## Rules (these are hard constraints)
+
+- **No styling in source.** Never write colors, pixel sizes, fonts, or layout
+  CSS into `.rmd`. Use semantic attributes like `emphasis=primary` and let
+  the theme decide visuals. (Themes can change; source must not.)
+
+- **Diff-clean edits.** One semantic change should touch only nearby lines.
+  Don't reorder unrelated attributes or rewrite a whole file for a small fix.
+
+- **Validate before shipping.** Validation failures are not warnings. Fix
+  the source before returning the artifact.
+
+- **Plain Markdown for fragile content.** Use plain Markdown — code blocks,
+  tables, blockquotes — for anything you're unsure how to express in `.rmd`.
+  Don't invent block names.
+
+- **Self-contained for sandboxes.** If the user will view the artifact inside
+  Claude's sandbox, in email, or anywhere external assets can't be fetched,
+  use `--mode self-contained`. `split` mode will not load in those contexts.
+
+## Block Selection Cheatsheet
+
+Map the user's intent to the smallest block set that delivers value:
+
+| Intent | Blocks |
+|---|---|
+| Compare options / approaches | `grid` + `chart` + `callout` |
+| PR / code review explainer | `diff` + `tabs` + `callout` |
+| Tunable prototype (params + copy back to chat) | `slider` + `export` |
+| Release / workflow | `flow` + `callout` + `timeline` |
+| Project status report | `chart` + `timeline` + `kanban` |
+| Research brief | `chart` + `grid` + `details` |
+| Showcase / gallery | `carousel` + `grid layout=masonry` |
+| Long doc with collapsible appendix | `details` + `tabs` |
+| Math / formal explanation | `math` + `callout` |
+
+The 14 supported blocks (v0.2): `chart`, `grid`, `callout`, `slider`,
+`export`, `flow`, `diff`, `tabs`, `timeline`, `kanban`, `details`, `carousel`,
+`embed`, `math`. Full reference: `references/blocks.md`.
+
+## Default Recipe
+
+For Claude-visible rich output:
+
+1. Write `examples/<short-name>.rmd` with appropriate blocks.
+2. `npm run rmd -- validate examples/<short-name>.rmd`
+3. `npm run rmd -- build examples/<short-name>.rmd --mode self-contained --out examples/<short-name>.html`
+4. Return `examples/<short-name>.html` as the deliverable.
+
+See `examples/` in this skill for two ready-to-study patterns:
+- `examples/decision-report.rmd` — comparison + chart + callout
+- `examples/tunable-config.rmd` — slider + export + flow
+
+## References
+
+- `references/blocks.md` — all 14 block types with attributes and examples
+- `references/artifacts.md` — build modes, validation, frontmatter tips

package/skills/claude/examples/decision-report.rmd

@@ -0,0 +1,64 @@
+---
+title: "Storage Tier Decision Report"
+theme: default
+share: team
+description: "Comparison of hot/warm/cold storage strategies for the analytics pipeline."
+---
+
+# Storage Tier Decision Report
+
+We need to pick a storage strategy for the analytics pipeline that handles
+~3 TB/day. Three candidates evaluated against latency, cost, and operational
+complexity.
+
+## Candidates
+
+:::grid 3
+### Hot only
+All data on NVMe SSD.
+**Pros**: lowest read latency (≈2 ms).
+**Cons**: $$$ per TB; capacity ceiling reached in ~6 months.
+---
+### Tiered (hot + cold)
+Recent 7 days on SSD, older on object storage.
+**Pros**: 70% cost reduction, latency unchanged for typical queries.
+**Cons**: needs lifecycle automation; cold-restore latency 30-60 s.
+---
+### Cold only
+Everything on object storage with index cache.
+**Pros**: cheapest; effectively unlimited.
+**Cons**: P95 read latency 1.5 s, breaks the SLA for live dashboards.
+:::
+
+## Cost vs Latency
+
+:::chart bar title="Monthly cost (k$) vs P95 read latency (ms)" y="cost(k$)" y2="P95(ms)" legend=top
+HotOnly      48 2
+Tiered       14 2
+ColdOnly     3  1500
+:::
+
+## Recommendation
+
+:::callout tip title="Pick Tiered"
+Tiered storage hits the SLA, costs roughly a third of hot-only, and the
+lifecycle automation is a one-time investment we already use for backups.
+:::
+
+## Rollout Plan
+
+:::flow direction=lr
+Spec -> Review -> Migrate cold path -> Enable lifecycle -> Monitor
+Migrate cold path -> Issue -> Pause and audit
+:::
+
+## Risk Register
+
+:::details title="Operational risks and mitigations"
+1. **Cold restore stalls during peak query**: cap concurrent restore jobs;
+   surface a "restoring" badge in the UI so users don't retry.
+2. **Lifecycle policy misfires and deletes hot data**: dry-run mode for first
+   7 days; alert on >1% delta vs expected size.
+3. **Object storage region outage**: keep last 24h of cold data mirrored to a
+   second region; documented failover runbook.
+:::

package/skills/claude/examples/tunable-config.rmd

@@ -0,0 +1,53 @@
+---
+title: "Rate Limiter Config — Tune & Copy"
+theme: default
+share: private
+description: "Adjust the token-bucket parameters and copy the resulting YAML."
+---
+
+# Rate Limiter Config — Tune & Copy
+
+Drag the sliders to tune the token-bucket rate limiter. The export button
+below copies the matching YAML config straight to your clipboard.
+
+## Parameters
+
+:::slider name=capacity label="Bucket capacity" min=10 max=2000 step=10 default=200 unit=req
+:::
+
+:::slider name=refill_rate label="Refill rate" min=1 max=500 step=1 default=50 unit=req/s
+:::
+
+:::slider name=burst_window label="Burst window" min=1 max=120 step=1 default=10 unit=s
+:::
+
+## Generated YAML
+
+:::export label="Copy YAML config" format=text
+rate_limiter:
+  type: token_bucket
+  capacity: {{capacity | int}}
+  refill_rate: {{refill_rate | int}}
+  burst_window_seconds: {{burst_window | int}}
+:::
+
+## How requests flow
+
+:::flow direction=lr
+Request -> Bucket has token? -> Allow
+Bucket has token? -> Refill check -> Allow
+Bucket has token? -> Refill check -> Reject 429
+:::
+
+## Tradeoffs
+
+:::callout warning title="Watch the burst window"
+A wide burst window smooths short spikes but lets sustained overload through
+longer. If your downstream is fragile, prefer narrow windows even at the cost
+of more 429s.
+:::
+
+:::callout tip title="Sane starting point"
+For most APIs, capacity ≈ 4× refill rate, burst window ≈ 10 s. Adjust from
+there based on observed P99 incident shape.
+:::

package/skills/claude/references/artifacts.md

@@ -0,0 +1,118 @@
+# Rich Markdown Artifacts
+
+## Source First
+
+Always write `.rmd` source first. It is the canonical artifact and must remain
+readable in plain Markdown tools. The HTML build is a derived view that can
+be regenerated any time.
+
+## Three Build Modes
+
+The CLI supports three output modes via `--mode`. Pick based on where the
+artifact will be viewed.
+
+### self-contained (default)
+
+```bash
+npm run rmd -- build path/to/doc.rmd --mode self-contained --out path/to/doc.html
+```
+
+Single HTML file with the renderer, theme CSS, runtime, and `.rmd` source all
+inlined. Zero external dependencies. Best for:
+
+- Claude desktop / chat sandbox (the artifact has to be self-contained)
+- Email attachments
+- Offline / archival
+- S3 / static-host one-click sharing
+- Any place where the consumer cannot install or fetch the renderer
+
+Tradeoff: file size is larger (~50–150 KB) because the renderer is inlined.
+
+### cdn
+
+```bash
+npm run rmd -- build path/to/doc.rmd --mode cdn --version 0.1.0 --out path/to/doc.html
+```
+
+Small HTML shell containing only the `.rmd` source plus a script tag pointing
+at a pinned CDN version of the renderer. Best for:
+
+- Blog posts, Notion, web pages where the renderer can be fetched from CDN
+- When the artifact itself must be small (token economy)
+
+Requires `--version` to be a complete semver (e.g. `0.1.0`); `latest` is rejected
+because sandboxed viewers must not depend on a moving CDN target.
+
+### split
+
+```bash
+npm run rmd -- build path/to/doc.rmd --mode split --out path/to/dist/index.html
+```
+
+Writes the HTML alongside `rmd.min.js` and `themes/<theme>.css` as separate
+files in the same directory. Best for:
+
+- Local development / hot reload
+- Custom hosting where you want to serve the renderer from your own origin
+- Inspecting the generated assets
+
+Cannot be opened in sandboxed environments (Claude artifact, email) because
+the relative asset paths will 404.
+
+## Validation
+
+Always validate before building or returning to the user:
+
+```bash
+npm run rmd -- validate path/to/doc.rmd
+```
+
+Validation prints `ok` on success or a list of `path: message` lines on failure.
+If validation fails, fix the source and re-run. Do not ship a file that fails
+validation — the renderer may degrade silently to plain code blocks.
+
+## Recommended Default
+
+For most Claude-driven requests:
+
+```bash
+npm run rmd -- validate examples/my-doc.rmd
+npm run rmd -- build examples/my-doc.rmd --mode self-contained --out examples/my-doc.html
+```
+
+Return the path `examples/my-doc.html`.
+
+## Local Preview During the Session
+
+When the user wants to interact with the artifact while you iterate:
+
+```bash
+npm run rmd -- open path/to/doc.rmd --port 0 --host 127.0.0.1 --no-open true
+```
+
+The CLI prints the bound URL. Use `--no-open true` so the agent does not try
+to launch a desktop browser.
+
+## Frontmatter Tips
+
+Every `.rmd` should start with a frontmatter block. Useful fields:
+
+```yaml
+---
+title: Quarterly Roadmap        # Required for sharing & metadata
+theme: default                  # Theme id; only `default` ships today
+share: private                  # private / team / public
+description: Short summary...   # Used by share cards / OG
+lang: zh-CN                     # BCP 47 — affects type/font defaults
+---
+```
+
+Unknown fields are kept but ignored. Custom fields should use the `x-` prefix
+to mark them as non-core (e.g. `x-team: backend`).
+
+## Iteration Loop
+
+When the user asks for revisions, re-run validate and build only — do not
+rewrite unrelated parts of the source. The skill optimizes for clean diffs;
+preserve the user's existing block structure unless they explicitly ask
+otherwise.