lilac-cli 0.2.0

data/lib/lilac/cli/build/bundle_asset_writer.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require_relative 'html_emitter'
+
+module Lilac
+  module CLI
+    # In :bundle delivery mode, emits all components' default templates,
+    # named templates, and Ruby scripts into a single
+    # `dist/lilac.bundle.html`. Pages reference it via
+    # `<link rel="lilac-bundle">`, and PageCompiler's boot module / the
+    # runtime registry fetches it before mount.
+    #
+    # For the :compiled target, scripts are NOT inlined into the bundle
+    # (the compiled wasm has no parser to evaluate text/ruby). Instead
+    # they are aggregated and compiled into a single `bundle.mrb`, plus
+    # a tiny standalone `start_only.mrb` (just `Lilac.start`) — both
+    # filenames ride on the returned `BundleAssets` so PageCompiler can
+    # chain them into each page's boot module.
+    #
+    # See decisions §20.6 (Lilac.start placement) and the bundle-fetch
+    # proposal for the rationale behind splitting bundle.mrb /
+    # start_only.mrb instead of appending `Lilac.start` to the bundle.
+    class BundleAssetWriter
+      # Build-level artifacts handed back to the orchestrator (Builder)
+      # and forwarded into the `BuildContext` PageCompiler reads. `url`
+      # is what gets stamped into each page's `<link rel="lilac-bundle">`;
+      # the two `.mrb` filenames are only populated when
+      # `target == :compiled` (otherwise scripts go into the bundle.html
+      # itself as <script type="text/ruby">).
+      BundleAssets = Struct.new(:url, :bundle_mrb, :start_only_mrb, keyword_init: true)
+
+      BUNDLE_FILENAME = 'lilac.bundle.html'
+      BUNDLE_URL = "/#{BUNDLE_FILENAME}"
+
+      def initialize(components:, template_cache:, target:,
+                     output_dir:, bytecode_builder:)
+        @components = components
+        @template_cache = template_cache
+        @target = target
+        @output_dir = output_dir
+        @bytecode_builder = bytecode_builder
+      end
+
+      # Writes the bundle file and (for :compiled) compiles bundle.mrb +
+      # start_only.mrb. Returns a `BundleAssets`, or nil when there are
+      # no components to bundle.
+      def write!
+        return nil if @components.empty?
+
+        parts, compiled_scripts = assemble_parts
+        write_html_file!(parts)
+        bundle_mrb, start_only_mrb = compile_compiled_scripts!(compiled_scripts)
+
+        BundleAssets.new(
+          url: BUNDLE_URL,
+          bundle_mrb: bundle_mrb,
+          start_only_mrb: start_only_mrb
+        )
+      end
+
+      private
+
+      # Walks every component once, producing the HTML `parts` that go
+      # into bundle.html and the deferred `compiled_scripts` list that
+      # gets compiled to bytecode (only on :compiled target — :full puts
+      # the script bodies inline into `parts` as <script type="text/ruby">).
+      def assemble_parts
+        parts = []
+        compiled_scripts = []
+
+        @components.each do |name, comp|
+          parsed = @template_cache.fetch(name, comp)
+
+          # Default template
+          parts << "<template>#{parsed[:default_html]}</template>"
+
+          # Named templates (user-defined + synthetic data-each rows)
+          parsed[:named].each do |nt|
+            parts << HtmlEmitter.render_named_template(nt.name, nt.html)
+          end
+
+          # Scanner-canonical: emit the user script as-is (no codegen
+          # bindings). Skipped entirely when no user_script exists.
+          user_script = comp.script.strip
+          next if user_script.empty?
+
+          if @target == :compiled
+            # Defer: scripts get aggregated into one .mrb below.
+            compiled_scripts << user_script
+          else
+            parts << HtmlEmitter.render_script(user_script)
+          end
+        end
+
+        [parts, compiled_scripts]
+      end
+
+      def write_html_file!(parts)
+        FileUtils.mkdir_p(@output_dir)
+        bundle_path = File.join(@output_dir, BUNDLE_FILENAME)
+        File.write(bundle_path, parts.join("\n") + "\n")
+      end
+
+      # :compiled — compile aggregated scripts into a .mrb that the
+      # page boot module loads via loadBytecode. `Lilac.start` is NOT
+      # appended to the bundle: when a page has its own page-inline
+      # .mrb chained after the bundle, that one terminates with
+      # `Lilac.start`; when a page has only the bundle, we emit a
+      # tiny start-only .mrb so the chain still ends with `Lilac.start`
+      # running once after both class definitions and any page-local
+      # scripts are loaded.
+      def compile_compiled_scripts!(compiled_scripts)
+        return [nil, nil] unless @target == :compiled && !compiled_scripts.empty?
+
+        bundle_mrb = @bytecode_builder.build(
+          compiled_scripts.join("\n\n"), source_label: 'bundle'
+        )
+        # Standalone `Lilac.start` .mrb, shared by all pages that have
+        # no page-inline scripts. Content-hashed so cache reuses it
+        # across pages.
+        start_only_mrb = @bytecode_builder.build(
+          'Lilac.start', source_label: 'bundle-start'
+        )
+        [bundle_mrb, start_only_mrb]
+      end
+    end
+  end
+end

