postsvg 0.1.0 → 0.3.0

data/TODO.roadmap/21-images.md

@@ -0,0 +1,45 @@
+# 21 — Images
+
+## Status: [ ]
+
+## Why
+
+`image`, `imagemask`, `colorimage` are common in real EPS files (logos,
+scanned graphics, illustrations). The legacy `Interpreter` emits a
+hardcoded placeholder. The new pipeline must do real work, including
+round-trip with SVG `<image>`.
+
+## Scope
+
+### P2a — PS → SVG (decode embedded images)
+
+- [ ] Parse `image` operator: width, height, bits/component,
+      matrix, datasource.
+- [ ] Decode datasource: hex string `<...>`, binary string `(...)`,
+      or proc (rare; emit placeholder).
+- [ ] Encode as PNG via `libpng` (same dep `emfsvg` uses) or as inline
+      base64 in an SVG `<image href="data:image/png;base64,...">`.
+- [ ] `imagemask`: 1-bit mask rendered as an SVG `<image>` with
+      opacity or as a clipped fill.
+- [ ] `colorimage`: multi-channel variant.
+
+### P2b — SVG → PS (embed images)
+
+- [ ] Resolve `<image href="...">`:
+  - `data:` URI → decode base64.
+  - file path → read.
+  - http(s) → fetch (optional; require explicit opt-in).
+- [ ] Decode PNG/JPEG to raw raster.
+- [ ] Re-encode as PS hex string for `image` operator.
+
+### P3 — Advanced
+
+- [ ] Subsampling, interpolation, transfer functions.
+- [ ] `setcolorspace` with ICCBased profiles.
+- [ ] Level 3 image dictionaries (`/ImageType 1`, `/ImageType 4`
+      masked images).
+
+## Reference
+
+- PLRM Chapter 7 (Imaging).
+- `../postscript-guide/docs/usage/advanced/images.adoc`.

data/TODO.roadmap/22-forms-and-resources.md

@@ -0,0 +1,25 @@
+# 22 — Forms and Resources
+
+## Status: [ ]
+
+## Why
+
+PS Forms (Level 2) are cached graphics objects — the PS analogue of
+SVG `<defs>` + `<use>`. The SVG→PS direction can naturally emit forms
+for repeated subtrees, but this is P3 work.
+
+## Scope
+
+- [ ] `Form resource`: define a form body, register it in a resource
+      dictionary, invoke via `execform`.
+- [ ] Map SVG `<defs>` + `<use>` to PS Forms.
+- [ ] `BeginData` / `EndData` DSC blocks for embedded binary form
+      bodies.
+- [ ] Form caching: if a form is invoked N times in a program, emit
+      the body once and `execform` N times. (Optimization; current
+      P0 SVG→PS just inlines.)
+
+## Reference
+
+- PLRM Chapter 8 (Forms and Resources).
+- `../postscript-guide/docs/usage/advanced/forms.adoc`.

data/TODO.roadmap/23-level2-level3.md

@@ -0,0 +1,52 @@
+# 23 — PS Level 2 / 3 Coverage
+
+## Status: [ ]
+
+## Why
+
+Real-world EPS files from Illustrator, Inkscape, Ghostscript, and
+Adobe tools use Level 2 / 3 features extensively. The 0.2.0 release
+covers only the common Level 1 subset. This file tracks the rest.
+
+## Level 2
+
+- [ ] **Color spaces**: `setcolorspace`, `setcolor`, `currentcolorspace`.
+  - DeviceGray, DeviceRGB, DeviceCMYK, DeviceN.
+  - CIEBasedABC, CIEBasedA.
+- [ ] **Patterns**: `makepattern`, `setpattern`. Tiling patterns
+      (Type 1) for now; shading patterns under Level 3.
+- [ ] **Halftone**: `setscreen`, `setcolorscreen`, `sethalftone`.
+- [ ] **Images**: `image` with image dictionary (Level 2 form),
+      `imagemask` dictionary form.
+- [ ] **Filters**: ASCIIHexDecode, ASCII85Decode, LZWDecode,
+      FlateDecode, RunLengthDecode, SubFileDecode, CCITTFaxDecode,
+      DCTDecode.
+- [ ] **Binary object format / binary tokens**.
+- [ ] **Composite fonts** (Type 0): FMapType, Encoding, WMode.
+- [ ] **Resource management**: `defineresource`, `findresource`,
+      `resourcestatus`, `enumerate`.
+- [ ] **Page device**: `setpagedevice`, `currentpagedevice` (paper
+      size, duplex, etc.).
+
+## Level 3
+
+- [ ] **Shading** (smooth gradients): types 1-7.
+  - `shfill` with ShadingType 1 (Function-based)
+  - Type 2 (Axial), Type 3 (Radial) — partial support exists; expand.
+  - Type 4 (Free-form Gouraud triangle), Type 5 (Lattice-form Gouraud),
+    Type 6 (Coons patch mesh), Type 7 (Tensor-product patch mesh).
+- [ ] **Clip paths**: More than one clip path at once; `setclipstrokeparams`.
+- [ ] **Image types**: `/ImageType 4` (masked), `/ImageType 3`
+      (interleaved).
+- [ ] **Transparent imaging**: PDF-in-PS extensions, opacity,
+      blending modes.
+- [ ] **CIDFont** improvements: vertical metrics, Unicode CMaps.
+- [ ] **Chromaticity** (`setchromaticity`).
+- [ ] **Paged device** additions: tray selection, install/exit
+      procedures.
+
+## Triage
+
+Each unchecked item should become its own roadmap file when prioritized.
+For now they are tracked collectively; promote to a numbered file when
+scheduled.

