@murumets-ee/media 0.71.0 → 0.73.0

package/dist/resolve-image-styles-YExI329D.mjs

@@ -0,0 +1,2 @@
+import{t as e}from"./rolldown-runtime-DK3Fl9T5.mjs";import{r as t,s as n}from"./shapes-CqppzFzb.mjs";import"./variant-plan-86tJKtVi.mjs";import{n as r}from"./media-config-DkbnXIjC.mjs";var i=e({resolveImageStyles:()=>o,resolveVariantConfig:()=>s});const a={thumbnail:{width:200,height:200,fit:`cover`,format:`webp`,quality:80}};async function o(e,t,n={}){try{let{createSettingsClient:t}=await import(`@murumets-ee/settings`),{imageStylesSettings:n}=await import(`./image-styles-settings.mjs`),r=await t(n,{app:e}).get(`imageStyles`);if(r&&Object.keys(r).length>0)return r}catch(e){if(n.strict)throw e;t?.warn({err:e},`resolveImageStyles: settings DB read failed — falling back`)}try{return r().imageStyles}catch{}return a}async function s(e,i,o={}){let s=null,c=null;try{let{createSettingsClient:t}=await import(`@murumets-ee/settings`),{imageStylesSettings:n}=await import(`./image-styles-settings.mjs`),r=await t(n,{app:e}).getAll();s=r.vocabulary,r.imageStyles&&Object.keys(r.imageStyles).length>0&&(c=r.imageStyles)}catch(e){if(o.strict)throw e;i?.warn({err:e},`resolveVariantConfig: settings DB read failed — falling back`)}let l=null;try{l=r()}catch{}let u=n({vocabulary:s??l?.vocabulary??t,styles:c??l?.imageStyles??a}),d=u.shapes.reduce((e,t)=>e+t.widths.length,0);return d>64&&i?.warn({mostPerPhotograph:d,cap:64},`resolveVariantConfig: shapes, widths and fixed styles together plan more files per photograph than the cap — the largest are trimmed`),u.unmapped.length>0&&i?.warn({unmapped:u.unmapped},`resolveVariantConfig: some image styles have no place in the shape model — they keep generating as fixed styles only`),u}export{s as n,i as r,o as t};
+//# sourceMappingURL=resolve-image-styles-YExI329D.mjs.map

