postsvg 0.1.0 → 0.3.0

data/TODO.roadmap/10-visitor.md

@@ -0,0 +1,58 @@
+# 10 — PsVisitor (OCP dispatch)
+
+## Status: [x]
+
+## Why
+
+The legacy `Interpreter#execute_operator` is a 50-arm `case op`
+statement. Adding a new operator means editing the statement; the OCP
+forbids this. The new visitor uses Ruby's `Module#register` /
+`Object#const_get` pattern (mirrors `emfsvg`'s `HANDLERS` hash but
+uses the model's own double-dispatch so adding an operator is one
+class).
+
+## Tasks
+
+- [x] `Postsvg::Visitors::PsVisitor` — `accept`s `Model::Operator`
+  subclasses via `op.accept(self, ctx)`. Each operator implements
+  `accept` to call `visitor.visit_<name>(self, ctx)`.
+- [x] Visitor has one `visit_*` method per operator. Each lives in its
+  own file under `lib/postsvg/visitors/ps_visitor/<category>.rb` so
+  adding a category is a new file, not an edit.
+- [x] Unknown operators (`Model::UnknownOperator`) hit
+  `visit_unknown`, which emits an XML comment
+  `<!-- unhandled: NAME -->` in verbose mode and is a no-op otherwise.
+
+## Adding a new operator (worked example)
+
+Suppose we want to add `setdash` (already exists; this is just the
+shape of the work):
+
+1. Create `lib/postsvg/model/operators/graphics_state/setdash.rb`:
+   ```ruby
+   class Postsvg::Model::Operators::SetDash < Postsvg::Model::Operator
+     keyword "setdash"
+     def self.from_operands(stack)
+       offset = stack.pop_number
+       pattern = stack.pop_array
+       new(pattern: pattern, offset: offset)
+     end
+     attr_reader :pattern, :offset
+     def accept(visitor, ctx); visitor.visit_setdash(self, ctx); end
+   end
+   ```
+2. Register in `lib/postsvg/model/operators/graphics_state.rb`:
+   `autoload :SetDash, "postsvg/model/operators/graphics_state/setdash"`.
+3. Register keyword in
+   `lib/postsvg/model/operators/registry.rb`:
+   `"setdash" => SetDash`.
+4. Implement `visit_setdash` in
+   `lib/postsvg/visitors/ps_visitor/graphics_state.rb`.
+
+No existing visitor method changes. No `case` statement edit.
+
+## Performance note
+
+Method dispatch on real Ruby classes is faster than `case op` string
+matching. The visitor will be measurably faster than the legacy
+interpreter on large files.

data/TODO.roadmap/11-operator-coverage.md

