venus_media_library 0.1.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8bc0532620557b83e5d9441d9d7d3c8b6908e07de77b902387156212c5f34dbb
-  data.tar.gz: e55f2d5bd5698921d1725718c5fa3c744a3ee365c78fa17a2fcde0886e195bb8
+  metadata.gz: 53f9b683221215b76b95f0248dd87938ebba0a7066c36ccc7b02dc23fece50e0
+  data.tar.gz: acf9d06d3f9a7712568f9f05c9584ccc9fda2772de1bcad6e1b2090c1cf07e8f
 SHA512:
-  metadata.gz: 8a5b72c1b7b0ba5efbaacfc3e6f2e3fc98e2bfbf1248d2c102c171231b9967e2ce37bf39696a5fcdf596129fc0623c19bbf240292f5c6f5f682956218b99edcc
-  data.tar.gz: bd469adfdf85aec05d9dd5dd6a69cb5188b5c1354ded20a85e040133c6f3bad3cb2aeaed0722c55ac75f4e5b5f29454b52269c05684ab6fd46dd40d7f3141e9c
+  metadata.gz: e1d247beff66e7d45750fcfa96813cdcb0bb7ed5a2cb0eb500486602f4b8354001ffc280fe399fbb504ad094b2e97b3715cb578b29e2aabce34d34b82fd4037f
+  data.tar.gz: e8928ccd013a969ff08cfef454886735297e5a74d84acc9b66a09335be91ede3a1a9f4f3dfbe59ede7a3b16acc4438b461b73b8c43c550e5ce01e989555b2999

data/CHANGELOG.md

@@ -4,6 +4,82 @@ All notable changes to this project are documented here. The format is based on
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and this project adheres
 to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.1.0] - 2026-08-18
+
+### Added
+- **Full-page library navigation.** At the engine mount point (`/media`) the
+  library now renders a role-gated vertical left-nav in a 30/70 split — a proper
+  browsing/management workspace — while the picker modal stays lean for everyday
+  "pick and go." Nav entries are built from the same admin gate that guards the
+  controllers, so a link is never shown that the controller would `403`.
+- **Category tabs in the picker modal.** The modal exposes Images / Legacy /
+  Static / Cloud / Community tabs (Legacy is admin-only), each loading its
+  category into the picker Turbo Frame.
+- **Field-aware type enforcement.** A host field's accepted content types now
+  flow (`media_picker_field`/`media_attach_field` → `picker_path(accept:)` →
+  frame) into the picker. Assets whose type does not match are rendered
+  non-selectable, and uploads of a disallowed type are rejected client-side and
+  re-validated server-side (422). Falls back to the configured global allowlist
+  when a field declares nothing, and never widens past it.
+
+### Notes
+- Static/Cloud assets have no Active Storage `signed_id`; they are pickable into
+  URL fields but cannot be attached to `has_one_attached` fields, and selecting
+  one never disturbs an existing attachment.
+
+## [1.0.0] - 2026-08-17
+
+### Added
+- A stable, documented public release of the mountable Rails media-library
+  engine, including private-by-default owner access, optional community sharing,
+  administrator imports, and tenant-aware scopes.
+- Browsable library and separate host-configured Static Assets pages at the
+  engine mount point.
+- A headless Chrome system test covering picker open, existing-image selection,
+  upload, and Escape-to-close behavior.
+- Settings-gated PDF uploads and selection. PDFs are disabled by default,
+  rendered as document tiles, and served only as protected attachments.
+- CI coverage for Ruby 3.2/Rails 7.1 and Ruby 3.4/Rails 8.1, plus contributor,
+  security, and release documentation.
+
+### Security
+- Trusted RubyGems publishing through the tag-triggered GitHub OIDC workflow;
+  the required publisher configuration is documented in `docs/RELEASING.md`.
+
+## [0.2.0] - 2026-08-17
+
+### Added
+- Owner-scoped media records with private-by-default uploads and optional
+  community sharing.
+- Host `current_user` and `current_user.admin?` conventions, configurable for
+  applications with a different authentication model.
+- Authorization-aware original and thumbnail delivery routes.
+- A tested Rails compatibility range through the 8.x series.
+
+### Security
+- Validate detected upload MIME types, require the declared type to match, and
+  enforce a configurable size limit.
+- Deliver SVG originals as attachments instead of inline documents.
+- Add configurable asset and legacy-blob tenant scopes; legacy blobs are denied
+  by default until explicitly scoped by the host.
+
+## [0.1.1] - 2026-08-17
+
+### Added
+- A self-contained SQLite dummy app and test suite; contributors and CI no
+  longer need PostgreSQL.
+- CI coverage for RuboCop, the full RSpec suite, gem building, and package
+  validation.
+- SVG upload coverage. `image/svg+xml` remains part of the default upload
+  allowlist.
+
+### Changed
+- The dummy app and installation guide now mount the browsable library at
+  `/venus_media_library`; the engine root at that URL renders the image grid.
+- `allowed_content_types` now strictly controls uploads instead of implicitly
+  permitting every `image/*` MIME type.
+- JSON pagination is capped at 100 images per page.
+
 ## [0.1.0] - 2026-08-15
 
 ### Added

