react_on_rails 17.0.0.rc.2 → 17.0.0.rc.3

data/lib/generators/react_on_rails/templates/base/base/config/webpack/commonWebpackConfig.js.tt

@@ -11,7 +11,87 @@ const commonOptions = {
   },
 };
 
+<% if use_tailwind? -%>
+const tailwindPostcssPlugin = require('@tailwindcss/postcss');
+
+const tailwindPostcssLoader = {
+  loader: 'postcss-loader',
+  options: {
+    postcssOptions: {
+      plugins: [tailwindPostcssPlugin],
+    },
+  },
+};
+
+const loaderName = (loader) => {
+  if (typeof loader === 'string') return loader;
+  if (loader && typeof loader.loader === 'string') return loader.loader;
+  return '';
+};
+
+const postcssLoaderUsesTailwind = (loader) => {
+  const plugins = loader?.options?.postcssOptions?.plugins || [];
+  const tailwindPluginName = tailwindPostcssPlugin.postcssPlugin || tailwindPostcssPlugin.name;
+
+  return plugins.some((plugin) => {
+    if (plugin === tailwindPostcssPlugin) return true;
+    if (!tailwindPluginName) return false;
+
+    return plugin?.postcssPlugin === tailwindPluginName || plugin?.name === tailwindPluginName;
+  });
+};
+
+const mergeTailwindPostcssLoader = (loader) => {
+  if (typeof loader === 'string') return tailwindPostcssLoader;
+  if (postcssLoaderUsesTailwind(loader)) return loader;
+
+  const existingOptions = loader.options || {};
+  const existingPostcssOptions = existingOptions.postcssOptions || {};
+  const existingPlugins = existingPostcssOptions.plugins || [];
+
+  return {
+    ...loader,
+    options: {
+      ...existingOptions,
+      postcssOptions: {
+        ...existingPostcssOptions,
+        plugins: [...existingPlugins, tailwindPostcssPlugin],
+      },
+    },
+  };
+};
+
+const addTailwindPostcssLoader = (webpackConfig) => {
+  const rules = webpackConfig.module?.rules;
+  if (!Array.isArray(rules)) return webpackConfig;
+
+  rules.forEach((rule) => {
+    if (!Array.isArray(rule.use)) return;
+
+    const postcssLoaderIndex = rule.use.findIndex((loader) => loaderName(loader).includes('postcss-loader'));
+    if (postcssLoaderIndex !== -1) {
+      rule.use[postcssLoaderIndex] = mergeTailwindPostcssLoader(rule.use[postcssLoaderIndex]);
+      return;
+    }
+
+    const cssLoaderIndex = rule.use.findIndex((loader) => loaderName(loader).includes('css-loader'));
+    if (cssLoaderIndex === -1) return;
+
+    rule.use.splice(cssLoaderIndex + 1, 0, tailwindPostcssLoader);
+  });
+
+  return webpackConfig;
+};
+
+<% end -%>
 // Copy the object using merge b/c the baseClientWebpackConfig and commonOptions are mutable globals
-const commonWebpackConfig = () => merge({}, baseClientWebpackConfig, commonOptions);
+const commonWebpackConfig = () => {
+  const webpackConfig = merge({}, baseClientWebpackConfig, commonOptions);
+<% if use_tailwind? -%>
+  return addTailwindPostcssLoader(webpackConfig);
+<% else -%>
+  return webpackConfig;
+<% end -%>
+};
 
 module.exports = commonWebpackConfig;

data/lib/generators/react_on_rails/templates/base/tailwind/app/javascript/src/HelloWorld/ror_components/HelloWorld.client.jsx

