proscenium 0.25.3 → 0.26.1

data/lib/proscenium/cli/verify.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require 'json'
+require_relative '../context_map'
+require_relative 'manager'
+
+module Proscenium
+  module CLI
+    # What install checks after the manager has run (#154): no gem context came from a registry,
+    # the manager installed every context (Bun exits 0 when a workspace is missing, so this is
+    # Proscenium's to check), and a peer meant to be shared is one copy.
+    class Verify
+      # A `packages:` key in pnpm-lock.yaml, and a `packages` entry in bun.lock, for a
+      # `@rubygems/*` package that is not a link to its context. A pnpm key starting with `@` is
+      # always quoted, and a Git one holds colons: `'@rubygems/hue@git+ssh://git@github.com/...':`.
+      PNPM_REGISTRY = %r{^\s{2}'(@rubygems/[^@'\s]+)@(?!link:|workspace:)[^']*':\s*$}
+      BUN_REGISTRY = %r{"(@rubygems/[^"]+)":\s*\["@rubygems/[^@"]+@(?!workspace:)}
+
+      def initialize(root, manager, gems)
+        @root = root
+        @manager = manager
+        @gems = gems
+      end
+
+      def call
+        lock = File.read(File.join(@root, Manager::LOCKFILES.key(@manager.name)))
+        check_registry(lock)
+        check_workspaces(lock)
+        check_peers
+      end
+
+      # A `@rubygems/*` package resolved from a registry, rather than linked to its context.
+      # bun.lock is JSON with trailing commas, so both locks are scanned as text.
+      def check_registry(lock)
+        found = lock.scan(@manager.name == 'pnpm' ? PNPM_REGISTRY : BUN_REGISTRY).flatten
+        return if found.empty?
+
+        raise Error.new('PSM-E-REGISTRY-TARBALL', packages: found.uniq.join(', '))
+      end
+
+      def check_workspaces(lock)
+        missing = @gems.reject do |gem|
+          path = ".proscenium/packages/#{gem}"
+          if @manager.name == 'pnpm'
+            # An importer with no dependencies is written on one line: `  <path>: {}`.
+            lock.match?(/^  #{Regexp.escape(path)}:(?: \{\})?$/)
+          else
+            lock.include?("\"#{path}\"")
+          end
+        end
+        return if missing.empty?
+
+        raise Error.new('PSM-E-WORKSPACE-MISSING', gems: missing.join(', '), manager: @manager.name)
+      end
+
+      # Each peer a context declares that the app also depends on must resolve, from the context
+      # and from the app, to one real directory. A context that is missing or not valid JSON has
+      # no peers to check; StaleContexts and `install --frozen` report it themselves.
+      def check_peers
+        app = app_dependencies
+        @gems.each do |gem|
+          dir = File.join(@root, '.proscenium', 'packages', gem)
+          (peers(dir).keys & app).each do |name|
+            from_gem = resolve(dir, name)
+            from_app = resolve(@root, name)
+            next if from_gem.nil? || from_app.nil? || from_gem == from_app
+
+            raise Error.new('PSM-E-PEER-SPLIT', gem:, package: name, manager: @manager.name)
+          end
+        end
+      end
+
+      def peers(dir)
+        context = ContextMap.read_json(File.join(dir, 'package.json'))
+        peers = context['peerDependencies'] if context.is_a?(Hash)
+        peers.is_a?(Hash) ? peers : {}
+      rescue Errno::ENOENT, JSON::ParserError
+        {}
+      end
+
+      def app_dependencies
+        package = ContextMap.read_json(File.join(@root, 'package.json'))
+        return [] unless package.is_a?(Hash)
+
+        # Peers too: pnpm installs the app's own peers at the root.
+        %w[dependencies devDependencies optionalDependencies peerDependencies].flat_map do |field|
+          package[field].is_a?(Hash) ? package[field].keys : []
+        end
+      rescue Errno::ENOENT, JSON::ParserError
+        []
+      end
+
+      # The real directory `name` resolves to from `dir`, walking up node_modules as Node does,
+      # but no higher than the app.
+      def resolve(dir, name)
+        current = dir
+        loop do
+          candidate = File.join(current, 'node_modules', name)
+          return File.realpath(candidate) if File.exist?(candidate)
+          return nil if current == @root || current == File.dirname(current)
+
+          current = File.dirname(current)
+        end
+      end
+    end
+  end
+end

data/lib/proscenium/cli.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+require_relative 'version'
+require_relative 'cli/error'
+require_relative 'cli/reporter'
+require_relative 'cli/gem_check'
+require_relative 'cli/install'
+require_relative 'cli/inspect'
+
+autoload :OptionParser, 'optparse'
+
+module Proscenium
+  # The `proscenium` command (#154): installs participating gems' JavaScript dependencies through
+  # the app's own package manager. It runs under `bundle exec` and reads the bundle in process.
+  #
+  # Load isolation is a contract, tested in test/cli/load_isolation_test.rb: nothing under
+  # lib/proscenium/cli/ may require `proscenium` itself, ActiveSupport, Rails, FFI or the engine
+  # library. Only Proscenium's plain-Ruby modules the engine shares with it (bundled_gems,
+  # dependency_context, context_map, stale_contexts) and these files.
+  module CLI
+    USAGE = <<~TEXT
+      Usage: bundle exec proscenium <command> [options]
+             bundle exec psm <command> [options]
+
+      Installs the NPM dependencies of the gems in your bundle that opt in.
+
+      Commands:
+        install            Install your gems' NPM dependencies
+        install --frozen   Check everything is up to date, without changing anything you commit
+        inspect [gem]      Show which gems install NPM dependencies, and any problems
+        doctor [gem]       The same as inspect
+        gem check [path]   For gem authors: check a gem's package.json and gemspec
+
+      install options:
+        --frozen                        Change nothing you commit; fail if anything is out of date
+        --production                    Leave out development dependencies, and keep the committed
+                                        dependency context of a gem in an excluded Bundler group
+        --offline                       Install from the package manager's cache only
+        --manager pnpm|bun              Which package manager, for an app with no package.json yet
+        --js-arg ARG                    Pass ARG to the package manager (repeatable)
+        --experimental-manager-version  Allow a package manager version Proscenium doesn't support
+
+      Options:
+        --json             Print newline-delimited JSON events instead of text
+        --quiet            Print less
+        --version          Print the Proscenium version
+        --help             Print this help
+    TEXT
+
+    module_function
+
+    # Runs the command in `argv` and returns its exit status.
+    def start(argv, out: $stdout, err: $stderr)
+      args = argv.dup
+      reporter = Reporter.new(out:, err:, json: !args.delete('--json').nil?,
+                              quiet: !args.delete('--quiet').nil?)
+      run(args, reporter)
+    rescue Error => e
+      reporter.error(e)
+      e.exit_status
+    rescue Interrupt
+      Error::EXIT.fetch(:interrupted)
+    rescue StandardError => e
+      internal = Error.new('PSM-E-INTERNAL', detail: "#{e.class}: #{e.message}")
+      reporter.error(internal)
+      internal.exit_status
+    end
+
+    def run(args, reporter)
+      # Anywhere, so `install --help` and `gem check --help` print it too.
+      if args.intersect?(%w[--help -h])
+        reporter.result(USAGE, event: 'help')
+        return 0
+      end
+
+      case args.first
+      when '--version', '-v'
+        reporter.result(Proscenium::VERSION, event: 'version', version: Proscenium::VERSION)
+      when nil
+        reporter.result(USAGE, event: 'help')
+      when 'install'
+        return Install.new(project_root, reporter, **install_options(args.drop(1))).call
+      when 'inspect', 'doctor'
+        return Inspect.new(project_root, reporter, gem: args[1]).call
+      when 'gem'
+        unless args[1] == 'check'
+          raise Error.new('PSM-E-USAGE', detail: 'Did you mean `proscenium gem check`?')
+        end
+
+        return GemCheck.new(args[2], reporter).call
+      else
+        raise Error.new('PSM-E-USAGE', detail: "Unknown command: #{args.join(' ')}")
+      end
+
+      0
+    end
+
+    # The active bundle's root: subdirectories and BUNDLE_GEMFILE both resolve to the app the
+    # bundle belongs to, so contexts are never written into another app.
+    def project_root = Bundler.root.to_s
+
+    def install_options(args)
+      options = { js_args: [] }
+      rest = OptionParser.new do |parser|
+        parser.on('--frozen') { options[:frozen] = true }
+        parser.on('--production') { options[:production] = true }
+        parser.on('--offline') { options[:offline] = true }
+        parser.on('--manager NAME') { options[:manager] = it }
+        parser.on('--experimental-manager-version') { options[:experimental] = true }
+        parser.on('--js-arg ARG') { options[:js_args] << it }
+      end.parse(args)
+      raise Error.new('PSM-E-USAGE', detail: "Unexpected argument: #{rest.join(' ')}") if rest.any?
+      if options[:js_args].any? && (options[:frozen] || options[:offline])
+        raise Error.new('PSM-E-USAGE', detail: '--js-arg cannot be used with --frozen or --offline')
+      end
+
+      options
+    rescue OptionParser::ParseError => e
+      raise Error.new('PSM-E-USAGE', detail: e.message)
+    end
+  end
+end

data/lib/proscenium/context_map.rb

@@ -0,0 +1,181 @@
+# frozen_string_literal: true
+
+require 'bundler'
+require 'json'
+require_relative 'app_package'
+require_relative 'bundled_gems'
+require_relative 'yaml_tree'
+
+module Proscenium
+  # What the engine passes Go about gem dependency contexts (#154): which gems resolve their bare
+  # imports from `.proscenium/packages/<gem>/`, and which of the app's own packages keep their link
+  # paths. Built from committed files and Bundler only. Like BundledGems, it loads nothing the
+  # `proscenium` CLI may not.
+  module ContextMap
+    CONTEXTS = File.join('.proscenium', 'packages')
+    REGISTRATION = '.proscenium/packages/*'
+
+    module_function
+
+    # Where the `proscenium` CLI keeps contexts, its lock and its marker: the bundle's root, which
+    # need not be Rails.root.
+    def project_root = Bundler.root.to_s
+
+    # The config keys Go reads, for the app at `root`. Read once per mapping generation: a value
+    # read during an older one is kept under that one's key, never handed to the next.
+    def config(root, generation = 0)
+      @config ||= {}
+      @config[[root, generation]] ||= { DependencyContexts: contexts(root),
+                                        AppLocalPackages: AppPackage.local_packages(root) }.freeze
+    end
+
+    def reset! = @config = {}
+
+    # Each registering file, with the lockfile and the name of the manager that reads it.
+    REGISTRARS = { 'pnpm-workspace.yaml' => %w[pnpm-lock.yaml pnpm],
+                   'package.json' => %w[bun.lock bun] }.freeze
+
+    # Whether the app at `root` adopted gem dependency contexts: pnpm's workspace file registers
+    # them, or package.json does in a Bun app. Each counts only where its manager installs: when
+    # packageManager names no other manager, and with that manager's lockfile or no other
+    # manager's, as an app missing its lockfile is an incomplete checkout, which must not silently
+    # switch the contexts off.
+    def adopted?(root) = !registrar(root).nil?
+
+    # The file whose registration makes the app at `root` adopted, or nil.
+    def registrar(root)
+      named = AppPackage.package_manager(root)
+      REGISTRARS.find do |file, (own, manager)|
+        # bun.lockb is Bun's too, until bun.lock replaces it.
+        others = [*UNSUPPORTED.keys, *REGISTRARS.values.map(&:first)] - [own] +
+                 (manager == 'bun' ? [] : ['bun.lockb'])
+        registers?(root, file) && [nil, manager].include?(named) &&
+          (File.exist?(File.join(root, own)) || others.none? { File.exist?(File.join(root, it)) })
+      end&.first
+    end
+
+    # Whether `file` lists the contexts: pnpm-workspace.yaml's `packages`, or package.json's
+    # `workspaces` (an array, or an object's `packages`). Parsed, so a commented-out line does not
+    # count. For the engine a file that does not parse counts if it names them, so a parse failure
+    # never silently switches off the context map and the stale check; `strict` (the CLI, which
+    # must register a file its manager can read) counts only a file that parses.
+    def registers?(root, file)
+      path = File.join(root, file)
+      File.exist?(path) && registered_in?(file, File.read(path))
+    end
+
+    def registered_in?(file, text, strict: false)
+      text = utf8(text).delete_prefix(BOM)
+      list = file.end_with?('.yaml') ? yaml_packages(text) : json_workspaces(text)
+      list.is_a?(Array) && list.any? { registration?(it) } && !excludes?(list)
+    rescue Psych::SyntaxError, JSON::ParserError
+      return false if strict
+
+      file.end_with?('.yaml') ? text.include?(REGISTRATION) : AppPackage.workspaces?(text)
+    end
+
+    # Whether the list has a `!` pattern that takes a context out: pnpm and Bun apply one whatever
+    # its order, so the contexts would never be installed. Generous: `*` crosses `/`, and any
+    # segment of the pattern may be a gem's directory.
+    def excludes?(list)
+      Array(list).grep(/\A!/).any? do |entry|
+        pattern = entry[1..].delete_prefix('./').chomp('/')
+        # A segment with a wildcard, class or brace, such as `[ah]ue`, may match any gem.
+        wide = pattern.split('/').map { it.match?(/[*?\[{]/) ? '*' : it }.join('/')
+        ['gem', *pattern.split('/')].product([pattern, wide]).any? do |name, glob|
+          File.fnmatch?(glob, "#{CONTEXTS}/#{name}", GLOB)
+        end
+      end
+    end
+
+    GLOB = File::FNM_EXTGLOB | File::FNM_DOTMATCH
+
+    def json_workspaces(text)
+      parsed = JSON.parse(text)
+      list = parsed['workspaces'] if parsed.is_a?(Hash)
+      list.is_a?(Hash) ? list['packages'] : list
+    end
+
+    # pnpm-workspace.yaml's `packages`: each entry's scalar text, or nil for one that is not a
+    # scalar; nil when the document is not a mapping or the key is missing or not a list. Read from
+    # the parse tree and never built into Ruby objects, so no alias can make it slow and no tag or
+    # date can raise. Raises Psych::SyntaxError.
+    def yaml_packages(text)
+      list, anchors = YamlTree.value(text, 'packages')
+      return unless list.is_a?(Psych::Nodes::Sequence)
+
+      list.children.map do |entry|
+        entry = YamlTree.node(entry, anchors)
+        entry.value if entry.is_a?(Psych::Nodes::Scalar)
+      end
+    end
+
+    # pnpm and Bun read `./<pattern>` and `<pattern>/` as the pattern.
+    def registration?(entry)
+      entry.is_a?(String) && entry.delete_prefix('./').chomp('/') == REGISTRATION
+    end
+
+    BOM = "\uFEFF"
+
+    # A JSON file as Node, pnpm and Bun read it, a leading byte order mark included.
+    def read_json(path) = parse_json(File.read(path))
+    def parse_json(text) = JSON.parse(utf8(text).delete_prefix(BOM))
+
+    # Text as UTF-8, whatever encoding the caller's locale gave it.
+    def utf8(text) = text.dup.force_encoding(Encoding::UTF_8)
+
+    # Gem name => absolute context directory for each participating gem, when the app at `root`
+    # adopted dependency contexts; empty before. A gem whose context is missing is mapped all the
+    # same: its imports then fail by name rather than fall back to the app's packages.
+    def contexts(root, specs = BundledGems.installed_specs)
+      return {} unless adopted?(root)
+
+      BundledGems.participating(specs, overrides: BundledGems.overrides(root)).keys.to_h do |gem|
+        [gem, File.join(root, CONTEXTS, gem)]
+      end
+    rescue BundledGems::ConfigError
+      {} # StaleContexts reports it, so every build is refused with the reason
+    end
+
+    INSTALLING = File.join('.proscenium', 'installing')
+    LOCK = File.join('.proscenium', 'lock')
+    INSTALLING_MESSAGE = '`bundle exec proscenium install` is running, or stopped before it ' \
+                         'finished. Wait for it, or run it again.'
+
+    # Whether an install is under way in the app at `root`, or stopped before it finished: its
+    # marker is there, or another process holds the project lock. The engine refuses to build or
+    # resolve meanwhile (C34). The probe takes a shared lock, so it never stops an install
+    # starting; the CLI retries a lock it finds taken for a moment. About 16 µs.
+    def installing?(root)
+      return true if File.exist?(File.join(root, INSTALLING))
+
+      lock = File.join(root, LOCK)
+      File.exist?(lock) && File.open(lock, File::RDONLY) { !it.flock(File::LOCK_SH | File::LOCK_NB) }
+    end
+
+    # Each file that says the app uses an unsupported manager, as Manager.select reads them.
+    UNSUPPORTED = { 'yarn.lock' => 'Yarn', '.yarnrc.yml' => 'Yarn', 'package-lock.json' => 'npm',
+                    'npm-shrinkwrap.json' => 'npm' }.freeze
+
+    # The one notice a process logs at boot when gems opt in but the app has not adopted dependency
+    # contexts, or nil. Those gems' imports keep resolving as they always have, so upgrading
+    # Proscenium never breaks an app that has not run `proscenium install` (C52).
+    def adoption_notice(root, specs = BundledGems.installed_specs)
+      return if adopted?(root)
+
+      gems = BundledGems.participating(specs, overrides: BundledGems.overrides(root)).keys
+      return if gems.empty?
+
+      opted = "#{gems.join(', ')} opt in to installing their NPM dependencies " \
+              'through Proscenium'
+      manager = UNSUPPORTED.find { |file, _| File.exist?(File.join(root, file)) }&.last
+      if manager
+        "#{opted}, but #{manager} is not supported, so the app keeps managing them."
+      else
+        "#{opted}. Run `bundle exec proscenium install` to install them."
+      end
+    rescue BundledGems::ConfigError => e
+      e.message
+    end
+  end
+end

data/lib/proscenium/css_module/transformer.rb

@@ -8,6 +8,14 @@ module Proscenium
       new(path).class_names(*names)
     end
 
+    # Flattens `names`, and drops nil, false and blank String or Symbol names. Anything else is
+    # kept, so that `#class_names` can reject it.
+    def self.filter_names(names)
+      names.flatten.reject do |name|
+        !name || ((name.is_a?(String) || name.is_a?(Symbol)) && name.to_s.blank?)
+      end
+    end
+
     def initialize(source_path)
       return unless (@source_path = source_path)
 
@@ -33,19 +41,22 @@ module Proscenium
     #   class_names "mypackage/button@large"
     #   class_names "@scoped/package/button@small"
     #
-    # When a block is given, it is yielded once per input name with
+    # Nested arrays of names are flattened, and nil, false and blank names are dropped (see
+    # `.filter_names`). Any other name that is not a String or Symbol raises TransformError.
+    #
+    # When a block is given, it is yielded once per name with
     # `(transformed_name, side_load_path)`. `side_load_path` is the exact string passed to
     # `Importer.import` for that name, or `nil` for names that did not trigger a side-load (plain
     # class names with `require_prefix: true`). The return value is unchanged — callers that don't
     # need the path can keep ignoring the block.
     #
-    # @param names [String,Symbol,Array<String,Symbol>]
+    # @param names [String,Symbol,nil,false,Array<String,Symbol,nil,false>]
     # @param require_prefix: [Boolean] whether or not to require the `@` prefix.
     # @yieldparam transformed_name [String]
     # @yieldparam side_load_path [String, nil]
     # @return [Array<String>] the transformed CSS module names.
     def class_names(*names, require_prefix: true)
-      names.map do |name|
+      self.class.filter_names(names).map do |name|
         transformed, path = transform_class_name(name, require_prefix: require_prefix)
         yield(transformed, path) if block_given?
         transformed
@@ -77,6 +88,10 @@ module Proscenium
     def transform_class_name(name, require_prefix:)
       original_name = name.dup
       name = name.to_s if name.is_a?(Symbol)
+      unless name.is_a?(String)
+        raise Proscenium::CssModule::TransformError.new(original_name.inspect,
+                                                        'class name must be a String or Symbol')
+      end
 
       if name.include?('/')
         if name.start_with?('@')

data/lib/proscenium/css_module.rb

@@ -5,7 +5,6 @@ module Proscenium::CssModule
 
   autoload :Path
   autoload :Transformer
-  autoload :Rewriter
 
   class TransformError < Proscenium::Error
     def initialize(name, additional_msg = nil)
@@ -26,7 +25,7 @@ module Proscenium::CssModule
 
     def class_names(*names, path: nil)
       path ||= respond_to?(:css_module_path) ? css_module_path : path
-      names = names.flatten.compact
+      names = Transformer.filter_names(names)
 
       cssm = Transformer.new(path)
       cssm.class_names(*names).join(' ') unless names.empty?
@@ -39,7 +38,7 @@ module Proscenium::CssModule
 
   # Accepts one or more CSS class names, and transforms them into CSS module names.
   #
-  # @param name [String,Symbol,Array<String,Symbol>]
+  # @param names [String,Symbol,nil,false,Array<String,Symbol,nil,false>]
   # @param path [Pathname] the path to the CSS module file to use for the transformation.
   # @return [String] the transformed CSS module names concatenated as a string.
   def css_module(*names, path: nil)
@@ -47,11 +46,11 @@ module Proscenium::CssModule
     transformer.class_names(*names, require_prefix: false).join(' ')
   end
 
-  # @param name [String,Symbol,Array<String,Symbol>]
+  # @param names [String,Symbol,nil,false,Array<String,Symbol,nil,false>]
   # @param path [Pathname] the path to the CSS file to use for the transformation.
-  # @return [String] the transformed CSS module names concatenated as a string.
+  # @return [String, nil] the transformed CSS module names concatenated as a string, or nil if none.
   def class_names(*names, path: nil)
-    names = names.flatten.compact
+    names = Transformer.filter_names(names)
     transformer = path.nil? ? cssm : Transformer.new(path)
     transformer.class_names(*names).join(' ') unless names.empty?
   end

data/lib/proscenium/dependency_context.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require 'digest'
+require 'json'
+
+module Proscenium
+  # A participating gem's dependency context (#154): its package.json through the
+  # `dependency-context-v1` projection, which keeps installation metadata only and is committed at
+  # `.proscenium/packages/<gem>/package.json`.
+  #
+  # The one owner of the projection and its hash, shared by the CLI and the engine, so it must not
+  # load ActiveSupport or anything else the CLI may not.
+  module DependencyContext
+    PROJECTION = 'dependency-context-v1'
+
+    # The manifest fields a context keeps, in the order it writes them. Everything else (scripts,
+    # devDependencies, version, entry points, workspaces) is left in the gem's own package.json.
+    FIELDS = %w[dependencies peerDependencies peerDependenciesMeta optionalDependencies engines os
+                cpu libc].freeze
+
+    module_function
+
+    def name_for(gem) = "@rubygems/#{gem}"
+
+    def description_for(gem)
+      "Generated by Proscenium from the #{gem} gem. Do not edit; " \
+        'run bundle exec proscenium install.'
+    end
+
+    # The context for `gem` from its parsed `manifest`. An empty field is left out, as an absent
+    # one is: the two install the same, so they hash the same.
+    def project(gem, manifest)
+      fields = FIELDS.each_with_object({}) do |key, kept|
+        value = manifest[key]
+        kept[key] = value unless value.nil? || (value.respond_to?(:empty?) && value.empty?)
+      end
+
+      { 'name' => name_for(gem), 'private' => true, 'description' => description_for(gem),
+        **fields,
+        'proscenium' => { 'projection' => PROJECTION, 'projectionSha256' => digest(gem, fields) } }
+    end
+
+    # The bytes committed for a context: fixed key order, two-space indent, a trailing newline, and
+    # nothing that varies by host or time.
+    def to_json(context) = "#{JSON.pretty_generate(context)}\n"
+
+    # The projection hash. It hashes a fixed-field encoding of the projected fields, not JSON, so
+    # it does not move with the json gem's output, key order, whitespace or escaping, and an edit
+    # to anything the projection drops leaves it alone.
+    def digest(gem, fields)
+      Digest::SHA256.hexdigest("#{PROJECTION}\n#{encode(name_for(gem))}#{encode(fields)}")
+    end
+
+    # A self-delimiting encoding: a type tag, a length where there is one, then the value. Hash
+    # keys are sorted by their bytes, so key order in the manifest does not matter; array order
+    # does, as it does to npm.
+    def encode(value)
+      case value
+      when String then "s#{value.bytesize}:#{value.b}"
+      when true then 't'
+      when false then 'f'
+      when nil then 'n'
+      when Integer then "i#{value};"
+      when Float then "d#{value};"
+      when Array then "a#{value.size}:#{value.map { encode(it) }.join}"
+      when Hash
+        pairs = value.sort_by { |key, _| key.to_s.b }
+        "h#{value.size}:#{pairs.map { |key, val| encode(key.to_s) + encode(val) }.join}"
+      else
+        raise ArgumentError, "cannot encode #{value.class} in a dependency context"
+      end
+    end
+  end
+end

data/lib/proscenium/error.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Proscenium
+  # The base of every error Proscenium raises.
+  #
+  # In a file of its own so that lib/proscenium/builder.rb can load without the rest of the gem:
+  # the release workflow loads the compiled library from an installed gem to prove it works, with
+  # no Rails app and no Rails, and builder.rb subclasses this at class-definition time.
+  class Error < StandardError; end
+end

data/lib/proscenium/helper.rb

@@ -2,15 +2,49 @@
 
 module Proscenium
   module Helper
+    # Sets the side load options of the template being rendered, for this render only. They are
+    # kept on the view, which lives for one request, keyed by template, because the template
+    # object itself is cached and shared by every request. `SideLoad.sideload_templates` scopes
+    # each value to the render that set it.
+    #
+    # Call it outside any `cache` block: a cache hit skips the block, and this call with it.
     def sideload_assets(value)
+      # ActionView does not push a partial rendered with a block onto `@current_template`, so while
+      # its body renders, `@current_template` is still the calling template.
+      identifier = (@proscenium_block_partial || @current_template).identifier
+
       if value.nil?
-        @current_template.instance_variable_defined?(:@sideload_assets_options) &&
-          @current_template.remove_instance_variable(:@sideload_assets_options)
+        proscenium_sideload_assets_options.delete identifier
       else
-        @current_template.instance_variable_set :@sideload_assets_options, value
+        proscenium_sideload_assets_options[identifier] = value
       end
     end
 
+    # Renders a partial given `block`, and yields the block to render it with. While the partial's
+    # body renders, `sideload_assets` applies to the partial. While the block runs, wherever it is
+    # run from, it applies to the template that passed the block. Any template rendered from
+    # either pushes itself onto `@current_template`, and `Monkey::Base` clears this while it does.
+    def proscenium_render_block_partial(partial, block)
+      previous = @proscenium_block_partial
+      calling_template = previous || @current_template
+      @proscenium_block_partial = partial
+
+      yield(proc do |*args|
+        current = @proscenium_block_partial
+        @proscenium_block_partial = calling_template
+        block.call(*args)
+      ensure
+        @proscenium_block_partial = current
+      end)
+    ensure
+      @proscenium_block_partial = previous
+    end
+
+    # @return [Hash] the `sideload_assets` value of each template in this render, by identifier.
+    def proscenium_sideload_assets_options
+      @proscenium_sideload_assets_options ||= {}
+    end
+
     def compute_asset_path(path, options = {})
       if %i[javascript stylesheet].include?(options[:type])
         return Proscenium::Manifest[path] || "/#{path}"
@@ -22,7 +56,7 @@ module Proscenium
     # Accepts one or more CSS class names, and transforms them into CSS module names.
     #
     # @see CssModule::Transformer#class_names
-    # @param name [String,Symbol,Array<String,Symbol>]
+    # @param names [String,Symbol,nil,false,Array<String,Symbol,nil,false>]
     # @param path [Pathname] the path to the CSS module file to use for the transformation.
     # @return [String] the transformed CSS module names concatenated as a string.
     def css_module(*names, path: nil)