vividly 0.0.1__py3-none-any.whl

vividly/__init__.py

@@ -0,0 +1 @@
+"""Vividly presentation builder and runner."""

vividly/cli.py

@@ -0,0 +1,344 @@
+"""Command-line interface for Vividly."""
+
+import argparse
+import functools
+import hashlib
+import http.server
+import json
+import shutil
+from collections.abc import Callable, Generator
+from contextlib import contextmanager
+from importlib import resources
+from importlib.metadata import version
+from pathlib import Path
+from typing import TypedDict, cast
+
+from .constants import (
+    BASELINE_NAME,
+    DEFAULT_PORT,
+    DEFAULT_SITE_ROOT,
+    EXISTING_FILE_LIST_LIMIT,
+    FRAMEWORK_VERSION_PATH,
+    IGNORED_NAMES,
+    MANAGED_ROLE,
+    SEED_PATH_PREFIXES,
+    SEED_ROLE,
+    SITE_INDEX_NAME,
+    STARTER_PROJECT_NAME,
+    STARTER_PROJECT_PACKAGE,
+)
+from .thumbnails import ThumbnailError, generate_thumbnails
+
+type CommandHandler = Callable[[argparse.Namespace], None]
+
+
+class FileRecord(TypedDict):
+    """Hash and upgrade policy for one file Vividly installed."""
+
+    sha256: str
+    role: str
+
+
+class Baseline(TypedDict):
+    """The set of files Vividly installed, as installed."""
+
+    framework_version: str
+    tool_version: str
+    files: dict[str, FileRecord]
+
+
+def unimplemented_command(arguments: argparse.Namespace) -> None:
+    """Report that a command is not implemented."""
+    command = cast(str, arguments.command)
+    print(f"vividly {command} is not implemented.")
+
+
+@contextmanager
+def starter_project() -> Generator[Path, None, None]:
+    """Yield a filesystem path to the packaged starter project."""
+    resource = resources.files(STARTER_PROJECT_PACKAGE).joinpath(STARTER_PROJECT_NAME)
+    with resources.as_file(resource) as path:
+        yield path
+
+
+def framework_version(payload_root: Path) -> str:
+    """Read the version the framework payload declares for itself."""
+    return (payload_root / FRAMEWORK_VERSION_PATH).read_text(encoding="utf-8").strip()
+
+
+def tool_version() -> str:
+    """Return the version of the installed vividly package."""
+    return version("vividly")
+
+
+def version_banner() -> str:
+    """Describe the tool and the framework version it can install."""
+    with starter_project() as starter:
+        return f"vividly {tool_version()} (bundled framework {framework_version(starter)})"
+
+
+def hash_file(path: Path) -> str:
+    """Return the SHA-256 digest of a file, with text line endings normalized to LF."""
+    data = path.read_bytes()
+    if b"\0" not in data:
+        data = data.replace(b"\r\n", b"\n")
+    return hashlib.sha256(data).hexdigest()
+
+
+def file_role(relative_path: str) -> str:
+    """Classify a shipped file as author content that update leaves alone, or as ours to upgrade."""
+    if relative_path.startswith(SEED_PATH_PREFIXES):
+        return SEED_ROLE
+    return MANAGED_ROLE
+
+
+def payload_files(payload_root: Path) -> list[Path]:
+    """List the files a copy of the payload installs, sorted by relative path."""
+    files = [
+        path
+        for path in payload_root.rglob("*")
+        if path.is_file() and IGNORED_NAMES.isdisjoint(path.relative_to(payload_root).parts)
+    ]
+    return sorted(files, key=lambda path: path.relative_to(payload_root).as_posix())
+
+
+def build_baseline(payload_root: Path) -> Baseline:
+    """Describe every file the payload installs, so update can detect later edits."""
+    files: dict[str, FileRecord] = {}
+    for path in payload_files(payload_root):
+        relative = path.relative_to(payload_root).as_posix()
+        files[relative] = {"sha256": hash_file(path), "role": file_role(relative)}
+    return {
+        "framework_version": framework_version(payload_root),
+        "tool_version": tool_version(),
+        "files": files,
+    }
+
+
+def write_baseline(project_root: Path, baseline: Baseline) -> Path:
+    """Write the baseline to the project root."""
+    baseline_path = project_root / BASELINE_NAME
+    baseline_path.write_text(json.dumps(baseline, indent=2) + "\n", encoding="utf-8")
+    return baseline_path
+
+
+def confirm(prompt: str) -> bool:
+    """Ask the user to approve an action."""
+    try:
+        answer = input(f"{prompt} [y/N]: ")
+    except EOFError:
+        return False
+    return answer.strip().lower() in {"y", "yes"}
+
+
+def existing_files(root: Path) -> list[str]:
+    """List the files already in a directory, as paths relative to it."""
+    if not root.is_dir():
+        return []
+    return sorted(
+        path.relative_to(root).as_posix() for path in root.rglob("*") if path.is_file()
+    )
+
+
+def init_command(arguments: argparse.Namespace) -> None:
+    """Create a new presentation from the packaged starter project."""
+    presentation_root = cast(Path, arguments.presentation_root).expanduser().resolve()
+    assume_yes = cast(bool, arguments.assume_yes)
+
+    if presentation_root.exists() and not presentation_root.is_dir():
+        raise SystemExit(f"vividly init: {presentation_root} is not a directory")
+
+    if (presentation_root / BASELINE_NAME).is_file():
+        raise SystemExit(
+            f"vividly init: {presentation_root} already holds a Vividly presentation "
+            f"({BASELINE_NAME}).\n"
+            "Run vividly update to upgrade it, or choose an empty directory."
+        )
+
+    existing = existing_files(presentation_root)
+    if existing:
+        shown = existing[:EXISTING_FILE_LIST_LIMIT]
+        listing = "\n".join(f"  {name}" for name in shown)
+        remainder = len(existing) - len(shown)
+        if remainder:
+            listing += f"\n  ...and {remainder} more"
+        plural = "" if len(existing) == 1 else "s"
+        raise SystemExit(
+            f"vividly init: {presentation_root} already contains {len(existing)} file{plural}:\n"
+            f"{listing}\n"
+            "Choose an empty directory, or remove these files before initializing.\n"
+            "If these are Vividly files from an older layout, run vividly update instead."
+        )
+
+    with starter_project() as starter:
+        print(f"Vividly will create a new presentation in {presentation_root}")
+        print("It copies the starter project, which adds:")
+        for entry in sorted(starter.iterdir(), key=lambda path: path.name):
+            suffix = "/" if entry.is_dir() else ""
+            print(f"  {entry.name}{suffix}")
+        print(f"and records the installed files in {BASELINE_NAME}.")
+
+        if not assume_yes and not confirm("Proceed?"):
+            print("vividly init: cancelled. Nothing was written.")
+            return
+
+        shutil.copytree(
+            starter,
+            presentation_root,
+            dirs_exist_ok=True,
+            ignore=shutil.ignore_patterns(*IGNORED_NAMES),
+        )
+        baseline = build_baseline(starter)
+
+    baseline_path = write_baseline(presentation_root, baseline)
+    print(f"Created presentation in {presentation_root}")
+    print(f"Recorded {len(baseline['files'])} files in {baseline_path}")
+    print('\nUse "vividly run" to edit your presentation.')
+
+
+def run_command(arguments: argparse.Namespace) -> None:
+    """Run a Vividly presentation locally."""
+    port = cast(int, arguments.port)
+    presentation_root = cast(Path, arguments.presentation_root).expanduser().resolve()
+    site_root = presentation_root / DEFAULT_SITE_ROOT
+    if not (site_root / SITE_INDEX_NAME).is_file():
+        raise SystemExit(
+            f"vividly run: no presentation site found at {site_root}\n"
+            "Run this command from a Vividly presentation root or pass its path."
+        )
+
+    handler = functools.partial(
+        http.server.SimpleHTTPRequestHandler,
+        directory=str(site_root),
+    )
+
+    with http.server.ThreadingHTTPServer(("", port), handler) as server:
+        print(f"Serving {site_root} at http://localhost:{server.server_port}")
+        try:
+            server.serve_forever()
+        except KeyboardInterrupt:
+            print("\nServer stopped.")
+
+
+def thumbnails_command(arguments: argparse.Namespace) -> None:
+    """Generate all thumbnails or a selected subset."""
+    presentation_root = cast(Path, arguments.presentation_root)
+    addresses = cast(list[str] | None, arguments.slides)
+
+    def report_progress(position: int, total: int, address: str) -> None:
+        print(f"Capturing {position}/{total}: {address}", flush=True)
+
+    try:
+        results = generate_thumbnails(
+            presentation_root,
+            addresses,
+            on_progress=report_progress,
+        )
+    except ThumbnailError as error:
+        raise SystemExit(f"vividly thumbnails: {error}") from error
+    for result in results:
+        print(f"Captured {result.address} at step {result.step}: {result.path}")
+    count = len(results)
+    noun = "thumbnail" if count == 1 else "thumbnails"
+    print(f"Generated {count} {noun}.")
+
+
+COMMANDS: tuple[tuple[str, str, CommandHandler], ...] = (
+    ("init", "Initialize a new presentation", init_command),
+    ("update", "Update the Vividly runtime", unimplemented_command),
+    ("run", "Run a presentation locally", run_command),
+    ("install-browser", "Install Chromium for thumbnail generation", unimplemented_command),
+    ("thumbnails", "Regenerate committed slide thumbnails", thumbnails_command),
+    ("publish", "Publish a presentation", unimplemented_command),
+)
+
+
+def port_number(value: str) -> int:
+    """Parse a valid TCP port number."""
+    port = int(value)
+    if not 1 <= port <= 65535:
+        raise argparse.ArgumentTypeError("port must be between 1 and 65535")
+    return port
+
+
+def create_parser() -> argparse.ArgumentParser:
+    """Create the command-line argument parser."""
+    parser = argparse.ArgumentParser(
+        prog="vividly",
+        description="Build, run, and publish Vividly presentations.",
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=version_banner(),
+        help="show the CLI version and the runtime version it installs",
+    )
+    subparsers = parser.add_subparsers(dest="command")
+
+    for name, help_text, handler in COMMANDS:
+        command_parser = subparsers.add_parser(name, help=help_text)
+        command_parser.set_defaults(handler=handler)
+        if name == "init":
+            command_parser.add_argument(
+                "presentation_root",
+                type=Path,
+                nargs="?",
+                default=Path.cwd(),
+                metavar="PATH",
+                help="empty directory for the new presentation (default: current directory)",
+            )
+            command_parser.add_argument(
+                "-y",
+                "--yes",
+                dest="assume_yes",
+                action="store_true",
+                help="skip the confirmation prompt",
+            )
+        if name == "run":
+            command_parser.add_argument(
+                "presentation_root",
+                type=Path,
+                nargs="?",
+                default=Path.cwd(),
+                metavar="PATH",
+                help="presentation root containing site/ (default: current directory)",
+            )
+            command_parser.add_argument(
+                "--port",
+                type=port_number,
+                default=DEFAULT_PORT,
+                help=f"port for the local server (default: {DEFAULT_PORT})",
+            )
+        if name == "thumbnails":
+            command_parser.add_argument(
+                "presentation_root",
+                type=Path,
+                nargs="?",
+                default=Path.cwd(),
+                metavar="PATH",
+                help="presentation root containing site/ (default: current directory)",
+            )
+            command_parser.add_argument(
+                "--slide",
+                action="append",
+                dest="slides",
+                metavar="ADDRESS",
+                help="complete manifest address to capture (repeatable; default: all slides)",
+            )
+
+    return parser
+
+
+def main() -> None:
+    """Run the Vividly command-line interface."""
+    parser = create_parser()
+    arguments = parser.parse_args()
+    if arguments.command is None:
+        parser.print_help()
+        return
+    handler = cast(CommandHandler, arguments.handler)
+    handler(arguments)
+
+
+if __name__ == "__main__":
+    main()