data/README.md

@@ -1,13 +1,13 @@
 # Media Library
 
-A mountable Rails engine that turns **Active Storage** into a browsable media library with an **image picker**.
+A mountable Rails engine that turns **Active Storage** into a browsable media library with an image-and-document picker.
 
-Content editors get a modal that lists every image already in Active Storage and lets them upload new ones. Drop `media_picker_field` next to any URL field (for example an `og:image` field) so editors *select* an image instead of typing a path.
+Content editors get a modal that lists authorized engine media and lets them upload new ones. Drop `media_picker_field` next to any URL field (for example an `og:image` field) so editors *select* an approved asset instead of typing a path.
 
 It is **storage-agnostic**: it uses whatever Active Storage service the host app configures — local Disk in development, Amazon S3 (or GCS, Azure, ...) in production. The engine never talks to a storage backend directly.
 
 - Namespaced under `VenusMediaLibrary::` (isolated engine)
-- Lists `ActiveStorage::Blob` records with an `image/*` content type, newest first
+- Lists owner-scoped Active Storage media records, newest first
 - HTML thumbnail grid **and** a JSON API
 - Upload via `ActiveStorage::Blob.create_and_upload!`
 - A modal picker (Turbo Frame + dependency-free vanilla JS)
@@ -29,12 +29,21 @@ bundle install
 
 Active Storage must be installed in the host app (`bin/rails active_storage:install && bin/rails db:migrate`).
 
+### Compatibility
+
+| Component | Supported |
+| --- | --- |
+| Ruby | 3.2+ |
+| Rails | 7.1 through 8.x |
+| Database | Any host-supported Active Record database |
+| Assets | Propshaft or Sprockets |
+
 ## Mount the engine
 
 In the host app's `config/routes.rb`:
 
 ```ruby
-mount VenusMediaLibrary::Engine, at: "/media"
+mount VenusMediaLibrary::Engine, at: "/venus_media_library"
 ```
 
 Include the picker JavaScript once in your layout (Propshaft/Sprockets):
@@ -80,6 +89,12 @@ chosen — so submitting the form without picking never detaches the current fil
 accepts a `signed_id` natively, so no controller changes are needed beyond
 permitting the attachment param (e.g. `params.permit(:cover)`).
 
+### Choosing URL or attachment mode
+
+Use `media_picker_field` for a string URL column and `media_attach_field` for
+a `has_one_attached` association. Both modes require host authorization; the
+attachment mode also requires permitting the attachment parameter.
+
 ### `media_picker_field` options
 
 | Option | Default | Description |
@@ -92,14 +107,18 @@ permitting the attachment param (e.g. `params.permit(:cover)`).
 
 ### Endpoints
 
-Mounted at your chosen path (examples assume `/media`):
+Mounted at your chosen path (examples assume `/venus_media_library`):
 
 | Method | Path | Purpose |
 | --- | --- | --- |
