proscenium 0.25.3 → 0.26.0

data/lib/proscenium/runtime/server.rb

@@ -96,9 +96,9 @@ module Proscenium
         @parent_pid = parent_pid
         @requests = Queue.new
         @cache = {}
-        @key_mutexes = {}
         @cache_mutex = Mutex.new
         @resolve_mutex = Mutex.new
+        @socket_mutex = Mutex.new
         @shutdown = false
       end
 
@@ -109,11 +109,25 @@ module Proscenium
       # nobody else in the directory to race. `/tmp` explicitly, not Dir.tmpdir, because a unix
       # socket path is capped near 104 bytes and a CI or sandboxed TMPDIR can spend most of it.
       #
+      # Except on Windows, which has no `/tmp`. Dir.tmpdir there is normally the per-user
+      # `AppData\Local\Temp`, which is short enough and private to the user by its default ACL -
+      # which matters, because the 0700 mktmpdir asks for means nothing on Windows. That is a
+      # default, not a guarantee: TMP or TEMP can point somewhere shared. Only a caller that
+      # supplies no socket_dir lands here; the bun test harness always supplies one, under the
+      # app's own tmp/.
+      #
       # Resolved on first use rather than in the constructor, because `handle` can be driven
       # without ever binding anything - most of this class' own tests do - and a constructor that
       # creates a directory would leave one behind for every such instance.
+      #
+      # Guarded, because `start` reads it on the server thread while a caller may read it on
+      # another: an unguarded `||=` let both see nil and make a directory each, and the caller then
+      # waited for a socket the server had not bound.
       def socket_path
-        @socket_path ||= File.join(@socket_dir ||= Dir.mktmpdir('proscenium-', '/tmp'), SOCKET_NAME)
+        @socket_mutex.synchronize do
+          @socket_dir ||= Dir.mktmpdir('proscenium-', Gem.win_platform? ? Dir.tmpdir : '/tmp')
+          @socket_path ||= File.join(@socket_dir, SOCKET_NAME)
+        end
       end
 
       def start
@@ -236,6 +250,7 @@ module Proscenium
       #   absPath - the real file on disk, for the runtime's own resolver
       def op_resolve(request)
         path = request.fetch('path')
+        refuse_while_installing!
 
         # `Resolver.resolved` is a plain class-level Hash with no synchronisation, so concurrent
         # resolves would race on it. Resolution is cheap and memoised, so serialising it costs
@@ -269,9 +284,16 @@ module Proscenium
         # and then stripped by the plugin.
         sourcemap = request.fetch('sourcemap', true) ? true : false
 
-        cached(:build, path, sourcemap) do
+        refuse_while_installing!
+        cached(path, sourcemap) do
           code = serve_or_build(path, sourcemap: sourcemap)
 
+          # esbuild passes a mis-encoded source's bytes through, and scanning them below would
+          # raise a bare "invalid byte sequence in UTF-8" that names no module.
+          unless code.valid_encoding?
+            raise EncodingError, "#{path} built to output that is not valid UTF-8"
+          end
+
           # A source map has no imports to resolve, and the client discards the field, so scanning
           # it is work nobody reads.
           path.end_with?('.map') ? { code: code } : { code: code, imports: resolve_imports(code) }
@@ -350,6 +372,9 @@ module Proscenium
 
         content = +''
         body.each { |chunk| content << chunk }
+        # A file served as it is, through ActionDispatch::FileHandler, comes in binary chunks.
+        # Everything served here is text, which the content type guard below ensures.
+        content.force_encoding(Encoding::UTF_8)
 
         return nil if status == 404
 
@@ -457,53 +482,49 @@ module Proscenium
         content
       end
 
-      # Keyed on the source file's mtime so an edit is picked up between runs of a watching runner.
+      # Before the cache, so an earlier result is not handed out while an install changes what it
+      # resolved against, or while contexts are stale (C24).
+      def refuse_while_installing!
+        reason = Proscenium::Builder.refusal
+        raise reason if reason
+      end
+
+      # Each module variant - its path and whether it carries a source map - holds the mtime of its
+      # source file, so an edit is picked up between runs of a watching runner.
       #