package/dist/resolve-image-styles-YExI329D.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-image-styles-YExI329D.mjs","names":[],"sources":["../src/resolve-image-styles.ts"],"sourcesContent":["/**\n * Image style resolution waterfall — single source of truth for the\n * \"which styles should we use?\" question.\n *\n * Priority: settings DB (user-configured) → plugin config (from `media()`\n * factory call) → hardcoded defaults (thumbnail only).\n *\n * This replaces three near-duplicate blocks (MediaClient's private\n * resolveImageStyles + two admin-route branches) that had drifted — the\n * routes didn't treat an empty stored object as \"fall back to config\"\n * while MediaClient did. Consolidating here keeps the behavior consistent\n * and logs the DB read failure so operators can diagnose issues instead\n * of silently getting defaults.\n *\n * Not cached. MediaClient wraps this with its own per-instance cache.\n */\n\nimport type { Logger, ToolkitApp } from '@murumets-ee/core'\nimport { requireMediaConfig } from './media-config.js'\nimport { buildVariantConfig, DEFAULT_IMAGE_VOCABULARY, type VariantConfig } from './shapes.js'\nimport type { ImageStyle, ImageVocabulary, ReadonlyImageVocabulary } from './types.js'\nimport { MAX_VARIANTS_PER_IMAGE } from './variant-plan.js'\n\nconst HARDCODED_DEFAULTS: Record<string, ImageStyle> = {\n  thumbnail: { width: 200, height: 200, fit: 'cover', format: 'webp', quality: 80 },\n}\n\n/**\n * `strict`: a FAILED settings read throws instead of falling back.\n *\n * The fallback is right for a reader — an image still resolves while the DB\n * blips. It is wrong for the variant job, which DELETES what the configuration\n * no longer names (images PR05): a pass that read the code defaults during an\n * outage would delete every variant of every shape the operator configured,\n * across the whole library if a backfill was running. So the job reads strictly\n * and lets the queue retry. An EMPTY stored value still falls through — that is\n * \"nothing configured\", not a failure.\n */\nexport interface ResolveOptions {\n  readonly strict?: boolean\n}\n\nexport async function resolveImageStyles(\n  app: ToolkitApp,\n  logger?: Logger,\n  options: ResolveOptions = {},\n): Promise<Record<string, ImageStyle>> {\n  // 1. Settings DB (source of truth once the admin UI has saved anything).\n  //    An empty record counts as \"nothing configured\" — fall through. This\n  //    matches the pre-extraction behavior of MediaClient and fixes the\n  //    routes' prior behavior of showing an empty UI in that case.\n  try {\n    const { createSettingsClient } = await import('@murumets-ee/settings')\n    const { imageStylesSettings } = await import('./image-styles-settings.js')\n    const settingsClient = createSettingsClient(imageStylesSettings, { app })\n    const stored = await settingsClient.get('imageStyles')\n    if (stored && Object.keys(stored).length > 0) return stored\n  } catch (err) {\n    // Logging matters: prior silent catches masked real issues (e.g. DB\n    // unavailable) as \"no styles\" and routed admins toward config fallback\n    // when the real failure was infrastructure.\n    if (options.strict) throw err\n    logger?.warn({ err }, 'resolveImageStyles: settings DB read failed — falling back')\n  }\n\n  // 2. Plugin config (from the `media()` factory call in lumi.config.ts).\n  try {\n    return requireMediaConfig().imageStyles\n  } catch {\n    // Plugin not initialized (e.g. unit tests that don't call media()) —\n    // fall through to hardcoded defaults. No log: this is a valid mode.\n  }\n\n  // 3. Hardcoded baseline — a single thumbnail style so uploads don't fail\n  //    in a toolkit that never registered the plugin.\n  return HARDCODED_DEFAULTS\n}\n\n/**\n * The shape model (images D003) — the vocabulary and ladder, with the stored\n * fixed styles folded in (`buildVariantConfig`).\n *\n * Same namespace and same waterfall as {@link resolveImageStyles}, applied per\n * key, from ONE settings read (`getAll`):\n *\n * - `vocabulary`: stored → `media({ vocabulary })` → `DEFAULT_IMAGE_VOCABULARY`.\n *   The key has no settings `default`, so \"unset\" really reads as `null` and\n *   the plugin-config tier is reachable — unlike `imageStyles`, whose settings\n *   default shadows its config tier (a pre-existing behaviour this leaves alone).\n * - `imageStyles`: exactly what {@link resolveImageStyles} would return, so the\n *   one-rung shapes and aliases describe the styles the legacy path actually\n *   generates.\n *\n * Mappings the model cannot express are logged, once per call, with the reason\n * — a style an operator configured must not silently stop mattering.\n *\n * Not cached; wrap it the way `createPublicMediaResolver` wraps\n * {@link resolveImageStyles}.\n */\nexport async function resolveVariantConfig(\n  app: ToolkitApp,\n  logger?: Pick<Logger, 'warn'>,\n  options: ResolveOptions = {},\n): Promise<VariantConfig> {\n  let storedVocabulary: ImageVocabulary | null = null\n  let storedStyles: Record<string, ImageStyle> | null = null\n  try {\n    const { createSettingsClient } = await import('@murumets-ee/settings')\n    const { imageStylesSettings } = await import('./image-styles-settings.js')\n    const all = await createSettingsClient(imageStylesSettings, { app }).getAll()\n    storedVocabulary = all.vocabulary\n    if (all.imageStyles && Object.keys(all.imageStyles).length > 0) storedStyles = all.imageStyles\n  } catch (err) {\n    if (options.strict) throw err\n    logger?.warn({ err }, 'resolveVariantConfig: settings DB read failed — falling back')\n  }\n\n  let configured: {\n    vocabulary: ReadonlyImageVocabulary\n    imageStyles: Record<string, ImageStyle>\n  } | null = null\n  try {\n    configured = requireMediaConfig()\n  } catch {\n    // Plugin not initialized — the hardcoded tier below. Valid, as above.\n  }\n\n  const config = buildVariantConfig({\n    vocabulary: storedVocabulary ?? configured?.vocabulary ?? DEFAULT_IMAGE_VOCABULARY,\n    styles: storedStyles ?? configured?.imageStyles ?? HARDCODED_DEFAULTS,\n  })\n  // The settings schema bounds the vocabulary on its own; the fixed styles are a\n  // different key and add one file each on top. Say so here, once per read,\n  // rather than only as a `dropped` count on every upload.\n  const mostPerPhotograph = config.shapes.reduce((sum, s) => sum + s.widths.length, 0)\n  if (mostPerPhotograph > MAX_VARIANTS_PER_IMAGE) {\n    logger?.warn(\n      { mostPerPhotograph, cap: MAX_VARIANTS_PER_IMAGE },\n      'resolveVariantConfig: shapes, widths and fixed styles together plan more files per photograph than the cap — the largest are trimmed',\n    )\n  }\n  if (config.unmapped.length > 0) {\n    logger?.warn(\n      { unmapped: config.unmapped },\n      'resolveVariantConfig: some image styles have no place in the shape model — they keep generating as fixed styles only',\n    )\n  }\n  return config\n}\n"],"mappings":"wPAuBA,MAAM,EAAiD,CACrD,UAAW,CAAE,MAAO,IAAK,OAAQ,IAAK,IAAK,QAAS,OAAQ,OAAQ,QAAS,EAAG,CAClF,EAiBA,eAAsB,EACpB,EACA,EACA,EAA0B,CAAC,EACU,CAKrC,GAAI,CACF,GAAM,CAAE,wBAAyB,MAAM,OAAO,yBACxC,CAAE,uBAAwB,MAAM,OAAO,+BAEvC,EAAS,MADQ,EAAqB,EAAqB,CAAE,KAAI,CACrC,CAAC,CAAC,IAAI,aAAa,EACrD,GAAI,GAAU,OAAO,KAAK,CAAM,CAAC,CAAC,OAAS,EAAG,OAAO,CACvD,OAAS,EAAK,CAIZ,GAAI,EAAQ,OAAQ,MAAM,EAC1B,GAAQ,KAAK,CAAE,KAAI,EAAG,4DAA4D,CACpF,CAGA,GAAI,CACF,OAAO,EAAmB,CAAC,CAAC,WAC9B,MAAQ,CAGR,CAIA,OAAO,CACT,CAuBA,eAAsB,EACpB,EACA,EACA,EAA0B,CAAC,EACH,CACxB,IAAI,EAA2C,KAC3C,EAAkD,KACtD,GAAI,CACF,GAAM,CAAE,wBAAyB,MAAM,OAAO,yBACxC,CAAE,uBAAwB,MAAM,OAAO,+BACvC,EAAM,MAAM,EAAqB,EAAqB,CAAE,KAAI,CAAC,CAAC,CAAC,OAAO,EAC5E,EAAmB,EAAI,WACnB,EAAI,aAAe,OAAO,KAAK,EAAI,WAAW,CAAC,CAAC,OAAS,IAAG,EAAe,EAAI,YACrF,OAAS,EAAK,CACZ,GAAI,EAAQ,OAAQ,MAAM,EAC1B,GAAQ,KAAK,CAAE,KAAI,EAAG,8DAA8D,CACtF,CAEA,IAAI,EAGO,KACX,GAAI,CACF,EAAa,EAAmB,CAClC,MAAQ,CAER,CAEA,IAAM,EAAS,EAAmB,CAChC,WAAY,GAAoB,GAAY,YAAc,EAC1D,OAAQ,GAAgB,GAAY,aAAe,CACrD,CAAC,EAIK,EAAoB,EAAO,OAAO,QAAQ,EAAK,IAAM,EAAM,EAAE,OAAO,OAAQ,CAAC,EAanF,OAZI,EAAA,IACF,GAAQ,KACN,CAAE,oBAAmB,IAAA,EAA4B,EACjD,sIACF,EAEE,EAAO,SAAS,OAAS,GAC3B,GAAQ,KACN,CAAE,SAAU,EAAO,QAAS,EAC5B,sHACF,EAEK,CACT"}

package/dist/routes-DaE0M8h8.mjs

@@ -0,0 +1,2 @@
+import{s as e}from"./focal-point-BWhtJzef.mjs";import{t}from"./media-config-DkbnXIjC.mjs";import{combineAdminRoutes as n,defineAdminRoute as r,runBounded as i,safeAudit as a,safeAuditMany as o}from"@murumets-ee/core";const s=/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;function c(e){return e!==void 0&&s.test(e)}const l=[`image`,`video`,`audio`,`document`,`other`];function u(e){return l.includes(e)}function d(e,t){if(e===null||!/^\d+$/.test(e))return t;let n=Number(e);return Number.isSafeInteger(n)?n:t}function f(e,t=200){return new Response(JSON.stringify(e),{status:t,headers:{"Content-Type":`application/json`}})}function p(e,t){return f({error:e},t)}const m={clientPromise:null};async function h(){if(!m.clientPromise){let e=(async()=>{let{getApp:e}=await import(`@murumets-ee/core`),{createStorageClient:t}=await import(`@murumets-ee/storage`),{getStorageConfig:n}=await import(`@murumets-ee/storage/plugin`),r=e();return t(n(),{app:r})})();e.catch(()=>{m.clientPromise===e&&(m.clientPromise=null)}),m.clientPromise=e}return m.clientPromise}async function g(){let{createAdminClient:e}=await import(`@murumets-ee/core/clients`),{MediaClient:t}=await import(`./client.mjs`),{Media:n}=await import(`./entity-CsDdjKz6.mjs`).then(e=>e.n),r=await h();return new t({admin:e(n),storage:r})}const _=async(t,n)=>{let{isStorageConfigured:r,getStorageConfigReason:i}=await import(`@murumets-ee/storage`),a=n.segments;if(a.length===2&&a[1]===`usage`){let e=a[0];if(!c(e))return p(`Invalid media ID format`,400);let{findMediaUsages:t}=await import(`./usage.mjs`),{getApp:n}=await import(`@murumets-ee/core`);return f({usages:await t(e,n())})}if(a.length>=2)return p(`Not found`,404);let o=a.length>0?a[0]:void 0;if(o!==void 0&&!c(o))return p(`Invalid media ID format`,400);if(!r()){let e=i()??`Storage not configured`;return a.length>0?f({error:e,configured:!1,reason:e},503):f({items:[],total:0,configured:!1,reason:e})}let s=await g();if(o!==void 0){let e=await s.findById(o);if(!e)return p(`Media not found`,404);let t=await s.getUrl(o);return f({...e,url:t})}let l=new URL(t.url),m=l.searchParams.get(`search`)??void 0,h=l.searchParams.get(`mediaType`),_=h!==null&&u(h)?h:void 0,v=Math.min(Math.max(d(l.searchParams.get(`limit`),24),1),100),y=Math.min(d(l.searchParams.get(`offset`),0),1e5),b=await s.findMany({...m!==void 0&&{search:m},..._!==void 0&&{mediaType:_},limit:v,offset:y}),x=b.items.map(e=>e.id),S=b.items.filter(e=>e.mediaType===`image`).map(e=>e.id),[C,w]=await Promise.all([s.getUrls(x),s.getVariantUrls(S,`thumbnail`)]);return f({items:b.items.map(t=>{let n=t.mediaType===`image`?w.get(t.id):void 0;return{id:t.id,title:t.title??null,alt:t.alt??null,filename:t.filename,mimeType:t.mimeType,size:t.size,mediaType:t.mediaType,url:C.get(t.id)??``,...n!==void 0&&{thumbnailUrl:n},width:t.width??null,height:t.height??null,...t.mediaType===`image`&&{focalPoint:e(t.focalPoint)}}}),total:b.total})},v=async(e,n)=>{let{isStorageConfigured:r,getStorageConfigReason:i,detectMimeType:o,isMimeTypeAllowed:s,readBoundedMultipart:c,tooLarge:l}=await import(`@murumets-ee/storage`);if(n.segments.length>0)return p(`Not found`,404);if(!r())return p(i()??`Storage not configured`,503);let{maxUploadSize:u,acceptedTypes:d}=t(),m=await c(e,u);if(!m.ok)return p(m.error,m.status);let h=m.value,_=h.get(`file`);if(!(_ instanceof File)||_.size===0)return p(`No file provided`,400);if(_.size>u){let e=l(u);return p(e.error,e.status)}let v=await g(),y=Buffer.from(await _.arrayBuffer()),{mimeType:b,mismatch:x}=await o(y,_.type||`application/octet-stream`);if(x)return p(`File content doesn't match declared type: claimed ${_.type}, detected ${b}`,400);if(!s(b,d))return p(`File type ${b} is not accepted`,415);let S=h.get(`visibility`);if(S!==null&&S!==`public`&&S!==`private`)return p(`Field 'visibility' must be 'public' or 'private'`,400);let C=await v.upload(y,{filename:_.name,mimeType:b,size:_.size,uploadedBy:n.user.id,...S!==null&&{visibility:S}}),w={id:C.media.id,title:C.media.title??null,alt:C.media.alt??null,filename:C.media.filename,mimeType:C.media.mimeType,size:C.media.size,mediaType:C.media.mediaType,url:C.url,width:C.media.width??null,height:C.media.height??null};return a(n,{action:`media.upload`,entityType:`media`,entityId:C.media.id,userId:n.user.id,...n.user.name!==void 0&&{userName:n.user.name},changes:{filename:C.media.filename,mimeType:C.media.mimeType,size:C.media.size,mediaType:C.media.mediaType}}),f(w,201)},y=async(e,t)=>{let{isStorageConfigured:n,getStorageConfigReason:r}=await import(`@murumets-ee/storage`);if(t.segments.length!==1)return p(`Not found`,404);if(!n())return p(r()??`Storage not configured`,503);let{getApp:i,getContext:o}=await import(`@murumets-ee/core`),{getMediaJobs:s}=await import(`./slot-CY4isqmN.mjs`).then(e=>e.r),c=i(),l=s();if(l){let{enqueueVariantsBackfill:e}=await import(`./backfill-trigger-BFL1L7_j.mjs`),{jobId:n,alreadyRunning:r}=await e(c,l.variantsBackfill);a(t,{action:`media.regenerate_variants`,userId:t.user.id,...t.user.name!==void 0&&{userName:t.user.name},metadata:{mode:`queued`,jobId:n,alreadyRunning:r}});let{getVariantBacklog:i}=await import(`./backlog-D-H5VUQA.mjs`).then(e=>e.t);return f({mode:`queued`,jobId:n,alreadyRunning:r,backlog:await i(c).catch(()=>null)},202)}let{regenerateAllVariants:u}=await import(`./regenerate-variants-RwV_AQSo.mjs`),{createStorageClient:d}=await import(`@murumets-ee/storage`),{getStorageConfig:m}=await import(`@murumets-ee/storage/plugin`),h=await u({app:c,storage:d(m(),{app:c}),logger:c.logger.child({media:!0}),contextResolver:()=>{let e=o();if(!(!e?.user||!e?.checker))return{user:e.user,checker:e.checker,...e.scope!==void 0&&{scope:e.scope}}}});return a(t,{action:`media.regenerate_variants`,userId:t.user.id,...t.user.name!==void 0&&{userName:t.user.name},metadata:{mode:`inline`,total:h.total,processed:h.processed,errors:h.errors}}),f({mode:`inline`,...h})},b=16*1024;async function x(e){let t=Number(e.headers.get(`content-length`));if(Number.isFinite(t)&&t>b)return{error:`Request body exceeds the maximum size`,status:413};let n=e.body,r;if(n===null){if(r=await e.text(),Buffer.byteLength(r,`utf8`)>b)return{error:`Request body exceeds the maximum size`,status:413}}else{let e=n.getReader(),t=[],i=0;try{for(;;){let{done:n,value:r}=await e.read();if(n)break;if(r!==void 0){if(i+=r.byteLength,i>b)return await e.cancel().catch(()=>void 0),{error:`Request body exceeds the maximum size`,status:413};t.push(r)}}}finally{e.releaseLock()}r=Buffer.concat(t).toString(`utf8`)}let i;try{i=JSON.parse(r)}catch{return{error:`Invalid JSON body`,status:400}}if(typeof i!=`object`||!i||Array.isArray(i))return{error:`Body must be a JSON object`,status:400};let a=i.ids;if(!Array.isArray(a)||a.length===0)return{error:`Body must contain "ids" array`,status:400};if(a.length>100)return{error:`Bulk delete limited to 100 items per request`,status:400};let o=[];for(let e of a){if(typeof e!=`string`||!c(e))return{error:`Body "ids" must contain valid media IDs`,status:400};o.push(e)}return{ids:o}}const S=async(e,t)=>{let n=t.segments;if(n.length===0){let n=await x(e);if(`error`in n)return p(n.error,n.status);let{isStorageConfigured:r,getStorageConfigReason:a}=await import(`@murumets-ee/storage`);if(!r())return p(a()??`Storage not configured`,503);let s=await g(),c=await i(n.ids,async e=>{try{return await s.delete(e),{status:`fulfilled`,id:e}}catch(t){return{status:`rejected`,id:e,reason:t}}}),l=c.filter(e=>e.status===`fulfilled`).map(e=>e.id);await o(t,l.map(e=>({action:`media.delete`,entityType:`media`,entityId:e,userId:t.user.id,...t.user.name!==void 0&&{userName:t.user.name},metadata:{bulk:!0}})));let u=c.find(e=>e.status===`rejected`);if(u&&u.status===`rejected`)throw u.reason;return f({deleted:l.length})}if(n.length>1)return p(`Not found`,404);let r=n[0];if(!c(r))return p(`Invalid media ID format`,400);let{isStorageConfigured:s,getStorageConfigReason:l}=await import(`@murumets-ee/storage`);return s()?(await(await g()).delete(r),a(t,{action:`media.delete`,entityType:`media`,entityId:r,userId:t.user.id,...t.user.name!==void 0&&{userName:t.user.name}}),f({deleted:1})):p(l()??`Storage not configured`,503)},C=[`admin`,`editor`,`agent`,`viewer`],w=[`admin`,`editor`];function T(){return n([r({prefix:`media`,path:``,method:`GET`,permission:`media:view`,defaultRoles:C,matchAnyPath:!0,description:`Read media — list, single item, or referencing-entity usage report.`,handler:_}),r({prefix:`media`,path:``,method:`POST`,permission:`media:create`,defaultRoles:w,description:"Upload a media file (multipart FormData with `file` field).",handler:v}),r({prefix:`media`,path:`regenerate-variants`,method:`POST`,permission:`media:create`,defaultRoles:w,description:`Catch every image up with the current shapes, widths and styles — queued as a background backfill (synchronous only when the app has no queue).`,handler:y}),r({prefix:`media`,path:``,method:`DELETE`,permission:`media:delete`,defaultRoles:w,matchAnyPath:!0,description:`Delete a media record + its storage object.`,handler:S})])}export{T as t};
+//# sourceMappingURL=routes-DaE0M8h8.mjs.map

package/dist/routes-DaE0M8h8.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"routes-DaE0M8h8.mjs","names":[],"sources":["../src/admin/routes.ts"],"sourcesContent":["/**\n * Media admin routes — one static `defineAdminRoute` per HTTP method.\n *\n * **URL surface served by this module:**\n *\n *   - GET    /api/admin/media                       — list with search/filter + URLs\n *   - GET    /api/admin/media/<id>                  — single record with URL\n *   - GET    /api/admin/media/<id>/usage            — entities referencing this media\n *   - POST   /api/admin/media                       — upload (multipart FormData)\n *   - POST   /api/admin/media/regenerate-variants   — queue the library variant backfill\n *                                                    (synchronous only in a queueless app)\n *   - DELETE /api/admin/media/<id>                  — delete + storage cleanup\n *   - DELETE /api/admin/media                       — bulk delete (body.ids[], ≤100)\n *\n * Standard entity CRUD (PATCH with translations) falls through to the\n * generic entity handler — add `Media` to `entities` in your handler config.\n *\n * **Why per-method `defineAdminRoute`** (vs. the previous top-level\n * `resource: 'media'` + auto-mapped permission):\n *\n *   - The wrapper (`guardedHandler` from `@murumets-ee/core`) owns the\n *     permission gate, `permission.denied` audit, and 403 body shape\n *     uniformly with every other migrated plugin. The previous shape\n *     relied on `METHOD_TO_ACTION` auto-mapping at the api-handler\n *     dispatch level which couldn't emit per-route audit metadata.\n *   - Inline `if (!checkPermission('media', 'create')) ...` defenses\n *     at the regenerate-variants / upload / delete branches are now\n *     redundant — the wrapper enforces the permission BEFORE the\n *     handler runs.\n *\n * **`matchAnyPath` rationale:** media's URL surface predates the\n * static-second-segment convention every other plugin follows\n * (`/taxonomy/<vocab>/<id>`, `/settings/<namespace>/<rest>`). The\n * second segment under `/media` is the media id itself — a runtime\n * UUID — which the dispatcher's literal `segments[0]` match would\n * miss for every request. The catch-all flag declares \"this entry\n * claims every (prefix, method) sub-path no other entry matched\" so\n * the existing URL contract works under the per-method dispatch\n * model. Static POST sub-paths (`regenerate-variants`) take\n * precedence over the catch-all entry on POST. See\n * `DefineAdminRouteSpec.matchAnyPath` in `@murumets-ee/core` for the\n * full contract.\n *\n * **Default roles:** broad for view (`['admin', 'editor', 'agent',\n * 'viewer']`), narrower for writes (`['admin', 'editor']`).\n * Conservative starting point — apps can grant more via the\n * Permissions UI.\n *\n * @example\n * ```typescript\n * import { createAdminApiHandler } from '@murumets-ee/admin-ui/server'\n * import { mediaRoutes } from '@murumets-ee/media/admin'\n * import { Media } from '@murumets-ee/media'\n *\n * const handler = createAdminApiHandler({\n *   authenticate: async (req) => { ... },\n *   entities: [Article, Media],\n *   routes: [...mediaRoutes()],\n * })\n * ```\n */\n\nimport {\n  type AdminRoute,\n  type AdminRouteHandler,\n  combineAdminRoutes,\n  defineAdminRoute,\n  runBounded,\n  safeAudit,\n  safeAuditMany,\n} from '@murumets-ee/core'\nimport type { MediaClient } from '../client.js'\nimport { readFocalPoint } from '../crop/focal-point.js'\nimport { readMediaConfig } from '../media-config.js'\nimport type { MediaPickerItem, MediaPickerListResult } from '../picker/types.js'\n\n// ---------------------------------------------------------------------------\n// Validation\n// ---------------------------------------------------------------------------\n\nconst UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i\n\nfunction isValidUuid(value: string | undefined): value is string {\n  return value !== undefined && UUID_RE.test(value)\n}\n\n/**\n * Closed enum of allowed `mediaType` filter values, in lockstep with the\n * `mediaType` field on the Media entity. The list MUST match\n * `MediaListOptions.mediaType` (declared in `../types.js`) — TypeScript\n * doesn't link the two automatically, so the small drift risk is\n * accepted in exchange for not pulling a runtime dep on the entity\n * schema package just to read its enum.\n *\n * Used as both the runtime allowlist (`isAllowedMediaType`) and the\n * source of truth for the narrowed type the guard produces — keeping\n * `as` casts off the handler's hot path.\n */\nconst ALLOWED_MEDIA_TYPES = ['image', 'video', 'audio', 'document', 'other'] as const\ntype AllowedMediaType = (typeof ALLOWED_MEDIA_TYPES)[number]\n\nfunction isAllowedMediaType(value: string): value is AllowedMediaType {\n  // Cast to readonly string[] so the typed-tuple `includes` check works\n  // with an arbitrary string input — `Array.prototype.includes`'s\n  // signature on a typed tuple only accepts members of the tuple\n  // (TS 4.9+ literal-narrowing), which is exactly what we want to\n  // sidestep here.\n  return (ALLOWED_MEDIA_TYPES as readonly string[]).includes(value)\n}\n\n/**\n * Hard cap on the `offset` query param. The dispatcher's allowed-pages\n * model is `limit ∈ [1, 100]`; even with the max page size that's\n * 1000 pages before hitting MAX_OFFSET, which is well beyond any\n * realistic admin-UI scroll depth. Forces slow-discard offset attacks\n * (`?offset=999999999`) to revert to a sane upper bound. Cursor-based\n * pagination would let this go higher, but the media list is\n * offset-based by convention with the entity-list shell.\n */\nconst MAX_OFFSET = 100_000\n\n/**\n * Strict non-negative integer parser for query params.\n *\n * `Number(raw)` silently coerces blanks (`'' → 0`), hex (`'0x05' → 5`),\n * exponent notation (`'1e2' → 100`), and signed (`'+5'/'-5'`) values —\n * all of which pass a downstream `Number.isInteger(n) && n >= 0` check.\n * Pre-filtering with `/^\\d+$/` keeps the contract honest: \"if you don't\n * send a pure non-negative integer string, you get the default.\" Same\n * pattern as `packages/taxonomy/src/admin/routes.ts:handleGet` tree\n * branch from PR-C-taxonomy.\n */\nfunction parseUintParam(raw: string | null, fallback: number): number {\n  if (raw === null || !/^\\d+$/.test(raw)) return fallback\n  const parsed = Number(raw)\n  // The regex above stops hex / exponent / signed / whitespace / blank\n  // inputs, but a long digit-only string still slips past — `Number(...)`\n  // returns `Infinity` past ~309 digits, and precision is lost past\n  // 2^53. Both would propagate through `client.findMany`'s\n  // `offset: parsed` into a Postgres query that either crashes the\n  // driver (`Infinity` is not a valid bigint) or silently rounds (the\n  // 2^53 precision-loss boundary). Reject via `Number.isSafeInteger`\n  // so overflowing inputs revert to `fallback` like every other\n  // malformed value.\n  if (!Number.isSafeInteger(parsed)) return fallback\n  return parsed\n}\n\n// ---------------------------------------------------------------------------\n// Response helpers\n// ---------------------------------------------------------------------------\n\nfunction jsonResponse(data: unknown, status = 200): Response {\n  return new Response(JSON.stringify(data), {\n    status,\n    headers: { 'Content-Type': 'application/json' },\n  })\n}\n\nfunction jsonError(message: string, status: number): Response {\n  return jsonResponse({ error: message }, status)\n}\n\n// ---------------------------------------------------------------------------\n// Per-request MediaClient factory + cached storage client\n// ---------------------------------------------------------------------------\n//\n// MediaClient and its AdminClient MUST be built per-request — AdminClient's\n// context resolver is captured eagerly at construction (see\n// buildContextResolver in @murumets-ee/core/clients). A module-level singleton\n// would bake the first request's user + tenant scope into every subsequent\n// request's writes — a cross-request permission/scope leak.\n//\n// Storage config is process-global and safe to cache once.\n\ntype StorageClient = Awaited<ReturnType<typeof import('@murumets-ee/storage').createStorageClient>>\n\ninterface StorageState {\n  clientPromise: Promise<StorageClient> | null\n}\n\n// Module-level state. `null` once eviction fires on a rejection so the next\n// request gets a fresh resolution attempt (see `getStorage`'s `.catch`).\nconst storageState: StorageState = { clientPromise: null }\n\n/**\n * Resolve the process-wide storage client. The pending-promise slot is\n * cleared on rejection so a transient `createStorageClient` failure\n * (DB hiccup, misconfig) doesn't poison every subsequent media request\n * for the lifetime of the Node process. Same pattern as\n * `packages/taxonomy/src/admin/routes.ts:getClient` from PR-C-taxonomy.\n */\nasync function getStorage(): Promise<StorageClient> {\n  if (!storageState.clientPromise) {\n    const pending = (async () => {\n      const { getApp } = await import('@murumets-ee/core')\n      const { createStorageClient } = await import('@murumets-ee/storage')\n      const { getStorageConfig } = await import('@murumets-ee/storage/plugin')\n      const app = getApp()\n      return createStorageClient(getStorageConfig(), { app })\n    })()\n    // Clear the slot on rejection so a transient failure doesn't poison\n    // every subsequent request. `pending.catch(handler)` attaches a\n    // synchronous rejection listener that resets the cached slot — the\n    // handler returns `undefined`, NOT a re-throw — so the new\n    // `.catch`-returned promise resolves, but we never await or hold\n    // that promise. The ORIGINAL `pending` (stored in\n    // `storageState.clientPromise`) is what callers `await`, and it's\n    // still in its rejected state — so the caller observing this\n    // resolution sees the underlying error. The `.catch` also marks\n    // the rejection as \"handled\" for Node's unhandled-rejection\n    // tracker. `storageState.clientPromise` holds the original `pending`\n    // so concurrent in-flight callers share one resolution.\n    pending.catch(() => {\n      if (storageState.clientPromise === pending) storageState.clientPromise = null\n    })\n    storageState.clientPromise = pending\n  }\n  return storageState.clientPromise\n}\n\nasync function getMediaClient(): Promise<MediaClient> {\n  const { createAdminClient } = await import('@murumets-ee/core/clients')\n  const { MediaClient } = await import('../client.js')\n  const { Media } = await import('../entity.js')\n  const storage = await getStorage()\n  const admin = createAdminClient(Media)\n  return new MediaClient({ admin, storage })\n}\n\n// ---------------------------------------------------------------------------\n// Handlers\n// ---------------------------------------------------------------------------\n\nconst handleGet: AdminRouteHandler = async (req, ctx) => {\n  const { isStorageConfigured, getStorageConfigReason } = await import('@murumets-ee/storage')\n  const segments = ctx.segments\n\n  // GET /media/<id>/usage — DB-only lookup, safe even when storage is\n  // unconfigured. Validate the UUID first so a malformed id 400s\n  // uniformly with the storage-configured branch below.\n  if (segments.length === 2 && segments[1] === 'usage') {\n    const id = segments[0]\n    if (!isValidUuid(id)) return jsonError('Invalid media ID format', 400)\n\n    const { findMediaUsages } = await import('../usage.js')\n    const { getApp } = await import('@murumets-ee/core')\n    const app = getApp()\n    const usages = await findMediaUsages(id, app)\n    return jsonResponse({ usages })\n  }\n\n  // Reject unknown sub-paths explicitly. The wrapper-gate has already\n  // passed (caller has `media:view`); a handler-level 404 here matches\n  // the dispatcher's miss-shape so unknown URLs don't fall through to\n  // the single-id branch and 400/500 with a misleading reason. The\n  // only valid 2-segment URL is `<id>/usage`, which was already\n  // claimed by the early-return above — anything else with >=2\n  // segments is not a recognized media route.\n  if (segments.length >= 2) return jsonError('Not found', 404)\n\n  // GET /media/<id> — validate UUID up front so a bad request still\n  // 400s when storage happens to be unconfigured (matches DELETE).\n  const singleId = segments.length > 0 ? segments[0] : undefined\n  if (singleId !== undefined && !isValidUuid(singleId)) {\n    return jsonError('Invalid media ID format', 400)\n  }\n\n  // Everything below needs a working storage client. If env isn't\n  // wired, return a structured \"disabled\" response rather than 500 —\n  // the media list page renders a banner and new admins can finish\n  // onboarding without being blocked on a crash loop.\n  if (!isStorageConfigured()) {\n    const reason = getStorageConfigReason() ?? 'Storage not configured'\n    if (segments.length > 0) {\n      // Single item — treat as not-found-ish to avoid leaking\n      // existence; include reason so the UI can surface it.\n      return jsonResponse({ error: reason, configured: false, reason }, 503)\n    }\n    // GET /media — empty list + disabled flag for the picker's banner.\n    const response: MediaPickerListResult & { configured: false; reason: string } = {\n      items: [],\n      total: 0,\n      configured: false,\n      reason,\n    }\n    return jsonResponse(response)\n  }\n\n  const client = await getMediaClient()\n\n  // GET /media/<id> — single item with URL (full record for EntityForm + picker)\n  if (singleId !== undefined) {\n    const record = await client.findById(singleId)\n    if (!record) return jsonError('Media not found', 404)\n\n    const url = await client.getUrl(singleId)\n    return jsonResponse({ ...record, url })\n  }\n\n  // GET /media — list with search/filter + batch URL resolution\n  const url = new URL(req.url)\n  const search = url.searchParams.get('search') ?? undefined\n  // mediaType MUST be validated against the entity's closed enum before\n  // it reaches `client.findMany` — the previous shape force-cast the raw\n  // query value with `as 'image' | ...` which is a type-system lie. A\n  // bogus value like `?mediaType=bogus` would parameterize into\n  // `WHERE media_type = 'bogus'` (no SQL injection — Drizzle is\n  // parameterized — but the row count is silently zero, which is\n  // confusing). Empty string from `?mediaType=` is also passed-through\n  // by the prior `?? undefined` shape since empty string is not null.\n  // Allowlist + type guard drops bogus / empty values cleanly so the\n  // filter is omitted instead of applied with a no-match value.\n  const rawMediaType = url.searchParams.get('mediaType')\n  const mediaType =\n    rawMediaType !== null && isAllowedMediaType(rawMediaType) ? rawMediaType : undefined\n  // Strict parsing keeps the contract honest — see `parseUintParam`\n  // JSDoc. Cap limit to [1, 100] and offset to [0, MAX_OFFSET] so a\n  // request can't ask for an unboundedly large page nor force a\n  // slow-discard scan with `?offset=99999999`.\n  const limit = Math.min(Math.max(parseUintParam(url.searchParams.get('limit'), 24), 1), 100)\n  const offset = Math.min(parseUintParam(url.searchParams.get('offset'), 0), MAX_OFFSET)\n\n  const result = await client.findMany({\n    ...(search !== undefined && { search }),\n    ...(mediaType !== undefined && { mediaType }),\n    limit,\n    offset,\n  })\n\n  // Resolve original URLs for all items, but thumbnail variants ONLY for\n  // images — a video/audio/document/other id will never have a `thumbnail`\n  // variant, so asking `getVariantUrls` to resolve one is pure waste (a\n  // storage lookup that falls through to the original, then gets discarded\n  // below anyway). `media-list-page.tsx` filters the same way.\n  const ids = result.items.map((item) => item.id)\n  const imageIds = result.items.filter((item) => item.mediaType === 'image').map((item) => item.id)\n  const [urlMap, thumbMap] = await Promise.all([\n    client.getUrls(ids),\n    client.getVariantUrls(imageIds, 'thumbnail'),\n  ])\n\n  const items: (MediaPickerItem & { thumbnailUrl?: string })[] = result.items.map((item) => {\n    // F115: `getVariantUrls` falls back to the ORIGINAL asset URL for any id\n    // with no `thumbnail` variant — correct for an image that just hasn't\n    // been processed yet, wrong for a video/audio/document/other row, which\n    // will never have one. Gating on `mediaType` keeps `thumbnailUrl` ABSENT\n    // rather than pointing a consumer's `<img src>` at a `.mp4`.\n    const thumbnailUrl = item.mediaType === 'image' ? thumbMap.get(item.id) : undefined\n    return {\n      id: item.id,\n      title: item.title ?? null,\n      alt: item.alt ?? null,\n      filename: item.filename,\n      mimeType: item.mimeType,\n      size: item.size,\n      mediaType: item.mediaType,\n      url: urlMap.get(item.id) ?? '',\n      ...(thumbnailUrl !== undefined && { thumbnailUrl }),\n      width: item.width ?? null,\n      height: item.height ?? null,\n      // Images only, like the thumbnail: a video has no subject to crop around.\n      ...(item.mediaType === 'image' && { focalPoint: readFocalPoint(item.focalPoint) }),\n    }\n  })\n\n  const response: MediaPickerListResult = { items, total: result.total }\n  return jsonResponse(response)\n}\n\nconst handleUpload: AdminRouteHandler = async (req, ctx) => {\n  const {\n    isStorageConfigured,\n    getStorageConfigReason,\n    detectMimeType,\n    isMimeTypeAllowed,\n    readBoundedMultipart,\n    tooLarge,\n  } = await import('@murumets-ee/storage')\n\n  // Upload is registered at `path: ''` (NOT matchAnyPath) — the\n  // dispatcher only invokes this handler when segments=[]. The api-\n  // handler ALSO rejects empty/whitespace-only first segments with a\n  // 400 before any plugin dispatcher runs (see\n  // `packages/admin-ui/src/server/api-handler/index.ts` segment-\n  // validation block). So this guard is defense-in-depth — per HANDOFF\n  // §\"Defense-in-depth `&& segments[i]` guards are fine\" — protecting\n  // against a future framework invariant change that lets a non-empty\n  // segment reach a `path: ''` static entry.\n  if (ctx.segments.length > 0) return jsonError('Not found', 404)\n\n  if (!isStorageConfigured()) {\n    return jsonError(getStorageConfigReason() ?? 'Storage not configured', 503)\n  }\n\n  // The plugin's `maxUploadSize` / `acceptedTypes`, from the registry the\n  // merge step filled before any init — see `media-config.ts` (F007).\n  const { maxUploadSize, acceptedTypes } = readMediaConfig()\n\n  // F007: bound the body BEFORE `formData()` makes it resident — and before\n  // building a MediaClient for a request that is about to be refused.\n  const envelope = await readBoundedMultipart(req, maxUploadSize)\n  if (!envelope.ok) return jsonError(envelope.error, envelope.status)\n  const formData = envelope.value\n\n  const file = formData.get('file')\n  // FormData `get` returns string | File | null. Reject anything that\n  // isn't a File so the typed `file.size`/`file.arrayBuffer()` below\n  // is safe without a runtime cast.\n  if (!(file instanceof File) || file.size === 0) {\n    return jsonError('No file provided', 400)\n  }\n\n  // The envelope bound covers the whole body; this covers the file, before\n  // `arrayBuffer()` copies it.\n  if (file.size > maxUploadSize) {\n    const refused = tooLarge(maxUploadSize)\n    return jsonError(refused.error, refused.status)\n  }\n\n  const client = await getMediaClient()\n\n  const buffer = Buffer.from(await file.arrayBuffer())\n\n  // Detect actual MIME type from file content (prevents spoofing).\n  const { mimeType, mismatch } = await detectMimeType(\n    buffer,\n    file.type || 'application/octet-stream',\n  )\n  if (mismatch) {\n    return jsonError(\n      `File content doesn't match declared type: claimed ${file.type}, detected ${mimeType}`,\n      400,\n    )\n  }\n  // `acceptedTypes` against the DETECTED type, so a renamed file cannot\n  // claim its way past the allowlist.\n  if (!isMimeTypeAllowed(mimeType, acceptedTypes)) {\n    return jsonError(`File type ${mimeType} is not accepted`, 415)\n  }\n\n  // Per-upload visibility, DEFAULTING TO PRIVATE — the caller opts in.\n  //\n  // This route serves two populations with opposite needs. The media picker\n  // uploads publishable web assets: a page's hero image MUST be public or the\n  // public site resolves it to `null` and renders no images at all, with a 200\n  // on every page and one warn log (F030). `packages/rent-ui`'s inspection\n  // wizard posts to this SAME route with handover and return photos — vehicle\n  // and apartment condition shots, plates, interiors, occasionally documents —\n  // which must stay behind time-limited signed urls.\n  //\n  // Deny-by-default decides the direction, and the asymmetry is the argument:\n  // forget the opt-in and an image is invisible, which is annoying, visible and\n  // fixable; default to public and forget an opt-out and those photos become\n  // permanently world-readable. A missed opt-in cannot leak. So the default is\n  // unchanged (`private` via StorageClient's own fallback) and rent's caller is\n  // untouched — it sends nothing and behaves exactly as before.\n  const visibilityRaw = formData.get('visibility')\n  if (visibilityRaw !== null && visibilityRaw !== 'public' && visibilityRaw !== 'private') {\n    return jsonError(\"Field 'visibility' must be 'public' or 'private'\", 400)\n  }\n  const result = await client.upload(buffer, {\n    filename: file.name,\n    mimeType,\n    size: file.size,\n    uploadedBy: ctx.user.id,\n    ...(visibilityRaw !== null && { visibility: visibilityRaw }),\n  })\n\n  const item: MediaPickerItem = {\n    id: result.media.id,\n    title: result.media.title ?? null,\n    alt: result.media.alt ?? null,\n    filename: result.media.filename,\n    mimeType: result.media.mimeType,\n    size: result.media.size,\n    mediaType: result.media.mediaType,\n    url: result.url,\n    width: result.media.width ?? null,\n    height: result.media.height ?? null,\n  }\n\n  safeAudit(ctx, {\n    action: 'media.upload',\n    entityType: 'media',\n    entityId: result.media.id,\n    userId: ctx.user.id,\n    ...(ctx.user.name !== undefined && { userName: ctx.user.name }),\n    changes: {\n      filename: result.media.filename,\n      mimeType: result.media.mimeType,\n      size: result.media.size,\n      mediaType: result.media.mediaType,\n    },\n  })\n\n  return jsonResponse(item, 201)\n}\n\nconst handleRegenerateVariants: AdminRouteHandler = async (_req, ctx) => {\n  const { isStorageConfigured, getStorageConfigReason } = await import('@murumets-ee/storage')\n\n  // Static POST path='regenerate-variants' — the dispatcher only invokes\n  // this handler when `segments[0] === 'regenerate-variants'`. Trailing\n  // segments (e.g. POST /media/regenerate-variants/extra) aren't a\n  // supported sub-route.\n  if (ctx.segments.length !== 1) return jsonError('Not found', 404)\n\n  if (!isStorageConfigured()) {\n    return jsonError(getStorageConfigReason() ?? 'Storage not configured', 503)\n  }\n\n  const { getApp, getContext } = await import('@murumets-ee/core')\n  const { getMediaJobs } = await import('../jobs/slot.js')\n  const app = getApp()\n\n  // With a queue: queue the library walk and return at once (images D004, S6).\n  // The walk queues one pass per photograph; the Queue page and the media\n  // library count them down while the site keeps serving.\n  const jobs = getMediaJobs()\n  if (jobs) {\n    const { enqueueVariantsBackfill } = await import('../jobs/backfill-trigger.js')\n    const { jobId, alreadyRunning } = await enqueueVariantsBackfill(app, jobs.variantsBackfill)\n    safeAudit(ctx, {\n      action: 'media.regenerate_variants',\n      userId: ctx.user.id,\n      ...(ctx.user.name !== undefined && { userName: ctx.user.name }),\n      metadata: { mode: 'queued', jobId, alreadyRunning },\n    })\n    const { getVariantBacklog } = await import('../jobs/backlog.js')\n    const backlog = await getVariantBacklog(app).catch(() => null)\n    return jsonResponse({ mode: 'queued', jobId, alreadyRunning, backlog }, 202)\n  }\n\n  // No queue in this app: the synchronous loop it always had, now additive.\n  const { regenerateAllVariants } = await import('../regenerate-variants.js')\n  const { createStorageClient } = await import('@murumets-ee/storage')\n  const { getStorageConfig } = await import('@murumets-ee/storage/plugin')\n  const storage = createStorageClient(getStorageConfig(), { app })\n\n  const result = await regenerateAllVariants({\n    app,\n    storage,\n    logger: app.logger.child({ media: true }),\n    contextResolver: () => {\n      const requestCtx = getContext()\n      if (!requestCtx?.user || !requestCtx?.checker) return undefined\n      return {\n        user: requestCtx.user,\n        checker: requestCtx.checker,\n        ...(requestCtx.scope !== undefined && { scope: requestCtx.scope }),\n      }\n    },\n  })\n\n  safeAudit(ctx, {\n    action: 'media.regenerate_variants',\n    userId: ctx.user.id,\n    ...(ctx.user.name !== undefined && { userName: ctx.user.name }),\n    metadata: {\n      mode: 'inline',\n      total: result.total,\n      processed: result.processed,\n      errors: result.errors,\n    },\n  })\n\n  return jsonResponse({ mode: 'inline', ...result })\n}\n\n/**\n * Cap on a bulk delete — the same number the generic entity CRUD route's own\n * bulk delete uses (`entity-crud.ts`'s `MAX_BULK_DELETE`), so a caller sees\n * one consistent limit regardless of which admin list it is deleting from.\n */\nconst MAX_BULK_DELETE = 100\n\n/**\n * Bound on the bulk-delete request body. A body here is `{ ids: string[] }`\n * of short UUID strings — generous headroom for {@link MAX_BULK_DELETE} of\n * them (each ~38 bytes quoted-and-comma'd).\n */\nconst MAX_BULK_DELETE_BODY_BYTES = 16 * 1024\n\n/** A validated bulk-delete request, or the error response to send instead. */\ntype BulkDeleteBody = { ids: string[] } | { error: string; status: number }\n\n/**\n * Read and parse the bulk-delete body, refusing anything past\n * {@link MAX_BULK_DELETE_BODY_BYTES}.\n *\n * `content-length` alone is NOT a bound — it is client-supplied, so a\n * chunked request (no header at all) or a spoofed small one sails through a\n * header-only check straight into an unbounded `req.json()` buffering\n * whatever the caller sends (review finding, entity-table PR06). Streamed\n * and byte-counted instead, same shape `entity-crud.ts`'s `readJsonBody`\n * uses for arbitrary write bodies — this one is sized for a much smaller,\n * closed shape, not copied wholesale, because `@murumets-ee/media` must not\n * depend on `@murumets-ee/admin-ui` (wrong dependency direction).\n */\nasync function readBulkDeleteBody(req: Request): Promise<BulkDeleteBody> {\n  const declared = Number(req.headers.get('content-length'))\n  if (Number.isFinite(declared) && declared > MAX_BULK_DELETE_BODY_BYTES) {\n    return { error: 'Request body exceeds the maximum size', status: 413 }\n  }\n\n  const body = req.body\n  let text: string\n  if (body === null) {\n    text = await req.text()\n    if (Buffer.byteLength(text, 'utf8') > MAX_BULK_DELETE_BODY_BYTES) {\n      return { error: 'Request body exceeds the maximum size', status: 413 }\n    }\n  } else {\n    const reader = body.getReader()\n    const chunks: Uint8Array[] = []\n    let total = 0\n    try {\n      while (true) {\n        const { done, value } = await reader.read()\n        if (done) break\n        if (value === undefined) continue\n        total += value.byteLength\n        if (total > MAX_BULK_DELETE_BODY_BYTES) {\n          // Stop pulling — without the cancel the peer keeps sending into a\n          // reader nobody drains, which is the connection this refusal\n          // exists to end.\n          await reader.cancel().catch(() => undefined)\n          return { error: 'Request body exceeds the maximum size', status: 413 }\n        }\n        chunks.push(value)\n      }\n    } finally {\n      reader.releaseLock()\n    }\n    text = Buffer.concat(chunks).toString('utf8')\n  }\n\n  let raw: unknown\n  try {\n    raw = JSON.parse(text)\n  } catch {\n    return { error: 'Invalid JSON body', status: 400 }\n  }\n  if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {\n    return { error: 'Body must be a JSON object', status: 400 }\n  }\n\n  const ids = (raw as Record<string, unknown>).ids\n  if (!Array.isArray(ids) || ids.length === 0) {\n    return { error: 'Body must contain \"ids\" array', status: 400 }\n  }\n  if (ids.length > MAX_BULK_DELETE) {\n    return { error: `Bulk delete limited to ${MAX_BULK_DELETE} items per request`, status: 400 }\n  }\n\n  // Reject anything that isn't a well-formed media id before any mutation —\n  // `client.delete()` would otherwise throw mid-batch, leaving a partially\n  // deleted set for a request that was malformed from the start.\n  //\n  // `Array.isArray` narrows to `any[]` (its lib.es5.d.ts signature is\n  // `arg is any[]`), so without the cast below every read of the loop\n  // variable counts as an `any` against `verify:types` — `as unknown[]`\n  // resets it to a type `typeof`/`isValidUuid` still narrow correctly, one\n  // step later than the guard that actually proves it.\n  const validated: string[] = []\n  for (const id of ids as unknown[]) {\n    if (typeof id !== 'string' || !isValidUuid(id)) {\n      return { error: 'Body \"ids\" must contain valid media IDs', status: 400 }\n    }\n    validated.push(id)\n  }\n  return { ids: validated }\n}\n\nconst handleDelete: AdminRouteHandler = async (req, ctx) => {\n  const segments = ctx.segments\n\n  // DELETE /media — no id supplied. Bulk delete (body: { ids: string[] }),\n  // matching the generic entity CRUD route's own bulk shape — `EntityList`'s\n  // \"Delete selected\" always sends this, and Media's `matchAnyPath` DELETE\n  // entry claims the whole `/media` prefix, so without this branch that\n  // request lands here and gets refused with \"Media ID required\" (found via\n  // browser verification, entity-table PR06 — S8's demonstration on a real\n  // Media list is what surfaced it: nothing before this PR had exercised a\n  // bulk delete against the live Media admin page).\n  if (segments.length === 0) {\n    const parsed = await readBulkDeleteBody(req)\n    if ('error' in parsed) return jsonError(parsed.error, parsed.status)\n\n    const { isStorageConfigured, getStorageConfigReason } = await import('@murumets-ee/storage')\n    if (!isStorageConfigured()) {\n      return jsonError(getStorageConfigReason() ?? 'Storage not configured', 503)\n    }\n\n    const client = await getMediaClient()\n    // MAX_BULK_DELETE bounds the TOTAL; `runBounded` bounds the CONCURRENCY —\n    // each `delete()` does entity DB work AND storage object/metadata work,\n    // so 100 ids fired via a bare `Promise.all` would open up to 100 of both\n    // at once, which is exactly the shared-pool-contention shape CLAUDE.md's\n    // \"No Unbounded Fan-Out\" rule exists to catch (CodeRabbit CLI finding,\n    // entity-table PR06). The worker catches internally and returns a\n    // settled-shaped result instead of letting `runBounded` see a rejection —\n    // that keeps its own fail-fast behavior from firing, so this stays\n    // allSettled-equivalent: every id gets attempted regardless of a sibling's\n    // failure, and the audit trail for the ones that DID succeed survives one\n    // that didn't (`safeAuditMany` below would otherwise be skipped entirely\n    // on any rejection, auditing NONE of them). The first failure is still\n    // rethrown after the audit write, so the response shape is unchanged —\n    // no new 207-partial-success contract.\n    const results = await runBounded(parsed.ids, async (id) => {\n      try {\n        await client.delete(id)\n        return { status: 'fulfilled' as const, id }\n      } catch (reason) {\n        return { status: 'rejected' as const, id, reason }\n      }\n    })\n    const deletedIds = results.filter((r) => r.status === 'fulfilled').map((r) => r.id)\n\n    // ONE batched write, awaited — not N unawaited `safeAudit` calls racing\n    // the connection pool after the response is already decided (review\n    // finding, entity-table PR06; `safeAuditMany`'s own docblock names this\n    // exact loop shape as the reason it exists).\n    await safeAuditMany(\n      ctx,\n      deletedIds.map((id) => ({\n        action: 'media.delete',\n        entityType: 'media',\n        entityId: id,\n        userId: ctx.user.id,\n        ...(ctx.user.name !== undefined && { userName: ctx.user.name }),\n        metadata: { bulk: true },\n      })),\n    )\n\n    const failure = results.find((r) => r.status === 'rejected')\n    if (failure && failure.status === 'rejected') throw failure.reason\n\n    return jsonResponse({ deleted: deletedIds.length })\n  }\n\n  // Reject sub-paths beyond /<id> — DELETE /media/<id>/usage etc.\n  if (segments.length > 1) return jsonError('Not found', 404)\n\n  const id = segments[0]\n  if (!isValidUuid(id)) return jsonError('Invalid media ID format', 400)\n\n  const { isStorageConfigured, getStorageConfigReason } = await import('@murumets-ee/storage')\n  if (!isStorageConfigured()) {\n    // Can't safely delete — MediaClient needs storage to remove the\n    // actual object, and partial delete (DB row gone, object orphaned)\n    // would leak storage. Surface the reason so the UI can display it.\n    return jsonError(getStorageConfigReason() ?? 'Storage not configured', 503)\n  }\n\n  // AdminClient.delete() checks entity_refs and throws\n  // ReferencedEntityError if this media is still referenced. The\n  // error bubbles to the caller's error handler which returns 409\n  // with usage details.\n  const client = await getMediaClient()\n  await client.delete(id)\n\n  safeAudit(ctx, {\n    action: 'media.delete',\n    entityType: 'media',\n    entityId: id,\n    userId: ctx.user.id,\n    ...(ctx.user.name !== undefined && { userName: ctx.user.name }),\n  })\n\n  return jsonResponse({ deleted: 1 })\n}\n\n// ---------------------------------------------------------------------------\n// Route factory\n// ---------------------------------------------------------------------------\n\n/**\n * Default roles for view: broad reach across the admin shell.\n *\n * `BUILT_IN_ROLES` in `packages/auth/src/permissions.ts` is\n * `['admin', 'public', 'authenticated', 'agent', 'customer']` — `admin` is\n * hardcoded as an unconditional yes in `buildPermissionChecker`,\n * `agent` is the only non-admin built-in that flows through\n * `buildInitialRoleDefinitions()` + `upsertBuiltInRoles` with default\n * media access (`customer` seeds with zero permissions — see that\n * function's JSDoc). The `agent` entry in this list is what gives ops\n * agents read-only media access on first boot of a fresh install.\n *\n * `editor` and `viewer` are CONVENTIONAL app-defined roles —\n * apps that follow the scaffold pattern create them as part of\n * their own role catalog. Including them in `defaultRoles` doesn't\n * seed them (the seeder only iterates the built-ins above), but\n * the values DO flow into the process-local permission catalog\n * (see `registerPermission` in `@murumets-ee/core`), which the\n * forthcoming Permission Matrix UI (PR-D) reads to show \"this\n * route's recommended default grants\" against the app's actual\n * role set. The catalog is also the mechanism via which a future\n * upgrade of `upsertBuiltInRoles` could extend the seed surface\n * to app-defined roles without each plugin having to re-declare\n * its defaults.\n */\nconst VIEW_DEFAULT_ROLES = ['admin', 'editor', 'agent', 'viewer'] as const\n\n/** Default roles for create/delete — narrower than view. */\nconst WRITE_DEFAULT_ROLES = ['admin', 'editor'] as const\n\n/**\n * Build admin API routes for media management.\n *\n * Returns `AdminRoute[]` from `combineAdminRoutes` — one entry per\n * `(prefix, method)` after grouping. Callers spread the result into\n * their top-level routes list: `routes: [...mediaRoutes()]`.\n *\n * Four `defineAdminRoute` entries:\n *\n *   - GET    matchAnyPath with `media:view`   defaultRoles: VIEW_DEFAULT_ROLES\n *   - POST   path=''            `media:create` defaultRoles: WRITE_DEFAULT_ROLES\n *   - POST   path='regenerate-variants' `media:create` defaultRoles: WRITE_DEFAULT_ROLES\n *   - DELETE matchAnyPath with `media:delete` defaultRoles: WRITE_DEFAULT_ROLES\n *\n * Permissions are auto-registered by the entity catalog\n * (`buildResourceCatalog` in `@murumets-ee/auth`) AND by\n * `registerPermission` inside `defineAdminRoute`. Idempotent —\n * `registerPermission` unions `defaultRoles` on repeat registration,\n * so the framework's two pathways agree on the final grant set.\n *\n * Standard entity CRUD (PATCH with translations) is NOT registered\n * here — it falls through to the generic entity handler. Add `Media`\n * to the `entities` array in your handler config to enable it.\n */\nexport function mediaRoutes(): AdminRoute[] {\n  const entries = [\n    defineAdminRoute({\n      prefix: 'media',\n      path: '',\n      method: 'GET',\n      permission: 'media:view',\n      defaultRoles: VIEW_DEFAULT_ROLES,\n      matchAnyPath: true,\n      description: 'Read media — list, single item, or referencing-entity usage report.',\n      handler: handleGet,\n    }),\n    defineAdminRoute({\n      prefix: 'media',\n      path: '',\n      method: 'POST',\n      permission: 'media:create',\n      defaultRoles: WRITE_DEFAULT_ROLES,\n      description: 'Upload a media file (multipart FormData with `file` field).',\n      handler: handleUpload,\n    }),\n    defineAdminRoute({\n      prefix: 'media',\n      path: 'regenerate-variants',\n      method: 'POST',\n      permission: 'media:create',\n      defaultRoles: WRITE_DEFAULT_ROLES,\n      description:\n        'Catch every image up with the current shapes, widths and styles — queued as a background ' +\n        'backfill (synchronous only when the app has no queue).',\n      handler: handleRegenerateVariants,\n    }),\n    defineAdminRoute({\n      prefix: 'media',\n      path: '',\n      method: 'DELETE',\n      permission: 'media:delete',\n      defaultRoles: WRITE_DEFAULT_ROLES,\n      matchAnyPath: true,\n      description: 'Delete a media record + its storage object.',\n      handler: handleDelete,\n    }),\n  ]\n\n  return combineAdminRoutes(entries)\n}\n"],"mappings":"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"}