-| `GET` | `/media/images` | HTML thumbnail grid (also `.json`) |
-| `GET` | `/media/images.json` | `{ images: [...], page:, has_more:, total: }` |
-| `POST` | `/media/images` | Upload a file (param `file`); returns the image JSON |
-| `GET` | `/media/picker?target=<input_id>` | Turbo Frame body for the modal |
+| `GET` | `/venus_media_library` | Browsable HTML thumbnail grid |
+| `GET` | `/venus_media_library/images` | HTML thumbnail grid (also `.json`) |
+| `GET` | `/venus_media_library/images.json` | `{ images: [...], page:, has_more:, total: }` |
+| `POST` | `/venus_media_library/images` | Upload a file (param `file`); returns the image JSON |
+| `GET` | `/venus_media_library/picker?target=<input_id>` | Turbo Frame body for the modal |
+| `GET` | `/venus_media_library/community_assets` | Tenant-scoped community-shared images (also `.json`) |
+| `GET` | `/venus_media_library/static_assets` | Host-configured static-asset page (also `.json`) |
+| `GET` | `/venus_media_library/cloud_assets` | Host-configured cloud-asset page (also `.json`) |
 
 Each image payload includes `id`, `signed_id`, `filename`, `content_type`, `byte_size`, `url`, and `thumb_url`.
 
@@ -109,8 +128,10 @@ In an initializer (e.g. `config/initializers/venus_media_library.rb`):
 
 ```ruby
 VenusMediaLibrary.configure do |config|
-  # Content types accepted by the uploader (any image/* is always allowed in the grid).
+  # Content types accepted by the uploader.
   config.allowed_content_types = %w[image/png image/jpeg image/webp image/gif image/svg+xml]
+  # Add application/pdf only when this host application permits PDF uploads.
+  # config.allowed_content_types << "application/pdf"
 
   # [width, height] for the grid thumbnail variant.
   config.thumbnail_size = [300, 300]
@@ -118,40 +139,64 @@ VenusMediaLibrary.configure do |config|
   # Images per page in the index / picker.
   config.per_page = 40
 
+  # Reject uploads larger than this many bytes (10 MiB by default).
+  config.max_file_size = 10 * 1024 * 1024
+
   # Which Active Storage service to store uploads on. nil = the host app's
   # default service (Disk in dev, S3 in prod, etc.).
   config.storage_service = nil
 
-  # How image URLs are built. :redirect (default) uses rails_blob_url; :proxy
-  # uses rails_storage_proxy_url so images on a PRIVATE bucket in proxy mode are
-  # absolute and publicly fetchable by crawlers (e.g. for an og:image).
+  # Retained for compatibility. Library URLs are authorization-aware engine URLs.
   config.url_type = :redirect
 
   # Optional access gate. A proc run in the engine controller's context before
   # every action, so it can use host helpers (current_user, redirect_to, head,
-  # main_app). Left nil the engine is open — set it to restrict the picker and
-  # upload endpoints to admins:
+  # main_app). Use it for a custom precondition before engine actions:
   #
   #   config.authenticate_with = lambda do
   #     redirect_to main_app.root_path unless current_user&.admin?
   #   end
   config.authenticate_with = nil
+
+  # Ownership defaults to the host application's authentication convention.
+  config.current_user = -> { current_user }
+  config.admin = ->(user) { user.admin? }
+
+  # Approved host-supplied records for non-library tabs. Each hash needs a
+  # filename and URL, with optional content_type and byte_size.
+  config.static_assets = -> { [] }
+  config.cloud_assets = -> { [] }
+
 end
 ```
 
 ### Configuration Details
 
-- **`allowed_content_types`** — Restricts uploads to these MIME types. The grid always shows any blob with `image/*` content type regardless. Defaults to common image formats; customize only if you need to block certain types.
+- **`allowed_content_types`** — Restricts uploads to these exact MIME types. The default explicitly includes SVG (`image/svg+xml`) but deliberately excludes PDFs. Add `application/pdf` here to enable PDF selection and uploads; PDFs render as document tiles and are delivered as protected downloads rather than embedded content.
 
 - **`thumbnail_size`** — Array of `[width, height]` for grid thumbnails. Larger values give better preview quality at the cost of image processing overhead and bandwidth.
 
