forme-ruby 0.1.0

data/docs/README.md

@@ -0,0 +1,18 @@
+# Forme Ruby Guides
+
+These guides introduce native PDF rendering, then cover application integration,
+development and release. Each guide states its prerequisites and includes runnable
+examples. Begin with [installation](installation.md).
+
+| Guide | You will learn |
+| --- | --- |
+| [Installation](installation.md) | Runtime requirements, Git/source installs and native packages. |
+| [Rendering](rendering.md) | Binary results, CSS, fonts, diagnostics and errors. |
+| [Rails](rails.md) | Explicit controller rendering and ownership of responses. |
+| [Contributing](../CONTRIBUTING.md) | Build, test and review changes. |
+| [GitHub setup](github-setup.md) | Repository protections, security and publishing setup. |
+| [Security exceptions](security-exceptions.md) | Reviewed, inaccessible upstream advisory paths. |
+| [Releasing](releasing.md) | Qualify packages and prepare trusted publishing. |
+
+See [README](../README.md) for a quick example and [CHANGELOG](../CHANGELOG.md)
+for version-specific changes. The gem remains independent of consumer applications.

data/docs/github-setup.md

@@ -0,0 +1,60 @@
+# Setting Up the GitHub Repository
+
+After reading this guide, you will know what is checked in and which GitHub and
+RubyGems settings a maintainer must enable. These instructions prepare
+`clearstackio/forme-ruby`; they do not authorize pushing or publishing.
+
+## Repository files
+
+The repository includes an MIT license, contributor and security guides, issue
+forms, a pull-request template, CODEOWNERS, Dependabot, CodeQL, dependency review,
+and build/release workflows. Actions are pinned to full commit SHAs; Dependabot
+proposes updates. CI runs on pull requests, main pushes and a weekly schedule.
+PR jobs do not receive publishing credentials. Checkout does not persist tokens.
+
+## Configure GitHub after an authorized push
+
+1. Set the description to “Native HTML and print CSS to PDF for Ruby and Rails,
+   powered by Forme.” Use topics `ruby`, `rails`, `pdf`, `rust`, `html-to-pdf`.
+2. Enable Issues and private vulnerability reporting. Enable the dependency
+   graph, Dependabot alerts, secret scanning and push protection where available.
+   CodeQL is provided as an advanced workflow for Ruby, Rust and GitHub Actions; do not also enable
+   CodeQL default setup.
+3. After the first successful run, protect `main` with a ruleset requiring pull
+   requests, one approving review, resolved conversations, current branches and
+   the `CI required`, CodeQL matrix and dependency-review checks. Select the
+   actual check names from GitHub. Block deletion and force pushes. Require code
+   owner review for changes; add another trusted maintainer so the sole owner's
+   pull requests can be reviewed. Do not silently bypass review to unblock them.
+4. Allow only reviewed Actions, keep the default workflow token read-only, and
+   disable Actions creating or approving pull requests. Keep fork approval on.
+5. Create environment `rubygems`, restrict deployment to `main`, and configure a
+   trusted maintainer as required reviewer with self-review prevented. Confirm
+   an eligible second reviewer exists before enabling this requirement.
+6. Configure RubyGems trusted publishing exactly as [releasing](releasing.md)
+   specifies. Do not store a long-lived publishing key in repository secrets.
+
+The existing remote has older history. The prepared local root commit replaces
+that history only after explicit authorization and consumer coordination. Enable
+force-push protection after that authorized initial transition. A backup local
+branch preserves the prior history. Never force-push just to make CI pass.
+
+## Release evidence
+
+`CI required` fails if any Ruby test, package build, distribution installation or
+audit fails or is skipped. Linux packages are built against glibc 2.28 and checked
+for newer symbol requirements. Compatibility jobs install the same artifact,
+not a newly rebuilt library. Rolling Arch is deliberately retested weekly.
+
+The manual release workflow accepts only a successful CI run from this repository,
+for the exact main commit. It validates package names, versions, platforms and
+license files before trusted publication, and records an attestation for the
+promotion workflow. Keep the successful CI URL with release notes. GitHub
+settings, hosted matrix success and RubyGems setup must be confirmed separately;
+local tests do not establish any of them.
+
+See GitHub's [secure Actions guidance](https://docs.github.com/en/actions/reference/security/secure-use)
+and RubyGems' [trusted publishing guide](https://guides.rubygems.org/trusted-publishing/).
+
+Rust scanning uses CodeQL’s supported `none` build mode with the pinned Rust
+toolchain; see [GitHub’s Rust scanning requirements](https://docs.github.com/en/code-security/reference/code-scanning/codeql/build-options-for-compiled-languages#building-rust).

data/docs/installation.md

@@ -0,0 +1,60 @@
+# Installing Forme Ruby
+
+After reading this guide, you will know how installation differs between Git,
+source and native packages, and how to check the installed renderer.
+
+## Requirements
+
+Use CRuby 3.2 or later. CI covers Ruby 3.2, 3.3, 3.4 and 4.0 on Linux AMD64 and
+macOS ARM64. The core has no Rails dependency. JRuby, Windows, musl and other
+architectures are not qualified release targets.
+
+| Package | Requirement |
+| --- | --- |
+| Git checkout or `ruby` source gem | Rust/Cargo 1.94.0 (qualified toolchain), linker, make, network access to pinned Git and crates.io dependencies. |
+| `arm64-darwin` | Apple Silicon, macOS 15 or later. |
+| `x86_64-linux-gnu` | AMD64 Linux, glibc 2.28 or later. |
+
+## Native qualification
+
+The Linux library is built inside pinned Red Hat UBI 8 with a baseline x86-64
+CPU target. CI rejects symbols requiring glibc newer than 2.28. The same gem
+is installed and renders a PDF in UBI 8, 9 and 10, Ubuntu 24.04 and 26.04,
+and current Arch Linux, without Rust installed. UBI testing exercises the
+RHEL userspace baseline; it is not a certification of every RHEL deployment.
+Use a Ruby 3.2+ installation even when a distribution defaults to older Ruby.
+
+The macOS gem is built on Apple Silicon macOS 15 with a 15.0 deployment target
+and installed on macOS 15 and 26. Both native artifacts are also installed
+across CRuby 3.2, 3.3, 3.4 and 4.0. Hosted qualification of this prepared commit
+is pending. These tests establish installation/rendering compatibility, not
+identical pagination for every font and document.
+
+## Install before the first release
+
+Version 0.1.0 is not yet published to RubyGems. Add the Git dependency shown in
+[README](../README.md) and run `bundle install`. Commit `Gemfile.lock` so builds
+use a reviewed revision. Compilation happens during installation; no compiler
+or dependency download runs during `require` or rendering.
+
+## Install a released version later
+
+After publication is confirmed, use:
+
+```ruby
+gem "forme-ruby", "~> 0.1.0", require: "forme_pdf"
+```
+
+Bundler selects a matching native package where available. A source fallback
+requires the build tools above; it is not a promise of support for every platform.
+Native packages load their own shared library without a system Forme install.
+
+## Verify the installation
+
+```bash
+bundle exec ruby -rforme_pdf -e 'FormePDF.verify!; abort "Invalid PDF" unless FormePDF.render_html("<h1>Hello</h1>").start_with?("%PDF-")'
+```
+
+`verify!` checks loading and ABI compatibility; the render exercises the engine.
+For `FormePDF::LoadError`, check the installed platform and library permissions.
+Reinstall the matching gem instead of copying a library from another platform.

data/docs/rails.md

@@ -0,0 +1,56 @@
+# Rendering PDFs in Rails
+
+After reading this guide, you will know how to render ERB to PDF while retaining
+control of permissions, templates and HTTP responses. The core gem does not
+require Rails; these examples assume an existing Rails application.
+
+## Render explicitly
+
+Select and authorize records in your application's controller before rendering.
+Supply a dedicated HTML template and layout:
+
+```ruby
+html = render_to_string(template: "invoices/pdf", layout: "pdf", formats: [:html])
+pdf = FormePDF.render_html(html)
+send_data pdf, type: "application/pdf", disposition: "inline", filename: "invoice.pdf"
+```
+
+Use `attachment` instead of `inline` when the application's download contract
+requires it. Application code owns routes, record scopes, filenames, asset
+selection and member-data masking. Keep browser print templates separate if
+PDF styling needs different behavior.
+
+## Use the optional adapter
+
+```ruby
+require "forme_pdf/rails"
+
+class InvoicesController < ApplicationController
+  include FormePDF::Rails
+end
+```
+
+From an already authorized action:
+
+```ruby
+pdf = render_forme_pdf(template: "invoices/pdf", layout: "pdf", locals: {invoice: @invoice})
+send_data pdf, type: "application/pdf", disposition: "inline", filename: "invoice.pdf"
+```
+
+`render_forme_pdf` returns bytes; it does not send a response. It passes
+`formats: [:html]` to Rails and forwards rendering options to FormePDF. It does
+not prepare assets, select records, install middleware, add routes or register
+a Railtie. The host application supplies Rails and controls its lifecycle.
+
+## Verify at startup
+
+Applications that require PDF availability can add this initializer:
+
+```ruby
+FormePDF.verify!
+```
+
+Load failure then prevents startup instead of silently disabling PDF reports.
+Test actual rendering in the deployment image too. The adapter spec uses an
+isolated controller double; consumers must test their actual Rails stack and
+report routes. No specific Rails version matrix is claimed by this gem.

data/docs/releasing.md

@@ -0,0 +1,83 @@
+# Preparing and Releasing Forme Ruby
+
+After reading this guide, you will know how to qualify source/native artifacts
+and which steps publish externally. **Current status: 0.1.0 is unreleased.**
+Local preparation does not authorize a push, tag or RubyGems publication.
+
+## Prepare locally
+
+1. Review README, guides, AGENTS, CHANGELOG, gemspec metadata, LICENSE, NOTICE
+   and generated third-party notices. Keep public examples free of private data.
+2. Run the contributor checks and package-install checks. Inspect package files:
+   source gems contain the locked Rust sources/build hook; native gems contain
+   their library and no build hook. Confirm guides and all notices are included.
+3. Keep `lib/forme_pdf/version.rb` and CHANGELOG aligned. Do not date an unreleased
+   entry as if it were published. Review the tested Forme revision and platform
+   minimums whenever native dependencies change.
+4. If history is explicitly squashed, record old/new refs and keep a backup.
+   Previously successful CI does not qualify the new commit. Consumers must not
+   lock to an unpublished SHA. Do not change remote history during local preparation.
+
+## Qualify the release commit later
+
+After a separately authorized GitHub push, require successful `ci.yml` for that
+exact `main` commit. CI tests CRuby 3.2, 3.3, 3.4 and 4.0 on Ubuntu 24.04 and
+macOS 15, builds source/native packages and clean-installs them. The same Linux
+artifact renders on UBI 8/9/10, Ubuntu 24.04/26.04 and Arch rolling; the macOS
+artifact renders on macOS 15/26. See [installation](installation.md). Review the three intended artifacts: `ruby`,
+`arm64-darwin`, and `x86_64-linux-gnu`. No Windows or musl binary is claimed.
+
+The repository already has published history. Replacing it after a local root
+squash would be a remote history rewrite, requiring separate authorization and
+coordination with consumers. Keep the existing reachable consumer pin until then.
+
+Review [GitHub repository setup](github-setup.md) before enabling releases.
+
+## Configure trusted publishing later
+
+Under the `ajaya` RubyGems account, configure a pending publisher for the new gem:
+
+| Field | Value |
+| --- | --- |
+| Gem | `forme-ruby` |
+| GitHub owner | `clearstackio` |
+| Repository | `forme-ruby` |
+| Workflow | `release.yml` |
+| Environment | `rubygems` |
+
+Use the matching GitHub environment and review its protections. A pending
+publisher becomes associated with the gem after its first successful upload.
+See the [official RubyGems trusted publishing guide](https://guides.rubygems.org/trusted-publishing/)
+for setup. No long-lived RubyGems API key is required by this workflow.
+
+## Publish only with explicit authorization
+
+The manual `release.yml` workflow takes a successful CI run ID and verifies its
+commit, branch and workflow path against the release invocation. It downloads
+those tested artifacts and publishes them; it does not rebuild them at release
+time. Package validation requires exactly the three intended platforms and
+matching names/versions. A provenance attestation records the release workflow
+that promotes those artifacts; it does not replace the linked CI build evidence.
+Treat dispatching it as publication, not a dry run.
+
+Before dispatch, confirm the version is available, the package inventory is
+correct and all three tested artifacts belong to the intended commit. Afterward,
+verify all platforms on RubyGems, install from RubyGems in clean environments and
+record the release date/tag. Partial publication cannot be overwritten: inspect
+which platforms succeeded before deciding how to recover. Update consumer
+Gemfiles only after the version is available and qualified.
+
+## Evidence and remaining gates
+
+The earlier `b6d287c` commit passed hosted Linux/macOS CI, including AlmaLinux 10.
+That is historical evidence, not approval of a new local squashed SHA. Hosted CI,
+trusted-publisher configuration and actual publication remain pending for the
+prepared release. No release workflow is run by local package tasks.
+
+Local preparation on 2026-09-18 verified macOS source/native installations and
+native Linux rendering in UBI 8/9, Ubuntu 24.04/26.04 and Arch. The UBI 8 build
+passed the glibc 2.28 symbol check. Arch's local QEMU run needed pacman's sandbox
+disabled; the committed hosted job uses its normal sandbox. UBI 10 could not
+start under the local emulator because it requires an x86-64-v3 CPU. Its hosted
+x86 check remains mandatory. These local results do not qualify the complete
+hosted matrix or authorize publication.

data/docs/rendering.md

@@ -0,0 +1,63 @@
+# Rendering PDFs
+
+After reading this guide, you will know how to render trusted HTML, register
+fonts and inspect diagnostics. Install the gem before running these examples.
+
+## Render HTML
+
+```ruby
+require "forme_pdf"
+
+pdf = FormePDF.render_html("<h1>Invoice</h1>", css: "@page { size: Letter; margin: 0.75in; }")
+File.binwrite("invoice.pdf", pdf)
+```
+
+Input must be a String containing valid text. Valid non-UTF-8 encodings are
+transcoded; binary input is interpreted as UTF-8. The result is a frozen binary
+ASCII-8BIT String. Always write with `File.binwrite`.
+
+## Style pages and supply assets
+
+Forme supports a subset of HTML and print CSS, not browser layout or JavaScript.
+Use dedicated print styles and inspect the resulting pages. Inline CSS or pass
+`css:`; embed images as data URIs. The binding does not fetch remote stylesheets
+or fonts. Local image paths are possible, so use trusted input only.
+
+Supply TTF font bytes explicitly:
+
+```ruby
+pdf = FormePDF.render_html(
+  '<p style="font-family: Report">A document</p>',
+  fonts: [{family: "Report", data: File.binread("report.ttf"), weight: 400, italic: false}]
+)
+```
+
+`css:` and `fonts:` are the supported rendering keywords. Font entries accept
+`family`, `data`, `weight` (default 400) and `italic` (default false). Unknown
+options fail. Register the weights/styles your document needs and check the PDF.
+
+## Inspect diagnostics
+
+```ruby
+result = FormePDF.render_html_result("<p>Report</p>")
+File.binwrite("report.pdf", result.pdf)
+puts result.passes
+result.warnings.each { |warning| warn warning }
+```
+
+The result and its warning array/strings are frozen. Unsupported CSS can produce
+warnings without a failed render. Review warnings using synthetic input; do not
+send sensitive document content or diagnostics to public logs.
+
+## Handle errors and concurrency
+
+`FormePDF::LoadError` and `FormePDF::RenderError` inherit `FormePDF::Error`.
+Invalid caller arguments can raise `ArgumentError` or encoding errors. Avoid
+rescuing everything and returning an HTML success response as if it were a PDF.
+
+Each render owns independent native result storage. Ruby copies the bytes and
+frees that result even when copying or decoding fails. Native calls release the
+Ruby lock; concurrent callers do not share output buffers. Ruby interruption is
+masked during native ownership, so thread cancellation is not a render deadline.
+Use process-level resource limits for large or hostile inputs. The API is not a
+sandbox and exposes no per-render timeout.

data/docs/security-exceptions.md

@@ -0,0 +1,41 @@
+# Reviewing Native Dependency Advisories
+
+After reading this guide, you will understand the current audit exceptions and
+when they must be reconsidered. Review date: 2026-09-18.
+
+## Scope
+
+These exceptions acknowledge vulnerable dependencies; they do not patch them.
+They apply only to Forme revision `f408920e632c59da0651b5b6d32f8c1397477673`,
+the locked dependency graph and the HTML-only Ruby API. Rendering is not a
+sandbox for arbitrary HTML. See [SECURITY](../SECURITY.md).
+
+| Advisory | Locked package | Why the affected path is inaccessible |
+| --- | --- | --- |
+| [RUSTSEC-2026-0195](https://rustsec.org/advisories/RUSTSEC-2026-0195.html) | quick-xml 0.37.5 | The engine uses plain `Reader`, never `NsReader` or its namespace resolver. |
+| [RUSTSEC-2026-0194](https://rustsec.org/advisories/RUSTSEC-2026-0194.html) | quick-xml 0.37.5 | Duplicate-attribute handling is vulnerable in upstream SVG parsing, but the HTML mapper never constructs SVG nodes. |
+| [RUSTSEC-2023-0071](https://rustsec.org/advisories/RUSTSEC-2023-0071.html) | rsa 0.9.10 | Private-key operations occur only in certification, which HTML conversion leaves disabled. |
+
+## Verify the boundaries
+
+`ext/forme_pdf/src/lib.rs` accepts only CSS and fonts, rejects unknown options,
+and calls `forme_pdf_html::render_html` with default HTML options. In the pinned
+upstream tree, `html/src/dom.rs` parses with html5ever. `html/src/map.rs` has no
+`NodeKind::Svg` construction and initializes `certification: None`.
+`engine/src/image_loader.rs` accepts JPEG, PNG and WebP, so an SVG image cannot
+enter the XML parser through an image URL. Font registration does not parse XML.
+Only `forme-pdf` consumes quick-xml and rsa in the locked dependency graph.
+
+The exceptions are configured in `.cargo/audit.toml`. Scheduled CI continues to
+report other advisories, including unmaintained dependency warnings. Re-review
+all exceptions when the engine pin, options schema, Cargo features or exports
+change, especially SVG, raw document/JSON, imports or signing. Check the exact
+new call paths; do not carry exceptions forward automatically.
+
+## Remove exceptions when possible
+
+Prefer an upstream update to quick-xml 0.41+ or feature-gating unused SVG and
+certification dependencies. The current upstream 0.37 constraint prevents a
+lockfile-only upgrade. RustSec lists no patched RSA version at review time;
+a version bump alone is not remediation. Track upstream fixes during the weekly
+dependency review and remove an exception once the dependency is fixed or removed.

data/examples/hello.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require "forme_pdf"
+
+pdf = FormePDF.render_html("<h1>Hello from Ruby</h1>", css: "@page { size: Letter; }")
+File.binwrite(ARGV.fetch(0, "hello.pdf"), pdf)