scrolly 0.2.2__tar.gz → 0.2.4__tar.gz

{scrolly-0.2.2 → scrolly-0.2.4}/.gitignore

@@ -5,6 +5,9 @@ dist/
 .pytest_cache/
 .ruff_cache/
 
+# Docs site build output (mkdocs build)
+/site/
+
 # Golden-test debug output (written next to the fixture on mismatch)
 *.actual.html
 

scrolly-0.2.4/PKG-INFO

@@ -0,0 +1,118 @@
+Metadata-Version: 2.4
+Name: scrolly
+Version: 0.2.4
+Summary: CLI that compiles a JSON5 deck + slide files into a self-contained 2D-canvas HTML presentation.
+Project-URL: Homepage, https://scrolly.readthedocs.io/en/stable/
+Project-URL: Documentation, https://scrolly.readthedocs.io/en/stable/
+Project-URL: Source, https://github.com/bertpl/scrolly
+Project-URL: Changelog, https://github.com/bertpl/scrolly/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/bertpl/scrolly/issues
+Author-email: Bert Pluymers <bert.pluymers@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: cli,html,presentation,scrollytelling,slides
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Multimedia :: Graphics :: Presentation
+Classifier: Topic :: Text Processing :: Markup :: HTML
+Requires-Python: >=3.11
+Requires-Dist: click>=8.2.0
+Requires-Dist: jinja2>=3.1
+Requires-Dist: json5>=0.13.0
+Requires-Dist: markdown>=3.4
+Requires-Dist: pydantic>=2.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.0.0
+Description-Content-Type: text/markdown
+
+# scrolly
+
+Compile a JSON5 deck into a single, 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-v4.webp)](https://scrolly.readthedocs.io/en/stable/)
+
+[![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/)
+[![License](https://img.shields.io/badge/license-MIT-blue)](https://github.com/bertpl/scrolly/blob/main/LICENSE)
+
+## Why it's different
+
+- **A 2D canvas you fly around**, not a linear reel. Slides sit on an
+  integer grid connected by edges; readers zoom out to a deck map and
+  zoom into any slide to scroll through it.
+- **Scroll-driven keyframe animation.** Element properties (position,
+  size, opacity, scale, angle) interpolate as the reader scrolls — no
+  timeline, no autoplay.
+- **One self-contained HTML file.** A default build inlines every
+  asset into a single `index.html` with zero external loads — open it
+  by double-clicking, host it anywhere, email it.
+- **Agent-friendly.** The CLI exposes full help, input schemas, deck
+  introspection, and numbered error codes, so agentic coding tools
+  immediately understand how to author and debug scrolly decks.
+
+## Installation
+
+```bash
+pip install scrolly        # or: uv tool install scrolly
+```
+
+## Quickstart
+
+```bash
+scrolly init my-deck                                    # scaffold a starter deck
+scrolly build my-deck/deck.deck.json --out out --force  # compile to one HTML file
+open out/index.html                                     # double-click anywhere
+```
+
+A deck is a `.deck.json` manifest plus one `.slide.json` per slide (both
+parsed as JSON5):
+
+```json5
+// deck.deck.json
+{
+  title: "My Deck",
+  slides: [
+    { id: "intro", position: [0, 0], source: "slides/intro.slide.json" },
+  ],
+  edges: [],
+}
+```
+
+```json5
+// slides/intro.slide.json
+{
+  title: "My Deck",
+  elements: [
+    { markdown: "# My Deck\n\nWelcome to your new presentation." },
+  ],
+}
+```
+
+## Elements
+
+Slides hold elements of six types — `markdown`, `image`, `image_sequence`,
+`mermaid`, `html`, and `iframe` — each animatable via scroll-driven
+keyframes. See the [element reference](https://scrolly.readthedocs.io/en/stable/reference/elements/)
+for fields and examples.
+
+## Learn more
+
+- **[Documentation](https://scrolly.readthedocs.io/en/stable/)** — guided
+  walkthrough, concepts, authoring, and the full reference, with a live
+  interactive deck right on the homepage.
+- **[Examples](examples/)** — including the
+  [stacked-diffs](examples/stacked-diffs/) hero deck.
+- **[Changelog](CHANGELOG.md)**.
+
+## License
+
+[MIT](https://github.com/bertpl/scrolly/blob/main/LICENSE).

scrolly-0.2.4/README.md

@@ -0,0 +1,85 @@
+# scrolly
+
+Compile a JSON5 deck into a single, 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-v4.webp)](https://scrolly.readthedocs.io/en/stable/)
+
+[![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/)
+[![License](https://img.shields.io/badge/license-MIT-blue)](https://github.com/bertpl/scrolly/blob/main/LICENSE)
+
+## Why it's different
+
+- **A 2D canvas you fly around**, not a linear reel. Slides sit on an
+  integer grid connected by edges; readers zoom out to a deck map and
+  zoom into any slide to scroll through it.
+- **Scroll-driven keyframe animation.** Element properties (position,
+  size, opacity, scale, angle) interpolate as the reader scrolls — no
+  timeline, no autoplay.
+- **One self-contained HTML file.** A default build inlines every
+  asset into a single `index.html` with zero external loads — open it
+  by double-clicking, host it anywhere, email it.
+- **Agent-friendly.** The CLI exposes full help, input schemas, deck
+  introspection, and numbered error codes, so agentic coding tools
+  immediately understand how to author and debug scrolly decks.
+
+## Installation
+
+```bash
+pip install scrolly        # or: uv tool install scrolly
+```
+
+## Quickstart
+
+```bash
+scrolly init my-deck                                    # scaffold a starter deck
+scrolly build my-deck/deck.deck.json --out out --force  # compile to one HTML file
+open out/index.html                                     # double-click anywhere
+```
+
+A deck is a `.deck.json` manifest plus one `.slide.json` per slide (both
+parsed as JSON5):
+
+```json5
+// deck.deck.json
+{
+  title: "My Deck",
+  slides: [
+    { id: "intro", position: [0, 0], source: "slides/intro.slide.json" },
+  ],
+  edges: [],
+}
+```
+
+```json5
+// slides/intro.slide.json
+{
+  title: "My Deck",
+  elements: [
+    { markdown: "# My Deck\n\nWelcome to your new presentation." },
+  ],
+}
+```
+
+## Elements
+
+Slides hold elements of six types — `markdown`, `image`, `image_sequence`,
+`mermaid`, `html`, and `iframe` — each animatable via scroll-driven
+keyframes. See the [element reference](https://scrolly.readthedocs.io/en/stable/reference/elements/)
+for fields and examples.
+
+## Learn more
+
+- **[Documentation](https://scrolly.readthedocs.io/en/stable/)** — guided
+  walkthrough, concepts, authoring, and the full reference, with a live
+  interactive deck right on the homepage.
+- **[Examples](examples/)** — including the
+  [stacked-diffs](examples/stacked-diffs/) hero deck.
+- **[Changelog](CHANGELOG.md)**.
+
+## License
+
+[MIT](https://github.com/bertpl/scrolly/blob/main/LICENSE).

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

@@ -1,6 +1,6 @@
 [project]
 name = "scrolly"
-version = "0.2.2"
+version = "0.2.4"
 description = "CLI that compiles a JSON5 deck + slide files into a self-contained 2D-canvas HTML presentation."
 readme = "README.md"
 license = "MIT"
@@ -40,7 +40,7 @@ dev = [
     # 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",
+    "gitsvg==0.2.3",
 ]
 # Optional group for the hero-animation capture pipeline (docs/_gen).
 # Heavy (Playwright ships browser binaries via `make capture-setup`),
@@ -54,6 +54,8 @@ capture = [
 scrolly = "scrolly._cli._cli:cli"
 
 [project.urls]
+Homepage = "https://scrolly.readthedocs.io/en/stable/"
+Documentation = "https://scrolly.readthedocs.io/en/stable/"
 Source = "https://github.com/bertpl/scrolly"
 Changelog = "https://github.com/bertpl/scrolly/blob/main/CHANGELOG.md"
 Issues = "https://github.com/bertpl/scrolly/issues"

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

@@ -8,6 +8,7 @@ from rich.console import Console
 from scrolly import __version__
 from scrolly._cli._errors import errors_command
 from scrolly._cli._introspect import introspect
+from scrolly._cli._schema import schema
 from scrolly.errors import ScrollyError, ValidationError
 from scrolly.pipeline import build_deck, load_deck
 from scrolly.pipeline.lint import lint_deck
@@ -82,52 +83,6 @@ def build(
     click.echo(f"Built '{deck.title or '(untitled)'}': {len(deck.slides)} slides, {len(deck.edges)} edges → {out_dir}")
 
 
-@cli.command()
-@click.argument("type_name", required=False)
-@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")
-        click.echo(f"  {'deck':<17}{'.deck.json':<24}Deck structure (slides + edges)")
-        for name in sorted(ir_types):
-            cls = ir_types[name]
-            click.echo(f"  {name:<17}{cls.SUFFIX:<24}{cls.DESCRIPTION}")
-        return
-
-    if type_name == "deck":
-        click.echo(json.dumps(deck_source_schema(), indent=2))
-        return
-
-    if type_name not in ir_types:
-        _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))
-
-
 @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).")
@@ -217,3 +172,4 @@ def init(dir_path: Path) -> None:
 
 cli.add_command(errors_command)
 cli.add_command(introspect)
+cli.add_command(schema)

scrolly-0.2.4/scrolly/_cli/_schema.py

@@ -0,0 +1,167 @@
+"""``scrolly schema`` — show source-file and slide-element schemas from the CLI.
+
+A Click group with two parallel subcommands, mirroring the
+subcommand-group structure of ``scrolly introspect``:
+
+* ``scrolly schema``                      — combined index of file and element schemas.
+* ``scrolly schema file``                 — index of source-file schemas (deck, slide).
+* ``scrolly schema file <type>``          — JSON Schema for a source-file type.
+* ``scrolly schema file --list-types``    — bare file-type names, one per line.
+* ``scrolly schema element``              — index of element schemas.
+* ``scrolly schema element <type>``       — JSON Schema for an element type.
+* ``scrolly schema element --list-types`` — bare element keys, one per line.
+
+``schema`` shows static *type* definitions; ``introspect`` inspects a
+specific *resolved deck instance* — different surfaces, kept distinct.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+
+import click
+from rich.console import Console
+
+_err_console = Console(stderr=True, highlight=False)
+
+# Width of the name / suffix columns in the human-readable index, matching
+# the alignment used by ``scrolly errors``.
+_NAME_COL = 17
+_SUFFIX_COL = 24
+
+
+# ==================================================================================================
+#  schema group
+# ==================================================================================================
+@click.group(name="schema", invoke_without_command=True)
+@click.pass_context
+def schema(ctx: click.Context) -> None:
+    """Show source-file and slide-element schemas.
+
+    \b
+    scrolly schema                  → combined index (file + element schemas)
+    scrolly schema file [<type>]    → source-file schemas (deck, slide)
+    scrolly schema element [<type>] → slide-element schemas (markdown, image, …)
+
+    Append --list-types to either subcommand for bare names (agent / scripting).
+    Shows static type definitions; use `scrolly introspect` for a resolved deck.
+    """
+    if ctx.invoked_subcommand is None:
+        _print_file_index()
+        click.echo()
+        _print_element_index()
+
+
+# --------------------------------------------------------------------------
+#  Subcommands
+# --------------------------------------------------------------------------
+@schema.command(name="file")
+@click.argument("type_name", required=False)
+@click.option(
+    "--list-types",
+    "list_types",
+    is_flag=True,
+    help="Print bare file-type names one per line (no descriptions) for scripting use.",
+)
+def schema_file(type_name: str | None, list_types: bool) -> None:
+    """Source-file schemas (deck, slide).
+
+    \b
+    scrolly schema file              → formatted index of file types
+    scrolly schema file <type>       → JSON Schema for <type>
+    scrolly schema file --list-types → bare type names, one per line (agent / scripting)
+    """
+    names = _file_type_names()
+
+    if list_types:
+        for name in names:
+            click.echo(name)
+        return
+
+    if type_name is None:
+        _print_file_index()
+        return
+
+    schema_dict = _file_schema(type_name)
+    if schema_dict is None:
+        _err_console.print(f"[red]error:[/red] unknown file type '{type_name}' (known: {', '.join(names)})")
+        sys.exit(1)
+    click.echo(json.dumps(schema_dict, indent=2))
+
+
+@schema.command(name="element")
+@click.argument("type_name", required=False)
+@click.option(
+    "--list-types",
+    "list_types",
+    is_flag=True,
+    help="Print bare element keys one per line (no descriptions) for scripting use.",
+)
+def schema_element(type_name: str | None, list_types: bool) -> None:
+    """Slide-element schemas (markdown, image, …).
+
+    \b
+    scrolly schema element              → formatted index of element types
+    scrolly schema element <type>       → JSON Schema for <type>
+    scrolly schema element --list-types → bare element keys, one per line (agent / scripting)
+    """
+    from scrolly.slide import element_source_types
+
+    elements = element_source_types()
+
+    if list_types:
+        for key in elements:
+            click.echo(key)
+        return
+
+    if type_name is None:
+        _print_element_index()
+        return
+
+    if type_name not in elements:
+        _err_console.print(f"[red]error:[/red] unknown element type '{type_name}' (known: {', '.join(elements)})")
+        sys.exit(1)
+    click.echo(json.dumps(elements[type_name].source_schema(), indent=2))
+
+
+# --------------------------------------------------------------------------
+#  Schema lookup + index rendering
+# --------------------------------------------------------------------------
+def _file_type_names() -> list[str]:
+    """Return the sorted source-file type names (deck + registered slide types)."""
+    from scrolly.slide import registered_ir_types
+
+    return sorted(["deck", *registered_ir_types()])
+
+
+def _file_schema(type_name: str) -> dict | None:
+    """Return the JSON Schema for a source-file type, or ``None`` if unknown."""
+    from scrolly.deck import deck_source_schema
+    from scrolly.slide import registered_ir_types
+
+    if type_name == "deck":
+        return deck_source_schema()
+    ir_types = registered_ir_types()
+    if type_name in ir_types:
+        return ir_types[type_name].source_schema()
+    return None
+
+
+def _print_file_index() -> None:
+    """Print the human-readable index of source-file schemas."""
+    from scrolly.slide import registered_ir_types
+
+    click.echo("File schemas (source files):\n")
+    click.echo(f"  {'deck':<{_NAME_COL}}{'.deck.json':<{_SUFFIX_COL}}Deck structure (slides + edges)")
+    for name, cls in sorted(registered_ir_types().items()):
+        click.echo(f"  {name:<{_NAME_COL}}{cls.SUFFIX:<{_SUFFIX_COL}}{cls.DESCRIPTION}")
+
+
+def _print_element_index() -> None:
+    """Print the human-readable index of slide-element schemas."""
+    from scrolly.slide import element_source_types
+
+    click.echo("Element schemas (slide elements):\n")
+    for key, cls in element_source_types().items():
+        click.echo(f"  {key:<{_NAME_COL}}{cls.DESCRIPTION}")

{scrolly-0.2.2 → scrolly-0.2.4}/scrolly/deck/introspect.py

@@ -35,7 +35,7 @@ def slides_to_json(
             ``slides``: map of slide id → {position, title, scroll_range,
                 element_count, snap_position_count}.
             ``edges``: list of {a: {slide, side}, b: {slide, side}}.
-            ``groups``: list of {label, color, slide_ids}.
+            ``groups``: list of {label, color, label_color, slide_ids}.
     """
     del slide_ids  # always deck-wide; param exists for signature uniformity
 
@@ -63,6 +63,7 @@ def slides_to_json(
         {
             "label": group.label,
             "color": group.color,
+            "label_color": group.label_color,
             "slide_ids": list(group.slide_ids),
         }
         for group in deck.groups

{scrolly-0.2.2 → scrolly-0.2.4}/scrolly/deck/model.py

@@ -82,6 +82,7 @@ class SlideGroup:
     label: str
     slide_ids: tuple[str, ...]
     color: str | None = None
+    label_color: str | None = None
 
 
 @dataclass(frozen=True)

{scrolly-0.2.2 → scrolly-0.2.4}/scrolly/deck/parser.py

@@ -79,8 +79,16 @@ def _parse_slides_and_groups(slides_raw: list, deck_path: Path) -> tuple[tuple[S
                 group_slide_ids.append(slide.id)
                 flat_idx += 1
 
-            color = _parse_group_color(item, ctx)
-            groups.append(SlideGroup(label=label, slide_ids=tuple(group_slide_ids), color=color))
+            color = _parse_group_hex_color(item, ctx, "color")
+            label_color = _parse_group_hex_color(item, ctx, "label_color")
+            groups.append(
+                SlideGroup(
+                    label=label,
+                    slide_ids=tuple(group_slide_ids),
+                    color=color,
+                    label_color=label_color,
+                )
+            )
         else:
             slide = _parse_slide(item, deck_dir, flat_idx, ctx)
             slides.append(slide)
@@ -92,16 +100,31 @@ def _parse_slides_and_groups(slides_raw: list, deck_path: Path) -> tuple[tuple[S
 _HEX_COLOR_RE = re.compile(r"^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6})$")
 
 
-def _parse_group_color(raw: dict, ctx: str) -> str | None:
-    """Parse and validate an optional hex color from a group object."""
-    if "color" not in raw:
+def _parse_group_hex_color(raw: dict, ctx: str, key: str) -> str | None:
+    """Parse and validate an optional hex color field from a group object.
+
+    Args:
+        raw: The raw group object.
+        ctx: Error-context prefix (e.g. ``slides[2]``).
+        key: Which field to read — ``color`` (background) or ``label_color``
+            (label override).
+
+    Returns:
+        The validated ``#RGB`` / ``#RRGGBB`` string, or ``None`` if the field
+        is absent.
+
+    Raises:
+        DeckParseError: If present but not a string (E004) or not a valid hex
+            color (E009).
+    """
+    if key not in raw:
         return None
-    color = raw["color"]
-    if not isinstance(color, str):
-        raise DeckParseError(code="E004", message=f"{ctx}: 'color' must be a string, got {type(color).__name__}")
-    if not _HEX_COLOR_RE.match(color):
-        raise DeckParseError(code="E009", message=f"{ctx}: 'color' must be #RGB or #RRGGBB, got '{color}'")
-    return color
+    value = raw[key]
+    if not isinstance(value, str):
+        raise DeckParseError(code="E004", message=f"{ctx}: '{key}' must be a string, got {type(value).__name__}")
+    if not _HEX_COLOR_RE.match(value):
+        raise DeckParseError(code="E009", message=f"{ctx}: '{key}' must be #RGB or #RRGGBB, got '{value}'")
+    return value
 
 
 def _require_list(d: dict, key: str, deck_path: Path) -> list:

{scrolly-0.2.2 → scrolly-0.2.4}/scrolly/deck/schema.py

@@ -55,6 +55,17 @@ def deck_source_schema() -> dict:
                                     "type": "string",
                                     "description": "Group label, displayed above the group rectangle in deck view.",
                                 },
+                                "color": {
+                                    "type": "string",
+                                    "description": "Group background fill as #RGB or #RRGGBB. Defaults to a neutral gray.",
+                                },
+                                "label_color": {
+                                    "type": "string",
+                                    "description": (
+                                        "Group label color as #RGB or #RRGGBB. Defaults to a "
+                                        "black-or-white auto-contrast pick against the background."
+                                    ),
+                                },
                                 "slides": {
                                     "type": "array",
                                     "description": "Slides in this group.",

{scrolly-0.2.2 → scrolly-0.2.4}/scrolly/errors/catalog/E003.md

@@ -14,5 +14,5 @@ require `title` and `elements`; per-slide entries in a deck require
 
 ## How to fix
 
-Add the missing field. Run `scrolly schema deck` or `scrolly schema
-slide` to see the full required shape for each file type.
+Add the missing field. Run `scrolly schema file deck` or `scrolly schema
+file slide` to see the full required schema for each file type.

{scrolly-0.2.2 → scrolly-0.2.4}/scrolly/errors/catalog/E299.md

@@ -17,5 +17,5 @@ path embedded in the error message.
 ## How to fix
 
 Read the embedded Pydantic message — it names the field path and the
-constraint that failed. Cross-reference with `scrolly schema slide`
-for the expected shape of the slide source.
+constraint that failed. Cross-reference with `scrolly schema file slide`
+for the expected schema of the slide source.

{scrolly-0.2.2 → scrolly-0.2.4}/scrolly/errors/catalog/E601.md

@@ -13,5 +13,6 @@ An element object with no recognised type field — no `markdown:`,
 
 ## How to fix
 
-Check the element JSON against `scrolly schema slide`. Each element
-must include the field that names its type.
+Run `scrolly schema element --list-types` to see the valid element
+types, then `scrolly schema element <type>` for one's fields. Each
+element must include the field that names its type.