package/dist/ru-ojvshRJy.mjs

@@ -0,0 +1,2 @@
+var e={PluginNav:{media:`Медиа`},Media:{imageVocabulary:{description:`Каждая фотография создаётся в каждой форме ниже и в каждой ширине. Слот, соотношение сторон которого совпадает с формой, использует её файлы; слот с другим соотношением сторон обрезается в браузере.`,usingDefaults:`Здесь пока ничего не сохранено. Показаны значения по умолчанию; пока вы не сохраните, сайт использует их — или формы, заданные в его коде, если они есть.`,widthsLabel:`Ширины (px)`,widthsHelp:`По возрастанию, через запятую. Фотография никогда не увеличивается — ширина, которую она не может обеспечить, пропускается.`,widthsInvalid:`Укажите до {count} возрастающих целых чисел от {min} до {max}.`,shapesLabel:`Формы`,naturalNote:`А также «natural» — каждая фотография в своей форме, в тех же ширинах.`,columnName:`Название`,columnRatio:`Соотношение (Ш:В)`,columnWidths:`Свои ширины`,ownWidthsPlaceholder:`Все ширины`,ratioInvalid:`Запишите соотношение как Ш:В, например 3:2.`,nameInvalid:`Строчные буквы, цифры, - и _, начиная с буквы — и не «natural».`,nameTaken:`Форма с названием «{name}» уже существует.`,tooMany:`Не более {count} форм.`,add:`Добавить форму`,remove:`Удалить {name}`,tooManyFiles:`Это даёт {count} файлов на каждую фотографию; максимум — {max}. Сначала удалите форму или ширину.`},variantBacklog:{waiting:`Изображений, ожидающих создания размеров: {count}`,workerRunning:`Обработчик очереди сейчас их создаёт. Пока он не закончит, эти изображения показываются в полном размере.`,workerMissing:`Ни один обработчик очереди не запущен, поэтому эти изображения показываются в полном размере — страницы грузятся медленнее, особенно на телефонах. Размеры изображений создаёт обработчик очереди — отдельный процесс, который должен работать рядом с сайтом (pnpm worker). Попросите того, кто обслуживает сайт, запустить его.`,waitingSince:`Самое старое поставлено в очередь {since}.`,failed:`Создание размеров не удалось {count} раз(а), попытки прекращены — причина на странице очереди.`,catchUp:`Обновление всей медиатеки поставлено в очередь: каждое изображение сверяется с текущими формами и стилями.`,catchUpWorkerMissing:`Ни один обработчик очереди не запущен, поэтому оно не началось. Размеры изображений создаёт обработчик очереди — отдельный процесс, который должен работать рядом с сайтом (pnpm worker). Попросите того, кто обслуживает сайт, запустить его.`,openQueue:`Открыть очередь`},variantGeneration:{workerRequired:`Размеры изображений создаются в фоне обработчиком очереди — отдельным процессом, который должен работать рядом с сайтом (pnpm worker). Без него сайт работает, но новые и изменённые изображения показываются в полном размере.`,regenerate:`Обновить все изображения`,regenerating:`Запуск…`,queued:`Запущено. Обработчик очереди обновляет медиатеку в фоне; сайт при этом продолжает работать. Следите за ходом на странице очереди.`,alreadyRunning:`Обновление уже идёт — следите за ним на странице очереди.`,inlineDone:`Обработано {processed} из {total}; пропущено {skipped}; ошибок {errors}.`,failed:`Не удалось запустить обновление: {reason}`}},MediaCropEditor:{tabListLabel:`Формы обрезки`,description:`Перетащите, чтобы расположить фотографию, прокрутите или сведите пальцы для масштабирования. Каждое место с этой формой покажет эту обрезку.`,xLabel:`Слева (%)`,yLabel:`Сверху (%)`,widthLabel:`Ширина (%)`,heightLabel:`Высота (%)`,clearShape:`Очистить эту обрезку`,noShapes:`Ни один настроенный стиль изображения пока не имеет фиксированного соотношения сторон, поэтому обрезать нечего.`,hasCropSuffix:`— сохранена собственная обрезка`}};export{e as default};
+//# sourceMappingURL=ru-ojvshRJy.mjs.map

