venus_media_library 0.2.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1499112ecf8687cfa0f34bd242c7443117c945d4800e4d74a5d163e33d406c42
-  data.tar.gz: ac7593b69b25cd85b6e1c029320ab776bd02e65284559f3814c69a9136ff5c95
+  metadata.gz: 53f9b683221215b76b95f0248dd87938ebba0a7066c36ccc7b02dc23fece50e0
+  data.tar.gz: acf9d06d3f9a7712568f9f05c9584ccc9fda2772de1bcad6e1b2090c1cf07e8f
 SHA512:
-  metadata.gz: f4281c9f9c2b06fdab878293cf5607a181f3bc31e6db14ec5c83cf7f7e330ac5401e4e8a8855090f08367f2f29b6babf6440ed18a69e16427356b97cf66ba6a3
-  data.tar.gz: 10e093ac59f1622f0f952977aab386e92194b309caa3f669f7dc0e48b49b54b4b6bcb868d948f7a0856c16bf874a60cb250fc48cb9f9e8be81b1c1bc4ea19e60
+  metadata.gz: e1d247beff66e7d45750fcfa96813cdcb0bb7ed5a2cb0eb500486602f4b8354001ffc280fe399fbb504ad094b2e97b3715cb578b29e2aabce34d34b82fd4037f
+  data.tar.gz: e8928ccd013a969ff08cfef454886735297e5a74d84acc9b66a09335be91ede3a1a9f4f3dfbe59ede7a3b16acc4438b461b73b8c43c550e5ce01e989555b2999

data/CHANGELOG.md

