openui-rails 0.1.0

data/app/controllers/openui/rails/actions_controller.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module OpenUI
+  module Rails
+    # Single allowlisted endpoint for surface actions. Both a component
+    # `onAction` and a browser `toolProvider` `Query()`/`Mutation()` call post
+    # here; the {Actions::Dispatcher} applies every gate (allowlist, schema,
+    # confirmation, staleness, authorization, idempotency) before any effect.
+    #
+    # Forged cross-site requests cannot pass Rails' CSRF protection, and a
+    # missing/invalid token is reported with the same structured shape as any
+    # other failed gate.
+    class ActionsController < ApplicationController
+      rescue_from ::ActionController::InvalidAuthenticityToken, with: :render_csrf_error
+      rescue_from OpenUI::Rails::Error, with: :render_domain_error
+
+      # Reads the JSON/form body only (not path params), so the documented
+      # top-level `action` key cannot collide with the Rails route's own
+      # `action` param. Only known keys are used; values are validated again by
+      # Submission and the action schema.
+      PAYLOAD_KEYS = %w[action args surface_id version idempotency_key confirmed].freeze
+
+      def create
+        result = dispatcher.call(payload, actor: actor)
+
+        render json: { result: result.to_h }, status: :ok
+      end
+
+      private
+
+      def dispatcher
+        Actions::Dispatcher.from_configuration
+      end
+
+      def payload
+        request.request_parameters.slice(*PAYLOAD_KEYS)
+      end
+
+      def actor
+        resolver = OpenUI::Rails.configuration.actor_resolver
+        return resolver.call(self) if resolver
+
+        current_user if respond_to?(:current_user, true)
+      end
+
+      def render_csrf_error(_error)
+        render json: { error: { code: "csrf_failed", message: "invalid authenticity token" } },
+               status: :unprocessable_content
+      end
+
+      def render_domain_error(error)
+        render json: { error: { code: error_code(error), message: error.message } },
+               status: error_status(error)
+      end
+
+      def error_code(error)
+        case error
+        when UnknownActionError then "unknown_action"
+        when UnauthorizedActionError then "unauthorized"
+        when StaleSurfaceError then "stale_surface"
+        when ReplayError then "replay"
+        when InvalidActionError then "invalid_action"
+        else "error"
+        end
+      end
+
+      def error_status(error)
+        case error
+        when UnknownActionError then :not_found
+        when UnauthorizedActionError then :forbidden
+        when StaleSurfaceError, ReplayError then :conflict
+        else :unprocessable_content
+        end
+      end
+    end
+  end
+end

data/app/controllers/openui/rails/application_controller.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module OpenUI
+  module Rails
+    # Preserve the host's authentication filters and current-user helpers.
+    class ApplicationController < ::ApplicationController
+      protect_from_forgery with: :exception
+    end
+  end
+end

data/app/javascript/openui/rails/openui_controller.js

