maquina_stream 0.1.0

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

@@ -0,0 +1,183 @@
+import ApplicationController from "maquina_stream/controllers/application_controller"
+
+// `ms-table` — copy and download a rendered table as markdown, CSV or TSV, and
+// toggle fullscreen.
+//
+// The render post-pass already mounts this controller on the table wrapper:
+//
+//   <div data-ms-table data-controller="ms-table">
+//     <table>…</table>
+//   </div>
+//
+// It emits no controls, so a host adds them inside the wrapper:
+//
+//   <button data-ms-control data-action="ms-table#copy"
+//           data-ms-table-format-param="markdown">…</button>
+//   <button data-ms-control data-action="ms-table#download"
+//           data-ms-table-format-param="csv">…</button>
+//   <button data-ms-control data-action="ms-table#toggleFullscreen">…</button>
+//
+// The table is reconstructed from the DOM, cell by cell, using `textContent`.
+// Nothing here reads or produces HTML.
+export default class extends ApplicationController {
+  static targets = ["table"]
+
+  static classes = ["fullscreen"]
+
+  static values = {
+    tableSelector: { type: String, default: "table" },
+    filename: { type: String, default: "table" },
+    format: { type: String, default: "markdown" },
+    fullscreen: { type: Boolean, default: false }
+  }
+
+  static mimes = {
+    markdown: "text/markdown",
+    csv: "text/csv",
+    tsv: "text/tab-separated-values"
+  }
+
+  static extensions = { markdown: "md", csv: "csv", tsv: "tsv" }
+
+  connect() {
+    this.startStreamGuard()
+  }
+
+  disconnect() {
+    this.stopStreamGuard()
+  }
+
+  // ------------------------------------------------------------------ actions
+
+  copy(event) {
+    if (this.refuseWhileStreaming(event)) return
+    this.copyText(this.serialize(this.formatFrom(event)))
+  }
+
+  download(event) {
+    if (this.refuseWhileStreaming(event)) return
+
+    const format = this.formatFrom(event)
+    const extension = this.constructor.extensions[format]
+    this.downloadText(
+      this.serialize(format),
+      `${this.filenameValue}.${extension}`,
+      this.constructor.mimes[format]
+    )
+  }
+
+  toggleFullscreen(event) {
+    if (this.refuseWhileStreaming(event)) return
+    this.fullscreenValue = !this.fullscreenValue
+  }
+
+  exitFullscreen() {
+    this.fullscreenValue = false
+  }
+
+  // The Fullscreen API is not available in every embedding context (an iframe
+  // without `allowfullscreen`, for one), so the class is the source of truth
+  // and the native call is best-effort on top of it.
+  fullscreenValueChanged(fullscreen, previous) {
+    if (this.hasFullscreenClass) {
+      this.element.classList.toggle(this.fullscreenClass, fullscreen)
+    }
+
+    if (previous === undefined) return
+
+    if (fullscreen) {
+      this.element.requestFullscreen?.().catch(() => {})
+    } else if (document.fullscreenElement === this.element) {
+      document.exitFullscreen?.().catch(() => {})
+    }
+
+    this.notify("fullscreen", { fullscreen })
+  }
+
+  // Turbo caches the page as it stands. A table left fullscreen would come
+  // back that way on a restore visit.
+  teardown() {
+    this.fullscreenValue = false
+  }
+
+  // ------------------------------------------------------------------ reading
+
+  formatFrom(event) {
+    const requested = event?.params?.format || this.formatValue
+    return this.constructor.extensions[requested] ? requested : "markdown"
+  }
+
+  get tableElement() {
+    if (this.hasTableTarget) return this.tableTarget
+    try {
+      return this.element.querySelector(this.tableSelectorValue)
+    } catch {
+      return null
+    }
+  }
+
+  // `[headerRow, ...bodyRows]`, every cell a plain string. `rowSpan`/`colSpan`
+  // are not expanded: markdown tables have no such thing, and the pipeline
+  // never produces them.
+  get rows() {
+    const table = this.tableElement
+    if (!table) return []
+
+    return Array.from(table.rows).map((row) =>
+      Array.from(row.cells).map((cell) => cell.textContent.trim())
+    )
+  }
+
+  // --------------------------------------------------------------- serializing
+
+  serialize(format) {
+    const rows = this.rows
+    if (!rows.length) return ""
+
+    switch (format) {
+      case "csv": return this.delimited(rows, ",")
+      case "tsv": return this.delimited(rows, "\t")
+      default: return this.markdown(rows)
+    }
+  }
+
+  // RFC 4180. A cell is quoted when it contains the separator, a double quote,
+  // CR or LF; embedded quotes are doubled. Applied to tabs too, so a TSV cell
+  // holding a tab or a newline still round-trips through any parser that reads
+  // RFC 4180 with a tab delimiter.
+  delimited(rows, separator) {
+    const width = Math.max(...rows.map((row) => row.length))
+
+    return rows
+      .map((row) => {
+        const padded = Array.from({ length: width }, (_, i) => row[i] ?? "")
+        return padded.map((cell) => this.quote(cell, separator)).join(separator)
+      })
+      .join("\r\n")
+  }
+
+  quote(cell, separator) {
+    const needsQuotes =
+      cell.includes(separator) || cell.includes('"') || cell.includes("\n") || cell.includes("\r")
+    return needsQuotes ? `"${cell.replace(/"/g, '""')}"` : cell
+  }
+
+  // GFM pipe table. `|` is escaped as `\|` — the only escape GFM defines
+  // inside a cell — and a newline becomes `<br>`, which is what GFM itself
+  // uses, since a pipe table row cannot span lines.
+  markdown(rows) {
+    const width = Math.max(...rows.map((row) => row.length))
+    const [header, ...body] = rows
+    const line = (row) => {
+      const padded = Array.from({ length: width }, (_, i) => row[i] ?? "")
+      return `| ${padded.map((cell) => this.escapePipes(cell)).join(" | ")} |`
+    }
+
+    const separator = `| ${Array.from({ length: width }, () => "---").join(" | ")} |`
+    return [line(header), separator, ...body.map(line)].join("\n")
+  }
+
+  escapePipes(cell) {
+    return cell.replace(/\\/g, "\\\\").replace(/\|/g, "\\|").replace(/\r?\n/g, "<br>")
+  }
+}

