postsvg 0.1.0 → 0.3.0

data/Rakefile

@@ -8,3 +8,103 @@ RSpec::Core::RakeTask.new(:spec)
 RuboCop::RakeTask.new
 
 task default: %i[spec rubocop]
+
+# Link checking tasks
+namespace :check do
+  desc "Check internal documentation links only (recommended for CI)"
+  task :links do
+    puts "Checking internal documentation links..."
+    puts "(External URLs are skipped to avoid anti-bot measures)"
+    puts
+
+    # Check if lychee is installed
+    unless system("which lychee > /dev/null 2>&1")
+      puts "\n❌ Error: lychee is not installed."
+      puts "\nInstall lychee using one of these methods:"
+      puts "  - cargo install lychee (requires Rust)"
+      puts "  - brew install lychee (macOS)"
+      puts "  - See https://lychee.cli.rs/ for more options"
+      exit 1
+    end
+
+    # Run lychee with --offline to check only internal links
+    success = system(
+      "lychee",
+      "--config", "lychee.toml",
+      "--offline",
+      "--format", "detailed",
+      "docs/**/*.adoc",
+      "README.adoc"
+    )
+
+    if success
+      puts "\n✅ All internal documentation links are valid!"
+    else
+      puts "\n❌ Broken internal links found. See output above for details."
+      exit 1
+    end
+  end
+
+  desc "Check all links including external URLs (may have false positives)"
+  task :links_all do
+    puts "Checking all documentation links (internal + external)..."
+    puts "⚠️  Note: External URLs may fail due to rate limiting or anti-bot measures"
+    puts
+
+    unless system("which lychee > /dev/null 2>&1")
+      puts "\n❌ Error: lychee is not installed."
+      puts "\nInstall lychee using one of these methods:"
+      puts "  - cargo install lychee (requires Rust)"
+      puts "  - brew install lychee (macOS)"
+      puts "  - See https://lychee.cli.rs/ for more options"
+      exit 1
+    end
+
+    success = system(
+      "lychee",
+      "--config", "lychee.toml",
+      "--format", "detailed",
+      "docs/**/*.adoc",
+      "README.adoc"
+    )
+
+    if success
+      puts "\n✅ All links are valid!"
+    else
+      puts "\n❌ Some links failed validation."
+      puts "Note: External URL failures may be due to anti-bot measures, not actual broken links."
+      exit 1
+    end
+  end
+
+  desc "Check documentation links (verbose output)"
+  task :links_verbose do
+    puts "Checking internal documentation links (verbose)..."
+
+    unless system("which lychee > /dev/null 2>&1")
+      puts "\n❌ Error: lychee is not installed."
+      puts "\nInstall lychee using one of these methods:"
+      puts "  - cargo install lychee (requires Rust)"
+      puts "  - brew install lychee (macOS)"
+      puts "  - See https://lychee.cli.rs/ for more options"
+      exit 1
+    end
+
+    success = system(
+      "lychee",
+      "--config", "lychee.toml",
+      "--offline",
+      "--format", "detailed",
+      "--verbose",
+      "docs/**/*.adoc",
+      "README.adoc"
+    )
+
+    if success
+      puts "\n✅ All internal links are valid!"
+    else
+      puts "\n❌ Broken links found. See output above for details."
+      exit 1
+    end
+  end
+end

data/TODO.roadmap/00-architecture.md