-      # ponytail: the key covers the keyed file only, and a bundled build inlines its whole graph -
-      # which is the default, so in `--watch` editing any module a test imports can serve the
-      # previous bundle until the test file itself is touched. Unbundled it is narrower but still
-      # real: a CSS module, an SVG and i18n data are inlined either way. `Metafile: true` is
+      # ponytail: the mtime covers the keyed file only, and a bundled build inlines its whole
+      # graph - which is the default, so in `--watch` editing any module a test imports can serve
+      # the previous bundle until the test file itself is touched. Unbundled it is narrower but
+      # still real: a CSS module, an SVG and i18n data are inlined either way. `Metafile: true` is
       # already set in internal/builder/build.go, so keying on the newest mtime across the
       # metafile's inputs is the fix when this bites.
+      #
       # Held across the build, not just around the hash read, so N concurrent requests for the same
       # module build it once and the rest wait for that result. A single mutex around the whole
-      # thing would serialise every build and defeat the worker pool, so the lock is per key.
+      # thing would serialise every build and defeat the worker pool, so the lock is per variant.
       #
       # A path with nothing on disk to key on is not cached at all. `.rjs` is rendered by a route,
       # so its bytes depend on app code that can change; keying it on a nil mtime made the key a
       # constant and pinned the first render for the life of the daemon. That is invisible in a
       # one-shot run and wrong in a watching one - a suite passing against bytes the app no longer
       # produces. A route render is cheap next to a build, so it happens each time instead.
-      def cached(kind, path, *extra)
+      def cached(path, *extra)
         mtime = mtime_of(path)
         return yield if mtime.nil?
 
-        key = [kind, path, mtime, *extra]
-        prune(kind, path, mtime)
-
-        hit = @cache_mutex.synchronize { @cache[key] }
-        return hit if hit
+        # One bucket per module variant. A new mtime replaces the bucket, lock and all, which is
+        # what keeps a long `--watch` session at one entry per module - and holds for a build that
+        # raised, which leaves its bucket without a value rather than a lock outside the cache.
+        key = [path, Proscenium::Builder.generation, *extra]
+        bucket = @cache_mutex.synchronize do
+          current = @cache[key]
+          next current if current && current[:mtime] == mtime
 
-        key_mutex = @cache_mutex.synchronize { @key_mutexes[key] ||= Mutex.new }
-
-        key_mutex.synchronize do
-          hit = @cache_mutex.synchronize { @cache[key] }
-          next hit if hit
-
-          value = yield
-          @cache_mutex.synchronize { @cache[key] = value }
-          value
+          @cache[key] = { mtime: mtime, mutex: Mutex.new }
         end
-      end
 
-      # An edited file gets a new key, and the old one would otherwise sit in both hashes for the
-      # life of the daemon - so a long `--watch` session holds every historical build of every
-      # module it ever saw. Dropping the superseded generations keeps one entry per module. Every
-      # variant of a superseded mtime goes, whatever else is in its key.
-      def prune(kind, path, mtime)
-        @cache_mutex.synchronize do
-          stale = @cache.keys.select { |k| k[0] == kind && k[1] == path && k[2] != mtime }
-          stale.each { |k| @cache.delete(k) && @key_mutexes.delete(k) }
+        bucket[:mutex].synchronize do
+          bucket.key?(:value) ? bucket[:value] : (bucket[:value] = yield)
         end
       end
 
@@ -533,9 +554,9 @@ module Proscenium
       end
 
       # `JSON.generate` raises `JSON::GeneratorError` - a StandardError, not an IOError - when the
-      # reply carries bytes that are not valid UTF-8, which is what a mis-encoded source file in
-      # the app produces. That needs reporting as a failed build rather than taking the daemon
-      # with it, so the developer learns which module is mis-encoded.
+      # reply carries bytes that are not valid UTF-8. `op_build` checks its own output first and
+      # names the module; this is the backstop for any other reply, reported as a failure rather
+      # than taking the daemon with it.
       def answer(socket, write_mutex, reply)
         line = begin
           JSON.generate(reply)

data/lib/proscenium/side_load.rb

