studio-engine 0.99.0.rc1 → 0.100.0.rc1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7a72dfbacf609fb2070a5230c3ef4ca8fe2ab0b8f876de2e18894b21e3338cfc
-  data.tar.gz: ebcf585ecf8450717ad1d0cd585825777f8f656095559fefac37415d375549b5
+  metadata.gz: ccf0cc77e250c21faca747741337d7b492defe5b3af054169b2e78a89a0908a8
+  data.tar.gz: 9fcfe0bcdcfd78e53fc67e0d627cabaf40c822428d997756451ad96b11c34f2d
 SHA512:
-  metadata.gz: 823e980eb4f59d60405f349f5b6dacc104dc1c25759dd35fecfc94db7b4cbcd5c797ca241850a2f91deedf2e261d96c46a17d498993f2e19d558c189a14628d9
-  data.tar.gz: 896ee84ba92c657fe476f14dee0db16bfa2ee87eba6ec7b5d87d1e29c5e08cf20fc5ea332e2a56433e69d0120dc2f727928c59b72c1e6e6de7c2c116fa38b7c7
+  metadata.gz: 8fa59ab9b1cc9538065e73d21264a7cf49b9afb21d0a4e030091ffe4edaf19a66f511fa00a4a17c8303c0531af1866cfa94e343b7725ed40a187f605a04e7aed
+  data.tar.gz: a90ebd5d35c3f7ab4964bf7ca484d760d44d8fd9ced4c44f3f05dd3423c57c89e972685ed8bb6cadd20ee4eda313980e1312f30503b2845e3270ee27bb01b0fb

data/CHANGELOG.md