data/TODO.roadmap/24-ci-and-release.md

@@ -0,0 +1,42 @@
+# 24 — CI and Release
+
+## Status: [ ]
+
+## Why
+
+Current CI runs `bundle exec rake` (spec + rubocop) on a generic
+workflow. For a 0.2.0 release that adds a whole new direction we need:
+
+- Multi-Ruby matrix.
+- Round-trip regression gate.
+- Compatibility report (which fixtures pass, which fail).
+- Release flow that respects the "no tags, no push to main" rule.
+
+## Tasks
+
+- [ ] `.github/workflows/test.yml` matrix:
+  - Ruby: 3.0, 3.1, 3.2, 3.3, 3.4
+  - OS: ubuntu-latest, macos-latest
+  - Steps: `bundle install`, `bundle exec rake` (spec + rubocop),
+    `bundle exec ruby scripts/run_round_trip.rb`.
+- [ ] `scripts/run_round_trip.rb`: walk `spec/fixtures/round_trip/*.svg`,
+  for each: `Postsvg.to_ps(svg); Postsvg.to_svg(ps)`; assert geometric
+  equivalence via `canon/rspec_matchers`. Print per-fixture result.
+- [ ] `scripts/compatibility_report.rb`: walk
+  `spec/fixtures/ps2svg/*.ps` and `spec/fixtures/eps2svg/*.eps`, run
+  through `Postsvg.to_svg`, summarize pass/fail and any unsupported
+  operators encountered. Output markdown table.
+- [ ] `docs/compatibility_matrix.adoc`: live document, regenerated by
+  the report script, listing supported subset.
+- [ ] `.github/workflows/release.yml`: triggered on tag push `v*` (by
+  a maintainer, never by an agent). Builds gem, pushes to rubygems.org,
+  creates GitHub Release with changelog excerpt.
+- [ ] Version bump policy: bump `lib/postsvg/version.rb` on every PR
+  that changes public API. Use semver: 0.x means anything can move.
+
+## What CI does NOT do
+
+- Push tags. Tags are human actions.
+- Push to main. PRs only.
+- Run on Windows. PS is a Unix/Cocoa-adjacent ecosystem; Windows
+  support is best-effort, not gated.

data/TODO.roadmap/README.md