vividly/constants.py

@@ -0,0 +1,25 @@
+"""Shared defaults for Vividly."""
+
+from pathlib import Path
+
+DEFAULT_SITE_ROOT = Path("site")
+DEFAULT_PORT = 8080
+
+SITE_INDEX_NAME = "index.html"
+
+# The framework declares its own version, so it can later ship separately from the tool.
+FRAMEWORK_VERSION_PATH = Path("site/vividly/version.txt")
+
+# Records what Vividly shipped, so update can tell its own files from the author's.
+BASELINE_NAME = "vividly-baseline.json"
+
+EXISTING_FILE_LIST_LIMIT = 10
+
+MANAGED_ROLE = "managed"
+SEED_ROLE = "seed"
+SEED_PATH_PREFIXES = ("site/slides/",)
+
+IGNORED_NAMES = frozenset({".DS_Store", "Thumbs.db", "__pycache__"})
+
+STARTER_PROJECT_PACKAGE = "vividly.resources"
+STARTER_PROJECT_NAME = "starter-project"

vividly/resources/__init__.py

@@ -0,0 +1 @@
+"""Packaged resources for creating Vividly presentation projects."""

vividly/resources/starter-project/.github/copilot-instructions.md

@@ -0,0 +1,10 @@
+# Vividly Presentation Project
+
+This repository contains a Vividly presentation. Keep the deployable presentation inside `site/`.
+
+- Read `vividly/docs/` before changing runtime behavior or presentation structure.
+- Treat `site/vividly/` as installed runtime infrastructure. Do not edit it while authoring slides.
+- Define presentation order and configuration in `site/slides/presentation.yaml`.
+- Put each slide in its own directory under `site/slides/` and keep slide-specific scripts, styles, data, assets, and vendored dependencies there.
+- Put presentation-wide assets, fonts, themes, and vendored dependencies under `site/vividly/`.
+- Preserve browser-native ES modules and the no-build-step deployment model.

