inkflow 0.1.0.dev0__py3-none-any.whl

inkflow/server.py

@@ -0,0 +1,380 @@
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import errno
+import importlib.resources
+import importlib.util
+import json
+import os
+import signal
+import sys
+import termios
+import time
+import traceback
+import tty
+import webbrowser
+from collections.abc import Awaitable, Callable
+from pathlib import Path
+from typing import TypedDict, cast
+
+from rich.console import Console
+from rich.live import Live
+from rich.text import Text
+from watchfiles import awatch  # pyright: ignore[reportUnknownVariableType]
+from websockets.asyncio.server import ServerConnection
+from websockets.asyncio.server import serve as ws_serve
+
+from inkflow.layout import resolve_theme_dir
+from inkflow.manifest import Deck
+from inkflow.pipeline import process_deck, resolve_transitions
+from inkflow.tui import LiveUI
+
+# ── Shared mutable state ──────────────────────────────────────────────────────
+
+
+class State(TypedDict):
+    slides: list[str]
+    transitions: list[dict[str, object]]
+    ws_clients: set[ServerConnection]
+    error: str | None
+    styles_css: str
+    dark_mode: bool
+
+
+_state: State = {
+    "slides": [],
+    "transitions": [],
+    "ws_clients": set(),
+    "error": None,
+    "styles_css": "",
+    "dark_mode": True,
+}
+
+
+# ── Deck loader ───────────────────────────────────────────────────────────────
+
+
+def load_deck(deck_path: Path) -> Deck:
+    spec = importlib.util.spec_from_file_location("_inkflow_deck", deck_path)
+    if spec is None or spec.loader is None:
+        raise ImportError(f"Cannot load module from {deck_path}")
+    mod = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(mod)
+    if not hasattr(mod, "deck"):
+        raise AttributeError(
+            f"{deck_path} must define a module-level variable named 'deck'"
+        )
+    return cast(Deck, mod.deck)
+
+
+# ── Build pipeline ────────────────────────────────────────────────────────────
+
+
+async def rebuild(deck_path: Path, ui: LiveUI) -> None:
+    ui.set_building()
+
+    async def _animate() -> None:
+        while True:
+            await asyncio.sleep(0.1)
+            ui.refresh()
+
+    spin = asyncio.create_task(_animate())
+    t0 = time.monotonic()
+    try:
+        deck = await asyncio.to_thread(load_deck, deck_path)
+        project_dir = deck_path.parent
+        slides = await asyncio.to_thread(process_deck, deck, project_dir)
+        transitions = resolve_transitions(deck)
+        styles_css = await asyncio.to_thread(load_styles, deck, project_dir)
+        _state["slides"] = slides
+        _state["transitions"] = transitions
+        _state["styles_css"] = styles_css
+        _state["dark_mode"] = deck.dark_mode
+        _state["error"] = None
+        ui.set_ok(len(slides), time.monotonic() - t0)
+        await broadcast(
+            json.dumps({"type": "update", "slides": slides, "transitions": transitions})
+        )
+    except Exception:
+        tb = traceback.format_exc()
+        _state["error"] = tb
+        ui.set_error(tb)
+        await broadcast(json.dumps({"type": "error", "message": tb}))
+    finally:
+        spin.cancel()
+        with contextlib.suppress(asyncio.CancelledError):
+            await spin
+        ui.refresh()
+
+
+# ── WebSocket broadcast ───────────────────────────────────────────────────────
+
+
+async def broadcast(msg: str) -> None:
+    dead: set[ServerConnection] = set()
+    for ws in list(_state["ws_clients"]):
+        try:
+            await ws.send(msg)
+        except Exception:
+            dead.add(ws)
+    _state["ws_clients"] -= dead
+
+
+# ── WebSocket handler ─────────────────────────────────────────────────────────
+
+
+def make_ws_handler(ui: LiveUI) -> Callable[[ServerConnection], Awaitable[None]]:
+    async def handler(websocket: ServerConnection) -> None:
+        _state["ws_clients"].add(websocket)
+        ui.refresh()
+        try:
+            await websocket.wait_closed()
+        finally:
+            _state["ws_clients"].discard(websocket)
+            ui.refresh()
+
+    return handler
+
+
+# ── HTTP handler ──────────────────────────────────────────────────────────────
+
+_StreamHandler = Callable[[asyncio.StreamReader, asyncio.StreamWriter], Awaitable[None]]
+
+
+def load_styles(deck: Deck, project_dir: Path) -> str:
+    pkg = importlib.resources.files("inkflow")
+    parts = [pkg.joinpath("theme", "styles.css").read_text(encoding="utf-8")]
+
+    if deck.theme is not None:
+        try:
+            theme_dir = resolve_theme_dir(deck.theme, project_dir)
+            theme_css = theme_dir / "styles.css"
+            if theme_css.exists():
+                parts.append(theme_css.read_text(encoding="utf-8"))
+        except ValueError:
+            pass
+
+    project_css = project_dir / "styles.css"
+    if project_css.exists():
+        parts.append(project_css.read_text(encoding="utf-8"))
+
+    return "\n".join(parts)
+
+
+def build_html(state: State, ws_port: int | None) -> bytes:
+    pkg = importlib.resources.files("inkflow")
+    template = pkg.joinpath("presenter.html").read_text(encoding="utf-8")
+    css = pkg.joinpath("presenter.css").read_text(encoding="utf-8")
+    js = pkg.joinpath("presenter.js").read_text(encoding="utf-8")
+    data_theme = "" if state["dark_mode"] else "light"
+    ws_port_js = "null" if ws_port is None else str(ws_port)
+    html = (
+        template.replace("__CSS__", css)
+        .replace("__JS__", js)
+        .replace("__STYLES__", state["styles_css"])
+        .replace("__DATA_THEME__", data_theme)
+        .replace("__SLIDES_JSON__", json.dumps(state["slides"]))
+        .replace("__TRANSITIONS_JSON__", json.dumps(state["transitions"]))
+        .replace("__WS_PORT__", ws_port_js)
+        .replace("__ERROR_JSON__", json.dumps(state["error"]))
+    )
+    return html.encode("utf-8")
+
+
+_SERVED_SUFFIXES = {".mp4", ".webm", ".ogg", ".mov"}
+_MIME_TYPES = {
+    ".mp4": "video/mp4",
+    ".webm": "video/webm",
+    ".ogg": "video/ogg",
+    ".mov": "video/quicktime",
+}
+
+
+def make_http_handler(ws_port: int, project_dir: Path | None = None) -> _StreamHandler:
+    async def handler(
+        reader: asyncio.StreamReader, writer: asyncio.StreamWriter
+    ) -> None:
+        try:
+            raw = await asyncio.wait_for(reader.read(4096), timeout=10)
+            request_line = raw.split(b"\r\n", 1)[0].decode(errors="replace")
+            parts = request_line.split(" ", 2)
+            request_path = parts[1] if len(parts) >= 2 else "/"
+
+            if project_dir is not None and request_path != "/":
+                asset_path = project_dir / request_path.lstrip("/")
+                suffix = asset_path.suffix.lower()
+                if asset_path.is_file() and suffix in _SERVED_SUFFIXES:
+                    mime = _MIME_TYPES[suffix]
+                    body = asset_path.read_bytes()
+                    header = (
+                        b"HTTP/1.1 200 OK\r\n"
+                        + f"Content-Type: {mime}\r\n".encode()
+                        + b"Cache-Control: no-store\r\n"
+                        + b"Connection: close\r\n"
+                        + b"Content-Length: "
+                        + str(len(body)).encode()
+                        + b"\r\n\r\n"
+                    )
+                    writer.write(header + body)
+                    await writer.drain()
+                    return
+
+            body = build_html(_state, ws_port)
+            header = (
+                b"HTTP/1.1 200 OK\r\n"
+                + b"Content-Type: text/html; charset=utf-8\r\n"
+                + b"Cache-Control: no-store\r\n"
+                + b"Connection: close\r\n"
+                + b"Content-Length: "
+                + str(len(body)).encode()
+                + b"\r\n\r\n"
+            )
+            writer.write(header + body)
+
+            await writer.drain()
+        except Exception:
+            pass
+        finally:
+            writer.close()
+            with contextlib.suppress(Exception):
+                await writer.wait_closed()
+
+    return handler
+
+
+# ── File watcher ──────────────────────────────────────────────────────────────
+
+
+async def _watch(deck_path: Path, ui: LiveUI, lock: asyncio.Lock) -> None:
+    async for _changes in awatch(str(deck_path.parent)):
+        if not lock.locked():  # skip if a rebuild is already in progress
+            async with lock:
+                await rebuild(deck_path, ui)
+
+
+# ── Keyboard handler ──────────────────────────────────────────────────────────
+
+
+def _open_browser(url: str) -> None:
+    # Redirect fd 1/2 to /dev/null so the browser process can't write startup
+    # noise to the terminal and corrupt the Rich Live cursor tracking.
+    devnull = os.open(os.devnull, os.O_WRONLY)
+    saved_out = os.dup(1)
+    saved_err = os.dup(2)
+    try:
+        os.dup2(devnull, 1)
+        os.dup2(devnull, 2)
+        webbrowser.open(url)
+    finally:
+        os.dup2(saved_out, 1)
+        os.dup2(saved_err, 2)
+        os.close(devnull)
+        os.close(saved_out)
+        os.close(saved_err)
+
+
+async def _read_keys(
+    deck_path: Path,
+    http_port: int,
+    ui: LiveUI,
+    lock: asyncio.Lock,
+    shutdown: asyncio.Event,
+) -> None:
+    if not sys.stdin.isatty():
+        return
+
+    loop = asyncio.get_running_loop()
+    queue: asyncio.Queue[str] = asyncio.Queue()
+
+    def _on_stdin() -> None:
+        ch = sys.stdin.read(1)
+        loop.call_soon_threadsafe(queue.put_nowait, ch)
+
+    fd = sys.stdin.fileno()
+    old_settings = termios.tcgetattr(fd)
+    try:
+        tty.setcbreak(fd)  # single-char reads, output processing (ONLCR) intact
+        loop.add_reader(fd, _on_stdin)
+        while True:
+            ch = await queue.get()
+            if ch in ("\x04", "q"):  # Ctrl-D, q (Ctrl-C handled via SIGINT)
+                shutdown.set()
+                return
+            elif ch == "o":
+                _open_browser(f"http://localhost:{http_port}")
+            elif ch == "r":
+                async with lock:
+                    await rebuild(deck_path, ui)
+            elif ch == "t":
+                ui.toggle_trace()
+    finally:
+        loop.remove_reader(fd)
+        termios.tcsetattr(fd, termios.TCSADRAIN, old_settings)
+
+
+# ── Public entry point ────────────────────────────────────────────────────────
+
+
+async def serve(deck_path: Path, http_port: int, ws_port: int) -> None:
+    console = Console()
+    rebuild_lock = asyncio.Lock()
+    shutdown = asyncio.Event()
+
+    loop = asyncio.get_running_loop()
+    loop.add_signal_handler(signal.SIGINT, shutdown.set)
+    loop.add_signal_handler(signal.SIGTERM, shutdown.set)
+
+    try:
+        http_handler = make_http_handler(ws_port, deck_path.parent)
+        # Bind before the Live UI so port conflicts fail fast with a clean message
+        try:
+            http_server = await asyncio.start_server(
+                http_handler, "127.0.0.1", http_port
+            )
+        except OSError as e:
+            if e.errno == errno.EADDRINUSE:
+                msg = (
+                    f"[red]error:[/red] port {http_port} is already in use."
+                    f" Pass [dim]--port PORT[/dim] to serve on a different port."
+                )
+                console.print(msg)
+                return
+            raise
+
+        with Live(Text(""), console=console, auto_refresh=False) as live:
+            ui = LiveUI(
+                live,
+                http_port,
+                deck_path.parent,
+                get_clients=lambda: len(_state["ws_clients"]),
+            )
+            try:
+                async with (
+                    http_server,
+                    ws_serve(make_ws_handler(ui), "127.0.0.1", ws_port),
+                ):
+                    await rebuild(deck_path, ui)
+                    tasks = [
+                        asyncio.create_task(http_server.serve_forever()),
+                        asyncio.create_task(_watch(deck_path, ui, rebuild_lock)),
+                        asyncio.create_task(
+                            _read_keys(deck_path, http_port, ui, rebuild_lock, shutdown)
+                        ),
+                    ]
+                    await shutdown.wait()
+                    for t in tasks:
+                        t.cancel()
+                    await asyncio.gather(*tasks, return_exceptions=True)
+            except OSError as e:
+                if e.errno == errno.EADDRINUSE:
+                    msg = (
+                        f"[red]error:[/red] port {ws_port} is already in use."
+                        f" Pass [dim]--ws-port PORT[/dim] to use a different one."
+                    )
+                    console.print(msg)
+                else:
+                    raise
+    finally:
+        loop.remove_signal_handler(signal.SIGINT)
+        loop.remove_signal_handler(signal.SIGTERM)

