Skip to content

Open-source manufacturing ERP, MES and QMS. Quoting, MRP, inventory, shop floor, quality and lot/serial traceability on one Postgres schema, with a REST API and MCP server. Self-host or use Carbon Cloud.

docs(mobile): spec, plan and record-header catalogue for the phone chrome

aashu76f734a37148
diff --git a/.ai/plans/2026-10-07-mobile-chrome-structure.md b/.ai/plans/2026-10-07-mobile-chrome-structure.md
new file mode 100644
index 0000000000..82879a3426
--- /dev/null
+++ b/.ai/plans/2026-10-07-mobile-chrome-structure.md
@@ -0,0 +1,506 @@
+# Mobile chrome structure — implementation plan
+
+**Spec / source:** `.ai/specs/2026-10-07-mobile-chrome-structure.md`
+**Research:** `.ai/research/2026-10-07-record-header-catalogue.md`
+**Branch:** `feat/mobile-redesign` (uncommitted working tree, `/Users/aashu/work/carbon/carbon-feat-mobile-redesign`). Never commit.
+
+## Progress
+- [x] Task 1: Single compact query in `@carbon/utils`
+- [x] Task 2: One compact store in `@carbon/react`
+- [x] Task 3: ERP callers of `useIsMobile`
+- [x] Task 4: Slot primitives
+- [x] Task 5: App bar actions and bottom bar on portal slots
+- [x] Task 6: App bar override on a value slot; `NewRecordPage` declares Back
+- [x] Task 7: Audit full-page `/new` routes
+- [x] Task 8: Record tabs on value slots
+- [x] Task 9: Action presentation context in `@carbon/react`
+- [x] Task 10: `RecordHeader`, `RecordAction`, `RecordPhoneChrome`, `RecordHeroTarget`
+- [x] Task 11: `DocumentHeader` card variant
+- [x] Task 12: Migrate shell-A headers (11)
+- [x] Task 13: Migrate shell-B headers (14)
+- [x] Task 14: Migrate other topbar headers and company cards (4)
+- [x] Task 15: Migrate card forms, actions-only pages, fixed asset (9)
+- [x] Task 16: Delete leftovers; Lingui extract
+- [ ] Task 17: End-to-end verification (static checks done; browser checks need the go-ahead)
+
+## Dependencies
+- Tasks 1 → 2 → 3, in order.
+- Task 4 has no dependencies. Tasks 5, 6 and 8 need Task 4. Task 7 needs Task 6.
+- Task 9 has no dependencies. Task 10 needs Tasks 4 and 9, and Task 11 needs Task 10.
+- Tasks 12–15 need Tasks 10 and 11; they are independent of each other but share files, so run them sequentially. Task 13 needs Task 8 (the item headers' DetailsTopbar).
+- Task 16 needs Tasks 12–15. Task 17 needs everything.
+
+Commands used below (all confirmed in package.json):
+- `cd apps/erp && npx tsgo --noEmit` is the erp typecheck (`typecheck` script = `react-router typegen && tsgo --noEmit`).
+- `cd packages/react && npx tsgo --noEmit`, and the same in `packages/utils`.
+- `pnpm exec biome check <files>` from the repo root.
+- `cd <pkg> && pnpm exec vitest run <paths>`.
+- `pnpm lingui:extract && pnpm lingui:clean` from the repo root.
+
+---
+
+## Task 1: Single compact query in `@carbon/utils`
+
+**Depends on:** none
+**Files:**
+- Modify: `packages/utils/src/viewport.ts` — delete `COMPACT_MAX_WIDTH` and make `COMPACT_QUERY = "(width < 48rem)"`. Update the doc comment to "Compact means below Tailwind `md` (48rem), the same query theme.css uses."
+- Modify: `packages/utils/src/viewport.test.ts` — change the `"max-width: 767px"` expectation to `"width < 48rem"`.
+
+**Verify:**
+```bash
+cd packages/utils && pnpm exec vitest run src/viewport.test.ts && npx tsgo --noEmit
+# Expected: tests pass, no type errors
+```
+**Out of scope:** the inline script's logic (it already uses `COMPACT_QUERY`).
+
+## Task 2: One compact store in `@carbon/react`
+
+**Depends on:** 1
+**Files:**
+- Modify: `packages/react/src/Compact.tsx`
+- Modify: `packages/react/src/hooks/useIsMobile.ts` — turn it into a re-export: `export { useIsMobile as default } from "../Compact";`
+- Modify: `apps/erp/app/root.tsx` — `<CompactProvider initialCompact=…>`. Add a comment next to `data-compact-ui=""`: "With CompactProvider below, the two halves of the compact opt-in (CSS and JS)."
+
+**Steps:**
+1. In `Compact.tsx`:
+ - Drop the `enabled` field and prop. The context becomes `{ initialCompact: boolean } | null`.
+ - `useCompact()` returns `context !== null && matches`, with server snapshot `context?.initialCompact ?? false`.
+ - Add `export function useIsMobile(): boolean | undefined`, which uses the same `subscribe`/`getSnapshot` with server snapshot `() => context ? context.initialCompact : undefined`. Doc: "Viewport below md, regardless of the compact opt-in; `undefined` until hydrated when no CompactProvider seeds it."
+ - Delete `useCompactSeed`.
+2. `rg "useCompactSeed|enabled=" packages apps --glob '*.tsx'` must not show any compact-related hits.
+
+**Verify:**
+```bash
+cd packages/react && npx tsgo --noEmit && pnpm exec vitest run
+cd ../../apps/erp && npx tsgo --noEmit
+# Expected: both typecheck clean, react tests pass
+```
+**Out of scope:** the MES/starter callers (their API is unchanged).
+
+## Task 3: ERP callers of `useIsMobile`
+
+**Depends on:** 2
+**Files:**
+- Modify: `apps/erp/app/components/Layout/Panels.tsx`:
+ - `PanelProvider`: `useIsMobile()` becomes `useCompact()` (same value in the ERP). Keep the effect body.
+ - `ResizablePanels`: delete the `isMobile` variable, the pathname collapse effect, and the whole `if (isMobile) { …Drawer… }` branch. Remove the `Drawer*` imports and `useIsMobile` if they are unused.
+- Modify: `apps/erp/app/components/Layout/Navigation/CollapsibleSidebar.tsx` — `useIsMobile` becomes `useCompact`. Rename `isMobile`/`wasMobile` to `isCompact`/`wasCompact`. Keep the effect: it still restores the desktop sidebar after a phone visit.
+- Modify: `apps/erp/app/components/Layout/Topbar/Breadcrumbs.tsx` — delete `const isMobile = useIsMobile()` and render `<CompanyBreadcrumb />` unconditionally. Breadcrumbs only renders inside `Topbar`, which returns null when compact (`Topbar.tsx:21-22`).
+
+**Verify:**
+```bash
+rg "useIsMobile" apps/erp
+# Expected: no output
+cd apps/erp && npx tsgo --noEmit
+```
+**Out of scope:** `packages/react/src/Sidebar.tsx` and `FunnelChart.tsx` (shared, unchanged API).
+
+## Task 4: Slot primitives
+
+**Depends on:** none
+**Files:**
+- Create: `apps/erp/app/components/Layout/Mobile/slots.tsx`. Precedent: `useAppBarOverride.ts` (the stack store) and `ChromeSlots.tsx` (the portal).
+
+**Steps:**
+1. Write:
+```tsx
+// SPDX header (copy from a sibling file)
+import { useCompact } from "@carbon/react";
+import type { ComponentProps, ReactNode } from "react";
+import { useEffect, useId } from "react";
+import { createPortal } from "react-dom";
+import { create } from "zustand";
+
+/**
+ * A place in the shell that pages render into. The filler's React context
+ * (forms, menus, route data) is kept, since it renders through a portal.
+ * Phones only: on desktop `Fill` renders nothing and the caller keeps its
+ * in-place copy.
+ */
+export function createPortalSlot() {
+ const useStore = create<{
+ target: HTMLElement | null;
+ count: number;
+ setTarget: (el: HTMLElement | null) => void;
+ add: (delta: 1 | -1) => void;
+ }>()((set) => ({
+ target: null,
+ count: 0,
+ setTarget: (target) => set((s) => (s.target === target ? s : { target })),
+ add: (delta) => set((s) => ({ count: Math.max(0, s.count + delta) }))
+ }));
+ // Stable, so React never detaches and re-attaches the target.
+ const ref = (el: HTMLElement | null) => useStore.getState().setTarget(el);
+
+ function Target(props: ComponentProps<"div">) {
+ return <div {...props} ref={ref} />;
+ }
+ function Fill({ children }: { children: ReactNode }) {
+ const isCompact = useCompact();
+ const target = useStore((s) => s.target);
+ const add = useStore((s) => s.add);
+ useEffect(() => {
+ if (!isCompact) return;
+ add(1);
+ return () => add(-1);
+ }, [isCompact, add]);
+ return isCompact && target ? createPortal(children, target) : null;
+ }
+ const useFilled = () => useStore((s) => s.count > 0);
+ return { Target, Fill, useFilled };
+}
+
+/**
+ * Data a page hands the shell. The newest provider wins; unmounting removes
+ * only its own entry. Callers memoize `value`: a new object re-provides it.
+ */
+export function createValueSlot<T>() {
+ const useStore = create<{
+ entries: { id: string; value: T }[];
+ put: (id: string, value: T) => void;
+ remove: (id: string) => void;
+ }>()((set) => ({
+ entries: [],
+ put: (id, value) =>
+ set((s) => ({ entries: [...s.entries.filter((e) => e.id !== id), { id, value }] })),
+ remove: (id) => set((s) => ({ entries: s.entries.filter((e) => e.id !== id) }))
+ }));
+ function useProvide(value: T | null) {
+ const id = useId();
+ const put = useStore((s) => s.put);
+ const remove = useStore((s) => s.remove);
+ useEffect(() => {
+ if (value === null) return;
+ put(id, value);
+ return () => remove(id);
+ }, [id, value, put, remove]);
+ }
+ const useValue = () => useStore((s) => s.entries.at(-1)?.value ?? null);
+ return { useProvide, useValue };
+}
+```
+
+**Verify:**
+```bash
+cd apps/erp && npx tsgo --noEmit && cd ../.. && pnpm exec biome check apps/erp/app/components/Layout/Mobile/slots.tsx
+# Expected: clean
+```
+**Out of scope:** migrating callers (Tasks 5, 6, 8, 10).
+
+## Task 5: App bar actions and bottom bar on portal slots
+
+**Depends on:** 4
+**Files:**
+- Modify: `apps/erp/app/components/Layout/Mobile/ChromeSlots.tsx`:
+ - Replace the context, provider, `useChromeSlotTargets` and the BottomBar count store with `const appBarActionsSlot = createPortalSlot(); const bottomBarSlot = createPortalSlot();`.
+ - `AppBarActions` keeps its dev-only 2-child warning and returns `<appBarActionsSlot.Fill>{children}</appBarActionsSlot.Fill>`.
+ - `BottomBar = bottomBarSlot.Fill`; `useBottomBarActive = bottomBarSlot.useFilled`.
+ - Export `AppBarActionsTarget = appBarActionsSlot.Target`.
+ - `MobileBottomChrome` renders `<bottomBarSlot.Target className="empty:hidden" />`.
+ - Keep `useCompactCssVar` unchanged.
+- Modify: `Mobile/MobileAppBar.tsx` — replace the `ref={appBarActionsRef}` div with `<AppBarActionsTarget className={…same classes…} />`. Drop `useChromeSlotTargets`.
+- Modify: `Mobile/index.ts` — remove the `ChromeSlotsProvider` export.
+- Modify: `apps/erp/app/routes/x+/_layout.tsx` — delete the `<ChromeSlotsProvider>` wrapper and its import, keeping the children.
+
+**Verify:**
+```bash
+rg "ChromeSlotsProvider|useChromeSlotTargets" apps/erp
+# Expected: no output
+cd apps/erp && npx tsgo --noEmit
+```
+**Out of scope:** `useCompactCssVar` (review section C).
+
+## Task 6: App bar override on a value slot; `NewRecordPage` declares Back
+
+**Depends on:** 4
+**Files:**
+- Modify: `Mobile/appBar.ts`:
+ - `AppBarState.kind` becomes `"root" | "pushed" | "selection"`.
+ - Add `export type AppBarOverride = Partial<AppBarState> & { trailing?: ReactNode }`.
+ - Add `export function mergeAppBar(base: AppBarState, override: AppBarOverride | null): AppBarState & { trailing?: ReactNode }`, which spreads the override over the base (an override with `kind: "pushed"` and no `subtitle` clears the subtitle).
+- Modify: `Mobile/useAppBarOverride.ts` — rebuild on `createValueSlot<AppBarOverride>()`. Export `useAppBarOverride = slot.useValue` and `useSetAppBarOverride = slot.useProvide`. Delete the hand-written stack.
+- Modify: `Mobile/useAppBar.ts`:
+ - Delete the `/new` block and the `useLocation` import.
+ - Return `mergeAppBar(state, override)` with `title` (the company name on Home), `moduleTitle`, and `Sidebar` only when the merged kind is `"root"`.
+- Modify: `Mobile/MobileAppBar.tsx`:
+ - Read everything from `useAppBar()`, without a separate override.
+ - Back renders when `kind === "pushed" && backTo`.
+ - `canSwitch = kind === "root" && Sidebar`.
+ - Actions are hidden when `kind === "selection"`, and the subtitle only shows when `kind === "pushed"`.
+ - `trailing` renders after the actions.
+- Modify: `Mobile/MobileTabBar.tsx` — replace its `useAppBarOverride()` hide rule with `useAppBar().kind !== "root"`. Read the current rule first and keep its result for every case: selection hides, pushed hides.
+- Modify: `components/Table/components/Compact/CompactList.tsx` — the override becomes `{ kind: "selection", title, trailing }`.
+- Modify: `routes/x+/inventory+/quantities+/$itemId.tsx` and `routes/x+/issue-workflow+/new.tsx` — the override becomes `{ kind: "pushed", title, backTo }`. Delete the copied Back Button JSX and the unused imports (`LuChevronLeft`, `Link`, `Button`).
+- Modify: `components/NewRecordPage.tsx`:
+ - Call `useSetAppBarOverride(useMemo(() => (listTo ? { kind: "pushed", backTo: listTo } : null), [listTo]))`, where `listTo = useBreadcrumbs().at(-1)?.to`.
+ - Import `useBreadcrumbs` from `~/components/Layout/Topbar/Breadcrumbs`.
+ - If `listTo === pathname`, provide null (a create page whose last crumb is itself).
+- Modify: `Mobile/appBar.test.ts` — add cases for `mergeAppBar`: a pushed override over a root base gives kind pushed with the override's backTo; a selection override keeps the base title when it has none; a null override returns the base.
+
+**Verify:**
+```bash
+cd apps/erp && pnpm exec vitest run app/components/Layout && npx tsgo --noEmit
+rg 'endsWith\("/new"\)' app/components/Layout
+# Expected: tests pass, typecheck clean, rg prints nothing
+```
+**Out of scope:** the breadcrumb-derived root/pushed rules in `deriveAppBar`.
+
+## Task 7: Audit full-page `/new` routes
+
+**Depends on:** 6
+**Files:** `apps/erp/app/routes/**/*new*.tsx` (read); modify only the ones found.
+
+**Steps:**
+1. For every route file whose path ends in `new.tsx` and that has a default export rendering UI, classify it:
+ - (a) It renders `NewRecordPage`: done.
+ - (b) It renders a Drawer/Modal/ModalCard or a form with `type="modal"`/`"drawer"` over a parent route: the list keeps its bar, so nothing changes.
+ - (c) It is a full page without `NewRecordPage`: wrap its root in `<NewRecordPage>`, or move its existing wrapper's classes into `className`, keeping desktop layout identical.
+2. Write the classification to `.ai/runs/2026-10-07-new-route-audit.txt`.
+3. If a (c) route's layout can't be kept identical inside `NewRecordPage`, call `useSetAppBarOverride` there directly with the same value instead.
+
+**Verify:**
+```bash
+cd apps/erp && npx tsgo --noEmit
+# Expected: clean; audit file lists every *new*.tsx route with a class
+```
+**Out of scope:** changing the forms themselves.
+
+## Task 8: Record tabs on value slots
+
+**Depends on:** 4
+**Files:**
+- Modify: `components/Layout/Panels.tsx`:
+ - Remove `recordTabs`/`setRecordTabs` from `PanelContextType` and its default, the `inert` prop, `CompactPanelProvider` and the `RecordTab` type.
+ - Add `export const recordTabsSlot = createValueSlot<CompactTabItem[]>(); export const recordFrameSlot = createValueSlot<true>();`.
+ - `CompactRecordTabs` calls `recordFrameSlot.useProvide(true)`, reads `recordTabsSlot.useValue()`, and maps each item to `{ ...item, active: panel === "content" && item.active, onClick: showContent }`.
+- Modify: `components/Layout/Navigation/DetailsTopbar.tsx`:
+ - Build `items: CompactTabItem[]` in a `useMemo` over `[links, location.pathname, paramString, preserveParams]`, with `active` computed as the compact branch already does.
+ - Phones: `recordTabsSlot.useProvide(isCompact ? items : null)`.
+ - If `recordFrameSlot.useValue()` is set, return null; otherwise render `<CompactTabRow items={items} />`.
+ - Delete `linksKey` and its effect.
+ - `links` is a new array on every render: memoize `items` on a key string of `name|to|count|active` joined, so the provider doesn't re-put on every render. Comment: "Keyed on what the tabs show."
+- Modify: `components/Layout/index.ts` — drop the `CompactPanelProvider` export if present.
+- Modify: `routes/x+/{part,material,tool,consumable,service}+/$itemId.tsx` — restore the `HEAD` component shape: inline the `*RouteBody` function back into the default export and drop `CompactPanelProvider`. Keep this branch's other changes, such as `explorerLabel`. Diff each against `git show HEAD:<path>` to confirm the only remaining delta is non-provider changes.
+
+**Verify:**
+```bash
+rg "CompactPanelProvider|setRecordTabs|linksKey" apps/erp
+# Expected: no output
+cd apps/erp && npx tsgo --noEmit
+```
+**Out of scope:** the `--header-height` override in `CompactRecordTabs`.
+
+## Task 9: Action presentation context in `@carbon/react`
+
+**Depends on:** none
+**Files:**
+- Create: `packages/react/src/ActionPresentation.tsx`
+- Modify: `packages/react/src/Button.tsx`, `packages/react/src/SplitButton.tsx`, `packages/react/src/index.tsx` (export `ActionPresentationProvider`).
+
+**Steps:**
+1. `ActionPresentation.tsx`:
+```tsx
+export type ActionPresentation =
+ | { kind: "bar"; emphasis: "primary" | "secondary" }
+ | { kind: "row"; onSelect: () => void };
+const Context = createContext<ActionPresentation | null>(null);
+export const ActionPresentationProvider = Context.Provider;
+export const useActionPresentation = () => useContext(Context);
+```
+2. `Button`: read `const presentation = useActionPresentation()`.
+ - `bar`: override `variant` with `presentation.emphasis` and `size` with `"lg"`, and add `w-full min-w-0`.
+ - `row`:
+ - Use `variant="ghost"`, `size="lg"` and the classes `h-12 w-full min-w-0 justify-start rounded-sm px-3 text-[15px] font-normal text-foreground shadow-none`, plus `text-destructive` when the given variant was `destructive`.
+ - Wrap `onClick` so it calls the original and then, unless `props["aria-haspopup"]` is set or the event was default-prevented, calls `setTimeout(presentation.onSelect, 0)`.
+ - Comment: "Next task, so a submit button's form is still mounted when the browser submits it."
+ - With no provider, behaviour is unchanged.
+3. `SplitButton`: read the presentation. In `bar` or `row`, the chevron Button gets `w-11 shrink-0 justify-center px-0` and the main Button `min-w-0 flex-1`. The chevron's Radix trigger already has `aria-haspopup`, so it won't close the sheet.
+
+**Verify:**
+```bash
+cd packages/react && npx tsgo --noEmit && pnpm exec vitest run
+# Expected: clean, tests pass
+```
+**Out of scope:** `buttonVariants` itself; Assignee's raw button.
+
+## Task 10: `RecordHeader`, `RecordAction`, `RecordPhoneChrome`, `RecordHeroTarget`
+
+**Depends on:** 4, 9
+**Files:**
+- Create: `apps/erp/app/components/Layout/RecordHeader.tsx`. Precedent: `components/Layout/RecordChrome.tsx`, which this replaces (copy its hero, app-bar ⋯ and bottom-bar markup), and the shell-A desktop markup in `modules/sales/ui/SalesOrder/SalesOrderHeader.tsx:390-417`.
+- Delete: `apps/erp/app/components/Layout/RecordChrome.tsx`, after Tasks 12–15 move its callers. Until then, keep it re-exporting the new parts so callers compile: `export { RecordAction } from "./RecordHeader"`, and `RecordChrome` implemented via `RecordPhoneChrome`.
+
+**Steps:**
+1. Slots: `recordPrimarySlot`, `recordSecondarySlot`, `recordOverflowSlot`, `recordHeroSlot` = `createPortalSlot()`.
+2. `RecordAction({ slot, children })`:
+ - Desktop: `<>{children}</>`.
+ - Phones: wrap the children in the matching slot's `Fill`, inside `<ActionPresentationProvider>`:
+ - `{kind: "bar", emphasis: "primary"}` for primary;
+ - `{kind: "bar", emphasis: "secondary"}` for secondary;
+ - `{kind: "row", onSelect: closeOverflow}` for overflow, where `closeOverflow` comes from a module zustand `useOverflowSheet` store `{ open, setOpen }`.
+3. `RecordPhoneChrome({ menu?, copyValue? })`, which renders nothing on desktop:
+ - the app-bar ⋯ (copy RecordChrome's `AppBarActions` block);
+ - `<BottomBar>` with `<recordPrimarySlot.Target className={cellClassName} />`, `<recordSecondarySlot.Target className={cellClassName} />`, and the ⋯ IconButton shown when `recordOverflowSlot.useFilled()`. Use `cellClassName = "flex min-w-0 flex-1 empty:hidden [&>*]:min-w-0 [&>*]:w-full"`: layout only, no button reach-in. The bar is rendered when any of the three slots is filled.
+ - the overflow `BottomSheet` with `open` from `useOverflowSheet`, its `BottomSheetContent forceMount` given `data-[state=closed]:hidden`, and `<recordOverflowSlot.Target className="flex flex-col [&>*]:w-full" />`. If `BottomSheetContent` doesn't forward `forceMount` to Radix `Content` and `Portal`, add that pass-through in `packages/react/src/BottomSheet.tsx`.
+4. `RecordHero({ title, subtitle, status, bleed })`:
+ - Copy RecordChrome's hero div.
+ - Phones only. It keeps the empty hidden div so `--header-height`/`--hero-height` resolve to 0, using `useCompactCssVar`.
+5. `RecordHeroTarget({ bleed })` renders `<recordHeroSlot.Target className={cn(bleed && "-mx-4 -mt-4")} />` on phones.
+6. `RecordHeader(props)`, with props as in the spec:
+ - **Desktop shell:**
+ - `div` class `flex flex-shrink-0 items-center justify-between gap-x-4 py-2 bg-card border-b border-border h-[var(--header-height)] overflow-x-auto scrollbar-hide compact:hidden`.
+ - Padding: `pl-2` with an explorer toggle, else `pl-4`; `pr-2` with a properties toggle, else `pr-4`.
+ - Left `HStack`: explorer IconButton (copy SalesOrderHeader), the title (on desktop only: `titleTo ? <Link to><Heading size="h4" className="flex items-center gap-2">{title}</Heading></Link> : <Heading size="h4" …>`), `{copyValue && <Copy text={copyValue} />}`, the ⋯ DropdownMenu when `menu`, then `{status}`.
+ - Right `HStack`: `{aside}{actions}`, then the properties IconButton.
+ - **Phones:** `<RecordHero title={isCompact ? title : undefined} subtitle status />` and `<RecordPhoneChrome menu copyValue />`. The desktop shell stays mounted (`compact:hidden`), but `title` is not rendered inside it while compact.
+ - If `subtitle` is given, the desktop shell shows it as `<p className="text-sm text-muted-foreground">` under the heading only when the caller passes `showSubtitleOnDesktop`.
+ - Inspection is the only caller with a desktop subtitle line today; see Task 14.
+ - If the catalogue shows another caller needs it, STOP and report.
+7. Export `RecordHeader`, `RecordAction`, `RecordPhoneChrome`, `RecordHero`, `RecordHeroTarget`, `recordHeroSlot`.
+
+**Verify:**
+```bash
+cd apps/erp && npx tsgo --noEmit && cd ../.. && pnpm exec biome check apps/erp/app/components/Layout/RecordHeader.tsx apps/erp/app/components/Layout/RecordChrome.tsx
+# Expected: clean
+```
+**Out of scope:** call-site migration.
+
+## Task 11: `DocumentHeader` card variant
+
+**Depends on:** 10
+**Files:**
+- Modify: `apps/erp/app/components/DocumentHeader.tsx`:
+ - Props: `{ title: string; subtitle?; status?; menuItems?; actions?; copyValue? = title; className? }`.
+ - Desktop: the existing `CardHeader`, plus `compact:hidden` (always).
+ - Phones: `<recordHeroSlot.Fill><RecordHero status={status} subtitle={subtitle} /></recordHeroSlot.Fill>` and `<RecordPhoneChrome menu={menuItems} copyValue={copyValue} />`.
+ - The `actions` node keeps its `RecordAction` wrappers from the callers.
+ - Translate the hard-coded `aria-label="More options"` with `t`.
+
+**Verify:**
+```bash
+cd apps/erp && npx tsgo --noEmit
+```
+**Out of scope:** callers (Task 15).
+
+## Task 12: Migrate shell-A headers (11)
+
+**Depends on:** 10, 11
+**Files:** `modules/sales/ui/SalesOrder/SalesOrderHeader.tsx`, `modules/sales/ui/Quotes/QuoteHeader.tsx`, `modules/sales/ui/SalesRFQ/SalesRFQHeader.tsx`, `modules/sales/ui/SalesReturnOrders/SalesReturnOrderHeader.tsx`, `modules/purchasing/ui/PurchaseOrder/PurchaseOrderHeader.tsx`, `modules/purchasing/ui/PurchaseReturnOrders/PurchaseReturnOrderHeader.tsx`, `modules/purchasing/ui/PurchasingRfq/PurchasingRFQHeader.tsx`, `modules/purchasing/ui/SupplierQuote/SupplierQuoteHeader.tsx`, `modules/invoicing/ui/PurchaseInvoice/PurchaseInvoiceHeader.tsx`, `modules/invoicing/ui/SalesInvoice/SalesInvoiceHeader.tsx`, `modules/production/ui/Jobs/JobHeader.tsx`.
+
+**Steps (per file):**
+1. Replace `<RecordChrome …/>` plus the `compact:hidden` shell with one `<RecordHeader>`:
+ - `title`: the id node. For Quote and PO, `<span className="flex items-center gap-0"><span>{id}</span><RevisionSuffix …/></span>` (and drop `subtitle`).
+ - `titleTo`: the existing Link `to`.
+ - `copyValue`, `menu`, `status`: the existing variables.
+ - `onToggleExplorer={toggleExplorer}` and `onToggleProperties={toggleProperties}`.
+ - `actions`: the existing right-hand HStack children, minus the properties toggle.
+2. Modals, disclosures and dialogs that were inside the shell move to right after `<RecordHeader>`. They portal anyway, so the position is irrelevant to the DOM.
+3. Where a slot and a variant restate one condition, name it once (`const isDraft = …`) and use it in both. Do not change any variant's resulting value.
+4. PO: delete the `isCompact` term from `invoiceVariant`, and `useCompact` if unused.
+5. Remove the now-unused imports.
+
+**Verify:**
+```bash
+cd apps/erp && npx tsgo --noEmit && cd ../.. && pnpm exec biome check <the 11 files>
+# Expected: clean
+```
+**Out of scope:** action logic, permissions, fetchers.
+
+## Task 13: Migrate shell-B headers (14)
+
+**Depends on:** 8, 10, 11
+**Files:** `modules/items/ui/{Materials/MaterialHeader,Parts/PartHeader,Tools/ToolHeader,Services/ServiceHeader,Consumables/ConsumableHeader}.tsx`, `modules/items/ui/ChangeNotice/ChangeNoticeHeader.tsx`, `modules/quality/ui/Issue/IssueHeader.tsx`, `modules/resources/ui/Maintenance/MaintenanceDispatchHeader.tsx`, `modules/inventory/ui/PickingLists/PickingListHeader.tsx`, `modules/inventory/ui/StockTransfers/StockTransferHeader.tsx`, `modules/production/ui/Procedures/ProcedureHeader.tsx`, `modules/resources/ui/Training/TrainingHeader.tsx`, `modules/quality/ui/Documents/QualityDocumentHeader.tsx`, `modules/production/ui/Assemblies/AssemblyInstructionHeader.tsx`.
+
+**Steps:** these are the same as Task 12, with these specifics:
+- **Item headers:** `aside={<DetailsTopbar links={…} />}`. Order becomes title · Copy · ⋯ · status (spec-approved).
+- **ChangeNotice / Issue / Maintenance:** the status moves after the ⋯ (spec-approved). ChangeNotice keeps its `line-through` span around the status.
+- **PickingList / StockTransfer / Procedure / Training / QualityDocument:** no `titleTo`.
+ - The badges that sat inside the Heading become `status`.
+ - The title is the live `displayName` where the file uses it.
+ - StockTransfer's inline `ViolationModal`s move after the header.
+- **Assembly:**
+ - `title={nameInput}` and no `copyValue`.
+ - `status={<>{statusBadge}{versionBadge}</>}`.
+ - The "edited by" span goes at the end of `status` with its `hidden lg:inline` class.
+ - Delete `{!isCompact && nameInput}` and `useCompact`.
+
+**Verify:**
+```bash
+cd apps/erp && npx tsgo --noEmit && cd ../.. && pnpm exec biome check <the 14 files>
+```
+**Out of scope:** `DetailsTopbar` internals (Task 8).
+
+## Task 14: Migrate other topbar headers and company cards (4)
+
+**Depends on:** 10, 11
+**Files:** `modules/quality/ui/Inspections/InspectionView.tsx`, `modules/workflows/ui/Builder/BuilderHeader.tsx`, `modules/sales/ui/Customer/CustomerHeader.tsx`, `modules/purchasing/ui/Supplier/SupplierHeader.tsx`.
+
+**Steps:**
+- **InspectionView:** keep its own desktop shell. Its markup (a raw `h1` with a wrapping meta line) doesn't match `RecordHeader`'s shell. Replace `<RecordChrome hero=…/>` with `<RecordHero subtitle={metaLine} status={statusBadge} />` + `<RecordPhoneChrome />`. It still passes its data once to each layout.
+- **BuilderHeader:** keep its `<header>` shell (topbar height, SaveMarker).
+ - Replace `RecordChrome` with `<RecordHero title={isCompact ? <WorkflowTitle …/> : undefined} status={…} />` + `<RecordPhoneChrome />`.
+ - The desktop renders `{!isCompact && <WorkflowTitle …/>}`, unchanged: the render-once rule is now expressed through `RecordHero`'s `title`, the same as RecordHeader.
+ - Keep `inHero` only if its styling is still needed in the hero. Check that `WorkflowTitle` renders correctly in the hero without it, and delete it if so.
+- **Customer / Supplier:** keep their Card markup. Replace `<RecordChrome menu copyValue/>` with `<RecordPhoneChrome menu={menuItems} copyValue={id} />`.
+
+**Verify:**
+```bash
+cd apps/erp && npx tsgo --noEmit && cd ../.. && pnpm exec biome check <the 4 files>
+```
+**Out of scope:** WorkflowTitle's rename logic.
+
+## Task 15: Migrate card forms, actions-only pages, fixed asset (9)
+
+**Depends on:** 10, 11
+**Files:** `modules/inventory/ui/Receipts/ReceiptForm/ReceiptForm.tsx`, `modules/inventory/ui/Shipments/ShipmentForm/ShipmentForm.tsx`, `modules/inventory/ui/WarehouseTransfers/WarehouseTransferForm.tsx`, `modules/invoicing/ui/Payment/PaymentForm.tsx` (+ `PaymentForm.test.tsx` mocks), `modules/invoicing/ui/Memo/MemoForm.tsx`, `modules/accounting/ui/JournalEntries/JournalEntryForm.tsx`, `routes/x+/fixed-asset+/$fixedAssetId.tsx`, `modules/inventory/ui/InventoryCount/InventoryCount.tsx`, `routes/x+/reimbursements+/$reimbursementId._index.tsx`.
+
+**Steps:**
+- **DocumentHeader callers:**
+ - Replace `<RecordChrome hero menu copyValue bleed />` with `<RecordHeroTarget bleed />` at the same spot. WarehouseTransfer: no `bleed`, at its current spot inside the Card.
+ - Pass `status`/`menuItems` straight to `DocumentHeader`.
+ - Drop `className="compact:hidden"`: DocumentHeader now owns it.
+ - Inline the hoisted `statusNode`/`menuItems` variables back if they are used once.
+- **JournalEntryForm:**
+ - Replace the hand-rolled CardHeader with `<DocumentHeader title={displayId} status={…} menuItems={isDraft || isPosted ? menuItems : undefined} actions={…} />` + `<RecordHeroTarget bleed />`.
+ - The desktop markup is the same: h3 heading, Copy, ⋯ and status. Check that the ⋯ IconButton's `type="button"` is preserved: DocumentHeader's IconButton defaults to `type="button"` through Button.
+- **InventoryCount / Reimbursement:** `<RecordChrome …/>` becomes `<RecordHero status={…} />` (InventoryCount) or nothing (Reimbursement), plus `<RecordPhoneChrome />`.
+- **PaymentForm.test.tsx:** update its mocks from `~/components/Layout/RecordChrome` to `~/components/Layout/RecordHeader`.
+
+**Verify:**
+```bash
+cd apps/erp && npx tsgo --noEmit && pnpm exec vitest run app/modules/invoicing && cd ../.. && pnpm exec biome check <the 9 files>
+# Expected: clean, tests pass
+```
+**Out of scope:** form validation and actions.
+
+## Task 16: Delete leftovers; Lingui extract
+
+**Depends on:** 12–15
+**Steps:**
+1. Delete `apps/erp/app/components/Layout/RecordChrome.tsx` and `apps/erp/app/modules/sales/ui/Quotes/RevisionSubtitle.tsx`.
+2. Run the grep below and fix every hit.
+3. Run `pnpm lingui:extract && pnpm lingui:clean`.
+
+**Verify:**
+```bash
+rg "RecordChrome|ChromeSlotsProvider|useChromeSlotTargets|useCompactSeed|CompactPanelProvider|COMPACT_MAX_WIDTH|RevisionSubtitle" apps packages --glob '!*.md' --glob '!*.po'
+rg "\[&_button\]|\[&_\.bg-destructive\]" apps/erp/app/components/Layout
+# Expected: both print nothing
+```
+
+## Task 17: End-to-end verification
+
+**Depends on:** all
+**Steps:**
+1. Run:
+ ```bash
+ cd packages/utils && npx tsgo --noEmit && pnpm exec vitest run
+ cd ../react && npx tsgo --noEmit && pnpm exec vitest run
+ cd ../../apps/erp && npx tsgo --noEmit && pnpm exec vitest run app/components app/modules/invoicing
+ cd ../mes && npx tsgo --noEmit
+ cd ../starter && npx tsgo --noEmit
+ cd ../.. && pnpm exec biome check $(git diff HEAD --name-only -- '*.ts' '*.tsx'; git ls-files --others --exclude-standard -- '*.ts' '*.tsx')
+ ```
+ Expected: all pass. Record any failure verbatim in the final report.
+2. Browser checks: the spec's acceptance criteria at 390px and at desktop width. These need the user's go-ahead to drive the browser; ask before starting.
+3. Tick the spec's acceptance criteria and add a Changelog line.
diff --git a/.ai/research/2026-10-07-record-header-catalogue.md b/.ai/research/2026-10-07-record-header-catalogue.md
new file mode 100644
index 0000000000..841ac058e9
--- /dev/null
+++ b/.ai/research/2026-10-07-record-header-catalogue.md
@@ -0,0 +1,109 @@
+# Record header catalogue (mobile redesign)
+
+Read-only survey of every call site of `RecordChrome` / `RecordAction` in the
+working tree (2026-10-07). It is input to `.ai/specs/2026-10-07-mobile-chrome-structure.md`.
+
+## Building blocks
+
+- **`RecordChrome`** (`apps/erp/app/components/Layout/RecordChrome.tsx`)
+ - Props: `hero {title, subtitle, status}`, `menu`, `copyValue`, `bleed` (`-mx-4 -mt-4`).
+ - It writes `--header-height` and `--hero-height` from the hero element.
+ - The app bar ⋯ shows "Copy ID" plus `menu`.
+ - The bottom bar has a primary cell, a secondary cell, and a ⋯ button. The ⋯ button opens the "Actions" BottomSheet when the overflow count is above 0.
+- **`RecordAction({slot})`**
+ - Desktop: renders its children in place.
+ - Phones: portals the children into the slot's zustand-held target and counts them.
+ - The overflow sheet closes when a `button` or `a` is clicked, unless the click is inside `[aria-haspopup]`.
+ - Sheet rows get their look from `[&_button]` / `[&_a]` overrides, plus `[&_.bg-destructive]:text-destructive` and `[&>*_button+button]:w-11` for the split-button chevron.
+- **`DocumentHeader`**
+ - Props: `{title: string, subtitle?, status?, menuItems?, actions?, className?}`. It renders `CardHeader` with an h3 heading, `Copy`, a ⋯ menu when there are items, the status, the subtitle and an actions HStack.
+ - This branch only added `className`.
+- **The common desktop ⋯ trigger** is `IconButton aria-label=t\`More options\` icon=LuEllipsisVertical variant="secondary" size="sm"`.
+
+## Call sites (38)
+
+**Shell A** (11): SalesOrder, Quote, SalesRFQ, SalesReturnOrder, PurchaseOrder, PurchaseReturnOrder, PurchasingRFQ, SupplierQuote, PurchaseInvoice, SalesInvoice, Job.
+- Class: `flex flex-shrink-0 items-center justify-between gap-x-4 p-2 bg-card border-b h-[var(--header-height)] overflow-x-auto scrollbar-hide compact:hidden`.
+- Left side: explorer toggle, Link > Heading h4 > id (plus `RevisionSuffix` in Quote and PO), Copy, ⋯, status.
+- Right side: actions, then the properties toggle.
+- Job has no `HStack w-full` wrapper.
+
+**Shell B** (14):
+- Members:
+ - 5 item headers: Material, Part, Tool, Service, Consumable.
+ - ChangeNotice, Issue, MaintenanceDispatch, PickingList, StockTransfer, Procedure, Training, QualityDocument, AssemblyInstruction.
+- Class: `flex flex-shrink-0 items-center justify-between gap-x-4 px-4 py-2 bg-card border-b border-border h-[var(--header-height)] overflow-x-auto scrollbar-hide compact:hidden`.
+- Item headers:
+ - Order: Link, Copy, status, ⋯. The right side holds `<DetailsTopbar links>`.
+ - They have 0 actions.
+ - On phones, DetailsTopbar registers the record tabs from inside the hidden shell.
+- Status-first order (status, Copy, ⋯): ChangeNotice, Issue, Maintenance.
+- Plain heading with no Link: PickingList, StockTransfer, Procedure, Training, QualityDocument.
+- Badges inside the Heading: Procedure, Training, QualityDocument.
+- Assembly:
+ - The title is a controlled `Input`, guarded by `{!isCompact && nameInput}`.
+ - It has no Copy.
+ - It has an "edited by" meta span.
+
+**Other topbar headers:**
+- InspectionView:
+ - Raw `h1`, status, and a `metaLine` subtitle.
+ - No Copy and no ⋯.
+- BuilderHeader:
+ - A `<header>` with `h-[var(--topbar-height)]`.
+ - The `WorkflowTitle` is stateful, guarded by `{!isCompact && …}`, with an `inHero` variant.
+ - It also has a lock indicator and a SaveMarker.
+
+**Company cards:** Customer, Supplier.
+- `CardTitle` with name, ⋯, then `Copy label icon`.
+- No hero. Supplier also has `CardAction` actions.
+
+**Card headers** (7):
+- Receipt, Shipment, WarehouseTransfer, Payment, Memo and FixedAsset use `DocumentHeader className="compact:hidden"`.
+- JournalEntryForm hand-rolls the same CardHeader.
+- `bleed` is set everywhere except WarehouseTransfer, which mounts RecordChrome inside the Card.
+- Payment and Memo mount RecordChrome inside the `ValidatedForm`.
+
+**Actions-only:**
+- InventoryCount:
+ - The actions live in the table header's `primaryAction`.
+ - The Notes action is an icon-only IconButton.
+- Reimbursement: `<RecordChrome />` with no props.
+
+## Facts that drive the design
+
+- `menu` and `copyValue` always equal the desktop ⋯ and `Copy text`. I found no mismatch.
+- `hero.title` is used only by Assembly and Builder.
+- `hero.subtitle` is used only by Quote and PO (`RevisionSubtitle`) and by Inspection (`metaLine`).
+- **Slot and variant duplicate each other:** 9 files compute a slot and then restate the same condition as the Button's `variant`.
+- **About 14 action pairs disagree**: the phone bar would show two filled buttons, or a primary-slot button styled secondary. The pairs:
+ - SO Invoice; Quote Lost; SalesRFQ No Quote.
+ - PI/SI Payment.
+ - Job Complete and Resume.
+ - Issue Complete; Maintenance Complete.
+ - PickingList Finish; StockTransfer Complete.
+ - WarehouseTransfer Shipments and Receive.
+ - Receipt Invoice and Post; Shipment Packing Slip.
+ - Builder Unpublish; Inspection Add Sample.
+- PO alone patches its mismatch with `isCompact`.
+- **Non-Button action children:**
+ - DropdownMenu triggers.
+ - `fetcher.Form`, `<form>`, `<Form>`.
+ - SplitButton (PO Finalize, Job Release).
+ - PrintButton, which owns its own Modal.
+ - Tooltip wrappers.
+ - Suspense/Await, including VersionMenu with `fallback={null}`.
+ - Assignee, a raw `<button>` built from `buttonVariants`.
+ - An icon-only IconButton.
+- **Hazards:**
+ 1. The item headers' DetailsTopbar must stay mounted on phones.
+ 2. Modals sit inside the hidden shell in 12 files.
+ 3. PrintButton sits in the overflow slot, so its Modal unmounts when the sheet closes.
+ 4. RecordAction counts children that render null, which can open an empty sheet.
+- **Button**
+ - It reads no context itself; it gets OperatingSystem context indirectly through `useShortcutKeys`.
+ - `IconButton` wraps Button.
+ - `bg-destructive` only comes from `buttonVariants.variant.destructive`.
+- **SplitButton**
+ - It is a `div.flex` holding two Buttons, and the chevron is a Radix trigger with `aria-haspopup`.
+ - Its `disabled` prop is declared but never used.
diff --git a/.ai/specs/2026-10-07-mobile-chrome-structure.md b/.ai/specs/2026-10-07-mobile-chrome-structure.md
new file mode 100644
index 0000000000..3754ce8837
--- /dev/null
+++ b/.ai/specs/2026-10-07-mobile-chrome-structure.md
@@ -0,0 +1,267 @@
+# Mobile chrome: one compact signal, one record header, one slot primitive
+
+> Status: in-progress
+> Author: Claude (with the branch owner)
+> Date: 2026-10-07
+
+## TLDR
+
+The mobile redesign works, but its phone chrome is built three times over:
+- **The breakpoint:** "is this a phone?" is answered by two hooks and two breakpoint units.
+- **Record headers:** every record header writes its desktop header and its phone header separately, and is wired to the phone bar by 149 hand-placed wrappers.
+- **Registries:** five separate registries move content into the shell.
+
+This spec merges each of these into one mechanism and keeps behaviour the same:
+- one compact signal (B3);
+- one `RecordHeader` that renders the desktop row and the phone chrome from one set of props (B1);
+- one slot module with two primitives, a portal slot and a value slot, which replaces the five registries (B2).
+
+Research: `.ai/research/2026-10-07-record-header-catalogue.md`.
+
+## Overview diagram
+
+```mermaid
+flowchart LR
+ subgraph Today
+ H["*Header.tsx"] --> RC["RecordChrome (hero, ⋯, bar)"]
+ H --> DS["hand-built desktop shell"]
+ H --> RA["149 × RecordAction → zustand targets"]
+ DT["DetailsTopbar"] -- effect --> PC["PanelContext.recordTabs"]
+ P["pages"] --> OV["override store"]
+ P --> CS["ChromeSlots context + count store"]
+ end
+ subgraph After
+ H2["*Header.tsx"] --> RH["RecordHeader (one prop set)"]:::new
+ RH --> PS["portal slots"]:::new
+ DT2["DetailsTopbar"] --> VS["value slots"]:::new
+ P2["pages / NewRecordPage"] --> VS
+ end
+ classDef new stroke-dasharray:4 3
+```
+
+## Problem Statement
+
+Each item below cites the file and line where the problem is.
+
+1. **"Compact" has several sources of truth.**
+ - The breakpoint is written twice. JS uses `(max-width: 767px)` (`packages/utils/src/viewport.ts:15-17`). CSS uses `width < 48rem` (`packages/config/tailwind/theme.css:19,33,448`).
+ - The opt-in is written twice: the `data-compact-ui` attribute (`apps/erp/app/root.tsx:260`) and `CompactProvider enabled` (`root.tsx:346`).
+ - There are two hooks: `useCompact` (built on useSyncExternalStore) and `useIsMobile` (built on useState plus an effect, and seeded through `useCompactSeed`).
+ - In the ERP, `isMobile === isCompact` always. That makes the `useIsMobile` branches dead code: the Panels drawer branch at `Panels.tsx:279-327` sits behind `if (isCompact)` at `:268`.
+2. **Every record header is built twice.**
+ - The duplication: 27 topbar headers render `<RecordChrome hero menu copyValue>` and also a hand-written `compact:hidden` desktop shell, passing the same title, Copy value, ⋯ menu and status to both. The catalogue found no case where the two disagree, which shows they are pure duplication.
+ - Stateful titles need `{!isCompact && …}` guards so they don't mount twice (Assembly, Builder).
+ - The overflow sheet restyles other components' buttons with CSS selectors such as `[&_button]…` and `[&_.bg-destructive]` (`RecordChrome.tsx:106-117`).
+ - The sheet closes through a native capture listener, a `setTimeout` and an `aria-haspopup` heuristic (`RecordChrome.tsx:138-154`).
+ - In about 14 actions, the phone slot and the desktop variant disagree, so the bar shows two filled buttons or a main cell styled grey. PO patches this with an `isCompact` branch (`PurchaseOrderHeader.tsx:238-243`).
+3. **Five registries do one job.**
+ - The five:
+ - ChromeSlots, a context holding `useState` targets, plus a separate zustand count store.
+ - RecordChrome's zustand target and count store.
+ - The app-bar override store.
+ - `recordTabs`, pushed into PanelContext from an effect keyed on a hand-serialised `linksKey`.
+ - `CompactPanelProvider` / `inert`, which exist only to give phones that registry.
+ - On top of that, the app bar marks `/new` routes as pushed with a pathname rule (`useAppBar.ts:34-42`).
+ - Two routes copy the app bar's Back button JSX word for word (`issue-workflow+/new.tsx:82`, `inventory+/quantities+/$itemId.tsx:110`).
+
+## Proposed Solution
+
+### B3 — one compact signal
+
+- **The query:** `viewport.ts` exports one query, `COMPACT_QUERY = "(width < 48rem)"`. It is the same string Tailwind and `theme.css` use. `COMPACT_MAX_WIDTH` is deleted, and the inline cookie-hint script keeps using `COMPACT_QUERY`.
+- **The hooks:** `Compact.tsx` owns one `subscribe`/`getSnapshot` pair over that query.
+ - `useCompact()`: a `CompactProvider` is present and the query matches.
+ - `useIsMobile()`: the query alone, with no opt-in. It moves into `Compact.tsx` on the same store:
+ - its server snapshot is the provider's `initialCompact`, else `false`, so MES and starter keep getting `false` before hydration, as `!!isMobile` returned before;
+ - `useCompact()` is `useIsMobile()` plus the provider check;
+ - `hooks/useIsMobile.ts` re-exports it.
+ - `useCompactSeed` is deleted.
+- **The provider:** `CompactProvider` loses its `enabled` prop. Its presence is the JS opt-in. `root.tsx` sets `data-compact-ui` on the same element tree, with a one-line comment linking the two, and those are the only two opt-in sites.
+- **ERP callers of `useIsMobile`:**
+ - `Panels.tsx`:
+ - the `PanelProvider` collapse effect switches to `isCompact`, which is the same value, so behaviour is identical;
+ - the drawer branch and its pathname-collapse effect are deleted.
+ - `CollapsibleSidebar.tsx`: its `wasMobile` effect switches to `isCompact` if the stored-open behaviour across the breakpoint is still wanted, and is deleted if it only served the removed drawer. The plan step reads it and records which.
+ - `Breadcrumbs.tsx`: its `!isMobile` branches are deleted. Breadcrumbs only renders when `Topbar` is not compact.
+
+### B1 — one record header
+
+**`RecordHeader`** (`apps/erp/app/components/Layout/RecordHeader.tsx`) replaces `RecordChrome` and the hand-built shells.
+
+```tsx
+<RecordHeader
+ title={id} // ReactNode; rendered once per breakpoint
+ titleTo={path.to.xDetails(id)} // optional Link
+ copyValue={id} // optional; desktop <Copy> + app-bar "Copy ID"
+ menu={menuItems} // optional; desktop ⋯ + app-bar ⋯
+ status={badges} // optional; desktop row + hero
+ subtitle={metaLine} // optional; hero (and desktop under the title)
+ onToggleExplorer={toggleExplorer} // optional leading IconButton
+ onToggleProperties={toggleProperties} // optional trailing IconButton
+ aside={<DetailsTopbar links={…} />} // optional right-hand node (item tabs)
+ actions={<>…RecordActions…</>}
+/>
+```
+
+**Desktop shell**
+- It is rendered from the props in one fixed order: leading toggle, title, Copy, ⋯, status, then on the right side the aside, actions and trailing toggle.
+- Padding comes from whether there is a toggle:
+ - with a toggle at an edge, it is `p-2` at that edge (shell A);
+ - otherwise `px-4 py-2` (shell B).
+ - So no padding prop is needed.
+- **Stays mounted on phones:** the shell is still rendered there, hidden with `compact:hidden`. That keeps its modals, `DetailsTopbar` and the action portals alive.
+- **Rendered once:** `title` goes into the shell only on desktop and into the hero only on phones. That replaces the `{!isCompact && …}` guards.
+
+**Phone chrome**
+- The hero holds `subtitle` and `status`, in place, with `--header-height` / `--hero-height` published as today. The app bar already names the record, so the hero shows `title` only when the caller sets `titleInHero` (an editable title, such as Assembly's name input).
+- The app bar ⋯ holds "Copy ID" and `menu`.
+- The bottom bar holds the primary cell, the secondary cell and the ⋯ button for the overflow sheet.
+- The hero, bar and sheet move into the `RecordPhoneChrome` part, which `RecordHeader` and the card header share.
+
+**`RecordAction`**
+- It keeps `slot: "primary" | "secondary" | "overflow"`, and its children stay JSX. That includes `fetcher.Form`, SplitButton, PrintButton, Suspense/Await and DropdownMenu triggers.
+- On phones it fills the matching portal slot (B2) and provides a **presentation context** to what it wraps:
+ - `bar-primary`: Button renders as `variant="primary" size="lg" w-full`, whatever `variant` it was given;
+ - `bar-secondary`: the same, with `variant="secondary"`;
+ - `row`: Button renders as an action-sheet row (`h-12`, start-aligned, transparent, 15px). A `destructive` variant becomes destructive text. After its own `onClick` runs, the Button calls the context's `onSelect()` to close the sheet, unless it is a popup trigger (`aria-haspopup`).
+ - `SplitButton` reads the same context: its chevron becomes a 44px cell.
+ - This replaces the `[&_button]` / `[&_.bg-destructive]` selector overrides and the native listener.
+ - The close is deferred to the next task, so a submit button's form is still mounted when the browser submits it. A comment keeps that reason.
+ - Controls that are not a Button render unchanged in the sheet: the Assignee popover trigger, and children that render null.
+
+**Overflow sheet:** each portal slot owns its DOM element, and the slot's `Target` only shows that element. The sheet body is the overflow `Target`. When the sheet closes, the actions stay mounted in the detached element, so a `PrintButton` keeps its Modal. This fixes catalogue hazard 3. (Radix `forceMount` cannot do this: a closed, force-mounted modal Dialog still hides the rest of the app and blocks its pointer events.)
+
+**Card headers**
+- `DocumentHeader` (the card variant) takes the same props: `title`, `subtitle`, `status`, `menu`, `actions`, and `copyValue` defaulting to `title`.
+- On phones it hides its `CardHeader` and renders the hero through a `recordHero` portal slot.
+- The 6 callers, plus `JournalEntryForm`'s hand-rolled copy, replace `<RecordChrome …/>` with `<RecordHeroTarget bleed />`. That keeps the hero where it renders today: outside the Card, full-bleed. The data is passed once.
+
+**Actions-only pages** (InventoryCount, Reimbursement) render `<RecordPhoneChrome />` (the bar only) in place of `<RecordChrome />`.
+
+**Per-header cleanup:** when a header's slot and variant restate one status condition, the condition is named once (`const isDraft = …`) and used for both. Desktop variants do not change. PO's `isCompact` variant branch is deleted, because the bar cell now sets the style.
+
+**Deleted:**
+- `RecordChrome` and its zustand store;
+- `RevisionSubtitle`: Quote and PO build the `id` + `RevisionSuffix` node once and pass it as `title` and, when the revision is above 0, as `subtitle`. The phone shows the same subtitle as before.
+- `WorkflowTitle` keeps its `inHero` styling, because the hero still renders it with hero styles.
+
+### B2 — one slot module
+
+`apps/erp/app/components/Layout/Mobile/slots.tsx` exports two primitives.
+
+```ts
+// Content that renders inside the shell: React context is preserved by a portal.
+createPortalSlot(): {
+ Target: (props: ComponentProps<"div">) => JSX.Element; // stable ref, one target
+ Fill: (props: { children: ReactNode }) => ReactPortal | null; // compact only, counted
+ useFilled: () => boolean;
+}
+// Data a page hands the shell; newest provider wins, unmount removes only its own.
+createValueSlot<T>(): {
+ useProvide: (value: T | null) => void; // caller memoizes `value`
+ useValue: () => T | null;
+}
+```
+
+**Portal slots:**
+- **`appBarActions`** replaces `AppBarActions` and `ChromeSlotsProvider`. Its consumers: `New`, `CompactToolbar`, ChartOfAccounts filters and WorkflowBuilder.
+- **`bottomBar`**: the tab bar hides while it is filled.
+- **The record slots:** `recordPrimary`, `recordSecondary`, `recordOverflow`, `recordHero`.
+- **Deleted:** `ChromeSlotsProvider`, `useChromeSlotTargets`, the BottomBar count store, RecordChrome's store and its module-level ref callbacks.
+
+**Value slots:**
+- **`appBar`**: the override, typed as `Partial<AppBarState> & { trailing?: ReactNode }`.
+ - `AppBarState.kind` gains `"selection"` for list selection mode, which hides the page actions, the section switcher and the subtitle.
+ - `MobileAppBar` merges the override over `useAppBar()` and always renders Back from the merged `kind: "pushed"` + `backTo`.
+ - **Deleted:** `leading`, both copied Back buttons, and the `useAppBar` `/new` pathname rule.
+- **`NewRecordPage`** provides `{ kind: "pushed", backTo: <last crumb's to> }`. The plan audits every full-page `/new` route and moves any that does not render `NewRecordPage` onto it, so none loses its Back button.
+- **`recordTabs`**:
+ - `DetailsTopbar` provides plain tab data `{ name, to, count, active }`, with `active` computed from the location it already reads, so no closures are stored.
+ - `CompactRecordTabs` reads it, and also provides a `recordFrame` value (`true`) that `DetailsTopbar` reads to decide whether to render its own row.
+ - This removes `recordTabs`/`setRecordTabs` from `PanelContext`, `CompactPanelProvider`, `PanelProvider`'s `inert`, and the `linksKey` effect. The item routes go back to their `HEAD` providers.
+
+### Design Decisions
+
+| Decision | Choice | Rationale |
+|----------|--------|-----------|
+| Breakpoint unit | `(width < 48rem)` in JS | Matches Tailwind/theme.css exactly; rem follows the user's default font size like the CSS already does. Range syntax needs Safari 16.4+, which the Tailwind v4 CSS already requires |
+| `useIsMobile` semantics | viewport only, no opt-in, `false` before hydration without a provider | The old hook returned `!!isMobile`; keeps MES/starter/`Sidebar`/`FunnelChart` behaviour; ERP gets the seeded first frame as today |
+| JS opt-in | provider presence | One flag fewer; the `enabled={false}` case has no caller |
+| Header actions API | JSX + `RecordAction slot` + presentation context | User choice: keeps Suspense/Await, forms, PrintButton working; removes CSS reach-in and native listener |
+| Slot vs desktop variant | slot stays explicit; phone bar cell decides style; desktop variants untouched | User choice; no desktop change; the 14 mismatches stop showing on phones |
+| Desktop element order | title · Copy · ⋯ · status (fixed) | One shell instead of 8 orderings; the reordering is small and visible only on desktop (see Risks) |
+| Card forms | `DocumentHeader` + `RecordHeroTarget` placement | Keeps the phone hero full-bleed above the Card and the desktop CardHeader inside it, with data passed once |
+| Popup scope | Modal, Drawer, BottomSheet, Popover, HoverCard, DropdownMenu and ContextMenu contents reset the presentation | React context crosses portals: without the reset, a dialog an action opens (PrintButton) would render its buttons as sheet rows. The old CSS selectors never reached portalled content |
+| Overflow sheet mount | each portal slot owns its DOM element; `Target` only shows it | Radix cannot keep a closed modal sheet mounted (`hideOthers` and `disableOutsidePointerEvents: true` would block the app, `@radix-ui/react-dialog` 1.1.15 `index.mjs:137,145`). An owned element keeps PrintButton's Modal alive when the sheet closes, with no per-action rules |
+| Slot primitives | portal slot + value slot | Portals keep the filler's React context (forms, menus); data slots need no DOM |
+| Create pages' Back | `NewRecordPage` declares it | User choice; replaces the `/new` URL rule |
+| CSS height vars | unchanged | Moving to pure flex layout is review section C, out of scope |
+
+## Data Model Changes
+
+N/A: this is a UI-only refactor with no tables, columns or migrations.
+
+## API / Service Changes
+
+N/A: no loaders, actions or services change. These public package APIs do change:
+- `@carbon/react`:
+ - `CompactProvider` loses `enabled`;
+ - `useCompactSeed` is removed;
+ - `useIsMobile` now comes from `Compact.tsx`, with the same export name;
+ - Button and SplitButton read an optional presentation context, so behaviour is unchanged without a provider.
+- `@carbon/utils`: `COMPACT_MAX_WIDTH` is removed.
+
+## UI Changes
+
+- **Desktop:** every topbar record header renders the same elements, with one change: in 11 headers the order becomes title · Copy · ⋯ · status. Those headers are the 5 item headers, ChangeNotice, Issue, Maintenance, Procedure, Training and QualityDocument. Variants, actions and modals are unchanged.
+- **Phones:**
+ - The bar's main cell is always filled and the second cell always outline.
+ - Sheet rows look as they do today.
+ - The sheet keeps PrintButton's dialog alive.
+ - Quote and PO keep `id` + revision as the hero subtitle.
+ - Create pages and the quantities/issue-workflow screens keep their Back button.
+
+## Acceptance Criteria
+
+- [ ] `rg "RecordChrome|ChromeSlotsProvider|useChromeSlotTargets|useCompactSeed|CompactPanelProvider|COMPACT_MAX_WIDTH|RevisionSubtitle" apps packages` returns nothing (code only; docs excluded).
+- [ ] `rg 'endsWith\("/new"\)' apps/erp/app/components/Layout` returns nothing, and `useAppBar.ts` has no pathname rule.
+- [ ] `rg "\[&_button\]|\[&_\.bg-destructive\]" apps/erp/app/components/Layout` returns nothing.
+- [ ] `rg "useIsMobile" apps/erp` returns nothing.
+- [ ] At 390px on a Sales Order in "To Ship and Invoice", the bar shows Ship filled, Invoice outline and ⋯. On desktop the same order shows both Ship and Invoice as primary, as before.
+- [ ] At 390px on a Receipt, ⋯ → Print → the print dialog stays open after the sheet closes.
+- [ ] At 390px on a Purchase Order, tapping ⋯ → Cancel Order closes the sheet and opens the cancel dialog. Tapping ⋯ → Preview opens its menu and keeps the sheet.
+- [ ] At 390px, `/x/customer/new` shows Back to Customers, and a list in selection mode shows "N selected" with Cancel and no page actions.
+- [ ] At 390px on a Part, the record tab row shows Details/Purchasing/… plus Properties. At desktop width, the Part's DetailsTopbar renders as before.
+- [ ] At 390px an Assembly Instruction's name input appears once (in the hero) and saves on blur.
+- [ ] `pnpm exec turbo run typecheck --filter=erp --filter=@carbon/react --filter=@carbon/utils` passes. Biome is clean on the changed files. The erp `Layout`/`Table` tests, the react tests and `viewport.test.ts` pass. `appBar.test.ts` covers the merged override and the `selection` kind.
+- [ ] Every new user-facing string uses Lingui, and `pnpm lingui:extract` has been run.
+
+## Risks
+
+| Risk | Severity | Mitigation |
+|------|----------|------------|
+| Desktop order change in 11 headers is unwanted | Low | Called out here for review at the spec gate. If it is rejected, a `statusPlacement` prop is the fallback |
+| A Button-like control in the sheet that is not a `Button` (Assignee) doesn't close the sheet | Low | It is a popup trigger, which keeps the sheet open today too; listed in the plan's browser checks |
+| Range-syntax media query on old iOS (< 16.4) | Low | The compact CSS already uses range syntax; JS now fails the same way the CSS does, rather than differently |
+| A full-page `/new` route without `NewRecordPage` loses its Back button | Med | The plan audits every `routes/**/new.tsx` and its siblings; acceptance check at `/x/customer/new` |
+| 38 call sites migrated in one pass | Med | Migrate in batches by shell kind, with typecheck after each; desktop and 390px screenshots of one header per batch (needs the user's go-ahead to drive the browser) |
+
+## Open Questions
+
+- [x] Does "all" cover the C/D review sections too? — **Answer:** No. B1–B3 now, and C/D in a later pass, because several depend on B.
+- [x] How are header actions written? — **Answer:** As JSX with a presentation context: one `RecordHeader` owns both layouts, and Button reads the context to render as a bar cell or a sheet row.
+- [x] How does a create page declare that it shows Back? — **Answer:** `NewRecordPage` declares it, and the `/new` URL rule is deleted. Full-page create routes are audited and moved onto it.
+- [x] Phone slot and desktop variant disagree in about 14 actions: which wins? — **Answer:** Phone styling only. The slot stays, the bar cell decides the phone style, and desktop variants don't change.
+
+## Changelog
+
+- 2026-10-07: Draft written after the four questions above were resolved.
+- 2026-10-07: Implemented (uncommitted). Changes from the draft:
+ - `useIsMobile` returns `false` before hydration, as the old hook did.
+ - Portal slots own their DOM element, in place of Radix `forceMount` (see Design Decisions).
+ - Popup contents reset the action presentation.
+ - The hero title is opt-in (`titleInHero`).
+ - Selection mode shows no Back button.
+ - A create page whose app bar was already pushed now goes Back to its list (its last crumb), not to the module.
+ - The `/new` audit found no full-page route outside `NewRecordPage` (`.ai/runs/2026-10-07-new-route-audit.txt`).
+- 2026-10-07: The inline `<head>` cookie script is removed. `CompactProvider` writes the compact hint cookie on mount and on each breakpoint crossing (`compactHintCookie` in `viewport.ts`), so one place watches the width per app.