@@ -287,7 +287,7 @@ describe("pickProjectFavicon", () => {
             filters: [
               {
                 name: "Images",
-                extensions: ["avif", "gif", "ico", "jpeg", "jpg", "png", "svg", "webp"],
+                extensions: ["avif", "gif", "ico", "jpeg", "jpg", "png", "svg", "webp", "icns"],
               },
             ],
           },
 
@@ -13,7 +13,7 @@ import {
   type DesktopEnvironmentBootstrap,
   type PickedThemeFile,
 } from "@t3tools/contracts";
-import { WORKSPACE_IMAGE_PREVIEW_EXTENSIONS } from "@t3tools/shared/filePreview";
+import { PROJECT_FAVICON_EXTENSIONS } from "@t3tools/shared/projectFavicon";
 import { resolveEditorCommand } from "@t3tools/shared/editor";
 import * as HostProcess from "@t3tools/shared/hostProcess";
 import * as NodeOS from "node:os";
@@ -271,7 +271,7 @@ export const pickProjectFavicon = DesktopIpc.makeIpcMethod({
       filters: [
         {
           name: "Images",
-          extensions: WORKSPACE_IMAGE_PREVIEW_EXTENSIONS.map((extension) => extension.slice(1)),
+          extensions: PROJECT_FAVICON_EXTENSIONS.map((extension) => extension.slice(1)),
         },
       ],
     });
 
@@ -1234,6 +1234,38 @@ describe("AssetAccess", () => {
     }).pipe(Effect.provide(layerTest)),
   );
 