package/dist/ru-ojvshRJy.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"ru-ojvshRJy.mjs","names":[],"sources":["../src/messages/ru.json"],"sourcesContent":[""],"mappings":""}

package/dist/schedule-JlvfUEVA.mjs

@@ -0,0 +1,2 @@
+import{r as e}from"./definitions-LJpgrdxd.mjs";import{t}from"./slot-CY4isqmN.mjs";import{createVariantDeps as n}from"./deps-DaGjHO16.mjs";let r=!1;async function i(i,a,o){try{let s=t();if(s){let{QueueClient:t}=await import(`@murumets-ee/queue/client`);return{mode:`queued`,jobId:await new t({app:i,logger:i.logger}).enqueue(s.generateVariants,{mediaId:a.id,epoch:e})}}r||(r=!0,i.logger.warn(`media: no queue plugin in this app — image variants are generated inline, so every image upload waits for them. Add queue() and run a worker to make uploads return at once.`));let{generateMediaVariants:c}=await import(`./generate-variants-Dpy4aT2o.mjs`);return await c(a.id,await n(i,o)),{mode:`inline`}}catch(e){return i.logger.error({err:e,mediaId:a.id},`media: variants could not be requested; the original is served until a backfill runs`),{mode:`failed`}}}export{i as requestVariants};
+//# sourceMappingURL=schedule-JlvfUEVA.mjs.map