@@ -0,0 +1,103 @@
+# 11 — Comprehensive PS Operator Coverage
+
+## Status: [~] (P0 subset complete; P1/P2/P3 ongoing)
+
+## Scope
+
+This file is the master list of PS operators we cover. Grouped by
+PLRM chapter. Each operator links to its source page in
+`../postscript-guide/docs/commands/<category>/index.adoc`.
+
+## Priority P0 (must have for 0.2.0) — DONE
+
+### Stack
+- [x] `pop`, `exch`, `dup`, `index`, `roll`, `clear`, `count`
+
+### Arithmetic / math
+- [x] `add`, `sub`, `mul`, `div`, `idiv`, `mod`, `neg`, `abs`
+- [x] `ceiling`, `floor`, `round`, `truncate`
+- [x] `sqrt`, `atan`, `cos`, `sin`, `ln`, `log`, `exp`
+
+### Boolean / bitwise
+- [x] `eq`, `ne`, `gt`, `ge`, `lt`, `le`
+- [x] `and`, `or`, `xor`, `not`, `bitshift`
+
+### Path construction
+- [x] `newpath`, `moveto`, `rmoveto`, `lineto`, `rlineto`
+- [x] `curveto`, `rcurveto`, `arc`, `arcn`, `closepath`, `currentpoint`
+
+### Painting
+- [x] `stroke`, `fill`, `eofill`, `clip`, `eoclip`
+
+### Color
+- [x] `setgray`, `setrgbcolor`, `setcmykcolor`, `sethsbcolor`
+
+### Graphics state
+- [x] `gsave`, `grestore`, `setlinewidth`, `setlinecap`,
+      `setlinejoin`, `setmiterlimit`, `setdash`
+
+### Transformations
+- [x] `translate`, `scale`, `rotate`, `concat`, `matrix`,
+      `currentmatrix`, `setmatrix`, `transform`, `dtransform`,
+      `itransform`, `idtransform`
+
+### Dictionary / control flow
+- [x] `dict`, `begin`, `end`, `def`, `load`, `store`, `known`, `get`,
+      `put`
+- [x] `if`, `ifelse`, `repeat`, `loop`, `for`, `exit`, `quit`,
+      `exec`, `stopped`
+
+### Device
+- [x] `showpage`, `copypage`, `nulldevice`
+
+## Priority P1 (0.3.0)
+
+### Strings, arrays, search
+- [ ] `length`, `get`, `put`, `getinterval`, `putinterval`, `search`,
+      `token`, `anchorsearch`
+- [ ] `string`, `substring`, `stringwidth`
+
+### Type / conversion
+- [ ] `type`, `cvlit`, `cvx`, `xcheck`, `cvs`, `cvn`, `cvr`, `cvi`,
+      `cvrs`
+
+### Files
+- [ ] `currentfile`, `read`, `readhexstring`, `readstring`, `closefile`,
+      `eof`, `flushfile`
+
+## Priority P2 (0.4.0) — Fonts and text
+
+- [ ] `findfont`, `scalefont`, `setfont`, `show`, `ashow`, `widthshow`,
+      `kshow`, `xshow`, `xyshow`, `yshow`, `stringwidth`
+- [ ] `FontDirectory`, `StandardEncoding`, `ISOLatin1Encoding`
+- [ ] `makefont`, `composefont`, `findencoding`
+- [ ] CharPath, Type 3 fonts (rendered via outline procedures)
+
+## Priority P3 (full PLRM)
+
+### Level 2 / 3
+- [ ] `image`, `colorimage`, `imagemask` — raster imagery
+- [ ] Shading types 1–7 (`shfill`)
+- [ ] Patterns: `makepattern`, `setpattern`
+- [ ] Forms: `BeginData`, `ExecuteForm`
+- [ ] Halftone: `setscreen`, `setcolorscreen`, `sethalftone`
+- [ ] CID fonts, Type 0 (composite) fonts
+- [ ] Filters: ASCIIHexDecode, ASCII85Decode, LZWDecode, FlateDecode,
+      RunLengthDecode, SubFileDecode
+- [ ] Binary object format, binary tokens
+- [ ] Page device: `setpagedevice`, `currentpagedevice`
+- [ ] Resource management: `defineresource`, `findresource`,
+      `enumerate`, `resourcestatus`, `undefineresource`
+- [ ] `setcolorspace`, `setcolor` (DeviceN, ICCBased)
+
+## Acceptance per operator
+
+- `Model::Operators::<Name>` class with typed operands.
+- `from_operands(stack)` factory that pops operands and returns the
+  instance.
+- `visit_<name>` in `PsVisitor` that mutates the graphics context /
+  path builder / svg builder.
+- Spec under `spec/postsvg/model/operators/<name>_spec.rb` covering
+  operand parsing and visitor side-effects.
+- Cross-reference in `docs/postscript/operators/<name>.adoc` (or
+  point at the existing page in `../postscript-guide`).

data/TODO.roadmap/12-svg-domain.md

