feat(core): manage browser tab title + favicon from AppShell

[erickteowarang]

Tracking issue: tailor-inc/platform-planning#1401

Summary

Today every app-shell consumer ships the same broken browser-tab experience: a hardcoded <title> that never changes as you navigate, and a <link rel="icon" href="/favicon.ico"> that 404s unless the app happens to drop a file in public/. This moves both concerns into AppShell so consumers get correct tab behaviour for free.

Title sync

AppShell now keeps document.title in sync with the active route, rendered as "<page> · <title>":

• <page> is the current breadcrumb leaf, resolved from the same page meta.title app-shell already uses for breadcrumbs — and it honours useOverrideBreadcrumb, so a detail page that sets a record name (e.g. an order number) gets it in the tab automatically, no extra wiring.
• <title> is the existing title prop on <AppShell>.

A single internal DocumentTitle mounted in the root route drives this for every page — no per-page code. When no title is set the tab shows just the page name; 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 like /favicon.ico, or a data URI). It updates the existing link from index.html in place (or creates one). When omitted it defaults to the bundled Tailor mark (a compact 32×32 PNG data URI, ~2 KB), so apps render correct branding out of the box and can override per-app.

Implementation

• components/document-title.tsx — DocumentTitle (internal), reads usePathSegments() + breadcrumb overrides + useAppShellConfig().title.
• components/favicon.tsx + lib/default-favicon.ts — Favicon (internal) + embedded Tailor default.
• routing/router.tsx — mounts <DocumentTitle /> in the root route element (inside the router + breadcrumb/config providers).
• components/appshell.tsx — new favicon prop, renders <Favicon href={props.favicon} />; title JSDoc updated to note tab-title behaviour.

Why here (shared location)

The breadcrumb trail is already resolved once per navigation in usePathSegments/createRootRoute. Driving the tab title from the leaf of that same trail means it tracks every route — and every consumer — from one place, instead of each app re-implementing a document.title effect.

Testing

• document-title.test.tsx (4) and favicon.test.tsx (3) — all pass.
• pnpm run lint clean; full turbo build green (6/6).
• No new public API beyond the favicon prop; title sync needs zero consumer changes.

Consumer migration (e.g. IMS / Monitor)

Pass title (and optionally favicon) to <AppShell>; delete any local document.title effect. With nothing passed, apps still get the Tailor favicon by default.

🤖 Generated with Claude Code

[IzumiSy]

Suggestion (non-blocking)

If we’re okay making React the sole owner of the document title and favicon (i.e. not relying on static <title> / favicon tags in index.html), I wonder if we could lean on React 19’s built-in head tag support here instead of updating the DOM imperatively with useEffect.

In other words:

• title via <title>{...}</title>
• favicon via <link rel="icon" href={...} />

That would let us keep this declarative and avoid direct document.title = ... / document.head.querySelector(...) logic.

Rough sketch:

import { useAppShellConfig } from "@/contexts/appshell-context";
import { useBreadcrumbOverride } from "@/contexts/breadcrumb-context";
import { usePathSegments } from "@/components/dynamic-breadcrumb";
import { DEFAULT_FAVICON_HREF } from "@/lib/default-favicon";

const SEPARATOR = " · ";

export const DocumentHead = () => {
  const { title: appTitle, favicon } = useAppShellConfig();
  const { basePath, segments } = usePathSegments();
  const { overrides } = useBreadcrumbOverride();

  const leaf = segments.at(-1);
  let pageTitle: string | undefined;

  if (leaf) {
    const leafFullPath = basePath ? `/${basePath}/${leaf.path}` : `/${leaf.path}`;
    pageTitle = overrides.get(leafFullPath) ?? leaf.title;
  }

  const nextTitle = [pageTitle, appTitle].filter(Boolean).join(SEPARATOR);
  const resolvedFavicon = favicon ?? DEFAULT_FAVICON_HREF;

  return (
    <>
      {nextTitle ? <title>{nextTitle}</title> : null}
      <link rel="icon" href={resolvedFavicon} />
    </>
  );
};

Then we could render that once near the router root instead of having separate effect-only components for title/favicon.

If the intent is to preserve static index.html values as a fallback, though, the current approach makes sense too.

[erickteowarang]

@IzumiSy Ah right not a bad idea, I forgot that React 19 has that now. Might make some changes

[erickteowarang]

@IzumiSy So I played around with it and I think the only problem right now is that there's no backward compatibility, i.e we will need to remove the static <title>/ from the index.html files we control in all of our client repos, so app-shell is the sole owner. Otherwise I'm pretty sure it will be overwritten by them.

Not a big deal, I do think it's a cleaner way to do it in app-shell and I don't want to constantly use useEffect haha.

[IzumiSy]

@IzumiSy So I played around with it and I think the only problem right now is that there's no backward compatibility, i.e we will need to remove the static <title>/ from the index.html files we control in all of our client repos, so app-shell is the sole owner. Otherwise I'm pretty sure it will be overwritten by them.

Not a big deal, I do think it's a cleaner way to do it in app-shell and I don't want to constantly use useEffect haha.

Yea, I think so too. Let's go bold.