@@ -4,6 +4,48 @@ 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
@@ -14,6 +56,13 @@ to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 - 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

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,6 +29,15 @@ 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`:
@@ -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 |
@@ -101,6 +116,9 @@ Mounted at your chosen path (examples assume `/venus_media_library`):
 | `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`.
 
@@ -112,6 +130,8 @@ In an initializer (e.g. `config/initializers/venus_media_library.rb`):
 VenusMediaLibrary.configure do |config|
   # 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]
@@ -119,6 +139,9 @@ 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
@@ -138,23 +161,41 @@ VenusMediaLibrary.configure do |config|
   # 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 exact MIME types. The default explicitly includes SVG (`image/svg+xml`).
+- **`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. 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.
 
 - **`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:
@@ -185,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).
@@ -243,9 +291,9 @@ If you must support IE11, you'll need polyfills. No Turbo Drive requirement, but
    - **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).
 
@@ -285,6 +333,8 @@ Each upload is owned by the user returned by `config.current_user` and starts pr
 
 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
@@ -296,12 +346,6 @@ Blobs that existed before the engine was installed have no owner and are intenti
 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.
@@ -347,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;
     }
 
@@ -92,6 +97,11 @@
     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();
@@ -102,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."; });
   }
@@ -117,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
@@ -125,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);
   }
@@ -156,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; }

data/app/controllers/venus_media_library/application_controller.rb

@@ -1,6 +1,8 @@
 module VenusMediaLibrary
   class ApplicationController < ActionController::Base
-    helper_method :venus_media_library_admin?
+    helper_method :venus_media_library_admin?,
+                  :venus_media_library_nav_items,
+                  :venus_media_library_active_nav
     # Run the host-configured access gate (if any) before every engine action.
     # The engine ships open; the host restricts the picker/upload endpoints by
     # setting VenusMediaLibrary.configuration.authenticate_with to a proc.
@@ -28,16 +30,70 @@ module VenusMediaLibrary
       instance_exec(venus_media_library_user, &VenusMediaLibrary.configuration.admin)
     end
 
+    # Destinations for the full-page management workspace's left navigation.
+    # Role-gated: legacy imports and the settings overview are admin-only,
+    # mirroring the `require_venus_media_library_admin!` gate those controllers
+    # already enforce, so the sidebar never advertises a forbidden link.
+    def venus_media_library_nav_items
+      items = [
+        { key: :library,   controller: "images",           label: "My Library",    path: images_path },
+        { key: :legacy,    controller: "legacy_assets",    label: "Legacy Assets", path: legacy_assets_path, admin: true },
+        { key: :static,    controller: "static_assets",    label: "Static Assets", path: static_assets_path },
+        { key: :cloud,     controller: "cloud_assets",     label: "Cloud Assets",  path: cloud_assets_path },
+        { key: :community, controller: "community_assets", label: "Community",     path: community_assets_path },
+        { key: :settings,  controller: "settings",         label: "Settings",      path: settings_path, admin: true }
+      ]
+      return items if venus_media_library_admin?
+
+      items.reject { |item| item[:admin] }
+    end
+
+    # The nav key for the controller handling the current request, used by the
+    # sidebar to highlight the active section without each view passing a local.
+    def venus_media_library_active_nav
+      venus_media_library_nav_items.find { |item| item[:controller] == controller_name }&.fetch(:key)
+    end
+
     def visible_media_assets
-      scope = VenusMediaLibrary::Asset.includes(:blob)
+      scope = scoped_media_assets
       return scope if venus_media_library_admin?
 
       scope.where(community_shared: true).or(scope.where(owner: venus_media_library_user))
     end
 
     def unowned_legacy_image_blobs
-      ActiveStorage::Blob.where("content_type LIKE ?", "image/%")
-                         .where.not(id: VenusMediaLibrary::Asset.select(:blob_id))
+      scope = ActiveStorage::Blob.where("content_type LIKE ?", "image/%")
+                                 .where.not(id: VenusMediaLibrary::Asset.select(:blob_id))
+      instance_exec(scope, &VenusMediaLibrary.configuration.legacy_blob_scope)
+    end
+
+    def scoped_media_assets
+      scope = VenusMediaLibrary::Asset.includes(:blob)
+      instance_exec(scope, &VenusMediaLibrary.configuration.asset_scope)
+    end
+
+    def load_media_assets(scope)
+      @page     = [ params.fetch(:page, 1).to_i, 1 ].max
+      @per_page = requested_per_page
+      offset    = (@page - 1) * @per_page
+
+      @total_count = scope.count
+      @blobs       = scope.order(created_at: :desc).offset(offset).limit(@per_page).to_a
+      @has_more    = offset + @blobs.size < @total_count
+      @images      = @blobs.map { |asset| ml_image_payload(asset) }
+    end
+
+    def load_host_assets(callback)
+      @assets = Array(instance_exec(&callback)).map do |asset|
+        asset.to_h.symbolize_keys.slice(:filename, :url, :content_type, :byte_size)
+      end
+    end
+
+    def requested_per_page
+      requested = params[:per_page].presence&.to_i
+      value = requested&.positive? ? requested : VenusMediaLibrary.configuration.per_page.to_i
+
+      value.clamp(1, ImagesController::MAX_PER_PAGE)
     end
 
     def require_venus_media_library_admin!

data/app/controllers/venus_media_library/assets_controller.rb

@@ -3,7 +3,7 @@ module VenusMediaLibrary
     def show
       asset = visible_media_assets.find(params[:id])
       send_data asset.blob.download, filename: asset.blob.filename.to_s,
-        type: asset.blob.content_type, disposition: "inline"
+        type: asset.blob.content_type, disposition: delivery_disposition(asset.blob)
     end
 
     def thumbnail
@@ -16,5 +16,15 @@ module VenusMediaLibrary
       send_data representation.download, filename: blob.filename.to_s,
         type: representation.image.content_type, disposition: "inline"
     end
+
+    private
+
+    # SVG is accepted for editorial use but is delivered as a download. Inline
+    # SVG may execute active content in a host application's origin. PDFs are
+    # also attachments: they remain selectable media but are not embedded in
+    # the host application's origin.
+    def delivery_disposition(blob)
+      [ "image/svg+xml", "application/pdf" ].include?(blob.content_type) ? "attachment" : "inline"
+    end
   end
 end

data/app/controllers/venus_media_library/cloud_assets_controller.rb

@@ -0,0 +1,12 @@
+module VenusMediaLibrary
+  class CloudAssetsController < ApplicationController
+    def index
+      load_host_assets(VenusMediaLibrary.configuration.cloud_assets)
+
+      respond_to do |format|
+        format.html
+        format.json { render json: { assets: @assets } }
+      end
+    end
+  end
+end

data/app/controllers/venus_media_library/community_assets_controller.rb

@@ -0,0 +1,16 @@
+module VenusMediaLibrary
+  class CommunityAssetsController < ApplicationController
+    include VenusMediaLibrary::ImagesHelper
+
+    def index
+      load_media_assets(scoped_media_assets.where(community_shared: true))
+
+      respond_to do |format|
+        format.html
+        format.json do
+          render json: { images: @images, page: @page, has_more: @has_more, total: @total_count }
+        end
+      end
+    end
+  end
+end