studio-engine 0.95.0 → 0.96.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1714a5594192d5463c4c2597efd50d5821b4f608dc6ad6b38f576133e7abdd36
-  data.tar.gz: 83da688d462f1a56dda9a7a62029860ae9803496a29262faa53c9cf8a8b27717
+  metadata.gz: f7dde1a30b166a051c73369b581da7849d842cbca707c106ee331563b88ebf5a
+  data.tar.gz: b5f02ca221a1f0e623eb6524f5d99874e4f40c22ff7ab5a1f2241f4a4893a6e3
 SHA512:
-  metadata.gz: 8654bb4ff77ee2b2e6af6a3ab5b89b27328538b9c9a962788bcc8565504ce97662ae18d66bb5498619cc622f7be8c213f878eb361a0301d24042ae96ea44e69f
-  data.tar.gz: 73c9d8465a52f47fe74570f13fdc2e042ed25addb982ea4f7620f599e45f7e7f260c71bb5581b2afb6eb76642c9bf12926aac57cf95de539ffefd69f4d066fc3
+  metadata.gz: c631412bfcc7c90633dd0c7b8bcab6422dc923e5f4c8dc32d26aae01d1868179f290913fe3448656a12a097cfc70b19ca9cf9d5ea26e057e7cd9e9baaa4c3904
+  data.tar.gz: 82a12672dec7dee2b1a0fc86a9c1b2c0a13e79b5ee0cb22437156b8fc93749515b21ebd457811e7c3b8063a23b3adf6201613332c8e8eaeb2d27bfce5edd5223

data/CHANGELOG.md

