scenet 0.1.0__tar.gz

scenet-0.1.0/LICENSE

@@ -0,0 +1,14 @@
+BSD Zero Clause License (0BSD)
+
+Copyright (c) 2026 Scenet contributors
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
+FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS
+OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
+TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF
+THIS SOFTWARE.

scenet-0.1.0/PKG-INFO

@@ -0,0 +1,248 @@
+Metadata-Version: 2.4
+Name: scenet
+Version: 0.1.0
+Summary: A semantic DSL for comic panels, compiled to SVG.
+Keywords: comics,dsl,compiler,svg,layout,constraint-solving
+Author: Scenet contributors
+License-Expression: 0BSD
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Multimedia :: Graphics
+Classifier: Topic :: Software Development :: Compilers
+Classifier: Typing :: Typed
+Requires-Dist: pydantic>=2.9
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: kiwisolver>=1.4
+Requires-Dist: shapely>=2.0
+Requires-Dist: fonttools>=4.55
+Requires-Dist: numpy>=2.1
+Requires-Dist: fonts>=0.1
+Requires-Dist: font-source-sans-pro>=0.0.1
+Requires-Python: >=3.12
+Project-URL: Homepage, https://github.com/azias/scenet
+Project-URL: Documentation, https://azias.github.io/scenet/
+Project-URL: Repository, https://github.com/azias/scenet
+Project-URL: Issues, https://github.com/azias/scenet/issues
+Project-URL: Changelog, https://github.com/azias/scenet/blob/main/CHANGELOG.md
+Project-URL: Playground, https://azias.github.io/scenet/playground/
+Description-Content-Type: text/markdown
+
+# Scenet
+
+**A semantic DSL for comic panels, compiled to SVG.**
+
+## ⚠️ This project is deliberately AI-generated
+
+This project is, by design, almost entirely generated by AI. It exists as a personal training
+ground for learning to work with AI coding tools. The architecture, code, tests and documentation
+are overwhelmingly AI-authored, under human direction and review.
+
+Treat it accordingly: an experiment first, a usable tool second.
+
+---
+
+[![CI](https://github.com/azias/scenet/actions/workflows/ci.yml/badge.svg)](https://github.com/azias/scenet/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/scenet.svg)](https://pypi.org/project/scenet/)
+[![Python](https://img.shields.io/pypi/pyversions/scenet.svg)](https://pypi.org/project/scenet/)
+[![License: 0BSD](https://img.shields.io/badge/License-0BSD-brightgreen.svg)](LICENSE)
+![Status: alpha](https://img.shields.io/badge/status-alpha-orange.svg)
+
+**[Documentation](https://azias.github.io/scenet/)** ·
+**[Playground](https://azias.github.io/scenet/playground/)** ·
+**[Tutorial](https://azias.github.io/scenet/tutorial/first_panel.html)** ·
+**[Changelog](CHANGELOG.md)**
+
+## What this is
+
+Music has notation. A score describes the *semantics* of a piece — pitch, duration, dynamics —
+without describing the waveform that eventually reaches your ear. Rendering is left to an
+interpreter, human or machine.
+
+Images have no such thing. SVG describes *how to draw*, not *what is depicted*: it is closer to a
+WAV file than to a score. Scenet is an attempt at the missing layer, narrowed to one tractable
+domain — the comic panel.
+
+You write what is in the panel:
+
+```yaml
+panel:
+  size: [1000, 1000]
+camera:
+  shot: medium_shot
+  angle: eye_level
+cast:
+  alice: {reference: alice, pose: pointing,     at: left_third,  facing: right}
+  bob:   {reference: bob,   pose: arms_crossed, at: right_third, facing: left}
+staging:
+  - alice left_of bob
+  - alice looking_at bob
+script:
+  - say: {by: alice, text: "You forgot your umbrella!", prefer: top_left}
+  - say: {by: bob,   text: "I know."}
+```
+
+You can also write a sequence, where each panel states only what changed from the one
+before — borrowed from OpenUSD's sparse override, because consecutive panels in a scene
+share nearly all their staging:
+
+```yaml
+panels:
+  establishing:
+    camera: {shot: full_shot}
+    cast: {alice: {reference: alice}, bob: {reference: bob}}
+  reaction:
+    over: establishing        # same cast, same staging
+    camera: {shot: close_up}  # move in
+```
+
+Or in comic script, the format writers already use:
+
+```
+PANEL 1
+@shot: full_shot
+Alice and Bob face each other on a rainy street corner.
+
+ALICE
+You forgot your umbrella!
+
+BOB (whisper)
+I know.
+```
+
+From any of these, the compiler works out the rest: how large each figure must be for a medium shot, where they
+stand, which way they face, how big each balloon needs to be for its text, where a balloon can sit
+without covering a face, and how its tail reaches the speaker's mouth — all while preserving
+reading order.
+
+**No generative image model is involved.** This is a deterministic compiler: constraint solving and
+computational geometry. The same input always produces byte-identical output.
+
+## Status
+
+**Alpha — panels and sequences compile end to end, from the command line, the
+browser, or an editor.** Framing, actor placement, balloon
+placement, reading order, tail routing and SVG emission all work, from either of two
+frontends. Not yet built: page composition (tiers, panels of varying size) and the
+interpretation layer that would give a panel a *style*. See
+[the phase plan](docs/explanation/status.md) for detail.
+
+```bash
+uv run scenet build examples/duel.panel.yaml --core --debug
+uv run scenet build examples/sequence.scene.yaml --strip
+uv run scenet build examples/umbrella.script --strip
+```
+
+`--core` writes the resolved intermediate tier as JSON; `--debug` writes an overlay showing
+the geometry the solver was working against — silhouette hulls, face exclusion zones, anchors,
+gaze vectors and tail routes.
+
+## How it works
+
+```
+  duel.panel.yaml     →     Panel Core (.core.json)     →     panel.svg
+  authored,                 resolved, fully numeric,          rendered
+  no coordinates            still named & inspectable
+```
+
+The intermediate tier is a real, writable format rather than a hidden data structure — so layouts
+can be inspected, hand-adjusted, and diffed independently of how they are drawn. The approach is
+borrowed from Vega-Lite, which compiles a high-level grammar into a lower-level one before emitting
+SVG.
+
+## Try it in the browser
+
+The **[playground](https://azias.github.io/scenet/playground/)** runs this compiler — the
+same Python, unmodified — in your browser under WebAssembly via
+[Pyodide](https://pyodide.org/). It is not a reimplementation: the page installs the exact
+wheel `uv build` produces, so there is no second copy of the geometry to drift out of step.
+
+Fifteen worked examples, covering every shot type, every balloon kind, both frontends and
+the constraint priorities. Each one is a real file under
+[`examples/gallery/`](examples/gallery/) that the test suite compiles, so the playground
+cannot offer an example that does not work.
+
+The editor is Monaco, fed the *same* JSON Schema the VS Code extension uses — generated
+from the compiler's own models, so completion and hover documentation cannot drift from
+what compiles. Everything is served from one origin: no CDN, no analytics, nothing
+fetched from anywhere else.
+
+## Editor support
+
+The [VS Code extension](editor/) gives completion and inline validation for panel
+documents, plus a side-by-side preview. Its JSON Schema is *generated from the
+compiler's own models* by `scenet schema`, so what the editor offers is what actually
+compiles. A test fails if the shipped schema goes stale.
+
+## Install
+
+```bash
+pip install scenet
+```
+
+Python 3.12 or newer. No system libraries, no fonts to install, nothing to configure. Ships
+a `py.typed` marker, so mypy, pyright, ty and basedpyright read the annotations straight
+from the package.
+
+```python
+from scenet import compile_source, render
+
+result = compile_source("cast: {alice: {reference: alice}}")
+svg = render(result.core)
+```
+
+## Development
+
+Requires [uv](https://docs.astral.sh/uv/). It manages the Python version too, so this is the whole
+setup:
+
+```bash
+uv sync --all-groups
+uv run pytest
+```
+
+Checks, all of which run in CI:
+
+```bash
+uv run ruff check . && uv run ruff format --check .
+uv run ty check
+uv run pytest
+```
+
+## Documentation
+
+**[azias.github.io/scenet](https://azias.github.io/scenet/)** — or read the Markdown
+source under [`docs/`](docs/), which GitHub renders without a build step.
+
+| | |
+|---|---|
+| [Tutorial](docs/tutorial/first_panel.md) | Build a panel from nothing, in fifteen minutes |
+| [How-to guides](docs/howto/index.md) | Sequences, comic scripts, your own characters, using it as a library |
+| [Language specification](docs/reference/language.md) | Every construct, with examples |
+| [Shot types](docs/reference/shot_types.md) | Normative camera framing table |
+| [Panel Core](docs/reference/panel_core.md) | The resolved intermediate format |
+| [Asset contract](docs/reference/asset_contract.md) | What a character puppet must declare |
+| [API reference](docs/reference/api/index.md) | Every public name |
+| [Design decisions](docs/explanation/design_decisions.md) | Why it is shaped this way |
+| [Prior art](docs/explanation/prior_art.md) | What already exists, and what was taken from it |
+
+Every Python example in the documentation is executed by the test suite. An example that
+omits an import, or that has drifted out of step with the code, fails the build.
+
+## License
+
+**0BSD** — see [LICENSE](LICENSE). This is deliberately one step more permissive than
+MIT: you may use, copy, modify and distribute this software for any purpose, with no
+obligation to preserve a copyright notice or reproduce the license. No attribution is
+required, though it is always welcome.
+
+Third-party components are listed in [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md). The
+lettering font arrives as an ordinary dependency under the SIL Open Font License, which does
+require its own notice be kept with it.
+
+**The language specification is free to implement.** Anyone may build their own compiler, editor,
+renderer or tooling for this language, in any project, commercial or otherwise, without restriction
+or attribution. A notation is only worth having if it is not owned.

scenet-0.1.0/README.md

@@ -0,0 +1,215 @@
+# Scenet
+
+**A semantic DSL for comic panels, compiled to SVG.**
+
+## ⚠️ This project is deliberately AI-generated
+
+This project is, by design, almost entirely generated by AI. It exists as a personal training
+ground for learning to work with AI coding tools. The architecture, code, tests and documentation
+are overwhelmingly AI-authored, under human direction and review.
+
+Treat it accordingly: an experiment first, a usable tool second.
+
+---
+
+[![CI](https://github.com/azias/scenet/actions/workflows/ci.yml/badge.svg)](https://github.com/azias/scenet/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/scenet.svg)](https://pypi.org/project/scenet/)
+[![Python](https://img.shields.io/pypi/pyversions/scenet.svg)](https://pypi.org/project/scenet/)
+[![License: 0BSD](https://img.shields.io/badge/License-0BSD-brightgreen.svg)](LICENSE)
+![Status: alpha](https://img.shields.io/badge/status-alpha-orange.svg)
+
+**[Documentation](https://azias.github.io/scenet/)** ·
+**[Playground](https://azias.github.io/scenet/playground/)** ·
+**[Tutorial](https://azias.github.io/scenet/tutorial/first_panel.html)** ·
+**[Changelog](CHANGELOG.md)**
+
+## What this is
+
+Music has notation. A score describes the *semantics* of a piece — pitch, duration, dynamics —
+without describing the waveform that eventually reaches your ear. Rendering is left to an
+interpreter, human or machine.
+
+Images have no such thing. SVG describes *how to draw*, not *what is depicted*: it is closer to a
+WAV file than to a score. Scenet is an attempt at the missing layer, narrowed to one tractable
+domain — the comic panel.
+
+You write what is in the panel:
+
+```yaml
+panel:
+  size: [1000, 1000]
+camera:
+  shot: medium_shot
+  angle: eye_level
+cast:
+  alice: {reference: alice, pose: pointing,     at: left_third,  facing: right}
+  bob:   {reference: bob,   pose: arms_crossed, at: right_third, facing: left}
+staging:
+  - alice left_of bob
+  - alice looking_at bob
+script:
+  - say: {by: alice, text: "You forgot your umbrella!", prefer: top_left}
+  - say: {by: bob,   text: "I know."}
+```
+
+You can also write a sequence, where each panel states only what changed from the one
+before — borrowed from OpenUSD's sparse override, because consecutive panels in a scene
+share nearly all their staging:
+
+```yaml
+panels:
+  establishing:
+    camera: {shot: full_shot}
+    cast: {alice: {reference: alice}, bob: {reference: bob}}
+  reaction:
+    over: establishing        # same cast, same staging
+    camera: {shot: close_up}  # move in
+```
+
+Or in comic script, the format writers already use:
+
+```
+PANEL 1
+@shot: full_shot
+Alice and Bob face each other on a rainy street corner.
+
+ALICE
+You forgot your umbrella!
+
+BOB (whisper)
+I know.
+```
+
+From any of these, the compiler works out the rest: how large each figure must be for a medium shot, where they
+stand, which way they face, how big each balloon needs to be for its text, where a balloon can sit
+without covering a face, and how its tail reaches the speaker's mouth — all while preserving
+reading order.
+
+**No generative image model is involved.** This is a deterministic compiler: constraint solving and
+computational geometry. The same input always produces byte-identical output.
+
+## Status
+
+**Alpha — panels and sequences compile end to end, from the command line, the
+browser, or an editor.** Framing, actor placement, balloon
+placement, reading order, tail routing and SVG emission all work, from either of two
+frontends. Not yet built: page composition (tiers, panels of varying size) and the
+interpretation layer that would give a panel a *style*. See
+[the phase plan](docs/explanation/status.md) for detail.
+
+```bash
+uv run scenet build examples/duel.panel.yaml --core --debug
+uv run scenet build examples/sequence.scene.yaml --strip
+uv run scenet build examples/umbrella.script --strip
+```
+
+`--core` writes the resolved intermediate tier as JSON; `--debug` writes an overlay showing
+the geometry the solver was working against — silhouette hulls, face exclusion zones, anchors,
+gaze vectors and tail routes.
+
+## How it works
+
+```
+  duel.panel.yaml     →     Panel Core (.core.json)     →     panel.svg
+  authored,                 resolved, fully numeric,          rendered
+  no coordinates            still named & inspectable
+```
+
+The intermediate tier is a real, writable format rather than a hidden data structure — so layouts
+can be inspected, hand-adjusted, and diffed independently of how they are drawn. The approach is
+borrowed from Vega-Lite, which compiles a high-level grammar into a lower-level one before emitting
+SVG.
+
+## Try it in the browser
+
+The **[playground](https://azias.github.io/scenet/playground/)** runs this compiler — the
+same Python, unmodified — in your browser under WebAssembly via
+[Pyodide](https://pyodide.org/). It is not a reimplementation: the page installs the exact
+wheel `uv build` produces, so there is no second copy of the geometry to drift out of step.
+
+Fifteen worked examples, covering every shot type, every balloon kind, both frontends and
+the constraint priorities. Each one is a real file under
+[`examples/gallery/`](examples/gallery/) that the test suite compiles, so the playground
+cannot offer an example that does not work.
+
+The editor is Monaco, fed the *same* JSON Schema the VS Code extension uses — generated
+from the compiler's own models, so completion and hover documentation cannot drift from
+what compiles. Everything is served from one origin: no CDN, no analytics, nothing
+fetched from anywhere else.
+
+## Editor support
+
+The [VS Code extension](editor/) gives completion and inline validation for panel
+documents, plus a side-by-side preview. Its JSON Schema is *generated from the
+compiler's own models* by `scenet schema`, so what the editor offers is what actually
+compiles. A test fails if the shipped schema goes stale.
+
+## Install
+
+```bash
+pip install scenet
+```
+
+Python 3.12 or newer. No system libraries, no fonts to install, nothing to configure. Ships
+a `py.typed` marker, so mypy, pyright, ty and basedpyright read the annotations straight
+from the package.
+
+```python
+from scenet import compile_source, render
+
+result = compile_source("cast: {alice: {reference: alice}}")
+svg = render(result.core)
+```
+
+## Development
+
+Requires [uv](https://docs.astral.sh/uv/). It manages the Python version too, so this is the whole
+setup:
+
+```bash
+uv sync --all-groups
+uv run pytest
+```
+
+Checks, all of which run in CI:
+
+```bash
+uv run ruff check . && uv run ruff format --check .
+uv run ty check
+uv run pytest
+```
+
+## Documentation
+
+**[azias.github.io/scenet](https://azias.github.io/scenet/)** — or read the Markdown
+source under [`docs/`](docs/), which GitHub renders without a build step.
+
+| | |
+|---|---|
+| [Tutorial](docs/tutorial/first_panel.md) | Build a panel from nothing, in fifteen minutes |
+| [How-to guides](docs/howto/index.md) | Sequences, comic scripts, your own characters, using it as a library |
+| [Language specification](docs/reference/language.md) | Every construct, with examples |
+| [Shot types](docs/reference/shot_types.md) | Normative camera framing table |
+| [Panel Core](docs/reference/panel_core.md) | The resolved intermediate format |
+| [Asset contract](docs/reference/asset_contract.md) | What a character puppet must declare |
+| [API reference](docs/reference/api/index.md) | Every public name |
+| [Design decisions](docs/explanation/design_decisions.md) | Why it is shaped this way |
+| [Prior art](docs/explanation/prior_art.md) | What already exists, and what was taken from it |
+
+Every Python example in the documentation is executed by the test suite. An example that
+omits an import, or that has drifted out of step with the code, fails the build.
+
+## License
+
+**0BSD** — see [LICENSE](LICENSE). This is deliberately one step more permissive than
+MIT: you may use, copy, modify and distribute this software for any purpose, with no
+obligation to preserve a copyright notice or reproduce the license. No attribution is
+required, though it is always welcome.
+
+Third-party components are listed in [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md). The
+lettering font arrives as an ordinary dependency under the SIL Open Font License, which does
+require its own notice be kept with it.
+
+**The language specification is free to implement.** Anyone may build their own compiler, editor,
+renderer or tooling for this language, in any project, commercial or otherwise, without restriction
+or attribution. A notation is only worth having if it is not owned.

scenet-0.1.0/pyproject.toml

@@ -0,0 +1,183 @@
+[project]
+name = "scenet"
+version = "0.1.0"
+description = "A semantic DSL for comic panels, compiled to SVG."
+readme = "README.md"
+requires-python = ">=3.12"
+license = "0BSD"
+license-files = ["LICENSE"]
+keywords = [
+    "comics",
+    "dsl",
+    "compiler",
+    "svg",
+    "layout",
+    "constraint-solving",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Multimedia :: Graphics",
+    "Topic :: Software Development :: Compilers",
+    "Typing :: Typed",
+]
+dependencies = [
+    "pydantic>=2.9",
+    "pyyaml>=6.0",
+    "kiwisolver>=1.4",
+    "shapely>=2.0",
+    "fonttools>=4.55",
+    "numpy>=2.1",
+    "fonts>=0.1",
+    "font-source-sans-pro>=0.0.1",
+]
+
+[[project.authors]]
+name = "Scenet contributors"
+
+[project.urls]
+Homepage = "https://github.com/azias/scenet"
+Documentation = "https://azias.github.io/scenet/"
+Repository = "https://github.com/azias/scenet"
+Issues = "https://github.com/azias/scenet/issues"
+Changelog = "https://github.com/azias/scenet/blob/main/CHANGELOG.md"
+Playground = "https://azias.github.io/scenet/playground/"
+
+[project.scripts]
+scenet = "scenet.cli:main"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.3",
+    "pytest-cov>=6.0",
+    "sybil>=10.1",
+    "ruff>=0.14",
+    "ty>=0.0.73",
+    "basedpyright>=1.31",
+    "pip-licenses>=5.0",
+    "types-pyyaml>=6.0",
+]
+docs = [
+    "sphinx>=9.1",
+    "myst-parser>=5.1",
+    "pydata-sphinx-theme>=0.20",
+    "sphinx-design>=0.7",
+    "sphinx-copybutton>=0.5.2",
+    "sphinx-autodoc-typehints>=3.13",
+    "sphinx-autobuild>=2025.8.25",
+    "linkify-it-py>=2.0",
+]
+
+[build-system]
+requires = ["uv_build>=0.12.5,<0.13.0"]
+build-backend = "uv_build"
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+src = [
+    "src",
+    "tests",
+]
+
+[tool.ruff.lint]
+select = [
+    "E",
+    "W",
+    "F",
+    "I",
+    "N",
+    "UP",
+    "ANN",
+    "B",
+    "C4",
+    "SIM",
+    "TC",
+    "PGH",
+    "PT",
+    "PL",
+    "RUF",
+    "D",
+    "S",
+    "A",
+    "RET",
+    "PTH",
+    "TRY",
+]
+ignore = [
+    "PLR0913",
+    "PLR2004",
+    "TRY003",
+    "TRY004",
+    "TC001",
+    "TC002",
+    "TC003",
+]
+
+[tool.ruff.lint.flake8-type-checking]
+quote-annotations = false
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = [
+    "ANN",
+    "PLR2004",
+    "S101",
+    "S314",
+    "D",
+    "RUF012",
+    "SLF001",
+]
+"src/scenet/__init__.py" = ["RUF022"]
+"docs/conf.py" = [
+    "D",
+    "A",
+    "INP",
+]
+
+[tool.ruff.format]
+docstring-code-format = true
+
+[tool.ty.src]
+include = [
+    "src",
+    "tests",
+]
+
+[tool.ty.rules]
+possibly-unresolved-reference = "error"
+
+[tool.basedpyright]
+include = [
+    "src",
+    "tests",
+]
+typeCheckingMode = "strict"
+pythonVersion = "3.12"
+reportMissingTypeStubs = false
+
+[tool.pytest.ini_options]
+testpaths = [
+    "tests",
+    "src",
+    "docs",
+    "README.md",
+]
+addopts = "    -q --strict-markers --strict-config --doctest-modules     --cov=scenet --cov-report=term-missing --cov-fail-under=90"
+xfail_strict = true
+
+[tool.coverage.run]
+branch = true
+source = ["src/scenet"]
+
+[tool.coverage.report]
+exclude_also = [
+    "if TYPE_CHECKING:",
+    "raise NotImplementedError",
+    "if __name__ == .__main__.:",
+]