@pramen/cms 0.0.61 → 0.0.64

package/dist/index.js

@@ -603,6 +603,18 @@ export const cmsSchema = {
         // Hierarchical vocabularies allow `parentId` on their terms; flat ones reject it on
         // write. Enforced in the handler, not the schema — one term table serves both.
         hierarchical: defaultTo(t.bool(), false),
+        // What this vocabulary classifies — a subset of `TAXONOMY_TARGETS`. NULL means EVERYTHING,
+        // which is both the backward-compatible reading for rows written before this column and a
+        // legitimate authored value ("Topics classifies whatever there is"). Without it a site with
+        // "Categories" for articles and tags for images offers both on both, so a photo can be
+        // filed under "Local news" and `getTermTree("category")` fills up with terms like "hero"
+        // that no page listing will ever use.
+        //
+        // A `t.json()` array rather than two booleans: the set of things a CMS classifies grows
+        // (collections are the obvious next one), and a column per target would need a migration
+        // each time. It is not queryable — JSON in a TEXT cell — but nothing pages by taxonomy:
+        // `listTaxonomies` reads them all and narrows in memory.
+        appliesTo: t.json(),
         createdAt: defaultTo(t.text(), expr.now()),
     })),
     cms_terms: Entity((t) => ({
@@ -622,6 +634,7 @@ export const cmsSchema = {
         taxonomy: r.belongsTo("cms_taxonomies", "taxonomyId", { onDelete: "cascade" }),
         parent: r.belongsTo("cms_terms", "parentId", { onDelete: "setNull" }),
         pages: r.hasMany("cms_page_terms", "termId"),
+        media: r.hasMany("cms_media_terms", "termId"),
     }), 
     // A slug identifies a term WITHIN its vocabulary — `/category/news` and `/tag/news`
     // are two different terms, and both are legitimate.
@@ -640,6 +653,23 @@ export const cmsSchema = {
     // One assignment per (page, term). Without it a double-submit leaves a page tagged
     // twice and every `with: { terms: true }` renders the term twice.
     { unique: [["pageId", "termId"]] }),
+    // The same junction for media. A SECOND table rather than one polymorphic
+    // `cms_object_terms(objectType, objectId, termId)`: a polymorphic key cannot carry a real
+    // foreign key, and the FKs are what does the work here — purging a media row or deleting a
+    // term takes its assignments with it, with no handler remembering to. A `where` traversal
+    // also needs a typed column to join on; `objectId` would have to be filtered by a
+    // discriminator the read engine has no way to require, so one forgotten `objectType`
+    // clause silently mixes a page's tags into a media query.
+    cms_media_terms: Entity((t) => ({
+        id: primaryKey(generated(t.uuid())),
+        mediaId: indexed(notNull(t.uuid())),
+        termId: indexed(notNull(t.uuid())),
+    }), (r) => ({
+        // `cascade` on both ends, as on the page junction. Note this fires on PURGE, not on
+        // trashing: `deleteMedia` only stamps `deletedAt`, so a restored file keeps its tags.
+        media: r.belongsTo("cms_media", "mediaId", { onDelete: "cascade" }),
+        term: r.belongsTo("cms_terms", "termId", { onDelete: "cascade" }),
+    }), { unique: [["mediaId", "termId"]] }),
     // A named template region an admin fills without touching code — the sidebar, the footer
     // column, the pre-footer strip.
     //
@@ -665,16 +695,166 @@ export const cmsSchema = {
     cms_media: Entity((t) => ({
         id: primaryKey(generated(t.uuid())),
         file: t.fileRef(),
+        // The three fields the library SORTS and FILTERS by, projected out of `file` into real
+        // columns. `file` is a `t.fileRef()` — JSON in a TEXT cell — so its `filename`,
+        // `contentType` and `size` are invisible to `orderBy` and `where`, and sorting a library
+        // after the page has been fetched sorts one page, which is not sorting.
+        //
+        // A duplicate, deliberately, and the cost is named: they are written where a media row is
+        // CREATED and nowhere else (`updateMedia` never touches the file), so there is one writer
+        // and `file` stays the source of truth for serving. SQLite generated columns would remove
+        // the duplication outright — `GENERATED ALWAYS AS (json_extract(file,'$.filename'))` — but
+        // the schema DSL has no way to declare one, and `generated()` here means something else
+        // entirely (auto-mint a uuid on insert).
+        //
+        // Nullable, so adding them is a plain `ADD COLUMN` on an existing store rather than a
+        // gated table rebuild; `cmsMigrations` backfills what is already there.
+        filename: indexed(t.text()),
+        contentType: indexed(t.text()),
+        size: t.int(),
         alt: t.text(),
         // Soft delete, as on cms_pages. The R2 OBJECT is deliberately kept while a media row
         // is trashed — deleting the bytes would make restore a lie. `purgeMedia` drops both.
         deletedAt: indexed(t.text()),
         createdAt: defaultTo(t.text(), expr.now()),
+    }), (r) => ({
+        // Media is classified by the SAME vocabularies pages are, through the same `cms_terms`
+        // table — a deployment that declares "Topics" gets to tag a photo with one without
+        // declaring it twice, and the terms screen stays the one place a vocabulary is edited.
+        //
+        // The traversal is what makes tagging worth having: `where: { terms: { id } }` compiles
+        // to a subquery through the junction, so the library filters by term IN SQL like it
+        // filters by kind. A tag you cannot filter a paged library by is decoration.
+        terms: r.manyToMany("cms_terms", { through: "cms_media_terms", sourceColumn: "mediaId", targetColumn: "termId" }),
     })),
 };
+/** …resolved to the order the read engine takes. `createdAt` is ISO-8601 TEXT (`expr.now()`),
+ * so a lexicographic sort on it IS chronological. */
+const MEDIA_SORTS = {
+    newest: { column: "createdAt", dir: "desc" },
+    oldest: { column: "createdAt", dir: "asc" },
+    name: { column: "filename", dir: "asc" },
+    name_desc: { column: "filename", dir: "desc" },
+    largest: { column: "size", dir: "desc" },
+    smallest: { column: "size", dir: "asc" },
+};
+/** The coarse type buckets the library filters by — the first segment of a MIME type, which
+ * is the distinction someone browsing a library actually makes ("show me the images"). */
+export const MEDIA_KINDS = ["image", "video", "audio", "document", "other"];
+/** MIME prefixes for the buckets that have one. `document` is a LIST rather than a prefix
+ * because the useful documents share no MIME family — a PDF is `application/pdf` and a Word
+ * file is `application/vnd.openxmlformats-…`. */
+const DOCUMENT_PREFIXES = ["application/pdf", "text/", "application/msword", "application/vnd."];
+/** Trim and cap a search needle. Capped because it lands in a `LIKE` pattern: the engine
+ * escapes `%` and `_` for us, so this is not an injection guard — it is a bound on work a
+ * caller can ask the database to do per row. */
+function mediaQuery(raw) {
+    const q = typeof raw === "string" ? raw.trim().slice(0, 120) : "";
+    return q === "" ? undefined : q;
+}
+/** Match a needle against the two fields that NAME a file: what it was uploaded as, and what
+ * an editor wrote about it. `alt` is included because it is the only human description a
+ * media row carries, and searching a library for "logo" should find the file somebody
+ * described as a logo even when the upload was called `IMG_2831.png`. */
+function mediaSearchWhere(q) {
+    return { OR: [{ filename: { contains: q } }, { alt: { contains: q } }] };
+}
+/** The `where` clause for one bucket, or `undefined` for "everything".
+ *
+ * `other` is the interesting one: it is defined as NOT any of the buckets that have a
+ * definition, so a file type nobody anticipated still has exactly one home rather than
+ * disappearing from every filter. A row whose `contentType` is NULL — uploaded before the
+ * projection columns existed and never backfilled — lands there too, which is the honest
+ * place for it.
+ *
+ * That NULL case needs its OWN clause, and did not have one. SQL is three-valued: against a
+ * NULL column every `LIKE` is NULL, so the `OR` is NULL and `NOT NULL` is NULL — which is not
+ * TRUE, so the row is excluded. `other` therefore matched everything except the rows it
+ * documents as belonging there, and a legacy row was invisible under ALL FIVE chips, with only
+ * "clear the filter" to find it and nothing on screen saying why. Exactly the deployment that
+ * upgraded and did not spread `cmsMigrations`. */
+function mediaKindWhere(kind) {
+    if (kind === undefined)
+        return undefined;
+    if (kind === "image" || kind === "video" || kind === "audio")
+        return { contentType: { startsWith: `${kind}/` } };
+    const documents = { OR: DOCUMENT_PREFIXES.map((p) => ({ contentType: { startsWith: p } })) };
+    if (kind === "document")
+        return documents;
+    const known = { OR: [{ contentType: { startsWith: "image/" } }, { contentType: { startsWith: "video/" } }, { contentType: { startsWith: "audio/" } }, documents] };
+    return { OR: [{ contentType: { isNull: true } }, { NOT: known }] };
+}
+// --- taxonomies: what a vocabulary classifies ---------------------------------------------
+/** The object types a vocabulary can be applied to. A CLOSED vocabulary, like `MEDIA_KINDS`:
+ * it decides which panels offer a taxonomy AND which assignments are accepted, so an unknown
+ * value must not be storable. */
+export const TAXONOMY_TARGETS = ["page", "media"];
+/** Whether a vocabulary applies to `target`.
+ *
+ * The permissive readings all collapse to TRUE, deliberately: NULL (never narrowed, or written
+ * before the column existed), a non-array, an array of things that are not targets. A stored
+ * value nobody can interpret must not silently stop a vocabulary from working — the failure
+ * would be a taxonomy that has quietly vanished from every panel, with the row still there. */
+export function taxonomyApplies(row, target) {
+    const list = row.appliesTo;
+    if (!Array.isArray(list))
+        return true;
+    const targets = list.filter((v) => TAXONOMY_TARGETS.includes(v));
+    return targets.length === 0 || targets.includes(target);
+}
+/** Parse an `appliesTo` input. `undefined` stays undefined (the field was not sent); `null`
+ * clears the narrowing back to "everything". An unknown target is a 400 rather than a silent
+ * drop — dropping it would store a NARROWER set than the caller asked for, which is the one
+ * direction that loses assignments. */
+function parseAppliesTo(raw) {
+    if (raw === undefined)
+        return undefined;
+    if (raw === null)
+        return null;
+    if (!Array.isArray(raw))
+        throw new BadRequest("appliesTo must be a list or null");
+    const out = [];
+    for (const v of raw) {
+        if (typeof v !== "string" || !TAXONOMY_TARGETS.includes(v)) {
+            throw new BadRequest(`appliesTo must contain only ${TAXONOMY_TARGETS.join(", ")}`);
+        }
+        if (!out.includes(v))
+            out.push(v);
+    }
+    // A vocabulary that classifies nothing is not a narrowing, it is a vocabulary nobody can
+    // reach — and it reads identically to NULL in storage, which means the opposite.
+    if (out.length === 0)
+        throw new BadRequest("appliesTo must name at least one of " + TAXONOMY_TARGETS.join(", "));
+    return out;
+}
+/** Refuse term ids from a vocabulary that does not classify `target`.
+ *
+ * The write side, not just the UI. Hiding a vocabulary from a panel without changing what the
+ * server accepts is the `hideI18n` mistake this package already retired once: the control
+ * disappears, the request does not, and `appliesTo` becomes a hint rather than a rule. It also
+ * has to be here for the assignments the panel never made — a script, a migration, an older
+ * editor build that has not learned the capability.
+ *
+ * Reads the terms' taxonomies through `ctx.db`, so an unreadable vocabulary refuses the
+ * assignment rather than being waved through. */
+async function assertTermsApplyTo(db, termIds, target) {
+    if (termIds.length === 0)
+        return;
+    const terms = await db.find({ from: "cms_terms", where: { id: { in: [...termIds] } }, select: ["id", "taxonomyId"], limit: termIds.length });
+    const taxIds = [...new Set(terms.map((t) => String(t.taxonomyId)))];
+    if (taxIds.length === 0)
+        return;
+    const taxa = await db.find({ from: "cms_taxonomies", where: { id: { in: taxIds } }, select: ["id", "slug", "appliesTo"], limit: taxIds.length });
+    const bad = taxa.filter((t) => !taxonomyApplies(t, target));
+    if (bad[0])
+        throw new BadRequest(`vocabulary '${String(bad[0].slug)}' does not apply to ${target}`);
+}
 /** Block Kit — custom admin pages, described as JSON and rendered by the editor. See
  * `./blockkit`. Re-exported so a host imports `adminPage` beside `collection`. */
-export { adminPage, createAdminPageHandlers, normalizeAdminResponse, validateAdminPages, MAX_ADMIN_BLOCK_DEPTH, } from "./blockkit";
+export { adminPage, createAdminPageHandlers, normalizeAdminResponse, validateAdminPages, ADMIN_ELEMENT_TYPES, ADMIN_PAGE_KINDS, MAX_ADMIN_BLOCK_DEPTH, } from "./blockkit";
+/** Custom admin PANELS — a project's own React screen inside the editor's chrome, for the
+ * screens a server-driven vocabulary cannot carry. See `./panel`. */
+export { adminPanel, isAdminPanel } from "./panel";
 /**
  * Columns this package wrote in the pre-ISO space form that the SCHEMA cannot identify.
  *
@@ -2503,9 +2683,35 @@ export function createCmsHandlers(opts = {}) {
         // same way it creates its content types. A vocabulary that is hierarchical allows
         // `parentId` on its terms; a flat one refuses it rather than storing something no
         // listing renders.
-        /** Every vocabulary. PUBLIC — like content types, a taxonomy's slug is structural (it
-         * is a URL segment) and a front end routes on it. */
-        listTaxonomies: query((ctx) => cdb(ctx).find({ from: "cms_taxonomies", orderBy: { column: "label" }, limit: PAGE_LIST_MAX_LIMIT })),
+        /** Every vocabulary, or just the ones that classify `target`. PUBLIC — like content
+         * types, a taxonomy's slug is structural (it is a URL segment) and a front end routes on
+         * it.
+         *
+         * Narrowed HERE rather than in each caller, so the page panel, the media panel and the
+         * write-side guard cannot disagree about what a vocabulary applies to. In memory, because
+         * `appliesTo` is a `t.json()` column that `where` cannot see into — which costs nothing:
+         * this handler already reads every taxonomy, and nothing pages by them.
+         *
+         * No `target` means EVERY vocabulary, which is what the Taxonomies screen needs: the one
+         * place that edits `appliesTo` must be able to see a vocabulary it has narrowed away. */
+        listTaxonomies: query(async (ctx, input) => {
+            const rows = await cdb(ctx).find({ from: "cms_taxonomies", orderBy: { column: "label" }, limit: PAGE_LIST_MAX_LIMIT });
+            const target = input?.target;
+            return target === undefined ? rows : rows.filter((r) => taxonomyApplies(r, target));
+        }, {
+            input: (raw) => {
+                const t = asObj(raw).target;
+                // Unrecognised narrows to nothing rather than falling back to everything: this one
+                // decides what a panel OFFERS, and answering "all of them" to a question the server
+                // did not understand is how a media panel ends up listing page-only vocabularies.
+                if (t === undefined || t === null)
+                    return {};
+                if (typeof t !== "string" || !TAXONOMY_TARGETS.includes(t)) {
+                    throw new BadRequest(`target must be one of ${TAXONOMY_TARGETS.join(", ")}`);
+                }
+                return { target: t };
+            },
+        }),
         createTaxonomy: mutation(async (ctx, input) => {
             const db = cdb(ctx);
             const clash = await db.find({ from: "cms_taxonomies", where: { slug: input.slug }, select: ["id"], limit: 1 });
@@ -2517,6 +2723,9 @@ export function createCmsHandlers(opts = {}) {
                 pluralLabel: input.pluralLabel ?? null,
                 description: input.description ?? null,
                 hierarchical: input.hierarchical ?? false,
+                // Unsent means EVERY target, which is what a vocabulary created before this existed
+                // means too — one reading of NULL, so an old row and a new one behave alike.
+                appliesTo: input.appliesTo ?? null,
             });
         }, {
             ...editor,
@@ -2528,6 +2737,7 @@ export function createCmsHandlers(opts = {}) {
                     pluralLabel: typeof o.pluralLabel === "string" ? o.pluralLabel : undefined,
                     description: typeof o.description === "string" ? o.description : undefined,
                     hierarchical: typeof o.hierarchical === "boolean" ? o.hierarchical : undefined,
+                    appliesTo: parseAppliesTo(o.appliesTo),
                 };
             },
         }),
