maquina_stream 0.1.0

data/config/locales/en.yml

@@ -0,0 +1,79 @@
+# English is the secondary translation. It must stay complete: every key in
+# es.yml exists here with the same shape, and
+# test/maquina_stream/locales_test.rb fails the build when one is missing —
+# a silent fallback to Spanish inside an English UI is a bug, not a default.
+en:
+  maquina_stream:
+    number:
+      decimal_separator: "."
+    streaming:
+      controls_disabled: "Available once the response finishes"
+    deferred:
+      error: "This block could not be rendered"
+    shimmer:
+      label: "Loading…"
+    code:
+      copy: "Copy"
+      copy_code: "Copy the code"
+      copied: "Code copied"
+      copy_failed: "Couldn't copy"
+      download: "Download"
+      download_code: "Download the code"
+      language: "Language: %{name}"
+    snippet:
+      copy: "Copy"
+      copy_command: "Copy the command"
+      copied: "Command copied"
+      copy_failed: "Couldn't copy"
+    table:
+      copy: "Copy"
+      copy_markdown: "Copy as Markdown"
+      copy_csv: "Copy as CSV"
+      copy_tsv: "Copy as TSV"
+      copied: "Table copied"
+      copy_failed: "Couldn't copy"
+      download: "Download"
+      download_csv: "Download as CSV"
+      download_markdown: "Download as Markdown"
+      fullscreen: "Full screen"
+      exit_fullscreen: "Exit full screen"
+    image:
+      download: "Download"
+      download_image: "Download the image %{name}"
+      failed: "The image could not be loaded"
+    link_safety:
+      title: "You are leaving this site"
+      body: "This link goes to %{host}, an external site. Do you want to continue?"
+      host: "Destination"
+      confirm: "Continue"
+      cancel: "Cancel"
+      always_allow: "Always allow this site"
+      external_link: "External link to %{host}"
+      close: "Close"
+    autoscroll:
+      scroll_to_bottom: "Go to the end"
+      following: "Following the response"
+    source_citation:
+      unknown: "Source"
+      link_title: "Open the source %{name}"
+    attachment:
+      unnamed: "Attachment"
+      download: "Download"
+      download_file: "Download %{name}"
+      remove: "Remove"
+      remove_file: "Remove %{name}"
+      remove_confirm: "Remove this attachment?"
+      size: "%{value} %{unit}"
+      units:
+        bytes: "B"
+        kb: "kB"
+        mb: "MB"
+        gb: "GB"
+        tb: "TB"
+    suggestion:
+      list_label: "Suggestions"
+      chip_label: "Use the suggestion: %{text}"
+    export:
+      cancelled: "> _Response cancelled before it finished._"
+      errored: "> _The response ended with an error._"
+      timed_out: "> _The response stopped after a timeout._"

data/config/locales/es.yml