inkflow/theme/layouts/center.svg

@@ -0,0 +1,3 @@
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:inkflow="urn:inkflow" inkflow:parent="../numbered-main.svg" viewBox="0 0 1920 1080" width="1920" height="1080">
+  <rect id="zone-content" x="80" y="80" width="1760" height="900"/>
+</svg>

inkflow/theme/layouts/cover.svg

@@ -0,0 +1,5 @@
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:inkflow="urn:inkflow" inkflow:parent="../main.svg" viewBox="0 0 1920 1080" width="1920" height="1080">
+  <rect id="zone-title" x="160" y="340" width="1600" height="220"/>
+  <rect id="zone-subtitle" x="160" y="580" width="1600" height="120"/>
+  <rect id="zone-note" x="160" y="730" width="1600" height="100"/>
+</svg>

inkflow/theme/layouts/default.svg

@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:inkflow="urn:inkflow" inkflow:parent="../numbered-main.svg" viewBox="0 0 1920 1080" width="1920" height="1080">
+  <rect id="zone-title" x="80" y="60" width="1760" height="120"/>
+  <rect id="zone-content" x="80" y="220" width="1760" height="780"/>
+</svg>

inkflow/theme/layouts/end.svg

@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:inkflow="urn:inkflow" inkflow:parent="../main.svg" viewBox="0 0 1920 1080" width="1920" height="1080">
+  <rect id="zone-title" x="160" y="380" width="1600" height="220"/>
+  <rect id="zone-subtitle" x="160" y="620" width="1600" height="120"/>
+</svg>

