studio-engine 0.98.0 → 0.99.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: df70057457219c86f48e88b9c2f59ab83c3829a9b254901ef9a0ad3dd159875a
-  data.tar.gz: 04e7219348362718aed9a77ca418f562b2bfc71219089080c254cdd8c0f17c2c
+  metadata.gz: 5c5140413bf4edd1a888bea60b99a3ad688930302c6ea037dceef808cb233705
+  data.tar.gz: 31c5c7205a47e8c2a6366f9262c5e61425732fde284e4618450e6825e2a1a3af
 SHA512:
-  metadata.gz: cfd4f6c32ea4b45960e42acc4d678dd7ef0a7e6ee9924b32afd8ae99c9ae050a1bab09de2f8972946b6f837a248857d9ab55c985bddb6719d444eb1c0ef374f6
-  data.tar.gz: fd502cba3059ad7506989575e7c8229373857f3fc78b63917b3dfba415e13ce516771ceba9807c69dba23a1b652fa441b75b7185d07b6287d879ed13b02fee5e
+  metadata.gz: 7d7b3b42b70bccae520be5c5db88d0d3544e30aa6810349e17c056b142856f1bcde44afb2edb7e49df4fdc727a3fa750ec9ed26213df24c64dc8d825f8527eca
+  data.tar.gz: 2d55e2f7f597bbfeb3e0f628d3e435f0d77aff729b341724c3eb975eea924aa0dc72dce1c0758e48f457d52c3676185bb45af9c9d5efd03f1f61a096952ec5cd

data/CHANGELOG.md