data/app/javascript/maquina_stream/index.js

@@ -0,0 +1,59 @@
+// maquina_stream — Stimulus entrypoint.
+//
+// The engine registers its own controllers rather than relying on the host's
+// eager-load glob: the identifiers are part of the DOM contract
+// (docs/javascript.md) and must not depend on where a host puts its files.
+//
+//   import { Application } from "@hotwired/stimulus"
+//   import { registerMaquinaStreamControllers } from "maquina_stream"
+//
+//   const application = Application.start()
+//   registerMaquinaStreamControllers(application)
+//
+// Nothing here imports a third-party library. The controllers that do —
+// `ms-diagram`, `ms-math` — import lazily at render time, per the NoBuild rule
+// in CLAUDE.md.
+
+import MsAutoscrollController from "maquina_stream/controllers/ms_autoscroll_controller"
+import MsCodeController from "maquina_stream/controllers/ms_code_controller"
+import MsLinkSafetyController from "maquina_stream/controllers/ms_link_safety_controller"
+import MsDeferredController from "maquina_stream/controllers/ms_deferred_controller"
+import MsDiagramController from "maquina_stream/controllers/ms_diagram_controller"
+import MsMathController from "maquina_stream/controllers/ms_math_controller"
+import MsRepairController from "maquina_stream/controllers/ms_repair_controller"
+import MsRevealController from "maquina_stream/controllers/ms_reveal_controller"
+import MsTableController from "maquina_stream/controllers/ms_table_controller"
+
+export { linkSafety } from "maquina_stream/controllers/ms_link_safety_controller"
+
+// Identifier → controller. The identifiers are fixed by docs/javascript.md.
+export const controllers = {
+  "ms-autoscroll": MsAutoscrollController,
+  "ms-code": MsCodeController,
+  "ms-link-safety": MsLinkSafetyController,
+  "ms-deferred": MsDeferredController,
+  "ms-diagram": MsDiagramController,
+  "ms-math": MsMathController,
+  "ms-repair": MsRepairController,
+  "ms-reveal": MsRevealController,
+  "ms-table": MsTableController
+}
+
+export function registerMaquinaStreamControllers(application) {
+  Object.entries(controllers).forEach(([identifier, controller]) => {
+    application.register(identifier, controller)
+  })
+
+  // Turbo caches the page as the user left it. A controller that mutated the
+  // DOM rolls that back here rather than in `disconnect`, which also runs on
+  // ordinary navigation. See betterstimulus.com, "global teardown".
+  document.addEventListener("turbo:before-cache", () => {
+    application.controllers.forEach((controller) => {
+      if (typeof controller.teardown === "function") controller.teardown()
+    })
+  })
+
+  return application
+}
+
+export default registerMaquinaStreamControllers

