scrolly 0.2.0__tar.gz → 0.2.2__tar.gz

scrolly-0.2.2/LICENSE

@@ -0,0 +1,28 @@
+MIT License
+
+Copyright (c) 2026, Bert Pluymers
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+----
+
+scrolly bundles third-party assets that ship under their own licenses,
+located alongside the asset in the package tree. See for example
+`scrolly/render/assets/mermaid-LICENSE` (MIT — Copyright (c) 2014-2022
+Knut Sveidqvist).

{scrolly-0.2.0 → scrolly-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: scrolly
-Version: 0.2.0
+Version: 0.2.2
 Summary: CLI that compiles a JSON5 deck + slide files into a self-contained 2D-canvas HTML presentation.
 Project-URL: Source, https://github.com/bertpl/scrolly
 Project-URL: Changelog, https://github.com/bertpl/scrolly/blob/main/CHANGELOG.md
@@ -33,6 +33,10 @@ Description-Content-Type: text/markdown
 
 Compile a JSON5 deck into a self-contained, scrollable 2D-canvas HTML presentation.
 
+*Liked by humans; understood by agents.*
+
+[![scrolly — scroll-driven 2D-canvas presentations](https://raw.githubusercontent.com/bertpl/scrolly/main/docs/assets/hero-v1.gif)](https://github.com/bertpl/scrolly)
+
 [![CI](https://img.shields.io/github/actions/workflow/status/bertpl/scrolly/push_to_main.yml?branch=main&label=CI)](https://github.com/bertpl/scrolly/actions/workflows/push_to_main.yml)
 [![PyPI](https://img.shields.io/pypi/v/scrolly.svg)](https://pypi.org/project/scrolly/)
 [![Python](https://img.shields.io/pypi/pyversions/scrolly.svg)](https://pypi.org/project/scrolly/)
@@ -53,11 +57,11 @@ uv tool install scrolly
 ## Quickstart
 
 ```bash
-scrolly build examples/worked-example/deck.deck.json --out /tmp/scrolly-out --force
+scrolly build examples/stacked-diffs/deck.deck.json --out /tmp/scrolly-out --force
 open /tmp/scrolly-out/index.html
 ```
 
-See [`examples/worked-example/`](examples/worked-example/) for a reference deck.
+See [`examples/stacked-diffs/`](examples/stacked-diffs/) for a complete example deck.
 
 ## Source format
 

{scrolly-0.2.0 → scrolly-0.2.2}/README.md

@@ -2,6 +2,10 @@
 
 Compile a JSON5 deck into a self-contained, scrollable 2D-canvas HTML presentation.
 
+*Liked by humans; understood by agents.*
+
+[![scrolly — scroll-driven 2D-canvas presentations](https://raw.githubusercontent.com/bertpl/scrolly/main/docs/assets/hero-v1.gif)](https://github.com/bertpl/scrolly)
+
 [![CI](https://img.shields.io/github/actions/workflow/status/bertpl/scrolly/push_to_main.yml?branch=main&label=CI)](https://github.com/bertpl/scrolly/actions/workflows/push_to_main.yml)
 [![PyPI](https://img.shields.io/pypi/v/scrolly.svg)](https://pypi.org/project/scrolly/)
 [![Python](https://img.shields.io/pypi/pyversions/scrolly.svg)](https://pypi.org/project/scrolly/)
@@ -22,11 +26,11 @@ uv tool install scrolly
 ## Quickstart
 
 ```bash
-scrolly build examples/worked-example/deck.deck.json --out /tmp/scrolly-out --force
+scrolly build examples/stacked-diffs/deck.deck.json --out /tmp/scrolly-out --force
 open /tmp/scrolly-out/index.html
 ```
 
-See [`examples/worked-example/`](examples/worked-example/) for a reference deck.
+See [`examples/stacked-diffs/`](examples/stacked-diffs/) for a complete example deck.
 
 ## Source format
 

{scrolly-0.2.0 → scrolly-0.2.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "scrolly"
-version = "0.2.0"
+version = "0.2.2"
 description = "CLI that compiles a JSON5 deck + slide files into a self-contained 2D-canvas HTML presentation."
 readme = "README.md"
 license = "MIT"
@@ -37,6 +37,17 @@ dev = [
     "pytest-cov>=6.0",
     "ruff>=0.14.0",
     "pre-commit>=4.0",
+    # Exact pin: gitsvg is pre-1.0 and its output schema can shift
+    # between releases. Used to regenerate the stacked-diffs example's
+    # gitsvg frames.
+    "gitsvg==0.2.2",
+]
+# Optional group for the hero-animation capture pipeline (docs/_gen).
+# Heavy (Playwright ships browser binaries via `make capture-setup`),
+# so it's separate from `dev` — casual contributors don't pay the cost.
+capture = [
+    "playwright>=1.40",
+    "pillow>=10.0",
 ]
 
 [project.scripts]
@@ -66,6 +77,10 @@ select = ["I"]
 
 [tool.pytest.ini_options]
 testpaths = ["tests/python"]
+# The hero-animation engine lives under docs/_gen (dev-only tooling, not
+# shipped in the wheel); put it on the path so its pure-logic unit tests
+# can import it without the optional `capture` group installed.
+pythonpath = ["docs/_gen"]
 
 [tool.coverage.run]
 source = ["scrolly"]

{scrolly-0.2.0 → scrolly-0.2.2}/scrolly/_cli/_cli.py

@@ -6,8 +6,10 @@ import click
 from rich.console import Console
 
 from scrolly import __version__
-from scrolly.errors import ScrollyError
-from scrolly.pipeline import build_deck, validate_deck_sources
+from scrolly._cli._errors import errors_command
+from scrolly._cli._introspect import introspect
+from scrolly.errors import ScrollyError, ValidationError
+from scrolly.pipeline import build_deck, load_deck
 from scrolly.pipeline.lint import lint_deck
 
 _err_console = Console(stderr=True, highlight=False)
@@ -41,6 +43,14 @@ def cli() -> None:
     is_flag=True,
     help="Disable gzip compression of inlined assets.",
 )
+@click.option(
+    "--offline",
+    is_flag=True,
+    help=(
+        "Skip the mermaid CDN download and use the wheel-bundled mermaid for "
+        "byte-reproducibility. SCROLLY_OFFLINE=1 in the environment is equivalent."
+    ),
+)
 def build(
     deck_path: Path,
     out_dir: Path,
@@ -49,6 +59,7 @@ def build(
     strict: bool,
     simplified_zoom_control: bool,
     no_compress: bool,
+    offline: bool,
 ) -> None:
     """Build a deck into a self-contained HTML presentation."""
     try:
@@ -59,6 +70,7 @@ def build(
             inline=not no_inline,
             simplified_zoom_control=simplified_zoom_control,
             compress=not no_compress,
+            offline=offline,
         )
     except ScrollyError as e:
         _err_console.print(f"[red]error:[/red] {e}")
@@ -72,12 +84,30 @@ def build(
 
 @cli.command()
 @click.argument("type_name", required=False)
-def schema(type_name: str | None) -> None:
-    """Show source file schemas. Lists types when called without an argument."""
+@click.option(
+    "--list-types",
+    "list_types",
+    is_flag=True,
+    help="Print bare type names one per line (no descriptions) for scripting use.",
+)
+def schema(type_name: str | None, list_types: bool) -> None:
+    """Show source file schemas.
+
+    \b
+    scrolly schema              → formatted index of available types
+    scrolly schema <type>       → JSON Schema for <type>
+    scrolly schema --list-types → bare type names, one per line (agent / scripting)
+    """
     from scrolly.deck import deck_source_schema
     from scrolly.slide import registered_ir_types
 
     ir_types = registered_ir_types()
+    all_type_names = sorted(["deck", *ir_types])
+
+    if list_types:
+        for name in all_type_names:
+            click.echo(name)
+        return
 
     if type_name is None:
         click.echo("Available schemas:\n")
@@ -92,8 +122,7 @@ def schema(type_name: str | None) -> None:
         return
 
     if type_name not in ir_types:
-        known = ", ".join(sorted(["deck", *ir_types]))
-        _err_console.print(f"[red]error:[/red] unknown type '{type_name}' (known: {known})")
+        _err_console.print(f"[red]error:[/red] unknown type '{type_name}' (known: {', '.join(all_type_names)})")
         sys.exit(1)
 
     click.echo(json.dumps(ir_types[type_name].source_schema(), indent=2))
@@ -102,18 +131,44 @@ def schema(type_name: str | None) -> None:
 @cli.command()
 @click.argument("deck_path", type=click.Path(exists=True, dir_okay=False, path_type=Path))
 @click.option("--strict", is_flag=True, help="Enable additional lint checks (e.g. out-of-range keyframes).")
-def validate(deck_path: Path, strict: bool) -> None:
+@click.option(
+    "--json",
+    "as_json",
+    is_flag=True,
+    help='Emit machine-readable JSON instead of text: {"ok": bool, "errors": [...]}.',
+)
+def validate(deck_path: Path, strict: bool, as_json: bool) -> None:
     """Validate a deck and all its slide sources without building."""
     try:
-        deck = validate_deck_sources(deck_path)
+        deck, _ = load_deck(deck_path)
     except ScrollyError as e:
-        _err_console.print(f"[red]error:[/red] {e}")
+        if as_json:
+            click.echo(json.dumps({"ok": False, "errors": [_error_to_dict(e)]}, indent=2))
+        else:
+            _err_console.print(f"[red]error:[/red] {e}")
         sys.exit(1)
 
     if strict:
         _report_diagnostics(deck)
 
-    click.echo(f"Valid: {len(deck.slides)} slides, {len(deck.edges)} edges")
+    if as_json:
+        click.echo(json.dumps({"ok": True, "errors": []}, indent=2))
+    else:
+        click.echo(f"Valid: {len(deck.slides)} slides, {len(deck.edges)} edges")
+
+
+def _error_to_dict(err: ScrollyError) -> dict:
+    """Serialise a ``ScrollyError`` for JSON output."""
+    if isinstance(err, ValidationError):
+        return {
+            "code": err.code,
+            "message": err.message,
+            "file": err.file,
+            "line": err.line,
+            "field": err.field,
+            "suggestion": err.suggestion,
+        }
+    return {"code": None, "message": str(err)}
 
 
 def _report_diagnostics(deck) -> None:
@@ -158,3 +213,7 @@ def init(dir_path: Path) -> None:
     (slides_dir / "intro.slide.json").write_text(_INIT_SLIDE)
 
     click.echo(f"Created deck in {dir_path}")
+
+
+cli.add_command(errors_command)
+cli.add_command(introspect)

scrolly-0.2.2/scrolly/_cli/_errors.py

@@ -0,0 +1,54 @@
+"""``scrolly errors`` — look up registered error codes from the CLI.
+
+Three forms, mirroring the progressive-disclosure pattern used by
+``scrolly schema``:
+
+* ``scrolly errors``              — formatted index of all codes with summaries.
+* ``scrolly errors <code>``       — long-form catalog entry for ``<code>``.
+* ``scrolly errors --list-codes`` — bare codes, one per line (scripting use).
+"""
+
+from __future__ import annotations
+
+import sys
+
+import click
+from rich.console import Console
+
+from scrolly.errors import is_registered_code, registered_codes
+from scrolly.errors._catalog import load_body, load_summary
+
+_err_console = Console(stderr=True, highlight=False)
+
+
+@click.command(name="errors")
+@click.argument("code", required=False)
+@click.option(
+    "--list-codes",
+    "list_codes",
+    is_flag=True,
+    help="Print bare codes one per line (no summaries) for scripting use.",
+)
+def errors_command(code: str | None, list_codes: bool) -> None:
+    """Look up registered error codes.
+
+    \b
+    scrolly errors              → formatted index of all codes with summaries
+    scrolly errors <code>       → long-form catalog entry for <code>
+    scrolly errors --list-codes → bare codes, one per line (agent / scripting)
+    """
+    if list_codes:
+        for c in sorted(registered_codes()):
+            click.echo(c)
+        return
+
+    if code is None:
+        for c in sorted(registered_codes()):
+            click.echo(f"  {c:<6}  {load_summary(c)}")
+        return
+
+    if not is_registered_code(code):
+        _err_console.print(f"[red]error:[/red] unknown error code '{code}'")
+        sys.exit(1)
+
+    click.echo(load_body(code))

scrolly-0.2.2/scrolly/_cli/_introspect/__init__.py

@@ -0,0 +1,46 @@
+"""``scrolly introspect <sub>`` — build-time introspection of a resolved deck.
+
+Each subcommand surfaces some aspect of what the renderer / browser will
+see, scoped to the agent's biggest blind spot: visual output is unreadable
+to a non-browser consumer, so introspection commands close the loop by
+returning structured JSON describing the deck's resolved state.
+
+Common conventions enforced via ``_common.run_introspect_command``:
+
+* **JSON-only output**, default to stdout, ``-o PATH`` for a file
+  destination.
+* **Validation gate first** — broken decks emit error messages to stderr
+  and exit non-zero with no JSON, so consumers never parse stale state.
+* **``--slide <id>``** (repeatable) on subcommands that produce per-slide
+  output, restricting the result to the named slides. Unknown ids exit
+  non-zero with a clear message.
+
+Output format may change before scrolly v1.0 — pin a version when caching
+the schema.
+"""
+
+from __future__ import annotations
+
+import click
+
+from scrolly._cli._introspect._assets import assets_command
+from scrolly._cli._introspect._dom import dom_command
+from scrolly._cli._introspect._elements import elements_command
+from scrolly._cli._introspect._slides import slides_command
+from scrolly._cli._introspect._snaps import snaps_command
+from scrolly._cli._introspect._snapshot import snapshot_command
+from scrolly._cli._introspect._timeline import timeline_command
+
+
+@click.group(name="introspect")
+def introspect() -> None:
+    """Inspect a resolved deck — JSON-only views for downstream consumers."""
+
+
+introspect.add_command(slides_command)
+introspect.add_command(elements_command)
+introspect.add_command(snaps_command)
+introspect.add_command(timeline_command)
+introspect.add_command(snapshot_command)
+introspect.add_command(dom_command)
+introspect.add_command(assets_command)

scrolly-0.2.2/scrolly/_cli/_introspect/_assets.py

@@ -0,0 +1,43 @@
+"""``scrolly introspect assets`` — per-asset metadata + slide references."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import click
+
+from scrolly._cli._introspect._common import run_introspect_command
+from scrolly.pipeline.introspect import assets_to_json
+
+
+@click.command(name="assets")
+@click.argument("deck_path", type=click.Path(exists=True, dir_okay=False, path_type=Path))
+@click.option(
+    "--slide",
+    "slide_ids",
+    multiple=True,
+    help="Restrict the asset walk to elements within the named slide(s). Repeatable.",
+)
+@click.option(
+    "--output",
+    "-o",
+    "output_path",
+    type=click.Path(dir_okay=False, path_type=Path),
+    help="Write JSON to this file instead of stdout.",
+)
+def assets_command(deck_path: Path, slide_ids: tuple[str, ...], output_path: Path | None) -> None:
+    """Asset table — declared assets, per-slide references, byte sizes, mime types.
+
+    Walks the resolved slide IRs for ``ImageElement`` / ``ImageSequenceElement``
+    references. Each entry reports absolute path, name, size, mime, exists
+    flag, and the slides that reference it.
+
+    Output format may change before scrolly v1.0 — pin a version when
+    caching the schema.
+    """
+    run_introspect_command(
+        deck_path,
+        slide_ids=slide_ids,
+        output_path=output_path,
+        to_json_fn=assets_to_json,
+    )

scrolly-0.2.2/scrolly/_cli/_introspect/_common.py

@@ -0,0 +1,136 @@
+"""Shared machinery for the ``scrolly introspect`` subcommands.
+
+Every subcommand goes through ``run_introspect_command``, which:
+
+1. Loads the deck through the shared validation gate (``load_deck``).
+2. On error, prints to stderr and exits non-zero with no JSON.
+3. If ``slide_ids`` is non-empty, validates each id against the
+   resolved slide list and exits with a clear message on unknown ids.
+4. Calls the supplied ``to_json_fn`` to produce the payload.
+5. Writes to ``output_path`` if given, otherwise stdout.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from collections.abc import Callable
+from pathlib import Path
+
+import click
+from rich.console import Console
+
+from scrolly.deck.model import Deck
+from scrolly.errors import ScrollyError
+from scrolly.pipeline import load_deck
+from scrolly.slide.ir import SlideIR
+
+_err_console = Console(stderr=True, highlight=False)
+
+ToJsonFn = Callable[[Deck, dict[str, SlideIR], tuple[str, ...] | None], dict]
+
+
+def run_introspect_command(
+    deck_path: Path,
+    slide_ids: tuple[str, ...],
+    output_path: Path | None,
+    *,
+    to_json_fn: ToJsonFn,
+) -> None:
+    """Run an introspect subcommand end-to-end: load → filter → serialize → output.
+
+    Args:
+        deck_path: Path to the ``.deck.json`` file.
+        slide_ids: Tuple of slide ids to filter to; empty tuple = no filter.
+        output_path: Optional file destination; ``None`` writes to stdout.
+        to_json_fn: Domain helper that produces the JSON-ready dict.
+
+    Raises:
+        SystemExit: Non-zero exit on validation gate failure or unknown
+            ``--slide`` ids; the error message goes to stderr.
+    """
+    try:
+        deck, slide_irs = load_deck(deck_path)
+    except ScrollyError as e:
+        _err_console.print(f"[red]error:[/red] {e}")
+        sys.exit(1)
+
+    if slide_ids:
+        known = {s.id for s in deck.slides}
+        unknown = [sid for sid in slide_ids if sid not in known]
+        if unknown:
+            _err_console.print(
+                f"[red]error:[/red] unknown slide id(s): {', '.join(unknown)}. Known: {', '.join(sorted(known))}"
+            )
+            sys.exit(1)
+
+    payload = to_json_fn(deck, slide_irs, slide_ids or None)
+    rendered = json.dumps(payload, indent=2)
+
+    if output_path is not None:
+        output_path.write_text(rendered, encoding="utf-8")
+    else:
+        click.echo(rendered)
+
+
+def run_snapshot_command(
+    deck_path: Path,
+    slide_id: str,
+    scrolls: tuple[float, ...],
+    output_path: Path | None,
+) -> None:
+    """Run the snapshot subcommand: load → validate slide_id + scrolls → snapshot → output.
+
+    Snapshot differs from the other introspect commands in two ways:
+    ``--slide`` is mandatory and single-valued (scroll positions are
+    slide-local, so multi-slide queries are ambiguous), and ``--scroll N``
+    is mandatory and repeatable. This helper enforces both invariants
+    plus the per-slide scroll-range validation: any ``--scroll`` outside
+    ``[0, scroll_range]`` for numeric ``scroll_range``, or below 0 for
+    ``"auto"`` slides, rejects the whole invocation with a clear message
+    rather than silently clamping or extrapolating beyond what the
+    browser can physically reach.
+
+    Args:
+        deck_path: Path to the ``.deck.json`` file.
+        slide_id: Slide to snapshot (mandatory, single).
+        scrolls: Tuple of scroll positions (mandatory, non-empty).
+        output_path: Optional file destination; ``None`` writes to stdout.
+
+    Raises:
+        SystemExit: Non-zero exit on validation gate failure, unknown
+            ``slide_id``, or any out-of-range scroll value.
+    """
+    from scrolly.slide.introspect import snapshot_to_json
+
+    try:
+        deck, slide_irs = load_deck(deck_path)
+    except ScrollyError as e:
+        _err_console.print(f"[red]error:[/red] {e}")
+        sys.exit(1)
+
+    known = {s.id for s in deck.slides}
+    if slide_id not in known:
+        _err_console.print(f"[red]error:[/red] unknown slide id: '{slide_id}'. Known: {', '.join(sorted(known))}")
+        sys.exit(1)
+
+    ir = slide_irs[slide_id]
+    scroll_range = ir.scroll_range
+    invalid: list[tuple[float, str]] = []
+    for scroll in scrolls:
+        if scroll < 0:
+            invalid.append((scroll, "negative scroll values are never reachable"))
+        elif isinstance(scroll_range, (int, float)) and scroll > scroll_range:
+            invalid.append((scroll, f"exceeds slide's scroll_range ({scroll_range})"))
+    if invalid:
+        lines = "\n".join(f"  scroll={s}: {reason}" for s, reason in invalid)
+        _err_console.print(f"[red]error:[/red] --scroll out-of-range for slide '{slide_id}':\n{lines}")
+        sys.exit(1)
+
+    payload = snapshot_to_json(deck, slide_irs, slide_id, scrolls)
+    rendered = json.dumps(payload, indent=2)
+
+    if output_path is not None:
+        output_path.write_text(rendered, encoding="utf-8")
+    else:
+        click.echo(rendered)

scrolly-0.2.2/scrolly/_cli/_introspect/_dom.py

@@ -0,0 +1,47 @@
+"""``scrolly introspect dom`` — rendered HTML + scoped CSS per element."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import click
+
+from scrolly._cli._introspect._common import run_introspect_command
+from scrolly.slide.introspect import dom_to_json
+
+
+@click.command(name="dom")
+@click.argument("deck_path", type=click.Path(exists=True, dir_okay=False, path_type=Path))
+@click.option(
+    "--slide",
+    "slide_ids",
+    multiple=True,
+    help=(
+        "Restrict output to the named slide id(s). Repeatable. Default = all slides — "
+        "but unfiltered output can be hundreds of KB; the filter is almost mandatory in practice."
+    ),
+)
+@click.option(
+    "--output",
+    "-o",
+    "output_path",
+    type=click.Path(dir_okay=False, path_type=Path),
+    help="Write JSON to this file instead of stdout.",
+)
+def dom_command(deck_path: Path, slide_ids: tuple[str, ...], output_path: Path | None) -> None:
+    """Rendered HTML + scoped CSS per element, sans deck-level chrome.
+
+    Answers "what does my config actually become" by running each
+    slide's element renderers and surfacing the per-element pieces —
+    HTML fragment and CSS rules — directly. No canvas runtime, no
+    scrollbar, no edge geometry, no inter-slide chrome.
+
+    Output format may change before scrolly v1.0 — pin a version when
+    caching the schema.
+    """
+    run_introspect_command(
+        deck_path,
+        slide_ids=slide_ids,
+        output_path=output_path,
+        to_json_fn=dom_to_json,
+    )

scrolly-0.2.2/scrolly/_cli/_introspect/_elements.py

@@ -0,0 +1,43 @@
+"""``scrolly introspect elements`` — fully-resolved per-slide element tree."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import click
+
+from scrolly._cli._introspect._common import run_introspect_command
+from scrolly.slide.introspect import element_tree_to_json
+
+
+@click.command(name="elements")
+@click.argument("deck_path", type=click.Path(exists=True, dir_okay=False, path_type=Path))
+@click.option(
+    "--slide",
+    "slide_ids",
+    multiple=True,
+    help="Restrict output to the named slide id(s). Repeatable. Default = all slides.",
+)
+@click.option(
+    "--output",
+    "-o",
+    "output_path",
+    type=click.Path(dir_okay=False, path_type=Path),
+    help="Write JSON to this file instead of stdout.",
+)
+def elements_command(deck_path: Path, slide_ids: tuple[str, ...], output_path: Path | None) -> None:
+    """Fully-resolved element tree per slide.
+
+    Defaults are filled in, ``*_file`` fields are inlined, asset paths
+    are absolute. Animated properties surface as their keyframe lists;
+    static properties surface as their values.
+
+    Output format may change before scrolly v1.0 — pin a version when
+    caching the schema.
+    """
+    run_introspect_command(
+        deck_path,
+        slide_ids=slide_ids,
+        output_path=output_path,
+        to_json_fn=element_tree_to_json,
+    )

scrolly-0.2.2/scrolly/_cli/_introspect/_slides.py

@@ -0,0 +1,40 @@
+"""``scrolly introspect slides`` — deck topology view."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import click
+
+from scrolly._cli._introspect._common import run_introspect_command
+from scrolly.deck.introspect import slides_to_json
+
+
+@click.command(name="slides")
+@click.argument("deck_path", type=click.Path(exists=True, dir_okay=False, path_type=Path))
+@click.option(
+    "--output",
+    "-o",
+    "output_path",
+    type=click.Path(dir_okay=False, path_type=Path),
+    help="Write JSON to this file instead of stdout.",
+)
+def slides_command(deck_path: Path, output_path: Path | None) -> None:
+    """Deck topology — slides, edges, groups, geometry.
+
+    Returns a deck-wide overview: every slide with its grid coord, title,
+    resolved scroll_range, element + snap counts; every edge with
+    fully-specified sides; every group with members and color.
+
+    No ``--slide`` filter — the value of this view is the relationships
+    between slides, which filtering would destroy.
+
+    Output format may change before scrolly v1.0 — pin a version when
+    caching the schema.
+    """
+    run_introspect_command(
+        deck_path,
+        slide_ids=(),
+        output_path=output_path,
+        to_json_fn=slides_to_json,
+    )