kempo-media 0.2.3 → 0.3.0

package/.github/workflows/publish.yml

@@ -33,7 +33,8 @@ jobs:
 
       - uses: actions/setup-node@v4
         with:
-          node-version: '20.x'
+          node-version: '22.x'
+          registry-url: 'https://registry.npmjs.org'
 
       - run: npm ci
 
@@ -41,11 +42,12 @@ jobs:
         run: |
           npm run build
 
-      # kempo/kempo-ui/kempo-server are peer dependencies and are not installed by npm ci above.
+      # kempo, kempo-files, kempo-thumbs, kempo-ui and kempo-server are peer dependencies and are not
+      # installed by npm ci above.
       # The published release is the right one to test against: it is what a site installing this
       # extension will actually pair it with.
       - name: Install the host for the test gate
-        run: npm install --no-save kempo@latest kempo-ui@latest kempo-server@latest
+        run: npm install --no-save kempo@latest kempo-files@latest kempo-thumbs@latest kempo-ui@latest kempo-server@latest
 
       - name: Run Unit Tests
         run: npm test
@@ -72,14 +74,11 @@ jobs:
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
-      - name: Setup .npmrc for OIDC
-        run: |
-          cat << EOF > ~/.npmrc
-          //registry.npmjs.org/:_authToken=\${NPM_TOKEN}
-          registry=https://registry.npmjs.org/
-          always-auth=true
-          EOF
+      # Trusted publishing needs npm >=11.5.1; Node 22.x still bundles 10.9.x. Without this, OIDC
+      # publish auth is silently unavailable and the registry returns a 404 rather than an auth error.
+      # Upgraded only now, not before npm ci: a newer npm skips dependency install scripts, which is
+      # how puppeteer downloads the Chrome the browser tests need, so the install and the tests run
+      # on the npm that Node ships, exactly as test.yml does.
+      - run: npm install -g npm@latest
 
       - run: npm publish --access public
-        env:
-          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

package/.github/workflows/test.yml

@@ -43,9 +43,9 @@ jobs:
 
       - run: npm ci
 
-      # kempo/kempo-ui/kempo-server are peer dependencies, which npm ci does not install.
+      # kempo, kempo-files, kempo-thumbs, kempo-ui and kempo-server are peer dependencies, which npm ci does not install.
       - name: Install the host for the test gate
-        run: npm install --no-save kempo@latest kempo-ui@latest kempo-server@latest
+        run: npm install --no-save kempo@latest kempo-files@latest kempo-thumbs@latest kempo-ui@latest kempo-server@latest
 
       - name: Apply database schema
         run: npx drizzle-kit push --force
@@ -92,6 +92,17 @@ jobs:
           repository: dustinpoissant/kempo-server
           path: kempo-server
 
+      # This extension sits on kempo-files and kempo-thumbs, and link:local links both.
+      - uses: actions/checkout@v4
+        with:
+          repository: dustinpoissant/kempo-files
+          path: kempo-files
+
+      - uses: actions/checkout@v4
+        with:
+          repository: dustinpoissant/kempo-thumbs
+          path: kempo-thumbs
+
       # kempo's own link:local script links both kempo-server and kempo-ui as siblings, so this
       # checkout needs to exist even though kempo-media itself doesn't import kempo-ui server-side.
       - uses: actions/checkout@v4

package/CHANGELOG.md

@@ -4,6 +4,23 @@ All notable changes to this project will be documented in this file.
 
 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).
 
