inkflow 0.1.0__tar.gz

inkflow-0.1.0/.claude/hooks/autofix.sh

@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+FILE=$(jq -r '.tool_input.file_path')
+
+case "$FILE" in
+  *.py)
+    # --unfixable F401: keep import sorting and every other autofix, but do NOT
+    # strip "unused" imports — mid-edit an import is often added before the line
+    # that uses it, and stripping it here breaks the file. --exit-zero so a
+    # transient unused import doesn't abort the hook before `ruff format` runs.
+    # `mise run check` remains the real gate for genuinely unused imports.
+    uv run ruff check --fix --unfixable F401 --exit-zero "$FILE"
+    uv run ruff format "$FILE"
+    ;;
+  *.js|*.mjs|*.cjs|*.jsx|*.ts|*.mts|*.cts|*.tsx|*.css|*.json|*.jsonc)
+    npx biome check --write "$FILE"
+    ;;
+esac

inkflow-0.1.0/.claude/settings.json

@@ -0,0 +1,19 @@
+{
+    "permissions": {
+        "allow": ["Bash(mise run *)"],
+        "ask": ["Edit(mise.toml)", "Write(mise.toml)"]
+    },
+    "hooks": {
+        "PostToolUse": [
+            {
+                "matcher": "Edit|Write",
+                "hooks": [
+                    {
+                        "type": "command",
+                        "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/autofix.sh"
+                    }
+                ]
+            }
+        ]
+    }
+}

inkflow-0.1.0/.gitattributes

@@ -0,0 +1 @@
+*.svg diff=inkscape-svg

inkflow-0.1.0/.githooks/pre-commit

