@seanyao/roll 2026.529.5 → 2026.601.2

package/lib/slides-render.py

@@ -99,6 +99,12 @@ def _coerce_scalar(v: str):
     return v
 
 
+# Keys whose `- item` children are always flat scalar strings, never coerced
+# into mappings even when an item contains a colon (e.g. `evidence:` citations
+# like `- TODO: see README.md:1`).
+_SCALAR_LIST_KEYS = ("evidence",)
+
+
 # A slide section starts at a line matching `^## Slide \d+` and continues
 # until the next such line or EOF.
 _SLIDE_HEADER_RE = re.compile(r"^##\s+Slide\s+(\d+)\s*$")
@@ -188,21 +194,21 @@ def _populate_slide(slide: dict, content_lines: list[str]) -> None:
                 block.pop()
             slide[key] = "\n".join(block) + "\n" if block else ""
         elif val == "":
-            # Could be `evidence:` list or an empty scalar.
-            list_items: list[str] = []
-            j = i + 1
-            while j < n:
-                bl = content_lines[j]
-                if bl.strip() == "":
-                    j += 1
-                    continue
-                if bl.lstrip().startswith("- "):
-                    list_items.append(bl.lstrip()[2:].strip())
-                    j += 1
-                    continue
-                break
-            if list_items:
-                slide[key] = list_items
+            # A bare `key:` introduces an indented child block, which may be:
+            #   - a list of scalars      (`- one.md:1`)        -> list[str]
+            #   - a list of mappings     (`- title_en: "..."`) -> list[dict]
+            #   - a nested mapping       (`  left_title_en: …`) -> dict
+            # or, if no indented child follows, an empty scalar.
+            key_indent = len(raw) - len(raw.lstrip(" "))
+            block, j = _collect_indented_block(content_lines, i + 1, key_indent)
+            if block:
+                # `evidence` is always a flat list of free-form citation
+                # strings (e.g. `- TODO: see README.md:1`), so it must never be
+                # coerced into a mapping by the generic block parser.
+                if key in _SCALAR_LIST_KEYS:
+                    slide[key] = _parse_scalar_list(block)
+                else:
+                    slide[key] = _parse_block(block)
                 i = j
             else:
                 slide[key] = ""
@@ -212,6 +218,207 @@ def _populate_slide(slide: dict, content_lines: list[str]) -> None:
             i += 1
 
 
