maquina_stream 0.1.0

data/docs/registries.md

@@ -0,0 +1,283 @@
+# Registries
+
+Three registries let you change what the pipeline renders without touching the
+engine. All three are process-global and are read during the render post-pass,
+so register from an initializer:
+
+```ruby
+# config/initializers/maquina_stream.rb
+MaquinaStream.register_fence "ruby", strategy: :server
+MaquinaStream.register_tag :source, attributes: %w[id href title], partial: "…"
+MaquinaStream.register_element :h2, partial: "headings/h2"
+```
+
+Whatever a registration renders still goes through the sanitizer, which is the
+last pass and has no exceptions. A registry cannot inject raw HTML into a
+document. See [security.md](security.md).
+
+`test/dummy/config/initializers/maquina_stream.rb` registers all of these, and
+`test/maquina_stream/registries_example_test.rb` drives that registration
+through the full pipeline. Copy from there.
+
+## Fences
+
+```ruby
+MaquinaStream.register_fence "ruby", strategy: :server
+MaquinaStream.register_fence "text", strategy: :passthrough
+MaquinaStream.register_fence "mermaid", strategy: :client,
+  controller: "ms-diagram",
+  payload: ->(source, info) { {source: source, info: info} }
+```
+
+| Strategy | What it does | When to use it |
+|---|---|---|
+| `:server` | Rouge highlights the source once the fence closes, into CSS classes. The default for every unregistered language. | Anything Rouge has a lexer for. |
+| `:client` | Nothing is rendered server-side. The block carries a `payload:` as a data attribute and a Stimulus `controller:` draws it in the browser. | Diagrams, math — anything whose renderer is a JavaScript library the server has no business running. |
+| `:passthrough` | The source is emitted as escaped text and nothing else happens to it. | A language Rouge would mangle, or one whose highlighting is not worth the CPU. |
+
+Two rules the pipeline enforces rather than trusts:
+
+- **An open fence is never highlighted.** The work would be thrown away on the
+  next frame, and it is the difference between a 500-line fence fitting in the
+  frame budget and not. Do not expect syntax colours until the closing ``` lands.
+- **A `:client` fence emits no payload until it closes.** Handing the client
+  half a diagram to draw produces an error state for text that was merely still
+  arriving. Until then it renders a `shimmer` skeleton.
+
+### `:server`, closed
+
+````markdown
+```ruby
+puts 1
+```
+````
+
+```html
+<div data-ms-code data-ms-code-lang="ruby" data-controller="ms-code" data-component="code-block" …>
+  <div data-code-block-part="header">
+    <span data-code-block-part="lang">ruby</span>
+    <span data-code-block-part="controls">
+      <button data-code-block-part="copy" data-ms-control data-action="ms-code#copy">Copiar</button>
+      <button data-code-block-part="download" data-ms-control data-action="ms-code#download">Descargar</button>
+    </span>
+  </div>
+  <pre data-code-block-part="pre"><code><span class="nb">puts</span> <span class="mi">1</span></code></pre>
+  <pre hidden data-ms-code-source>puts 1
+</pre>
+</div>
+```
+
+The `<pre hidden data-ms-code-source>` carrier is what the copy and download
+buttons read, so a copy hands back the raw source rather than Rouge's span
+markup. It is a `<pre hidden>` and not a script tag on purpose: the sanitizer
+drops every script element, and cannot tell our carrier from an imitation of it.
+
+The same fence while still open renders the shell and the carrier, with no
+highlighting spans and no control buttons.
+
+### `:client`, closed
+
+````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. See [deferred-renderers.md](deferred-renderers.md).
+
+While the fence is open there is no payload and no controller at all — only the
+shimmer.
+
+### `:passthrough`
+
+````markdown
+```text
+as is
+```
+````
+
+```html
+<pre data-ms-element="pre"><code class="language-text">as is
+</code></pre>
+```
+
+## Custom tags
+
+Models emit XML-ish tags that mean something to your application rather than to
+markdown: `<source>`, `<citation>`, `<thinking>`. Register one and the post-pass
+replaces its node with your partial.
+
+The reference case is a model citing its sources:
+
+```ruby
+MaquinaStream.register_tag :source,
+  attributes: %w[id href title],
+  partial: "maquina_stream/components/source_citation",
+  literal_content: false
+```
+
+| Option | Meaning |
+|---|---|
+| `attributes:` | The attribute names the tag may carry. Anything else on it is dropped before the partial is called. |
+| `partial:` | The partial that renders it. Registered attribute names arrive as locals, so they must match the locals it declares — `href`, not `url`. |
+| `literal_content:` | `true` passes the tag's body as text; `false` renders it as markdown. |
+
+```markdown
+Según la fuente <source id="3" href="https://example.com/a" title="Un artículo" onclick="alert(1)"></source>.
+```
+
+```html
+<p data-ms-element="p">Según la fuente <span data-component="source-citation" data-ms-source-id="3" …>
+  <a data-source-citation-part="link" href="https://example.com/a" rel="noopener noreferrer">Un artículo</a>
+</span>.</p>
+```
+
+`onclick` never reaches the partial at all — it is gone before the sanitizer is
+even asked, because the registration did not list it.
+
+### An unregistered tag does not survive; its content does
+
+The sanitizer *unwraps* an element it does not know: the tag goes, its children
+stay.
+
+```markdown
+text <danger id="1">content</danger> more
+```
+
+```html
+<p data-ms-element="p">text content more</p>
+```
+
+Text stranded at the top level this way is wrapped into a `<p>` before the
+document is split, so it lands in a block of its own with an id and a digest,
+and morphs and repairs like any other block. Its id comes from the first free
+index at or after its position, so ids stay unique but are not always in
+ascending order.
+
+Mid-stream this is stable. `maquina_remend` removes only a tag whose `>` has not
+arrived yet (`"text <thinki"` → `"text"`), the sanitizer unwraps the tag whether
+it closed or not, and closing the tag changes no block above it — so nothing
+flickers and no sealed block is rewritten.
+
+### Block-level tags
+
+A registered tag can also wrap several paragraphs. The partial receives the
+whole thing as its `content`, rendered as markdown:
+
+```ruby
+MaquinaStream.register_tag :thinking, attributes: [], partial: "tags/reasoning"
+```
+
+```erb
+<%# app/views/tags/_reasoning.html.erb %>
+<%# locals: (content: "") %>
+<section data-ms-reasoning><%= content.to_s.html_safe %></section>
+```
+
+```markdown
+<thinking>
+One.
+
+Two.
+</thinking>
+
+After.
+```
+
+```html
+<section data-ms-reasoning id="ms-7-b0" data-ms-block data-ms-block-digest="434332299dedf830">
+  <p data-ms-element="p">One.</p>
+  <p data-ms-element="p">Two.</p>
+</section>
+<p id="ms-7-b1" data-ms-element="p" data-ms-block data-ms-block-digest="e44dfc18531833b6">After.</p>
+```
+
+Two things to know before you reach for this:
+
+1. **The whole tag is one block.** Four paragraphs of reasoning are one id, one
+   digest and one unit of repair — not four. If you want them to seal and
+   repair separately, leave the tag unregistered and style the blocks instead.
+2. **That block cannot seal until the tag closes**, so everything inside it is
+   re-sent on every frame. A four-paragraph body costs about 30% more bytes on
+   the wire than the same text unregistered; a twenty-paragraph body costs 3.5x,
+   and the single block is 88% of it. Keep block-level tags short, or accept the
+   cost at the tail.
+3. **Only registered names are treated this way.** With an empty registry the
+   buffer is untouched, and a `<thinking>` inside a fence or a backtick span
+   stays text:
+
+````markdown
+```text
+<thinking>x</thinking>
+```
+````
+
+```html
+<pre data-ms-element="pre"><code class="language-text">&lt;thinking&gt;x&lt;/thinking&gt;
+</code></pre>
+```
+
+### Where block-level handling applies
+
+Only to names you passed to `register_tag`, and only where the opening tag
+begins a line under four columns of indent — the shape that starts an HTML
+block. An inline `<citation>…</citation>` in the middle of a sentence is left
+exactly as the model wrote it, because it already renders correctly.
+
+It never applies inside a fenced code block, an inline code span, an indented
+code block, an HTML comment, `<script>`, `<pre>`, `<style>`, `<textarea>`, CDATA
+or a processing instruction — that text is content, not markup. A tag broken
+across a newline, one whose `>` has not arrived, an opener with no closer, a
+closer with no opener, and `<thinking/>` are all left alone.
+
+One limitation follows from the indent rule: **a block-level registered tag
+inside a list item is not supported.** Put it at the top level.
+
+## Element overrides
+
+Replace the markup the renderer produces for one element with a partial of your
+own:
+
+```ruby
+MaquinaStream.register_element :h2, partial: "headings/h2"
+```
+
+The partial receives `content:` (the element's inner HTML) and `node:` (the
+Nokogiri node), so it must declare both:
+
+```erb
+<%# app/views/headings/_h2.html.erb %>
+<%# locals: (content: "", node: nil) %>
+<h2 class="section-heading"><span aria-hidden="true">§</span> <%= content.to_s.html_safe %></h2>
+```
+
+```markdown
+## Thinking
+```
+
+```html
+<h2 class="section-heading"><span aria-hidden="true">§</span> Thinking<a href="#thinking" class="anchor" …></a></h2>
+```
+
+Registering the same element twice replaces the first registration; the last one
+in wins. Elements you do not override carry `data-ms-element="<tag>"` as a
+styling hook, which is usually enough — reach for an override when you need
+different structure, not different CSS.
+
+## Resetting
+
+```ruby
+MaquinaStream.reset_registries!
+```
+
+For tests. Called in production it loses every registration your initializer
+made.

data/docs/repair.md

@@ -0,0 +1,162 @@
+# Repair
+
+## What it is for
+
+Action Cable gives no delivery guarantee, no ordering guarantee and no gap
+detection. A frame can simply not arrive: a flaky connection, a backgrounded
+tab, a reconnect in the middle of a message. Deltas are an optimization, and
+they do not converge on their own — only the open tail is patched, so a block
+that changes after it has stopped being the tail is never re-sent.
+
+The repair path is where correctness lives. The browser periodically asks the
+server what the message currently is, compares that against its own DOM, and
+asks for the blocks that differ.
+
+If you fix a correctness bug inside the delta path, you have fixed it in the
+wrong place.
+
+## What you must implement
+
+Three things, and then it runs on its own.
+
+### 1. Mount the engine
+
+```ruby
+# config/routes.rb
+mount MaquinaStream::Engine => "/maquina_stream"
+```
+
+### 2. Configure the two seams
+
+```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
+```
+
+`find_stream` receives the `:sid` from the URL — that is `#maquina_stream_id`,
+which defaults to `to_param` — and returns a record or `nil`. Return `nil` and
+the engine answers `404`. Leave it unset and every engine request raises
+`MaquinaStream::ConfigurationError`: the engine does not go looking for a model
+on its own.
+
+`authorize` receives the record and the `ActionDispatch::Request`. Anything
+falsy answers `403`. **Leaving it unset denies everything**; there is no
+permissive default, because an engine that guesses is an engine that leaks.
+
+Scope the lookup rather than relying on `authorize` alone where you can — the
+same advice as any Rails controller:
+
+```ruby
+c.find_stream = ->(sid) { Current.user.messages.find_by(id: sid) }
+```
+
+### 3. Put the repair URLs on the message element
+
+```erb
+<div id="ms-msg-<%= message.maquina_stream_id %>"
+     data-controller="ms-repair"
+     data-ms-repair-manifest-url-value="<%= maquina_stream.manifest_path(sid: message.maquina_stream_id) %>"
+     data-ms-repair-blocks-url-value="<%= maquina_stream.blocks_path(sid: message.maquina_stream_id) %>"
+     data-ms-repair-interval-value="4000"><%= MaquinaStream.render(message) %></div>
+```
+
+`maquina_stream.` is the mounted engine's route proxy, so the paths follow
+wherever you mounted it. `data-ms-repair-interval-value` defaults to 4000ms;
+`0` turns the keyframe timer off and leaves the other three triggers.
+
+That is all. The blocks the engine renders already carry the `id`,
+`data-ms-block` and `data-ms-block-digest` the controller diffs on.
+
+## The two routes
+
+### `GET /maquina_stream/:sid/manifest`
+
+What the browser is told the message currently *is*, in a bounded number of
+bytes. Not HTML.
+
+```json
+{"seq":7,"cutoff":0,"rollup":"e3b0c44298fc1c14",
+ "blocks":[["ms-42-b0","999bd5bd2841c435"],["ms-42-b1","6c7c33d9dcefa12c"]]}
+```
+
+| Key | Meaning |
+|---|---|
+| `seq` | the sequence number this manifest describes |
+| `cutoff` | how many sealed blocks fall behind the window |
+| `rollup` | one digest covering every block behind the cutoff |
+| `blocks` | `[[id, digest], …]` for the blocks inside the window |
+
+Only sealed blocks are listed — an open block is about to change, so there is
+nothing to reconcile it against. With the default `seal_lag` of 2, the last two
+blocks of a message are absent from the manifest by design.
+
+The manifest is windowed rather than complete because listing every sealed block
+made it track message length almost exactly: 1.8KB for a 2KB message, 88KB for a
+100KB one, sent every keyframe. The last `manifest_window` sealed blocks go in
+full, and one rollup digest covers everything older. A client whose rollup
+matches knows its history is intact and only has to consider the window; a
+client whose rollup differs asks for the whole thing with `?full=1`, which is
+rare and no more expensive than the cold page load it resembles.
+
+### `GET /maquina_stream/:sid/blocks?ids[]=…`
+
+The blocks the client asked for, as morphing Turbo Stream actions.
+
+```html
+<turbo-stream method="morph" action="replace" target="ms-42-b1">
+  <template><p id="ms-42-b1" data-ms-element="p" data-ms-block data-ms-block-digest="6c7c33d9dcefa12c">Dos</p></template>
+</turbo-stream>
+```
+
+`method="morph"` is what makes the repair silent: idiomorph patches the existing
+node in place, so client state inside it survives and no animation fires for a
+replacement that never happens.
+
+`ids` comes from the client, so it is filtered against the document rather than
+trusted — only ids the message actually has are served, and only the ones
+requested. A request for every block is a legitimate cold repair, so the count
+is not capped, but each id is matched, never interpolated.
+
+Asking to repair nothing is a normal answer to a manifest that already agreed,
+and returns an empty stream rather than an error.
+
+## What the browser does with them
+
+`ms-repair` fetches on four triggers:
+
+1. the final seal, always;
+2. a gap in the sequence — every stream action carries `data-ms-seq`;
+3. a reconnect, or the tab becoming visible again;
+4. the periodic keyframe.
+
+It compares the manifest against its own DOM, requests only the blocks whose
+digests differ, and morphs them in. Repair therefore costs what has drifted, not
+what the message weighs.
+
+Before the morph it dispatches `ms:suppress` on the message element and
+`ms:resume` after it, so the reveal animation unwraps whatever was mid-flight
+and re-baselines afterwards — a repair never re-reveals text the reader has
+already read.
+
+It dispatches `ms:repaired` (with `{reason, blocks}`) and `ms:repair-failed`
+(with `{reason, error}`) if you want to observe it. See
+[javascript.md](javascript.md).
+
+## Responses you should expect
+
+| Situation | Response |
+|---|---|
+| `find_stream` returns `nil` | `404` |
+| `authorize` returns falsy | `403` |
+| `authorize` not configured | `403` |
+| `find_stream` not configured | `MaquinaStream::ConfigurationError` |
+
+## Transport independence
+
+The repair path is plain `GET`, so a client that lost frames recovers over HTTP
+no matter how those frames were delivered. Frames, sequence numbers, the
+manifest and these two routes are transport-independent by construction — which
+is what makes `config.transport` a seam worth having rather than a setting.