@@ -35,8 +35,8 @@ module Proscenium
         out = []
         Proscenium::Importer.each_stylesheet(delete: true) do |path, opts|
           opts = opts[:css].is_a?(Hash) ? opts[:css] : {}
-          opts[:preload_links_header] = false if fragments
-          opts[:data] ||= {}
+          opts = opts.merge(data: opts[:data] || {})
+          opts = opts.merge(preload_links_header: false) if fragments
 
           out << helpers.stylesheet_link_tag(path.delete_prefix('/'), extname: false, **opts)
         end
@@ -62,7 +62,7 @@ module Proscenium
           next if opts.delete(:lazy)
 
           opts = opts[:js].is_a?(Hash) ? opts[:js] : {}
-          opts[:preload_links_header] = false if fragments
+          opts = opts.merge(preload_links_header: false) if fragments
 
           out << helpers.javascript_include_tag(path.delete_prefix('/'), extname: false, **opts)
         end
@@ -98,21 +98,7 @@ module Proscenium
       def sideload_inheritance_chain(obj, options)
         return unless Proscenium.config.side_load
 
-        options = {} if options.nil?
-        options = { js: options, css: options } unless options.is_a?(Hash)
-
-        unless obj.sideload_assets_options.nil?
-          tpl_options = obj.sideload_assets_options
-          options = if tpl_options.is_a?(Hash)
-                      options.deep_merge tpl_options
-                    else
-                      { js: tpl_options, css: tpl_options }
-                    end
-        end
-
-        %i[css js].each do |k|
-          options[k] = obj.instance_eval(&options[k]) if options[k].is_a?(Proc)
-        end
+        options = merge_options(options, obj.sideload_assets_options, obj)
 
         css_imports = []
 
@@ -148,6 +134,77 @@ module Proscenium
           Importer.sideload_css it, **options
         end
       end
+
+      # Whether `template`, rendered by `view`, should have its assets side loaded.
+      def sideloadable?(view, template)
+        Proscenium.config.side_load && view.controller.respond_to?(:sideload_assets_options) &&
+          template.respond_to?(:identifier) && template.respond_to?(:type) && template.type == :html
+      end
+
+      # Renders the block, then side loads each of `templates`, and returns what the block
+      # returned. A template's `sideload_assets` value belongs to this one render: the view's
+      # stored value is set aside before the block and put back after it, so a repeated or nested
+      # render of the same template neither inherits this one's value nor overwrites it.
+      def sideload_templates(view, templates)
+        # A layout can be `false`, meaning none, and a template can be its own layout.
+        templates = templates.select(&:itself).uniq(&:identifier)
+        # A view rendered before Proscenium::Helper is included has nowhere to store a value.
+        store = view.try(:proscenium_sideload_assets_options) || {}
+        saved = templates.to_h { |tpl| [tpl.identifier, store.delete(tpl.identifier)] }
+
+        result = yield
+        templates.each { |tpl| sideload_template tpl, view.controller, store[tpl.identifier] }
+        result
+      ensure
+        saved&.each { |id, value| value.nil? ? store.delete(id) : store[id] = value }
+      end
+
+      # Returns a new options hash: `base`, with `override` deep merged over it, or replacing it
+      # when not a Hash, and any Proc `css`/`js` value evaluated against `receiver`. A nil `base`
+      # is empty, and a nil `override` changes nothing. Keys are symbolized at every depth, before
+      # merging, so options with indifferent access merge with symbol-keyed ones.
+      #
+      # Neither input is modified, and no Hash is shared with them - `base` is usually a class
+      # attribute, so writing to it would leak one request's options into every later one. Values
+      # other than hashes are passed through as they are, not copied: `dup` on an ActiveRecord
+      # model returns a new record with no id.
+      def merge_options(base, override, receiver)
+        options = base.nil? ? {} : base
+        options = { js: options, css: options } unless options.is_a?(Hash)
+        options = options.deep_symbolize_keys
+
+        unless override.nil?
+          options = if override.is_a?(Hash)
+                      options.deep_merge(override.deep_symbolize_keys)
+                    else
+                      { js: override, css: override }
+                    end
+        end
+
+        options.to_h do |key, value|
+          value = evaluate(value, receiver) if (key in :css | :js) && value.is_a?(Proc)
+          [key, value.is_a?(Hash) ? value.deep_symbolize_keys : value]
+        end
+      end
+
+      private
+
+      # `instance_eval` passes the receiver as the block's argument, which a lambda taking none
+      # rejects. Every other proc keeps receiving it, as it always has.
+      def evaluate(value, receiver)
+        if value.lambda? && value.arity.zero?
+          receiver.instance_exec(&value)
+        else
+          receiver.instance_eval(&value)
+        end
+      end
+
+      def sideload_template(tpl, controller, override)
+        return unless (tpl_path = Pathname.new(tpl.identifier)).file?
+
+        options = merge_options(controller.sideload_assets_options, override, controller)
+        Importer.sideload tpl_path, **options
+      end
     end
   end
 end