@@ -4,8 +4,123 @@ The format is [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This pro
 
 ## Unreleased
 
+## 0.100.0 — 2026-10-10
+
+### Added
+
+- **A meeting plays beside its transcript on the knowledge document page.**
+  `/admin/knowledge/:id`, in its preview frame:
+  - A document with a recording gets a native `<video>` or `<audio>` player.
+    Its source is the six-hour presigned URL (`recording_url`), written only
+    into the admin-only, `no-store` preview response; the show page holds no
+    signed URL and the app reads none of the recording.
+  - A text document that holds at least two cue lines is shown as cues (time,
+    speaker, text) in place of the preformatted block, with the plain text kept
+    under them, closed. Any other text file previews exactly as before.
+  - With a recording, a click on a cue seeks the player there and plays, and
+    the cue being spoken is marked and kept in view inside the cue list. With
+    none, the cues still render with each time as plain text.
+  - With no stored recording, an http(s) `recording_link` shows as a link that
+    opens in a new tab (`rel="noopener noreferrer"`).
+  - A document whose own file is audio or video (`mp4`, `m4v`, `mov`, `webm`,
+    `ogv`, `mp3`, `m4a`, `wav`, `ogg`, `oga`, `weba`) plays in the same player,
+    served as the type its extension names.
+
+  A transcript longer than the 256 KB text head is read a second time, up to
+  the parser's 2 MB; one preview makes two ranged reads at most. All 5,000 cues
+  the parser allows are rendered, and a transcript cut by a cap says so and
+  links the download. Speaker names and cue text are escaped.
+
+  The script is `studio/knowledge_transcript` and a `knowledge-transcript`
+  controller that `studio/stimulus` registers lazily, so a page without a
+  recording fetches neither. No migration, no setting, no new route. An app
+  without the recording columns shows no player and no link. README, *The
+  document page*, has every bound and what was measured at the caps.
+- `Studio::KnowledgePreview.player_for(doc)` (a `Player` of `kind`, `url` and
+  `error`, or nil without a recording), `.clock(seconds)`, and two more kinds
+  from `kind_for`: `:video` and `:audio`. `Result` gains `cues` and
+  `cues_truncated`, and the kind `:transcript`.
+
+### Fixed
+
+- **The style guide's Save and Regenerate toast success only when the server
+  wrote.** `studio/theme_editor` asks `/admin/theme` for JSON and counts a 2xx
+  from that request alone as saved; `ThemeSettingsController` answers the fetch
+  `204` after the write and `422` with the reason when it refuses. A redirect,
+  which the fetch does not follow, and a `401` toast "Save failed" with a
+  prompt to sign in: an ended session bounced the save to sign-in before and
+  the editor toasted "Theme saved" over nothing written. A save still sends one
+  request. A form post to `/admin/theme` keeps its redirect and flash.
+
 ## 0.99.0 — 2026-10-09
 
+### Added
+
+- **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.
+
 ### Fixed
 
 - **A modal left open no longer comes back on Back when `studio/application`
@@ -365,70 +480,6 @@ 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

@@ -1127,8 +1127,8 @@ upload carried a Content-Disposition; supply it otherwise.
 
 A knowledge document (`Studio::KnowledgeDoc`) is usually a meeting's transcript.
 Its recording can be stored beside it, in the same private bucket, so the audio
-or video does not stay on a notetaker's servers. This is the backend; the
-document page does not show a player yet.
+or video does not stay on a notetaker's servers. The document page plays it
+beside the transcript: see [The document page](#the-document-page) below.
 
 **Adopting it needs a migration.** Run `bin/rails studio_engine:install:migrations
 && bin/rails db:migrate`. It adds four nullable columns to
@@ -1277,6 +1277,91 @@ indented below and `Speaker • 0:02` with the text below, and `M:SS` or
 text per cue, never raises, and answers no cues for text that is not a
 transcript. `read(text)` answers the cues and whether a bound cut them short.
 
+### The document page
+
+`/admin/knowledge/:id` shows a meeting as its recording beside its transcript.
+Everything below is in the page's preview frame (`GET /admin/knowledge/:id/preview`,
+admin only, `Cache-Control: no-store`); the show page itself reads nothing from
+the bucket and holds no signed URL.
+
+- **The player.** A document with a recording (`recording?`) gets a native
+  `<video controls preload="metadata">`, or `<audio controls>` when the
+  recording is audio (`recording_kind`).
+- **The transcript.** A text document whose first 256 KB holds at least two cue
+  lines (`Studio::KnowledgePreview::TRANSCRIPT_MIN_CUES`) is shown as cues: the
+  time, the speaker and what was said. The same text is kept under them, closed,
+  as "Plain text", so a file read as a transcript by mistake is still readable
+  and the lines above the first cue are still on the page. Any other text file
+  previews exactly as before.
+- **Click to play.** With a recording, a click on a cue's time or its line sets
+  the player to that cue and plays. While it plays, the cue being spoken is
+  marked and kept in view inside the cue list. Only the list is ever scrolled,
+  never the page, and not for five seconds after the reader last scrolled the
+  list. Without a recording the cues still render, with each time as plain text.
+- **The external link.** A document with no stored recording whose
+  `recording_link` is an http(s) link shows "Open it where it was recorded", in
+  a new tab with `rel="noopener noreferrer"`. A stored recording is played, not
+  linked.
+- **Audio and video files.** A document whose own file is `mp4`, `m4v`, `mov`,
+  `webm`, `ogv`, `mp3`, `m4a`, `wav`, `ogg`, `oga` or `weba` plays in the same
+  player. It is served as the type its extension names (signed into the URL),
+  never as the type that was stored.
+- **Layout.** From 64rem wide the player sits beside the cues; below that it sits
+  above them. The cue list scrolls inside itself in both, so the player stays in
+  view while the lines scroll.
+
+**How the player gets its source.** The preview frame writes a presigned GET
+(`recording_url`, six hours) into the player's `src`. The alternative, an
+admin-only endpoint that redirects each request to a fresh URL, was not taken.
+It would keep the URL out of the frame's source, but not shorten its life: a
+browser that sends its later ranged requests straight to the redirected URL
+needs that URL to outlive the sitting all the same. And how each browser's
+player behaves through a cross-origin redirect is not something this gem's
+browser lane, which is Chromium only, could establish. The frame already
+writes a signed URL into a `src` for a PDF and an image; this is the same
+move with a longer life. The recording's bytes are reachable only through that
+URL, which is written only into an admin-only, `no-store` response. A page
+left open past six hours needs a reload before it will seek again.
+
+**Stored content is text.** A cue's speaker and words are escaped. The only
+attribute a cue writes is its whole number of seconds. A player's `src` is a
+URL the engine signed and checked to be http(s); the external link is
+`recording_link`, which answers http(s) links only.
+
+**The script.** `studio/knowledge_transcript` (logic, with `node:test` tests) and
+the `knowledge-transcript` controller, registered lazily by `studio/stimulus`
+like the geo manager's: a page with no recording never fetches either. The
+markup arrives inside a lazy `<turbo-frame>` and the controller connects when it
+does. If the module fails to load, the player keeps its own controls, the cues
+stay readable, and the page says click-to-play did not load.
+
+**An app without the recording columns** renders the page as before: no player,
+no link, nothing signed. A transcript still shows as cues there, since that
+needs no column.
+
+**The bounds.**
+
+| What | Bound |
+|------|-------|
+| Bucket reads for one text preview | Two ranged GETs at most: 256 KB + 1 byte, then, only when that head was cut and already holds two cues, 2 MB + 1 byte (`Studio::KnowledgeTranscript::MAX_TEXT_BYTES`). 2,359,298 bytes in all |
+| Recording bytes read by the app | None. The URL is signed locally; the browser streams by range |
+| Text parsed | 2 MB a pass, two passes (the head, then the longer read) |
+| Cues rendered | 5,000 (`MAX_CUES`), all of them; past it, or past 2 MB, a notice says the transcript is longer than shown and links the download |
+| One cue | 8 KB of text, a 120-character speaker |
+| Plain text under the cues | The first 256 KB, as a text preview shows |
+| Page size | Six times the text kept (HTML escaping at its worst) plus about 250 bytes of markup a cue. 3.6 MB for 4,951 cues of ordinary speech at the 2 MB cap; 14.7 MB for 5,000 cues of nothing but quote characters, under a 16.2 MB ceiling the suite pins |
+| Script, on connect | One pass over the cues and one sort |
+| Script, per `timeupdate` | One binary search: 13 comparisons at 5,000 cues. The page is written only when the current cue changes (two class changes and one scroll of the list) |
+
+Measured in headless Chromium on a development Mac, at 4,951 cues and 2 MB of
+text: 19,891 elements, the page loaded in 0.76 s and click-to-play was ready at
+0.90 s; a `timeupdate` inside one cue took 4 microseconds, and one that changed
+the cue 0.23 ms. Not measured: Safari, Firefox, or a phone.
+
+**Not verified against a live bucket:** that R2 answers the player's ranged
+requests on a six-hour presigned URL, and that it serves a document's own audio
+or video file with the overridden content type.
+
 ## Remote image URLs
 
 `Studio::ImageCache.validate_source_url!(url)` is the check to run before the

data/app/controllers/studio/knowledge_docs_controller.rb

@@ -121,9 +121,14 @@ module Studio
     # 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.
+    #
+    # The recording's player is rendered here too, and only here: its source
+    # is a six-hour signed URL, which belongs in this no-store response and
+    # not in the show page. Signing reads nothing from the bucket.
     def preview
       @preview = @doc.preview
-      log_preview_failure(@preview.error) if @preview.error
+      @player = Studio::KnowledgePreview.player_for(@doc)
+      [@preview.error, @player&.error].compact.each { |error| log_preview_failure(error) }
       response.headers["Cache-Control"] = "no-store"
     end
 

data/app/controllers/theme_settings_controller.rb

@@ -13,9 +13,11 @@ class ThemeSettingsController < ApplicationController
     rescue_and_log(target: @theme_setting) do
       @theme_setting.update!(theme_params)
       Rails.cache.delete("studio/theme/#{Studio.app_name}")
-      redirect_to admin_theme_path, notice: "Theme saved."
+      done "Theme saved."
     end
   rescue StandardError => e
+    return render(json: { error: e.message }, status: :unprocessable_entity) if request.format.json?
+
     @defaults = Studio.theme_config
     @preview_css = Studio::ThemeResolver.new(@theme_setting.resolved_colors).to_css
     flash.now[:alert] = "Error saving theme: #{e.message}"
@@ -24,11 +26,19 @@ class ThemeSettingsController < ApplicationController
 
   def regenerate
     Rails.cache.delete("studio/theme/#{Studio.app_name}")
-    redirect_to admin_theme_path, notice: "Theme cache cleared."
+    done "Theme cache cleared."
   end
 
   private
 
+  # The style guide saves by fetch and asks for JSON: a 204 is its proof of the
+  # write. A form post is redirected back to the editor.
+  def done(notice)
+    return head(:no_content) if request.format.json?
+
+    redirect_to admin_theme_path, notice: notice
+  end
+
   def theme_params
     params.require(:theme_setting).permit(:primary, :accent1, :accent2, :warning, :danger, :dark, :light)
   end

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

@@ -0,0 +1,22 @@
+// knowledge-transcript: a recording beside its transcript on the knowledge
+// layer's document page, on the engine's Stimulus application (studio/stimulus,
+// which reads data-studio-controller and registers this controller lazily). It
+// sits on the transcript's wrapper, which arrives inside a lazy turbo-frame:
+//
+//   <div data-studio-controller="knowledge-transcript">
+//     <video data-knowledge-player ...>   <ol data-knowledge-cues> ...
+//
+// The seeking, the marking and the following are studio/knowledge_transcript.
+import { Controller } from "@hotwired/stimulus"
+import { mountTranscript } from "studio/knowledge_transcript"
+
+export default class extends Controller {
+  connect() {
+    this.transcript = mountTranscript(this.element)
+  }
+
+  disconnect() {
+    if (this.transcript) this.transcript.destroy()
+    this.transcript = null
+  }
+}

data/app/javascript/studio/knowledge_transcript.js

@@ -0,0 +1,191 @@
+// studio/knowledge_transcript: a meeting's recording beside its transcript, on
+// the knowledge layer's document page (/admin/knowledge/:id). A click on a cue
+// seeks the player there and plays; while it plays, the cue being spoken is
+// marked and kept in view inside the cue list.
+//
+// The markup is studio/knowledge_docs/_preview_transcript:
+//
+//   <div data-studio-controller="knowledge-transcript">
+//     <video data-knowledge-player controls ...></video>
+//     <ol data-knowledge-cues>
+//       <li data-seconds="62"><button type="button">1:02</button> ...</li>
+//
+// It arrives inside a lazy <turbo-frame>, after the page has loaded; the
+// knowledge-transcript controller (registered lazily by studio/stimulus) mounts
+// it whenever the element appears. Without this module the page still works:
+// the player has its own controls and the cues are plain text.
+//
+// WHAT IT COSTS, since a transcript can hold 5,000 cues:
+//   - mounting reads each cue's data-seconds once and sorts the cues by time
+//     once (cueOrder);
+//   - a `timeupdate` (a browser fires several a second) is one binary search,
+//     MAX_SEARCH_STEPS comparisons at most whatever the cue count (cueAt), and
+//     touches the page only when the current cue CHANGED: two class writes, and
+//     one scroll of the cue list;
+//   - every cue shares the one click listener on the list.
+//
+// FOLLOWING NEVER FIGHTS THE READER. Only the cue list's own scrollTop is ever
+// written, never the page's. When the reader scrolls the list, following stops
+// for FOLLOW_PAUSE_MS after their last scroll; the scroll this module causes is
+// told apart from theirs by the position it left the list at. A click on a cue
+// resumes following at once.
+//
+// It imports nothing; test/javascript/knowledge_transcript.test.mjs loads it
+// as a data: module. Bound to the page by the knowledge-transcript controller.
+
+export const PLAYER = "[data-knowledge-player]"
+export const CUES = "[data-knowledge-cues]"
+export const CUE = "[data-seconds]"
+export const CURRENT_CLASS = "knowledge-cue-current"
+export const READY_ATTRIBUTE = "data-knowledge-transcript-ready"
+
+// How long after the reader's last scroll of the cue list following stays off.
+export const FOLLOW_PAUSE_MS = 5000
+// How far down the list's visible height a followed cue is placed.
+export const FOLLOW_OFFSET = 0.25
+// The most halvings cueAt makes: enough for 2^32 cues.
+export const MAX_SEARCH_STEPS = 32
+
+// A cue's time in seconds, or NaN for anything that is not a time.
+export function secondsOf(value) {
+  if (value === null || value === undefined || value === "") return NaN
+  const seconds = Number(value)
+  return Number.isFinite(seconds) && seconds >= 0 ? seconds : NaN
+}
+
+// The cue positions ordered by time, earliest first; cues that share a time
+// keep their page order. A transcript is nearly always in time order already,
+// but nothing promises it, and cueAt needs it. A cue with no time is left out.
+export function cueOrder(seconds) {
+  const order = []
+  for (let index = 0; index < seconds.length; index++) {
+    if (Number.isFinite(seconds[index])) order.push(index)
+  }
+  return order.sort((a, b) => (seconds[a] - seconds[b]) || (a - b))
+}
+
+// The position (in `seconds`) of the cue being spoken at `time`: the last cue,
+// by time, that has started. -1 before the first cue. A binary search over
+// `order`.
+export function cueAt(order, seconds, time) {
+  if (!Number.isFinite(time)) return -1
+  let low = 0
+  let high = order.length
+  for (let step = 0; step < MAX_SEARCH_STEPS && low < high; step++) {
+    const middle = (low + high) >>> 1
+    if (seconds[order[middle]] <= time) low = middle + 1
+    else high = middle
+  }
+  return low === 0 ? -1 : order[low - 1]
+}
+
+// Where the cue list should scroll to so the cue is in view, or null when it
+// already is. Positions are in the list's own scroll coordinates.
+//   cueTop, cueHeight: the cue;  scrollTop, viewHeight: the list's window
+export function followTop({ cueTop, cueHeight, scrollTop, viewHeight }) {
+  if (cueTop >= scrollTop && cueTop + cueHeight <= scrollTop + viewHeight) return null
+  return Math.max(0, Math.round(cueTop - viewHeight * FOLLOW_OFFSET))
+}
+
+// Whether the reader has text selected, in which case a click on a line is the
+// end of a selection and not a request to seek.
+function selecting(win) {
+  if (!win || typeof win.getSelection !== "function") return false
+  const selection = win.getSelection()
+  return !!selection && !selection.isCollapsed && String(selection).length > 0
+}
+
+// Binds one transcript. `root` holds the player and the cue list. Returns
+// { destroy, current } or null when either is missing. `now` and `win` are
+// arguments so a test can supply them.
+export function mountTranscript(root, { now = () => Date.now(), win = (typeof window === "undefined" ? null : window) } = {}) {
+  const media = root.querySelector(PLAYER)
+  const list = root.querySelector(CUES)
+  if (!media || !list) return null
+
+  const cues = Array.from(list.querySelectorAll(CUE))
+  const seconds = cues.map((cue) => secondsOf(cue.getAttribute("data-seconds")))
+  const order = cueOrder(seconds)
+
+  let current = -1
+  let pausedUntil = 0
+  // The scrollTop this module last left the list at; a scroll event that
+  // finds the list there is its own.
+  let placedAt = null
+
+  const follow = (cue) => {
+    if (now() < pausedUntil) return
+    const listBox = list.getBoundingClientRect()
+    const cueBox = cue.getBoundingClientRect()
+    const top = followTop({
+      cueTop: cueBox.top - listBox.top + list.scrollTop,
+      cueHeight: cueBox.height,
+      scrollTop: list.scrollTop,
+      viewHeight: list.clientHeight
+    })
+    if (top === null) return
+    list.scrollTop = top
+    placedAt = list.scrollTop
+  }
+
+  const mark = () => {
+    const index = cueAt(order, seconds, media.currentTime)
+    if (index === current) return
+    if (current >= 0) {
+      cues[current].classList.remove(CURRENT_CLASS)
+      cues[current].removeAttribute("aria-current")
+    }
+    current = index
+    if (index < 0) return
+    cues[index].classList.add(CURRENT_CLASS)
+    cues[index].setAttribute("aria-current", "true")
+    follow(cues[index])
+  }
+
+  const seek = (event) => {
+    const target = event.target
+    const cue = target && typeof target.closest === "function" ? target.closest(CUE) : null
+    if (!cue || !list.contains(cue)) return
+    // The time itself is a button and always seeks; the rest of the line seeks
+    // unless the click finished a text selection.
+    const onButton = typeof target.closest === "function" && !!target.closest("button")
+    if (!onButton && selecting(win)) return
+
+    const at = secondsOf(cue.getAttribute("data-seconds"))
+    if (!Number.isFinite(at)) return
+    pausedUntil = 0
+    media.currentTime = at
+    const playing = typeof media.play === "function" ? media.play() : null
+    if (playing && typeof playing.catch === "function") playing.catch(() => {})
+    mark()
+  }
+
+  const scrolled = () => {
+    if (placedAt !== null && Math.abs(list.scrollTop - placedAt) < 1) return
+    placedAt = null
+    pausedUntil = now() + FOLLOW_PAUSE_MS
+  }
+
+  media.addEventListener("timeupdate", mark)
+  media.addEventListener("seeked", mark)
+  list.addEventListener("click", seek)
+  list.addEventListener("scroll", scrolled, { passive: true })
+  root.setAttribute(READY_ATTRIBUTE, "")
+  mark()
+
+  return {
+    current: () => current,
+    destroy() {
+      media.removeEventListener("timeupdate", mark)
+      media.removeEventListener("seeked", mark)
+      list.removeEventListener("click", seek)
+      list.removeEventListener("scroll", scrolled)
+      root.removeAttribute(READY_ATTRIBUTE)
+      if (current >= 0) {
+        cues[current].classList.remove(CURRENT_CLASS)
+        cues[current].removeAttribute("aria-current")
+      }
+      current = -1
+    }
+  }
+}

data/app/javascript/studio/stimulus.js

@@ -53,7 +53,9 @@ export const schema = {
 // that must work whenever its page does is not listed here: a failed load is
 // final for the document (studio/lazy_controllers). The board is listed: a
 // board whose controller failed still renders, counts and toasts, and says that
-// its cards do not drag (data-studio-controller-failed="board").
+// its cards do not drag (data-studio-controller-failed="board"). So is the
+// knowledge transcript: a recording whose controller failed still plays from
+// its own controls, and its page says that click-to-play did not load.
 export const LAZY = {
   "board": () => import("studio/controllers/board_controller"),
   "geo-settings": () => import("studio/controllers/geo_settings_controller"),
@@ -61,7 +63,8 @@ export const LAZY = {
   "email-banner-scale": () => import("studio/controllers/email_banner_scale_controller"),
   "booking": () => import("studio/controllers/booking_controller"),
   "footer-map": () => import("studio/controllers/footer_map_controller"),
-  "survey": () => import("studio/controllers/survey_controller")
+  "survey": () => import("studio/controllers/survey_controller"),
+  "knowledge-transcript": () => import("studio/controllers/knowledge_transcript_controller")
 }
 
 export const application = Application.start(document.documentElement, schema)

data/app/javascript/studio/theme_editor.js

@@ -137,20 +137,33 @@ export function themeEditor(seed) {
 // The editor's form carries _method=patch, and sending the real method means
 // nothing depends on Rack::MethodOverride parsing a multipart fetch body.
 //
-// THE REDIRECT IS NOT FOLLOWED. The controller answers a save with a 302 back
-// to /admin/theme, and a fetch that follows a 302 keeps a PATCH a PATCH: it
-// sends the save again on every hop until the browser gives up.
+// It asks for JSON, which the controller answers with a 204 once it has
+// written. NO REDIRECT IS FOLLOWED: a fetch that follows a 302 keeps a PATCH a
+// PATCH and sends the save again on every hop.
 export function formRequest(data) {
   const override = data.get("_method")
   if (override) data.delete("_method")
-  return { method: override ? String(override).toUpperCase() : "POST", body: data, redirect: "manual" }
+  return {
+    method: override ? String(override).toUpperCase() : "POST",
+    body: data,
+    headers: { Accept: "application/json" },
+    redirect: "manual"
+  }
 }
 
-// Whether the server took the save: a 2xx, or its own redirect (which a fetch
-// told not to follow reports as an opaque redirect). A failed save is rendered
-// in place with a 422.
+// Whether the server took the save: a 2xx from the request itself. A redirect
+// (opaque, because none is followed) is the admin gate turning the request
+// away, and a refused save is a 422.
 export function saved(response) {
-  return response.ok || response.type === "opaqueredirect"
+  return response.ok === true
+}
+
+export const SIGNED_OUT = "Not signed in as an admin. Sign in and save again."
+
+// Why a response that is not a save failed, for the toast.
+export function failureReason(response) {
+  if (response.type === "opaqueredirect" || response.status === 401) return SIGNED_OUT
+  return "HTTP " + response.status
 }
 
 // x-data="dsThemeEditor({...})": style/_theme.
@@ -179,7 +192,7 @@ export function dsThemeEditor(seed) {
       const request = formRequest(new FormData(form))
       fetch(form.action, request)
         .then((res) => {
-          if (!saved(res)) throw new Error("HTTP " + res.status)
+          if (!saved(res)) throw new Error(failureReason(res))
           return res
         })
         .then(() => { this.toast("notice", label, "Saved in place — the page stayed put.") })

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

@@ -1,10 +1,22 @@
 <%# 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. %>
+    Studio::KnowledgePreview::Result), doc, and optionally player (a
+    Studio::KnowledgePreview::Player for the document's recording). Stored
+    content is only ever emitted as escaped text: a table cell, a <pre>, a
+    transcript cue, or (for a PDF, image, audio or video file) not at all,
+    the browser fetching it from a signed URL. %>
+<% player = local_assigns[:player] %>
 <%= render "studio/knowledge_docs/preview_styles" %>
+<% if player && preview.kind != :transcript %>
+  <%# A recording beside a document that is not a transcript: the player
+      alone, above whatever the file shows. A transcript places its own. %>
+  <div class="knowledge-recording" id="knowledge-recording">
+    <%= render "studio/knowledge_docs/preview_player", player: player, title: doc.title %>
+  </div>
+<% end %>
 <div id="knowledge-preview-body" data-preview-kind="<%= preview.kind %>">
   <% case preview.kind %>
+  <% when :transcript %>
+    <%= render "studio/knowledge_docs/preview_transcript", preview: preview, doc: doc, player: player %>
   <% when :table %>
     <% sheets = preview.sheets %>
     <% if sheets.size > 1 || sheets.first.name.present? %>
@@ -60,7 +72,14 @@
   <% when :image %>
     <img class="knowledge-preview-image" id="knowledge-preview-image" src="<%= preview.url %>"
          alt="<%= doc.title %>" referrerpolicy="no-referrer">
+  <% when :video, :audio %>
+    <%# The document's own file is the media. Served as the type its name
+        earned (signed into the URL), never as the type that was stored. %>
+    <%= render "studio/knowledge_docs/preview_player",
+               player: Studio::KnowledgePreview::Player.new(kind: preview.kind, url: preview.url),
+               title: doc.title, dom_id: "knowledge-preview-media" %>
   <% else %>
-    <%= render "studio/knowledge_docs/preview_fallback", reason: preview.reason, doc: doc %>
+    <%# A document that is only a recording has no file to fall back from. %>
+    <%= render "studio/knowledge_docs/preview_fallback", reason: preview.reason, doc: doc unless player && !doc.file? %>
   <% end %>
 </div>

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

@@ -0,0 +1,14 @@
+<%# One native player. locals: player (a Studio::KnowledgePreview::Player),
+    title, and optionally dom_id. The source is a signed URL the engine made;
+    nothing a document holds reaches an attribute here but its title. The
+    transcript controller finds the element by data-knowledge-player. %>
+<% dom_id = local_assigns[:dom_id] || "knowledge-player" %>
+<% if !player.playable? %>
+  <p class="knowledge-preview-note" id="knowledge-player-unavailable">The recording could not be loaded. Reload the page to try again.</p>
+<% elsif player.kind == :audio %>
+  <audio class="knowledge-player" id="<%= dom_id %>" data-knowledge-player
+         controls preload="metadata" src="<%= player.url %>" aria-label="<%= title %>"></audio>
+<% else %>
+  <video class="knowledge-player knowledge-player-video" id="<%= dom_id %>" data-knowledge-player
+         controls playsinline preload="metadata" src="<%= player.url %>" aria-label="<%= title %>"></video>
+<% end %>

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

@@ -2,7 +2,12 @@
     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. %>
+    selectors: no script, so no dependency on the host's Alpine or its CSP.
+
+    The transcript is one grid: the player beside the cues from 64rem up, and
+    above them below that. The cue list is its own scroll box in both, so the
+    player stays where it is while the lines scroll. A cue looks clickable only
+    once the controller has connected (data-knowledge-transcript-ready). %>
 <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; }
@@ -21,4 +26,35 @@
     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; }
+  .knowledge-recording { margin-bottom: .75rem; }
+  .knowledge-player { display: block; width: 100%; border-radius: .375rem; }
+  .knowledge-player-video { max-height: 70vh; background: #000; }
+  .knowledge-transcript { display: grid; gap: .75rem; grid-template-columns: minmax(0, 1fr); }
+  .knowledge-transcript-hint, .knowledge-transcript-failed { display: none; margin: .5rem 0 0; }
+  [data-knowledge-transcript-ready] .knowledge-transcript-hint { display: block; }
+  [data-studio-controller-failed~="knowledge-transcript"] .knowledge-transcript-failed { display: block; }
+  .knowledge-cues { list-style: none; margin: 0; padding: 0; overflow: auto; max-height: 70vh; overscroll-behavior: contain;
+    border: 1px solid rgb(148 163 184 / .4); border-radius: .375rem; }
+  .knowledge-cue { display: grid; grid-template-columns: 4.25rem minmax(0, 1fr); column-gap: .5rem; padding: .4rem .6rem;
+    font-size: .8rem; line-height: 1.45; border-top: 1px solid rgb(148 163 184 / .2); }
+  .knowledge-cue:first-child { border-top: 0; }
+  .knowledge-cue-time { grid-row: 1 / span 2; align-self: start; justify-self: start; padding: 0; border: 0; background: none;
+    color: inherit; font: inherit; font-variant-numeric: tabular-nums; opacity: .7; }
+  .knowledge-cue-speaker { font-weight: 600; overflow-wrap: anywhere; }
+  .knowledge-cue-text { grid-column: 2; margin: 0; white-space: pre-line; overflow-wrap: anywhere; }
+  .knowledge-cue-current { background: rgb(59 130 246 / .16); box-shadow: inset 3px 0 0 rgb(59 130 246 / .8); }
+  [data-knowledge-transcript-ready] .knowledge-cue { cursor: pointer; }
+  [data-knowledge-transcript-ready] .knowledge-cue:hover { background: rgb(148 163 184 / .14); }
+  [data-knowledge-transcript-ready] .knowledge-cue-current:hover { background: rgb(59 130 246 / .22); }
+  [data-knowledge-transcript-ready] button.knowledge-cue-time { cursor: pointer; opacity: 1; text-decoration: underline; }
+  .knowledge-transcript-plain { font-size: .8rem; }
+  .knowledge-transcript-plain > summary { cursor: pointer; opacity: .75; margin-bottom: .5rem; }
+  @media (max-width: 63.99rem) {
+    .knowledge-transcript-with-player .knowledge-player-video { max-height: 35vh; }
+    .knowledge-transcript-with-player .knowledge-cues { max-height: 50vh; }
+  }
+  @media (min-width: 64rem) {
+    .knowledge-transcript-with-player { grid-template-columns: minmax(0, 3fr) minmax(0, 2fr); align-items: start; }
+    .knowledge-transcript-with-player .knowledge-transcript-plain { grid-column: 1 / -1; }
+  }
 </style>

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

@@ -0,0 +1,59 @@
+<%# A meeting transcript as cues: the time, who spoke, what they said.
+    locals: preview (kind :transcript), doc, player (or nil).
+
+    With a playable recording the wrapper names the knowledge-transcript
+    controller (studio/knowledge_transcript): a click on a cue seeks the
+    player, and the cue being spoken is marked and kept in view. Without one
+    there is no controller and each time is plain text.
+
+    Every cue's speaker and text came out of a stored file and is emitted
+    escaped. The only attribute a cue writes is its whole number of seconds.
+
+    One listener serves every cue (the controller listens on the list), so
+    the cues carry no action attribute of their own. %>
+<% playable = player&.playable? %>
+<div class="knowledge-transcript<%= " knowledge-transcript-with-player" if player %>" id="knowledge-transcript"<% if playable %> data-studio-controller="knowledge-transcript"<% end %>>
+  <% if player %>
+    <div id="knowledge-transcript-player">
+      <%= render "studio/knowledge_docs/preview_player", player: player, title: doc.title %>
+      <% if playable %>
+        <p class="knowledge-preview-note knowledge-transcript-hint" id="knowledge-transcript-hint">Click a line to play from there.</p>
+        <p class="knowledge-preview-note knowledge-transcript-failed" id="knowledge-transcript-failed">Click-to-play could not load. The player still works; reload the page to try again.</p>
+      <% end %>
+    </div>
+  <% end %>
+  <div id="knowledge-transcript-lines">
+    <% if preview.cues_truncated %>
+      <p class="knowledge-preview-note" id="knowledge-transcript-truncated" data-transcript-truncated>
+        This transcript is longer than the page shows;
+        <%= link_to "download", admin_knowledge_doc_download_path(doc), data: { turbo: false } %> for the full file.
+      </p>
+    <% end %>
+    <ol class="knowledge-cues" id="knowledge-cues" data-knowledge-cues>
+      <% preview.cues.each do |cue| %>
+        <li class="knowledge-cue" data-seconds="<%= cue.seconds.to_i %>">
+          <% if playable %>
+            <button type="button" class="knowledge-cue-time"><%= Studio::KnowledgePreview.clock(cue.seconds) %></button>
+          <% else %>
+            <span class="knowledge-cue-time"><%= Studio::KnowledgePreview.clock(cue.seconds) %></span>
+          <% end %>
+          <span class="knowledge-cue-speaker"><%= cue.speaker %></span>
+          <p class="knowledge-cue-text"><%= cue.text %></p>
+        </li>
+      <% end %>
+    </ol>
+  </div>
+  <%# What the text preview shows for this file, kept one click away: a file
+      read as a transcript by mistake is still readable, and the lines above
+      the first cue (a title, a date) are still on the page. %>
+  <details class="knowledge-transcript-plain" id="knowledge-transcript-plain">
+    <summary>Plain text</summary>
+    <% 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>
+  </details>
+</div>

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

@@ -8,5 +8,5 @@
   </div>
 <% end %>
 <turbo-frame id="knowledge-preview">
-  <%= render "studio/knowledge_docs/preview", preview: @preview, doc: @doc %>
+  <%= render "studio/knowledge_docs/preview", preview: @preview, doc: @doc, player: @player %>
 </turbo-frame>

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

@@ -1,5 +1,6 @@
 <%# /admin/knowledge/:id — one document: metadata, access, download, the
-    inline preview, and the triage form that files it out of the inbox. %>
+    inline preview (with its recording and transcript), and the triage form
+    that files it out of the inbox. %>
 <%= render "studio/knowledge_docs/chip_styles" %>
 
 <div class="mb-4 text-sm">
@@ -34,10 +35,24 @@
   </div>
 <% end %>
 
-<% if @doc.file? %>
+<%# The recording is a second object beside the file. Both readers answer
+    "none" on a table without the recording columns, and this section then
+    renders exactly as it did before them. %>
+<% recording = @doc.recording? %>
+<% recording_link = recording ? nil : @doc.recording_link %>
+<% if @doc.file? || recording || recording_link %>
   <div id="knowledge-preview-section" class="mb-6">
-    <h2 class="font-semibold mb-2">Preview</h2>
-    <% if @doc.preview_kind %>
+    <h2 class="font-semibold mb-2"><%= @doc.file? ? "Preview" : "Recording" %></h2>
+    <% if recording_link %>
+      <%# No recording is stored, only where it lives. recording_link answers
+          http(s) links alone, so nothing else can reach this href. %>
+      <p id="knowledge-recording-link" class="text-sm mb-2">
+        The recording is not stored here.
+        <%= link_to "Open it where it was recorded", recording_link, id: "knowledge-recording-open",
+                    target: "_blank", rel: "noopener noreferrer" %>
+      </p>
+    <% end %>
+    <% if @doc.preview_kind || recording %>
       <%# 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. %>
@@ -47,7 +62,7 @@
           <%= link_to "Open it", admin_knowledge_doc_preview_path(@doc), id: "knowledge-preview-open" %>
         </p>
       </turbo-frame>
-    <% else %>
+    <% elsif @doc.file? %>
       <%# 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">

data/app/views/style/_theme.html.erb

@@ -6,7 +6,8 @@
      Save-in-place: unlike the standalone /admin/theme page (which redirects to
      itself on save), THIS section intercepts Save + Regenerate and submits them
      via fetch — the page never navigates away, the live preview stays put, and
-     the outcome is a toast. The standalone page's own redirect is unchanged.
+     the outcome is a toast. The fetch asks for JSON and the controller answers
+     it 204 once it has written; the standalone page's redirect is unchanged.
      The editor is studio/theme_editor's dsThemeEditor factory, which
      studio/alpine_shims publishes.
 

data/lib/studio/knowledge_preview.rb

@@ -2,7 +2,8 @@
 
 module Studio
   # What /admin/knowledge/:id shows of a document without a download: a
-  # workbook or CSV as tables, a PDF or image inline, text as text.
+  # workbook or CSV as tables, a PDF or image inline, text as text, a meeting
+  # transcript as timestamped cues, and an audio or video file in a player.
   #
   # NOT required by lib/studio.rb. Studio::KnowledgeDoc requires it on first
   # use, and the spreadsheet reader (nokogiri, zlib) and `csv` load later
@@ -51,6 +52,27 @@ module Studio
   #                          previews its first rows.
   #   TEXT_HEAD_BYTES        likewise for text.
   #   INLINE_MAX_BYTES       a PDF or image past this is not embedded.
+  #
+  # THE TRANSCRIPT PATH. A text file is read as today (one ranged GET of
+  # TEXT_HEAD_BYTES + 1). Only when that head was cut short AND already holds
+  # TRANSCRIPT_MIN_CUES cues is the object read a second time, up to the
+  # transcript parser's own cap:
+  #
+  #   bucket reads           at most two GETs for one preview: 256 KB + 1, then
+  #                          Studio::KnowledgeTranscript::MAX_TEXT_BYTES + 1
+  #                          (2 MB + 1). 2,359,298 bytes in all.
+  #   text parsed            the parser stops at MAX_TEXT_BYTES whatever it is
+  #                          handed; it runs once on the head and once on the
+  #                          longer read.
+  #   cues                   KnowledgeTranscript::MAX_CUES (5,000), every one
+  #                          rendered; their text is part of the 2 MB parsed,
+  #                          so it totals 2 MB at most, 8 KB a cue, and a
+  #                          speaker is 120 characters at most.
+  #   plain text kept        the same TEXT_HEAD_BYTES head a text file shows,
+  #                          rendered collapsed under the cues.
+  #
+  # An audio or video file is never read here: the browser streams it from a
+  # signed URL by range, so no size cap applies to it.
   module KnowledgePreview
     class Error < StandardError; end
     # The file is not what its name says, or is damaged. The message completes
@@ -73,6 +95,14 @@ module Studio
     DELIMITED_HEAD_BYTES  = 1 * MEGABYTE
     TEXT_HEAD_BYTES       = 256 * 1024
     INLINE_MAX_BYTES      = 100 * MEGABYTE
+    # Cue lines a text file's head must hold before it is shown as a
+    # transcript. One line that happens to read "Agenda • 9:00" is not one.
+    TRANSCRIPT_MIN_CUES   = 2
+    # How long a signed URL for an audio or video file is good for. The same
+    # six hours, for the same reason, as a recording's
+    # (Studio::KnowledgeDoc::Recording::RECORDING_URL_TTL): the player makes a
+    # new ranged request on every seek, so the URL must outlive the sitting.
+    MEDIA_URL_TTL         = 6 * 60 * 60
 
     XLSX_MIME = "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
 
@@ -82,7 +112,10 @@ module Studio
       ".pdf" => :pdf,
       ".png" => :image, ".jpg" => :image, ".jpeg" => :image, ".gif" => :image, ".webp" => :image,
       ".txt" => :text, ".md" => :text, ".markdown" => :text, ".log" => :text,
-      ".json" => :text, ".vtt" => :text, ".srt" => :text
+      ".json" => :text, ".vtt" => :text, ".srt" => :text,
+      ".mp4" => :video, ".m4v" => :video, ".mov" => :video, ".webm" => :video, ".ogv" => :video,
+      ".mp3" => :audio, ".m4a" => :audio, ".wav" => :audio, ".ogg" => :audio, ".oga" => :audio,
+      ".weba" => :audio
     }.freeze
 
     KIND_BY_MIME = {
@@ -90,7 +123,10 @@ module Studio
       "text/csv" => :delimited, "text/tab-separated-values" => :delimited,
       "application/pdf" => :pdf,
       "image/png" => :image, "image/jpeg" => :image, "image/gif" => :image, "image/webp" => :image,
-      "application/json" => :text
+      "application/json" => :text,
+      "video/mp4" => :video, "video/quicktime" => :video, "video/webm" => :video, "video/ogg" => :video,
+      "audio/mpeg" => :audio, "audio/mp4" => :audio, "audio/wav" => :audio, "audio/ogg" => :audio,
+      "audio/webm" => :audio
     }.freeze
 
     # The content type an inline object is SERVED as. Chosen here, from the
@@ -101,8 +137,14 @@ module Studio
     INLINE_TYPE_BY_EXTENSION = {
       ".pdf" => "application/pdf",
       ".png" => "image/png", ".jpg" => "image/jpeg", ".jpeg" => "image/jpeg",
-      ".gif" => "image/gif", ".webp" => "image/webp"
+      ".gif" => "image/gif", ".webp" => "image/webp",
+      ".mp4" => "video/mp4", ".m4v" => "video/mp4", ".mov" => "video/quicktime",
+      ".webm" => "video/webm", ".ogv" => "video/ogg",
+      ".mp3" => "audio/mpeg", ".m4a" => "audio/mp4", ".wav" => "audio/wav",
+      ".ogg" => "audio/ogg", ".oga" => "audio/ogg", ".weba" => "audio/webm"
     }.freeze
+    # The kinds a browser streams by range from a signed URL.
+    MEDIA_KINDS = %i[video audio].freeze
 
     Cell  = Struct.new(:text, :numeric)
     # rows is a rectangle of Cell-or-nil. row_limit is the row count the
@@ -110,14 +152,27 @@ module Studio
     Sheet = Struct.new(:name, :rows, :truncated_rows, :truncated_columns, :hidden, :row_limit,
                        keyword_init: true)
 
-    # kind: :table, :pdf, :image, :text or :fallback.
+    # kind: :table, :pdf, :image, :video, :audio, :text, :transcript or
+    # :fallback.
+    # A :transcript carries `cues` (Studio::KnowledgeTranscript::Cue, frozen)
+    # and `cues_truncated` (a bound cut the cues short), plus the same `text`
+    # head and `truncated` flag a :text result has.
     # error: the unexpected exception behind a fallback, for the caller to
     # log; nil when the fallback is an ordinary refusal.
     Result = Struct.new(:kind, :sheets, :omitted_sheets, :text, :truncated, :url, :reason, :error,
-                        keyword_init: true) do
+                        :cues, :cues_truncated, keyword_init: true) do
       def fallback? = kind == :fallback
     end
 
+    # What the page needs to play a document's recording: kind is :video or
+    # :audio and url a signed http(s) URL. When the URL could not be signed
+    # both are nil and `error` holds why, for the caller to log.
+    Player = Struct.new(:kind, :url, :error, keyword_init: true) do
+      def playable? = !url.nil?
+    end
+
+    WEB_URL = %r{\Ahttps?://}i
+
     NUMERIC_TEXT = /\A\(?[-+$€£]?\s?\d[\d,]*(\.\d+)?%?\)?\z/
 
     class << self
@@ -164,7 +219,7 @@ module Studio
         when :spreadsheet then spreadsheet(doc, storage)
         when :delimited   then delimited(doc, storage)
         when :text        then text(doc, storage)
-        when :pdf, :image then inline(doc, kind)
+        when :pdf, :image, :video, :audio then inline(doc, kind)
         else fallback(no_preview_reason(doc))
         end
       rescue TooLarge => e
@@ -178,6 +233,31 @@ module Studio
         fallback("The preview could not be built.", error: e)
       end
 
+      # The Player for a document's recording, or nil when it has none (and
+      # on a table without the recording columns). Signs a URL and reads
+      # nothing. Never raises: a URL that cannot be signed is a Player that is
+      # not playable.
+      def player_for(doc)
+        return nil unless doc.respond_to?(:recording?) && doc.recording?
+
+        url = doc.recording_url.to_s
+        # The signer only ever answers http(s). This is the last check before
+        # the value becomes a src attribute.
+        raise Error, "the recording's signed URL is not an http(s) URL" unless url.match?(WEB_URL)
+
+        Player.new(kind: doc.recording_kind == :audio ? :audio : :video, url: url)
+      rescue StandardError, LoadError => e
+        Player.new(error: e)
+      end
+
+      # 62 -> "1:02", 3725 -> "1:02:05": how a cue's time reads on the page.
+      def clock(seconds)
+        total = [seconds.to_i, 0].max
+        hours, rest = total.divmod(3600)
+        minutes, secs = rest.divmod(60)
+        hours.positive? ? format("%d:%02d:%02d", hours, minutes, secs) : format("%d:%02d", minutes, secs)
+      end
+
       # --- readers, usable without a document ---------------------------------
 
       def read_spreadsheet(bytes, **overrides)
@@ -296,19 +376,46 @@ module Studio
       end
 
       def text(doc, storage)
-        bytes = (storage || Studio::S3).download(key: doc.s3_key, max_bytes: TEXT_HEAD_BYTES + 1)
+        store = storage || Studio::S3
+        bytes = store.download(key: doc.s3_key, max_bytes: TEXT_HEAD_BYTES + 1)
         partial = bytes.bytesize > TEXT_HEAD_BYTES
-        Result.new(kind: :text, text: decode(bytes.byteslice(0, TEXT_HEAD_BYTES), partial: partial), truncated: partial)
+        head = decode(bytes.byteslice(0, TEXT_HEAD_BYTES), partial: partial)
+        transcript(doc, store, head, partial) || Result.new(kind: :text, text: head, truncated: partial)
+      end
+
+      # The :transcript Result when `head` reads as one, else nil. `head` is
+      # the text preview's own read. A head that was the whole file is all
+      # there is to parse; a head that was cut is read again, once, up to the
+      # parser's cap, because a meeting's transcript is often longer than the
+      # 256 KB a text preview shows.
+      def transcript(doc, store, head, partial)
+        require "studio/knowledge_transcript"
+        reading = Studio::KnowledgeTranscript.read(head)
+        return nil if reading.cues.size < TRANSCRIPT_MIN_CUES
+
+        cut = false
+        if partial
+          cap = Studio::KnowledgeTranscript::MAX_TEXT_BYTES
+          bytes = store.download(key: doc.s3_key, max_bytes: cap + 1)
+          cut = bytes.bytesize > cap
+          reading = Studio::KnowledgeTranscript.read(decode(bytes.byteslice(0, cap), partial: cut))
+        end
+        Result.new(kind: :transcript, cues: reading.cues, cues_truncated: cut || reading.truncated?,
+                   text: head, truncated: partial)
       end
 
       def inline(doc, kind)
-        refuse_over!(doc, INLINE_MAX_BYTES)
+        media = MEDIA_KINDS.include?(kind)
+        # A player streams by range, so an audio or video file has no size at
+        # which showing it costs more.
+        refuse_over!(doc, INLINE_MAX_BYTES) unless media
         content_type = inline_content_type(filename: doc.filename, mime_type: doc.mime_type)
         # Without a type of our choosing the URL would be signed to serve the
         # STORED type, which is the one thing this path exists to prevent.
         raise Unreadable, "its type cannot be shown inline" if content_type.nil?
 
-        Result.new(kind: kind, url: doc.signed_url(inline_as: content_type))
+        url = media ? doc.signed_url(expires_in: MEDIA_URL_TTL, inline_as: content_type) : doc.signed_url(inline_as: content_type)
+        Result.new(kind: kind, url: url)
       end
 
       def refuse_over!(doc, cap)

data/lib/studio/version.rb

@@ -1,3 +1,3 @@
 module Studio
-  VERSION = "0.99.0.rc1"
+  VERSION = "0.100.0.rc1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: studio-engine
 version: !ruby/object:Gem::Version
-  version: 0.99.0.rc1
+  version: 0.100.0.rc1
 platform: ruby
 authors:
 - Alex McRitchie
@@ -438,6 +438,7 @@ files:
 - app/javascript/studio/controllers/geo_settings_controller.js
 - app/javascript/studio/controllers/hold_button_controller.js
 - app/javascript/studio/controllers/identity_mini_controller.js
+- app/javascript/studio/controllers/knowledge_transcript_controller.js
 - app/javascript/studio/controllers/link_preview_card_controller.js
 - app/javascript/studio/controllers/link_sidebar_controller.js
 - app/javascript/studio/controllers/modal_host_controller.js
@@ -455,6 +456,7 @@ files:
 - app/javascript/studio/hold_button_hooks.js
 - app/javascript/studio/identity_mini.js
 - app/javascript/studio/image_upload.js
+- app/javascript/studio/knowledge_transcript.js
 - app/javascript/studio/lazy_controllers.js
 - app/javascript/studio/leveling_activity.js
 - app/javascript/studio/link_preview_card.js
@@ -580,8 +582,10 @@ files:
 - app/views/studio/knowledge_docs/_doc_row.html.erb
 - app/views/studio/knowledge_docs/_preview.html.erb
 - app/views/studio/knowledge_docs/_preview_fallback.html.erb
+- app/views/studio/knowledge_docs/_preview_player.html.erb
 - app/views/studio/knowledge_docs/_preview_sheet.html.erb
 - app/views/studio/knowledge_docs/_preview_styles.html.erb
+- app/views/studio/knowledge_docs/_preview_transcript.html.erb
 - app/views/studio/knowledge_docs/_upload_form.html.erb
 - app/views/studio/knowledge_docs/coverage.html.erb
 - app/views/studio/knowledge_docs/index.html.erb