maquina_stream 0.1.0

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

@@ -0,0 +1,110 @@
+import ApplicationController from "maquina_stream/controllers/application_controller"
+
+// `ms-autoscroll` — keep the bottom of a growing message in view while it
+// streams, and get out of the way the instant the user scrolls up.
+//
+//   <div data-controller="ms-autoscroll"
+//        data-action="scroll->ms-autoscroll#track wheel->ms-autoscroll#release
+//                     touchmove->ms-autoscroll#release"
+//        style="overflow-y: auto">
+//     <div id="ms-msg-42">…</div>
+//   </div>
+//
+// Or against the window, for a page that scrolls as a whole:
+//
+//   <div data-controller="ms-autoscroll"
+//        data-ms-autoscroll-scroller-value="window"
+//        data-action="scroll@window->ms-autoscroll#track
+//                     wheel@window->ms-autoscroll#release
+//                     touchmove@window->ms-autoscroll#release">
+//
+// The rule the whole controller exists to keep: **it never scrolls unless it
+// is pinned, and only the user can pin it.** A programmatic scroll always
+// lands at the bottom, so it re-satisfies the pin condition and never fights
+// a user who is reading further up.
+export default class extends ApplicationController {
+  static values = {
+    // "self" (the controller element scrolls) or "window".
+    scroller: { type: String, default: "self" },
+    // How close to the bottom still counts as "at the bottom", in pixels. A
+    // couple of device pixels of rounding is normal, and a sub-pixel layout
+    // would otherwise unpin on its own.
+    threshold: { type: Number, default: 32 },
+    // Serialized so it survives a Turbo morph and can be read from a test.
+    pinned: { type: Boolean, default: true }
+  }
+
+  connect() {
+    // The message grows by morph and by Turbo Stream, neither of which fires a
+    // DOM event this controller can hang off. An observer is the only signal.
+    this.observer = new MutationObserver(() => this.follow())
+    this.observer.observe(this.element, { childList: true, subtree: true, characterData: true })
+    this.follow()
+  }
+
+  disconnect() {
+    this.observer?.disconnect()
+    this.observer = null
+    cancelAnimationFrame(this.frame)
+  }
+
+  // ------------------------------------------------------------------ actions
+
+  // Bound to `scroll`. Pinning is derived from position, never remembered:
+  // the user scrolls back to the bottom and is pinned again, by the same rule
+  // that unpinned them.
+  track() {
+    this.pinnedValue = this.atBottom
+  }
+
+  // Bound to `wheel` and `touchmove`. Scroll events can lag a gesture by a
+  // frame or two on a long document; an upward gesture unpins immediately so
+  // the next append does not yank the view back down.
+  // An unpin here is never final: the `scroll` event that follows the gesture
+  // runs `track`, which pins again if the gesture ended at the bottom.
+  release(event) {
+    if (event.type === "wheel" && event.deltaY >= 0) return
+    this.pinnedValue = false
+  }
+
+  // Public, for a "jump to latest" button.
+  pin() {
+    this.pinnedValue = true
+    this.scrollToBottom()
+  }
+
+  unpin() {
+    this.pinnedValue = false
+  }
+
+  pinnedValueChanged(pinned, previous) {
+    if (previous === undefined) return
+    this.notify("autoscroll", { pinned })
+  }
+
+  // ------------------------------------------------------------------ scroller
+
+  get scroller() {
+    return this.scrollerValue === "window" ? document.scrollingElement : this.element
+  }
+
+  get atBottom() {
+    const scroller = this.scroller
+    if (!scroller) return true
+    const distance = scroller.scrollHeight - scroller.scrollTop - scroller.clientHeight
+    return distance <= this.thresholdValue
+  }
+
+  follow() {
+    if (!this.pinnedValue) return
+    // Coalesce a burst of appends into one scroll per frame.
+    cancelAnimationFrame(this.frame)
+    this.frame = requestAnimationFrame(() => this.scrollToBottom())
+  }
+
+  scrollToBottom() {
+    const scroller = this.scroller
+    if (!scroller) return
+    scroller.scrollTop = scroller.scrollHeight
+  }
+}

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