data/lib/proscenium/stale_contexts.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+require 'json'
+require_relative 'bundled_gems'
+require_relative 'context_map'
+require_relative 'dependency_context'
+require_relative 'cli/contexts'
+require_relative 'cli/error'
+require_relative 'cli/verify'
+
+module Proscenium
+  # Whether an adopted app's committed gem dependency contexts are what its bundle calls for
+  # (#154). A stale context resolves a gem's imports against the wrong dependency graph, so the
+  # engine refuses to build until `proscenium install` brings them up to date. Built from
+  # committed files and Bundler only; it loads nothing the `proscenium` CLI may not.
+  module StaleContexts
+    COMMAND = 'Run `bundle exec proscenium install` and commit .proscenium/packages.'
+    EDITED = 'its dependency context was edited by hand'
+    ORPHAN = '%<gem>s: its dependency context is left over, as the gem is no longer in the ' \
+             'bundle or no longer opted in'
+
+    module_function
+
+    # One line for each way the committed contexts differ from the bundle; empty when current, or
+    # before the app adopts. A context is stale when a participating gem has none, when its gem
+    # left Gemfile.lock or stopped participating, when its projection hash is not the gem's
+    # current one, or when that hash is not the one its own fields produce (a hand edit). A
+    # locked gem that is not installed (a group BUNDLE_WITHOUT excludes) keeps its context as
+    # committed.
+    def problems(root, specs = BundledGems.installed_specs, locked = BundledGems.locked_names)
+      registrar = ContextMap.registrar(root)
+      return [] unless registrar
+
+      # Only the registration in use: a Bun app does not read a pnpm-workspace.yaml left over.
+      unparsable = unparsable_workspace(root) if registrar == 'pnpm-workspace.yaml'
+      return [unparsable] if unparsable
+
+      participating = BundledGems.participating(specs, overrides: BundledGems.overrides(root))
+      contexts = CLI::Contexts.new(root, participating)
+      committed = CLI::Contexts.committed(root)
+      found = contexts.problems.map { |code, args| CLI::Error.new(code, **args).message }
+      contexts.contexts.each_value do |context|
+        problem = compare(context, committed[context.gem])
+        found << "#{context.gem}: #{problem}" if problem
+      end
+      excluded = (locked || []) - specs.map(&:name)
+      orphans = committed.keys - participating.keys - excluded
+      found + orphans.map { format(ORPHAN, gem: it) } +
+        split_peers(root, contexts.contexts.keys & committed.keys)
+    rescue BundledGems::ConfigError => e
+      [e.message]
+    end
+
+    # An app counts as adopted when a pnpm-workspace.yaml it cannot parse names the contexts, so
+    # the engine never silently switches them off; it refuses until the file parses. Not
+    # package.json: Bun reads JSON that Ruby refuses, such as a trailing comma.
+    def unparsable_workspace(root)
+      path = File.join(root, 'pnpm-workspace.yaml')
+      return unless File.exist?(path)
+
+      ContextMap.yaml_packages(ContextMap.utf8(File.read(path)).delete_prefix(ContextMap::BOM))
+      nil
+    rescue Psych::SyntaxError => e
+      "pnpm-workspace.yaml: it is not valid YAML (#{e.problem} at line #{e.line})"
+    end
+
+    # A peer meant to be shared that the gem and the app reach as two copies, as an app-only
+    # `pnpm update react` can leave it: install checks this too, and the engine repeats it for each
+    # generation.
+    def split_peers(root, gems)
+      pnpm = ContextMap.registers?(root, 'pnpm-workspace.yaml')
+      CLI::Verify.new(root, Struct.new(:name).new(pnpm ? 'pnpm' : 'bun'), gems).check_peers
+      []
+    rescue CLI::Error => e
+      [e.message]
+    end
+
+    # The committed context is projected again from the fields it holds, not taken on trust: a
+    # hand edit that kept the reported hash would build against a graph no install produced.
+    def compare(context, path)
+      return "its dependency context hasn't been written yet" unless path && File.exist?(path)
+
+      committed = ContextMap.read_json(path)
+      unless committed.is_a?(Hash) && committed['proscenium'].is_a?(Hash)
+        return 'its dependency context is not valid JSON'
+      end
+      if committed['proscenium']['projection'] != DependencyContext::PROJECTION
+        return 'its dependency context was written by a different version of Proscenium'
+      end
+
+      # Parsed, so reformatting is not an edit; whole, so its name and the other generated fields
+      # count as well as its hash.
+      edited = DependencyContext.project(context.gem, committed) != committed
+      return EDITED if edited
+      return if committed == JSON.parse(context.json)
+
+      'its NPM dependencies changed since its dependency context was written'
+    rescue JSON::ParserError
+      'its dependency context is not valid JSON'
+    end
+
+    # The build error for the app at `root`, or nil when its contexts are current. Read once per
+    # mapping generation, as ContextMap.config is.
+    def message(root, generation = 0)
+      @message ||= {}
+      key = [root, generation]
+      return @message[key] if @message.key?(key)
+
+      found = problems(root)
+      @message[key] = if found.any?
+                        "Gem dependency contexts are out of date:\n" \
+                          "#{found.map { "  - #{it}" }.join("\n")}\n#{COMMAND}"
+                      end
+    end
+
+    def reset! = @message = {}
+  end
+end