data/app/views/maquina_stream/components/_attachment.html.erb

@@ -0,0 +1,139 @@
+<%# EXTRACTION CANDIDATE → maquina_components. See MaquinaStream::VENDORED_COMPONENTS %>
+<%# locals: (filename: nil, byte_size: nil, content_type: nil, url: nil, preview_url: nil, remove_path: nil, controls: {}, unnamed_label: nil, download_label: nil, download_aria_label: nil, remove_label: nil, remove_aria_label: nil, remove_confirm: nil, size_units: nil, size_format: "%{value} %{unit}", decimal_separator: ".", thumbnail_attributes: {}, download_attributes: {}, remove_attributes: {}, variant: :grid, size: :md, css_classes: "", **html_options) %>
+<%#
+  One attached file. The locals are ActiveStorage's own attribute names —
+  `filename`, `byte_size`, `content_type` — plus the two URLs the host resolved
+  (`url` for the blob, `preview_url` for a variant). AI Elements' Attachment
+  takes a `FileUIPart`; that is the AI SDK's client-side model and importing it
+  would fight the server-rendered decision. We take the visual design, not the
+  props.
+
+  Three variants:
+
+    :grid    a card — thumbnail (images) or icon glyph, then name and meta
+    :inline  a compact pill for flowing next to text
+    :list    a full-width row, name and meta on one line
+
+  The media category is derived from `content_type` here, in Ruby, never by a
+  JS utility reading the DOM.
+
+  Every label is a local, and so is every attribute that binds this markup to
+  someone's JavaScript: the thumbnail's failure hook and the download control's
+  target arrive as `thumbnail_attributes` and `download_attributes`. In this
+  engine MaquinaStream::Components::Contract supplies them (`ms-attachment`,
+  `data-ms-attachment-target`) and translates the labels; nothing about
+  maquina_stream is written down here.
+
+  `controls` switches the two affordances off individually — a control the
+  caller has not enabled, or has not named, is not rendered. An image whose
+  blob 404s must not offer a download that cannot work, which is why the
+  download control is reachable from the same controller the thumbnail reports
+  its error to.
+%>
+<%
+  filename     = local_assigns.fetch(:filename, nil).to_s
+  byte_size    = local_assigns.fetch(:byte_size, nil)
+  content_type = local_assigns.fetch(:content_type, nil).presence
+  url          = local_assigns.fetch(:url, nil).presence
+  preview_url  = local_assigns.fetch(:preview_url, nil).presence
+  remove_path  = local_assigns.fetch(:remove_path, nil).presence
+  controls     = local_assigns.fetch(:controls, nil) || {}
+  variant      = (local_assigns.fetch(:variant, nil) || :grid).to_sym
+  size         ||= :md
+
+  image     = content_type.to_s.start_with?("image/")
+  thumbnail = image && preview_url
+  label     = filename.presence || unnamed_label
+
+  downloadable = url.present? && controls.fetch(:download, true) && download_label.present?
+  removable    = remove_path.present? && controls.fetch(:remove, true) && remove_label.present?
+
+  units       = Array(size_units).presence || %w[B kB MB GB TB]
+  size_format = local_assigns.fetch(:size_format, nil).presence || "%{value} %{unit}"
+  separator   = local_assigns.fetch(:decimal_separator, nil).presence || "."
+
+  human_size =
+    if byte_size.present?
+      bytes = Integer(byte_size)
+      index = 0
+      index += 1 while bytes >= 1024**(index + 1) && index < units.length - 1
+      number =
+        if index.zero?
+          bytes.to_s
+        else
+          format("%.1f", bytes.to_f / 1024**index).sub(".", separator)
+        end
+      format(size_format, value: number, unit: units[index])
+    end
+
+  control_classes = "shrink-0 rounded px-2 py-1 text-xs text-gray-500 hover:bg-gray-100 dark:text-gray-400 dark:hover:bg-gray-800"
+
+  download_options = {
+    download: filename.presence,
+    data: { attachment_part: "download" },
+    "aria-label" => download_aria_label.presence || download_label,
+    class: control_classes
+  }.merge(download_attributes)
+
+  remove_options = {
+    method: :delete,
+    form: { data: { turbo_confirm: remove_confirm } },
+    data: { attachment_part: "remove" },
+    "aria-label" => remove_aria_label.presence || remove_label,
+    class: control_classes
+  }.merge(remove_attributes)
+
+  layout_classes = {
+    grid:   "ms-attachment--grid flex w-40 flex-col gap-2 rounded-lg border border-gray-200 bg-white p-2 text-sm dark:border-gray-800 dark:bg-gray-900",
+    inline: "ms-attachment--inline inline-flex max-w-full items-center gap-2 rounded-full border border-gray-200 bg-gray-50 px-3 py-1 text-xs dark:border-gray-800 dark:bg-gray-900",
+    list:   "ms-attachment--list flex w-full items-center gap-3 rounded-md border border-gray-200 bg-white px-3 py-2 text-sm dark:border-gray-800 dark:bg-gray-900"
+  }.fetch(variant, "ms-attachment--grid flex w-40 flex-col gap-2 rounded-lg border border-gray-200 bg-white p-2 text-sm dark:border-gray-800 dark:bg-gray-900")
+
+  attributes = component_html_options(
+    html_options,
+    own_data: {
+      component: "attachment",
+      variant: variant,
+      size: size
+    },
+    css_classes: css_classes,
+    base_classes: "ms-attachment #{layout_classes}"
+  )
+%>
+<%= tag.figure(**attributes) do %>
+  <% if thumbnail %>
+    <img src="<%= preview_url %>"
+         alt="<%= label %>"
+         loading="lazy"
+         data-attachment-part="thumbnail"
+         class="<%= variant == :grid ? "h-24 w-full rounded object-cover" : "h-8 w-8 rounded object-cover" %>"
+         <%= tag.attributes(thumbnail_attributes) %>>
+  <% else %>
+    <span data-attachment-part="icon"
+          aria-hidden="true"
+          class="flex h-8 w-8 shrink-0 items-center justify-center rounded bg-gray-100 text-xs font-medium uppercase text-gray-500 dark:bg-gray-800 dark:text-gray-400">
+      <%= File.extname(filename).delete_prefix(".").first(4).presence || "•" %>
+    </span>
+  <% end %>
+
+  <figcaption data-attachment-part="meta" class="flex min-w-0 flex-1 flex-col">
+    <span data-attachment-part="filename" class="truncate font-medium text-gray-900 dark:text-gray-100" title="<%= label %>"><%= label %></span>
+    <% if human_size || content_type %>
+      <span data-attachment-part="details" class="truncate text-xs text-gray-500 dark:text-gray-400">
+        <%= [ human_size, content_type ].compact.join(" · ") %>
+      </span>
+    <% end %>
+  </figcaption>
+
+  <% if downloadable %>
+    <%= link_to url, download_options do %>
+      <%= download_label %>
+    <% end %>
+  <% end %>
+
+  <% if removable %>
+    <%= button_to remove_path, remove_options do %>
+      <%= remove_label %>
+    <% end %>
+  <% end %>
+<% end %>