data/lib/lilac/cli/build/bytecode_builder.rb

@@ -0,0 +1,212 @@
+# frozen_string_literal: true
+
+require 'digest'
+require 'fileutils'
+require 'open3'
+require 'tmpdir'
+
+require_relative 'build_error'
+require_relative 'wasm_mrbc_driver'
+
+module Lilac
+  module CLI
+    # Compiles aggregated Ruby source to mruby bytecode, then writes it
+    # under the build output with a content-hash filename so browsers
+    # cache-invalidate automatically when the bytes change.
+    #
+    # Used by `Builder` when `target == :compiled`. Owns the compile
+    # subprocess (or wasm driver) lifecycle and error translation;
+    # `Builder` keeps the HTML / vendor concerns.
+    #
+    # Backend dispatch — first hit wins:
+    #
+    #   1. explicit `mrbc_path:` (from `Lilac::CLI.configure { c.mrbc_path = ... }`
+    #      or `--mrbc-path` CLI flag)                                  → :binary
+    #   2. ENV["MRBC"]                                                  → :binary
+    #   3. ENV["MRUBY_WASM_RUNTIME_PATH"]/mruby/build/host/bin/mrbc     → :binary
+    #   4. `lilac-wasm-bin` gem ships `mrbc-host.wasm` AND wasmtime-rb
+    #      loadable AND module instantiates with required exports       → :wasm
+    #   5. `mrbc` on $PATH                                              → :binary
+    #
+    # The wasm-driven backend is the "default for end users" path — a
+    # scaffolded `lilac new` Gemfile pulls in `lilac-wasm-bin` and
+    # `wasmtime`, so `gem install lilac-cli && bundle install` is enough
+    # to make `lilac build --target compiled` work without any external
+    # binary. Explicit `mrbc_path` / ENV vars override (priority 1-3) so
+    # devs who built mruby themselves get the native path.
+    #
+    # If nothing resolves, raises BuildError pointing at the most likely
+    # fix paths.
+    class BytecodeBuilder
+      class Error < BuildError; end
+
+      # 8 hex chars (32 bits) — enough collision resistance for cache
+      # busting, short enough to keep filenames readable.
+      HASH_LENGTH = 8
+
+      def initialize(output_dir: nil, mrbc_path: nil, basename: 'app',
+                     disable_gem_discovery: false)
+        @configured_mrbc_path = mrbc_path
+        @output_dir = output_dir
+        @basename = basename
+        # Mirrors `CompiledRuntimeResolver`'s kwarg — lets the bytecode
+        # builder's tests sandbox out the gem's `mrbc-host.wasm` when
+        # they want to assert specific discovery fallbacks. Production
+        # callers leave it false and the gem's wasm is picked up by
+        # default (priority #4).
+        @disable_gem_discovery = disable_gem_discovery
+      end
+
+      # Compile a Ruby source string into a `.mrb` file under
+      # `output_dir`. Returns the basename of the produced file (e.g.
+      # `"app.a3f29b21.mrb"`) so the caller can wire it into a fetch URL.
+      def build(ruby_source, source_label: '(aggregated)')
+        raise Error, '`build` requires `output_dir:` at construction time' unless @output_dir
+        FileUtils.mkdir_p(@output_dir)
+        bytecode = compile_to_bytes(ruby_source, source_label: source_label)
+        filename = "#{@basename}.#{content_hash(bytecode)}.mrb"
+        dest = File.join(@output_dir, filename)
+        File.binwrite(dest, bytecode)
+        filename
+      end
+
+      # Compile a Ruby source string into raw mruby bytecode (no write,
+      # no hashing). Used by `lilac package-build` which wants explicit
+      # control over output path / filename — it has no need for the
+      # content-hash cache-busting that `build` does for `.lil` apps.
+      def compile_to_bytes(ruby_source, source_label: '(aggregated)')
+        backend = resolve_backend!
+        case backend.first
+        when :binary then compile_via_binary(backend.last, ruby_source, source_label)
+        when :wasm   then compile_via_wasm(backend.last, ruby_source, source_label)
+        end
+      end
+
+      # Diagnostic accessor: returns `[:binary, "/path"]` or
+      # `[:wasm, "/path/to/wasm"]` describing which backend `build` would
+      # select, or nil when nothing resolves. Doesn't raise — `lilac
+      # doctor` uses it to render the OK / WARN line; `build` calls
+      # `resolve_backend!` instead.
+      def resolve_backend
+        if (binary = resolve_mrbc_binary)
+          return [:binary, binary]
+        end
+        if (wasm = discoverable_mrbc_host_wasm) && WasmMrbcDriver.available?(wasm_path: wasm)
+          return [:wasm, wasm]
+        end
+        if (path_binary = path_lookup('mrbc'))
+          return [:binary, path_binary]
+        end
+
+        nil
+      end
+
+      # Resolved mrbc binary path for `lilac doctor` and back-compat.
+      # Nil when no binary is discoverable (gem-provided wasm doesn't
+      # count). Renamed-but-kept-as-alias for callers that pre-date the
+      # backend dispatch (e.g. existing tests).
+      def resolve_mrbc
+        resolve_mrbc_binary || path_lookup('mrbc')
+      end
+
+      private
+
+      # Discovery routes 1-3 from the docstring above — explicit
+      # arg / ENV / monorepo convention. The PATH fallback (#5) lives
+      # in `resolve_backend` so it's only consulted after the wasm
+      # backend has been tried.
+      def resolve_mrbc_binary
+        @configured_mrbc_path && File.executable?(@configured_mrbc_path) and return @configured_mrbc_path
+        if (env = ENV['MRBC']) && File.executable?(env)
+          return env
+        end
+
+        if (mwr = ENV['MRUBY_WASM_RUNTIME_PATH'])
+          candidate = File.join(mwr, 'mruby', 'build', 'host', 'bin', 'mrbc')
+          return candidate if File.executable?(candidate)
+        end
+        nil
+      end
+
+      def discoverable_mrbc_host_wasm
+        return nil if @disable_gem_discovery
+
+        require 'lilac/wasm/bin'
+        ::Lilac::Wasm::Bin.mrbc_host_wasm
+      rescue LoadError
+        nil
+      end
+
+      def resolve_backend!
+        resolve_backend || raise(Error, backend_not_found_message)
+      end
+
+      def compile_via_binary(mrbc, ruby_source, source_label)
+        Dir.mktmpdir('lilac-mrbc-') do |dir|
+          tmp_rb  = File.join(dir, 'input.rb')
+          tmp_mrb = File.join(dir, 'input.mrb')
+          File.write(tmp_rb, ruby_source)
+
+          stdout, stderr, status = Open3.capture3(mrbc, '-o', tmp_mrb, tmp_rb)
+          raise Error, binary_error_message(source_label, stdout, stderr, status) unless status.success?
+
+          File.binread(tmp_mrb)
+        end
+      end
+
+      def compile_via_wasm(wasm_path, ruby_source, source_label)
+        # Reuse the driver across `build` calls within a single
+        # invocation — engine + module + instance setup is the slow part
+        # (~200-500ms cold) and is amortized over every component.
+        @wasm_driver ||= WasmMrbcDriver.new(wasm_path: wasm_path)
+        @wasm_driver.compile(ruby_source)
+      rescue WasmMrbcDriver::CompileError => e
+        raise Error, "mrbc-host.wasm failed compiling #{source_label}:\n#{e.message}"
+      rescue WasmMrbcDriver::WasmtimeMissingError, WasmMrbcDriver::WasmExportMissingError => e
+        # Shouldn't reach here under normal flow — `resolve_backend!`
+        # only returns `:wasm` after `available?` succeeded — but if the
+        # wasm path goes stale mid-build (e.g. file removed), surface
+        # the typed error rather than crashing.
+        raise Error, "wasm mrbc backend unavailable: #{e.message}"
+      end
+
+      def content_hash(bytes)
+        Digest::SHA256.hexdigest(bytes)[0, HASH_LENGTH]
+      end
+
+      # Walk $PATH for `name`. Falls back to nil when not found —
+      # callers translate to a user-facing error with
+      # `backend_not_found_message`.
+      def path_lookup(name)
+        (ENV['PATH'] || '').split(File::PATH_SEPARATOR).each do |dir|
+          candidate = File.join(dir, name)
+          return candidate if File.executable?(candidate) && !File.directory?(candidate)
+        end
+        nil
+      end
+
+      def backend_not_found_message
+        <<~MSG.strip
+          No mrbc backend found. Tried (in priority order):
+            1. configured `c.mrbc_path` / `--mrbc-path`
+            2. ENV["MRBC"]
+            3. ENV["MRUBY_WASM_RUNTIME_PATH"]/mruby/build/host/bin/mrbc
+            4. lilac-wasm-bin gem's mrbc-host.wasm (wasmtime-rb driven)
+            5. `mrbc` on $PATH
+
+          To fix, either:
+            • Add `gem "lilac-wasm-bin"` and `gem "wasmtime"` to your Gemfile
+              (recommended — the scaffolded Gemfile from `lilac new` already does this)
+            • Set ENV["MRBC"]=/abs/path/to/mrbc
+            • Set ENV["MRUBY_WASM_RUNTIME_PATH"] to a built mruby-wasm-runtime checkout
+            • Add `c.mrbc_path = "/abs/path"` to lilac.config.rb
+            • Put `mrbc` on your $PATH (e.g. build mruby locally)
+        MSG
+      end
+
+      def binary_error_message(source_label, _stdout, stderr, status)
+        "mrbc failed (exit=#{status.exitstatus}) compiling #{source_label}:\n#{stderr.strip}"
+      end
+    end
+  end
+end