inkflow/theme/layouts/fact.svg

@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:inkflow="urn:inkflow" inkflow:parent="../numbered-main.svg" viewBox="0 0 1920 1080" width="1920" height="1080">
+  <rect id="zone-fact" x="80" y="300" width="1760" height="300"/>
+  <rect id="zone-caption" x="80" y="650" width="1760" height="160"/>
+</svg>

inkflow/theme/layouts/media-left.svg

@@ -0,0 +1,5 @@
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:inkflow="urn:inkflow" inkflow:parent="../numbered-main.svg" viewBox="0 0 1920 1080" width="1920" height="1080">
+  <rect id="zone-title" x="80" y="60" width="1760" height="120"/>
+  <rect id="zone-media" x="80" y="220" width="840" height="780"/>
+  <rect id="zone-content" x="1000" y="220" width="840" height="780"/>
+</svg>

inkflow/theme/layouts/media-right.svg

@@ -0,0 +1,5 @@
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:inkflow="urn:inkflow" inkflow:parent="../numbered-main.svg" viewBox="0 0 1920 1080" width="1920" height="1080">
+  <rect id="zone-title" x="80" y="60" width="1760" height="120"/>
+  <rect id="zone-content" x="80" y="220" width="840" height="780"/>
+  <rect id="zone-media" x="1000" y="220" width="840" height="780"/>
+</svg>