@@ -0,0 +1,82 @@
+# Español es el idioma por defecto del motor. Cada etiqueta de control y cada
+# nombre accesible vive aquí; ningún texto visible se escribe en línea en una
+# plantilla o en un controlador Stimulus.
+#
+# test/maquina_stream/locales_test.rb exige que es.yml y en.yml tengan
+# exactamente el mismo conjunto de claves: una traducción que falta rompe la
+# compilación en vez de degradarse en silencio.
+es:
+  maquina_stream:
+    number:
+      decimal_separator: ","
+    streaming:
+      controls_disabled: "Disponible cuando termine la respuesta"
+    deferred:
+      error: "No se pudo representar este bloque"
+    shimmer:
+      label: "Cargando…"
+    code:
+      copy: "Copiar"
+      copy_code: "Copiar el código"
+      copied: "Código copiado"
+      copy_failed: "No se pudo copiar"
+      download: "Descargar"
+      download_code: "Descargar el código"
+      language: "Lenguaje: %{name}"
+    snippet:
+      copy: "Copiar"
+      copy_command: "Copiar el comando"
+      copied: "Comando copiado"
+      copy_failed: "No se pudo copiar"
+    table:
+      copy: "Copiar"
+      copy_markdown: "Copiar como Markdown"
+      copy_csv: "Copiar como CSV"
+      copy_tsv: "Copiar como TSV"
+      copied: "Tabla copiada"
+      copy_failed: "No se pudo copiar"
+      download: "Descargar"
+      download_csv: "Descargar como CSV"
+      download_markdown: "Descargar como Markdown"
+      fullscreen: "Pantalla completa"
+      exit_fullscreen: "Salir de pantalla completa"
+    image:
+      download: "Descargar"
+      download_image: "Descargar la imagen %{name}"
+      failed: "La imagen no se pudo cargar"
+    link_safety:
+      title: "Vas a salir del sitio"
+      body: "Este enlace lleva a %{host}, un sitio externo. ¿Quieres continuar?"
+      host: "Destino"
+      confirm: "Continuar"
+      cancel: "Cancelar"
+      always_allow: "Permitir siempre este sitio"
+      external_link: "Enlace externo a %{host}"
+      close: "Cerrar"
+    autoscroll:
+      scroll_to_bottom: "Ir al final"
+      following: "Siguiendo la respuesta"
+    source_citation:
+      unknown: "Fuente"
+      link_title: "Abrir la fuente %{name}"
+    attachment:
+      unnamed: "Archivo adjunto"
+      download: "Descargar"
+      download_file: "Descargar %{name}"
+      remove: "Eliminar"
+      remove_file: "Eliminar %{name}"
+      remove_confirm: "¿Eliminar este adjunto?"
+      size: "%{value} %{unit}"
+      units:
+        bytes: "B"
+        kb: "kB"
+        mb: "MB"
+        gb: "GB"
+        tb: "TB"
+    suggestion:
+      list_label: "Sugerencias"
+      chip_label: "Usar la sugerencia: %{text}"
+    export:
+      cancelled: "> _Respuesta cancelada antes de terminar._"
+      errored: "> _La respuesta terminó con un error._"
+      timed_out: "> _La respuesta se interrumpió por tiempo de espera._"

data/config/routes.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+MaquinaStream::Engine.routes.draw do
+  # Mounted at /maquina_stream by the host:
+  #   GET /maquina_stream/:sid/manifest      => { seq:, blocks: [[id, digest], …] }
+  #   GET /maquina_stream/:sid/blocks?ids[]= => Turbo Stream, morph per block
+  scope ":sid" do
+    resource :manifest, only: :show
+    resources :blocks, only: :index
+  end
+end

data/docs/configuration.md