@@ -0,0 +1,30 @@
+import React, { useState } from 'react';
+import '../../../stylesheets/application.css';
+
+const HelloWorld = (props) => {
+  const [name, setName] = useState(props.name);
+
+  return (
+    <section className="mx-auto max-w-xl rounded-lg border border-slate-200 bg-white p-6 text-slate-900 shadow-sm">
+      <p className="text-sm font-semibold uppercase text-sky-600">React on Rails + Tailwind CSS</p>
+      <h3 className="mt-2 text-2xl font-bold">Hello, {name}!</h3>
+      <p className="mt-3 text-sm leading-6 text-slate-600">
+        This component is server-rendered by Rails and styled by Tailwind CSS v4.
+      </p>
+      <form className="mt-5">
+        <label className="block text-sm font-medium text-slate-700" htmlFor="name">
+          Say hello to:
+          <input
+            id="name"
+            className="mt-2 w-full rounded-md border border-slate-300 px-3 py-2 shadow-sm focus:border-sky-500 focus:outline-hidden focus:ring-2 focus:ring-sky-200"
+            type="text"
+            value={name}
+            onChange={(e) => setName(e.target.value)}
+          />
+        </label>
+      </form>
+    </section>
+  );
+};
+
+export default HelloWorld;

data/lib/generators/react_on_rails/templates/base/tailwind/app/javascript/src/HelloWorld/ror_components/HelloWorld.client.tsx

@@ -0,0 +1,34 @@
+import React, { useState } from 'react';
+import '../../../stylesheets/application.css';
+
+interface HelloWorldProps {
+  name: string;
+}
+
+const HelloWorld: React.FC<HelloWorldProps> = (props) => {
+  const [name, setName] = useState(props.name);
+
+  return (
+    <section className="mx-auto max-w-xl rounded-lg border border-slate-200 bg-white p-6 text-slate-900 shadow-sm">
+      <p className="text-sm font-semibold uppercase text-sky-600">React on Rails + Tailwind CSS</p>
+      <h3 className="mt-2 text-2xl font-bold">Hello, {name}!</h3>
+      <p className="mt-3 text-sm leading-6 text-slate-600">
+        This component is server-rendered by Rails and styled by Tailwind CSS v4.
+      </p>
+      <form className="mt-5">
+        <label className="block text-sm font-medium text-slate-700" htmlFor="name">
+          Say hello to:
+          <input
+            id="name"
+            className="mt-2 w-full rounded-md border border-slate-300 px-3 py-2 shadow-sm focus:border-sky-500 focus:outline-hidden focus:ring-2 focus:ring-sky-200"
+            type="text"
+            value={name}
+            onChange={(e) => setName(e.target.value)}
+          />
+        </label>
+      </form>
+    </section>
+  );
+};
+
+export default HelloWorld;

data/lib/generators/react_on_rails/templates/base/tailwind/app/javascript/stylesheets/application.css

@@ -0,0 +1 @@
+@import "tailwindcss";

data/lib/generators/react_on_rails/templates/redux/tailwind/app/javascript/bundles/HelloWorld/components/HelloWorld.jsx

@@ -0,0 +1,25 @@
+import React from 'react';
+
+const HelloWorld = ({ name, updateName }) => (
+  <section className="mx-auto max-w-xl rounded-lg border border-slate-200 bg-white p-6 text-slate-900 shadow-sm">
+    <p className="text-sm font-semibold uppercase text-sky-600">React on Rails + Redux + Tailwind CSS</p>
+    <h3 className="mt-2 text-2xl font-bold">Hello, {name}!</h3>
+    <p className="mt-3 text-sm leading-6 text-slate-600">
+      This Redux-backed component is server-rendered by Rails and styled by Tailwind CSS v4.
+    </p>
+    <div className="mt-5">
+      <label className="block text-sm font-medium text-slate-700" htmlFor="name">
+        Say hello to:
+        <input
+          id="name"
+          className="mt-2 w-full rounded-md border border-slate-300 px-3 py-2 shadow-sm focus:border-sky-500 focus:outline-hidden focus:ring-2 focus:ring-sky-200"
+          type="text"
+          value={name}
+          onChange={(e) => updateName(e.target.value)}
+        />
+      </label>
+    </div>
+  </section>
+);
+
+export default HelloWorld;

