svgpng 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b524138f15150416ade4889beb0e274c7a2d95a3c6de0ea922c6c724bcce8e7e
+  data.tar.gz: fd790268f7e181b3b0f8b1ee25226538469591575fd191a850e98c48537670b9
+SHA512:
+  metadata.gz: 700edd9628338fbb3aa4061c960d5a4168607d356723c2cf064d9c3ce4c01d2b636e9f7480aa8a376224b0f678e68d230f5adf081f4f34ba395e3be9bb84fe34
+  data.tar.gz: f080adccda2a82dd122adf67a039f47263df97c04e93c8a1871b9918c5a69f24d13f826377257d8ac6f7da256b1f4bba0291c9025733c6db7bd11e78ae9aa7f6

data/README.adoc

@@ -0,0 +1,81 @@
+= Svgpng
+
+Svgpng is a byte-oriented Ruby API for rendering SVG to PNG. This checkout
+implements the Ruby pipeline, owned native renderer, explicit font selection, and
+pinned PNG encoder. Real native renders, goldens, and an installed developer
+package have been checked locally. Seven-target CI and release artifact
+qualification remain pending; no platform support or cross-platform byte identity
+is advertised yet.
+
+== Current status
+
+The Ruby boundary and fixed rendering contract are recorded in
+link:docs/decisions/svg-to-png.md[the rendering decision]. Rendering requires a
+matching packaged native library; without one it raises
+`Svgpng::UnsupportedPlatformError`. Requiring the Ruby API does not load native
+code or probe system libraries.
+
+== Interface
+
+`Svgpng.render(svg_bytes, profile: {}, fonts: {}, fallback_fonts: [])` accepts
+SVG bytes and caller-supplied fonts. It returns a `Svgpng::Result` with
+`png_bytes`, `width`, `height`, `warnings`, and `font_manifest`. The API accepts
+no filesystem, network, base-directory, resource-map, or loader input. Font
+faces use `Svgpng::FontFace.new(bytes:, source_id:, family: nil)`; metadata is
+read from the font bytes. The optional `family:` value asserts a matching family
+for fallback use and cannot override the supplied metadata.
+
+Fixed limits, sizing, reference policy, font selection, and PNG encoding have
+local native acceptance coverage. The decision document records their contract,
+ownership, target packages, and the checks still required before support can be
+advertised.
+
+== Developer checks
+
+Run `bundle exec rspec` and `bundle exec rubocop`. The default suite includes
+the dependency-free C pixel conversion checks and native loader controls.
+The lazy Fiddle binding covers root attributes, rendering, pixel conversion, and
+PNG encoding. Real font and golden acceptance uses an explicitly built artifact:
+
+[source,sh]
+----
+SVGPNG_TEST_NATIVE_LIBRARY=/absolute/path/to/svgpng.dylib \
+bundle exec rspec spec/renderer_font_integration_spec.rb spec/svgpng/golden_spec.rb
+----
+
+See link:docs/goldens.md[the golden workflow] for corpus coverage and intentional
+regeneration.
+
+The PNG encoder source requires libpng 1.6.59 and zlib 1.3.2. To run its
+round-trip, chunk-profile, deterministic-byte, and allocation-failure assertions,
+provide verified static dependency installations:
+
+[source,sh]
+----
+SVGPNG_LIBPNG_PREFIX=/path/to/libpng-1.6.59 \
+SVGPNG_ZLIB_PREFIX=/path/to/zlib-1.3.2 \
+bundle exec rake native:check_encoder
+----
+
+This developer task invokes a C11 compiler (`SVGPNG_CC`, or Ruby's configured
+compiler) and links the explicit `lib/libpng16.a` and `lib/libz.a` archives.
+Missing dependencies and different header/runtime versions fail the check.
+It does not establish source provenance, a complete renderer dependency closure,
+cross-platform output identity, or an installable native renderer package.
+
+To check a staged eight-gem set, provide its checksum manifest and an empty
+temporary install directory:
+
+[source,sh]
+----
+SVGPNG_RELEASE_DIR=/path/to/staged-gems \
+SVGPNG_RELEASE_MANIFEST=/path/to/checksums.yml \
+SVGPNG_RESOLUTION_DESTINATION=/path/to/empty-install \
+bundle exec rake svgpng:verify_package_resolution
+----
+
+This verifies artifact digests and package metadata, builds a temporary local
+RubyGems index containing the full set, and resolves and installs from that index
+without network access. It does not execute the installed renderer. The test suite
+uses real gem containers with synthetic native payloads; those fixtures establish
+selection and installation behavior only.