@@ -0,0 +1,96 @@
+import ApplicationController from "maquina_stream/controllers/application_controller"
+
+// `ms-code` — copy and download a rendered code block.
+//
+// The DOM contract (docs/javascript.md) fixes the shape:
+//
+//   <div data-ms-code data-ms-code-lang="ruby" data-controller="ms-code">
+//     <button data-ms-control data-action="ms-code#copy">…</button>
+//     <button data-ms-control data-action="ms-code#download">…</button>
+//     <pre><code>…highlighted…</code></pre>
+//     <pre hidden data-ms-code-source>…raw source…</pre>
+//   </div>
+//
+// Copy and download read the `data-ms-code-source` carrier, never the
+// highlighted markup. The carrier is a `<pre hidden>`, not a script tag: its
+// content is ordinary escaped text, so `textContent` is the whole story and
+// nothing has to be unescaped. Reading the highlighted `<code>` instead would
+// hand back Rouge's span soup collapsed into text.
+export default class extends ApplicationController {
+  // Late-bound so a host with a different carrier does not have to fork the
+  // controller. Both are scoped to `this.element`.
+  static values = {
+    sourceSelector: { type: String, default: "[data-ms-code-source]" },
+    filename: { type: String, default: "" }
+  }
+
+  static targets = ["source"]
+
+  // Extension per language. An unknown language downloads as `.txt` rather
+  // than guessing: a wrong extension is worse than a generic one.
+  static extensions = {
+    bash: "sh", c: "c", cpp: "cpp", csharp: "cs", css: "css", diff: "diff",
+    elixir: "ex", erb: "erb", go: "go", haml: "haml", html: "html",
+    java: "java", javascript: "js", js: "js", json: "json", jsx: "jsx",
+    kotlin: "kt", markdown: "md", md: "md", python: "py", py: "py",
+    ruby: "rb", rb: "rb", rust: "rs", scss: "scss", sh: "sh", shell: "sh",
+    sql: "sql", swift: "swift", toml: "toml", ts: "ts", tsx: "tsx",
+    typescript: "ts", xml: "xml", yaml: "yml", yml: "yml", zsh: "sh"
+  }
+
+  connect() {
+    this.startStreamGuard()
+  }
+
+  disconnect() {
+    this.stopStreamGuard()
+  }
+
+  // ------------------------------------------------------------------ actions
+
+  copy(event) {
+    if (this.refuseWhileStreaming(event)) return
+    this.copyText(this.source)
+  }
+
+  download(event) {
+    if (this.refuseWhileStreaming(event)) return
+    this.downloadText(this.source, this.downloadName, "text/plain")
+  }
+
+  // ------------------------------------------------------------------ reading
+
+  get sourceElement() {
+    if (this.hasSourceTarget) return this.sourceTarget
+    try {
+      return this.element.querySelector(this.sourceSelectorValue)
+    } catch {
+      // The selector is a DOM-derived string; a malformed one must not throw
+      // out of an event handler.
+      return null
+    }
+  }
+
+  // Untrusted text. It is only ever handed to the clipboard, to a Blob, or to
+  // a textarea's `value` — never assigned as HTML.
+  get source() {
+    return this.sourceElement?.textContent ?? ""
+  }
+
+  // The DOM contract writes the language as `data-ms-code-lang`, which is one
+  // suffix short of a Stimulus value (`data-ms-code-lang-value`). It is read as
+  // a plain attribute on purpose so the pipeline's output needs no change.
+  get language() {
+    return (this.element.getAttribute("data-ms-code-lang") || "").trim().toLowerCase()
+  }
+
+  get extension() {
+    return this.constructor.extensions[this.language] || "txt"
+  }
+
+  get downloadName() {
+    if (this.filenameValue.length) return this.filenameValue
+    const stem = this.language.replace(/[^a-z0-9_-]/g, "") || "snippet"
+    return `${stem}.${this.extension}`
+  }
+}

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

