maquina_stream 0.1.0

data/app/assets/stylesheets/maquina_stream/themes/dark.css

@@ -0,0 +1,235 @@
+/* Generated by `rake maquina_stream:themes`. Do not edit by hand. */
+[data-theme="dark"] [data-ms-code] table td { padding: 5px; }
+[data-theme="dark"] [data-ms-code] table pre { margin: 0; }
+[data-theme="dark"] [data-ms-code], [data-theme="dark"] [data-ms-code] .w {
+  color: #c9d1d9;
+  background-color: #161b22;
+}
+[data-theme="dark"] [data-ms-code] .k, [data-theme="dark"] [data-ms-code] .kd, [data-theme="dark"] [data-ms-code] .kn, [data-theme="dark"] [data-ms-code] .kp, [data-theme="dark"] [data-ms-code] .kr, [data-theme="dark"] [data-ms-code] .kt, [data-theme="dark"] [data-ms-code] .kv {
+  color: #ff7b72;
+}
+[data-theme="dark"] [data-ms-code] .gr {
+  color: #f0f6fc;
+}
+[data-theme="dark"] [data-ms-code] .gd {
+  color: #ffdcd7;
+  background-color: #67060c;
+}
+[data-theme="dark"] [data-ms-code] .nb {
+  color: #ffa657;
+}
+[data-theme="dark"] [data-ms-code] .nc {
+  color: #ffa657;
+}
+[data-theme="dark"] [data-ms-code] .no {
+  color: #ffa657;
+}
+[data-theme="dark"] [data-ms-code] .nn {
+  color: #ffa657;
+}
+[data-theme="dark"] [data-ms-code] .sr {
+  color: #7ee787;
+}
+[data-theme="dark"] [data-ms-code] .na {
+  color: #7ee787;
+}
+[data-theme="dark"] [data-ms-code] .nt {
+  color: #7ee787;
+}
+[data-theme="dark"] [data-ms-code] .gi {
+  color: #aff5b4;
+  background-color: #033a16;
+}
+[data-theme="dark"] [data-ms-code] .ges {
+  font-weight: bold;
+  font-style: italic;
+}
+[data-theme="dark"] [data-ms-code] .kc {
+  color: #79c0ff;
+}
+[data-theme="dark"] [data-ms-code] .l, [data-theme="dark"] [data-ms-code] .ld, [data-theme="dark"] [data-ms-code] .m, [data-theme="dark"] [data-ms-code] .mb, [data-theme="dark"] [data-ms-code] .mf, [data-theme="dark"] [data-ms-code] .mh, [data-theme="dark"] [data-ms-code] .mi, [data-theme="dark"] [data-ms-code] .il, [data-theme="dark"] [data-ms-code] .mo, [data-theme="dark"] [data-ms-code] .mx {
+  color: #79c0ff;
+}
+[data-theme="dark"] [data-ms-code] .sb {
+  color: #79c0ff;
+}
+[data-theme="dark"] [data-ms-code] .bp {
+  color: #79c0ff;
+}
+[data-theme="dark"] [data-ms-code] .ne {
+  color: #79c0ff;
+}
+[data-theme="dark"] [data-ms-code] .nl {
+  color: #79c0ff;
+}
+[data-theme="dark"] [data-ms-code] .py {
+  color: #79c0ff;
+}
+[data-theme="dark"] [data-ms-code] .nv, [data-theme="dark"] [data-ms-code] .vc, [data-theme="dark"] [data-ms-code] .vg, [data-theme="dark"] [data-ms-code] .vi, [data-theme="dark"] [data-ms-code] .vm {
+  color: #79c0ff;
+}
+[data-theme="dark"] [data-ms-code] .o, [data-theme="dark"] [data-ms-code] .ow {
+  color: #79c0ff;
+}
+[data-theme="dark"] [data-ms-code] .gh {
+  color: #1f6feb;
+  font-weight: bold;
+}
+[data-theme="dark"] [data-ms-code] .gu {
+  color: #1f6feb;
+  font-weight: bold;
+}
+[data-theme="dark"] [data-ms-code] .s, [data-theme="dark"] [data-ms-code] .sa, [data-theme="dark"] [data-ms-code] .sc, [data-theme="dark"] [data-ms-code] .dl, [data-theme="dark"] [data-ms-code] .sd, [data-theme="dark"] [data-ms-code] .s2, [data-theme="dark"] [data-ms-code] .se, [data-theme="dark"] [data-ms-code] .sh, [data-theme="dark"] [data-ms-code] .sx, [data-theme="dark"] [data-ms-code] .s1, [data-theme="dark"] [data-ms-code] .ss {
+  color: #a5d6ff;
+}
+[data-theme="dark"] [data-ms-code] .nd {
+  color: #d2a8ff;
+}
+[data-theme="dark"] [data-ms-code] .nf, [data-theme="dark"] [data-ms-code] .fm {
+  color: #d2a8ff;
+}
+[data-theme="dark"] [data-ms-code] .err {
+  color: #f0f6fc;
+  background-color: #8e1519;
+}
+[data-theme="dark"] [data-ms-code] .c, [data-theme="dark"] [data-ms-code] .ch, [data-theme="dark"] [data-ms-code] .cd, [data-theme="dark"] [data-ms-code] .cm, [data-theme="dark"] [data-ms-code] .cp, [data-theme="dark"] [data-ms-code] .cpf, [data-theme="dark"] [data-ms-code] .c1, [data-theme="dark"] [data-ms-code] .cs {
+  color: #8b949e;
+}
+[data-theme="dark"] [data-ms-code] .gl {
+  color: #8b949e;
+}
+[data-theme="dark"] [data-ms-code] .gt {
+  color: #8b949e;
+}
+[data-theme="dark"] [data-ms-code] .ni {
+  color: #c9d1d9;
+}
+[data-theme="dark"] [data-ms-code] .si {
+  color: #c9d1d9;
+}
+[data-theme="dark"] [data-ms-code] .ge {
+  color: #c9d1d9;
+  font-style: italic;
+}
+[data-theme="dark"] [data-ms-code] .gs {
+  color: #c9d1d9;
+  font-weight: bold;
+}
+@media (prefers-color-scheme: dark) {
+:root:not([data-theme="light"]) [data-ms-code] table td { padding: 5px; }
+:root:not([data-theme="light"]) [data-ms-code] table pre { margin: 0; }
+:root:not([data-theme="light"]) [data-ms-code], :root:not([data-theme="light"]) [data-ms-code] .w {
+  color: #c9d1d9;
+  background-color: #161b22;
+}
+:root:not([data-theme="light"]) [data-ms-code] .k, :root:not([data-theme="light"]) [data-ms-code] .kd, :root:not([data-theme="light"]) [data-ms-code] .kn, :root:not([data-theme="light"]) [data-ms-code] .kp, :root:not([data-theme="light"]) [data-ms-code] .kr, :root:not([data-theme="light"]) [data-ms-code] .kt, :root:not([data-theme="light"]) [data-ms-code] .kv {
+  color: #ff7b72;
+}
+:root:not([data-theme="light"]) [data-ms-code] .gr {
+  color: #f0f6fc;
+}
+:root:not([data-theme="light"]) [data-ms-code] .gd {
+  color: #ffdcd7;
+  background-color: #67060c;
+}
+:root:not([data-theme="light"]) [data-ms-code] .nb {
+  color: #ffa657;
+}
+:root:not([data-theme="light"]) [data-ms-code] .nc {
+  color: #ffa657;
+}
+:root:not([data-theme="light"]) [data-ms-code] .no {
+  color: #ffa657;
+}
+:root:not([data-theme="light"]) [data-ms-code] .nn {
+  color: #ffa657;
+}
+:root:not([data-theme="light"]) [data-ms-code] .sr {
+  color: #7ee787;
+}
+:root:not([data-theme="light"]) [data-ms-code] .na {
+  color: #7ee787;
+}
+:root:not([data-theme="light"]) [data-ms-code] .nt {
+  color: #7ee787;
+}
+:root:not([data-theme="light"]) [data-ms-code] .gi {
+  color: #aff5b4;
+  background-color: #033a16;
+}
+:root:not([data-theme="light"]) [data-ms-code] .ges {
+  font-weight: bold;
+  font-style: italic;
+}
+:root:not([data-theme="light"]) [data-ms-code] .kc {
+  color: #79c0ff;
+}
+:root:not([data-theme="light"]) [data-ms-code] .l, :root:not([data-theme="light"]) [data-ms-code] .ld, :root:not([data-theme="light"]) [data-ms-code] .m, :root:not([data-theme="light"]) [data-ms-code] .mb, :root:not([data-theme="light"]) [data-ms-code] .mf, :root:not([data-theme="light"]) [data-ms-code] .mh, :root:not([data-theme="light"]) [data-ms-code] .mi, :root:not([data-theme="light"]) [data-ms-code] .il, :root:not([data-theme="light"]) [data-ms-code] .mo, :root:not([data-theme="light"]) [data-ms-code] .mx {
+  color: #79c0ff;
+}
+:root:not([data-theme="light"]) [data-ms-code] .sb {
+  color: #79c0ff;
+}
+:root:not([data-theme="light"]) [data-ms-code] .bp {
+  color: #79c0ff;
+}
+:root:not([data-theme="light"]) [data-ms-code] .ne {
+  color: #79c0ff;
+}
+:root:not([data-theme="light"]) [data-ms-code] .nl {
+  color: #79c0ff;
+}
+:root:not([data-theme="light"]) [data-ms-code] .py {
+  color: #79c0ff;
+}
+:root:not([data-theme="light"]) [data-ms-code] .nv, :root:not([data-theme="light"]) [data-ms-code] .vc, :root:not([data-theme="light"]) [data-ms-code] .vg, :root:not([data-theme="light"]) [data-ms-code] .vi, :root:not([data-theme="light"]) [data-ms-code] .vm {
+  color: #79c0ff;
+}
+:root:not([data-theme="light"]) [data-ms-code] .o, :root:not([data-theme="light"]) [data-ms-code] .ow {
+  color: #79c0ff;
+}
+:root:not([data-theme="light"]) [data-ms-code] .gh {
+  color: #1f6feb;
+  font-weight: bold;
+}
+:root:not([data-theme="light"]) [data-ms-code] .gu {
+  color: #1f6feb;
+  font-weight: bold;
+}
+:root:not([data-theme="light"]) [data-ms-code] .s, :root:not([data-theme="light"]) [data-ms-code] .sa, :root:not([data-theme="light"]) [data-ms-code] .sc, :root:not([data-theme="light"]) [data-ms-code] .dl, :root:not([data-theme="light"]) [data-ms-code] .sd, :root:not([data-theme="light"]) [data-ms-code] .s2, :root:not([data-theme="light"]) [data-ms-code] .se, :root:not([data-theme="light"]) [data-ms-code] .sh, :root:not([data-theme="light"]) [data-ms-code] .sx, :root:not([data-theme="light"]) [data-ms-code] .s1, :root:not([data-theme="light"]) [data-ms-code] .ss {
+  color: #a5d6ff;
+}
+:root:not([data-theme="light"]) [data-ms-code] .nd {
+  color: #d2a8ff;
+}
+:root:not([data-theme="light"]) [data-ms-code] .nf, :root:not([data-theme="light"]) [data-ms-code] .fm {
+  color: #d2a8ff;
+}
+:root:not([data-theme="light"]) [data-ms-code] .err {
+  color: #f0f6fc;
+  background-color: #8e1519;
+}
+:root:not([data-theme="light"]) [data-ms-code] .c, :root:not([data-theme="light"]) [data-ms-code] .ch, :root:not([data-theme="light"]) [data-ms-code] .cd, :root:not([data-theme="light"]) [data-ms-code] .cm, :root:not([data-theme="light"]) [data-ms-code] .cp, :root:not([data-theme="light"]) [data-ms-code] .cpf, :root:not([data-theme="light"]) [data-ms-code] .c1, :root:not([data-theme="light"]) [data-ms-code] .cs {
+  color: #8b949e;
+}
+:root:not([data-theme="light"]) [data-ms-code] .gl {
+  color: #8b949e;
+}
+:root:not([data-theme="light"]) [data-ms-code] .gt {
+  color: #8b949e;
+}
+:root:not([data-theme="light"]) [data-ms-code] .ni {
+  color: #c9d1d9;
+}
+:root:not([data-theme="light"]) [data-ms-code] .si {
+  color: #c9d1d9;
+}
+:root:not([data-theme="light"]) [data-ms-code] .ge {
+  color: #c9d1d9;
+  font-style: italic;
+}
+:root:not([data-theme="light"]) [data-ms-code] .gs {
+  color: #c9d1d9;
+  font-weight: bold;
+}
+}

