openui-rails 0.1.0 → 0.3.0

data/lib/openui/rails/default_library/openui.LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2011-2024 Thesys Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/lib/openui/rails/default_library/provenance.json

@@ -0,0 +1,15 @@
+{
+  "runtime_package": "@openuidev/browser-bundle",
+  "runtime_version": "0.2.1",
+  "runtime_integrity": "sha384-GNNBzicRNkuscleA9e7/4cz6JwE9PE4BRKJ1udKWNzBh4DTD2/zpfOz4p91n8sW0",
+  "library": "openuiChatLibrary",
+  "exports": {
+    "library.prompt.txt": "prompt()",
+    "library.spec.json": "toSpec()"
+  },
+  "sha256": {
+    "library.prompt.txt": "7a334672957298e60543d80650615102b934bc88f69115e8602770a988514c3d",
+    "library.spec.json": "2c36842674a3d1f3a06deddd90304c67da65fc83686dd45e51d1b67d4a2178ad",
+    "openui.LICENSE.txt": "b6bdd2d3d161722fb3f3afc039114cfa9f3236f036e1c98e0853bc3a85f6cd9e"
+  }
+}

data/lib/openui/rails/default_library.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "tempfile"
+
+module OpenUI
+  module Rails
+    # Task implementation for installing exports of the pinned default library.
+    class DefaultLibrary # :nodoc:
+      DIRECTORY = File.expand_path("default_library", __dir__)
+      NAMES = %w[library.spec.json library.prompt.txt openui.LICENSE.txt].freeze
+
+      def self.files(directory: DIRECTORY)
+        provenance = JSON.parse(File.read(File.join(directory, "provenance.json")))
+        integrity = RuntimePackage::FILES.fetch("package/dist/openui-bundle.min.js").last
+        unless provenance.fetch("runtime_version") == RuntimeAsset::PINNED_VERSION && provenance.fetch("runtime_integrity") == integrity
+          raise ConfigurationError, "default library exports do not match the pinned runtime"
+        end
+
+        NAMES.to_h do |name|
+          content = File.binread(File.join(directory, name))
+          unless Digest::SHA256.hexdigest(content) == provenance.fetch("sha256").fetch(name)
+            raise ConfigurationError, "default library export checksum mismatch; reinstall the gem"
+          end
+          [ name, content ]
+        end
+      rescue JSON::ParserError, KeyError, SystemCallError
+        raise ConfigurationError, "default library exports are unavailable or invalid; reinstall the gem"
+      end
+
+      def self.prepare(root:, configuration: OpenUI::Rails.configuration, force: false)
+        root = File.realpath(root)
+        exports = files
+        targets = [ configuration.library_spec_path, configuration.prompt_path ].map { |path| safe_path(path, root) }
+        targets << safe_path(File.join(File.dirname(targets.last), "openui.LICENSE.txt"), root)
+        if targets.uniq.size != targets.size || targets.any? { |path| targets.any? { |other| path.start_with?("#{other}/") } }
+          raise ConfigurationError, "prompt and spec need distinct file paths"
+        end
+        contents = targets.zip(NAMES.map { |name| exports.fetch(name) }).to_h
+        if !force && contents.any? { |path, content| File.exist?(path) && File.binread(path) != content }
+          raise ConfigurationError, "existing library files differ; preserve your custom library or explicitly use openui:library:prepare[true]"
+        end
+
+        contents.each do |path, content|
+          next if File.file?(path) && File.binread(path) == content
+
+          FileUtils.mkdir_p(File.dirname(path))
+          Tempfile.create(".openui-library-", File.dirname(path)) do |temporary|
+            temporary.chmod(0o644)
+            temporary.binmode
+            temporary.write(content)
+            temporary.flush
+            if force
+              File.rename(temporary.path, path)
+            else
+              File.link(temporary.path, path)
+            end
+          end
+        end
+        configuration.reset!
+        targets
+      rescue Errno::EEXIST
+        raise ConfigurationError, "library file appeared during preparation; rerun without overwriting it"
+      end
+
+      def self.safe_path(path, root)
+        raise ConfigurationError, "configure both library_spec_path and prompt_path before preparing the library" if path.nil?
+
+        target = File.expand_path(path, root)
+        unless !File.symlink?(target) && (!File.exist?(target) || File.file?(target))
+          raise ConfigurationError, "library outputs must be regular files inside the application root"
+        end
+
+        ancestor = File.dirname(target)
+        ancestor = File.dirname(ancestor) until File.exist?(ancestor) || File.symlink?(ancestor)
+        real = File.realpath(ancestor)
+        unless File.directory?(ancestor) && (real == root || real.start_with?("#{root}/"))
+          raise ConfigurationError, "library output directory resolves outside the application root"
+        end
+        File.join(real, target.delete_prefix(ancestor).delete_prefix("/"))
+      end
+      private_class_method :safe_path
+    end
+  end
+end