@@ -0,0 +1,347 @@
+import { Controller } from "@hotwired/stimulus"
+
+// The pinned runtime is fetched once per page and shared by every surface.
+// A rejected promise is evicted so a later mount can retry.
+const runtimePromises = new Map()
+
+function loadRuntime(url, integrity) {
+  if (!runtimePromises.has(url)) {
+    const promise = new Promise((resolve, reject) => {
+      const script = document.createElement("script")
+      script.src = url
+      script.async = true
+      script.crossOrigin = "anonymous"
+      if (integrity) script.integrity = integrity
+      script.addEventListener("load", () => {
+        if (!window.__OpenUI) {
+          reject(new Error(`OpenUI runtime at ${url} did not expose window.__OpenUI`))
+          return
+        }
+        resolve(window.__OpenUI)
+      })
+      script.addEventListener("error", () =>
+        reject(new Error(`Failed to load the OpenUI runtime from ${url}`))
+      )
+      document.head.appendChild(script)
+    })
+    promise.catch(() => runtimePromises.delete(url))
+    runtimePromises.set(url, promise)
+  }
+  return runtimePromises.get(url)
+}
+
+/**
+ * Mounts the official OpenUI renderer against a server-owned surface.
+ *
+ * The element is a passive view: it renders the accumulated OpenUI Lang, routes
+ * every action/tool call to the single Rails endpoint, and never holds a
+ * credential. Streaming envelopes arrive as `openui:envelope` events and are
+ * applied in order, ignoring duplicates and requesting a snapshot on a gap.
+ */
+export default class extends Controller {
+  connect() {
+    const connection = Symbol("openui-connection")
+    this.connection = connection
+    this.mountPoint = document.createElement("div")
+    this.element.appendChild(this.mountPoint)
+    this.abortController = new AbortController()
+    this.state ||= {
+      source: this.initialResponse,
+      streaming: this.streaming,
+      completed: this.element.dataset.openuiCompleted === "true",
+      nextSequence: Number(this.element.dataset.openuiNextSequence || 0),
+      needsSnapshot: this.element.dataset.openuiNeedsSnapshot === "true",
+    }
+
+    this.onEnvelope = (event) => this.applyEnvelope(event.detail)
+    // Listen on the document so any transport can deliver an envelope: a
+    // dispatch on this element bubbles up, and the envelope controller (used by
+    // the Turbo transport) re-emits from its own element. applyEnvelope ignores
+    // envelopes for other message ids, so a shared document listener is safe.
+    document.addEventListener("openui:envelope", this.onEnvelope)
+    this.onBeforeCache = () => {
+      this.element.dataset.openuiResponse = this.state.source
+      this.element.dataset.openuiStreaming = String(this.state.streaming)
+      this.element.dataset.openuiNextSequence = String(this.state.nextSequence)
+      this.element.dataset.openuiCompleted = String(this.state.completed)
+      this.element.dataset.openuiNeedsSnapshot = String(this.state.needsSnapshot)
+      this.disconnect()
+    }
+    document.addEventListener("turbo:before-cache", this.onBeforeCache)
+
+    this.syncBusy()
+    this.renderRuntime(connection)
+  }
+
+  disconnect() {
+    this.connection = null
+    document.removeEventListener("openui:envelope", this.onEnvelope)
+    document.removeEventListener("turbo:before-cache", this.onBeforeCache)
+    this.abortController?.abort()
+    this.root?.unmount()
+    this.root = null
+    this.mountPoint?.remove()
+    this.mountPoint = null
+  }
+
+  async renderRuntime(connection) {
+    try {
+      const runtime = await loadRuntime(this.runtimeUrl, this.runtimeIntegrity)
+      await this.verifyLibrary(runtime.openuiChatLibrary)
+      if (connection !== this.connection || !this.element.isConnected || !this.mountPoint) return
+      this.runtime = runtime
+      this.render()
+    } catch (error) {
+      if (connection !== this.connection) return
+      this.state.streaming = false
+      this.syncBusy()
+      this.handleError(error)
+    }
+  }
+
+  render() {
+    this.syncBusy()
+    if (!this.runtime || !this.mountPoint || !this.connection) return
+    if (!this.withinByteLimit(this.state.source)) return
+    const { React, createRoot, Renderer, openuiChatLibrary } = this.runtime
+    if (!this.root) this.root = createRoot(this.mountPoint)
+    this.root.render(
+      React.createElement(Renderer, {
+        // The Renderer accepts either raw OpenUI Lang or a stored message that
+        // carries `]]>openui:` markers, so one accumulated field is enough.
+        response: this.state.source,
+        library: openuiChatLibrary,
+        isStreaming: this.state.streaming,
+        initialState: this.initialState,
+        // The official runtime emits { type, params }. It does not await this
+        // void callback; dispatchAction already emits a structured error.
+        onAction: (action) => { this.dispatchAction(action).catch(() => {}) },
+        onStateUpdate: (formState) => this.persistState(formState),
+        toolProvider: this.toolProvider(),
+        onError: (error) => this.handleError(error),
+      })
+    )
+  }
+
+  async verifyLibrary(library) {
+    const expected = this.element.dataset.openuiLibraryFingerprint
+    if (!expected) return
+    if (typeof library?.toSpec !== "function" || !window.crypto?.subtle) {
+      throw Object.assign(new Error("Cannot verify the configured OpenUI library"), { code: "library_version_mismatch" })
+    }
+    const canonical = (value) => {
+      if (Array.isArray(value)) return value.map(canonical)
+      if (value !== null && typeof value === "object") {
+        return Object.fromEntries(Object.keys(value).sort().map((key) => [ key, canonical(value[key]) ]))
+      }
+      return value
+    }
+    const bytes = new TextEncoder().encode(JSON.stringify(canonical(library.toSpec())))
+    const digest = await window.crypto.subtle.digest("SHA-256", bytes)
+    const fingerprint = `sha256:${Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, "0")).join("")}`
+    if (fingerprint !== expected) {
+      throw Object.assign(new Error("Runtime library differs from the configured prompt/spec library"), { code: "library_version_mismatch" })
+    }
+  }
+
+  // --- Streaming -----------------------------------------------------------
+
+  applyEnvelope(envelope) {
+    if (!envelope || envelope.message_id !== this.messageId) return
+    if (!Number.isSafeInteger(envelope.sequence) || envelope.sequence < 0 ||
+        (envelope.type === "openui.delta" && typeof envelope.delta !== "string") ||
+        (envelope.type === "openui.snapshot" && typeof envelope.response !== "string")) {
+      return this.handleError(Object.assign(new Error("Malformed stream envelope"), { code: "invalid_envelope" }))
+    }
+    if (envelope.library_version && this.libraryVersion && envelope.library_version !== this.libraryVersion) {
+      return this.handleError(Object.assign(new Error("OpenUI library version mismatch"), { code: "library_version_mismatch" }))
+    }
+    if (envelope.type !== "openui.snapshot") {
+      if (envelope.sequence < this.state.nextSequence || this.state.completed) return
+      if (this.state.needsSnapshot || envelope.sequence > this.state.nextSequence) return this.requestSnapshot()
+    }
+
+    switch (envelope.type) {
+      case "openui.delta":
+        return this.applyDelta(envelope)
+      case "openui.snapshot":
+        return this.applySnapshot(envelope)
+      case "openui.completed":
+        this.state.nextSequence += 1
+        this.state.streaming = false
+        this.state.completed = true
+        return this.render()
+      case "openui.error":
+        // A stream that ends in error is no longer busy, so assistive tech can
+        // read whatever rendered before the failure.
+        this.state.streaming = false
+        this.state.completed = true
+        this.state.nextSequence += 1
+        this.syncBusy()
+        return this.handleError(Object.assign(new Error(envelope.message || "stream error"), {
+          code: envelope.code,
+        }))
+      default:
+        return undefined
+    }
+  }
+
+  applyDelta(envelope) {
+    if (!this.withinByteLimit(this.state.source + envelope.delta)) return
+    this.state.source = this.state.source + envelope.delta
+    this.state.nextSequence += 1
+    this.state.streaming = envelope.streaming !== false
+    this.render()
+  }
+
+  applySnapshot(envelope) {
+    const minimum = this.state.needsSnapshot ? this.state.nextSequence - 1 : this.state.nextSequence
+    if (envelope.sequence < minimum || !this.withinByteLimit(envelope.response)) return
+    this.state.source = envelope.response
+    this.state.nextSequence = envelope.sequence + 1
+    this.state.needsSnapshot = false
+    this.state.streaming = envelope.streaming === true
+    this.state.completed = !this.state.streaming
+    this.render()
+  }
+
+  requestSnapshot() {
+    if (this.state.needsSnapshot) return
+    this.state.needsSnapshot = true
+    this.dispatch("snapshot-required", { surfaceId: this.surfaceId, sequence: this.state.nextSequence })
+  }
+
+  withinByteLimit(source) {
+    const limit = Number(this.element.dataset.openuiStreamByteLimit || 1048576)
+    if (new TextEncoder().encode(source).byteLength <= limit) return true
+    this.state.streaming = false
+    this.state.completed = true
+    this.syncBusy()
+    this.handleError(Object.assign(new Error("OpenUI stream exceeds byte limit"), { code: "stream_too_large" }))
+    return false
+  }
+
+  // --- Actions -------------------------------------------------------------
+
+  async dispatchAction(payload = {}) {
+    const body = {
+      action: payload.action ?? payload.name ?? payload.type,
+      args: payload.args ?? payload.params ?? {},
+      surface_id: this.surfaceId,
+      version: this.version,
+      idempotency_key: payload.idempotency_key ?? this.newIdempotencyKey(),
+      confirmed: payload.confirmed === true,
+    }
+
+    try {
+      const response = await fetch(this.actionsUrl, {
+        method: "POST",
+        credentials: "same-origin",
+        signal: this.abortController.signal,
+        headers: this.headers(),
+        body: JSON.stringify(body),
+      })
+      if (response.redirected) {
+        throw Object.assign(new Error("Action request was redirected; authentication may have expired"), { code: "unauthorized" })
+      }
+      if (!response.headers.get("Content-Type")?.includes("application/json")) {
+        throw Object.assign(new Error("Action endpoint did not return JSON"), { code: "invalid_response" })
+      }
+      let json
+      try {
+        json = await response.json()
+      } catch {
+        throw Object.assign(new Error("Action endpoint returned malformed JSON"), { code: "invalid_response" })
+      }
+      if (!response.ok) {
+        throw Object.assign(new Error(json?.error?.message || "action failed"), { code: json?.error?.code })
+      }
+      const result = json?.result
+      if (!result || result.action !== body.action || result.surface_id !== body.surface_id || result.version !== body.version) {
+        throw Object.assign(new Error("Action response does not match the submitted action"), { code: "invalid_response" })
+      }
+      this.dispatch("action", { surfaceId: this.surfaceId, result })
+      return result
+    } catch (error) {
+      if (error.name !== "AbortError" || this.connection) this.handleError(error)
+      throw error
+    }
+  }
+
+  // Every browser `Query()`/`Mutation()` tool call is routed to the same
+  // server endpoint; the host registry decides what is permitted.
+  toolProvider() {
+    const reserved = new Set([ "callTool", "then", "__proto__", "constructor", "prototype", "toJSON" ])
+    return this.tools ||= new Proxy(
+      {},
+      {
+        has: (_target, name) => typeof name === "string" && !reserved.has(name),
+        get: (_target, name) => {
+          if (typeof name !== "string" || reserved.has(name)) return undefined
+          return (args) => this.dispatchAction({ action: name, args: args ?? {} }).then((result) => result.value)
+        },
+      }
+    )
+  }
+
+  // Persisting form state is the host's job; emit an event and let it decide.
+  persistState(formState) {
+    this.dispatch("state", { surfaceId: this.surfaceId, state: formState })
+  }
+
+  // --- Helpers -------------------------------------------------------------
+
+  // Mirror the streaming state onto `aria-busy` so a screen reader waits for a
+  // streaming region to settle instead of announcing each delta.
+  syncBusy() {
+    this.element.setAttribute("aria-busy", this.state.streaming ? "true" : "false")
+  }
+
+  handleError(error) {
+    // Renderer#onError receives an array, including [] after successful parses.
+    if (Array.isArray(error)) {
+      if (error.length === 0) return
+      error = Object.assign(new Error(error.map((entry) => entry.message || String(entry)).join("; ")),
+        { code: "renderer_error" })
+    }
+    console.error("[openui-rails]", error)
+    this.dispatch("error", { surfaceId: this.surfaceId, message: error?.message, code: error?.code })
+  }
+
+  headers() {
+    const token = document.querySelector("meta[name='csrf-token']")?.content
+    const headers = { "Content-Type": "application/json", Accept: "application/json" }
+    if (token) headers["X-CSRF-Token"] = token
+    return headers
+  }
+
+  newIdempotencyKey() {
+    if (window.crypto?.randomUUID) return window.crypto.randomUUID()
+    return `${Date.now()}-${Math.random().toString(36).slice(2)}`
+  }
+
+  dispatch(name, detail) {
+    this.element.dispatchEvent(new CustomEvent(`openui:${name}`, { bubbles: true, detail }))
+  }
+
+  get surfaceId() { return this.element.dataset.openuiSurfaceId }
+  get messageId() { return this.element.dataset.openuiMessageId || this.surfaceId }
+  get libraryVersion() { return this.element.dataset.openuiLibraryVersion }
+  get version() { return Number(this.element.dataset.openuiVersion || 0) }
+  get streaming() { return this.element.dataset.openuiStreaming === "true" }
+  get actionsUrl() { return this.element.dataset.openuiActionsUrl }
+  get runtimeUrl() { return this.element.dataset.openuiRuntimeUrl }
+  get runtimeIntegrity() { return this.element.dataset.openuiRuntimeIntegrity }
+
+  get initialResponse() { return this.element.dataset.openuiResponse || "" }
+
+  get initialState() {
+    const raw = this.element.dataset.openuiInitialState
+    if (!raw) return undefined
+    try {
+      return JSON.parse(raw)
+    } catch {
+      return undefined
+    }
+  }
+}

