@12-apps/storage 1.0.0

package/src/payload.ts

@@ -0,0 +1,127 @@
+import { isAcceptedContentType } from './content-types';
+import type { StorageProblem } from './problems';
+
+/**
+ * Proving that some bytes really are an image of the type they claim, and
+ * decoding the base64 form of them.
+ *
+ * A browser POSTs its bytes as a request stream; an agent cannot make an
+ * arbitrary HTTP request at all — it calls tools, with JSON arguments — so its
+ * bytes travel base64 inside the write that uses them. That second form needs
+ * three checks the stream gets from its transport for free:
+ *
+ *   - the SIZE cap has to hold against the ENCODED length, before decoding, or a
+ *     30 MB string is allocated twice over just to be rejected;
+ *   - the encoding may be malformed, and `Buffer.from(…, 'base64')` silently
+ *     discards what it does not recognise — so a typo'd payload would otherwise
+ *     be stored as a truncated, unopenable image;
+ *   - the declared `contentType` is the only thing naming the format, and it
+ *     decides both the stored extension AND the type the object is served back
+ *     with.
+ *
+ * That last check is what keeps an upload surface from being a way to park
+ * arbitrary content at a world-readable URL on the store's own domain: bytes
+ * that are not one of the accepted formats are refused whatever they claim to
+ * be. It runs on BOTH entrances — the decode does it as part of decoding, and
+ * the streaming path does it on the bytes it read — because neither may be the
+ * one that forgets.
+ */
+
+/** `data:image/png;base64,` — an agent is as likely to send this as bare base64. */
+const DATA_URL_PREFIX = /^data:[\w.+-]+\/[\w.+-]+(;[\w.+-]+=[\w.+-]+)*;base64,/i;
+
+/** Standard base64 alphabet with at most the two padding characters. */
+const BASE64 = /^[A-Za-z0-9+/]+={0,2}$/;
+
+function startsWith(bytes: Uint8Array, signature: readonly number[], offset = 0): boolean {
+  return signature.every((byte, index) => bytes[offset + index] === byte);
+}
+
+/**
+ * The MIME type the BYTES themselves declare, by magic number — `undefined` for
+ * anything that is not one of the accepted formats.
+ */
+export function sniffImageContentType(bytes: Uint8Array): string | undefined {
+  if (startsWith(bytes, [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a])) return 'image/png';
+  if (startsWith(bytes, [0xff, 0xd8, 0xff])) return 'image/jpeg';
+  // "GIF8", covering both 87a and 89a.
+  if (startsWith(bytes, [0x47, 0x49, 0x46, 0x38])) return 'image/gif';
+  // "RIFF" …4-byte length… "WEBP".
+  if (
+    startsWith(bytes, [0x52, 0x49, 0x46, 0x46]) &&
+    startsWith(bytes, [0x57, 0x45, 0x42, 0x50], 8)
+  ) {
+    return 'image/webp';
+  }
+  return undefined;
+}
+
+/**
+ * Do `bytes` really carry an image of `contentType`? `null` when they agree.
+ *
+ * In one place because both entrances need it, and one of them has nothing else
+ * corroborating the claim: there is no file dialog upstream of a tool call.
+ */
+export function verifyImageBytes(
+  bytes: Uint8Array,
+  contentType: string,
+): StorageProblem | null {
+  if (bytes.byteLength === 0) return 'empty_file';
+  if (!isAcceptedContentType(contentType)) return 'unsupported_content_type';
+  return sniffImageContentType(bytes) === contentType ? null : 'content_mismatch';
+}
+
+export type DecodedPayload =
+  | { ok: true; bytes: Uint8Array }
+  | { ok: false; problem: StorageProblem };
+
+/**
+ * Bytes a padded base64 string decodes to, EXACTLY — every 4 characters carry 3
+ * bytes, less the 1 or 2 the padding stands in for.
+ *
+ * The approximation without that correction over-counts by up to two bytes,
+ * which is invisible everywhere except at the cap, where it refuses a file of
+ * exactly the documented maximum.
+ */
+function decodedLength(encoded: string): number {
+  let padding = 0;
+  if (encoded.endsWith('=')) padding = encoded.endsWith('==') ? 2 : 1;
+  return (encoded.length / 4) * 3 - padding;
+}
+
+/**
+ * Strip the data-URL wrapper and any whitespace, then restore padding a caller
+ * dropped (unpadded base64 is common and unambiguous).
+ *
+ * A length one more than a multiple of 4 pads to three `=`, which the alphabet
+ * check then rejects — correctly, since no base64 string has that length.
+ */
+function normalize(input: string): string {
+  const encoded = input.replace(DATA_URL_PREFIX, '').replace(/\s+/g, '');
+  const remainder = encoded.length % 4;
+  return remainder === 0 ? encoded : encoded.padEnd(encoded.length + (4 - remainder), '=');
+}
+
+/**
+ * Decode `input` and prove it really is an image of `contentType`.
+ *
+ * `maxBytes` is judged on the ENCODED length first, so an oversize payload is
+ * never decoded at all.
+ */
+export function decodeImagePayload(
+  input: string,
+  contentType: string,
+  maxBytes: number,
+): DecodedPayload {
+  const encoded = normalize(input);
+  if (encoded.length === 0) return { ok: false, problem: 'empty_file' };
+  if (!BASE64.test(encoded)) return { ok: false, problem: 'invalid_base64' };
+  if (decodedLength(encoded) > maxBytes) return { ok: false, problem: 'file_too_large' };
+
+  // Copied out of Node's Buffer pool so the stored bytes are a standalone
+  // Uint8Array rather than a view into a shared allocation.
+  const bytes = new Uint8Array(Buffer.from(encoded, 'base64'));
+  if (bytes.byteLength === 0) return { ok: false, problem: 'empty_file' };
+  const mismatch = verifyImageBytes(bytes, contentType);
+  return mismatch ? { ok: false, problem: mismatch } : { ok: true, bytes };
+}