+def _collect_indented_block(
+    lines: list[str], start: int, parent_indent: int
+) -> tuple[list[str], int]:
+    """
+    Gather lines that belong to the indented child block of a `key:` at
+    `parent_indent`. A line belongs to the block if it is blank or indented
+    strictly deeper than the parent key. Returns (block_lines, next_index).
+
+    Trailing blank lines are dropped so an all-blank block reads as empty.
+    """
+    block: list[str] = []
+    j = start
+    n = len(lines)
+    while j < n:
+        bl = lines[j]
+        if bl.strip() == "":
+            block.append("")
+            j += 1
+            continue
+        indent = len(bl) - len(bl.lstrip(" "))
+        if indent <= parent_indent:
+            break
+        block.append(bl)
+        j += 1
+    while block and block[-1] == "":
+        block.pop()
+    return block, j
+
+
+def _parse_block(block: list[str]):
+    """
+    Parse an indented YAML-subset block into a list or a dict.
+
+    - If the first non-blank line starts with `- `, the block is a sequence.
+      Each `- ` opens a new item; a scalar follows `- ` directly (list of
+      scalars) or a `key: value` does (list of mappings, with subsequent
+      deeper-indented `key: value` lines folded into the same item).
+    - Otherwise the block is a mapping of `key: value` / `key:` (nested)
+      entries.
+
+    Scalars are coerced via `_coerce_scalar`. Nested `key:` with no inline
+    value recurse into another block (supports `compare`'s `left_items:`).
+    """
+    # Find the indentation of the block's own top level (first non-blank line).
+    first = next((b for b in block if b.strip() != ""), "")
+    base_indent = len(first) - len(first.lstrip(" "))
+
+    if first.lstrip().startswith("- "):
+        return _parse_sequence(block, base_indent)
+    return _parse_mapping(block, base_indent)
+
+
+def _parse_sequence(block: list[str], base_indent: int) -> list:
+    """Parse a `- ...` sequence at `base_indent` into list[str] | list[dict]."""
+    items: list = []
+    i = 0
+    n = len(block)
+    while i < n:
+        line = block[i]
+        if line.strip() == "":
+            i += 1
+            continue
+        stripped = line.lstrip()
+        # Only treat a `- ` at the sequence's own indent as an item start.
+        indent = len(line) - len(stripped)
+        if indent == base_indent and stripped.startswith("- "):
+            # Strip the dash and ALL following spaces; `content_col` is the
+            # column where the item's first key actually begins, which equals
+            # the indent of the item's continuation lines in well-formed YAML.
+            after_dash = stripped[1:]
+            rest = after_dash.lstrip(" ")
+            content_col = indent + 1 + (len(after_dash) - len(rest))
+            if ":" in rest and not _looks_like_scalar(rest):
+                # List of mappings. Re-indent the inline key to `content_col`
+                # so the sub-block has one consistent base indent regardless of
+                # how the author spaced the `- ` (fixes hardcoded-indent
+                # mis-parse).
+                sub = [(" " * content_col) + rest]
+                i += 1
+                while i < n:
+                    bl = block[i]
+                    if bl.strip() == "":
+                        sub.append("")
+                        i += 1
+                        continue
+                    bi = len(bl) - len(bl.lstrip(" "))
+                    if bi <= base_indent:
+                        break
+                    sub.append(bl)
+                    i += 1
+                items.append(_parse_mapping(sub, content_col))
+            else:
+                items.append(_coerce_scalar(rest.strip()))
+                i += 1
+        else:
+            # Defensive: ignore stray lines that don't open an item.
+            i += 1
+    return items
+
+
+def _parse_mapping(block: list[str], base_indent: int | None = None) -> dict:
+    """Parse `key: value` / `key:` (nested / block-literal) lines into a dict.
+
+    `base_indent` defaults to the indent of the block's first non-blank line so
+    callers need not compute it; only top-level keys at that indent are read,
+    deeper lines are folded into the value of the key they belong to.
+    """
+    out: dict = {}
+    i = 0
+    n = len(block)
+    if base_indent is None:
+        first = next((b for b in block if b.strip() != ""), "")
+        base_indent = len(first) - len(first.lstrip(" "))
+    while i < n:
+        line = block[i]
+        if line.strip() == "" or ":" not in line:
+            i += 1
+            continue
+        indent = len(line) - len(line.lstrip(" "))
+        if indent != base_indent:
+            # Belongs to a deeper structure handled by recursion; skip.
+            i += 1
+            continue
+        key, _, val = line.partition(":")
+        key = key.strip()
+        val = val.strip()
+        if val == "|":
+            block_lines, j = _collect_indented_block(block, i + 1, base_indent)
+            out[key] = _dedent_block_literal(block_lines)
+            i = j
+        elif val == "":
+            child, j = _collect_indented_block(block, i + 1, base_indent)
+            if child:
+                if key in _SCALAR_LIST_KEYS:
+                    out[key] = _parse_scalar_list(child)
+                else:
+                    out[key] = _parse_block(child)
+                i = j
+            else:
+                out[key] = ""
+                i += 1
+        else:
+            out[key] = _coerce_scalar(val)
+            i += 1
+    return out
+
+
+def _dedent_block_literal(block_lines: list[str]) -> str:
+    """Strip the common leading indent of a `key: |` block literal and join the
+    lines, matching the top-level block-literal handling in `_populate_slide`."""
+    out: list[str] = []
+    common_indent: int | None = None
+    for bl in block_lines:
+        if bl.strip() == "":
+            out.append("")
+            continue
+        indent = len(bl) - len(bl.lstrip(" "))
+        if common_indent is None:
+            common_indent = indent
+        elif indent < common_indent:
+            common_indent = indent
+    if common_indent is None:
+        return ""
+    for bl in block_lines:
+        out.append(bl[common_indent:] if bl.strip() != "" else "")
+    while out and out[-1] == "":
+        out.pop()
+    return "\n".join(out) + "\n" if out else ""
+
+
+def _parse_scalar_list(block: list[str]) -> list:
+    """Parse a `- item` sequence as a flat list of scalar strings, regardless of
+    whether an item contains a colon (used for `evidence:` citations)."""
+    items: list = []
+    for line in block:
+        s = line.strip()
+        if s.startswith("- "):
+            items.append(_coerce_scalar(s[2:].strip()))
+    return items
+
+
+def _looks_like_scalar(rest: str) -> bool:
+    """A `- ` item is a scalar (not a mapping) when the text before the first
+    colon looks like a value rather than a bare key — e.g. a path `README.md:42`
+    where the colon is part of the value. Heuristic: it's a mapping only when
+    the segment before the colon is a bare identifier (word chars / underscore)
+    and is immediately followed by a space or end-of-string."""
+    head, sep, tail = rest.partition(":")
+    if not sep:
+        return True
+    head = head.strip()
+    if not head or not re.match(r"^[A-Za-z_][A-Za-z0-9_]*$", head):
+        return True
+    # `key:value` with no space is treated as a scalar (e.g. `README.md:42`
+    # never reaches here since `.` breaks the identifier rule, but a bare
+    # `word:7` would — require a space after the colon for a mapping).
+    if tail and not tail.startswith(" ") and not tail == "":
+        return True
+    return False
+
+
 # ─────────────────────────── Mustache subset ─────────────────────────────────
 
 