data/lib/generators/react_on_rails/templates/redux/tailwind/app/javascript/bundles/HelloWorld/components/HelloWorld.tsx

@@ -0,0 +1,29 @@
+import React from 'react';
+import type { PropsFromRedux } from '../containers/HelloWorldContainer';
+
+// Component props are inferred from Redux container
+type HelloWorldProps = PropsFromRedux;
+
+const HelloWorld: React.FC<HelloWorldProps> = ({ name, updateName }) => (
+  <section className="mx-auto max-w-xl rounded-lg border border-slate-200 bg-white p-6 text-slate-900 shadow-sm">
+    <p className="text-sm font-semibold uppercase text-sky-600">React on Rails + Redux + Tailwind CSS</p>
+    <h3 className="mt-2 text-2xl font-bold">Hello, {name}!</h3>
+    <p className="mt-3 text-sm leading-6 text-slate-600">
+      This Redux-backed component is server-rendered by Rails and styled by Tailwind CSS v4.
+    </p>
+    <div className="mt-5">
+      <label className="block text-sm font-medium text-slate-700" htmlFor="name">
+        Say hello to:
+        <input
+          id="name"
+          className="mt-2 w-full rounded-md border border-slate-300 px-3 py-2 shadow-sm focus:border-sky-500 focus:outline-hidden focus:ring-2 focus:ring-sky-200"
+          type="text"
+          value={name}
+          onChange={(e) => updateName(e.target.value)}
+        />
+      </label>
+    </div>
+  </section>
+);
+
+export default HelloWorld;

data/lib/react_on_rails/doctor.rb

@@ -3,9 +3,11 @@
 require "json"
 require "erb"
 require "stringio"
+require "tempfile"
 require "timeout"
 require "yaml"
 require_relative "utils"
+require_relative "version"
 require_relative "config_path_resolver"
 require_relative "shakapacker_config_helpers"
 require_relative "dev/server_mode"
@@ -116,15 +118,69 @@ module ReactOnRails
     # than this is a sign of an unexpectedly broad pattern, not legitimate config.
     RENDERER_CACHE_DEPLOY_SCRIPT_GLOB_MAX_MATCHES = 100
 
-    def initialize(verbose: false, fix: false)
+    # Supported output formats. :text is the human-readable default; :json emits
+    # a machine-readable report (see JSON_SCHEMA_VERSION below).
+    OUTPUT_FORMATS = %i[text json].freeze
+
+    # Version of the machine-readable doctor report schema (FORMAT=json).
+    # Bump ONLY on breaking changes to the shape below. Schema (v1):
+    #
+    #   {
+    #     "schema_version": 1,
+    #     "ror_version": "<ReactOnRails::VERSION>",
+    #     "status": "pass" | "warn" | "fail",          // worst check status
+    #     "checks": [
+    #       {
+    #         "id": "<stable snake_case id from CHECK_SECTIONS>",
+    #         "title": "<human section title>",
+    #         "status": "pass" | "warn" | "fail",
+    #         "message": "<most severe message content, or null>",
+    #         "details": [ { "level": "success|warning|error|info", "content": "..." } ]
+    #       }
+    #     ],
+    #     "summary": { "pass": <count>, "warn": <count>, "fail": <count> }
+    #   }
+    #
+    # No timestamp is included so output is deterministic for a given app state.
+    # Exit code semantics match text mode: 1 if any check fails, else 0.
+    JSON_SCHEMA_VERSION = 1
+
+    # Doctor check sections. The :id values are part of the stable JSON schema
+    # contract (consumed by agents/tooling) — never rename or reuse them; add new
+    # sections with new ids instead.
+    CHECK_SECTIONS = [
+      { id: "environment_prerequisites", title: "Environment Prerequisites", method: :check_environment },
+      { id: "react_on_rails_versions", title: "React on Rails Versions", method: :check_react_on_rails_versions },
+      { id: "react_on_rails_packages", title: "React on Rails Packages", method: :check_packages },
+      { id: "javascript_package_dependencies", title: "JavaScript Package Dependencies",
+        method: :check_dependencies },
+      { id: "key_configuration_files", title: "Key Configuration Files", method: :check_key_files },
+      { id: "configuration_analysis", title: "Configuration Analysis", method: :check_configuration_details },
+      { id: "bin_dev_launcher_setup", title: "bin/dev Launcher Setup", method: :check_bin_dev_launcher },
+      { id: "rails_integration", title: "Rails Integration", method: :check_rails },
+      { id: "bundler_configuration", title: "Bundler Configuration", method: :check_bundler_configuration },
+      { id: "testing_setup", title: "Testing Setup", method: :check_testing_setup },
+      { id: "development_environment", title: "Development Environment", method: :check_development },
+      { id: "react_on_rails_pro_setup", title: "React on Rails Pro Setup", method: :check_pro_setup },
+      { id: "react_server_components", title: "React Server Components", method: :check_rsc_setup }
+    ].freeze
+
+    def initialize(verbose: false, fix: false, format: :text)
       @verbose = verbose
       @fix = fix
