scrolly 0.1.0__py3-none-any.whl

scrolly/__init__.py

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

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/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/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/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, ...] = ()

scrolly/deck/parser.py

@@ -0,0 +1,168 @@
+"""Parse a JSON5 deck file into a `RawDeck`.
+
+Purely syntactic: checks file shape (required fields, types) and returns a
+`RawDeck` whose edges may still have omitted sides. Semantic checks (unique
+ids, edges reference real slides, one-slide-per-cell, diagonal-inference
+rejection) live in `validator.py` and `inference.py`.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import json5
+
+from scrolly.deck.model import Position, RawDeck, RawEdge, RawEndpoint, Side, Slide, SlideGroup
+from scrolly.errors import DeckParseError
+
+
+def parse_deck(deck_path: Path) -> RawDeck:
+    """Load and parse a JSON5 deck file.
+
+    Slide source paths are resolved relative to the deck file's directory.
+    """
+    try:
+        raw = json5.loads(deck_path.read_text())
+    except ValueError as e:
+        raise DeckParseError(f"{deck_path}: could not parse JSON5: {e}") from e
+
+    if not isinstance(raw, dict):
+        raise DeckParseError(f"{deck_path}: deck file must be a JSON5 object, got {type(raw).__name__}")
+
+    title = raw.get("title")
+    if title is not None and not isinstance(title, str):
+        raise DeckParseError(f"{deck_path}: field 'title' must be a string if present")
+
+    slides_raw = _require_list(raw, "slides", deck_path)
+    slides, groups = _parse_slides_and_groups(slides_raw, deck_path)
+
+    edges_raw = raw.get("edges", [])
+    if not isinstance(edges_raw, list):
+        raise DeckParseError(f"{deck_path}: field 'edges' must be a list if present")
+    edges = tuple(_parse_edge(e, idx) for idx, e in enumerate(edges_raw))
+
+    return RawDeck(title=title, slides=slides, edges=edges, groups=groups)
+
+
+def _parse_slides_and_groups(slides_raw: list, deck_path: Path) -> tuple[tuple[Slide, ...], tuple[SlideGroup, ...]]:
+    deck_dir = deck_path.parent
+    slides: list[Slide] = []
+    groups: list[SlideGroup] = []
+    flat_idx = 0
+
+    for top_idx, item in enumerate(slides_raw):
+        ctx = f"slides[{top_idx}]"
+        if not isinstance(item, dict):
+            raise DeckParseError(f"{ctx}: must be an object, got {type(item).__name__}")
+
+        if "group" in item:
+            label = item["group"]
+            if not isinstance(label, str) or not label.strip():
+                raise DeckParseError(f"{ctx}: 'group' must be a non-empty string")
+            label = label.strip()
+
+            if "slides" not in item or not isinstance(item["slides"], list):
+                raise DeckParseError(f"{ctx}: group must have a 'slides' list")
+
+            group_slide_ids: list[str] = []
+            for inner_idx, inner in enumerate(item["slides"]):
+                inner_ctx = f"slides[{top_idx}].slides[{inner_idx}]"
+                if isinstance(inner, dict) and "group" in inner:
+                    raise DeckParseError(f"{inner_ctx}: nested groups are not allowed")
+                slide = _parse_slide(inner, deck_dir, flat_idx, inner_ctx)
+                slides.append(slide)
+                group_slide_ids.append(slide.id)
+                flat_idx += 1
+
+            groups.append(SlideGroup(label=label, slide_ids=tuple(group_slide_ids)))
+        else:
+            slide = _parse_slide(item, deck_dir, flat_idx, ctx)
+            slides.append(slide)
+            flat_idx += 1
+
+    return tuple(slides), tuple(groups)
+
+
+def _require_list(d: dict, key: str, deck_path: Path) -> list:
+    if key not in d:
+        raise DeckParseError(f"{deck_path}: missing required field '{key}'")
+    v = d[key]
+    if not isinstance(v, list):
+        raise DeckParseError(f"{deck_path}: field '{key}' must be a list, got {type(v).__name__}")
+    return v
+
+
+def _parse_slide(raw: Any, deck_dir: Path, idx: int, ctx: str | None = None) -> Slide:
+    if ctx is None:
+        ctx = f"slides[{idx}]"
+    if not isinstance(raw, dict):
+        raise DeckParseError(f"{ctx}: must be an object, got {type(raw).__name__}")
+
+    slide_id = _require_str(raw, "id", ctx)
+    position = _parse_position(raw, ctx)
+    source_raw = _require_str(raw, "source", ctx)
+
+    source = (deck_dir / source_raw).resolve()
+    return Slide(id=slide_id, position=position, source=source)
+
+
+def _parse_position(raw_slide: dict, ctx: str) -> Position:
+    if "position" not in raw_slide:
+        raise DeckParseError(f"{ctx}: missing required field 'position'")
+    raw_pos = raw_slide["position"]
+    if not isinstance(raw_pos, list) or len(raw_pos) != 2:
+        raise DeckParseError(f"{ctx}: 'position' must be a two-element array [x, y]")
+    x, y = raw_pos
+    if not _is_int(x) or not _is_int(y):
+        raise DeckParseError(f"{ctx}: 'position' entries must be integers")
+    return Position(x=x, y=y)
+
+
+def _require_str(d: dict, key: str, ctx: str) -> str:
+    if key not in d:
+        raise DeckParseError(f"{ctx}: missing required field '{key}'")
+    v = d[key]
+    if not isinstance(v, str):
+        raise DeckParseError(f"{ctx}: field '{key}' must be a string, got {type(v).__name__}")
+    return v
+
+
+def _is_int(v: Any) -> bool:
+    # bool is a subclass of int in Python — exclude it.
+    return isinstance(v, int) and not isinstance(v, bool)
+
+
+def _parse_edge(raw: Any, idx: int) -> RawEdge:
+    ctx = f"edges[{idx}]"
+    if not isinstance(raw, list):
+        raise DeckParseError(f"{ctx}: must be a two-element array, got {type(raw).__name__}")
+    if len(raw) != 2:
+        raise DeckParseError(f"{ctx}: must be a two-element array, got {len(raw)} elements")
+
+    return RawEdge(
+        a=_parse_endpoint(raw[0], f"{ctx}[0]"),
+        b=_parse_endpoint(raw[1], f"{ctx}[1]"),
+    )
+
+
+def _parse_endpoint(raw: Any, ctx: str) -> RawEndpoint:
+    if not isinstance(raw, str):
+        raise DeckParseError(f"{ctx}: endpoint must be a string, got {type(raw).__name__}")
+
+    parts = raw.split("|", 1)
+    slide_id = parts[0].strip()
+    if not slide_id:
+        raise DeckParseError(f"{ctx}: endpoint has empty slide id")
+
+    if len(parts) == 1:
+        return RawEndpoint(slide_id=slide_id, side=None)
+
+    side_str = parts[1].strip()
+    try:
+        side = Side(side_str)
+    except ValueError:
+        valid = ", ".join(s.value for s in Side)
+        raise DeckParseError(f"{ctx}: side '{side_str}' is not one of ({valid})") from None
+
+    return RawEndpoint(slide_id=slide_id, side=side)

scrolly/deck/schema.py

@@ -0,0 +1,104 @@
+"""JSON Schema for the deck source format."""
+
+
+def deck_source_schema() -> dict:
+    """Return a JSON Schema describing the deck JSON5 source format."""
+    return {
+        "$schema": "https://json-schema.org/draft/2020-12/schema",
+        "title": "Deck source format",
+        "description": (
+            "A JSON5 file describing the presentation: a list of slides "
+            "on an integer grid, plus optional edges connecting them."
+        ),
+        "type": "object",
+        "properties": {
+            "title": {
+                "type": "string",
+                "description": "Human-readable deck title.",
+            },
+            "slides": {
+                "type": "array",
+                "description": "The slides in the deck. Items are bare slide objects or group wrappers.",
+                "items": {
+                    "oneOf": [
+                        {
+                            "type": "object",
+                            "description": "A single slide.",
+                            "properties": {
+                                "id": {
+                                    "type": "string",
+                                    "description": "Unique slide identifier, referenced by edges.",
+                                },
+                                "position": {
+                                    "type": "array",
+                                    "description": "Integer grid position [x, y]. x increases left-to-right, y increases top-to-bottom.",
+                                    "items": {"type": "integer"},
+                                    "minItems": 2,
+                                    "maxItems": 2,
+                                },
+                                "source": {
+                                    "type": "string",
+                                    "description": (
+                                        "Path to the slide source file, relative to the deck file. "
+                                        "The filename suffix determines the slide type "
+                                        "(e.g. .static.md, .scrollimation.json, .storyboard.json)."
+                                    ),
+                                },
+                            },
+                            "required": ["id", "position", "source"],
+                            "additionalProperties": False,
+                        },
+                        {
+                            "type": "object",
+                            "description": "A group wrapper containing slides. Rendered as a labelled rectangle in deck view.",
+                            "properties": {
+                                "group": {
+                                    "type": "string",
+                                    "description": "Group label, displayed above the group rectangle in deck view.",
+                                },
+                                "slides": {
+                                    "type": "array",
+                                    "description": "Slides in this group.",
+                                    "items": {
+                                        "type": "object",
+                                        "properties": {
+                                            "id": {"type": "string"},
+                                            "position": {
+                                                "type": "array",
+                                                "items": {"type": "integer"},
+                                                "minItems": 2,
+                                                "maxItems": 2,
+                                            },
+                                            "source": {"type": "string"},
+                                        },
+                                        "required": ["id", "position", "source"],
+                                        "additionalProperties": False,
+                                    },
+                                    "minItems": 1,
+                                },
+                            },
+                            "required": ["group", "slides"],
+                            "additionalProperties": False,
+                        },
+                    ],
+                },
+            },
+            "edges": {
+                "type": "array",
+                "description": "Navigation edges connecting slides.",
+                "items": {
+                    "type": "array",
+                    "description": (
+                        "A two-element array of endpoint strings. "
+                        'Each endpoint is "slide_id" (side inferred from positions) '
+                        'or "slide_id|side" (side explicit: top, bottom, left, right).'
+                    ),
+                    "items": {"type": "string"},
+                    "minItems": 2,
+                    "maxItems": 2,
+                },
+            },
+        },
+        "required": ["slides"],
+        "additionalProperties": False,
+    }