-- **`per_page`** — Number of images to display per page. Smaller values suit mobile-friendly UIs; larger values reduce pagination clicks.
+- **`per_page`** — Number of images to display per page. Smaller values suit mobile-friendly UIs; larger values reduce pagination clicks. JSON callers can request up to 100 images per page.
+
+- **`max_file_size`** — Maximum upload size in bytes. The default is 10 MiB.
 
 - **`storage_service`** — Active Storage service name (e.g. `:amazon`, `:google`). Leave `nil` to use the host app's default, making the engine truly storage-agnostic. Uploads automatically inherit the configured service.
 
-- **`url_type`** — Controls how image URLs are built:
-  - `:redirect` (default) — `rails_blob_url` returns a temporary redirect URL that points to your storage backend (S3, GCS, etc.). Works for public URLs but blocks crawlers if your bucket is private.
-  - `:proxy` — `rails_storage_proxy_url` returns a proxy URL through Rails, which streams bytes from storage. Useful for private buckets where external crawlers (e.g., social media bots fetching `og:image`) need public, absolute URLs.
+- **`current_user`** — A controller-context callback that returns the signed-in host user. It defaults to `current_user`; every engine endpoint requires it to return a user.
+
+- **`admin`** — A callback that determines whether that user can manage all media. It defaults to `->(user) { user.admin? }`.
+
+- **`asset_scope`** — A controller-context callback receiving the engine asset relation. Use it to restrict all list, picker, download, and admin queries to the current tenant. It defaults to the supplied relation.
+
+- **`legacy_blob_scope`** — A controller-context callback receiving unowned image blobs. It defaults to `scope.none`, so legacy blobs cannot cross tenant boundaries accidentally. Configure it explicitly only when the host can prove which legacy blobs belong to the current tenant.
+
+- **`static_assets`** — A controller-context callback that returns approved host asset hashes for the separate `/static_assets` page. Each hash needs `filename` and `url`, with optional `content_type` and `byte_size`; the engine never scans host directories.
+
+- **`cloud_assets`** — A controller-context callback with the same hash shape for the separate `/cloud_assets` page. Use it to present approved CDN or object-storage assets. The engine never enumerates a bucket, accepts storage credentials, or makes an arbitrary cloud object public.
+
+- **Community Assets** — The `/community_assets` tab shows only `community_shared: true` records after the host's `asset_scope` is applied. Private uploads never appear there.
+
+- **`url_type`** — Retained for backward-compatible host configuration. Browsing and picker URLs are always protected engine routes, so private uploads are never exposed via an Active Storage signed URL.
 
 - **`authenticate_with`** — A proc that gates access to the engine. Runs before every action in the engine's controller context, so you can call host helpers like `current_user`, `redirect_to`, and `head`. Return nothing to allow, or redirect/deny to block. Example:
   ```ruby
@@ -181,6 +226,13 @@ Without these, variant generation fails and thumbnail images won't display.
 
 ## Styling & Customization
 
+Include the engine's explicit entrypoints in the host layout:
+
+```erb
+<%= stylesheet_link_tag "venus_media_library/application", "venus_media_library/picker" %>
+<%= javascript_include_tag "venus_media_library/venus_media_library", defer: true %>
+```
+
 All picker and library CSS is namespaced under `.ml-*` classes to avoid conflicts with the host app. The engine ships two stylesheets:
 
 - **`venus_media_library/application.css`** — Layout and structure (grid, pagination, forms).
@@ -232,16 +284,16 @@ If you must support IE11, you'll need polyfills. No Turbo Drive requirement, but
 
 ### The Picker Flow
 
-1. **User clicks "Choose from library"** — Opens a modal via a Turbo Frame (`GET /media/picker?target=<input_id>`).
+1. **User clicks "Choose from library"** — Opens a modal via a Turbo Frame (`GET /venus_media_library/picker?target=<input_id>`).
 2. **Modal loads the image grid** — The frame fetches the index view, listing images newest-first with pagination.
 3. **User uploads or selects** —
    - **Select:** Click an image tile; JavaScript writes the blob's `signed_id` and URL into the form inputs and closes the modal.
-   - **Upload:** Click the upload button; JavaScript posts the file to `POST /media/images`, attaches the new blob to the same inputs, and reloads the grid.
+   - **Upload:** Click the upload button; JavaScript posts the file to `POST /venus_media_library/images`, attaches the new blob to the same inputs, and reloads the grid.
 4. **Form submission** — The host app form submits with the image data, storing it as a URL column or Active Storage attachment.
 
-### URL Signing & Storage Agnosticism
+### Authorized delivery & storage agnosticism
 
-All image URLs are built via Active Storage helpers (`rails_blob_url` or `rails_storage_proxy_url`), which handle signed URLs and expiration. The engine never directly accesses the storage backend; it trusts Active Storage to route the request appropriately.
+The engine serves library URLs through authorization-aware routes. It never directly accesses the storage backend; Active Storage routes the authorized byte requests.
 
 Upload destinations are determined by `config.storage_service` — if `nil`, the host app's default service is used, allowing per-environment configuration (Disk locally, S3 in production).
 
@@ -256,7 +308,7 @@ cd spec/dummy && bundle exec rspec ../
 Or use the included Rakefile:
 
 ```bash