+      @format = format.respond_to?(:to_sym) ? format.to_sym : format
+      unless OUTPUT_FORMATS.include?(@format)
+        raise ArgumentError, "Invalid doctor format #{format.inspect}; expected one of #{OUTPUT_FORMATS.join(', ')}"
+      end
+
       @checker = SystemChecker.new
       @test_output_path_strategy = :unknown
       @rails_environment_loaded = false
     end
 
     def run_diagnosis
+      return run_json_diagnosis if format == :json
+
       print_header
       run_all_checks
       print_summary
@@ -135,7 +191,7 @@ module ReactOnRails
 
     private
 
-    attr_reader :verbose, :fix, :checker
+    attr_reader :verbose, :fix, :format, :checker
 
     def print_header
       puts Rainbow("\n#{'=' * 80}").cyan
@@ -156,35 +212,139 @@ module ReactOnRails
     end
 
     def run_all_checks
-      checks = [
-        ["Environment Prerequisites", :check_environment],
-        ["React on Rails Versions", :check_react_on_rails_versions],
-        ["React on Rails Packages", :check_packages],
-        ["JavaScript Package Dependencies", :check_dependencies],
-        ["Key Configuration Files", :check_key_files],
-        ["Configuration Analysis", :check_configuration_details],
-        ["bin/dev Launcher Setup", :check_bin_dev_launcher],
-        ["Rails Integration", :check_rails],
-        ["Bundler Configuration", :check_bundler_configuration],
-        ["Testing Setup", :check_testing_setup],
-        ["Development Environment", :check_development],
-        ["React on Rails Pro Setup", :check_pro_setup],
-        ["React Server Components", :check_rsc_setup]
-      ]
-
-      checks.each do |section_name, check_method|
+      CHECK_SECTIONS.each do |section|
         initial_message_count = checker.messages.length
-        send(check_method)
+        send(section[:method])
 
         # Only print header if messages were added
         next unless checker.messages.length > initial_message_count
 
-        print_section_header(section_name)
+        print_section_header(section[:title])
         print_recent_messages(initial_message_count)
         puts
       end
     end
 