data/app/views/maquina_stream/components/_code_block.html.erb

@@ -0,0 +1,74 @@
+<%# EXTRACTION CANDIDATE → maquina_components. See MaquinaStream::VENDORED_COMPONENTS %>
+<%# locals: (lang: nil, source: "", highlighted: nil, controls: {}, copy_label: nil, copy_aria_label: nil, download_label: nil, download_aria_label: nil, source_attributes: {}, copy_attributes: {}, download_attributes: {}, variant: :default, size: :md, css_classes: "", **html_options) %>
+<%#
+  A code block: a highlighted rendering plus the raw source, verbatim, for
+  whatever offers to copy or download it.
+
+  This partial does not highlight. `highlighted` arrives already marked up by
+  the caller and is nil while a fence is still open, in which case the plain
+  source renders instead — highlighting an open fence is wasted work on every
+  frame.
+
+  Nothing here knows about maquina_stream. The engine's DOM contract
+  (`data-ms-code`, `data-ms-code-lang`, `data-ms-code-source`, the `ms-code`
+  controller and the `data-ms-control` stream guard — all fixed in
+  docs/javascript.md) arrives as `data:` and as the three `*_attributes`
+  locals, from MaquinaStream::Components::Contract. Labels arrive the same way:
+  a control with no label is not rendered, because a caller that has not named
+  a button has not asked for one.
+%>
+<%
+  lang        = local_assigns.fetch(:lang, nil)
+  source      = source.to_s
+  highlighted = local_assigns.fetch(:highlighted, nil)
+  controls    = local_assigns.fetch(:controls, nil) || {}
+  variant   ||= :default
+  size      ||= :md
+
+  copyable     = controls[:copy] && copy_label.present?
+  downloadable = controls[:download] && download_label.present?
+
+  attributes = component_html_options(
+    html_options,
+    own_data: {
+      component: "code-block",
+      variant: variant,
+      size: size
+    },
+    css_classes: css_classes,
+    base_classes: "ms-code-block relative my-4 overflow-hidden rounded-lg border border-gray-200 bg-gray-50 text-sm dark:border-gray-800 dark:bg-gray-900"
+  )
+%>
+<%= tag.div(**attributes) do %>
+  <% if lang.present? || controls.present? %>
+    <div data-code-block-part="header" class="flex items-center justify-between border-b border-gray-200 px-3 py-1.5 text-xs text-gray-500 dark:border-gray-800 dark:text-gray-400">
+      <span data-code-block-part="lang"><%= lang %></span>
+
+      <% if controls.present? %>
+        <span data-code-block-part="controls" class="flex gap-1">
+          <% if copyable %>
+            <button type="button"
+                    data-code-block-part="copy"
+                    aria-label="<%= copy_aria_label.presence || copy_label %>"
+                    class="rounded px-2 py-0.5 hover:bg-gray-200 dark:hover:bg-gray-800"
+                    <%= tag.attributes(copy_attributes) %>>
+              <%= copy_label %>
+            </button>
+          <% end %>
+          <% if downloadable %>
+            <button type="button"
+                    data-code-block-part="download"
+                    aria-label="<%= download_aria_label.presence || download_label %>"
+                    class="rounded px-2 py-0.5 hover:bg-gray-200 dark:hover:bg-gray-800"
+                    <%= tag.attributes(download_attributes) %>>
+              <%= download_label %>
+            </button>
+          <% end %>
+        </span>
+      <% end %>
+    </div>
+  <% end %>
+
+  <pre data-code-block-part="pre" class="overflow-x-auto p-3"><code data-code-block-part="code" class="font-mono"><%= highlighted.present? ? highlighted : source %></code></pre>
+  <pre hidden <%= tag.attributes(source_attributes) %>><%= source %></pre>
+<% end %>

