openui-rails 0.1.0

data/lib/openui/rails/stream/transports.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require "openui/rails/stream/transports/memory"
+require "openui/rails/stream/transports/action_cable"
+require "openui/rails/stream/transports/turbo_streams"
+
+module OpenUI
+  module Rails
+    module Stream
+      # Transport wrappers for {Broadcaster}. Each responds to
+      # `#broadcast(envelope)` and is intentionally thin: sequencing, coalescing
+      # and size limits live in {Bridge}, not here.
+      module Transports
+        module_function
+
+        # Build a transport from a configured name.
+        #
+        # @param name [Symbol] :action_cable, :turbo / :turbo_streams or :memory
+        #
+        # @param options [Hash] forwarded to the transport constructor
+        #
+        # @return [ActionCable, TurboStreams, Memory]
+        #
+        # @raise [ConfigurationError] when the name is unsupported
+        def build(name, **options)
+          case name.to_sym
+          when :action_cable
+            ActionCable.new(options.delete(:stream_name), **options)
+          when :turbo, :turbo_streams
+            TurboStreams.new(options.delete(:stream), **options)
+          when :memory
+            Memory.new(**options)
+          else
+            raise ConfigurationError,
+                  "unsupported transport #{name.inspect}; expected one of [:action_cable, :turbo, :memory]"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/openui/rails/surface.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+module OpenUI
+  module Rails
+    # Immutable description of one mounted OpenUI surface.
+    #
+    # The host Rails app owns persistence; the Gem only needs a stable,
+    # opaque identifier plus the current revision and the source to render.
+    # A surface can be built explicitly or coerced from a host record that
+    # exposes `id` (and, optionally, `version`, `library_version`, `response`,
+    # `context`, `message_id`).
+    class Surface
+      # Surface values copied from an explicit object, hash, or host record.
+      ATTRIBUTES = %i[id version library_version response context streaming message_id].freeze
+
+      attr_reader(*ATTRIBUTES)
+
+      # Coerce a host record, hash, or existing surface into a new Surface.
+      # Non-nil overrides replace values extracted from the input.
+      #
+      # @param value [Surface, Hash, #id, nil]
+      #
+      # @param overrides [Hash] surface attribute overrides
+      #
+      # @return [Surface]
+      def self.coerce(value = nil, **overrides)
+        attributes = extract(value).merge(overrides.compact)
+        new(**attributes)
+      end
+
+      def self.extract(value)
+        case value
+        when nil then {}
+        when Surface then value.to_h
+        when Hash
+          ATTRIBUTES.each_with_object({}) do |key, attributes|
+            if value.key?(key)
+              attributes[key] = value[key]
+            elsif value.key?(key.to_s)
+              attributes[key] = value[key.to_s]
+            end
+          end
+        else extract_record(value)
+        end
+      end
+      private_class_method :extract
+
+      def self.extract_record(record)
+        unless record.respond_to?(:id)
+          raise ArgumentError, "surface must respond to #id or be a Hash/#{name}"
+        end
+
+        ATTRIBUTES.each_with_object({ id: record.id }) do |attribute, memo|
+          memo[attribute] = record.public_send(attribute) if attribute != :id && record.respond_to?(attribute)
+        end
+      end
+      private_class_method :extract_record
+
+      # Build an immutable surface snapshot for the browser mount.
+      #
+      # @param id [String, #to_s] stable opaque identifier
+      #
+      # @param version [Integer, nil] non-negative revision used for stale-action checks
+      #
+      # @param library_version [String, nil] fingerprint of the browser library manifest
+      #
+      # @param response [String, nil] OpenUI Lang source rendered by the browser
+      #
+      # @param context [Object, nil] JSON-compatible initial state
+      #
+      # @param streaming [Boolean] whether a response is still streaming
+      #
+      # @param message_id [String, nil] stream identity; defaults to id
+      #
+      # @return [Surface]
+      def initialize(id:, version: 0, library_version: nil, response: nil, context: nil,
+                     streaming: false, message_id: nil)
+        raise ArgumentError, "surface id is required" if id.nil? || id.to_s.empty?
+        unless version.nil? || (version.is_a?(Integer) && version >= 0)
+          raise ArgumentError, "surface version must be a non-negative Integer"
+        end
+        raise ArgumentError, "surface response must be a String" unless response.nil? || response.is_a?(String)
+
+        @id = id.to_s.dup.freeze
+        @version = version || 0
+        @library_version = library_version&.to_s&.dup&.freeze
+        @response = response&.dup&.freeze
+        @context = JsonValue.copy(context)
+        @streaming = streaming ? true : false
+        @message_id = (message_id&.to_s || @id).dup.freeze
+        freeze
+      end
+
+      # Whether the host says this surface is still receiving a response.
+      #
+      # @return [Boolean]
+      def streaming? = @streaming
+
+      # Return the surface fields as a symbol-keyed hash.
+      #
+      # @return [Hash]
+      def to_h
+        {
+          id: id, version: version, library_version: library_version,
+          response: response, context: context, streaming: streaming, message_id: message_id
+        }
+      end
+
+      # The flat `data:` hash for the Stimulus mount element. Keys use
+      # underscores so Rails renders them as `data-openui-*` attributes; nil
+      # values are omitted so the controller can rely on presence.
+      #
+      # Every value is deliberately a String. DOM data attributes are strings,
+      # and Rails only JSON-coerces *non-String* values. This path broke on
+      # Rails 8.0 with json >= 3.1 (ActiveSupport passes a `quirks_mode:`
+      # keyword the gem removed). Emitting strings keeps rendering independent
+      # of ActiveSupport's JSON encoder.
+      #
+      # @param stream [Boolean] mark this mount as streaming
+      #
+      # @param actions_endpoint [String] host engine action URL
+      #
+      # @param initial_state [Object, nil] JSON-compatible state override
+      #
+      # @return [Hash] HTML data attributes with string values
+      def to_mount_data(stream: false, actions_endpoint:, initial_state: nil)
+        {
+          controller: "openui",
+          openui_surface_id: id,
+          openui_message_id: message_id,
+          openui_version: version.to_s,
+          openui_library_version: library_version,
+          openui_streaming: (streaming? || stream) ? "true" : "false",
+          openui_actions_url: actions_endpoint,
+          openui_response: response,
+          openui_stream_byte_limit: OpenUI::Rails.configuration.stream_byte_limit.to_s,
+          openui_initial_state: encode_state(initial_state || context)
+        }.compact
+      end
+
+      private
+
+      def encode_state(state)
+        return nil if state.nil?
+
+        state.is_a?(String) ? state : JSON.generate(state)
+      end
+    end
+  end
+end