+    # JSON output mode: stdout carries ONLY the JSON report (schema documented
+    # at JSON_SCHEMA_VERSION); any stray output produced by checks is routed to
+    # stderr so the report stays parseable.
+    def run_json_diagnosis
+      results = nil
+      stray_output = capture_stdout { results = collect_check_results }
+      $stderr.print(stray_output) unless stray_output.empty?
+
+      puts JSON.pretty_generate(build_json_report(results))
+      exit(diagnosis_exit_code)
+    end
+
+    def collect_check_results
+      CHECK_SECTIONS.map do |section|
+        initial_message_count = checker.messages.length
+        send(section[:method])
+
+        {
+          id: section[:id],
+          title: section[:title],
+          messages: checker.messages[initial_message_count..]
+        }
+      end
+    end
+
+    # Captures everything written to the stdout file descriptor (fd 1) while the
+    # block runs — including direct STDOUT writes, child processes inheriting
+    # fd 1, and C extensions — not just Ruby-level $stdout. Reassigning $stdout
+    # to a StringIO would miss those, letting stray bytes corrupt the JSON report.
+    #
+    # NOT thread-safe: STDOUT.reopen redirects fd 1 process-wide, so any
+    # concurrent thread writing to stdout is captured too. Doctor runs only as
+    # a single-threaded rake task today; revisit before using in threaded code.
+    # rubocop:disable Style/GlobalStdStream
+    def capture_stdout
+      captured_file = Tempfile.new("react_on_rails_doctor_stdout")
+      original_stdout = $stdout
+      original_fd = STDOUT.dup
+      STDOUT.flush
+      STDOUT.reopen(captured_file.path, "w")
+      $stdout = STDOUT
+      yield
+      STDOUT.flush
+      File.read(captured_file.path)
+    ensure
+      begin
+        STDOUT.flush
+      rescue IOError, SystemCallError
+        nil
+      end
+      if original_fd
+        begin
+          STDOUT.reopen(original_fd)
+        ensure
+          original_fd.close
+        end
+      end
+      $stdout = original_stdout if original_stdout
+      captured_file&.close!
+    end
+    # rubocop:enable Style/GlobalStdStream
+
+    def build_json_report(results)
+      checks = results.map { |result| build_check_entry(result) }
+      statuses = checks.map { |check| check[:status] }
+
+      {
+        schema_version: JSON_SCHEMA_VERSION,
+        ror_version: ReactOnRails::VERSION,
+        status: overall_status(statuses),
+        checks:,
+        summary: {
+          pass: statuses.count("pass"),
+          warn: statuses.count("warn"),
+          fail: statuses.count("fail")
+        }
+      }
+    end
+
+    def build_check_entry(result)
+      messages = result[:messages]
+      status = check_status(messages)
+
+      {
+        id: result[:id],
+        title: result[:title],
+        status:,
+        message: primary_message(messages, status),
+        details: messages.map { |message| { level: message[:type].to_s, content: message[:content] } }
+      }
+    end
+
+    def check_status(messages)
+      if messages.any? { |message| message[:type] == :error }
+        "fail"
+      elsif messages.any? { |message| message[:type] == :warning }
+        "warn"
+      else
+        "pass"
+      end
+    end
+
+    def overall_status(statuses)
+      if statuses.include?("fail")
+        "fail"
+      elsif statuses.include?("warn")
+        "warn"
+      else
+        "pass"
+      end
+    end
+
+    def primary_message(messages, status)
+      severity = { "fail" => :error, "warn" => :warning }[status]
+      return nil unless severity
+
+      message = messages.find { |msg| msg[:type] == severity }
+      message && message[:content]
+    end
+
     def print_section_header(section_name)
       puts Rainbow("#{section_name}:").blue.bold
       puts Rainbow("-" * (section_name.length + 1)).blue
@@ -1765,14 +1925,17 @@ module ReactOnRails
     def exit_with_status
       if checker.errors?
         puts Rainbow("❌ Doctor found critical issues. Please address errors above.").red.bold
-        exit(1)
       elsif checker.warnings?
         puts Rainbow("⚠️  Doctor found some issues. Consider addressing warnings above.").yellow
-        exit(0)
       else
         puts Rainbow("🎉 All checks passed! Your React on Rails setup is healthy.").green.bold
-        exit(0)
       end
+
+      exit(diagnosis_exit_code)
+    end
+
+    def diagnosis_exit_code
+      checker.errors? ? 1 : 0
     end
 
     # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity

