maquina_stream 0.1.0

data/docs/streaming.md

@@ -0,0 +1,308 @@
+# Streaming
+
+What you implement, what the engine does with it, and where the line between
+the two is.
+
+## What the engine owns, and what you own
+
+The engine renders markdown to HTML, splits it into blocks, decides which blocks
+may freeze, works out what changed since the last frame, and emits Turbo Stream
+actions. It serves the repair routes.
+
+You own three things, and none of them has a default the engine could guess:
+
+| Yours | Where it goes |
+|---|---|
+| Persisting the buffer, the sequence and the status | `MaquinaStream::Streamable` |
+| Looking a record up by its stream id | `config.find_stream` |
+| Deciding whether a request may see it | `config.authorize` |
+
+The engine also never:
+
+- guesses a broadcast target — `stream_for:` is yours;
+- writes host columns other than through `#maquina_stream_append` and
+  `#maquina_stream_seal!`;
+- creates the `#ms-msg-<sid>` element it appends blocks into;
+- sends markdown to the browser.
+
+## The Streamable contract
+
+```ruby
+class Message < ApplicationRecord
+  include MaquinaStream::Streamable
+
+  maquina_stream buffer: :content,
+    stream_for: ->(m) { [:conversation, m.conversation_id, :messages] }
+end
+```
+
+The macro generates each method below when its backing column exists:
+
+| Method | Returns | Column it reads |
+|---|---|---|
+| `#maquina_stream_id` | `String`, stable and unique per message | none — it is `to_param` |
+| `#maquina_stream_buffer` | `String`, the raw markdown so far | the one named by `buffer:` |
+| `#maquina_stream_append(text)` | the whole buffer, appended and persisted | the one named by `buffer:` |
+| `#maquina_stream_sequence` | `Integer`, monotonic, one per frame that went out | `stream_sequence` |
+| `#maquina_stream_advance` | `Integer`, the next sequence number, incremented atomically | `stream_sequence` |
+| `#maquina_stream_open?` | `Boolean` | `stream_status` |
+| `#maquina_stream_status` | the end state as a Symbol, `nil` while open | `stream_status` |
+| `#maquina_stream_seal!(status: :complete)` | the status Symbol it sealed with | `stream_status` |
+| `#maquina_stream_target` | the Turbo broadcast target | none — it calls `stream_for:` |
+
+`stream_status` holds `open` while the stream is being written; every other
+value is a seal. The four seal statuses are `:complete`, `:cancelled`,
+`:errored` and `:timed_out`. A stream that timed out is not one that errored:
+nothing went wrong, the model simply stopped answering, and the partial text is
+still worth keeping and replaying.
+
+### When your columns are named differently
+
+The macro includes a module, so anything you define in the class body wins:
+
+```ruby
+class Message < ApplicationRecord
+  include MaquinaStream::Streamable
+  maquina_stream buffer: :body, stream_for: ->(m) { [m.chat, :messages] }
+
+  def maquina_stream_sequence = frame_number
+  def maquina_stream_open? = finished_at.nil?
+  def maquina_stream_seal!(status: :complete) = update!(finished_at: Time.current, outcome: status)
+end
+```
+
+A model that cannot use the macro at all implements the nine methods itself and
+never includes the concern.
+
+### When the contract is unmet
+
+Calling a method whose column is missing raises `MaquinaStream::ContractError`,
+naming the method, the column and the class:
+
+```
+Note does not satisfy MaquinaStream::Streamable: #maquina_stream_sequence
+needs a `stream_sequence` column, and Note has none. Add the column,
+or define #maquina_stream_sequence on Note yourself.
+```
+
+`Message.maquina_stream_contract_gaps` answers the same question without calling
+anything, and is worth one assertion in your own suite:
+
+```ruby
+assert_empty Message.maquina_stream_contract_gaps   # => []
+```
+
+### The broadcast target
+
+`stream_for:` receives the record and returns whatever `Turbo::StreamsChannel`
+accepts as a stream name — a record, an array, a string:
+
+```ruby
+maquina_stream stream_for: ->(m) { [:conversation, m.conversation_id, :messages] }
+```
+
+The page subscribes to the same thing:
+
+```erb
+<%= turbo_stream_from :conversation, @conversation.id, :messages %>
+```
+
+The stream name is yours, which means who may subscribe is yours too. Sign or
+scope it exactly as you would any other Turbo stream. If `stream_for:` is
+missing or not callable, `#maquina_stream_target` raises rather than guessing.
+
+## The broadcaster
+
+```ruby
+broadcaster = MaquinaStream::Broadcaster.new(message)
+model.stream { |token| broadcaster.append(token) }
+broadcaster.seal!
+```
+
+`#append(text)` appends to your column — the host owns persistence, so it writes
+first and only then has something to broadcast — and emits a frame if the frame
+budget has elapsed. It returns the `Frame` that went out, or `nil` when this
+append was coalesced into the next one.
+
+`#broadcast` emits without appending, for a buffer that moved by some other
+route. `#seal!(status:)` seals the record and emits the final frame.
+
+**One broadcaster per stream, held for the life of that stream.** What the
+browser already has lives in the instance, so a fresh broadcaster mid-stream
+re-sends every block. It is not thread-safe; drive one stream from one place.
+
+### What a frame carries
+
+A frame appends the blocks the browser has never seen and patches the open tail,
+and nothing else. A block that has not changed is never re-sent, which is the
+difference between bandwidth tracking drift and bandwidth tracking message
+length.
+
+```ruby
+b = MaquinaStream::Broadcaster.new(message)
+b.append("# Informe\n\n")
+b.append("Todo bien.\n\n")
+b.append("Segunda parte.\n")
+b.seal!
+```
+
+```
+seq=1 final=false appends=["ms-1-b0"] patch=[]
+seq=2 final=false appends=["ms-1-b1"] patch=[]
+seq=3 final=false appends=["ms-1-b2"] patch=[]
+seq=4 final=true  appends=[]          patch=[]
+```
+
+Over the wire, appends go out as `broadcast_append_to` against
+`#ms-msg-<sid>`; patches as `broadcast_replace_to` with `method: "morph"`, so
+idiomorph patches the node in place instead of recreating it. Every stream
+action carries `data-ms-seq` and `data-ms-frame`, and the final one is marked
+`final`.
+
+Block ids are index-derived (`ms-<sid>-b<n>`), never content-derived, because
+idiomorph keys on `id` and a content-derived id makes morph delete and recreate.
+
+### Coalescing
+
+Frames inside `frame_budget_ms` accumulate instead of going out one per token,
+and the coalescing happens *before* the render rather than after it: building a
+frame means rendering the whole buffer, so doing that per token and throwing the
+result away is how a stream becomes quadratic in message length.
+
+Skipping a frame costs nothing. The next one is computed against what the
+browser actually has, so it carries the accumulated difference. Choosing the
+budget is in [configuration.md](configuration.md).
+
+### Deltas are an optimization
+
+Only the open tail is patched. A block that changes after it has stopped being
+the tail — a heading that completes as the paragraph below it begins — is left
+for the repair path, which fixes it for free because that is a *content* change
+and content is exactly what a manifest digest covers. See [repair.md](repair.md).
+
+## Sealing
+
+**Always seal, including when the stream failed.** The client has no other way
+to learn the stream is over, and the final frame is never coalesced and never
+skipped: it is what makes every intra-stream drift cosmetic and self-correcting.
+
+```ruby
+def stream_from(chat, prompt, broadcaster: MaquinaStream::Broadcaster.new(self))
+  chat.ask(prompt) { |chunk| broadcaster.append(chunk.content.to_s) }
+  broadcaster.seal!
+rescue
+  broadcaster.seal!(status: :errored)
+  raise
+end
+```
+
+A run that raises somewhere else — a timeout, a refusal, an endpoint that went
+away — can leave records still open, and an open record is a client waiting for
+a frame that is never coming. Only you know the run ended, so only you can send
+that frame:
+
+```ruby
+def self.seal_abandoned!(conversation_id:)
+  where(conversation_id: conversation_id, stream_status: "open").each do |record|
+    MaquinaStream::Broadcaster.new(record).seal!(status: :errored)
+    record.broadcast_shell
+  end
+end
+```
+
+Sealing through `Broadcaster#seal!` emits the final frame. Calling
+`record.maquina_stream_seal!` directly only records the status — use that when
+you mean to close a stream silently.
+
+`Message#broadcast_shell` in the dummy app shows the other half: re-broadcasting
+the message wrapper as a morph once it seals, which is what takes
+`data-ms-streaming` off, stops the reveal and re-enables the controls.
+
+## Streaming an agent run
+
+An agent run is a loop — think, call a tool, read the result, continue. **A tool
+call is its own `Streamable` record**, not a block inside the assistant's
+message.
+
+```ruby
+thinking = Message.create!(conversation_id: id, role: "assistant")
+tool     = Message.create!(conversation_id: id, role: "tool", tool_name: "read_file")
+```
+
+- Each step seals independently, with its own status. A tool call that errors
+  does not mark the reasoning before it as errored.
+- Each step has its own sequence and its own manifest, so a lost frame in one
+  step never drags another into a repair.
+- Steps of one conversation **share a cable stream** — that is what `stream_for:`
+  is for. Their frames never collide, because block ids are namespaced by
+  message id.
+- Two streams open at once is what a parallel tool call *is*, and there is no
+  other way to represent it.
+- A late tool result is simply its own stream, still open, sealing when it
+  finishes. Held inside one buffer it would instead rewrite blocks in the middle
+  of a message whose tail has already moved on — which is exactly the case
+  `seal_lag` cannot cover, because the lag protects the last few blocks, not one
+  twenty back.
+
+One caveat: a markdown link reference cannot cross records. If step one writes
+`[docs][ref]` and step three defines `[ref]:`, the link never resolves, because
+each record is rendered on its own. If a run's steps genuinely share link
+references, keep them in one record.
+
+`Message.stream_agent_run` in `test/dummy/app/models/message.rb` is a worked
+example against a real [Nexo](https://maquina.app/documentation/nexo/) agent,
+and `/harness/agent` runs it. Nexo reports tool activity through the block
+`Agent#prompt` takes, so each `:tool_call` opens a record and each
+`:tool_result` seals one. Nothing in the engine depends on it — any client
+that hands you text as it arrives works the same way.
+
+## History, and rendering a sealed message
+
+A sealed message is immutable, so render it through the cache:
+
+```erb
+<%= MaquinaStream.render(message) %>
+```
+
+```html
+<h1 id="ms-1-b0" data-ms-element="h1" data-ms-block data-ms-block-digest="bebc578f97924e6b">Informe…</h1>
+<p id="ms-1-b1" data-ms-element="p" data-ms-block data-ms-block-digest="1bc2ef335d92b2a5">Todo bien.</p>
+<p id="ms-1-b2" data-ms-element="p" data-ms-block data-ms-block-digest="453593ffc6cfefe9">Segunda parte.</p>
+```
+
+Cached by buffer digest once sealed, rendered live while open, and a new key if
+you edit the message. Re-rendering fifty finished messages on every page load is
+work nobody asked for.
+
+Pagination is yours — which messages, in what order. `/history` in the dummy app
+shows one pattern: a lazy Turbo Frame at the top of each page loads the page
+above it on scroll, so history grows upward without a pagination bar.
+
+Live, reload, replay and export produce the same document byte for byte. There
+is no separate "streaming mode" output to reconcile against a "static" one.
+
+## Export
+
+```ruby
+MaquinaStream::Export.markdown(message)
+```
+
+The buffer already *is* markdown, so export is mostly a question of the parts
+that are not clean. A cancelled stream ends mid-token, so the buffer is repaired
+first with the same preprocessor the renderer uses — an export matches what was
+on screen:
+
+```ruby
+message.content              # => "Un **inform"
+MaquinaStream::Export.markdown(message)
+# => "Un **inform**\n\n> _Respuesta cancelada antes de terminar._\n"
+```
+
+Anything that did not finish gets a status footer, because a cancelled message
+that exports as though it were complete is a lie in a file somebody keeps. Pass
+`annotate: false` to suppress it — for a caller re-ingesting the text that will
+carry the status some other way.
+
+Deferred content exports as its source: a diagram exports as its `mermaid`
+fence, verbatim, because that is what the model wrote and what another tool can
+read.

data/lib/generators/maquina_stream/install/USAGE

@@ -0,0 +1,26 @@
+Description:
+    Wires maquina_stream into a host application: the initializer, the engine
+    mount, the importmap pins, the Stimulus registration and the stylesheets.
+
+    It never overwrites a file. Anything already in place is reported and left
+    alone, so re-running is safe.
+
+    Two seams are deliberately left stubbed — `find_stream` and `authorize`.
+    The engine cannot guess a host's authorization, and a guessed one is how an
+    engine leaks other people's messages. Until `authorize` is written, every
+    repair request is refused.
+
+Example:
+    bin/rails generate maquina_stream:install
+
+    Creates or reports:
+        config/initializers/maquina_stream.rb
+        config/routes.rb                          mount MaquinaStream::Engine
+        config/importmap.rb                       @hotwired/turbo-rails pin
+        app/javascript/controllers/index.js       registerMaquinaStreamControllers
+        app/views/layouts/application.html.erb    the three stylesheet links
+
+    bin/rails generate maquina_stream:install --deferred-renderers
+
+    Also pins mermaid and katex with `preload: false`, for the client-deferred
+    diagram and math renderers.

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

@@ -0,0 +1,199 @@
+# frozen_string_literal: true
+
+require "rails/generators/base"
+
+module MaquinaStream
+  module Generators
+    # Wires the engine into a host: the initializer, the mount, the importmap
+    # pins, the Stimulus registration and the stylesheets.
+    #
+    # ```sh
+    # bin/rails generate maquina_stream:install
+    # ```
+    #
+    # Every step is idempotent and none of them overwrites a host file. A step
+    # whose ingredient is missing — no importmap, no Stimulus entrypoint, no
+    # layout — says what to do by hand instead of failing or silently doing
+    # nothing, because a generator that no-ops quietly is worse than one that
+    # is not there.
+    #
+    # Two things it exists to prevent, both learned the hard way:
+    #
+    # - **Turbo must be pinned by the host.** Repair applies Turbo Stream
+    #   morphs; with `window.Turbo` undefined every repair fails inside a catch
+    #   and nothing in the browser says so.
+    # - **A deferred-renderer pin needs `preload: false`.** importmap-rails
+    #   preloads by default, which fetches the library on every page and
+    #   defeats the lazy import it exists to avoid.
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Wires maquina_stream into this application: initializer, mount, importmap, Stimulus, stylesheets."
+
+      class_option :deferred_renderers, type: :boolean, default: false,
+        desc: "Also pin mermaid and katex (preload: false) for the diagram and math renderers"
+
+      INITIALIZER = "config/initializers/maquina_stream.rb"
+      ROUTES = "config/routes.rb"
+      IMPORTMAP = "config/importmap.rb"
+      LAYOUT = "app/views/layouts/application.html.erb"
+
+      # Where `registerMaquinaStreamControllers(application)` can go, best
+      # first. Both have an `application` in scope in a stock importmap app.
+      ENTRYPOINTS = %w[
+        app/javascript/controllers/index.js
+        app/javascript/application.js
+      ].freeze
+
+      MOUNT = 'mount MaquinaStream::Engine => "/maquina_stream"'
+
+      TURBO_PIN = <<~RUBY
+        # Required by maquina_stream: repair applies Turbo Stream morphs, and with
+        # `window.Turbo` undefined every repair fails silently inside a catch.
+        pin "@hotwired/turbo-rails", to: "turbo.min.js"
+      RUBY
+
+      DEFERRED_PINS = <<~RUBY
+        # Libraries the client-deferred renderers import lazily. `preload: false` is
+        # load-bearing: importmap-rails preloads by default, which would emit a
+        # <link rel="modulepreload"> and fetch both on every page — exactly the cost
+        # the lazy import inside `ms-deferred#library()` exists to avoid.
+        pin "mermaid", to: "https://cdn.jsdelivr.net/npm/mermaid@11.4.1/+esm", preload: false
+        pin "katex", to: "https://cdn.jsdelivr.net/npm/katex@0.16.11/dist/katex.mjs", preload: false
+      RUBY
+
+      REGISTRATION = <<~JS
+        // maquina_stream registers its own Stimulus identifiers rather than relying
+        // on an eager-load glob: those identifiers are part of the DOM contract.
+        import { registerMaquinaStreamControllers } from "maquina_stream"
+        registerMaquinaStreamControllers(application)
+      JS
+
+      STYLESHEETS = <<~ERB
+        <%= stylesheet_link_tag "maquina_stream/reveal" %>
+        <%= stylesheet_link_tag "maquina_stream/themes/light" %>
+        <%= stylesheet_link_tag "maquina_stream/themes/dark" %>
+      ERB
+
+      def create_initializer
+        if exists?(INITIALIZER)
+          skip INITIALIZER, "already exists — left untouched"
+        else
+          template "initializer.rb.tt", INITIALIZER
+        end
+      end
+
+      def mount_engine
+        return by_hand(ROUTES, MOUNT) unless exists?(ROUTES)
+        return skip(ROUTES, "engine already mounted") if read(ROUTES).include?("MaquinaStream::Engine")
+
+        route MOUNT
+      end
+
+      def pin_turbo
+        return by_hand(IMPORTMAP, TURBO_PIN, importmap_absent_note) unless exists?(IMPORTMAP)
+        return skip(IMPORTMAP, "@hotwired/turbo-rails already pinned") if read(IMPORTMAP).include?("@hotwired/turbo-rails")
+        return turbo_missing unless turbo_available?
+
+        append_to_file IMPORTMAP, "\n#{TURBO_PIN}"
+      end
+
+      def pin_deferred_renderers
+        return unless options[:deferred_renderers]
+        return by_hand(IMPORTMAP, DEFERRED_PINS) unless exists?(IMPORTMAP)
+        return skip(IMPORTMAP, "mermaid and katex already pinned") if read(IMPORTMAP).include?('pin "mermaid"')
+
+        append_to_file IMPORTMAP, "\n#{DEFERRED_PINS}"
+      end
+
+      def register_controllers
+        entrypoint = ENTRYPOINTS.find { |path| exists?(path) && read(path).match?(/\bapplication\b/) }
+        return by_hand(ENTRYPOINTS.first, REGISTRATION, entrypoint_absent_note) if entrypoint.nil?
+        return skip(entrypoint, "controllers already registered") if read(entrypoint).include?("registerMaquinaStreamControllers")
+
+        append_to_file entrypoint, "\n#{REGISTRATION}"
+      end
+
+      def link_stylesheets
+        return by_hand(LAYOUT, STYLESHEETS) unless exists?(LAYOUT)
+        return skip(LAYOUT, "stylesheets already linked") if read(LAYOUT).include?("maquina_stream/reveal")
+
+        inject_into_file LAYOUT, STYLESHEETS.gsub(/^/, "    "), before: %r{^\s*</head>}
+      end
+
+      def report_the_two_seams
+        say ""
+        say "maquina_stream is wired. Two things are still yours:", :green
+        say ""
+        say "  1. #{INITIALIZER} — `authorize` is a stub that denies everything."
+        say "     Until you replace it every repair request is refused, which is safe"
+        say "     and also broken: the browser can never repair a message."
+        say ""
+        say "  2. bin/rails generate maquina_stream:streamable Message"
+        say "     — the migration and the model macro, and it fills in `find_stream`."
+        say ""
+      end
+
+      private
+        def exists?(path)
+          File.exist?(File.join(destination_root, path))
+        end
+
+        def read(path)
+          File.read(File.join(destination_root, path))
+        end
+
+        def skip(path, why)
+          say_status :skip, "#{path}: #{why}", :yellow
+        end
+
+        # A missing ingredient is reported loudly and with the exact content to
+        # paste. Silence here is what left our own dummy app without Turbo.
+        def by_hand(path, content, note = nil)
+          say_status :"by hand", path, :red
+          say note if note
+          say ""
+          say content.gsub(/^/, "    ")
+          say ""
+        end
+
+        # Turbo is the host's pin, but pinning it against a gem that is not
+        # there produces a 404 on every page — so it is only added when the
+        # host's own Gemfile has turbo-rails. The question is about the
+        # application being generated into, not about this process.
+        def turbo_available?
+          gemfile.match?(/^\s*gem ["']turbo-rails["']/)
+        end
+
+        def gemfile
+          exists?("Gemfile") ? read("Gemfile") : ""
+        end
+
+        def turbo_missing
+          say_status :error, "turbo-rails is not in this application", :red
+          say <<~MESSAGE
+
+            maquina_stream requires Turbo. Repair applies Turbo Stream morphs, and
+            with `window.Turbo` undefined every repair fails silently inside a catch:
+            the message simply stops being correct and nothing says so.
+
+                bundle add turbo-rails
+                bin/rails turbo:install
+                bin/rails generate maquina_stream:install
+
+          MESSAGE
+        end
+
+        def importmap_absent_note
+          "No config/importmap.rb. maquina_stream ships JavaScript by importmap and " \
+            "has no build step; with a bundler, import its source from app/javascript " \
+            "in the gem. Either way Turbo has to be loaded:"
+        end
+
+        def entrypoint_absent_note
+          "No Stimulus entrypoint with an `application` in scope. Add this wherever " \
+            "you call `Application.start()`:"
+        end
+    end
+  end
+end

data/lib/generators/maquina_stream/install/templates/initializer.rb.tt

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+# maquina_stream. Every option is listed with the default it already has, so
+# uncomment only what you are changing. The full reference, with the measured
+# cost of each cadence setting, is in docs/configuration.md.
+MaquinaStream.configure do |c|
+  # ---------------------------------------------------------------------------
+  # Host seams. The engine resolves nothing and authorizes nothing on its own,
+  # and the two below are the reason. Both are stubs: fill them in.
+  # ---------------------------------------------------------------------------
+
+  # Turns a stream id into a record. `rails g maquina_stream:streamable Message`
+  # rewrites this line for you; until then it raises, which is what an unset
+  # `find_stream` does too — a silent nil would look like a missing record
+  # rather than a missing seam.
+  c.find_stream = ->(sid) { raise NotImplementedError, "maquina_stream: c.find_stream is still the generated stub" }
+
+  # STUB, AND THE ONE THING THIS GENERATOR WILL NOT GUESS FOR YOU.
+  #
+  # As written it denies every repair request — exactly what an unset
+  # `authorize` does. That is the safe failure and a broken feature both: the
+  # browser can never repair a message until you replace it, and a message that
+  # loses a frame stays wrong until the page reloads.
+  #
+  # It receives the record `find_stream` returned and the ActionDispatch
+  # request, and answers whether this request may see this record. Something
+  # like:
+  #
+  #   c.authorize = ->(record, request) do
+  #     record.conversation.member?(request.session[:user_id])
+  #   end
+  #
+  # Guessing this is how an engine leaks other people's messages, so it guesses
+  # nothing.
+  c.authorize = ->(record, request) { false }
+
+  # Which transport Broadcaster's default emitter uses. `:turbo_streams` is the
+  # only value the engine ships; the seam exists so SSE is possible without the
+  # broadcaster knowing about it.
+  # c.transport = :turbo_streams
+
+  # ---------------------------------------------------------------------------
+  # Streaming cadence
+  # ---------------------------------------------------------------------------
+
+  # How long appends coalesce before one frame goes out. The one number worth
+  # thinking about: if your provider streams token by token you pay 2.34x the
+  # document size at 100ms and 1.08x at 250ms, and the reveal animation covers
+  # the coarser cadence. If your text arrives in batches or whole steps,
+  # raising it buys nothing. Measurements in docs/configuration.md.
+  # c.frame_budget_ms = 100
+
+  # How many blocks must open after a block before it may freeze. Markdown
+  # reinterprets backwards — a paragraph becomes a heading when its underline
+  # arrives — so a block near the tail is still moving.
+  # c.seal_lag = 2
+
+  # How often the client reconciles its DOM against the manifest, in ms.
+  # c.keyframe_interval_ms = 4_000
+
+  # How many recent sealed blocks a manifest carries in full. Everything older
+  # is covered by one rollup digest, which is what bounds the payload by the
+  # window instead of by the message.
+  # c.manifest_window = 50
+
+  # ---------------------------------------------------------------------------
+  # Presentation
+  # ---------------------------------------------------------------------------
+
+  # Fallback locale for the engine's own labels when I18n.locale is unset.
+  # Spanish and English both ship complete.
+  # c.locale = :es
+
+  # `:maquina` renders through maquina_components when that gem is installed
+  # and defines a component; `:plain` forces the engine's own Tailwind fallback
+  # even when the gem is present.
+  # c.components = :maquina
+
+  # Rouge theme names for the two generated highlighting stylesheets. Names are
+  # Rouge's own — `github.light`, not `github_light`. Changing them means
+  # re-running `bin/rails maquina_stream:themes`.
+  # c.themes = {light: "github.light", dark: "github.dark"}
+
+  # Which interactive affordances render. A hash merges onto the defaults one
+  # level deep; `false` turns everything off, `true` turns everything back on.
+  # c.controls = {code: {download: false}}
+
+  # ---------------------------------------------------------------------------
+  # URL hardening. Read by the sanitizer, the last pass before any HTML leaves
+  # the server. Every one of these loosens or tightens what a *model* may put
+  # in an href or a src, and model output is prompt-injectable.
+  # ---------------------------------------------------------------------------
+
+  # Base for resolving relative URLs. nil leaves a relative URL relative.
+  # c.default_origin = nil
+
+  # The only schemes that survive.
+  # c.allowed_protocols = %w[http https mailto]
+
+  # "*" allows any destination. A list of prefixes strips the href off every
+  # link not starting with one; the text stays.
+  # c.allowed_link_prefixes = ["*"]
+
+  # The same, for images. An image whose src does not survive is removed
+  # entirely: a broken rectangle carrying an attacker-chosen alt is worse than
+  # nothing.
+  # c.allowed_image_prefixes = ["*"]
+
+  # Whether data: image URLs survive. Only base64 rasters ever do;
+  # data:image/svg+xml is refused whatever this is set to.
+  # c.allow_data_images = true
+end
+
+# Fences and tags the renderer should know about beyond CommonMark. See
+# docs/registries.md and docs/deferred-renderers.md.
+#
+# MaquinaStream.register_fence "ruby", strategy: :server
+# MaquinaStream.register_fence "mermaid",
+#   strategy: :client,
+#   controller: "ms-diagram",
+#   payload: ->(source, info) { {source: source, info: info} }

data/lib/generators/maquina_stream/streamable/USAGE

@@ -0,0 +1,28 @@
+Description:
+    Makes one model streamable: the migration carrying the columns the
+    Streamable contract requires, and the `include` plus `maquina_stream` macro
+    in the model itself.
+
+    Per model, because a host may have several — an assistant message and a
+    tool call are two streams, not one.
+
+    The migration's columns come from MaquinaStream::Streamable itself, so they
+    cannot drift from the contract `maquina_stream_contract_gaps` checks.
+
+Example:
+    bin/rails generate maquina_stream:streamable Message
+
+    Creates or reports:
+        db/migrate/XXXXXXXX_add_maquina_stream_to_messages.rb
+        app/models/message.rb                     include + maquina_stream
+        config/initializers/maquina_stream.rb     fills in the find_stream stub
+
+    bin/rails generate maquina_stream:streamable Message --buffer=body
+
+    Names a different column as the markdown buffer.
+
+    bin/rails generate maquina_stream:streamable Message \
+      --stream-for="[:conversation, message.conversation_id, :messages]"
+
+    Sets the Turbo broadcast target. The engine never guesses one: who may
+    subscribe to a stream is your question, not the engine's.