@@ -2536,7 +2746,14 @@ export function createCmsHandlers(opts = {}) {
          *
          * Turning `hierarchical` OFF is refused while any term still has a parent. Allowing it
          * would leave a stored hierarchy that no reader renders and no writer can clear, and
-         * flattening the terms silently is a destructive edit behind a checkbox. */
+         * flattening the terms silently is a destructive edit behind a checkbox.
+         *
+         * NARROWING `appliesTo` is refused on exactly the same grounds, and it is the same bug:
+         * dropping a target this vocabulary is already used for would strand those assignments —
+         * still stored, still returned by `listPageTerms`/`listMediaTerms`, but invisible in the
+         * panel that could remove them, because the panel only renders vocabularies that apply.
+         * Unassign them first; then the narrowing is a settings change rather than a silent
+         * orphaning. WIDENING is always fine — it strands nothing. */
         updateTaxonomy: mutation(async (ctx, input) => {
             const db = cdb(ctx);
             const rows = await db.find({ from: "cms_taxonomies", where: { id: input.id }, limit: 1 });
@@ -2548,8 +2765,20 @@ export function createCmsHandlers(opts = {}) {
                 if (nested[0])
                     throw new BadRequest("this vocabulary still has nested terms — move them to the top level before making it flat");
             }
+            if (input.appliesTo !== undefined && input.appliesTo !== null) {
+                const next = input.appliesTo;
+                for (const target of TAXONOMY_TARGETS) {
+                    // Only a target this vocabulary applies to TODAY and would not after the patch.
+                    if (next.includes(target) || !taxonomyApplies(row, target))
+                        continue;
+                    const junction = target === "page" ? "cms_page_terms" : "cms_media_terms";
+                    const used = await db.find({ from: junction, where: { term: { taxonomyId: input.id } }, select: ["id"], limit: 1 });
+                    if (used[0])
+                        throw new BadRequest(`this vocabulary is still assigned to ${target === "page" ? "pages" : "media"} — remove those assignments before narrowing it`);
+                }
+            }
             const patch = {};
-            for (const k of ["label", "pluralLabel", "description", "hierarchical"]) {
+            for (const k of ["label", "pluralLabel", "description", "hierarchical", "appliesTo"]) {
                 if (input[k] !== undefined)
                     patch[k] = input[k];
             }
@@ -2569,6 +2798,9 @@ export function createCmsHandlers(opts = {}) {
                     out.description = typeof o.description === "string" ? o.description : null;
                 if (typeof o.hierarchical === "boolean")
                     out.hierarchical = o.hierarchical;
+                const appliesTo = parseAppliesTo(o.appliesTo);
+                if (appliesTo !== undefined)
+                    out.appliesTo = appliesTo;
                 return out;
             },
         }),
@@ -2752,6 +2984,7 @@ export function createCmsHandlers(opts = {}) {
                 const found = await db.find({ from: "cms_terms", where: { id: { in: [...wanted] } }, select: ["id"], limit: wanted.size });
                 if (found.length !== wanted.size)
                     throw new BadRequest("one or more termIds are not terms");
+                await assertTermsApplyTo(db, [...wanted], "page");
             }
             const existing = await db.find({ from: "cms_page_terms", where: { pageId: input.pageId }, select: ["id", "termId"], limit: MAX_TERMS });
             const have = new Map(existing.map((l) => [String(l.termId), String(l.id)]));
@@ -2951,7 +3184,15 @@ export function createCmsHandlers(opts = {}) {
                 filename: input.ref.filename,
                 uploadedAt: Date.now(),
             };
-            return cdb(ctx).insert("cms_media", { file, alt: input.alt ?? null });
+            // The projection columns go in beside `file`, from the SAME resolved values — never
+            // from `input`, which is the client's claim about a blob it has just uploaded.
+            return cdb(ctx).insert("cms_media", {
+                file,
+                filename: file.filename ?? null,
+                contentType: file.contentType ?? null,
+                size: file.size ?? null,
+                alt: input.alt ?? null,
+            });
         }, {
             ...editor,
             input: (raw) => {
@@ -2973,8 +3214,40 @@ export function createCmsHandlers(opts = {}) {
         listMedia: query((ctx, input) => {
             const limit = Math.min(Math.max(Math.trunc(Number(input?.limit ?? 50)) || 50, 1), 200);
             const offset = Math.max(Math.trunc(Number(input?.offset ?? 0)) || 0, 0);
-            return cdb(ctx).find({ from: "cms_media", orderBy: { column: "createdAt", dir: "desc" }, limit, offset });
-        }, viewer),
+            // The narrowings AND together — a search inside a type filter inside a tag is all
+            // three. Built as a list so none has to know whether the others are present.
+            const clauses = [
+                mediaKindWhere(input?.kind),
+                input?.q ? mediaSearchWhere(input.q) : undefined,
+                // A relation traversal, compiled to a subquery through `cms_media_terms`. Filtering
+                // by term therefore costs the same page of rows as filtering by kind — the whole
+                // reason the assignments are a junction rather than a JSON array on the media row.
+                input?.term ? { terms: { id: input.term } } : undefined,
+            ].filter((c) => c !== undefined);
+            const where = clauses.length === 0 ? undefined : clauses.length === 1 ? clauses[0] : { AND: clauses };
+            return cdb(ctx).find({ from: "cms_media", where, orderBy: MEDIA_SORTS[input?.sort ?? "newest"], limit, offset });
+        }, {
+            ...viewer,
+            // Parsed, not cast: `sort` names an ORDER BY and `kind` a WHERE, and both arrive from a
+            // browser. Anything unrecognised falls back to the default rather than erroring — a
+            // stale bookmark carrying a sort this build dropped should show the library, not a 400.
+            input: (raw) => {
+                const o = asObj(raw);
+                const sort = typeof o.sort === "string" && o.sort in MEDIA_SORTS ? o.sort : undefined;
+                const kind = typeof o.kind === "string" && MEDIA_KINDS.includes(o.kind) ? o.kind : undefined;
+                return {
+                    limit: typeof o.limit === "number" ? o.limit : undefined,
+                    offset: typeof o.offset === "number" ? o.offset : undefined,
+                    sort,
+                    kind,
+                    q: mediaQuery(o.q),
+                    // An id, not a slug: a slug identifies a term only within its vocabulary, and the
+                    // filter has no vocabulary to resolve it against. An id that is not a term matches
+                    // nothing, which is the same answer as a term with no files.
+                    term: typeof o.term === "string" && o.term !== "" ? o.term : undefined,
+                };
+            },
+        }),
         getMedia: query(async (ctx, input) => {
             const rows = await cdb(ctx).find({ from: "cms_media", where: { id: input.id }, limit: 1 });
             return rows[0] ?? null;
@@ -3002,6 +3275,74 @@ export function createCmsHandlers(opts = {}) {
                 return { id: o.id, alt: typeof o.alt === "string" ? o.alt : null };
             },
         }),
+        /** A media asset's assigned terms.
+         *
+         * The media row is read FIRST, through `ctx.db`, so the caller's own scope decides
+         * whether this answers — the junction and `cms_terms` are granted unscoped, so without
+         * it anyone holding an id could read a TRASHED file's tags and the non-empty answer
+         * would confirm the file exists. Same rule as `listPageTerms`, for the same reason. */
+        listMediaTerms: query(async (ctx, input) => {
+            const db = cdb(ctx);
+            const media = await db.find({ from: "cms_media", where: { id: input.mediaId }, select: ["id"], limit: 1 });
+            if (!media[0])
+                return [];
+            const links = await db.find({ from: "cms_media_terms", where: { mediaId: input.mediaId }, select: ["termId"], limit: MAX_TERMS });
+            const ids = links.map((l) => String(l.termId));
+            if (ids.length === 0)
+                return [];
+            const rows = await db.find({ from: "cms_terms", where: { id: { in: ids } }, orderBy: [{ column: "position" }, { column: "label" }], limit: ids.length });
+            return rows;
+        }, {
+            ...viewer,
+            input: (raw) => {
+                const id = asObj(raw).mediaId;
+                if (typeof id !== "string" || id === "")
+                    throw new BadRequest("mediaId is required");
+                return { mediaId: id };
+            },
+        }),
+        /** Replace a media asset's term assignments wholesale — set semantics, like
+         * `setPageTerms`, and for the same reason: the panel holds the whole selection, and two
+         * calls each patching one end of it race into a state neither asked for. */
+        setMediaTerms: mutation(async (ctx, input) => {
+            const db = cdb(ctx);
+            const media = await db.find({ from: "cms_media", where: { id: input.mediaId }, select: ["id"], limit: 1 });
+            if (!media[0])
+                throw notFound("media");
+            const wanted = new Set(input.termIds);
+            if (wanted.size > 0) {
+                const found = await db.find({ from: "cms_terms", where: { id: { in: [...wanted] } }, select: ["id"], limit: wanted.size });
+                if (found.length !== wanted.size)
+                    throw new BadRequest("one or more termIds are not terms");
+                await assertTermsApplyTo(db, [...wanted], "media");
+            }
+            const existing = await db.find({ from: "cms_media_terms", where: { mediaId: input.mediaId }, select: ["id", "termId"], limit: MAX_TERMS });
+            const have = new Map(existing.map((l) => [String(l.termId), String(l.id)]));
+            for (const [termId, linkId] of have)
+                if (!wanted.has(termId))
+                    await db.delete("cms_media_terms", linkId);
+            for (const termId of wanted)
+                if (!have.has(termId))
+                    await db.insert("cms_media_terms", { mediaId: input.mediaId, termId });
+            return { ok: true, count: wanted.size };
+        }, {
+            ...editor,
+            input: (raw) => {
+                const o = asObj(raw);
+                if (typeof o.mediaId !== "string" || o.mediaId === "")
+                    throw new BadRequest("mediaId is required");
+                if (!Array.isArray(o.termIds))
+                    throw new BadRequest("termIds must be a list");
+                const ids = o.termIds.map((v) => {
+                    if (typeof v !== "string" || v === "")
+                        throw new BadRequest("termIds must be a list of ids");
+                    return v;
+                });
+                if (ids.length > MAX_TERMS)
+                    throw new BadRequest(`a file may carry at most ${MAX_TERMS} terms`);
+                return { mediaId: o.mediaId, termIds: ids };
+            },
+        }),
         /** Trash a media row. The R2 OBJECT IS KEPT — deleting the bytes here would make
          * `restoreMedia` a lie, and a block still referencing the id would render a dead url
          * with no way back. `purgeMedia` is what drops both — and `listTrash` is how you find
@@ -3420,6 +3761,11 @@ export function createCmsHandlers(opts = {}) {
             // the next cold start. That is GitHub #48 in the deployment that upgraded the editor to
             // fix it. Absent ⇒ the editor treats no type as code-defined, which is correct there.
             codeDefinedTypes: true,
+            // Media carries taxonomy terms, and `listMedia` understands `term`. Declared for the
+            // usual reason: an older server has neither handler, so the detail panel's Tags
+            // section would 404 on open and the library's tag filter would send an argument that
+            // is ignored — a filter that visibly does nothing. Absent ⇒ neither is drawn.
+            mediaTerms: true,
             // PER-CALLER, unlike everything else here. `viewer` is `editorRoles ∪ reviewerRoles`,
             // so a reviewer-only session reaches this handler and every read handler — but every
             // WRITE is `editorRoles`. Without this the editor renders the authoring surfaces
@@ -4035,7 +4381,7 @@ export function cmsPolicies(opts = {}) {
         "cms_content_types", "cms_block_types", "cms_blocks", "cms_pages", "cms_page_blocks", "cms_page_revisions", "cms_media", "cms_audit",
         // Site furniture. Full CRUD for an editor, like every other cms_ table — the per-handler
         // `auth` gate is what separates editor from reviewer; this is the row scope.
-        "cms_menus", "cms_redirects", "cms_taxonomies", "cms_terms", "cms_page_terms", "cms_widget_areas",
+        "cms_menus", "cms_redirects", "cms_taxonomies", "cms_terms", "cms_page_terms", "cms_media_terms", "cms_widget_areas",
     ];
     // Soft-deleted rows are filtered in the ACL, not in each handler. A read scope is
     // AND-merged into every `ctx.db` read, so one policy hides a trashed row from the public
@@ -4092,6 +4438,10 @@ export function cmsPolicies(opts = {}) {
             policy(`${p}:public:taxonomies:read`, "cms_taxonomies", "read", allow()),
             policy(`${p}:public:terms:read`, "cms_terms", "read", allow()),
             policy(`${p}:public:page-terms:read`, "cms_page_terms", "read", allow()),
+            // The media junction, for the same reason as the page one: `where: { terms: … }` on a
+            // media row compiles to a subquery THROUGH it, so without the grant the library's tag
+            // filter matches nothing and reads as "no files carry this tag".
+            policy(`${p}:public:media-terms:read`, "cms_media_terms", "read", allow()),
             policy(`${p}:public:widget-areas:read`, "cms_widget_areas", "read", allow()),
         ],
         editor: editorPolicies,
@@ -5165,6 +5515,61 @@ export function createCollectionTasks(collections) {
  * between the revision insert and the page update leaves the page unpublished with an orphan
  * revision until the next at-least-once redelivery re-runs (the token still matches, so it
  * completes). Acceptable for a scheduled job; the interactive path is atomic. */
+/**
+ * The CMS's own data migrations — spread into `app.migrations`.
+ *
+ *     migrations: [...cmsMigrations]
+ *
+ * Opt-in like every other fragment this package ships (`cmsHandlers`, `cmsPolicies`,
+ * `cmsTasks`), and with the same consequence for forgetting it: nothing breaks loudly. Media
+ * rows written before the projection columns existed keep NULL `filename`/`contentType`, so
+ * they sort together under a name sort and answer only the `other` type filter. New uploads
+ * are unaffected — `createMedia` writes the columns itself.
+ */
+export const cmsMigrations = [
+    {
+        // Fill the columns `cms_media` grew for sorting and filtering, out of the `file` JSON that
+        // has always held the same three values.
+        id: "cms:2026-09-04-media-projection-columns",
+        // `MigrationContext<typeof cmsSchema>` is what types `db` here — the `DataMigration`
+        // contract is schema-agnostic, so an unparameterized ctx hands back untyped rows.
+        async up({ db, driver }) {
+            const d = driver.dialect;
+            const t = d.id("cms_media");
+            const set = (c, path) => `${d.id(c)} = json_extract(${d.id("file")}, '$.${path}')`;
+            try {
+                // One statement for the whole table. `WHERE filename IS NULL` makes it cheap on a
+                // store that has nothing to do, and keeps it off rows a later upload already filled.
+                await driver.exec(`UPDATE ${t} SET ${set("filename", "filename")}, ${set("contentType", "contentType")}, ${set("size", "size")} ` +
+                    `WHERE ${d.id("filename")} IS NULL AND ${d.id("contentType")} IS NULL`, []);
+                return;
+            }
+            catch {
+                // `json_extract` is a JSON1 function. It is present in D1 and in every ordinary SQLite
+                // build, but nothing in this repo has depended on it before and DO SQLite is
+                // Cloudflare's own engine — so a missing function must not brick a tenant's boot,
+                // which is exactly what a data migration's fail-closed contract would otherwise do.
+                // The fallback walks the rows through the ORM, where the fileRef codec has already
+                // parsed the same JSON for us. Slower, and bounded by how many media a tenant has.
+            }
+            // No chunking: this runs inside `blockConcurrencyWhile` on a tenant's first fetch, so a
+            // very large library will stall that one request — which is still the right trade
+            // against leaving half the table unsorted forever, since a migration runs ONCE.
+            const rows = await db.find({ from: "cms_media", where: { filename: { isNull: true }, contentType: { isNull: true } } });
+            for (const row of rows) {
+                const file = row.file;
+                if (!file || typeof file !== "object" || Array.isArray(file))
+                    continue;
+                const ref = file;
+                await db.update("cms_media", String(row.id), {
+                    filename: typeof ref.filename === "string" ? ref.filename : null,
+                    contentType: typeof ref.contentType === "string" ? ref.contentType : null,
+                    size: typeof ref.size === "number" ? ref.size : null,
+                });
+            }
+        },
+    },
+];
 export const cmsTasks = {
     "cms:publish": async (ctx, payload) => {
         const { pageId, token } = asObj(payload);

package/dist/panel.d.ts

@@ -0,0 +1,53 @@
+/** One custom admin panel: a nav entry the browser bundle fills in.
+ *
+ * There is no `render` here and there is not meant to be one — the rendering half is a
+ * React component the deployment's panel bundle registers under the same `slug`. Everything
+ * that decides whether the entry EXISTS is here, on the server, where it can be enforced.
+ */
+export interface AdminPanelDef {
+    /** Discriminates a panel from an `AdminPageDef` in the one registry they share. Set by
+     * {@link adminPanel}; it is a required field rather than an inferred one so a hand-built
+     * object literal cannot be a half-declared panel. */
+    readonly kind: "panel";
+    /** URL + registry key: served at `/apps/:slug` in the editor, and the id the browser
+     * bundle registers its component under. */
+    readonly slug: string;
+    /** Nav label. */
+    readonly label: string;
+    /** Optional nav icon (emoji or short string). */
+    readonly icon?: string;
+    /** Where it sits in the nav — see `NAV_ORDER`. Defaults to `NAV_ORDER.adminPages`. */
+    readonly navOrder?: number;
+    /** Roles that may open it. Defaults to the deployment's `editorRoles`, exactly as a Block
+     * Kit page's does — one registry, one gate.
+     *
+     * This is the ONLY authorization a panel gets for free. A panel's own code runs in the
+     * browser, so every call it makes is an ordinary RPC under the caller's own identity and
+     * ACL; this list decides who is shown the screen, not what the screen may do. */
+    readonly roles?: readonly string[];
+}
+/**
+ * Declare a custom admin panel. Spread the result into `createAdminPageHandlers` alongside
+ * any `adminPage()`s:
+ *
+ *   const curation = adminPanel("curation", {
+ *     label: "Curation",
+ *     icon: "🎛",
+ *     navOrder: NAV_ORDER.media + 10,
+ *     roles: ["editor", "admin"],
+ *   });
+ *
+ *   handlers = { ...createAdminPageHandlers([desk, curation], { editorRoles }) };
+ *
+ * The matching component is registered by the deployment's panel bundle — see the
+ * "Custom admin panels" section of the CMS docs.
+ */
+export declare function adminPanel(slug: string, opts: Omit<AdminPanelDef, "slug" | "kind">): AdminPanelDef;
+/** Whether a registry entry is a panel (and so has no server-side render).
+ *
+ * Reads the discriminant rather than testing for the ABSENCE of `render`: "no render" is
+ * also what a malformed page looks like, and `validateAdminPages` has to be able to tell a
+ * panel from a page someone forgot to finish. */
+export declare function isAdminPanel(def: {
+    readonly kind?: string;
+}): def is AdminPanelDef;