data/lib/react_on_rails/font_helper.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+
+module ReactOnRails
+  # First-party font optimization helper, a `next/font/local` analog for Rails.
+  #
+  # Given a self-hosted (committed + fingerprinted) `.woff2` file already served by
+  # your asset pipeline, this returns the markup an ERB view should place in the
+  # document `<head>`:
+  #
+  #   1. `<link rel="preload" as="font" type="font/woff2" crossorigin>` so the
+  #      browser fetches the font in parallel with the first paint;
+  #   2. an `@font-face` rule with `font-display: swap` so text renders immediately
+  #      with a fallback and swaps in the web font when ready;
+  #   3. an optional metric-matched fallback `@font-face` (`size-adjust` plus
+  #      `ascent-override` / `descent-override` / `line-gap-override`) so the system
+  #      fallback occupies the same space as the web font, eliminating the layout
+  #      shift (CLS) that normally happens on the swap.
+  #
+  # It mirrors the `<head>`-injection convention used by `react_component_hash`
+  # (see `ReactOnRails::Helper`): the caller wraps the return value in
+  # `content_for :head`, and the layout yields it inside `<head>`.
+  #
+  # Example (ERB view):
+  #
+  #   <% content_for :head do %>
+  #     <%= react_on_rails_font_face(
+  #           family: "Inter",
+  #           src: asset_path("inter-latin-400-normal.woff2"),
+  #           weight: 400,
+  #           fallback: {
+  #             family: "Arial",
+  #             size_adjust: "107.12%",
+  #             ascent_override: "90.44%",
+  #             descent_override: "22.52%",
+  #             line_gap_override: "0.0%"
+  #           }
+  #         ) %>
+  #   <% end %>
+  #
+  # Then set the CSS font stack to the web font followed by its fallback face, e.g.
+  # `font-family: "Inter", "Inter Fallback", sans-serif;`.
+  module FontHelper
+    extend ActiveSupport::Concern
+
+    # CSS/HTML metacharacters that would let an argument break out of the
+    # `<style>` / `<link>` context this helper emits.
+    UNSAFE_TOKEN = /[<>"\r\n]/
+
+    # Emits the preload `<link>`, the primary `@font-face`, and (when `fallback:`
+    # is supplied) a metric-matched fallback `@font-face`.
+    #
+    # @param family [String] CSS font-family name for the web font (e.g. "Inter").
+    # @param src [String] URL/path to the `.woff2` (typically `asset_path(...)`).
+    # @param weight [Integer, String] `font-weight` (default 400). A range like
+    #   "100 900" is valid for variable fonts.
+    # @param style [String] `font-style` (default "normal").
+    # @param display [String] `font-display` (default "swap").
+    # @param unicode_range [String, nil] optional `unicode-range` to subset the face.
+    # @param preload [Boolean] emit the preload `<link>` (default true).
+    # @param fallback [Hash, nil] metric-matched fallback face. Keys:
+    #   :family (required, the local system font, e.g. "Arial"),
+    #   :name (the generated face name, default "#{family} Fallback"),
+    #   :size_adjust, :ascent_override, :descent_override, :line_gap_override.
+    # @return [ActiveSupport::SafeBuffer] head markup, ready for `content_for :head`.
+    #
+    # @note SECURITY: arguments are interpolated verbatim into the trusted CSS/HTML
+    #   emitted into `<head>` and the result is marked `html_safe`. Pass only
+    #   developer-controlled values (font names, asset paths), never end-user input.
+    #   Values containing `<`, `>`, `"`, or a newline raise `ArgumentError`.
+    def react_on_rails_font_face(family:, src:, weight: 400, style: "normal", display: "swap",
+                                 unicode_range: nil, preload: true, fallback: nil)
+      ReactOnRails::FontHelper.font_face_markup(
+        family:, src:, weight:, style:, display:,
+        unicode_range:, preload:, fallback:
+      ).html_safe
+    end
+
+    # Pure-string builder so the markup can be unit-tested without a view context.
+    # Returns a plain (not html_safe) String.
+    def self.font_face_markup(family:, src:, weight: 400, style: "normal", display: "swap",
+                              unicode_range: nil, preload: true, fallback: nil)
+      # Validate every value interpolated into the trusted <style>/<link> markup so no
+      # argument can break out of the CSS/HTML context (see the contract in the docstring).
+      ensure_safe!("family", family)
+      ensure_safe!("src", src)
+      ensure_safe!("weight", weight)
+      ensure_safe!("style", style)
+      ensure_safe!("display", display)
+      ensure_safe!("unicode_range", unicode_range) if unicode_range
+      if fallback
+        ensure_safe!("fallback[:family]", fallback.fetch(:family))
+        ensure_safe!("fallback[:name]", fallback[:name]) if fallback[:name]
+        %i[size_adjust ascent_override descent_override line_gap_override].each do |key|
+          ensure_safe!("fallback[:#{key}]", fallback[key]) if fallback[key]
+        end
+      end
+      rule = font_face_rule(family:, src:, weight:, style:, display:, unicode_range:)
+      parts = []
+      parts << preload_link(src) if preload
+      parts << +"<style>\n#{rule}"
+      parts[-1] << "\n#{fallback_font_face_rule(family, fallback, weight:, style:)}" if fallback
+      parts[-1] << "\n</style>"
+      parts.join("\n")
+    end
+
+    # Rejects values that could break out of the CSS/HTML context. Font helper
+    # arguments are emitted into trusted `<head>` markup, so they must be
+    # developer-controlled, not end-user input.
+    def self.ensure_safe!(name, value)
+      return unless value.to_s.match?(UNSAFE_TOKEN)
+
+      raise ArgumentError,
+            "react_on_rails_font_face: #{name}=#{value.inspect} contains an unsafe character " \
+            "(<, >, \", or newline); font arguments must be developer-controlled, not end-user input."
+    end
+
+    def self.preload_link(src)
+      %(<link rel="preload" href="#{src}" as="font" type="font/woff2" crossorigin="anonymous">)
+    end
+
+    def self.font_face_rule(family:, src:, weight:, style:, display:, unicode_range:)
+      lines = [
+        "@font-face {",
+        %(  font-family: "#{family}";),
+        %(  src: url("#{src}") format("woff2");),
+        "  font-weight: #{weight};",
+        "  font-style: #{style};",
+        "  font-display: #{display};"
+      ]
+      lines << "  unicode-range: #{unicode_range};" if unicode_range
+      lines << "}"
+      lines.join("\n")
+    end
+
+    # Generates the metric-matched fallback face. Hardcode `size-adjust` and the
+    # override percentages from the font's published metrics (see the fonts docs
+    # for how the Inter-over-Arial numbers are derived). The `font-weight` and
+    # `font-style` mirror the primary face so the browser matches this fallback to
+    # the same elements (otherwise the size-adjust CLS protection silently fails for
+    # non-400 weights / non-normal styles), the way `next/font` generates its
+    # weight-matched fallback.
+    def self.fallback_font_face_rule(family, fallback, weight:, style:)
+      name = fallback[:name] || "#{family} Fallback"
+      local = fallback.fetch(:family)
+      lines = [
+        "@font-face {",
+        %(  font-family: "#{name}";),
+        %(  src: local("#{local}");),
+        "  font-weight: #{weight};",
+        "  font-style: #{style};"
+      ]
+      lines << "  size-adjust: #{fallback[:size_adjust]};" if fallback[:size_adjust]
+      lines << "  ascent-override: #{fallback[:ascent_override]};" if fallback[:ascent_override]
+      lines << "  descent-override: #{fallback[:descent_override]};" if fallback[:descent_override]
+      lines << "  line-gap-override: #{fallback[:line_gap_override]};" if fallback[:line_gap_override]
+      lines << "}"
+      lines.join("\n")
+    end
+  end
+end