@seanyao/roll 2026.524.2 → 2026.526.1

package/lib/roll-loop-status.py

@@ -52,6 +52,11 @@ from roll_render import (
 # Paths — must match bin/roll's _project_slug + _SHARED_ROOT defaults
 # ════════════════════════════════════════════════════════════════════════════
 def project_slug(path: Optional[str] = None) -> str:
+    # US-LOOP-006: cycle wrapper exports ROLL_MAIN_SLUG — honour it.
+    env_slug = os.environ.get("ROLL_MAIN_SLUG", "").strip()
+    if env_slug:
+        return env_slug
+
     path = os.path.realpath(path or os.getcwd())
     try:  # resolve git worktree → main tree (FIX-034 in bin/roll)
         common = subprocess.check_output(
@@ -62,10 +67,57 @@ def project_slug(path: Optional[str] = None) -> str:
             path = common[:-5]
     except Exception:
         pass
+
+    # US-OBS-010: derive slug from git remote URL for stable cross-machine
+    # identity.  Normalize: strip .git, git@HOST:PATH → https://HOST/PATH,
+    # lowercase.  Fallback chain: origin → first remote → path-based.
+    remote_url = _git_remote_url(path)
+    if remote_url:
+        # Normalize
+        remote_url = remote_url.rstrip("/")
+        if remote_url.endswith(".git"):
+            remote_url = remote_url[:-4]
+        m = re.match(r"^git@([^:]+):(.+)$", remote_url)
+        if m:
+            remote_url = f"https://{m.group(1)}/{m.group(2)}"
+        remote_url = remote_url.lower()
+        base = re.sub(r"[^A-Za-z0-9]+", "-", os.path.basename(remote_url)).strip("-")
+        h = hashlib.md5(remote_url.encode()).hexdigest()[:6]
+        return f"{base}-{h}"
+
     base = re.sub(r"[^A-Za-z0-9]+", "-", os.path.basename(path)).strip("-")
     h = hashlib.md5(path.encode()).hexdigest()[:6]
     return f"{base}-{h}"
 
+
+def _git_remote_url(repo_path: str) -> Optional[str]:
+    """Return the normalized remote URL for a git repo, or None."""
+    try:
+        url = subprocess.check_output(
+            ["git", "-C", repo_path, "remote", "get-url", "origin"],
+            stderr=subprocess.DEVNULL, text=True
+        ).strip()
+        if url:
+            return url
+    except Exception:
+        pass
+    # Fallback: first available remote
+    try:
+        remotes = subprocess.check_output(
+            ["git", "-C", repo_path, "remote"],
+            stderr=subprocess.DEVNULL, text=True
+        ).strip().splitlines()
+        if remotes:
+            url = subprocess.check_output(
+                ["git", "-C", repo_path, "remote", "get-url", remotes[0]],
+                stderr=subprocess.DEVNULL, text=True
+            ).strip()
+            if url:
+                return url
+    except Exception:
+        pass
+    return None
+
 def shared_root() -> Path:
     return Path(os.environ.get("ROLL_SHARED_ROOT") or os.path.expanduser("~/.shared/roll"))
 
@@ -73,23 +125,39 @@ def shared_root() -> Path:
 # Loaders
 # ════════════════════════════════════════════════════════════════════════════
 def load_events(slug: str, days: int) -> List[Dict[str, Any]]:
-    path = shared_root() / "loop" / f"events-{slug}.ndjson"
-    if not path.exists():
+    # US-LOOP-023: read the head NDJSON plus its rotated siblings .1..4.
+    # bin/roll rotates events-<slug>.ndjson at 10MB keeping 4 archives; without
+    # this loop the dashboard silently dropped any cycle whose events landed in
+    # a rotated file (the "永久留存" promise of US-LOOP-004 only held on disk).
+    head = shared_root() / "loop" / f"events-{slug}.ndjson"
+    candidates = [head] + [head.with_suffix(f".ndjson.{i}") for i in range(1, 5)]
+    existing = [p for p in candidates if p.exists()]
+    if not existing:
         return []
     cutoff = datetime.now(timezone.utc) - timedelta(days=days + 1)  # +1 for grace
     out: List[Dict[str, Any]] = []
-    with path.open() as f:
-        for line in f:
-            line = line.strip()
-            if not line:
-                continue
-            try:
-                e = json.loads(line)
-                e["_ts"] = datetime.fromisoformat(e["ts"].replace("Z", "+00:00"))
-                if e["_ts"] >= cutoff:
-                    out.append(e)
-            except Exception:
-                continue
+    seen: set[str] = set()  # dedup on the raw JSON line (rotation is mv, so
+                            # duplicates only appear from manual ops — defensive)
+    for p in existing:
+        with p.open() as f:
+            for line in f:
+                line = line.strip()
+                if not line:
+                    continue
+                if line in seen:
+                    continue
+                seen.add(line)
+                try:
+                    e = json.loads(line)
+                    e["_ts"] = datetime.fromisoformat(e["ts"].replace("Z", "+00:00"))
+                    if e["_ts"] >= cutoff:
+                        out.append(e)
+                except Exception:
+                    continue
+    out.sort(key=lambda e: e["_ts"])
+    if os.environ.get("ROLL_DEBUG_LOAD"):
+        print(f"roll-loop-status: loaded {len(out)} events from {len(existing)} files",
+              file=sys.stderr)
     return out
 
 # cron.log entry format (from bin/roll):
@@ -587,6 +655,57 @@ def bucket_by_day(cycles: List[Dict[str, Any]]) -> Dict[str, List[Dict[str, Any]
         out[day].append(cy)
     return out
 
+def rollup_for_story(cycles: List[Dict[str, Any]], story_id: str) -> Dict[str, Any]:
+    """US-LOOP-024: aggregate cycles belonging to a single story.
+
+    Case-insensitive match on cy["story"]. Sums duration / tokens / cost,
+    splits outcomes into ✓ (done|idle) / ✗ (fail) / ⏵ (running), collects
+    PR landings, captures the model from the first matching cycle.
+    """
+    sid_lower = (story_id or "").lower()
+    matched = [cy for cy in cycles if (cy.get("story") or "").lower() == sid_lower]
+    r: Dict[str, Any] = {
+        "story_id": story_id,
+        "cycles": matched,
+        "count": len(matched),
+        "ok_count": 0, "fail_count": 0, "running_count": 0,
+        "span_start": None, "span_end": None,
+        "duration_s": 0, "cost": 0.0,
+        "input_tokens": 0, "output_tokens": 0,
+        "cache_creation_tokens": 0, "cache_read_tokens": 0,
+        "prs": [], "model": None,
+    }
+    for cy in matched:
+        outcome = cy.get("outcome") or ""
+        if outcome == "fail":
+            r["fail_count"] += 1
+        elif outcome == "running":
+            r["running_count"] += 1
+        else:
+            r["ok_count"] += 1
+        if cy.get("start"):
+            if r["span_start"] is None or cy["start"] < r["span_start"]:
+                r["span_start"] = cy["start"]
+        if cy.get("end"):
+            if r["span_end"] is None or cy["end"] > r["span_end"]:
+                r["span_end"] = cy["end"]
+        if cy.get("duration_s"):
+            r["duration_s"] += cy["duration_s"]
+        for tk in ("input_tokens", "output_tokens",
+                   "cache_creation_tokens", "cache_read_tokens"):
+            if cy.get(tk):
+                r[tk] += cy[tk]
+        if cy.get("cost_list") is not None:
+            r["cost"] += cy["cost_list"]
+        elif cy.get("cron"):
+            r["cost"] += cy["cron"]["cost"]
+        if cy.get("pr_num"):
+            r["prs"].append({"num": cy["pr_num"],
+                             "outcome": cy.get("pr_outcome") or "open"})
+        if cy.get("model") and not r["model"]:
+            r["model"] = cy["model"]
+    return r
+
 def rollup_for_day(day_cycles: List[Dict[str, Any]]) -> Dict[str, Any]:
     # US-VIEW-012: track input + output separately so the daily summary can
     # show two metric rows. cache_read tokens deliberately excluded — they're
@@ -812,6 +931,56 @@ def render(events, cron, state, backlog, *, days=3, lang="both", now=None,
           c("muted", "       ") +
           c("dim", "more   ") + c("blue", "roll loop status --days 7"))
 
+# US-LOOP-013: valid schedule periods (must divide 60)
+_VALID_SCHEDULE_PERIODS = {60, 30, 20, 15, 12, 10, 6, 5}
+
+
+def _schedule_valid(period: int, offset: int) -> bool:
+    """Validate schedule spec: period must divide 60, offset in [0, period)."""
+    return period in _VALID_SCHEDULE_PERIODS and 0 <= offset < period
+
+
+def _read_schedule_spec(project_root: Optional[Path] = None) -> Tuple[int, int]:
+    """US-LOOP-013: read loop schedule spec, mirroring bin/roll's _loop_schedule_spec.
+
+    Returns (period_minutes, offset_minute).
+    Priority: .roll/local.yaml → ~/.roll/config.yaml → default (60, hash-derived)
+    """
+    project_root = (project_root or Path()).resolve()
+
+    # 1. Try project-level .roll/local.yaml
+    local_file = project_root / ".roll" / "local.yaml"
+    if local_file.exists():
+        try:
+            text = local_file.read_text(errors="ignore")
+            # Parse loop_schedule block: loop_schedule:\n  period_minutes: N\n  offset_minute: N
+            period_m = re.search(r'period_minutes:\s*(\d+)', text)
+            offset_m = re.search(r'offset_minute:\s*(\d+)', text)
+            if period_m and offset_m:
+                period = int(period_m.group(1))
+                offset = int(offset_m.group(1))
+                if _schedule_valid(period, offset):
+                    return (period, offset)
+        except Exception:
+            pass
+
+    # 2. Try global ~/.roll/config.yaml loop_minute (backward compat)
+    config_file = Path(os.path.expanduser("~/.roll/config.yaml"))
+    if config_file.exists():
+        try:
+            text = config_file.read_text(errors="ignore")
+            m = re.search(r'^loop_minute:\s*(\d+)', text, re.MULTILINE)
+            if m:
+                offset = int(m.group(1))
+                return (60, offset)
+        except Exception:
+            pass
+
+    # 3. Default: derive offset from project path hash (matches bin/roll)
+    h = int(hashlib.md5(str(project_root).encode()).hexdigest()[:2], 16) % 60
+    return (60, h)
+
+
 def _read_plist_loop_minute() -> int:
     """FIX-063: read actual loop Minute from launchd plist (truth source).
     Falls back to 48 only when plist missing/unparseable.
@@ -864,12 +1033,20 @@ def _detect_install_state() -> str:
 
 
 def _next_cron_hint(state: Dict[str, str], zh: bool = False) -> str:
-    """Compute next cron fire time from the actual launchd plist Minute (FIX-063)."""
+    """US-LOOP-013: compute next cron fire time from schedule spec.
+
+    Handles multi-trigger schedules (period < 60) by scanning forward
+    from the current hour's offset minute.
+    """
     now = datetime.now().astimezone()
-    minute_target = _read_plist_loop_minute()
-    nxt = now.replace(minute=minute_target, second=0, microsecond=0)
-    if nxt <= now:
-        nxt += timedelta(hours=1)
+    period, offset = _read_schedule_spec()
+
+    # Start at offset minute within the current hour, then advance
+    # by 'period' minutes until we find a slot after 'now'.
+    nxt = now.replace(minute=offset, second=0, microsecond=0)
+    while nxt <= now:
+        nxt += timedelta(minutes=period)
+
     delta = nxt - now
     mins = int(delta.total_seconds() // 60)
     secs = int(delta.total_seconds() % 60)

package/lib/roll-loop-story.py

@@ -0,0 +1,191 @@
+#!/usr/bin/env python3
+"""
+roll-loop-story — compact per-story rollup for `roll loop story <ID>`.
+
+Loads the same event / cron / runs / git-merge sources as roll-loop-status,
+filters cycles to one story id (case-insensitive), and renders a single
+panel covering cycles count, span, duration, tokens, cost, model, PR list,
+and recent cycle lines.
+
+Usage:
+  roll loop story US-LOOP-004
+  roll loop story us-loop-004                # case-insensitive
+  roll loop story US-LOOP-004 --json         # machine-readable
+  roll loop story US-LOOP-004 --days 30      # widen window (default 30)
+
+Exit codes:
+  0 — at least one cycle found
+  2 — story id has no cycles in the event window
+"""
+from __future__ import annotations
+import argparse, importlib.util, json, os, sys
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Dict, List
+
+_LIB_DIR = os.path.dirname(os.path.realpath(__file__))
+
+# Reuse the loaders + aggregator from roll-loop-status.py. importlib because the
+# filename has a hyphen and isn't import-safe.
+_spec = importlib.util.spec_from_file_location(
+    "_rls", os.path.join(_LIB_DIR, "roll-loop-status.py")
+)
+rls = importlib.util.module_from_spec(_spec)
+_spec.loader.exec_module(rls)
+
+
+def collect_cycles(days: int) -> List[Dict[str, Any]]:
+    slug = rls.project_slug()
+    events = rls.load_events(slug, days)
+    cron = rls.load_cron_log(slug)
+    runs = rls.load_runs(slug)
+    git_merges = rls.load_pr_merges_from_git(days)
+    cycles = rls.aggregate(events, cron)
+    if runs:
+        rls.merge_runs_into_cycles(cycles, runs)
+    if git_merges:
+        rls.repair_orphan_cycles_from_git(cycles, git_merges)
+    rls.backfill_usage_from_claude_sessions(cycles, slug)
+    return cycles
+
+
+def _outcome_glyph(o: str) -> str:
+    return {"fail": "✗", "running": "⏵", "idle": "·"}.get(o, "✓")
+
+
+def _fmt_dt(dt: datetime) -> str:
+    return dt.astimezone().strftime("%Y-%m-%d %H:%M")
+
+
+def _fmt_dur(s: int) -> str:
+    if not s:
+        return "—"
+    h, rem = divmod(s, 3600)
+    m, _ = divmod(rem, 60)
+    return f"{h}h {m:02d}m" if h else f"{m}m"
+
+
+def _fmt_tokens(n: int) -> str:
+    if not n:
+        return "0"
+    if n >= 1_000_000:
+        return f"{n/1_000_000:.1f}M"
+    if n >= 1_000:
+        return f"{n/1_000:.0f}k"
+    return str(n)
+
+
+def _fmt_pr(p: Dict[str, Any]) -> str:
+    g = {"merged": "✓", "closed": "✗"}.get(p["outcome"], "⏵")
+    return f"#{p['num']} {g}"
+
+
+def render_panel(r: Dict[str, Any], description: str = "") -> str:
+    head = f"── {r['story_id']}"
+    if description:
+        head += f" · {description}"
+    head += " " + "─" * max(0, 78 - len(head))
+
+    cycles = r["cycles"]
+    span = "—"
+    if r.get("span_start") and r.get("span_end"):
+        span = f"{_fmt_dt(r['span_start'])}  →  {_fmt_dt(r['span_end'])}"
+    elif r.get("span_start"):
+        span = f"{_fmt_dt(r['span_start'])}  →  (running)"
+
+    counts = f"  cycles    {r['count']}  (✓ {r['ok_count']}  ✗ {r['fail_count']}  ⏵ {r['running_count']})"
+    line_span = f"  span      {span}"
+    line_dur = (f"  duration  {_fmt_dur(r['duration_s'])}"
+                f"   tokens  in {_fmt_tokens(r['input_tokens'])}"
+                f"  out {_fmt_tokens(r['output_tokens'])}"
+                f"  cache w {_fmt_tokens(r['cache_creation_tokens'])}"
+                f"  r {_fmt_tokens(r['cache_read_tokens'])}")
+    model = r.get("model") or "—"
+    line_cost = f"  cost      ${r['cost']:.2f}    model  {model}"
+
+    prs = r.get("prs") or []
+    line_prs = "  PRs       " + (" ".join(_fmt_pr(p) for p in prs[:8]) if prs else "—")
+
+    # Recent 3 cycles (oldest → newest of the matched set; mirror confirmed layout).
+    recent = sorted(cycles, key=lambda c: c.get("start") or datetime.min.replace(tzinfo=timezone.utc))[-3:]
+    recent_lines: List[str] = []
+    for i, cy in enumerate(recent):
+        label = cy.get("label", "—")
+        glyph = _outcome_glyph(cy.get("outcome", ""))
+        cost = cy.get("cost_list")
+        cost_s = f"${cost:.2f}" if cost is not None else "—"
+        prefix = "  recent   " if i == 0 else "           "
+        recent_lines.append(f"{prefix} {label}  {glyph}  {cost_s}")
+    if not recent_lines:
+        recent_lines.append("  recent    —")
+
+    return "\n".join([head, counts, line_span, line_dur, line_cost, line_prs] + recent_lines)
+
+
+def to_json(r: Dict[str, Any]) -> str:
+    def conv(o: Any) -> Any:
+        if isinstance(o, datetime):
+            return o.astimezone(timezone.utc).isoformat()
+        raise TypeError(f"{type(o)} not serializable")
+
+    payload = {k: v for k, v in r.items() if k != "cycles"}
+    payload["cycles"] = [
+        {
+            "label": cy.get("label"),
+            "start": cy.get("start"),
+            "end": cy.get("end"),
+            "outcome": cy.get("outcome"),
+            "duration_s": cy.get("duration_s"),
+            "input_tokens": cy.get("input_tokens"),
+            "output_tokens": cy.get("output_tokens"),
+            "cache_creation_tokens": cy.get("cache_creation_tokens"),
+            "cache_read_tokens": cy.get("cache_read_tokens"),
+            "cost_list": cy.get("cost_list"),
+            "model": cy.get("model"),
+            "pr_num": cy.get("pr_num"),
+            "pr_outcome": cy.get("pr_outcome"),
+        }
+        for cy in r.get("cycles", [])
+    ]
+    return json.dumps(payload, default=conv, indent=2)
+
+
+def _backlog_description(story_id: str) -> str:
+    bl = rls.load_backlog()
+    return bl.get(story_id.upper(), "")
+
+
+def main(argv=None) -> int:
+    p = argparse.ArgumentParser(
+        description="roll loop story — per-story cycle rollup")
+    p.add_argument("story_id", help="Story ID (case-insensitive, e.g. US-LOOP-004)")
+    p.add_argument("--days", type=int, default=30,
+                   help="event window in days (default 30)")
+    p.add_argument("--json", action="store_true",
+                   help="emit machine-readable JSON instead of the panel")
+    args = p.parse_args(argv)
+
+    cycles = collect_cycles(args.days)
+    r = rls.rollup_for_story(cycles, args.story_id)
+
+    if args.json:
+        print(to_json(r))
+        return 0 if r["count"] > 0 else 2
+
+    if r["count"] == 0:
+        sys.stderr.write(
+            f"roll loop story: no cycles found for {args.story_id} "
+            f"in the last {args.days} days\n"
+            f"未找到 {args.story_id} 在最近 {args.days} 天内的循环\n"
+        )
+        return 2
+
+    print(render_panel(r, _backlog_description(args.story_id.upper())))
+    return 0
+
+
+if __name__ == "__main__":
+    try:
+        sys.exit(main())
+    except BrokenPipeError:
+        pass

package/lib/roll_render.py

@@ -88,6 +88,17 @@ def fmt_dur(s: int) -> str:
         return f"{s // 60}m"
     return f"{s // 3600}h {(s % 3600) // 60}m"
 
+# FIX-121: agent → primary model used by `roll loop` dashboard's fallback
+# when an event stream lacks an explicit model name (non-claude agents'
+# stdout isn't stream-json so loop-fmt can't extract model). Keeps the
+# model column consistent with claude's "opus-4-7" style.
+_AGENT_PRIMARY_MODEL = {
+    "pi":       "deepseek-v4-pro",
+    "deepseek": "deepseek-v4-pro",
+    "kimi":     "kimi-k2-0905",
+}
+
+
 def fmt_model(model) -> str:
     """Short label for the cycle row's model column.
 
@@ -339,8 +350,11 @@ def cycle_row(cy: Dict[str, Any], backlog: Dict[str, str]) -> None:
     # FIX-119: fall back to cy["agent"] (from agent_used event) when model
     # is unknown — non-claude agents (pi, deepseek, kimi) don't expose model
     # info in stream-json, leaving a "—" or "?" on the dashboard.
+    # FIX-121: map agent → its configured primary model so the column shows
+    # the actual model name (e.g. "deepseek-v4-pro") consistently with
+    # claude's "opus-4-7", not the bare agent name ("pi").
     if model_label in ("—", "?") and cy.get("agent"):
-        model_label = cy["agent"]
+        model_label = _AGENT_PRIMARY_MODEL.get(cy["agent"], cy["agent"])
     # Auto-hide model column on narrow screens — keeps the dashboard readable
     # when terminal is < 100 cols (cost / story IDs are higher-priority).
     show_model = COLS >= 100

package/lib/slides/components/README.md

@@ -0,0 +1,117 @@
+# Slide Components Library
+
+Reusable Mustache partials for slide layouts. Each partial is a self-contained
+HTML fragment consumed by `lib/slides-render.py`. Partials use CSS classes from
+the introduction-v3 template and require no additional stylesheets.
+
+## Layout Reference
+
+| Layout      | Partial File       | Use When                                   | Avoid When                          |
+|-------------|--------------------|--------------------------------------------|-------------------------------------|
+| `plain`     | `plain.html`       | Free-form text, no structure needed        | Data has compare / flow / timeline  |
+| `cards-2`   | `cards-2.html`     | 2 parallel concepts, side-by-side feature  | 3+ items (use cards-3/cards-4)      |
+| `cards-3`   | `cards-3.html`     | 3 pillars, triple option, 3-step summary   | 2 items (use cards-2)               |
+| `cards-4`   | `cards-4.html`     | 4 quadrants, pricing tiers, team roles     | <4 items (too sparse)               |
+| `compare`   | `compare.html`     | Before/after, problem/solution, old/new    | Unrelated items (use cards)         |
+| `pipeline`  | `pipeline.html`    | Sequential flow, CI/CD, process steps      | Unordered items (use cards)         |
+| `timeline`  | `timeline.html`    | Chronological events, history, roadmap     | Single event (use highlight)        |
+| `quote`     | `quote.html`       | Testimonial, key takeaway, memorable line  | Multi-paragraph prose (use plain)   |
+| `highlight` | `highlight.html`   | Callout, warning, important note           | Normal body text (use plain)        |
+
+## Field Tables
+
+### cards-2 / cards-3 / cards-4
+
+| Variable        | Required | Type   | Description                     |
+|-----------------|----------|--------|---------------------------------|
+| `cards`         | yes      | array  | Array of card objects           |
+| `cards[].title_en` | yes   | string | Card title (English)            |
+| `cards[].title_zh` | yes   | string | Card title (Chinese)            |
+| `cards[].body_en`  | yes   | string | Card body HTML (English, raw)   |
+| `cards[].body_zh`  | yes   | string | Card body HTML (Chinese, raw)   |
+| `accent_color`  | no       | string | Unused — reserved for future    |
+
+### compare
+
+| Variable             | Required | Type   | Description                     |
+|----------------------|----------|--------|---------------------------------|
+| `left_title_en`      | yes      | string | Left column heading (EN)        |
+| `left_title_zh`      | yes      | string | Left column heading (ZH)        |
+| `right_title_en`     | yes      | string | Right column heading (EN)       |
+| `right_title_zh`     | yes      | string | Right column heading (ZH)       |
+| `left_items`         | yes      | array  | Left column items               |
+| `left_items[].text_en` | yes    | string | Item text (EN)                  |
+| `left_items[].text_zh` | yes    | string | Item text (ZH)                  |
+| `right_items`        | yes      | array  | Right column items              |
+| `right_items[].text_en` | yes   | string | Item text (EN)                  |
+| `right_items[].text_zh` | yes   | string | Item text (ZH)                  |
+
+### pipeline
+
+| Variable            | Required | Type   | Description                     |
+|---------------------|----------|--------|---------------------------------|
+| `stages`            | yes      | array  | Pipeline stages in order        |
+| `stages[].title_en` | yes      | string | Stage title (EN)                |
+| `stages[].title_zh` | yes      | string | Stage title (ZH)                |
+| `stages[].desc_en`  | yes      | string | Stage description (EN)          |
+| `stages[].desc_zh`  | yes      | string | Stage description (ZH)          |
+| `stages[].css_class` | yes     | string | CSS class: `pipe-idea`, `pipe-backlog`, `pipe-build`, `pipe-verify`, or `pipe-release` |
+
+### timeline
+
+| Variable            | Required | Type   | Description                     |
+|---------------------|----------|--------|---------------------------------|
+| `items`             | yes      | array  | Timeline entries (chronological)|
+| `items[].title_en`  | yes      | string | Entry title (EN)                |
+| `items[].title_zh`  | yes      | string | Entry title (ZH)                |
+| `items[].body_en`   | yes      | string | Entry body HTML (EN, raw)       |
+| `items[].body_zh`   | yes      | string | Entry body HTML (ZH, raw)       |
+
+### quote
+
+| Variable  | Required | Type   | Description                     |
+|-----------|----------|--------|---------------------------------|
+| `text_en` | yes      | string | Quote text (EN)                 |
+| `text_zh` | yes      | string | Quote text (ZH)                 |
+
+### highlight
+
+| Variable  | Required | Type   | Description                     |
+|-----------|----------|--------|---------------------------------|
+| `body_en` | yes      | string | Body HTML (EN, raw)             |
+| `body_zh` | yes      | string | Body HTML (ZH, raw)             |
+
+### plain
+
+| Variable  | Required | Type   | Description                     |
+|-----------|----------|--------|---------------------------------|
+| `body_en` | yes      | string | Body HTML (EN, raw)             |
+| `body_zh` | yes      | string | Body HTML (ZH, raw)             |
+
+## CSS Classes
+
+Every class name in these partials is copied verbatim from the introduction-v3
+template (`lib/slides/templates/introduction-v3.html`). Do **not** introduce
+new class names — the template's CSS is the single source of truth.
+
+## Usage
+
+Partials are consumed by `lib/slides-render.py` when a `deck.md` slide declares
+a `layout` field (US-DECK-017). Until then, all partials render the same
+`plain` layout by default.
+
+```markdown
+### Slide 3: Architecture Overview
+
+layout: cards-3
+title_en: Three Layers
+title_zh: 三层架构
+
+body_en: |
+  1. {{#cards}}...{{/cards}}
+body_zh: |
+  1. {{#cards}}...{{/cards}}
+```
+
+The renderer inlines the partial's HTML into the template and resolves
+Mustache variables and sections from the slide context.

package/lib/slides/components/cards-2.html

@@ -0,0 +1,9 @@
+<!-- cards-2: requires cards[].{title_en,title_zh,body_en,body_zh}, optional accent_color -->
+<div class="cards cards-2">
+{{#cards}}
+<div class="card">
+<h3><span class="lang-en">{{title_en}}</span><span class="lang-zh">{{title_zh}}</span></h3>
+<p><span class="lang-en">{{{body_en}}}</span><span class="lang-zh">{{{body_zh}}}</span></p>
+</div>
+{{/cards}}
+</div>

package/lib/slides/components/cards-3.html

@@ -0,0 +1,9 @@
+<!-- cards-3: requires cards[].{title_en,title_zh,body_en,body_zh}, optional accent_color -->
+<div class="cards cards-3">
+{{#cards}}
+<div class="card">
+<h3><span class="lang-en">{{title_en}}</span><span class="lang-zh">{{title_zh}}</span></h3>
+<p><span class="lang-en">{{{body_en}}}</span><span class="lang-zh">{{{body_zh}}}</span></p>
+</div>
+{{/cards}}
+</div>

package/lib/slides/components/cards-4.html

@@ -0,0 +1,9 @@
+<!-- cards-4: requires cards[].{title_en,title_zh,body_en,body_zh}, optional accent_color -->
+<div class="cards cards-4">
+{{#cards}}
+<div class="card">
+<h3><span class="lang-en">{{title_en}}</span><span class="lang-zh">{{title_zh}}</span></h3>
+<p><span class="lang-en">{{{body_en}}}</span><span class="lang-zh">{{{body_zh}}}</span></p>
+</div>
+{{/cards}}
+</div>

package/lib/slides/components/compare.html

@@ -0,0 +1,22 @@
+<!-- compare: requires left_title_en,left_title_zh,right_title_en,right_title_zh, left_items[].{text_en,text_zh}, right_items[].{text_en,text_zh} -->
+<div class="compare">
+<div class="compare-col compare-before">
+<h3><span class="lang-en">{{left_title_en}}</span><span class="lang-zh">{{left_title_zh}}</span></h3>
+{{#left_items}}
+<div class="compare-item">
+<span class="icon">✗</span>
+<span class="lang-en">{{text_en}}</span><span class="lang-zh">{{text_zh}}</span>
+</div>
+{{/left_items}}
+</div>
+<div class="compare-arrow">→</div>
+<div class="compare-col compare-after">
+<h3><span class="lang-en">{{right_title_en}}</span><span class="lang-zh">{{right_title_zh}}</span></h3>
+{{#right_items}}
+<div class="compare-item">
+<span class="icon">✓</span>
+<span class="lang-en">{{text_en}}</span><span class="lang-zh">{{text_zh}}</span>
+</div>
+{{/right_items}}
+</div>
+</div>

package/lib/slides/components/highlight.html

@@ -0,0 +1,9 @@
+<!-- highlight: requires body_en (raw HTML), body_zh (raw HTML) -->
+<div class="highlight-box">
+<div class="lang-en">
+{{{body_en}}}
+</div>
+<div class="lang-zh">
+{{{body_zh}}}
+</div>
+</div>