data/app/javascript/openui/rails/openui_envelope_controller.js

@@ -0,0 +1,38 @@
+import { Controller } from "@hotwired/stimulus"
+
+/**
+ * Bridges a server transport into the surface controller.
+ *
+ * Turbo Streams cannot dispatch a custom event directly, so the Turbo
+ * transport appends this element carrying a JSON envelope. On connect it
+ * re-emits the envelope as `openui:envelope`, which bubbles to the surface
+ * controller listening on `document`, then removes itself. No inline script
+ * and no CSP relaxation are involved.
+ *
+ * The same event shape is what an Action Cable subscriber should dispatch.
+ */
+export default class extends Controller {
+  connect() {
+    const payload = this.element.dataset.openuiEnvelopePayload
+
+    if (payload) {
+      const detail = this.parse(payload)
+      if (detail) {
+        this.element.dispatchEvent(
+          new CustomEvent("openui:envelope", { bubbles: true, detail })
+        )
+      }
+    }
+
+    this.element.remove()
+  }
+
+  parse(payload) {
+    try {
+      return JSON.parse(payload)
+    } catch (error) {
+      console.error("[openui-rails] invalid envelope payload", error)
+      return null
+    }
+  }
+}

data/config/routes.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+OpenUI::Rails::Engine.routes.draw do
+  post "actions", to: "actions#create", as: :actions
+end