@@ -418,6 +625,84 @@ def _inline(text: str) -> str:
     return text
 
 
+# ──────────────────────────── layout routing ────────────────────────────────
+
+
+# The default layout when a slide omits `layout:` — preserves the pre-layout
+# behaviour (a plain lang-en / lang-zh body block).
+DEFAULT_LAYOUT = "plain"
+
+
+class LayoutResolver:
+    """
+    Map a slide's `layout` name to its component partial path.
+
+    Partials live in `lib/slides/components/<layout>.html` next to this module.
+    The resolver does not read the file — it only computes and validates the
+    path so callers get a clear `Unknown layout: ...` error before any I/O.
+    """
+
+    def __init__(self, components_dir: Path | None = None) -> None:
+        if components_dir is None:
+            components_dir = Path(__file__).resolve().parent / "slides" / "components"
+        self.components_dir = components_dir
+
+    def available(self) -> list[str]:
+        """Return the sorted layout names backed by a `<name>.html` partial."""
+        if not self.components_dir.is_dir():
+            return []
+        names = [
+            p.stem
+            for p in self.components_dir.glob("*.html")
+        ]
+        # Locale-independent ordering: plain (the default/fallback) first, then
+        # the rest in plain ASCII sort so the error message is deterministic
+        # across CI locales.
+        rest = sorted(n for n in names if n != DEFAULT_LAYOUT)
+        head = [DEFAULT_LAYOUT] if DEFAULT_LAYOUT in names else []
+        return head + rest
+
+    def resolve(self, layout: str) -> Path:
+        """
+        Return the partial path for `layout`, or raise ValueError with the list
+        of available layouts when no matching partial file exists.
+
+        Layout names are restricted to `[a-z0-9-]+` so a malicious or malformed
+        `layout:` field (e.g. `../../etc/passwd`) can never escape
+        `components_dir` — anything else is reported as an unknown layout.
+        """
+        if not re.fullmatch(r"[a-z0-9-]+", layout):
+            avail = ", ".join(self.available())
+            raise ValueError(f"Unknown layout: {layout}; available: {avail}")
+        path = self.components_dir / f"{layout}.html"
+        if not path.is_file():
+            avail = ", ".join(self.available())
+            raise ValueError(f"Unknown layout: {layout}; available: {avail}")
+        return path
+
+
+def render_slide_inner(slide: dict, resolver: LayoutResolver) -> str:
+    """
+    Resolve the slide's layout to a partial, render that partial against the
+    slide dict, and return the inner HTML to inject into the main template's
+    slide slot.
+
+    The result is stripped of the partial's leading `<!-- ... -->` doc comment
+    and of surrounding blank lines so that, for the default `plain` layout, the
+    output is byte-identical to the pre-layout template body block.
+    """
+    layout = slide.get("layout") or DEFAULT_LAYOUT
+    partial_path = resolver.resolve(layout)
+    partial = partial_path.read_text(encoding="utf-8")
+    # Drop a leading HTML doc comment (the `<!-- layout: requires ... -->`
+    # header every partial carries) so it never leaks into the rendered deck.
+    partial = re.sub(
+        r"\A\s*<!--.*?-->(?:\s*\n)?", "", partial, count=1, flags=re.DOTALL
+    )
+    rendered = mustache(partial, slide)
+    return rendered.strip("\n")
+
+
 # ───────────────────────────── render_deck ──────────────────────────────────
 
 