inkflow/theme/layouts/quote.svg

@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:inkflow="urn:inkflow" inkflow:parent="../numbered-main.svg" viewBox="0 0 1920 1080" width="1920" height="1080">
+  <rect id="zone-quote" x="160" y="300" width="1600" height="400"/>
+  <rect id="zone-attribution" x="160" y="730" width="1600" height="100"/>
+</svg>

inkflow/theme/layouts/section.svg

@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:inkflow="urn:inkflow" inkflow:parent="../main.svg" viewBox="0 0 1920 1080" width="1920" height="1080">
+  <rect id="zone-section-title" x="80" y="380" width="1760" height="220"/>
+  <rect id="zone-section-subtitle" x="80" y="620" width="1760" height="120"/>
+</svg>

inkflow/theme/layouts/statement.svg

@@ -0,0 +1,3 @@
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:inkflow="urn:inkflow" inkflow:parent="../numbered-main.svg" viewBox="0 0 1920 1080" width="1920" height="1080">
+  <rect id="zone-statement" x="80" y="280" width="1760" height="520"/>
+</svg>

inkflow/theme/layouts/two-cols-header.svg

@@ -0,0 +1,5 @@
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:inkflow="urn:inkflow" inkflow:parent="../numbered-main.svg" viewBox="0 0 1920 1080" width="1920" height="1080">
+  <rect id="zone-header" x="80" y="60" width="1760" height="120"/>
+  <rect id="zone-left" x="80" y="220" width="840" height="780"/>
+  <rect id="zone-right" x="1000" y="220" width="840" height="780"/>
+</svg>