data/lib/proscenium/templates/rescues/build_error.html.erb

@@ -1,6 +1,6 @@
 <header>
   <h1>
-    <%= Rails.gem_version >= Gem::Version.new('7.1.0') ? @exception_wrapper.exception_class_name : @exception.class.to_s %>
+    <%= @exception_wrapper.exception_class_name %>
     <% if params_valid? && @request.parameters['controller'] %>
       in <%= @request.parameters['controller'].camelize %>Controller<% if @request.parameters['action'] %>#<%= @request.parameters['action'] %><% end %>
     <% end %>
@@ -8,18 +8,20 @@
 </header>
 
 <main role="main" id="container">
-  <%= render "rescues/message_and_suggestions", exception: @exception, exception_wrapper: Rails.gem_version >= Gem::Version.new('7.1.0') ? @exception_wrapper : nil %>
+  <%= render "rescues/message_and_suggestions", exception: @exception, exception_wrapper: @exception_wrapper %>
 
-  <% if @exception.error['location'] %>
+  <%# Go marshals esbuild's Message without JSON tags, so the keys are the Go field names. This
+      block read lowercase keys and had never rendered. %>
+  <% if (location = @exception.error['Location']) %>
     <div class="source">
       <div class="data">
 <pre>
 
-    <%= @exception.error['location']['file'] %>:<%= @exception.error['location']['line'] %>:<%= @exception.error['location']['column'] %>
+    <%= location['File'] %>:<%= location['Line'] %>:<%= location['Column'] %>
 