data/lib/lilac/cli/build/compiled_boot_module.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module Lilac
+  module CLI
+    # Emits the `<script type="module">` boot stub for the `:compiled`
+    # target: it loads `.mrb` bytecode, boots the lilac-compiled wasm,
+    # and (in :bundle delivery) pulls the bundle's `<template>` elements
+    # into the live document before `Lilac.start` runs.
+    #
+    # Split out of PageCompiler so the JS-string generation lives next to
+    # HtmlEmitter's markup-emitting peers rather than mixing into the
+    # per-page compile flow.
+    module CompiledBootModule
+      module_function
+
+      # Decide the .mrb load order for a :compiled × :bundle page's boot
+      # module. The bundle .mrb always loads first (component class
+      # definitions, no `Lilac.start`). The tail is either the page-local
+      # .mrb (which itself ends with `Lilac.start`) or the shared
+      # `start-only.mrb` fallback so every page's chain terminates with
+      # `Lilac.start`.
+      def mrb_chain(bundle_assets, page_local_mrb)
+        return [] unless bundle_assets
+
+        chain = []
+        chain << bundle_assets.bundle_mrb if bundle_assets.bundle_mrb
+        if page_local_mrb
+          chain << page_local_mrb
+        elsif bundle_assets.bundle_mrb && bundle_assets.start_only_mrb
+          chain << bundle_assets.start_only_mrb
+        end
+        chain
+      end
+
+      # Emits the module script that loads `.mrb` bytecode and boots
+      # the lilac-compiled wasm. Inlines the boot logic instead of
+      # depending on `@takahashim/lilac-compiled`'s published `index.js`
+      # — the npm boot helper has occasionally drifted from the bridge's
+      # current API (e.g. `loadIrep` rename → `loadBytecode`) and a
+      # self-contained module is one fewer moving part to keep in sync.
+      # The `data-lilac-bootstrap` attribute marks the tag so a future
+      # asset-pipeline pass can rewrite the URLs.
+      #
+      # `Lilac.start` is NOT called here via `vm.eval`: the compiled
+      # wasm excludes `mruby-compiler` / `mruby-eval`, so post-load
+      # eval of arbitrary Ruby source is unsupported. Instead the
+      # builder appends `Lilac.start` to the bundle so it runs as part
+      # of `loadBytecode` (decisions §20.6 caveat).
+      def render(mrb_filenames, package_urls: [], delivery: :inline)
+        # Accept either a single filename or an array (used by the
+        # :bundle delivery path to chain bundle.mrb + page-inline.mrb in
+        # one VM).
+        mrb_filenames = Array(mrb_filenames)
+
+        # Package `.mrb` bundles load BEFORE the user bytecode so any
+        # `Scanner.register("ClassName")` calls (and the Handler classes
+        # they refer to) are ready by the time component mount runs.
+        # Mirrors the load ordering in `npm/lilac-compiled/index.js`'s
+        # boot helper.
+        package_loads = package_urls.map do |url|
+          "vm.loadBytecode(new Uint8Array(await (await fetch(#{url.inspect})).arrayBuffer()));"
+        end
+        bytecode_loads = mrb_filenames.map do |filename|
+          %(vm.loadBytecode(new Uint8Array(await (await fetch("./#{filename}")).arrayBuffer())));
+        end
+        all_loads = (package_loads + bytecode_loads).join("\n  ")
+
+        # :bundle delivery: the compiled wasm has no parser, so unlike
+        # the :full boot helper we can't `vm.eval` bundle scripts —
+        # those land in the chained .mrb above. But we still need to
+        # pull the bundle's <template> elements into the live document
+        # before `Lilac.start` runs (which is in the page-local /
+        # start-only .mrb). Fetch + DOMParser the bundle and append
+        # each <template>; scripts inside the bundle are intentionally
+        # ignored (they don't exist for :compiled bundles).
+        bundle_block =
+          if delivery == :bundle
+            <<~JS.chomp.gsub(/^/, '  ')
+              for (const link of document.querySelectorAll('link[rel="lilac-bundle"]')) {
+                const res = await fetch(link.getAttribute("href"));
+                const doc = new DOMParser().parseFromString(await res.text(), "text/html");
+                for (const tpl of doc.querySelectorAll("template")) {
+                  document.body.appendChild(tpl.cloneNode(true));
+                }
+              }
+            JS
+          end
+
+        body_parts = []
+        body_parts << bundle_block if bundle_block
+        body_parts << "  #{all_loads}" unless all_loads.empty?
+
+        <<~HTML.strip
+          <script type="module" data-lilac-bootstrap>
+            import { createVM } from "./vendor/lilac-compiled/mruby-wasm-js/index.js";
+            const vm = await createVM({ wasm: "./vendor/lilac-compiled/lilac.wasm" });
+          #{body_parts.join("\n")}
+          </script>
+        HTML
+      end
+    end
+  end
+end