package/src/problems.ts

@@ -0,0 +1,116 @@
+/**
+ * Why an upload was refused, the status that describes it, and the sentence the
+ * person uploading reads.
+ *
+ * ONE table for all of it, because the same refusal has to serve two entrances:
+ * a browser POSTing bytes and a host write carrying them base64 in its body (an
+ * agent's only option — a tool call is JSON). Two tables would let the two
+ * entrances tell one store owner two different things about one file.
+ *
+ * The messages are pt-BR because they reach a Brazilian store owner, directly
+ * or relayed by an agent. They are product copy, not developer strings: a host
+ * with another audience passes `messages` to the mount rather than translating
+ * the package.
+ */
+
+/** Everything an upload can be refused for, across both entrances. */
+export type StorageProblem =
+  /** The base64 field is not base64. */
+  | 'invalid_base64'
+  /** Zero bytes arrived. */
+  | 'empty_file'
+  /** Over the configured `maxBytes`. */
+  | 'file_too_large'
+  /** The bytes' magic number contradicts the declared `Content-Type`. */
+  | 'content_mismatch'
+  /** A `Content-Type` outside the accepted formats. */
+  | 'unsupported_content_type'
+  /** The pipeline could not decode the bytes. */
+  | 'image_unreadable'
+  /** Decoding would allocate more than the pipeline's pixel ceiling. */
+  | 'image_dimensions_too_large'
+  /** No driver could store the bytes — an operator problem, not the caller's. */
+  | 'storage_not_configured'
+  /** The driver refused for any other reason. */
+  | 'storage_unavailable';
+
+/** The HTTP status each refusal answers with. */
+export const STORAGE_PROBLEM_STATUS: Readonly<Record<StorageProblem, number>> = {
+  invalid_base64: 400,
+  empty_file: 400,
+  content_mismatch: 400,
+  unsupported_content_type: 400,
+  image_unreadable: 400,
+  file_too_large: 413,
+  image_dimensions_too_large: 413,
+  storage_not_configured: 503,
+  storage_unavailable: 502,
+};
+
+/** The sentence each refusal is stated in. */
+export type StorageMessages = Readonly<Record<StorageProblem, string>>;
+
+/** Copy that only makes sense with the configured ceiling in it. */
+export interface StorageMessageContext {
+  /** `8 MB`, already formatted. */
+  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.
+ *
+ * Thrown by the write path so a host write (`createProduct` with bytes in the
+ * body) fails with a usable status instead of creating a row whose photo is
+ * silently missing — the same status and the same sentence the endpoint answers.
+ */
+export class StorageProblemError extends Error {
+  readonly problem: StorageProblem;
+  readonly status: number;
+
+  constructor(problem: StorageProblem, message: string) {
+    super(message);
+    this.name = 'StorageProblemError';
+    this.problem = problem;
+    this.status = STORAGE_PROBLEM_STATUS[problem];
+  }
+}
+
+/** Is `error` one of this package's refusals? */
+export function isStorageProblem(error: unknown): error is StorageProblemError {
+  return error instanceof StorageProblemError;
+}
+
+/**
+ * Missing configuration is an OPERATOR problem, not a runtime bug — a driver
+ * raises this and the write path maps it to the 503 an admin UI can explain,
+ * rather than to the generic "try again" a bucket timeout gets.
+ */
+export class StorageNotConfiguredError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'StorageNotConfiguredError';
+  }
+}

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

