Media Resources Architecture

Scope

@prox-os/media defines the Prox OS media resource contract and first UI primitives. It covers how apps describe media and how reusable components present that media inside OS windows, Storybook, and future iframe or remote module surfaces.

The package emits media action intent. The OS Shell decides how to execute system actions.

Media package emits media action intent.
OS Shell owns system context menu execution.

Media Resource Contract

The core union is OsMediaResource:

• OsImageSource for images, avatars, icons, covers, and screenshots.
• OsEmbedSource for videos and embedded surfaces such as YouTube, Vimeo, Figma, Notion, GitHub, Grist, or custom embeds.
• OsExternalLinkSource for Notion pages, Figma files, GitHub resources, Grist documents, docs, generic URLs, documents, and attachments.

Each resource keeps url, optional canonicalUrl, optional thumbnailUrl, alt text, provider metadata, title, description, and extensible metadata.

Covered Media Kinds

Phase 1 includes primitives for:

• image, avatar, icon, cover, screenshot, gallery;
• video and embed wrappers;
• YouTube click-to-load embeds;
• external link previews for Notion, Figma, GitHub, Grist, docs, and generic URLs.

OsMediaPreview chooses the display mode from the resource kind. OsMediaCard wraps the preview with title, description, provider badge, and optional action buttons.

Provider Detection

detectMediaProvider(url) maps common hosts to providers:

• local and remote;
• Cloudflare Images and R2 placeholders;
• YouTube and Vimeo;
• Notion, Figma, GitHub, Grist, and Google Drive;
• custom fallback.

Provider detection is a UI helper, not an access-control system.

Remote Allowlist

OsMediaRemotePattern and isAllowedMediaUrl provide the first allowlist shape:

protocol, hostname, optional pathname

The default list is suitable for demos and first-party examples. Production allowlists should come from workspace policy, app manifest routing metadata, or server-side media policy.

Embed Security

OsEmbedFrame centralizes iframe defaults:

• sandbox defaults;
• allow defaults for media playback;
• lazy iframe loading;
• referrer policy;
• provider badge and visible title.

OsYouTubeEmbed defaults to click-to-load so Storybook and app windows do not load third-party iframe code before the user asks for it.

Context Actions

OsMediaAction reserves common future actions:

• open in OS;
• open in new tab;
• copy URL;
• copy Markdown;
• download;
• save to Media Library;
• set as avatar;
• set as cover;
• inspect metadata;
• generate alt text;
• transform image.

OsImage, OsMediaPreview, and OsMediaCard accept context action props and callbacks. They do not import shell stores or shell context menu code. Future OS integration should pass an adapter through app runtime context or component props.

Phase 2: Cloudflare Adapter

The Cloudflare-first adapter should resolve stable resource contracts into runtime URLs:

• R2 stores originals.
• Cloudflare Images or Transformations provides variants.
• Workers generate signed URLs and enforce workspace permissions.
• OsImageTransform maps to Cloudflare width, height, fit, quality, format, gravity, dpr, and background options.
• Internal r2:// and cf:// URIs remain private to the adapter.

Phase 3: OS Media Library

The product layer should become a Media Library App later:

• user uploads;
• app assets;
• avatar and cover management;
• attachment browser;
• AI-generated image provenance;
• usage tracking;
• workspace-level permissions;
• media search;
• media metadata inspector.

@prox-os/media is the contract and UI foundation for that product layer, not the library backend itself.