data/lib/generators/openui/install/install_generator.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/base"
+
+module OpenUI
+  # `bin/rails generate openui:install`
+  #
+  # Sets up a host app: an initializer, the `config/openui` library directory
+  # and the engine mount. It does not fetch the pinned JS runtime; that is a
+  # deliberate, reproducible step documented in the generated README and run
+  # with `bin/rails openui:runtime:fetch`.
+  class InstallGenerator < ::Rails::Generators::Base
+    # Thor derives the generator namespace from the class name with its own
+    # snake_case, which does not know the OpenUI acronym; set it explicitly so
+    # `rails generate openui:install` resolves.
+    namespace "openui:install"
+
+    source_root File.expand_path("templates", __dir__)
+
+    desc "Install openui-rails: configuration, library directory and engine mount."
+
+    def create_initializer
+      template "config/initializers/openui.rb.tt", "config/initializers/openui.rb"
+    end
+
+    def create_library_directory
+      template "config/openui/README.md", "config/openui/README.md"
+    end
+
+    def mount_engine
+      return unless routes_file?
+
+      route 'mount OpenUI::Rails::Engine => "/openui-rails"' unless already_mounted?
+    end
+
+    def show_next_steps
+      say ""
+      say "openui-rails installed.", :green
+      say ""
+      say "Next steps:"
+      say "  1. Generate the library prompt and spec with the pinned CLI:"
+      say "     npx --yes @openuidev/cli@0.6.0 generate <entry> --out config/openui/library.prompt.txt --no-telemetry"
+      say "  2. Self-host the pinned runtime:"
+      say "     bin/rails openui:runtime:fetch"
+      say "  3. Register actions and an authorizer (see config/initializers/openui.rb)."
+      say "  4. Pin/register the Stimulus controllers and include openui_stylesheet_tag in your layout."
+      say "     The default bundle requires the exact openuiChatLibrary prompt/spec. See the gem README."
+      say ""
+    end
+
+    private
+
+    def routes_file?
+      File.exist?(File.join(destination_root, "config/routes.rb"))
+    end
+
+    def already_mounted?
+      File.read(File.join(destination_root, "config/routes.rb")).include?("OpenUI::Rails::Engine")
+    end
+  end
+end