data/docs/decisions/svg-to-png.md

@@ -0,0 +1,368 @@
+# SVG-to-PNG rendering contract
+
+**Status: implemented and locally verified; native delivery gates pending.**
+This decision fixes the public behavior and native ownership. The Ruby pipeline,
+owned resvg fork and render ABI, reference policy, explicit-font resolver, PNG
+encoder, golden corpus, and installed developer package have local acceptance
+evidence. Seven-target CI, the complete staged native release set, and
+cross-platform byte identity remain pending. No publication or platform-support
+claim follows from local verification.
+
+## Public Ruby boundary
+
+The public call is:
+
+```ruby
+Svgpng.render(svg_bytes, profile: {}, fonts: {}, fallback_fonts: [])
+```
+
+`svg_bytes` is a byte string containing one SVG document. `profile` is a hash
+with only symbol keys `:width`, `:height`, `:scale`, and `:background`.
+`fonts` maps a requested CSS family spelling to one or more `Svgpng::FontFace`
+objects. `fallback_fonts` is an ordered array of those faces. A face is
+constructed as `Svgpng::FontFace.new(bytes:, source_id:, family: nil)`; its bytes are
+immutable after construction and `source_id` is caller-provided diagnostic
+text. Family names, style, weight, stretch, and glyph coverage are derived from
+OpenType metadata in the bytes. Caller declarations cannot override metadata.
+For fallback faces, the optional `family:` keyword asserts a family spelling
+against the supplied font's metadata; a mismatch raises `FontMetadataError`.
+Omitting it lets the renderer derive the fallback family from metadata.
+The assertion does not change fallback order, source IDs, or manifest identity.
+There is no resource map, base path, directory, filesystem loader, network
+loader, or other external-resource injection API.
+
+Successful rendering returns `Svgpng::Result` with `png_bytes`, integer
+`width` and `height`, ordered structured `warnings`, and a `font_manifest`
+diagnostic describing resolved faces and their source IDs and content digests.
+The manifest never exposes native pointers or engine-specific objects. Digests
+are computed from supplied bytes at runtime; no native-source digest is asserted
+by this decision.
+
+The stable public error classes are `ProfileError`, `InputError`, `FontError`,
+`FontMetadataError`, `DuplicateFontError`, `MissingFamilyError`,
+`MissingGlyphError`, `ForbiddenReferenceError`, `LimitError`, `NativeError`,
+`EncodingError`, and `UnsupportedPlatformError`, all under `Svgpng`. They
+represent observable input, policy, native-boundary, and encoding failures.
+Errors must not include sensitive host paths or resource contents. Invalid
+profile values use `ProfileError`; malformed SVG or URI syntax uses
+`InputError`; invalid OpenType bytes use `FontMetadataError`; duplicate
+normalized faces use `DuplicateFontError`; absent requested families use
+`MissingFamilyError`; uncovered shaped clusters use `MissingGlyphError`;
+prohibited references use `ForbiddenReferenceError`; preflight/pre-allocation
+bounds use `LimitError`; native status failures use `NativeError`; PNG writer
+failures use `EncodingError`. A shell install can be required and its non-render
+API inspected on any platform; only a render call without a matching native
+package raises `UnsupportedPlatformError`, including detected and supported
+platform identifiers.
+
+## Profile validation and output geometry
+
+The implementation accepts only the four profile keys above. Unknown keys and
+string keys are errors. `width` and `height`, when present, must be positive
+Ruby integers (booleans are not integers for this contract), within 32768.
+`scale` must be a positive, finite base-10 decimal string. Parse it as an exact
+rational; reject numeric Ruby values, NaN, infinity, zero, negatives, and
+malformed strings. `background` must be a string. `scale` cannot be combined
+with either dimension. After deriving and rounding dimensions, enforce each
+dimension <= 32768 and total pixels <= 64,000,000.
+
+Resolve the SVG's intrinsic viewport in the pinned parser. CSS px is one source
+unit; physical CSS lengths convert at 96 dpi. Resolve percentage root width or
+height against a 300 by 150 default viewport. Reject other relative root sizing,
+including `em`, `rem`, `ex`, and `calc()`, so the result cannot depend on font
+or host state. Reject non-positive or non-finite resolved dimensions.
+
+Intrinsic-size resolution proceeds as follows:
+
+1. If root width and height both resolve positively, use both.
+2. If exactly one resolves and a positive `viewBox` is usable, derive the
+   missing axis using the viewBox aspect ratio. If no usable viewBox exists,
+   use 300 for a missing width or 150 for a missing height.
+3. If neither resolves, use the positive viewBox width and height when present;
+   otherwise use 300 by 150.
+
+The document's `preserveAspectRatio` (default `xMidYMid meet`) governs drawing
+the viewBox inside this intrinsic viewport. It is separate from the outer
+profile fit described below.
+
+Output size precedence is fixed:
+
+1. Both `width` and `height`: use that exact canvas.
+2. `width` only: derive height from the intrinsic aspect ratio.
+3. `height` only: derive width from the intrinsic aspect ratio.
+4. `scale` only: multiply both intrinsic dimensions by the exact scale.
+5. Empty profile: use intrinsic dimensions.
+
+Round each derived positive dimension by `floor(value + 1/2)`. Clamp a positive
+result below one pixel to one. Do not clamp zero or invalid source values into
+valid output. Check dimensions, pixel count, row stride, and output-buffer
+arithmetic after rounding and before the corresponding allocation. RGBA8 row
+stride is `width * 4`; all multiplications and sums are checked for overflow.
+
+Preserve the intrinsic aspect ratio. For an exact two-axis canvas, compute
+`fit = min(output_width / intrinsic_width, output_height / intrinsic_height)`.
+Scale both viewport axes by `fit` and center them using translations
+`(output_width - scaled_width) / 2` and
+`(output_height - scaled_height) / 2`. Pass those values to the native transform.
+Never stretch axes independently. The outer fit does not replace the SVG's own
+viewBox `preserveAspectRatio` behavior.
+
+The default background is transparent black. Accepted strings are exactly
+`transparent`, `#RRGGBB`, and `#RRGGBBAA`; expand six hex digits with alpha `FF`.
+For each channel, premultiply using integer division:
+`(channel * alpha + 127) / 255`. Fill the complete canvas, including letterbox
+areas, with that premultiplied color before compositing the SVG source-over.
+There is no background operation after RGBA unpremultiplication.
+
+Required profile fixtures include the 300 by 150 no-size/no-viewBox default,
+viewBox-only dimensions, one-axis derivation, both-axis fitting and padding,
+scale, half-pixel rounding, transparent and explicit-alpha backgrounds, and
+each rejected key, type, value, limit, and incompatible combination.
+
+## Fonts and diagnostics
+
+System-font loading is disabled and the package bundles no fonts. Normalize
+family matching with Unicode NFC, CSS quote removal, whitespace collapse, and
+ASCII case folding. Every `fonts` key must match at least one family name found
+in its supplied face metadata. Reject malformed fonts and duplicate normalized
+family/style/weight/stretch faces; do not break ties using hash iteration or
+filesystem order.
+
+The resolver uses resvg's computed CSS family, style, weight, and stretch
+request. Within an exact requested family it follows the pinned resvg/fontdb
+face-matching algorithm. For each shaped cluster, first select an exact-family
+face with full cluster coverage. If none covers it, consider `fallback_fonts`
+strictly in caller order and match style, weight, and stretch within each
+fallback family. The face selected by the resolver callback must be the face
+resvg actually shapes and renders; an independent preflight guess is
+insufficient. If no supplied face covers a cluster, raise `MissingGlyphError`
+with the requested family and missing Unicode scalars.
+
+Emit substitution warnings in first document-use order. Deduplicate by
+requested family, selected family, style/weight/stretch, and missing scalar set.
+Each warning names requested and selected families and the triggering scalars.
+The result's font manifest reports resolved face/source diagnostics and
+byte-derived SHA-256 digests. Real native acceptance compares regular, bold,
+italic, and condensed selection with exact-face controls, including fallback
+selection in both supplied-face orders. The golden corpus records caller family
+order and first-use warning order with deduplication.
+
+## SVG references and parser boundary
+
+At the raw render byte boundary, reject every XML `DOCTYPE` declaration before
+DOM construction or entity expansion. The guard must be token-aware so
+`DOCTYPE` text in comments or CDATA is not mistaken for a declaration. Permit
+same-document fragments such as `href="#symbol"` and `url(#gradient)`, and
+inline `data:` values already contained in the SVG bytes. Reject malformed URI
+syntax as `InputError`.
+
+The pinned XML/CSS parser boundary rejects relative and absolute paths,
+drive and UNC paths, traversal or symlink-looking paths, protocol-relative
+URLs, `file:`, `http:`, `https:`, every other non-`data:` scheme, and CSS
+`@import` before any resolver or decoder can request external bytes. Apply this
+rule to all URI-bearing SVG attributes and CSS `url(...)`. The rejection patch
+returns a stable forbidden-reference status and reference class/document
+location without echoing sensitive host content. It accepts no resource bytes
+and provides no loader callback. Leave resvg's filesystem resources directory
+unset; do not change working directory, materialize files, or use an HTTP
+client. Tests must prove forbidden inputs fail without filesystem or socket
+access, including concurrent renders. Positive controls cover inline `data:`
+raster values and same-document fragments.
+
+## Limits and unsupported SVG behavior
+
+Enforce these fixed limits before the associated allocation:
+
+| Resource | Limit |
+| --- | ---: |
+| SVG input bytes | 16 MiB |
+| Font faces in one request | 64 |
+| One font's bytes | 32 MiB |
+| Total font bytes in one request | 128 MiB |
+| Output width or height | 32768 pixels |
+| Output pixels | 64,000,000 |
+| Row stride and output buffer | checked arithmetic; buffer <= 256 MiB |
+
+Count/byte limits are checked before parsing or copying their associated data;
+dimension, pixel, stride, and output-buffer checks happen after size resolution
+and before allocation. `LimitError` covers only these enforceable checks.
+There is no safe cancellation API for the synchronous resvg call, so there is
+no in-process render-time deadline. Callers who need a wall-clock bound must
+render in a killable isolated process. Static constructs unsupported by the
+pinned resvg release retain resvg's documented behavior; Svgpng does not
+promise a blanket error for every ignored or unsupported construct.
+
+## Native ownership and packaging decision
+
+The native pipeline is owned as follows:
+
+* `native/svgpng_renderer/` owns the Rust C ABI for guarded root attributes,
+  rendering, render-output allocation/freeing, and status diagnostics. Its
+  isolated upstream copy implements font-byte loading, resolver and shaping
+  hooks, and parser-side reference rejection.
+* `native/svgpng_shim/` owns checked RGBA unpremultiplication and the PNG encoder
+  ABI, including its output allocation/freeing. Ruby returns copied owned bytes
+  and never frees memory allocated by a different allocator.
+* The Claricle-maintained resvg fork is based on upstream **v0.48.1**. Its
+  reviewable patch and exact source identity are recorded in
+  `vendor/manifest.yml`: fork commit
+  `1b17e0b252844414bf108b59b78e0a2148b3a91a`, source SHA-256
+  `1a708ce8627a52546e088b377f52b69daa874a4dd59d16b0fef7030c7e3cf1ff`.
+  The upstream C API alone is not assumed to enforce this contract.
+* The shared library statically links the fork, **libpng 1.6.59**, and
+  **zlib 1.3.2**. The packaged shared library is the dependency closure; neither
+  Fiddle nor the dynamic loader may resolve ambient copies of these libraries.
+* `lib/svgpng/native.rb` and `native_render.rb` bind the C ABI through Fiddle;
+  `lib/svgpng/renderer.rb` coordinates Ruby input validation and native calls.
+  Do not compile at gem install time, add a compiled Ruby extension, shell out,
+  or search system library paths.
+* `vendor/manifest.yml` records source/archive and patch digests, the Cargo lock
+  hash, dependency and font license inventory, and measured local build settings.
+  Rust **1.85.0** was used for the local build. The golden manifest records the
+  actual artifact checksum and size. Per-target release binary checksums and
+  sizes remain pending; upstream license inventory still identifies its
+  redistribution audit as pending.
+
+### Local macOS renderer build
+
+`rake native:build_renderer` is a developer-only, host build helper. It
+requires explicit `SVGPNG_CARGO_HOME`, `SVGPNG_RUSTUP_HOME`,
+`SVGPNG_LIBPNG_PREFIX`, `SVGPNG_ZLIB_PREFIX`, and
+`SVGPNG_RENDERER_OUTPUT` values. The Cargo invocation is locked and offline;
+the dependency prefixes must contain `include/png.h` plus `lib/libpng16.a`
+and `include/zlib.h` plus `lib/libz.a`. It combines the Rust static library
+with `native/svgpng_shim/rgba.c` and `encoder.c` and links those exact PNG and
+zlib archives. The output must be a `.dylib` under `/private/tmp`; this task
+does not populate `lib/svgpng/native/`, create a gem, cross-compile, or qualify
+a release target. Apple framework and system-library flags are local linker
+inputs. Rust's reported native static-library requirements on the macOS build
+host were `-lSystem -lc -lm`; no Apple frameworks were reported.
+
+### Local macOS developer package
+
+`rake native:local_package` builds one temporary, developer-labeled
+`arm64-darwin` gem from the Ruby shell and an explicitly supplied `.dylib`.
+Set `SVGPNG_TEST_NATIVE_LIBRARY` to that built artifact,
+`SVGPNG_DEV_PACKAGE_DIR` to an empty directory below `/private/tmp`, and
+`SVGPNG_DEV_LABEL` to a short identifier for the build. The task rejects
+non-regular or symlinked inputs, inspects `otool -L`, and permits only the
+system runtime dependency; libpng and zlib must be statically linked. It stages
+the gem without modifying `lib/svgpng/native/`, checks its gem metadata and
+payload, installs it locally into an isolated `GEM_HOME`, and runs a 2-by-3
+render smoke test using only the installed gem. The package SHA-256 and
+diagnostic output are written beside the gem. This verifies one local package
+and installed API path; it is not release qualification, a published download
+check, or evidence for any other target.
+
+The initial package set is seven native gems and one shell gem, all at the same
+version, initially **0.1.0**:
+
+| RubyGems platform | Native package |
+| --- | --- |
+| `arm64-darwin` | one shared library |
+| `x86_64-darwin` | one shared library |
+| `x86_64-linux` | one shared library |
+| `aarch64-linux` | one shared library |
+| `x86_64-linux-musl` | one shared library |
+| `aarch64-linux-musl` | one shared library |
+| `x64-mingw-ucrt` | one shared library |
+| `ruby` | Ruby API and errors only; no native library |
+
+One native artifact serves every supported Ruby version for its platform. On a
+supported target, RubyGems should select the matching native package when the
+complete set is available. On other targets, the `ruby` shell installs and
+loads without probing ambient libraries; rendering raises
+`UnsupportedPlatformError` with the detected platform and supported targets.
+Do not advertise a native target until that target passes the byte-identity
+gate.
+
+## PNG byte profile
+
+resvg supplies premultiplied RGBA8 rows in top-to-bottom order. For every
+component, including alpha zero, convert to straight RGBA as follows:
+
+```text
+if alpha == 0: straight = 0
+else: straight = min(255, (premultiplied * 255 + alpha / 2) / alpha)
+```
+
+Use checked integer arithmetic. Treat resulting channels as sRGB sample values;
+perform no gamma or color-profile transform. Background compositing is already
+complete in resvg before this conversion.
+
+Encode PNG color type 6 (RGBA), bit depth 8, no interlace, and
+`PNG_FILTER_NONE`. Use zlib level 9, default strategy, window 15, memory level
+8, and a 32 KiB libpng compression buffer. Emit only the PNG signature,
+`IHDR`, one or more deterministic `IDAT` chunks, and `IEND`, in that order.
+Omit time, text, DPI, gamma, chromaticity, sRGB, ICC, EXIF, and every other
+ancillary chunk. Golden tests must inspect structure and chunk order as well as
+the complete file digest.
+
+The encoder checks and committed golden PNGs pin local chunk structure and
+compression output. Matching these bytes on all seven targets remains a delivery
+gate; local results alone do not establish cross-platform byte identity.
+
+## Delivery and evidence gates
+
+The required implementation sequence is captured by owned cards 01, 02, 03,
+and 05 in the Vectory `TODO.svg-to-png` plan. Card 01 establishes the Ruby
+contract and focused profile examples. Card 03 proves the font-selection and
+forbidden-reference hooks. Card 02 builds an unpublished, checksummed local
+candidate set of all seven native gems plus the shell, including a native gem
+for Vectory's development/CI platform. Card 05 proves repeated exact output on
+all seven targets and verifies the staged artifacts by checksum. Until those
+gates pass, native delivery and support remain pending; no 0.1.0 publication or
+cross-platform determinism claim follows from this design document.
+
+The bounded golden corpus must record fixture source and licence, complete
+profile, SVG/font digests and normalized metadata, resvg fork/upstream/patch
+identifiers, libpng/zlib/toolchain/build identifiers, encoding settings,
+expected dimensions, ordered warnings/errors, and expected SHA-256. Positive
+fixtures cover dimensions/viewBox, paths and strokes, gradients/clips/masks,
+alpha/background, unpremultiplication edges, inline raster data, fragments,
+exact fonts, face matching, ordered fallback, partial coverage, warning order,
+and enforceable limits. Negative fixtures cover malformed input, missing font
+or glyph, prohibited references, limits, loader/native failures, and encoding
+failures. Representative unsupported static constructs pin documented resvg
+output behavior without asserting a universal error. Each positive case renders
+twice in a clean process and must match its committed PNG byte-for-byte on all
+seven targets. Host fonts, locale, timezone, working directory, environment,
+and render order/concurrency must not change bytes or warnings.
+
+The artifact set is immutable after the gate. Verify that the seven native gems
+and shell gem match staged SHA-256 values; do not rebuild for publication.
+Publication is one eight-file release set, followed by clean package-resolution
+checks proving native selection and a minimal golden on a supported target and
+shell selection, successful require, and render-time unsupported-platform
+failure on an unsupported target. Golden updates require an explicit
+compatibility change; before 1.0, a byte change requires a minor version bump
+and changelog entry, and from 1.0 it requires a major version bump (working
+rule pending confirmation).
+
+Current verification state: Ruby and real native acceptance cover exact profiles,
+input/reference guards, owned ABI buffers, PNG encoding, and explicit-font
+selection and diagnostics. Sizing goldens include width-only, height-only,
+two-axis containment, decimal scale, and the positive 32768-by-1 boundary. Font
+acceptance includes weight, italic style, condensed stretch, ordered fallback,
+whole-cluster coverage, and first-use deduplicated warnings. Golden checks compare
+repeated clean-process renders with committed PNG bytes and metadata. A local
+macOS developer gem has been installed and rendered through its installed API.
+The shell also builds, installs, and loads without a native library, with the
+documented render-time unsupported-platform failure. Release-set resolution
+specs use real gem containers with synthetic native payloads, proving selection
+and installation only. The seven-target CI qualification and real staged release
+artifact set remain pending, as do publication and the cross-platform support
+gates.
+
+### Initial Ruby preflight representation
+
+The Ruby raw-input guard currently accepts UTF-8 XML bytes (including an optional
+UTF-8 BOM); invalid UTF-8 and NUL-bearing encodings raise `InputError` before parsing.
+The native parser separately enforces URI/CSS and nested-resource policy; this
+Ruby guard does not replace that parser boundary.
+Other XML encodings are a current guard limitation, not a finalized restriction
+on the byte-oriented render contract.
+Intrinsic numeric tokens are bounded to 1024 bytes and an absolute decimal exponent
+of 4096 before rational construction (`LimitError`); values overflowing finite IEEE
+754 magnitude are invalid (`ProfileError`). Positive underflow remains exact for
+rounding and the one-pixel clamp. These limits prevent unbounded big-integer parsing.