@@ -0,0 +1,100 @@
+import { useState, type ComponentType, type JSX } from 'react';
+
+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 { ImageField, type ImageFieldProps } from './image-field';
+import type { ImageProfile } from './optimize-image';
+import { useUpload, type UploadState, type UseUploadConfig } from './use-upload';
+
+/**
+ * The one thing this package exposes to a FRONTEND host.
+ *
+ * Everything the upload IS lives inside: the browser-side re-encode, the upfront
+ * refusals, the single same-origin POST, the failure vocabulary, the picker and its
+ * preview. The host names where the API is mounted, and that is the whole wiring.
+ *
+ * `maxBytes` defaults to {@link DEFAULT_MAX_UPLOAD_BYTES} — the same constant the
+ * backend mount is meant to be given — so the two agree by construction unless a
+ * host deliberately diverges. It is only an EARLY refusal in any case: the server
+ * is the authority, and the copy the browser shows is generated from whatever
+ * number it was handed, so it cannot claim a limit it is not applying.
+ */
+
+export interface WebStorageConfig {
+  /** Where the router is mounted, e.g. `/api`. */
+  apiBase: string;
+  /** The ceiling the server enforces. Default {@link DEFAULT_MAX_UPLOAD_BYTES}. */
+  maxBytes?: number;
+  /** The browser-side re-encode profile. */
+  profile?: ImageProfile;
+  /** 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.
+   */
+  messages?: Partial<WebStorageMessages>;
+}
+
+export interface WebStorage {
+  /** A standalone upload surface — the whole thing, ready to render. */
+  page: ComponentType;
+  /** The field a form drops in: picker, preview, refusal, and a key out. */
+  ImageField: ComponentType<ImageFieldProps>;
+  /** The primitive, for a host composing its own affordance. */
+  useUpload: () => UploadState;
+  /** What this surface enforces before a request leaves the browser. */
+  limits: { maxBytes: number; maxBytesLabel: string };
+}
+
+export function createWebStorage(config: WebStorageConfig): WebStorage {
+  const maxBytes = config.maxBytes ?? DEFAULT_MAX_UPLOAD_BYTES;
+  const uploadConfig: UseUploadConfig = {
+    apiBase: config.apiBase,
+    maxBytes,
+    ...(config.profile ? { profile: config.profile } : {}),
+    ...(config.fetchImpl ? { fetchImpl: config.fetchImpl } : {}),
+    ...(config.messages ? { messages: config.messages } : {}),
+  };
+  const useBoundUpload = (): UploadState => useUpload(uploadConfig);
+
+  function BoundImageField(props: ImageFieldProps): JSX.Element {
+    return <ImageField {...props} uploader={useBoundUpload()} />;
+  }
+
+  /**
+   * The standalone surface: pick a file, see the key it was stored under. It is
+   * what a host mounts to prove the wiring end to end, and what the consumer
+   * harness drives — the key on screen is the same string a form would save.
+   */
+  function UploadPage(): JSX.Element {
+    const [imageKey, setImageKey] = useState<string | null>(null);
+    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>
+        <BoundImageField
+          value={imageKey}
+          onChange={setImageKey}
+          label="Foto do produto"
+          helperText="A imagem é reduzida no navegador antes do envio."
+        />
+      </Stack>
+    );
+  }
+
+  return {
+    page: UploadPage,
+    ImageField: BoundImageField,
+    useUpload: useBoundUpload,
+    limits: { maxBytes, maxBytesLabel: megabytes(maxBytes) },
+  };
+}

