stream_weaver 0.3.0

data/lib/stream_weaver/opal/builder.rb

@@ -0,0 +1,193 @@
+# frozen_string_literal: true
+require "fileutils"
+require_relative "shell"
+require_relative "../css"
+require_relative "../theme"
+
+module StreamWeaver
+  module Opal
+    class OpalBuilder
+      # opal is the heavyweight compiler behind `streamweaver opal-build` --
+      # not a runtime dependency of the gem (see stream_weaver.gemspec), so a
+      # doc-shelf-only install must never be forced to have it. Load it here,
+      # on first actual use, instead of at file-load time.
+      def self.require_opal!
+        require "opal"
+      rescue LoadError
+        raise LoadError, "Opal features need the opal gem: gem install opal"
+      end
+
+      # Convenience entry point
+      def self.build(app_file, output_dir: "dist", title: nil, theme: nil)
+        require_opal!
+        new(app_file, output_dir: output_dir, title: title, theme: theme).call
+      end
+
+      def initialize(app_file, output_dir: "dist", title: nil, theme: nil)
+        @app_file   = app_file
+        @output_dir = output_dir
+        @title      = title || derive_title
+        @theme      = theme
+        @lib_root   = File.expand_path(File.join(__dir__, "../.."))
+        @stubs_root = File.join(__dir__, "stubs")
+      end
+
+      def call
+        FileUtils.mkdir_p(@output_dir)
+        write_app_js
+        copy_morphdom
+        copy_marked
+        copy_browser_assets
+        write_theme_css
+        write_index_html
+      end
+
+      private
+
+      # Assets committed under opal/stubs, plus mermaid from the gitignored
+      # vendor dir (see bin/vendor_browser_assets -- it is too large to commit).
+      # Anything missing falls back to its CDN in OpalShell, which keeps builds
+      # working for web deployment; only offline and browser-extension hosts
+      # actually require the local copies.
+      #
+      # sw-mermaid-zoom.js is different from the rest: it is StreamWeaver's own
+      # code, not a third-party library, so it has no CDN to fall back to and
+      # is always committed (unlike mermaid.min.js itself). It is copied
+      # unconditionally -- since Adapter::Static#render_mermaid (shared by both
+      # adapters) always writes the mermaid source into a data attribute rather
+      # than element text, this engine is the only thing that can read it. A
+      # build missing it would render an empty box, not a diagram
+      # (stream_weaver-mermaid-extension).
+      def copy_browser_assets
+        {
+          "prism.min.js"           => File.join(@stubs_root, "prism.min.js"),
+          "prism-tomorrow.min.css" => File.join(@stubs_root, "prism-tomorrow.min.css"),
+          "diff.min.js"            => File.join(@stubs_root, "diff.min.js"),
+          "mermaid.min.js"         => mermaid_source_path,
+          "sw-mermaid-zoom.js"     => File.join(@lib_root, "stream_weaver", "assets", "js", "sw-mermaid-zoom.js")
+        }.each do |name, src|
+          next unless src && File.exist?(src)
+
+          FileUtils.cp(src, output_path(name))
+        end
+
+        return if mermaid_source_path && File.exist?(mermaid_source_path)
+
+        warn "[OpalBuilder] mermaid.min.js not vendored -- falling back to CDN. " \
+             "Run bin/vendor_browser_assets for an offline build."
+      end
+
+      def mermaid_source_path
+        @mermaid_source_path ||= File.join(@lib_root, "..", "vendor", "js", "mermaid.min.js")
+      end
+
+      def local_asset(name)
+        File.exist?(output_path(name)) ? name : nil
+      end
+
+      def write_app_js
+        File.write(output_path("app.js"), compile.to_s)
+      end
+
+      def copy_morphdom
+        src = File.join(@stubs_root, "morphdom.min.js")
+        FileUtils.cp(src, output_path("morphdom.min.js")) if File.exist?(src)
+      end
+
+      def copy_marked
+        src = File.join(@stubs_root, "marked.umd.js")
+        FileUtils.cp(src, output_path("marked.umd.js")) if File.exist?(src)
+      end
+
+      def write_theme_css
+        css = StreamWeaver::CSS.full_stylesheet
+        css += "\n" + StreamWeaver::Theme.visual_skills_css
+        css += "\n" + StreamWeaver::CSS.animation_css
+        if @theme
+          unless StreamWeaver::Theme::Presets.get(@theme.to_sym)
+            warn "[OpalBuilder] Unknown theme preset: #{@theme}"
+          end
+          css += "\n" + StreamWeaver::Theme::Presets.generate_preset_css(@theme.to_sym)
+        end
+        File.write(output_path("sw-theme.css"), css)
+      end
+
+      def write_index_html
+        morphdom_js = File.exist?(output_path("morphdom.min.js")) ? "morphdom.min.js" : nil
+        marked_js   = File.exist?(output_path("marked.umd.js"))   ? "marked.umd.js"   : nil
+        File.write(output_path("index.html"),
+          OpalShell.render(
+            title: @title,
+            app_js: "app.js",
+            morphdom_js: morphdom_js,
+            marked_js: marked_js,
+            prism_js: local_asset("prism.min.js"),
+            prism_css: local_asset("prism-tomorrow.min.css"),
+            diff_js: local_asset("diff.min.js"),
+            mermaid_js: local_asset("mermaid.min.js"),
+            mermaid_zoom_js: local_asset("sw-mermaid-zoom.js"),
+            theme_css: File.exist?(output_path("sw-theme.css")) ? "sw-theme.css" : nil,
+            google_fonts_url: google_fonts_url_for_build,
+            body_theme: @theme ? "sw-theme-default sw-theme-#{@theme}" : "sw-theme-default",
+            dark_mode_script: StreamWeaver::Theme::AutoMode.inline_script
+          ))
+      end
+
+      def google_fonts_url_for_build
+        if @theme && (preset = StreamWeaver::Theme::Presets.get(@theme.to_sym))
+          StreamWeaver::Theme::Presets.google_fonts_url(preset)
+        else
+          "https://fonts.googleapis.com/css2?family=Crimson+Pro:wght@400;500;600&family=Source+Sans+3:wght@400;500;600;700&display=swap"
+        end
+      end
+
+      def compile
+        builder = build_opal_bundle
+        builder.build_str(stripped_source, File.basename(@app_file))
+      end
+
+      def build_opal_bundle
+        ::Opal::Builder.new(missing_require_severity: :ignore).tap do |b|
+          b.append_paths(@stubs_root)
+          b.append_paths(@lib_root)
+          b.build("opal")
+          # Must come immediately after "opal" (which defines Opal.regexp) --
+          # see regexp_anchor_patch.rb's own header comment for what bug
+          # this fixes and why the position matters (every compiled file
+          # captures its own local reference to the function it patches, at
+          # load time). This build (`streamweaver opal-build`, the AOT
+          # per-file compile path) doesn't currently hit the bug this
+          # patches -- nothing in its output builds a runtime-interpolated
+          # \A/\z-anchored regex today -- but bin/build_extension's bundle
+          # does, and keeping both Opal builders in sync means the fix
+          # doesn't silently stop applying the moment that changes.
+          b.build("stream_weaver/opal/regexp_anchor_patch")
+          build_stdlib(b)
+          b.build("stream_weaver/opal_entry")
+        end
+      end
+
+      def build_stdlib(builder)
+        %w[set cgi json digest thread].each do |lib|
+          builder.build(lib)
+        rescue => e
+          warn "[OpalBuilder] Could not build stdlib '#{lib}': #{e.message}"
+        end
+      end
+
+      def stripped_source
+        File.read(@app_file)
+          .gsub(/^\s*require_relative\s+['"][^'"]+['"]\s*$/, "")
+          .gsub(/^\s*require\s+['"]stream_weaver['"]\s*$/, "")
+      end
+
+      def output_path(filename)
+        File.join(@output_dir, filename)
+      end
+
+      def derive_title
+        File.basename(@app_file, ".rb").tr("_-", " ").split.map(&:capitalize).join(" ")
+      end
+    end
+  end
+end

data/lib/stream_weaver/opal/env.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+# backtick_javascript: true
+
+module StreamWeaver
+  module Opal
+    # Answers "is there a DOM here?" for code that is compiled once and then
+    # runs in two very different hosts.
+    #
+    # The same bundle powers a browser tab (where `document` and `window` exist
+    # and the runtime patches live nodes) and a bare Node process (where neither
+    # exists and the runtime can only build strings). Rather than making every
+    # caller take a "browser or not" argument -- which would change the shape of
+    # `app()` and break existing builds -- the browser-only paths ask here and
+    # no-op when the answer is no.
+    #
+    # Under MRI this is always false: MRI is neither host, and short-circuiting
+    # before the backtick keeps the JS probe from being evaluated as a shell
+    # command.
+    module Env
+      def self.dom?
+        return false unless RUBY_ENGINE == "opal"
+
+        # :nocov:
+        `typeof document !== 'undefined' && document !== null && typeof document.createElement === 'function'`
+        # :nocov:
+      end
+    end
+  end
+end

data/lib/stream_weaver/opal/reactive_state.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module StreamWeaver
+  module Opal
+    class ReactiveState
+      def initialize(hash = {})
+        @data         = hash.transform_keys(&:to_sym)
+        @watchers     = Hash.new { |h, k| h[k] = [] }
+        @tracking     = nil
+        @track_map    = Hash.new { |h, k| h[k] = [] }
+        @change_hooks = []
+      end
+
+      def [](key)
+        key = key.to_sym
+        @track_map[key] << @tracking if @tracking && !@track_map[key].include?(@tracking)
+        @data[key]
+      end
+
+      def []=(key, value)
+        key = key.to_sym
+        old = @data[key]
+        @data[key] = value
+        return if old == value
+        notify_watchers(key)
+        @change_hooks.each { |h| h.call(key) }
+      end
+
+      def watch(key, &block)
+        @watchers[key.to_sym] << block
+      end
+
+      def on_any_change(&block)
+        @change_hooks << block
+      end
+
+      def track(region_id)
+        prev, @tracking = @tracking, region_id
+        yield
+      ensure
+        @tracking = prev
+      end
+
+      def reset_tracking
+        @track_map.clear
+      end
+
+      def dependencies_for(region_id)
+        @track_map.each_with_object([]) { |(key, ids), arr| arr << key if ids.include?(region_id) }
+      end
+
+      def dependencies_for_key(key)
+        @track_map[key.to_sym].dup
+      end
+
+      def ==(other)
+        other.is_a?(ReactiveState) ? @data == other.to_h : @data == other
+      end
+
+      def to_h
+        @data.dup
+      end
+
+      def key?(key)
+        @data.key?(key.to_sym)
+      end
+
+      private
+
+      def notify_watchers(key)
+        @watchers[key].each { |w| w.call(@data[key]) }
+      end
+    end
+  end
+end

data/lib/stream_weaver/opal/regexp_anchor_patch.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+# backtick_javascript: true
+
+# Fixes a real Opal bug: \A and \z anchors are only translated to JS's ^/$
+# for a regex LITERAL known at compile time. An INTERPOLATED regex literal
+# (`/foo#{bar}baz/`) goes through Opal.regexp, which joins the source parts
+# and passes them straight to `new RegExp(...)` with zero anchor
+# translation. \A/\z aren't valid JS regex escapes, so they silently match
+# nothing instead of anchoring -- no error, just a pattern that quietly
+# never matches.
+#
+# Regexp.new(string) is NOT the same bug and does not need this patch --
+# it has its own, separate corelib-level translation
+# (`regexp.replace('\A', '^').replace('\z', '$')`, no interpolation
+# involved at all). That handling has its own narrower limitations (no /g,
+# so only the first \A and first \z in a pattern get translated; \Z isn't
+# handled) but is unaffected by, and doesn't fix, the Opal.regexp bug this
+# file patches.
+#
+# Found via StreamWeaver::Org::Reader#callout_marker_match, which builds
+# /\A\*(#{Regexp.union(VARIANT_EMOJI.keys)})...\*\z/ at runtime -- every
+# emoji-marked callout silently misclassified as a card. Not specific to
+# Regexp.union, emoji, or that one call site: reproduced with a plain
+# string interpolated into an anchored pattern, no union/escape involved --
+# it's specifically about interpolation, not about Regexp.new.
+#
+# Must load AFTER `opal` (which defines Opal.regexp) and BEFORE anything
+# else in the build sequence -- every compiled file captures its OWN
+# `$regexp = Opal.regexp` local alias at module-load time (a per-file
+# Opal codegen optimization), so patching Opal.regexp from a script loaded
+# after the whole bundle has already executed is too late: those aliases
+# already point at the original, unpatched function. Compiling this as
+# part of the same Opal::Builder sequence (see bin/build_extension),
+# positioned right after `opal` and before any other `builder.build` call,
+# is what makes every later file's alias capture pick up the fix instead.
+#
+# \A -> ^ is an exact translation as long as the pattern never reaches JS's
+# `m` (multiline) flag -- confirmed by reading Opal.regexp's own source: it
+# only ever sets JS's `s` (dotall) for Ruby's /m modifier, never JS's `m`,
+# so ^ stays equivalent to \A for every pattern this function is ever
+# called with. \z -> $ is the same story for \z specifically; \Z is treated
+# the same way here for simplicity, though it isn't exact (\Z also matches
+# just before a trailing newline, $ without /m doesn't) -- fine for this
+# codebase's actual patterns, worth knowing if a future one relies on that
+# distinction.
+#
+# Not yet filed upstream -- tracked as stream_weaver-mg6b.
+if RUBY_ENGINE == "opal"
+  %x{
+    (function () {
+      var original = Opal.regexp;
+      Opal.regexp = function (parts, flags) {
+        for (var i = 0; i < parts.length; i++) {
+          if (typeof parts[i] === "string") {
+            parts[i] = parts[i].replace(/\\A/g, "^").replace(/\\[zZ]/g, "$");
+          }
+        }
+        return original(parts, flags);
+      };
+    })();
+  }
+end

data/lib/stream_weaver/opal/renderer.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require "cgi"
+
+module StreamWeaver
+  module Opal
+    class OpalRenderer
+      attr_reader :adapter
+
+      def initialize(adapter, state)
+        @adapter = adapter
+        @state = state
+        @output = []
+      end
+
+      # Block tags — open tag, yield, close tag.
+      # If the block returns a String and nothing was added to @output inside the block,
+      # treat the return value as plain text (mirrors Phlex behavior for simple text blocks).
+      %w[div span p ul ol li h1 h2 h3 h4 h5 h6 form label select textarea
+         nav header footer main section article aside table thead tbody tr th td
+         button fieldset legend details summary strong em a
+         pre code blockquote figure figcaption caption style script small
+         time mark sub sup abbr dl dt dd].each do |tag|
+        define_method(tag) do |**attrs, &block|
+          @output << "<#{tag}#{attrs_to_html(attrs)}>"
+          if block
+            before_len = @output.length
+            result = block.call
+            # If block didn't add anything (returned a string), emit it as plain text
+            if @output.length == before_len && result.is_a?(String)
+              @output << html_escape(result)
+            end
+          end
+          @output << "</#{tag}>"
+        end
+      end
+
+      # Void (self-closing) tags
+      %w[input hr br img link meta].each do |tag|
+        define_method(tag) do |**attrs|
+          @output << "<#{tag}#{attrs_to_html(attrs)}>"
+        end
+      end
+
+      def plain(text)
+        @output << html_escape(text.to_s)
+      end
+
+      def raw(html)
+        @output << html.to_s
+      end
+
+      # Phlex marks trusted strings with #safe before #raw will emit them.
+      # Here #raw already emits verbatim, so this is just the identity function
+      # -- it exists so shared renderers can call view.raw(view.safe(css))
+      # unchanged in both adapters.
+      def safe(html) = html.to_s
+
+      def to_html
+        @output.join
+      end
+
+      private
+
+      def attrs_to_html(attrs)
+        return "" if attrs.empty?
+        " " + attrs.filter_map do |k, v|
+          next if v == false
+          key = k.to_s.tr("_", "-")
+          v == true ? key : "#{key}=\"#{html_escape(v.to_s)}\""
+        end.join(" ")
+      end
+
+      def html_escape(str) = CGI.escapeHTML(str.to_s)
+    end
+  end
+end

data/lib/stream_weaver/opal/runtime.rb

@@ -0,0 +1,250 @@
+# frozen_string_literal: true
+
+require_relative "reactive_state"
+require_relative "shell"
+
+module StreamWeaver
+  module Opal
+    class OpalRuntime
+      class << self
+        attr_accessor :current
+      end
+
+      attr_reader :state
+
+      def initialize(adapter:)
+        @adapter              = adapter
+        @state                = ReactiveState.new
+        @callbacks            = {}
+        @block                = nil
+        @start_hooks          = []
+        @start_hooks_fired    = false
+        @watchers_initialized = false
+        @sync_rendering       = false
+        @rerender_pending     = false
+        @state.on_any_change { schedule_rerender }
+      end
+
+      def watchers_initialized? = @watchers_initialized
+
+      def set_block(&block)
+        @block = block
+      end
+
+      def update_state(key, value)
+        @state[key] = value
+      end
+
+      def register_callback(dom_id, &proc)
+        @callbacks[dom_id] = proc
+      end
+
+      def invoke_callback(dom_id)
+        @callbacks[dom_id]&.call(@state)
+      end
+
+      def register_start_hook(block)
+        @start_hooks << block unless @start_hooks_fired
+      end
+
+      def render_html
+        @callbacks.clear
+        @state.reset_tracking
+        OpalRuntime.current = self
+
+        # First pass: build components and determine count (no tracking yet)
+        app = StreamWeaver::App.new("__opal__", &@block)
+        app.rebuild_with_state(@state)
+        @watchers_initialized = true
+        n = app.components.length
+
+        register_component_callbacks(app.components)
+
+        # Second pass: render each component inside its own track region.
+        # rebuild_with_state is called inside each track block so that state
+        # reads in the DSL block (e.g. `text state[:name].to_s`) are recorded
+        # against the correct region_id.
+        # DSL-time reads (state[:key] inside the app block) happen during rebuild_with_state,
+        # so we re-build once per region inside track() to attribute reads to the correct region.
+        parts = (0...n).map do |i|
+          region_html = @state.track("sw-region-#{i}") do
+            scoped_app = StreamWeaver::App.new("__opal__", &@block)
+            scoped_app.rebuild_with_state(@state)
+            component = scoped_app.components[i]
+            sub = OpalRenderer.new(@adapter, @state)
+            component.render(sub, @state) if component
+            sub.to_html
+          end
+          "<div id=\"sw-region-#{i}\">#{region_html}</div>"
+        end
+        parts.join
+      ensure
+        OpalRuntime.current = nil
+      end
+
+      # --- DOM-free rendering -------------------------------------------------
+      #
+      # render_html already builds the whole document without touching the DOM;
+      # everything below is what a non-browser host (Node, a CLI) needs around
+      # it. Nothing here references `window` or `document`, directly or through
+      # a callee, so the same compiled bundle renders in a bare Node process.
+
+      # The document body, as a string. Same markup the browser paints.
+      def render_body_html
+        render_html
+      end
+
+      # Per-component CSS gathered during the last render.
+      #
+      # In a browser the adapter appends this to <head> and the caller never
+      # needs it. With no <head> to append to, the caller has to place it, so
+      # the collected text is handed back rather than dropped -- a document
+      # rendered to a file is styled because of this.
+      def collected_css
+        return "" unless @adapter.respond_to?(:collected_css_text)
+
+        @adapter.collected_css_text
+      end
+
+      # A complete, standalone HTML document: body markup baked in, component
+      # CSS inlined, no app.js and no runtime boot. This is the artifact a
+      # `streamweaver-render doc.rb > doc.html` CLI writes out.
+      #
+      # stylesheet: framework CSS to inline ahead of the component CSS. Defaults
+      # to whatever is reachable from the current host (see CSS.base_stylesheet)
+      # -- a host that ships the full theme file can pass its contents instead.
+      # Remaining options are forwarded to OpalShell.render.
+      def render_document(title: "StreamWeaver Document", stylesheet: nil, **shell_options)
+        body = render_html
+        css  = [stylesheet || StreamWeaver::CSS.base_stylesheet, collected_css]
+               .reject { |c| c.nil? || c.to_s.strip.empty? }.join("\n")
+
+        OpalShell.render(
+          title: title,
+          app_js: nil,
+          body_html: body,
+          inline_css: css,
+          **shell_options
+        )
+      end
+
+      def register_component_callbacks(components)
+        Array(components).each do |c|
+          c.register_callbacks(@callbacks)
+          register_component_callbacks(c.children)
+        end
+      end
+
+      def render_and_patch
+        @sync_rendering = true
+        html = render_html
+        patch_dom(html)
+      ensure
+        @sync_rendering = false
+        fire_start_hooks_once
+      end
+
+      def invoke_and_patch(dom_id)
+        @sync_rendering = true
+        invoke_callback(dom_id)
+        patch_dom(render_html)
+      ensure
+        @sync_rendering = false
+      end
+
+      def update_and_patch(key, value)
+        @sync_rendering = true
+        update_state(key, value)
+        affected_regions = @state.dependencies_for_key(key.to_sym)
+        if affected_regions.empty?
+          patch_dom(render_html)
+        else
+          html = render_html
+          patch_regions(affected_regions, html)
+        end
+      ensure
+        @sync_rendering = false
+      end
+
+      def patch_regions(region_ids, full_html)
+        # :nocov:
+        %x{
+          var parser = new DOMParser();
+          var doc = parser.parseFromString('<div id="sw-app">' + #{full_html} + '</div>', 'text/html');
+          var ids = #{region_ids};
+          for (var i = 0; i < ids.length; i++) {
+            var id = ids[i];
+            var newRegion = doc.getElementById(id);
+            var oldRegion = document.getElementById(id);
+            if (newRegion && oldRegion) { morphdom(oldRegion, newRegion); }
+          }
+        }
+        # :nocov:
+        announce_render
+      end
+
+      def fire_start_hooks_once
+        return if @start_hooks_fired
+        @start_hooks_fired = true
+        hooks = @start_hooks.dup
+        schedule_start_hooks(hooks)
+      end
+
+      def schedule_start_hooks(hooks)
+        # :nocov:
+        runtime = self
+        %x{
+          setTimeout(function() {
+            #{hooks.each(&:call)};
+            #{runtime.schedule_rerender};
+          }, 0);
+        }
+        # :nocov:
+      end
+
+      def schedule_rerender
+        # State mutations during a sync render are dropped — app blocks should not
+        # write state as a side effect of building the view.
+        return if @sync_rendering || @rerender_pending
+        @rerender_pending = true
+        return unless RUBY_ENGINE == "opal"
+        runtime = self
+        # :nocov:
+        %x{
+          setTimeout(function() {
+            #{runtime.perform_async_render};
+          }, 0);
+        }
+        # :nocov:
+      end
+
+      def perform_async_render
+        @rerender_pending = false
+        render_and_patch
+      end
+
+      def patch_dom(html)
+        # :nocov:
+        %x{ morphdom(document.getElementById('sw-app'), '<div id="sw-app">' + #{html} + '</div>') }
+        # :nocov:
+        announce_render
+      end
+
+      # Signals that freshly patched markup is in the DOM.
+      #
+      # Libraries that decorate rendered output rather than produce it --
+      # Prism, Mermaid -- have to run after a patch, and again after every
+      # subsequent one, because morphdom replaces nodes and takes their
+      # decoration with it. Start hooks and re-renders are scheduled through
+      # setTimeout, so there is no moment after start() when a caller can
+      # simply assume the DOM is settled; this event is that signal.
+      def announce_render
+        return unless RUBY_ENGINE == "opal"
+
+        # :nocov:
+        %x{ document.dispatchEvent(new CustomEvent("sw:render")) }
+        # :nocov:
+      end
+    end
+  end
+end