feat(core): consumer-editable favicon with Tailor default

Add a `favicon` prop to AppShell that sets the document favicon (any
`<link rel="icon">` href — public-path URL or data URI), updating the
existing link from index.html in place. Defaults to the bundled Tailor
mark (a 32x32 PNG data URI) when omitted, so apps render correct
branding without an asset-copy step.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: erickteowarang

.changeset/document-title-sync.md

@@ -2,4 +2,7 @@
 "@tailor-platform/app-shell": minor
 ---
 
-Sync the browser tab title (`document.title`) with the active route. AppShell now sets the tab to `"<page> · <title>"`, where `<page>` is the current breadcrumb leaf (including any `useOverrideBreadcrumb` override, so detail pages show their record name automatically) and `<title>` is the `title` prop passed to `<AppShell>`. Works for every page with no per-page wiring; when no `title` is set the tab shows just the page name, and when nothing resolves the static `index.html` title is left untouched.
+Manage the browser tab from AppShell — title and favicon.
+
+- **Title**: AppShell now keeps `document.title` in sync with the active route as `"<page> · <title>"`, where `<page>` is the current breadcrumb leaf (including any `useOverrideBreadcrumb` override, so detail pages show their record name automatically) and `<title>` is the `title` prop passed to `<AppShell>`. Works for every page with no per-page wiring; when no `title` is set the tab shows just the page name, and when nothing resolves the static `index.html` title is left untouched.
+- **Favicon**: new `favicon` prop on `<AppShell>` sets the document favicon (any `<link rel="icon">` href — a public-path URL or a data URI), updating the existing link from `index.html` in place. When omitted it defaults to the bundled Tailor favicon, so apps get correct branding out of the box.

packages/core/src/components/appshell.tsx

@@ -21,6 +21,7 @@ import { ThemeProvider } from "@/contexts/theme-context";
 import { BreadcrumbOverrideProvider } from "@/contexts/breadcrumb-context";
 import { CommandPaletteProvider, type SearchSource } from "@/contexts/command-palette-context";
 import { BuiltInCommandPalette } from "@/components/command-palette";
+import { Favicon } from "@/components/favicon";
 import { useIsClient } from "@/hooks/use-is-client";
 import { convertPagesToModules } from "@/fs-routes/converter";
 import type { PageEntry } from "@/fs-routes/types";