@@ -0,0 +1,223 @@
+import ApplicationController from "maquina_stream/controllers/application_controller"
+
+// `ms-deferred` — the base class for a renderer that runs in the browser.
+//
+// Subclasses (`ms-diagram`, `ms-math`) supply two things: how to import their
+// library, and how to turn a payload into markup. Everything else — when to
+// render, what to do on a repair morph, how to fail, and what may reach the
+// DOM — is decided here, once.
+//
+//   <div data-controller="ms-diagram"
+//        data-ms-diagram-payload-value='{"source":"graph TD…"}'>
+//     <div data-ms-diagram-target="output" data-turbo-permanent>…</div>
+//   </div>
+//
+// Split ownership, from docs/deferred-renderers.md: the payload attribute is server
+// state and belongs to morph; the output element is client state and belongs to
+// this controller. A repair morph that leaves the payload byte-identical fires
+// no value-changed callback, so it triggers no re-render and no flicker — which
+// is the property Phase 4 depends on.
+export default class extends ApplicationController {
+  static targets = ["output"]
+
+  static values = {
+    payload: Object,
+    // Rendering is deferred until the element is on screen. A conversation
+    // scrolled back through hundreds of messages should not render hundreds of
+    // diagrams nobody is looking at.
+    eager: { type: Boolean, default: false }
+  }
+
+  connect() {
+    this.connected = true
+
+    if (this.eagerValue) return this.render()
+
+    this.observer = new IntersectionObserver((entries) => {
+      if (entries.some((entry) => entry.isIntersecting)) this.render()
+    }, { rootMargin: "200px" })
+
+    this.observer.observe(this.element)
+  }
+
+  disconnect() {
+    this.connected = false
+    this.observer?.disconnect()
+    this.observer = null
+  }
+
+  // The payload changed under a morph: re-render, but only because it really
+  // changed. Stimulus only fires this when the attribute's value differs.
+  //
+  // The `connected` guard is the whole of the lazy load, and it is not
+  // defensive coding. Stimulus invokes every value-changed callback ONCE while
+  // the context connects, before `connect()` runs, and it passes as `previous`
+  // the value type's DEFAULT — `{}` for an Object — never `undefined`. So a
+  // guard written as `previous === undefined` never fires: the initial
+  // invocation reads as a real change, resets `rendered` and calls `render()`.
+  //
+  // That is exactly what happened. With mermaid and katex pinned in the dummy
+  // app, Chromium fetched both at scrollY 0 with the blocks 4,500px down the
+  // page. `library()` is lazy and the observer is correct; this callback was
+  // calling past both of them.
+  payloadValueChanged(payload, previous) {
+    if (!this.connected) return
+    if (JSON.stringify(payload) === JSON.stringify(previous)) return
+
+    this.rendered = false
+    this.render()
+  }
+
+  async render() {
+    if (this.rendered) return
+    if (!this.hasPayload) return
+
+    this.rendered = true
+
+    try {
+      const markup = await this.draw(this.payloadValue)
+      this.replaceOutput(markup)
+    } catch (error) {
+      this.fail(error)
+    }
+  }
+
+  get hasPayload() {
+    return this.payloadValue && Object.keys(this.payloadValue).length > 0
+  }
+
+  // ------------------------------------------------------------- subclass API
+
+  // Import the library. Called once, lazily, and only when there is something
+  // to draw — a page with no deferred content loads no renderer at all.
+  async library() {
+    throw new Error("ms-deferred subclasses must implement library()")
+  }
+
+  // Turn a payload into markup. Returns a string or a Node.
+  async draw(_payload) {
+    throw new Error("ms-deferred subclasses must implement draw()")
+  }
+
+  // ------------------------------------------------------------------ output
+
+  // Nothing a renderer produces is trusted. The server sanitized the document,
+  // and this sanitizes again on the way in: the payload is model output, the
+  // library is third-party, and neither is a reason to skip the check. See
+  // CLAUDE.md — renderer output gets sanitized client-side even though the
+  // server already sanitized the document.
+  replaceOutput(markup) {
+    if (!this.hasOutputTarget) return
+
+    const safe = this.sanitize(markup)
+    this.outputTarget.replaceChildren(safe)
+    this.notify("rendered", { controller: this.identifier })
+  }
+
+  sanitize(markup) {
+    const template = document.createElement("template")
+
+    if (markup instanceof Node) {
+      template.content.append(markup)
+    } else {
+      template.innerHTML = String(markup)
+    }
+
+    this.scrub(template.content)
+    return template.content
+  }
+
+  // An allowlist, not a blocklist: anything not named here loses its markup and
+  // keeps its text. Scripts and foreign-content subtrees go entirely.
+  scrub(root) {
+    const allowed = this.constructor.allowedElements
+    const dropWithContent = this.constructor.droppedElements
+
+    for (const node of [...root.querySelectorAll("*")]) {
+      const name = node.tagName.toLowerCase()
+
+      if (dropWithContent.has(name)) {
+        node.remove()
+        continue
+      }
+
+      for (const attribute of [...node.attributes]) {
+        if (!this.attributeAllowed(name, attribute)) node.removeAttribute(attribute.name)
+      }
+
+      if (!allowed.has(name)) node.replaceWith(...node.childNodes)
+    }
+  }
+
+  attributeAllowed(_element, attribute) {
+    const name = attribute.name.toLowerCase()
+
+    if (name.startsWith("on")) return false
+    if (name === "style") return false
+    if (["href", "xlink:href", "src", "srcdoc", "formaction"].includes(name)) {
+      return name === "href" && /^(https?:|mailto:|#)/i.test(attribute.value.trim())
+    }
+
+    return this.constructor.allowedAttributes.has(name)
+  }
+
+  static allowedElements = new Set([
+    "svg", "g", "path", "rect", "circle", "ellipse", "line", "polyline", "polygon",
+    "text", "tspan", "marker", "defs", "symbol", "use", "title", "desc", "foreignObject",
+    "div", "span", "p", "br", "sub", "sup", "table", "tbody", "tr", "td", "annotation",
+    "semantics", "mrow", "mi", "mn", "mo", "ms", "mtext", "mfrac", "msqrt", "mroot",
+    "msub", "msup", "msubsup", "munder", "mover", "munderover", "mtable", "mtr", "mtd",
+    "mspace", "mpadded", "mphantom", "menclose", "mstyle", "math", "a"
+  ])
+
+  static droppedElements = new Set([
+    "script", "iframe", "object", "embed", "link", "meta", "base", "form",
+    "input", "button", "textarea", "select", "audio", "video", "animate",
+    "animatetransform", "set", "handler", "listener"
+  ])
+
+  static allowedAttributes = new Set([
+    "class", "id", "width", "height", "viewbox", "d", "fill", "stroke",
+    "stroke-width", "stroke-linecap", "stroke-linejoin", "stroke-dasharray",
+    "transform", "x", "y", "x1", "x2", "y1", "y2", "cx", "cy", "r", "rx", "ry",
+    "points", "text-anchor", "dominant-baseline", "font-size", "font-family",
+    "font-weight", "opacity", "fill-opacity", "stroke-opacity", "marker-end",
+    "marker-start", "preserveaspectratio", "aria-label", "aria-hidden", "role",
+    "mathvariant", "displaystyle", "scriptlevel", "href", "dir", "lang",
+    "colspan", "rowspan", "columnalign", "rowalign", "open", "close", "separator"
+  ])
+
+  // ------------------------------------------------------------------- errors
+
+  // A broken payload never breaks the message. The block degrades to something
+  // readable and says why, and the rest of the message is untouched.
+  fail(error) {
+    if (!this.hasOutputTarget) return
+
+    const fallback = document.createElement("div")
+    fallback.setAttribute("data-ms-deferred-error", "")
+    fallback.setAttribute("role", "note")
+
+    const message = document.createElement("p")
+    message.textContent = this.errorLabel
+
+    // The source is the export fallback, and it is the same one for every
+    // deferred renderer: show what the model actually wrote. See
+    // docs/deferred-renderers.md.
+    const source = document.createElement("pre")
+    source.textContent = this.payloadValue?.source ?? ""
+
+    fallback.append(message, source)
+    this.outputTarget.replaceChildren(fallback)
+    this.notify("render-failed", { controller: this.identifier, error: String(error) })
+  }
+
+  // The server renders the label, translated, into the data attribute. This
+  // fallback is only reached when a host renders the block without one, so it
+  // is the language of last resort rather than the engine's default locale —
+  // JavaScript cannot read I18n, and hardcoding Spanish here would show Spanish
+  // to a host that never asked for it.
+  get errorLabel() {
+    return this.element.dataset.msDeferredErrorLabel || "This block could not be rendered."
+  }
+}

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

@@ -0,0 +1,40 @@
+import MsDeferredController from "maquina_stream/controllers/ms_deferred_controller"
+
+// `ms-diagram` — Mermaid, rendered in the browser, in strict security mode.
+//
+// The library is imported the first time a diagram is actually about to draw,
+// so a page with no diagrams never fetches it. Pinned by version: NoBuild means
+// no lockfile, so the version lives in the importmap and nowhere else.
+export default class extends MsDeferredController {
+  static values = {
+    ...MsDeferredController.values,
+    theme: { type: String, default: "default" }
+  }
+
+  static library = null
+
+  async library() {
+    // securityLevel "strict" is the point: it disables click handlers and
+    // inline HTML inside diagram source, which is model output.
+    if (!this.constructor.library) {
+      const mermaid = await import("mermaid")
+      mermaid.default.initialize({
+        startOnLoad: false,
+        securityLevel: "strict",
+        theme: this.themeValue
+      })
+      this.constructor.library = mermaid.default
+    }
+
+    return this.constructor.library
+  }
+
+  async draw(payload) {
+    const mermaid = await this.library()
+    const id = `ms-mermaid-${Math.random().toString(36).slice(2)}`
+    const { svg } = await mermaid.render(id, String(payload.source ?? ""))
+
+    // Sanitized by ms-deferred on the way in, strict mode or not.
+    return svg
+  }
+}

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

@@ -0,0 +1,196 @@
+import ApplicationController from "maquina_stream/controllers/application_controller"
+
+// The host seam for the allowlist. It is a function, so it cannot live in a
+// data attribute — and it must not: an allowlist an injected fragment can
+// rewrite is not an allowlist.
+//
+//   import { linkSafety } from "maquina_stream"
+//   linkSafety.allow = (url) => url.hostname.endsWith("example.com")
+//
+// `url` is a parsed `URL`. Returning true follows the link with no dialog.
+export const linkSafety = {
+  allow: null
+}
+
+// `ms-link-safety` — confirm before following a link out of a rendered message.
+//
+//   <div data-controller="ms-link-safety"
+//        data-action="click->ms-link-safety#intercept">
+//     …rendered message, links and all…
+//     <dialog data-ms-link-safety-target="dialog">
+//       <p data-ms-link-safety-target="url"></p>
+//       <label><input type="checkbox" data-ms-link-safety-target="remember"> …</label>
+//       <button data-action="ms-link-safety#confirm">Continuar</button>
+//       <button data-action="ms-link-safety#cancel">Cancelar</button>
+//     </dialog>
+//   </div>
+//
+// Mounted on the message container rather than on each anchor: the anchors are
+// model output and the count is unbounded, and one delegated listener survives
+// a repair morph that replaces every one of them.
+export default class extends ApplicationController {
+  static targets = ["dialog", "url", "remember"]
+
+  static values = {
+    // Same origin is always followed without a prompt. Anything else is
+    // "external" unless the host allowlist or a remembered host says otherwise.
+    origin: { type: String, default: "" },
+    // Turns the whole guard off — for a host that does its own interstitial.
+    bypass: { type: Boolean, default: false },
+    // Hosts the user chose to trust, kept for the tab only. Session storage,
+    // not local: trust granted mid-conversation should not outlive it.
+    rememberKey: { type: String, default: "ms-link-safety.trusted" }
+  }
+
+  // A URL the dialog must never offer to follow, whatever the document says.
+  // The server sanitizer already drops these; a second check here costs
+  // nothing and this controller is the thing that calls `window.open`.
+  static allowedProtocols = ["http:", "https:", "mailto:"]
+
+  disconnect() {
+    this.closeDialog({ restoreFocus: false })
+  }
+
+  // ------------------------------------------------------------------ actions
+
+  // Delegated. Everything that is not an anchor with an href falls straight
+  // through to the browser.
+  intercept(event) {
+    if (event.defaultPrevented || event.button !== 0) return
+    if (event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) return
+
+    const anchor = event.target instanceof Element ? event.target.closest("a[href]") : null
+    if (!anchor || !this.element.contains(anchor)) return
+
+    const url = this.parse(anchor.getAttribute("href"))
+
+    // An href we cannot parse, or one on a protocol we refuse, is stopped
+    // here. Letting the browser have it is the one thing we must not do.
+    if (!url) {
+      event.preventDefault()
+      this.notify("link-refused", { href: anchor.getAttribute("href") })
+      return
+    }
+
+    if (this.permitted(url)) return
+
+    event.preventDefault()
+    this.ask(url, anchor)
+  }
+
+  confirm(event) {
+    event?.preventDefault()
+
+    const url = this.pending
+    if (this.hasRememberTarget && this.rememberTarget.checked && url) this.trust(url.host)
+    this.closeDialog()
+
+    if (!url) return
+    this.notify("link-followed", { href: url.href })
+    window.open(url.href, "_blank", "noopener,noreferrer")
+  }
+
+  cancel(event) {
+    event?.preventDefault()
+    const url = this.pending
+    this.closeDialog()
+    this.notify("link-cancelled", { href: url?.href })
+  }
+
+  // ------------------------------------------------------------------- policy
+
+  get origin() {
+    return this.originValue || window.location.origin
+  }
+
+  parse(href) {
+    let url
+    try {
+      url = new URL(href, this.origin)
+    } catch {
+      return null
+    }
+    return this.constructor.allowedProtocols.includes(url.protocol) ? url : null
+  }
+
+  permitted(url) {
+    if (this.bypassValue) return true
+    if (url.protocol !== "http:" && url.protocol !== "https:") return true
+    if (url.origin === this.origin) return true
+    if (this.trusted.has(url.host)) return true
+
+    // The host callback is asked last so it can only widen, never narrow, and
+    // a callback that throws denies rather than admits.
+    try {
+      return Boolean(linkSafety.allow?.(url))
+    } catch {
+      return false
+    }
+  }
+
+  get trusted() {
+    try {
+      return new Set(JSON.parse(window.sessionStorage.getItem(this.rememberKeyValue) || "[]"))
+    } catch {
+      return new Set()
+    }
+  }
+
+  trust(host) {
+    try {
+      const hosts = this.trusted
+      hosts.add(host)
+      window.sessionStorage.setItem(this.rememberKeyValue, JSON.stringify([...hosts]))
+    } catch {
+      // Private browsing. Trust simply does not persist.
+    }
+  }
+
+  // ------------------------------------------------------------------- dialog
+
+  ask(url, anchor) {
+    this.pending = url
+    this.trigger = anchor
+
+    if (!this.hasDialogTarget) {
+      // No dialog in the markup. `window.confirm` traps focus and restores it
+      // by itself, so the contract still holds.
+      if (window.confirm(url.href)) this.confirm()
+      else this.cancel()
+      return
+    }
+
+    // The href is attacker-influenced text. It is written as text, never as
+    // markup, and never into an href on the dialog itself.
+    if (this.hasUrlTarget) this.urlTarget.textContent = url.href
+    if (this.hasRememberTarget) this.rememberTarget.checked = false
+
+    // `showModal` is the focus trap: the browser makes the rest of the
+    // document inert and keeps Tab inside the dialog. Re-implementing that in
+    // JavaScript is how focus traps get holes.
+    this.dialogTarget.showModal()
+    this.boundDialogCancel ||= (event) => {
+      // Esc. Route it through `cancel` so one path closes the dialog.
+      event.preventDefault()
+      this.cancel()
+    }
+    this.dialogTarget.addEventListener("cancel", this.boundDialogCancel)
+    this.notify("link-prompted", { href: url.href })
+  }
+
+  closeDialog({ restoreFocus = true } = {}) {
+    if (this.hasDialogTarget && this.dialogTarget.open) {
+      if (this.boundDialogCancel) {
+        this.dialogTarget.removeEventListener("cancel", this.boundDialogCancel)
+      }
+      this.dialogTarget.close()
+    }
+
+    // Focus goes back where it came from, always — the anchor the user
+    // clicked, so a keyboard user is not dumped at the top of the document.
+    if (restoreFocus && this.trigger?.isConnected) this.trigger.focus()
+
+    this.pending = null
+    this.trigger = null
+  }
+}