@@ -0,0 +1,23 @@
+#!/usr/bin/env bash
+# Strip Inkscape editor metadata from staged SVG files before committing.
+# Installed by: inkflow setup-git
+
+set -e
+
+mapfile -t staged < <(git diff --cached --name-only --diff-filter=ACM \
+  | grep -E '\.svg$' || true)
+[ ${#staged[@]} -eq 0 ] && exit 0
+
+if [ -x ".venv/bin/inkflow" ]; then
+    INKFLOW=".venv/bin/inkflow"
+elif command -v inkflow &>/dev/null; then
+    INKFLOW="inkflow"
+else
+    echo "[inkflow] inkflow not found, skipping SVG clean" >&2
+    exit 0
+fi
+
+echo "[inkflow] cleaning staged SVGs..."
+"$INKFLOW" clean "${staged[@]}"
+
+git add "${staged[@]}"

inkflow-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,66 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: jdx/mise-action@v4
+
+      - run: npm ci
+
+      - name: JS checks
+        run: |
+          npx biome check src/ts/ src/css/
+          npx tsc --noEmit
+
+      - name: Check bundles are up to date
+        run: |
+          mise run bundle
+          git diff --exit-code src/inkflow/bundles/
+
+      - run: uv run ruff format --check src/ tests/
+
+      - run: uv run ruff check src/ tests/
+
+      - run: uv run basedpyright
+
+      - run: uv run deptry src
+
+      - run: uv run pytest
+
+      - run: git ls-files '*.svg' | xargs --no-run-if-empty uv run inkflow clean --check
+
+      - name: Build demo deck
+        run: uv run inkflow build --deck demo/deck.py
+
+      - name: Build theme showcase deck
+        run: uv run inkflow build --deck src/inkflow/theme/showcase/deck.py
+
+      - name: Build init deck
+        run: |
+          uv run inkflow init /tmp/test-init
+          uv run inkflow build --deck /tmp/test-init/deck.py
+
+  export:
+    runs-on: ubuntu-latest
+    if: github.ref == 'refs/heads/main' || github.event_name == 'pull_request'
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: jdx/mise-action@v4
+
+      - name: Install Google Chrome
+        run: |
+          wget -q https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb
+          sudo apt-get install -y ./google-chrome-stable_current_amd64.deb
+
+      - name: Export demo deck
+        run: uv run inkflow export --deck demo/deck.py --no-sandbox

inkflow-0.1.0/.github/workflows/docs.yml

@@ -0,0 +1,45 @@
+name: Docs
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+
+permissions:
+  contents: write
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b
+
+      - run: uv sync --group docs
+
+      - run: uv run inkflow build --deck demo/deck.py --output docs/demo
+
+      - run: uv run inkflow build --deck src/inkflow/theme/showcase/deck.py --output docs/built-in-theme/presentation
+
+      - run: uv run mkdocs build --strict
+
+  deploy:
+    if: github.event_name == 'push'
+    needs: build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b
+
+      - run: uv sync --group docs
+
+      - run: uv run inkflow build --deck demo/deck.py --output docs/demo
+
+      - run: uv run inkflow build --deck src/inkflow/theme/showcase/deck.py --output docs/built-in-theme/presentation
+
+      - run: uv run mkdocs gh-deploy --force

inkflow-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,39 @@
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+      contents: write
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b
+
+      - name: Check version matches tag
+        run: |
+          TAG="${GITHUB_REF_NAME#v}"
+          VERSION=$(python -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
+          if [ "$TAG" != "$VERSION" ]; then
+            echo "Tag $GITHUB_REF_NAME does not match pyproject.toml version $VERSION"
+            exit 1
+          fi
+
+      - run: uv build
+
+      - name: Smoke test
+        run: uv run --with dist/*.whl --no-project -- inkflow build --deck demo/deck.py --output /tmp/inkflow-smoke
+
+      - run: uv publish
+
+      - name: Create GitHub release
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+        run: gh release create "$GITHUB_REF_NAME" dist/* --generate-notes

inkflow-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+node_modules/
+*.egg-info/
+*.pyc
+.venv/
+__pycache__/
+build/
+deck.pdf
+dist/
+docs/demo/index.html
+docs/demo/assets/
+docs/built-in-theme/presentation/
+site/

inkflow-0.1.0/.python-version

@@ -0,0 +1 @@
+3.11

inkflow-0.1.0/CLAUDE.md

@@ -0,0 +1,252 @@
+# Inkflow — codebase guide
+
+## Running
+
+```bash
+uv run inkflow serve --deck demo/deck.py   # start server at localhost:7777
+mise run check                      # lint + format + typecheck + test (Python and JS)
+mise run bundle                     # rebuild JS/CSS bundles from src/ts/ and src/css/
+```
+
+## Git setup (one-time, per clone)
+
+```bash
+uv run inkflow setup-git
+```
+
+Configures two things:
+- **Pre-commit hook** (`.githooks/pre-commit`) — strips Inkscape editor metadata from staged SVGs before every commit, so viewport pan/zoom/window state never lands in history
+- **SVG diff driver** — `git diff`, `git log -p`, and GitHub's diff view show only visual changes even for SVGs that haven't been cleaned in-place
+
+Git won't run this automatically on clone — that's an intentional git security boundary — so it needs to be run once. After that it's invisible.
+
+SVG source files should be kept clean (no Inkscape metadata) in the repository. Run `uv run inkflow clean demo/slides/*.svg` to clean any files committed before the hook was in place.
+
+## Project layout
+
+```
+src/
+  inkflow/
+    __init__.py       exports: Deck, Slide, Image, Video, Media, TextBox, Animation,
+                               Transition, Align, VAlign, Direction, Inline, Content,
+                               ZoneContent, ColorMode, MediaFit, MediaAlign, Muted
+                               and the `animations` and `transitions` namespaces
+    manifest.py       dataclasses for the deck DSL; Animation/Transition base.
+                               Media is a `_MediaBase` shared by Image + Video; `Media`
+                               is the `Image | Video` union alias (not callable).
+                               Video adds playback fields (controls, autoplay, muted,
+                               loop, poster, start, end, play_on_step)
+                               Deck params: slides, transition, theme, mode: ColorMode,
+                               style, font_size, embed_fonts
+                               Slide params: src, id, md, zones, animations, transition,
+                               extra_style, title, notes, visible, font_size
+    enums.py          shared enums (Direction, Align, VAlign, MediaFit, MediaAlign,
+                               ColorMode, Muted); `_KebabStrEnum` base emits CSS token
+                               values (Muted is a plain Enum, resolved in Python)
+    animations.py     concrete animation types (FadeIn, FadeOut, Bounce, SlideIn/Out,
+                               ZoomIn/Out, Highlight) subclassing manifest.Animation
+    transitions.py    concrete transition types (Cut, Crossfade, Morph, Push, Cover,
+                               Zoom, Fade, Wipe) subclassing manifest.Transition
+    pipeline.py       animation annotation + layout inlining
+    content.py        TextBox / Image / Video injection into zone rects, with alignment
+                               support; Video emits data-* playback attrs (driven by video.ts)
+    layout.py         parent inject/set/strip: layout chain resolution and Inkscape layer writing
+    markdown.py       markdown-it-py rendering only: code-fence highlighting, LaTeX math,
+                               HTML->well-formed-XML normalization (no inkflow-specific grammar)
+    zones.py          ::zone:: / ::step:: marker grammar, zone param extraction, and slide
+                               assembly (parsed markdown -> per-zone TextBox/Media)
+    server.py         HTTP server, WebSocket server, file watcher, build pipeline
+    export.py         static HTML export (inkflow build) and PDF export (inkflow export)
+    cli/              CLI package (entry point inkflow.cli:main). _common.py holds the
+                               `main` group, shared options, and the Project/Target helpers;
+                               commands are grouped by area: project.py (init, setup-git,
+                               completion), present.py (serve, build, export), authoring.py
+                               (clean, add, parent group, sync, layouts), color.py (colorize,
+                               palette), verify.py. Submodules register on `main` by import.
+    clean.py          SVG Inkscape metadata stripping (used by cli and pre-commit hook)
+    colors.py         CSS color token extraction, hex→class mapping, SVG colorization, GPL palette
+    git_setup.py      git hook + SVG diff driver setup
+    init.py           project scaffolding (inkflow init)
+    loaders.py        deck style / script loading helpers
+    logging.py        unified log sink over stdlib logging: `logger`, shared Rich
+                               `console`, `report` (cargo-style status), `collect_logs`
+                               (per-rebuild capture), and three independent sinks
+                               (console/file/browser), each a level, resolved by
+                               `resolve_levels` (`--log-level*` flags + INKFLOW_LOG_LEVEL*
+                               env, `off` disables) and installed by `configure`
+    svg.py            SVG tree utilities (ensure_defs, with_namespaces, compose_with_ancestors)
+    svgio.py          SVG parse/serialize primitives: one hardened parser, SvgElement alias
+    verify.py         slide authoring checks (inkflow verify)
+    ns.py             XML namespace constants
+    tui.py            terminal UI (Rich)
+    presenter.html    shell template — inlined with CSS/JS at serve time
+    pdf.html          PDF export template
+    bundles/          pre-built JS/CSS output (committed; no Node needed at install time)
+      presenter.js    navigation, transitions, WebSocket, presenter panel
+      presenter.css   all presenter styles including the sidebar panel
+    theme/            built-in theme: main.svg, layouts/*.svg, styles.css
+  ts/                 TypeScript source
+    globals.d.ts      ambient declarations for Python-injected globals (__SLIDES_JSON__ etc.)
+    shared/           types, step logic, step-ring SVG builder, cubic-bezier easing
+    presenter/        main presenter modules — navigation, transitions (progress-driven
+                      via progress-driver.ts), overview, picker, websocket, status bar,
+                      keyboard, syncmenu.ts (sync-mode status-bar control),
+                      pv.ts (presenter panel sidebar), and video.ts (step-driven
+                      <video> playback, wired in via status.ts)
+  css/                CSS source
+    shared/           theme variables, animation keyframes
+    presenter/        presenter partials including pv.css (sidebar panel)
+demo/
+  deck.py             11-slide demo deck (SVG slides, some filling zones with Markdown via md=)
+  slides/             source SVGs and Markdown content files
+mise.toml             task runner + tool versions (replaces poethepoet)
+package.json          JS devDependencies: biome, esbuild, typescript
+biome.json            Biome lint + format config (4-space indent, noUnusedVariables=error)
+tsconfig.json         TypeScript config (noEmit, verbatimModuleSyntax — tsc as type-checker only)
+```
+
+## Key architecture decisions
+
+**No SVG editor subprocess at serve time.**
+Any SVG editor writes the files; the pipeline reads them directly with lxml,
+strips Inkscape/Sodipodi editor namespaces, and annotates elements with animation classes.
+No GUI window flashes, instant processing.
+
+**Live reload pushes slides over WebSocket, not `location.reload()`.**
+When files change the server sends `{"type":"update","slides":[...],"transitions":[...],"logs":[{"level","message"},...]}` and the presenter swaps content in place, preserving the current slide index.
+Non-fatal records collected during the rebuild (`inkflow.logging.collect_logs`, filtered to the browser sink's level) ride along on the `update` message and show as a dismissible `#warning-banner`, each entry styled by level via a `log-<level>` class (dismissal sticks across rebuilds until the log set changes, keyed on a signature in `ui.ts`); a fatal build error is sent separately as `{"type":"error","message":"..."}` and displayed as the full-screen overlay (also logged to the file sink). Static `build` sends no logs to the page (they go to the CLI instead).
+The HTTP response includes `Cache-Control: no-store` so hard refreshes always get fresh content.
+
+**Position sync is a dumb relay with client-side authority + modes.**
+Clients send `{"type":"nav","slideIndex","step"}` (validated + clamped server-side by `_coerce_nav_position`); the server stores the last position and rebroadcasts it as `{"type":"position",...}` to the *other* clients, and pushes it once to each newly connected client. A window that booted from a deep link (URL slide segment, captured by `readURL()` before `syncURL()` rewrites the bar) or reconnected asserts its own position and ignores that first push; a bare window adopts it. Each client also has a per-tab **sync mode** (`two-way`/`present`/`follow`/`solo`, `shared/types.ts`) deciding locally whether it broadcasts nav (`sends()`) and applies incoming positions (`receives()`) — the server knows nothing about modes. `s` cycles the mode; `syncmenu.ts` owns the status-bar widget, `websocket.ts` the network/state. Switching into a receiving mode sends `{"type":"sync-request"}` to catch up. Persisted in `sessionStorage`.
+
+**`loadSlide()` vs `applyStep()` in the presenter JS.**
+Step advances within a slide must NOT re-render `stage.innerHTML` — that would make CSS transitions invisible because the browser only paints once per JS task.
+`loadSlide()` sets innerHTML (elements start at opacity 0).
+Subsequent `applyStep()` calls only toggle `.active` on existing DOM elements, triggering CSS transitions.
+
+**`deck.py` is a Python module, not YAML/TOML.**
+Loaded via `importlib.util.spec_from_file_location`. Must define a `main() -> Deck` function.
+
+**Morph transition uses a rAF loop over SVG attributes, not CSS transforms.**
+CSS `transform: translate(Xpx)` on SVG elements is interpreted in SVG user units, not CSS viewport pixels — FLIP-based approaches produce a coordinate gap proportional to the viewBox scale.
+Instead, `morphSlide()` snapshots raw geometry attributes (`x`, `y`, `width`, `height`, `rx` for rects; `cx`, `cy`, `r` for circles) before the innerHTML swap, then drives a `requestAnimationFrame` loop that calls `setAttribute` each frame in SVG user units.
+Colors are lerped channel-by-channel.
+Exit-only elements are reconstructed as ghost nodes in the new SVG and faded out.
+Backward navigation passes the outgoing slide's transition to `loadSlide()` so the morph plays in reverse.
+
+**`presenter.html`/`css`/`js` are inlined at serve time.**
+`build_html()` in `server.py` reads the template and the two bundles, substituting `__CSS__`, `__JS__`, `__STYLES__`, `__DATA_THEME__`, `__SLIDES_JSON__`, `__TRANSITIONS_JSON__`, `__WS_PORT__`, `__ERROR_JSON__` tokens.
+Edit the source files, run `mise run bundle`, and reload the browser to see changes.
+
+**The presenter panel is a sidebar inside the single presenter page, not a separate route.**
+`<aside id="pv">` lives in `presenter.html` and is hidden (`width: 0`) by default.
+Pressing `p` toggles `body.pv-open`, which CSS-transitions the sidebar to 30% width while the stage flexes back.
+`pv.ts` owns all panel logic (clock, next-preview, notes); it reads directly from `state.slides` so no second WS connection or position sync is needed.
+For second-screen use, open the same URL in two windows and toggle the panel in one.
+
+**Font embedding is automatic and zero-config.**
+After `process_deck()`, `fonts.embed_fonts_css()` (serve) or `fonts.embed_fonts_css_subsetted()`
+(build/export) scans every slide SVG for named `font-family` values, discovers matching font
+files, and injects `@font-face` blocks (base64 data-URI) into the global CSS via `__STYLES__`.
+Generic families (`sans-serif`, `serif`, `monospace`, etc.) are always skipped.
+
+Font search order: `<project_dir>/fonts/` → user font dirs → system font dirs (all OS-specific).
+Committing fonts in `fonts/` gives fully reproducible output independent of the host system.
+
+For serve: full font files are embedded; the font index is cached at module level so only the
+first rebuild in a session pays the directory-scan cost. For build/export: fonts are subsetted
+to only the codepoints present in the slides (via `fonttools`), typically 10–30 KB per variant.
+`brotli` is a required dependency, so subsetted fonts are always emitted as WOFF2. If subsetting fails for a given font (for example a corrupt or unreadable file), the full font file is embedded instead.
+
+Unresolvable fonts produce a yellow TUI warning and fall back to system rendering.
+Opt out per-deck: `Deck(embed_fonts=False)`.
+
+**Markdown content injection (`md=`) uses `<foreignObject>`.**
+Markdown is rendered to HTML via `markdown-it-py`.
+Zone `<rect>` elements in the layout SVG are replaced with `<foreignObject>` of the same geometry containing the rendered HTML.
+Typography and color come from the CSS cascade (`theme/styles.css` + per-deck/per-slide `style=`) injected into the `<foreignObject>` HTML head.
+
+**Text zone alignment — three layers, increasing specificity.**
+
+*1. Layout SVG CSS variables* — set once, applies to every slide that uses the layout:
+```css
+/* inside the layout SVG's <defs><style> */
+#zone-title   { --inkflow-valign: center; }
+#zone-content { --inkflow-padding: 40px; }
+```
+`--inkflow-align` (`left`/`center`/`right`/`justify`), `--inkflow-valign` (`start`/`center`/`end`), and `--inkflow-padding` (any CSS length) are consumed by `.inkflow-wrapper` and `.inkflow-content` in `theme/styles.css` via `var()`. No pipeline extraction; pure browser cascade.
+
+*2. Markdown zone marker parameters* — per-zone, per-slide, directly in the `.md` file:
+```
+::content align=center valign=center padding=60::
+```
+`align`, `valign`, and `padding` are the supported keys. `valign` accepts `top`/`center`/`bottom` (mapped to flexbox `start`/`center`/`end`). `padding` is in SVG user units. These translate to inline `style` attributes on the generated `<foreignObject>` wrapper and content divs, overriding CSS variables.
+
+*3. Python `TextBox` explicit params* — in `deck.py`:
+```python
+from inkflow import Align, Slide, TextBox, VAlign
+Slide(
+    "layout.svg",
+    zones={"content": TextBox(text="...", align=Align.CENTER, valign=VAlign.TOP, padding=40)},
+)
+```
+The target zone is the `zones` dict key (`"content"` → `zone-content`); `TextBox` has no selector argument, its first positional is `text`. `Align` and `VAlign` are `StrEnum`s exported from the top-level package. `None` (the default) means "defer to CSS variable".
+
+**foreignObject DOM structure after injection:**
+```
+<foreignObject>
+  <div class="inkflow-wrapper" [style="justify-content:…;padding:…;"]>
+    <div class="inkflow-content" [style="text-align:…;"]>
+      {rendered HTML}
+    </div>
+  </div>
+</foreignObject>
+```
+Inline styles are only emitted when the corresponding param is non-`None`; CSS variables handle layout-level defaults without touching the element's `style`.
+
+**Layout chain resolution at build time, not on disk.**
+`inject-layout` writes locked Inkscape preview layers into SVGs for authoring reference,
+but the pipeline resolves `inkflow:parent` chains in memory and composites layers on the fly.
+SVG files on disk are never modified by the serve/build pipeline.
+
+## Server
+
+- HTTP on port 7777 (asyncio streams, custom handler)
+- WebSocket on port 7778 (websockets 16.0 — uses `websockets.asyncio.server.serve`, not the legacy `websockets.serve`)
+- File watcher: `watchfiles.awatch` (async generator)
+- Both run inside an `asyncio.TaskGroup`
+
+## Animation pipeline
+
+`pipeline.py` processes each slide as a single lxml tree: parsed once via the hardened parser in `svgio.py`, threaded through the pipeline, serialized once at the end. `SlideSvg` wraps the tree and each pipeline step is a method that mutates it in place (like `list.sort()`), delegating the DOM work to `content.py`/`svg.py` functions that take and return the root element. Key steps:
+1. `clean_inkscape_tree(src)` — parse with the hardened lxml parser, remove elements/attrs in `http://www.inkscape.org/namespaces/inkscape` and `http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd`, call `etree.cleanup_namespaces()`. (`clean_inkscape_svg` wraps this and serializes to a pretty-printed string for the CLI/pre-commit hook.)
+2. `annotate_svg(root, animations)` — find elements by id (stripping leading `#`), set `class`, `data-step`, and merge `--anim-*` custom properties into `style`
+
+The CSS class is `anim-<slug>`, where the slug is the kebab-cased type name (`Animation.slug()` / `Transition.slug()`, a `_Slugged` mixin in `manifest.py`): `FadeIn → anim-fade-in`, `SlideIn → anim-slide-in`, `Highlight → anim-highlight`. There is no per-type registry. `_anim_style` emits one `--anim-<field>` custom property per non-`None` parameter (via the shared `_set_fields` field-walk, with a unit table for `duration`/`delay`/`distance`); the `direction` field instead becomes an `anim-from-<value>` modifier class (`_anim_classes`). CSS in `src/css/shared/animations.css` consumes the custom props via `var(--anim-…, default)`.
+
+All SVG parsing routes through `svgio.py` (`parse_svg`, `parse_svg_file`, `serialize_svg`), which uses one hardened parser config (`resolve_entities=False, no_network=True, load_dtd=False, huge_tree=False`, constructed per call since lxml parsers are not thread-safe). This is defense-in-depth plus crash-robustness: an SVG referencing an external/DTD entity degrades to an inert node instead of crashing the rebuild. `svgio.py` also exports the `SvgElement` type alias used across the backend.
+
+## JS toolchain
+
+Three tools, each with a distinct role:
+
+- **Biome** — linter and formatter for TypeScript and CSS. Run via `mise run lint-js`. Config in `biome.json`.
+- **tsc** — type-checker only (`noEmit: true`). Never emits files; esbuild does that. Run via `mise run typecheck-js`.
+- **esbuild** — bundler. Produces committed bundles in `src/inkflow/bundles/` that the Python inlining pipeline reads at serve/build time. Run via `mise run bundle`.
+
+`pip install inkflow` ships the pre-built bundles — no Node at install time.
+
+`verbatimModuleSyntax: true` in tsconfig enforces `import type` for type-only imports, which esbuild requires since it transpiles files individually without type information.
+
+## Dependencies
+
+```
+click>=8.0           CLI
+lxml>=5.0            SVG processing
+markdown-it-py>=3.0  Markdown rendering
+platformdirs>=4.0    per-user log + font directories (inkflow.logging, fonts.py)
+rich>=15.0           terminal UI
+watchfiles>=0.21     inotify-based file watcher
+websockets>=12.0     WebSocket server (uses 16.x asyncio API)
+```

inkflow-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nick Le Large
+
+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.

inkflow-0.1.0/PKG-INFO

@@ -0,0 +1,155 @@
+Metadata-Version: 2.4
+Name: inkflow
+Version: 0.1.0
+Summary: Beautiful slides from SVG. Your editor, your style.
+Project-URL: Homepage, https://ll-nick.github.io/inkflow
+Project-URL: Repository, https://github.com/ll-nick/inkflow
+Author: Nick Le Large
+License: MIT
+License-File: LICENSE
+Keywords: animation,inkscape,presentation,slides,svg
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Multimedia :: Graphics :: Presentation
+Requires-Python: >=3.11
+Requires-Dist: brotli>=1.2.0
+Requires-Dist: click>=8.0
+Requires-Dist: fonttools>=4.63.0
+Requires-Dist: latex2mathml>=3.81.0
+Requires-Dist: lxml>=5.0
+Requires-Dist: markdown-it-py>=3.0
+Requires-Dist: mdit-py-plugins>=0.6.1
+Requires-Dist: platformdirs>=4.0
+Requires-Dist: pygments>=2.20.0
+Requires-Dist: rich>=15.0.0
+Requires-Dist: typing-extensions>=4.15.0
+Requires-Dist: watchfiles>=0.21
+Requires-Dist: websockets>=12.0
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="docs/assets/logo-light-landscape.svg">
+    <source media="(prefers-color-scheme: light)" srcset="docs/assets/logo-dark-landscape.svg">
+    <img src="docs/assets/logo-dark-landscape.svg" width="80%">
+  </picture>
+</p>
+
+<p align="center"><strong>Beautiful slides from SVG. Your editor, your style.</strong></p>
+
+<p align="center">
+  <a href="https://ll-nick.github.io/inkflow/demo/">
+    <img src="docs/assets/demo-button.svg" alt="Try the live demo">
+  </a>
+</p>
+
+> **Early-stage software.**
+> Expect bugs, missing features, and breaking changes.
+
+## The idea
+
+Every presentation tool makes you choose.
+
+**Visual editors** (PowerPoint, Keynote, Google Slides) give you a canvas.
+Drag shapes, resize freely, iterate until it looks right.
+But your work lives in proprietary formats tied to a platform or subscription,
+and exporting to anything else means fighting a lossy conversion.
+
+**Code-based tools** (Beamer, Slidev, reveal.js) keep everything as plain text.
+Files are diffable, version-controlled, reproducible.
+But you describe layout in markup instead of drawing it.
+Creativity suffers when moving a box means editing a coordinate.
+The blank page is a text cursor, not a canvas.
+
+**Inkflow gives you both.**
+Your authoring environment is a proper vector editor.
+Draw freely, iterate visually.
+Your source files are SVG, Markdown, and Python: open formats, plain text, not tied to any software or service.
+
+## How it works
+
+A deck is a plain Python file:
+
+```python
+from inkflow import Deck, Image, MediaFit, Slide, Video, animations, transitions
+
+def main() -> Deck:
+    return Deck(
+        slides=[
+            # SVG slide: draw freely in Inkscape, animate elements by id
+            Slide(
+                "title.svg",
+                animations=[
+                    animations.FadeIn("#headline", step=1),
+                    animations.FadeIn("#subtitle", step=2),
+                ],
+            ),
+            Slide(
+                "diagram.svg",
+                # Fill predefined content zones using Markdown
+                md="diagram.md",
+                # Set a transition for the whole slide, and multiple animations for individual elements
+                transition=transitions.Crossfade(),
+                animations=[
+                    animations.Bounce("#box-a", step=1),
+                    animations.Bounce("#box-b", step=2),
+                ],
+            ),
+            Slide(
+                # Reuse a built-in, theme or project-local layout
+                "media-right",
+                md="image.md",
+                # Fill a named zone with an image, or a video with playback control
+                # (autoplay, loop, mute, trim, play-on-step)
+                zones={"media": Image("assets/photo.jpg", fit=MediaFit.COVER)},
+            ),
+            Slide(
+                "media-left",
+                md="clip.md",
+                zones={"media": Video("assets/demo.mp4", autoplay=True, loop=True)},
+            ),
+        ]
+    )
+```
+
+When you run `inkflow serve`, Inkflow reads the slides as defined in the Python file
+and processes them into a web-based presentation.
+It will inject the Markdown and media files into the SVGs, apply the transitions and animations, and serve the result to your browser.
+
+## Quick start
+
+```bash
+uv add inkflow # or: pip install inkflow
+inkflow init my-deck
+cd my-deck
+inkflow serve
+# press "o" in the tui to open http://localhost:7777 in your browser,
+# press ? in the presenter for keyboard shortcuts
+```
+
+To try the bundled demo:
+
+```bash
+git clone https://github.com/ll-nick/inkflow
+cd inkflow
+uv run inkflow serve --deck demo/deck.py
+```
+
+No SVG editor is invoked at serve time. Inkscape or any other tool writes the files, Inkflow reads them.
+Saving a slide reloads the presenter automatically.
+
+## Acknowledgements
+
+[Slidev](https://sli.dev) is an excellent presentation tool and a direct inspiration for this project.
+It's a Node.js project with a very different architecture and feature set,
+including many things Inkflow will never do.
+
+This project was built making heavy use of coding agents and would not have been possible without them.
+Does that make it "slopware"?
+I'll let you be the judge of that but I can say that I try my best to keep the agents in check.
+Every architectural decision is mine, there's a CI to ensure a certain level of code quality,
+and before merging, I spend a good amount of time reviewing all changes in good old-fashioned manual labor.