-bundle exec rake spec
+bundle exec rake app:spec
 ```
 
 When testing a host app that uses Media Library, you can:
@@ -275,6 +327,16 @@ When testing a host app that uses Media Library, you can:
 
 ## Troubleshooting
 
+### Ownership and community sharing
+
+Each upload is owned by the user returned by `config.current_user` and starts private. A member can browse and download their own uploads; checking **Share with community** during upload makes that item visible to other signed-in members. Admins, as determined by `config.admin`, can browse and download every engine-managed upload.
+
+The engine sends originals and thumbnails through its own authorization-aware routes. Do not use an Active Storage blob URL as a substitute for an engine media URL, because it bypasses the ownership check.
+
+The upload endpoint verifies the detected MIME type with Marcel, requires it to match the browser-declared type, enforces the allowlist and `max_file_size`, and stores the detected type. SVG remains supported, but originals are delivered as downloads rather than inline documents to avoid executing SVG active content in the host application's origin.
+
+Blobs that existed before the engine was installed have no owner and are intentionally invisible to normal members. Admins can use **Import unowned legacy uploads** from the library to claim an image into their private library, then use the normal community-sharing control if appropriate. Do not expose legacy blobs by direct Active Storage URLs.
+
 ### Thumbnails aren't generating
 
 **Symptom:** Gray placeholder squares instead of previews in the grid.
@@ -284,12 +346,6 @@ When testing a host app that uses Media Library, you can:
 rails active_storage:install && rails db:migrate
 ```
 
-### Private S3 bucket — og:image not visible to crawlers
-
-**Symptom:** Social media preview cards show no image for posts with private S3 URLs.
-
-**Solution:** Set `config.url_type = :proxy` so Rails proxies image bytes through a public endpoint. This requires Rails to stream the file, so monitor for performance impact with large images.
-
 ### Upload endpoint is open to the public
 
 **Symptom:** Anyone can upload images to your media library.
@@ -313,12 +369,12 @@ end
 
 **Solution:** Check browser console for errors. Verify:
 1. JavaScript is loaded: `<%= javascript_include_tag "venus_media_library/venus_media_library", defer: true %>`
-2. The engine is mounted and accessible at your chosen path (default: `/media`).
+2. The engine is mounted and accessible at your chosen path (recommended: `/venus_media_library`).
 3. No JavaScript errors in other assets are breaking the page.
 
 ## Development
 
