oxy-app-visual-identity

name

oxy-app-visual-identity

description

Use when rendering or sourcing a custom app's icon/favicon or screenshot/art on ANY surface — the homepage launcher card (web-app/src/pages/launcher), the admin apps browser (web-app/src/pages/admin/AdminCustomApps), an app rail tile, or any new place that shows an app's picture. Also when adding icon/art fields to an apps API DTO (workspace_custom_apps.rs, admin/apps/handlers.rs). Triggers on "app icon", "app favicon", "app art", "app screenshot", "AppCard icon", "AppFavicon", "icon_url", "art_url", "launcher card image", "app thumbnail/preview", "monogram fallback".

Customer-app visual identity (icon + art), unified

A custom app has exactly two pictures, and there is one way to source and render each — everywhere. Do not grow a second mechanism per surface.

Scope: platform rendering only. This is how oxy sources + renders app pictures. How an app author declares icon/art and ships the asset files is a customer-apps concern — see the hello-oxy example + the customer-app-development skill in the customer-apps repo, not here. The field contract itself is defined once in OxyAppManifest (+ the SDK manifest type); this skill only references it. Keep authoring how-to out of here so the two don't drift.

The single source of truth

Both pictures come only from the bundle's oxy-app.json manifest, as relative paths inside the bundle:

Manifest field	Meaning	API field	Rendered as
icon	the app glyph/favicon (a small square mark)	icon_url	24px object-contain mark beside the name / rail tile
art	the app screenshot/preview (a wide image)	art_url	h-40 w-full object-cover card image

The API turns each relative path into a same-origin URL: <app canonical url>/<path>, after safe_relative_art_path rejects anything that escapes the bundle (.., absolute, off-origin, \\, ?, #). The homepage helper is manifest_card_fields + CustomAppSummary::from_model_with_manifest in crates/app/src/server/api/workspace_custom_apps.rs. Reuse that helper — do not re-derive URLs by hand.

Non-negotiables

• Manifest is the ONLY source. Do not add a <url>/favicon.ico fetch, a headless-browser screenshot capture, an icon/art/screenshot/favicon DB column, or any per-surface image derivation. If a picture isn't in the manifest, the app has no picture — render the fallback, not a second lookup. (There is deliberately no screenshot capture yet; art is author-supplied only.)
• The homepage's manifest approach is canonical; every other surface follows it. Admin adopts what the homepage shows, never the reverse. The old admin-only AppFavicon (<url>/favicon.ico) mechanism is removed — admin reads icon_url from the API like the homepage does.
• One shared render component per picture. AppMark (icon → monogram fallback: the name's initial in a tile) and AppArt (art → initial-letter tile fallback). Both the launcher and the admin browser import the same components. A new surface showing an app icon imports AppMark; it does not hand-roll an <img> + fallback.
• Fallbacks, not blanks. No icon_url → monogram (never nothing). No art_url → letter tile. Both fallbacks derive from app.name[0] and use bg-primary/10 + text-primary, so a picture-less app still reads as a first-class card.
• List endpoints resolve manifests in BATCH. Any endpoint returning many apps (admin list_apps/list_my_apps, homepage list_custom_apps) must resolve the per-app manifest with a single batched load (join published_build_id → app_builds.manifest_json, plus apps.manifest_override), never an N+1 per-app read. Manifest resolution is metadata: a failure yields empty icon/art, never a 500.

Where it lives

• Backend, homepage: workspace_custom_apps.rs — list_custom_apps, manifest_card_fields, safe_relative_art_path, from_model_with_manifest.
• Backend, admin: crates/app/src/server/api/admin/apps/handlers.rs — AppResponse carries icon_url/art_url; list_apps/list_my_apps/the single-app read populate them via the shared helper + a batched manifest load.
• Frontend shared: AppMark + AppArt (icon/art with fallbacks) — one home, imported by both pages/launcher/components/AppCard.tsx and pages/admin/AdminCustomApps/**.
• Manifest type: art + icon on OxyAppManifest (crates/app/src/server/api/custom_apps_manifest.rs); mirror any change in the SDK manifest type + the custom-app author oxy.d.ts.

Litmus test before adding image code

Ask: "Am I about to fetch/derive an app picture from anything other than icon_url/art_url?" If yes (a favicon.ico probe, a screenshot job, a second column) — stop; that's the divergence this skill exists to prevent. And: "Would a new surface render the fallback the same as the homepage?" If not, route it through AppMark/AppArt.