package/dist/schedule-JlvfUEVA.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"schedule-JlvfUEVA.mjs","names":[],"sources":["../src/jobs/schedule.ts"],"sourcesContent":["/**\n * Asking for a photograph's variants — queued when the app has a queue, inline\n * when it does not.\n *\n * The queued path is the design (images D004): the upload returns as soon as\n * the row exists, and the worker generates. The inline path is what an app\n * without the queue plugin (`apps/web-astro`) always had, kept rather than\n * removed so that such an app does not silently lose variants — it pays the\n * old upload stall instead, and says so once in its log.\n */\n\nimport type { ToolkitApp } from '@murumets-ee/core'\nimport { UPLOAD_EPOCH } from './definitions.js'\nimport { createVariantDeps, type VariantMediaAccess } from './deps.js'\nimport type { VariantGenerationDeps, VariantSourceRow } from './generate-variants.js'\nimport { getMediaJobs } from './slot.js'\n\nexport type VariantRequestOutcome =\n  /** A `media:generate-variants` job is waiting for the worker. */\n  | { readonly mode: 'queued'; readonly jobId: string }\n  /** No queue in this app — generated before returning. */\n  | { readonly mode: 'inline' }\n  /** Neither happened; logged. The original is served until a backfill runs. */\n  | { readonly mode: 'failed' }\n\nlet warnedInline = false\n\n/**\n * Queue (or, with no queue, run) a variant pass for `row`. Never throws: the\n * row already exists and serves its original, which is the correct fallback\n * for anything that goes wrong here.\n */\nexport async function requestVariants(\n  app: ToolkitApp,\n  row: Pick<VariantSourceRow, 'id'>,\n  clients: { media: VariantMediaAccess; storage: VariantGenerationDeps['storage'] },\n): Promise<VariantRequestOutcome> {\n  try {\n    const jobs = getMediaJobs()\n    if (jobs) {\n      const { QueueClient } = await import('@murumets-ee/queue/client')\n      const queue = new QueueClient({ app, logger: app.logger })\n      const jobId = await queue.enqueue(jobs.generateVariants, {\n        mediaId: row.id,\n        epoch: UPLOAD_EPOCH,\n      })\n      return { mode: 'queued', jobId }\n    }\n    if (!warnedInline) {\n      warnedInline = true\n      app.logger.warn(\n        'media: no queue plugin in this app — image variants are generated inline, so every ' +\n          'image upload waits for them. Add queue() and run a worker to make uploads return at once.',\n      )\n    }\n    const { generateMediaVariants } = await import('./generate-variants.js')\n    await generateMediaVariants(row.id, await createVariantDeps(app, clients))\n    return { mode: 'inline' }\n  } catch (err) {\n    app.logger.error(\n      { err, mediaId: row.id },\n      'media: variants could not be requested; the original is served until a backfill runs',\n    )\n    return { mode: 'failed' }\n  }\n}\n"],"mappings":"0IAyBA,IAAI,EAAe,GAOnB,eAAsB,EACpB,EACA,EACA,EACgC,CAChC,GAAI,CACF,IAAM,EAAO,EAAa,EAC1B,GAAI,EAAM,CACR,GAAM,CAAE,eAAgB,MAAM,OAAO,6BAMrC,MAAO,CAAE,KAAM,SAAU,MAAA,MAJL,IADF,EAAY,CAAE,MAAK,OAAQ,EAAI,MAAO,CAChC,CAAC,CAAC,QAAQ,EAAK,iBAAkB,CACvD,QAAS,EAAI,GACb,MAAO,CACT,CAAC,CAC8B,CACjC,CACK,IACH,EAAe,GACf,EAAI,OAAO,KACT,8KAEF,GAEF,GAAM,CAAE,yBAA0B,MAAM,OAAO,oCAE/C,OADA,MAAM,EAAsB,EAAI,GAAI,MAAM,EAAkB,EAAK,CAAO,CAAC,EAClE,CAAE,KAAM,QAAS,CAC1B,OAAS,EAAK,CAKZ,OAJA,EAAI,OAAO,MACT,CAAE,MAAK,QAAS,EAAI,EAAG,EACvB,sFACF,EACO,CAAE,KAAM,QAAS,CAC1B,CACF"}

package/dist/shapes-BpOEJeLx.mjs

@@ -0,0 +1,2 @@
+function e(e){let t=[];for(let n of e.shapes)n.ratio===null||!(n.ratio>0)||n.name.length>64||t.push({name:n.name,ratio:n.ratio});return t.sort((e,t)=>e.name<t.name?-1:+(e.name>t.name))}function t(e){let t=[];for(let[n,r]of Object.entries(e))r.width&&r.width>0&&r.height&&r.height>0&&t.push({name:n,ratio:r.width/r.height});return t.sort((e,t)=>e.name.localeCompare(t.name))}export{t as n,e as t};
+//# sourceMappingURL=shapes-BpOEJeLx.mjs.map

package/dist/shapes-BpOEJeLx.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"shapes-BpOEJeLx.mjs","names":[],"sources":["../src/crop/shapes.ts"],"sourcesContent":["/**\n * The crop editor's shape vocabulary — which shapes have a fixed aspect ratio,\n * and so get a crop tab (images PR03, rewired in PR08).\n *\n * Admin-only: unlike `focal-point.ts` / `crop-rect.ts`, this never reaches\n * the render spine. It runs once, server-side, on the media edit page.\n */\n\nimport type { ResolvedShape } from '../shapes.js'\nimport type { CropShape, ImageStyle } from '../types.js'\nimport { MAX_SHAPE_NAME_LENGTH } from './crop-rect.js'\n\n/**\n * The crop tabs for a resolved variant config — every shape the generator\n * plans that has a fixed ratio, under the NAME the generator reads a crop by.\n *\n * 🔴 **This is the one the media edit page uses, and the name is the contract.**\n * A crop is stored as `crops[<tab name>]` and the generator looks it up as\n * `crops[shape.name]` (`variant-plan.ts` `effectiveRect`). Before images PR08\n * the tabs came from {@link deriveCropShapes} over the LEGACY fixed styles —\n * `card`, `hero`, `thumbnail` — while PR04 had folded each of those, at its\n * default, into a vocabulary shape (`landscape`, `wide`, `square`). So on a\n * default site every tab was a name no shape carried: a crop drawn on any of\n * them changed no file, and the vocabulary's own shapes had no tab at all\n * (images F031). Reading the SAME config the generator plans from makes the two\n * name sets one set by construction.\n *\n * `natural` has no ratio and gets no tab; a legacy style an operator edited away\n * from its default is its own one-rung shape, and keeps its tab. Neither does a\n * name longer than `MAX_SHAPE_NAME_LENGTH`: `cropsValidation` refuses a crops\n * map carrying such a key, so a tab for it could never be saved — and would\n * take every other tab's save down with it.\n *\n * Sorted by code unit, not `localeCompare`, for the reason `shapes.ts`'s\n * `compareNames` gives: collation depends on the runtime's ICU data.\n */\nexport function cropShapesFor(config: {\n  readonly shapes: readonly Pick<ResolvedShape, 'name' | 'ratio'>[]\n}): CropShape[] {\n  const shapes: CropShape[] = []\n  for (const shape of config.shapes) {\n    if (shape.ratio === null || !(shape.ratio > 0)) continue\n    if (shape.name.length > MAX_SHAPE_NAME_LENGTH) continue\n    shapes.push({ name: shape.name, ratio: shape.ratio })\n  }\n  return shapes.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0))\n}\n\n/**\n * Which of `styles` declare a fixed ratio, sorted by name for a stable tab\n * order.\n *\n * @deprecated For the crop editor use {@link cropShapesFor} (images F031).\n *\n * ⚠️ Superseded for the crop editor by {@link cropShapesFor} (images F031): the\n * names here are LEGACY style names, which the generator does not read a crop\n * by once a style is folded into a vocabulary shape. Kept for its existing\n * public callers.\n *\n * A style with only ONE dimension set (`full: { width: 2400, fit: 'inside' }`)\n * constrains one axis and lets the other float — there is no fixed hole to\n * drag a crop window over, so it is excluded rather than offered a tab that\n * cannot mean anything.\n */\nexport function deriveCropShapes(styles: Record<string, ImageStyle>): CropShape[] {\n  const shapes: CropShape[] = []\n  for (const [name, style] of Object.entries(styles)) {\n    if (!(style.width && style.width > 0 && style.height && style.height > 0)) continue\n    shapes.push({ name, ratio: style.width / style.height })\n  }\n  return shapes.sort((a, b) => a.name.localeCompare(b.name))\n}\n"],"mappings":"AAoCA,SAAgB,EAAc,EAEd,CACd,IAAM,EAAsB,CAAC,EAC7B,IAAK,IAAM,KAAS,EAAO,OACrB,EAAM,QAAU,MAAQ,EAAE,EAAM,MAAQ,IACxC,EAAM,KAAK,OAAA,IACf,EAAO,KAAK,CAAE,KAAM,EAAM,KAAM,MAAO,EAAM,KAAM,CAAC,EAEtD,OAAO,EAAO,MAAM,EAAG,IAAO,EAAE,KAAO,EAAE,KAAO,GAAK,IAAE,KAAO,EAAE,KAAa,CAC/E,CAkBA,SAAgB,EAAiB,EAAiD,CAChF,IAAM,EAAsB,CAAC,EAC7B,IAAK,GAAM,CAAC,EAAM,KAAU,OAAO,QAAQ,CAAM,EACzC,EAAM,OAAS,EAAM,MAAQ,GAAK,EAAM,QAAU,EAAM,OAAS,GACvE,EAAO,KAAK,CAAE,OAAM,MAAO,EAAM,MAAQ,EAAM,MAAO,CAAC,EAEzD,OAAO,EAAO,MAAM,EAAG,IAAM,EAAE,KAAK,cAAc,EAAE,IAAI,CAAC,CAC3D"}

