files

Imported from crbnos/carbon (packages/files/AGENTS.md). Install upstream with npx skills add crbnos/carbon --skill files. Copyright stays with the author.

@carbon/files

File handling, one subpath per file class. The goal is that "what is this file, can we store it, what does it become, how do we serve it" has exactly ONE answer in the codebase, shared by the browser, Node, and the Supabase edge runtime.

The image pipeline

The implementation lives in packages/database/supabase/functions/shared/image-pipeline.ts (the edge runtime only mounts supabase/functions/); ./media/image.ts re-exports it by relative path — the same deliberate pattern as @carbon/utils precision.ts. Do not "fix" that import and do not duplicate the code.

Codecs are wasm, lazy-loaded per format and identical in every runtime: libheif-js (HEIC/HEIF decode), jSquash mozjpeg / png / webp (decode + encode), jSquash resize. No ImageMagick anywhere. Node cannot load wasm over fetch(file:), hence ./media/node. Bare specifiers resolve via package.json in Node/browser and via functions/deno.json imports in Deno — add BOTH when adding a codec.

Shape modes (ImageShapeOptions): default = center-crop 300×300 (avatars), contained = fit + 10% pad to 300×300 (item thumbnails), height: n = proportional (logos, 128/512), convert = format normalization only (attachments). JPEG/HEIC/AVIF sources re-encode as JPEG (alpha flattened onto white), everything else as PNG.

HEIC is never stored. Every upload chokepoint converts first, through MediaUploader: both apps' FileDropzone, the ERP useFileUpload hook (the one document-panel upload mutation — TanStack-shaped: options at the hook or per-call, onSuccess/onError, isUploading; all ten document panels go through it, including RecordDocuments for supplier/customer records), useImageUpload (ERP + MES editor hooks), Suggestion, slide uploads, DocumentCreateForm, AttachmentsList, the three curated forms (ItemThumbnailUpload, ProfilePhotoForm, CompanyLogoForm). Non-browser callers (REST/MCP/integrations) use the process-image edge function, which runs the same processImage; the MCP signed-URL flow (createDocumentUploadUrl in documents.service, which every module's create*DocumentUploadUrl delegates to) mints a .heic name into {companyId}/tmp/uploads/… staging, and insertUploadedDocument converts it to JPEG (imgproxy round-trip — the bytes are already in storage) at the real path before the row exists; the nightly cleanup job sweeps everything under {companyId}/tmp/ older than a day. Temp staging for the imgproxy fallback is private/{companyId}/tmp/.

Fallback order in prepareImageUpload: wasm pipeline → (browser only) native createImageBitmap decode for formats the pipeline lacks (gif, avif) → imgproxy storage round-trip. On the edge function, MAX_PIXELS (25MP) guards the wasm decode (it materialises the full RGBA frame — ~200MB for a 48MP iPhone photo); over that it falls back to imgproxy, which decodes natively in bounded memory.

Adding a file class: create src/<type>/ with an index.ts, add the ./<type> export to package.json, and add a row above. Don't pre-create empty slots — json, text etc. get a subpath the day something needs unifying, not before.

Always

• Export/download through encodeCsv + downloadCsv (or downloadBlob); never string-join cells or build a <a download> inline.
• Add a new ERP document-panel upload via the useFileUpload hook; anywhere else, run picked files through MediaUploader.prepareForUpload first — never upload a picked File raw.
• Serve files with getContentType(effectiveExtension(path)) — never a local MIME map.
• Read PDFs through ./pdf only. Never import pdfjs-dist or pdfjs from react-pdf at a call site — react-pdf's <Document>/<Page> are the only things app code takes from that package.

One PDF.js engine per bundle

react-pdf hard-imports pdfjs-dist (5.4) and unpdf ships its own serverless build (6.1, worker inlined). Two engines in one browser bundle means two workers and ~2 MB of duplicate code, so ./pdf resolves the engine per runtime:

unpdf still carries import("unpdf/pdfjs") as a never-reached fallback, which Vite emitted as a 1.5 MB lazy chunk in every deploy. Both apps alias unpdf/pdfjs to app/ssr-shims/unpdf-pdfjs-stub.mjs to keep it out; the ERP client build was verified to contain exactly ONE engine chunk (388 KB). Any new app that consumes ./pdf in the browser needs the same alias.

• Classify with getDocumentType; narrow to preview-capable with isPreviewableDocumentType (a @ts-expect-error on a DocumentPreview type prop means a missing narrow, not a type bug).

Never

• Import ./media/node from anything that can reach the browser bundle.
• Store a .heic/.heif object. The preview routes' read-time transform is a safety net for legacy/API-stored files, not a licence to skip conversion.
• Expose imgproxy outside the Docker network — it reads the storage volume with no RLS.

Validation

pnpm --filter @carbon/files test        # vitest (includes a real HEIC fixture)
pnpm --filter @carbon/files typecheck
cd packages/database/supabase/functions && deno check --no-lock shared/image-pipeline.ts

Cross-References

• packages/database/supabase/functions/process-image/ — the authed server entry
• packages/database/supabase/functions/logo-resizer/, thumbnail/ — consumers of the pipeline primitives (decodeImage / resizeImage / encodeImage)
• packages/dev/docker/docker-compose.dev.yml, contrib/deploying/simple-docker-caddy/docker-compose.prod.yml — imgproxy service
• apps/{erp,mes}/app/routes/file+/preview+/$bucket.$.tsx — read-side serving