scrolly 0.1.0__tar.gz

scrolly-0.1.0/.gitignore

@@ -0,0 +1,41 @@
+# Python
+__pycache__/
+*.egg-info/
+dist/
+.pytest_cache/
+.ruff_cache/
+
+# Coverage
+htmlcov/
+.coverage
+reports/
+
+# Virtual environments
+.venv/
+
+# Node
+node_modules/
+
+# Private dev docs
+design/
+.local/
+
+# IDE
+.idea/
+.vscode/
+
+# OS
+.DS_Store
+._*
+Thumbs.db
+Desktop.ini
+
+# AI assistants
+.claude/
+CLAUDE.md
+AGENTS.md
+.cursor/
+.cursorrules
+.aider*
+.copilot/
+.github/copilot-instructions.md

scrolly-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+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-0.1.0/PKG-INFO

@@ -0,0 +1,65 @@
+Metadata-Version: 2.4
+Name: scrolly
+Version: 0.1.0
+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
+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 self-contained, scrollable 2D-canvas HTML presentation.
+
+[![CI](https://github.com/bertpl/scrolly/actions/workflows/push_to_main.yml/badge.svg)](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)
+
+## Installation
+
+```bash
+pip install scrolly
+```
+
+Or with [uv](https://docs.astral.sh/uv/):
+
+```bash
+uv tool install scrolly
+```
+
+## Quickstart
+
+```bash
+scrolly build examples/worked-example/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
+demonstrating all supported slide types.
+
+## License
+
+[MIT](https://github.com/bertpl/scrolly/blob/main/LICENSE).

scrolly-0.1.0/README.md

@@ -0,0 +1,34 @@
+# scrolly
+
+Compile a JSON5 deck into a self-contained, scrollable 2D-canvas HTML presentation.
+
+[![CI](https://github.com/bertpl/scrolly/actions/workflows/push_to_main.yml/badge.svg)](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)
+
+## Installation
+
+```bash
+pip install scrolly
+```
+
+Or with [uv](https://docs.astral.sh/uv/):
+
+```bash
+uv tool install scrolly
+```
+
+## Quickstart
+
+```bash
+scrolly build examples/worked-example/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
+demonstrating all supported slide types.
+
+## License
+
+[MIT](https://github.com/bertpl/scrolly/blob/main/LICENSE).

scrolly-0.1.0/pyproject.toml

@@ -0,0 +1,78 @@
+[project]
+name = "scrolly"
+version = "0.1.0"
+description = "CLI that compiles a JSON5 deck + slide files into a self-contained 2D-canvas HTML presentation."
+readme = "README.md"
+license = "MIT"
+authors = [
+    { name = "Bert Pluymers", email = "bert.pluymers@gmail.com" }
+]
+requires-python = ">=3.11"
+keywords = ["presentation", "slides", "scrollytelling", "html", "cli"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Intended Audience :: End Users/Desktop",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Multimedia :: Graphics :: Presentation",
+    "Topic :: Text Processing :: Markup :: HTML",
+]
+dependencies = [
+    "click>=8.2.0",
+    "json5>=0.13.0",
+    "jinja2>=3.1",
+    "pyyaml>=6.0",
+    "markdown>=3.4",
+    "pydantic>=2.0",
+    "rich>=13.0.0",
+]
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0",
+    "pytest-cov>=6.0",
+    "ruff>=0.14.0",
+    "pre-commit>=4.0",
+]
+
+[project.scripts]
+scrolly = "scrolly._cli._cli:cli"
+
+[project.urls]
+Source = "https://github.com/bertpl/scrolly"
+Changelog = "https://github.com/bertpl/scrolly/blob/main/CHANGELOG.md"
+Issues = "https://github.com/bertpl/scrolly/issues"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.sdist]
+packages = ["scrolly"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["scrolly"]
+
+[tool.ruff]
+line-length = 120
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["I"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests/python"]
+
+[tool.coverage.run]
+source = ["scrolly"]
+
+[tool.coverage.report]
+precision = 2
+exclude_also = [
+    "@abstractmethod",
+    "@abc.abstractmethod",
+]

scrolly-0.1.0/scrolly/__init__.py

@@ -0,0 +1,3 @@
+from importlib.metadata import version
+
+__version__ = version("scrolly")

scrolly-0.1.0/scrolly/_cli/_cli.py

@@ -0,0 +1,120 @@
+import json
+import sys
+from pathlib import Path
+
+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
+
+_err_console = Console(stderr=True, highlight=False)
+
+
+@click.group()
+@click.version_option(__version__, prog_name="scrolly")
+def cli() -> None:
+    """scrolly — compile a JSON5 deck into a self-contained 2D-canvas HTML presentation."""
+
+
+@cli.command()
+@click.argument("deck_path", type=click.Path(exists=True, dir_okay=False, path_type=Path))
+@click.option(
+    "--out",
+    "out_dir",
+    required=True,
+    type=click.Path(file_okay=False, path_type=Path),
+    help="Output directory.",
+)
+@click.option("--force", is_flag=True, help="Overwrite a non-empty output directory.")
+@click.option("--no-inline", is_flag=True, help="Write assets as separate files instead of inlining.")
+def build(deck_path: Path, out_dir: Path, force: bool, no_inline: bool) -> None:
+    """Build a deck into a self-contained HTML presentation."""
+    try:
+        deck = build_deck(deck_path, out_dir, force=force, inline=not no_inline)
+    except ScrollyError as e:
+        _err_console.print(f"[red]error:[/red] {e}")
+        sys.exit(1)
+
+    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)
+def schema(type_name: str | None) -> None:
+    """Show source file schemas. Lists types when called without an argument."""
+    from scrolly.deck import deck_source_schema
+    from scrolly.slide import registered_ir_types
+
+    ir_types = registered_ir_types()
+
+    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:
+        known = ", ".join(sorted(["deck", *ir_types]))
+        _err_console.print(f"[red]error:[/red] unknown type '{type_name}' (known: {known})")
+        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))
+def validate(deck_path: Path) -> None:
+    """Validate a deck and all its slide sources without building."""
+    try:
+        deck = validate_deck_sources(deck_path)
+    except ScrollyError as e:
+        _err_console.print(f"[red]error:[/red] {e}")
+        sys.exit(1)
+
+    click.echo(f"Valid: {len(deck.slides)} slides, {len(deck.edges)} edges")
+
+
+_INIT_DECK = """\
+{
+  title: "My Deck",
+  slides: [
+    { id: "intro", position: [0, 0], source: "slides/intro.static.md" },
+  ],
+  edges: [],
+}
+"""
+
+_INIT_SLIDE = """\
+---
+initial_scroll_position: 0
+---
+
+# My Deck
+
+Welcome to your new presentation.
+"""
+
+
+@cli.command()
+@click.argument("dir_path", type=click.Path(path_type=Path))
+def init(dir_path: Path) -> None:
+    """Scaffold a minimal deck in DIR_PATH."""
+    if dir_path.exists() and any(dir_path.iterdir()):
+        _err_console.print(f"[red]error:[/red] directory is not empty: {dir_path}")
+        sys.exit(1)
+
+    slides_dir = dir_path / "slides"
+    slides_dir.mkdir(parents=True, exist_ok=True)
+
+    (dir_path / "deck.deck.json").write_text(_INIT_DECK)
+    (slides_dir / "intro.static.md").write_text(_INIT_SLIDE)
+
+    click.echo(f"Created deck in {dir_path}")

scrolly-0.1.0/scrolly/deck/__init__.py

@@ -0,0 +1,43 @@
+"""Deck model, parsing, validation, and inference (Layer A).
+
+Pipeline:
+    raw_deck = parse_deck(path)
+    validate_raw_deck(raw_deck)
+    deck = infer_edges(raw_deck)
+    validate_deck(deck)
+"""
+
+from scrolly.deck.inference import infer_edges
+from scrolly.deck.model import (
+    Deck,
+    Edge,
+    Endpoint,
+    Position,
+    RawDeck,
+    RawEdge,
+    RawEndpoint,
+    Side,
+    Slide,
+    SlideGroup,
+)
+from scrolly.deck.parser import parse_deck
+from scrolly.deck.schema import deck_source_schema
+from scrolly.deck.validator import validate_deck, validate_raw_deck
+
+__all__ = [
+    "Deck",
+    "Edge",
+    "Endpoint",
+    "SlideGroup",
+    "Position",
+    "RawDeck",
+    "RawEdge",
+    "RawEndpoint",
+    "Side",
+    "Slide",
+    "deck_source_schema",
+    "infer_edges",
+    "parse_deck",
+    "validate_deck",
+    "validate_raw_deck",
+]

scrolly-0.1.0/scrolly/deck/inference.py

@@ -0,0 +1,61 @@
+"""Fill in omitted edge sides by inferring from slide positions.
+
+An endpoint with `side=None` has its side inferred from where the other
+endpoint's slide sits relative to this one on the grid:
+
+    dx > 0 → right    dx < 0 → left
+    dy > 0 → bottom   dy < 0 → top
+
+If the two slides are diagonal (dx ≠ 0 and dy ≠ 0), there is no unique
+side and a `DeckInferenceError` is raised.
+"""
+
+from __future__ import annotations
+
+from scrolly.deck.model import Deck, Edge, Endpoint, Position, RawDeck, Side
+from scrolly.errors import DeckInferenceError
+
+
+def infer_edges(deck: RawDeck) -> Deck:
+    """Return a `Deck` with every edge's sides fully specified."""
+    positions = {slide.id: slide.position for slide in deck.slides}
+    inferred: list[Edge] = []
+
+    for idx, edge in enumerate(deck.edges):
+        a_pos = positions[edge.a.slide_id]
+        b_pos = positions[edge.b.slide_id]
+
+        a_side = edge.a.side or _infer_side(a_pos, b_pos, idx, edge.a.slide_id, edge.b.slide_id)
+        b_side = edge.b.side or _infer_side(b_pos, a_pos, idx, edge.b.slide_id, edge.a.slide_id)
+
+        inferred.append(
+            Edge(
+                a=Endpoint(slide_id=edge.a.slide_id, side=a_side),
+                b=Endpoint(slide_id=edge.b.slide_id, side=b_side),
+            )
+        )
+
+    return Deck(title=deck.title, slides=deck.slides, edges=tuple(inferred), groups=deck.groups)
+
+
+def _infer_side(
+    from_pos: Position,
+    to_pos: Position,
+    edge_idx: int,
+    from_id: str,
+    to_id: str,
+) -> Side:
+    """Return the side of `from_pos`'s slide that faces `to_pos`'s slide."""
+    dx = to_pos.x - from_pos.x
+    dy = to_pos.y - from_pos.y
+
+    if dx != 0 and dy == 0:
+        return Side.RIGHT if dx > 0 else Side.LEFT
+    if dy != 0 and dx == 0:
+        return Side.BOTTOM if dy > 0 else Side.TOP
+
+    # Diagonal or same cell — no unique side.
+    raise DeckInferenceError(
+        f"edges[{edge_idx}]: cannot infer side for '{from_id}' — "
+        f"'{from_id}' and '{to_id}' are not on the same row or column"
+    )

scrolly-0.1.0/scrolly/deck/model.py

@@ -0,0 +1,103 @@
+"""Data model for the deck (Layer A).
+
+The parser produces a `RawDeck` (edges may have omitted sides). The inference
+step fills in omitted sides and produces a `Deck` (every edge side is known).
+Downstream layers work exclusively with the fully-specified `Deck`.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+from pathlib import Path
+
+
+class Side(Enum):
+    """One of the four sides of a slide. Edges attach to sides."""
+
+    TOP = "top"
+    BOTTOM = "bottom"
+    LEFT = "left"
+    RIGHT = "right"
+
+
+@dataclass(frozen=True)
+class Position:
+    """Integer grid position. x increases left → right, y increases top → bottom."""
+
+    x: int
+    y: int
+
+
+@dataclass(frozen=True)
+class Slide:
+    """One slide on the canvas.
+
+    The slide's *type* (which renderer handles it) is encoded in the
+    `source` filename's suffix and resolved at render time via
+    `scrolly.slide.get_renderer_for_path`. No `type` field on the model.
+    """
+
+    id: str
+    position: Position
+    source: Path
+
+
+@dataclass(frozen=True)
+class RawEndpoint:
+    """Edge endpoint pre-inference — the side may be omitted."""
+
+    slide_id: str
+    side: Side | None
+
+
+@dataclass(frozen=True)
+class Endpoint:
+    """Edge endpoint post-inference — the side is always known."""
+
+    slide_id: str
+    side: Side
+
+
+@dataclass(frozen=True)
+class RawEdge:
+    """Undirected edge between two slides, pre-inference."""
+
+    a: RawEndpoint
+    b: RawEndpoint
+
+
+@dataclass(frozen=True)
+class Edge:
+    """Undirected edge between two slides, fully specified."""
+
+    a: Endpoint
+    b: Endpoint
+
+
+@dataclass(frozen=True)
+class SlideGroup:
+    """A named group of slides, visualised as a background rectangle in deck view."""
+
+    label: str
+    slide_ids: tuple[str, ...]
+
+
+@dataclass(frozen=True)
+class RawDeck:
+    """Deck as parsed from disk, with edges potentially missing side info."""
+
+    title: str | None
+    slides: tuple[Slide, ...]
+    edges: tuple[RawEdge, ...]
+    groups: tuple[SlideGroup, ...] = ()
+
+
+@dataclass(frozen=True)
+class Deck:
+    """Deck after inference, with every edge side fully specified."""
+
+    title: str | None
+    slides: tuple[Slide, ...]
+    edges: tuple[Edge, ...]
+    groups: tuple[SlideGroup, ...] = ()