@@ -0,0 +1,139 @@
+# 00 — Architecture
+
+## Status: [x] (this is the design doc; it is the contract for all later files)
+
+## Problem
+
+Postsvg 0.1.0 ships two parallel pipelines:
+
+1. **Live path** (`Postsvg.convert`): raw PS string → hand-written
+   `Tokenizer` → `Interpreter#interpret` (a 900-line stack machine that
+   emits SVG strings inline via `emit_svg_path`).
+2. **Dormant Parslet path**: `Parser::PostscriptParser`,
+   `Parser::Transform`, `Converter`, plus an unused `SvgGenerator` and
+   `GraphicsState` that are only reached from `Converter`.
+
+The README, gemspec dependency list (`parslet`), and most of `docs/`
+describe the dormant Parslet path as if it were live. The live path has
+no domain model — every operator reaches into raw hashes and arrays and
+mutates them, which makes adding features (let alone a reverse
+direction) unsafe.
+
+We need:
+
+- A real **domain model** (typed PS records) so the renderer and the
+  serializer can both consume the same data.
+- A **renderer** that walks the model and emits SVG via a clean builder.
+- A **serializer** that walks the model and emits PS source.
+- A **parser** for SVG that produces a parallel `Svg::*` model.
+- A **translation** layer that walks the SVG model and produces PS
+  records, which the serializer writes out.
+
+All of this must be open for extension (OCP): new PS operator → new
+record class + visitor arm; new SVG element → new value class + handler.
+Existing code must not change to add new cases.
+
+## Target layering
+
+```
+                            ┌─────────────────────┐
+                  bytes ───▶│  Postsvg::Lexer     │  comment-aware
+                            └──────────┬──────────┘
+                                       │ tokens
+                                       ▼
+                            ┌─────────────────────┐
+                            │  Postsvg::Parser    │  AST + proc inlining
+                            └──────────┬──────────┘
+                                       │ Model::Program
+                                       ▼
+   ┌──────────────────────────────────────────────────────────────┐
+   │  Postsvg::Model::*  (typed PS records, immutable value objs) │
+   │   Program, Statement, Procedure, Dictionary, Array, String,  │
+   │   Number, Name, operators (Moveto, Lineto, Stroke, …)        │
+   └──────────────────────────────────────────────────────────────┘
+              │                                          ▲
+              │ visit                                    │ emit
+              ▼                                          │
+   ┌─────────────────────┐                  ┌─────────────────────┐
+   │  Postsvg::Renderer  │                  │  Postsvg::Serializer│
+   │   + PsVisitor       │                  │   (Model → PS src)  │
+   │   + SvgBuilder      │                  │                     │
+   └──────────┬──────────┘                  └──────────▲──────────┘
+              │ SVG string                             │ Model::Program
+              ▼                                        │
+   ┌─────────────────────┐                            │
+   │  Postsvg::Svg::*    │  parse                     │
+   │   Document, Element │────────────┐               │
+   └──────────▲──────────┘            │               │
+              │                       ▼               │
+              │             ┌─────────────────────┐   │
+              │             │ Postsvg::Translation│   │
+              │             │   PsRenderer        │   │
+              │             │   + HandlerRegistry │   │
+              │             │   + Handlers::*     │   │
+              │             └──────────┬──────────┘   │
+              │                        │ Model::Program
+              │                        └───────────────┘
+              │
+              │ round-trip closes here: SVG → Model → SVG
+```
+
+## MECE responsibility split
+
+| Namespace                  | Owns                                | Does NOT own                       |
+|----------------------------|-------------------------------------|------------------------------------|
+| `Postsvg::Lexer`           | PS source → `Model::Token[]`        | semantics, execution               |
+| `Postsvg::Parser`          | tokens → `Model::Program`           | rendering, serialization           |
+| `Postsvg::Model::*`        | typed records, value equality       | execution, IO                       |
+| `Postsvg::GraphicsContext` | CTM, color, clip stack, font        | emitting anything                  |
+| `Postsvg::Matrix`          | affine transforms                  | graphics state                     |
+| `Postsvg::Color`           | RGB / Gray / CMYK conversions       | mutating state                     |
+| `Postsvg::SvgBuilder`      | SVG byte emission, dedup, viewbox   | PS semantics                       |
+| `Postsvg::Renderer`        | PS → SVG orchestration              | SVG parsing                        |
+| `Postsvg::Visitors::PsVisitor` | dispatch Model record → builder | orchestration                      |
+| `Postsvg::Svg::*`          | SVG domain model (parse side)       | PS knowledge                       |
+| `Postsvg::Translation::*`  | SVG model → PS Model records       | SVG parsing, PS serialization      |
+| `Postsvg::Serializer`      | Model records → PS source text     | SVG                                |
+| `Postsvg::CLI`             | argument parsing, IO               | conversion logic                   |
+
+## Constraints (non-negotiable)
+
+These come from the user's global `~/.claude/CLAUDE.md` and from the
+project's existing rules:
+
+1. **No `require_relative` in `lib/`.** Use Ruby `autoload` declared in
+   the immediate parent namespace file.
+2. **No `double()` in specs.** Real instances or `Struct.new`.
+3. **No `send` to private methods, no `instance_variable_set`/`get`,
+   no `respond_to?` for type checks.**
+4. **No AI attribution** anywhere.
+5. **Never delete source files.** The dormant Parslet pipeline
+   (`Parser`, `Converter`, `SvgGenerator`, `GraphicsState`,
+   `parser/postscript_parser.rb`, `parser/transform.rb`) stays in the
+   tree under a clearly-marked legacy path; it is no longer on the
+   autoload path of the public API.
+6. **Never commit to `main`, never push tags, never push to `main`.**
+7. **Library packages have no side effects.** No writes to
+   `__dir__`/`import.meta.url`-style paths.
+8. **DRY / OCP / MECE.** Adding a PS operator or an SVG element must
+   not require editing a switch statement; it must be a class + a
+   registration.
+
+## What we do NOT do here
+
+- We do not chase byte-exact parity with Ghostscript or Inkscape —
+  that is a separate goal and is incompatible with the pure-Ruby,
+  no-external-deps constraint.
+- We do not implement Level 3 shading, CID fonts, or image filters in
+  the P0 / P1 scope. Those are P3.
+- We do not delete the Parslet pipeline. It is preserved for reference
+  and for any future migration.
+
+## Source materials
+
+- `../postscript-guide/docs/` — operator reference (Levels 1/2/3),
+  syntax, data types. Use this for operator semantics, stack effects,
+  and edge cases.
+- `../emfsvg/` — architectural template (Renderer / Visitor / SvgBuilder
+  for forward direction; Svg::Document / Translation::EmfRenderer /
+  HandlerRegistry / Handlers::* for reverse direction).