data/lib/openui/rails/version.rb

@@ -0,0 +1,5 @@
+module OpenUI
+  module Rails
+    VERSION = "0.1.0"
+  end
+end

data/lib/openui/rails/view_helper.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module OpenUI
+  module Rails
+    # View helper that emits the escaped DOM mount the Stimulus controller
+    # connects to. It renders no OpenUI UI itself: the browser runtime owns
+    # rendering, Rails owns the opaque identifier and revision.
+    module ViewHelper
+      # Include once in the host layout's head. The pinned bundle requires its
+      # stylesheet; it is not injected by JavaScript or repeated per surface.
+      def openui_stylesheet_tag
+        stylesheet_link_tag RuntimeAsset.stylesheet_url,
+          integrity: RuntimeAsset.stylesheet_integrity, crossorigin: "anonymous"
+      end
+
+      # Render a mount element for a surface.
+      #
+      # @param surface [Surface, #id, nil] a Surface, a host record, or nil when
+      #   `response`/`id` are supplied directly
+      # @param stream [Boolean] mark the surface as still streaming
+      # @param label [String, nil] accessible name; when given the mount is
+      #   exposed as a `region` landmark so assistive tech can find it
+      # @param options [Hash] overrides forwarded to {Surface.coerce}
+      # @return [ActiveSupport::SafeBuffer]
+      def openui_surface(surface = nil, stream: false, dom_id: nil, initial_state: nil, label: nil, **options)
+        surface ||= options.delete(:surface)
+        surface = Surface.coerce(surface, **options)
+        fingerprint = OpenUI::Rails.configuration.library_fingerprint
+        if fingerprint && surface.library_version && fingerprint != surface.library_version
+          raise LibraryVersionError, "surface targets a different library; regenerate it with the configured library"
+        end
+        data = surface.to_mount_data(
+          stream: stream,
+          actions_endpoint: OpenUI::Rails.configuration.actions_endpoint,
+          initial_state: initial_state
+        ).merge(RuntimeAsset.mount_data)
+        data[:openui_library_fingerprint] = fingerprint if fingerprint
+
+        # `aria-busy` tells assistive tech the region is still being updated, so
+        # a streaming surface is not announced mid-flight. The controller keeps
+        # it in sync as envelopes complete.
+        aria = { busy: surface.streaming? || stream }
+        aria[:label] = label if label
+
+        tag.div(
+          "",
+          id: dom_id || "openui-surface-#{surface.id}",
+          class: "openui-surface",
+          role: label ? "region" : nil,
+          data: data,
+          aria: aria
+        )
+      end
+    end
+  end
+end