@@ -0,0 +1,62 @@
+# 12 — SVG Domain Model (`Postsvg::Svg::*`)
+
+## Status: [x]
+
+## Why
+
+The SVG→PS direction needs a typed intermediate, parallel to
+`Postsvg::Model::*` on the PS side. Consuming raw Nokogiri nodes would
+couple every translator to libxml2 quirks; building value objects up
+front gives us:
+
+- Stable equality for round-trip tests.
+- A clean place to attach SVG-specific semantics (`paint`,
+  `stroke-dasharray`, `clip-path` reference resolution).
+- A registration point for the OCP handler dispatch.
+
+The shape is borrowed directly from `emfsvg/lib/emfsvg/svg/*`.
+
+## Tasks
+
+- [x] `Postsvg::Svg::Parser.call(svg_string) -> Svg::Document`.
+- [x] `Postsvg::Svg::Document` — carries `root_element`, `viewbox`,
+  `width`, `height`, `clip_paths` registry (built from `<defs>`).
+- [x] `Postsvg::Svg::Element` — base class with:
+  - `ELEMENT_NAME` constant
+  - `children`, `clip_path`, `transform`
+  - `self.register(name, subclass)` — populates a class-level registry
+  - `self.from_node(node)` — dispatches to registered subclass, falls
+    back to `OpenElement` so unknown tags descend into children
+- [x] Elements (P0 set):
+  - `Svg::Elements::Svg` (root)
+  - `Svg::Elements::Group`
+  - `Svg::Elements::Path`
+  - `Svg::Elements::Rect`
+  - `Svg::Elements::Circle`
+  - `Svg::Elements::Ellipse`
+  - `Svg::Elements::Line`
+  - `Svg::Elements::Polyline`
+  - `Svg::Elements::Polygon`
+  - `Svg::Elements::Text` (+ `Tspan`)
+  - `Svg::Elements::Image`
+  - `Svg::Elements::Defs`
+  - `Svg::Elements::ClipPath`
+  - `Svg::Elements::LinearGradient`, `Svg::Elements::RadialGradient`
+- [x] Value objects for cross-cutting concepts:
+  - `Svg::Color` — wraps `Postsvg::Color`
+  - `Svg::Paint` — solid color, `url(#id)` reference, or `none`
+  - `Svg::Stroke` — width, dasharray, dashoffset, linecap, linejoin,
+    miterlimit
+  - `Svg::PathData::Command` — single SVG path command; `PathData`
+    parses the `d` attribute into an array of commands
+  - `Svg::TransformList` — parses `transform="..."` into a list of
+    `Matrix` instances
+- [x] `Svg::ClipPathRegistry.from_document(doc)` — indexes
+  `<clipPath id="…">` definitions by id for handler lookup.
+
+## Out of scope
+
+- CSS stylesheet parsing. SVG `<style>` blocks are not interpreted;
+  presentation attributes only. (Future work; tracked in
+  `23-level2-level3.md`.)
+- Animation elements (`<animate>`, `<animateTransform>`). Skipped.

data/TODO.roadmap/13-translation-handlers.md