data/app/views/maquina_stream/components/_shimmer.html.erb

@@ -0,0 +1,36 @@
+<%# Engine-owned, permanent. NOT an extraction candidate. %>
+<%# locals: (lines: 3, variant: :default, size: :md, label: nil, css_classes: "", **html_options) %>
+<%#
+  The one skeleton in the engine: open blocks and deferred payloads that have
+  not rendered yet. No ad-hoc placeholder markup exists anywhere else; if a
+  new state needs a skeleton, it renders this.
+%>
+<%
+  lines   = Integer(local_assigns.fetch(:lines, 3))
+  variant ||= :default
+  size    ||= :md
+  label   = local_assigns.fetch(:label, nil).presence ||
+            t("maquina_stream.shimmer.label", default: "Cargando…")
+
+  attributes = component_html_options(
+    html_options,
+    own_data: {
+      component: "shimmer",
+      variant: variant,
+      size: size
+    },
+    css_classes: css_classes,
+    base_classes: "ms-shimmer my-3 flex w-full flex-col gap-2"
+  )
+  attributes[:role]  ||= "status"
+  attributes["aria-busy"] ||= "true"
+  attributes["aria-live"] ||= "polite"
+%>
+<%= tag.div(**attributes) do %>
+  <span class="sr-only"><%= label %></span>
+  <% lines.times do |line| %>
+    <span data-shimmer-part="line"
+          aria-hidden="true"
+          class="ms-shimmer-line block h-3 rounded bg-gray-200 dark:bg-gray-800 <%= line == lines - 1 ? "w-2/3" : "w-full" %>"></span>
+  <% end %>
+<% end %>