data/docs/security.md

@@ -0,0 +1,247 @@
+# Security
+
+Everything this engine renders is model output, and model output is
+prompt-injectable by definition. A document that reached the sanitizer having
+"already been checked" has not been checked — it has been parsed.
+
+## The one rule for a host
+
+**Never assign model output as raw HTML.**
+
+The engine's own output is `html_safe` because it has been through the
+sanitizer. Anything else — a buffer, a payload, a tool result, a value you read
+back out of rendered markup in JavaScript — is not. Do not `html_safe` it, do
+not `innerHTML` it, do not hand it to a template that will.
+
+```erb
+<%= MaquinaStream.render(message) %>          <%# sanitized on the way out %>
+<%= raw message.content %>                    <%# never %>
+```
+
+## The sanitizer
+
+```ruby
+MaquinaStream::Sanitizer.call(html, config: MaquinaStream.config) # => String
+```
+
+It is the last pass in the render chain — `maquina_remend → CommonMarker →
+Nokogiri post-pass → Sanitizer` — and the only one that assumes the document is
+hostile. It runs unconditionally: no mode, no flag, no fast path skips it. It is
+a pure function, with no Rails and no request.
+
+Nokogiri's **HTML5** parser builds the tree, because a sanitizer that parses
+differently from the engine that will render the output is a mutation-XSS bug
+waiting for its input.
+
+```
+in : <a href="javascript:alert(1)">clic</a>
+out: <a>clic</a>
+
+in : <img src="x" onerror="alert(1)">
+out: <img src="x">
+
+in : <script>alert(1)</script>hola
+out: hola
+```
+
+### How it decides
+
+1. An element on the drop list — or in the SVG or MathML namespace — is removed
+   **with its subtree**.
+2. An element not on the allowlist is **unwrapped**: the element goes, its
+   sanitized children stay. Text survives; markup does not.
+3. On a surviving element, each attribute must be named by the allowlist.
+   Everything else is dropped, not escaped and kept.
+4. `href` and `src` are re-parsed and re-checked. A rejected `href` leaves the
+   link with its text; a rejected `src` removes the `<img>` entirely, because a
+   broken rectangle carrying an attacker-chosen `alt` is worse than nothing.
+5. Comments, processing instructions and doctypes are removed. CDATA becomes
+   text.
+
+### What survives
+
+**Elements** — rendered markdown plus the post-pass wrappers: headings, `p`,
+`div`, `span`, `br`, `hr`, lists (`ul ol li dl dt dd`), tables
+(`table thead tbody tfoot tr td th caption colgroup col`),
+`pre code kbd samp var`, `blockquote figure figcaption details summary section
+article aside`, `a`, `img`, the inline set (`em strong b i u s del ins mark
+small sub sup q abbr dfn cite time wbr`), and `input` — the last only as the
+tasklist checkbox, forced `disabled`.
+
+**Attributes**
+
+| Scope | Allowed |
+|---|---|
+| Global | `id class title lang dir role translate`, plus `aria-*` |
+| `a` | `href target rel hreflang type` |
+| `img` | `src alt width height loading decoding` |
+| Lists and tables | `start reversed type value colspan rowspan align valign headers scope abbr span` |
+| `time`, `details` | `datetime`, `open` |
+| The engine's | every `data-ms-*`, plus `data-component data-variant data-size data-slot data-state data-side data-orientation data-controller data-action data-turbo-permanent data-turbo-temporary` |
+
+`data-controller` and `data-action` are filtered **by value**: only `ms-`
+identifiers survive, and only action descriptors naming one. A third-party
+controller's `data-<name>-*-value` attributes are dropped with it, so an
+injected controller arrives with no configuration:
+
+```
+in : <div data-controller="evil" data-evil-url-value="x">hi</div>
+out: <div>hi</div>
+```
+
+Anchors keep `target` normalized to `_blank`/`_self` and always gain
+`rel="noopener noreferrer"`.
+
+### What is dropped
+
+- Every `on*` attribute, whatever its case, and whatever the parser made of a
+  name split across a newline.
+- `srcdoc`, `formaction`, `style`, `action`, `http-equiv`, `background`, `ping`,
+  `srcset`, `usemap`, `name`, `contenteditable`, `accesskey`.
+- Every namespaced attribute — `xlink:href`, `xml:base` — without exception.
+- `script style svg math template noscript iframe object embed form button
+  select textarea base link meta …`, each with its subtree.
+
+That last one includes any `<script type="text/plain">` carrier: the sanitizer
+cannot tell yours from an imitation of it, and Nokogiri's HTML5 serializer
+writes script children unescaped, so a fence containing
+`</script><img onerror=…>` would break out on the next parse. **A code block
+that needs its raw source in the DOM must carry it on a non-script element** —
+which is why the engine's carrier is a `<pre hidden data-ms-code-source>`.
+
+### URL hardening
+
+Applied to `href` and `src`, in order:
+
+1. Control characters and Unicode whitespace are stripped first, so the scheme
+   tested is the scheme a browser would act on (`java\tscript:`,
+   `java\nscript:`).
+2. `//host`, `\\host`, `/\host` — protocol-relative in every spelling — are
+   rejected.
+3. The scheme is read from the raw value **and** from a decoded copy (HTML
+   entities, then percent-encoding). `java&#115;cript:`, `&amp;#106;avascript:`,
+   `%6Aavascript:` and `JaVaScRiPt:` all resolve to a dangerous scheme and are
+   rejected.
+4. The scheme must appear in `config.allowed_protocols` (default `http https
+   mailto`).
+5. A relative URL is resolved against `config.default_origin` when one is set,
+   and the result must still be on an allowed protocol. With no origin set it is
+   left as written. A bare `#fragment` is always kept.
+6. The final URL must start with one of `config.allowed_link_prefixes` /
+   `allowed_image_prefixes`. `["*"]`, the default, means any.
+
+`data:` is special-cased: image positions only, only when
+`config.allow_data_images`, and only base64 raster types.
+
+```
+allow_data_images = true   <img src="data:image/png;base64,iVBORw0KGgo=">  → kept
+allow_data_images = false  <img src="data:image/png;base64,iVBORw0KGgo=">  → removed
+either                     <img src="data:image/svg+xml;base64,…">         → removed
+```
+
+`data:image/svg+xml` is a scriptable document wearing an image's MIME type and
+never passes, whatever you configure.
+
+Tightening the two prefix lists is the main lever you have over what a model may
+link to. See [configuration.md](configuration.md).
+
+## The markdown normalisation pass
+
+One pass runs between `maquina_remend` and the markdown parser, and it can only
+insert newlines: around the opening and closing tags of tags you registered with
+`register_tag`, so a block-level `<thinking>` parses as its own HTML block
+instead of leaving a stray end tag inside a paragraph. Without it, the parser
+never closes the element and the rest of the message is handed to your partial.
+
+It is deliberately narrow, because it changes how model-written text is parsed:
+
+- The allowlist is your `register_tag` registry. An unregistered tag is never
+  matched and never moved.
+- Fenced blocks and inline code win — matching runs over masked text, so a
+  registered name inside them is content.
+- CommonMark's raw HTML regions — comments, `<script>`, `<pre>`, `<style>`,
+  `<textarea>`, CDATA, processing instructions — are masked too. A blank line
+  inserted inside one of those would end it early and publish what it hid.
+- Indented code is excluded by an indent rule.
+- A match must be a complete, well-formed tag on one line, parsed with
+  CommonMark's attribute grammar, so a `>` inside a quoted value cannot make an
+  insertion land mid-tag.
+
+Because it only inserts newlines, it can promote model text from raw HTML into
+markdown, or split a paragraph — but it cannot introduce an element or an
+attribute the allowlist does not name. The sanitizer runs unconditionally,
+last, over the parsed HTML. The whole XSS corpus is additionally run through the
+renderer with tags registered.
+
+## Why the client sanitizes again
+
+The server pass proves one thing: the HTML **the engine** serializes is safe. It
+cannot speak for HTML the browser builds afterwards.
+
+- Client-deferred renderers (`ms-diagram`, `ms-math`) receive a JSON payload and
+  produce new DOM from it. That payload is attacker-influenced text which passed
+  through the sanitizer as an attribute *value*, never as markup — nothing has
+  sanitized its output until the controller does. So `ms-deferred` applies its
+  own allowlist to whatever the library returns.
+- `data-controller` is an allowlisted attribute. The sanitizer restricts it to
+  the `ms-` namespace, but cannot tell a controller the post-pass emitted from
+  one an injected fragment asked for. Every `ms-` controller therefore treats its
+  own values as untrusted input rather than as server intent.
+- Serialize-and-reparse is where mutation XSS lives. Two parsers, two rounds of
+  entity decoding and one namespace boundary are enough to turn inert text into
+  markup.
+
+Server-side escaping protects the attribute boundary. It does not protect
+whatever the client does with the value inside it.
+
+## Renderer posture
+
+| Renderer | Setting | What it buys |
+|---|---|---|
+| `ms-diagram` (Mermaid) | `securityLevel: "strict"` | disables click handlers and inline HTML in diagram source |
+| `ms-math` (KaTeX) | `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 |
+
+## Limits
+
+- **It sanitizes HTML, not meaning.** A model that writes a plausible phishing
+  link to an allowed host produces a link the sanitizer will happily keep. That
+  is what `allowed_link_prefixes` and the link-safety dialog are for.
+- **A registered partial is yours to get right.** Registry output still goes
+  through the sanitizer, so it cannot introduce an element or attribute the
+  allowlist does not name — but a partial that renders an attacker-supplied
+  string into an allowed attribute is a hole the allowlist cannot see.
+- **Your own controllers are outside its reach.** A controller of yours that
+  reads a value out of rendered markup and assigns it as HTML has undone the
+  whole chain.
+- **The broadcast target is yours.** The sanitizer has nothing to say about who
+  may subscribe to a Turbo stream.
+
+## Extending the allowlist
+
+Everything lives in constants at the top of `lib/maquina_stream/sanitizer.rb`:
+
+- a new element → `ALLOWED_ELEMENTS`, or `DROP_WITH_CONTENT` if its contents
+  must not survive it;
+- a new attribute → `GLOBAL_ATTRIBUTES`, or the element's entry in
+  `ELEMENT_ATTRIBUTES`;
+- a new hook of your own → name it `data-ms-*` and it is already allowed;
+- a new URL-bearing attribute → give it a branch in `scrub_attribute_value` that
+  runs it through `safe_url`, never a bare entry in the allowlist. An unhardened
+  URL attribute is the whole bug.
+
+Every change comes with a corpus file. `test/fixtures/xss/*.txt` holds one
+attack per file:
+
+```
+--- input
+<a href="javascript:alert(1)">clic</a>
+--- note
+javascript: link. The anchor text survives; the href must be dropped.
+```
+
+The suite turns each file into its own test case at load time, so adding a file
+adds a test and there is no way to add an attack that is quietly not run. Every
+entry is asserted to produce no script element, no `on*` attribute, no forbidden
+attribute and no dangerous URL scheme, and to be a fixed point under a second
+sanitization pass.