+  it.effect("serves a native macOS app icon as its embedded PNG", () =>
+    Effect.gen(function* () {
+      const fileSystem = yield* FileSystem.FileSystem;
+      const path = yield* Path.Path;
+      const root = yield* fileSystem.makeTempDirectoryScoped({
+        prefix: "t3-asset-favicon-icns-",
+      });
+      const icns = new Uint8Array(8 + 8 + screenshotPng.length);
+      icns.set(new TextEncoder().encode("icns"));
+      new DataView(icns.buffer).setUint32(4, icns.length);
+      icns.set(new TextEncoder().encode("ic07"), 8);
+      new DataView(icns.buffer).setUint32(12, 8 + screenshotPng.length);
+      icns.set(screenshotPng, 16);
+      yield* fileSystem.makeDirectory(path.join(root, "Resources"));
+      yield* fileSystem.writeFile(path.join(root, "Resources", "AppIcon.icns"), icns);
+
+      const result = yield* issueAssetUrl({
+        resource: { _tag: "project-favicon", cwd: root },
+      });
+      const suffix = result.relativeUrl.slice(`${ASSET_ROUTE_PREFIX}/`.length);
+      const separatorIndex = suffix.indexOf("/");
+
+      expect(result.sourcePath).toBe(path.join("Resources", "AppIcon.icns"));
+      const asset = yield* resolveAsset(
+        suffix.slice(0, separatorIndex),
+        suffix.slice(separatorIndex + 1),
+      );
+      expect(asset?.kind === "bytes" ? asset.mimeType : null).toBe("image/png");
+      expect(asset?.kind === "bytes" ? Uint8Array.from(asset.bytes) : null).toEqual(screenshotPng);
+    }).pipe(Effect.provide(layerTest)),
+  );
+
   it.effect("rejects a resolved project favicon with a non-image extension", () =>
     Effect.gen(function* () {
       const fileSystem = yield* FileSystem.FileSystem;
 
@@ -31,7 +31,10 @@ import {
   type ImageDimensions,
 } from "@t3tools/shared/imageDimensions";
 import { githubMediaFetchUrl, githubMediaFileName } from "@t3tools/shared/githubMedia";
-import { PROJECT_FAVICON_FALLBACK_MARKER } from "@t3tools/shared/projectFavicon";
+import {
+  isProjectFaviconPath,
+  PROJECT_FAVICON_FALLBACK_MARKER,
+} from "@t3tools/shared/projectFavicon";
 import { MAX_TOOL_OUTPUT_IMAGE_BASE64_LENGTH, toolOutputImages } from "@t3tools/shared/toolOutput";
 import * as Clock from "effect/Clock";
 import * as Crypto from "effect/Crypto";
@@ -57,6 +60,7 @@ import { expandHomePathWith } from "../pathExpansion.ts";
 import * as ProjectFaviconResolver from "../project/ProjectFaviconResolver.ts";
 import * as WorkspacePaths from "../workspace/WorkspacePaths.ts";
 import * as NativeAppIconResolver from "./NativeAppIconResolver.ts";
+import { extractIcnsPng } from "./icns.ts";
 import { openMediaFile, readMediaFileHeader, type OpenMediaFile } from "./MediaFile.ts";
 
 export const ASSET_ROUTE_PREFIX = "/api/assets";
@@ -65,6 +69,8 @@ const SIGNING_SECRET_NAME = "asset-access-signing-key";
 const ASSET_TOKEN_TTL_MS = 60 * 60 * 1000;
 const PROJECT_FAVICON_TOKEN_BUCKET_MS = 30 * 60 * 1000;
 const PROJECT_FAVICON_VERSION_PREFIX = "v";
+// Clients draw project icons from a 96px thumbnail at most.
+const PROJECT_FAVICON_ICNS_MIN_SIZE = 96;
 const INLINE_VIDEO_MIME_TYPE_PATTERN = /^video\/[\w!#$&^.+-]+$/i;
 // Extensions a document viewer or audio player may request inline. The extension comes from
 // the attachment id the server assigned, never from the client's mime type.
@@ -233,6 +239,26 @@ const readToolOutputImage = Effect.fn("AssetAccess.readToolOutputImage")(functio
     : { mimeType: image.mimeType, bytes: Buffer.from(image.data, "base64") };
 });
 
+/** Serves an `.icns` favicon as its embedded PNG, since browsers cannot draw it. */
+const projectFaviconAsset = Effect.fn("AssetAccess.projectFaviconAsset")(function* (
+  filePath: string,
+) {
+  if (!filePath.toLowerCase().endsWith(".icns")) {
+    return { kind: "file", path: filePath } satisfies ResolvedAsset;
+  }
+  const fileSystem = yield* FileSystem.FileSystem;
+  const bytes = yield* fileSystem.readFile(filePath).pipe(
+    Effect.tapError((cause) =>
+      Effect.logError("Failed to read project icon image.", { filePath, cause }),
+    ),
+    Effect.orElseSucceed(() => null),
+  );
+  const png = bytes ? extractIcnsPng(bytes, PROJECT_FAVICON_ICNS_MIN_SIZE) : null;
+  return png
+    ? ({ kind: "bytes", bytes: png, mimeType: "image/png" } satisfies ResolvedAsset)
+    : null;
+});
+
 const resolveCanonicalFile = Effect.fn("AssetAccess.resolveCanonicalFile")(function* (
   filePath: string,
 ) {
@@ -633,7 +659,7 @@ export const issueAssetUrl = Effect.fn("AssetAccess.issueAssetUrl")(function* (i
       const relativePath =
         faviconPath && !isExternalOverride ? path.relative(workspaceRoot, faviconPath) : null;
       const sourceFaviconPath = isExternalOverride ? faviconPath : relativePath;
-      if (sourceFaviconPath && !isWorkspaceImagePreviewPath(sourceFaviconPath)) {
+      if (sourceFaviconPath && !isProjectFaviconPath(sourceFaviconPath)) {
         return yield* new AssetPreviewTypeValidationError({ resource: input.resource });
       }
       sourcePath = sourceFaviconPath ?? undefined;
@@ -836,7 +862,7 @@ export const resolveAsset = Effect.fn("AssetAccess.resolveAsset")(function* (
       workspaceRoot: claims.workspaceRoot,
       relativePath: claims.relativePath,
     });
-    return faviconPath ? ({ kind: "file", path: faviconPath } satisfies ResolvedAsset) : null;
+    return faviconPath ? yield* projectFaviconAsset(faviconPath) : null;
   }
 
   if (claims.kind === "project-favicon-external") {
@@ -849,9 +875,7 @@ export const resolveAsset = Effect.fn("AssetAccess.resolveAsset")(function* (
       ),
       Effect.orElseSucceed(() => null),
     );
-    return faviconPath === claims.filePath
-      ? ({ kind: "file", path: faviconPath } satisfies ResolvedAsset)
-      : null;
+    return faviconPath === claims.filePath ? yield* projectFaviconAsset(faviconPath) : null;
   }
 
   if (claims.kind === "github-media") {
 
@@ -0,0 +1,62 @@
+import { describe, expect, it } from "vite-plus/test";
+
+import { extractIcnsPng } from "./icns.ts";
+
+function pngHeader(size: number): Uint8Array {
+  const png = new Uint8Array(24);
+  png.set([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, 0, 0, 0, 13, 0x49, 0x48, 0x44, 0x52]);
+  new DataView(png.buffer).setUint32(16, size);
+  new DataView(png.buffer).setUint32(20, size);
+  return png;
+}
+
+function icns(...entries: ReadonlyArray<readonly [type: string, data: Uint8Array]>): Uint8Array {
+  const length = 8 + entries.reduce((total, [, data]) => total + 8 + data.length, 0);
+  const bytes = new Uint8Array(length);
+  const view = new DataView(bytes.buffer);
+  bytes.set(new TextEncoder().encode("icns"));
+  view.setUint32(4, length);
+  let offset = 8;
+  for (const [type, data] of entries) {
+    bytes.set(new TextEncoder().encode(type), offset);
+    view.setUint32(offset + 4, 8 + data.length);
+    bytes.set(data, offset + 8);
+    offset += 8 + data.length;
+  }
+  return bytes;
+}
+
+const widthOf = (png: Uint8Array | null) =>
+  png ? new DataView(png.buffer, png.byteOffset).getUint32(16) : null;
+
+describe("extractIcnsPng", () => {
+  it("picks the smallest PNG that covers the requested size", () => {
+    const file = icns(
+      ["TOC ", new Uint8Array(16)],
+      ["ic09", pngHeader(512)],
+      ["icp5", pngHeader(32)],
+      ["ic07", pngHeader(128)],
+      ["ic08", pngHeader(256)],
+    );
+
+    expect(widthOf(extractIcnsPng(file, 96))).toBe(128);
+  });
+
+  it("falls back to the largest PNG when none covers the requested size", () => {
+    const file = icns(["icp4", pngHeader(16)], ["icp5", pngHeader(32)]);
+
+    expect(widthOf(extractIcnsPng(file, 96))).toBe(32);
+  });
+
+  it("returns null for files without a PNG entry or with a foreign header", () => {
+    expect(extractIcnsPng(icns(["it32", new Uint8Array(64)]), 96)).toBeNull();
+    expect(extractIcnsPng(pngHeader(128), 96)).toBeNull();
+  });
+
+  it("stops at an entry whose length runs past the file", () => {
+    const file = icns(["ic07", pngHeader(128)], ["ic08", pngHeader(256)]);
+    new DataView(file.buffer).setUint32(8 + 8 + 24 + 4, 4096);
+
+    expect(widthOf(extractIcnsPng(file, 200))).toBe(128);
+  });
+});
@@ -0,0 +1,27 @@
+import { readImageDimensions } from "@t3tools/shared/imageDimensions";
+
+const ICNS_HEADER_BYTES = 8;
+const ICNS_MAGIC = 0x69636e73; // "icns"
+const PNG_MAGIC = 0x89504e47; // "\x89PNG"
+
+/** Picks the smallest PNG at least `minSize` wide, else the largest; null when there is none. */
+export function extractIcnsPng(bytes: Uint8Array, minSize: number): Uint8Array | null {
+  const data = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  if (bytes.length < ICNS_HEADER_BYTES || data.getUint32(0) !== ICNS_MAGIC) return null;
+  const end = Math.min(data.getUint32(4), bytes.length);
+  let best: { readonly png: Uint8Array; readonly width: number } | null = null;
+  for (let offset = ICNS_HEADER_BYTES; offset + ICNS_HEADER_BYTES <= end;) {
+    const length = data.getUint32(offset + 4);
+    if (length < ICNS_HEADER_BYTES || offset + length > end) break;
+    const entry = bytes.subarray(offset + ICNS_HEADER_BYTES, offset + length);
+    const isPng = entry.length >= 4 && data.getUint32(offset + ICNS_HEADER_BYTES) === PNG_MAGIC;
+    offset += length;
+    const width = isPng ? readImageDimensions(entry)?.width : undefined;
+    if (width === undefined) continue;
+    const isBetter =
+      best === null ||
+      (best.width < minSize ? width > best.width : width >= minSize && width < best.width);
+    if (isBetter) best = { png: entry, width };
+  }
+  return best?.png ?? null;
+}
@@ -22,7 +22,7 @@ import * as Schema from "effect/Schema";
 import * as WorkspacePaths from "../workspace/WorkspacePaths.ts";
 import * as T3ProjectFileLoader from "./T3ProjectFileLoader.ts";
 
-// Resolution probes 21 well-known paths plus 7 source files, so a miss
+// Resolution probes 23 well-known paths plus 7 source files, so a miss
 // costs ~30 filesystem probes. AssetAccess resolves on every project-favicon
 // asset URL, and a project's icon does not move, so the answer is cached.
 const FAVICON_CACHE_CAPACITY = 512;
@@ -69,6 +69,8 @@ const FAVICON_CANDIDATES = [
   "assets/logo.svg",
   "assets/logo.png",
   ".idea/icon.svg",
+  "Resources/AppIcon.icns",
+  "AppIcon.icns",
 ] as const;
 
 // Files that may contain a <link rel="icon"> or icon metadata declaration.
 
@@ -25,7 +25,7 @@ import type {
   ProjectSearchContentsResult,
   ProjectSearchEntriesResult,
 } from "@t3tools/contracts";
-import { isWorkspaceImagePreviewPath } from "@t3tools/shared/filePreview";
+import { isProjectFaviconPath } from "@t3tools/shared/projectFavicon";
 
 // fff-node stays external to the CLI bundle because it dlopens a native
 // library. A static `import` of an external package is a hard error inside a
@@ -169,7 +169,7 @@ function mapFileSearchResult(
 ): ProjectSearchEntriesResult {
   const entries = result.items.flatMap((item) => {
     const entry = toFileEntry(item);
-    return entry && (!imageOnly || isWorkspaceImagePreviewPath(entry.path)) ? [entry] : [];
+    return entry && (!imageOnly || isProjectFaviconPath(entry.path)) ? [entry] : [];
   });
   return {
     entries: entries.slice(0, limit),
 
@@ -163,6 +163,10 @@ const decodeFaviconPath = Schema.decodeUnknownEffect(ProjectFaviconPath);
 effectIt.effect("project favicon paths accept only supported image files", () =>
   Effect.gen(function* () {
     assert.strictEqual(yield* decodeFaviconPath("brand/icon.svg"), "brand/icon.svg");
+    assert.strictEqual(
+      yield* decodeFaviconPath("Resources/AppIcon.icns"),
+      "Resources/AppIcon.icns",
+    );
     assert.strictEqual((yield* Effect.exit(decodeFaviconPath(".env")))._tag, "Failure");
   }),
 );
 
@@ -97,7 +97,7 @@ const ProjectMonogramIcon = Schema.Struct({
 /** A workspace-relative image a project may use as its favicon. */
 export const ProjectFaviconPath = TrimmedNonEmptyString.check(
   Schema.isMaxLength(1024),
-  Schema.isPattern(/\.(?:avif|gif|ico|jpe?g|png|svg|webp)$/i),
+  Schema.isPattern(/\.(?:avif|gif|icns|ico|jpe?g|png|svg|webp)$/i),
 );
 export type ProjectFaviconPath = typeof ProjectFaviconPath.Type;
Original file line number	Diff line number	Diff line change
`@@ -287,7 +287,7 @@ describe("pickProjectFavicon", () => {`
`287`	`287`	`filters: [`
`288`	`288`	`{`
`289`	`289`	`name: "Images",`
`290`		`- extensions: ["avif", "gif", "ico", "jpeg", "jpg", "png", "svg", "webp"],`
	`290`	`+ extensions: ["avif", "gif", "ico", "jpeg", "jpg", "png", "svg", "webp", "icns"],`
`291`	`291`	`},`
`292`	`292`	`],`
`293`	`293`	`},`