@@ -0,0 +1,219 @@
+# Configuration
+
+Configure once, from an initializer. Configuration is global and read on every
+render, so changing it mid-stream changes what later frames of an open message
+look like.
+
+```ruby
+# config/initializers/maquina_stream.rb
+MaquinaStream.configure do |c|
+  c.find_stream = ->(sid) { Message.find_by(id: sid) }
+  c.authorize = ->(record, request) { record.conversation.readable_by?(request) }
+end
+```
+
+Everything else has a working default. `MaquinaStream.config` returns the same
+object outside a `configure` block.
+
+## Host seams
+
+| Option | Default | What it does |
+|---|---|---|
+| `find_stream` | `nil` | Callable turning a stream id into a record. Unset, every repair request raises `ConfigurationError`. |
+| `authorize` | `nil` | Callable deciding whether a request may see a record. **Unset, every repair request is refused.** |
+| `transport` | `:turbo_streams` | 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. |
+
+`find_stream` raises when unset and `authorize` denies when unset, and the
+difference is deliberate: a silent `nil` from the finder would look like a
+missing record rather than a missing seam, while denial is always the safe
+answer to "may this request see this?".
+
+See [repair.md](repair.md) for both in context.
+
+## Streaming cadence
+
+| Option | Default | What it does |
+|---|---|---|
+| `frame_budget_ms` | `100` | How long appends coalesce before one frame goes out. |
+| `seal_lag` | `2` | How many blocks must open after a block before it may freeze. |
+| `keyframe_interval_ms` | `4000` | How often the client reconciles its DOM against the manifest. |
+| `manifest_window` | `50` | How many recent sealed blocks a manifest carries in full. |
+
+### Choosing `frame_budget_ms`
+
+This is the one number worth thinking about, because the right value depends on
+how *your* model delivers text. Coalescing only saves bytes when appends arrive
+faster than the budget: below that, raising it merges frames and cuts bandwidth;
+above it, raising it does nothing but add latency.
+
+Measured on a 20KB message, as a multiple of the size of the rendered document.
+Find the row that matches your model and pick a column you can live with:
+
+| How your text arrives | 60ms | 100ms | 150ms | 250ms |
+|---|---|---|---|---|
+| token by token — 4 chars every 25ms | 3.03x | 2.34x | 1.65x | 1.08x |
+| batched — 40 chars every 200ms | 1.07x | 1.07x | 1.07x | 0.89x |
+| step by step — 2000 chars every second | 1.17x | 1.17x | 1.17x | 1.17x |
+
+**If your provider streams token by token, raise this.** At the default you pay
+2.34x; at 250ms you pay 1.08x, and the word-level reveal animation covers the
+coarser cadence so the reader does not see the difference.
+
+**If your text arrives in batches or whole steps, leave it alone.** Raising it
+buys nothing at those cadences, and at 250ms it starts silently merging two
+steps into one frame — which costs the per-step feedback that is the reason to
+stream a step at all.
+
+### `seal_lag`
+
+A block freezes only once `seal_lag` later blocks exist. Markdown reinterprets
+backwards — a paragraph becomes a heading when its underline arrives — so a
+block that is still near the tail is still moving. Lower it and you freeze
+blocks that were about to change; raise it and more blocks stay in the patch set
+of every frame.
+
+The seal pointer additionally stops at a block holding an unresolved link
+reference, because `[docs]` cannot be rendered until `[docs]:` arrives.
+
+With the default, a four-block message has two sealed blocks and two open ones:
+
+```ruby
+doc = MaquinaStream::Document.new("# Uno\n\nDos\n\nTres\n\nCuatro\n",
+  config: MaquinaStream.config, sid: "42", mode: :streaming)
+
+doc.blocks.map { |b| [b.id, b.sealed?] }
+# => [["ms-42-b0", true], ["ms-42-b1", true], ["ms-42-b2", false], ["ms-42-b3", false]]
+```
+
+### `keyframe_interval_ms` and `manifest_window`
+
+The keyframe is the periodic "am I still right?" check. Lower it and drift is
+corrected sooner, at the cost of one small request per interval per open
+message. The request is small because the manifest is windowed: the last
+`manifest_window` sealed blocks in full, plus one rollup digest covering
+everything older, so the payload is bounded by the window rather than by the
+message.
+
+## Presentation
+
+| Option | Default | What it does |
+|---|---|---|
+| `locale` | `:es` | Fallback locale for the engine's own labels when `I18n.locale` is unset. Spanish and English both ship complete. |
+| `components` | `:maquina` | `: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. |
+| `themes` | `{light: "github.light", dark: "github.dark"}` | Rouge theme names for the two generated highlighting stylesheets. |
+| `controls` | every control on | Which interactive affordances render. |
+
+### Themes
+
+Highlighting emits CSS classes and never inline colour, so switching to dark
+mode is a stylesheet concern and needs no re-render — which matters, because a
+re-render mid-stream would mean re-broadcasting sealed blocks to change a
+colour.
+
+Two stylesheets ship generated. Load both; they are scoped so only one applies:
+
+```erb
+<%= stylesheet_link_tag "maquina_stream/themes/light" %>
+<%= stylesheet_link_tag "maquina_stream/themes/dark" %>
+```
+
+```css
+/* every rule is scoped to a code block and to one scheme */
+:root:not([data-theme="dark"]) [data-ms-code] … { }
+[data-theme="dark"]            [data-ms-code] … { }
+```
+
+Changing `config.themes` means regenerating them:
+
+```sh
+bundle exec rake maquina_stream:themes
+```
+
+Names are Rouge's own — the registry has `github.light` and `github.dark`, not
+`github_dark`. An unknown name raises `MaquinaStream::Themes::UnknownTheme`
+rather than falling back silently.
+
+### Controls
+
+Every control, and its group:
+
+| Group | Controls |
+|---|---|
+| `code` | `copy`, `download` |
+| `table` | `copy`, `download`, `fullscreen` |
+| `image` | `download` |
+| `attachment` | `download`, `remove` |
+| `suggestion` | `enabled` |
+| `link_safety` | a single boolean, not a group |
+
+An assigned hash merges onto the defaults one level deep, so you name only what
+you are changing:
+
+```ruby
+c.controls = {code: {download: false}}   # copy stays on
+c.controls = false                       # everything off
+c.controls = true                        # everything back on
+```
+
+```ruby
+config.control?(:code, :copy)      # => true
+config.control?(:code, :download)  # => false, after the first line above
+config.control?(:code)             # => true, while any code control remains
+```
+
+Turning a group off removes the buttons the renderer emits. A table with no
+controls left loses its control bar and its `data-controller` too — a controller
+with nothing to drive is cost on every frame:
+
+```html
+<!-- controls = false -->
+<div data-ms-table><table data-ms-element="table">…</table></div>
+```
+
+Controls you render yourself should carry `data-ms-control`, or they stay
+clickable while the message is still streaming. See [javascript.md](javascript.md).
+
+## URL hardening
+
+Read by the sanitizer, which is 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.
+
+| Option | Default | What it does |
+|---|---|---|
+| `default_origin` | `nil` | Base for resolving relative URLs. `nil` leaves a relative URL relative. |
+| `allowed_protocols` | `%w[http https mailto]` | The only schemes that survive. |
+| `allowed_link_prefixes` | `["*"]` | `"*"` allows any destination. A list of prefixes strips the `href` off every link not starting with one; the text stays. |
+| `allowed_image_prefixes` | `["*"]` | Same, for images. An image whose `src` does not survive is removed entirely. |
+| `allow_data_images` | `true` | Whether `data:` image URLs survive. Only base64 rasters ever do. |
+
+```ruby
+c.allowed_link_prefixes = ["https://example.com/"]
+```
+
+```html
+<!-- in  --> <a href="https://evil.test/x">a</a> <a href="https://example.com/ok">b</a>
+<!-- out --> <a>a</a> <a href="https://example.com/ok" rel="noopener noreferrer">b</a>
+```
+
+```ruby
+c.default_origin = "https://app.example.com"
+```
+
+```html
+<!-- in  --> <a href="/docs">d</a>
+<!-- out --> <a href="https://app.example.com/docs" rel="noopener noreferrer">d</a>
+```
+
+`data:image/svg+xml` is refused whatever `allow_data_images` is set to: it is a
+scriptable document wearing an image's MIME type. Full detail in
+[security.md](security.md).
+
+## Resetting
+
+```ruby
+MaquinaStream.reset_configuration!
+```
+
+For tests. Called in production it loses your `find_stream` and `authorize`
+seams, and every repair request after it is refused.

data/docs/deferred-renderers.md

@@ -0,0 +1,184 @@
+# Client-deferred renderers
+
+Some things cannot be rendered on the server without shipping a rendering engine
+with them — a Mermaid diagram, a KaTeX formula. Those render in the browser,
+from **one JSON payload for one leaf node**.
+
+This is not an exception to "only rendered HTML reaches the browser". The client
+never parses markdown; it receives a payload for a single, already-identified
+block and nothing else.
+
+## What the engine ships
+
+Two renderers, and no fence name for either. Which fence means "diagram" is your
+decision:
+
+```ruby
+# config/initializers/maquina_stream.rb
+MaquinaStream.register_fence "mermaid",
+  strategy: :client,
+  controller: "ms-diagram",
+  payload: ->(source, info) { {source: source, info: info} }
+
+MaquinaStream.register_fence "math",
+  strategy: :client,
+  controller: "ms-math",
+  payload: ->(source, _info) { {source: source, display: true} }
+```
+
+Pin the libraries yourself. The engine never pins a third-party library — one
+that pinned Mermaid would win or lose a version fight with your app for no
+reason — and `preload: false` is what keeps the lazy import lazy:
+
+```ruby
+# config/importmap.rb
+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
+```
+
+NoBuild: there is no lockfile, so the version lives in the importmap and nowhere
+else.
+
+## What it renders
+
+While the fence is open there is no payload and no controller — just a skeleton:
+
+````markdown
+```mermaid
+graph TD; A-->B;
+````
+
+```html
+<div data-component="shimmer" role="status" aria-busy="true" aria-live="polite">
+  <span class="sr-only">mermaid</span>
+  …
+</div>
+```
+
+Once it closes:
+
+````markdown
+```mermaid
+graph TD; A-->B;
+```
+````
+
+```html
+<div data-controller="ms-diagram"
+     data-ms-diagram-payload-value='{"source":"graph TD; A--\u003eB;\n","info":"mermaid"}'>
+  <div data-ms-diagram-target="output" data-turbo-permanent>…shimmer…</div>
+</div>
+```
+
+**Split ownership.** The payload attribute is server state and belongs to morph.
+The output element is client state, is `data-turbo-permanent`, and belongs to
+the controller. A repair morph that leaves the payload byte-identical fires no
+value-changed callback, so it triggers no re-render and no flicker.
+
+**No payload until the fence closes.** Handing the client half a diagram to draw
+produces an error state for text that was merely still arriving.
+
+## Writing your own
+
+Nothing about a renderer lives in the engine. The registry carries the
+controller name and the payload shape; the controller is yours.
+
+```ruby
+MaquinaStream.register_fence "timeline",
+  strategy: :client,
+  controller: "ms-timeline",
+  payload: ->(source, info) { {source: source, info: info, format: "timeline"} }
+```
+
+```js
+import MsDeferredController from "maquina_stream/controllers/ms_deferred_controller"
+
+class MsTimelineController extends MsDeferredController {
+  static library = null
+
+  async library() {
+    if (!this.constructor.library) {
+      const timeline = await import("timeline")
+      this.constructor.library = timeline.default ?? timeline
+    }
+
+    return this.constructor.library
+  }
+
+  async draw(payload) {
+    const timeline = await this.library()
+    return timeline.renderToString(String(payload.source ?? ""))
+  }
+}
+
+application.register("ms-timeline", MsTimelineController)
+```
+
+Two methods: `library()` imports lazily and memoizes on the class, `draw(payload)`
+returns a markup string. Everything else is decided for you.
+
+`payload:` is a callable receiving `(source, info)` and returning a Hash; it
+defaults to `{source:, info:}`. It is serialized as JSON into a data attribute,
+so it must be JSON-representable.
+
+`ms-timeline` appears nowhere in the engine. The dummy app registers exactly
+this.
+
+## What `ms-deferred` decides for every renderer
+
+- **When to render.** On intersection, not on connect: a conversation scrolled
+  back through hundreds of messages must not render hundreds of diagrams nobody
+  is looking at. Set `data-ms-<name>-eager-value="true"` to override.
+- **Lazy import.** The library is imported the first time something is actually
+  about to draw. A page with no deferred content loads no renderer library.
+- **Re-rendering.** Only when the payload really changed. A morph that leaves it
+  byte-identical does nothing.
+- **Sanitization of the output.** An allowlist, applied to whatever the library
+  returns — SVG and MathML elements, the geometry and presentation attributes
+  they need, and nothing that takes a URL except an `href` starting `https:`,
+  `http:`, `mailto:` or `#`. The payload is model output and the library is
+  third-party; neither is a reason to skip the check. This runs *in addition to*
+  the server's sanitizer. See [security.md](security.md).
+- **Failure.** A broken payload never breaks the message.
+
+## The export fallback
+
+**Show the source the model wrote.** That is the answer for every deferred
+renderer, implemented once, and used for the error state, for
+`MaquinaStream::Export.markdown`, and for any environment where the renderer
+cannot run:
+
+```html
+<div data-ms-deferred-error role="note">
+  <p>This block could not be rendered.</p>
+  <pre>graph TD; A-->B;</pre>
+</div>
+```
+
+Alt text would be a summary nobody wrote, and a server-rendered substitute would
+mean shipping the rendering engine to the server — which is the reason these are
+deferred at all.
+
+The label is read from `data-ms-deferred-error-label` on the block itself, and
+falls back to the English string above when there is none — JavaScript cannot
+read `I18n`, and hardcoding the engine's default locale would show Spanish to a
+host that never asked for it. A renderer of your own can put a translated label
+on the element it renders.
+
+## Security posture
+
+| Renderer | Setting | What it buys |
+|---|---|---|
+| `ms-diagram` | `securityLevel: "strict"` | disables click handlers and inline HTML in diagram source, which is model output |
+| `ms-math` | `trust: false` | refuses `\htmlClass`, `\includegraphics` and `\href`, all of which take attacker-controlled strings into the DOM |
+| both | output allowlist | the library is third-party; its output is scrubbed before it reaches the DOM |
+
+`ms-math` also runs with `throwOnError: false`, so a malformed formula degrades
+to the fallback rather than taking the message down.
+
+## Events
+
+| Event | Detail |
+|---|---|
+| `ms:rendered` | `{controller}` |
+| `ms:render-failed` | `{controller, error}` |