typstify 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 02ec11e818e2f0b65a784efb1db7e5e6aeb45f95f3e06189a8bf1ebc56d24811
+  data.tar.gz: ff48f408265ec390b57cc9f071edda050747b11795e15d2a6f07a34ff2037ddf
+SHA512:
+  metadata.gz: 37e3c8c203c967dbfbec72dc0023dae2428919a3606938b00a88ae29b0fd6034cace8481d1db610d51496d0f78e83cf75c2eedcc0f6f18484bbc6eaebd88f6ca
+  data.tar.gz: 29960b89f82e52cd8878a6fdac2a8a978c9acbefa3e11f8e69a96e3fb6d94dadfd52c795d513fe13e1c46a1ad2007ef3985c1047643ace49ed314db70d0581f1

data/CHANGELOG.md

@@ -0,0 +1,49 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] — 2026-08-31
+
+First release.
+
+### Added
+
+- `render pdf:` renderer for any Rails controller, honouring `data:`, `filename:`,
+  `disposition:` and `status:`.
+- `Typstify.render` and `Typstify.render_and_attach` for jobs, mailers and ActiveStorage.
+- **Data mode**: templates are pure `.typ` and read their input from `data.json`, so user
+  content is data rather than source and cannot alter the document.
+- **Workspace isolation**: every render compiles in a fresh temporary directory containing only
+  the template, its `shared/` partials and `data.json`, with Typst rooted there. Symlinks in the
+  shared tree are skipped rather than followed out of the root.
+- **ERB mode** (`.typ.erb`) with the `typ()` escaping helper, one spec per escaped character.
+- Starter template pack: invoice, receipt, report and certificate, each with sample data and a
+  shared `branding.typ`.
+- `rails g typstify:install` and `rails g typstify:template <name>`.
+- `rake typstify:preview[invoices/show]` and `rake typstify:templates`.
+- PDF standard selection: `:ua_1` (PDF/UA-1), `:a_1b`, `:a_2b`, `:a_3b`, `:a_4`, `:pdf_1_7`,
+  `:pdf_2_0`.
+- Strict font checking: a family a template names but nothing can supply raises
+  `FontMissingError` in development and test, and warns in production.
+- `ignore_system_fonts`, which skips the operating system's font directories. Worth knowing:
+  that scan costs roughly 50 ms per render — the starter invoice goes from 58 ms to 4 ms.
+- `package_cache` for vendored Typst Universe packages, for builds with no network.
+- Inter (SIL OFL) bundled, so the starter templates render with no configuration.
+
+### Known limitations
+
+- `on_warning` does not fire for warnings from a **successful** compile. The `typst` binding
+  discards them; it only formats warnings into the message when compilation fails. The hook
+  works for failure-path warnings and for this gem's own font check. Fix opened upstream:
+  [actsasflinn/typst-rb#10](https://github.com/actsasflinn/typst-rb/pull/10).
+- `package_cache` is effective on Linux, where the platform data directory follows
+  `XDG_DATA_HOME`. macOS uses a fixed location that no environment variable redirects.
+- Ruby threads do not speed up rendering: the binding holds the GVL through compilation. Use
+  processes for throughput.
+
+[Unreleased]: https://github.com/TheSoloHacker47/typstify/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/TheSoloHacker47/typstify/releases/tag/v0.1.0

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nikhil Nelson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,235 @@
+# typstify
+
+> PDF generation for Rails on the [Typst](https://typst.app) engine — the wkhtmltopdf replacement.
+> Invoices, reports, certificates: fast, beautiful, accessible (PDF/UA), and no headless Chrome in your Docker image.
+
+[![Gem Version](https://badge.fury.io/rb/typstify.svg)](https://rubygems.org/gems/typstify)
+[![CI](https://github.com/TheSoloHacker47/typstify/actions/workflows/ci.yml/badge.svg)](https://github.com/TheSoloHacker47/typstify/actions)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/TheSoloHacker47/typstify/blob/main/LICENSE)
+
+## Why
+
+Your Rails app generates PDFs. Your options until now:
+
+| | problem |
+|---|---|
+| wicked_pdf / pdfkit | built on **wkhtmltopdf, which is archived and unmaintained** — no security fixes, ancient WebKit |
+| grover / Chrome-based | ships a **full browser** in your production image: hundreds of MB, memory spikes, cold starts |
+| prawn | hand-positioning a coordinate DSL for every invoice line |
+
+[Typst](https://typst.app) is the Rust-based successor to LaTeX: a markup language that
+compiles to PDF in **milliseconds**, reads **JSON natively**, and can emit **PDF/UA-1
+accessible PDFs** — which the European Accessibility Act now effectively requires for
+machine-generated customer documents. `typstify` makes it feel like Rails.
+
+## Quickstart
+
+```ruby
+# Gemfile
+gem "typstify"
+```
+
+```bash
+bundle && rails g typstify:install && rails g typstify:template invoice
+```
+
+```ruby
+# app/controllers/invoices_controller.rb
+def show
+  invoice = Invoice.find(params[:id])
+  render pdf: "invoices/show",
+         data: { number: invoice.number,
+                 total: invoice.total.format,
+                 line_items: invoice.line_items.map { |li| { name: li.name, qty: li.qty, amount: li.amount.format } } },
+         filename: "invoice-#{invoice.number}.pdf"
+end
+```
+
+```typ
+// app/views/invoices/show.typ
+#let data = json("data.json")
+
+= Invoice #data.number
+
+#table(
+  columns: (1fr, auto, auto),
+  [*Item*], [*Qty*], [*Amount*],
+  ..data.line_items.map(i => (i.name, str(i.qty), i.amount)).flatten()
+)
+
+#align(right)[*Total: #data.total*]
+```
+
+That's a complete, styled, paginated invoice. No browser. No dead binaries.
+
+## The data-first design (and why it's safer)
+
+Notice what the template does: it reads your data as **JSON**, it doesn't interpolate strings.
+Your Ruby data can contain anything — Typst markup, `#` directives, quotes — and it renders as
+literal text, because content never becomes code.
+
+Each render also happens in a fresh temporary directory containing only the template, its
+`shared/` partials, and `data.json`. Typst is invoked with that directory as its compile root,
+so a template physically cannot read your `.env`, your credentials, or any other view. Not
+because we filter the path — because the file is not there.
+
+`spec/security/` asserts both properties directly; they are the specs worth reading first.
+
+Prefer classic ERB? `.typ.erb` templates work too — pass every dynamic value through the
+`typ()` escaping helper:
+
+```erb
+= Hello <%= typ(@user.display_name) %>
+```
+
+But use data mode. Future-you says thanks.
+
+## Everywhere you need a PDF
+
+```ruby
+# Background jobs / plain Ruby
+pdf_bytes = Typstify.render(template: "reports/monthly", data: payload)
+
+# Mailers
+attachments["report.pdf"] = Typstify.render(template: "reports/monthly", data: payload)
+
+# ActiveStorage
+Typstify.render_and_attach(user.documents, template: "certificates/completion",
+                           data: cert_data, filename: "certificate.pdf")
+```
+
+Batch-generating 10,000 invoices in a job? Typst's per-document compile time is milliseconds —
+see [`docs/batch-generation.md`](https://github.com/TheSoloHacker47/typstify/blob/main/docs/batch-generation.md) for a Sidekiq/Solid Queue pattern
+and the two settings that make output reproducible.
+
+## Starter templates
+
+`rails g typstify:template <name>` for: **invoice** · **receipt** · **report** ·
+**certificate**. Each comes with sample data and a preview task:
+
+```bash
+rake typstify:preview[invoices/show]
+```
+
+which compiles with the bundled `sample_data.json` into `tmp/previews/`, so you can iterate on
+design without loading your app's initializers or touching the database. Shared branding (logo,
+colours, footer) lives in `app/views/shared/branding.typ` — change it once, every document
+updates.
+
+## Accessible PDFs (EAA / ADA)
+
+HTML→PDF pipelines produce untagged PDFs that fail accessibility requirements. Typst supports
+PDF/UA-1 output; enable it globally:
+
+```ruby
+Typstify.configure { |c| c.pdf_standard = :ua_1 }
+```
+
+Also available: `:a_1b`, `:a_2b`, `:a_3b`, `:a_4`, `:pdf_1_7`, `:pdf_2_0`. PDF/UA-1 requires a
+document title, so set `#set document(title: "…")` in the template.
+
+If you invoice EU customers, your compliance team will hug you.
+
+## Fonts & Docker (read this before deploying)
+
+Typst uses system fonts plus any directories you configure. The reliable production setup is
+vendoring fonts in your app:
+
+```ruby
+c.font_paths = [Rails.root.join("app/assets/fonts")]
+```
+
+A missing font family fails loudly in development and test (`strict_fonts`, on by default
+there) instead of silently substituting a different face in production. Inter ships with the
+gem, so the starter templates work with no configuration at all.
+
+Once your fonts are vendored, turn off the system font scan. It costs about **50 ms per
+render** — the starter invoice goes from 58 ms to 4 ms:
+
+```ruby
+c.ignore_system_fonts = true
+```
+
+Typst Universe packages can be vendored into a directory for network-free builds — with a
+platform caveat that matters. Full guide: [`docs/fonts-and-docker.md`](https://github.com/TheSoloHacker47/typstify/blob/main/docs/fonts-and-docker.md).
+
+## Configuration
+
+```ruby
+# config/initializers/typstify.rb — written by the install generator
+Typstify.configure do |c|
+  c.template_root = Rails.root.join("app/views")                 # default
+  c.shared_dir    = "shared"                                     # partials namespace
+  c.font_paths    = [Rails.root.join("app/assets/fonts")]
+  c.ignore_system_fonts = true                                   # false by default; see below
+  c.package_cache = Rails.root.join("vendor/typst_packages")     # vendored Universe packages
+  c.pdf_standard  = :ua_1                                        # nil by default
+  c.strict_fonts  = Rails.env.local?                             # the default
+  c.on_warning    = ->(warnings, template) { Rails.logger.warn("#{template}: #{warnings}") }
+end
+```
+
+### One honest caveat about `on_warning`
+
+The `typst` binding this gem depends on discards the compiler's warnings when compilation
+**succeeds** — it only formats them into the message when compilation fails. So `on_warning`
+fires for warnings that accompany a compile error, and for the font check this gem performs
+itself, but not yet for arbitrary success-path warnings. There is nothing to listen to until
+that changes upstream, so the fix is in flight there:
+[actsasflinn/typst-rb#10](https://github.com/actsasflinn/typst-rb/pull/10). Rather than ship an
+option that quietly never fires, the missing-font case — the one that actually bites people —
+is checked here, before the compiler runs.
+
+## Errors
+
+| | when |
+|---|---|
+| `Typstify::MissingTemplate` | neither `.typ` nor `.typ.erb` exists; the message lists both paths tried |
+| `Typstify::CompileError` | Typst rejected the document; carries its annotated diagnostic and the line, with your template's name substituted for the workspace path |
+| `Typstify::FontMissingError` | a template names a font nothing can supply, in strict mode |
+| `Typstify::PathError` | a template name resolved outside `template_root` |
+| `ArgumentError` | `data:` contains something JSON cannot represent; the message names the key path, e.g. `data.line_items[0].amount` |
+
+## Migrating from wicked_pdf
+
+There's no HTML→Typst converter — you rewrite each PDF view, and that's genuinely fine: most
+teams have 2–5 PDF views, and each takes minutes, not hours, in Typst. The side-by-side
+walkthrough (a real wicked_pdf invoice vs its Typst version, at a third of the line count):
+[`docs/migrating-from-wicked_pdf.md`](https://github.com/TheSoloHacker47/typstify/blob/main/docs/migrating-from-wicked_pdf.md).
+
+## Compatibility
+
+Ruby ≥ 3.1 · Rails 7.1 – 8.1 · Linux & macOS. PDF compilation is done by the excellent
+[`typst` gem](https://github.com/actsasflinn/typst-rb) (Rust binding to the Typst compiler) —
+this gem is the Rails layer on top, and ships no compiler of its own.
+
+Note: Rails 8.1 requires Ruby 3.4 or newer in practice, because `actionview` uses syntax that
+older Rubies cannot parse. The CI matrix pairs them accordingly.
+
+## Related work
+
+[`typst-rails`](https://github.com/durable-oss/typst-rails) by David J. Berube covers similar
+ground and appeared around the same time; it supports Rage and Sinatra alongside Rails. This
+gem is narrower on purpose — Rails only — and spends that focus on the sandboxed workspace, the
+data-mode security model, the starter template pack and PDF/UA output. Worth comparing both
+against what you need.
+
+## Contributing
+
+```bash
+git clone https://github.com/TheSoloHacker47/typstify && cd typstify
+bin/setup && bundle exec rake
+```
+
+Template pack contributions especially welcome — new document types need sample data, a spec,
+and a golden. See [CONTRIBUTING.md](https://github.com/TheSoloHacker47/typstify/blob/main/CONTRIBUTING.md).
+
+## License
+
+[MIT](https://github.com/TheSoloHacker47/typstify/blob/main/LICENSE). Inter is vendored under the [SIL Open Font License](https://github.com/TheSoloHacker47/typstify/blob/main/fonts/inter/OFL.txt).
+Typst itself is Apache-2.0 by the Typst team — go star it.
+
+## More from me
+
+- [scrubber_rb](https://github.com/TheSoloHacker47/scrubber-rb) — fast PII and secret redaction for Ruby, with a Rust core
+- [bundler-overrule](https://github.com/TheSoloHacker47/bundler-overrule) — force, ban and swap gem versions in your Gemfile

data/SECURITY.md

@@ -0,0 +1,47 @@
+# Security policy
+
+## Supported versions
+
+The latest minor release receives security fixes.
+
+## Reporting a vulnerability
+
+Report privately through GitHub's
+[security advisory form](https://github.com/TheSoloHacker47/typstify/security/advisories/new),
+or by email to thesolohacker47@gmail.com. Please do not open a public issue first.
+
+Expect an acknowledgement within 72 hours, and a fix or a plan within 14 days for anything
+confirmed.
+
+## What counts as a vulnerability here
+
+This gem makes two claims. A credible way to break either is a vulnerability:
+
+1. **Data cannot become code.** Anything passed as `data:` reaches the template through
+   `data.json` and is read as a string. If you can make a value passed through `data:` execute
+   as Typst — call a function, read a file, alter the document's structure — that is a
+   vulnerability.
+2. **A template cannot read outside its workspace.** Each render compiles in a temporary
+   directory holding only the template, its `shared/` partials and `data.json`, with Typst
+   rooted there. If you can make a template read a file that was not copied in for it — through
+   a symlink, a path in `template_root`, a package import, or anything else — that is a
+   vulnerability.
+
+Also in scope: a way to make `Typstify::Resolver` open a file outside `template_root`, and a
+way to make `Typstify::Escaping.typ` emit a string that Typst still parses as markup.
+
+## What does not count
+
+- **ERB mode without `typ()`.** `.typ.erb` interpolates Ruby strings into Typst source; an
+  unescaped value there is injection by construction, which is why `typ()` exists and why the
+  README says to use data mode instead. `spec/security/erb_mode_spec.rb` documents this
+  explicitly.
+- **Templates authored by an attacker.** A `.typ` file in `app/views` is code you deployed. The
+  workspace boundary limits what it can reach, but the threat model is untrusted *data*, not
+  untrusted templates.
+- **Vulnerabilities in the Typst compiler itself.** Report those to
+  [typst/typst](https://github.com/typst/typst); we will pick up the fix when the binding does.
+
+## Credit
+
+Reporters are credited in the changelog and the advisory unless they ask not to be.

data/fonts/inter/OFL.txt

@@ -0,0 +1,92 @@
+Copyright (c) 2016 The Inter Project Authors (https://github.com/rsms/inter)
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+http://scripts.sil.org/OFL
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded,
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION AND CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

data/lib/generators/typstify/install/install_generator.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module Typstify
+  module Generators
+    # rails g typstify:install
+    #
+    # Drops in the initializer and the shared branding partial every starter
+    # template imports.
+    class InstallGenerator < ::Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Creates config/initializers/typstify.rb and app/views/shared/branding.typ"
+
+      def create_initializer
+        template "typstify.rb", "config/initializers/typstify.rb"
+      end
+
+      def create_branding
+        copy_file Typstify.template_pack_path.join("shared", "branding.typ").to_s,
+                  "app/views/shared/branding.typ"
+      end
+
+      def report
+        say ""
+        say "Typstify installed.", :green
+        say ""
+        say "  Next:  rails g typstify:template invoice"
+        say "         rake typstify:preview[invoices/show]"
+        say ""
+        say "  Fonts: templates use Inter, which ships with the gem. To use your own,"
+        say "         vendor the files and set c.font_paths in the initializer."
+        say "         See https://github.com/TheSoloHacker47/typstify/blob/main/docs/fonts-and-docker.md"
+        say ""
+      end
+    end
+  end
+end

data/lib/generators/typstify/install/templates/typstify.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+# Typstify — PDF generation on the Typst engine.
+# https://github.com/TheSoloHacker47/typstify
+
+Typstify.configure do |c|
+  # Where .typ templates live. They are views like any other.
+  c.template_root = Rails.root.join("app/views")
+
+  # Subdirectory of template_root copied into every compile, so
+  # `#import "shared/branding.typ"` resolves from any template.
+  c.shared_dir = "shared"
+
+  # Extra font directories. The gem's bundled Inter is always on the path.
+  # Vendoring the fonts your templates name is the reliable production setup —
+  # see docs/fonts-and-docker.md.
+  # c.font_paths = [Rails.root.join("app/assets/fonts")]
+
+  # Skip the operating system's font directories. Once your fonts are vendored
+  # above, nothing on the system is being used and scanning for it costs about
+  # 50 ms per render: the starter invoice goes from 58 ms to 4 ms. Off by
+  # default because it changes which face a template naming "Helvetica" gets.
+  # c.ignore_system_fonts = true
+
+  # Vendored Typst Universe packages, for builds with no network.
+  # Effective on Linux (so: in your Docker image); see the same doc for why.
+  # c.package_cache = Rails.root.join("vendor/typst_packages")
+
+  # Accessible output. :ua_1 is PDF/UA-1, which the European Accessibility Act
+  # effectively requires of machine-generated customer documents.
+  # Also available: :a_1b, :a_2b, :a_3b, :a_4, :pdf_1_7, :pdf_2_0.
+  # c.pdf_standard = :ua_1
+
+  # Raise instead of warning when a template names a font nothing can supply.
+  # Defaults to true in development and test, false in production.
+  # c.strict_fonts = Rails.env.local?
+
+  # Where warnings go. See the README for what this currently does and does not
+  # catch — the compiler binding drops warnings on a successful compile.
+  # c.on_warning = lambda do |warnings, template|
+  #   Rails.logger.warn("[typstify] #{template}: #{warnings.join("; ")}")
+  # end
+end

data/lib/generators/typstify/template/template_generator.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module Typstify
+  module Generators
+    # rails g typstify:template invoice
+    #
+    # Copies a starter template and its sample data into app/views, so the
+    # preview task works immediately and you have something real to edit.
+    class TemplateGenerator < ::Rails::Generators::NamedBase
+      AVAILABLE = %w[invoice receipt report certificate].freeze
+
+      # The gem's own template pack is the source: this generator copies
+      # starter documents, it does not render ERB of its own.
+      source_root Typstify.template_pack_path.to_s
+
+      class_option :path, type: :string, default: nil,
+                          desc: "Where to put it, e.g. billing/invoice (default: <plural>/show)"
+
+      desc "Copies a starter template (#{AVAILABLE.join(", ")}) into app/views"
+
+      def validate_name
+        return if AVAILABLE.include?(name)
+
+        raise ::Rails::Generators::Error,
+              "Unknown template #{name.inspect}. Available: #{AVAILABLE.join(", ")}"
+      end
+
+      def copy_template
+        copy_file "#{name}/#{name}.typ", "app/views/#{destination}.typ"
+      end
+
+      def copy_sample_data
+        copy_file "#{name}/sample_data.json",
+                  "app/views/#{File.dirname(destination)}/sample_data.json"
+      end
+
+      def ensure_branding
+        return if File.exist?(File.join(destination_root, "app/views/shared/branding.typ"))
+
+        copy_file "shared/branding.typ", "app/views/shared/branding.typ"
+      end
+
+      def report
+        say ""
+        say "Preview it:  rake typstify:preview[#{destination}]", :green
+        say ""
+        say "Render it from a controller:"
+        say ""
+        say "    render pdf: #{destination.inspect},"
+        say "           data: { ... },"
+        say "           filename: #{"#{name}.pdf".inspect}"
+        say ""
+      end
+
+      private
+
+      def destination
+        @destination ||= begin
+          given = options[:path]
+          given.nil? || given.empty? ? "#{name}s/show" : given
+        end
+      end
+    end
+  end
+end

data/lib/tasks/typstify.rake

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+namespace :typstify do
+  desc "Compile a template with its sample data: rake typstify:preview[invoices/show]"
+  task :preview, [:template] do |_task, args|
+    require "typstify"
+    require "json"
+    require "fileutils"
+
+    name = args[:template]
+    abort "Usage: rake typstify:preview[invoices/show]" if name.to_s.empty?
+
+    resolution = Typstify::Resolver.new.call(name)
+    sample = resolution.path.dirname.join("sample_data.json")
+    data =
+      if sample.file?
+        JSON.parse(File.read(sample, encoding: Encoding::UTF_8))
+      else
+        warn "No sample_data.json next to #{resolution.path}; rendering with empty data."
+        {}
+      end
+
+    output = Pathname.new("tmp/previews").join("#{name.tr("/", "-")}.pdf")
+    FileUtils.mkdir_p(output.dirname)
+    output.binwrite(Typstify.render(template: name, data: data))
+
+    puts "Wrote #{output} (#{output.size} bytes)"
+    system("open", output.to_s) if RUBY_PLATFORM.include?("darwin") && ENV["TYPSTIFY_OPEN"] != "0"
+  end
+
+  desc "List the templates Typstify can see"
+  task :templates do
+    require "typstify"
+    root = Typstify.config.template_root
+    found = Dir.glob(root.join("**", "*.typ{,.erb}"))
+    puts "template_root: #{root}"
+    if found.empty?
+      puts "  (none)"
+    else
+      found.each { |path| puts "  #{Pathname.new(path).relative_path_from(root)}" }
+    end
+  end
+end