-The engine ships with a dummy app under `spec/dummy` (Active Storage configured with the Disk service, engine mounted at `/media`).
+The engine ships with a dummy app under `spec/dummy` (Active Storage configured with the Disk service, engine mounted at `/venus_media_library`).
 
 ```bash
 bundle install
@@ -335,7 +391,10 @@ gem build venus_media_library.gemspec        # produces venus_media_library-<ver
 gem push venus_media_library-<version>.gem   # publish to RubyGems
 ```
 
-`gem push` requires RubyGems credentials (and 2FA/OTP if enabled) — **the gem owner enters these**; they are not stored in the repo. Bump `VenusMediaLibrary::VERSION` in `lib/venus_media_library/version.rb` before each release.
+Follow [the release guide](docs/RELEASING.md). Releases normally use GitHub
+Actions trusted publishing; no RubyGems token is stored in the repository or
+GitHub secrets. Bump `VenusMediaLibrary::VERSION` in
+`lib/venus_media_library/version.rb` before each release.
 
 ## License
 

data/app/assets/javascripts/venus_media_library/venus_media_library.js

@@ -3,6 +3,7 @@
 // Wiring (all via delegated events, no framework required):
 //   [data-ml-open][data-ml-target][data-ml-src]  open the modal for a field
 //   [data-ml-close]                               close the modal
+//   [data-ml-picker-nav]                          switch category / paginate in-frame
 //   .ml-tile[data-ml-url][data-ml-signed-id]      choose an image
 //   input[data-ml-upload]                         upload a new image
 //
@@ -61,6 +62,8 @@
 
   function chooseTile(tile) {
     if (!activeTargetId) { closeModal(); return; }
+    // Assets whose type the field doesn't accept render disabled; never pick one.
+    if (tile.disabled || tile.classList.contains("ml-tile--disabled")) return;
     var url = tile.getAttribute("data-ml-url");
     var signedId = tile.getAttribute("data-ml-signed-id");
 
@@ -71,10 +74,12 @@
       input.dispatchEvent(new Event("change", { bubbles: true }));
     }
     var hidden = document.querySelector('[data-ml-signed-id-for="' + activeTargetId + '"]');
-    if (hidden) {
+    if (hidden && signedId) {
       hidden.value = signedId;
       // Attach mode ships the hidden field disabled so an empty value can't
-      // detach the current file; enable it now that a signed_id is set.
+      // detach the current file; enable it now that a signed_id is set. External
+      // assets (static/cloud) carry no signed_id, so we skip this entirely and
+      // leave any existing attachment intact.
       hidden.disabled = false;
     }
 
@@ -90,6 +95,13 @@
 
     var form = new FormData();
     form.append("file", file);
+    var share = document.querySelector("[data-ml-community-share]");
+    form.append("community_shared", share && share.checked ? "1" : "0");
+    // Constrain the upload to the opening field's accepted types (server
+    // re-validates); the frame carries them as data-ml-accept.
+    var f = frame();
+    var accept = f ? f.getAttribute("data-ml-accept") : null;
+    if (accept) form.append("accept", accept);
 
     var headers = { "Accept": "application/json" };
     var token = csrfToken();
@@ -100,9 +112,9 @@
         if (!r.ok) throw new Error("Upload failed");
         return r.json();
       })
-      .then(function (image) {
-        if (status) status.textContent = "Uploaded " + image.filename;
-        prependTile(image);
+      .then(function (media) {
+        if (status) status.textContent = "Uploaded " + media.filename;
+        prependTile(media);
       })
       .catch(function () { if (status) status.textContent = "Upload failed."; });
   }
@@ -115,7 +127,7 @@
     return "images";
   }
 
