Command line#
scenet [--version] <command> [options]
Four commands: build compiles a document, check validates one without compiling it,
schema emits the JSON Schema, and mcp serves all of that to a model. A bare scenet prints help to stderr and exits 2
— it did nothing, and a script chaining off its status should not read that as success.
scenet build#
Since 0.1.
scenet build SOURCE [-o OUTPUT] [--core] [--debug] [--conditioning] [--live-text] [--mono] [--no-aria] [--embed-images] [--strip] [--pdf] [--quiet] [--watch]
Compiles SOURCE to SVG. The frontend is chosen by extension:
Extension |
Read as |
|---|---|
|
YAML — single panel or a |
|
Comic script |
Options#
-o,--output PATHWhere to write. Defaults to the source’s name with an
.svgextension, alongside it. Note thatduel.panel.yamlbecomesduel.svg, notduel.panel.svg. A directory, one that exists or one written with a trailing/such asout/, takes that default name inside it, so-o .writesduel.svgto the current directory. Any other path is the SVG file itself, and every other output is named after it. Since 0.1.--coreAlso write the resolved Panel Core as JSON — every coordinate the compiler chose, in a format you can read, diff and hand-edit. See Panel Core. Since 0.1.
--debugAlso write a diagnostic overlay showing the geometry the solver was working against: silhouette hulls, face exclusion zones, named anchors, gaze vectors and tail routes. This is usually the fastest way to see why a panel came out the way it did. Since 0.1.
--conditioningAlso export each panel’s staging for image models, as five files beside its SVG: the pose as OpenPose JSON, boxes with phrases, a depth map, a mask, and the semantics. No model runs: each is another emitter reading Panel Core, text, JSON or SVG, and byte-identical like the rest. Per panel only; a page’s frames are in its Page Core (
--core). See export for image models. Since 0.12.--live-textEmit selectable
<text>elements instead of glyph outlines. Smaller files and selectable text, but the result depends on the reader having a metrically compatible font installed, and on the renderer kerning it as the compiler measured it — browsers do by default. The default emits outlines, which makes the file genuinely self-contained. With--pdf, the print PDF is lettered in text too, and exactly: each face is embedded as a subset where its licence (the font’sOS/2fsType) allows, and every glyph lands where its outline would; a face that may not be embedded stays in outlines, and a note says so. Sound effects stay outlines in both. Since 0.1.--monoDraw every value as its grey and ignore its colour: a black-and-white edition of a document drawn in
palette: tinted, made without editing it. Every panel, page and strip is byte-identical to what the same document writes withpalette: mono, because a palette only ever adds a colour beside a value the compiler had already decided on its grey. With--pdf, the print PDF is printed in the greys too, rather than in the colours’ CMYK twins: the same filepalette: monoprints. Panel Core and the exports for image models are unaffected:--corestill records the palette and its colours. Since 0.13.--no-ariaWrite no accessibility markup. By default each panel is an image a screen reader can read —
role="img", named by its<title>with what it shows and then everything said in it, in reading order — and a strip or a page is a named group of them; see accessible output. This leaves all of that out, for a pipeline that post-processes the SVG, and is otherwise byte-identical: the same file less those attributes and elements. Debug overlays never carry it. Since 0.12.--embed-imagesWrite each supplied picture into the SVG as a
data:URI, so the file stands alone. By default a picture is linked by the path the document wrote, which a viewer reads from beside the SVG: that finds it when the SVG is written beside the document, as it is by default. Written anywhere else, the build says so in anote:, since the link will not resolve there; an SVG shown as an<img>, or turned into a PNG, loads no linked file at all. Embedding is byte-identical for the same picture. Since 0.12.--stripFor a document of more than one panel, also lay every panel out side by side in reading order, as one extra file. Ignored when there is only one panel, a one-panel scene included. Since 0.1.
--pdfAlso write the document as one print PDF,
stem.pdf, beside the SVGs: a PDF page per page, or per panel for a document with no pages; with pages, a panel on no page is not printed. A page unit prints as 0.1 mm, and a page’sbleedruns the sheet past its trim (TrimBox and BleedBox). Lettering, balloon borders and every line are 100% black and overprint; the paper knocks out; greys are black tints, the night foreground rich black; a tinted palette prints its colours’ CMYK twins under GRACoL 2013 (CGATS21-2-CRPC6), and with--monoits greys; supplied pictures go in with their pixels unchanged; the fog and cloud veil is the SVG’s noise, rasterised at 127 dpi. It letters in outlines, or with--live-textin its embedded faces. The other SVG options do not change it — it carries its pictures, so--no-aria,--embed-imagesand--stripleave its bytes as they are. Notes say what print leaves out or changes: a colour that is none of the palette’s, a picture below 300 dpi, a face that may not be embedded. RGB pictures are tagged sRGB, and an output intent names the printing condition, but no PDF/X conformance is claimed. See Print a comic. Since 0.13.--quietSuppress the
wroteandnote:lines. You do not normally want this: the notes are where the compiler tells you it did something you did not ask for. Each kind has a name, listed with what to do about it in Work out why a panel looks wrong — all but what the build says about its files: a linked picture written away from its document, and what--pdfleaves out. Since 0.1.--watchBuild once, then rebuild when the source, a file read during compilation, or a tracked dependency directory changes. Changes are debounced until inputs have stayed still for about 300 ms. Failed builds are reported and watching continues; the source and previously observed dependencies stay watched so a deleted source or a partial failed build can recover. Watch mode does not start a server or reload a browser. It polls with the standard library by default; install
scenet[watch]to usewatchfileswhen available. Ctrl-C exits with 0. Since 0.13.
Output naming#
A single-panel document writes to the requested name. A multi-panel document suffixes each panel with its own name, so the mapping back to the source stays obvious:
sequence.scene.yaml → sequence.establishing.svg
sequence.reaction.svg
sequence.strip.svg (with --strip)
A document that lays its panels out with pages:, or a comic script with PAGE headings, also
writes each page beside them, with its Page Core and overlay when --core and --debug ask for
them. Pages are numbered by position, from 1, whatever a script’s headings call them:
story.scene.yaml → story.page-1.svg
story.page-1.core.json (with --core)
story.page-1.debug.svg (with --debug)
With --pdf, the whole document is one PDF named after the main SVG, and -o with a .pdf
name is a usage error, since -o names the SVG:
story.scene.yaml → story.pdf (with --pdf)
With --conditioning, each panel’s exports for image models are named after its SVG:
duel.panel.yaml → duel.svg
duel.pose.json (with --conditioning)
duel.boxes.json
duel.depth.svg
duel.mask.svg
duel.semantics.json
Two outputs that would be the same file are a usage error, exit 2, and nothing is written: a
panel named page-1 beside a page, strip beside the strip, or x.debug or x.depth beside
panel x’s overlay or depth map. One file silently replacing the other is the kind of loss
Scenet refuses everywhere else. Names are compared ignoring case, as Windows and macOS compare them, so a document
writes the same set of files everywhere. A panel name holding / or \ cannot be part of
a file name and is refused the same way.
Exit status#
Code |
Meaning |
|---|---|
0 |
Compiled |
1 |
The document could not be compiled — reported as a plain message, not a traceback |
2 |
Usage error, or the source file does not exist or has an extension no frontend reads |
Every error the compiler raises inherits ScenetError, and all of them mean “your panel
cannot be compiled” rather than “scenet broke”. They print as one line. A traceback from
scenet is a bug worth reporting.
Examples#
scenet build examples/gallery/01-two-characters.panel.yaml
scenet build examples/gallery/01-two-characters.panel.yaml --core --debug
scenet build examples/gallery/12-sequence.scene.yaml --strip
scenet build examples/gallery/13-comic-script.script --strip -o out/umbrella.svg
Also export each panel’s staging for image models, beside its SVG:
scenet build examples/gallery/01-two-characters.panel.yaml --conditioning
Letter in selectable text rather than outlines:
scenet build examples/gallery/01-two-characters.panel.yaml --live-text
A black-and-white edition of a tinted document, without editing it:
scenet build examples/gallery/40-tinted-hours.scene.yaml --mono
Without the accessibility markup, for a pipeline that post-processes the SVG:
scenet build examples/gallery/01-two-characters.panel.yaml --no-aria
A supplied picture written into the SVG, so the file stands alone:
scenet build examples/gallery/52-a-jpeg.panel.yaml --embed-images -o out/jpeg.svg
The print PDF, beside the SVGs:
scenet build examples/gallery/12-sequence.scene.yaml --pdf
In a script, with nothing printed on success:
scenet build examples/gallery/01-two-characters.panel.yaml --quiet
Rebuilt on every save, until Ctrl-C:
scenet build examples/gallery/01-two-characters.panel.yaml --watch
scenet check#
Since 0.3.
scenet check SOURCE... [--format {text,sarif}] [-o OUTPUT] [--quiet] [--deep]
Reports everything wrong with one or more documents and exits non-zero if anything is an error. A note reports a house limit rather than a contradiction — a balloon over the words a publisher asks for, say — so the document still builds, and a note alone never fails the check. Nothing is written unless you ask for it — no SVG, no Panel Core.
Unlike build, this does not stop at the first fault. pydantic reports every field error
at once and several files are reported together, because whoever is fixing them — a person
or an agent — wants the whole list rather than one round trip per mistake.
Beyond validating the IR, check resolves every cast member’s reference, pose and
expression against the puppet library — the IR alone cannot tell pointing from
smirking, since both are just strings until something looks them up. The library is
read once per document, however many panels it has, and a puppet file a cast names once
per panel that casts it. This is still the cheap pass: no solver, no font
metrics, no balloon placement — those are what --deep adds.
Why this exists#
No JSON Schema can catch the errors that matter most here. The interesting checks are
model_validators: every actor id in staging and script resolving to a cast member,
and the left_of/right_of graph being acyclic. Neither is expressible in JSON Schema,
and both are exactly what a generator gets wrong. So structured diagnostics — not the
published schema — are what make a generate/validate/repair loop work.
Options#
--format text(default)One line per finding on stderr,
file:line:column: rule: message, orfile:line:column: note: rule: messagefor a note, where GCC and Clang put a severity. What a person reads.file: okfollows on stdout for each document when none has an error, notes or not. Since 0.3.--format sarifSARIF 2.1.0, the OASIS standard GCC, Clang and MSVC emit and GitHub code scanning ingests directly. Nothing but the document reaches stdout, so redirecting it produces a file a parser accepts. To see the findings in VS Code, see Findings the schema cannot see. Since 0.3.
-o,--output PATHWrite the report to this file instead of the terminal, in either format. In text format the file holds the findings, one per line, and is empty when every document is valid. It names a file, so a directory is refused. Since 0.3.
--quietSuppress the per-file
okline. Findings are always reported — this hides the reassurance, never the diagnosis. Since 0.3.--deepAlso run the full compiler on any document that passes every cheap check, to additionally catch
layoutandballoon-placement— two rules in the catalogue that the cheap pass cannot produce, because they only surface once the solver actually runs. Off by default: it costs a real compile, including font metrics. Skipped for a document the cheap pass already found something wrong with, so a document with a bad pose reports that once rather than a second, worse-located finding for the same fault. Since 0.6.
Exit status#
Code |
Meaning |
|---|---|
0 |
No document has an error; notes may have been printed |
1 |
At least one error |
2 |
Usage error, or a source file does not exist or has an extension no frontend reads |
The status means the same thing in both formats, so CI can key off it without parsing anything.
Rules#
Every finding carries a stable ruleId, and each has an entry in
the diagnostics reference: why it happens, how to fix it, and a document that
gives it beside the same document fixed. SARIF links it from the rule’s helpUri. These identifiers do not change across
releases: a ruleId that moves silently closes every alert that referenced the old one
and opens a duplicate under the new one, so renaming one is a breaking change even though
nothing stops compiling.
A rule’s level is part of it too. An error is a contradiction the compiler cannot
build past; a note is a house limit a document can exceed and still compile. SARIF
carries the level in both defaultConfiguration and each result, so an editor shows a
note as information rather than a red squiggle.
Rule |
Level |
Raised when |
|---|---|---|
error |
The file is not valid YAML, or is empty; in a comic script, its front matter. A line indented to match no line above it is said to be |
|
error |
A key written twice in one mapping, which YAML would drop silently; in a comic script, a directive written twice in one panel, or |
|
error |
The top level is a list or a scalar |
|
error |
A key the language does not define — usually a typo |
|
error |
A required value was not supplied |
|
error |
A known key holding the wrong type or an out-of-range value |
|
error |
Non-positive size, or margins leaving no usable area |
|
error |
An id in |
|
error |
A line spoken from off panel by somebody drawn in the panel |
|
error |
An underscore that opens emphasis in a line of |
|
error |
A relation relating an actor to itself |
|
error |
|
|
error |
|
|
error |
An |
|
error |
A panel of a scene that writes |
|
error |
Two panels in a comic script with the same name, even counting pages |
|
error |
A page placing a panel that does not exist, or one twice, two stacked columns side by side, two insets that overlap, an inset too big for its panel, a slant that cannot apply or is too steep, a bleed on a side that does not reach the margin, or no room for its tiers |
|
error |
A |
|
error |
A setting’s |
|
error |
A setting that names a |
|
error |
A |
|
error |
An |
|
error |
A |
|
error |
A picture in |
|
error |
A picture whose figures the panel casts has no artwork contract beside it ( |
|
error |
A cast |
|
error |
A cast member with both |
|
error |
A staging relation naming a figure a picture draws, or a |
|
error |
A font in |
|
error |
Valid, but no layout satisfies its required constraints ( |
|
error |
No legal position exists for a balloon ( |
|
error |
No legal position exists for a sound effect ( |
|
note |
A balloon or caption over about 25 words, or a panel over about 50: Dark Horse’s limits |
|
note |
A comic script’s |
|
note |
A cue in a comic script with nothing said under it, or a name in capitals with a line under it outside any panel |
|
note |
A shared staging relation left out of a panel its actor is left out of: |
|
error |
A failure with no more specific rule — worth reporting |
Source positions#
A finding is located in the file it is about, which is usually the document checked. A fault inside a picture’s artwork contract, or inside a puppet file a cast member names, is located in that file — its own path, line and column — since that is the file to open to fix it; checked as text, with no file of its own, the document points at the line naming the picture or the puppet instead.
yaml.safe_load discards the position of every value, so the document is composed a
second time with yaml.compose, whose node tree carries start_mark and end_mark. Those
marks are 0-based and SARIF is 1-based; the conversion happens once, at that boundary.
ruamel.yaml’s .lc marks would do the same job and are what one usually reaches for.
They were not used: PyYAML is already a dependency, so a second YAML implementation in the
runtime — and in the licence gate — would buy nothing.
Comic scripts are line-oriented, so a finding there carries a line and no column. A script
line is prose, and pointing at a character within it would imply a precision the parser
does not have. SARIF could say “line 5” with startLine alone, but GitHub code scanning
requires all four bounds, so the region runs from column 1 to the end of the line, and an
editor underlines the whole line. The text format prints column 1.
Columns count Unicode code points, and the SARIF run says so with columnKind. An editor
that counts UTF-16 code units, as VS Code does, converts them.
Fingerprints#
Each result carries a partialFingerprints entry under scenetDiagnostic/v1, derived
from the rule, the structural path, the message and the file — deliberately not from
the line number. A fingerprint keyed on position changes whenever anybody adds a comment
at the top of the file, which turns one long-standing alert into a new alert on every
edit, and de-duplicating alerts is the entire point of the field.
The file enters as the uri the result reports, not as you typed it, so a.panel.yaml
and its absolute path give one fingerprint.
Examples#
scenet check examples/gallery/01-two-characters.panel.yaml
scenet check examples/gallery/*.panel.yaml examples/gallery/*.scene.yaml
scenet check --format sarif examples/gallery/01-two-characters.panel.yaml > results.sarif
scenet check --deep examples/gallery/*.panel.yaml examples/gallery/*.scene.yaml
The findings in a file, one per line, and only the exit status on the terminal:
scenet check --quiet -o report.txt examples/gallery/01-two-characters.panel.yaml
Uploading to GitHub code scanning, which is how findings become annotations on a pull request:
- run: >-
uv run scenet check --format sarif -o results.sarif
examples/gallery/*.panel.yaml examples/gallery/*.scene.yaml
- uses: github/codeql-action/upload-sarif@v4
with:
sarif_file: results.sarif
As a library#
The same findings are available without the process boundary:
from pathlib import Path
from scenet.diagnostics import diagnose_source, to_sarif
source = """
cast:
alice: {reference: alice}
script:
- say: {by: bpb, text: Hello}
"""
found = diagnose_source(source, source=Path("duel.panel.yaml"))
finding = found[0]
assert finding.rule == "unknown-actor"
assert finding.path == ("script", 0, "say", "by")
assert finding.region.start.line == 5
document = to_sarif(found, root=Path.cwd())
assert document["runs"][0]["results"][0]["ruleId"] == "scenet/unknown-actor"
The assertions are the point: this block is executed by the test suite, so an example that stopped being true would fail the build rather than quietly misinform.
diagnose_file is the same thing for a path on disk, and picks the frontend by
extension.
scenet.diagnostics is a public module. It is not re-exported from the scenet package
namespace, because it reads the package version and importing it from __init__ would
close an import cycle.
scenet schema#
Since 0.1.
scenet schema [-o OUTPUT] [--scene | --artwork | --puppet]
Emits the JSON Schema for a panel document, derived from the same pydantic models the compiler validates against. Editors use it for completion and inline validation, so what the editor suggests cannot drift from what compiles — see editor support.
-o,--output PATHWrite to this file instead of stdout. It names a file, so a directory is refused. Since 0.1.
--sceneEmit the multi-panel scene schema instead of the single-panel one. A scene allows the same keys as a panel — where they act as defaults every panel inherits — plus
panels:, whose members may additionally carryover:. Since 0.1.--artworkEmit the schema for an artwork contract, the
*.art.yamlfile beside a supplied picture that declares the figures it draws. What a schema cannot say — every point on the picture, every region a simple polygon, the size the picture’s own —scenet checkdoes. Since 0.12.--puppetEmit the schema for a puppet file, the
*.puppet.yamla cast member names by its path inreference:. It requires every landmark, ahead_topof zero and astanding_neutralpose; what a schema cannot say — landmarks increasing downward, a skeleton that is a tree, every joint a part or a pose names declared —scenet checkdoes, in the puppet file, on a document that casts it. Since 0.13.
scenet schema -o panel.schema.json
scenet schema --scene -o scene.schema.json
scenet schema --artwork -o artwork.schema.json
scenet schema --puppet -o puppet.schema.json
The output is sorted and indented, so it is stable under version control.
Exit status#
Code |
Meaning |
|---|---|
0 |
The schema was written |
2 |
Usage error, or |
scenet mcp#
Since 0.8.
scenet mcp [--transport {stdio,streamable-http}] [--host HOST] [--port PORT]
Runs an MCP server whose tools read the specification, list the characters, validate, compile and render — so a model can check the panel it wrote, read what is wrong and fix it, with nobody copying error text between windows. The tools themselves are documented in the MCP server reference.
Needs the optional extra, which brings the official mcp SDK:
pip install 'scenet[mcp]'
Without it, the command says so on stderr and exits 2. Every other command works without the extra.
--transport stdio(default)For a client that launches the server itself, which is how desktop and editor clients run a local server. Nothing but protocol messages reaches stdout — the server never prints, and the compiler’s notes travel inside tool results. Since 0.8.
--transport streamable-httpListens for remote clients over Streamable HTTP. There is no authentication, so put it behind something that provides it before exposing it beyond your own machine. SSE is not offered: the protocol deprecated it in favour of Streamable HTTP. Since 0.8.
--host HOST,--port PORTWhere Streamable HTTP listens. Defaults to
127.0.0.1and8000, so it is reachable only from the same machine unless you say otherwise. Since 0.8.
Exit status#
Code |
Meaning |
|---|---|
0 |
The client disconnected |
2 |
Usage error, or the |
scenet mcp
scenet mcp --transport streamable-http --port 8765
scenet mcp --transport streamable-http --host 127.0.0.1 --port 8765
scenet --version#
Since 0.1.
Prints the installed version and exits 0.
Determinism#
The same input always produces byte-identical output, as
Determinism says: two runs on different machines produce files
you can compare with cmp. The print PDF carries no date and takes its /ID from its content,
and compresses nothing: zlib implementations differ from one platform to the next.