What’s new#
Every release, newest first, and what is on main but not yet released under Unreleased. It
is the project’s CHANGELOG, shown
here as it is written there. For what Scenet does as a whole, see
What Scenet does today.
All notable changes to this project are documented here.
The format follows Keep a Changelog, and this project adheres to Semantic Versioning.
While the version is below 1.0.0, minor releases may break things. That is what being
below 1.0 means.
Unreleased#
0.13.0 - 2026-11-12#
Upgrading from 0.12.0.
The depth map of every panel with a ground, floor, water or ceiling changes once (#227), and with it the bytes of its
.depth.svg: regenerate golden depth maps of your own. Nothing else changes, Panel Core included.
Added#
The front door and the story (#323). The README and the site’s landing page open the same way: the gallery tour’s picture, one sentence on what Scenet does today, buttons to the playground, the gallery and the install guide, the AI-generated notice word for word, and a door for each reader: Discover, Write comics, Build with Python, Drive from a model, Contribute. The README is the PyPI page too, so every link in it is absolute and it stays under 120 lines; a test holds it to both. About gains Why Scenet, the score-and-performer thesis rewritten for what Scenet is now, with the style layer defined; What Scenet does today, a feature matrix in place of the phase log, whose every “since” is checked against the releases mined from the tags and the CHANGELOG, unreleased work marked; and What’s new, this file. The navbar reads Learn, Guides, Language, Python API, Gallery, Playground, About, with Contribute in the footer; the how-to guides are grouped by what the reader is doing, a line each; and Use the playground documents every button, Puppet… included, which a test holds to the page’s toolbar. Design decisions is named so and grouped by theme, the PDF print spike is a design note marked superseded, the glossary gains character, scene, sequence, page, book and retreat, and reader pages say what a thing does rather than which issue added it.
One umbrella panel. The gallery’s
01-two-charactersis the example every page shows: the README, the landing page, the skill and the Python track. The language reference’s complete example, gallery71, is that panel with a setting, and a test holds every copy to it. The six files at the top ofexamples/are folded into the gallery, whose files the reference’s commands now name.Learn Scenet from Python (#322): the developer’s track, five chapters under
docs/tutorial/python/, frompip install scenetto Scenet inside a program of your own. Compile and render calls everycompile_*entry point and every renderer, writes files, and hands fonts and pictures back withfonts=andembed=; Read what it decided reads a Panel Core as objects and as JSON, edits one and draws it again, and shows determinism; Errors and notes walks theScenetErrortree, a fault’s rule and place, and notes matched by their codes; Bring your own adds a puppet library, a font asmetrics=, a document’s files asbase=, and a picture; Outputs, batch and CI builds a folder, keeps golden files, runsscenet check, writes SARIF from Python, and calls the MCP tools and server in process. Every example is a complete script followed by what it prints: the test suite runs each one alone, in a folder holding the documents its chapter saved, and compares its output with the page.tests/test_python_track.pyholds every chapter to its parts, its examples to their output, and the track to every publiccompile_*andrender_*function, each called and linked to its reference page. The Tutorial page now leads to both tracks.The author’s tour (#321): twelve chapters under
docs/tutorial/, from a first panel to a printed page, comic scripts, art and puppets of your own, right to left, and what Scenet tells you. Each shows what you will make, as a gallery picture, beside its complete document; builds it and says what the compiler decided; opens its examples in the playground; runsscenet check; and links the key cards and the diagnostics entries. The gallery’s groups are now the tour’s chapters, in its order, in the playground’s menu too, and the Gallery page sends each group to its chapter.tests/test_tutorial.pyholds every chapter to that shape, every “Try it” list to its group, every printed output to what the command prints, and the tour to the whole language: every key of a panel or a scene, and every top-level key of a puppet file and an artwork contract, is written in a chapter’s document and linked to its card. The first chapter,first_panel.md, is rewritten for an author: it installs withuv tool install, builds the file it wrote, and names a note by its id.The install guide names the
mcpandwatchextras.A documented command runs on the files its page wrote. A
bashblock in the docs now finds every file a block above it, captioned with a file name, shows, and the gallery’s pictures, fonts and puppets; a line ending in# exits 1must exit 1, so a page can showscenet checkfailing on a mistake. A captioned copy of a gallery example counts as that example.The command-line reference is complete (#320). Every option of every command has an example, which the test suite runs – a
--watchexample runs its first build – and every command and option says the release it appeared in, mined from the tags intodocs/reference/cli.since.tomlbyscripts/mine_cli_since.py:--pdf,--mono,--watchand--puppetare 0.13, not yet released.scenet schemahas an exit-status table, held to a scenario for each code as the other commands’ are. Each rule in the table of rules links its entry in the diagnostics reference. A test fails on an option without an example or a release, and on an issue number in the page.A finding links its entry (#320). SARIF gives every rule a
helpUri, its entry in the diagnostics reference, and itshelpends by naming that entry, in text and in Markdown, so code scanning and an editor send a reader to why it happens and how to fix it. The MCP server’s findings carry the same address ashelp_uri, and the VS Code extension opens the rule’s own entry from Problems rather than the list of every rule.scenet.diagnostics.help_urigives the address for an id.puppet-file’s help names the published how-to instead of a path in the repository. The spec pack’sdiagnosticspart and the skill’sreferences/diagnostics.mdare the reference page itself, entry for entry, with its documents and their fixes, the compile notes included; a cross-reference to the Python API in any page the pack carries is printed as code instead of as raw MyST.A diagnostics reference (#320), as Rust’s error index is: an entry for each of the 37 rules
scenet checkreports and each of the 8 notes the compiler gives, atdocs/reference/diagnostics.md. An entry gives the id, its level, what it says, why it happens, how to fix it, the keys that can give it, the release it was first given in and the gallery examples that show it – then a document that gives it, whatscenet checkorscenet buildprints of that document, and the same document fixed. The page is generated byscripts/build_diagnostics.pyfrom the catalogue andtests/rule_corpus/, which gains a fixed twin for every document infixed/and a document for every compile note; the test suite holds each document to giving exactly its diagnostic and each twin to giving nothing. The compile notes are described in a new catalogue,scenet.diagnostics.COMPILE_NOTES, as the rules are. Every key card links the entry of each diagnostic it can give, compile notes included, and every entry links back to its keys. The gallery’s “Read about it” for the examples of “What Scenet tells you” opens the entry of the note they show. A{scenet-example}can show a fault on purpose with:gives: <id>: the build fails unless the document gives exactly that. “Since” is mined from the release tags intodocs/reference/diagnostics.since.toml.Every key of the language has a card (#319), as a cppreference entry does: all 128 keys a panel, a scene, an artwork contract or a puppet file can write. A card opens on the key’s meaning – the line an editor shows on hover – then a table of where it is written (in a document and in a comic script), its type, values, default, the release it appeared in, the findings it can give and the gallery examples that show it; then what it means, how it resolves against everything else and its limits; then a minimal document, compiled when the documentation is built by a new
{scenet-example}directive and shown with its picture and an “Open in the playground” link. The facts are generated from the published schemas byscripts/build_language_pages.py, between markers, and a test fails on a key without a card, a card for a key that does not exist, a stale table or an example that does not compile. “Since” is mined from the editor’s schemas at each release tag intodocs/reference/language/since.toml, values added later marked on their own (warm, 0.13). Every default an audit found unstated is now stated, the nine placement zones are listed, and the missing sections are written: the scene document (panels,over, the merge rules andnull), the staging mapping form,setting’s own keys, the camera’s retreat, puppet files and artwork contracts. An All keys, A to Z page lists every key, and a glossary says what the reference’s words mean. The gallery’s “Read about it” opens the card of the key an example shows, andunknown-keyandinvalid-fieldsend a reader to the index. The spec pack and the skill print each card’s example as YAML and each included file in full.The language reference is a page per block (#319).
docs/reference/language/holds an overview, the blocks, a complete example, conflicts and determinism, then a page each forpanel,camera,setting,cast,staging,script,description,lettering,direction,palette, andpageandpages. The old page keeps each heading it had, with a link to its new home, so a link written before the split still lands on what it named. The gallery’s “Read about it”, every page of the documentation, the spec pack’slanguagepart and the skill’sreferences/language.mdfollow the pages; a rule’s help names the published reference instead of a path in the repository.Every key a document can write says what it means on hover (#319). The editor’s four JSON Schemas – panel, scene, artwork contract and puppet – give each key a description of its own, one paragraph, where 4 of 77 had one: the meaning now sits under each field in the models, which the Python reference shows too. A definition’s description is its summary alone, and no description carries a Sphinx role, a docstring section, a doctest, an issue number or the repository’s own agent instructions. A test fails on a key without a description, and on any of those.
llms.txtand the spec pack’s schema part list all four schemas, and the line describing the command line namesscenet schema. The copies the site serves for one version link that version’s pages, pictures and schemas,/dev/or/vX.Y/; the committed copies link the root, as before.Every public name explains itself as a reference entry (#318). Each name in
scenet.__all__has a summary, an example that imports it fromscenetand shows its output, and See also; each function its parameters, what it returns, exactly which public errors it raises and when, and a note on its limits. A test over__all__holds each to it. Issue numbers are gone from every docstring, which says what the thing does instead.CompileResult’score,placementsandposedare described, so the reference lists them, as are 68 other fields no description reached, and a test fails on a field of an exported model left undescribed; a field described withField(description=...)is shown with it. FourteenReturns:sections no longer render their first words as a type, and a test keeps them so. An alias such asFaceMarkreadsFaceStroke | FaceDisc, without pydantic’s metadata.panel_core.mdhas a table of every Panel and Page Core field, made from the models. The library guide covers all seven renderers, books and pages,fonts=,embed=andmetrics=, building a panel in Python, the Core object model, and threads, caches and the files a compile reads. The editor’s JSON Schemas leave a docstring’s Python sections out of a description, which an author writing YAML has no use for.The Python reference has a page for every public name (#318). Each opens on a card – its import line, the module that defines it with a link to its source, what to install, the release it appeared in and how stable it is – then its signature and docstring. A function or main class has a page of its own; enumerations share one per group, and so do the errors.
scripts/build_api_pages.pywrites them, and the index’s overview, from__all__’s own groups, where the hand-kept table had left out 25 names;--checkand a test fail on a stale page. “Since” is mined from__all__at each release tag intodocs/reference/api/since.toml, with each parameter a function gained later markedversionadded; a test fails on a public name without one. The module pages now document the internals alone, marked as outside semantic versioning. A Guarantees page says what stays stable, what determinism covers, what threads may share and which caches they do, which files a compile reads, and how long it takes.FontMetrics, whichmetrics=andfonts=take, is importable fromscenet.The print PDF says what its colours are (#283). RGB pictures are tagged with the ICC’s sRGB profile, shipped in the package and written once per file; grey pictures and CMYK JPEGs keep their device space. An output intent names the printing condition the CMYK twins were made for,
CGATS21-2-CRPC6, by its registry identifier, without embedding its profile. Every page blends its transparency in CMYK, and the file says it is not trapped. No PDF/X conformance is claimed: no free tool can check it. A test holds every gallery PDF to the PDF/X-4 requirements the writer can meet, and the print how-to says what is missing and how a printer converts the file.Panels that bleed past the trim (#281). A page placement’s
bleed: trueruns its frame out to the bleed line on every side that reaches the page’s margin,bleed: [top, left]on those sides; no border is drawn there. The cast is staged in what the reader sees, out to the trim, and lettering keeps inside the frame as it was, so the trim cuts neither. Panel Core gainsopenandlettering, a Page Core framebleed, each only where something bleeds. Gallery example 73 writes every form of the key.A tinted palette prints in colour (#280). Every colour the compiler owns has a CMYK twin under CGATS21-2-CRPC6 (GRACoL 2013), converted from its sRGB colour through the condition’s ICC profile with littleCMS, relative colorimetric with black point compensation, and committed as
scenet.emit.cmyk;scripts/make_palette.pygenerates it and--checks it, with the profiles inscripts/profiles/and Pillow as a pinned dev dependency. The print PDF draws a tinted mass, veil, rain andwarmcaption in its twin, lettering staying 100% black over it.--monoandrender_pdf(..., mono=True)print the greys instead: the same file as the document’spalette: monotwin. A colour none of the palette’s prints its grey, with a note; the note that a tinted panel prints in its greys is gone. Greys follow the same condition: a grey prints on black alone at the K that prints its lightness there, read from black’s ramp measured through the profile, where K = 1 − L printed far too light (#707070went from K 45% to 69%), so every PDF’s greys move once. The tints and the ramp were checked against the profile, never on paper.The fog and cloud veil in print (#282). The print PDF drew no veil, and said so; it now carries the same noise the SVG’s
feTurbulencedraws, computed by the compiler from SVG 1.1’s reference algorithm and laid over the veil’s ink as a soft mask, where the SVG paints it, at 127 dpi. Where the reference code would divide by a zero gradient, the gradient stays zero, as Chromium keeps it.scenet.emit.turbulencecomputes it, in numpy, to the same bytes everywhere;print_notesno longer mentions the veil.Live text in the print PDF (#284).
scenet build --pdf --live-text,render_pdf(..., live_text=True)and the playground’s Print tab with live text on letter balloons and captions as text, so the words can be selected, searched and copied. Each face is embedded as a subset of the glyphs it draws, at its own glyph ids, and every glyph lands where its outline would, at the advance and kerning the solver measured. A face goes in only where its licence allows: the font’sOS/2fsTypeis read as the OpenType specification says, and a face that may not be embedded, or a CFF2 one, keeps its lettering in outlines, with a note. Sound effects stay outlines. Outlines remain the default, and no PDF changes unless asked.scenet.emit.pdf_fontscarries a face;FontMetricskeeps its bytes and gives a character’s glyph id.The README shows the gallery’s tour (#243), as
scenet builddraws it, and links the Gallery page. The picture is fetched from GitHub by its full address, so PyPI’s project page shows it too.Every section of the language reference shows its construct (#243): a picture of a gallery example, and a link to each example whose
doc:names the section, on the Gallery page. A test holds every section to it, or to a written reason for showing nothing, such as Determinism’s. The spec pack and the agent skill carry the same pictures and links.Gallery examples 71 and 72 (#243). 71 is the language reference’s complete example, a test keeping the two identical, so the reference can show what it compiles to. 72 shows one shore under each
horizon, which no example showed before. Example 69 now reads about its puppet in the language reference’s section on puppets of your own.A Gallery page in the documentation (#243), beside the tutorial: every example the playground offers, in its menu’s order and under its groups, each with its summary, its pictures, a link that opens it in that version’s playground, the page that explains it and its source. Each picture’s alternative text is what its SVG says to a screen reader.
scripts/build_spec.pywrites it from the manifest, and a test fails if it is stale.A picture of every gallery example, for the documentation (#243).
docs/images/gallery/holds each example drawn whole, asscenet buildwrites it: its pages, or else its strip, or else its one panel, with the picture it is lettered over written in.update_golden.pyrewrites them with the goldens and a test holds each to its digest, so none can drift from what the compiler draws. The home page and thepalettesection show theirs from there.How-to: Print a comic (#80): a page’s printed size and bleed, what prints in which ink, what print leaves out, and checking the plates with Ghostscript. The design decisions record why print is an emitter from Core rather than a converter, and the black-plate rule.
Print in the playground and the gallery (#80). The playground’s Print tab shows a document’s print PDF in the browser’s own viewer, with what print leaves out, and Download saves it. Gallery example 70 is a US comic page made for print, with its bleed.
scenet build --pdf(#80) writes the document as one print PDF beside its SVGs, a PDF page per page or per panel, with what print leaves out said in notes.-ostill names the SVG; a.pdfthere is refused.A page prints at a size, with a bleed (#80). A page unit prints as a tenth of a millimetre, so the default page is 200 × 300 mm and a US comic is
size: [1682.75, 2603.5].page: {bleed: 31.75}runs the printed sheet 0.125 in past the trim on every side; nothing on the page moves, and a page without it is what it was. A panel can bleed into it since #281.A print PDF, from Python (#80):
render_pdfdraws a document as a PDF a printer takes. Lettering, balloon borders and every line are 100% black and overprint, so type stays sharp when the colour plates drift; the paper knocks out; greys are black tints; the night foreground prints rich black; a tinted palette prints its colours’ CMYK twins (#280). A page unit prints as 0.1 mm. The file is byte-identical from run to run, with no date in it. Supplied pictures go in with their pixels unchanged: a JPEG and most PNGs as the file’s own data, the rest decoded and stored uncompressed, alpha as a soft mask.print_notessays what print leaves out or changes, and names a picture that prints below 300 dpi.A puppet of your own, from a document (#242). A cast member names a
*.puppet.yamlfile by its path, relative to the document, as it names a font or a picture:reference: puppets/pip.puppet.yaml. Soscenet checkandscenet buildread it beside the document,--watchrebuilds when it changes, the playground has Puppet… beside Font… and Image…, and the MCP server takes it infiles, wherelist_puppetsnow describes it too. A reference that does not end in.puppet.yamlis a shipped puppet’s name, as before, and Panel Core records the reference as written, for the camera as for the actor. A file that is absolute, missing or not a puppet is the new rulepuppet-file: in the puppet file, at the key that is wrong, when the document is checked as a file, and on the line naming it otherwise.scenet checkandscenet buildrefuse a puppet file given as a document.scenet schema --puppet, the JSON Schema for a puppet file, so an editor completes and checks a*.puppet.yamlas it does a panel. It is the model’s own, plus every landmark required,head_topzero and astanding_neutralpose. The VS Code extension ships it for every*.puppet.yaml, the site publishes it besideartwork.schema.json, and a test fails if the site leaves off a schema the extension ships.Pip, the gallery’s own puppet (#242). A child five heads tall, where alice and bob are both seven and a half, with a knot of hair, cast beside alice in example 69 in every pose and expression it has. The coverage test holds a puppet the gallery ships to that as it holds the shipped ones, and the spec pack prints it after its example.
The gallery writes the comic-script format in full (#241). Six scripts, 63 to 68, each in a convention writers use: one kept in Markdown, a manga read right to left over two pages, two French planches that walk the shot ladder in abbreviations and in full, one written like a screenplay, and a letterer’s script after Blambot’s. Between them they write every word a cue, a caption or a sound may carry in parentheses, every French shot and angle, every keyword a heading or a label opens with, every directive, and the forms of line no table holds, from a heading in Markdown to a panel before the first PAGE. A new test reads them as the script frontend reads them, from its own tables and patterns, so a word or a keyword the frontend gains fails it until an example writes it. Write a panel as a comic script links each convention to its example in the playground.
A Try it link over a gallery example’s try-this. The playground puts it over the
# Try this:comment, and it uncomments the line under it,#and all, as one edit Ctrl+Z takes back. Deleting only the#by hand left a space too many, and a comic script, whose try-this ends its front matter, has no comment for Ctrl+/ to toggle.The gallery shows what the checker and the compiler tell you (#240). A new group, What Scenet tells you, has an example for every note:
word-limit,panel-count,looks-like-dialogueanddropped-relationfromscenet check, and from the compiler a camera that retreats, a tail that bends around a face, a mouth a picture’s fit crops away, marks cut off by the frame, an inset over a face, a slant through a face, and a regular face standing in for the italic and bold italic ones a document did not name (examples 53 to 62, and 10). Each says what to change to make its note go away, and ends with a commented line that, uncommented, is an error located on that line. The manifest declares the notes each example gives undernotes:, and the tests hold every example to exactly those: eight older examples gavecamera-retreatedwithout anybody checking, and now say so.Every compile note has a name.
CompileResult.compile_notesgives each note with what kind it is —camera-retreated,curved-tail,cropped-mouth,cropped-marks,inset-covers-face,slant-cuts-face,italic-stand-inorbold-italic-stand-in— as aCompileNote, exported besideCompileResult.notesstill gives the sentences, word for word: match on the name, which stays when a sentence is reworded.The playground lists what
scenet checknotes, each under its rule and a click away from its line, as an error is, then what the compiler noted, under its name. A check’s note was a squiggle in the editor and nothing more.The gallery writes every construct of the language, and a test reads it against the schemas (#239). Eleven examples, 42 to 52: a font of your own (Comic Neue, in
examples/gallery/fonts/with its licence), a sound pulled toward a zone from its source, the five zones between the corners, a description, staging spelled out as subject, predicate and object, a mass in front of the cast, a document of two pages with an inset read after its panel, leaving somebody out withnull, a look at a voice from off panel, puppets that become a picture’s figures, and a JPEG.scripts/make_gallery_photo.pypaints the JPEG and encodes it itself. The coverage test now walks each document beside the published panel and scene schemas, so a word in a comment no longer passes it: every property, enum value, form and signed number they offer must be written, as must the removals the docs teach, every pose and expression of every puppet, a second page, and both picture formats.The playground’s gallery is a guided tour (#237). It opens on a new example,
38-tour.scene.yaml: one page lettered over both gallery pictures in colour, with posed puppets, figures a picture draws, a locale caption, a thought, emanata, a sound effect and an inset. The menu groups the examples by theme, Previous and Next walk them in that order, and under the editor each says in a sentence what it shows, with a link to the page of the documentation that explains it.#example=<file>opens a gallery example by name, a link that does not go stale as a#src=share link does when the example changes.The playground shows every output (#238). Depth, Mask, Pose, Boxes and Semantics tabs show the exports for image models of every panel of any document, side by side under each panel’s name, made only while one of them is open. A Screen reader tab lists what a screen reader is given: every image and group the SVG names, nested, with its words. A Files tab shows the files beside the document: the gallery’s pictures and artwork contracts, and the fonts and pictures you add. An Output menu letters with live text, as
--live-textdoes, and shows a document of several panels as its pages, a strip, or each panel on its own. A document of several panels downloads its exports as one ZIP, each file named asscenet build --conditioningnames it.scenet.emit.previewdraws the pose and the boxes to be looked at: each actor’s skeleton in OpenPose’s colours, and each box labelled with its phrase in its region’s colour in the mask.scenet.emit.export.conditioning_archiveputs every panel’s exports in one ZIP, the same bytes on every run and every platform.The gallery manifest gains
groups:,start:, andgroup:,summary:anddoc:on every entry, and its titles are short names. Entries are only ever appended, as its header now says: a playground draft remembers its example by position. The spec pack prints each example’s summary under its title.scenet build --watch(#78) rebuilds when the source or compilation dependencies change, with debounced saves and recovery after failed builds. The optionalwatchextra installs the file-watching dependency.The tinted ladder (#244), the first step of the colour policy: the value ladder in colour, each value with the OKLab lightness of the grey on its rung, so that a panel drawn in it is, in monochrome, the panel drawn in greys. Each hour has a shadow hue at the foreground and an atmosphere hue at the sky, and the rungs move between them.
TINTEDinscenet.solve.backdropis generated from those two ends byscripts/make_palette.py, andscripts/setting_sheet.py --palette tinteddraws every place and weather in it.palette: mono | tinted(#244), what a panel is drawn in.tinteddraws every value on the ladder (the masses of a setting, the veil and the rain) in its twin colour.mono, the default, is what every panel already was. It is written whereletteringis: at the top of a panel, besidepanels:for every panel, on one panel for that panel alone, or in a comic script’s front matter or as@palette:. A panel may have its own, for a flashback in grey on a page in colour. Panel Core keeps every grey where it was and addscolourbeside it (fall_colourfor rain), withpaletteat the top, all left out inmono: no existing Core, SVG or export changes. Every decision is still made on the grey, so a tinted Core with its colours taken out is the mono one. The pose, boxes, depth and mask exports are the same in every palette, and the semantics names the palette when it is notmono.Paletteis exported, andcolour_forgives a grey’s twin.scenet build --mono(#244) draws a tinted document as a black-and-white edition, without editing it: every value as its grey, and every panel, page and strip byte-identical to what the same document writes withpalette: mono.render,render_page,render_pagesandrender_striptakemono=True, MCPrendertakesmono, andPanelCore.as_mono()gives the panel with its colours taken back out, which is the mono Core.tone: warm(#244), the yellowlocalecaption that #28 left out for want of a colour policy. Its value is thedayrow’s atmosphere rung,#eeeeee, taken by index aspaleandinkare, and it is lettered in ink. Underpalette: tintedits box is drawn in that grey’s twin, the pale yellow#fef0a1, which the ink reads on at 16:1. Inmonoit is the grey, which is what a black-and-white reprint does to a yellow caption. Panel Core records the yellow as the caption’scolour, besidefill, and leaves it out inmono.paper,paleandinkstay neutral in every palette.Colour in the gallery and the reference (#244). Two gallery examples, Every hour in colour and A flashback in grey, join A yellow caption. The language reference has a
palettesection with both pages as pictures, andwarmin thetonetable. Panel Core’s reference documents the colour keys, and the design decisions record why colour is a twin of value.
Changed#
CI measures coverage on Python 3.14 only. The 90% branch-coverage gate stays on the Linux 3.14 job; the 3.12, 3.13 and Windows jobs run every test, doctest and documentation example with
--no-cov. Before 3.14, coverage cannot usesys.monitoringfor branches, and its tracer made the required 3.12 job the one every pull request waited for. A test holds the workflow to it.The fix for
puppet-filenamesscenet schema --puppet(#271), as the fix forartwork-contractnames--artwork, and the asset-contract reference names the schema beside the puppet it shows. A test runs everyscenet schemacommand a fix names, so a fix cannot point at a schema the command does not print.scenet build --watchkeeps one file watcher open (#266), where it opened and closed one about ten times a second, and watches each folder without its subfolders: a document at the root of a project no longer has its.venvornode_moduleswatched. The watcher moves only when a rebuild reads other files, or a missing folder appears. A file is read and hashed again only once its size or modification time moves, so fonts and pictures are no longer reread on every poll, with or withoutwatchfiles; touching a file still rebuilds nothing. A file written less than two seconds before a poll is hashed again at the next one, so a save that keeps both its size and its timestamp (FAT, some network shares) is still seen.A note in the playground is styled as information, neutral and marked ℹ, not as an orange warning: nothing is wrong when the compiler says what it decided.
The gallery’s CI job drops the notes the manifest declares before code scanning (
scripts/check_gallery.py), so the examples that give a note on purpose open no alert. An error, or a note nobody declared, is still uploaded and still fails the job.lightnessandcontrast_ratiorefuse a colour (#244) with aValueError, rather than answer for it with a formula that is exact only for a neutral grey. Every decision the compiler makes from a value is made on the grey.A ground, floor or stretch of water recedes in the depth export (#227), instead of standing as one flat grey that a depth model reads as a wall. Each is a straight vertical ramp from its own step at the horizon to the farthest figure’s step at the bottom edge, white when every figure is; a ceiling is the same ramp running up to the top edge. A flat surface’s inverse depth is linear in screen height, so the straight ramp is the shape perspective gives. The ramp is never darker than its plane’s step, so the painter’s order holds, and never paler than a figure standing on it. A ground in the foreground plane stays flat, and so does every other kind. Each ramped region’s paint names its step as the fallback. A hand-edited Core with no horizon has each surface recede from its own far edge.
Fixed#
A YAML document’s
PanelSyntaxErrorcarries its rule and place (#322). A fault validation found reached a caller withrule=Noneandloc=(), only the message saying what and where, though a comic script’s error already carried both. Nowruleandlocare those of the first fault, asscenet checkorders them; a fault in a panel of a scene keeps its rule, and itslocstarts atpanelsand the panel’s name, as every other fault in a scene’s does.Build and check a comic in CI installs the current release. Its workflow pinned
scenet==0.10.0; it pins 0.12.0, and a test holds the pin, and the release the page says it was checked with, to the version inpyproject.toml.The language reference states what the compiler does (#319).
panel.sizewas called required; it is[1000, 1000]when left out. The caption key table left out thewarmtone. The shot-type reference said a panel may raise its footroom, which no key does: each shot sets its own. “Five authored layers” left outlettering,palette,directionanddescription, which the opening table now lists. The spec pack and the skill said two figures need a left-to-right order; the compiler orders them byat:, then by actor id, and the reference now says so and recommends stating the order withleft_of. Issue numbers are gone from the page, and a test keeps them out.The Python API reference renders (#316). Every version of the site since v0.8 showed it as raw reStructuredText:
.. py:class::as text,sphinx_autodoc_typehintsnoise, and doctests run together into one paragraph. Its pages called autodoc from MyST fences, which read autodoc’s output as Markdown, soobjects.invheld no Python object, none of the guides’{func}links went anywhere, and no page linked its source. Autodoc now runs in{eval-rst}fences, and docstrings are reStructuredText throughout: their nine Markdown tables are grid tables, and their Markdown headings, links and indented examples are rST. The documentation build now fails on a reference that reaches nothing (nitpicky), on raw markup on any built page, and on a name inscenet.__all__thatobjects.invlacks. Each field is documented once:undoc-members: False, which Sphinx reads as on, is gone. Enum members stay;__new__on everyStrEnumand pydantic’s validators go.Side,TypeSize,CoreImageandCoreModeljoin their modules’__all__, and the ten modules no page documented are on the reference.Every example works pasted into a fresh file, and every document shown compiles (#317). Docstring examples ran in their module’s globals, so 37 called what they document without importing it; each now runs with builtins only, and imports what it uses. Each Python block of a page runs in a namespace of its own, where two leaned on the block before. A public name is imported from
scenet, which 19 docstrings imported from the module defining it. Everyyamland comic-script block in the documentation and the README is compiled as the document it shows: the README’s comic script, and the how-to’s first one, which named a cast they never declared, now carry their front matter, and the language reference’s short examples are complete panels. A block that is only a part of a document says so in a caption,Part of story.scene.yaml, and comic scripts are fenced asscenet-script. A test fails on each of the four mistakes;CONTRIBUTING.mdand the testing guide state the rule.except ScenetErrorcatches every error a public call raises (#318), asscenet.errorspromised and 34 plain built-in raises denied. Each keeps the built-in it was, so anexceptwritten for that still works. New, all importable fromscenet:RenderError, aValueError: a renderer was not handed a font the Core was lettered in, a picture’s bytes, or a panel a page places; was handed nothing to draw, or panels read two ways; or a picture print cannot carry.UnknownActorError, aKeyError:PanelCore.actorandPanelCore.speaker, for a name the panel does not hold.FileReadError, anOSErrorwith the system’serrno,strerrorandfilename, andMissingFileError, also aFileNotFoundError: every function that takes a path, for a file it cannot read.MalformedAssetError, anAssetErrorand aValueError:load_puppetfor a file that is not a well-formed puppet, which was pydantic’sValidationError;PuppetLibrary.from_directoryfor a name declared twice; a font file that cannot be measured.CoreSyntaxError, aSourceError:PanelCore.from_jsonandPageCore.from_json, which raisedjson.JSONDecodeErrororValidationError.
compile_book_fileandcompile_documentraiseSourceErrorfor an extension no frontend reads, and a document that is not UTF-8 is aPanelSyntaxErrorunder rulesyntax, where it was aUnicodeDecodeError.UnknownPoseErrorandUnknownExpressionError, whichPuppetSpecalready raised, are importable fromscenettoo. Anexcept pydantic.ValidationErroraroundload_puppet, orexcept json.JSONDecodeErroraroundfrom_json, no longer catches;except ValueErrordoes. Building a model yourself, such asPanelIR(...), still raises pydantic’sValidationError, asscenet.errorsnow says. A test fails on any plain built-in raised where a caller could see it.A right-to-left document without pages prints right to left (#296). Its print PDF, one page per panel, did not say
/Direction /R2L, which only pages read right to left wrote, so a reader laid it out left to right.The playground’s print PDF is the one
scenet build --pdfwrites (#294). It carried the picture of a panel no page places, which nothing draws, and refused the whole document when that picture was one print cannot carry, such as a lossless JPEG.render_pdfnow takes only the pictures of the panels it prints.scripts/build_site.pybuilds on Windows. It read the releasesghlists in the system’s code page rather than in UTF-8, so a curly quote in a release’s notes stopped the build before it downloaded anything.The spec pack’s pictures are on the site. The language reference shows two pictures for
palette, and the spec pack and the agent skill, which carry the reference with every link made absolute, linked them atimages/palette/on the site, where nothing was: Sphinx serves a page’s pictures from_images/. Each version of the site now servesdocs/images/atimages/.Add your own character is rewritten around a puppet file a document casts (#242). It said puppets have no expressions, though both shipped ones have ten, and its sample puppet named joints it never declared. It now shows the gallery’s pip in full, as the file it is, says how to cast one from a document, the command line, the playground, MCP and Python, and lists every fault validation catches.
A fault in a puppet is said at the key that is wrong. The checks of a whole puppet — a landmark out of order, a joint naming a parent that does not exist — reported it at the top of the file; each now names its key, worded as before.
A puppet must declare
standing_neutral, the pose a cast member gets when it names none. Without it every such member wasunknown-pose, each on its own line, and nothing said the puppet was what was wrong; now it is one finding, at the puppet’sposes.scenet checkreads the shipped puppets once per document, as its reference always said, rather than once for every panel it checks.A numbered line from somebody nobody draws is a line. In a comic script,
1. PHONE (OP): Ring.was read as prose, without a word, thoughPHONE (OP): Ring.is a line: a lettering item’s number was set aside only before a cast member’s cue. Somebody heard from off panel or in voice over need not be cast, numbered or not.A line indented to match no line above it is said to be (#261). PyYAML calls it “expected
”, which says nothing of the space too many or too few behind it; the message now says how far in the line is, and how far in the line it likely goes with is: deleting the #of a gallery example’s try-this line and leaving its space, say.A syntax error in a comic script’s front matter is located (#261): rule
syntax, on its line of the file, where it was ruleinvalid-fieldon line 1, with line numbers counted from the front matter’s first line.The how-to on debugging a layout named two of the compiler’s notes; there are eight, now each in a table with what to do about it.
The scene schema accepts a
nullwhereversettleapplies one (#239):camera: nullon a panel of figures over one with a camera, as the docs teach, was underlined in an editor and compiled. Any key a scene reaches through mappings may now benull; a list entry is still whole. The panel schema is unchanged.A member left out with
nullkeeps the look at them while heard from off panel (#258).cast: {carol: null}dropped the panel’s ownbob looking_at carol, with adropped-relationnote, even while Carol spokeoff_panelthere, and heroff_panel: trueended on the side nearer her balloon. As with a comic script’sCAROL (OP), Bob now turns toward her side and her line ends on the side she was written to stand on; every other relation that names her still goes. In a script,@cast: {CAROL: null}besideCAROL (OP)is no longer refused as drawing her.The contributor documents say what CI does (#324).
CONTRIBUTING.mdlists every gate CI runs,basedpyrightand the documentation build included, installs every dependency group, says what to regenerate when the output moves, and asks for the commit titles the history actually has rather than Conventional Commits; it and the maintainer guide link each other. Both, withCLAUDE.mdand the design decisions, say to quote forward references, since the 3.12 floor needs it: two of them said the opposite. The design decisions callbasedpyrightblocking, asci.ymlhas made it, and gain the section on the floor the install guide links. The maintainer guide has a row for every check a pull request runs.SECURITY.mdsays alpha, names the release that gets fixes, and covers what Scenet really reads and serves:scenet mcpover HTTP, fonts, pictures, artwork contracts, puppet files and paths that climb out with... The pull request template asks for a CHANGELOG line and lists every generator; the bug report takes a scene, a comic script and the files a document names. Every kind in this file is one heading per release, and tests hold all of it to the repository.
0.12.0 - 2026-10-29#
Upgrading from 0.11.1.
A font path written with
\between folders is refused, on Windows as everywhere else: write/. So is one holding a control character, which used to crashbuildandcheck.conflicting-settingcovers a picture too: animagebeside aplace,massesor ahorizon. Its SARIF description and help say so; a place beside masses is reported exactly as before. A panel that inherits a place and names an image is refused the same way; it writesplace: nullbeside the image.A comic script’s prose is now read, as its panel’s description. A line of it holding a control character an SVG cannot hold, which used to pass unnoticed, is reported at that line as
invalid-field.descriptionin a script’s front matter is refused.Every Panel Core gains
description, and each balloon, caption and sound effect alabel. Nothing else in it moves, andformat_versionstays 1: a Core without them is still valid and writes back byte for byte, but golden Core files of your own will need regenerating once. 0.11 refuses the new keys.Every Panel Core gains
camera; each actorjoints,featuresand, when it looks at somebody,looking_at; a backdrop of massestimeand, for a named place,place(#72). Nothing else in it moves, no SVG changes, andformat_versionstays 1: a Core without them is still valid and writes back byte for byte, but golden Core files of your own will need regenerating once. Every gallery Core was compared with its 0.11.1 golden and differs by these keys alone. A panel whose cast a picture draws has nocamera, and 0.11 refuses the new keys.A balloon over its own speaker’s body costs what it always should have when the actor id is not the puppet’s name (
ALICE: {reference: alice},carol: {reference: alice}). Such a speaker was charged as a bystander, so balloons drifted away from them. Three gallery panels letter differently, each balloon now beside its speaker: regenerate golden Cores of your own that cast an actor under another name.CaptionEvent.preferisNonewhen it was not written, where it used to readtop_left: an unwritten zone is where reading starts, which the solver decides fromdirection. A caption is placed exactly where it was. Code reading it from the Python API takesNoneastop_leftfor a left-to-right panel.CastMember.referencemay beNone, for a member that is a figure a picture draws, andCompileResult.cameraisNonefor a panel whose cast is all figures. Code reading either from the Python API narrows them first;PanelIR.puppets()gives every puppet’s reference. A member that names neither a puppet nor a figure is reported exactly as before.Every SVG’s bytes change once, to carry what a screen reader reads: a
roleand a<title>per panel, andaria-hiddenon a page’s own shapes. Nothing is drawn differently and lettering stays outlines.--no-aria(aria=False) gives back exactly the SVG written before, for a pipeline that post-processes it; debug overlays are unchanged.
Added#
Export a panel’s staging for image models (#72):
scenet build --conditioningwrites five files beside each panel’s SVG — the pose as OpenPose COCO-18 JSON, a phrase and a box per figure as GLIGEN takes them, a depth map (stepped grey planes in painter’s order, white near), an instance mask under the panel’s own ids, where a character keeps its colour across panels unless another in the same panel has the same hue, and the semantics: camera, setting, cast with each character’s mask colour, and lettering, as structure and never as a prompt. No model runs in Scenet: each is one more emitter reading Panel Core, text, JSON or SVG, byte-identical like the rest, and nothing is rasterised. The pose names left and right as OpenPose does, by the subject’s side; a point outside the panel, an ear, or a joint a puppet does not name is0, 0, 0. Figures a picture draws have boxes and masks and no pose; a picture is the far plane; a panel read right to left exports the same pose, boxes, depth and mask.render_conditioningandConditioningjoinscenet.__all__; MCPrendertakesconditioning(still five tools); the playground offers the five downloads for a one-panel document. See the how-to, “Export a panel’s staging for image models”.direction: ltr | rtl, which way a comic is read (#68):rtlfor manga, read from the top right. It is the comic’s progression, not its text’s, and EPUB’s word for it. Written once for the whole document — at the top of a panel, besidepanels:, or in a comic script’s front matter — and inherited by every panel; a panel’s own, and a script’s@direction:, are the new rulepanel-direction. The editor’s schema offers it. Panel Core and Page Core record it when it isrtl; a left-to-right Core is byte-identical andformat_versionstays 1.A panel read right to left is lettered from the top right. A balloon or caption may never sit above and right of one before it; a caption with no
prefer, and a voice from off panel with no side named, start top right; every tiebreak between equal placements is mirrored, so the mirror image of a panel is lettered as the exact mirror of the original; and a generated description names the cast from the right. Nothing in the picture moves: figures, gaze, tails and sound effects are byte-identical, andprefer:,at:and named sides keep meaning places on the panel. The debug overlay says “read right to left”.Pages and strips read right to left. Under
direction: rtla tier’s first panel, or first column, is at its right; each frame is the one the tier reversed would have, so every panel keeps its size and its art, an inset keeps its corner and a slant leans as written. The pages of a document side by side (render_pages, the playground) and a strip start at the right, and every one is still written in reading order. A strip or a row of pages read two ways is refused.Two gallery pages, the same manga page read right to left and left to right.
setting: {image: ..., fit: cover | contain}: a picture drawn elsewhere, behind the cast (#70). It is a backdrop of its own, so it is written instead of aplaceormasses, never beside them or beside ahorizon(conflicting-setting); afitwith no image isinvalid-field. A panel that inherits a place writesplace: nullbeside its image, and the editor’s schema now accepts thatnull.The picture is read from its PNG or JPEG header, beside the document as a font is, and only its size is taken.
scenet checkreports a picture that is absolute, missing, not a PNG or JPEG, or turned by its EXIF orientation as the new ruleimage-file, without the solver. Text compiled with no folder may be handed the files it names instead:basetakes a mapping from the path the document writes to the file’s bytes, for fonts as for pictures.The picture is placed, and Panel Core records it. Centred, filling the panel (
cover) or shown whole inside it (contain), never stretched.backdrop.imageholds the path as written, the media type, a digest of the bytes, the pixel size, the fit in SVG’s words and the rectangle it is drawn in; over a picturebackdrop.horizonis left out. A Core of masses is byte-identical, andformat_versionstays 1. The picture costs a balloon nothing and does not move the camera, and a generated description names no place and no hour over it — only the weather drawn on top.The picture is drawn, as an
<image>on the paper, under every figure and the weather, in the rectangle Panel Core placed it in. It is linked byxlink:href— Inkscape does not load plainhref— to the path exactly as written, which resolves when the SVG is beside the document;scenet build --embed-images(embed=on every renderer) writes its bytes in as adata:URI instead, andbuildsays so in a note when a link will not resolve. The debug overlay shows where it was placed. A new how-to, Letter over your own art, and a gallery example drawn over a picture the repository paints itself, under its own licence.The MCP server’s
validate,compileandrendertakefiles: the files a document names, by the path it writes, as base64. They stand in for the document’s folder, read in memory, so a model can letter over a picture — or in a font — it sends;renderembeds the picture. Still five tools.The playground’s Image… button adds a
.pngor.jpgto the document’sart/folder, for as long as the tab is open, and the preview and every download embed it. The VS Code preview embeds pictures too, since it is not drawn beside the document.An artwork contract declares the figures a supplied picture draws (#71): beside
art/p01.png,art/p01.art.yamlgives each figure’sface(a disc lettering may not cover),mouth(where a tail ends) andbody, andkeep_outregions lettering should stay off, all in the picture’s own pixels, with thesizethey were measured on.scenet schema --artworkemits its JSON Schema, which the VS Code extension associates with*.art.yamland the documentation site publishes beside the others. Panel Core records what a contract declares, mapped into the panel through the picture’s fit:figures, besideactors, and the picture’skeep_out. Both are left out when empty, so every Core reads and writes as before andformat_versionstays 1; the debug overlay draws each figure’s face, mouth and body, and each keep-out.Figures a picture draws, in the cast (#71):
cast: {ana: {figure: ana}}in place ofreference:. The panel’s picture’s artwork contract says where each face, mouth and body is, and lettering is placed by the same rules as around a puppet: never over a declared face — anybody’s in the picture, cast or not — tails aimed at the mouth, bodies and keep-out regions a cost. The camera and staging do not run. A cast figure a panel’s picture does not draw is not in that panel. Four new rules, each from the cheap pass:unknown-figure,artwork-contract(reported in the contract when the document is checked as a file),conflicting-cast(a puppet and a figure at once, a puppet’s key on a figure, a mixed cast, one figure played twice) andfigure-staging(staging naming a figure, a camera over figures). Acovercrop that cuts a speaking figure’s mouth out of the panel ends its tail on the frame, with a note.scenet checkandbuildrefuse a*.art.yamlgiven as a document. The panel and scene schemas acceptfigure.A gallery example of figures a picture draws,
35-figures.scene.yaml: a station platform painted byscripts/make_gallery_figures.py, with its artwork contract written from the same constants, lettered undercoverandcontain. Two of its three people are cast, the third is kept clear of all the same, and its timetable board is a keep-out.Contracts travel with their picture. The playground’s Image… button adds a picture’s
.art.yamlbeside it, cleaned to the same name so the two pair; the MCP server takes it infiles, its instructions andget_spec’s characters part say so, and the spec pack prints the gallery’s contract. Still five tools. A how-to, Letter the people in your own art.A panel’s
description: what it shows, in words, for a reader who cannot see it. Written asdescription:in YAML; in a comic script, the panel’s prose is it — its lines one paragraph, Markdown’s markers taken off — unless an@description:directive, kept exactly as written, says something else. It is carried and never interpreted, for accessible output to read (#76). It describes one panel, so it is never inherited: besidepanels:or in a script’s front matter it is refused asunknown-key, and a panel drawnover:another does not take its parent’s.Panel Core carries the words a panel is read in, built in the pipeline so the emitter copies them.
descriptionis the panel’s own, or generated from what it holds —Medium shot. A street at night, in the rain. Alice, left, pointing, angry, looking at Bob; Bob, right, arms crossed, sweating.— and every balloon, caption and sound effect has alabel: who says it, how, and the words,Bob, whispering: I know.Read inorder, they are the panel’s text as its reader takes it. Generated text is templated English.A screen reader can read the panel (#76). Each panel is one image,
role="img", named by one<title>: the description, then every balloon, caption and sound effect in reading order — in the name, since a description alone is often not spoken, and nowhere else, since NVDA read a<desc>a second time. It needs no id, so panels inlined together in one page cannot name each other. A strip or a page is a namedrole="group"of its panels, in reading order.scenet build --no-aria,aria=Falseon every renderer andaria: falseon the MCP server’srenderleave it all out. Checked with NVDA 2026.2 and Edge 155, and against Edge’s UI Automation tree; results, and how to check with VoiceOver, are in the new how-to, Make a panel a screen reader can read.
Changed#
A page’s SVG writes its panels in reading order, insets included, since document order is what a screen reader follows. An inset used to be painted after every other panel to stay on top; now its parent is cut around the inset’s ring instead, so an inset
read: beforeits parent comes first and is still on top. The page looks the same, to within anti-aliasing along the rings; only a page with insets changes, and only its bytes.The strip and the page place a panel’s body, built for them, instead of cutting it out of the panel’s serialised SVG, which made the panel’s first two lines something they silently depended on. Byte for byte the same.
Fixed#
A backdrop of more than ten masses is drawn back to front. Mass ids are numbered back to front, and the painter’s sort compared them as text, so
m10was drawn beforem2: ten walls and a window in one plane painted the window, one rung paler, out under the walls. Masses in one plane are now drawn in the order Panel Core lists them. No gallery panel has more than ten, and none changes.A speaker is forgiven a balloon over their own body whatever the actor is called. The placer half-weights the speaker’s silhouette, and looked the speaker up by the puppet’s name while the silhouettes are keyed by actor id. An actor called anything but its puppet, which every comic script’s capitals are, was charged as a bystander: in the gallery’s comic script a line moved to the far corner of the panel behind a tail bent outside it.
A font path with a backslash is refused on every system, as
font-file. Windows readfonts\Comic.ttfas a folder and a file, and every other system as one file name, so the same document lettered in its font on one machine and was refused on the next. Write/between folders.A control character in a font path is a finding, not a crash.
lettering: {font: "fonts/a\0.ttf"}reached the file system, whoseValueErrorwas not one the compiler reports, soscenet buildandscenet checkboth ended in a traceback. Any control character in a declared path is nowfont-file, naming the character.Mutation testing runs again.
mutation.ymlinstalled only themutationgroup, and the documentation site’s tests needdocs, so mutmut’s clean run failed and no mutant was tried. It now installs every group, as CI’s test jobs do.The VS Code preview draws each figure with its own clip. It inlines every SVG a build wrote into one page, and a page has one set of ids, so a second panel in a slanted tier was clipped by the first one’s outline, and page 2’s panels by page 1’s frames. Each figure’s ids, and every reference to one, now carry a prefix of their own.
0.11.1 - 2026-10-18#
The documentation site documents the release you install, and shows off its playground;
and two comic-script fixes. The site’s root now serves the latest release, main moves under
/dev/, and each minor version keeps its own path; the playground says which version it runs,
and the home page shows its example compiled, with a button to open it there. A full stop
now ends a PAGE heading, and no line of a comic script can stall the compiler.
Upgrading from 0.11.0. The language, the command line and the Python API are unchanged,
and so is every YAML document’s output. A comic script changes only where a PAGE heading
ends in a full stop, as in PAGE 7. or PAGE TWENTY ONE.: see Fixed.
Added#
The documentation site documents what you install. Its root, and every address already in use there — the documentation, the playground,
schemas/panel.schema.json,scenet-spec.md,llms.txt— now serves the latest release, not unreleasedmain.mainmoves to/dev/, and each minor version from 0.8 stays online under its own path, such as/v0.10/, its playground running that release’s compiler. A version switcher in the navbar keeps the page you are on./dev/and older versions carry a banner linking to the same page in the latest. Pin a schema or the spec pack to a release by putting its version in the path:…/scenet/v0.11/schemas/panel.schema.json(#171).Each release attaches its built site as
scenet-X.Y.Z-site.zip, built from the wheel it publishes, before PyPI. The site serves every version from these, unchanged. Releases 0.8.0 to 0.11.0 have theirs backfilled.The playground says which version it runs, with the same version switcher as the documentation, keeping a shared document across the switch. On
main’s and on an old release’s it says so, with a link to the latest. Playgrounds built before this change, those of 0.11.0 and earlier, carry no switcher.The documentation’s home page shows its example compiled — the file
scenet buildwrites for it, kept current with the golden files — and a button opens that example in the playground. The navbar names the playground beside the sections, and every link to it opens the playground of the version being read.Dependencies and code are watched by GitHub’s own security tooling. Dependabot alerts and security updates cover the dependency graph, which GitHub builds from
uv.lockand bothpackage-lock.jsonfiles, transitive dependencies included. A pull request adding a dependency with a high or critical vulnerability fails dependency review. CodeQL analyses the Python, the TypeScript and the workflows on every pull request, onmainand weekly. Secret scanning rejects a push that contains a credential. SeeSECURITY.md.
Changed#
Every pull request checks the package as a release would. CI’s new Package job builds the sdist and the wheel, runs
twine check --stricton them, smoke-tests the wheel from an empty directory, and builds the wheel again from the sdist alone, comparing the two. The smoke test is now one script,scripts/smoke_wheel.py, that the release runs too. Nothing is published: TestPyPI stays a manual rehearsal.
Fixed#
A full stop ends a PAGE heading, as it ends a PANEL one.
Page 4B.named its page4B.andPAGE 7.a page called7.;PAGE TWENTY ONE.andPLANCHE 3.were not read as headings at all, sinceONE.and3.are not numbers, so their panels ran on into the page before. They are pages4B,7,21and3now. A full stop inside a label, as inPAGE 3.5, stays.
Security#
A comic script cannot stall the compiler with one crafted line. The PAGE heading pattern backtracked exponentially on a line like
PAGE !-!-!-…(: fifty characters took seconds, and each two more took four times as long. Found by CodeQL, which led to the rest: the PAGE, SFX, caption and cue-with-its-line patterns each let two parts take the same run of space, so a long gap was quadratic or cubic – a caption line of sixty thousand tabs took twenty seconds, an SFX line with a note three minutes. Every line is now read in time linear in its length, soscenet build,scenet check(which the editor runs on open and save), the MCP server and the playground cannot be hung by a script. The patterns read every script as before, with one exception at the edge: inPAGE A - .the full stop now ends the heading, as it already did inPAGE A ., rather than ending the label.The playground’s DOMPurify is 3.4.17, past two advisories affecting versions up to 3.4.15 (GHSA-6688-9rhm-gjv2, GHSA-p98j-92pf-mc4p). It reaches the playground through monaco-editor, which pins an older version, so the override that lifts it is raised by hand: Dependabot’s security update cannot do it.
0.11.0 - 2026-10-17#
Lettering, sound effects, and comic scripts as publishers write them. A stressed word is
lettered in bold italic, every pair is kerned, the type size can be set, and an author can
letter in their own face. Sound effects are lettered into the picture in a display face. A comic
script may be written as Dark Horse publishes its format, or in French, with captions that carry
speech, voices from off panel, small type, and its PAGE headings laid out as pages; scenet check gains notes, the first of them a publisher’s word limits.
Upgrading from 0.10.
Every example’s lettering shifts slightly. Kerning makes most balloons and captions up to about 1.5% narrower, and where two positions had scored nearly equal a balloon may sit somewhere else. Golden files of your own will need regenerating once.
A few comic-script lines mean something new, each listed under Changed: prose before the first heading is a title page,
PANEL ONEis panel1,Panel 1. A description.is a heading, an all-capsNAME: textwith NAME in the cast is dialogue, a bareCAPTIONstarts a caption, andCAP,CAPTIONandSFXare reserved.A comic script with PAGE headings now writes its pages, and the panels on them are compiled at the size of their frames and lettered at the page’s one size, so they look different; the front matter’s
panel: {size}now sizes only panels on no page.scenet checkcan print notes –file:line:column: note: rule: message– and exits 0 when there are only notes. The MCP server’s findings gainlevel, andvalidatecalls a document with only notes valid.
Added#
scenet checkreports notes as well as errors. A note is a house limit rather than a contradiction: the document still builds, so a note never fails the check. The first is Dark Horse’s word limit,word-limit: a balloon or caption over about 25 words, or a panel over about 50, in YAML and in comic scripts alike. Words are counted as lettered, so--and emphasis underscores add none, and sound effects are not counted.In text, a note reads
file:line:column: note: rule: message; an error’s line is unchanged.In SARIF, the level comes from the rule, in
defaultConfigurationand in each result, so VS Code and the playground show a note as information.checkexits 1 only on an error, and printsokfor a document with only notes.The MCP server’s findings gain
level, andvalidatecalls a document valid when none is an error. (Part of #75)
Comic scripts in Dark Horse’s published layout compile.
PAGE ONE (five panels)is a page heading whose count is checked against the panels under it, as the newpanel-countnote.Panel 1. Alice and Bob on a corner.is a panel heading with its description on the same line, andPanel Oneis panel1. A title page — the writer’s name and address — may come before the first heading. Markdown’s## PANEL 2,**PANEL 2**and horizontal rules are read as the headings and blank lines they mark. A cue with nothing said under it, and a name in capitals with a line under it on the title page, arelooks-like-dialoguenotes.scenet buildprints these notes, andBook.notescarries them. (Part of #75)Comic scripts read Dark Horse’s lettering labels.
CAP:andCAPTIONtake their text from the line or the lines under them; Dark Horse’sCAP/ALICEis a spoken caption by Alice, with the writer’s quotation marks taken off so they are not doubled;ALICE (V.O.)is a voice over, lettered as a spoken caption.ALICE: Hello.is dialogue when Alice is in the panel’s cast, and alooks-like-dialoguenote otherwise.(burst)is a shout, several parentheticals are read together, and Blambot’s numbered items,1. ALICE:, are read with their number set aside. (Part of #75)@over:in comic scripts writes a panel as a change to another, with the merge rulesover:has in YAML: the panel inherits the other’s directives, never its dialogue.@over: 1names panel 1 on the same page first, then the panel named1. A missing panel, a cycle or a panel over itself is onecompositionfinding at the@over:line. (Part of #75)Off-panel speech.
say: {by: caller, text: "Open up!", off_panel: left}is spoken by somebody nobody draws: the balloon’s tail ends on the frame, on that side, or on the slanted outline of a slanted panel.off_panel: truelets the compiler take the nearer of left and right. The speaker is not in the cast, and one who is drawn cannot speak from off panel: the new erroroff-panel-speaker. Panel Core balloons gainoff_panel, the side, written only when set, so no existing Core changes. (Part of #75)ALICE (OP)in a comic script is off-panel speech, as are(OFF),(O.S.)and(O.C.). Alice is left out of that panel’s cast and of the staging that names her, each relation with adropped-relationnote, and her tail ends on the frame on the side she was written to stand, unless the cue names one,(OP, right). A cue for somebody never cast,PHONE (OP), works too. (Part of #75)Small lettering.
say: {..., size: small}letters a line at three quarters of the dialogue size, in a balloon padded as the normal size would be: muttered, as Blambot describes it. A comic script’s(small)and(weak)give it. (Part of #75)French comic scripts.
PLANCHE 1 (six cases),CASE 2andVIGNETTE 2are headings;RÉCITATIF,CARTOUCHEandNARRATIFare captions;ONOMATOPÉEis a sound effect;LÉA : « Bonjour. »is a cue and its line, with a no-break space before the colon.(pensée)is a thought,(off)and(hors champ)off-panel speech.@shot:and@angle:take the échelle des plans —gros planisbig_close_up,plan rapproché épauleisclose_up— and plongée, contre-plongée. Both highlighters follow, and the gallery gains33-planche.script. (Part of #75)A figure may look at somebody heard from off panel:
bob looking_at carol, where Carol speaksoff_panel: left, turns Bob toward the left of the frame and aims his eyes out of it. With no side named, Carol is heard from the side Bob faces. In a comic script,BOB looking_at ALICEnow survivesALICE (OP)instead of being dropped with a note. (Part of #75)nullleaves an inherited cast member out of a panel:cast: {bob: null}in a scene’s panel, underover:or over the scene’s defaults, or@cast: {BOB: null}in a script. It follows JSON Merge Patch (RFC 7386), “If the value is null, remove”. The staging relations that name him go too, each adropped-relationnote, and the JSON Schema accepts thenull. (Part of #75)French delivery words, from the BnF’s sheet on balloons:
(murmure)and(chuchoté)are a whisper,(cri)and(crié)a shout,(à voix basse)small type. (Part of #75)compile_scriptcompiles a comic script handed over as text, exactly asscenet buildcompiles a.scriptfile.scenet check --deep, the MCP server and the playground now all go through it, rather than assembling a script each their own way. (Part of #75)A stressed word is lettered in bold italic. Write it between underscores, the way a script underlines it:
I _told_ you. It works in dialogue and captions, in YAML and in comic scripts, and the word is measured in bold italic as well as drawn in it, so it widens its balloon by exactly as much as it is drawn wider. An underscore inside a word stays an underscore, and\_writes one anywhere. Emphasis that is opened and never closed is reported asunbalanced-emphasis, and a value starting with*, which YAML reads as an alias, now says to quote it. Panel Core gainsrunsbesidelines, written only for a line with emphasis, so every existing panel compiles byte for byte as before. (Part of #74)The editor guide shows how to see
scenet checkfindings in VS Code today: write them as SARIF and open the file with Microsoft’s SARIF Viewer. (Part of #77)The VS Code extension shows what
scenet checkfinds, as you open and save a panel, scene or comic script: an actor not in the cast, an ordering cycle, a pose the puppet lacks, which the schema cannot see. Each finding is underlined where it is and listed under Problems with its rule, linked to its explanation, and goes away when it is fixed.scenet.checkDeepadds--deep;scenet.checkOnSaveturns it off. Ifscenetcannot be run, or crashes, a notification says so once rather than leaving the list empty. (Part of #77)The extension is now versioned with the compiler, starting at 0.10.0, so the
.vsixon a release says which release it belongs to.The VS Code extension highlights comic scripts, as the playground does: headings, directives, captions, cues and their parentheticals, dialogue set apart from prose, and the front matter as YAML. Both highlighters are tested against one set of fixture scripts, which are themselves checked against the compiler’s reading, so neither can drift from the other or from the format. (Closes #77)
Type size can be set:
lettering: {size: N}is the dialogue size in panel units, and captions keep their proportion to it. Set besidepanels:it applies to every panel, so a whole page letters at one size you chose; on one panel, to that panel alone; in a comic script, in the front matter or an@lettering:directive. Left out, nothing changes. (Part of #74)Letter in your own face.
lettering: {font: fonts/Comic.ttf}, or a file per face underregular,italicandbold_italic, sets the lettering in fonts the document names, read relative to the folder it is in – never a system font, and never an absolute path. A face left out stands in from one given, and the compiler says so when that matters. Panel Core records each face by family, style and a digest of its bytes, never a path; the renderer is handed the fonts and refuses a panel whose fonts it was not given;--live-textnames the family measured. A font that is missing, absolute or not a font is the new rulefont-file, located at the face. The playground gains Font… to add a file for the session. Capitals stay as you type them, and Source Sans Pro stays the default; both are recorded. (Part of #74)Scenet ships a display face for sound effects: Bangers, by Vernon Adams, under the SIL Open Font License 1.1. No package carries it, so it is vendored inside the wheel with its licence beside it, recorded in
THIRD_PARTY_NOTICES.md, and pinned by a test to the file in google/fonts. Nothing letters in it yet; sound effects will. (Part of #73)Sound effects.
- sfx: {text: BLAM, from: bob}letters a sound into the picture in the display face, with no balloon:small,mediumorlarge, turned byrotate, bent along anarc, andhollowfor an open effect the art shows through. It is placed by candidates and cost near its source or in itsprefer:zone, never covers a face, and is never given a coordinate. Balloons pay to cover it, as they pay for emanata, and no figure moves for it. It takes its number in the script’s reading order without the geometric rule. Panel Core gainssfx, every letter already turned and placed; the debug overlay shows each one’s footprint;scenet check --deepreports one with nowhere to go assfx-placement;lettering.fontcan name adisplayface. Panels without one compile exactly as before. (Part of #73)Sound effects in comic scripts:
SFX: BLAM,SFX (BOB, large): KRAKfor its source and size, and Dark Horse’s bareSFX:cue with the sound on the next line – which used to be dropped as prose, or read as a character called SFX. AnSFX:cue with nothing under it is reported rather than lost. The playground and the VS Code extension highlight them, and the playground colours an effect’sfrom:as an actor. Sound effects are recorded indocs/explanation/design_decisions.mdandprior_art.md. (Closes #73)A comic script’s PAGE headings lay its panels out on pages, as a scene’s
pages:does. A page’s panels go into tiers by a fixed rule — at most three tiers up to nine panels, an odd one alone in the middle tier — or by@tiers: 2 1 2written right after the heading. The front matter’spage:sets the format;pages:there is an error, as is a@tiers:that does not add up or is written elsewhere, underpage-layout.scenet buildwrites each page, with its Page Core and overlay. With it, every row of #75 is done: the spec pack, the Agent Skill and Drive Scenet from a model now say that Dark Horse’s format and French scripts are read as written. (Closes #75)
Changed#
Comic scripts: what a few lines mean has changed (Part of #75):
Prose before the first PANEL heading is a title page, not an error. A directive, a caption, a sound effect or a cast member’s cue there is still one.
A panel numbered in words is named by its number:
PANEL ONEis panel1, andscenet buildwritesname.1.svgfor it rather thanname.ONE.svg.Panel 1. A description.is a heading; it was prose.A line of three or more
-,*or_ends a speech, as a blank line does; it was joined onto the speech.An all-caps
NAME: textwith NAME in the cast is dialogue; it was prose. One in the middle of a speech starts a new balloon; it was joined onto the speech above.A bare
CAPTIONline starts a caption whose text is under it; it was an error.CAP,CAPTIONandSFXare reserved, and cannot be a cast member’s id.A balloon’s text in one pair of quotation marks is lettered without them.
A script with PAGE headings now writes its pages,
name.page-1.svgand on, and the panels on them are compiled at the size of their frames and lettered at the page’s one size, so they look different from before. The front matter’spanel: {size}now sizes only panels that are on no page.
Lettering is kerned. Pair adjustments are read from the font’s GPOS
kernfeature, or a legacykerntable, and applied to measurement and to the glyph outlines alike, so what is measured is still exactly what is drawn. Every example’s output changes once: most balloons and captions come out slightly narrower, by up to about 1.5% (a kern pair can loosen as well as tighten, so a few grow a little), and where two positions had scored nearly equal a balloon may sit somewhere else.--live-textrelies on the renderer kerning as the compiler measured it, which browsers do by default. Checked pair by pair against HarfBuzz, which is a test dependency only. (Part of #74)The VS Code extension’s comic-script grammar is generated from one definition of each kind of line, rather than hand-written with every heading spelled out in up to four places. Highlighting is unchanged. (Part of #75)
Fixed#
A
--or...written apart from its word could be lettered alone on the last line, or at the start of one:the lamp is out --broke before the dash. Blambot sets both with no space, so a dash or an ellipsis now stays with the word it is written against. The space is still lettered as written; no gallery example moves. (Part of #75)A line between a PAGE heading and its first PANEL was filed into the panel before the page: a speech there was spoken in the previous page’s last panel. It now belongs to the page, and a speech there is an error, since it belongs to no panel. (Part of #75)
The playground took a YAML panel that opens with a
---document marker for a comic script, and a script written as Dark Horse asks,Panel 1., for YAML. A script is now told by its fenced front matter or a panel heading in any of its forms. (Part of #75)Spoken captions by two speakers were quoted as one run. Consecutive
spokencaptions open a quote each and close only the last, but the run did not end when the speaker changed, so the first speaker’s words were never closed. A change ofbynow ends the run. No shipped example moves. (Part of #75)A comic-script directive written twice in one panel silently kept the second.
@setting: {weather: rain}and then@setting: {place: docks}lost the rain. The second is nowduplicate-key, at its line, naming the first. An@script:directive, which the panel’s cues used to overwrite without a word, isduplicate-keytoo. (Part of #75)A fault in a comic-script panel kept neither its rule nor its line. Everything validation found was reported as
invalid-fieldat the PANEL heading: a speaker not in the cast, an unknown place, a bad@shot:. It now keeps its own rule (unknown-actor,unknown-place, …) and points at the cue or directive that holds it. When a panel has several, the first in reading order is reported. (Part of #75)A cue with an accented name lost its dialogue.
HÉLÈNEorZOË (whisper)failed the cue pattern’s A-to-Z capitals, so the cue and the line under it were filed as prose without a word. Any capital letter now starts a cue, in the compiler and in both highlighters. A script is also read composed (Unicode NFC), so a name a macOS editor stored asEand a separate accent matches the front matter’sÉ. (Part of #75)A comic script saved with a byte-order mark was rejected for having content before the first PANEL heading: the mark hid the front matter. It is now ignored. (Part of #75)
Line numbers in a comic script’s findings could be wrong after a line holding a line separator, form feed or similar character, which Python splits a line at and an editor does not. Lines are now split at line feeds alone. (Part of #75)
The VS Code preview could not run
uv run scenet, the setting its README suggests: it ran the compiler from wherever VS Code runs extensions, its own install directory, whereuvfinds no project. It now runs from the document’s workspace folder.The VS Code extension could not run
scenetfrom a path with a space in it, such as one underC:\Program Files, thoughscenet.executableasks for an absolute path: the setting was split on every space. A part in double quotes now keeps its spaces.A comic-script finding repeated its file in the message, spelled as it was typed. Given an absolute path,
scenet checkwrote that path into its SARIF output, and the finding’s fingerprint changed with the spelling. The location still names the file.A SARIF fingerprint depended on how the file was named on the command line, for every kind of document:
a.panel.yamland its absolute path gave two fingerprints for one result, so an editor and CI would have raised two alerts for one fault. It now uses theurithe result reports. A path given relative to the working directory, as CI gives it, keeps the fingerprint it had.SARIF output did not say what a column counts. SARIF 2.1.0 requires
columnKindon a run with results, and without it an editor counting UTF-16 code units, as VS Code does, points one column further off past each emoji. It is nowunicodeCodePoints.A comic-script finding pointed at the first character of its line in SARIF, which claimed a precision the parser does not have. Its region is now the whole line, so an editor or code scanning underlines the line.
The playground never coloured a comic script’s
PAGEandPANELheadings, and the line after a cue with a parenthetical, such asBOB (whisper), was not shown as dialogue. Monaco refused those three highlighting rules and dropped the lines without a word. The rules are fixed, and a test now runs them through Monaco’s own lexer, where a refused rule fails.The playground coloured a comic script by older rules than the compiler reads it by.
Panel 1.,ALICE:andCAPTION: Later.were shown as prose; a cue did not end the speech before it; and a---scene divider opened front matter that never closed, colouring the rest of the script as YAML. It now follows the script frontend line for line, and shared fixtures, checked against the frontend, hold it there.Toggle Line Comment in a VS Code comic script wrote
//lines, which the format does not have: the compiler kept them as prose, or read them as dialogue under a cue. The extension no longer declares a comment syntax for scripts, as the playground never did.scenet check --format sarifcrashed on a caption that named a speaker it cannot have, such asby:on alocalecaption. Its rule,caption-speaker, had never been added to the catalogue, so writing the finding as SARIF, or returning it from the MCP server’svalidatetool, ended in aKeyError. The rule is now catalogued and documented, the finding points atby:rather than the whole caption, and a test holds every rule the compiler raises to the catalogue.
0.10.0 - 2026-10-10#
Pages. A scene can now be laid out on pages – tiers of panels, columns beside them,
insets set into corners and gutters that lean – and scenet build writes each page beside
its panels. This release also closes more than twenty ways a document could lose something,
point at the wrong line, or end in a traceback, and the test suite now holds the compiler to
its promises with generated documents, golden outputs on every platform and weekly mutation
testing.
Upgrading from 0.9.
Some documents that compiled now refuse, each for a fault that was losing something without a word: a key written twice in YAML, a panel named with an unquoted number,
.infor.nananywhere, a control character in a line or an actor id, an inset that does not fit its panel, and two outputs that would be the same file.Every panel with lettering renders slightly differently. Glyphs are now drawn at the size they were measured, which at some sizes is 14% smaller than before; a strip’s ids are prefixed by each panel’s position; and
--stripno longer writes a strip of one panel.Some findings moved: an unknown speaker is at
script.N.say.by, a block-style key at its own line, a brokenover:at theover:. Code that matched on the old paths, the MCP server’swhereincluded, needs updating.A comic script that numbers its panels per page now names them by page and panel (
2-1), where before the later page overwrote the earlier one.
Added#
Pages. A scene can lay its panels out with
pages:: each page a list of tiers, each tier a list of panels, and a weight for each tier’s height and each panel’s width, shared out of whatpage:’s margin and gutters leave, the way CSS Grid shares a row. A panel on a page is compiled at its frame’s size and nothing else changes about it, except that every panel on a page letters at one type size. (#66)scenet buildwrites each page asstem.page-<n>.svg, with its Page Core and overlay under--coreand--debug, and refuses a panel whose file would be a page’s.A new tier, Page Core, records where every frame is and the type height the page shares.
compile_bookreturns the panels and the pages;render_pageandrender_pagesdraw them.scenet checkreportsscenet/page-layoutfor a placement naming no panel, a panel placed twice, or no room left by the margin and gutters.The published schema, the VS Code extension and the playground understand pages; the playground shows a document’s pages side by side, and its Panel Core view holds the Page Cores. MCP
compilereturns each Page Core andrenderone SVG per page.A gallery example, a how-to (Compose a page), and a prior-art entry on where the rules come from: Cohn’s reading-order experiments, Peeters, Groensteen, CSS Grid.
Columns on a page: a tall panel beside a stack. A tier can hold
columns:in place ofpanels:, each column a stack of panels shared out byheight, and a column of one panel spans the whole tier. A tier of columns is read down each column before across, as readers read a stack blocked by a tall panel. Two stacks side by side block nothing, readers go across them, andscenet checkrefuses them aspage-layout. (Part of #67)Insets: a small panel set into a corner of another, drawn over it inside a ring of white.
insets:on any placed panel takes a corner, asize(a fraction of the parent, at most a half) andread: beforeorafter. Readers split about evenly over an inset, so its place in the reading order is written, never guessed: after its parent by default. (Part of #67)The parent’s art does not move. Its lettering keeps clear of every inset, as firmly as of a face, and its Panel Core records what it kept clear of as
exclusions. A note says when an inset covers a face.Page Core frames gain
inset_ofandclearance, and the page paints every inset over its parent whatever its reading order. Neither new field is written where it is unused, so every existing Core is byte-identical.scenet checkreports two insets that overlap aspage-layout, located at the second.The debug overlay draws what an inset covers. A gallery example, and a section of the Compose a page how-to.
Slanted tiers:
slanton a tier of panels leans every gutter in it, up to 30 degrees either way, for a beat that should not sit square. Neighbours share one cut, a gutter stays a gutter wide across it, and the tier’s outer edges stay upright, so every frame is a convex four-sided shape. (Closes #67)A slanted panel is staged in its bounding box and cropped to its
outline, which its Panel Core and its Page Core frame record; its lettering stays inside the outline, a margin in. A note says when the cut runs through a face.A rectangle writes no
outline, so every existing Core and page is byte-identical.scenet checkrefuses, aspage-layout, a slant on a tier of columns, on a tier of one panel or on panels with insets, and one too steep to leave every panel some width.
scenet/duplicate-panel, the finding for two panels in a script that would still share a name:PANEL 1twice on one page, or twice with no PAGE heading between them. It points at the heading that repeats. (#63)scenet/duplicate-key, the finding for a key written twice in one YAML mapping. It points at the second and names the line of the first. (#83)Golden outputs, checked on every platform. The gallery is built through
scenet buildin every CI job, Windows included, and the bytes on disk must match committed goldens: every Panel and Page Core in full, and a digest of every SVG. Two processes with different hash seeds, and a relative path against an absolute one, must write the same bytes, and no output may hold the path it came from.scripts/update_golden.pyregenerates them. (#94)Weekly mutation testing of the solver and the emitters.
.github/workflows/mutation.ymlruns mutmut oversolve/andemit/every Monday and on demand, and reports every small edit to the code that no test notices, with the score in the job summary. A second job runs the property tests with fresh random seeds and 300 examples each. Neither runs on pull requests or blocks a merge. mutmut is in its ownmutationdependency group, so a plainuv syncdoes not install it. (#95)The command-line reference is a tested contract. Each command’s options, choices, defaults and exit statuses, the frontends, and every behavioural sentence in
docs/reference/cli.mdare checked against the code in both directions, so neither can drift alone. Every rule has a document intests/rule_corpus/that must produce exactly one finding of it. And thescenetcommands in the documentation’s shell examples now run in the test suite, as its Python examples already did. (#93)Property-based tests for pages, scripts and broken documents. Generated books are held to the documented reading order, worked out from the pages as written, to frames that stay inside the margins and clear of each other, and to sound SVG with ids unique across pages. Generated comic scripts lose no panel and no line. And a valid document given any one mistake from a catalogue of twenty-odd must get exactly one finding from
scenet check, under the right rule and on the right line; arbitrary input must never get a traceback. The eight bugs they found are fixed above. (#92)Property-based tests. The checks a compiled panel must pass, which ran on five hand-written panels, now also run on panels Hypothesis generates: lettering inside the margin, off every face and in reading order against every earlier box; an SVG that parses, whose ids resolve and whose glyphs are drawn at their measured size; compiles that are byte-identical; Panel Core that round-trips; and
scenet check --deepagreeing with the compiler. The examples are fixed, so a failure replays on every machine.docs/maintainer/testing.mdexplains the profiles and how to add a generator. (#91)
Fixed#
The same panel could compile to different bytes. kiwisolver, which places the cast, keys its internal maps by object address, so the same layout solved twice could come back a few ulps apart. A coordinate derived from it that sat on a rounding boundary then printed as
247.95in one compile and247.96in the next, in the same process. Solved positions are now snapped to a millionth of a unit as they leave the solver, far above that noise and far below anything the output shows. One gallery golden moves by 0.01 as a result. Found by the weekly Hypothesis exploration. (#117)One mistake in a puppet part was reported six times. A part is a bone (
from,to,width) or a blob (at,radius), and a bone with a badwidthwas also tried as a blob, so pydantic listed five more errors about a blob nobody wrote, under paths naming its classes. A part is now checked only as the kind its keys say it is, atparts.N.boneorparts.N.blob, and a part with the keys of both kinds or of neither is one error that says what a part must be. The same fix #98 made for script entries. (#92)A font with no character map raised
KeyError: 'cmap'from inside fontTools when passed asmetrics=, instead of theValueErrorthatFontMetricsdocuments for a font it cannot measure text against. Found while triaging mutation testing. (#95)scenet buildcould silently overwrite one output with another. Only a panel named like a page was refused. A panel namedstripreplaced the strip,x.debugreplaced panelx’s overlay, and two names differing only in case wrote one file on Windows and macOS. Every output is now planned before anything is written, and two that would be the same file, compared ignoring case, are a usage error: exit 2, nothing written. (Refs #93)A panel name holding
/or\madescenet buildend in a traceback. It is now a usage error, exit 2, saying why the name cannot be part of a file name. (Refs #93)--stripwrote a strip of one panel for a scene with a single panel, although the reference says it is ignored for one; only a document whose panel was calledpanelskipped it. A strip now needs more than one panel. (Refs #93)An unknown speaker was located one step short of its
by:. The finding’s path wasscript.0.by, which the document does not have – a line is written- say: {by: ...}– so a script in block style was pointed at- say:rather than theby:line. The path is nowscript.0.say.by, as every other fault in a script entry has been since the verb picks the event, and the finding lands on the unknown name itself. The MCP server’swherefield for it changes the same way. (Refs #92)Some findings pointed at the wrong line, or at no line at all. A syntax error at the very end of a file – a bracket never closed – was put on the line after the last one, which an editor or code scanning cannot show. And a key whose value is a block, such as
panel:with its fields beneath it, was located at the block’s first field: a panel whose margin left no room pointed atsize:, and a cast member missingreferenceat whatever key it did have. The first now sits at the end of the last line, the second at its key. (Refs #92)A broken
over:was located at the wholepanels:block.scenet checkpointed a missing parent, a cycle or anover:that is not a name at the first line ofpanels:, wherever the fault was. It now points at theover:to change, and a missing parent’s message names the panel that refers to it. (Refs #92)A misspelled required key was reported twice.
referense: alicecame back as an unknown key and as a missingreference, both at one place, for one mistake. When an unknown key closely matches a required key missing from the same mapping,scenet checkandbuildnow report onescenet/unknown-keyfinding, ending “did you mean ‘reference’?”. An unrelated unknown key beside a missing one is still two findings. (Refs #92)A staging sentence relating an actor to itself was filed under the wrong rule.
alice left_of alicecame back fromscenet checkasscenet/invalid-field, althoughscenet/reflexive-relationexists for exactly this; the frontend rewrote the error and lost the rule. It is now reported asreflexive-relation, andbuildkeeps the rule and location of every fault the frontend finds itself – an unknown place too – ascheckdoes. (Refs #92)An inset could be drawn outside the panel it is set into. An inset sits a gutter in from its corner, so in a panel narrower or shorter than that it landed over the next panel or the page margin, and
scenet checksaid nothing. An inset that does not fit is now refused asscenet/page-layout, at the inset, saying what to change. (Refs #92)A document nested a few hundred levels deep ended in a traceback. PyYAML reads a document recursively, and Python’s recursion limit is not a YAML error, so
scenet check,check --deep,buildand a comic script’s front matter all ended inRecursionError. It is now reported as invalid YAML: “the document is nested too deeply to read”. (Refs #92)A control character in a panel wrote an SVG no XML parser accepts. A
\x07in a line of dialogue broke--live-textoutput, and one in an actor id broke the default output too, through itsidattribute. XML cannot hold these characters even escaped, so a line, a caption or an actor id holding one is now refused asscenet/invalid-field, naming the character. Tab, line feed and carriage return are still accepted. (Refs #91)A panel named with a number beside one named with a word crashed
scenet checkandscenet buildwith aTypeErrortraceback. YAML reads an unquoted1:as a number andnull:as nothing, and the names could not be sorted together. A panel’s name is text, as a cast member’s id already was, so each one that is not is now reported asscenet/invalid-fieldat the name, with the quoted spelling to use instead. (#92)Lettering was drawn larger than it was measured. Each glyph’s scale, the font size over the font’s units per em, was written to two decimal places like a coordinate. At size 35 that is 0.035, written as 0.04, so every letter was drawn 14% larger than the width the balloon was sized for and its neighbours were spaced for. The scale is now written to six places, and a test holds every drawn glyph to its measured size. (#91)
An infinite or undefined number ended the interpreter.
.infand.nanare valid YAML floats, and one in a panel’s or a page’s size, margin, height or width passedscenet checkand then reached the solver, where kiwisolver stopped the process outright: no traceback, no message, no output. Every number a document, a puppet or a Panel Core holds must now be finite, and one that is not is reported asscenet/invalid-fieldat its key. (#91)One mistake in a script entry was reported up to four times by
scenet check. A caption withkind: narrationalso came back as every reason it was not asay, all at the same place. The entry’s verb now picks the event it is checked against, so the one real fault is reported, at the field it is in (script.0.caption.kind). A face mark in a hand-edited Panel Core is picked by itsmarkthe same way. Entries built in Python without a verb are still accepted, and the published schema is unchanged.-onaming a directory crashedscenet build,checkandschemawith a traceback;scenet build x.panel.yaml -o .was enough.buildnow writes into a directory under the default name, ascpdoes. A directory is one that exists, or a path ending in/.checkandschemawrite one file of their own, so they refuse a directory with a usage error.scenet check -o FILEignored-oin text format. The findings went to the terminal and no file was written, although the reference said it wrote the report to the file. It now does, as it already did for SARIF. The file is empty when every document is valid.A mistake inside one tier of
pages:was reported twice byscenet check. The second report said the list of tiers was empty, which it was not: pydantic also calls a tuple too short when one of its items fails. That echo is now dropped wherever pydantic’s errors become findings.Output was not byte-identical across platforms. On Windows, every SVG, Core, overlay, strip and page that
scenet buildwrote had CRLF line endings, as did reports and schemas written with-oandscenet schemaredirected from stdout. The same build on Linux wrote LF. Everything is now written as UTF-8 with LF everywhere. A SARIF report printed to a Windows console no longer fails on a character outside its code page. CI now runs the test suite on Windows as well, where a test checks the written bytes.A comic script could lose panels and dialogue without saying so. Three cases, none of which raised anything. (#63)
Panel numbers that start again on each page overwrote each other, so
PAGE ONE / PANEL 1 / PANEL 2 / PAGE TWO / PANEL 1compiled two panels. Publishers’ script formats number panels per page, so this is the common case. When numbers repeat, every panel is now named by its page too:PANEL 1underPAGE TWOis2-1, written toname.2-1.svg. Spelled-out pages are named by their number. A script that numbers straight through keeps its names.Dialogue wrapped onto a second line lost that line. A speech now runs to the next blank line, joined with spaces. Prose written directly under dialogue with no blank line between them now joins the speech; a line that looks like a cue still starts a new one.
PANEL 1:named the panel1:, andscenet buildwrotename.1:.svg, which Windows cannot hold.PANEL 1:andPANEL 1.both name panel1now.
--striplet figures spill out of their panels, and repeated every id. A shot crops the body at the frame, and a panel on its own hides the rest behind itsviewBox; in a strip nothing clipped, so bodies drew into the gutter. Each panel is now clipped to its frame, overlay included, so a panel looks the same in a strip as alone. And every id is unique: each panel’s ids, and the references to them, are prefixed by its position (p1-,p2-), never by its name, which could not be kept safe insideurl(#...). The strip’s output changes; a single panel’s is byte-identical.renderandrender_debugtake anid_prefixfor this, empty by default. (#64)Reference documents disagreed with the code in eight places, now each true again and the first three held there by a test. (#65)
shot_types.md, the normative one, saidanglemoved the eye-line. It has always scaled headroom (×0.5, ×1.0, ×1.6), as the code, the IR and gallery 03 say.The puppet example in
asset_contract.mdused fields the contract never had, so a puppet written from it would not load. It is now a complete puppet that does.The rule table in
cli.mdlackedunknown-placeandconflicting-setting.The constraint table in
language.mdhad panel bounds as required and ordering as strong; it is the other way round, on purpose.BalloonKindsaid speech and whisper balloons were ellipses and thought balloons clouds; they are rounded rectangles and an ellipse.The editor guide claimed highlighting for
.scriptfiles, which the extension does not have (#77). The comic-script guide said rain was not a construct (it has been since 0.6.0), and the status page still listed tinted captions as planned and pages as untracked.
A key written twice in YAML lost the first without a word. PyYAML keeps the last of two equal keys, so
cast: {alice: …, alice: …}compiled one character andscenet checkcalled itok; the same went for panels, settings and a puppet’s poses. Every YAML Scenet reads (panels, scenes, a script’s front matter and@directives, puppet files) now refuses a repeated key, as the YAML specification says it should. A merge key’s override is still allowed. Documents that compiled with a silently dropped key now fail; that is the fix. A puppet file that is not valid YAML is now anAssetErrornaming the file, rather than PyYAML’s bare error. (#83)
0.9.0 - 2026-10-03#
A release for maintainers: Scenet can now be listed in the MCP registry from a workflow. The
language, the compiler and the scenet mcp server are unchanged from 0.8.0.
Added#
A workflow lists releases in the MCP registry.
mcp-publisher login githubcannot publish under an organisation namespace, because the registry’s GitHub App is not installed on the organisation andio.github.creatoan/*answers 403 whatever the role. The new.github/workflows/registry.ymllogs in with the workflow’s OIDC token instead, which proves the namespace through the repository and needs no secret. Run it by hand for an existing tag, or set the repository variableMCP_REGISTRY_PUBLISHto haverelease.ymlcall it after each release. It checks thatserver.jsonnames the tag’s version and that the version is on PyPI before it publishes, and pinsmcp-publisherto a version and a SHA-256. (#60)
Fixed#
The release guide advised
mcp-publisher publish --dry-run, which publishes.publishhas no such flag, so an unknown one is ignored and the listing happens. The guide now says to usevalidate, which checks the manifest against the live registry and changes nothing. (#60)
0.8.0 - 2026-10-02#
Models can now be told how to write Scenet, and can check what they wrote: a spec pack, an Agent Skill and an MCP server. A comic’s marks — sweat, dizziness, oaths, dust — join the language, and diagnostics in comic scripts and shared casts now point at the right line.
Added#
Emanata: what a comic draws around a character. A cast member takes
marks:, a list from Mort Walker’s Lexicon of Comicana:plewds(sweat flying off the head),squeans(dizziness),grawlixes(an oath, as a spiral, a star, a bolt and a hash) andbriffits(the dust of a hasty exit). A list rather than a secondexpression:, because they compose — a character can be angry and sweating. Every puppet gets every mark; nothing new is declared per puppet. Atlong_shoteach mark collapses to a dot, and a figure too small to have a face has none. (#21)Marks cost a balloon space, and never move anybody. They are drawn outside the head, where balloons go, so each mark has a zone that balloons and captions pay to cover — weighted above covering a body, with no discount for the speaker. They stay out of the hull, so staging, the camera and every figure are exactly where they would be without them, and a crowded panel still compiles. The camera makes no room for them either, so a mark cropped by a tight shot is reported in the compile notes. The debug overlay draws the zones.
scripts/contact_sheet.py --marksrenders every mark across the shot ladder, and the gallery gains23-emanata.scene.yaml.A way to tell a model how to write Scenet. The spec pack puts the language reference, the shot types, the comic-script format, the shipped characters, every diagnostic rule, the JSON Schema and the whole gallery in one file, published at
/scenet-spec.mdbeside anllms.txt. It is what to hand a chat app that cannot run code, such as NotebookLM, which can then write a comic script for you to compile.skills/scenetis an Agent Skill for coding agents. All of it is generated from the compiler’s own sources, and a test fails if a committed copy goes stale. (#11)scenet mcp, an MCP server, so a model can validate its own panel, read findings that name the rule, the line and the fix, and render the result with nobody relaying errors. Five read-only tools —get_spec,list_puppets,validate,compile,render— over stdio or Streamable HTTP, on protocol revision 2026-07-28. It needs the new optional extra:pip install 'scenet[mcp]'. Aserver.jsondescribes it for the official MCP registry. (#11)Driving Scenet from a model, a how-to for each kind of client, and two entries in prior art: WordsEye, the ancestor of text-to-scene, and Gumin et al. 2025, the strongest argument against a declarative language, recorded for what it actually found. (#11)
Changed#
Panel Core actors gain
marks,emanataandemanata_zones. All default to empty, soformat_versionstays 1 and a Core document written before them still reads. Every actor now serialises the three keys, so a golden file captured against 0.7.0 will differ by them — and by nothing else: every example in the repository lays out byte-identically.
Fixed#
A comic script’s line numbers counted from the end of its front matter, not from the top of the file, so
scenet checkand the playground pointed several lines above the fault in any script with a cast block — which is nearly all of them.A panel in a comic script that failed validation — a misspelled
@shot:, say — was reported at line 1 whichever panel it was. It is now reported at that panel’sPANELheading.A bad name in a shared cast was reported once per panel, every copy pointing at the panel rather than at the line that was wrong — in a comic script’s front matter, all of them at line 1. A fault in a scene’s defaults or a script’s front matter is now reported once, where it is written. A panel’s own mistakes still carry its name.
scenet buildprinted a traceback for a file with an unsupported extension, andscenet checkcalled the same fileok. Both now report it as a usage error, exit 2.scenet build foo.panel.ymlwrotefoo.panel.yml.svg..ymlis now named exactly as.yamlis:foo.svg.The command-line reference’s
scenet check examples/gallery/*.yamlexamples failed, because the glob also matched the gallery’s manifest. CI’s gallery check now includes the gallery’s comic script, which it had skipped.
0.7.0 - 2026-10-02#
The playground became a place to work, the editor schema stopped rejecting valid
documents, and the project moved to the creatoan organisation.
Added#
The playground became a place to work, not just a demo. The output zooms and pans — scroll or pinch about the pointer, drag, double-click for Fit or 100%,
+ - 0 1and the arrows — and keeps the zoom while you edit. Download saves the panel as SVG or a 2× PNG, the overlay, the Panel Core and the source, named asscenet buildnames them;Ctrl+Ssaves the source. Edits survive a reload, and Share copies a link that carries the whole document in its fragment, so no server is involved. A failed compile is reported by the same checkerscenet checkruns: each finding is a squiggle on its own line, and the list under the output jumps to it. Actors, staging relations and script verbs are coloured; Panel Core opens in a read-only editor with folding; the split between the panes can be dragged; the output can go full screen. The editor also shows the example at once instead of sitting empty while Python boots. (#45)render_strip(..., debug=True)lays out each panel’s overlay where the strip puts the panel, so a scene has an overlay too. (#44)
Changed#
The project moved to
creatoan/scenet. GitHub redirects the repository, its issues and pull requests, andgitremotes. The documentation and playground are now at creatoan.github.io/scenet; the oldazias.github.io/scenetaddresses do not redirect, because GitHub Pages never does. If a YAML document names the schema, update its first line to:# yaml-language-server: $schema=https://creatoan.github.io/scenet/schemas/panel.schema.json
Fixed#
The published JSON Schema rejected the syntax people write. It described the IR, after the frontend has rewritten staging sentences,
- say:wrappers,place:and partial scene overrides away — so 21 of the 22 gallery documents failed it, and the playground and the VS Code extension underlined lines that compiled. The newscenet.schemamodule puts each of those back; a test now validates every shipped example against the shipped schema. (#44)The overlay wrote actor ids into SVG unescaped, in an
idattribute and in text labels. The playground puts that SVG into the page, so an actor id could close its attribute and add markup. Identifiers are now escaped as they already were in the panel itself. (#44)scenet checkreported a bad staging sentence or script entry against the whole document. It now points at the entry — an unknown predicate, a malformed sentence, an unknown verb. (#44)
0.6.0 - 2026-08-27#
Setting: a panel can now show where and when it happens — and a caption box can be tinted to read against it.
Added#
The setting layer: a panel can show where and when it happens. Every panel rendered figures on white; there was no
settingblock at all. Captions (0.4.0) shipped the cheap half of establishing place — alocalebox can sayMIDNIGHT. THE DOCKS.— and this is the expensive half.setting: place: docks horizon: mid time: night weather: rain
Backdrops are described tonal masses, never drawn geometry. Crisp architecture needs a vanishing point and this is deliberately a flat, orthographic compiler, so drawn buildings would fight the compiler’s own model — soft masses have no perspective to get wrong. It is also how comics actually establish place: notan (Dow, Composition, 1899) says place is read from the arrangement of masses rather than from rendered detail, and aerial perspective supplies the parametric rule — with distance, value contrast drops toward the atmosphere.
Twelve mass kinds, from COCO-Stuff supercategories —
building,ground,plant,sky,solid,structural,wateroutdoors,ceiling,floor,furniture,wall,windowindoors. Taken from an existing taxonomy of stuff rather than invented, for the same reason the predicates came from Visual Genome. Not its leaf names: the real classes arebuilding-otherandsky-other, and nobody should have to type that.Ten named places —
alley,desert,docks,field,forest,mountain,office,room,shore,street— each expanding into a mass list the author could have written themselves. That rule is what keeps a preset a library rather than a second opaque format, and it is enforced by a test. The expansion happens in the frontend, so the IR has noplacefield at all — the same treatmentalice left_of bobgets.planereuses the existing painter’s order rather than introducing a second one. The three backdrop planes take negative depths;foregroundtakes one above the frontmost actor, so a foreground mass draws over the cast the way a silhouetted doorway does. Value follows from the plane and from nothing else, which is what keeps the notan reading literal.timeandweather.timesupplies the two ends of the value ladder rather than tinting a daytime panel, sonightis a darker, narrower ladder — and the ladder stays monotonic in depth at every hour by construction.weatheraddsfogas afeTurbulenceveil, andrainandsnowas that veil plus falling marks.CoreBackdropon Panel Core, carrying fully resolved numeric polygons and tone values — the same discipline ascapsules,blobsandface_marks, so the emitter still makes no layout decision. Absent on a panel that says nothing about where it is, which is why this needed noformat_versionbump.Masses are a soft cost for balloon placement, never an exclusion. Balloons sit over backgrounds routinely; that is what a background is for. Covering one costs an order of magnitude less than covering a face, weighted so a foreground silhouette costs more than empty sky.
scenet checkreportsunknown-placeandconflicting-setting, each naming the field. A place and a mass list together is rejected rather than guessed at: a place is a mass list.scripts/setting_sheet.py, the calibration instrument — every place against every hour on one sheet, every weather on another. Whether three greys read as depth is not a question a test can answer, and four things moved because of what the first sheet showed.Gallery examples 19, 20 and 21, and a
docs/reference/language.mdsection for the block.Caption boxes can be tinted. Captions shipped in 0.4.0 with four kinds and the typography that goes with them, and one value:
#ffffff, hardcoded in the emitter. Atonekey now chooses from a three-value palette.- caption: {text: "Noon. Nothing for miles.", kind: locale, tone: ink}
The failing case is the pale end, not the dark one. A caption box is opaque, so its lettering was never at risk — the text sits on the fill whatever is behind it. The box is what stops reading: against the ladder above, a white box on a noon sky is 1.16:1, and only the stroke separates it at all.
The palette is rungs of the backdrop’s own value ladder —
paper#ffffff,pale#adadad,ink#090909, the last two taken from thedayrow by index rather than restated, so lettering and backdrop cannot drift apart as either is tuned.paperis the default, so no existing panel moves. No free-formfill:, and no yellow: an open colour field would be this language’s one open vocabulary, and the classic yellowlocalebox would be the first non-neutral value in the codebase.inkinverts the lettering to paper — reversed type — chosen by contrast in the solver and carried onCoreCaptionasfillandink. The same rule and the same reason as falling rain, and it leaves the emitter with no decision about which mark reads. Both fields are defaulted, so a Core document written before this still parses and noformat_versionbump was needed.The lettering floor is enforced rather than asserted.
contrast_ratioinsolve/backdrop.pymeasures WCAG relative luminance — the ladder is spaced in OKLab because that predicts even perceived steps, but legibility is checked against the published threshold. Every tone clears 4.5:1 against its own lettering, and every rung of every hour has at least one tone above 3:1 to sit on. This is the one visual rule in the compiler with an objective answer, so it is a test rather than a taste.Gallery example 22, a
tonerow and section indocs/reference/language.md, andfill/inkindocs/reference/panel_core.md.scenet check --deep. Runs the full compiler on any document that passes the cheap checks, to additionally catchlayoutandballoon-placementfailures — the two rules in the catalogue that were in the catalogue but unreachable fromcheck. Off by default: it costs a real compile, including font metrics, andcheckstays the cheap pass it is documented as unless asked otherwise.
Changed#
long_shotreframes noticeably wider, andwidewith it — headroom0.14→0.28, footroom0.06→0.10.solve/camera.pyadmitted the problem in a comment: with no environment to show,long_shotandfull_shotcrop at the same landmark and could differ only by a little headroom, so two rungs at the widest end of the ladder stayed degenerate. There is an environment now, so a long shot can mean what it says — the figure fills roughly two thirds of what a full shot does. Every existing panel that asks forlong_shotorwiderenders smaller than it did. The comment is gone anddocs/reference/shot_types.mdis updated.PanelSyntaxErrorcarries an optionalruleandloc, so a check the frontend performs itself can name a catalogue rule and a field instead of arriving as a genericinvalid-field. Both default to nothing, so every existing raise is unchanged.The determinism boundary is written down in
docs/reference/language.md: the contract is on the emitted SVG text, which stays byte-identical, and has never been on pixels.feTurbulenceis reproducible by specification and browsers still agree only approximately on what to paint from it. Stated now, while adding the first feature that depends on it, rather than left for somebody to rediscover when a screenshot test flakes.docs/explanation/prior_art.md: shape grammars move from future to load-bearing, with the finding that no open-source Python CGA implementation exists — the reference one is commercial, inside Esri CityEngine — so the formalism is reused rather than a library. Notan, aerial perspective and COCO-Stuff are added as load-bearing; physically based sky models (Preetham, Hosek-Wilkie) are recorded as examined and rejected, since they solve a radiometric problem this compiler does not have.PuppetSpec.pose_anglesand.expression_statesraiseUnknownPoseErrorandUnknownExpressionErroron a name the puppet does not declare, rather than a bareKeyError. Both are alsoKeyError— following the precedentUnknownPuppetErroralready set — soexcept KeyErrorand the documentedRaises: KeyErroron both methods keep working unchanged.
Fixed#
extreme_close_upframed the forehead, not the eyes. Its crop landmark (eyes) sits inside the face rather than at its edge, and the anchoring rule bottom-anchors every crop line — which put the eyes exactly on the panel’s bottom edge and the rest of the eye region, and the whole face centre, below it.extreme_close_upnow carriesfootroom: 0.45, the only lever that can move a crop line off the bottom edge; headroom cannot, because it shifts the figure down and shrinks it by exactly the same amount.docs/reference/shot_types.mdexplains why in the Resolution section, and the table now shows the footroom instead of—.scenet checksaid nothing about an unknownpose:orexpression:, thenscenet buildcrashed with a bareKeyError. The IR validates syntax and structure without knowing the puppet library exists, sopose: smirkingpassed every check and only failed once the solver tried to look it up.checknow resolves every cast member’sreference,poseandexpressionagainst the puppet library — reading it once per document, only when there is a cast to check — and reportsunknown-pose,unknown-expressionand (newly reachable fromcheck)unknown-puppet, each with aruleIdand a location naming the field. This closes thecheck/buildgap entirely rather than for two known bad field names:--deep(below) extends the same guarantee tolayoutandballoon-placement.
Upgrading#
Nothing was removed and no document stops compiling. Four things a caller should expect to see move:
Every panel that asks for
long_shotorwiderenders smaller. The two rungs at the wide end of the ladder were degenerate with no environment to show, and now that there is one they are not. This is the change most likely to be visible in your own panels.extreme_close_upframes the eyes rather than the forehead. Any panel using it renders differently, and correctly, for the first time.Panel Core output has changed for any panel with a caption.
CoreCaptiongainedfillandink, andPanelCoregainedbackdrop. All three are defaulted or optional, so a 0.5.0 document still parses andformat_versiondid not move — but a golden file captured against 0.5.0 will differ.Eleven names joined
scenet.__all__—SettingSpec,Mass,MassKind,Plane,Spans,Horizon,TimeOfDay,Weather,PLACES,PlaceandCaptionTone. Additions only; nothing was removed or renamed.
Known limitations#
A caption’s tone is checked against the palette, not against the panel it lands in. The contrast floors hold between every tone and every rung of the ladder, which is what makes them enforceable — but nothing warns you that this caption was placed over a foreground mass it barely separates from. The information is all present by the time the box is placed; the check is not written.
No yellow caption box. The classic yellow
localebox would be the first non-neutral value in the codebase, and the language has no colour policy to put it under yet. The three tones that shipped are neutral greys from an existing ladder.A caption tone is per caption, with no panel-level default. A letterer would set one once for a page; here you write it on each box that wants it.
A backdrop is tonal masses, and will not draw a specific building. That is the design, not a gap — but it does mean
place: docksgives you the docks in the way a thumbnail does, not in the way a background artist would.
0.5.0 - 2026-08-26#
Faces: a character can now look like something.
Added#
Faces. A character can now look angry, bored or asleep.
expression:on a cast member selects one by name, exactly aspose:does — because a face is the same kind of thing as a body: a small closed set of arrangements a character can be in.The odd part was that the face was already in the contract and simply never drawn. The puppets declared
eyesandchinlandmarks andeyes/mouthanchors,FaceSpecreserved a disc no balloon may cover, and the emitter drew the head as one filled circle. This is the rendering that was missing, not new modelling.Ten expressions, and they are a drawing convention.
neutral,happy,laughing,coy,bored,scared,sad,angry,shouting,surprise— Comic Chat’s emotion wheel plussurprise, taken from a system that actually rendered faces for live conversations rather than from a psychology of emotion. They are the small closed set of faces comics draw, not a claim that a person feeling anger produces this face; Barrett et al. 2019 is recorded inprior_art.mdso that claim is never reintroduced.Feature points, named after MPEG-4 FDP groups — brow, eye, nose, mouth — with a mapping to MediaPipe landmark indices in the asset contract. The groups are the reusable part; the standard’s 66 displacements are a measurement, not a notation. No jaw: the head is a circle that does not deform, so a jaw group would have nothing to move.
looking_atfinally shows on the face. Pupils are aimed at whoever a character is looking at, using a vector computed after placement and stored asCoreActor.gaze_aim. The existinggazewas the head’s forward direction — horizontal for every actor in every panel, since no pose rotates the head — so a pupil offset by it would have shown nothing that mirroring did not already show.CoreActor.face_marks, as sampled polylines and discs. Curves are sampled during compilation, so everything an expression does is a number in Panel Core and the emitter keeps making no decisions.scripts/contact_sheet.pyrenders every expression at every shot type onto one page. Whether a furrowed brow reads as anger at fourteen panel units is not a question a test can answer, and this is the instrument for answering it by looking.Two gallery examples: ten expressions across a scene, and a big close-up that is the first panel in the gallery to show a face at all.
Changed#
Level of detail. Below a threshold face radius no features are drawn, because five of them inside a head a couple of dozen units across stop being a face and become a smudge. Panels large enough to show a face are unaffected.
Upgrading#
Nothing was removed and no document stops compiling. Two things a caller might notice:
CoreActorgainedexpression,gaze_aimandface_marks. A panel whose puppets declare no features compiles exactly as before, but the shipped puppets now declare some — so Core output for any panel usingaliceorbobhas changed, and a golden file captured against 0.4.0 will differ.scenet.assets.contractgainedFeature,FeatureSpec,ExpressionSpecand the three state enums. They are puppet-authoring types and are not inscenet.__all__;expression:in a document is a plain name, aspose:is.
Known limitations#
extreme_close_upframes the forehead rather than the eyes. The crop rule anchors a shot’s landmark at the bottom of the frame, which is right for every rung except the tightest, where the landmark sits inside the thing being framed. Correct pershot_types.md, which is normative, and newly visible now that there is a face to look at.An unknown
expression:is not reported byscenet checkand fails the build with a bareKeyError, exactly as an unknownpose:has always done. Consistency was the deliberate choice; the fix belongs to the checker.
0.4.0 - 2026-08-26#
Captions: a panel can now speak in its own voice.
Added#
Captions. A panel can now state where and when it happens without a character having to explain it out loud, which is the thing writers are told not to do.
- caption: {text: "Midnight. The docks."}in YAML,CAPTION: Midnight. The docks.in a comic script.The four caption kinds are the letterers’ own —
locale,monologue,spokenandeditorial, from Blambot’s Comic Book Grammar & Tradition rather than invented, as the predicates were taken from Visual Genome. Note for anyone who guessed otherwise: “narration” is not one of them.Italic is a real face, not a skew. The italic of the same family already shipped in a declared dependency, so the three italic kinds are measured in the face they are drawn in. A synthetic oblique would measure as the roman face and draw as neither, which is exactly the disagreement between solver and emitter the lettering tier exists to prevent.
Quotation marks are lettering, so the compiler applies them. In a run of consecutive
spokencaptions each opens with a quote and only the last one closes — Blambot’s rule, objective enough to test. They are added before measurement and carried through Panel Core inlines; marks added by the emitter would not fit the box drawn for them.A caption may name an off-panel speaker.
byon aspokencaption is the one place in the language where an actor id is allowed not to resolve, and deliberately: somebody off panel is not in the cast, which is the whole point of saying they are off panel.PanelCore.captions, and a sixteenth gallery example.
Changed#
Balloons and captions are placed in one pass, sharing one reading order.
ordernow counts across both, so a caption written between two lines of dialogue takes the number between theirs. Placing every caption first would have been simpler and wrong — a caption written last would have imposed reading order on the balloons before it. Panels without captions are unaffected, which is why the Core format version did not move.
Upgrading#
Nothing was removed and no document stops compiling. A panel with no captions compiles to byte-identical Core. Three things a caller might notice:
PanelCoregainedcaptions, andCoreBalloon.orderis now a position in the panel’s whole reading order rather than an index among balloons. They differ only once a panel has a caption in it, so anything readingorderas “which balloon is this” wantsballoons.index(...)instead.scenet.__all__gainedCaptionEventandCaptionKind.solve.balloons.place_balloonsis nowplace_scriptand returns aScriptLayoutrather than a tuple of balloons.scenet.solveis internal and outside the versioning promise, but it is a name that existed and does not any more.
0.3.0 - 2026-08-26#
Diagnostics a machine can read, and the deploy that had quietly been failing for a week.
Added#
scenet checkvalidates documents without compiling them, and exits non-zero if anything is wrong. It 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.--format sarifemits SARIF 2.1.0, the OASIS standard GCC, Clang and MSVC emit and GitHub code scanning ingests directly. This matters more than the published JSON Schema does: the checks that catch what a generator actually gets wrong — every actor id resolving to a cast member, theleft_of/right_ofgraph being acyclic — aremodel_validators, and neither is expressible in JSON Schema at all. Structured diagnostics are what make a generate/validate/repair loop work.A stable rule catalogue. Every finding carries a
ruleIdsuch asscenet/unknown-actor, and those identifiers do not change across releases — aruleIdthat moves silently closes every alert referencing the old one and opens a duplicate under the new one.scenet.diagnosticsis a public module:diagnose_source,diagnose_fileandto_sarifgive the same findings without the process boundary.CI checks the gallery and uploads the result to code scanning, so a broken example becomes an annotation on the pull request that broke it.
Changed#
ScriptSyntaxErrorcarries its line as a number, not only inside the message text, so comic scripts get positions too. Lines only: a script line is prose, and a column would imply a precision the parser does not have.RuleViolationErroris a new exported error type. It is raised only inside pydantic validators and never escapes as itself, so it deliberately does not inheritScenetError— that would promise anexcept ScenetErrorclause could catch it.CI builds the playground assets, so a break there fails a pull request instead of the Pages deploy after merge.
Fixed#
Diagnostics now name the field rather than the document. pydantic reports a model-level validator’s location as
()— the whole document — because a validator has no way to say which field it was unhappy about. The two checks that matter most both knew the exact path and had nowhere to put it, so an unknown speaker reportedat <root>. It now reportsat script.0.by, in the prose output as well as in SARIF.The documentation site and playground had not deployed since
6a43750. The playground refuses a wheel older than the source it was built from — a guard that exists because a silently stale playground once cost an hour. Its freshness walk covered every file undersrc/, including__pycache__, and the Pages workflow builds the wheel then builds the documentation, where Sphinxautodocimportsscenetand the interpreter writes fresh bytecode. So every deploy compared the wheel against its own doc build and refused.v0.2.0shipped while this was broken.The stale-wheel error now names the offending file. “older than
src/” pointed at a directory of four hundred files when the culprit was one nobody thinks about.scenet checkunderstands scene documents. Apanels:document validated as a single panel reportedpanelsas an unknown key — a confident, wrong diagnostic on every valid scene file in the repository. Found while wiring the gallery into CI.
Upgrading#
Nothing was removed and no document stops compiling. Two things a caller might notice:
Diagnostic messages for unresolved actor ids and ordering cycles now name a path instead of
<root>. Anything asserting on the oldat <root>:text will need updating.scenet.errors.__all__gainedRuleViolationError.
0.2.0 - 2026-08-26#
A correctness release for the shot ladder, and a pass over the things the project says
about itself. Panels using medium_full, long_shot, full_shot or wide render
differently than they did in 0.1.0 — see below before upgrading.
Changed#
wideremains an exact synonym forlong_shot, and the gallery example now says so, so the two identical panels read as intentional rather than broken.The playground moved above the fold in
README.mdanddocs/index.md, and the repository homepage points at it. It runs the real compiler under Pyodide and it was the last section of the landing page, below the licence in reading order.docs/explanation/status.mdgained a Planned section. Its phase table stopped at 6, so everything in the tracker was invisible in the one document claiming to be authoritative. The tickets are listed without numbering them into phases, because that order is genuinely not decided.docs/index.mdnames Diátaxis. The four sections always followed it; saying so tells a contributor where a new page belongs.
Fixed#
Shots that show feet now actually show them. The crop lands the
feetlandmark on the frame edge, but the drawing continues past it: the ankle sits exactly on that landmark and the shin is a round-capped stroke, so half its width fell below. At long shot that was nine panel units hanging outside a 560-unit panel — the one thing a long shot is defined by not doing.ShotSpecgainsfootroom, non-zero only for the shots that show feet. It is also right compositionally: a figure standing on the exact bottom edge reads as falling out of the panel rather than standing on anything.medium_fullandcowboyare no longer the same shot. Both cropped atmid_thigh, so the ladder had nine rungs while claiming ten, and two adjacent panels in the gallery were identical for no reason a reader could see. Medium full — the three-quarter shot — cuts at the knees; the cowboy or American shot cuts at mid-thigh, a framing that comes from 1930s Westerns needing the holster in frame. Two tests asserted they were aliases, so the bug was pinned in place by its own test suite.The normative shot-type table was wrong.
docs/reference/shot_types.mdcalls itself normative and claimedlong_shothad a headroom of0.60; the code uses0.14. It also still listedcowboyas an alias. A test now parses that table and asserts every crop landmark and headroom matches the code — a specification nobody checks is a comment in a different file.The language reference no longer says nothing works.
docs/reference/language.mdopened by telling every reader — and every model retrieving it — that “at present, nothing compiles”, which stopped being true at phase 1, whilestatus.mdtwo clicks away listed phases 0–6 as done and called itself authoritative. The more-read document was the wrong one.
Upgrading#
No document stops compiling and no API changed. What changed is geometry, so identical input produces different SVG:
medium_fullcrops at the knees rather than mid-thigh, drawing the figure smaller.long_shot,wideandfull_shotreserve footroom, which reduces the space available to the figure and so its scale.
If you have committed .core.json or SVG output for panels using those shots, regenerate
it.
0.1.0 - 2026-08-23#
First release. A comic panel goes in as a semantic description and comes out as SVG, deterministically — constraint solving and computational geometry, with no generative image model anywhere in the pipeline.
The language#
Panel documents (
*.panel.yaml): panel size and margin, camera shot and angle, a cast of characters with poses and anchors, staging relations written as sentences (alice left_of bob), and dialogue.Sequences (
*.scene.yaml) withover:sparse override, borrowed from OpenUSD’s composition arcs: a panel names a parent and states only what differs.Comic script (
*.script), the format writers already use, with a YAML preamble for what a script has no way to say. Prose descriptions are preserved and never interpreted.
All three produce the same validated IR, so nothing downstream knows there is more than one syntax.
The compiler#
Camera framing from anatomical crop landmarks — the waist, the chest, the shoulders — rather than a fraction of panel height, so a shot type does not bake in one body and one pose. One camera and one scale per panel.
Actor placement through a Cassowary solver, with priorities: non-overlap and declared ordering are required, panel bounds are strong, requested anchors are weak. A crowded panel lets a figure bleed off the edge rather than refusing to compile.
The camera retreats when a cast will not fit across the frame, and says so, because a panel that is quietly not the shot you asked for is a panel you cannot debug.
Lettering measured against real font metrics, with line breaking scored on the shape a letterer would choose. The font is a declared dependency, never a system lookup — determinism requires text to measure identically everywhere.
Balloon placement by scored candidate search: a balloon may never cover a face, and reading order is a hard constraint checked against every predecessor rather than only the last one.
Tail routing that stops at the face outline instead of the mouth anchor buried inside the head, and bends around an obstructing face when it must.
Three tiers, all of them yours#
*.panel.yaml → IR (scene graph) → Panel Core (.core.json) → SVG
Panel Core is a real, writable format rather than a hidden data structure: a layout can be exported, read, diffed, hand-adjusted, and read back for emission.
Tools#
scenet build, with--core,--debug,--stripand--live-text.scenet schema, generating the JSON Schema from the compiler’s own models.A browser playground running the compiler unmodified under WebAssembly via Pyodide, with a Monaco editor fed that same schema, and fifteen worked examples. Entirely self-hosted: it makes no request to any other origin.
A VS Code extension with schema-driven completion, validation and a live preview.
The library#
import scenetexposes a curated public API: compiling, parsing, rendering, both intermediate tiers, the describing types, puppets and one error hierarchy rooted atScenetError.Ships
py.typed, so downstream type checkers read the annotations directly.
Documentation#
Structured on Diátaxis — tutorial, how-to, reference, explanation — and built with Sphinx. Every Python example is executed by the test suite, so an example that omits an import or has drifted out of step with the code fails the build.
Security#
Identifiers and dialogue are escaped into their SVG attributes and elements. An actor id containing a quotation mark could previously close its own attribute, which is a scripting vector wherever the output is rendered inline.
Dependency licenses are gated in CI against an explicit allowlist, checked against a runtime-only environment.
Published to PyPI through Trusted Publishing with Sigstore attestations, so the repository holds no publishing credential of any kind.
Known limitations#
Page composition — tiers, panels of varying size, the page-level reading path — is not built.
--striplays panels in a row and nothing more.There is no interpretation layer: a panel has no style, and figures render as wireframe puppets.
Prose in a comic script is preserved but never interpreted. Describing rain does not produce rain.
long_shotandfull_shotcrop at the same landmark, so with no environment to show they can differ only by headroom.