vividly/resources/starter-project/.github/instructions/vividly.instructions.md

@@ -0,0 +1,15 @@
+---
+description: "Use when creating or modifying Vividly slides, presentation manifests, themes, assets, or other files under the hosted site."
+applyTo:
+  - "site/slides/**"
+  - "site/vividly/themes/**"
+---
+# Vividly Authoring Instructions
+
+- Read `vividly/docs/presentation-orchestration-spec.md` for the runtime contract.
+- Keep every slide independently authorable in its own `site/slides/<slide-id>/` directory.
+- Use browser-native ES modules; do not introduce a compilation or bundling step.
+- Resolve slide-local templates, styles, data, assets, and vendored modules relative to the slide module.
+- Register slides in `site/slides/presentation.yaml`; do not hard-code presentation order in the runtime.
+- Put reusable presentation styling in `site/vividly/themes/` rather than leaking slide CSS globally.
+- Do not modify `site/vividly/runtime/` during ordinary presentation authoring.

vividly/resources/starter-project/.github/skills/vividly-presentations/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: vividly-presentations
+description: "Create and revise Vividly web presentations. Use when adding slides, arranging the presentation manifest, authoring slide steps, or working with presentation assets and themes."
+argument-hint: "Describe the presentation or slide change"
+---
+# Vividly Presentations
+
+## Procedure
+
+1. Read `vividly/docs/presentation-orchestration-spec.md` and inspect `site/slides/presentation.yaml`.
+2. Inspect neighboring slides for established visual and structural conventions.
+3. Create or update one self-contained directory under `site/slides/` for each affected slide.
+4. Keep slide-local markup, CSS, JavaScript, data, assets, and dependencies inside that directory.
+5. Update `site/slides/presentation.yaml` when slides or presentation structure change.
+6. Run `vividly run`, open the reported URL, and verify navigation, builds, layout, and assets in the browser.
+
+Do not edit `site/vividly/runtime/` merely to accommodate one slide. Runtime changes require an explicit presentation-system task.