-  function prependTile(image) {
+  function prependTile(media) {
     var grid = document.querySelector("[data-ml-grid]");
     if (!grid) return;
     // Build with DOM methods (not innerHTML): filenames are user-controlled, so
@@ -123,21 +135,29 @@
     var btn = document.createElement("button");
     btn.type = "button";
     btn.className = "ml-tile";
-    btn.setAttribute("data-ml-signed-id", image.signed_id);
-    btn.setAttribute("data-ml-url", image.url);
-    btn.setAttribute("data-ml-filename", image.filename);
-    btn.title = image.filename;
-
-    var img = document.createElement("img");
-    img.src = image.thumb_url;
-    img.alt = image.filename;
-    img.loading = "lazy";
+    btn.setAttribute("data-ml-signed-id", media.signed_id);
+    btn.setAttribute("data-ml-url", media.url);
+    btn.setAttribute("data-ml-filename", media.filename);
+    btn.title = media.filename;
+
+    if (media.previewable) {
+      var img = document.createElement("img");
+      img.src = media.thumb_url;
+      img.alt = media.filename;
+      img.loading = "lazy";
+      btn.appendChild(img);
+    } else {
+      var documentTile = document.createElement("span");
+      documentTile.className = "ml-tile__document";
+      documentTile.setAttribute("aria-hidden", "true");
+      documentTile.textContent = media.content_type === "application/pdf" ? "PDF" : "FILE";
+      btn.appendChild(documentTile);
+    }
 
     var name = document.createElement("span");
     name.className = "ml-tile__name";
-    name.textContent = image.filename;
+    name.textContent = media.filename;
 
-    btn.appendChild(img);
     btn.appendChild(name);
     grid.insertBefore(btn, grid.firstChild);
   }
@@ -154,6 +174,15 @@
       closeModal();
       return;
     }