inkflow/theme/layouts/two-cols.svg

@@ -0,0 +1,5 @@
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:inkflow="urn:inkflow" inkflow:parent="../numbered-main.svg" viewBox="0 0 1920 1080" width="1920" height="1080">
+  <rect id="zone-title" x="80" y="60" width="1760" height="120"/>
+  <rect id="zone-left" x="80" y="220" width="840" height="780"/>
+  <rect id="zone-right" x="1000" y="220" width="840" height="780"/>
+</svg>

inkflow/theme/main.svg

@@ -0,0 +1,3 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1920 1080" width="1920" height="1080">
+  <rect width="1920" height="1080" class="slide-bg"/>
+</svg>

inkflow/theme/numbered-main.svg

@@ -0,0 +1,6 @@
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:inkflow="urn:inkflow" inkflow:parent="./main.svg" viewBox="0 0 1920 1080" width="1920" height="1080" version="1.1" id="svg1">
+  <defs id="defs1"/>
+  <text id="zone-slide-number" x="1820" y="1055" class="theme-text-muted" text-anchor="end" font-size="28px" font-family="sans-serif">99</text>
+  <text id="zone-slide-total" x="1860" y="1055" class="theme-text-muted" font-size="28px" font-family="sans-serif">99</text>
+  <text id="text1" x="1832.489" y="1055" class="theme-text-muted" font-size="28px" font-family="sans-serif">/</text>
+</svg>

inkflow/theme/showcase/deck.py

@@ -0,0 +1,18 @@
+from inkflow import Crossfade, Deck, MarkdownSlide
+
+deck = Deck(transition=Crossfade())
+
+deck.slides = [
+    MarkdownSlide("cover", content="01-cover"),
+    MarkdownSlide("section", content="02-section"),
+    MarkdownSlide("default", content="03-default", steps=True),
+    MarkdownSlide("center", content="04-center"),
+    MarkdownSlide("two-cols", content="05-two-cols"),
+    MarkdownSlide("two-cols-header", content="06-two-cols-header"),
+    MarkdownSlide("fact", content="07-fact"),
+    MarkdownSlide("quote", content="08-quote"),
+    MarkdownSlide("statement", content="09-statement"),
+    MarkdownSlide("media-left", content="10-media-left"),
+    MarkdownSlide("media-right", content="11-media-right"),
+    MarkdownSlide("end", content="12-end"),
+]