package/dist/shapes-C51rXSDJ.d.mts

@@ -0,0 +1,90 @@
+import { i as ImageStyle, n as ImageFormat, p as ReadonlyImageVocabulary, r as ImageShape } from "./types-6PZQ4Zq6.mjs";
+
+//#region src/shapes.d.ts
+/**
+ * The implicit shape every configuration has: the photograph's own ratio, over
+ * the ladder. It is what a slot that declares no shape draws, so it is what
+ * that slot's `srcset` is made of. Reserved — no vocabulary shape may use it.
+ */
+declare const NATURAL_SHAPE = "natural";
+/**
+ * The default width ladder. Six rungs, because this is a LOCAL sharp on
+ * somebody's VPS: Astro ships a shorter list for local services than for
+ * remote ones, and says why — every rung is a generated file (R006).
+ */
+declare const DEFAULT_IMAGE_LADDER: readonly number[];
+/**
+ * The seeded shape vocabulary.
+ *
+ * ⚠️ Portrait is **3:4, not 4:5**. 4:5 is folk wisdom with no design-system
+ * backing anywhere in the survey; 3:4 has eBay's and the UAE design system's
+ * (R009). Re-read R009 before changing it.
+ */
+declare const DEFAULT_IMAGE_SHAPES: Readonly<Record<string, Readonly<ImageShape>>>;
+/**
+ * The seeded vocabulary + ladder — what a site that configured nothing gets.
+ * Frozen: it is shared by every reader, so a caller that wants to edit it
+ * copies it first (the settings editor and `resolveMediaConfig` both do).
+ */
+declare const DEFAULT_IMAGE_VOCABULARY: ReadonlyImageVocabulary;
+/** One shape the generator will produce variants for, fully defaulted. */
+interface ResolvedShape {
+  readonly name: string;
+  /** width / height, or `null` for the photograph's own ratio. */
+  readonly ratio: number | null;
+  /** Ascending, distinct. The rungs this shape is generated at, before the per-image filter. */
+  readonly widths: readonly number[];
+  readonly format: ImageFormat;
+  readonly quality: number;
+  /** Where it came from — the vocabulary, the implicit natural shape, or a legacy fixed style. */
+  readonly origin: 'vocabulary' | 'natural' | 'style';
+}
+/**
+ * A legacy style name answered by a (shape, rung) of the vocabulary.
+ *
+ * The rung is one the shape is CONFIGURED at. A given photograph may still not
+ * have it — a source narrower than the rung plans nothing that wide. That is a
+ * CONTRACT for the reader, which does not exist yet (images PR06 resolves
+ * variants for a render): resolving an alias for one photograph must take the
+ * nearest variant that photograph has, as it would for a shape asked by name.
+ */
+interface ShapeAlias {
+  readonly shape: string;
+  readonly width: number;
+}
+/** A legacy style the shape model cannot express, and why. */
+interface UnmappedStyle {
+  readonly name: string;
+  readonly reason: string;
+}
+/** The whole variant configuration, resolved. */
+interface VariantConfig {
+  /** `natural` first, then sorted by name. */
+  readonly shapes: readonly ResolvedShape[];
+  /** Legacy style name → the (shape, rung) that now answers it. */
+  readonly aliases: ReadonlyMap<string, ShapeAlias>;
+  /** Legacy styles and vocabulary entries that have no place in the model. */
+  readonly unmapped: readonly UnmappedStyle[];
+}
+/**
+ * Fold a vocabulary and the stored fixed styles into one {@link VariantConfig}.
+ *
+ * LENIENT, because it is a READ: the settings route validates what it stores
+ * (`image-styles-settings.ts`), but plugin config is code nobody validated, and
+ * a bad entry must cost that entry — reported in `unmapped` — never every
+ * upload's variants. Deterministic: the same input always yields the same
+ * config, in the same order, which the variant keys depend on.
+ */
+declare function buildVariantConfig(input: {
+  readonly vocabulary: ReadonlyImageVocabulary;
+  readonly styles: Readonly<Record<string, ImageStyle>>;
+}): VariantConfig;
+/**
+ * What a legacy style NAME refers to in the shape model: the (shape, rung) of
+ * its alias, or — for a style that became a one-rung shape — that shape at its
+ * one width. `undefined` for a name the model does not know.
+ */
+declare function resolveStyleName(config: VariantConfig, name: string): ShapeAlias | undefined;
+//#endregion
+export { ResolvedShape as a, VariantConfig as c, NATURAL_SHAPE as i, buildVariantConfig as l, DEFAULT_IMAGE_SHAPES as n, ShapeAlias as o, DEFAULT_IMAGE_VOCABULARY as r, UnmappedStyle as s, DEFAULT_IMAGE_LADDER as t, resolveStyleName as u };
+//# sourceMappingURL=shapes-C51rXSDJ.d.mts.map

package/dist/shapes-C51rXSDJ.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shapes-C51rXSDJ.d.mts","names":[],"sources":["../src/shapes.ts"],"mappings":";;;;AA2MgB;AAIhB;;;cAvJa,aAAA;AAyJI;AAIjB;;;;AAJiB,cAlJJ,oBAAA;;;;;;;;cAWA,oBAAA,EAAsB,QAAA,CAAS,MAAA,SAAe,QAAA,CAAS,UAAA;;;;;AAiJzB;cArI9B,wBAAA,EAA0B,uBAGrC;;UA2Fe,aAAA;EAAA,SACN,IAAA;;WAEA,KAAA;;WAEA,MAAA;EAAA,SACA,MAAA,EAAQ,WAAW;EAAA,SACnB,OAAA;;WAEA,MAAA;AAAA;;;;;;;;;;UAYM,UAAA;EAAA,SACN,KAAA;EAAA,SACA,KAAK;AAAA;;UAIC,aAAA;EAAA,SACN,IAAA;EAAA,SACA,MAAM;AAAA;;UAIA,aAAA;;WAEN,MAAA,WAAiB,aAAA;;WAEjB,OAAA,EAAS,WAAA,SAAoB,UAAA;;WAE7B,QAAA,WAAmB,aAAA;AAAA;;;;;;;;;;iBAwGd,kBAAA,CAAmB,KAAA;EAAA,SACxB,UAAA,EAAY,uBAAA;EAAA,SACZ,MAAA,EAAQ,QAAA,CAAS,MAAA,SAAe,UAAA;AAAA,IACvC,aAAA;;;;;;iBAgIY,gBAAA,CAAiB,MAAA,EAAQ,aAAA,EAAe,IAAA,WAAe,UAAU"}

package/dist/shapes-CqppzFzb.mjs

@@ -0,0 +1,2 @@
+const e=`natural`,t=Object.freeze([320,640,960,1280,1920,2560]),n=Object.freeze({square:Object.freeze({ratio:`1:1`}),landscape:Object.freeze({ratio:`3:2`}),wide:Object.freeze({ratio:`16:9`}),portrait:Object.freeze({ratio:`3:4`})}),r=Object.freeze({shapes:n,ladder:t}),i=`webp`,a=8192,o=/^[a-z][a-z0-9_-]{0,63}$/,s=/^([1-9]\d*):([1-9]\d*)$/;function c(e){if(typeof e!=`string`)return null;let t=s.exec(e);if(t===null)return null;let n=Number(t[1]),r=Number(t[2]);return n>1e4||r>1e4?null:n/r}function l(e){return e.ladder.length+Object.values(e.shapes).reduce((t,n)=>t+(n.widths??e.ladder).length,0)}const u=new Map([[`thumbnail`,{style:{width:200,height:200,fit:`cover`,format:`webp`,quality:80},shape:`square`}],[`card`,{style:{width:600,height:400,fit:`cover`,format:`webp`,quality:85},shape:`landscape`}],[`hero`,{style:{width:1920,height:800,fit:`cover`,format:`webp`,quality:85},shape:`wide`}],[`full`,{style:{width:2400,fit:`inside`,format:`webp`,quality:90},shape:e}]]);function d(e,t){return e.find(e=>e>=t)??e[e.length-1]}function f(e,t){return e<t?-1:+(e>t)}function p(e,t){return e.width===t.width&&e.height===t.height&&(e.fit??`cover`)===(t.fit??`cover`)&&(e.format??`webp`)===(t.format??`webp`)&&(e.quality??80)===(t.quality??80)}function m(e){return typeof e==`number`&&Number.isInteger(e)&&e>=16&&e<=8192}function h(e){return[...new Set(e.filter(m))].sort((e,t)=>e-t)}function g(e){return typeof e==`number`&&Number.isInteger(e)&&e>=1&&e<=100}const _=new Set([`webp`,`jpeg`,`png`,`avif`]);function v(e){return typeof e==`string`&&_.has(e)}function y(n){let r=[],a=new Map,s=h(Array.isArray(n.vocabulary.ladder)?n.vocabulary.ladder:[]).slice(0,12),l=s.length>0?s:[...t],m=Object.entries(n.vocabulary.shapes??{}).sort(([e],[t])=>f(e,t));for(let[e,t]of m){if(!o.test(e)||e===`natural`){r.push({name:e,reason:`not a usable shape name`});continue}if(a.size>=16){r.push({name:e,reason:`more than 16 shapes configured`});continue}let n=c(t?.ratio);if(n===null){r.push({name:e,reason:`ratio is not W:H in positive integers`});continue}let s=Array.isArray(t.widths)?h(t.widths):[];a.set(e,{name:e,ratio:n,widths:s.length>0?s.slice(0,12):l,format:v(t.format)?t.format:i,quality:g(t.quality)?t.quality:80,origin:`vocabulary`})}a.set(e,{name:e,ratio:null,widths:l,format:i,quality:80,origin:`natural`});let _=new Map,y=new Set,x=new Map(a),S=0,C=Object.entries(n.styles??{}).sort(([e],[t])=>f(e,t));for(let[e,t]of C){let n=u.get(e);if(n&&p(t,n.style)&&x.has(n.shape))continue;if(y.add(e),a.has(e)){r.push({name:e,reason:`a vocabulary shape has the same name`});continue}let i=b(e,t);`reason`in i?r.push(i):S>=16?r.push({name:e,reason:`more than 16 fixed styles configured`}):(a.set(e,i),S++)}for(let[e,t]of u){if(y.has(e)||a.has(e))continue;let n=x.get(t.shape),r=n&&t.style.width&&d(n.widths,t.style.width);n&&r&&_.set(e,{shape:n.name,width:r})}return{shapes:[...a.values()].sort((e,t)=>e.origin===`natural`?-1:t.origin===`natural`?1:f(e.name,t.name)),aliases:_,unmapped:r}}function b(e,t){if(!o.test(e))return{name:e,reason:`not a usable shape name`};let n=t.fit??`cover`,r=v(t.format)?t.format:i,a=g(t.quality)?t.quality:80;return m(t.width)?n===`cover`?m(t.height)?{name:e,ratio:t.width/t.height,widths:[t.width],format:r,quality:a,origin:`style`}:{name:e,reason:`a cover style needs a height`}:n===`inside`&&t.height===void 0?{name:e,ratio:null,widths:[t.width],format:r,quality:a,origin:`style`}:{name:e,reason:`fit '${n}' with this box has no single ratio and width`}:{name:e,reason:`no width, or a width outside the ladder bounds`}}function x(e,t){let n=e.aliases.get(t);if(n)return n;let r=e.shapes.find(e=>e.name===t&&e.origin===`style`),i=r?.widths[0];return r&&i!==void 0?{shape:r.name,width:i}:void 0}export{e as a,c,a as i,l,n,o,r,y as s,t,x as u};
+//# sourceMappingURL=shapes-CqppzFzb.mjs.map