data/app/assets/stylesheets/maquina_stream/themes/light.css

@@ -0,0 +1,117 @@
+/* Generated by `rake maquina_stream:themes`. Do not edit by hand. */
+:root:not([data-theme="dark"]) [data-ms-code] table td { padding: 5px; }
+:root:not([data-theme="dark"]) [data-ms-code] table pre { margin: 0; }
+:root:not([data-theme="dark"]) [data-ms-code], :root:not([data-theme="dark"]) [data-ms-code] .w {
+  color: #24292f;
+  background-color: #f6f8fa;
+}
+:root:not([data-theme="dark"]) [data-ms-code] .k, :root:not([data-theme="dark"]) [data-ms-code] .kd, :root:not([data-theme="dark"]) [data-ms-code] .kn, :root:not([data-theme="dark"]) [data-ms-code] .kp, :root:not([data-theme="dark"]) [data-ms-code] .kr, :root:not([data-theme="dark"]) [data-ms-code] .kt, :root:not([data-theme="dark"]) [data-ms-code] .kv {
+  color: #cf222e;
+}
+:root:not([data-theme="dark"]) [data-ms-code] .gr {
+  color: #f6f8fa;
+}
+:root:not([data-theme="dark"]) [data-ms-code] .gd {
+  color: #82071e;
+  background-color: #ffebe9;
+}
+:root:not([data-theme="dark"]) [data-ms-code] .nb {
+  color: #953800;
+}
+:root:not([data-theme="dark"]) [data-ms-code] .nc {
+  color: #953800;
+}
+:root:not([data-theme="dark"]) [data-ms-code] .no {
+  color: #953800;
+}
+:root:not([data-theme="dark"]) [data-ms-code] .nn {
+  color: #953800;
+}
+:root:not([data-theme="dark"]) [data-ms-code] .sr {
+  color: #116329;
+}
+:root:not([data-theme="dark"]) [data-ms-code] .na {
+  color: #116329;
+}
+:root:not([data-theme="dark"]) [data-ms-code] .nt {
+  color: #116329;
+}
+:root:not([data-theme="dark"]) [data-ms-code] .gi {
+  color: #116329;
+  background-color: #dafbe1;
+}
+:root:not([data-theme="dark"]) [data-ms-code] .ges {
+  font-weight: bold;
+  font-style: italic;
+}
+:root:not([data-theme="dark"]) [data-ms-code] .kc {
+  color: #0550ae;
+}
+:root:not([data-theme="dark"]) [data-ms-code] .l, :root:not([data-theme="dark"]) [data-ms-code] .ld, :root:not([data-theme="dark"]) [data-ms-code] .m, :root:not([data-theme="dark"]) [data-ms-code] .mb, :root:not([data-theme="dark"]) [data-ms-code] .mf, :root:not([data-theme="dark"]) [data-ms-code] .mh, :root:not([data-theme="dark"]) [data-ms-code] .mi, :root:not([data-theme="dark"]) [data-ms-code] .il, :root:not([data-theme="dark"]) [data-ms-code] .mo, :root:not([data-theme="dark"]) [data-ms-code] .mx {
+  color: #0550ae;
+}
+:root:not([data-theme="dark"]) [data-ms-code] .sb {
+  color: #0550ae;
+}
+:root:not([data-theme="dark"]) [data-ms-code] .bp {
+  color: #0550ae;
+}
+:root:not([data-theme="dark"]) [data-ms-code] .ne {
+  color: #0550ae;
+}
+:root:not([data-theme="dark"]) [data-ms-code] .nl {
+  color: #0550ae;
+}
+:root:not([data-theme="dark"]) [data-ms-code] .py {
+  color: #0550ae;
+}
+:root:not([data-theme="dark"]) [data-ms-code] .nv, :root:not([data-theme="dark"]) [data-ms-code] .vc, :root:not([data-theme="dark"]) [data-ms-code] .vg, :root:not([data-theme="dark"]) [data-ms-code] .vi, :root:not([data-theme="dark"]) [data-ms-code] .vm {
+  color: #0550ae;
+}
+:root:not([data-theme="dark"]) [data-ms-code] .o, :root:not([data-theme="dark"]) [data-ms-code] .ow {
+  color: #0550ae;
+}
+:root:not([data-theme="dark"]) [data-ms-code] .gh {
+  color: #0550ae;
+  font-weight: bold;
+}
+:root:not([data-theme="dark"]) [data-ms-code] .gu {
+  color: #0550ae;
+  font-weight: bold;
+}
+:root:not([data-theme="dark"]) [data-ms-code] .s, :root:not([data-theme="dark"]) [data-ms-code] .sa, :root:not([data-theme="dark"]) [data-ms-code] .sc, :root:not([data-theme="dark"]) [data-ms-code] .dl, :root:not([data-theme="dark"]) [data-ms-code] .sd, :root:not([data-theme="dark"]) [data-ms-code] .s2, :root:not([data-theme="dark"]) [data-ms-code] .se, :root:not([data-theme="dark"]) [data-ms-code] .sh, :root:not([data-theme="dark"]) [data-ms-code] .sx, :root:not([data-theme="dark"]) [data-ms-code] .s1, :root:not([data-theme="dark"]) [data-ms-code] .ss {
+  color: #0a3069;
+}
+:root:not([data-theme="dark"]) [data-ms-code] .nd {
+  color: #8250df;
+}
+:root:not([data-theme="dark"]) [data-ms-code] .nf, :root:not([data-theme="dark"]) [data-ms-code] .fm {
+  color: #8250df;
+}
+:root:not([data-theme="dark"]) [data-ms-code] .err {
+  color: #f6f8fa;
+  background-color: #82071e;
+}
+:root:not([data-theme="dark"]) [data-ms-code] .c, :root:not([data-theme="dark"]) [data-ms-code] .ch, :root:not([data-theme="dark"]) [data-ms-code] .cd, :root:not([data-theme="dark"]) [data-ms-code] .cm, :root:not([data-theme="dark"]) [data-ms-code] .cp, :root:not([data-theme="dark"]) [data-ms-code] .cpf, :root:not([data-theme="dark"]) [data-ms-code] .c1, :root:not([data-theme="dark"]) [data-ms-code] .cs {
+  color: #6e7781;
+}
+:root:not([data-theme="dark"]) [data-ms-code] .gl {
+  color: #6e7781;
+}
+:root:not([data-theme="dark"]) [data-ms-code] .gt {
+  color: #6e7781;
+}
+:root:not([data-theme="dark"]) [data-ms-code] .ni {
+  color: #24292f;
+}
+:root:not([data-theme="dark"]) [data-ms-code] .si {
+  color: #24292f;
+}
+:root:not([data-theme="dark"]) [data-ms-code] .ge {
+  color: #24292f;
+  font-style: italic;
+}
+:root:not([data-theme="dark"]) [data-ms-code] .gs {
+  color: #24292f;
+  font-weight: bold;
+}