@@ -48,6 +49,14 @@ type SharedAppShellProps = React.PropsWithChildren<{
    */
   icon?: React.ReactNode;
 
+  /**
+   * Browser-tab favicon href. Accepts anything valid on `<link rel="icon">` —
+   * a public-path URL (e.g. `/favicon.ico`) or a data URI. AppShell applies it
+   * to the document, updating the `<link rel="icon">` from `index.html` in
+   * place (or creating one). When omitted, the bundled Tailor favicon is used.
+   */
+  favicon?: string;
+
   /**
    * Base path for the app shell
    */
@@ -327,6 +336,7 @@ export const AppShell = (props: AppShellProps) => {
         <BreadcrumbOverrideProvider>
           <CommandPaletteProvider searchSources={props.searchSources}>
             <ThemeProvider defaultTheme="system" storageKey="appshell-ui-theme">
+              <Favicon href={props.favicon} />
               <RouterContainer>
                 {props.children}
                 <BuiltInCommandPalette />

packages/core/src/components/favicon.test.tsx

@@ -0,0 +1,33 @@
+import { render, waitFor } from "@testing-library/react";
+import { describe, it, expect, beforeEach } from "vitest";
+import { DEFAULT_FAVICON_HREF } from "@/lib/default-favicon";
+import { Favicon } from "./favicon";
+
+const getIconLink = () => document.querySelector<HTMLLinkElement>('link[rel="icon"]');
+
+describe("Favicon", () => {
+  beforeEach(() => {
+    document.head.querySelectorAll('link[rel="icon"]').forEach((el) => el.remove());
+  });
+
+  it("applies the consumer-provided href", async () => {
+    render(<Favicon href="/custom.ico" />);
+    await waitFor(() => expect(getIconLink()?.getAttribute("href")).toBe("/custom.ico"));
+  });
+
+  it("falls back to the bundled Tailor default when no href is given", async () => {
+    render(<Favicon />);
+    await waitFor(() => expect(getIconLink()?.getAttribute("href")).toBe(DEFAULT_FAVICON_HREF));
+  });
+
+  it("updates the existing icon link in place rather than adding another", async () => {
+    const existing = document.createElement("link");
+    existing.rel = "icon";
+    existing.href = "/old.ico";
+    document.head.appendChild(existing);
+
+    render(<Favicon href="/new.ico" />);
+    await waitFor(() => expect(getIconLink()?.getAttribute("href")).toBe("/new.ico"));
+    expect(document.head.querySelectorAll('link[rel="icon"]').length).toBe(1);
+  });
+});

packages/core/src/components/favicon.tsx

@@ -0,0 +1,37 @@
+import { useEffect } from "react";
+import { DEFAULT_FAVICON_HREF } from "@/lib/default-favicon";
+
+type FaviconProps = {
+  /**
+   * Favicon href to apply. Any value accepted by `<link rel="icon">` works:
+   * a public-path URL (e.g. `/favicon.ico`) or a data URI. When omitted, the
+   * bundled Tailor default ({@link DEFAULT_FAVICON_HREF}) is used.
+   */
+  href?: string;
+};
+
+/**
+ * Keeps the document favicon in sync with the `favicon` prop passed to
+ * `<AppShell>`, falling back to the bundled Tailor mark when none is given.
+ *
+ * Updates the existing `<link rel="icon">` from `index.html` in place (or
+ * creates one if absent), so consumers don't need to declare a favicon link
+ * themselves. Rendered once by `<AppShell>`.
+ *
+ * @internal
+ */
+export const Favicon = ({ href }: FaviconProps) => {
+  const resolved = href ?? DEFAULT_FAVICON_HREF;
+
+  useEffect(() => {
+    let link = document.querySelector<HTMLLinkElement>('link[rel="icon"]');
+    if (!link) {
+      link = document.createElement("link");
+      link.rel = "icon";
+      document.head.appendChild(link);
+    }
+    link.href = resolved;
+  }, [resolved]);
+
+  return null;
+};

packages/core/src/lib/default-favicon.ts

@@ -0,0 +1,10 @@
+/**
+ * Default favicon used when a consumer does not pass a `favicon` prop to
+ * `<AppShell>`. It is the Tailor mark, embedded as a 32×32 PNG data URI so it
+ * ships in the bundle and needs no asset-copy step in the consuming app.
+ *
+ * Consumers override it by passing `favicon` (any href: a public-path URL such
+ * as `/favicon.ico`, or a data URI).
+ */
+export const DEFAULT_FAVICON_HREF =
+  "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAACAAAAAgCAYAAABzenr0AAAAAXNSR0IArs4c6QAAAERlWElmTU0AKgAAAAgAAYdpAAQAAAABAAAAGgAAAAAAA6ABAAMAAAABAAEAAKACAAQAAAABAAAAIKADAAQAAAABAAAAIAAAAACshmLzAAAFKUlEQVRYCe1WS2xUZRQ+57+3paXEQmOKJYDRgGVDQjRGWOgCDLS6Mu2UMiWupKSF1JYAjsZoE23SaaFtQBC7QBdgSkYSNRYIVkE3BLUEJbgwEA210EGtQKowj3uP35nO0Ll0WmbK1pO5r3/OOd93Hv+DaYbS1SWFcwytEUNvkdAsN59eaGjg4VzdmVwNVP/9Hlk326YjwtTHTE8T03KJUuVMfNm5GB04IEv5Dm0CcL1tUbHjELkukW0TS4wW5eIrpZsVgX0d8oiVT1soQnXGpscUNB4nQvQKTq5DYWThXMppY6PMKS0l09rKt1JjUz3hYmrZt0/mWA5VsFCADT2lyg7AVSwL7w6NkaHjHKf2zS18budOWQBdH4htRl+EQfrltjYeGrfIfJ8yA/u7pdLEqQWRPWcsmqXp1ohNsmsQ9QnDtHvufDo1MEAmsFO2ClE9dJarDvSXxGK0DLC5EfhgrywTh7bBkd+yqUiB9VKnAgSk/2c43VtSRgdrajga2C6rS4rpdYyttgyZlD4ylBdzaG7muCdGPRnYv0dWiksfAbgcT0+d4w6NYKiHHTrUsI2H39ghKwI7JIAMVYBssfZFiqhmChn6CRlUsgnxbby+RF9Ch0ovjY+M3z3TkF1aBebl6sxFtFpnRH0LkRyG07WNTRwc+pNcpPttl+lLlGY93CTAFVT1Yfs7rraYS2uC3XzR57++oqpupFdcOes6Tn/VhqtalrviJcDECq6CdGoU55Gi9Q1NvHHwAl0OBKTFidFX+LsV18MasYoCQ8bQoD3GpXXtHfzm8PDVwuq6kT2Io9+wvYnYlCBbTwBiVUI7efOUIPVHIoVCN2Dw2itNfBJ1fp4s1NlFnQGWDoz3CEifwmzYHWzngcrKvx6q8ofrMUu3M9tLBdPBdfEFZ3qxJUUpHH1OSQA9cHleAZ1tbpZVWHhCtqG5OvdTdVZjZOgMZsKusoXU39TEkZf84TpLYo0AWgkk47oxVbsrjLks4nowPR93Ncdfxmge3S4ooMUASYDrsGYHqf4Vj4OFMXqvtYdvVNUOPVPtH2lGtD628q0EsGjUk0XY9ZTd8zFZHSNaZxRSJTEVXTqdz/RisJPf/XF0uLS6LtxLlt0P4FrQA3gUmkmDhNX0t+ky4LFM9sXf+RY1HRsYvFTlv7aVHd7BnLeYsHC4jgLnLvfPQNJncgX87p0gX3i0fFEts9WDFlqsEQsIzFSyJqAZwG9UgUDmcWTbkinqnAuZrAmoU1QWHBKC1SL7OidtMj5yIpDRwwMO/k/AkwE0WnIneMC85mDuJUCkRyjRjQhksl4jcsDDlNX5NCEeAjGLvsX2ezEWp2uO0Oc+H+li7tGZMM3tjYGrewF+d9ItPc63bOFLOBOsjVv0ZMOr3AEjwZx/4PnGOMnqaoU94pgdNSfSCUxKMw6X19IVsPu5OHgkNqH08WzesR3DDo3lxn9hYzrN7LzQkd6Sm+m2kwik/5l8/0cPKXl5OKI5WZYDoIYtDTqMkh5F6J2ffjz/twy+s2g0iy6gLF9HY1SA7f1DdYKjN+OMkEEAjHRjiY4KOZ+J43R80lc2iOpPWUZPD2TwSMEgXxm9SRUFhfRsZzd76peuj80p8Yk6fw9+9Rz5ZsPRvgU/TAeuBtmUgHp72XO0ERxrUntBorNRa+yKV5D5XRyVvlCo9I90ctO9Z0XgXgfCMkQ45qLJmCQ+6kjkC4uc7tDhhefv1b3f94wI5BcV9UfH/j2O/o6Qbbqs26fPhEI1MzoU/AeEofRp9F8pTwAAAABJRU5ErkJggg==";