scrolly 0.2.2__tar.gz → 0.2.3__tar.gz

{scrolly-0.2.2 → scrolly-0.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: scrolly
-Version: 0.2.2
+Version: 0.2.3
 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
@@ -35,7 +35,7 @@ Compile a JSON5 deck into a self-contained, scrollable 2D-canvas HTML presentati
 
 *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)
+[![scrolly — scroll-driven 2D-canvas presentations](https://raw.githubusercontent.com/bertpl/scrolly/main/docs/assets/hero-v2.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/)

{scrolly-0.2.2 → scrolly-0.2.3}/README.md

@@ -4,7 +4,7 @@ Compile a JSON5 deck into a self-contained, scrollable 2D-canvas HTML presentati
 
 *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)
+[![scrolly — scroll-driven 2D-canvas presentations](https://raw.githubusercontent.com/bertpl/scrolly/main/docs/assets/hero-v2.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/)

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

@@ -1,6 +1,6 @@
 [project]
 name = "scrolly"
-version = "0.2.2"
+version = "0.2.3"
 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`),

{scrolly-0.2.2 → scrolly-0.2.3}/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.3}/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.3}/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.3}/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.3}/scrolly/render/assets/canvas.css

@@ -93,9 +93,13 @@ body {
   initial-value: 0.5;
 }
 
+/* `--view-scale` is the deck→slide interpolated scale applied to `.canvas`.
+ * `inherits: true` so the connector overlay (`.canvas-edge` / `#edge-dot`)
+ * can divide its stroke widths by it and stay a constant on-screen size
+ * regardless of how far deck view zooms out. */
 @property --view-scale {
   syntax: "<number>";
-  inherits: false;
+  inherits: true;
   initial-value: 1;
 }
 
@@ -859,7 +863,7 @@ body.view-deck .slide-container.selected:hover .subcanvas {
 .slide-group-label {
   position: absolute;
   transform: translate(-50%, -50%);
-  color: #000000;
+  color: var(--slide-group-label-color, #000000);
   font-family: system-ui, -apple-system, sans-serif;
   font-size: 5dvmax;
   font-weight: 600;
@@ -883,7 +887,21 @@ body.view-deck .slide-container.selected:hover .subcanvas {
   display: block;
   z-index: 5;
   opacity: calc(1 - var(--view-zoom, 1));
-  --connector-color: #4a4a4a;
+  --connector-color: #333333;
+  /* Connector line + end-dot sizes, in on-screen px. The rules below divide
+   * these by --view-scale so they stay visually constant regardless of how far
+   * deck view zooms out (which grows with the slide grid). Tune for thickness. */
+  --edge-width: 1.25;
+  --edge-dot: 4;
+  /* Sharp casing: a second, slightly wider set of connectors + dots is drawn
+   * in an opaque light tint (--edge-halo-color) directly behind the dark ones
+   * (.canvas-edge-halo / .edge-dot-cap-halo, emitted by BezierOverlay), giving
+   * a crisp light edge that separates them from dark backdrops without the
+   * softness of a blur. --edge-halo-ring is the extra on-screen px per side,
+   * divided by --view-scale to stay constant on-screen like the stroke widths
+   * above. */
+  --edge-halo-ring: 0.75;
+  --edge-halo-color: #cccccc;
 }
 
 /* ---- Slide-to-slide pan scale dip ------------------------------------- */
@@ -909,11 +927,37 @@ body.pan-transitioning .canvas {
 .canvas-edge {
   fill: none;
   stroke: var(--connector-color);
-  stroke-width: 3;
+  /* Divide by --view-scale so the line keeps a constant on-screen width
+   * regardless of grid size: non-scaling-stroke cancels the SVG-internal
+   * viewBox scale, the division cancels the .canvas deck-view transform. */
+  stroke-width: calc(var(--edge-width) / var(--view-scale, 1));
   vector-effect: non-scaling-stroke;
   stroke-linecap: round;
 }
 
+/* White casing drawn behind every connector (--edge-halo-ring px wider per
+ * side). BezierOverlay emits all casing paths before any dark path, so the
+ * casing never paints over a dark line where two connectors cross. */
+.canvas-edge-halo {
+  fill: none;
+  stroke: var(--edge-halo-color);
+  stroke-width: calc((var(--edge-width) + 2 * var(--edge-halo-ring)) / var(--view-scale, 1));
+  vector-effect: non-scaling-stroke;
+  stroke-linecap: round;
+}
+
+/* End-of-connector dots: round caps on a zero-length line in the #edge-dot
+ * marker. Same constant-on-screen-size treatment as the connector line. */
+.edge-dot-cap {
+  stroke-width: calc(var(--edge-dot) / var(--view-scale, 1));
+}
+
+/* Matching wider white casing for the dots, via the #edge-dot-halo marker. */
+.edge-dot-cap-halo {
+  stroke: var(--edge-halo-color);
+  stroke-width: calc((var(--edge-dot) + 2 * var(--edge-halo-ring)) / var(--view-scale, 1));
+}
+
 /* ---- Help button -------------------------------------------------------- */
 
 /* Styled like the simplified zoom control: same size, background, colour,

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

@@ -601,6 +601,10 @@
       this._config = snapConfig;
       this._containerFn = containerFn;
       this._enabled = true;
+      // The idle auto-snap (settle to nearest snap after IDLE_MS of scroll
+      // inactivity) can be turned off independently of `_enabled`, leaving the
+      // snap control, dots, and manual up()/down() intact. See setIdleSnap().
+      this._idleSnap = true;
       this._timer = null;
       this._anim = null;
       this._animTarget = null;
@@ -658,11 +662,21 @@
 
     schedule(slideId) {
       this.cancel();
-      if (!this._enabled) return;
+      if (!this._enabled || !this._idleSnap) return;
       if (!this._snapsFor(slideId)) return;
       this._timer = setTimeout(() => { this._timer = null; this._animateToNearest(slideId); }, SnapManager.IDLE_MS);
     }
 
+    // Toggle the idle auto-snap only. Unlike `_setEnabled`, this leaves the
+    // snap feature on (control, scrollbar snap dots, and manual up()/down()
+    // nav all keep working) — it just stops the post-idle settle from firing.
+    // The capture harness sets this off so scripted setScroll positions render
+    // exactly instead of being pulled toward a snap mid-capture.
+    setIdleSnap(enabled) {
+      this._idleSnap = enabled;
+      if (!enabled) this.cancel();
+    }
+
     cancel() {
       if (this._timer !== null) { clearTimeout(this._timer); this._timer = null; }
       if (this._anim !== null) { cancelAnimationFrame(this._anim); this._anim = null; }
@@ -689,8 +703,13 @@
 
       this._animTarget = target;
       const start = current;
-      const t0 = performance.now();
+      // Anchor t0 to the first frame's timestamp, not performance.now():
+      // a rAF timestamp can predate a now() taken just before scheduling,
+      // making elapsed (and thus t) negative on frame 1, which drives
+      // easeOutQuad below 0 and kicks the position backward for one frame.
+      let t0 = null;
       const step = (now) => {
+        if (t0 === null) t0 = now;
         const elapsed = now - t0;
         const t = Math.min(1, elapsed / SnapManager.DURATION_MS);
         const ease = SnapManager.easeOutQuad(t);
@@ -1014,6 +1033,11 @@
         const label = document.createElement("span");
         label.className = "slide-group-label";
         label.textContent = group.label;
+        // `label_color` is resolved server-side (override or auto-contrast
+        // pick); fall back to the CSS default if absent.
+        if (group.label_color) {
+          label.style.setProperty("--slide-group-label-color", group.label_color);
+        }
         this._elements.push({ group, svg, path, label });
       }
       const firstSlideContainer = this._canvas.querySelector(".slide-container");
@@ -1293,15 +1317,21 @@
       this._svg.style.height = data.height;
 
       const ns = "http://www.w3.org/2000/svg";
-      for (const d of data.paths) {
+      // Two passes so every white casing sits behind every dark connector:
+      // all halos first (wider, opaque white), then all dark lines on top.
+      // Interleaving would let a later edge's casing paint over an earlier
+      // edge's dark line at a crossing.
+      const addPath = (d, cls, marker) => {
         const path = document.createElementNS(ns, "path");
-        path.setAttribute("class", "canvas-edge");
-        path.setAttribute("marker-start", "url(#edge-dot)");
-        path.setAttribute("marker-end", "url(#edge-dot)");
+        path.setAttribute("class", cls);
+        path.setAttribute("marker-start", `url(#${marker})`);
+        path.setAttribute("marker-end", `url(#${marker})`);
         path.setAttribute("d", d);
         this._svg.appendChild(path);
         this._paths.push(path);
-      }
+      };
+      for (const d of data.paths) addPath(d, "canvas-edge-halo", "edge-dot-halo");
+      for (const d of data.paths) addPath(d, "canvas-edge", "edge-dot");
     }
   }
 
@@ -2174,6 +2204,13 @@
       scrollManager,
       isAnimating: () => document.body.classList.contains("view-transitioning"),
     });
+    // Turn off the idle auto-snap under automation: scripted setScroll
+    // positions are exact, but the idle-snap timer would otherwise fire between
+    // the capture's (slow) screenshots and animate the scroll toward the
+    // nearest snap — a visible wobble + catch-up jump. The snap feature stays
+    // enabled, so the scrollbar's snap dots (a key debug-mode cue) and the
+    // scripted Shift+Arrow nav both keep working.
+    snapManager.setIdleSnap(false);
     console.log("scrolly automation hook active");
   }
 })(typeof module !== "undefined" ? module.exports : {});

scrolly-0.2.3/scrolly/render/color.py

@@ -0,0 +1,66 @@
+"""Color utilities for rendering: luminance and legible-text-color picks."""
+
+from __future__ import annotations
+
+import re
+
+_HEX_COLOR_RE = re.compile(r"^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6})$")
+
+
+def _hex_to_rgb(hex_color: str) -> tuple[int, int, int]:
+    """Parse a ``#RGB`` or ``#RRGGBB`` string into 0-255 ``(r, g, b)`` bytes.
+
+    Args:
+        hex_color: A ``#RGB`` or ``#RRGGBB`` hex color string.
+
+    Returns:
+        The ``(r, g, b)`` byte triple.
+
+    Raises:
+        ValueError: If ``hex_color`` is not a ``#RGB`` or ``#RRGGBB`` color.
+    """
+    if not _HEX_COLOR_RE.match(hex_color):
+        raise ValueError(f"not a #RGB or #RRGGBB color: {hex_color!r}")
+    digits = hex_color[1:]
+    if len(digits) == 3:
+        digits = "".join(c * 2 for c in digits)
+    return int(digits[0:2], 16), int(digits[2:4], 16), int(digits[4:6], 16)
+
+
+def _srgb_to_linear(channel: int) -> float:
+    """Linearize one sRGB 0-255 channel to its 0-1 linear-light value."""
+    c = channel / 255
+    return c / 12.92 if c <= 0.03928 else ((c + 0.055) / 1.055) ** 2.4
+
+
+def relative_luminance(hex_color: str) -> float:
+    """Compute the WCAG relative luminance of a hex color.
+
+    Args:
+        hex_color: A ``#RGB`` or ``#RRGGBB`` hex color string.
+
+    Returns:
+        Relative luminance in ``[0, 1]`` (sRGB channels linearized and weighted
+        per WCAG 2.x).
+    """
+    r, g, b = _hex_to_rgb(hex_color)
+    return 0.2126 * _srgb_to_linear(r) + 0.7152 * _srgb_to_linear(g) + 0.0722 * _srgb_to_linear(b)
+
+
+def legible_text_color(background: str) -> str:
+    """Pick black or white for the most legible text on a background color.
+
+    Chooses whichever of black or white yields the higher WCAG contrast ratio
+    against ``background``. The crossover sits at luminance ≈ 0.179, so light
+    and mid-tone backgrounds get black and only genuinely dark ones get white.
+
+    Args:
+        background: A ``#RGB`` or ``#RRGGBB`` background color string.
+
+    Returns:
+        ``"#000000"`` or ``"#ffffff"``.
+    """
+    luminance = relative_luminance(background)
+    contrast_black = (luminance + 0.05) / 0.05
+    contrast_white = 1.05 / (luminance + 0.05)
+    return "#000000" if contrast_black >= contrast_white else "#ffffff"

{scrolly-0.2.2 → scrolly-0.2.3}/scrolly/render/nav_data.py

@@ -23,9 +23,15 @@ from __future__ import annotations
 from typing import Any
 
 from scrolly.deck import Deck
+from scrolly.render.color import legible_text_color
 from scrolly.render.fan import FAN_SPACING_FACTOR, compute_fan_offsets
 from scrolly.slide import SlideHTML
 
+# Default group-background fill, used when a group sets no explicit `color`.
+# Mirrors `.slide-group-bg { fill }` in canvas.css so the label auto-contrast
+# pick matches the rendered background.
+DEFAULT_GROUP_BACKGROUND = "#dcdcdc"
+
 
 def build_nav_data(deck: Deck, chunks: dict[str, SlideHTML]) -> dict[str, Any]:
     """Return a JSON-serialisable representation of the deck for the client.
@@ -93,10 +99,15 @@ def build_nav_data(deck: Deck, chunks: dict[str, SlideHTML]) -> dict[str, Any]:
 
     edges_data = _build_edges(deck, fan)
 
-    groups_data = [
-        {"label": g.label, "slide_ids": list(g.slide_ids), **({"color": g.color} if g.color else {})}
-        for g in deck.groups
-    ]
+    groups_data = []
+    for g in deck.groups:
+        entry: dict[str, Any] = {"label": g.label, "slide_ids": list(g.slide_ids)}
+        if g.color:
+            entry["color"] = g.color
+        # Resolve the label color here so the client just applies it: an explicit
+        # `label_color` override wins, else auto-contrast against the background.
+        entry["label_color"] = g.label_color or legible_text_color(g.color or DEFAULT_GROUP_BACKGROUND)
+        groups_data.append(entry)
 
     return {
         "initial_slide": deck.slides[0].id if deck.slides else None,

{scrolly-0.2.2 → scrolly-0.2.3}/scrolly/render/templates/index.html.j2

@@ -23,9 +23,19 @@
                 markerWidth="0.001" markerHeight="0.001"
                 refX="0" refY="0"
                 overflow="visible">
-          <line x1="0" y1="0" x2="0" y2="0"
+          <line class="edge-dot-cap"
+                x1="0" y1="0" x2="0" y2="0"
                 stroke="var(--connector-color)"
-                stroke-width="15"
+                stroke-linecap="round"
+                vector-effect="non-scaling-stroke"/>
+        </marker>
+        <marker id="edge-dot-halo"
+                markerUnits="userSpaceOnUse"
+                markerWidth="0.001" markerHeight="0.001"
+                refX="0" refY="0"
+                overflow="visible">
+          <line class="edge-dot-cap-halo"
+                x1="0" y1="0" x2="0" y2="0"
                 stroke-linecap="round"
                 vector-effect="non-scaling-stroke"/>
         </marker>