@@ -0,0 +1,69 @@
+# 13 — Translation Handlers (SVG → PS)
+
+## Status: [x]
+
+## Why
+
+The SVG → PS direction is the mirror of the PS → SVG renderer. Where
+the renderer walks PS records and emits SVG, the translator walks SVG
+elements and emits PS records. The records are then serialized by
+`Postsvg::Serializer`.
+
+The handler-per-element pattern (mirrors `emfsvg`'s
+`Translation::Handlers::*`) keeps the dispatch OCP: new SVG element
+type → new handler class + registration, no switch.
+
+## Tasks
+
+- [x] `Postsvg::Translation::PsRenderer` — top-level orchestrator.
+  Takes `Svg::Document`, returns `Model::Program`.
+- [x] `Postsvg::Translation::HandlerRegistry` — element class →
+  handler class. Walks superclass chain so subclassing handlers
+  inherits behaviour.
+- [x] `Postsvg::Translation::Context` — carries:
+  - `program` (the `Model::Program` being built)
+  - `graphics_stack` (mirrors renderer's)
+  - `clip_path_registry` (resolved references)
+  - `serializer_options` (eps:, page_size:)
+- [x] `Postsvg::Translation::RecordEmitter` — thin helper that appends
+  `Model::Operator` instances to `program.body` in source order.
+- [x] Handlers (P0 set):
+  - `Handlers::SvgHandler` — emits header: `%%BoundingBox`,
+    `newpath`, set up Y-flip
+  - `Handlers::GroupHandler` — `gsave`, transform concat, descend,
+    `grestore`
+  - `Handlers::PathHandler` — converts `PathData` commands to PS
+    `moveto`/`lineto`/`curveto`/`closepath`, then `stroke`/`fill`
+    based on `paint-*` attributes
+  - `Handlers::RectHandler` — synthesizes path: `newpath`,
+    `x y moveto`, `w 0 rlineto`, `0 h rlineto`, `-w 0 rlineto`,
+    `closepath`
+  - `Handlers::CircleHandler` — `arc`
+  - `Handlers::EllipseHandler` — `scale` + `arc` + restore
+  - `Handlers::LineHandler` — `moveto`, `lineto`, `stroke`
+  - `Handlers::PolylineHandler` / `Handlers::PolygonHandler` —
+    walk points
+  - `Handlers::TextHandler` — `findfont`/`scalefont`/`setfont`,
+    `moveto`, `show`
+  - `Handlers::ImageHandler` — emit `image` with `datasource`
+    (PNG bytes hex-encoded; full image support is P2)
+  - `Handlers::DefsHandler` — registers but does not paint
+  - `Handlers::ClipPathHandler` — defines clip via `clippath`/`clip`
+
+## Handler contract
+
+```ruby
+class Handlers::PathHandler
+  def self.call(element, context)
+    # 1. Update graphics context from element's paint/stroke/transform.
+    # 2. Emit Model records (moveto/lineto/...).
+    # 3. Emit terminal operator (stroke/fill/clip).
+    # 4. Recurse into children if any.
+  end
+end
+```
+
+Handlers never touch the serializer directly. They build `Model::*`
+records; the serializer consumes them later. This keeps the model the
+single source of truth and enables future PS → PS transformations
+(optimization, validation) without re-parsing.

data/TODO.roadmap/14-ps-serializer.md

@@ -0,0 +1,49 @@
+# 14 — PS Serializer
+
+## Status: [x]
+
+## Why
+
+The SVG→PS direction's last step. Walks a `Model::Program` and emits
+PostScript source text. Also used internally by tests for
+pretty-printing.
+
+## Tasks
+
+- [x] `Postsvg::Serializer.call(program, eps: false) -> String`.
+- [x] Output structure:
+  ```
+  %!PS-Adobe-3.0 [<eps: EPSF-3.0>]
+  %%Creator: Postsvg <version>
+  %%BoundingBox: LLX LLY URX URY
+  %%HiResBoundingBox: ...    (when sub-integer precision matters)
+  %%EndComments
+  <body: literal/procedure/operator output>
+  showpage
+  %%EOF
+  ```
+- [x] BoundingBox computed by walking the program's path operations
+  with the current CTM (a second lightweight pass; the renderer does
+  the same walk for SVG viewbox sizing).
+- [x] Operator serialization: each `Model::Operator` knows how to emit
+  itself via `Serializer::emit_<name>(op, io)`. Same OCP shape as the
+  visitor: a new operator adds a method, no switch edits.
+- [x] String literal escaping: `( )`, `\\`, `\n`, `\r`, `\t`, octal
+  for non-printables. Mirrors PLRM §3.2.2.
+- [x] Hex string alternative for binary data: `<DEADBEEF>`.
+- [x] Number formatting through `FormatNumber`.
+- [x] `eps: true` adds the `EPSF-3.0` header and a `%%EndProlog` /
+  `%%Page` block.
+
+## Round-trip guarantee
+
+For the supported subset, `Serializer.call(Parser.parse(
+Lexer.tokenize(ps)))` produces output that re-parses to an equivalent
+`Model::Program` (modulo formatting). This is the contract the
+round-trip spec asserts.
+
+## Out of scope
+
+- Token-stream preservation (comments, whitespace) is not preserved
+  across round-trip. Input formatting is normalized.
+- Binary PostScript (Level 2 binary object format). Future P3 work.

data/TODO.roadmap/15-cli-and-public-api.md

@@ -0,0 +1,47 @@
+# 15 — CLI + Public API
+
+## Status: [x]
+
+## Why
+
+The public surface needs to be:
+
+1. Symmetric: `to_svg` / `to_ps` / `to_eps` — clear direction in the
+   name.
+2. Predictable: `convert` is a synonym for the original direction
+   (PS→SVG) for backwards compatibility, but new code uses the
+   directional names.
+3. Discoverable: CLI `--help` shows every command.
+
+## Tasks
+
+- [x] Public API (in `lib/postsvg.rb`):
+  ```ruby
+  Postsvg.to_svg(ps_or_eps_string, **opts)        # PS/EPS → SVG
+  Postsvg.to_svg_file(input_path, output_path=nil, **opts)
+  Postsvg.convert(...)                            # alias for to_svg (BC)
+  Postsvg.convert_file(...)                       # alias (BC)
+
+  Postsvg.to_ps(svg_string, eps: false, **opts)   # SVG → PS
+  Postsvg.to_eps(svg_string, **opts)              # SVG → EPS
+  Postsvg.to_ps_file(input_path, output_path=nil, **opts)
+  ```
+- [x] `Postsvg::Options` frozen struct shared by both directions:
+  `verbose:`, `width:`, `height:`, `viewbox_override:`, `eps:`.
+- [x] CLI (Thor):
+  - `postsvg convert INPUT [OUTPUT]` — PS/EPS → SVG (BC)
+  - `postsvg to-svg INPUT [OUTPUT]` — explicit alias
+  - `postsvg to-ps INPUT [OUTPUT]` — SVG → PS
+  - `postsvg to-eps INPUT [OUTPUT]` — SVG → EPS
+  - `postsvg batch INPUT_DIR [OUTPUT_DIR]` — auto-detects by extension
+  - `postsvg version`
+- [x] Auto-detection in `batch`: `.ps`/`.eps` → SVG; `.svg` → PS.
+- [x] CLI exit codes: 0 success, 1 usage error, 2 conversion error.
+
+## Deprecation path
+
+- `Postsvg.convert` and `Postsvg.convert_file` remain as aliases. No
+  removal in 0.2; revisit at 1.0.
+- The dormant `Postsvg::Converter` class is no longer autoloaded.
+  Callers needing it can `require "postsvg/legacy/converter"`
+  explicitly.

data/TODO.roadmap/16-specs.md

@@ -0,0 +1,84 @@
+# 16 — Specs
+
+## Status: [~]
+
+## Why
+
+Per the global rule: "Good specs throughout. Every public method
+should have specs. Every behavioral edge case should be covered.
+Specs use real model instances — never doubles."
+
+## Layout
+
+```
+spec/
+├── spec_helper.rb
+├── postsvg_spec.rb               # public API contract
+├── postsvg/
+│   ├── lexer_spec.rb             # token-by-token
+│   ├── parser_spec.rb            # AST shape, DSC capture
+│   ├── model/
+│   │   ├── program_spec.rb
+│   │   ├── token_spec.rb
+│   │   └── operators/
+│   │       ├── stack_spec.rb
+│   │       ├── arithmetic_spec.rb
+│   │       ├── path_spec.rb
+│   │       └── ...               # one per operator category
+│   ├── graphics_context_spec.rb
+│   ├── matrix_spec.rb
+│   ├── color_spec.rb
+│   ├── svg_builder_spec.rb
+│   ├── renderer_spec.rb          # PS → SVG
+│   ├── visitors/
+│   │   └── ps_visitor_spec.rb
+│   ├── svg/
+│   │   ├── parser_spec.rb
+│   │   ├── document_spec.rb
+│   │   └── elements/
+│   │       └── *_spec.rb
+│   ├── translation/
+│   │   ├── handler_registry_spec.rb
+│   │   ├── ps_renderer_spec.rb
+│   │   └── handlers/
+│   │       └── *_spec.rb
+│   ├── serializer_spec.rb
+│   ├── cli_spec.rb
+│   └── integration_spec.rb       # full-pipeline + fixtures
+├── round_trip_spec.rb            # SVG → PS → SVG
+└── fixtures/
+    ├── ps2svg/                   # existing fixtures (kept)
+    ├── eps2svg/                  # existing fixtures (kept)
+    ├── svg2ps/                   # new: SVG → PS inputs + expected
+    └── round_trip/               # new: SVG ↔ PS pairs
+```
+
+## Tasks
+
+- [x] Each `Model::Operators::*` class has a spec for:
+  - `from_operands` parsing (correct pops, error on stack underflow)
+  - value equality
+- [x] Each `Svg::Elements::*` class has a spec for `from_node`
+  (parses attributes correctly, drops nothing silently).
+- [x] Each `Translation::Handlers::*` has a spec that builds a minimal
+  SVG element, runs the handler against a real `Context` (no double),
+  and asserts on the emitted `Model::Program` records.
+- [x] `SvgBuilder` spec covers dedup (two identical clipPaths → one
+  `<defs>` entry) and XML escaping.
+- [x] `Serializer` spec round-trips: serialize → lex → parse →
+  equality with original `Model::Program`.
+- [x] `Renderer` spec covers PS→SVG for each fixture in
+  `spec/fixtures/ps2svg/` and `spec/fixtures/eps2svg/`.
+- [x] `Cli` spec uses `StringIO` capture of stdout; writes inputs to
+  `Dir.tmpdir`; cleans up.
+- [x] `Round-trip` spec: for each SVG in `spec/fixtures/round_trip/`,
+  `to_ps` then `to_svg` and assert geometric equivalence (within 1px
+  tolerance; uses `Canon` matcher configured in spec_helper).
+
+## Anti-patterns banned
+
+- `double(...)`, `instance_double(...)`, `allow_any_instance_of`.
+- Mocking the file system with `FakeFS`. Use `Dir.tmpdir`.
+- Mocking time. Pass `Time.at(fixed)` to constructors that need it.
+- `subject { described_class }` with implicit receiver — explicit
+  `expect(described_class.foo).to ...`.

data/TODO.roadmap/17-docs-sync.md

@@ -0,0 +1,47 @@
+# 17 — Docs Sync
+
+## Status: [ ]
+
+## Why
+
+The README, `docs/architecture.adoc`, and most of `docs/api-reference`
+currently describe the dormant Parslet pipeline. The CLAUDE.md flags
+this; we need to either:
+
+(a) Update them to describe the live pipeline (preferred).
+(b) Clearly mark them as describing a planned pipeline.
+
+(a) wins because users actually consult these docs.
+
+## Tasks
+
+- [ ] README.adoc:
+  - Replace "three-stage architecture" diagram with the new pipeline
+    diagram (from `00-architecture.md`).
+  - Add `Postsvg.to_ps` / `Postsvg.to_eps` examples.
+  - Update CLI examples to include `to-ps`, `to-eps`.
+  - Update limitations to reflect current actual coverage.
+- [ ] docs/architecture.adoc:
+  - Describe Lexer / Parser / Model / Renderer / Visitor / SvgBuilder.
+  - Describe Svg::* / Translation / Serializer.
+  - Add the "MECE responsibility split" table from
+    `00-architecture.md`.
+- [ ] docs/api-reference.adoc:
+  - Per-method yardoc-style entries for the public API.
+- [ ] docs/cli-reference.adoc:
+  - All commands; auto-detected batch.
+- [ ] docs/postscript/svg-mapping.adoc:
+  - How each PS operator maps to SVG (one row per operator).
+- [ ] docs/postscript/implementation-notes.adoc:
+  - The design choices in `00-architecture.md` summarized for users.
+- [ ] docs/CHANGELOG.md:
+  - 0.2.0 entry with new SVG → PS / EPS direction and breaking
+    changes (if any).
+
+## What NOT to touch
+
+- `docs/postscript/operators/*.adoc` — these are content pages, not
+  architecture docs. They stay unless an operator's documented
+  behaviour changed (it shouldn't).
+- `CLAUDE.md` — already accurate; update only if the architecture
+  diverges from what it says.

data/TODO.roadmap/18-performance-and-determinism.md

@@ -0,0 +1,47 @@
+# 18 — Performance and Determinism
+
+## Status: [ ]
+
+## Why
+
+Pure-Ruby string manipulation can be slow. The legacy `Interpreter`
+allocates a new `PathBuilder` on every `reset`; the new pipeline can
+do better. Determinism matters for round-trip tests and for
+reproducible builds.
+
+## Tasks
+
+- [ ] **Frozen-string literals everywhere.** Add `# frozen_string_literal: true` to every `.rb` file.
+- [ ] **`FormatNumber`** is the single source for float formatting.
+  Profile with `benchmark-ips` against representative PS files
+  (`spec/fixtures/ps2svg/example_full.ps` is the heaviest).
+- [ ] **`SvgBuilder`** uses a single `String` accumulator (`String#<<`).
+  Avoid `Array#join`.
+- [ ] **Dedup registry** uses an interned `String` key (frozen) so
+  hash lookup is O(1) with no allocation.
+- [ ] **Matrix multiplication** is inlined in `Matrix#multiply` (already
+  the case) — no object allocation per component.
+- [ ] **Procedure invocation** uses an explicit depth counter rather
+  than relying on Ruby's stack (which would `SystemStackError` on
+  pathological inputs at ~3000 deep).
+- [ ] **GC pressure**: pass `Model::Operator` instances by reference,
+  never deep-copy them between passes.
+- [ ] **Profiling harness**: `scripts/profile.rb INPUT.ps` runs the
+  pipeline under `stackprof` and prints the top 20 hotspots. Useful
+  for regression detection.
+- [ ] **Memory bound**: `Renderer::MAX_OUTPUT_BYTES` (100 MB default,
+  configurable). Raise `RenderError` past this.
+
+## Determinism checklist
+
+- Two runs of the same input → byte-equal output.
+- IDs (`clip1`, `grad1`, `pattern1`) start at 1 on every
+  `SvgBuilder.new`.
+- No `Time.now`, no `SecureRandom`, no `Object#object_id` in IDs.
+- No iteration over `Hash` whose order depends on insertion of
+  non-deterministic keys.
+
+## Out of scope
+
+- Streaming output (incremental SVG emission for huge files). Future
+  work; would require SvgBuilder to expose an `each_chunk` enumerator.

data/TODO.roadmap/19-error-model.md

@@ -0,0 +1,45 @@
+# 19 — Error Model
+
+## Status: [ ]
+
+## Why
+
+Today there is one error class (`Postsvg::Error`) plus three trivial
+subclasses. Operators silently swallow bad operands
+(`safe_pop_number(0)` returns 0). This makes debugging impossible and
+makes the gem unsafe for untrusted input.
+
+## Tasks
+
+- [ ] Typed errors, one per failure mode:
+  - `Postsvg::ParseError` — lexer/parser failed.
+    - `LexError < ParseError` — bad character / unterminated string.
+    - `SyntaxError < ParseError` — unbalanced braces, missing operands.
+  - `Postsvg::RenderError` — PS → SVG execution failed.
+    - `StackUnderflowError < RenderError`.
+    - `UndefinedOperatorError < RenderError` (vs. `UnknownOperator`,
+      which is recoverable).
+    - `RecursionLimitError < RenderError`.
+  - `Postsvg::TranslationError` — SVG → PS failed.
+    - `UnsupportedElementError < TranslationError`.
+    - `UnresolvedReferenceError < TranslationError` (`url(#missing)`).
+  - `Postsvg::SerializeError` — Model → PS failed.
+  - `Postsvg::SizeLimitError < RenderError` — exceeded
+    `MAX_OUTPUT_BYTES`.
+- [ ] All errors carry:
+  - `source_position` (line, column) when known
+  - `operator_name` when applicable
+  - `original` (wrapped exception) when applicable
+- [ ] No `rescue StandardError` blanket catches in the public API.
+  Catch specific errors; re-raise everything else.
+- [ ] Legacy `safe_pop_number(default)` is removed; underflow raises
+  `StackUnderflowError`. Operators that legitimately handle missing
+  operands (e.g. optional dictionary args) use explicit `stack.maybe_pop`.
+
+## Why typed errors
+
+- Users can catch the specific failure they care about.
+- Tests can assert `expect { ... }.to raise_error(ParseError)` without
+  matching an unrelated crash.
+- The CLI can format different errors differently (syntax error →
+  point at file:line; unsupported element → suggest workaround).

data/TODO.roadmap/20-font-and-text.md

@@ -0,0 +1,46 @@
+# 20 — Fonts and Text
+
+## Status: [ ]
+
+## Why
+
+The legacy `Interpreter` emits a stub `<text>` element from `show`,
+which is not even close to correct — PS fonts have metrics, kerning,
+encoding, and often glyph-specific procedures. For the SVG→PS
+direction, mapping `<text>` back to PostScript `show` requires a font
+the target device knows about.
+
+## Scope by priority
+
+### P2a — Names and basic show (0.4.0)
+
+- [ ] Built-in PS font registry: Courier, Helvetica, Times-Roman +
+      oblique/bold variants. Map SVG generic families (`serif`,
+      `sans-serif`, `monospace`) to these.
+- [ ] `findfont` / `scalefont` / `setfont` parsing in the PS direction.
+- [ ] `show` / `stringwidth` operators (without kerning).
+- [ ] SVG `<text>` → PS: emit `findfont`, `scalefont`, `setfont`,
+      `moveto`, `show`.
+
+### P2b — Outline text (0.5.0)
+
+- [ ] For fonts whose metrics we know (Helvetica, Courier, Times),
+      convert `<text>` to outlines (path operations) for fidelity.
+      Optional flag: `Postsvg.to_svg(ps, text_mode: :outlines)`.
+- [ ] `charpath` operator.
+
+### P3 — Full font machinery
+
+- [ ] Type 1 font parsing (`.pfa` / `.pfb`).
+- [ ] Type 3 font procedures (rendered via their PaintProc).
+- [ ] CID fonts (composite, vertical writing modes).
+- [ ] `ashow`, `widthshow`, `kshow`, `xshow`, `xyshow`, `yshow`.
+- [ ] Encoding vectors: `StandardEncoding`, `ISOLatin1Encoding`,
+      custom encodings via `defineencoding`.
+
+## Reference
+
+- `../postscript-guide/docs/commands/font-text/index.adoc` — operator
+  reference.
+- `../postscript-guide/docs/usage/advanced/fonts-text.adoc` — tutorial.
+- PLRM Chapter 5 (Fonts) and Chapter 9 (Typesetter's Model).