-<%= @exception.error['location']['line'].to_s.rjust 5 %> │    <%= @exception.error['location']['line_text'] %>
-      │    <%= (@exception.error['location']['length'] > 1 ? "~" * @exception.error['location']['length'] : "^").rjust(@exception.error['location']['column'] + @exception.error['location']['length']) %>
-<%- if @exception.error['location']['suggestion'].present? %>    + │    <%= @exception.error['location']['suggestion'].rjust(@exception.error['location']['column'] + 1) %>
+<%= location['Line'].to_s.rjust 5 %> │    <%= location['LineText'] %>
+      │    <%= (location['Length'].to_i > 1 ? "~" * location['Length'] : "^").rjust(location['Column'].to_i + location['Length'].to_i) %>
+<%- if location['Suggestion'].present? %>    + │    <%= location['Suggestion'].rjust(location['Column'].to_i + 1) %>
 <% else %> <%- end %>
 </pre>
       </div>

data/lib/proscenium/utils.rb

@@ -4,6 +4,20 @@ module Proscenium
   module Utils
     module_function
 
+    # A filesystem path in the slash form everything it is matched against - Rails.root, the public
+    # path, a gem's full_gem_path - already uses. Paths produced outside Ruby arrive in the form
+    # the platform produced: esbuild's metafile, and every path Bun hands the test harness. On
+    # Windows that is backslashes, so a plain `start_with?`/`delete_prefix` against Rails.root
+    # misses, and nothing raises - the path just falls through to whatever handles "not ours".
+    #
+    # Windows only, because a backslash is a legal character in a file name everywhere else.
+    #
+    # @param path [String] an absolute filesystem path.
+    # @return [String]
+    def fs_path(path)
+      Gem.win_platform? ? path.tr('\\', '/') : path
+    end
+
     # Returns a short digest for the given `value`, intended for CSS module class name suffixes.
     #
     # @param value [#to_s] The value to create the digest from. This will usually be the absolute
@@ -13,6 +27,47 @@ module Proscenium
       Digest::SHA1.hexdigest(value.to_s)[..7]
     end
 
+    # The path a CSS module's class-name suffix is built from: the file's path under the app root.
+    #
+    # Where there is no such path - a gem on another drive than the app, which is RubyInstaller's
+    # default - it is the absolute path itself. relative_path_from raised there, and failed every
+    # view using the module. The absolute path is what esbuild falls back to when it builds the
+    # stylesheet's class names (MakePrettyPaths keeps the path it could not relativise), and
+    # internal/plugin/css.go does the same, so all three agree.
+    #
+    # @param abs_path [String] absolute file system path of the CSS module.
+    # @return [Pathname, String]
+    def css_module_relative_path(abs_path)
+      Pathname.new(abs_path).relative_path_from(Rails.root)
+    rescue ArgumentError
+      abs_path
+    end
+
+    # Returns the readable part of a CSS module class name: the given path, made safe to use in a
+    # class name.
+    #
+    # This is a port of `CssLocalAppendice` in esbuild-internal, which builds the class names in the
+    # stylesheet. The two must agree byte for byte or the style silently does not apply, so change
+    # them together (test/css_module_suffixes.json is checked against both). The rules: drop the
+    # file extension, turn `/`, `\` and `.` into `-`, turn any other character outside
+    # `A-Z a-z 0-9 - _` into `_`, and start with `_` if the result would start with a digit.
+    #
+    # Go works in runes, so the path is read as UTF-8 whatever its tag: the FFI hands paths back as
+    # ASCII-8BIT, where each byte of a multibyte character would become a `_` of its own. A byte
+    # that is not valid UTF-8 becomes one `_`, as it does in Go.
+    #
+    # @param path [#to_s] path of the CSS module file, relative to the app root.
+    # @return [String]
+    def css_module_suffix(path)
+      path.to_s
+          .dup.force_encoding(Encoding::UTF_8)
+          .scrub { |bytes| '_' * bytes.bytesize }
+          .sub(%r{\.[^./]*\z}, '')
+          .gsub(%r{[/\\.]}, '-')
+          .gsub(/[^A-Za-z0-9_-]/, '_')
+          .sub(/\A(?=\d)/, '_')
+    end
+
     # Merges the given array of attribute `name`'s into the `kw_arguments`. A bang attribute is one
     # that ends with an exclamation mark or - in Ruby parlance - a "bang", and has a boolean value.
     # Modifies the given `kw_attributes`, and only attribute names in `allowed` will be merged.

data/lib/proscenium/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Proscenium
-  VERSION = '0.25.3'
+  VERSION = '0.26.0'
 end