vividly/resources/starter-project/site/index.html

@@ -0,0 +1,20 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Vividly</title>
+
+  <link rel="stylesheet" href="vividly/css/base.css">
+  <link rel="stylesheet" href="vividly/css/kit.css">
+  <link rel="stylesheet" href="vividly/css/controls.css">
+
+  <script src="vividly/vendor/js-yaml.min.js"></script>
+  <script src="vividly/vendor/marked.min.js"></script>
+  <script src="vividly/vendor/highlight.min.js"></script>
+  <script type="module" src="vividly/runtime/presentation.js"></script>
+</head>
+<body>
+  <vividly-presentation manifest="./slides/presentation.yaml"></vividly-presentation>
+</body>
+</html>

vividly/resources/starter-project/site/slides/annotated-markdown/document.md

@@ -0,0 +1,50 @@
+<vividly-document-header title="Annotated Markdown">
+A document reader whose annotations form the slide's step sequence.
+</vividly-document-header>
+
+# Controls and slides
+
+Vividly controls render regions of a slide. They expose state as properties and events,
+but they do not know about the presentation's step axis.
+
+<vividly-annotation title="The control boundary">
+The viewer can appear beside other content or more than once on a slide. That makes it
+a control rather than a slide module.
+</vividly-annotation>
+
+## A thin adapter
+
+The reusable slide module loads this document, counts its annotations, and maps each
+step to `activeAnnotation`.
+
+```js
+setStep(step) {
+  this.viewer.revealAnnotation(step);
+}
+```
+
+<vividly-annotation title="Absolute steps">
+Selecting annotation 1 always establishes the same state. The viewer does not need to
+know whether the presenter moved forward, backward, or followed a deep link.
+</vividly-annotation>
+
+## Independent navigation
+
+Select an annotation from the left pane or use the presentation arrow keys. Both paths
+end at the same slide step and URL.
+
+<vividly-annotation title="One source of truth">
+Pointer interaction emits an event. The adapter asks the orchestrator to navigate, and
+the orchestrator writes the resulting step back to the control.
+</vividly-annotation>
+
+## Hidden mounting
+
+The runtime mounts nearby slides while their layers are hidden. Annotation selection is
+safe at that point; scrolling waits until the current task finishes and layout is
+available.
+
+<vividly-annotation title="Deferred scrolling">
+The deferred operation is cancellable and does not depend on animation frames, which
+may stop while a browser tab is in the background.
+</vividly-annotation>

