Media and Images Architecture

Scope

@prox-os/media is the first shared media resource package for Prox OS. It is not a clone of Next.js Image, not an upload system, and not a complete media library. It defines a portable media contract and UI primitives that official apps, incubating apps, iframe surfaces, and future external apps can share.

The first phase covers images, avatars, icons, covers, screenshots, galleries, external link previews, and safe embed wrappers. Storage, uploads, crop tools, AI generation, and private media permissions remain future platform work.

Why A Shared Image Layer

Apps should not scatter raw img tags, unscoped iframe embeds, or one-off fallback styles. A shared image layer gives Prox OS one place to define:

• required alt behavior and decorative-image intent;
• layout stability through width / height / aspectRatio;
• lazy loading and async decoding defaults;
• responsive image fields such as srcSet, sizes, and picture sources;
• placeholders, dominant colors, skeletons, initials, and broken-image fallback;
• remote allowlist and provider detection helpers;
• future context actions such as copy URL, open in OS, inspect metadata, and save to Media Library.

Why Not Copy Next.js Image

Prox OS hosts local module apps, package apps, standalone Pages apps, iframe apps, and future remote modules. A Next.js-specific component would leak one framework's optimizer and deployment assumptions into the app contract.

OsImage keeps the app-facing API stable while implementation adapters can change later. Today it renders standard picture / img markup. A future adapter can map the same OsImageTransform object to Cloudflare Images, R2 + Workers, Unpic, or a custom optimizer without changing app code.

OsImage Responsibilities

OsImage owns the display contract for image-like resources:

• src, alt, decorative, width, height, aspectRatio;
• sizes, srcSet, and sources for responsive images and art direction;
• loading="lazy" and decoding="async" by default;
• fit, radius, placeholder, fallback, and dominant-color hints;
• crossOrigin and referrerPolicy;
• transform metadata for future image optimizer adapters;
• contextActions, onAction, and onContextMenuRequest hooks.

Decorative images must be explicit via decorative. Non-decorative images should carry meaningful alt text. The package cannot enforce every product copy decision, but Storybook examples should model alt-first usage.

Layout Stability

Apps should pass either width / height or aspectRatio. When neither is provided, OsImage chooses a variant-specific fallback ratio to avoid visible layout shift. This is intentionally conservative: apps can still render quick mock media, but production surfaces should provide dimensions.

Placeholder And Fallback

The first phase supports:

• skeleton placeholder;
• dominant color or gradient placeholder;
• icon fallback;
• initials fallback for avatars;
• broken image fallback.

These are UI states, not upload or image-processing features.

Remote Allowlist

isAllowedMediaUrl(url, patterns) and detectMediaProvider(url) provide the minimum policy helpers. The default pattern list is an example for demos and first-party surfaces. Production policy should be supplied by the OS host, workspace policy, app manifest, or server-side media gateway.

Apps should not build iframe or remote media URLs by hand when a provider adapter exists.

Transform Contract

OsImageTransform intentionally resembles common image-CDN controls:

width, height, fit, quality, format, gravity, dpr, background

Phase 1 stores and displays the transform intent. It does not perform image optimization.

Phase 2: Cloudflare Media Adapter

The Cloudflare-first route should map the same contract to platform services:

• R2 stores original media assets.
• Cloudflare Images or Image Transformations handles resize, crop, format, and quality.
• Workers handle auth, signed URLs, workspace permissions, and private media.
• r2:// and cf:// internal URIs can be resolved by a host adapter.
• app icon, avatar, cover, and screenshot variants can be generated from the same source resource.

Private media should move through signed URLs or a Worker proxy, not direct public bucket URLs.

Unpic Strategy

Unpic is a useful implementation reference for multi-CDN responsive images and could become an internal adapter. It is not the Prox OS app API. Business apps should depend on @prox-os/media, not Unpic primitives, so the implementation can later move between plain img, Cloudflare, Unpic, or a custom optimizer.

Non-goals

• No upload flow.
• No R2 or Cloudflare Images runtime integration.
• No crop editor.
• No AI image generation.
• No vendor SDK dependency for Notion, Figma, YouTube, or Grist.
• No OS Shell context menu import from @prox-os/media.