package/dist/shapes-CqppzFzb.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"shapes-CqppzFzb.mjs","names":[],"sources":["../src/shapes.ts"],"sourcesContent":["/**\n * The shape model — what a variant IS once size and shape are separate axes\n * (images D003).\n *\n * - A **shape** is a name carrying one ratio (`square` 1:1, `portrait` 3:4, …).\n * - The **ladder** is one global, ascending list of widths.\n * - A **variant** is (shape × rung), its height derived from the ratio.\n *\n * `ImageStyle` conflated the two — `card: {600×400}` is one ratio at one\n * width — which is why no `srcset` could ever come out of it: a `srcset` needs\n * several widths at ONE shape.\n *\n * ## Why this lives in the SAME settings namespace\n *\n * The vocabulary is a second key (`vocabulary`) of the existing\n * `media.imageStyles` namespace, not a namespace of its own (C7). So it inherits\n * the settings DB → plugin config → hardcoded waterfall, the auto-derived\n * `settings_media.imageStyles` permission resource, and the admin settings page.\n * The existing `imageStyles` key keeps its meaning — an operator's fixed styles\n * — and keeps generating exactly as before for every caller that reads it.\n *\n * ## How the existing styles map onto the model — read-time, never rewritten\n *\n * {@link buildVariantConfig} folds the stored styles into the model when it is\n * READ, so no stored row is migrated and nothing an operator saved is lost:\n *\n * - The four seeded defaults, UNMODIFIED, become **aliases** onto the vocabulary\n *   (`thumbnail` → `square`@320, `card` → `landscape`@640, `hero` → `wide`@1920,\n *   `full` → the natural ladder's top rung). A caller that still asks for\n *   `'thumbnail'` by name is pointed at a variant the vocabulary generates\n *   anyway, instead of commissioning a near-duplicate file.\n * - Any other style — an operator's own, or a default they edited — becomes a\n *   **one-rung shape** under its own name. It keeps generating at the width they\n *   chose, and now at the ratio they chose as a first-class shape.\n * - A style no shape can express (`contain`/`fill`/`outside` fits, a height-only\n *   box, an `inside` box bounded on both axes) is reported as **unmapped**,\n *   with the reason. It is not dropped from anything: it still generates through\n *   the legacy path. It simply has no place in a ratio-and-width model.\n *\n * ## Bounded by configuration\n *\n * Nothing here takes a ratio from markup. A render site asking for a raw ratio\n * (`'1007/577'`) gets CSS cropping and the natural ladder, and no generated\n * variants (D003, N1) — which is what keeps the variant matrix bounded by what\n * an operator configured rather than by what a page happens to contain.\n *\n * Pure — no DB, no sharp, no settings client. Unit-tested on its own.\n */\n\nimport type { ImageFormat, ImageShape, ImageStyle, ReadonlyImageVocabulary } from './types.js'\n\n/**\n * The implicit shape every configuration has: the photograph's own ratio, over\n * the ladder. It is what a slot that declares no shape draws, so it is what\n * that slot's `srcset` is made of. Reserved — no vocabulary shape may use it.\n */\nexport const NATURAL_SHAPE = 'natural'\n\n/**\n * The default width ladder. Six rungs, because this is a LOCAL sharp on\n * somebody's VPS: Astro ships a shorter list for local services than for\n * remote ones, and says why — every rung is a generated file (R006).\n */\nexport const DEFAULT_IMAGE_LADDER: readonly number[] = Object.freeze([\n  320, 640, 960, 1280, 1920, 2560,\n])\n\n/**\n * The seeded shape vocabulary.\n *\n * ⚠️ Portrait is **3:4, not 4:5**. 4:5 is folk wisdom with no design-system\n * backing anywhere in the survey; 3:4 has eBay's and the UAE design system's\n * (R009). Re-read R009 before changing it.\n */\nexport const DEFAULT_IMAGE_SHAPES: Readonly<Record<string, Readonly<ImageShape>>> = Object.freeze({\n  square: Object.freeze({ ratio: '1:1' }),\n  landscape: Object.freeze({ ratio: '3:2' }),\n  wide: Object.freeze({ ratio: '16:9' }),\n  portrait: Object.freeze({ ratio: '3:4' }),\n})\n\n/**\n * The seeded vocabulary + ladder — what a site that configured nothing gets.\n * Frozen: it is shared by every reader, so a caller that wants to edit it\n * copies it first (the settings editor and `resolveMediaConfig` both do).\n */\nexport const DEFAULT_IMAGE_VOCABULARY: ReadonlyImageVocabulary = Object.freeze({\n  shapes: DEFAULT_IMAGE_SHAPES,\n  ladder: DEFAULT_IMAGE_LADDER,\n})\n\nexport const DEFAULT_VARIANT_FORMAT: ImageFormat = 'webp'\nexport const DEFAULT_VARIANT_QUALITY = 80\n\n/**\n * Bounds on the vocabulary. Every shape and every rung is a file per image, so\n * these are what keep one upload from commissioning an unbounded amount of\n * sharp work (CLAUDE.md \"No unbounded fan-out\"). The planner applies a hard\n * per-image cap on top — `MAX_VARIANTS_PER_IMAGE` in `variant-plan.ts` —\n * because legacy styles, which predate these bounds, also become shapes.\n */\nexport const MAX_SHAPES = 16\n/**\n * How many legacy fixed styles become one-rung shapes; the rest are reported\n * as unmapped. Legacy styles predate every bound here, and the planner deals\n * rungs round-robin, so this is what guarantees EVERY shape its first variant\n * under `MAX_VARIANTS_PER_IMAGE`: `MAX_SHAPES + MAX_STYLE_SHAPES + 1` (natural)\n * is 33, well under 64. A style past it is not resolvable by name either — it\n * is in no shape, so `resolveStyleName` answers `undefined` for it.\n */\nexport const MAX_STYLE_SHAPES = 16\nexport const MAX_LADDER_RUNGS = 12\nexport const MIN_VARIANT_WIDTH = 16\nexport const MAX_VARIANT_WIDTH = 8192\n/** The largest term a `W:H` ratio may carry. `1:10000` is already absurd. */\nexport const MAX_RATIO_TERM = 10000\n\n/**\n * Shape and style names — the same rule the style-name validator has always\n * had, bounded at 64 characters: a shape's name is also its `crops` KEY, and\n * `isCropsRecord` refuses a key longer than that (`MAX_SHAPE_NAME_LENGTH` in\n * `crop/crop-rect.ts`), so an unbounded name got a crop tab whose every save\n * failed (images PR08 review). Refused here, on save, where the operator sees it.\n */\nexport const SHAPE_NAME_PATTERN = /^[a-z][a-z0-9_-]{0,63}$/\n\nconst RATIO_PATTERN = /^([1-9]\\d*):([1-9]\\d*)$/\n\n/**\n * `'3:2'` → `1.5` (width / height), or `null` when the value is not a ratio\n * this model accepts: two positive integers, neither above\n * {@link MAX_RATIO_TERM}.\n */\nexport function parseShapeRatio(ratio: unknown): number | null {\n  if (typeof ratio !== 'string') return null\n  const match = RATIO_PATTERN.exec(ratio)\n  if (match === null) return null\n  const w = Number(match[1])\n  const h = Number(match[2])\n  if (w > MAX_RATIO_TERM || h > MAX_RATIO_TERM) return null\n  return w / h\n}\n\n/**\n * How many files a vocabulary plans per photograph, at most: every shape at its\n * widths (its own, else the ladder) plus `natural` over the ladder. The ONE\n * count both the settings schema and the editor check against the per-image\n * cap, so the editor cannot build what the route will refuse.\n */\nexport function plannedFileCount(vocabulary: {\n  readonly shapes: Readonly<Record<string, { readonly widths?: readonly number[] | undefined }>>\n  readonly ladder: readonly number[]\n}): number {\n  return (\n    vocabulary.ladder.length +\n    Object.values(vocabulary.shapes).reduce(\n      (sum, shape) => sum + (shape.widths ?? vocabulary.ladder).length,\n      0,\n    )\n  )\n}\n\nfunction gcd(a: number, b: number): number {\n  let x = a\n  let y = b\n  while (y !== 0) {\n    const t = y\n    y = x % y\n    x = t\n  }\n  return x\n}\n\n/** `(600, 400)` → `'3:2'`. Both arguments positive integers. */\nexport function reduceRatio(width: number, height: number): string {\n  const d = gcd(width, height)\n  return `${width / d}:${height / d}`\n}\n\n/** One shape the generator will produce variants for, fully defaulted. */\nexport interface ResolvedShape {\n  readonly name: string\n  /** width / height, or `null` for the photograph's own ratio. */\n  readonly ratio: number | null\n  /** Ascending, distinct. The rungs this shape is generated at, before the per-image filter. */\n  readonly widths: readonly number[]\n  readonly format: ImageFormat\n  readonly quality: number\n  /** Where it came from — the vocabulary, the implicit natural shape, or a legacy fixed style. */\n  readonly origin: 'vocabulary' | 'natural' | 'style'\n}\n\n/**\n * A legacy style name answered by a (shape, rung) of the vocabulary.\n *\n * The rung is one the shape is CONFIGURED at. A given photograph may still not\n * have it — a source narrower than the rung plans nothing that wide. That is a\n * CONTRACT for the reader, which does not exist yet (images PR06 resolves\n * variants for a render): resolving an alias for one photograph must take the\n * nearest variant that photograph has, as it would for a shape asked by name.\n */\nexport interface ShapeAlias {\n  readonly shape: string\n  readonly width: number\n}\n\n/** A legacy style the shape model cannot express, and why. */\nexport interface UnmappedStyle {\n  readonly name: string\n  readonly reason: string\n}\n\n/** The whole variant configuration, resolved. */\nexport interface VariantConfig {\n  /** `natural` first, then sorted by name. */\n  readonly shapes: readonly ResolvedShape[]\n  /** Legacy style name → the (shape, rung) that now answers it. */\n  readonly aliases: ReadonlyMap<string, ShapeAlias>\n  /** Legacy styles and vocabulary entries that have no place in the model. */\n  readonly unmapped: readonly UnmappedStyle[]\n}\n\n/**\n * The four seeded defaults, exactly as `defaultImageStyles` has always defined\n * them, and the vocabulary shape each one maps to (images PR04 acceptance).\n *\n * The RUNG is not stored: it is the smallest of the shape's widths that is at\n * least the style's own width, else its largest — so on the seeded ladder\n * `thumbnail` (200) → `square`@320, `card` (600) → `landscape`@640, `hero`\n * (1920) → `wide`@1920 and `full` (2400) → `natural`@2560, and on an\n * operator's own ladder it lands on a rung that ladder actually has.\n *\n * A stored style is aliased only when it is STILL this default. An operator who\n * edited `card` to 800×600 meant 800×600; that becomes a one-rung shape.\n */\nexport const LEGACY_STYLE_ALIASES: ReadonlyMap<\n  string,\n  { readonly style: ImageStyle; readonly shape: string }\n> = new Map([\n  [\n    'thumbnail',\n    {\n      style: { width: 200, height: 200, fit: 'cover', format: 'webp', quality: 80 },\n      shape: 'square',\n    },\n  ],\n  [\n    'card',\n    {\n      style: { width: 600, height: 400, fit: 'cover', format: 'webp', quality: 85 },\n      shape: 'landscape',\n    },\n  ],\n  [\n    'hero',\n    {\n      style: { width: 1920, height: 800, fit: 'cover', format: 'webp', quality: 85 },\n      shape: 'wide',\n    },\n  ],\n  [\n    'full',\n    { style: { width: 2400, fit: 'inside', format: 'webp', quality: 90 }, shape: NATURAL_SHAPE },\n  ],\n])\n\n/** The rung an alias answers with — see {@link LEGACY_STYLE_ALIASES}. */\nfunction aliasRung(widths: readonly number[], wanted: number): number | undefined {\n  return widths.find((w) => w >= wanted) ?? widths[widths.length - 1]\n}\n\n/**\n * Code-unit order, not `localeCompare`: the order decides nothing a reader\n * sees, but it must be the same on every process that plans a key, and a\n * collation depends on the ICU data and locale the process happens to have.\n */\nfunction compareNames(a: string, b: string): number {\n  return a < b ? -1 : a > b ? 1 : 0\n}\n\nfunction sameStyle(a: ImageStyle, b: ImageStyle): boolean {\n  return (\n    a.width === b.width &&\n    a.height === b.height &&\n    (a.fit ?? 'cover') === (b.fit ?? 'cover') &&\n    (a.format ?? DEFAULT_VARIANT_FORMAT) === (b.format ?? DEFAULT_VARIANT_FORMAT) &&\n    (a.quality ?? DEFAULT_VARIANT_QUALITY) === (b.quality ?? DEFAULT_VARIANT_QUALITY)\n  )\n}\n\nfunction isWidth(value: unknown): value is number {\n  return (\n    typeof value === 'number' &&\n    Number.isInteger(value) &&\n    value >= MIN_VARIANT_WIDTH &&\n    value <= MAX_VARIANT_WIDTH\n  )\n}\n\n/** Ascending and distinct, invalid entries dropped. */\nfunction normaliseWidths(widths: readonly unknown[]): number[] {\n  return [...new Set(widths.filter(isWidth))].sort((a, b) => a - b)\n}\n\nfunction isQuality(value: unknown): value is number {\n  return typeof value === 'number' && Number.isInteger(value) && value >= 1 && value <= 100\n}\n\nconst FORMATS: ReadonlySet<string> = new Set<ImageFormat>(['webp', 'jpeg', 'png', 'avif'])\n\nfunction isFormat(value: unknown): value is ImageFormat {\n  return typeof value === 'string' && FORMATS.has(value)\n}\n\n/**\n * Fold a vocabulary and the stored fixed styles into one {@link VariantConfig}.\n *\n * LENIENT, because it is a READ: the settings route validates what it stores\n * (`image-styles-settings.ts`), but plugin config is code nobody validated, and\n * a bad entry must cost that entry — reported in `unmapped` — never every\n * upload's variants. Deterministic: the same input always yields the same\n * config, in the same order, which the variant keys depend on.\n */\nexport function buildVariantConfig(input: {\n  readonly vocabulary: ReadonlyImageVocabulary\n  readonly styles: Readonly<Record<string, ImageStyle>>\n}): VariantConfig {\n  const unmapped: UnmappedStyle[] = []\n  const byName = new Map<string, ResolvedShape>()\n\n  const ladder = normaliseWidths(\n    Array.isArray(input.vocabulary.ladder) ? input.vocabulary.ladder : [],\n  ).slice(0, MAX_LADDER_RUNGS)\n  const effectiveLadder = ladder.length > 0 ? ladder : [...DEFAULT_IMAGE_LADDER]\n\n  const vocabularyEntries = Object.entries(input.vocabulary.shapes ?? {}).sort(([a], [b]) =>\n    compareNames(a, b),\n  )\n  for (const [name, shape] of vocabularyEntries) {\n    if (!SHAPE_NAME_PATTERN.test(name) || name === NATURAL_SHAPE) {\n      unmapped.push({ name, reason: 'not a usable shape name' })\n      continue\n    }\n    if (byName.size >= MAX_SHAPES) {\n      unmapped.push({ name, reason: `more than ${MAX_SHAPES} shapes configured` })\n      continue\n    }\n    const ratio = parseShapeRatio(shape?.ratio)\n    if (ratio === null) {\n      unmapped.push({ name, reason: 'ratio is not W:H in positive integers' })\n      continue\n    }\n    const own = Array.isArray(shape.widths) ? normaliseWidths(shape.widths) : []\n    byName.set(name, {\n      name,\n      ratio,\n      widths: own.length > 0 ? own.slice(0, MAX_LADDER_RUNGS) : effectiveLadder,\n      format: isFormat(shape.format) ? shape.format : DEFAULT_VARIANT_FORMAT,\n      quality: isQuality(shape.quality) ? shape.quality : DEFAULT_VARIANT_QUALITY,\n      origin: 'vocabulary',\n    })\n  }\n\n  byName.set(NATURAL_SHAPE, {\n    name: NATURAL_SHAPE,\n    ratio: null,\n    widths: effectiveLadder,\n    format: DEFAULT_VARIANT_FORMAT,\n    quality: DEFAULT_VARIANT_QUALITY,\n    origin: 'natural',\n  })\n\n  // A Map, not an object literal: every lookup below is by an operator-chosen\n  // NAME, and `constructor` passes the name rule — on a plain object it would\n  // find `Object.prototype.constructor` instead of nothing.\n  const aliases = new Map<string, ShapeAlias>()\n  const claimed = new Set<string>()\n  // What an alias may point at: the vocabulary and `natural` — fixed BEFORE the\n  // styles are read, so an operator's own style never becomes an alias target\n  // (a 3:1 style called `square` must not answer for `thumbnail`), and the\n  // answer does not depend on which style names sort first.\n  const aliasTargets = new Map(byName)\n  let styleShapes = 0\n\n  const styleEntries = Object.entries(input.styles ?? {}).sort(([a], [b]) => compareNames(a, b))\n  for (const [name, style] of styleEntries) {\n    const legacy = LEGACY_STYLE_ALIASES.get(name)\n    // Still the default AND its shape still exists → an alias, below. With the\n    // shape gone the style stands on its own as a one-rung shape, rather than\n    // being neither a shape, an alias nor unmapped.\n    if (legacy && sameStyle(style, legacy.style) && aliasTargets.has(legacy.shape)) continue\n    claimed.add(name)\n    if (byName.has(name)) {\n      unmapped.push({ name, reason: 'a vocabulary shape has the same name' })\n      continue\n    }\n    const converted = styleAsShape(name, style)\n    if ('reason' in converted) unmapped.push(converted)\n    else if (styleShapes >= MAX_STYLE_SHAPES) {\n      unmapped.push({ name, reason: `more than ${MAX_STYLE_SHAPES} fixed styles configured` })\n    } else {\n      byName.set(name, converted)\n      styleShapes++\n    }\n  }\n\n  for (const [name, legacy] of LEGACY_STYLE_ALIASES) {\n    // A name an operator reused for their own style, or one the vocabulary\n    // itself defines, answers as itself — never as the alias.\n    if (claimed.has(name) || byName.has(name)) continue\n    const target = aliasTargets.get(legacy.shape)\n    const width = target && legacy.style.width && aliasRung(target.widths, legacy.style.width)\n    if (target && width) aliases.set(name, { shape: target.name, width })\n  }\n\n  // `natural` first: it is what every slot that names no shape draws, so when\n  // the per-image cap has to cut, it must not be the shape that loses.\n  const shapes = [...byName.values()].sort((a, b) =>\n    a.origin === 'natural' ? -1 : b.origin === 'natural' ? 1 : compareNames(a.name, b.name),\n  )\n  return { shapes, aliases, unmapped }\n}\n\n/** A legacy fixed style as a one-rung shape, or the reason it cannot be one. */\nfunction styleAsShape(name: string, style: ImageStyle): ResolvedShape | UnmappedStyle {\n  if (!SHAPE_NAME_PATTERN.test(name)) return { name, reason: 'not a usable shape name' }\n  const fit = style.fit ?? 'cover'\n  const format = isFormat(style.format) ? style.format : DEFAULT_VARIANT_FORMAT\n  const quality = isQuality(style.quality) ? style.quality : DEFAULT_VARIANT_QUALITY\n  if (!isWidth(style.width)) {\n    return { name, reason: 'no width, or a width outside the ladder bounds' }\n  }\n  if (fit === 'cover') {\n    if (!isWidth(style.height)) return { name, reason: 'a cover style needs a height' }\n    return {\n      name,\n      ratio: style.width / style.height,\n      widths: [style.width],\n      format,\n      quality,\n      origin: 'style',\n    }\n  }\n  if (fit === 'inside' && style.height === undefined) {\n    return { name, ratio: null, widths: [style.width], format, quality, origin: 'style' }\n  }\n  return { name, reason: `fit '${fit}' with this box has no single ratio and width` }\n}\n\n/**\n * What a legacy style NAME refers to in the shape model: the (shape, rung) of\n * its alias, or — for a style that became a one-rung shape — that shape at its\n * one width. `undefined` for a name the model does not know.\n */\nexport function resolveStyleName(config: VariantConfig, name: string): ShapeAlias | undefined {\n  const alias = config.aliases.get(name)\n  if (alias) return alias\n  const shape = config.shapes.find((s) => s.name === name && s.origin === 'style')\n  const width = shape?.widths[0]\n  return shape && width !== undefined ? { shape: shape.name, width } : undefined\n}\n"],"mappings":"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"}