vividly/resources/starter-project/site/slides/contact-sheet/slide.css

@@ -0,0 +1,45 @@
+:scope {
+  display: grid;
+  grid-template-rows: auto 1fr;
+  gap: var(--spacing-lg);
+  padding: var(--spacing-xl);
+}
+
+.sheet-heading {
+  margin: 0;
+  font-family: var(--font-display);
+  font-size: var(--font-size-xl);
+}
+
+.sheet-grid {
+  display: grid;
+  grid-template-columns: repeat(3, 1fr);
+  gap: var(--spacing-lg);
+  align-content: start;
+}
+
+/* --on comes from .v-at and is 1 only on this tile's step. */
+.sheet-tile {
+  margin: 0;
+  cursor: pointer;
+  opacity: calc(0.4 + 0.6 * var(--on));
+  transform: scale(calc(0.96 + 0.04 * var(--on)));
+  outline: 2px solid rgb(79 195 247 / var(--on));
+  outline-offset: 4px;
+  border-radius: var(--radius-md);
+  transition: opacity 300ms ease, transform 300ms ease, outline-color 300ms ease;
+}
+
+.sheet-tile img {
+  display: block;
+  width: 100%;
+  aspect-ratio: 8 / 5;
+  object-fit: cover;
+  border-radius: var(--radius-md);
+}
+
+.sheet-tile figcaption {
+  margin-top: var(--spacing-xs);
+  font-size: var(--font-size-sm);
+  color: var(--text-muted);
+}

vividly/resources/starter-project/site/slides/contact-sheet/slide.js

