@moloodev/platform 0.0.0-stage → 0.1.0

package/package.json

@@ -1,6 +1,40 @@
 {
   "name": "@moloodev/platform",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./builtin-editors": "./src/builtin-editors.ts",
+    "./network": "./src/network.ts",
+    "./dev-certs": "./src/dev-certs.ts",
+    "./constants": "./src/constants.ts",
+    "./naming": "./src/naming.ts",
+    "./occupancy-protocol": "./src/occupancy-protocol.ts",
+    "./file-content": "./src/file-content.ts",
+    "./bundle": "./src/bundle.ts",
+    "./file-delivery": "./src/file-delivery.ts",
+    "./ids": "./src/ids.ts"
+  },
+  "dependencies": {
+    "nanoid": "^6.0.1",
+    "zod": "^4.5.4"
+  },
+  "devDependencies": {
+    "@types/node": "^24.13.3",
+    "tsx": "^4.23.13",
+    "typescript": "^7.0.2",
+    "@moloodev/typescript-config": "0.1.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "tsx --test 'src/**/*.test.ts' 'src/**/*.test.tsx'"
+  }
 }

package/src/api-surfaces.ts

@@ -0,0 +1,101 @@
+import { getMarketingOrigin } from "./origins";
+import { getPlatformAppById, getPlatformAppUrl } from "./platform";
+import { resolveSiteEnv, type SiteEnv } from "./url";
+import { WORKSPACE_HOST_API } from "./workspace-host";
+
+/**
+ * Shared platform API version segment. Modules mount at `/v1/{moduleId}`
+ * (no `/platform` prefix).
+ */
+export const PLATFORM_API = {
+  id: "platform",
+  apiVersion: "v1",
+  name: "Platform",
+} as const;
+
+export type ApiSurfaceRef = {
+  id: string;
+  apiVersion: string;
+  name?: string;
+};
+
+/** First path segments that must never be treated as a product API id. */
+export const RESERVED_API_ROOT_SEGMENTS = new Set([
+  "health",
+  "platform",
+  "v1",
+  "favicon.ico",
+]);
+
+export function getApiOrigin(env: SiteEnv = resolveSiteEnv()): string {
+  const api = getPlatformAppById("api");
+  if (!api) {
+    throw new Error("PLATFORM_APPS is missing api");
+  }
+  return getPlatformAppUrl(api, env);
+}
+
+export function getDocsOrigin(env: SiteEnv = resolveSiteEnv()): string {
+  return `${getMarketingOrigin(env)}/docs`;
+}
+
+export function getDocsSurfaceUrl(
+  surfaceId: string,
+  env: SiteEnv = resolveSiteEnv(),
+): string {
+  return `${getDocsOrigin(env)}/${surfaceId}`;
+}
+
+export function getApiOpenApiUrl(
+  _surface?: ApiSurfaceRef,
+  env: SiteEnv = resolveSiteEnv(),
+): string {
+  return `${getApiOrigin(env)}/openapi`;
+}
+
+export function getApiOpenApiJsonUrl(
+  env: SiteEnv = resolveSiteEnv(),
+): string {
+  return `${getApiOrigin(env)}/openapi.json`;
+}
+
+/** Base URL for platform modules: `{origin}/v1`. */
+export function getPlatformApiBaseUrl(
+  env: SiteEnv = resolveSiteEnv(),
+): string {
+  return `${getApiOrigin(env)}/${PLATFORM_API.apiVersion}`;
+}
+
+export function resolveApiSurface(
+  id: string,
+): ApiSurfaceRef | undefined {
+  if (id === PLATFORM_API.id) return PLATFORM_API;
+  if (id === WORKSPACE_HOST_API.id) return WORKSPACE_HOST_API;
+  return undefined;
+}
+
+export function isProductApiSurface(
+  id: string,
+): ApiSurfaceRef | undefined {
+  if (RESERVED_API_ROOT_SEGMENTS.has(id)) return undefined;
+  if (id === WORKSPACE_HOST_API.id) return WORKSPACE_HOST_API;
+  return undefined;
+}
+
+export function getSurfaceChromeLinks(
+  surfaceId: string,
+): { docsHref: string; apiHref: string } | null {
+  if (surfaceId === WORKSPACE_HOST_API.id) {
+    return {
+      docsHref: getDocsSurfaceUrl(WORKSPACE_HOST_API.id),
+      apiHref: getApiOpenApiUrl(),
+    };
+  }
+  if (surfaceId === "web") {
+    return {
+      docsHref: getDocsOrigin(),
+      apiHref: getApiOpenApiUrl(),
+    };
+  }
+  return null;
+}

