scrolly 0.2.3__tar.gz → 0.2.4__tar.gz

{scrolly-0.2.3 → 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.3 → scrolly-0.2.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "scrolly"
-version = "0.2.3"
+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"
@@ -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.3 → 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.3 → 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.3 → 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.3 → 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.

{scrolly-0.2.3 → scrolly-0.2.4}/scrolly/render/assets/canvas.css

@@ -1023,7 +1023,7 @@ body.pan-transitioning .canvas {
   left: 0;
   width: 100%;
   height: 100%;
-  background: rgba(60, 60, 60, 0.5);
+  background: rgba(200, 200, 200, 0.5);
   backdrop-filter: blur(16px);
   -webkit-backdrop-filter: blur(16px);
 }

{scrolly-0.2.3 → scrolly-0.2.4}/scrolly/render/assets/canvas.js

@@ -1651,6 +1651,18 @@
     };
   }
 
+  // ---- resolveVersionLabel (pure — help-screen version display) ------------
+  // The " vX.Y.Z" fragment shown after "scrolly" in the help About panel, or
+  // "" when there is nothing to show. A `scrolly-version` URL override (null
+  // when the param is absent) takes precedence over the built-in
+  // `meta.version`; an empty override hides the version entirely — used by the
+  // capture pipeline so rendered help screens don't bake in a pre-release
+  // version number.
+  function resolveVersionLabel(override, metaVersion) {
+    const version = override !== null ? override : metaVersion;
+    return version ? " v" + version : "";
+  }
+
   // ---- Exports (for Node.js / Vitest testing) -------------------------------
 
   if (typeof exports !== "undefined") {
@@ -1668,6 +1680,7 @@
     exports.resolveTarget = resolveTarget;
     exports.decompressBundle = decompressBundle;
     exports.buildAutomationHook = buildAutomationHook;
+    exports.resolveVersionLabel = resolveVersionLabel;
   }
 
   // ---- DOM code (skipped in Node.js) ----------------------------------------
@@ -2054,11 +2067,12 @@
       const uniqueLine = formatCounts(p.unique);
       const compressedLine = p.compressed ? "yes" : "no";
       const savedLine = p.bytes_saved > 0 ? formatBytes(p.bytes_saved) : "0 B";
+      const versionParam = new URLSearchParams(window.location.search).get("scrolly-version");
 
       body.innerHTML =
         '<h2>About</h2>' +
         '<div class="help-about">' +
-        '<p class="help-about-title"><strong>scrolly</strong> v' + meta.version + '</p>' +
+        '<p class="help-about-title"><strong>scrolly</strong>' + resolveVersionLabel(versionParam, meta.version) + '</p>' +
         '<p><a href="https://opensource.org/licenses/MIT" target="_blank" rel="noopener">MIT License</a></p>' +
         '<p>' + meta.author + '</p>' +
         '<p><a href="' + meta.pypi_url + '" target="_blank" rel="noopener">' + meta.pypi_url + '</a></p>' +

{scrolly-0.2.3 → scrolly-0.2.4}/scrolly/slide/__init__.py

@@ -7,7 +7,7 @@ renderers with the element-IR registry.
 
 from scrolly.slide.element_ir import renderers as _element_renderers  # noqa: F401 — register element renderers
 from scrolly.slide.html import SlideHTML
-from scrolly.slide.ir import SlideIR
+from scrolly.slide.ir import SlideIR, element_source_types
 from scrolly.slide.processor import Renderer
 from scrolly.slide.registry import (
     find_renderer,
@@ -26,6 +26,7 @@ __all__ = [
     "Renderer",
     "SlideHTML",
     "SlideIR",
+    "element_source_types",
     "find_renderer",
     "get_ir_class_for_path",
     "register_ir",

{scrolly-0.2.3 → scrolly-0.2.4}/scrolly/slide/ir/__init__.py

@@ -15,6 +15,7 @@ from scrolly.slide.ir._framework.element import (
     MarkdownElement,
     MermaidElement,
     SlideElement,
+    element_source_types,
 )
 from scrolly.slide.ir._framework.utils import parse_json5_ir, resolve_asset_paths
 from scrolly.slide.ir.slide import SlideIR
@@ -33,6 +34,7 @@ __all__ = [
     "SlideElement",
     "SlideIR",
     "Vec2Keyframes",
+    "element_source_types",
     "parse_json5_ir",
     "resolve_asset_paths",
 ]