@@ -429,6 +714,8 @@ def render_deck(deck_path: Path, template_path: Path) -> str:
     fm, body = parse_frontmatter(src)
     slides = parse_slides(body)
 
+    resolver = LayoutResolver()
+
     # Pre-render body_en / body_zh markdown into HTML strings so the template
     # can drop them in via {{{body_en_html}}}.
     for slide in slides:
@@ -437,6 +724,9 @@ def render_deck(deck_path: Path, template_path: Path) -> str:
         # Provide an `evidence` flag for inverted-section use in templates.
         if "evidence" not in slide:
             slide["evidence"] = []
+        # US-DECK-018: route each slide through its layout partial and inject
+        # the result via the main template's {{{slide_inner_html}}} slot.
+        slide["slide_inner_html"] = render_slide_inner(slide, resolver)
 
     context: dict = dict(fm)
     context["slides"] = slides

package/lib/slides-validate.py

@@ -45,6 +45,76 @@ REQUIRED_FRONTMATTER = (
 )
 REQUIRED_SLIDE_KEYS = ("title_en", "title_zh", "body_en", "body_zh")
 
+# Every slide must always carry a bilingual title.
+REQUIRED_TITLE_KEYS = ("title_en", "title_zh")
+
+# ── Layout schema (US-DECK-017) ──────────────────────────────────────────────
+#
+# The default layout (and the implicit layout for slides with no `layout:`
+# field) is `plain`, which keeps the Phase 1.5 `body_en` / `body_zh` contract.
+# Every other layout declares its required fields so the validator can flag a
+# missing field with a concrete line number + an example snippet.
+#
+# Field contracts mirror the Mustache partials shipped by US-DECK-016 in
+# lib/slides/components/<layout>.html — keep the two in sync.
+
+DEFAULT_LAYOUT = "plain"
+
+# scalar required fields per layout (besides the always-required title_en/zh).
+_LAYOUT_SCALAR_FIELDS = {
+    "plain": ("body_en", "body_zh"),
+    "cards-2": (),
+    "cards-3": (),
+    "cards-4": (),
+    "compare": (
+        "left_title_en",
+        "left_title_zh",
+        "right_title_en",
+        "right_title_zh",
+    ),
+    "pipeline": (),
+    "timeline": (),
+    "quote": ("text_en", "text_zh"),
+    "highlight": ("body_en", "body_zh"),
+}
+
+# list-of-mapping required fields: layout -> (list_key, (item_field, ...)).
+_LAYOUT_LIST_FIELDS = {
+    "cards-2": ("cards", ("title_en", "title_zh", "body_en", "body_zh")),
+    "cards-3": ("cards", ("title_en", "title_zh", "body_en", "body_zh")),
+    "cards-4": ("cards", ("title_en", "title_zh", "body_en", "body_zh")),
+    "pipeline": ("stages", ("title_en", "title_zh", "desc_en", "desc_zh")),
+    "timeline": ("items", ("title_en", "title_zh", "body_en", "body_zh")),
+    "compare": ("left_items", ("text_en", "text_zh")),
+}
+# compare also requires a right_items list with the same item shape.
+_LAYOUT_EXTRA_LISTS = {
+    "compare": (("right_items", ("text_en", "text_zh")),),
+}
+
+LAYOUT_WHITELIST = tuple(_LAYOUT_SCALAR_FIELDS.keys())
+
+# Minimal example snippet per layout, shown when a required field is missing.
+_LAYOUT_EXAMPLES = {
+    "cards-2": 'cards:\n  - title_en: "..."\n    title_zh: "..."\n    '
+    'body_en: "..."\n    body_zh: "..."',
+    "cards-3": 'cards:\n  - title_en: "..."\n    title_zh: "..."\n    '
+    'body_en: "..."\n    body_zh: "..."',
+    "cards-4": 'cards:\n  - title_en: "..."\n    title_zh: "..."\n    '
+    'body_en: "..."\n    body_zh: "..."',
+    "compare": 'left_title_en: "..."\nleft_title_zh: "..."\n'
+    'right_title_en: "..."\nright_title_zh: "..."\n'
+    'left_items:\n  - text_en: "..."\n    text_zh: "..."\n'
+    'right_items:\n  - text_en: "..."\n    text_zh: "..."',
+    "pipeline": 'stages:\n  - title_en: "..."\n    title_zh: "..."\n    '
+    'desc_en: "..."\n    desc_zh: "..."',
+    "timeline": 'items:\n  - title_en: "..."\n    title_zh: "..."\n    '
+    'body_en: "..."\n    body_zh: "..."',
+    "quote": 'text_en: "..."\ntext_zh: "..."',
+    "highlight": 'body_en: |\n  ...\nbody_zh: |\n  ...',
+    "plain": 'body_en: |\n  ...\nbody_zh: |\n  ...',
+}
+
 
 def _load_renderer():
     """Import lib/slides-render.py as a module (hyphenated filename, so we
@@ -79,8 +149,34 @@ def validate_frontmatter(fm: dict) -> list[str]:
     return errors
 
 
-def validate_slides(fm: dict, slides: list[dict]) -> list[str]:
+def _slide_header_lines(src: str) -> dict:
+    """Map slide number -> 1-based source line of its `## Slide N` header."""
+    import re
+
+    header_re = re.compile(r"^##\s+Slide\s+(\d+)\s*$")
+    out: dict = {}
+    for idx, line in enumerate(src.splitlines(), start=1):
+        m = header_re.match(line)
+        if m:
+            out[int(m.group(1))] = idx
+    return out
+
+
+def slide_layout(slide: dict) -> str:
+    """Return a slide's declared layout, defaulting to `plain` when absent."""
+    layout = slide.get("layout")
+    if not layout:
+        return DEFAULT_LAYOUT
+    return str(layout)
+
+
+def _is_empty(v) -> bool:
+    return v is None or (isinstance(v, str) and v.strip() == "")
+
+
+def validate_slides(fm: dict, slides: list[dict], line_of: dict | None = None) -> list[str]:
     errors: list[str] = []