@@ -4,6 +4,19 @@ The format is [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This pro
 
 ## Unreleased
 
+## 0.99.0 — 2026-10-09
+
+### Fixed
+
+- **A modal left open no longer comes back on Back when `studio/application`
+  fails to load.** `studio/modal_host` binds the stale-modal sweep itself, on
+  a bfcache `pageshow` and on `turbo:before-cache`, once per document, for
+  every host on the page. The `modal-host` controller bound it before, so a
+  failed boot left the stores registered and the sweep unbound. The controller
+  now registers its host's store and nothing else, so each event sweeps a
+  store once. `clearStaleModalsIn(doc, win)` is exported beside
+  `clearStaleModals(win, name)`. No markup changes.
+
 ## 0.98.0 — 2026-10-09
 
 ### Changed
@@ -352,6 +365,70 @@ The format is [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This pro
   before. A non-http(s) String raises `ArgumentError` at boot; a callable
   answering one draws no link. The link opens in a new tab with
   `rel="noopener noreferrer"`. See README, *The image generator link*.
+- **Knowledge documents preview in the page.** `/admin/knowledge/:id` gains a
+  Preview section, so reading a document no longer means downloading it:
+  - `.xlsx` and `.xlsm` workbooks render as tables, one tab per sheet. A formula
+    shows the value Excel last calculated for it, and numbers render through
+    their number format (dates, percentages, currency, accounting negatives).
+  - `.csv` and `.tsv` render as one table.
+  - PDFs and images (`png`, `jpg`, `gif`, `webp`) display inline, fetched by the
+    browser from a 15-minute signed URL.
+  - Text, markdown, JSON and caption files display as preformatted text. Stored
+    content is always escaped, never rendered as HTML.
+  - Anything else (`.xls`, `.docx`, SVG), anything over a cap, and any file that
+    will not parse shows one sentence saying why, beside the download link. The
+    page never fails on a bad file.
+
+  The section is a lazy `<turbo-frame>` over a new admin-only endpoint,
+  `GET /admin/knowledge/:id/preview` (`admin_knowledge_doc_preview_path`), so the
+  show page itself reads nothing from the bucket. It rides the existing
+  `Studio.draw_knowledge_routes` opt-in; there is no migration and no new setting.
+
+  The caps, all constants on `Studio::KnowledgePreview`:
+  - A sheet: 500 rows and 50 columns. A cell: 32,767 characters (Excel's own
+    limit; cut with a mark past it).
+  - A workbook: 20 sheets, 50,000 filled cells, 100,000 rendered cells (empty
+    ones included) and 2 MB of cell text. The sheet that spends the last of one
+    of these is cut there and says so; later sheets are counted in a notice.
+  - A workbook read as a whole: a 20 MB file; 64 MB inflated across every part
+    read (`INFLATE_BUDGET`, a part read twice counted twice); 16 MB of text handed
+    over by the XML parser, kept or not (`MAX_PARSED_TEXT_BYTES`); and 10 seconds
+    of wall-clock time (`SPREADSHEET_DEADLINE_SECONDS`). Past any of these the
+    preview falls back to the download link.
+  - What the XML parser is given, enforced on the byte stream before it
+    (`Studio::KnowledgePreview::XmlGuard`): a part must be UTF-8 and open with
+    `<`; a part with a `<!DOCTYPE` is refused; a text node or CDATA section
+    stops at 1 MB; the start tags of all elements open at once stop at 64 KB
+    together; comments and processing instructions stop at 64 KB a part;
+    nesting stops at 256 and namespace declarations at 1,024. A workbook part in
+    UTF-16, or one carrying megabyte comments, falls back to the download link.
+  - A workbook's tables: 4,096 relationships and 4,096 sheets (more is refused);
+    4,096 custom number formats and 512 distinct formats in use (past either, a
+    number renders as General). A number format longer than Excel's 255
+    characters is ignored, and no number renders past thirty decimals.
+  - The first 1 MB of a CSV, the first 256 KB of a text file, and 100 MB for an
+    inline PDF or image.
+
+  A sheet or file cut by a cap says so and links the download.
+- `Studio::KnowledgePreview` (`lib/studio/knowledge_preview.rb`), loaded on
+  first use and not by `require "studio"`: `kind_for(filename:, mime_type:)`,
+  `for(doc)` returning a `Result`, `read_spreadsheet(bytes)` and
+  `read_delimited(bytes)`. The workbook reader is the engine's own, on Zlib and
+  nokogiri; it adds no spreadsheet gem.
+- `Studio::KnowledgeDoc#preview`, `#preview_kind` and `#filename`, and
+  `#signed_url(inline_as: "application/pdf")`.
+- `Studio::S3.download(key:, max_bytes:)` reads only the head of an object (a
+  ranged GET; `max_bytes` must be a positive Integer), and `Studio::S3.signed_url`
+  takes `response_content_disposition:` and `response_content_type:`, signed into
+  the URL. Both are optional; existing calls are unchanged. The signing is tested
+  against an R2-style endpoint; that R2 serves the overridden headers is
+  documented by Cloudflare and not yet verified against a live bucket.
+
+### Changed
+
+- The gemspec declares `csv` (`>= 3.0`). It left Ruby's default gems in 3.4 and
+  the CSV preview requires it. Apps whose lockfile already names `csv` see no
+  change; the rest gain one pure-Ruby gem on their next engine bump.
 
 ### Changed
 

data/README.md

@@ -967,6 +967,16 @@ set as a pair. R2 serves nothing anonymously from its S3 endpoint, so with an
 endpoint and no `s3_public_url`, `Studio::S3.url` raises `NotConfigured` and
 `upload` writes but returns `nil`; serve private objects with `signed_url`.
 
+`signed_url` also takes `response_content_disposition:` and
+`response_content_type:`, which are signed into the URL. On S3 they override the
+headers the object is served with, and Cloudflare documents the same for R2; the
+engine's tests cover the signing against an R2-style endpoint, and nobody has yet
+verified the served headers against a live R2 bucket. `"inline"` plus a content
+type the caller chose is how the knowledge layer shows a private PDF or image in
+the page (`Studio::KnowledgeDoc#signed_url(inline_as:)`).
+`download(key:, max_bytes:)` reads only the head of an object; `max_bytes` must
+be a positive Integer.
+
 `Studio::S3.delete` moves the object to `trash/` for three days rather than
 deleting it; see [Trash and restore](#trash-and-restore).
 

data/app/controllers/studio/knowledge_docs_controller.rb

@@ -13,7 +13,7 @@ module Studio
   # deliberate second step, not a side effect of upload.
   class KnowledgeDocsController < ApplicationController
     before_action :require_admin
-    before_action :set_doc, only: [:show, :update, :download]
+    before_action :set_doc, only: [:show, :update, :download, :preview]
 
     VIEWS = %w[folders flat].freeze
 
@@ -112,8 +112,31 @@ module Studio
       redirect_to @doc.signed_url, allow_other_host: true
     end
 
+    # GET /admin/knowledge/:id/preview — the document read in the page. The
+    # show page loads this into a <turbo-frame>, so the bucket read and the
+    # parse happen here and never hold up the page itself.
+    #
+    # Always a 200: Studio::KnowledgePreview answers every failure (unknown
+    # type, over a cap, damaged, storage down) as a fallback Result carrying
+    # one sentence, rendered beside the download link. The response is
+    # no-store because it holds either the document's contents or a signed
+    # URL to them.
+    def preview
+      @preview = @doc.preview
+      log_preview_failure(@preview.error) if @preview.error
+      response.headers["Cache-Control"] = "no-store"
+    end
+
     private
 
+    # An unexpected failure behind a fallback is worth a record; a failure to
+    # record it is not worth the page.
+    def log_preview_failure(error)
+      create_error_log(error)
+    rescue StandardError => e
+      Rails.logger.warn "[knowledge preview] could not log #{error.class}: #{e.class}: #{e.message}"
+    end
+
     def expectation_params
       params.require(:knowledge_expectation)
             .permit(:entity, :title, :path, :category, :cadence, :start_on,

data/app/javascript/studio/controllers/modal_host_controller.js

@@ -14,27 +14,17 @@
 // The stack, the focus trap and the registries are studio/modal_host, which
 // registers each host's store on alpine:init (a full load, where a controller
 // connects too late) and before a Turbo render. connect() registers it too, for
-// a Turbo visit and for markup that arrived any other way, and binds the
-// bfcache and Turbo snapshot cleanup to this host while it is on the page.
-// Registered by studio/application.
+// a Turbo visit and for markup that arrived any other way. The bfcache and
+// Turbo snapshot cleanup is studio/modal_host's own binding, one per document,
+// so it holds when this controller never loads; binding it here as well would
+// sweep each store twice. Registered by studio/application.
 import { Controller } from "@hotwired/stimulus"
-import { registerModalStore, clearStaleModals } from "studio/modal_host"
+import { registerModalStore } from "studio/modal_host"
 
 export default class extends Controller {
   static values = { store: { type: String, default: "modals" }, scoped: Boolean }
 
   connect() {
-    const name = this.storeValue
-    registerModalStore(window.Alpine, { store: name, scoped: this.scopedValue }, { doc: document, win: window })
-
-    this.onPageShow = (event) => { if (event.persisted) clearStaleModals(window, name) }
-    this.onBeforeCache = () => clearStaleModals(window, name)
-    window.addEventListener("pageshow", this.onPageShow)
-    document.addEventListener("turbo:before-cache", this.onBeforeCache)
-  }
-
-  disconnect() {
-    window.removeEventListener("pageshow", this.onPageShow)
-    document.removeEventListener("turbo:before-cache", this.onBeforeCache)
+    registerModalStore(window.Alpine, { store: this.storeValue, scoped: this.scopedValue }, { doc: document, win: window })
   }
 }

data/app/javascript/studio/modal_host.js

@@ -12,7 +12,8 @@
 //   data-modal-host-store-value="modals"     (the scoped host: its own name)
 //   data-modal-host-scoped-value="true"      (the scoped host only)
 //
-// and studio/controllers/modal_host_controller binds the element's lifetime.
+// and studio/controllers/modal_host_controller registers the host's store when
+// the element connects.
 //
 // WHEN A STORE REGISTERS, AND WHY NOT IN connect(). Alpine evaluates
 // $store.<name>.current() as it starts, which is BEFORE Stimulus connects any
@@ -538,9 +539,9 @@ export function registerHostsIn(root, env) {
   for (var i = 0; i < hosts.length; i++) registerModalStore(env.win.Alpine, hosts[i], env)
 }
 
-// The bfcache and Turbo snapshot cleanup: a modal left open does not reappear
-// on the next visit, but a dismissible: false card survives (see
-// closeAllDismissible). Bound per host by the controller.
+// The bfcache and Turbo snapshot cleanup for one store: a modal left open does
+// not reappear on the next visit, but a dismissible: false card survives (see
+// closeAllDismissible).
 export function clearStaleModals(win, name) {
   if (!win.Alpine || !win.Alpine.store) return
   var store = win.Alpine.store(name)
@@ -548,7 +549,19 @@ export function clearStaleModals(win, name) {
   else if (store && typeof store.closeAll === 'function') store.closeAll()
 }
 
-// Installs the globals and the three registration paths, once per document.
+// Sweeps the store of every host on the page, each store once.
+export function clearStaleModalsIn(doc, win) {
+  var hosts = hostsIn(doc)
+  var swept = []
+  for (var i = 0; i < hosts.length; i++) {
+    if (swept.indexOf(hosts[i].store) !== -1) continue
+    swept.push(hosts[i].store)
+    clearStaleModals(win, hosts[i].store)
+  }
+}
+
+// Installs the globals, the three registration paths and the stale-modal
+// sweep, once per document.
 var installedOn = new WeakSet()
 
 export function installModalHost(doc, win) {
@@ -565,6 +578,13 @@ export function installModalHost(doc, win) {
   doc.addEventListener('turbo:before-frame-render', function (event) {
     if (event.detail) registerHostsIn(event.detail.newFrame, env)
   })
+  // THE SWEEP IS BOUND HERE, the one place, and not by the controller: this
+  // module loads by its own tag, so the sweep survives a boot that fails to
+  // load, and one binding per document sweeps each store once per event.
+  win.addEventListener('pageshow', function (event) {
+    if (event.persisted) clearStaleModalsIn(doc, win)
+  })
+  doc.addEventListener('turbo:before-cache', function () { clearStaleModalsIn(doc, win) })
   // Alpine already running (a host that loads it ahead of the module tags).
   if (win.Alpine && win.Alpine.version) registerHostsIn(doc, env)
 }

data/app/models/studio/knowledge_doc.rb

@@ -167,10 +167,45 @@ module Studio
     end
 
     # 15-minute presigned GET — the only way a private object leaves the bucket.
-    def signed_url(expires_in: 900)
+    #
+    # inline_as: a content type. The URL then serves the object with
+    # Content-Disposition: inline and THAT type, whatever was stored, which is
+    # what lets the show page embed a PDF or an image (Studio::KnowledgePreview
+    # picks the type from the file's kind, never from mime_type).
+    def signed_url(expires_in: 900, inline_as: nil)
       raise Studio::S3::Error, "no file attached to #{title.inspect}" unless file?
 
-      Studio::S3.signed_url(key: s3_key, expires_in: expires_in)
+      if inline_as
+        Studio::S3.signed_url(key: s3_key, expires_in: expires_in,
+                              response_content_disposition: "inline", response_content_type: inline_as)
+      else
+        Studio::S3.signed_url(key: s3_key, expires_in: expires_in)
+      end
+    end
+
+    # The stored object's file name (the upload's name, sanitized, behind the
+    # key's timestamp prefix). There is no filename column; the key carries it.
+    def filename
+      File.basename(s3_key.to_s)
+    end
+
+    # --- preview ----------------------------------------------------------------
+
+    # :spreadsheet, :delimited, :pdf, :image, :text, or nil when the show page
+    # can only offer the download. Reads nothing from the bucket.
+    def preview_kind
+      return nil unless file?
+
+      require "studio/knowledge_preview"
+      Studio::KnowledgePreview.kind_for(filename: filename, mime_type: mime_type)
+    end
+
+    # The Studio::KnowledgePreview::Result for this document. Reads the
+    # bucket, so the show page loads it lazily (KnowledgeDocsController#preview)
+    # rather than calling it inline. Never raises.
+    def preview
+      require "studio/knowledge_preview"
+      Studio::KnowledgePreview.for(self)
     end
 
     # --- lifecycle ------------------------------------------------------------

data/app/views/studio/knowledge_docs/_preview.html.erb

@@ -0,0 +1,66 @@
+<%# A document's inline preview, by kind. locals: preview (a
+    Studio::KnowledgePreview::Result), doc. Stored content is only ever
+    emitted as escaped text: a table cell, a <pre>, or (for a PDF or image)
+    not at all, the browser fetching it from a signed URL. %>
+<%= render "studio/knowledge_docs/preview_styles" %>
+<div id="knowledge-preview-body" data-preview-kind="<%= preview.kind %>">
+  <% case preview.kind %>
+  <% when :table %>
+    <% sheets = preview.sheets %>
+    <% if sheets.size > 1 || sheets.first.name.present? %>
+      <%# One radio per sheet, then the tabs, then the panels: all siblings,
+          so :checked can reach both the tab's look and the panel's display. %>
+      <style>
+        <% sheets.each_index do |index| %>
+          #knowledge-sheet-radio-<%= index %>:checked ~ .knowledge-sheet-tabs label[for="knowledge-sheet-radio-<%= index %>"] { opacity: 1; font-weight: 600; background: rgb(148 163 184 / .18); }
+          #knowledge-sheet-radio-<%= index %>:checked ~ .knowledge-sheet-panels #knowledge-sheet-panel-<%= index %> { display: block; }
+        <% end %>
+      </style>
+      <% sheets.each_index do |index| %>
+        <input type="radio" name="knowledge-sheet" class="knowledge-sheet-radio"
+               id="knowledge-sheet-radio-<%= index %>"<%= " checked".html_safe if index.zero? %>>
+      <% end %>
+      <div class="knowledge-sheet-tabs" id="knowledge-sheet-tabs">
+        <% sheets.each_with_index do |sheet, index| %>
+          <label class="knowledge-sheet-tab" for="knowledge-sheet-radio-<%= index %>"><%= sheet.name.presence || "Sheet #{index + 1}" %><%= " (hidden)" if sheet.hidden %></label>
+        <% end %>
+      </div>
+      <% if preview.omitted_sheets.to_i.positive? %>
+        <p class="knowledge-preview-note" id="knowledge-preview-omitted-sheets">
+          <%= pluralize(preview.omitted_sheets, "more sheet") %> not shown;
+          <%= link_to "download", admin_knowledge_doc_download_path(doc), data: { turbo: false } %> for the full file.
+        </p>
+      <% end %>
+      <div class="knowledge-sheet-panels">
+        <% sheets.each_with_index do |sheet, index| %>
+          <div class="knowledge-sheet-panel" id="knowledge-sheet-panel-<%= index %>">
+            <%= render "studio/knowledge_docs/preview_sheet", sheet: sheet, doc: doc %>
+          </div>
+        <% end %>
+      </div>
+    <% else %>
+      <%= render "studio/knowledge_docs/preview_sheet", sheet: sheets.first, doc: doc %>
+    <% end %>
+  <% when :text %>
+    <% if preview.truncated %>
+      <p class="knowledge-preview-note" data-preview-truncated>
+        Showing the start of this file;
+        <%= link_to "download", admin_knowledge_doc_download_path(doc), data: { turbo: false } %> for the full file.
+      </p>
+    <% end %>
+    <pre class="knowledge-preview-text" id="knowledge-preview-text"><%= preview.text %></pre>
+  <% when :pdf %>
+    <%# No sandbox attribute, on purpose: a sandboxed frame does not get
+        Chromium's built-in PDF viewer, so the document would not show. What
+        guards this frame is that the bucket serves the object as
+        application/pdf whatever was stored (signed into the URL), from the
+        bucket's own origin, which holds no session of this app. %>
+    <iframe class="knowledge-preview-pdf" id="knowledge-preview-pdf" src="<%= preview.url %>"
+            title="<%= doc.title %>" referrerpolicy="no-referrer" loading="lazy"></iframe>
+  <% when :image %>
+    <img class="knowledge-preview-image" id="knowledge-preview-image" src="<%= preview.url %>"
+         alt="<%= doc.title %>" referrerpolicy="no-referrer">
+  <% else %>
+    <%= render "studio/knowledge_docs/preview_fallback", reason: preview.reason, doc: doc %>
+  <% end %>
+</div>

data/app/views/studio/knowledge_docs/_preview_fallback.html.erb

@@ -0,0 +1,9 @@
+<%# The preview that could not be shown: one plain sentence and the same
+    download link the page header carries. locals: reason, doc. %>
+<p id="knowledge-preview-fallback" class="knowledge-preview-note">
+  <%= reason %>
+  <% if doc.file? %>
+    <%= link_to "Download it instead (15-min link)", admin_knowledge_doc_download_path(doc),
+                id: "knowledge-preview-download", data: { turbo: false } %>
+  <% end %>
+</p>

data/app/views/studio/knowledge_docs/_preview_sheet.html.erb

@@ -0,0 +1,43 @@
+<%# One sheet (or a whole CSV) as a grid: column letters across the top and
+    row numbers down the side, as the spreadsheet itself shows them, so a
+    figure can be named by its cell. locals: sheet (KnowledgePreview::Sheet),
+    doc. Every cell is escaped text. %>
+<% width = sheet.rows.first.to_a.size %>
+<% if sheet.truncated_rows || sheet.truncated_columns %>
+  <p class="knowledge-preview-note" data-preview-truncated>
+    Showing the first
+    <%= [ ("#{number_with_delimiter(sheet.row_limit)} rows" if sheet.truncated_rows),
+          ("#{width} columns" if sheet.truncated_columns) ].compact.to_sentence %>;
+    <%= link_to "download", admin_knowledge_doc_download_path(doc), data: { turbo: false } %> for the full file.
+  </p>
+<% end %>
+<% if sheet.rows.empty? %>
+  <p class="knowledge-preview-note" data-preview-empty>This sheet is empty.</p>
+<% else %>
+  <div class="knowledge-preview-scroll">
+    <table class="knowledge-preview-table">
+      <thead>
+        <tr>
+          <th></th>
+          <% width.times do |index| %>
+            <th scope="col"><%= Studio::KnowledgePreview.column_letter(index) %></th>
+          <% end %>
+        </tr>
+      </thead>
+      <tbody>
+        <% sheet.rows.each_with_index do |row, index| %>
+          <tr>
+            <th scope="row"><%= index + 1 %></th>
+            <% row.each do |cell| %>
+              <% if cell %>
+                <td<%= ' class="knowledge-cell-number"'.html_safe if cell.numeric %>><%= cell.text %></td>
+              <% else %>
+                <td></td>
+              <% end %>
+            <% end %>
+          </tr>
+        <% end %>
+      </tbody>
+    </table>
+  </div>
+<% end %>

data/app/views/studio/knowledge_docs/_preview_styles.html.erb

@@ -0,0 +1,24 @@
+<%# The preview's look. A scoped style block, like the chip styles, because a
+    host's Tailwind build may not scan this gem's views. Colours are slate at
+    low alpha over whatever the host paints, so one definition reads in a
+    light theme and a dark one. The sheet tabs are radio buttons and sibling
+    selectors: no script, so no dependency on the host's Alpine or its CSP. %>
+<style>
+  .knowledge-preview-note { font-size: .8rem; opacity: .75; margin: 0 0 .5rem; }
+  .knowledge-preview-scroll { overflow: auto; max-height: 70vh; border: 1px solid rgb(148 163 184 / .4); border-radius: .375rem; }
+  .knowledge-preview-table { border-collapse: collapse; font-size: .8rem; line-height: 1.3; font-variant-numeric: tabular-nums; }
+  .knowledge-preview-table th, .knowledge-preview-table td { border: 1px solid rgb(148 163 184 / .3); padding: .2rem .5rem;
+    white-space: pre; max-width: 28rem; overflow: hidden; text-overflow: ellipsis; text-align: left; vertical-align: top; }
+  .knowledge-preview-table th { background: rgb(148 163 184 / .14); font-weight: 500; opacity: .8; text-align: center; }
+  .knowledge-preview-table td.knowledge-cell-number { text-align: right; }
+  .knowledge-preview-text { overflow: auto; max-height: 70vh; margin: 0; padding: .75rem; font-size: .8rem; line-height: 1.45;
+    white-space: pre-wrap; overflow-wrap: anywhere; border: 1px solid rgb(148 163 184 / .4); border-radius: .375rem; }
+  .knowledge-preview-pdf { display: block; width: 100%; height: 80vh; border: 1px solid rgb(148 163 184 / .4); border-radius: .375rem; }
+  .knowledge-preview-image { display: block; max-width: 100%; height: auto; border: 1px solid rgb(148 163 184 / .4); border-radius: .375rem; }
+  .knowledge-sheet-radio { position: absolute; opacity: 0; pointer-events: none; }
+  .knowledge-sheet-tabs { display: flex; flex-wrap: wrap; gap: .25rem; margin-bottom: .5rem; }
+  .knowledge-sheet-tab { padding: .2rem .65rem; font-size: .8rem; cursor: pointer; white-space: nowrap;
+    border: 1px solid rgb(148 163 184 / .4); border-radius: .375rem; opacity: .7; }
+  .knowledge-sheet-panel { display: none; }
+  .knowledge-sheet-radio:focus-visible ~ .knowledge-sheet-tabs { outline: 2px solid rgb(59 130 246 / .7); outline-offset: 2px; }
+</style>

data/app/views/studio/knowledge_docs/preview.html.erb

@@ -0,0 +1,12 @@
+<%# /admin/knowledge/:id/preview — the body the show page's turbo-frame loads.
+    The frame tag is written by hand so the view needs no Turbo helper. Opened
+    directly (a browser without Turbo follows the frame's own link here), it
+    is a small page of its own with a way back. %>
+<% unless request.headers["Turbo-Frame"].present? %>
+  <div class="mb-4 text-sm">
+    <%= link_to "← #{@doc.title}", admin_knowledge_doc_path(@doc) %>
+  </div>
+<% end %>
+<turbo-frame id="knowledge-preview">
+  <%= render "studio/knowledge_docs/preview", preview: @preview, doc: @doc %>
+</turbo-frame>

data/app/views/studio/knowledge_docs/show.html.erb

@@ -1,5 +1,5 @@
-<%# /admin/knowledge/:id — one document: metadata, access, download, and the
-    triage form that files it out of the inbox. %>
+<%# /admin/knowledge/:id — one document: metadata, access, download, the
+    inline preview, and the triage form that files it out of the inbox. %>
 <%= render "studio/knowledge_docs/chip_styles" %>
 
 <div class="mb-4 text-sm">
@@ -34,6 +34,30 @@
   </div>
 <% end %>
 
+<% if @doc.file? %>
+  <div id="knowledge-preview-section" class="mb-6">
+    <h2 class="font-semibold mb-2">Preview</h2>
+    <% if @doc.preview_kind %>
+      <%# Lazy: the frame fetches the preview once it scrolls into view, so
+          this page never waits on a bucket read or a parse. Without Turbo
+          the link inside is the way in. %>
+      <turbo-frame id="knowledge-preview" loading="lazy" src="<%= admin_knowledge_doc_preview_path(@doc) %>">
+        <p class="text-sm opacity-70">
+          Loading the preview…
+          <%= link_to "Open it", admin_knowledge_doc_preview_path(@doc), id: "knowledge-preview-open" %>
+        </p>
+      </turbo-frame>
+    <% else %>
+      <%# A kind with no preview is known from the row alone: say so here
+          rather than spend a request to learn it. %>
+      <p id="knowledge-preview-fallback" class="text-sm opacity-70">
+        There is no inline preview for this kind of file.
+        <%= link_to "Download it instead (15-min link)", admin_knowledge_doc_download_path(@doc), id: "knowledge-preview-download" %>
+      </p>
+    <% end %>
+  </div>
+<% end %>
+
 <div id="knowledge-triage" class="p-4 border rounded">
   <h2 class="font-semibold mb-3">File it</h2>
   <%= form_with url: admin_knowledge_doc_path(@doc), method: :patch, local: true do |form| %>