@12-apps/storage 2.0.1 → 2.2.0

package/package.json

@@ -1,15 +1,17 @@
 {
   "name": "@12-apps/storage",
-  "version": "2.0.1",
+  "version": "2.2.0",
   "type": "module",
   "description": "Image uploads that land at YOUR OWN ORIGIN, never at the bucket (12-20). Isomorphic core (format allowlist, upload ceiling, object-key grammar, rendition set, refusal taxonomy, wire schemas), host-mounted backend surface (./server: createApiStorage, the local-disk driver, the image-pipeline port, the orphan reclaim), Hono adapter (./hono), the S3-compatible driver behind its own subpath (./s3) and the bound picker + upload hook (./react). Standardized adoption contract in ADOPTING.md.",
   "exports": {
     ".": "./src/index.ts",
-    "./server": "./src/server/index.ts",
-    "./react": "./src/react/index.ts",
     "./hono": "./src/hono/index.ts",
+    "./manifest": "./src/manifest/index.ts",
+    "./manifest/server": "./src/manifest/server.ts",
+    "./package.json": "./package.json",
+    "./react": "./src/react/index.ts",
     "./s3": "./src/s3/index.ts",
-    "./package.json": "./package.json"
+    "./server": "./src/server/index.ts"
   },
   "scripts": {
     "clean": "rm -rf node_modules coverage",
@@ -20,6 +22,7 @@
     "typecheck": "tsc --noEmit"
   },
   "peerDependencies": {
+    "@12-apps/wiring": ">=1.9.0",
     "@aws-sdk/client-s3": ">=3.700.0",
     "hono": ">=4.0.0",
     "react": ">=19.0.0",
@@ -40,12 +43,13 @@
     }
   },
   "dependencies": {
-    "@12-apps/ui": "^6.1.0",
+    "@12-apps/ui": "^6.3.1",
     "zod": "^4.3.5"
   },
   "devDependencies": {
     "@12-apps/eslint-config": "^1.21.1",
     "@12-apps/typescript-config": "^1.20.1",
+    "@12-apps/wiring": "^1.10.0",
     "@aws-sdk/client-s3": "^3.703.0",
     "@testing-library/react": "^16.1.0",
     "@types/react": "19.2.2",

package/src/hono/index.ts

@@ -38,8 +38,13 @@ export type ResolveStorageActor = (
 
 export interface StorageHonoConfig extends ApiStorageConfig {
   resolveActor: ResolveStorageActor;
-  /** 401 body message. pt-BR by default, like every other refusal here. */
-  unauthenticatedMessage?: string;
+  /**
+   * The 401 body's sentence when `resolveActor` answers null — REQUIRED, the
+   * host's words (pt-BR hosts: `PT_BR_STORAGE_UNAUTHENTICATED` from
+   * `../pt-BR`). The old default was the same silent leak every other surface
+   * here just paid down.
+   */
+  unauthenticatedMessage: string;
 }
 
 export interface StorageHono extends ApiStorage {
@@ -67,7 +72,7 @@ function send(c: Context, response: StorageRouteResponse): Response {
 export function storageRouter(config: StorageHonoConfig): StorageHono {
   const { resolveActor, unauthenticatedMessage, ...apiConfig } = config;
   const api = createApiStorage(apiConfig);
-  const unauthenticated = unauthenticatedMessage ?? 'Não autenticado.';
+  const unauthenticated = unauthenticatedMessage;
   const router = new Hono();
 
   for (const route of api.routes) {

package/src/index.ts

@@ -70,12 +70,12 @@ export {
   STORAGE_PROBLEM_STATUS,
   StorageNotConfiguredError,
   StorageProblemError,
-  defaultStorageMessages,
   isStorageProblem,
   type StorageMessageContext,
   type StorageMessages,
   type StorageProblem,
 } from './problems';
+export { PT_BR_STORAGE_MESSAGES, PT_BR_STORAGE_UNAUTHENTICATED } from './pt-BR';
 
 export {
   imageSources,

package/src/manifest/index.ts

@@ -0,0 +1,34 @@
+/**
+ * `@12-apps/storage/manifest` — the SHARED wiring manifest.
+ *
+ * Identity and the runtime inventory. Three absences are deliberate rather
+ * than unfinished:
+ *
+ * - **No `db`.** This package owns no table. What an uploaded object leaves
+ *   behind is a KEY, and the row that key hangs off is the host's own — a
+ *   product image, a store logo — so there is nothing here to compose.
+ * - **No `env`.** `./server`'s own header states the rule this manifest would
+ *   otherwise have to restate: there are no `process.env` reads in shipped
+ *   source, because every deployment-shaped decision (the driver, the byte
+ *   ceiling, the key prefix, the bucket) is an ARGUMENT. A package that reads
+ *   the environment decides for its host; this one asks.
+ * - **No `web` inventory.** The React half is components a host renders, not
+ *   a mountable surface with its own routes.
+ *
+ * `observability` is mandatory here because `http` is: a refused upload or a
+ * driver that could not be reached files under `storage` rather than under
+ * whichever host happened to mount it.
+ *
+ * `@12-apps/wiring` is a TYPE-ONLY devDependency (the report-builder move):
+ * the manifests are plain `satisfies`-checked values, and the producer
+ * factories' runtime assertions run in this package's own test suite.
+ */
+
+import type { PackageManifest } from '@12-apps/wiring';
+
+export const storageManifest = {
+  name: '@12-apps/storage',
+  contract: 1,
+  observability: { namespace: 'storage' },
+  server: ['http'],
+} as const satisfies PackageManifest;

package/src/manifest/server.ts

@@ -0,0 +1,95 @@
+/**
+ * `@12-apps/storage/manifest/server` — the server capabilities.
+ *
+ * `http.create` wraps `createApiStorage` in a WIRE VIEW that finally makes the
+ * response rendering the PACKAGE's. `StorageRouteResponse` is a three-way
+ * union — a JSON answer, an object's bytes, or a redirect to where the object
+ * lives — and until now every host turned those three arms into a `Response`
+ * itself. That is mechanism, identical for every host, and one arm of it is
+ * a security detail rather than a formatting one:
+ *
+ *     const body = response.bytes.slice().buffer;
+ *
+ * The `.slice()` is load-bearing. A `Uint8Array` from Node is a view over a
+ * POOLED allocation, so handing `.buffer` straight to `Response` serves the
+ * client whatever else happens to share that pool. A host that re-derives this
+ * renderer has to know that; a host that binds this manifest does not.
+ *
+ * The bytes and redirect arms therefore answer the contract's RAW half
+ * (`{ response }`), which wiring 1.9.0 added for exactly this: answers
+ * `{ status, body }` cannot express — a stream, a redirect whose headers are
+ * the payload, bytes with their own content type.
+ */
+
+import type { AnyServerManifest, WireRequest, WireRouteAnswer } from '@12-apps/wiring';
+
+import {
+  createApiStorage,
+  type ApiStorage,
+  type ApiStorageConfig,
+  type StorageRoute,
+  type StorageRouteResponse,
+} from '../server';
+
+/** The descriptor's chosen answer, as the wiring contract carries it. */
+export function asWireAnswer(response: StorageRouteResponse): WireRouteAnswer {
+  if ('redirect' in response) {
+    return { response: Response.redirect(response.redirect, 302) };
+  }
+  if ('bytes' in response) {
+    // Its OWN ArrayBuffer — see the note above; a view over the pool leaks.
+    const body = response.bytes.slice().buffer as ArrayBuffer;
+    return {
+      response: new Response(body, {
+        status: response.status,
+        headers: {
+          ...response.headers,
+          'content-length': String(response.bytes.byteLength),
+        },
+      }),
+    };
+  }
+  return { status: response.status, body: response.body };
+}
+
+/** One `StorageRoute` as the wiring contract reads it. */
+function asWireRoute(route: StorageRoute): {
+  method: StorageRoute['method'];
+  path: string;
+  kind: 'authenticated' | 'public';
+  handle(request: WireRequest): Promise<WireRouteAnswer>;
+} {
+  return {
+    method: route.method,
+    path: route.path,
+    // The descriptor's own `auth` flag IS the contract's route kind: a
+    // `public` object read is anonymous by design, and the host's gates read
+    // this rather than a second table that could disagree with it.
+    kind: route.auth === 'public' ? 'public' : 'authenticated',
+    handle: async (request) => {
+      if (!request.request) {
+        throw new Error('@12-apps/storage needs the raw request — bind an adapter that forwards it.');
+      }
+      return asWireAnswer(
+        await route.handle({
+          actor: (request.actor ?? null) as Parameters<StorageRoute['handle']>[0]['actor'],
+          params: request.params,
+          request: request.request,
+        }),
+      );
+    },
+  };
+}
+
+/** `createApiStorage`, its routes re-shaped for the aggregate. */
+export function createWireApiStorage(
+  config: ApiStorageConfig,
+): Omit<ApiStorage, 'routes'> & { routes: ReturnType<typeof asWireRoute>[] } {
+  const api = createApiStorage(config);
+  return { ...api, routes: api.routes.map(asWireRoute) };
+}
+
+export const storageServerManifest = {
+  name: '@12-apps/storage',
+  http: { create: createWireApiStorage },
+} as const satisfies AnyServerManifest;

package/src/problems.ts

@@ -56,29 +56,6 @@ export interface StorageMessageContext {
   limit: string;
 }
 
-/**
- * The default pt-BR copy. `limit` is interpolated rather than hard-coded so a
- * host that raises `maxBytes` cannot end up with a message naming the old
- * number — the single commonest way this kind of copy goes stale.
- */
-export function defaultStorageMessages(context: StorageMessageContext): StorageMessages {
-  return {
-    invalid_base64: 'A imagem enviada não está codificada corretamente em base64.',
-    empty_file: 'A imagem enviada está vazia.',
-    file_too_large: `A imagem enviada é maior que o limite de ${context.limit}.`,
-    content_mismatch:
-      'O conteúdo da imagem não corresponde ao formato informado. Envie um PNG, JPEG, WebP ou GIF.',
-    unsupported_content_type: 'Formato não suportado. Envie PNG, JPG, WebP ou GIF.',
-    image_unreadable:
-      'Não foi possível ler a imagem enviada — o arquivo parece estar corrompido.',
-    image_dimensions_too_large:
-      'A imagem enviada tem dimensões grandes demais para ser processada.',
-    storage_not_configured: 'O armazenamento de imagens ainda não foi configurado nesta loja.',
-    storage_unavailable:
-      'Não foi possível salvar a imagem agora. Tente novamente em instantes.',
-  };
-}
-
 /**
  * A refusal, carrying the status and the finished sentence.
  *

package/src/pt-BR.ts

@@ -0,0 +1,30 @@
+import type { StorageMessageContext, StorageMessages } from './problems';
+
+/**
+ * The pt-BR pack — a NAMED factory a host passes by hand
+ * (`messages: PT_BR_STORAGE_MESSAGES`), never a default. The filename is what
+ * exempts this file from the copy-portability gate: Portuguese may ship, it
+ * may not be silent. `limit` is interpolated rather than hard-coded so a
+ * host that raises `maxBytes` cannot end up with a message naming the old
+ * number — the single commonest way this kind of copy goes stale.
+ */
+export function PT_BR_STORAGE_MESSAGES(context: StorageMessageContext): StorageMessages {
+  return {
+    invalid_base64: 'A imagem enviada não está codificada corretamente em base64.',
+    empty_file: 'A imagem enviada está vazia.',
+    file_too_large: `A imagem enviada é maior que o limite de ${context.limit}.`,
+    content_mismatch:
+      'O conteúdo da imagem não corresponde ao formato informado. Envie um PNG, JPEG, WebP ou GIF.',
+    unsupported_content_type: 'Formato não suportado. Envie PNG, JPG, WebP ou GIF.',
+    image_unreadable:
+      'Não foi possível ler a imagem enviada — o arquivo parece estar corrompido.',
+    image_dimensions_too_large:
+      'A imagem enviada tem dimensões grandes demais para ser processada.',
+    storage_not_configured: 'O armazenamento de imagens ainda não foi configurado nesta loja.',
+    storage_unavailable:
+      'Não foi possível salvar a imagem agora. Tente novamente em instantes.',
+  };
+}
+
+/** The 401 the mounted router answers when the host resolves no actor. */
+export const PT_BR_STORAGE_UNAUTHENTICATED = 'Não autenticado.';

package/src/react/create-web-storage.tsx

@@ -4,7 +4,7 @@ import { Stack } from '@12-apps/ui/mui/Stack';
 import { Text } from '@12-apps/ui/typography/Text';
 
 import { DEFAULT_MAX_UPLOAD_BYTES, megabytes } from '../limits';
-import type { WebStorageMessages } from './failures';
+import type { WebStorageMessageContext, WebStorageMessages } from './failures';
 import { ImageField, type ImageFieldProps } from './image-field';
 import type { ImageProfile } from './optimize-image';
 import { useUpload, type UploadState, type UseUploadConfig } from './use-upload';
@@ -33,13 +33,14 @@ export interface WebStorageConfig {
   /** How requests are made. Default: same-origin `fetch`. */
   fetchImpl?: typeof fetch;
   /**
-   * pt-BR refusal copy overrides, mirroring the server mount's `messages`.
-   *
-   * Override `forbidden` to name YOUR reason: the package states only that the
-   * account may not upload, because `mayUpload` is one host-computed boolean and a
-   * package that named a role model would be wrong for every host but the first.
+   * Every sentence this surface renders — REQUIRED, the host's own factory of
+   * the mount's ceiling, mirroring the server mount's `messages` (pt-BR
+   * hosts: `PT_BR_WEB_STORAGE_MESSAGES` from `./pt-BR`). Write `forbidden` to
+   * name YOUR reason: the package states only that the account may not
+   * upload, because `mayUpload` is one host-computed boolean and a package
+   * that named a role model would be wrong for every host but the first.
    */
-  messages?: Partial<WebStorageMessages>;
+  messages: (context: WebStorageMessageContext) => WebStorageMessages;
 }
 
 export interface WebStorage {
@@ -60,7 +61,7 @@ export function createWebStorage(config: WebStorageConfig): WebStorage {
     maxBytes,
     ...(config.profile ? { profile: config.profile } : {}),
     ...(config.fetchImpl ? { fetchImpl: config.fetchImpl } : {}),
-    ...(config.messages ? { messages: config.messages } : {}),
+    messages: config.messages,
   };
   const useBoundUpload = (): UploadState => useUpload(uploadConfig);
 
@@ -75,17 +76,16 @@ export function createWebStorage(config: WebStorageConfig): WebStorage {
    */
   function UploadPage(): JSX.Element {
     const [imageKey, setImageKey] = useState<string | null>(null);
+    const messages = config.messages({ limit: megabytes(maxBytes) });
     return (
       <Stack spacing={2} data-testid="storage-upload-page">
-        <Text as="h2">Imagens da loja</Text>
-        <Text as="p">
-          {`Envie um PNG, JPG, WebP ou GIF de até ${megabytes(maxBytes)}.`}
-        </Text>
+        <Text as="h2">{messages.pageTitle}</Text>
+        <Text as="p">{messages.pageIntro}</Text>
         <BoundImageField
           value={imageKey}
           onChange={setImageKey}
-          label="Foto do produto"
-          helperText="A imagem é reduzida no navegador antes do envio."
+          label={messages.fieldLabel}
+          helperText={messages.fieldHelper}
         />
       </Stack>
     );

package/src/react/failures.ts

@@ -88,8 +88,25 @@ export interface WebStorageMessages {
   unsupported_content_type_upfront: (context: { contentType: string }) => string;
   /** 2xx with no key in the body — accepted, and unusable. */
   missing_key: string;
+  /**
+   * A refusal whose body carried no sentence and no code this table knows —
+   * the status (and the raw code, when there was one) ride along, because
+   * they are what turns "it failed" into something greppable.
+   */
+  upload_failed_http: (context: { status: number; detail: string }) => string;
   /** Anything thrown on the way. The last resort, and it says so. */
   upload_failed: string;
+
+  /**
+   * The standalone upload page's own chrome — heading, the one-line
+   * instruction (which carries the ceiling, same rule as the refusals), the
+   * field label and its helper. These rendered as literals inside
+   * `createWebStorage` until copy became required config.
+   */
+  pageTitle: string;
+  pageIntro: string;
+  fieldLabel: string;
+  fieldHelper: string;
 }
 
 /** Copy that only makes sense with the configured ceiling in it. */
@@ -98,34 +115,6 @@ export interface WebStorageMessageContext {
   limit: string;
 }
 
-/**
- * The default pt-BR copy. `limit` is interpolated rather than hard-coded for the
- * same reason the server does it: a host that raises the ceiling must not end up
- * with a message naming the old number.
- */
-export function defaultWebStorageMessages(
-  context: WebStorageMessageContext,
-): WebStorageMessages {
-  return {
-    forbidden: 'Sua conta não tem permissão para enviar imagens nesta loja.',
-    unsupported_content_type: 'Formato não suportado. Envie PNG, JPG, WebP ou GIF.',
-    file_too_large: `Imagem muito grande. O limite é ${context.limit}.`,
-    invalid_key: 'Não foi possível localizar essa imagem.',
-    not_found: 'Essa imagem não está mais disponível.',
-    session_expired: 'Sua sessão expirou. Entre novamente e repita o envio.',
-    transport: 'Não foi possível falar com o servidor. Verifique sua conexão e tente de novo.',
-    empty_file: 'Arquivo vazio (0 bytes). Escolha a imagem novamente.',
-    file_too_large_upfront: ({ size, limit }) =>
-      `Imagem muito grande: ${size}. O limite é ${limit} — reduza a imagem e tente de novo.`,
-    unknown_content_type:
-      'Não foi possível identificar o tipo do arquivo. Envie um PNG, JPG ou WebP.',
-    unsupported_content_type_upfront: ({ contentType }) =>
-      `Formato não suportado (${contentType}). Envie PNG, JPG, WebP ou GIF.`,
-    missing_key: 'O servidor aceitou a imagem mas não devolveu a chave. Tente de novo.',
-    upload_failed: 'Falha ao enviar a imagem. Tente de novo em instantes.',
-  };
-}
-
 /**
  * The messages in force for a mount's ceiling.
  *
@@ -135,9 +124,9 @@ export function defaultWebStorageMessages(
  */
 export function messagesOf(
   maxBytes: number,
-  overrides?: Partial<WebStorageMessages>,
+  factory: (context: WebStorageMessageContext) => WebStorageMessages,
 ): WebStorageMessages {
-  return { ...defaultWebStorageMessages({ limit: megabytes(maxBytes) }), ...overrides };
+  return factory({ limit: megabytes(maxBytes) });
 }
 
 const resolve = messagesOf;
@@ -173,9 +162,9 @@ function sentenceFor(messages: WebStorageMessages, code: string): string | undef
 export function rejectFileUpfront(
   file: File,
   maxBytes: number,
-  overrides?: Partial<WebStorageMessages>,
+  factory: (context: WebStorageMessageContext) => WebStorageMessages,
 ): string | null {
-  const messages = resolve(maxBytes, overrides);
+  const messages = resolve(maxBytes, factory);
   if (file.size === 0) {
     return messages.empty_file;
   }
@@ -230,9 +219,9 @@ async function statedError(response: Response): Promise<string | null> {
 export async function uploadFailure(
   response: Response,
   maxBytes: number,
-  overrides?: Partial<WebStorageMessages>,
+  factory: (context: WebStorageMessageContext) => WebStorageMessages,
 ): Promise<string> {
-  const messages = resolve(maxBytes, overrides);
+  const messages = resolve(maxBytes, factory);
   if (response.status === 401) return messages.session_expired;
   const stated = await statedError(response);
   // A sentence rather than a code: the server already phrased it for the owner,
@@ -245,7 +234,7 @@ export async function uploadFailure(
   // what turns a support request from "it failed" into something greppable — so it
   // rides along with the status rather than being mapped away.
   const detail = stated ? ` (${stated})` : '';
-  return `Não foi possível enviar a imagem (HTTP ${response.status}${detail}). Tente de novo em instantes.`;
+  return messages.upload_failed_http({ status: response.status, detail });
 }
 
 /**
@@ -254,8 +243,10 @@ export async function uploadFailure(
  * One sentence, and it can afford to be definite: the upload goes to our own
  * origin, so there is no cross-origin case to hedge about.
  */
-export function transportFailure(overrides?: Partial<WebStorageMessages>): string {
-  // No ceiling to interpolate on this one, so it is read without a limit rather
-  // than through a table built from a number that would be a lie.
-  return overrides?.transport ?? defaultWebStorageMessages({ limit: '' }).transport;
+export function transportFailure(
+  factory: (context: WebStorageMessageContext) => WebStorageMessages,
+): string {
+  // No ceiling to interpolate on this one, so the factory is read without a
+  // limit rather than through a table built from a number that would be a lie.
+  return factory({ limit: '' }).transport;
 }

package/src/react/index.ts

@@ -35,10 +35,10 @@ export {
 } from './optimize-image';
 
 export {
-  defaultWebStorageMessages,
   rejectFileUpfront,
   transportFailure,
   uploadFailure,
   type WebStorageMessageContext,
   type WebStorageMessages,
 } from './failures';
+export { PT_BR_WEB_STORAGE_MESSAGES } from './pt-BR';

package/src/react/pt-BR.ts

@@ -0,0 +1,38 @@
+import type { WebStorageMessageContext, WebStorageMessages } from './failures';
+
+/**
+ * The pt-BR pack — a NAMED factory a host passes by hand, never a default.
+ * `limit` is interpolated rather than hard-coded for the same reason the
+ * server pack does it: a host that raises the ceiling must not end up with
+ * copy naming the old number. The filename is what exempts this file from
+ * the copy-portability gate: Portuguese may ship, it may not be silent.
+ */
+export function PT_BR_WEB_STORAGE_MESSAGES(
+  context: WebStorageMessageContext,
+): WebStorageMessages {
+  return {
+    forbidden: 'Sua conta não tem permissão para enviar imagens nesta loja.',
+    unsupported_content_type: 'Formato não suportado. Envie PNG, JPG, WebP ou GIF.',
+    file_too_large: `Imagem muito grande. O limite é ${context.limit}.`,
+    invalid_key: 'Não foi possível localizar essa imagem.',
+    not_found: 'Essa imagem não está mais disponível.',
+    session_expired: 'Sua sessão expirou. Entre novamente e repita o envio.',
+    transport: 'Não foi possível falar com o servidor. Verifique sua conexão e tente de novo.',
+    empty_file: 'Arquivo vazio (0 bytes). Escolha a imagem novamente.',
+    file_too_large_upfront: ({ size, limit }) =>
+      `Imagem muito grande: ${size}. O limite é ${limit} — reduza a imagem e tente de novo.`,
+    unknown_content_type:
+      'Não foi possível identificar o tipo do arquivo. Envie um PNG, JPG ou WebP.',
+    unsupported_content_type_upfront: ({ contentType }) =>
+      `Formato não suportado (${contentType}). Envie PNG, JPG, WebP ou GIF.`,
+    missing_key: 'O servidor aceitou a imagem mas não devolveu a chave. Tente de novo.',
+    upload_failed_http: ({ status, detail }) =>
+      `Não foi possível enviar a imagem (HTTP ${status}${detail}). Tente de novo em instantes.`,
+    upload_failed: 'Falha ao enviar a imagem. Tente de novo em instantes.',
+
+    pageTitle: 'Imagens da loja',
+    pageIntro: `Envie um PNG, JPG, WebP ou GIF de até ${context.limit}.`,
+    fieldLabel: 'Foto do produto',
+    fieldHelper: 'A imagem é reduzida no navegador antes do envio.',
+  };
+}

package/src/react/use-upload.ts

@@ -6,6 +6,7 @@ import {
   rejectFileUpfront,
   transportFailure,
   uploadFailure,
+  type WebStorageMessageContext,
   type WebStorageMessages,
 } from './failures';
 import { optimizeImage, type ImageProfile } from './optimize-image';
@@ -56,8 +57,11 @@ export interface UseUploadConfig {
   profile?: ImageProfile;
   /** How the request is made. Default: same-origin `fetch`. */
   fetchImpl?: typeof fetch;
-  /** pt-BR refusal copy overrides, for the codes only the host can explain. */
-  messages?: Partial<WebStorageMessages>;
+  /**
+   * The refusal copy, as the host's own factory of the mount's ceiling —
+   * REQUIRED (pt-BR hosts: `PT_BR_WEB_STORAGE_MESSAGES` from `./pt-BR`).
+   */
+  messages: (context: WebStorageMessageContext) => WebStorageMessages;
 }
 
 export function useUpload(config: UseUploadConfig): UploadState {

package/src/server/create-api-storage.ts

@@ -1,7 +1,7 @@
 import { ACCEPTED_CONTENT_TYPES } from '../content-types';
 import { DEFAULT_KEY_PREFIX } from '../keys';
 import { megabytes } from '../limits';
-import { defaultStorageMessages, type StorageMessages } from '../problems';
+import type { StorageMessageContext, StorageMessages } from '../problems';
 import { CATALOG_RENDITIONS, type RenditionSpec } from '../renditions';
 import { imageSources, objectUrl, versionedObjectUrl, type ImageSources } from '../urls';
 import { inlineImageSchema, objectKeySchema, type InlineImage } from '../wire';
@@ -94,8 +94,13 @@ export interface ApiStorageConfig {
   renditions?: readonly RenditionSpec[];
   /** Top-level key segment. Default `products`. */
   keyPrefix?: string;
-  /** pt-BR refusal copy overrides. */
-  messages?: Partial<StorageMessages>;
+  /**
+   * The sentence each refusal is stated in — REQUIRED, the host's words. A
+   * factory of the mount's own context so a host that raises `maxBytes`
+   * cannot end up with copy naming the old ceiling. pt-BR hosts pass
+   * `PT_BR_STORAGE_MESSAGES` from `../pt-BR`.
+   */
+  messages: (context: StorageMessageContext) => StorageMessages;
 }
 
 /** What the mount reports about itself — the anti-drift surface. */
@@ -167,10 +172,7 @@ const SILENT: StorageLogger = { error: () => undefined };
 export function createApiStorage(config: ApiStorageConfig): ApiStorage {
   const specs = config.renditions ?? CATALOG_RENDITIONS;
   const keyPrefix = config.keyPrefix ?? DEFAULT_KEY_PREFIX;
-  const messages: StorageMessages = {
-    ...defaultStorageMessages({ limit: megabytes(config.maxBytes) }),
-    ...config.messages,
-  };
+  const messages: StorageMessages = config.messages({ limit: megabytes(config.maxBytes) });
   const writeDeps: StoreImageDeps = {
     driver: config.driver,
     pipeline: config.imagePipeline,