+    line_of = line_of or {}
     actual = len(slides)
     declared = fm.get("total_slides")
     if isinstance(declared, int) and declared != actual:
@@ -89,14 +185,98 @@ def validate_slides(fm: dict, slides: list[dict]) -> list[str]:
             f"found {actual} `## Slide N` sections"
         )
     for slide in slides:
-        n = slide.get("number", "?")
-        for key in REQUIRED_SLIDE_KEYS:
-            v = slide.get(key)
-            if v is None or (isinstance(v, str) and v.strip() == ""):
-                errors.append(f"slide {n}: missing or empty {key}")
+        errors += validate_slide_layout(slide, line_of)
+    return errors
+
+
+def validate_slide_layout(slide: dict, line_of: dict | None = None) -> list[str]:
+    """
+    Validate a single slide's required fields for its declared layout.
+
+    - Title fields are always required.
+    - A missing `layout:` is treated as `plain` (no error — backward compat).
+    - An unknown layout name is rejected against the whitelist.
+    - Per-layout scalar + list-of-mapping required fields are checked, with the
+      concrete `deck.md:<line>` location (header line of the slide) and a field
+      example for the layout.
+    """
+    line_of = line_of or {}
+    errors: list[str] = []
+    n = slide.get("number", "?")
+    line = line_of.get(n)
+    loc = f"deck.md:{line}" if line else f"slide {n}"
+
+    # Title is always required regardless of layout.
+    for key in REQUIRED_TITLE_KEYS:
+        if _is_empty(slide.get(key)):
+            errors.append(f"slide {n} ({loc}): missing or empty {key}")
+
+    layout = slide_layout(slide)
+    if layout not in LAYOUT_WHITELIST:
+        errors.append(
+            f"slide {n} ({loc}): unknown layout {layout!r}; "
+            f"allowed: {', '.join(LAYOUT_WHITELIST)}"
+        )
+        return errors
+
+    example = _LAYOUT_EXAMPLES.get(layout, "")
+
+    def missing(field: str) -> None:
+        msg = f"slide {n} ({loc}): layout {layout!r} requires field {field!r}"
+        if example:
+            msg += f"\nHint: example for {layout}:\n{example}"
+        errors.append(msg)
+
+    # Scalar required fields.
+    for field in _LAYOUT_SCALAR_FIELDS.get(layout, ()):
+        if _is_empty(slide.get(field)):
+            missing(field)
+
+    # List-of-mapping required fields.
+    list_specs: list = []
+    if layout in _LAYOUT_LIST_FIELDS:
+        list_specs.append(_LAYOUT_LIST_FIELDS[layout])
+    list_specs += list(_LAYOUT_EXTRA_LISTS.get(layout, ()))
+    for list_key, item_fields in list_specs:
+        items = slide.get(list_key)
+        if not isinstance(items, list) or not items:
+            missing(list_key)
+            continue
+        for idx, item in enumerate(items, start=1):
+            if not isinstance(item, dict):
+                errors.append(
+                    f"slide {n} ({loc}): {list_key}[{idx}] must be a mapping "
+                    f"with {', '.join(item_fields)}"
+                )
+                continue
+            for f in item_fields:
+                if _is_empty(item.get(f)):
+                    errors.append(
+                        f"slide {n} ({loc}): {list_key}[{idx}] missing {f!r}"
+                    )
     return errors
 
 
