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] [PyPI] [Python] [License: 0BSD] [Status: alpha]

Playground · Documentation · Tutorial · Changelog

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:

panel:  size: [1000, 1000]camera:  shot: medium_shot  angle: eye_levelsetting:  place: street  weather: raincast:  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 bobscript:  - 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:

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_shotAlice and Bob face each other on a rainy street corner.
ALICEYou 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 for detail.

uv run scenet build examples/duel.panel.yaml --core --debuguv run scenet build examples/sequence.scene.yaml --stripuv 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 runs this compiler — the same Python, unmodified — in your browser under WebAssembly via Pyodide. 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/ 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 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 covers each kind of client:

• A chat app that cannot run code — NotebookLM, the Gemini app — gets the spec pack: 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, an Agent Skills folder.
• An MCP client gets scenet mcp, whose tools validate, compile and render, so the model can read its own errors and fix them.

pip install 'scenet[mcp]'scenet mcp

Install

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.

from scenet import compile_source, render
result = compile_source("cast: {alice: {reference: alice}}")svg = render(result.core)

Development

Requires uv. It manages the Python version too, so this is the whole setup:

uv sync --all-groupsuv run pytest

Checks, all of which run in CI:

uv run ruff check . && uv run ruff format --check .uv run ty checkuv run pytest

Documentation

creatoan.github.io/scenet — or read the Markdown source under docs/, which GitHub renders without a build step.

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. 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. 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.