data/app/controllers/maquina_stream/application_controller.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module MaquinaStream
+  # Every engine request resolves the record through the host's `find_stream`
+  # callable and is authorized by the host's `authorize` callable. With neither
+  # configured the engine refuses: it never assumes it may serve a message.
+  class ApplicationController < ActionController::Base
+    before_action :set_stream_record
+    before_action :authorize_stream_record
+
+    private
+      def set_stream_record
+        @record = MaquinaStream.config.find_stream!(params[:sid])
+        head :not_found unless @record
+      end
+
+      def authorize_stream_record
+        head :forbidden unless MaquinaStream.config.authorized?(@record, request)
+      end
+  end
+end

data/app/controllers/maquina_stream/blocks_controller.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module MaquinaStream
+  # The blocks the client asked for, as morphing Turbo Stream actions.
+  #
+  # Only ids the message actually has are served, and only the ones requested:
+  # `ids` comes from the client, so it is filtered against the document rather
+  # than trusted. A request for every block is a legitimate cold repair, so the
+  # count is not capped — but each id is matched, not interpolated.
+  class BlocksController < ApplicationController
+    # `GET /maquina_stream/:sid/blocks?ids[]=…` → a Turbo Stream carrying one
+    # morphing replace per requested block.
+    def index
+      requested = Array(params[:ids]).map(&:to_s).to_set
+      blocks = document.blocks.select { |block| requested.include?(block.id) }
+
+      # Rendered explicitly rather than via `render turbo_stream:`, which does
+      # not count as a render when the list is empty and then looks for a
+      # template that does not exist. Asking to repair nothing is a normal
+      # answer to a manifest that already agreed.
+      render plain: blocks.map { |block| morph(block) }.join, content_type: Mime[:turbo_stream]
+    end
+
+    private
+      def document
+        Document.new(
+          @record.maquina_stream_buffer,
+          config: MaquinaStream.config,
+          sid: @record.maquina_stream_id,
+          mode: @record.maquina_stream_open? ? :streaming : :static
+        )
+      end
+
+      # `method: :morph` is what makes the repair silent: idiomorph patches the
+      # existing node in place, so client state inside it survives and no
+      # animation is triggered by a replacement that never happens.
+      def morph(block)
+        turbo_stream.replace(block.id, block.html, method: :morph)
+      end
+  end
+end