data/lib/openui/rails.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require "openui/rails/version"
+
+module OpenUI
+  # Rails integration for Thesys OpenUI Lang.
+  #
+  # This is an *unofficial* integration: it does not port or fork the OpenUI
+  # parser/renderer, it wires the official, version-pinned JavaScript runtime
+  # into a Rails engine and keeps Rails authoritative for auth, tenancy and
+  # persistence.
+  module Rails
+  end
+end
+
+require "openui/rails/errors"
+require "openui/rails/json_value"
+require "openui/rails/library_manifest"
+require "openui/rails/prompt_builder"
+require "openui/rails/message"
+require "openui/rails/stream/envelope"
+require "openui/rails/stream/accumulator"
+require "openui/rails/stream/bridge"
+require "openui/rails/stream/broadcaster"
+require "openui/rails/stream/transports"
+require "openui/rails/actions"
+require "openui/rails/adapters/ruby_llm"
+require "openui/rails/runtime_asset"
+require "openui/rails/runtime_package"
+require "openui/rails/surface"
+require "openui/rails/view_helper"
+require "openui/rails/configuration"
+require "openui/rails/engine"

data/lib/tasks/openui.rake

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+namespace :openui do
+  namespace :runtime do
+    desc "Vendor the checksum-locked OpenUI JS, CSS and license (requires npm)"
+    task :fetch, [ :destination ] => :environment do |_task, args|
+      configuration = OpenUI::Rails.configuration
+      destination = args[:destination] || ::Rails.root.join("public", configuration.local_runtime_path.delete_prefix("/"))
+      paths = OpenUI::Rails::RuntimePackage.fetch(
+        destination: destination, version: OpenUI::Rails::RuntimeAsset.version(configuration)
+      )
+      paths.each { |path| puts "Vendored #{path}" }
+      puts "Checksums verified; include <%= openui_stylesheet_tag %> in your layout."
+    end
+  end
+end

metadata

@@ -0,0 +1,125 @@
+--- !ruby/object:Gem::Specification
+name: openui-rails
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Andy Wang
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-10-18 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+description: |
+  Render model-generated, streaming, interactive OpenUI Lang UI inside an
+  existing Rails application without migrating the whole frontend to a
+  React/Next.js SPA. Reuses the official, version-pinned OpenUI JavaScript
+  runtime, keeps Rails authoritative for authentication, authorization and
+  persistence, and ships an optional RubyLLM adapter. This is an unofficial
+  integration and is not affiliated with, endorsed by, or maintained by
+  Thesys.
+email:
+- wangyaodi@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- AUDIT.md
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- CONFIGURATION.md
+- CONTRIBUTING.md
+- LICENSE
+- README.md
+- RELEASING.md
+- SECURITY.md
+- THIRD_PARTY_NOTICES.md
+- UPGRADING.md
+- app/controllers/openui/rails/actions_controller.rb
+- app/controllers/openui/rails/application_controller.rb
+- app/javascript/openui/rails/openui_controller.js
+- app/javascript/openui/rails/openui_envelope_controller.js
+- config/routes.rb
+- lib/generators/openui/install/install_generator.rb
+- lib/generators/openui/install/templates/config/initializers/openui.rb.tt
+- lib/generators/openui/install/templates/config/openui/README.md
+- lib/openui/rails.rb
+- lib/openui/rails/actions.rb
+- lib/openui/rails/actions/dispatcher.rb
+- lib/openui/rails/actions/idempotency/memory_store.rb
+- lib/openui/rails/actions/invocation.rb
+- lib/openui/rails/actions/registry.rb
+- lib/openui/rails/actions/schema.rb
+- lib/openui/rails/actions/submission.rb
+- lib/openui/rails/adapters/ruby_llm.rb
+- lib/openui/rails/configuration.rb
+- lib/openui/rails/engine.rb
+- lib/openui/rails/errors.rb
+- lib/openui/rails/json_value.rb
+- lib/openui/rails/library_manifest.rb
+- lib/openui/rails/message.rb
+- lib/openui/rails/prompt_builder.rb
+- lib/openui/rails/runtime_asset.rb
+- lib/openui/rails/runtime_package.rb
+- lib/openui/rails/stream/accumulator.rb
+- lib/openui/rails/stream/bridge.rb
+- lib/openui/rails/stream/broadcaster.rb
+- lib/openui/rails/stream/envelope.rb
+- lib/openui/rails/stream/transports.rb
+- lib/openui/rails/stream/transports/action_cable.rb
+- lib/openui/rails/stream/transports/memory.rb
+- lib/openui/rails/stream/transports/turbo_streams.rb
+- lib/openui/rails/surface.rb
+- lib/openui/rails/version.rb
+- lib/openui/rails/view_helper.rb
+- lib/tasks/openui.rake
+homepage: https://github.com/yorzi/openui-rails
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/yorzi/openui-rails
+  changelog_uri: https://github.com/yorzi/openui-rails/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/yorzi/openui-rails/issues
+  documentation_uri: https://openui-rails.wangyaodi.com
+  rubygems_mfa_required: 'true'
+  allowed_push_host: https://rubygems.org
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Unofficial Rails integration for Thesys OpenUI Lang.
+test_files: []