@@ -4,6 +4,118 @@ The format is [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This pro
 
 ## Unreleased
 
+## 0.96.0 — 2026-10-08
+
+### Added
+
+- **A knowledge document can hold its meeting's recording.** The backend only;
+  no page changes yet. `Studio::KnowledgeDoc` gains:
+  - `attach_recording!(path, filename: nil, source_url: nil)`: copies a local
+    audio or video file into the app's private bucket beside the document, in
+    16 MB parts, never whole in memory, and saves the row. Replacing a
+    recording moves the old object to `trash/` (`Studio::S3.delete`).
+  - `attach_recording_from_url!(url, filename: nil, source_url: nil)`: the same,
+    from an https download on port 443. Every hop goes through the engine's SSRF
+    guard (`Studio::ImageCache.vet_source_url!`) and connects to the address it
+    was vetted against. A download that ends short of its declared length, or
+    before a chunked body's last chunk, fails and stores nothing. Nothing of
+    the download URL is stored, printed or used as a name.
+  - `recording?`, `recording_kind` (`:video` or `:audio`), `recording_link` (the
+    external page, only when it is an http(s) link) and
+    `recording_url(expires_in:)`, a presigned GET good for six hours by default
+    (`RECORDING_URL_TTL`).
+
+  Only MP4, M4V, MOV, M4A, WebM, MP3, WAV and Ogg are stored, judged by the
+  file's first bytes; the stored content type comes from that check, never from
+  a remote server's header. A recording may be up to 4 GB. An operator attaches
+  one with `bin/rails studio:knowledge:attach_recording ID=<id> FILE=<path>` (or
+  `URL=<https url>`, or `URL=-` to read the URL from standard input and keep it
+  off the command line). README, *Knowledge recordings*, walks every phase of a
+  fetch and of an upload with its time bound, its size bound and what a failure
+  leaves behind.
+
+  **Adopting it needs a migration:** `bin/rails studio_engine:install:migrations
+  && bin/rails db:migrate` adds `recording_key`, `recording_mime_type`,
+  `recording_byte_size` and `recording_source_url` to `studio_knowledge_docs`.
+  An app that has not run it keeps working: `recording?` is false, and only the
+  two attach methods raise (`MissingRecordingColumns`, naming the fix).
+
+  The multipart upload is tested against a stubbed client only. That a live R2
+  bucket accepts it is not yet verified.
+- `Studio::S3::Multipart.upload_file(key:, path:, content_type:, max_bytes:)`
+  (`require "studio/s3/multipart"`), a streaming multipart upload of a local
+  file. It uses its own client with `request_checksum_calculation` and
+  `response_checksum_validation` at `when_required` and sends a Content-MD5 with
+  each part; `Studio::S3.client` is unchanged. The upload is aborted on any
+  error or signal, and an object whose size cannot be confirmed is deleted.
+- `Studio::KnowledgeTranscript.parse(text)` (`require
+  "studio/knowledge_transcript"`): transcript text to cues of `seconds`,
+  `speaker` and `text`, for both layouts the layer holds (`0:02 - Speaker` with
+  the text indented below, and `Speaker • 0:02` with the text below), with
+  `M:SS` and `H:MM:SS` stamps. It reads at most 2 MB and 5,000 cues, never
+  raises, and answers no cues for text that is not a transcript. `read(text)`
+  also says whether a bound cut the reading short.
+- **An "Email image generator" link at the top of `/admin/emails`, set per
+  app.** `config.email_manager_generator_url` takes an http(s) URL or a callable
+  that receives the request; `email_manager_generator_label` (default "Email image
+  generator") and `email_manager_generator_description` override the wording.
+  Unset, nil or blank draws nothing, and the page renders byte-for-byte as
+  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*.
+
+### Changed
+
+- **The modal host and the scoped host move to an ES module and a Stimulus
+  controller.** `studio/modals/_host` and `studio/modals/_scoped_host` render
+  markup and styles only; their inline scripts (the shared host's store,
+  registry and cleanup, the load convention it rendered, and the scoped host's
+  copy of the stack) are gone. The stacks, the focus trap both share, the
+  animation and card-width registries and `holdAtLeast` are `studio/modal_host`,
+  with `node:test` unit tests; each host's `<template>` carries
+  `data-studio-controller="modal-host"` and `data-modal-host-store-value`
+  (the scoped host adds `data-modal-host-scoped-value="true"`), and the
+  `modal-host` controller binds the bfcache and Turbo snapshot cleanup to it.
+  `layouts/studio/_head` imports `studio/modal_host` by its own nonced module
+  tag, as it does `studio/alpine_stores`, so a failed boot keeps the stores.
+  Stores register on `alpine:init`, before a Turbo render, and on connect, and
+  only where a host renders: an app with no shared host still has no
+  `$store.modals`. `$store.modals`, every scoped `$store.<name>`,
+  `window.ModalAnimations` and `window.StudioModals` keep their names and API.
+- **`window.ModalAnimations` and `window.StudioModals` (`CARD_WIDTHS`,
+  `DEFAULT_CARD_WIDTH`, `MIN_LOAD_MS`, `holdAtLeast`) are published on every
+  page**, once the document has parsed, merged over whatever the app defined
+  first. They were published only by a host's inline script, so an app's
+  definition had to come before the host render; anywhere in the page works now.
+- **`studio/modals/_load_convention` renders nothing.** The convention it carried
+  is `studio/modal_host`'s; the partial stays so a render of it by name still
+  resolves.
+
+### Breaking
+
+- **A direct write to a persisted `Sluggable` slug is invalid.** `update(slug:)`,
+  or assigning `slug` and saving, on a row that already has a slug fails
+  validation with `errors[:slug]` of kind `:readonly` ("changes only through
+  rename_slug!"); `update!` and `save!` raise `ActiveRecord::RecordInvalid`.
+  Change a slug with `rename_slug!` or `rename_slug`, which also cascade to the
+  child columns. Filling a blank slug and writes that skip validations
+  (`update_column`, `update_all`) are unaffected.
+
+### Fixed
+
+- **The component gallery is not mounted when lookbook loads before
+  studio-engine.** A host that lists `gem "lookbook"` above `gem "studio-engine"`
+  drew the gallery anyway; it now draws no gallery or asset route, and the boot
+  warning says so and names the fix: move `gem "lookbook"` below
+  `gem "studio-engine"` in the Gemfile and restart.
+- **`--color-danger-ink` clears AA on its own 10% tint.** It was derived
+  against the theme surfaces only, so `bg-danger/10 text-danger-ink` (the danger
+  badge and chip) measured 4.10:1 light and 4.18:1 dark; it now counts its tint
+  as the warning and success inks do, and measures 4.61:1 and 4.53:1. The default
+  ink moves from `#BA3535` to `#AC3131` (light) and `#F48484` to `#F58F8F`
+  (dark). A consumer test that pins either hex, or that expects danger-ink to
+  fail on a danger tint, needs updating.
+
 ## 0.95.0 — 2026-10-07
 
 ### Security
@@ -127,24 +239,8 @@ The format is [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This pro
 
 ## 0.93.0 — 2026-10-07
 
-## 0.92.2 — 2026-10-07
-
-## 0.92.1 — 2026-10-07
-
 ### Added
 
-- **The engine owns `error_logs`, `theme_settings` and `image_caches`.** Three
-  migrations (`ensure_error_logs_table`, `ensure_theme_settings_table`,
-  `ensure_image_caches_table`) create each table when it is absent and, on an app
-  that already has it, add only the engine columns it lacks, as nullable columns;
-  nothing is altered or dropped and no index is added. Adopt with
-  `bin/rails studio_engine:install:migrations` and `bin/rails db:migrate`; the
-  release's lock bump does both. Hosts no longer copy these tables from
-  `docs/NEW_APP_SETUP.md`.
-- **A boot check names a missing engine column** (`Studio::HostSchema`). It
-  raises `Studio::HostSchemaError` in development and test, and logs (and reports
-  to Sentry) in production; `Studio.host_schema_check = :raise | :log | false`
-  overrides. Extra host columns are never reported, and rake tasks skip it.
 - **`Sluggable#rename_slug!` changes a slug on purpose and cascades.** It updates
   the row and every child column that holds the old slug in one transaction:
   each `has_many`/`has_one` declared with `primary_key: :slug`, plus the pairs a
@@ -166,6 +262,25 @@ The format is [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This pro
   Code that relied on a save moving the slug calls `rename_slug!(name_slug)`
   instead.
 
+## 0.92.2 — 2026-10-07
+
+## 0.92.1 — 2026-10-07
+
+### Added
+
+- **The engine owns `error_logs`, `theme_settings` and `image_caches`.** Three
+  migrations (`ensure_error_logs_table`, `ensure_theme_settings_table`,
+  `ensure_image_caches_table`) create each table when it is absent and, on an app
+  that already has it, add only the engine columns it lacks, as nullable columns;
+  nothing is altered or dropped and no index is added. Adopt with
+  `bin/rails studio_engine:install:migrations` and `bin/rails db:migrate`; the
+  release's lock bump does both. Hosts no longer copy these tables from
+  `docs/NEW_APP_SETUP.md`.
+- **A boot check names a missing engine column** (`Studio::HostSchema`). It
+  raises `Studio::HostSchemaError` in development and test, and logs (and reports
+  to Sentry) in production; `Studio.host_schema_check = :raise | :log | false`
+  overrides. Extra host columns are never reported, and rake tasks skip it.
+
 ### Fixed
 
 - **A theme save no longer raises on apps without `theme_settings.slug`**

data/README.md

@@ -35,7 +35,7 @@ resolved.
 - **Theme system**: Dynamic CSS custom properties generated from 7 role colors (primary, dark, light, success, accent, warning, danger). Dark/light mode toggle. Admin theme editor at `/admin/theme`.
 - **UI primitives**: Shared component partials and CSS primitives such as `components/emoji_swap` for nav/sidebar emoji hover transitions.
 - **Operator tooling**: Shared `studio/banners/environment` banner with Dev Mode + email connector controls and `studio/banners/impersonation`.
-- **Sluggable concern**: a human-readable slug written once at create (`to_param` returns it); `rename_slug!` changes it and cascades to every child column in one transaction, and a refused rename answers 422
+- **Sluggable concern**: a human-readable slug written once at create (`to_param` returns it); `rename_slug!` changes it and cascades to every child column in one transaction, any other write that changes a persisted slug is invalid, and a refused rename answers 422
 - **ThemeSetting model**: Per-app DB overrides with fallback to config defaults
 - **Geo**: `Studio::GeoDetection` places every visitor (IP → country + subdivision, session-cached), `Studio::GeoSetting` stores the operator's blocked countries and regions, `require_geo_allowed` locks whichever surfaces an app chooses, and the shared badge + `/admin/geo` manager ship with it. See [`docs/GEO.md`](docs/GEO.md).
 - **Site identity and link previews**: `Studio::SiteIdentity` holds the app's title, description and image, edited at `/admin/link_preview` beside a live unfurl card and read anywhere through `Studio.site_identity`. Every page unfurls with it unless it calls `link_preview image:, title:, description:`, and `Studio::LinkPreviewBots` serves preview fetchers a slim page under iMessage's 1 MiB limit. Adopt with `bin/rails g studio:site_identity`. See [`docs/LINK_PREVIEW.md`](docs/LINK_PREVIEW.md).
@@ -477,9 +477,12 @@ Recognized props: `dismissible: false` disables escape/click-outside dismissal
 animation from the registry (`'pop'` default, `'shake'`, `'slide'`).
 
 `window.ModalAnimations` is the animation registry — each key maps a CSS class
-to its duration. To add a custom animation, define `window.ModalAnimations`
-**before** the host renders with your extra keys (they merge over the engine
-defaults) and ship the matching CSS class in the app stylesheet:
+to its duration. `studio/modal_host` (an ES module the engine head imports on
+every page, which also owns `$store.modals`, the focus trap and
+`window.StudioModals`) merges an app's entries over the engine defaults once
+the document has parsed. To add a custom animation, define
+`window.ModalAnimations` in a script anywhere in the page with your extra keys
+and ship the matching CSS class in the app stylesheet:
 
 ```html
 <script>
@@ -487,16 +490,17 @@ defaults) and ship the matching CSS class in the app stylesheet:
 </script>
 ```
 
-Prefer an inline script placed before the host render, as above. A module that
-loads after the host (e.g. via importmap) and assigns `window.ModalAnimations`
-**replaces** the merged registry rather than extending it — the host guards
-against this (unknown keys and gutted registries fall back to the built-in
-`'pop'`), but your other custom keys are lost unless the late script merges
-into the existing object instead of assigning over it.
+An inline script anywhere in the page, as above, or a host module (it
+evaluates before the engine's) both merge. A script that assigns
+`window.ModalAnimations` LATER, after the page has loaded, **replaces** the
+merged registry rather than extending it: the store guards against this
+(unknown keys and gutted registries fall back to the built-in `'pop'`), but
+your other custom keys are lost unless the late script merges into the existing
+object instead of assigning over it.
 
 `window.StudioModals.CARD_WIDTHS` is the **card-width registry**, and it works
-exactly like the animation one: define it **before** the host renders and your
-entries merge over the engine defaults. Keys are modal ids, values are the
+exactly like the animation one: define it in the page and your entries merge
+over the engine defaults. Keys are modal ids, values are the
 Tailwind `max-w-*` class that card should use. `DEFAULT_CARD_WIDTH` (default
 `max-w-sm`) covers every id you don't name:
 
@@ -707,6 +711,29 @@ its helper names; drawing them there raises at route-load and kills every route
 in the app. The gate covers only the page — the registry and the inherited
 defaults are always on.
 
+### The image generator link
+
+An app can put a link to its own banner generator at the top of the page: a
+short line and a button that opens the generator in a new tab. Unset (the
+default), nil or blank draws nothing, and the page renders exactly as it did
+before the setting existed.
+
+```ruby
+# config/initializers/studio.rb
+config.email_manager_generator_url = "https://example.com/email-art"
+# or worked out per request; the callable receives the request:
+config.email_manager_generator_url = ->(request) { "#{request.base_url}/admin/email-art" }
+
+config.email_manager_generator_label       = "Header generator"   # default "Email image generator"
+config.email_manager_generator_description = "Open it, copy the prompt, paste it into Claude Code."
+```
+
+The default line reads "Make a new header with <app name>'s character model:
+open the generator, copy the prompt, paste it into Claude Code." The URL must be
+an absolute `http`/`https` URL with a host: any other String (a `javascript:`
+URL, a relative path) raises `ArgumentError` at boot, and a callable that
+answers one draws no link. Every value is escaped.
+
 ### The catalog
 
 A registered email carries a key, a label, a description, what **type** it is,
@@ -1086,6 +1113,160 @@ destroyed before the object was trashed, so the task prints the
 and the record must be re-attached by hand. `filename` is known only when the
 upload carried a Content-Disposition; supply it otherwise.
 
+## Knowledge recordings
+
+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.
+
+**Adopting it needs a migration.** Run `bin/rails studio_engine:install:migrations
+&& bin/rails db:migrate`. It adds four nullable columns to
+`studio_knowledge_docs`: `recording_key`, `recording_mime_type`,
+`recording_byte_size` (bigint) and `recording_source_url`. An app that has not
+run it keeps working: `recording?` is false and `recording_link` is nil, and only
+the two attach methods raise (`Studio::KnowledgeDoc::Recording::MissingRecordingColumns`,
+before any byte moves).
+
+```ruby
+doc.attach_recording!("/tmp/standup.mp4", source_url: "https://notes.example.com/calls/abc")
+doc.attach_recording_from_url!("https://files.example.com/standup.mp4", filename: "standup.mp4")
+doc.recording?        # => true
+doc.recording_kind    # => :video (or :audio)
+doc.recording_url     # presigned GET, six hours
+doc.recording_link    # the external page, when it is an http(s) link
+```
+
+From a one-off dyno or a laptop:
+
+```bash
+bin/rails studio:knowledge:attach_recording ID=42 FILE=/tmp/standup.mp4
+bin/rails studio:knowledge:attach_recording ID=42 URL=https://files.example.com/standup.mp4
+echo "$DOWNLOAD_URL" | bin/rails studio:knowledge:attach_recording ID=42 URL=-
+```
+
+`NAME=<file name>` names the object (a fetched recording is otherwise
+`recording.<ext>`) and `SOURCE_URL=<page>` sets the link.
+
+**Keep a download URL off the command line.** It carries a credential, and a
+command line is logged: by shell history, by `ps`, and by a platform's record of
+the command it started. `URL=-` reads the URL from standard input instead.
+Whether a given platform's one-off runner passes standard input through has not
+been tested here; check before relying on it.
+
+**What is printed and stored.** The task prints the document's id, the bucket,
+the key, the type and the size. It does not print the title or the link (a
+title is content of the layer, and the output goes to a log). The download URL
+is never stored, never printed, and no part of it names the object: a failure
+message names the URL's scheme and host only. `SOURCE_URL` is the one URL kept.
+
+**What is stored.** Audio and video only: MP4, M4V, MOV, M4A, WebM, MP3, WAV and
+Ogg. The file's first 16 bytes decide, and the stored content type comes from
+that check (`Studio::KnowledgeRecording::TYPES`), never from a header a remote
+server sent. A file name's extension picks within a container (`.m4a` is
+`audio/mp4`) and must agree with the bytes; an extension off the list is
+refused, and a name with no extension is judged by its bytes alone. An old
+QuickTime file with no `ftyp` box is refused; re-export it as MP4.
+
+**The object.** `knowledge/<entity>/<path>/<timestamp>-<random>-recording-<name>`,
+beside the document's own object. Replacing a recording uploads the new object,
+saves the row, then moves the old object to `trash/` for three days (see
+[Trash and restore](#trash-and-restore)).
+
+**The playback URL** is good for six hours (`RECORDING_URL_TTL`), not the
+document link's fifteen minutes: a player makes a new request each time the
+viewer seeks, and each one is checked against the URL's expiry.
+
+### The fetch, phase by phase
+
+`attach_recording_from_url!` is a server-side fetch of a URL the caller
+supplied, run with the bucket's credentials in the process. Each hop, the first
+URL and every redirect, must be https on port 443, may carry no user or
+password, and goes through `Studio::ImageCache.vet_source_url!` (see
+[Remote image URLs](#remote-image-urls)); the connection is then made to an
+address that hop was vetted against. A host that vets to no address is refused.
+
+The whole fetch has one deadline, `FETCH_DEADLINE` (3,600 seconds), and every
+time bound below is also cut to what is left of it. It is enforced on every
+read and write of the socket, by `Studio::KnowledgeRecording::Meter`, not only
+as body arrives.
+
+| Phase | Time bound | Size bound | Left if the process dies here |
+|-------|------------|------------|-------------------------------|
+| URL check and DNS, each hop | 6 s a lookup (`Studio::ImageCache::RESOLVE_DEADLINE`). **Not cut to the fetch's time left**: a lookup in flight can run the fetch up to 6 s over | URL 8,192 bytes (`MAX_URL_BYTES`) | an empty temporary file |
+| Connect and TLS, each address | 20 s (`CONNECT_DEADLINE`); at most 4 addresses a hop (`MAX_ADDRESSES`) | the TLS library's own handshake limits | an empty temporary file |
+| Sending the request | the fetch's time left | the URL | an empty temporary file |
+| Status line, `1xx` responses, headers | 30 s for all of them together (`HEADER_DEADLINE`) | 64 KB for all of them together (`MAX_UNDELIVERED_BYTES`) | an empty temporary file |
+| A redirect | counts as a hop: 3 followed (`MAX_REDIRECTS`), each vetted and bounded as above | Location 8,192 bytes; its body is never read | an empty temporary file |
+| Chunk-size lines and trailers | the fetch's time left; 30 s for any one silent wait | 64 KB between two pieces of body | a partial temporary file |
+| The body | the fetch's time left; 30 s for any one silent wait (`Studio::ImageCache::READ_TIMEOUT`) | 4 GB (`MAX_BYTES`), counted before each write; a declared `Content-Length` over it is refused before the body | a partial temporary file |
+
+- **A complete body or nothing.** A response that declares a `Content-Length`
+  and sends any other number of bytes fails (`FetchFailed`) before anything is
+  uploaded, and so does a chunked body that ends before its last chunk. The
+  recording already stored is untouched. **A body with no `Content-Length` and
+  no chunking cannot be checked**: it ends when the server closes the
+  connection, and a download cut short there looks the same as one that
+  finished. Compare the printed size with the source's when a server sends such
+  a response.
+- **The temporary file** is in the system temporary directory, takes up to the
+  recording's size (4 GB at most) and is deleted on every way out, an interrupt
+  or `SIGTERM` included. After a `SIGKILL` it stays on that machine's disk; on a
+  one-off dyno that disk goes with the dyno.
+- A compressed body is refused, a redirect or error response's body is never
+  read, a failed request is not retried, and only a failure to connect moves on
+  to the host's next address.
+- Any port but 443 is refused, on the first URL and on every redirect.
+- The meter reads Net::HTTP's socket through two of its instance variables,
+  because net-http has no hook for it. On a net-http where they are not what it
+  expects, the fetch is refused instead of run unmetered. Written against
+  net-http 0.9.1 and net-protocol 0.2.2.
+
+### The upload, phase by phase
+
+`Studio::S3::Multipart.upload_file` sends the file in 16 MB parts, one in memory
+at a time (`PART_SIZE`), at most 10,000 of them (`MAX_PARTS`). The whole upload
+has a deadline, `UPLOAD_DEADLINE` (7,200 seconds), read before each part. One
+request to the store is bounded by the SDK client, not by that deadline: 15 s to
+connect, 60 s for any one silent read, 3 retries (the SDK's defaults, pinned by
+a test).
+
+| Phase | Time bound | Size bound | Left in the bucket if it fails here | Left after a `SIGKILL` here |
+|-------|------------|------------|--------------------------------------|------------------------------|
+| Create the upload | one SDK request | none | nothing | an upload with no parts |
+| Each part | `UPLOAD_DEADLINE` before it starts; one SDK request | 16 MB; the file's size at open; 4 GB | nothing: the upload is aborted on any error or signal | the parts sent so far |
+| Complete | one SDK request | none | nothing: aborted. If the store completed and the answer was lost, a whole object no row points at | the parts, or a whole object |
+| Confirm the stored size | one SDK request | none | nothing: the object is deleted on a wrong size, an error or a signal | a whole object no row points at |
+| Save the row | the database's own statement timeout; the engine sets none | none | nothing: the new object is moved to `trash/` on any error or signal | a whole object no row points at |
+| Trash the replaced recording | three SDK requests | 5 GiB a copy (`Studio::S3::Trash::MAX_COPY_BYTES`) | the row points at the new recording; the old object stays where it was | the same |
+
+- **Parts left by a killed process** are not visible in a bucket listing. The
+  bucket's abort-incomplete-multipart lifecycle rule removes them; R2's default
+  rule does so after 7 days. No process can clean up after its own `SIGKILL`.
+- **A whole object no row points at** sits under
+  `knowledge/<entity>/<path>/` with `-recording-` in its name. List that prefix
+  and compare against `recording_key` to find one.
+- **Two attaches to one document at the same time** leave one recording and no
+  orphan: the save reads the key it replaces from the database under a row
+  lock, so whichever saves second trashes the first one's object.
+
+**Checksums and R2.** `Studio::S3::Multipart` uploads through its own client,
+built from `Studio::S3.client_options` with `request_checksum_calculation` and
+`response_checksum_validation` at `when_required`, and sends a Content-MD5 with
+each part. Newer `aws-sdk-s3` versions add a CRC32 by default, and R2 has refused
+some of the combinations that produces. The request shape is tested against a
+stubbed client; **a multipart upload to a live R2 bucket has not been verified.**
+
+### Transcripts
+
+`Studio::KnowledgeTranscript.parse(text)` (`require
+"studio/knowledge_transcript"`) turns transcript text into cues of `seconds`,
+`speaker` and `text`. It reads two layouts, `0:02 - Speaker` with the text
+indented below and `Speaker • 0:02` with the text below, and `M:SS` or
+`H:MM:SS` stamps. It reads at most 2 MB of text and 5,000 cues, keeps 8 KB of
+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.
+
 ## Remote image URLs
 
 `Studio::ImageCache.validate_source_url!(url)` is the check to run before the

data/app/javascript/studio/application.js

@@ -18,6 +18,7 @@
 // (Studio::Engine.javascript_boot_graph), so the boot costs one round trip.
 import { Application, defaultSchema } from "@hotwired/stimulus"
 import NavCollapseController from "studio/controllers/nav_collapse_controller"
+import ModalHostController from "studio/controllers/modal_host_controller"
 import { startPinnedStack } from "studio/pinned_stack"
 import { installAlpineShims } from "studio/alpine_shims"
 
@@ -33,5 +34,6 @@ export const schema = {
 
 const application = Application.start(document.documentElement, schema)
 application.register("nav-collapse", NavCollapseController)
+application.register("modal-host", ModalHostController)
 
 export { application }

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

@@ -0,0 +1,40 @@
+// modal-host: one modal host's lifetime, on the engine's Stimulus application
+// (studio/application, which reads data-studio-controller). It sits on the
+// host's outer <template>:
+//
+//   <template x-if="$store.modals.current()"
+//             data-studio-controller="modal-host"
+//             data-modal-host-store-value="modals">          (studio/modals/_host)
+//
+//   <template x-if="$store.labModals.current()"
+//             data-studio-controller="modal-host"
+//             data-modal-host-store-value="labModals"
+//             data-modal-host-scoped-value="true">          (studio/modals/_scoped_host)
+//
+// 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.
+import { Controller } from "@hotwired/stimulus"
+import { registerModalStore, clearStaleModals } 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)
+  }
+}