data/app/views/maquina_stream/components/_snippet.html.erb

@@ -0,0 +1,50 @@
+<%# EXTRACTION CANDIDATE → maquina_components. See MaquinaStream::VENDORED_COMPONENTS %>
+<%# locals: (command: "", label: nil, prompt: "$", copy_label: nil, copy_aria_label: nil, source_attributes: {}, copy_attributes: {}, variant: :default, size: :md, css_classes: "", **html_options) %>
+<%#
+  A single command with a copy affordance, and the same raw-source carrier the
+  code block uses, so copying is exact even when the visible line is decorated
+  with a prompt.
+
+  Which controller reads that carrier, and what the copy button says, are the
+  caller's business: they arrive as `data:`, `source_attributes`,
+  `copy_attributes` and `copy_label`. In this engine that caller is
+  MaquinaStream::Components::Contract, which wires `ms-code`.
+%>
+<%
+  command = command.to_s
+  label   = local_assigns.fetch(:label, nil)
+  prompt  = local_assigns.fetch(:prompt, "$")
+  variant ||= :default
+  size    ||= :md
+
+  attributes = component_html_options(
+    html_options,
+    own_data: {
+      component: "snippet",
+      variant: variant,
+      size: size
+    },
+    css_classes: css_classes,
+    base_classes: "ms-snippet my-3 flex items-center gap-2 rounded-md border border-gray-200 bg-gray-50 px-3 py-2 font-mono text-sm dark:border-gray-800 dark:bg-gray-900"
+  )
+%>
+<%= tag.div(**attributes) do %>
+  <% if label.present? %>
+    <span data-snippet-part="label" class="font-sans text-xs text-gray-500 dark:text-gray-400"><%= label %></span>
+  <% end %>
+
+  <span data-snippet-part="prompt" aria-hidden="true" class="select-none text-gray-400"><%= prompt %></span>
+  <code data-snippet-part="command" class="flex-1 overflow-x-auto whitespace-pre"><%= command %></code>
+
+  <% if copy_label.present? %>
+    <button type="button"
+            data-snippet-part="copy"
+            aria-label="<%= copy_aria_label.presence || copy_label %>"
+            class="rounded px-2 py-1 text-xs text-gray-500 hover:bg-gray-200 dark:text-gray-400 dark:hover:bg-gray-800"
+            <%= tag.attributes(copy_attributes) %>>
+      <%= copy_label %>
+    </button>
+  <% end %>
+
+  <pre hidden <%= tag.attributes(source_attributes) %>><%= command %></pre>
+<% end %>

data/app/views/maquina_stream/components/_source_citation.html.erb

@@ -0,0 +1,42 @@
+<%# Engine-owned, permanent. NOT an extraction candidate. %>
+<%# locals: (id: nil, title: nil, href: nil, index: nil, variant: :default, size: :md, css_classes: "", **html_options) %>
+<%#
+  The reference implementation of `register_tag :source`. The model emits
+  <source id="123">Título</source>; the Nokogiri post-pass swaps that node for
+  this partial with the tag's attributes as locals.
+
+  `href` is whatever the host's finder resolved — the engine never dereferences
+  a model-supplied id itself, and an unresolved citation still renders, as
+  text, rather than vanishing.
+%>
+<%
+  id      = local_assigns.fetch(:id, nil).presence
+  title   = local_assigns.fetch(:title, nil).presence
+  href    = local_assigns.fetch(:href, nil).presence
+  index   = local_assigns.fetch(:index, nil)
+  variant ||= :default
+  size    ||= :md
+  label   = title || id || t("maquina_stream.source_citation.unknown", default: "Fuente")
+
+  attributes = component_html_options(
+    html_options,
+    own_data: {
+      component: "source-citation",
+      variant: variant,
+      size: size,
+      ms_source_id: id
+    },
+    css_classes: css_classes,
+    base_classes: "ms-source-citation inline-flex items-baseline gap-1 rounded border border-gray-200 px-1.5 text-xs text-gray-600 dark:border-gray-800 dark:text-gray-300"
+  )
+%>
+<%= tag.span(**attributes) do %>
+  <% if index.present? %>
+    <span data-source-citation-part="index" class="font-mono text-gray-400"><%= index %></span>
+  <% end %>
+  <% if href %>
+    <%= link_to label, href, data: { source_citation_part: "link" }, class: "underline underline-offset-2" %>
+  <% else %>
+    <span data-source-citation-part="label"><%= label %></span>
+  <% end %>
+<% end %>