data/app/controllers/maquina_stream/manifests_controller.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module MaquinaStream
+  # The snapshot the repair path diffs against: sequence plus one digest per
+  # sealed block. A few hundred bytes whatever the message weighs.
+  class ManifestsController < ApplicationController
+    # `GET /maquina_stream/:sid/manifest` →
+    # `{ seq:, cutoff:, rollup:, blocks: [[id, digest], …] }`.
+    def show
+      # `full=1` is the cold path: a client whose rollup disagrees with ours
+      # cannot repair from the window alone and asks for everything.
+      render json: Manifest.for(@record, full: params[:full].present?).to_h
+    end
+  end
+end

data/app/helpers/maquina_stream/components_helper.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module MaquinaStream
+  # The view side of the component seam. Engine views and the render pipeline
+  # call `component`; nothing renders a vendored partial by path.
+  module ComponentsHelper
+    # Renders one component through the seam.
+    #
+    # ```erb
+    # <%= component(:code_block, lang: "ruby", source: raw, css_classes: "…") %>
+    # ```
+    #
+    # `name` resolves to a `maquina_components` partial when that gem defines
+    # it, and to the vendored fallback otherwise. Locals go through
+    # MaquinaStream::Components::Contract on the way in.
+    #
+    # The partial is generic; the engine's DOM contract and labels are added
+    # here, by MaquinaStream::Components::Contract. That is what lets a vendored
+    # partial leave for maquina_components without carrying `data-ms-*` or the
+    # `maquina_stream.*` locale namespace with it.
+    def component(name, **locals, &block)
+      config = maquina_stream_config
+      partial = MaquinaStream::Components.partial_for(name, config: config)
+      locals = MaquinaStream::Components::Contract.apply(name, locals, config: config)
+
+      if block
+        render(layout: partial, locals: locals, &block)
+      else
+        render(partial: partial, locals: locals)
+      end
+    end
+
+    # Merges caller-supplied data attributes with the component's own.
+    #
+    # The component wins its identity keys — `component`, `variant`, `size` and
+    # anything ending in `_part` — because those are what the CSS selects on.
+    # `controller` and `action` concatenate, component tokens first. Every other
+    # key belongs to the caller.
+    def component_data(own, provided = nil)
+      own = own.compact
+      provided = (provided || {}).transform_keys { |key| key.to_s.tr("-", "_").to_sym }
+
+      merged = provided.merge(own) do |key, caller_value, own_value|
+        if %i[controller action].include?(key)
+          [own_value, caller_value].compact.join(" ").strip
+        else
+          own_value
+        end
+      end
+
+      merged.reject { |_, value| value.nil? }
+    end
+
+    # Same-shaped merge for the non-data attributes a caller passes through
+    # `**html_options`, with `css_classes` folded into `class`.
+    def component_html_options(html_options, own_data: {}, css_classes: nil, base_classes: nil)
+      options = html_options.dup
+      provided_data = options.delete(:data) || options.delete("data")
+
+      options[:data] = component_data(own_data, provided_data)
+      classes = component_classes(base_classes, css_classes)
+      options[:class] = classes if classes.present?
+      options
+    end
+
+    def component_classes(*tokens)
+      tokens.flatten.compact.map(&:to_s).reject(&:empty?).join(" ").presence
+    end
+
+    # Stylesheet paths for the components currently rendering from our own
+    # app/views. Empty once maquina_components serves all of them.
+    def component_stylesheets
+      MaquinaStream::Components.stylesheets(config: maquina_stream_config)
+    end
+
+    def maquina_stream_config
+      MaquinaStream.config
+    end
+  end
+end

