pandid 0.1.0rc1__tar.gz

pandid-0.1.0rc1/.github/workflows/ci.yml

@@ -0,0 +1,69 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  # The release workflow calls these same gates on the tagged commit, so a
+  # release runs the matrix that is actually maintained rather than a copy.
+  workflow_call:
+
+permissions:
+  contents: read
+
+# Cancel superseded runs on the same ref (e.g. rapid pushes to a PR branch).
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    name: Lint (ruff)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+      - name: ruff check
+        run: ruff check .
+      - name: ruff format (tests must stay formatted)
+        run: ruff format --check tests
+
+  typecheck:
+    name: Type check (mypy)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+      - name: mypy
+        run: mypy pandid
+
+  test:
+    name: Tests (py${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+      - name: pytest
+        run: pytest -q

pandid-0.1.0rc1/.github/workflows/release.yml

@@ -0,0 +1,65 @@
+name: Release
+
+# Publishing is driven by the tag, not by a branch: pushing `v0.1.0` cuts the
+# release. The tag must name the version in pandid/__init__.py — the build job
+# below refuses to go on if it does not.
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+jobs:
+  # Re-run the full CI matrix against the tagged commit: a tag can point at a
+  # commit that never went through a pull request.
+  gates:
+    name: Gates
+    uses: ./.github/workflows/ci.yml
+
+  build:
+    name: Build sdist + wheel
+    needs: [gates]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Tag must match pandid.__version__
+        run: |
+          tag="${GITHUB_REF_NAME#v}"
+          src="$(python -c 'import pandid; print(pandid.__version__)')"
+          if [ "$tag" != "$src" ]; then
+            echo "::error::tag $GITHUB_REF_NAME does not name pandid.__version__ ($src)"
+            exit 1
+          fi
+      - name: Build
+        run: |
+          python -m pip install --upgrade pip
+          pip install build twine
+          python -m build
+      - name: Check the metadata PyPI will render
+        run: twine check --strict dist/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: [build]
+    runs-on: ubuntu-latest
+    # Named environment so the repository owner can require a manual approval,
+    # and so the PyPI trusted publisher can be scoped to it, before any upload.
+    environment:
+      name: pypi
+      url: https://pypi.org/p/pandid
+    permissions:
+      id-token: write   # mint the OIDC token PyPI trusted publishing exchanges
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

pandid-0.1.0rc1/.gitignore

@@ -0,0 +1,43 @@
+# Byte-compiled / optimized files
+__pycache__/
+*.py[cod]
+
+# Packaging / build
+build/
+dist/
+*.egg-info/
+
+# Virtual environments
+.venv/
+venv/
+
+# Tooling caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# uv lockfile (not committed for this library)
+uv.lock
+
+# Generated diagram output (reproducible from examples/)
+*.svg
+# ...but the golden fixtures are source, not output: the regression suite has
+# nothing to compare against if these are ignored.
+!tests/golden/*.svg
+# ...and the gallery is documentation: docs/gallery/README.md has nothing to
+# show if these are ignored. Regenerate by running examples/ (see that README).
+!docs/gallery/*.svg
+
+# Agent / harness working files
+.agents/
+.superpowers/
+skills-lock.json
+
+# local render artifacts
+renders/
+
+# Reference drawings (third-party coursework; kept local, not redistributed)
+professional_examples/
+
+# Agent worktrees (created per-run under .claude/, never part of the project)
+.claude/worktrees/

pandid-0.1.0rc1/.pre-commit-config.yaml

@@ -0,0 +1,19 @@
+# Local commit-time checkers, mirroring CI. Enable with:
+#   pip install pre-commit && pre-commit install
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.14
+    hooks:
+      - id: ruff            # lint the whole tree (auto-fixes what it safely can)
+        args: [--fix]
+      - id: ruff-format     # keep the test suite formatted
+        files: ^tests/
+
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-toml
+      - id: check-merge-conflict

pandid-0.1.0rc1/CHANGELOG.md

@@ -0,0 +1,156 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-07-28
+
+First public release. Nothing was published before it, so everything below is the
+initial feature set rather than a change to something users have, and the entries
+are headlines rather than a description of the library. `README.md` is the tour,
+[`docs/api.md`](docs/api.md) is the reference, and
+[`docs/gallery/README.md`](docs/gallery/README.md) walks the eleven examples.
+Later releases will list changes rather than capabilities.
+
+### Added
+
+- **Topology.** `Flowsheet` is the container and the single source of truth for
+  connectivity, with `add()`, `connect()`, `add_component()` and
+  `add_annotation()`. 28 typed `Unit` classes declare named ports reachable as
+  `unit.ports[name]` or as attributes (`pump.suction`), and a typo raises an
+  error naming the real ports. `connect()` validates every connection: outlet to
+  inlet only, both units on the same flowsheet, one stream per port, and signal
+  against process. A `Unit` subclass of your own declaring its `kind` and
+  `PORTS` is laid out, routed and drawn like a shipped class.
+- **Assemblies and branching.** `Tee` is the pipe tee, drawn as bare pipe and
+  scheduled nowhere, so a bypass, a drain, a vent or a PSV takeoff no longer puts
+  equipment on the sheet that the plant does not contain.
+  `Flowsheet.add_valve_station()` builds the eight devices and four tees a
+  control valve is installed in, in one call.
+- **Numbering.** Automatic stream numbers carry one number *through* inline
+  valves, reducers and fittings. Line numbers (`size`, `schedule`, `service`,
+  `spec`, `insulation`, plus an auto-filled `sequence`) are assembled by
+  `line_numbering_scheme` and assigned by the same pass, so a line number
+  survives an in-line fitting and breaks where the spec break is marked.
+- **Layout.** Sugiyama-style automatic layout: cycle breaking, layer assignment,
+  crossing reduction and coordinate assignment, with the main flow line
+  straightened onto one axis. The geometry model separates intent (`Pin`, written
+  only by `Unit.pin()`) from result (`Frame`, written only by the engine), which
+  is what makes `layout()` idempotent. `pin()` takes a grid cell or exact
+  coordinates, a quarter turn, a mirror, and `port=` to place a **nozzle** rather
+  than a corner. Port faces and equipment tags are then chosen automatically from
+  where each peer actually landed, and `nozzle()` overrides that pick where a
+  drawing convention has to be stated.
+- **Routing.** Orthogonal A\* over a visibility graph, with port anchors projected
+  onto unit boundaries, used-edge penalties so runs do not overlap, crossing
+  jump-gaps, and separation of co-located parallel runs. `Stream.via([...])`
+  forces explicit waypoints. `route()` places attached instruments and re-routes
+  until the two agree rather than trading a fixed number of passes.
+- **Rendering.** SVG with **no runtime dependencies**; `.pdf` and `.png` go
+  through the optional `cairosvg` backend. `page_size="A4"`..`"A0"` draws a sheet
+  of exactly that ISO 216 size, `border="zone"` rules the ASME-style zone frame,
+  and `diagram="p&id"` draws process lines without arrowheads. Signal lines are
+  drawn at half the weight of process pipe, the 2:1 ratio ISO 15519-1 §6.2
+  requires. A `TitleBlock`, `Revision` rows, and docked `Annotation` / `TableBox`
+  furniture (`equipment_list()`, `notes()`, `legend()`) are sheet furniture drawn
+  whatever the border, and every cell is measured before it is written into, so
+  text that cannot fit is reported on `fs.warnings` rather than drawn across a
+  rule.
+- **Symbols.** 139 registered `(kind, variant)` pairs across 28 kinds, generated
+  from the draw.io / diagrams.net P&ID stencils by `scripts/vendor_symbols.py`
+  and matched to ISO 10628-2 where a symbol exists. Feed/Product flags, the
+  variable-port Mixer and Splitter, the pipe tee and the ANSI/ISA-5.1 balloons are
+  hand-drawn originals. Every port is checked to land on drawn ink, at every box
+  shape a unit can be given. `variant=` is checked against the registry, so a
+  typo raises naming the nearest match rather than reaching the printer.
+- **Instrumentation (ISA-5.1).** `add_instrument()` and the `Instrument` unit
+  draw the functional letters over a loop number, in six balloon variants plus
+  the two trip squares ANSI/ISA-5.1-2009 distinguishes. `Instrument.attach()`
+  anchors a balloon to the stream or equipment it reads, with an impulse line to
+  the tap. Typed signal lines (`electric`, `pneumatic`, `data`, `software`,
+  `capillary`) are legal only between two signal connections.
+  `Flowsheet.add_loop()` declares a control loop, so the loop number is typed
+  once and each balloon's own letters are checked against it.
+- **Valve marking.** `Valve(normal_position="closed")` darkens the body
+  (PIP PIC001 4.2.2.7) or writes `NC` beside it where a filled body would hide
+  the device (ISO 15519-1 §11.4.5), and refuses on a control or relief valve
+  (clause 4.2.2.10). `Valve(fail=...)` writes the six ANSI/ISA-5.1-2009 Table
+  5.4.4 codes beside an actuated valve. `Fitting(variant="blind")` takes the same
+  `normal_position` and changes shape rather than fill.
+- **Validation.** `Flowsheet.validate()` returns `Issue` records, errors first.
+  Errors such as overlapping pinned units raise from `render()` rather than emit
+  a silently wrong drawing; warnings such as a route crossing a unit body, a tag
+  whose letters are out of ISO 15519-2 §5.2.4 order, or a gravity-dependent
+  symbol given a quarter turn collect on `fs.warnings`.
+- **Spec format.** `Flowsheet.to_dict()` / `from_dict()` round-trip the whole
+  topology as JSON-safe data, and `pandid.spec` reads the same shape from YAML or
+  JSON. An unknown key is rejected rather than ignored, and the message names the
+  key it was probably meant to be.
+- **Command line.** A `pandid` command, installed with the distribution:
+  `pandid draw plant.yaml -o plant.pdf --page-size A3 --border zone`,
+  `pandid validate plant.yaml`, and `pandid symbols --kind valve`. Exit codes a
+  build script can gate on, and every user-provokable failure is one line on
+  stderr rather than a traceback. Built on `argparse`, so the package still has
+  no runtime dependencies.
+- **Packaging and tooling.** `pandid/py.typed` (PEP 561), a golden-SVG regression
+  suite, symbol- and route-invariant suites, CI on Python 3.10 to 3.13, and a
+  release workflow that checks the tag against `pandid.__version__` and publishes
+  over PyPI Trusted Publishing. `pandid.__version__` is the only place the version
+  is written; the build backend reads it from there.
+
+### Changed
+
+Two attributes were renamed on the way to this release. Nothing was published, so
+there is no alias and the old spellings simply do not exist. **Both are also spec
+keys**, so a YAML or JSON file written against a pre-release checkout has to be
+edited: the reader rejects an unknown key rather than ignoring it, and names the
+new one.
+
+- `Unit.significant` is now **`Unit.new_line_number`**, and the unit spec key
+  `significant:` is now `new_line_number:`. It marks the inline item at which a
+  line number breaks and a new one starts, which is what the new name says and
+  the old one did not.
+- `connect(tear_hint=...)` and `Stream.tear_hint` are now
+  **`draw_as_recycle`**, and the stream spec key `tear_hint:` is now
+  `draw_as_recycle:`. It marks a stream to be drawn as a recycle loop.
+
+Neither rename changes a drawn sheet: every golden fixture and all eleven example
+SVGs are byte-identical across it.
+
+### Removed
+
+The deprecated aliases, on the same reasoning: nothing has been published, so
+keeping them preserves compatibility with code that cannot exist. This follows the
+clean breaks already made for `hot_*` to `shell_*` on heat-exchanger nozzles.
+
+- `styling=` on `to_svg()` / `render()`. Use `border="zone"` and
+  `diagram="p&id"`, which are independent and name the two things it bundled.
+- `anchor=` on `Annotation`, `TableBox`, `equipment_list()`, `notes()` and
+  `legend()`. Use `align=`.
+- `Unit.port_face()`. Use `Unit.nozzle()`, whose `face` is the compass point on
+  the finished sheet. The two disagreed on a rotated or mirrored unit, since
+  `port_face()` read its face in the symbol's own frame, so **rewrite each call
+  site with the face the reader sees** rather than substituting the name (#26).
+- `Symbol.port_alts` and `Symbol.free_ports`. Declare the whole menu, home
+  placement included, in `Symbol.port_faces`; the faceless set is
+  `Symbol.faceless_ports`.
+- `Unit._PORTS`. Use `Unit.PORTS`, the same list of `(name, direction, role)`
+  tuples under a name that does not tell the one attribute a subclass must set
+  that it is private.
+
+### Licence
+
+Licensed under the **PolyForm Small Business License 1.0.0**: free for
+individuals, research, teaching, and companies under 100 people and 1,000,000 USD
+revenue; a commercial licence is required above either threshold. Source-available
+rather than OSI open source.
+
+The vendored draw.io symbol geometry remains **Apache-2.0**, as that licence
+requires. The stencil artwork carries one additional field-of-use restriction on
+top of that grant, naming Atlassian products and marketplace distribution and
+excluding diagram output; `NOTICE` reproduces it in full, lists exactly which
+files fall under which licence, and both texts ship in the distribution.
+
+[0.1.0]: https://github.com/Alpha9463/pandid/releases/tag/v0.1.0

pandid-0.1.0rc1/CONTRIBUTING.md

@@ -0,0 +1,301 @@
+# Contributing to `pandid`
+
+Thanks for helping. This covers setup, the checks that have to pass, and the
+four things about this codebase a new contributor will otherwise get wrong.
+
+## Setup
+
+Python 3.10+ (CI tests 3.10 – 3.13). From a checkout:
+
+```bash
+pip install -e '.[dev]'          # pytest, ruff, mypy
+pip install -e '.[dev,pdf]'      # ...plus cairosvg, if you need PDF/PNG export
+```
+
+The package has **zero runtime dependencies** and must stay that way: `pandid/` may
+import only the Python standard library. `cairosvg` is optional and is imported
+lazily inside `Flowsheet.render()`, only when the output path ends in `.pdf` or
+`.png`.
+
+Optionally install the commit hooks, which mirror the CI lint gates:
+
+```bash
+pip install pre-commit && pre-commit install
+```
+
+## The gates
+
+All four must pass. CI (`.github/workflows/ci.yml`) runs the same four.
+
+```bash
+python -m pytest -q                 # tests (CI: pytest -q on 3.10/3.11/3.12/3.13)
+python -m ruff check .              # lint the whole tree
+python -m ruff format --check tests # tests/ must stay ruff-formatted
+python -m mypy pandid                  # type check (blocking, not advisory)
+```
+
+`ruff format` is enforced on `tests/` only. The rest of the tree is linted but
+not auto-formatted, so don't reformat `pandid/` in a feature PR.
+
+Keep a PR to one concern. If a change touches rendering, say so and show what
+moved (see *Goldens* below).
+
+## Where things live
+
+1. **Topology** (`pandid/flowsheet.py`, `pandid/units.py`, `pandid/ports.py`,
+   `pandid/streams.py`) holds units, ports and stream connectivity.
+2. **Geometry.** `pandid/layout/` runs Sugiyama layering, then ordering, then
+   coordinates, emitting each unit's resolved `Frame`, and finally port-face
+   selection and label placement. `pandid/portgeom.py` is the single source of
+   truth for port geometry, and `pandid/routing/` is the visibility graph and
+   the A\* search over it.
+3. **Render** (`pandid/render/`) produces the SVG output and the symbol
+   registry, with `pandid/validate.py` and `pandid/document.py` beside it.
+
+Geometry separates *intent* (`Pin`, written by `pin()`) from *result* (`Frame`,
+written by the layout engine), which is what makes `layout()` idempotent.
+
+`scripts/vendor_symbols.py` generates the symbol library into
+`pandid/render/_vendored_symbols.py`, converting mxGraph stencil XML to SVG via
+`scripts/mxgraph_to_svg.py`. `scripts/symbol_sheet.py` renders a catalogue.
+
+---
+
+## 1. Symbols come from the vendored stencils, never from hand-editing
+
+`pandid/render/_vendored_symbols.py` is **generated**, and its own docstring says
+so: draw.io-derived equipment symbols under Apache-2.0, generated by
+`scripts/vendor_symbols.py`, not to be edited by hand, with attribution in
+`NOTICE`. The file is regenerated wholesale, so a hand edit is lost the next
+time anyone runs the generator and the drawing silently reverts.
+
+The pipeline is:
+
+```
+scripts/vendor_data/drawio/*.xml     mxGraph stencil XML, vendored from jgraph/drawio
+        │
+        ├── scripts/mxgraph_to_svg.py      stencil XML -> plain SVG
+        │
+        └── scripts/vendor_symbols.py      KIND_MAP: (kind, variant) -> stencil shape + ports
+                    │
+                    ▼
+        pandid/render/_vendored_symbols.py    generated; registered last, overriding
+                                           the hand-drawn defaults of the same kind
+```
+
+To add or change an equipment symbol:
+
+1. Add an entry to `KIND_MAP` in `scripts/vendor_symbols.py`, naming the stencil
+   file, the shape, and where each port lands. A port is either a named draw.io
+   `<constraint>` anchor (`"W"`, `"E"`, `"N"`, `"S"`, …) or an explicit
+   placement on a bounding-box edge.
+2. Regenerate:
+
+   ```bash
+   python scripts/vendor_symbols.py
+   ```
+
+3. Review it visually. `python scripts/symbol_sheet.py out.svg` draws every
+   registered `(kind, variant)` in a labelled grid with a red dot on each port
+   anchor. It is a dev tool, not part of the package.
+4. Commit the regenerated `_vendored_symbols.py` with your `KIND_MAP` change,
+   never one without the other.
+
+The shape's `aspect` comes across with it, as `Symbol.stretchable`. The stencil
+author has already answered whether the drawing may be reshaped to fill a box of
+another shape (`aspect="variable"`, mxGraph's default) or has to keep its
+proportions (`aspect="fixed"`), and that is the same question a unit given an
+explicit `width` and `height` asks. Every shape `KIND_MAP` names today is a
+variable one, because the 24 fixed shapes in the stencil set are draw.io's own
+instrument balloons, which `pandid` draws itself, so no generated symbol carries
+the keyword. Do not set it by hand on one: change the stencil mapping, or say so
+in `symbols.py` if the symbol is hand-drawn.
+
+Only a handful of symbols are hand-drawn in `pandid/render/symbols.py`: the
+Feed/Product boundary flags, the variable-port Mixer and Splitter, and the
+ISA-5.1 instrument balloons. Those are original primitives, not stencils. New
+*equipment* should come from the stencils, so the sheet stays visually
+consistent and `NOTICE` remains the whole attribution story.
+
+### Symbols that have to stretch
+
+There is a third case, and today it has one member. The generator emits one
+fixed-size `Symbol` per shape, and a fixed drawing lands in whatever box its
+unit is given: reshaped to fill it, or held to its own proportions and centred
+in it. Some artwork survives neither. Stretching a belt conveyor draws its
+rollers as ellipses; holding its proportions instead draws a short conveyor
+adrift in a long box. A symbol the user is meant to resize along *one* axis,
+leaving the rest of it alone, cannot come out of the generator at all.
+
+Such a symbol is written as a *builder* in `pandid/render/symbols.py`, taking the
+size and returning a `Symbol` drawn at it, and `SymbolRegistry.for_unit()`
+resolves it against the unit. Because the artwork is built to the size, the
+`<defs>` entry is per size and the placed box is exactly the box it was drawn
+in, so the scale factor is 1 and every rotation and mirror still works the way
+it does for a fixed symbol.
+
+It is still stencil-derived and still Apache-2.0. Adapting one means:
+
+1. write the builder in `pandid/render/symbols.py`, with a comment naming the
+   stencil file, the shape, and what was changed;
+2. record it in `ADAPTED_ELSEWHERE` in `scripts/vendor_symbols.py`, so the
+   mapping table stays the place provenance is looked up;
+3. name it and its file in `NOTICE` section 2. It is not an original primitive
+   and does not belong in the section 1 paragraph that lists those.
+
+Do not reach for this to avoid vendoring. A symbol with a fixed size goes
+through `KIND_MAP` like everything else.
+
+## 2. Every port must land on drawn ink
+
+A nozzle floating in whitespace draws a stream that fails to touch its
+equipment. `tests/test_symbol_invariants.py` enforces this over **every**
+registered `(kind, variant)`, not just the ones the examples use:
+
+- the symbol SVG parses and declares a `stroke-width`;
+- every port, and every alternate face in `port_faces`, lies inside the symbol's
+  declared bounding box;
+- every port and alternate is within `GEOM_TOL` (2 units) of the nearest drawn
+  stroke, measured against the SVG primitives flattened to line segments;
+- no two *different* ports resolve to the same point, which would stack two
+  streams on one pixel;
+- and the same again on a *rendered sheet*, with every unit forced into box
+  shapes nothing is drawn at: much wider than tall, much taller than wide,
+  square. A unit given an explicit `width`/`height` is drawn at that box, so
+  this is where the artwork and the ports can drift apart: the rectangle the
+  drawing lands in is read back out of the SVG and the resolved nozzle is
+  measured against it.
+
+That last one is what `Symbol.stretchable` answers. A symbol that may be
+reshaped fills the box, and its ports map onto it linearly. One that may not,
+an instrument balloon being a circle because ISA-5.1 says a circle, keeps its
+aspect and is centred, and `pandid.portgeom.ink_box` is what keeps its ports on
+the drawing rather than out in the whitespace beside it. The vendored symbols
+take the answer from the stencil's own `aspect` attribute, as section 1 above
+describes.
+
+If that suite fails on your symbol, **move the port onto the geometry**. Adding
+the symbol to `_KNOWN_GEOMETRY_GAPS` is not the fix, and a PR that does it will
+be sent back. That set fences off three pre-existing, *deliberate* cases: the
+pump and compressor suction nozzles, which sit in the mouth of an opening the
+casing is drawn around.
+
+The one legitimate escape hatch is `Symbol.faceless_ports`. An instrument
+balloon is a circle, so its signal connections have no face of their own and may
+offer the same faces as each other. Faceless ports are still checked against the
+nozzles that do own a face, and equipment nozzles are never faceless.
+
+## 3. Goldens: a changed golden means changed rendering
+
+`tests/golden/*.svg` are committed SVG fixtures, one per fixed scenario, and
+`tests/test_golden.py` renders each scenario and compares. They are *source*,
+not build output, which is why `.gitignore`'s blanket `*.svg` rule carries a
+`!tests/golden/*.svg` negation.
+
+The comparison runs on normalized text (`_normalize` canonicalizes the `<defs>`
+ordering, which depends on the process hash seed and on nothing about the
+diagram). Every other line compares verbatim, so a real regression fails.
+
+After an *intentional* rendering change:
+
+```bash
+PANDID_UPDATE_GOLDEN=1 python -m pytest tests/test_golden.py -q
+```
+
+(on Windows PowerShell: `$env:PANDID_UPDATE_GOLDEN=1; python -m pytest tests/test_golden.py -q`)
+
+Then **read `git diff tests/golden/` before committing**. A golden diff is the
+diagram changing for every user, so the PR has to say what changed and why, with
+the before/after visible. "the test was red" is not a reason. If you cannot
+explain the diff, you have found a bug, not a golden that needed updating.
+
+`tests/golden/README.md` explains why the fixtures are rebuilt inline in
+`test_golden.py` rather than by running `examples/*.py`. Those scripts write
+into `examples/`, and `03`'s title block would stamp today's date into the
+fixture. Read it before adding a scenario.
+
+## 4. Port geometry goes through `pandid/portgeom.py`
+
+Layout, routing, and rendering must never compute a port position
+independently. They all call into `pandid/portgeom.py`, the single source of truth
+for a unit's resolved size and its port coordinates.
+
+The bug it prevents actually happened: the renderer forgot a mirror flip the
+router had applied, and every mirrored unit's streams drew visually detached
+from their nozzles.
+
+- `resolve_size(unit)` gives the intrinsic `(w, h)` of a unit's placed box.
+- `symbol_to_box(...)` maps a point from the symbol's own coordinates into the
+  placed box, applying mirroring **first** and then the clockwise quarter turn,
+  which is exactly the order the renderer's SVG transform composes in.
+- `ink_box(...)` gives the rectangle inside that box the artwork actually
+  occupies: the whole of it for a symbol that may be reshaped, and the centred,
+  aspect-preserving part of it for one that may not. Ports are resolved against
+  *that*, so a symbol drawn smaller than its box keeps its nozzles on the
+  drawing. `unit_box()` stays the full placed box, since that is the space the
+  unit occupies and what the router has to route around.
+- `port_point(unit, frame, name)` is where a stream visually attaches.
+- `port_anchor(unit, frame, name)` is the routing anchor, projected onto the
+  bounding-box edge, plus the outward direction.
+- `unit_box(unit, frame)` is the true drawn bounding box the router treats as an
+  obstacle.
+
+Every one of these takes the resolved box explicitly rather than reading
+`unit.frame`, so the same code works during layout (on a `_Slot`) and afterwards
+(on a `Frame`). If you find yourself writing `frame.x + something` to find a
+nozzle, stop and use `portgeom`.
+
+The related invariant on the geometry model: `Pin` is *intent*, written only by
+`Unit.pin()` and never by the engine, and `Frame` is *result*, written only by
+the layout engine. The solver reseeds from `Pin` on every run, which is what
+makes `layout()` idempotent. Don't write coordinates back onto a `Pin`.
+
+---
+
+## Examples and the gallery
+
+`examples/*.py` are runnable scripts and are checked by `ruff`. They render into
+`examples/` (gitignored). The gallery under `docs/gallery/` is generated by
+running them and copying the output, as `docs/gallery/README.md` describes. If
+you add an example, add it to the gallery in the same PR, and consider adding
+the scenario to `tests/test_golden.py`.
+
+## Releasing
+
+The version is written in exactly one place, `pandid/__init__.py`. `pyproject.toml`
+declares it `dynamic` and the build backend reads that literal, so there is no
+second copy to forget. To cut a release, bump `__version__`, move the CHANGELOG
+`[Unreleased]` heading to the new number, merge, then push the matching tag.
+
+```bash
+git tag v0.1.0 && git push origin v0.1.0
+```
+
+`.github/workflows/release.yml` takes it from there. It re-runs the four gates
+against the tagged commit, refuses to build if the tag and `pandid.__version__`
+disagree, builds the sdist and wheel, and publishes to PyPI over Trusted
+Publishing. Nothing is uploaded from a laptop and there is no API token to leak.
+
+## Reporting a bug
+
+Include the flowsheet that reproduces it (the topology is usually 15 lines) and
+the SVG you got. `fs.validate()` returns the engine's own findings, errors first
+and then warnings, and is usually the fastest way to describe what went wrong.
+
+## Licence
+
+The engine is under the [PolyForm Small Business License
+1.0.0](https://polyformproject.org/licenses/small-business/1.0.0), free for
+individuals, research, teaching and small companies. A commercial licence is
+required above 100 people or 1,000,000 USD revenue. It is source-available
+rather than OSI open source.
+
+By opening a pull request you agree that your contribution is licensed under
+those same terms, and that the maintainer may also offer it under a commercial
+licence. If that is not something you want, say so in the PR and it will not be
+merged rather than left ambiguous.
+
+Symbols derived from the draw.io / diagrams.net P&ID stencils are **Apache-2.0**
+and stay that way. That licence permits the surrounding work to be licensed
+differently only while its own terms and attribution are preserved. If you
+vendor anything new, add it to the file list in `NOTICE` in the same PR.