package/src/app-icon.ts

@@ -0,0 +1,31 @@
+export type AppIcon =
+  | "hierarchy"
+  | "shuffle"
+  | "cube"
+  | "brush"
+  | "package"
+  | "grid"
+  | "music"
+  | "map"
+  | "sparkles"
+  | "users"
+  | "device"
+  | "chart"
+  | "world"
+  | "camera"
+  | "bolt"
+  | "palette"
+  | "robot"
+  | "layers"
+  | "message"
+  | "flag"
+  | "clock"
+  | "dice"
+  | "target"
+  | "wand"
+  | "cloud"
+  | "code"
+  | "home"
+  | "book"
+  | "activity"
+  | "shield";

package/src/asset-types.ts

@@ -0,0 +1,518 @@
+/** Icons used by asset kinds and file appearance resolvers. Independent of chrome `AppIcon`. */
+export const FILE_APPEARANCE_ICONS = [
+  "tabler:folder",
+  "tabler:hierarchy",
+  "tabler:layout",
+  "tabler:table",
+  "tabler:markdown",
+  "tabler:photo",
+  "tabler:movie",
+  "tabler:music",
+  "tabler:file-text",
+  "tabler:database",
+  "tabler:code",
+  "tabler:archive",
+  "tabler:typography",
+  "tabler:cube",
+  "tabler:file",
+  "tabler:package",
+  "tabler:help",
+] as const;
+
+export type AssetTypeIcon = (typeof FILE_APPEARANCE_ICONS)[number];
+
+/**
+ * Primitive storage and CRDT collaboration mode for an asset.
+ * - `json`: UTF-8 JSON object projected into Y.Doc `root` `SharedMap`.
+ * - `text`: UTF-8 text projected into `root.get("body")` (`SharedText`).
+ * - `blob`: Immutable binary object in object storage (`asset_blob`) with a pointer in `root`.
+ */
+export const STORAGE_MODES = ["json", "text", "blob"] as const;
+export type StorageMode = (typeof STORAGE_MODES)[number];
+
+export function isStorageMode(value: unknown): value is StorageMode {
+  return (
+    typeof value === "string" &&
+    (STORAGE_MODES as readonly string[]).includes(value)
+  );
+}
+
+/** Canonical first-party JSON `$schema` URIs. */
+export const FIRST_PARTY_SCHEMAS = {
+  layout: "https://moloo.dev/schemas/layout/v1.json",
+  catalog: "https://moloo.dev/schemas/catalog/v1.json",
+  table: "https://moloo.dev/schemas/table/v1.json",
+  loop: "https://moloo.dev/schemas/loop/v1.json",
+  bundle: "https://moloo.dev/schemas/bundle/v1.json",
+} as const;
+
+export type FirstPartySchemaKey = keyof typeof FIRST_PARTY_SCHEMAS;
+
+export type FileAppearance = {
+  label: string;
+  color: string;
+  icon: AssetTypeIcon;
+};
+
+/** Optional file matcher rule declared by an installed `EditorManifest`. */
+export type FileAppearanceMatcher = {
+  extensions?: readonly string[];
+  mimeTypes?: readonly string[];
+  schema?: string;
+  storageMode?: StorageMode;
+  label?: string;
+  icon?: AssetTypeIcon;
+  color?: string;
+};
+
+export const UNKNOWN_FILE_APPEARANCE: FileAppearance = {
+  label: "알 수 없음",
+  color: "#94a3b8",
+  icon: "tabler:help",
+};
+
+const PATTERN_APPEARANCE_MAP = {
+  "moloo.folder": { label: "폴더", color: "#94a3b8", icon: "tabler:folder" },
+  "moloo.loop": { label: "루프", color: "#f07858", icon: "tabler:hierarchy" },
+  "moloo.table": { label: "테이블", color: "#3d9b8f", icon: "tabler:table" },
+  "moloo.markdown": { label: "마크다운", color: "#5b6abf", icon: "tabler:markdown" },
+  "moloo.bundle": { label: "번들", color: "#2f7a86", icon: "tabler:package" },
+  "moloo.layout": { label: "레이아웃", color: "#7695b3", icon: "tabler:layout" },
+  "moloo.catalog": { label: "카탈로그", color: "#9474ad", icon: "tabler:package" },
+  "moloo.image": { label: "이미지", color: "#a5c65b", icon: "tabler:photo" },
+  "moloo.video": { label: "비디오", color: "#8f7fe0", icon: "tabler:movie" },
+  "moloo.audio": { label: "오디오", color: "#c78cd9", icon: "tabler:music" },
+  "moloo.document": { label: "문서", color: "#89b4e8", icon: "tabler:file-text" },
+  "moloo.data": { label: "데이터", color: "#66b06f", icon: "tabler:database" },
+  "moloo.code": { label: "코드", color: "#5c73c9", icon: "tabler:code" },
+  "moloo.archive": { label: "압축", color: "#b3a27a", icon: "tabler:archive" },
+  "moloo.font": { label: "글꼴", color: "#b09bbf", icon: "tabler:typography" },
+  "moloo.model": { label: "3D 모델", color: "#d1b24f", icon: "tabler:cube" },
+  "moloo.binary": { label: "바이너리", color: "#a7adba", icon: "tabler:file" },
+} as const satisfies Record<string, FileAppearance>;
+
+export type KnownPatternId = keyof typeof PATTERN_APPEARANCE_MAP;
+
+export const KNOWN_PATTERN_IDS = Object.keys(
+  PATTERN_APPEARANCE_MAP,
+) as KnownPatternId[];
+
+const DOCUMENT_SUBTYPES = new Set([
+  "pdf",
+  "msword",
+  "rtf",
+  "vnd.openxmlformats-officedocument.wordprocessingml.document",
+  "vnd.ms-powerpoint",
+  "vnd.openxmlformats-officedocument.presentationml.presentation",
+  "vnd.oasis.opendocument.text",
+  "vnd.oasis.opendocument.presentation",
+  "epub+zip",
+]);
+const DATA_SUBTYPES = new Set([
+  "json",
+  "xml",
+  "sql",
+  "vnd.ms-excel",
+  "vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+  "vnd.oasis.opendocument.spreadsheet",
+  "yaml",
+  "x-yaml",
+  "toml",
+]);
+const CODE_SUBTYPES = new Set([
+  "javascript",
+  "typescript",
+  "x-httpd-php",
+  "wasm",
+  "x-sh",
+  "x-python",
+  "x-python-code",
+  "x-rust",
+]);
+const ARCHIVE_SUBTYPES = new Set([
+  "zip",
+  "x-zip-compressed",
+  "x-rar-compressed",
+  "vnd.rar",
+  "x-7z-compressed",
+  "gzip",
+  "x-gzip",
+  "x-tar",
+  "x-bzip2",
+  "x-xz",
+  "zstd",
+]);
+const CODE_TEXT_SUBTYPES = new Set([
+  "html",
+  "css",
+  "javascript",
+  "typescript",
+  "x-python",
+  "x-sh",
+  "jsx",
+  "tsx",
+  "x-rust",
+  "x-vue",
+]);
+const DATA_TEXT_SUBTYPES = new Set(["csv", "xml", "yaml", "x-yaml", "tab-separated-values"]);
+
+/** The MIME family pattern an uploaded MIME type maps to; unknown or malformed types are `moloo.binary`. */
+export function patternForContentType(contentType: string): KnownPatternId {
+  const [type = "", subtypeRaw = ""] = contentType.trim().toLowerCase().split(";")[0]!.split("/");
+  const subtype = subtypeRaw.trim();
+  switch (type) {
+    case "image":
+      return "moloo.image";
+    case "video":
+      return "moloo.video";
+    case "audio":
+      return "moloo.audio";
+    case "font":
+      return "moloo.font";
+    case "model":
+      return "moloo.model";
+    case "text":
+      if (CODE_TEXT_SUBTYPES.has(subtype)) return "moloo.code";
+      if (DATA_TEXT_SUBTYPES.has(subtype)) return "moloo.data";
+      return "moloo.document";
+    case "application":
+      if (DOCUMENT_SUBTYPES.has(subtype)) return "moloo.document";
+      if (DATA_SUBTYPES.has(subtype)) return "moloo.data";
+      if (CODE_SUBTYPES.has(subtype)) return "moloo.code";
+      if (ARCHIVE_SUBTYPES.has(subtype)) return "moloo.archive";
+      if (subtype.startsWith("font-") || subtype.startsWith("x-font")) return "moloo.font";
+      return "moloo.binary";
+    default:
+      return "moloo.binary";
+  }
+}
+
+const COMPOUND_SCHEMA_BY_SUFFIX: readonly [string, string][] = [
+  [".layout.json", FIRST_PARTY_SCHEMAS.layout],
+  [".mlayout", FIRST_PARTY_SCHEMAS.layout],
+  [".catalog.json", FIRST_PARTY_SCHEMAS.catalog],
+  [".mcat", FIRST_PARTY_SCHEMAS.catalog],
+  [".table.json", FIRST_PARTY_SCHEMAS.table],
+  [".loop.json", FIRST_PARTY_SCHEMAS.loop],
+  [".bundle.json", FIRST_PARTY_SCHEMAS.bundle],
+];
+
+const EXTENSION_MIME_MAP: Record<string, { contentType: string; storageMode: StorageMode }> = {
+  ".json": { contentType: "application/json", storageMode: "json" },
+  ".mlayout": { contentType: "application/json", storageMode: "json" },
+  ".mcat": { contentType: "application/json", storageMode: "json" },
+  ".md": { contentType: "text/markdown", storageMode: "text" },
+  ".markdown": { contentType: "text/markdown", storageMode: "text" },
+  ".txt": { contentType: "text/plain", storageMode: "text" },
+  ".csv": { contentType: "text/csv", storageMode: "text" },
+  ".tsv": { contentType: "text/tab-separated-values", storageMode: "text" },
+  ".yaml": { contentType: "application/yaml", storageMode: "text" },
+  ".yml": { contentType: "application/yaml", storageMode: "text" },
+  ".toml": { contentType: "application/toml", storageMode: "text" },
+  ".xml": { contentType: "application/xml", storageMode: "text" },
+  ".html": { contentType: "text/html", storageMode: "text" },
+  ".css": { contentType: "text/css", storageMode: "text" },
+  ".js": { contentType: "text/javascript", storageMode: "text" },
+  ".mjs": { contentType: "text/javascript", storageMode: "text" },
+  ".ts": { contentType: "text/typescript", storageMode: "text" },
+  ".tsx": { contentType: "text/tsx", storageMode: "text" },
+  ".jsx": { contentType: "text/jsx", storageMode: "text" },
+  ".py": { contentType: "text/x-python", storageMode: "text" },
+  ".rs": { contentType: "text/x-rust", storageMode: "text" },
+  ".sh": { contentType: "text/x-sh", storageMode: "text" },
+  ".sql": { contentType: "application/sql", storageMode: "text" },
+  ".png": { contentType: "image/png", storageMode: "blob" },
+  ".jpg": { contentType: "image/jpeg", storageMode: "blob" },
+  ".jpeg": { contentType: "image/jpeg", storageMode: "blob" },
+  ".webp": { contentType: "image/webp", storageMode: "blob" },
+  ".gif": { contentType: "image/gif", storageMode: "blob" },
+  ".svg": { contentType: "image/svg+xml", storageMode: "blob" },
+  ".avif": { contentType: "image/avif", storageMode: "blob" },
+  ".mp4": { contentType: "video/mp4", storageMode: "blob" },
+  ".webm": { contentType: "video/webm", storageMode: "blob" },
+  ".mp3": { contentType: "audio/mpeg", storageMode: "blob" },
+  ".wav": { contentType: "audio/wav", storageMode: "blob" },
+  ".ogg": { contentType: "audio/ogg", storageMode: "blob" },
+  ".pdf": { contentType: "application/pdf", storageMode: "blob" },
+  ".zip": { contentType: "application/zip", storageMode: "blob" },
+  ".gz": { contentType: "application/gzip", storageMode: "blob" },
+  ".7z": { contentType: "application/x-7z-compressed", storageMode: "blob" },
+  ".woff": { contentType: "font/woff", storageMode: "blob" },
+  ".woff2": { contentType: "font/woff2", storageMode: "blob" },
+  ".ttf": { contentType: "font/ttf", storageMode: "blob" },
+  ".otf": { contentType: "font/otf", storageMode: "blob" },
+  ".glb": { contentType: "model/gltf-binary", storageMode: "blob" },
+  ".gltf": { contentType: "model/gltf+json", storageMode: "json" },
+};
+
+const TEXT_APPLICATION_SUBTYPES = new Set([
+  "yaml",
+  "x-yaml",
+  "toml",
+  "xml",
+  "sql",
+  "javascript",
+  "typescript",
+  "x-sh",
+  "x-python",
+  "x-rust",
+]);
+
+function normalizeMimeType(raw?: string | null): string {
+  if (!raw) return "";
+  const base = raw.trim().toLowerCase().split(";")[0]?.trim() ?? "";
+  return base.includes("/") ? base : "";
+}
+
+/**
+ * Classify a file by its name and optional declared MIME type into its default
+ * primitive `storageMode` (`"json" | "text" | "blob"`), normalized `contentType`,
+ * and inferred first-party `$schema` URI (if any).
+ */
+export function classifyFile(input: {
+  fileName: string;
+  contentType?: string | null;
+}): {
+  storageMode: StorageMode;
+  contentType: string;
+  defaultSchema: string | null;
+} {
+  const name = input.fileName.trim();
+  const lower = name.toLowerCase();
+  if (name === ".keep") {
+    return {
+      storageMode: "json",
+      contentType: "application/x-directory",
+      defaultSchema: null,
+    };
+  }
+
+  let defaultSchema: string | null = null;
+  for (const [suffix, schema] of COMPOUND_SCHEMA_BY_SUFFIX) {
+    if (lower.endsWith(suffix) && lower.length > suffix.length) {
+      defaultSchema = schema;
+      break;
+    }
+  }
+
+  const declared = normalizeMimeType(input.contentType);
+  const dotIdx = lower.lastIndexOf(".");
+  const ext = dotIdx > 0 ? lower.slice(dotIdx) : "";
+  const fromExt = ext ? EXTENSION_MIME_MAP[ext] : undefined;
+
+  const contentType =
+    declared && declared !== "application/octet-stream"
+      ? declared
+      : (fromExt?.contentType ?? (declared || "application/octet-stream"));
+
+  const [type = "", subtype = ""] = contentType.split("/");
+  if (
+    defaultSchema !== null ||
+    contentType === "application/json" ||
+    subtype.endsWith("+json") ||
+    fromExt?.storageMode === "json"
+  ) {
+    return {
+      storageMode: "json",
+      contentType:
+        contentType === "application/octet-stream"
+          ? "application/json"
+          : contentType,
+      defaultSchema,
+    };
+  }
+
+  if (
+    (type === "text" && contentType !== "image/svg+xml") ||
+    TEXT_APPLICATION_SUBTYPES.has(subtype) ||
+    fromExt?.storageMode === "text"
+  ) {
+    return {
+      storageMode: "text",
+      contentType:
+        contentType === "application/octet-stream" && fromExt
+          ? fromExt.contentType
+          : contentType,
+      defaultSchema: null,
+    };
+  }
+
+  return {
+    storageMode: "blob",
+    contentType,
+    defaultSchema: null,
+  };
+}
+
+const FIRST_PARTY_SCHEMA_APPEARANCE: Record<string, FileAppearance> = {
+  [FIRST_PARTY_SCHEMAS.layout]: PATTERN_APPEARANCE_MAP["moloo.layout"],
+  [FIRST_PARTY_SCHEMAS.catalog]: PATTERN_APPEARANCE_MAP["moloo.catalog"],
+  [FIRST_PARTY_SCHEMAS.table]: PATTERN_APPEARANCE_MAP["moloo.table"],
+  [FIRST_PARTY_SCHEMAS.loop]: PATTERN_APPEARANCE_MAP["moloo.loop"],
+  [FIRST_PARTY_SCHEMAS.bundle]: PATTERN_APPEARANCE_MAP["moloo.bundle"],
+};
+
+function isCompoundExtension(ext: string): boolean {
+  const withoutLeadingDot = ext.startsWith(".") ? ext.slice(1) : ext;
+  return withoutLeadingDot.includes(".");
+}
+
+function scoreMatcher(
+  file: {
+    name: string;
+    storageMode?: string;
+    contentType: string;
+    schema?: string | null;
+  },
+  matcher: FileAppearanceMatcher,
+): number {
+  if (matcher.storageMode && file.storageMode && matcher.storageMode !== file.storageMode) {
+    return 0;
+  }
+  if (matcher.schema && file.schema && matcher.schema === file.schema) {
+    return 400;
+  }
+  const lowerName = file.name.toLowerCase();
+  if (matcher.extensions && matcher.extensions.length > 0) {
+    let bestExt = "";
+    for (const rawExt of matcher.extensions) {
+      const ext = rawExt.toLowerCase();
+      if (lowerName.endsWith(ext) && lowerName.length > ext.length) {
+        if (ext.length > bestExt.length) bestExt = ext;
+      }
+    }
+    if (bestExt.length > 0) {
+      return (isCompoundExtension(bestExt) ? 300 : 200) + bestExt.length;
+    }
+  }
+  const mime = normalizeMimeType(file.contentType);
+  if (matcher.mimeTypes && matcher.mimeTypes.length > 0 && mime) {
+    for (const rawTarget of matcher.mimeTypes) {
+      const target = rawTarget.trim().toLowerCase();
+      if (target === mime) return 150;
+      if (target.endsWith("/*")) {
+        const prefix = target.slice(0, -1);
+        if (mime.startsWith(prefix)) return 100;
+      }
+    }
+  }
+  return 0;
+}
+
+/**
+ * Resolve cosmetic display metadata (`label`, `color`, `icon`) for a file from
+ * installed editor matchers, falling back to first-party `$schema`/extension
+ * rules and OS-style MIME family defaults.
+ */
+export function resolveFileAppearance(
+  file: {
+    name: string;
+    storageMode?: string;
+    contentType: string;
+    schema?: string | null;
+  },
+  matchers: readonly FileAppearanceMatcher[] = [],
+): FileAppearance {
+  if (file.name === ".keep" || normalizeMimeType(file.contentType) === "application/x-directory") {
+    return PATTERN_APPEARANCE_MAP["moloo.folder"];
+  }
+
+  const classified = classifyFile({
+    fileName: file.name,
+    contentType: file.contentType,
+  });
+  const effectiveSchema = file.schema ?? classified.defaultSchema;
+  const effectiveFile = {
+    ...file,
+    storageMode: file.storageMode ?? classified.storageMode,
+    contentType: normalizeMimeType(file.contentType) || classified.contentType,
+    schema: effectiveSchema,
+  };
+
+  let bestScore = 0;
+  let bestMatcher: FileAppearanceMatcher | null = null;
+  for (const matcher of matchers) {
+    const score = scoreMatcher(effectiveFile, matcher);
+    if (score > bestScore && (matcher.label || matcher.icon || matcher.color)) {
+      bestScore = score;
+      bestMatcher = matcher;
+    }
+  }
+
+  if (effectiveSchema && FIRST_PARTY_SCHEMA_APPEARANCE[effectiveSchema]) {
+    const base = FIRST_PARTY_SCHEMA_APPEARANCE[effectiveSchema]!;
+    // Only let a matcher override a first-party schema/compound-extension appearance
+    // when it matched at schema (>= 400) or compound-extension (>= 300) specificity,
+    // never on a generic .json or application/json rule.
+    const override = bestScore >= 300 ? bestMatcher : null;
+    return {
+      label: override?.label ?? base.label,
+      color: override?.color ?? base.color,
+      icon: override?.icon ?? base.icon,
+    };
+  }
+
+  const lowerName = file.name.toLowerCase();
+  const mime = effectiveFile.contentType;
+  if (
+    mime === "text/markdown" ||
+    lowerName.endsWith(".md") ||
+    lowerName.endsWith(".markdown")
+  ) {
+    const md = PATTERN_APPEARANCE_MAP["moloo.markdown"];
+    const override = bestScore >= 150 ? bestMatcher : null;
+    return {
+      label: override?.label ?? md.label,
+      color: override?.color ?? md.color,
+      icon: override?.icon ?? md.icon,
+    };
+  }
+
+  const fallbackKind = patternForContentType(mime);
+  const fallback = PATTERN_APPEARANCE_MAP[fallbackKind];
+  return {
+    label: bestMatcher?.label ?? fallback.label,
+    color: bestMatcher?.color ?? fallback.color,
+    icon: bestMatcher?.icon ?? fallback.icon,
+  };
+}
+
+/**
+ * Resolve cosmetic appearance for either a pattern/kind identifier (`moloo.*`)
+ * or an asset summary with `name`, `storageMode`, `contentType`, and `schema`.
+ * When file fields (`storageMode`, `schema`, or `contentType` + `name`) are
+ * present, they take precedence over a legacy `type` string.
+ */
+export function resolvePatternAppearance(
+  input:
+    | string
+    | {
+        type?: string;
+        name?: string;
+        storageMode?: StorageMode;
+        contentType?: string | null;
+        schema?: string | null;
+      },
+): FileAppearance {
+  if (typeof input === "string") {
+    return Object.hasOwn(PATTERN_APPEARANCE_MAP, input)
+      ? PATTERN_APPEARANCE_MAP[input as KnownPatternId]
+      : UNKNOWN_FILE_APPEARANCE;
+  }
+  if (
+    input.storageMode ||
+    input.schema ||
+    (input.contentType && input.name)
+  ) {
+    return resolveFileAppearance({
+      name: input.name ?? "",
+      storageMode: input.storageMode,
+      contentType: input.contentType ?? "application/octet-stream",
+      schema: input.schema ?? null,
+    });
+  }
+  if (input.type && Object.hasOwn(PATTERN_APPEARANCE_MAP, input.type)) {
+    return PATTERN_APPEARANCE_MAP[input.type as KnownPatternId];
+  }
+  return UNKNOWN_FILE_APPEARANCE;
+}