@@ -0,0 +1,44 @@
+// Image slide: a grid where the current step highlights one tile. Highlight is
+// pure CSS via the kit's .v-at primitive; JS only builds the grid.
+
+import { Slide } from '../../vividly/runtime/slide.js';
+
+export const meta = {
+  title: 'Contact Sheet',
+  styles: ['./slide.css'],
+};
+
+const IMAGES = [
+  { src: 'aurora', label: 'Aurora' },
+  { src: 'canyon', label: 'Canyon' },
+  { src: 'harbor', label: 'Harbor' },
+  { src: 'dunes', label: 'Dunes' },
+  { src: 'glacier', label: 'Glacier' },
+  { src: 'orchard', label: 'Orchard' },
+];
+
+export default class ContactSheet extends Slide {
+  async preload() {
+    return { steps: IMAGES.length };
+  }
+
+  mount(root) {
+    root.innerHTML = `
+      <h2 class="sheet-heading">Contact Sheet</h2>
+      <div class="sheet-grid">
+        ${IMAGES.map(
+          (img, i) => `
+          <figure class="sheet-tile v-at" style="--at: ${i}" data-index="${i}">
+            <img src="${this.ctx.asset(`../../vividly/assets/demo/${img.src}.svg`)}" alt="${img.label}">
+            <figcaption>${img.label}</figcaption>
+          </figure>`
+        ).join('')}
+      </div>
+    `;
+
+    root.addEventListener('click', (e) => {
+      const tile = e.target.closest('.sheet-tile');
+      if (tile) this.ctx.navigate(this.ctx.address, Number(tile.dataset.index));
+    });
+  }
+}

vividly/resources/starter-project/site/slides/diagram-build/slide.css

@@ -0,0 +1,58 @@
+:scope {
+  display: grid;
+  align-content: center;
+  gap: var(--spacing-xl);
+  padding: var(--spacing-xl);
+  max-width: 62rem;
+  margin-inline: auto;
+}
+
+h2 {
+  margin: 0;
+  font-family: var(--font-display);
+  font-size: var(--font-size-xl);
+}
+
+.pipeline {
+  list-style: none;
+  margin: 0;
+  padding: 0;
+  display: grid;
+  gap: var(--spacing-md);
+}
+
+.stage {
+  --reveal-rise: 20px;
+  display: grid;
+  grid-template-columns: auto 1fr;
+  grid-template-areas: 'num title' 'num caption';
+  column-gap: var(--spacing-md);
+  align-items: center;
+  padding: var(--spacing-md) var(--spacing-lg);
+  background: var(--bg-elevated);
+  border-left: 3px solid var(--accent);
+  border-radius: var(--radius-md);
+}
+
+.stage-num {
+  grid-area: num;
+  display: grid;
+  place-items: center;
+  width: 2rem;
+  height: 2rem;
+  border-radius: 50%;
+  background: var(--accent);
+  color: var(--text-inverse);
+  font-variant-numeric: tabular-nums;
+  font-weight: 600;
+}
+
+.stage strong {
+  grid-area: title;
+  font-family: var(--font-mono);
+  font-size: var(--font-size-md);
+}
+
+.stage .v-caption {
+  grid-area: caption;
+}

vividly/resources/starter-project/site/slides/diagram-build/slide.html

@@ -0,0 +1,24 @@
+<h2>How a slide gets on screen</h2>
+
+<ol class="pipeline">
+  <li class="stage v-reveal" style="--at: 0">
+    <span class="stage-num">1</span>
+    <strong>import()</strong>
+    <span class="v-caption">The module loads. Styles are scoped and adopted.</span>
+  </li>
+  <li class="stage v-reveal" style="--at: 1">
+    <span class="stage-num">2</span>
+    <strong>preload()</strong>
+    <span class="v-caption">Data is fetched. The slide declares its step count.</span>
+  </li>
+  <li class="stage v-reveal" style="--at: 2">
+    <span class="stage-num">3</span>
+    <strong>mount()</strong>
+    <span class="v-caption">DOM is built while hidden, so transitions can cross-fade.</span>
+  </li>
+  <li class="stage v-reveal" style="--at: 3">
+    <span class="stage-num">4</span>
+    <strong>enter() &rarr; setStep()</strong>
+    <span class="v-caption">The runtime writes data-step and --step. CSS takes over.</span>
+  </li>
+</ol>

vividly/resources/starter-project/site/slides/diagram-build/slide.js

@@ -0,0 +1,6 @@
+export const meta = {
+  title: 'CSS-Driven Build',
+  template: './slide.html',
+  styles: ['./slide.css'],
+  steps: 4,
+};