data/lib/generators/openui/install/templates/config/initializers/openui.rb.tt

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+OpenUI::Rails.configure do |config|
+  # Transport for incremental updates: :turbo, :action_cable or :none.
+  config.transport = :turbo
+
+  # The prompt and spec generated from the same, pinned library revision by the
+  # OpenUI CLI. See config/openui/README.md for the exact command.
+  config.library_spec_path = Rails.root.join("config/openui/library.spec.json")
+  config.prompt_path = Rails.root.join("config/openui/library.prompt.txt")
+
+  # :self_hosted (default) serves a vendored runtime; :external requires an
+  # explicit, exact-version runtime_url. See `bin/rails openui:runtime:fetch`.
+  config.runtime_assets = :self_hosted
+  # config.runtime_integrity = "sha384-..."
+
+  # Authorize every action/tool call. This fails closed: with no authorizer an
+  # action is denied. Return truthy to permit.
+  # config.authorize_action = ->(invocation) do
+  #   OrderPolicy.new(invocation.actor, invocation.args["orderId"]).refresh?
+  # end
+
+  # Resolve a surface id to a record scoped to the actor/tenant. Returning nil
+  # is treated as "unknown or inaccessible surface" and denies the action.
+  # config.surface_resolver = ->(surface_id, actor:, **) { actor&.surfaces&.find_by(id: surface_id) }
+
+  # Expose the current actor to the actions endpoint. Defaults to `current_user`
+  # when the controller responds to it.
+  # config.actor_resolver = ->(controller) { controller.current_user }
+end

data/lib/generators/openui/install/templates/config/openui/README.md

@@ -0,0 +1,24 @@
+# OpenUI library artifacts
+
+This directory holds the **prompt** and **spec** generated from the same,
+version-pinned component-library revision. Both must come from one revision so
+the model prompt and the browser component library cannot drift.
+
+The default browser bundle contains `openuiChatLibrary` only. For that bundle,
+save the exact outputs of `window.__OpenUI.openuiChatLibrary.prompt()` and
+`.toSpec()` as the prompt text and JSON spec. A custom library needs a matching
+host-built runtime; the CLI does not change the default browser bundle.
+
+For a custom library, use the pinned CLI (never `@latest`):
+
+```bash
+npx --yes @openuidev/cli@0.6.0 generate ./src/library.ts --out config/openui/library.prompt.txt --no-telemetry
+```
+
+The command writes `config/openui/library.prompt.txt` and
+`config/openui/library.prompt.txt.spec.json`. Rename the spec to
+`library.spec.json` (or point `library_spec_path` at the generated name) and
+commit both files. `OpenUI::Rails` fingerprints the spec; a mismatched
+fingerprint is a visible failure rather than a silent re-render.
+
+Set `DO_NOT_TRACK=1` in CI as well as `--no-telemetry`.