package/dist/slot-CY4isqmN.mjs

@@ -0,0 +1,2 @@
+import{t as e}from"./rolldown-runtime-DK3Fl9T5.mjs";var t=e({getMediaJobs:()=>r,setMediaJobs:()=>i});const n=Symbol.for(`@murumets-ee/media:jobs`);function r(){return globalThis[n]}function i(e){globalThis[n]=e}export{i as n,t as r,r as t};
+//# sourceMappingURL=slot-CY4isqmN.mjs.map

package/dist/slot-CY4isqmN.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"slot-CY4isqmN.mjs","names":[],"sources":["../src/jobs/slot.ts"],"sourcesContent":["/**\n * Where the registered media job handles live, so an enqueuer can find them\n * without importing the registration (which pulls in `@murumets-ee/core`) —\n * the entity's own behavior reads this, and `entity.ts` must stay light.\n *\n * `globalThis` + `Symbol.for`, the queue's own registry shape: it survives HMR\n * and a duplicated module instance, so the upload route in the Next process\n * sees the handles the plugin's `init` stored.\n */\n\nimport type { JobDefinition } from '@murumets-ee/queue/client'\nimport type { GenerateVariantsPayload, VariantsBackfillPayload } from './definitions.js'\n\nexport interface MediaJobs {\n  readonly generateVariants: JobDefinition<GenerateVariantsPayload>\n  readonly variantsBackfill: JobDefinition<VariantsBackfillPayload>\n}\n\nconst SLOT = Symbol.for('@murumets-ee/media:jobs')\ninterface GlobalWithSlot {\n  [SLOT]?: MediaJobs\n}\n\n/** The registered job handles, or `undefined` when the queue plugin is not in this app. */\nexport function getMediaJobs(): MediaJobs | undefined {\n  return (globalThis as GlobalWithSlot)[SLOT]\n}\n\n/** Written once, by `registerMediaJobs`. */\nexport function setMediaJobs(jobs: MediaJobs): void {\n  ;(globalThis as GlobalWithSlot)[SLOT] = jobs\n}\n\n/** For tests only. */\nexport function clearMediaJobs(): void {\n  delete (globalThis as GlobalWithSlot)[SLOT]\n}\n"],"mappings":"qGAkBA,MAAM,EAAO,OAAO,IAAI,yBAAyB,EAMjD,SAAgB,GAAsC,CACpD,OAAQ,WAA8B,EACxC,CAGA,SAAgB,EAAa,EAAuB,CACjD,WAA+B,GAAQ,CAC1C"}

package/dist/{types-CnORVkLZ.d.mts → types-6PZQ4Zq6.d.mts}

@@ -72,6 +72,18 @@ declare const Media: import("@murumets-ee/entity").Entity<{
    * its own accepts any JSON.
    */
   focalPoint: import("@murumets-ee/entity").JsonField & Partial<import("@murumets-ee/entity").JsonField>;
+  /**
+   * Per-shape crop overrides, keyed by shape name — `{x, y, w, h}` fractions
+   * of the image, `[0,1]` (images D002). Optional: a shape absent from this
+   * map falls back to the rect `focalPoint` implies for that shape's ratio,
+   * which is why a missing crop is a fallback and never a hole. Written by
+   * the crop editor (`@murumets-ee/media/crop-editor`, images PR03).
+   *
+   * `null` and `{}` both mean "no shape has an override" — the same reading
+   * `readFocalPoint` gives an absent focal point (D010). Shape is enforced
+   * by `cropsValidation()` below.
+   */
+  crops: import("@murumets-ee/entity").JsonField & Partial<import("@murumets-ee/entity").JsonField>;
   mediaType: import("@murumets-ee/entity").SelectField & {
     options: readonly ["image", "video", "audio", "document", "other"];
   } & {
@@ -79,7 +91,7 @@ declare const Media: import("@murumets-ee/entity").Entity<{
     readonly required: true;
     readonly indexed: true;
   };
-}, "media", [import("@murumets-ee/entity").Behavior<import("@murumets-ee/entity").AuditableFields, string>, import("@murumets-ee/entity").Behavior<Record<never, never>, "focalPointValidation">, import("@murumets-ee/entity").SearchableBehavior]>;
+}, "media", [import("@murumets-ee/entity").Behavior<import("@murumets-ee/entity").AuditableFields, string>, import("@murumets-ee/entity").Behavior<Record<never, never>, "focalPointValidation">, import("@murumets-ee/entity").Behavior<Record<never, never>, "cropsValidation">, import("@murumets-ee/entity").Behavior<Record<never, never>, "variantRegeneration">, import("@murumets-ee/entity").SearchableBehavior]>;
 //#endregion
 //#region src/types.d.ts
 /** Media type derived from MIME type */
@@ -146,6 +158,65 @@ interface MediaListResult {
   limit: number;
   offset: number;
 }
+/** An output encoding for a generated variant. */
+type ImageFormat = 'webp' | 'jpeg' | 'png' | 'avif';
+/**
+ * A named aspect ratio in the operator's shape vocabulary (images D003).
+ *
+ * A shape is a NAME carrying ONE ratio; its SIZES come from the global
+ * {@link ImageVocabulary.ladder}. A variant is (shape × ladder rung), so one
+ * shape yields a whole `srcset` — the thing an {@link ImageStyle}, being one
+ * ratio at one width, could never produce.
+ *
+ * A `type`, not an `interface`, because it is stored inside a `setting.json()`
+ * value, and only a type alias is assignable to a JSON value type.
+ */
+type ImageShape = {
+  /** `W:H` in positive integers — `'3:2'`, `'3:4'`, `'16:9'`. */ratio: string;
+  /**
+   * Widths for THIS shape instead of the global ladder. Unset for a vocabulary
+   * shape; a legacy fixed style survives as a shape with exactly one entry.
+   */
+  widths?: number[]; /** Output format (default: `'webp'`). */
+  format?: ImageFormat; /** Output quality 1–100 (default: 80). */
+  quality?: number;
+};
+/**
+ * The shape vocabulary and the width ladder — the `vocabulary` key of the
+ * `media.imageStyles` settings namespace (images D003, C7).
+ */
+type ImageVocabulary = {
+  /** Shape name → shape. Names follow the style-name rule and may not be `natural`. */shapes: Record<string, ImageShape>; /** Ascending, distinct pixel widths every shape is generated at. */
+  ladder: number[];
+};
+/** A vocabulary as it is READ — what config and the model accept; nothing mutates one. */
+type ReadonlyImageVocabulary = {
+  readonly shapes: Readonly<Record<string, ImageShape>>;
+  readonly ladder: readonly number[];
+};
+/**
+ * A FIXED-BOX image processing preset — one ratio at one width.
+ *
+ * The pre-images-D003 model, still honoured: stored styles keep generating
+ * exactly as before, and each one also appears in the shape model as a
+ * one-rung shape (or, for the four seeded defaults, as an ALIAS onto the
+ * vocabulary — see `shapes.ts`).
+ */
+/**
+ * A named shape the crop editor offers a tab for (images PR03) — a shape the
+ * variant generator plans with a fixed aspect ratio, under the name it reads a
+ * crop by (`cropShapesFor`, images F031).
+ *
+ * A NUMERIC width/height ratio, not {@link ImageShape}'s `'W:H'` string: the
+ * crop editor's aspect-lock math (`crop-editor.tsx`, `crop/crop-rect.ts`) works
+ * in numbers throughout, and the resolved variant config already carries the
+ * number. The `natural` shape has no fixed ratio and gets no tab.
+ */
+interface CropShape {
+  readonly name: string;
+  /** width / height. */
+  readonly ratio: number;
+}
 /** Named image processing preset — defines how to resize/convert an image variant */
 interface ImageStyle {
   /** Max width in pixels (omit for height-only constraint) */
@@ -155,7 +226,7 @@ interface ImageStyle {
   /** Resize strategy (default: 'cover') */
   fit?: 'cover' | 'contain' | 'inside' | 'outside' | 'fill';
   /** Output format (default: 'webp') */
-  format?: 'webp' | 'jpeg' | 'png' | 'avif';
+  format?: ImageFormat;
   /** Output quality 1–100 (default: 80) */
   quality?: number;
 }
@@ -173,9 +244,15 @@ interface MediaPluginConfig {
   maxUploadSize?: number;
   /** Default file visibility (default: 'public') */
   defaultVisibility?: FileVisibility;
-  /** Named image processing presets. Variants generated on upload for each style. */
+  /** Named image processing presets. A file per style is generated for every image, by the queue worker (images D004). */
   imageStyles?: Record<string, ImageStyle>;
+  /**
+   * The shape vocabulary and width ladder, used when the settings DB holds none
+   * (default: `DEFAULT_IMAGE_VOCABULARY` — square 1:1, landscape 3:2, wide 16:9,
+   * portrait 3:4 over `[320, 640, 960, 1280, 1920, 2560]`).
+   */
+  vocabulary?: ReadonlyImageVocabulary;
 }
 //#endregion
-export { MediaRecord as a, MediaUploadResult as c, MediaPluginConfig as i, Media as l, MediaListOptions as n, MediaType as o, MediaListResult as r, MediaUploadOptions as s, ImageStyle as t };
-//# sourceMappingURL=types-CnORVkLZ.d.mts.map
+export { ImageVocabulary as a, MediaPluginConfig as c, MediaUploadOptions as d, MediaUploadResult as f, ImageStyle as i, MediaRecord as l, Media as m, ImageFormat as n, MediaListOptions as o, ReadonlyImageVocabulary as p, ImageShape as r, MediaListResult as s, CropShape as t, MediaType as u };
+//# sourceMappingURL=types-6PZQ4Zq6.d.mts.map

package/dist/types-6PZQ4Zq6.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types-6PZQ4Zq6.d.mts","names":[],"sources":["../src/entity.ts","../src/types.ts"],"mappings":";;;;;;;;AAsBA;;;;;;;;;;;;cAAa,KAAA,gCAAK,MAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KCjBN,SAAA;;UAGK,kBAAA;;EAEf,QAAA;;EAEA,QAAA;;EAEA,IAAA;;EAEA,UAAA,GAAa,cAAc;EDMX;ECJhB,KAAA;;EAEA,GAAA;;EAEA,WAAA;;EAEA,KAAA;;EAEA,MAAA;;EAEA,UAAA;AAAA;;UAIe,iBAAA;;EAEf,KAAA,EAAO,WAAW;;EAElB,GAAA;AAAA;;;;;;;;KAUU,WAAA,GAAc,cAAc,QAAQ,KAAA,CAAM,SAAA;;UAGrC,gBAAA;;EAEf,SAAA,GAAY,SAAS;;EAErB,cAAA;;EAEA,MAAA;;EAEA,KAAA;;EAEA,MAAA;;EAEA,OAAA;;EAEA,cAAA;AAAA;;UAIe,eAAA;EACf,KAAA,EAAO,WAAW;EAClB,KAAA;EACA,KAAA;EACA,MAAA;AAAA;;KAIU,WAAA;;;;;;;;;;;;KAaA,UAAA;iEAEV,KAAA;;AArFF;;;EA0FE,MAAA,aA1FmB;EA4FnB,MAAA,GAAS,WAAW,EAzFa;EA2FjC,OAAA;AAAA;;;;;KAOU,eAAA;EAxFV,qFA0FA,MAAA,EAAQ,MAAM,SAAS,UAAA,GAtFvB;EAwFA,MAAA;AAAA;;KAIU,uBAAA;EAAA,SACD,MAAA,EAAQ,QAAA,CAAS,MAAA,SAAe,UAAA;EAAA,SAChC,MAAA;AAAA;;;;;;;AAhFN;AAUL;;;;;;;;AAA+D;AAG/D;;UAyFiB,SAAA;EAAA,SACN,IAAA;EAxFT;EAAA,SA0FS,KAAK;AAAA;;UAIC,UAAA;EAtFf;EAwFA,KAAA;EApFA;EAsFA,MAAA;EAtFc;EAwFd,GAAA;EApF8B;EAsF9B,MAAA,GAAS,WAAW;EArFF;EAuFlB,OAAA;AAAA;;UAIe,iBAAA;EAxFf;;AAAM;AAIR;;;;EA4FE,aAAA;EA/EU;EAiFV,aAAA;;EAEA,iBAAA,GAAoB,cAAA;EAjFpB;EAmFA,WAAA,GAAc,MAAA,SAAe,UAAA;EA5E7B;;;;AAEO;EAgFP,UAAA,GAAa,uBAAA;AAAA"}