package/src/react/failures.ts

@@ -0,0 +1,201 @@
+import { ACCEPTED_CONTENT_TYPES } from '../content-types';
+import { megabytes } from '../limits';
+
+/**
+ * Why an upload failed, in words the store owner can act on.
+ *
+ * Collapsing every cause into one "Falha ao enviar a imagem." is what made a
+ * failed upload unreportable: the owner saw a message that named no cause, could
+ * not tell a file they should shrink from a permission the operator had not
+ * granted, and had nothing to paste into a support request.
+ *
+ * The upload being a SINGLE same-origin POST is what let this shrink to one rule.
+ * A two-hop version had to explain a presign step, a signed grant that could age
+ * out, a bucket's own `<Code>` coming back to the browser, and — the honest but
+ * useless one — "rede ou CORS", because a blocked cross-origin PUT is deliberately
+ * indistinguishable from an offline network at the `fetch` layer. None of those
+ * can happen: the browser talks to our own origin, and the server is the only
+ * thing that talks to storage.
+ *
+ * What remains is one rule: **whatever the response DOES say is said out loud.**
+ *
+ * ## Why this table is overridable
+ *
+ * Every sentence here reaches a store owner, so it is product copy and it is
+ * pt-BR — but two of these refusals are decided by rules the PACKAGE does not
+ * know. `forbidden` is the sharp one: `mayUpload` is deliberately one host-computed
+ * boolean, and this file once answered it with *"é preciso ser OWNER ou ADMIN"* —
+ * naming a role model that belongs to one host. An adopter whose roles are
+ * `manager`/`staff`, or who gates on an `@12-apps/rbac` permission, would show an
+ * owner two role names that do not exist in their product, with no knob to change
+ * it. So the copy states the OUTCOME ("your account may not") and the host
+ * supplies the CAUSE if it wants one, through `messages` — the same escape hatch
+ * the server's refusals already have.
+ */
+
+/**
+ * The browser-side refusal copy, as one table a host may override.
+ *
+ * Mirrors the server's `StorageMessages` deliberately: same shape, same reason,
+ * so a host that overrides a sentence on one side can find the other.
+ *
+ * These are the refusals the browser has to phrase ITSELF — a bare code, or a
+ * status with no body at all. Anything the server states as a finished sentence is
+ * surfaced verbatim instead and never reaches this table (see {@link uploadFailure}).
+ */
+export interface WebStorageMessages {
+  /**
+   * 403. States the outcome only: the reason is the host's rule, and naming a
+   * role model here would be wrong for every host but the first.
+   */
+  forbidden: string;
+  unsupported_content_type: string;
+  /** Carries the ceiling, so a host overriding it states its own number. */
+  file_too_large: string;
+  invalid_key: string;
+  not_found: string;
+  /** 401 — the session went away between picking the file and sending it. */
+  session_expired: string;
+  /** `fetch` rejected outright; no response ever arrived. */
+  transport: string;
+}
+
+/** Copy that only makes sense with the configured ceiling in it. */
+export interface WebStorageMessageContext {
+  /** `8 MB`, already formatted. */
+  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.',
+  };
+}
+
+function resolve(
+  maxBytes: number,
+  overrides: Partial<WebStorageMessages> | undefined,
+): WebStorageMessages {
+  return { ...defaultWebStorageMessages({ limit: megabytes(maxBytes) }), ...overrides };
+}
+
+/**
+ * The sentence for a refusal CODE, or `undefined` for a code with no entry.
+ *
+ * An own-property check rather than a bare `in`: the code arrives from a response
+ * body, so `constructor` or `toString` would otherwise resolve through the
+ * prototype and be shown to a store owner as an explanation.
+ */
+function sentenceFor(messages: WebStorageMessages, code: string): string | undefined {
+  if (!Object.prototype.hasOwnProperty.call(messages, code)) return undefined;
+  return messages[code as keyof WebStorageMessages];
+}
+
+/**
+ * Refuse a file before any request leaves the browser, or `null` to proceed.
+ *
+ * Measured against the bytes that would ACTUALLY be sent, which is why it runs
+ * after `optimizeImage` and not before: a 12 MB phone photo is a perfectly good
+ * product image once it is 1280px of WebP, and refusing it against the cap first
+ * was sending owners off to find an image editor for a file we can fix here.
+ *
+ * An empty `file.type` means the OS could not identify the file at all (an
+ * extensionless drop, most often) — worth its own sentence, because "formato não
+ * suportado" reads as an accusation about a file the owner knows is a PNG.
+ */
+export function rejectFileUpfront(file: File, maxBytes: number): string | null {
+  if (file.size === 0) {
+    return 'Arquivo vazio (0 bytes). Escolha a imagem novamente.';
+  }
+  if (file.size > maxBytes) {
+    return `Imagem muito grande: ${megabytes(file.size)}. O limite é ${megabytes(
+      maxBytes,
+    )} — reduza a imagem e tente de novo.`;
+  }
+  if (file.type === '') {
+    return 'Não foi possível identificar o tipo do arquivo. Envie um PNG, JPG ou WebP.';
+  }
+  if (!ACCEPTED_CONTENT_TYPES.includes(file.type)) {
+    return `Formato não suportado (${file.type}). Envie PNG, JPG, WebP ou GIF.`;
+  }
+  return null;
+}
+
+/** The `error` field of a JSON refusal, or `null` when there isn't one. */
+async function statedError(response: Response): Promise<string | null> {
+  try {
+    const parsed: unknown = JSON.parse(await response.text());
+    if (parsed && typeof parsed === 'object' && 'error' in parsed) {
+      const error = (parsed as { error: unknown }).error;
+      return typeof error === 'string' ? error : null;
+    }
+    return null;
+  } catch {
+    // An unreadable or non-JSON body tells us nothing extra; the status still does.
+    return null;
+  }
+}
+
+/**
+ * Explain a refusal from the upload endpoint.
+ *
+ * **The server's own sentence wins.** Every refusal the mount can phrase — an
+ * unreadable file, a format that contradicts the bytes, a ceiling, an unsupported
+ * type, storage not configured — arrives as a finished pt-BR sentence built from
+ * the mount's OWN `maxBytes` and through the mount's OWN `messages` overrides.
+ * Those are surfaced verbatim rather than re-worded here, so the two entrances
+ * cannot drift into telling one store owner two different things about one file,
+ * and so a limit named on screen is the limit something enforces.
+ *
+ * That last point is why the table below is a FALLBACK and not the primary path.
+ * The endpoint used to answer `file_too_large` as a bare code, and the browser
+ * re-derived the number from its own default: a mount capped at 4 MB refusing a
+ * 6 MB file produced *"o limite é 8 MB"* — a ceiling nothing applied. The codes
+ * that remain are the ones no `StorageMessages` entry exists for (`forbidden`,
+ * `invalid_key`, `not_found`) plus any older mount still answering a code.
+ */
+export async function uploadFailure(
+  response: Response,
+  maxBytes: number,
+  overrides?: Partial<WebStorageMessages>,
+): Promise<string> {
+  const messages = resolve(maxBytes, overrides);
+  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,
+  // with its own number and its own overrides in it. Checked BEFORE the table so a
+  // mount that states a limit is never second-guessed by a local default.
+  if (stated && /\s/.test(stated)) return stated;
+  const known = stated ? sentenceFor(messages, stated) : undefined;
+  if (known) return known;
+  // An unrecognised CODE is still the most useful string in the response — it is
+  // 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.`;
+}
+
+/**
+ * `fetch` rejected outright — no response ever arrived.
+ *
+ * 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;
+}

package/src/react/image-field.tsx

@@ -0,0 +1,119 @@
+import { useState, type JSX } from 'react';
+
+import { Alert } from '@12-apps/ui/data-display/Alert';
+import { Box } from '@12-apps/ui/mui/Box';
+import { Stack } from '@12-apps/ui/mui/Stack';
+import { Text } from '@12-apps/ui/typography/Text';
+import { Button } from '@12-apps/ui/form/Button';
+import { UploadButton } from '@12-apps/ui/form/UploadButton';
+
+import { ACCEPTED_CONTENT_TYPES } from '../content-types';
+import type { UploadOptions, UploadState } from './use-upload';
+
+/**
+ * The picker, the preview and the refusal, as one field.
+ *
+ * `@12-apps/ui/form/UploadButton` is the presentation and this is the BINDING: it
+ * owns the three things a form gets wrong when it wires an upload by hand.
+ *
+ *   1. **The preview appears the moment the file is PICKED**, not when the upload
+ *      lands. An empty slot during the round-trip reads as "the click did nothing",
+ *      which is exactly how a swallowed storage 503 looked. A failure withdraws it
+ *      and `error` says why.
+ *   2. **A failed upload restores the previous preview.** Leaving the new one up
+ *      would show a photo that is not saved and will not be.
+ *   3. **The saved key is the only output.** A form folds `imageKey` into its save
+ *      payload; it never learns a URL, because only the server knows which driver
+ *      is running and where a CDN points.
+ */
+
+export interface ImageFieldProps {
+  /** The key already saved on the row, if any. */
+  value?: string | null;
+  /** A URL for the saved key — the server resolved it through the driver. */
+  previewUrl?: string | null;
+  /** Called with the new key, or `null` when the image is removed. */
+  onChange: (imageKey: string | null) => void;
+  label?: string;
+  helperText?: string;
+  /** Passed through per upload — `{ optimize: false }` for a rendered canvas. */
+  uploadOptions?: UploadOptions;
+  disabled?: boolean;
+  'data-testid'?: string;
+}
+
+/** {@link ImageFieldProps} plus the bound upload state the factory injects. */
+export interface BoundImageFieldProps extends ImageFieldProps {
+  uploader: UploadState;
+}
+
+const ACCEPT = ACCEPTED_CONTENT_TYPES.join(',');
+
+export function ImageField(props: BoundImageFieldProps): JSX.Element {
+  const { uploader } = props;
+  const [preview, setPreview] = useState<string | null>(props.previewUrl ?? null);
+  const testId = props['data-testid'] ?? 'storage-image-field';
+
+  async function handleSelect(file: File): Promise<void> {
+    const objectUrl = URL.createObjectURL(file);
+    const previous = preview;
+    setPreview(objectUrl);
+    const key = await uploader.upload(file, props.uploadOptions);
+    if (key) {
+      props.onChange(key);
+      return;
+    }
+    URL.revokeObjectURL(objectUrl);
+    setPreview(previous);
+  }
+
+  function handleRemove(): void {
+    setPreview(null);
+    uploader.clearError();
+    props.onChange(null);
+  }
+
+  return (
+    <Stack spacing={1} data-testid={testId}>
+      {preview ? (
+        <Box>
+          {/* A plain <img>: a package cannot assume a framework's image
+              component, and this preview is a local blob half the time. */}
+          <img
+            src={preview}
+            alt={props.label ?? 'Imagem'}
+            data-testid={`${testId}-preview`}
+            style={{ maxWidth: 160, maxHeight: 160, objectFit: 'contain' }}
+          />
+        </Box>
+      ) : null}
+      <UploadButton
+        variant="dropzone"
+        label={props.label ?? 'Enviar imagem'}
+        accept={ACCEPT}
+        disabled={props.disabled || uploader.uploading}
+        uploading={uploader.uploading}
+        helperText={props.helperText}
+        onSelect={(file) => void handleSelect(file)}
+        data-testid={`${testId}-picker`}
+      />
+      {preview ? (
+        <Box>
+          <Button variant="text" onClick={handleRemove} dataTestId={`${testId}-remove`}>
+            Remover imagem
+          </Button>
+        </Box>
+      ) : null}
+      {uploader.error ? (
+        <Alert variant="danger" data-testid={`${testId}-error`}>
+          {uploader.error}
+        </Alert>
+      ) : null}
+      {props.value ? (
+        <Text as="p" data-testid={`${testId}-key`}>
+          {props.value}
+        </Text>
+      ) : null}
+    </Stack>
+  );
+}