data/lib/openui/rails/doctor.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+module OpenUI
+  module Rails
+    # Read-only task diagnostics. Never executes application authorization,
+    # makes HTTP requests, or prints file contents and exception messages.
+    class Doctor # :nodoc:
+      Check = Struct.new(:name, :status, :message, keyword_init: true)
+      Report = Struct.new(:checks, keyword_init: true) do
+        def ok? = checks.none? { |check| check.status == :fail }
+
+        def to_s
+          lines = checks.map { |check| "[#{check.status.to_s.upcase}] #{check.name}: #{check.message}" }
+          lines << (ok? ? "Required local checks passed. Review all UNVERIFIED checks." : "Setup has required failures. Fix them and rerun openui:doctor.")
+          lines.join("\n")
+        end
+      end
+
+      def initialize(root:, configuration: OpenUI::Rails.configuration, routes:)
+        @root = File.expand_path(root)
+        @configuration = configuration
+        @routes = routes
+      end
+
+      def run
+        @checks = []
+        valid = check_configuration
+        check_route
+        check_assets
+        check_library_identity if valid
+        record("browser", :unverified, "Verify Stimulus registration, rendering, stylesheet loading, and event handling in a browser.")
+        record("authorization", :unverified, "Review actor resolution, tenant-scoped surfaces, and global or per-action authorizers. Callbacks were not executed; missing authorization denies actions.")
+        record("idempotency", :unverified, "Verify atomic shared storage for multiple workers, TTL limits, and business constraints.")
+        record("recovery", :unverified, "Verify authorized subscriptions, canonical snapshots, and host-owned fallback UI.")
+        Report.new(checks: @checks.freeze)
+      end
+
+      private
+
+      def record(name, status, message)
+        @checks << Check.new(name: name, status: status, message: message).freeze
+      end
+
+      def check_configuration
+        @configuration.validate!
+        prompt = @configuration.prompt_path
+        raise ConfigurationError if prompt.nil? || !File.file?(prompt) || File.zero?(prompt)
+
+        record("configuration", :pass, "Library files and numeric limits are valid.")
+        true
+      rescue OpenUI::Rails::Error, SystemCallError, ArgumentError, TypeError
+        record("configuration", :fail, "Review library paths, nonempty prompt, manifest JSON, asset settings, and numeric limits. For the default library, run openui:library:prepare.")
+        false
+      end
+
+      def check_route
+        endpoint = @configuration.actions_endpoint
+        raise ConfigurationError unless endpoint.is_a?(String) && endpoint.start_with?("/") && !endpoint.start_with?("//") && !endpoint.match?(/[?#]/)
+
+        raise ConfigurationError unless endpoint.end_with?("/actions")
+
+        mounts = @routes.routes.select { |route| route.app.respond_to?(:app) && route.app.app == Engine }
+        mount_path = endpoint.delete_suffix("/actions")
+        mount_path = "/" if mount_path.empty?
+        matching = mounts.any? do |route|
+          route.path.spec.to_s == mount_path && (route.verb.empty? || route.verb.include?("POST"))
+        end
+        if matching
+          record("actions route", :pass, "Static engine mount matches actions_endpoint. Request constraints were not executed.")
+        elsif mounts.any? { |route| route.path.spec.to_s.match?(/[:*]/) }
+          record("actions route", :unverified, "The engine has a dynamic mount. Verify actions_endpoint and request constraints in the host.")
+        else
+          raise ConfigurationError
+        end
+      rescue OpenUI::Rails::Error, ArgumentError
+        record("actions route", :fail, "Mount OpenUI::Rails::Engine and match actions_endpoint to that mount's /actions path.")
+      end
+
+      def default_assets?
+        @configuration.runtime_assets == :self_hosted && @configuration.runtime_url.nil?
+      end
+
+      def check_assets
+        unless default_assets? && @configuration.runtime_stylesheet_url.nil?
+          urls = [ RuntimeAsset.url(@configuration), RuntimeAsset.stylesheet_url(@configuration) ]
+          hashes = [ RuntimeAsset.integrity(@configuration), RuntimeAsset.stylesheet_integrity(@configuration) ]
+          raise ConfigurationError unless urls.all? { |url| url.is_a?(String) && !url.empty? } &&
+            hashes.all? { |value| value.is_a?(String) && value.match?(/\Asha(?:256|384|512)-[A-Za-z0-9+\/=]+\z/) }
+
+          record("runtime assets", :unverified, "Custom or external URLs and integrity settings exist. No network request or content verification was performed.")
+          return
+        end
+
+        raise ConfigurationError unless RuntimeAsset.version(@configuration) == RuntimeAsset::PINNED_VERSION
+
+        public_root = File.join(@root, "public")
+        url = @configuration.local_runtime_path
+        raise ConfigurationError unless url.is_a?(String) && url.start_with?("/") && !url.match?(/[?#]/)
+
+        directory = File.expand_path(url.delete_prefix("/"), public_root)
+        raise ConfigurationError unless directory.start_with?("#{public_root}/")
+
+        RuntimePackage::FILES.each_value do |suffix, expected|
+          path = File.join(directory, "#{RuntimeAsset::FILE_PREFIX}-#{RuntimeAsset::PINNED_VERSION}.#{suffix}")
+          inside = File.file?(path) && File.realpath(path).start_with?("#{File.realpath(@root)}/public/")
+          verified = inside && "sha384-#{Digest::SHA384.file(path).base64digest}" == expected
+          sri = case suffix
+          when "js" then RuntimeAsset.integrity(@configuration)
+          when "css" then RuntimeAsset.stylesheet_integrity(@configuration)
+          else expected
+          end
+          verified &&= valid_integrity?(path, sri)
+          record("runtime #{suffix}", verified ? :pass : :fail,
+            verified ? "Matches the pinned checksum and configured integrity." : "Missing asset, checksum mismatch, or incorrect integrity override. Run openui:runtime:fetch and review integrity settings.")
+        end
+      rescue OpenUI::Rails::Error, SystemCallError, ArgumentError, TypeError
+        record("runtime assets", :fail, "Review runtime version, paths, URLs, stylesheet, and integrity hashes. Keep default assets inside public/ and run openui:runtime:fetch.")
+      end
+
+      def valid_integrity?(path, value)
+        return false unless value.is_a?(String) && value.match?(/\Asha(?:256|384|512)-[A-Za-z0-9+\/=]+\z/)
+
+        algorithm = value.split("-", 2).first
+        "#{algorithm}-#{Digest.const_get(algorithm.upcase).file(path).base64digest}" == value
+      end
+
+      def check_library_identity
+        unless default_assets?
+          record("library identity", :unverified, "Verify the configured prompt/spec against the actual custom runtime library.")
+          return
+        end
+
+        files = DefaultLibrary.files
+        matching = @configuration.library_fingerprint == LibraryManifest.parse(files.fetch("library.spec.json")).fingerprint &&
+          File.binread(@configuration.prompt_path) == files.fetch("library.prompt.txt")
+        record("library identity", matching ? :pass : :fail,
+          matching ? "Prompt and spec match the pinned default chat library." : "The default runtime needs its matching prompt/spec. Preserve custom files or use openui:library:prepare; custom libraries need a matching custom runtime.")
+      rescue OpenUI::Rails::Error, SystemCallError, ArgumentError, TypeError
+        record("library identity", :fail, "Cannot verify the pinned default library exports. Review the gem installation and configured files.")
+      end
+    end
+  end
+end

data/lib/openui/rails/library_manifest.rb

@@ -123,7 +123,7 @@ module OpenUI
       # Human-readable identifier, e.g. "support@1.2.0+1a2b3c4d5e6f".
       attr_reader :identifier
 
-      # Return the names declared in the components collection.
+      # Return names from an array or name-keyed components collection.
       #
       # @return [Array<String>]
       def component_names = names_for(:components)
@@ -178,6 +178,7 @@ module OpenUI
         keys = COLLECTION_KEYS.fetch(collection)
         keys.each do |key|
           value = document[key]
+          return value.keys if value.is_a?(Hash)
           next unless value.is_a?(Array)
 
           return value.filter_map { |entry| name_of(entry) }

data/lib/openui/rails/surface.rb

@@ -8,10 +8,10 @@ module OpenUI
     # 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`).
+    # `context`, `message_id`, `next_sequence`, `completed`).
     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
+      ATTRIBUTES = %i[id version library_version response context streaming message_id next_sequence completed].freeze
 
       attr_reader(*ATTRIBUTES)
 
@@ -72,15 +72,28 @@ module OpenUI
       #
       # @param message_id [String, nil] stream identity; defaults to id
       #
+      # @param next_sequence [Integer] next expected envelope sequence after persisted output
+      #
+      # @param completed [Boolean] ignore later non-snapshot envelopes for a terminal response
+      #
       # @return [Surface]
       def initialize(id:, version: 0, library_version: nil, response: nil, context: nil,
-                     streaming: false, message_id: nil)
+                     streaming: false, message_id: nil, next_sequence: 0, completed: false)
         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)
 
+        unless next_sequence.is_a?(Integer) && next_sequence.between?(0, 9_007_199_254_740_991)
+          raise ArgumentError, "next_sequence must be a non-negative JavaScript-safe Integer"
+        end
+        unless [ true, false ].include?(completed) && !(completed && streaming)
+          raise ArgumentError, "completed must be boolean and cannot coexist with streaming"
+        end
+
+        @next_sequence = next_sequence
+        @completed = completed
         @id = id.to_s.dup.freeze
         @version = version || 0
         @library_version = library_version&.to_s&.dup&.freeze
@@ -102,7 +115,8 @@ module OpenUI
       def to_h
         {
           id: id, version: version, library_version: library_version,
-          response: response, context: context, streaming: streaming, message_id: message_id
+          response: response, context: context, streaming: streaming, message_id: message_id,
+          next_sequence: next_sequence, completed: completed
         }
       end
 
@@ -124,10 +138,14 @@ module OpenUI
       #
       # @return [Hash] HTML data attributes with string values
       def to_mount_data(stream: false, actions_endpoint:, initial_state: nil)
+        raise ArgumentError, "completed surfaces cannot be mounted as streaming" if completed && stream
+
         {
           controller: "openui",
           openui_surface_id: id,
           openui_message_id: message_id,
+          openui_next_sequence: next_sequence.to_s,
+          openui_completed: completed.to_s,
           openui_version: version.to_s,
           openui_library_version: library_version,
           openui_streaming: (streaming? || stream) ? "true" : "false",

data/lib/openui/rails/version.rb

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

data/lib/openui/rails.rb

@@ -27,7 +27,9 @@ require "openui/rails/actions"
 require "openui/rails/adapters/ruby_llm"
 require "openui/rails/runtime_asset"
 require "openui/rails/runtime_package"
+require "openui/rails/default_library"
 require "openui/rails/surface"
 require "openui/rails/view_helper"
 require "openui/rails/configuration"
+require "openui/rails/doctor"
 require "openui/rails/engine"

data/lib/tasks/openui.rake

@@ -1,6 +1,25 @@
 # frozen_string_literal: true
 
 namespace :openui do
+  desc "Check local OpenUI setup without writes or network requests"
+  task doctor: :environment do
+    report = OpenUI::Rails::Doctor.new(root: ::Rails.root, routes: ::Rails.application.routes).run
+    puts report
+    exit 1 unless report.ok?
+  end
+
+  namespace :library do
+    desc "Prepare the pinned default chat prompt and spec (pass true to overwrite)"
+    task :prepare, [ :force ] => :environment do |_task, args|
+      unless [ nil, "true", "false" ].include?(args[:force])
+        raise OpenUI::Rails::ConfigurationError, "force must be true or false"
+      end
+      paths = OpenUI::Rails::DefaultLibrary.prepare(root: ::Rails.root, force: args[:force] == "true")
+      paths.each { |path| puts "Prepared #{path}" }
+      puts "Default library ready; commit the prompt and spec together."
+    end
+  end
+
   namespace :runtime do
     desc "Vendor the checksum-locked OpenUI JS, CSS and license (requires npm)"
     task :fetch, [ :destination ] => :environment do |_task, args|

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: openui-rails
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Andy Wang
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-18 00:00:00.000000000 Z
+date: 2026-10-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -49,6 +49,7 @@ files:
 - CODE_OF_CONDUCT.md
 - CONFIGURATION.md
 - CONTRIBUTING.md
+- DEVELOPMENT.md
 - LICENSE
 - README.md
 - RELEASING.md
@@ -60,6 +61,25 @@ files:
 - app/javascript/openui/rails/openui_controller.js
 - app/javascript/openui/rails/openui_envelope_controller.js
 - config/routes.rb
+- examples/support_desk/README.md
+- examples/support_desk/app/controllers/support_desk/base_controller.rb
+- examples/support_desk/app/controllers/support_desk/conversations_controller.rb
+- examples/support_desk/app/controllers/support_desk/sessions_controller.rb
+- examples/support_desk/app/javascript/support_desk.js
+- examples/support_desk/app/models/support_desk/conversation.rb
+- examples/support_desk/app/models/support_desk/demo.rb
+- examples/support_desk/app/models/support_desk/receipt.rb
+- examples/support_desk/app/models/support_desk/ticket.rb
+- examples/support_desk/app/models/support_desk/user.rb
+- examples/support_desk/app/views/layouts/support_desk/application.html.erb
+- examples/support_desk/app/views/support_desk/conversations/index.html.erb
+- examples/support_desk/app/views/support_desk/conversations/show.html.erb
+- examples/support_desk/boot.rb
+- examples/support_desk/config/importmap.rb
+- examples/support_desk/config/initializers/openui.rb
+- examples/support_desk/config/routes.rb
+- examples/support_desk/db/migrate/20261019000000_create_support_desk.rb
+- examples/support_desk/install.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
@@ -73,6 +93,12 @@ files:
 - lib/openui/rails/actions/submission.rb
 - lib/openui/rails/adapters/ruby_llm.rb
 - lib/openui/rails/configuration.rb
+- lib/openui/rails/default_library.rb
+- lib/openui/rails/default_library/library.prompt.txt
+- lib/openui/rails/default_library/library.spec.json
+- lib/openui/rails/default_library/openui.LICENSE.txt
+- lib/openui/rails/default_library/provenance.json
+- lib/openui/rails/doctor.rb
 - lib/openui/rails/engine.rb
 - lib/openui/rails/errors.rb
 - lib/openui/rails/json_value.rb