data/app/views/maquina_stream/components/_suggestion.html.erb

@@ -0,0 +1,73 @@
+<%# EXTRACTION CANDIDATE → maquina_components. See MaquinaStream::VENDORED_COMPONENTS %>
+<%# locals: (items: [], label: nil, controls: {}, variant: :default, size: :md, css_classes: "", **html_options) %>
+<%#
+  A row of suggestion chips above a prompt input. Server-rendered, no client
+  state, no Stimulus controller: a chip is either a link the host supplied or a
+  form submission the host supplied, and the page it lands on decides what
+  happens next.
+
+  `items` is an array of hashes shaped by the host, not by the AI SDK:
+
+    { text: "Resume el hilo", href: prompts_path }                     → link
+    { text: "Resume el hilo", href: prompts_path, method: :post,
+      params: { prompt: "Resume el hilo" } }                           → form
+
+  `text` is the chip's visible label; a hash may carry `:label` when the
+  accessible name should differ from it. Anything without `text` is skipped
+  rather than rendering an empty chip.
+
+  The whole row is gated on `controls[:enabled]`, so a caller that does not
+  want suggestions turns them off once rather than in every template. In this
+  engine the caller is MaquinaStream::Components::Contract, which reads
+  `config.controls[:suggestion]` — configuration is the engine's, not this
+  component's.
+
+  `label` names the row for assistive technology, and is a local for the same
+  reason: a generic component owns no locale namespace.
+%>
+<%
+  items    = Array(local_assigns.fetch(:items, nil)).map { |item| item.to_h.symbolize_keys }
+  items    = items.select { |item| item[:text].to_s.present? }
+  label    = local_assigns.fetch(:label, nil).presence
+  controls = local_assigns.fetch(:controls, nil) || {}
+  variant  ||= :default
+  size     ||= :md
+
+  chip_classes = "ms-suggestion-chip inline-flex max-w-full items-center rounded-full border border-gray-200 bg-white px-3 py-1 text-sm text-gray-700 hover:bg-gray-50 dark:border-gray-800 dark:bg-gray-900 dark:text-gray-200 dark:hover:bg-gray-800"
+
+  attributes = component_html_options(
+    html_options,
+    own_data: {
+      component: "suggestion",
+      variant: variant,
+      size: size
+    },
+    css_classes: css_classes,
+    base_classes: "ms-suggestion flex flex-wrap gap-2"
+  )
+  attributes[:role] ||= "list"
+  attributes["aria-label"] ||= label
+%>
+<% if controls.fetch(:enabled, true) && items.any? %>
+  <%= tag.div(**attributes) do %>
+    <% items.each do |item| %>
+      <%= tag.div(role: "listitem", data: { suggestion_part: "item" }, class: "contents") do %>
+        <% if item[:method].present? && item[:method].to_sym != :get %>
+          <%= button_to item[:text],
+                item[:href],
+                method: item[:method],
+                params: item[:params],
+                data: { suggestion_part: "chip" },
+                "aria-label": item[:label].presence || item[:text],
+                class: chip_classes %>
+        <% else %>
+          <%= link_to item[:text],
+                item[:href],
+                data: { suggestion_part: "chip" },
+                "aria-label": item[:label].presence || item[:text],
+                class: chip_classes %>
+        <% end %>
+      <% end %>
+    <% end %>
+  <% end %>
+<% end %>

data/config/importmap.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+# Appended to the host's importmap by `MaquinaStream::Engine`.
+#
+# The engine pins only its own source. `@hotwired/stimulus` is the host's pin —
+# an engine that pinned it would win or lose a version fight with the app for
+# no reason. NoBuild: nothing here is compiled, bundled or fetched from npm.
+pin "maquina_stream", to: "maquina_stream/index.js"
+pin_all_from MaquinaStream::Engine.root.join("app/javascript/maquina_stream/controllers"),
+  under: "maquina_stream/controllers"