data/lib/lilac/cli/build/compiled_runtime_resolver.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require_relative "runtime_resolver"
+
+module Lilac
+  module CLI
+    # Locates the `target: :compiled` runtime that gets vendored into
+    # `dist/vendor/lilac-compiled/`:
+    #
+    #   * `lilac.wasm`     — the compiled-variant wasm bundle (vendored
+    #                        name; the monorepo/gem source is
+    #                        `lilac-compiled.wasm`)
+    #   * `mruby-wasm-js/` — the JS↔mruby bridge (resolved by the shared
+    #                        base — same artifact as the :full target)
+    #
+    # The boot module is rendered inline by the builder
+    # (`render_compiled_boot_module`); we don't ship the npm package's
+    # `index.js`. Only the wasm-specific discovery differs from `:full`,
+    # so this class supplies just those hooks. See `RuntimeResolver`.
+    class CompiledRuntimeResolver < RuntimeResolver
+      # Distinct from FullRuntimeResolver::Error; both < RuntimeResolver::Error.
+      class Error < RuntimeResolver::Error; end
+
+      def initialize(lilac_compiled_path: nil, **opts)
+        super(lilac_wasm_path: lilac_compiled_path, **opts)
+      end
+
+      private
+
+      def wasm_env_key
+        "LILAC_COMPILED_WASM"
+      end
+
+      def gem_provided_wasm
+        return nil if @disable_gem_discovery
+        require "lilac/wasm/bin"
+        ::Lilac::Wasm::Bin.lilac_compiled_wasm
+      rescue LoadError
+        nil
+      end
+
+      def monorepo_wasm_candidate
+        File.join(monorepo_root, "build", "lilac-compiled.wasm")
+      end
+
+      def wasm_not_found_message
+        <<~MSG.strip
+          lilac-compiled.wasm not found. Tried:
+            • configured `c.lilac_compiled_path` (#{@configured_wasm_path.inspect})
+            • ENV["LILAC_COMPILED_WASM"] (#{ENV["LILAC_COMPILED_WASM"].inspect})
+            • lilac-wasm-bin gem (not on load path)
+            • monorepo: #{monorepo_wasm_candidate}
+
+          To fix, either:
+            • Add `gem "lilac-wasm-bin"` to your Gemfile (recommended — the scaffolded Gemfile from `lilac new` already includes it)
+            • Pass `--lilac-compiled-path /abs/path/to/lilac.wasm` on the command line
+            • Add `c.lilac_compiled_path = "/abs/path"` to lilac.config.rb
+            • Set ENV["LILAC_COMPILED_WASM"]
+            • In the monorepo: run `make lilac-compiled` to produce build/lilac-compiled.wasm
+        MSG
+      end
+    end
+  end
+end

data/lib/lilac/cli/build/component_name.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Lilac
+  module CLI
+    # Value object for a `.lil` component's kebab-case name. Holds the
+    # raw string and exposes the derived forms the build pipeline
+    # needs:
+    #
+    #   name = ComponentName.new("admin--user-card")
+    #   name.ruby_class                 # => "Admin::UserCard"
+    #   name.to_s                       # => "admin--user-card"
+    #
+    # `--` separates namespace segments, `-` separates words within a
+    # segment. Empty segments (leading/trailing `--`, double `-` between
+    # words) raise at construction so misnamed files fail loudly rather
+    # than emitting `::Foo` / `Foo::` downstream.
+    class ComponentName
+      attr_reader :kebab
+
+      def initialize(kebab)
+        @kebab = kebab.to_s
+        @ruby_class = build_ruby_class
+      end
+
+      def ruby_class
+        @ruby_class
+      end
+
+      def to_s
+        @kebab
+      end
+
+      def ==(other)
+        other.is_a?(ComponentName) && other.kebab == @kebab
+      end
+      alias_method :eql?, :==
+
+      def hash
+        @kebab.hash
+      end
+
+      private
+
+      def build_ruby_class
+        @kebab.split("--", -1).map { |segment|
+          raise ArgumentError, "Invalid component name: #{@kebab.inspect} (empty namespace segment)" if segment.empty?
+
+          segment.split("-").map { |word|
+            raise ArgumentError, "Invalid component name: #{@kebab.inspect} (empty word segment)" if word.empty?
+
+            word[0].upcase + (word[1..] || "")
+          }.join
+        }.join("::")
+      end
+    end
+  end
+end

data/lib/lilac/cli/build/component_scripts_assembler.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require_relative 'component_name'
+require_relative '../lint/cross_ref_linter'
+
+module Lilac
+  module CLI
+    # Per-page assembly of the Ruby source one bundle script contains:
+    # the user-authored `<script>` body of every component used on the
+    # page. Binding is scanner-canonical (the runtime scanner wires
+    # `data-*` at mount), so no `Lilac::Bindings::<Class>` codegen is
+    # emitted here — this class only runs `CrossRefLinter` (to surface
+    # signal/method mismatches as build errors) and returns the user
+    # script unchanged.
+    #
+    # Used only by `PageCompiler` (per-page injection). The :bundle
+    # delivery writer takes a leaner path through `BundleAssetWriter`
+    # because the bundle file gathers ALL components rather than the
+    # "used on this page" subset, and skips the lint pass entirely.
+    class ComponentScriptsAssembler
+      def initialize(template_cache:)
+        @template_cache = template_cache
+      end
+
+      # Returns `Array<String>` — one Ruby source chunk per component
+      # that had a non-empty user script. Order matches `used_names`
+      # so that any user-side dependency on declaration order (e.g.
+      # subclass after parent) is preserved across the bundle.
+      #
+      # `synthesized_names` marks components that originate from a
+      # page-inline `<X data-component=...>` (their `comp.script` slot
+      # is empty by construction; the actual class body lives in the
+      # page's `<script type="text/ruby">` blocks). For those the
+      # cross-ref linter reads the page-level inline Ruby instead so
+      # `@signal` / `def method` lookups resolve.
+      def assemble(used_names, components, synthesized_names:, page_inline_scripts:)
+        synth_lint_script = page_inline_scripts.join("\n\n")
+        used_names.map do |name|
+          assemble_one(name, components[name], synthesized_names, synth_lint_script)
+        end.reject(&:empty?)
+      end
+
+      private
+
+      def assemble_one(name, comp, synthesized_names, synth_lint_script)
+        parsed = @template_cache.fetch(name, comp)
+        user_script = comp.script.strip
+        lint_script = synthesized_names.include?(name) ? synth_lint_script : user_script
+
+        run_lint!(name, parsed, lint_script)
+
+        # Scanner-canonical: no codegen module is emitted. The user
+        # script is returned as-is; the runtime scanner wires the
+        # component's `data-*` directives at mount.
+        user_script
+      end
+
+      # Cross-reference lint surfaces signal/method mismatches as build
+      # errors before the bytecode pass. Errors raise — warnings go to
+      # stderr and the build carries on inside CrossRefLinter.
+      def run_lint!(name, parsed, lint_script)
+        result = CrossRefLinter.lint(
+          script_text: lint_script,
+          directives: parsed[:default_directives],
+          refs_map: parsed[:default_refs_map],
+          component_name: ComponentName.new(name).ruby_class,
+          file: parsed[:source_path] ? File.basename(parsed[:source_path]) : '(template)'
+        )
+        return unless result.errors?
+
+        raise Builder::Error,
+              "build failed: #{result.errors} lint error(s) in template; see warnings above."
+      end
+    end
+  end
+end