+def lint_slide_layout(slide: dict) -> list[str]:
+    """
+    Non-fatal layout warnings (returned separately so the caller can print but
+    not fail). Currently: declaring a rich layout while also carrying a stray
+    `body_en` / `body_zh` that the layout will not consume (possible waste).
+    """
+    warnings: list[str] = []
+    layout = slide_layout(slide)
+    if layout in ("plain", "highlight"):
+        return warnings  # these layouts legitimately consume body_en/zh
+    n = slide.get("number", "?")
+    for f in ("body_en", "body_zh"):
+        if not _is_empty(slide.get(f)):
+            warnings.append(
+                f"slide {n}: layout {layout!r} does not use {f!r}; "
+                f"the field will be ignored (possible waste)"
+            )
+    return warnings
+
+
 def evaluate_grounding(slides: list[dict]) -> tuple[int, int, bool]:
     """
     Return (citations, threshold, meets_threshold).
@@ -141,15 +321,23 @@ def main(argv: list[str]) -> int:
         err(f"failed to parse deck.md: {e}", "解析 deck.md 失败")
         return 3
 
+    line_of = _slide_header_lines(src)
+
     schema_errors: list[str] = []
     schema_errors += validate_frontmatter(fm)
-    schema_errors += validate_slides(fm, slides)
+    schema_errors += validate_slides(fm, slides, line_of)
 
     if schema_errors:
         for e in schema_errors:
             err(e)
         return 1
 
+    # Non-fatal layout lint warnings (e.g. a rich layout carrying a stray body
+    # that it will not consume). These print but do not change the exit code.
+    for slide in slides:
+        for w in lint_slide_layout(slide):
+            err(f"⚠️ {w}")
+
     citations, threshold, ok = evaluate_grounding(slides)
     if not ok:
         err(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seanyao/roll",
-  "version": "2026.529.5",
+  "version": "2026.601.2",
   "description": "Roll — Roll out features with AI agents",
   "scripts": {
     "test": "bash tests/run.sh"