+## [Unreleased]
+### Changed
+ - **Media now sits on kempo-files, with thumbnails from kempo-thumbs.** Before, this extension kept its own copy of everything: uploads in the site's `public/media/uploads/` (static serving, no permissions), and `sharp` thumbnails in `public/media/thumbnails/`, parallel to kempo-files' permission-checked library and kempo-thumbs' ffmpeg thumbnails. Anything consuming images had to handle both stacks. Now an asset is a kempo-files file plus a `kempoMediaAsset` row (kind, dimensions, alt text, display name), the **asset id is the file id** (no mapping table), the bytes live in kempo-files' `files/media/` folder, and a thumbnail is whatever kempo-thumbs made. One storage layer, one set of file permissions, one thumbnail path.
+ - `kempo-config.json` declares `"dependencies": ["kempo-files", "kempo-thumbs"]`; kempo will not install this extension until both are enabled. kempo-thumbs is required rather than optional so every consumer can rely on `thumbnail` meaning the same thing. Requires `kempo-files` >= 0.1.5, which adds `uploadFile`, caller-chosen ids and download caching.
+ - **Asset shape.** Same ids, same fields (`path`, `thumbnailPath`, `altText`, `kind`, `width`, `height`, ...), but `path` is now the kempo-files URL without its leading slash (`kempo-files/api/files/<id>`) rather than a path under `public/`, and `thumbnailPath` is the small kempo-thumbs thumbnail (its `sm` size, else its smallest ready one), `null` until it exists. New: `url`, `thumbnail`, `thumbnails` (every size, for a `srcset`), `public`, `fileId`. Removed: `filename`.
+ - **Visibility.** Assets are public by default, as before; the flag is now kempo-files' `public` flag, settable through `updateMediaAsset(id, { public })` / `PATCH`. kempo-thumbs already refuses a private file's thumbnails to anyone who could not fetch it.
+ - `uploadMediaAsset` replaces `storeUpload` as the way to store a Buffer. It goes through kempo-files' `uploadFile`, so `file:before_upload` can refuse an upload and `file:uploaded` reaches kempo-thumbs. `deleteMediaAsset(id)` no longer takes a `rootDir`; deleting the file is what makes kempo-thumbs remove its thumbnails. **Breaking for callers of the old `storeUpload(...)` + `createMediaAsset(...)` pair**; this extension had not been published.
+ - Dimensions come from ffprobe (kempo-thumbs' binary) for images and video, and are `null` when the file cannot be decoded.
+ - The admin library shows the original image while a thumbnail is pending and refreshes itself a few times (only for images and video uploaded in the last two minutes) until it arrives. The editor picker has priority `-10`, so it loads after kempo-files' own picker and wins the shared `window.kempo.openAssetPicker`.
+
+### Migration
+ - **`update.js` moves 0.2.x installs into kempo-files** under the same ids, keeping bytes, alt text, kind, dimensions, upload date and uploader; registers each old `/media/uploads/<id>.<ext>` URL as an alias so embedded links keep working (needs `public/CATCH.js`); removes the old files, the old `sharp` thumbnails and the `thumbnail_max_dimension` setting; has kempo-thumbs make new thumbnails; and finally drops the `filename`, `path` and `thumbnailPath` columns. Idempotent, resumable after an interruption, and it refuses to start (changing nothing) unless kempo-files and kempo-thumbs are enabled. See the README.
+
+### Removed
+ - `sharp` and the `thumbnail_max_dimension` setting: thumbnail sizes, format and quality are kempo-thumbs' settings now.
+ - `install.js`: nothing needs creating up front. The `media` folder in kempo-files is created by the first upload, and nothing is written under `public/` any more.
+
 ## [0.2.0] - 2026-08-13
 ### Added
  - **Uploads.** `POST /kempo-media/api/media` accepts a `multipart/form-data` upload, validates its type, stores it under a generated name in the site's own `public/media/uploads/`, and records it. The multipart parser is written here rather than pulled in: the usual libraries stream a body that is still arriving, and kempo-server has already buffered the whole thing by the time a route runs. It works entirely on Buffers, so file content is never decoded — decoding it as UTF-8 is exactly the corruption kempo-server 3.2.0 fixed.

package/README.md

@@ -2,28 +2,59 @@
 
 Media library extension for [kempo](https://github.com/dustinpoissant/kempo) — upload and manage images, video, audio, 3D models and archives, with a picker wired into the editor's image control.
 
+A media asset is a [kempo-files](https://github.com/dustinpoissant/kempo-files) file plus the metadata a media library needs (kind, dimensions, alt text), and its thumbnails come from [kempo-thumbs](https://github.com/dustinpoissant/kempo-thumbs). There is one storage layer, one set of file permissions and one thumbnail path for the whole site.
+
 ## What it does
 
 - **A media library in the admin**, at *Media* in the sidebar: a grid of thumbnails with search, filtering by type, drag-and-drop upload with per-file progress, and delete.
 - **A picker in the editor.** kempo-ui's image control grows a **Browse…** button that opens the library, so an author inserts an image by looking at it instead of remembering its URL.
-- **Thumbnails for images**, generated on upload. Other kinds show a type icon.
-- **Range-request support for free.** Uploads are stored in your site's own `public/`, so kempo-server serves them directly and video and audio seek properly.
+- **Thumbnails for images and video**, made by kempo-thumbs shortly after upload. A fresh image shows its original until the thumbnail is ready, and the grid refreshes itself. Audio and the other kinds show a type icon.
+- **Public by default, with range requests.** Files are served by kempo-files: no login for a public asset, `Range` support so video and audio seek, correct content types, and cache headers with `304` revalidation.
+
+## How it fits together
+
+```
+upload --> kempo-media --> kempo-files (bytes, name, public flag, permissions, serving)
+                |                |
+                |                +-- file:uploaded --> kempo-thumbs --> ffmpeg --> thumbnail files (also kempo-files)
+                +-- kempoMediaAsset row: kind, dimensions, alt text, display name
+```
+
+- **The asset id is the file id.** There is no mapping table, and other extensions that store a media id keep working. An asset's URL is `/kempo-files/api/files/<id>` and is stable across renames and moves.
+- **Files live in kempo-files' `files/media/` folder**, named `<id>.<ext>`. The name you uploaded is kept as the asset's display name only; it never reaches the filesystem. Nothing is written under the site's `public/` any more.
+- **Two permission layers, deliberately.** `media:*` (below) decides who may use the media API and library. What is allowed on the underlying file is kempo-files' business: its own/others permissions apply if someone opens the file in the files library, and its `public` flag decides whether the world can fetch it.
+- **Visibility is the file's `public` flag**, nothing separate. Assets are public by default, as they always were. `updateMediaAsset(id, { public: false })` (or a `PATCH` with `public: false`) closes the original, and kempo-thumbs refuses its thumbnails to anyone who could not fetch the original.
+- **kempo-thumbs is required, not optional.** One thumbnail path (ffmpeg, which also covers video frames) beats a library that sometimes has `sharp` thumbnails and sometimes none, and every consumer can count on `thumbnail` meaning the same thing. kempo-media's own `sharp` thumbnail code and the `thumbnail_max_dimension` setting are gone; thumbnail sizes, format and quality are kempo-thumbs' settings. The cost is that a thumbnail appears a moment after the upload instead of with it.
 
 ## Requirements
 
 | Package | Version | Why |
 |---|---|---|
-| `kempo` | >= 4.2.26 | Extension host |
-| `kempo-server` | >= 3.2.0 | First release with binary-safe request bodies. On anything earlier, uploaded files arrive corrupted. |
-| `kempo-ui` | >= 0.4.43 | First release with the `window.kempo.openAssetPicker` hook the editor picker uses. The library itself works without it. |
+| `kempo` | >= 4.2.39 | Extension host, including extension `dependencies` |
+| `kempo-files` | >= 0.1.5 | Storage and serving. 0.1.5 adds `uploadFile` (upload hooks), caller-chosen ids and download caching. |
+| `kempo-thumbs` | >= 0.1.3 | Thumbnails. Its ffprobe also supplies image and video dimensions. |
+| `kempo-server` | >= 3.3.0 | Binary-safe request bodies, and the file server kempo-files streams through |
+| `kempo-ui` | >= 0.4.43 | The `window.kempo.openAssetPicker` hook the editor picker uses. The library itself works without it. |
 
 ## Install
 
 ```
-npm install kempo-media
+npm install kempo-media kempo-files kempo-thumbs
 ```
 
-Then install it from kempo's admin under **Extensions**. On install it creates `public/media/uploads/` and `public/media/thumbnails/` in your site.
+Then, from kempo's admin under **Extensions**, install and enable **kempo-files**, then **kempo-thumbs**, then **kempo-media**. kempo refuses to install this one until the other two are enabled, and refuses to disable either while this is.
+
+### Upgrading from 0.2.x
+
+0.2.x kept uploads in your site's `public/media/uploads/` and made its own thumbnails. Install and enable kempo-files and kempo-thumbs, then **update kempo-media** from the Extensions screen. The update:
+
+- moves every existing asset into kempo-files **under the same id**, so products, inventory items and anything else that stored a media id are untouched; alt text, kind, dimensions, upload date and uploader are kept, and the bytes are copied exactly;
+- registers each old URL (`/media/uploads/<id>.png`) as the file's **alias**, so a page that embedded one keeps working. Aliases are resolved through kempo-files' `route:unmatched` hook, which needs the site's `public/CATCH.js` (see kempo-files' README);
+- deletes the old files and the old `sharp` thumbnails from `public/media/`, and the retired `thumbnail_max_dimension` setting;
+- asks kempo-thumbs to make new thumbnails, which appear over the next few moments;
+- then drops the old `filename`, `path` and `thumbnailPath` columns.
+
+It is safe to run again. If kempo-files or kempo-thumbs is missing, it stops before touching anything and says which. An asset whose file had already vanished from disk keeps its row and id (and is listed in the log), as it did before. The columns are only dropped once every row is accounted for, so a half-finished run resumes cleanly. Until the update has run, uploads fail, because the old table still demands the old columns.
 
 ## Permissions
 
@@ -31,8 +62,8 @@ Then install it from kempo's admin under **Extensions**. On install it creates `
 |---|---|
 | `media:browse` | List and view library assets |
 | `media:upload` | Upload new assets |
-| `media:update` | Edit alt text and rename |
-| `media:delete` | Delete assets |
+| `media:update` | Edit alt text, rename, and change visibility |
+| `media:delete` | Delete assets (and their files and thumbnails) |
 
 A `kempo-media:editor` group is created granting browse, upload and update — but not delete.
 
@@ -41,9 +72,8 @@ A `kempo-media:editor` group is created granting browse, upload and update — b
 | Name | Default | Description |
 |---|---|---|
 | `max_upload_size_mb` | `250` | Largest single file accepted |
-| `thumbnail_max_dimension` | `480` | Longest edge of generated thumbnails, in pixels |
 
-`max_upload_size_mb` sits **below** kempo-server's own `maxBodySize` (500 MB by default), which is the real ceiling. Raising this setting above that has no effect; the request is rejected before this extension sees it.
+`max_upload_size_mb` sits **below** kempo-server's own `maxBodySize` (500 MB by default), which is the real ceiling. Raising this setting above that has no effect; the request is rejected before this extension sees it. Thumbnail sizes, output format and quality are kempo-thumbs' settings.
 
 ## Accepted file types
 
@@ -55,20 +85,33 @@ A `kempo-media:editor` group is created granting browse, upload and update — b
 | 3D model | `glb` `gltf` `obj` `fbx` |
 | Archive | `zip` |
 
-**SVG is deliberately not accepted.** kempo-server serves SVG as inline, unsanitised markup on your site's own origin, so an uploaded SVG carrying a `<script>` would be stored XSS against the admin who opens it. Supporting it needs a sanitiser first, not just an entry in the list.
+**SVG is deliberately not accepted.** A web server serving SVG inline and unsanitised on your site's own origin turns an uploaded SVG carrying a `<script>` into stored XSS against the admin who opens it. Supporting it needs a sanitiser first, not just an entry in the list.
 
 ## Using assets from your own code
 
-Uploaded files are served from your site root, so an asset's `path` is its URL:
-
 ```js
-import { getMediaAssets } from 'kempo-media/sdk';
+import { getMediaAssets, getMediaAsset, uploadMediaAsset } from 'kempo-media/sdk';
 
 const [error, data] = await getMediaAssets({ kind: 'image', limit: 10 });
-// data.assets[0].path === 'media/uploads/a1b2c3d4e5f60718.png'  ->  /media/uploads/...
+const asset = data.assets[0];
 ```
 
-The same functions are available in the browser from `/kempo-media/sdk.js`, plus `uploadMedia(file, { alt }, onProgress)`.
+An asset carries its row plus what kempo-files and kempo-thumbs add:
+
+| Field | |
+|---|---|
+| `id`, `fileId` | The asset id, which is also the kempo-files file id |
+| `originalName`, `kind`, `mimeType`, `sizeBytes`, `altText`, `width`, `height`, `uploadedBy`, `createdAt`, `updatedAt` | The media row |
+| `url` / `path` | The original: `/kempo-files/api/files/<id>`, and the same without the leading slash |
+| `thumbnail` / `thumbnailPath` | The small thumbnail (kempo-thumbs' `sm` size, else its smallest ready one), the same two ways, or `null` until kempo-thumbs has made one |
+| `thumbnails` | Every size kempo-thumbs knows about, whatever its status, for a `srcset` |
+| `public` | Whether anyone can fetch it |
+
+Show `thumbnail ?? url` wherever a small image is wanted. `thumbnail` is `null` for a moment after upload, for audio without cover art, and for anything ffmpeg cannot read.
+
+`uploadMediaAsset({ filename, data, altText, uploadedBy, maxBytes, public })` stores a Buffer: it fires kempo-files' `file:before_upload` and `file:uploaded` hooks (so a site's upload policy applies and kempo-thumbs hears about the file), probes the dimensions, and resolves to the asset. `pickThumbnail(thumbnails)` is the selection rule above, exported. `createMediaAsset` registers metadata for a kempo-files file you already have.
+
+The same read functions are available in the browser from `/kempo-media/sdk.js`, plus `uploadMedia(file, { alt, public }, onProgress)` (`public` defaults to true).
 
 ## Providing your own picker
 
@@ -80,10 +123,12 @@ window.kempo.openAssetPicker = async ({ alt }) => ({ url: '/some/image.png', alt
 
 Resolve `null` to insert nothing. See kempo-ui's markdown-editor documentation for the full contract.
 
+kempo-files installs the same hook for its own library, so with both present the question is which loads last. kempo-media's picker is registered with priority `-10` (later than kempo-files' `0`), so the editor opens the media library. An extension that wants to replace both needs a priority below that.
+
 ## Local development
 
 ```
-npm run link:local   # links sibling ../kempo and ../kempo-ui checkouts
+npm run link:local   # links sibling ../kempo, ../kempo-files, ../kempo-thumbs, ../kempo-server and ../kempo-ui checkouts
 npm test
 ```
 
@@ -93,22 +138,23 @@ Note that `npm install <anything>` in a consuming project drops packages linked
 
 ### Running the database-backed tests
 
-Two suites (`tests/media-api-contract.node-test.js`, `tests/media-data-layer.node-test.js`) drive this extension against a real Postgres — one installs it and hits its actual HTTP routes, the other exercises the CRUD layer directly. Both skip themselves with a clear message when no database is reachable, so `npm test` is safe to run without one. To actually run them:
+Three suites drive this extension against a real Postgres: `media-api-contract` installs kempo-files, kempo-thumbs and kempo-media and hits the real HTTP routes of a spawned server (upload, serving, ranges, caching, the thumbnail appearing through the real hooks, visibility, delete), `media-data-layer` exercises the library functions directly, and `media-migration` runs the 0.2.x move against a recreated legacy table. They skip themselves with a clear message when no database is reachable, so `npm test` is safe to run without one — but a green run that skipped them proves nothing, so check for `(SKIPPED)`. To actually run them:
 
 ```
 docker compose up -d                                   # starts kempo-media-test-db on localhost:5435
 export DATABASE_URL=$(grep DATABASE_URL .env.example | cut -d= -f2-)
-npx drizzle-kit push --force                            # creates kempo's core tables + kempoMediaAsset
+npx drizzle-kit push --force                            # creates kempo's core tables, kempo-files', kempo-thumbs' and kempoMediaAsset
 npm test
 ```
 
-`DATABASE_URL` needs to be a real environment variable for both `drizzle-kit` and `npm test` — this repo has no dotenv step of its own to load a `.env` file, so `.env.example` is a copy-paste reference, not something read automatically.
+`DATABASE_URL` needs to be a real environment variable for both `drizzle-kit` and `npm test` — this repo has no dotenv step of its own to load a `.env` file, so `.env.example` is a copy-paste reference, not something read automatically. The suites write into `files/` in this checkout (git-ignored), and need `kempo-files` and `kempo-thumbs` linked (`npm run link:local`).
 
 `drizzle.config.js` here exists only for this — the table itself is created for real via `createTablesFromSchema` at install time, the same as it would be on a live site.
 
 ## Known limits
 
 - **Uploads are buffered in memory, not streamed to disk.** kempo-server reads the whole request body before a route runs, so a very large upload is bounded by available RAM rather than disk. `maxBodySize` is the ceiling.
-- **Thumbnails are images only.** No video frame extraction or waveforms — that needs ffmpeg and a job queue, neither of which exists here.
-- **`sharp` is a native module.** It is the one dependency that can fail to install on an unusual host. It is imported lazily, so if it is missing you get uploads without thumbnails rather than a broken extension.
+- **Thumbnails arrive after the upload**, not with it, and are generated in kempo-thumbs' in-process queue. A restart can lose queued work; its admin screen's *Generate missing* picks it back up.
+- **Only assets uploaded through this library are in it.** Other files in kempo-files do not appear in the media grid unless registered with `createMediaAsset`.
+- **A replaced public file can be cached for up to an hour** by browsers (kempo-files' cache lifetime).
 - **No usage tracking.** Deleting an asset does not check whether a page links to it.

package/admin/asset-picker.global.html

@@ -1,4 +1,4 @@
-<content id="kempo-media-asset-picker" name="Media asset picker" owner="kempo-media" enabled="true" locked="true" location="scripts" priority="0">
+<content id="kempo-media-asset-picker" name="Media asset picker" owner="kempo-media" enabled="true" locked="true" location="scripts" priority="-10">
 <script type="module">
   /*
     Installs the picker kempo-ui's image control looks for. kempo core scans every enabled
@@ -7,6 +7,11 @@
 
     The hook is read when the control's dropdown opens rather than at page load, so setting it here
     is early enough regardless of which loads first.
+
+    kempo-files installs the same hook for its own library, and this extension requires it, so both
+    are always present. Content with a lower priority renders later and the last assignment wins;
+    -10 puts this one after kempo-files' (0), so the editor opens the media library, not the raw
+    file library.
   */
   import Dialog from '/kempo-ui/components/Dialog.js';
   import '/admin/extension/kempo-media/components/MediaLibrary.js';
@@ -32,7 +37,7 @@
     };
 
     const chosen = asset => ({
-      url: `/${asset.path}`,
+      url: `/${asset.path}`, // the kempo-files URL: public, cacheable and range-capable
       // The asset's own alt text describes the file; fall back to whatever was already typed
       alt: asset.altText || alt
     });

package/admin/components/MediaLibrary.js

@@ -17,6 +17,19 @@ import { getMediaAssets, uploadMedia, deleteMediaAsset } from '/kempo-media/sdk.
 const BASE = '/admin/extension/kempo-media';
 const PAGE_SIZE = 24;
 
+/*
+  kempo-thumbs makes thumbnails after the upload, in the background, so a fresh image or video has
+  none for a moment. The grid asks again every few seconds, but only for assets young enough that a
+  thumbnail is still expected and only a bounded number of times, so a file ffmpeg cannot read does
+  not keep the library polling forever.
+*/
+const THUMBNAIL_POLL_MS = 2500;
+const THUMBNAIL_POLL_LIMIT = 8;
+const THUMBNAIL_EXPECTED_MS = 2 * 60 * 1000;
+const awaitingThumbnail = asset => ['image', 'video'].includes(asset.kind)
+  && !asset.thumbnailPath
+  && Date.now() - new Date(asset.createdAt).getTime() < THUMBNAIL_EXPECTED_MS;
+
 const formatBytes = bytes => {
   if(bytes < 1024) return `${bytes} B`;
   if(bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(0)} KB`;
@@ -53,6 +66,8 @@ export default class MediaLibrary extends ShadowComponent {
     this.dragging = false;
     this.uploads = [];
     this.selectedId = '';
+    this.pollAttempts = 0;
+    this.pollTimer = null;
   }
 
   connectedCallback() {
@@ -60,8 +75,14 @@ export default class MediaLibrary extends ShadowComponent {
     this.load();
   }
 
-  load = async () => {
-    this.loading = true;
+  disconnectedCallback() {
+    super.disconnectedCallback();
+    clearTimeout(this.pollTimer);
+  }
+
+  load = async ({ quiet = false } = {}) => {
+    clearTimeout(this.pollTimer);
+    if(!quiet) this.loading = true;
     const [error, data] = await getMediaAssets({
       kind: this.kind || undefined,
       search: this.search || undefined,
@@ -70,11 +91,16 @@ export default class MediaLibrary extends ShadowComponent {
     });
     this.loading = false;
     if(error){
-      Toast.error(`Could not load the media library: ${error.msg}`);
+      if(!quiet) Toast.error(`Could not load the media library: ${error.msg}`);
       return;
     }
     this.assets = data.assets;
     this.total = data.total;
+
+    this.pollAttempts = quiet ? this.pollAttempts + 1 : 0;
+    if(this.pollAttempts < THUMBNAIL_POLL_LIMIT && this.assets.some(awaitingThumbnail)){
+      this.pollTimer = setTimeout(() => this.load({ quiet: true }), THUMBNAIL_POLL_MS);
+    }
   };
 
   goTo = offset => {
@@ -84,9 +110,9 @@ export default class MediaLibrary extends ShadowComponent {
 
   handleSearch = e => {
     // Re-running the query on every keystroke would fire a request per character
-    clearTimeout(this._searchTimer);
+    clearTimeout(this.searchTimer);
     const value = e.target.value;
-    this._searchTimer = setTimeout(() => {
+    this.searchTimer = setTimeout(() => {
       this.search = value;
       this.offset = 0;
       this.load();
@@ -169,8 +195,8 @@ export default class MediaLibrary extends ShadowComponent {
         @dblclick=${() => this.selectable && this.dispatchEvent(new CustomEvent('asset-confirmed', { detail: { asset }, bubbles: true, composed: true }))}
       >
         <div class="preview">
-          ${asset.thumbnailPath
-            ? html`<img src="/${asset.thumbnailPath}" alt=${asset.altText || asset.originalName} loading="lazy" />`
+          ${asset.thumbnailPath || asset.kind === 'image'
+            ? html`<img src="/${asset.thumbnailPath || asset.path}" alt=${asset.altText || asset.originalName} loading="lazy" />`
             : html`<img class="type-icon" src="${BASE}/icons/${asset.kind}.svg" alt=${asset.kind} />`}
         </div>
         <div class="meta">

package/admin/nav.global.html

@@ -1,3 +1,3 @@
 <content id="kempo-media-nav" name="Media" owner="kempo-media" enabled="true" locked="true" location="admin-nav-extensions" priority="0">
-<k-aside-item icon="image" href="/admin/extension/kempo-media/" no-expand>Media</k-aside-item>
+<k-aside-item icon="image" group="Media" group-icon="image" href="/admin/extension/kempo-media/" no-expand>Media</k-aside-item>
 </content>

package/drizzle.config.js

@@ -3,10 +3,11 @@ import { defineConfig } from 'drizzle-kit';
 /*
   Local/CI test-database setup only — this extension has no migrations of its own in production.
   kempoMediaAsset is created the real way, via createTablesFromSchema at install time (see
-  install.js and installExtension in kempo's sdk), which the data-layer and API-contract test
-  suites exercise directly. This file exists so `npx drizzle-kit push` can stand up a throwaway
-  database with both kempo's core tables (user/session/permission/...) and this extension's own,
-  mirroring the schema array kempo's own app-drizzle.config.js template scaffolds into a real site.
+  installExtension in kempo's sdk), which the data-layer and API-contract test suites exercise
+  directly. This file exists so `npx drizzle-kit push` can stand up a throwaway database with
+  kempo's core tables (user/session/permission/...), the two extensions this one sits on
+  (kempo-files and kempo-thumbs) and its own, mirroring the schema array kempo's own
+  app-drizzle.config.js template scaffolds into a real site.
 
   No dotenv here on purpose: unlike a real kempo site, nothing in this repo's own runtime loads
   .env either, so pulling it in only for this file would be one more dependency to explain rather
@@ -17,6 +18,8 @@ export default defineConfig({
   schema: [
     './server/db/schema.js',
     './node_modules/kempo/server/db/schema.js',
+    './node_modules/kempo-files/server/db/schema.js',
+    './node_modules/kempo-thumbs/server/db/schema.js',
   ],
   out: './server/db/migrations',
   dialect: 'postgresql',

package/kempo-config.json

@@ -2,6 +2,7 @@
   "docs": "https://github.com/dustinpoissant/kempo-media#readme",
   "public-scope": "kempo-media",
   "schema": "./server/db/schema.js",
+  "dependencies": ["kempo-files", "kempo-thumbs"],
   "permissions": [
     { "name": "media:browse", "description": "List and view media library assets" },
     { "name": "media:upload", "description": "Upload new media assets" },
@@ -9,8 +10,7 @@
     { "name": "media:delete", "description": "Delete media assets" }
   ],
   "settings": [
-    { "name": "max_upload_size_mb", "value": "250", "type": "number", "description": "Maximum size, in MB, of a single uploaded file" },
-    { "name": "thumbnail_max_dimension", "value": "480", "type": "number", "description": "Longest edge, in pixels, of generated image thumbnails" }
+    { "name": "max_upload_size_mb", "value": "250", "type": "number", "description": "Maximum size, in MB, of a single uploaded file" }
   ],
   "groups": [
     { "name": "kempo-media:editor", "description": "Can browse, upload, and edit media", "permissions": ["media:browse", "media:upload", "media:update"] }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "kempo-media",
-  "version": "0.2.3",
-  "description": "Media library extension for kempo — upload and manage images, video, audio, 3D models, and archives",
+  "version": "0.3.0",
+  "description": "Media library extension for kempo — upload and manage images, video, audio, 3D models, and archives, stored in kempo-files with thumbnails from kempo-thumbs",
   "license": "MIT",
   "author": "Dustin Poissant",
   "type": "module",
@@ -9,13 +9,12 @@
   "scripts": {
     "build": "node scripts/build.js",
     "test": "kempo-test -l minimal",
-    "link:local": "npm install ../kempo ../kempo-ui --no-save"
+    "link:local": "npm install ../kempo ../kempo-files ../kempo-thumbs ../kempo-server ../kempo-ui --no-save --no-legacy-peer-deps --force"
   },
   "kempo": {
     "public-scope": "kempo-media"
   },
   "exports": {
-    "./install": "./install.js",
     "./update": "./update.js",
     "./sdk": "./sdk.js"
   },
@@ -24,16 +23,18 @@
     "url": "git+https://github.com/dustinpoissant/kempo-media.git"
   },
   "dependencies": {
-    "drizzle-orm": "^0.45.2",
-    "sharp": "^0.35.3"
+    "drizzle-orm": "^0.45.2"
   },
   "peerDependencies": {
-    "kempo": ">=4.2.26",
-    "kempo-server": ">=3.2.0",
+    "kempo": ">=4.2.39",
+    "kempo-files": ">=0.1.5",
+    "kempo-server": ">=3.3.0",
+    "kempo-thumbs": ">=0.1.3",
     "kempo-ui": ">=0.4.43"
   },
   "devDependencies": {
     "drizzle-kit": "^0.31.10",
-    "kempo-testing-framework": "^1.4.11"
+    "kempo-testing-framework": "^1.4.11",
+    "postgres": "^3.4.9"
   }
 }

package/public/api/media/DELETE.js

@@ -1,9 +1,6 @@
-import { join } from 'path';
 import { currentUserHasPermission } from 'kempo/server/sdk.js';
 import deleteMediaAsset from '../../../server/utils/media/deleteMediaAsset.js';
 
-const ROOT_DIR = join(process.cwd(), 'public');
-
 export default async (request, response) => {
   const token = request.cookies.session_token;
 
@@ -14,7 +11,7 @@ export default async (request, response) => {
   const { id } = request.body || {};
   if(!id) return response.status(400).json({ error: 'An asset id is required' });
 
-  const [error, data] = await deleteMediaAsset(id, { rootDir: ROOT_DIR });
+  const [error, data] = await deleteMediaAsset(id);
   if(error) return response.status(error.code).json({ error: error.msg });
 
   response.json(data);

package/public/api/media/PATCH.js

@@ -8,10 +8,10 @@ export default async (request, response) => {
   if(permError) return response.status(permError.code).json({ error: permError.msg });
   if(!canUpdate) return response.status(403).json({ error: 'Insufficient permissions' });
 
-  const { id, altText, originalName } = request.body || {};
+  const { id, altText, originalName, public: isPublic } = request.body || {};
   if(!id) return response.status(400).json({ error: 'An asset id is required' });
 
-  const [error, asset] = await updateMediaAsset(id, { altText, originalName });
+  const [error, asset] = await updateMediaAsset(id, { altText, originalName, public: isPublic });
   if(error) return response.status(error.code).json({ error: error.msg });
 
   response.json({ asset });

package/public/api/media/POST.js

@@ -1,10 +1,6 @@
-import { join } from 'path';
 import { getSession, currentUserHasPermission, getSetting } from 'kempo/server/sdk.js';
 import parseMultipart, { extractBoundary } from '../../../server/utils/uploads/parseMultipart.js';
-import storeUpload from '../../../server/utils/uploads/storeUpload.js';
-import createMediaAsset from '../../../server/utils/media/createMediaAsset.js';
-
-const ROOT_DIR = join(process.cwd(), 'public');
+import uploadMediaAsset from '../../../server/utils/media/uploadMediaAsset.js';
 
 export default async (request, response) => {
   const token = request.cookies.session_token;
@@ -34,24 +30,19 @@ export default async (request, response) => {
   }
 
   const altPart = parts.find(p => p.name === 'alt' && !p.filename);
+  const publicPart = parts.find(p => p.name === 'public' && !p.filename);
 
   const [, maxUploadMb] = await getSetting('kempo-media', 'max_upload_size_mb', 250);
-  const [, thumbnailMaxDimension] = await getSetting('kempo-media', 'thumbnail_max_dimension', 480);
-
-  const [storeError, asset] = await storeUpload({
-    rootDir: ROOT_DIR,
+  const [error, asset] = await uploadMediaAsset({
     filename: filePart.filename,
     data: filePart.data,
-    mimeType: filePart.contentType,
     altText: altPart ? altPart.data.toString('utf8') : '',
     uploadedBy: session.user.id,
     maxBytes: Number(maxUploadMb) * 1024 * 1024,
-    thumbnailMaxDimension: Number(thumbnailMaxDimension),
+    public: publicPart?.data.toString('utf8') !== 'false',
+    request,
   });
-  if(storeError) return response.status(storeError.code).json({ error: storeError.msg });
-
-  const [recordError, row] = await createMediaAsset(asset);
-  if(recordError) return response.status(recordError.code).json({ error: recordError.msg });
+  if(error) return response.status(error.code).json({ error: error.msg });
 
-  response.status(201).json({ asset: row });
+  response.status(201).json({ asset });
 };

package/public/sdk.js

@@ -33,10 +33,11 @@ export const deleteMediaAsset = id => req('DELETE', `${BASE}/media`, { id });
   has no way to report how far a request body has been sent, and a progress bar is the difference
   between a usable upload of a large video and one that looks frozen.
 */
-export const uploadMedia = (file, { alt = '' } = {}, onProgress) => new Promise(resolve => {
+export const uploadMedia = (file, { alt = '', public: isPublic = true } = {}, onProgress) => new Promise(resolve => {
   const form = new FormData();
   form.append('file', file);
   if(alt) form.append('alt', alt);
+  if(!isPublic) form.append('public', 'false');
 
   const xhr = new XMLHttpRequest();
   xhr.open('POST', `${BASE}/media`);

package/sdk.js

@@ -4,12 +4,14 @@
   /kempo-media/sdk.js — same names, different transport.
 */
 
+export { default as uploadMediaAsset } from './server/utils/media/uploadMediaAsset.js';
 export { default as createMediaAsset } from './server/utils/media/createMediaAsset.js';
 export { default as getMediaAsset } from './server/utils/media/getMediaAsset.js';
 export { default as getMediaAssets } from './server/utils/media/getMediaAssets.js';
 export { default as updateMediaAsset } from './server/utils/media/updateMediaAsset.js';
 export { default as deleteMediaAsset } from './server/utils/media/deleteMediaAsset.js';
 
-export { default as storeUpload } from './server/utils/uploads/storeUpload.js';
+export { pickThumbnail } from './server/utils/media/describeAssets.js';
+
 export { default as parseMultipart, extractBoundary } from './server/utils/uploads/parseMultipart.js';
 export { ALLOWED_TYPES, KINDS, typeForFilename } from './server/utils/uploads/fileTypes.js';

package/server/db/schema.js

@@ -1,14 +1,16 @@
 import { pgTable, text, integer, timestamp } from 'drizzle-orm/pg-core';
 
+/*
+  What a media asset adds to a kempo-files file. The bytes, the name on disk, who may fetch them and
+  the thumbnails all belong to kempo-files and kempo-thumbs; this row holds only what a media
+  library needs on top: the kind, the dimensions, the display name and the alt text.
+*/
 export const kempoMediaAsset = pgTable('kempoMediaAsset', {
-  id: text('id').primaryKey(), // crypto.randomBytes(8).toString('hex')
-  filename: text('filename').notNull(), // server-generated name on disk — never derived from user input
+  id: text('id').primaryKey(), // also the id of the kempo-files file behind it, so no mapping table
   originalName: text('originalName').notNull(),
   mimeType: text('mimeType').notNull(),
   kind: text('kind').notNull(), // 'image' | 'video' | 'audio' | 'model3d' | 'archive'
   sizeBytes: integer('sizeBytes').notNull(),
-  path: text('path').notNull(), // relative to the site's public/, e.g. 'media/uploads/<id>.png'
-  thumbnailPath: text('thumbnailPath'), // images only; null for every other kind
   altText: text('altText').notNull().default(''),
   width: integer('width'),
   height: integer('height'),