inkflow/theme/showcase/slides/01-cover.md

@@ -0,0 +1,7 @@
+# inkflow built-in theme
+
+## A tour of all twelve layouts
+
+::note::
+
+Press Space or → to advance

inkflow/theme/showcase/slides/02-section.md

@@ -0,0 +1,7 @@
+::section-title::
+
+Part 1: Full-slide layouts
+
+::section-subtitle::
+
+`cover` · `section` · `end`

inkflow/theme/showcase/slides/03-default.md

@@ -0,0 +1,11 @@
+# The `default` layout
+
+Title at the top, content fills the rest.
+
+- Supports **bold**, _italic_, and `inline code`
+- Bullet lists can be stepped with `steps=True`
+- Code blocks, blockquotes, and nested lists all work
+
+::step::
+
+Each `::step::` marker reveals the next chunk on click.

inkflow/theme/showcase/slides/04-center.md

@@ -0,0 +1,8 @@
+::content::
+
+# `center`
+
+One large zone spans the entire slide.
+
+Great for a single strong statement, a full-bleed diagram,
+or anything that needs maximum breathing room.

inkflow/theme/showcase/slides/05-two-cols.md

@@ -0,0 +1,17 @@
+# `two-cols`
+
+::left::
+
+## Left column
+
+- Independent content
+- Each column scrolls on its own
+- Use for comparisons or before/after
+
+::right::
+
+## Right column
+
+- Counters or complements the left
+- Both columns sit below a shared title
+- Swap to `two-cols-header` for a wider header zone

inkflow/theme/showcase/slides/06-two-cols-header.md

@@ -0,0 +1,13 @@
+::header::
+
+`two-cols-header` — shared header, two equal columns
+
+::left::
+
+The header zone is wider than `two-cols` title zone and sits
+above both columns, providing shared context.
+
+::right::
+
+Use this layout when the header is the primary label and the
+columns carry parallel or contrasting detail underneath.

inkflow/theme/showcase/slides/07-fact.md

@@ -0,0 +1,7 @@
+::fact::
+
+# 0 type errors
+
+::caption::
+
+`fact` — one large number or short claim, with a caption below for context.

inkflow/theme/showcase/slides/08-quote.md

@@ -0,0 +1,7 @@
+::quote::
+
+"Simple things should be simple, complex things should be possible."
+
+::attribution::
+
+— Alan Kay

inkflow/theme/showcase/slides/09-statement.md

@@ -0,0 +1,3 @@
+::statement::
+
+## One idea per slide.

inkflow/theme/showcase/slides/10-media-left.md

@@ -0,0 +1,15 @@
+# `media-left`
+
+::media::
+
+_media zone_
+
+Image or video fills the left half.
+Pass `media=Media("file.jpg")` to `MarkdownSlide`.
+
+::content::
+
+Text content occupies the right half.
+
+Use this layout when a visual element is the primary focus and
+the text provides supporting context.

inkflow/theme/showcase/slides/11-media-right.md

@@ -0,0 +1,16 @@
+# `media-right`
+
+::content::
+
+Text content occupies the left half.
+
+Use this layout when the narrative leads and the visual
+confirms or illustrates — the natural reading direction
+carries the eye from text to image.
+
+::media::
+
+_media zone_
+
+Image or video fills the right half.
+Pass `media=Media("file.jpg")` to `MarkdownSlide`.

inkflow/theme/showcase/slides/12-end.md

@@ -0,0 +1,3 @@
+# That's all twelve layouts.
+
+## `uv run inkflow serve src/inkflow/theme/showcase/deck.py`