+    // Category tabs / "load older" reload the picker frame in place. When Turbo
+    // is present it drives the frame via data-turbo-frame; otherwise fetch it.
+    var nav = e.target.closest("[data-ml-picker-nav]");
+    if (nav && nav.closest("#" + MODAL_ID)) {
+      if (window.Turbo && frame() && frame().tagName.toLowerCase() === "turbo-frame") return;
+      e.preventDefault();
+      loadFrame(nav.getAttribute("href"));
+      return;
+    }
     var tile = e.target.closest(".ml-tile");
     if (tile && tile.closest("#" + MODAL_ID)) {
       e.preventDefault();

data/app/assets/stylesheets/venus_media_library/layout.css

@@ -0,0 +1,82 @@
+/*
+ * Full-page media library management workspace shell. Namespaced under .ml-* to
+ * avoid clashing with the host app. This styles the /media full-page context
+ * only; the picker modal keeps its own lean layout in picker.css.
+ */
+
+.ml-body { margin: 0; }
+
+/* 30% left navigation column beside a 70% content column. */
+.ml-layout {
+  display: flex;
+  align-items: stretch;
+  min-height: 100vh;
+}
+.ml-layout__nav {
+  flex: 0 0 30%;
+  max-width: 30%;
+  box-sizing: border-box;
+  background: #f7f8fa;
+  border-right: 1px solid #e2e2e2;
+}
+.ml-layout__content {
+  flex: 1 1 70%;
+  min-width: 0; /* let the grid shrink instead of overflowing the row */
+  box-sizing: border-box;
+}
+
+/* Sidebar navigation. */
+.ml-nav {
+  position: sticky;
+  top: 0;
+  padding: 1rem .75rem;
+}
+.ml-nav__brand {
+  font-weight: 700;
+  font-size: 1.05rem;
+  color: #1d4f80;
+  padding: .25rem .75rem 1rem;
+}
+.ml-nav__list {
+  list-style: none;
+  margin: 0;
+  padding: 0;
+  display: flex;
+  flex-direction: column;
+  gap: .15rem;
+}
+.ml-nav__link {
+  display: block;
+  padding: .55rem .75rem;
+  color: #333;
+  text-decoration: none;
+  border-radius: 6px;
+  border-left: 3px solid transparent;
+}
+.ml-nav__link:hover { background: #eef1f5; color: #1d4f80; }
+.ml-nav__link[aria-current="page"] {
+  background: #e7eefb;
+  color: #1d4f80;
+  border-left-color: #2b6cb0;
+  font-weight: 600;
+}
+
+/* Responsive: stack the nav above the content and lay entries out as a wrapping
+ * horizontal bar on narrow viewports. */
+@media (max-width: 640px) {
+  .ml-layout { flex-direction: column; min-height: 0; }
+  .ml-layout__nav {
+    flex-basis: auto;
+    max-width: none;
+    border-right: 0;
+    border-bottom: 1px solid #e2e2e2;
+  }
+  .ml-nav { position: static; padding: .5rem; }
+  .ml-nav__brand { padding: .25rem .5rem .5rem; }
+  .ml-nav__list { flex-direction: row; flex-wrap: wrap; gap: .25rem; }
+  .ml-nav__link { border-left: 0; border-bottom: 3px solid transparent; }
+  .ml-nav__link[aria-current="page"] {
+    border-left-color: transparent;
+    border-bottom-color: #2b6cb0;
+  }
+}

data/app/assets/stylesheets/venus_media_library/picker.css

@@ -22,6 +22,11 @@
 .ml-library__header { display: flex; align-items: baseline; gap: 1rem; }
 .ml-library__count { color: #666; }
 
+.ml-tabs { display: flex; gap: .25rem; flex-wrap: wrap; margin: 0 0 1rem; border-bottom: 1px solid #d7d7d7; }
+.ml-tabs__tab { padding: .5rem .75rem; color: #444; text-decoration: none; border: 1px solid transparent; border-bottom: 0; border-radius: 4px 4px 0 0; }
+.ml-tabs__tab:hover { background: #f5f5f5; color: #222; }
+.ml-tabs__tab[aria-current="page"] { color: #1d4f80; background: #fff; border-color: #d7d7d7; font-weight: 600; margin-bottom: -1px; }
+
 .ml-grid {
   display: grid;
   grid-template-columns: repeat(auto-fill, minmax(140px, 1fr));
@@ -42,6 +47,17 @@
 }
 .ml-tile:hover { border-color: #2b6cb0; box-shadow: 0 0 0 2px rgba(43,108,176,.2); }
 .ml-tile img { width: 100%; height: 120px; object-fit: cover; display: block; background: #fafafa; }
+.ml-tile__document {
+  display: grid;
+  place-items: center;
+  width: 100%;
+  height: 120px;
+  background: #f8fafc;
+  color: #b42318;
+  font-size: 1.05rem;
+  font-weight: 700;
+  letter-spacing: .08em;
+}
 .ml-tile__name {
   font-size: .75rem;
   padding: .35rem .4rem;
@@ -51,6 +67,13 @@
   text-overflow: ellipsis;
 }
 
+/* Disabled tiles: assets whose type the opening field does not accept. */
+.ml-tile--disabled { cursor: not-allowed; opacity: .4; filter: grayscale(1); }
+.ml-tile--disabled:hover { border-color: #e2e2e2; box-shadow: none; }
+
+/* Category tabs inside the modal sit just under the upload toolbar. */
+.ml-picker__tabs { margin-top: .25rem; }
+
 .ml-empty { color: #777; padding: 1rem; text-align: center; }
 .ml-pagination { display: flex; gap: .5rem; justify-content: center; }
 
@@ -80,3 +103,12 @@
 .ml-picker__toolbar { display: flex; align-items: center; gap: 1rem; margin-bottom: .5rem; }
 .ml-picker__hint { color: #666; font-size: .85rem; }
 .ml-picker__more { text-align: center; }
+
+/* Administrator configuration overview */
+.ml-settings__intro { max-width: 54rem; color: #555; }
+.ml-settings__section { margin-top: 1.5rem; }
+.ml-settings__section h2 { font-size: 1.05rem; margin-bottom: .5rem; }
+.ml-settings__list { display: grid; grid-template-columns: minmax(10rem, 16rem) 1fr; gap: .5rem 1rem; margin: 0; }
+.ml-settings__list dt { font-weight: 600; }
+.ml-settings__list dd { margin: 0; }
+.ml-settings__types { margin: 0; padding-left: 1.25rem; }