@@ -0,0 +1,77 @@
+# Postsvg Roadmap — PS/EPS ⇔ SVG
+
+This directory captures every work item needed to take Postsvg from a
+one-directional (PS/EPS → SVG) hand-rolled interpreter to a fully
+bidirectional (PS/EPS ⇔ SVG) transformer with a clean, OCP-compliant,
+model-driven architecture modelled on `emfsvg`.
+
+Each file is one unit of work. Files are numbered in dependency order;
+later files depend on earlier ones unless noted.
+
+## Status legend
+
+- `[ ]` — not started
+- `[~]` — in progress
+- `[x]` — complete
+
+## Index
+
+| #  | File                                | Priority | Status | Summary                                                       |
+|----|-------------------------------------|----------|--------|---------------------------------------------------------------|
+| 00 | `00-architecture.md`                | P0       | [x]    | Target architecture and design rationale                      |
+| 01 | `01-autoload-migration.md`          | P0       | [x]    | Convert `lib/` to Ruby `autoload`                             |
+| 02 | `02-isolate-dormant-code.md`        | P0       | [x]    | Quarantine Parslet/Converter/old SvgGenerator (no deletion)   |
+| 03 | `03-domain-model.md`                | P0       | [x]    | `Postsvg::Model::*` typed PS record value objects             |
+| 04 | `04-lexer.md`                       | P0       | [x]    | Comment-safe PS lexer producing `Model::Token`s               |
+| 05 | `05-parser.md`                      | P0       | [x]    | Token → `Model::Program` (AST with procedure inlining)        |
+| 06 | `06-graphics-state.md`              | P0       | [x]    | `Postsvg::GraphicsContext` immutable snapshot + stack         |
+| 07 | `07-matrix-and-color.md`            | P0       | [x]    | `Matrix` affine + `Color` RGB/Gray/CMYK value objects         |
+| 08 | `08-svg-builder.md`                 | P0       | [x]    | `Postsvg::SvgBuilder` append-only emitter                     |
+| 09 | `09-renderer.md`                    | P0       | [x]    | `Postsvg::Renderer` orchestrator for PS→SVG                   |
+| 10 | `10-visitor.md`                     | P0       | [x]    | `Postsvg::Visitors::PsVisitor` OCP dispatch                   |
+| 11 | `11-operator-coverage.md`           | P1       | [~]    | Comprehensive PS operator coverage (Levels 1/2/3)             |
+| 12 | `12-svg-domain.md`                  | P0       | [x]    | `Postsvg::Svg::*` value objects + Nokogiri parser             |
+| 13 | `13-translation-handlers.md`        | P0       | [x]    | `Postsvg::Translation::Handlers::*` (SVG → PS, OCP)           |
+| 14 | `14-ps-serializer.md`               | P0       | [x]    | `Postsvg::Serializer` Model → PS/EPS source                   |
+| 15 | `15-cli-and-public-api.md`          | P0       | [x]    | Finalise `Postsvg.convert/to_ps/from_svg` + CLI               |
+| 16 | `16-specs.md`                       | P0       | [~]    | Per-component + round-trip spec coverage                      |
+| 17 | `17-docs-sync.md`                   | P1       | [ ]    | README/docs reflect the live pipeline                         |
+| 18 | `18-performance-and-determinism.md` | P2       | [ ]    | Frozen-string literals, dedup, deterministic output           |
+| 19 | `19-error-model.md`                 | P1       | [ ]    | Typed errors: ParseError / UnsupportedError / SerializeError  |
+| 20 | `20-font-and-text.md`               | P2       | [ ]    | Font metrics, glyph outlines, `show`/`ashow`/`widthshow`      |
+| 21 | `21-images.md`                      | P2       | [ ]    | `image`/`imagemask` round-trip with PNG encode/decode         |
+| 22 | `22-forms-and-resources.md`         | P3       | [ ]    | PS Forms, resource dictionary, `ExecuteForm`                  |
+| 23 | `23-level2-level3.md`               | P3       | [ ]    | Shading, patterns, halftone, CID fonts, filters               |
+| 24 | `24-ci-and-release.md`              | P2       | [ ]    | Matrix CI, compatibility report, release flow                 |
+
+## Priority key
+
+- **P0** — without this, the bidirectional pipeline does not exist.
+- **P1** — meaningful completeness gap (operator coverage, error model).
+- **P2** — production hardening (perf, CI, fonts, images).
+- **P3** — full PLRM conformance for advanced users.
+
+## What "done" looks like
+
+For 0.2.0 (this roadmap's target):
+
+```ruby
+# PS/EPS → SVG (existing direction, rebuilt on clean pipeline)
+Postsvg.convert(ps_string)            # => svg string
+Postsvg.convert_file(in, out=nil)
+
+# SVG → PS/EPS (new direction)
+Postsvg.to_ps(svg_string, eps: false) # => ps string
+Postsvg.to_eps(svg_string)            # => eps string
+Postsvg.from_svg_file(path, eps: true)
+```
+
+```sh
+postsvg convert  INPUT.ps|INPUT.eps  [OUTPUT.svg]   # PS/EPS → SVG
+postsvg to-ps    INPUT.svg           [OUTPUT.ps]    # SVG → PS
+postsvg to-eps   INPUT.svg           [OUTPUT.eps]   # SVG → EPS
+postsvg batch    INPUT_DIR           [OUTPUT_DIR]   # auto-detects direction
+```
+
+Test coverage: every public method has specs; round-trip
+(`SVG → PS → SVG`) preserves geometry for the supported subset.

data/docs/.gitignore

@@ -0,0 +1,29 @@
+# Jekyll build artifacts
+_site/
+.sass-cache/
+.jekyll-cache/
+.jekyll-metadata
+
+# Bundler
+.bundle/
+vendor/
+
+# Ruby
+*.gem
+*.rbc
+.config
+coverage/
+InstalledFiles
+lib/bundler/man/
+
+# Temporary files
+*~
+*.swp
+*.swo
+.DS_Store
+
+# Log files
+*.log
+
+# Lock files (optional - comment out if you want to commit)
+Gemfile.lock

data/docs/CHANGELOG.md

@@ -0,0 +1,114 @@
+# Documentation Changelog
+
+All notable changes to the Postsvg documentation will be documented in this file.
+
+## [Unreleased]
+
+### Added - 2025-01-24
+
+**Core Infrastructure:**
+- Added Jekyll configuration with just-the-docs theme (`_config.yml`)
+- Created documentation homepage and navigation hub (`index.adoc`)
+- Added Gemfile for Jekyll dependencies
+- Created .gitignore for build artifacts
+- Added README.md with build and contribution guidelines
+- Created comprehensive documentation plan (DOCUMENTATION_PLAN.md)
+
+**Parent-Level Documentation (10 files):**
+- Added Getting Started overview (`getting-started.adoc`)
+- Added Core Concepts overview (`concepts.adoc`)
+- Added API Reference overview (`api-reference.adoc`)
+- Added CLI Reference overview (`cli-reference.adoc`)
+- Added Architecture documentation (`architecture.adoc`)
+- Added Advanced Topics overview (`advanced-topics.adoc`)
+- Added Development Guide (`development.adoc`)
+- Added Contributing Guide (`contributing.adoc`)
+- Added Troubleshooting Guide (`troubleshooting.adoc`)
+- Added Frequently Asked Questions (`faq.adoc`)
+
+**Getting Started Child Topics:**
+- Added Installation Guide (`getting-started/installation.adoc`)
+  - Platform-specific installation instructions
+  - Docker installation
+  - CI/CD integration examples
+  - Troubleshooting installation issues
+- Added Basic Usage Guide (`getting-started/basic-usage.adoc`)
+  - CLI usage patterns
+  - Ruby API examples
+  - Common workflows
+  - Error handling patterns
+- Added First Conversion Tutorial (`getting-started/first-conversion.adoc`)
+  - Step-by-step tutorial
+  - Creating PostScript files
+  - Converting to SVG
+  - Common issues and solutions
+
+**Documentation Features:**
+- 50+ practical code examples with syntax highlighting
+- 200+ cross-references with file paths and line numbers
+- ASCII diagrams for architecture visualization
+- MECE principles (Mutually Exclusive, Collectively Exhaustive)
+- Standard document structure (Purpose, References, Concepts, Bibliography)
+- Search functionality enabled
+- Mobile-responsive layout
+- AsciiDoc format with rich formatting support
+
+**Quality Standards:**
+- Following LADL specification best practices
+- Consistent document templates
+- Clear hierarchical organization
+- Example-driven content
+- Comprehensive cross-referencing
+
+### Documentation Stats
+- **Total Files**: 19 documentation files
+- **Total Lines**: ~8,500 lines
+- **Parent Topics**: 10/10 (100%)
+- **Child Topics**: 3/44 created (7%)
+- **Code Examples**: 50+
+- **Cross-References**: 200+
+
+## Future Additions
+
+### Priority 1: Essential Child Topics
+- [ ] `getting-started/common-workflows.adoc` - Real-world usage patterns
+- [ ] `api-reference/postsvg-module.adoc` - Main module documentation
+- [ ] `api-reference/converter.adoc` - Converter class details
+- [ ] `api-reference/interpreter.adoc` - Interpreter class details
+- [ ] `cli-reference/convert-command.adoc` - Convert command details
+- [ ] `cli-reference/batch-command.adoc` - Batch command details
+- [ ] `cli-reference/check-command.adoc` - Check command details
+
+### Priority 2: Core Concepts
+- [ ] `concepts/conversion-pipeline.adoc` - Pipeline details
+- [ ] `concepts/graphics-state.adoc` - State management
+- [ ] `concepts/coordinate-systems.adoc` - Coordinate handling
+
+### Priority 3: Architecture
+- [ ] `architecture/conversion-pipeline.adoc` - Pipeline implementation
+- [ ] `architecture/command-registry.adoc` - Command system
+- [ ] `architecture/design-decisions.adoc` - Architectural rationale
+
+## Notes
+
+**Documentation Philosophy:**
+- Write for clarity over cleverness
+- Provide practical examples for every feature
+- Cross-reference related topics extensively
+- Follow MECE principles for organization
+- Keep content up-to-date with code changes
+
+**Contribution Guidelines:**
+- All new features must be documented
+- Documentation changes follow same PR process as code
+- Use standard document template
+- Include code examples that are tested
+- Maintain cross-references
+
+## Version History
+
+- **2025-01-24** - Initial documentation infrastructure created
+  - Jekyll site configured
+  - Parent-level documentation complete
+  - Essential getting started guides added
+  - Ready for deployment to GitHub Pages