data/TODO.roadmap/01-autoload-migration.md

@@ -0,0 +1,39 @@
+# 01 — Migrate `lib/` to Ruby `autoload`
+
+## Status: [x]
+
+## Why
+
+The repo's global rule (see `~/.claude/CLAUDE.md` rule 9) forbids
+`require_relative` (and `require` with paths inside the library) in
+library code. Reasons: lazy loading, no circular-load crashes, clean
+`$LOAD_PATH`, and a single place to read "what does this namespace
+expose."
+
+## Tasks
+
+- [x] Define all `autoload` entries for `Postsvg` in `lib/postsvg.rb`.
+- [x] Create namespace files for sub-namespaces:
+  - `lib/postsvg/model.rb` — `Postsvg::Model` autoloads
+  - `lib/postsvg/visitors.rb` — `Postsvg::Visitors` autoloads
+  - `lib/postsvg/svg.rb` — `Postsvg::Svg` autoloads
+  - `lib/postsvg/translation.rb` — `Postsvg::Translation` autoloads
+  - `lib/postsvg/model/operators.rb` — `Postsvg::Model::Operators`
+  - `lib/postsvg/svg/elements.rb` — `Postsvg::Svg::Elements`
+  - `lib/postsvg/translation/handlers.rb` — `Postsvg::Translation::Handlers`
+- [x] Remove every `require_relative` in `lib/` (each file relies on its
+  parent namespace's autoload declaration).
+- [x] Keep `require "parslet"`, `require "thor"`, `require "nokogiri"`
+  in `lib/postsvg.rb` only (external gems).
+- [x] Verify `ruby -Ilib -e "require 'postsvg'; Postsvg.convert('...')"`
+  still works.
+
+## Rule of thumb
+
+Each `lib/foo/bar/baz.rb` file defines `class Foo::Bar::Baz`. The
+*parent* (`lib/foo/bar.rb`) declares `autoload :Baz, "foo/bar/baz"`.
+The root (`lib/foo.rb`) declares `autoload :Bar, "foo/bar"`.
+
+This means: never reach across namespaces. If `Baz` needs `Quux`, do
+not `require_relative "../quux"` — the parent of `Baz` already
+autoloaded `Quux` (or will, when something references it).

data/TODO.roadmap/02-isolate-dormant-code.md

@@ -0,0 +1,51 @@
+# 02 — Isolate dormant code (no deletion)
+
+## Status: [x]
+
+## Why
+
+The repo's first absolute rule is **NEVER DELETE source files**. The
+following files exist but are not on the live conversion path:
+
+- `lib/postsvg/converter.rb` (class `Postsvg::Converter`)
+- `lib/postsvg/parser.rb` (class `Postsvg::Parser`)
+- `lib/postsvg/parser/postscript_parser.rb` (Parslet grammar)
+- `lib/postsvg/parser/transform.rb` (Parslet AST transform)
+- `lib/postsvg/svg_generator.rb` (class `Postsvg::SvgGenerator`)
+- `lib/postsvg/graphics_state.rb` (class `Postsvg::GraphicsState`)
+- `lib/postsvg/interpreter.rb` (class `Postsvg::Interpreter` — the
+  pre-refactor live path)
+- `lib/postsvg/tokenizer.rb` (class `Postsvg::Tokenizer` — pre-refactor
+  lexer)
+
+These remain useful as reference material (the dormant Parslet grammar
+in particular encodes operator-precedence and syntax insights the new
+parser will want to consult). They must NOT be deleted.
+
+## Tasks
+
+- [x] Move these files under `lib/postsvg/legacy/` to make their status
+  unambiguous (filesystem move, not deletion; `git mv` preserves
+  history).
+- [x] Add a module docstring to each: "Legacy implementation, kept for
+  reference. Not on the public autoload path."
+- [x] Do not declare autoload entries for them in `lib/postsvg.rb`.
+- [x] Add a README in `lib/postsvg/legacy/` explaining why they are
+  there and how the new pipeline supersedes them.
+- [x] Keep their specs (if any) green by adjusting require paths in the
+  spec files only — never in the legacy lib files themselves.
+
+## What this is NOT
+
+- Not deletion.
+- Not renaming the public classes (the legacy `Postsvg::Converter`
+  etc. keep their names; they just live in a different file).
+- Not a deprecation cycle with warnings — they are simply not loaded
+  by the public API anymore.
+
+## Roll-forward path (future, out of scope)
+
+If/when we want to merge the Parslet grammar's precedence rules into
+the new `Parser`, we can do it as a separate refactor that deletes the
+`legacy/` directory — at that point it is a deliberate replacement,
+not deletion of "unused" code.

data/TODO.roadmap/03-domain-model.md

@@ -0,0 +1,66 @@
+# 03 — PS Domain Model (`Postsvg::Model::*`)
+
+## Status: [x]
+
+## Why
+
+A typed record layer is the backbone of bidirectional conversion:
+
+- The PS→SVG renderer walks records and emits SVG.
+- The SVG→PS translator builds records and hands them to the serializer.
+- Round-trip tests assert against the record list, not against string
+  fragments.
+
+Without a model, every operator is bespoke string manipulation. With a
+model, every operator is a value object that participates in equality,
+serialization, and dispatch.
+
+## Tasks
+
+- [x] `Model::Token` — lexical token (type, value, position).
+  Replaces the bare `Struct` in legacy `Tokenizer`.
+- [x] `Model::Number`, `Model::Name`, `Model::StringLiteral`,
+  `Model::HexLiteral`, `Model::Array`, `Model::Procedure`,
+  `Model::Dictionary` — literal value objects.
+- [x] `Model::Program` — root AST node; carries `header` (DSC comments)
+  and `body` (statement list).
+- [x] `Model::Operators::*` — one class per PS operator
+  (see `11-operator-coverage.md` for the full list).
+  Each is a frozen `Struct`-like value with:
+  - `keyword` — the PS operator name (e.g. `"moveto"`)
+  - typed operand fields
+  - `accept(visitor, ctx)` — double-dispatch entry point
+- [x] Operators grouped by category (`Operators::Path::*`,
+  `Operators::Painting::*`, etc.) — MECE by domain, not by file count.
+
+## Operator base class
+
+```ruby
+class Model::Operator
+  def self.keyword(name)
+    define_method(:keyword) { name }
+  end
+
+  def accept(visitor, ctx)
+    visitor.public_send(:"visit_#{self.class.visit_name}", self, ctx)
+  end
+end
+```
+
+`visitor.visit_moveto(op, ctx)` is public. No `send` to private
+methods; the visitor's API is intentionally public.
+
+## Why Struct (not OpenStruct or hand-rolled classes)
+
+- `Struct` gives `==`, `hash`, `members`, `to_h`, and `[]` for free.
+- Frozen Structs are immutable value objects.
+- Subclassing `Struct.new(...)` works for adding behaviour without
+  losing value semantics.
+
+## What goes here vs. `GraphicsContext`
+
+- **Model** = the *program* (what was said).
+- **GraphicsContext** = the *interpreter state* (what's true right now
+  as the program executes).
+
+The visitor mutates the context; it does not mutate the model.

data/TODO.roadmap/04-lexer.md

@@ -0,0 +1,40 @@
+# 04 — PS Lexer (`Postsvg::Lexer`)
+
+## Status: [x]
+
+## Why
+
+The legacy `Tokenizer` strips comments with a global
+`gsub(/%[^\n\r]*/, " ")` *before* tokenizing. This corrupts `%`
+characters inside string literals (`(100% off)` becomes `(100 off)`).
+
+The new lexer must:
+
+- Be comment-aware: distinguish `%` starting a line comment from `%`
+  inside `(...)` strings and `<...>` hex strings.
+- Carry source positions (line, column) for error messages.
+- Emit `Model::Token` value objects, not bare `Struct`s.
+- Never mutate the input.
+
+## Tasks
+
+- [x] `Lexer.tokenize(source) -> [Model::Token]` — public entry.
+- [x] State machine with these states:
+  - `:top` — normal scanning
+  - `:string` — inside `(...)`, tracks nesting, honours `\` escapes
+  - `:hexstring` — inside `<...>`, stops at `>`
+  - `:line_comment` — from `%` to end of line, but only when in `:top`
+- [x] Token types: `:number`, `:name` (with leading `/` stripped,
+  stored as a `Name` literal flag), `:operator`, `:string`,
+  `:hexstring`, `:proc_open`, `:proc_close`, `:array_open`,
+  `:array_close`, `:dict_open`, `:dict_close`.
+- [x] Numeric scanner handles: integers, decimals, leading-dot,
+  trailing-dot, scientific notation, leading sign.
+- [x] DSC comments (`%%BoundingBox:` etc.) are captured as a special
+  `:dsc` token so the parser can extract header metadata without
+  re-parsing source.
+
+## Out of scope
+
+- Binary tokens (Level 2 binary object format). Future work; tracked
+  in `23-level2-level3.md`.

data/TODO.roadmap/05-parser.md

@@ -0,0 +1,43 @@
+# 05 — PS Parser (`Postsvg::Parser`)
+
+## Status: [x]
+
+## Why
+
+Turn the token stream into a typed `Model::Program`. The legacy
+`Interpreter` mixed lexing, parsing, and execution in one pass; we
+separate them so that:
+
+- The renderer can pre-scan for `%%BoundingBox`, `%%Pages`, etc.
+- The serializer can walk a typed AST.
+- Tests can assert on the AST, not on side effects.
+
+## Tasks
+
+- [x] `Parser.parse(tokens) -> Model::Program`.
+- [x] Procedure bodies (`{ ... }`) become `Model::Procedure` nodes
+  carrying nested tokens — *not* flattened into the stream.
+- [x] Arrays (`[ ... ]`) become `Model::Array` literals.
+- [x] Dictionaries (`<< ... >>`) become `Model::Dictionary` literals.
+- [x] DSC comments (`%%BoundingBox:`, `%%Title:`, `%%Pages:`, etc.)
+  populate `Model::Program#header`.
+- [x] Operator dispatch: when an operator token is consumed, pop the
+  right number of operands off an internal parse stack and construct
+  the corresponding `Model::Operators::*` instance. *Unknown*
+  operators stay as `Model::UnknownOperator` so the visitor can warn
+  rather than crash.
+- [x] PostScript's `def` defines names that may later be referenced as
+  operators. The parser records these in a `definitions` map; on
+  encountering a bare name that resolves to a `Model::Procedure`, it
+  emits a `Model::InvokeProcedure` node carrying the procedure body.
+
+## Design choice: do we inline procedures?
+
+The legacy `Interpreter` splices procedure tokens back into the token
+stream (`tokens.insert(current_index + 1, *proc_tokens)`). This is
+fast but loses structure.
+
+The new parser keeps procedures as values; the **renderer** is
+responsible for descending into them when they are invoked. This makes
+the AST stable across passes (useful for the renderer's bounding-box
+pre-scan) and lets the serializer emit procedures verbatim.

data/TODO.roadmap/06-graphics-state.md

@@ -0,0 +1,45 @@
+# 06 — Graphics Context
+
+## Status: [x]
+
+## Why
+
+The legacy code has two graphics-state classes:
+
+- `Postsvg::GraphicsState` — only reached by the dormant `Converter`.
+- `@g_state` hash inside `Interpreter` — the live state, untyped.
+
+Neither is reusable for the new pipeline. We need one
+direction-agnostic value object that:
+
+- Carries CTM, colors, line style, font, dash pattern, clip stack.
+- Is **immutable**; "saving" state pushes a snapshot onto a stack,
+  "restoring" pops back to the previous snapshot.
+- Does not own SVG/PS-specific emission logic.
+
+## Tasks
+
+- [x] `Postsvg::GraphicsContext` — frozen `Struct`-based value object.
+  Fields: `ctm`, `fill_color`, `stroke_color`, `stroke_width`,
+  `line_cap`, `line_join`, `miter_limit`, `dash`, `font_name`,
+  `font_size`, `clip_stack`, `last_text_position`, `fill_rule`.
+- [x] `Postsvg::GraphicsStack` — push/pop of immutable snapshots.
+  `grestore` pops; an attempt to pop an empty stack is a no-op (mirrors
+  PS spec — `grestore` with empty stack is a no-op).
+- [x] Defaults match PLRM defaults: black fill, 1pt stroke, butt cap,
+  miter join, miter limit 10, identity CTM, Helvetica 12pt.
+
+## Why immutable
+
+- Snapshots are O(1) reference copies; no deep dup.
+- Push/pop cannot accidentally share mutable state across snapshots
+  (which was a recurring bug source in the legacy `GraphicsState`
+  where `@transform_matrix` was an in-place array).
+- Round-trip tests can compare snapshots for equality.
+
+## CoordinateState parallel
+
+`emfsvg` has a `CoordinateState` that is deliberately shared across
+`SaveDC`/`RestoreDC` snapshots (GDI quirk). PostScript has no such
+quirk — every `gsave`/`grestore` is a full state save — so we do not
+need a parallel struct here.

data/TODO.roadmap/07-matrix-and-color.md

@@ -0,0 +1,37 @@
+# 07 — Matrix and Color
+
+## Status: [x]
+
+## Why
+
+Both directions need affine transforms and color conversions. Today
+these are spread across `lib/postsvg/matrix.rb` (one good class),
+`lib/postsvg/colors.rb` (a module of free functions), and ad-hoc
+hex/rgb formatting scattered through the interpreter.
+
+## Tasks
+
+- [x] `Postsvg::Matrix` — already exists and is mostly correct. Keep
+  its API; freeze the instance on construction. Add `with(a:, b:, c:,
+  d:, e:, f:)` for functional updates so callers never mutate.
+- [x] `Postsvg::Color` — value object with `red`, `green`, `blue` in
+  `[0, 255]`, plus constructors `Color.rgb`, `Color.gray`,
+  `Color.cmyk`, `Color.parse` (CSS `#rrggbb`, `rgb(...)`, named).
+- [x] `Color#to_svg` — `"#rrggbb"` or `"rgb(r, g, b)"` based on
+  readability (hex by default).
+- [x] `Color#to_ps_setrgbcolor` — `"r g b setrgbcolor"` with PS-native
+  `[0,1]` floats.
+- [x] `Color#to_ps_setgray` — when the color is gray, emit shorter
+  `setgray` form.
+- [x] Drop the free-function `Colors` module in favour of `Color`
+  instances. (The legacy module stays under `legacy/`.)
+
+## Numeric formatting helper
+
+`Postsvg::FormatNumber` — single source of truth for both directions:
+
+- Integers print without trailing `.0`.
+- Floats print to 4 decimals, trailing zeros stripped.
+- `-0` normalized to `0`.
+
+Replaces the three copies of `num_fmt` in the legacy code.

data/TODO.roadmap/08-svg-builder.md

@@ -0,0 +1,51 @@
+# 08 — SvgBuilder
+
+## Status: [x]
+
+## Why
+
+The legacy `Interpreter` emits SVG by string concatenation inline with
+execution. This means:
+
+- No central place to enforce XML well-formedness.
+- No way to dedup clipPaths / gradients / patterns across the program.
+- Hard to test (every operator test has to assert on a fragment).
+
+## Tasks
+
+- [x] `Postsvg::SvgBuilder` — append-only emitter with this surface:
+  - `#open_svg(viewbox:, width:, height:)`
+  - `#close_svg`
+  - `#open_group(transform: nil, clip_path_id: nil, attrs: {})`
+  - `#close_group`
+  - `#path(d:, fill:, stroke:, stroke_width:, line_cap:, line_join:,
+    dash:, clip_path_id:)`
+  - `#text(content:, x:, y:, font_family:, font_size:, fill:, attrs:)`
+  - `#image(href:, x:, y:, width:, height:, transform:)`
+  - `#register_clip_path(d:) -> id` — returns existing id if `d` is
+    byte-equal to a previously-registered path.
+  - `#register_linear_gradient(...)` / `#register_radial_gradient(...)`
+    — same dedup contract.
+  - `#register_pattern(...)` — same.
+  - `#to_s` — final SVG string.
+- [x] XML escaping centralized in `SvgBuilder#escape` (no copy in
+  callers).
+- [x] All shape/text/gradient methods return `self` so calls chain.
+- [x] Deterministic ordering: `<defs>` block emits clipPaths first,
+  then gradients, then patterns — sorted by registration order so IDs
+  are reproducible.
+- [x] The Y-flip wrapper `<g transform="translate(0 H) scale(1 -1)">`
+  is the builder's responsibility, not the renderer's. The renderer
+  emits shapes in PS-native coordinates; the builder wraps them.
+
+## Determinism invariants
+
+- Two runs of the same input produce byte-equal SVG.
+- ID counters start at 1 on every `SvgBuilder.new`.
+- Floating-point output goes through `FormatNumber` (see `07`).
+
+## Out of scope
+
+- Byte-exact parity with Ghostscript or any external tool. Postsvg
+  produces clean, valid SVG — it does not reproduce another tool's
+  formatting quirks (unlike `emfsvg`'s libemf2svg parity goal).

data/TODO.roadmap/09-renderer.md

@@ -0,0 +1,52 @@
+# 09 — Renderer (PS → SVG orchestrator)
+
+## Status: [x]
+
+## Why
+
+The renderer is the entry point for PS/EPS → SVG. It owns the lifecycle
+that the legacy `Interpreter` did, but with clean boundaries:
+
+```
+source ──▶ Lexer ──▶ Parser ──▶ Model::Program
+                                    │
+                                    ▼
+                          Renderer#call
+                                    │
+                       ┌────────────┴───────────┐
+                       │ GraphicsStack          │
+                       │ PathBuilder            │
+                       │ SvgBuilder             │
+                       │ PsVisitor              │
+                       └────────────┬───────────┘
+                                    │
+                                    ▼
+                                SVG string
+```
+
+## Tasks
+
+- [x] `Postsvg::Renderer.call(program, options) -> String`.
+- [x] `Renderer::Options` frozen struct: `eps:`, `width:`, `height:`,
+  `viewbox_override:`, `verbose:`.
+- [x] BoundingBox pre-scan: walk the program once to find any drawing
+  outside the declared BoundingBox; if found, expand viewbox or warn.
+- [x] Single pass execution: walk `program.body`, dispatch each
+  statement via `PsVisitor`, accumulate output in `SvgBuilder`.
+- [x] Procedure invocation: when the visitor hits
+  `Model::InvokeProcedure`, it descends into the procedure body with
+  the current context. Recursion limit (default 64) prevents infinite
+  loops from mutually-recursive procedures.
+- [x] `MAX_OUTPUT_BYTES` guard (mirrors `emfsvg`): raise
+  `RenderError` if output exceeds 100 MB. Pure-Ruby, no memory cap
+  enforcement beyond this.
+
+## Why a separate Renderer and Visitor
+
+- The **Renderer** owns lifecycle (open/close SVG, viewbox, options).
+- The **Visitor** owns per-record semantics (what does `moveto` do to
+  the path builder?).
+
+Splitting them means the Visitor can be unit-tested with a stub
+Renderer (a real `SvgBuilder` instance, no double) and reused for any
+future "render to non-SVG" target (e.g. an in-memory shape tree).