data/docs/goldens.md

@@ -0,0 +1,74 @@
+# Reproducing and updating goldens
+
+The corpus at `spec/fixtures/svg_to_png/manifest.json` pins SVG inputs, explicit
+font bytes, PNG bytes, public metadata, typed failures, and encoder settings.
+`bundle exec rake svgpng:verify_manifest` checks the committed checksums without
+loading a native renderer. Native golden specs use the explicitly supplied
+`SVGPNG_TEST_NATIVE_LIBRARY`; see the native build instructions in
+[`svg-to-png.md`](decisions/svg-to-png.md).
+
+The committed corpus includes width-only and height-only sizing, two-axis
+containment, exact decimal scale, and a positive 32768-by-1 canvas boundary. Font
+cases use supplied regular, bold, italic, and condensed faces, caller-ordered
+fallback families, whole-cluster fallback, and first-use warning order with
+deduplication. Native font integration also compares style and stretch selection
+against exact-face controls in both supplied-face orders. These local acceptance
+checks do not establish the pending seven-target byte-identity gate.
+
+Golden changes are intentional compatibility changes. Review the renderer,
+encoder, dependency, version and CHANGELOG impact before regeneration. Build the
+native artifact from the source pinned in `vendor/manifest.yml`, finish that build,
+and keep the artifact unchanged while the task runs. Use an absolute artifact
+path. Do not regenerate with a downloaded or unrelated renderer merely to make a
+comparison pass.
+
+From the repository root, after building the artifact, run:
+
+```sh
+SVGPNG_COMPATIBILITY_UPDATE=yes \
+SVGPNG_COMPATIBILITY_IMPACT='Reviewed: describe the version and CHANGELOG decision here' \
+SVGPNG_TEST_NATIVE_LIBRARY=/absolute/path/to/svgpng.dylib \
+SVGPNG_GOLDEN_BUILD_COMMAND='Record the exact command and build environment used' \
+SVGPNG_GOLDEN_TOOLCHAIN='Record actual rustc -Vv and C compiler --version output' \
+bundle exec rake svgpng:update_goldens
+```
+
+Replace each descriptive value with the reviewed decision and actual build
+information; the task rejects missing or blank values. The artifact extension is
+platform dependent. The build-command and toolchain values are operator supplied
+attestations; hashing the artifact does not prove that it was built from the
+recorded source. Preserve the corresponding build log as review evidence.
+
+The task first verifies existing input/output checksums and encoding settings. For
+an intentional SVG or font change, review and update its input checksum in the
+manifest before running the task. Keep old PNG checksums until regeneration.
+The task prints old and new renderer identifiers and PNG digests, renders every
+entry before writing outputs, and rejects changed error classes. Error details
+and successful metadata are updated for review. If rendering fails or the
+artifact checksum changes during rendering, it writes no golden files. File
+writes themselves are not a filesystem transaction; restore from version control
+if a write fails.
+
+The new `renderer` record replaces the old record using the current vendor
+manifest: upstream/fork commits, patch hashes, renderer source and Cargo lock
+hashes, and all three source archive identities. It also records the SHA256 and
+size of the actual library used, reviewed compatibility impact, explicit build
+command/toolchain information, declared vendor build settings, and running Ruby
+and platform. Declared vendor settings and actual toolchain evidence are distinct.
+A source update therefore updates the golden renderer identity even if PNG bytes
+are unchanged. Keep vendor provenance current before regenerating.
+
+After regeneration, inspect the PNGs and review every manifest change, including
+warnings, font selection, dimensions and failure details. Run the manifest check
+again and the native golden specs against the same artifact:
+
+```sh
+bundle exec rake svgpng:verify_manifest
+SVGPNG_TEST_NATIVE_LIBRARY=/absolute/path/to/svgpng.dylib \
+bundle exec rspec spec/svgpng/golden_spec.rb
+```
+
+Commit intended input, output and provenance changes together. Do not accept
+unexplained byte drift. Fixture origins and font licensing are documented in the
+[corpus README](../spec/fixtures/svg_to_png/README.md); dependency licenses are
+recorded under `vendor/licenses` and `vendor/rust-dependencies.json`.