data/app/javascript/maquina_stream/controllers/application_controller.js

@@ -0,0 +1,169 @@
+import { Controller } from "@hotwired/stimulus"
+
+// Base class for every `ms-` controller.
+//
+// Two things live here because every controller needs them and neither belongs
+// in a single one:
+//
+//   1. `streaming` — the one signal that makes controls inert while a message
+//      is still being written. See docs/javascript.md.
+//   2. `copyText` / `downloadText` — clipboard and download plumbing, including
+//      the insecure-context clipboard fallback.
+//
+// Nothing here ever assigns a DOM-derived or payload-derived string as HTML.
+// Per docs/security.md the sanitizer cannot tell our attributes from injected
+// ones, so every value a controller reads is untrusted input.
+export default class ApplicationController extends Controller {
+  // ---------------------------------------------------------------- streaming
+
+  // The message element. The DOM contract fixes `#ms-msg-<sid>`; hosts that
+  // wrap rendered output themselves can mark it with `data-ms-message`.
+  get messageElement() {
+    return this.element.closest("[data-ms-message]") ||
+      this.element.closest("[data-ms-streaming]") ||
+      this.element.closest("[id^='ms-msg-']")
+  }
+
+  // A message is open exactly while its element carries `data-ms-streaming`.
+  //
+  // This used to read `data-ms-caret` off the tail block. Blocks no longer
+  // carry chrome at all — it made a block's bytes disagree with its digest, so
+  // repair could not correct it and two tabs could disagree — and the caret
+  // moved to the message element, derived in CSS. Reading the caret here
+  // therefore reported "not streaming" for every message, and controls were
+  // never inert. See docs/javascript.md.
+  //
+  // Still one source of truth, and still the server's: the host stamps the
+  // attribute from `maquina_stream_open?`.
+  get streaming() {
+    const message = this.messageElement
+    if (!message) return false
+    return message.hasAttribute("data-ms-streaming")
+  }
+
+  // Controls opt in by carrying `data-ms-control`. They are disabled while the
+  // message streams so the UI never offers half a code block to copy.
+  startStreamGuard() {
+    this.syncStreamGuard()
+    if (!this.messageElement) return
+
+    this.streamGuardObserver = new MutationObserver(() => this.syncStreamGuard())
+    this.streamGuardObserver.observe(this.messageElement, {
+      subtree: true,
+      childList: true,
+      attributes: true,
+      // The seal removes data-ms-streaming from the message element, which is
+      // what re-enables the controls.
+      attributeFilter: ["data-ms-streaming"]
+    })
+  }
+
+  stopStreamGuard() {
+    this.streamGuardObserver?.disconnect()
+    this.streamGuardObserver = null
+  }
+
+  syncStreamGuard() {
+    const streaming = this.streaming
+    this.element.querySelectorAll("[data-ms-control]").forEach((control) => {
+      control.disabled = streaming
+      control.setAttribute("aria-disabled", String(streaming))
+    })
+  }
+
+  // Every public action that touches the clipboard, the filesystem or the
+  // layout starts with this. The observer above is a convenience; this is the
+  // guarantee.
+  refuseWhileStreaming(event) {
+    if (!this.streaming) return false
+    event?.preventDefault()
+    this.notify("refused", { reason: "streaming" })
+    return true
+  }
+
+  // ---------------------------------------------------------------- clipboard
+
+  // `navigator.clipboard` is undefined in an insecure context — plain HTTP on
+  // anything but localhost — which is exactly where this engine gets demoed.
+  // The fallback is a throwaway textarea plus `document.execCommand("copy")`.
+  // When both fail, a `ms:copy-failed` event is dispatched carrying the text so
+  // the host can offer it another way; nothing is silently lost.
+  async copyText(text) {
+    if (window.isSecureContext && navigator.clipboard) {
+      try {
+        await navigator.clipboard.writeText(text)
+        this.notify("copied", { length: text.length })
+        return true
+      } catch {
+        // Permission denied, or the document is not focused. Fall through.
+      }
+    }
+
+    if (this.copyWithSelection(text)) {
+      this.notify("copied", { length: text.length, fallback: true })
+      return true
+    }
+
+    this.notify("copy-failed", { text })
+    return false
+  }
+
+  copyWithSelection(text) {
+    const carrier = document.createElement("textarea")
+    carrier.value = text
+    carrier.setAttribute("readonly", "")
+    carrier.setAttribute("aria-hidden", "true")
+    carrier.style.position = "fixed"
+    carrier.style.top = "0"
+    carrier.style.left = "-9999px"
+    document.body.appendChild(carrier)
+
+    const previous = document.activeElement
+    let copied = false
+    try {
+      carrier.select()
+      carrier.setSelectionRange(0, carrier.value.length)
+      copied = document.execCommand("copy")
+    } catch {
+      copied = false
+    } finally {
+      carrier.remove()
+      if (previous instanceof HTMLElement) previous.focus()
+    }
+    return copied
+  }
+
+  // ---------------------------------------------------------------- downloads
+
+  downloadText(text, filename, mime = "text/plain") {
+    const blob = new Blob([text], { type: `${mime};charset=utf-8` })
+    const url = URL.createObjectURL(blob)
+    const link = document.createElement("a")
+    link.href = url
+    link.download = this.safeFilename(filename)
+    link.rel = "noopener"
+    document.body.appendChild(link)
+    link.click()
+    link.remove()
+    // Revoking synchronously races the download in Safari.
+    setTimeout(() => URL.revokeObjectURL(url), 1000)
+    this.notify("downloaded", { filename: link.download })
+  }
+
+  // A filename is built from a DOM-derived language string. Path separators,
+  // control characters and leading dots are stripped rather than trusted.
+  safeFilename(name) {
+    const cleaned = String(name)
+      .replace(/[\u0000-\u001f\u007f]/g, "")
+      .replace(/[\\/:*?"<>|]/g, "-")
+      .replace(/^\.+/, "")
+      .trim()
+    return cleaned.length ? cleaned.slice(0, 120) : "download.txt"
+  }
+
+  // ------------------------------------------------------------------- events
+
+  notify(name, detail = {}) {
+    this.dispatch(name, { detail, prefix: "ms" })
+  }
+}