scrolly 0.2.1__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.1 → scrolly-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: scrolly
-Version: 0.2.1
+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.1 → 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.1 → scrolly-0.2.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "scrolly"
-version = "0.2.1"
+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.1 → scrolly-0.2.2}/scrolly/_cli/_cli.py

@@ -43,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,
@@ -51,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:
@@ -61,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}")

scrolly-0.2.2/scrolly/errors/catalog/E306.md

@@ -0,0 +1,20 @@
+# E306 - image_sequence timing constraint violated
+
+## Cause
+
+One of the timing constraints on `image_sequence` is violated:
+`frame_distance` must be `> 0`; `hold_fraction` must be in `[0, 1)` (so the
+crossfade `frame_distance * (1 - hold_fraction)` stays positive); `fade_in`
+and `fade_out` must be `>= 0`.
+
+## Example
+
+```json5
+{ image_sequence: ["a.png", "b.png"], frame_distance: 400, hold_fraction: 1 }
+// hold_fraction = 1 leaves no room to crossfade
+```
+
+## How to fix
+
+Set `frame_distance > 0`, `0 <= hold_fraction < 1`, and `fade_in,
+fade_out >= 0`. `hold_fraction` defaults to `0.2`, so it can be omitted.

{scrolly-0.2.1 → scrolly-0.2.2}/scrolly/pipeline/lint.py

@@ -145,9 +145,8 @@ def _check_image_sequence(
     diagnostics: list[Diagnostic],
 ) -> None:
     """Check the auto-generated opacity keyframes for an image sequence element."""