data/lib/svgpng/errors.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Svgpng
+  class Error < StandardError; end
+  class InputError < Error; end
+  class ProfileError < InputError; end
+  class LimitError < InputError; end
+  class FontError < InputError; end
+  class FontMetadataError < FontError; end
+  class DuplicateFontError < FontError; end
+
+  # An unresolved requested family, optionally identified by native diagnostics.
+  class MissingFamilyError < FontError
+    attr_reader :requested_family
+
+    def initialize(message = nil, requested_family: nil)
+      @requested_family = requested_family&.dup&.freeze
+      super(message)
+    end
+  end
+
+  # Missing Unicode scalar values for an explicitly requested family.
+  class MissingGlyphError < FontError
+    attr_reader :requested_family, :scalars
+
+    def initialize(message = nil, requested_family: nil, scalars: nil)
+      @requested_family = requested_family&.dup&.freeze
+      @scalars = scalars&.dup&.freeze
+      super(message)
+    end
+  end
+
+  # A rejected reference, with structural identifiers rather than resource paths.
+  class ForbiddenReferenceError < InputError
+    attr_reader :reference_class, :location
+
+    def initialize(message = nil, reference_class: nil, location: nil)
+      @reference_class = reference_class&.dup&.freeze
+      @location = location&.dup&.freeze
+      super(message)
+    end
+  end
+
+  class NativeError < Error; end
+  class EncodingError < NativeError; end
+
+  # Raised only when a native-free shell is asked to render.
+  class UnsupportedPlatformError < Error
+    attr_reader :platform, :supported_targets
+
+    def initialize(platform:, supported_targets:)
+      @platform = platform.dup.freeze
+      @supported_targets = supported_targets.map { |target| target.dup.freeze }.freeze
+      super("No packaged SVGPNG renderer for #{platform}; supported targets: #{supported_targets.join(", ")}")
+    end
+  end
+end

data/lib/svgpng/font_face.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module Svgpng
+  # A byte container. Only the pinned native parser may assert face metadata.
+  class FontFace
+    attr_reader :bytes, :source_id, :sha256, :family
+
+    def initialize(bytes:, source_id:, family: nil)
+      validate_bytes!(bytes)
+      raise InputError, "Font source_id must be a nonempty String" unless source_id.is_a?(String) && !source_id.empty?
+
+      validate_family!(family)
+
+      @bytes = bytes.b.freeze
+      @source_id = source_id.dup.freeze
+      @family = family&.dup&.freeze
+      @sha256 = Digest::SHA256.hexdigest(@bytes).freeze
+      freeze
+    end
+
+    private
+
+    def validate_family!(family)
+      return if family.nil? || (family.is_a?(String) && !family.strip.empty?)
+
+      raise InputError, "Fallback font family must be a nonempty String"
+    end
+
+    def validate_bytes!(bytes)
+      raise FontMetadataError, "Font bytes must be a nonempty String" unless bytes.is_a?(String) && !bytes.empty?
+      raise LimitError, "Font exceeds #{Limits::FONT_BYTES} bytes" if bytes.bytesize > Limits::FONT_BYTES
+    end
+  end
+end