data/lib/proscenium/yaml_tree.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require 'yaml'
+
+module Proscenium
+  # YAML read from Psych's parse tree, never built into Ruby objects (#154): no alias can make it
+  # slow, and no tag or date can raise. Shared by the engine and the `proscenium` CLI, so it loads
+  # nothing the CLI may not.
+  module YamlTree
+    module_function
+
+    # The node a root mapping's last `key` holds, aliases resolved, and the document's anchors; nil
+    # when the document is not a mapping or has no such key. A key the root inherits through a
+    # merge key (`<<: *defaults`) counts, as pnpm reads it. Raises Psych::SyntaxError.
+    def value(text, key)
+      root = Psych.parse_stream(text).children.first&.root
+      return unless root.is_a?(Psych::Nodes::Mapping)
+
+      anchors = root.each.grep_v(Psych::Nodes::Alias).select(&:anchor).to_h { [it.anchor, it] }
+      [lookup(root, key, anchors), anchors]
+    end
+
+    # `key`'s node in `mapping`: its own last one, else the first merged mapping's, following
+    # merges until one is already being looked in.
+    def lookup(mapping, key, anchors, merging = [])
+      return unless mapping.is_a?(Psych::Nodes::Mapping) && merging.none? { it.equal?(mapping) }
+
+      pairs = mapping.children.each_slice(2).map { |name, value| [node(name, anchors), value] }
+      _, found = pairs.reverse_each.find { |name, _| scalar?(name, key) }
+      return node(found, anchors) if found
+
+      merges = pairs.filter_map { |name, value| node(value, anchors) if scalar?(name, '<<') }
+      merges.each do |merged|
+        sources = merged.is_a?(Psych::Nodes::Sequence) ? merged.children : [merged]
+        sources.each do |source|
+          inherited = lookup(node(source, anchors), key, anchors, [*merging, mapping])
+          return inherited if inherited
+        end
+      end
+      nil
+    end
+
+    def scalar?(node, value) = node.is_a?(Psych::Nodes::Scalar) && node.value == value
+
+    # The node an alias names, or the node itself.
+    def node(node, anchors) = node.is_a?(Psych::Nodes::Alias) ? anchors[node.anchor] : node
+  end
+end

data/lib/proscenium.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'active_support'
+require_relative 'proscenium/error'
 
 module Proscenium
   extend ActiveSupport::Autoload
@@ -14,7 +15,9 @@ module Proscenium
 
   FILE_EXTENSIONS = ['js', 'mjs', 'ts', 'jsx', 'tsx', 'css', 'js.map', 'mjs.map', 'jsx.map',
                      'ts.map', 'tsx.map', 'css.map'].freeze
-  ALLOWED_DIRECTORIES = 'app,lib,config,node_modules'
+  # A gem dependency context's own node_modules holds the copy of a package the linker nested
+  # there, when the gem pins a version the app's does not satisfy (#154).
+  ALLOWED_DIRECTORIES = 'app,lib,config,node_modules,.proscenium/packages/*/node_modules'
   VENDOR_PATH_GLOB = '/vendor/**.{js,css}'
   APP_PATH_GLOB = "/{#{ALLOWED_DIRECTORIES}}/**.{#{FILE_EXTENSIONS.join(',')}}".freeze
   GEMS_PATH_GLOB = "/node_modules/@rubygems/**.{#{FILE_EXTENSIONS.join(',')}}".freeze
@@ -31,12 +34,14 @@ module Proscenium
   autoload :EnsureLoaded
   autoload :SideLoad
   autoload :CssModule
-  autoload :ReactComponentable
   autoload :Helper
   autoload :Builder
   autoload :Importer
   autoload :Resolver
   autoload :BundledGems
+  autoload :ContextMap
+  autoload :StaleContexts
+  autoload :MappingGeneration
 
   class Deprecator
     def deprecation_warning(name, message, _caller_backtrace = nil)
@@ -46,8 +51,6 @@ module Proscenium
     end
   end
 
-  class Error < StandardError; end
-
   class MissingAssetError < Error
     def initialize(path)
       super