scenet

# Scenet

**A semantic DSL for comic panels, compiled to SVG.**

## ⚠️ This project is deliberately AI-generated

This project is, by design, almost entirely generated by AI. It exists as a personal training
ground for learning to work with AI coding tools. The architecture, code, tests and documentation
are overwhelmingly AI-authored, under human direction and review.

Treat it accordingly: an experiment first, a usable tool second.

---

[![CI](https://github.com/creatoan/scenet/actions/workflows/ci.yml/badge.svg)](https://github.com/creatoan/scenet/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/scenet.svg)](https://pypi.org/project/scenet/)
[![Python](https://img.shields.io/pypi/pyversions/scenet.svg)](https://pypi.org/project/scenet/)
[![License: 0BSD](https://img.shields.io/badge/License-0BSD-brightgreen.svg)](LICENSE)
![Status: alpha](https://img.shields.io/badge/status-alpha-orange.svg)

**[Playground](https://creatoan.github.io/scenet/playground/)** ·
**[Documentation](https://creatoan.github.io/scenet/)** ·
**[Tutorial](https://creatoan.github.io/scenet/tutorial/first_panel.html)** ·
**[Changelog](CHANGELOG.md)**

## What this is

Music has notation. A score describes the *semantics* of a piece — pitch, duration, dynamics —
without describing the waveform that eventually reaches your ear. Rendering is left to an
interpreter, human or machine.

Images have no such thing. SVG describes *how to draw*, not *what is depicted*: it is closer to a
WAV file than to a score. Scenet is an attempt at the missing layer, narrowed to one tractable
domain — the comic panel.

You write what is in the panel:

```yaml
panel:
  size: [1000, 1000]
camera:
  shot: medium_shot
  angle: eye_level
setting:
  place: street
  weather: rain
cast:
  alice: {reference: alice, pose: pointing,     at: left_third,  facing: right}
  bob:   {reference: bob,   pose: arms_crossed, at: right_third, facing: left}
staging:
  - alice left_of bob
  - alice looking_at bob
script:
  - say: {by: alice, text: "You forgot your umbrella!", prefer: top_left}
  - say: {by: bob,   text: "I know."}
```

You can also write a sequence, where each panel states only what changed from the one
before — borrowed from OpenUSD's sparse override, because consecutive panels in a scene
share nearly all their staging:

```yaml
panels:
  establishing:
    camera: {shot: full_shot}
    cast: {alice: {reference: alice}, bob: {reference: bob}}
  reaction:
    over: establishing        # same cast, same staging
    camera: {shot: close_up}  # move in
```

Or in comic script, the format writers already use:

```
PANEL 1
@shot: full_shot
Alice and Bob face each other on a rainy street corner.

ALICE
You forgot your umbrella!

BOB (whisper)
I know.
```

From any of these, the compiler works out the rest: how large each figure must be for a medium shot, where they
stand, which way they face, how big each balloon needs to be for its text, where a balloon can sit
without covering a face, and how its tail reaches the speaker's mouth — all while preserving
reading order.

**No generative image model is involved.** This is a deterministic compiler: constraint solving and
computational geometry. The same input always produces byte-identical output.

## Status

**Alpha — panels and sequences compile end to end, from the command line, the
browser, or an editor.** Framing, actor placement, balloon
and caption placement, reading order, tail routing, drawn faces and the marks around them, tonal backdrops
and SVG emission all
work, from either of two frontends. Not yet built: page composition (tiers, panels of varying size) and the
interpretation layer that would give a panel a *style*. See
[the phase plan](docs/explanation/status.md) for detail.

```bash
uv run scenet build examples/duel.panel.yaml --core --debug
uv run scenet build examples/sequence.scene.yaml --strip
uv run scenet build examples/umbrella.script --strip
```

`--core` writes the resolved intermediate tier as JSON; `--debug` writes an overlay showing
the geometry the solver was working against — silhouette hulls, face exclusion zones, anchors,
gaze vectors and tail routes.

## How it works

```
  duel.panel.yaml     →     Panel Core (.core.json)     →     panel.svg
  authored,                 resolved, fully numeric,          rendered
  no coordinates            still named & inspectable
```

The intermediate tier is a real, writable format rather than a hidden data structure — so layouts
can be inspected, hand-adjusted, and diffed independently of how they are drawn. The approach is
borrowed from Vega-Lite, which compiles a high-level grammar into a lower-level one before emitting
SVG.

## Try it in the browser

The **[playground](https://creatoan.github.io/scenet/playground/)** runs this compiler — the
same Python, unmodified — in your browser under WebAssembly via
[Pyodide](https://pyodide.org/). It is not a reimplementation: the page installs the exact
wheel `uv build` produces, so there is no second copy of the geometry to drift out of step.

Its worked examples cover every shot type, every balloon kind, every caption kind, every
expression and mark, every mass kind and place, both frontends and the constraint priorities. Each one is a real file under
[`examples/gallery/`](examples/gallery/) that the test suite compiles, so the playground
cannot offer an example that does not work.

The editor is Monaco, fed the *same* JSON Schema the VS Code extension uses — generated
from the compiler's own models, so completion and hover documentation cannot drift from
what compiles. Everything is served from one origin: no CDN, no analytics, nothing
fetched from anywhere else.

## Editor support

The [VS Code extension](editor/) gives completion and inline validation for panel
documents, plus a side-by-side preview. Its JSON Schema is *generated from the
compiler's own models* by `scenet schema`, so what the editor offers is what actually
compiles. A test fails if the shipped schema goes stale.

## Using it from a model

No model knows Scenet from training, so the project hands the language over instead.
[Driving Scenet from a model](docs/howto/drive_from_a_model.md) covers each kind of client:

- **A chat app that cannot run code** — NotebookLM, the Gemini app — gets the
  [spec pack](https://creatoan.github.io/scenet/scenet-spec.md): the language, the
  comic-script format, the characters, every diagnostic and the whole gallery, in one file.
- **An agent that loads skills** gets [`skills/scenet`](skills/scenet/), an
  [Agent Skills](https://agentskills.io/) folder.
- **An MCP client** gets `scenet mcp`, whose tools validate, compile and render, so the model
  can read its own errors and fix them.

```bash
pip install 'scenet[mcp]'
scenet mcp
```

<!-- mcp-name: io.github.creatoan/scenet -->

## Install

```bash
pip install scenet
```

Python 3.12 or newer. No system libraries, no fonts to install, nothing to configure. Ships
a `py.typed` marker, so mypy, pyright, ty and basedpyright read the annotations straight
from the package.

```python
from scenet import compile_source, render

result = compile_source("cast: {alice: {reference: alice}}")
svg = render(result.core)
```

## Development

Requires [uv](https://docs.astral.sh/uv/). It manages the Python version too, so this is the whole
setup:

```bash
uv sync --all-groups
uv run pytest
```

Checks, all of which run in CI:

```bash
uv run ruff check . && uv run ruff format --check .
uv run ty check
uv run pytest
```

## Documentation

**[creatoan.github.io/scenet](https://creatoan.github.io/scenet/)** — or read the Markdown
source under [`docs/`](docs/), which GitHub renders without a build step.

| | |
|---|---|
| [Tutorial](docs/tutorial/first_panel.md) | Build a panel from nothing, in fifteen minutes |
| [How-to guides](docs/howto/index.md) | Sequences, comic scripts, your own characters, using it as a library |
| [Language specification](docs/reference/language.md) | Every construct, with examples |
| [Shot types](docs/reference/shot_types.md) | Normative camera framing table |
| [Panel Core](docs/reference/panel_core.md) | The resolved intermediate format |
| [Asset contract](docs/reference/asset_contract.md) | What a character puppet must declare |
| [MCP server](docs/reference/mcp.md) | The tools `scenet mcp` serves to a model |
| [API reference](docs/reference/api/index.md) | Every public name |
| [Design decisions](docs/explanation/design_decisions.md) | Why it is shaped this way |
| [Prior art](docs/explanation/prior_art.md) | What already exists, and what was taken from it |

Every Python example in the documentation is executed by the test suite. An example that
omits an import, or that has drifted out of step with the code, fails the build.

## License

**0BSD** — see [LICENSE](LICENSE). This is deliberately one step more permissive than
MIT: you may use, copy, modify and distribute this software for any purpose, with no
obligation to preserve a copyright notice or reproduce the license. No attribution is
required, though it is always welcome.

Third-party components are listed in [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md). The
lettering font arrives as an ordinary dependency under the SIL Open Font License, which does
require its own notice be kept with it.

**The language specification is free to implement.** Anyone may build their own compiler, editor,
renderer or tooling for this language, in any project, commercial or otherwise, without restriction
or attribution. A notation is only worth having if it is not owned.