-    n = len(el.image_sequence)
-    timeline_start = el.scroll_offset - el.fade_in
-    timeline_end = el.scroll_offset + (n - 1) * el.frame_distance + el.hold + el.fade_out
+    timeline_start = el.timeline_start()
+    timeline_end = el.timeline_end()
     if timeline_start < 0:
         diagnostics.append(
             Diagnostic(

{scrolly-0.2.1 → scrolly-0.2.2}/scrolly/pipeline/orchestrator.py

@@ -12,6 +12,7 @@ from scrolly.pipeline.assets import copy_assets, rewrite_asset_refs
 from scrolly.pipeline.loader import load_deck
 from scrolly.pipeline.writer import write_output
 from scrolly.render.assembler import assemble
+from scrolly.render.bundled_assets import MermaidAsset, mermaid_asset
 from scrolly.slide.html import SlideHTML
 from scrolly.slide.ir import SlideIR
 from scrolly.slide.registry import find_renderer
@@ -25,8 +26,28 @@ def build_deck(
     inline: bool = True,
     simplified_zoom_control: bool = False,
     compress: bool = True,
+    offline: bool = False,
 ) -> Deck:
-    """Build a deck from `deck_path` into `out_dir`. Returns the fully-resolved `Deck`."""
+    """Build a deck from `deck_path` into `out_dir`. Returns the fully-resolved `Deck`.
+
+    Args:
+        deck_path: Path to the ``.deck.json`` source.
+        out_dir: Destination directory for ``index.html`` (and bundled
+            assets when ``inline=False``).
+        force: Allow overwriting a non-empty ``out_dir``.
+        inline: Inline CSS/JS/mermaid into ``index.html`` (default) vs.
+            emit separate files.
+        simplified_zoom_control: Use the legacy single-icon zoom-out
+            control instead of the default deck mini-map.
+        compress: Emit the combined-payload gzip+base64 bundle when the
+            ≥5% savings gate passes.
+        offline: Skip the mermaid CDN download and use the
+            wheel-bundled mermaid instead. Honored together with the
+            ``SCROLLY_OFFLINE`` environment variable.
+
+    Returns:
+        The fully-resolved ``Deck``.
+    """
     deck, slide_irs = load_deck(deck_path)
 
     # Bundler is the canonical "compressible payload tracker" whenever
@@ -56,6 +77,13 @@ def build_deck(
             if fallback:
                 chunks = _substitute_fallback(chunks, fallback)
 
+    # Resolve mermaid once when any chunk needs it — threaded into both
+    # assemble (for inlined content + help-screen version) and write_output
+    # (for the standalone-file emission under `inline=False`).
+    mermaid: MermaidAsset | None = None
+    if any(chunk.has_mermaid for chunk in chunks.values()):
+        mermaid = mermaid_asset(offline=offline)
+
     html = assemble(
         deck,
         chunks,
@@ -63,10 +91,10 @@ def build_deck(
         simplified_zoom_control=simplified_zoom_control,
         compressed_payload_json=compressed_payload_json,
         bundle_stats=bundle_stats,
+        mermaid=mermaid,
     )
-    has_mermaid = any(chunk.has_mermaid for chunk in chunks.values())
 
-    write_output(out_dir, html, force=force, has_mermaid=has_mermaid, inline=inline)
+    write_output(out_dir, html, force=force, mermaid=mermaid, inline=inline)
     if not inline:
         copy_assets(chunks, out_dir)
 

{scrolly-0.2.1 → scrolly-0.2.2}/scrolly/pipeline/writer.py

@@ -5,7 +5,7 @@ from __future__ import annotations
 from pathlib import Path
 
 from scrolly.errors import OutputError
-from scrolly.render import iter_assets, mermaid_asset
+from scrolly.render import MermaidAsset, iter_assets
 
 
 def write_output(
@@ -13,13 +13,25 @@ def write_output(
     html: str,
     *,
     force: bool = False,
-    has_mermaid: bool = False,
+    mermaid: MermaidAsset | None = None,
     inline: bool = True,
 ) -> None:
     """Write `html` as `out_dir/index.html` and optionally copy bundled assets.
 
-    If `out_dir` exists and is non-empty, `force=True` is required to overwrite.
-    In inline mode, only `index.html` is written (CSS/JS are embedded in the HTML).
+    Args:
+        out_dir: Destination directory.
+        html: Assembled page HTML.
+        force: Allow overwriting a non-empty `out_dir`.
+        mermaid: Resolved mermaid asset (passed through from
+            :func:`build_deck`). When ``inline=False`` and ``mermaid``
+            is non-None, the mermaid JS file is written alongside the
+            other bundled assets.
+        inline: When ``True``, only ``index.html`` is written (CSS, JS,
+            and mermaid are embedded in the HTML).
+
+    Raises:
+        OutputError: ``out_dir`` exists but is not a directory, or is
+            non-empty without ``force=True``.
     """
     if out_dir.exists():
         if not out_dir.is_dir():
@@ -36,6 +48,5 @@ def write_output(
     if not inline:
         for name, content in iter_assets():
             (out_dir / name).write_bytes(content)
-        if has_mermaid:
-            name, content = mermaid_asset()
-            (out_dir / name).write_bytes(content)
+        if mermaid is not None:
+            (out_dir / mermaid.name).write_bytes(mermaid.content)

scrolly-0.2.2/scrolly/render/__init__.py

@@ -0,0 +1,6 @@
+"""Final HTML assembly — canvas template + bundled static assets."""
+
+from scrolly.render.assembler import assemble
+from scrolly.render.bundled_assets import MermaidAsset, bundled_css, bundled_js, iter_assets, mermaid_asset
+
+__all__ = ["MermaidAsset", "assemble", "bundled_css", "bundled_js", "iter_assets", "mermaid_asset"]

{scrolly-0.2.1 → scrolly-0.2.2}/scrolly/render/assembler.py

@@ -15,7 +15,7 @@ from jinja2 import Environment, PackageLoader, StrictUndefined, select_autoescap
 from scrolly import __version__
 from scrolly.deck import Deck
 from scrolly.pipeline._bundler import BundleStats
-from scrolly.render.bundled_assets import bundled_css, bundled_js, mermaid_js
+from scrolly.render.bundled_assets import MermaidAsset, bundled_css, bundled_js
 from scrolly.render.nav_data import build_nav_data
 from scrolly.render.zoom_control import MinimapGeometry, compute_minimap_geometry
 from scrolly.slide import SlideHTML
@@ -43,6 +43,7 @@ def assemble(
     simplified_zoom_control: bool = False,
     compressed_payload_json: str | None = None,
     bundle_stats: BundleStats | None = None,
+    mermaid: MermaidAsset | None = None,
 ) -> str:
     """Render the deck and its chunks into a single HTML string.
 
@@ -59,6 +60,10 @@ def assemble(
         bundle_stats: Stats from the bundler's ``build()``, used to
             populate the help-screen statistics. ``None`` when no bundle
             was emitted.
+        mermaid: Resolved mermaid asset (content + version + source
+            tier), or ``None`` when the deck has no mermaid elements.
+            Inlined into the page when ``inline=True`` and present;
+            its version always lands in the help-screen meta.
 
     Returns:
         The rendered HTML page as a single string.
@@ -66,16 +71,16 @@ def assemble(
     template = _env().get_template("index.html.j2")
     nav_data = build_nav_data(deck, chunks)
     scoped_css_blocks = _collect_scoped_css(deck, chunks)
-    has_mermaid = any(chunk.has_mermaid for chunk in chunks.values())
+    has_mermaid = mermaid is not None
     minimap: MinimapGeometry | None = None if simplified_zoom_control else compute_minimap_geometry(deck)
-    meta = _build_meta(deck, chunks, bundle_stats=bundle_stats)
+    meta = _build_meta(deck, chunks, bundle_stats=bundle_stats, mermaid=mermaid)
 
     inline_vars = {}
     if inline:
         inline_vars["bundled_css"] = bundled_css()
         inline_vars["bundled_js"] = bundled_js()
-        if has_mermaid:
-            inline_vars["mermaid_js_content"] = mermaid_js()
+        if mermaid is not None:
+            inline_vars["mermaid_js_content"] = mermaid.content.decode("utf-8")
 
     html = template.render(
         title=deck.title or "scrolly",
@@ -100,8 +105,21 @@ def _build_meta(
     chunks: dict[str, SlideHTML],
     *,
     bundle_stats: BundleStats | None = None,
+    mermaid: MermaidAsset | None = None,
 ) -> dict[str, Any]:
-    """Build the metadata dict injected into the HTML for the help screen."""
+    """Build the metadata dict injected into the HTML for the help screen.
+
+    Args:
+        deck: The fully-resolved deck.
+        chunks: Rendered per-slide HTML chunks.
+        bundle_stats: Bundler snapshot for the payload-stats section.
+        mermaid: Resolved mermaid asset, whose version is surfaced in
+            the help-screen statistics. ``None`` for decks without
+            mermaid elements.
+
+    Returns:
+        Help-screen metadata dict.
+    """
     return {
         "version": __version__,
         "author": "Bert Pluymers",
@@ -110,6 +128,7 @@ def _build_meta(
             "slides": len(deck.slides),
             "edges": len(deck.edges),
             "payloads": _payload_stats(bundle_stats),
+            "mermaid_version": mermaid.version if mermaid is not None else None,
             "file_size": "__FILE_SIZE_PLACEHOLDER__",
         },
     }

{scrolly-0.2.1 → scrolly-0.2.2}/scrolly/render/assets/canvas.css

@@ -314,6 +314,48 @@ body {
   overflow: hidden;
 }
 
+/* ---- Mixed-font typography inside slide content ------------------------
+ *
+ * Slides routinely mix the body sans-serif with inline `<code>`, `<kbd>`,
+ * `<samp>` and `<pre>` blocks. By default the browser pairs `system-ui`
+ * (SF Pro / Segoe UI / Roboto) with the user's preferred generic
+ * `monospace` (Menlo / Consolas / Courier) — fonts not designed to share
+ * metrics — which makes inline `<code>` glyphs sit visibly higher or
+ * lower than adjacent sans-serif text whenever a layout depends on
+ * vertical alignment between lines.
+ *
+ * Two corrections, narrow scope (slide content only — UI chrome keeps
+ * its explicit per-component fonts):
+ *
+ *   1. Pin monospace to `ui-monospace` and OS-native pairs. `ui-monospace`
+ *      picks the platform partner of `system-ui` (SF Mono on macOS,
+ *      Cascadia Mono on Windows), drawn by the same designer to share
+ *      metrics with the sans-serif.
+ *
+ *   2. Set `font-size-adjust: from-font` on the slide-element wrapper.
+ *      The browser computes the body sans-serif's x-height ratio and
+ *      inherits it down; when a `<code>` descendant falls back to its
+ *      monospace family, the monospace font is rescaled so its x-height
+ *      matches the sans-serif's. The visible "weight" of glyphs aligns
+ *      across fonts even though their natural metrics differ.
+ *
+ * Together these reduce the residual mismatch to where it's no longer
+ * visible in normal slide layouts. The structural fix — a layout
+ * primitive that owns vertical pitch independently of font metrics —
+ * would supersede this CSS defaulting.
+ */
+.slide-type-slide-json .slide-element {
+  font-size-adjust: from-font;
+}
+
+.slide-type-slide-json .slide-element code,
+.slide-type-slide-json .slide-element kbd,
+.slide-type-slide-json .slide-element samp,
+.slide-type-slide-json .slide-element pre {
+  font-family: ui-monospace, SFMono-Regular, "SF Mono",
+               Menlo, Consolas, monospace;
+}
+
 /* Animation-driven slides (numeric scroll_range) counter-translate the
  * chunk's scroll-driven translateY so content stays visually stationary
  * while --scroll-position drives the calc()-based keyframe expressions