margin/simplify/.research/frontend-utils.md

# Non-component TypeScript across the four apps

Scope: hooks, utilities, stores, the IPC layer. Non-test `.ts`: margin 4061 lines, margin-calendar 3811,
margin-docs 16868, margin-mail 11429. Shorthand: **M** margin, **C** margin-calendar, **D** margin-docs,
**X** margin-mail.

## The shared package already exists

`margin-shared` is at `/Users/pj/Workspace/projects/python/margin/shared`: a `file:` dependency of M, D and X,
exporting `.`, `./fonts`, `./icons` and two stylesheets, 299 lines of source today.

**C is not wired to it at all**, in TypeScript or CSS. It has no `margin-shared` in `package.json` and its
`src/styles/tokens.css` does not `@import "margin-shared/css/tokens.css"` the way the other three do. That
dependency line is the prerequisite for everything here.

**The extraction pattern is already proven.** `M/src/model/fonts.ts` (41 lines) and `D/src/model/fonts.ts`
(40) are re-export shims: pull the catalogue from `margin-shared/fonts`, declare one app-local alias
(`BookFonts` vs `DocumentFonts`) so call sites keep the app's own noun. Copy that shape.

No app uses tsconfig path aliases, so nothing needs build config beyond the dependency. All three vitest apps
run `environment: "node"`, so shared hooks need the `typeof window` guards D already writes, or
`vi.stubGlobal` as in `D/src/width.test.ts:24`. No app has a `utils/`, `lib/`, `helpers/` or `hooks/`
directory: everything is either a single-purpose top-level module or defined inline atop the one component
that needs it.

## Byte-identical today

**`src/escape.ts`**, all four. 36 lines in M, C and D, all three md5 `3b1f67d691647be7d61a23a5acd96a7b`. X's
is 40 lines, differing only by a four-line header; strip comments and all four hash identically
(`9c8530a09b35e5d697bb2b95674a2e73`). Signature `useEscapeLayer(active: boolean, onEscape: () => void): void`,
a module-level stack of Escape handlers behind one lazily-bound capture-phase listener. Move verbatim, keeping
X's header. 144 duplicated lines, zero risk. All three keyboard registries already defer to it by name rather
than handling Escape themselves, and its `const latest = useRef(onEscape); latest.current = onEscape;` is an
inline `useLatest` that falls out of the extraction for free.
**`useMediaQuery`**, all four `src/useMedia.ts`, byte-identical (`c3499ac5ee3d1a12b138d71b2cc787ed`).
**`usePhone` and `useTouch`**, C/D/X, byte-identical bodies (`d565f08a...`, `f4285e4c...`), with `PHONE_QUERY
= "(max-width: 640px)"` and `TOUCH_QUERY = "(pointer: coarse)"`; the only difference between the three files
is prose describing each app's layout. M has neither, only a stale `useCompact` on a 899px query that D
deleted when it added the phone/touch pair.

**`src/theme.ts`**, M/C/X. Strip comments, normalise the key, all three hash identically
(`ab9c99ff29565c686028e16960274d9d`); the literal M-to-C diff is one line. **`src/store/useTheme.ts`**, M and
C, byte-identical (`b48a3bccfadd21b9bb4efa91eef5041c`, 16 lines); X's 17 differ only by extracting a
`set(theme)` action. **`src/store/useToast.ts`**, C and D, byte-identical (`dfc90357bbcfbbfe71ffb8ba0e680c00`,
15 lines). M has no toast.

**The `src/ipc.ts` preamble.** Lines 1 to 41 of C's and D's are byte-identical
(`afde11927f75a3a81b2b459658c5b7be`), doc comments included: header, `isTauri`, `isMobileOs` with its iPadOS
carve-out, `isDesktop`, `isMacDesktop`, `live()`. So is the body of `call<T>`
(`b4259488afdd6a0f154b8e86eae1ff9c`). X has the same code with two comments abridged, plus one real addition
at `X/src/ipc.ts:752-758`: it logs a failed command to Rust before rethrowing, skipping `log_note` itself to
avoid a loop.

**`src/store/useOverlays.ts`**, C (64 lines) and X (72). Diffed with comments stripped, the entire difference
is the `Overlay` union and one prettier reflow of `push`; all seven actions are character-identical. X's
header: "Ported from the calendar's store of the same name."

**The keys platform block**, C/D/X, not one character differing, at `C:76-87`, `D:206-217`, `X:521-532`. Also
byte-identical across those three: the `NAMED` glyph map, `commandMatches`, `isTyping`, and
`pushContext`/`useKeyContext`.

```ts
const isMac = typeof navigator !== "undefined" && /mac|iphone|ipad/i.test(navigator.userAgent ?? "");
export const PRIMARY_LABEL = isMac ? "⌘" : "Ctrl+";
export const primaryHeld = (e: { metaKey: boolean; ctrlKey: boolean }): boolean =>
  isMac ? e.metaKey : e.ctrlKey;
export const secondaryHeld = (e: { metaKey: boolean; ctrlKey: boolean }): boolean =>
  isMac ? e.ctrlKey : e.metaKey;
```

## The three cleanest lifts

**`createOverlays<T>()`.** Nothing in the body knows what an overlay is. Each app writes `export const
useOverlays = createOverlays<Overlay>();` and keeps its own union. About 130 lines at zero behavioural risk. M
and D have no overlay store but both have palettes and dialogs and would adopt it.

```ts
export interface OverlayState<T extends string> {
  open: T | null;
  trail: T[];
  show: (overlay: T) => void;
  push: (overlay: T) => void;
  back: () => void;
  reachedFrom: (previous: T) => void;
  toggle: (overlay: T) => void;
  close: () => void;
}
export function createOverlays<T extends string>(): UseBoundStore<StoreApi<OverlayState<T>>>;
```

**`onAppEvent`.** Nobody wraps Tauri's `listen`, and it shows. X is the exception, at `X/src/App.tsx:69-77`,
signature `onAppEvent<T>(name: string, handler: (payload: T) => void): () => void`. It returns a synchronous
unsubscribe, so each effect is one line, and it falls back to `window.addEventListener` for a `CustomEvent` of
the same name outside Tauri, which is what lets Playwright drive the connect flow in a browser. C hand-rolls a
four-`.then(stop => stop())` teardown at `C/src/App.tsx:52-86`; D uses a third pattern, a module exporting
`startWorkspaceEvents(): () => void` that the shell mounts (`D/src/workspace.ts:366-378`).
The event names are already common property: `menu-action` in all four, `auth`, `sync-progress` and
`store-changed` in C and X, `pdf-warnings` in M and D. Four apps, the same names, three subscription
mechanics. Lift X's nine lines; keep D's "module exports `start*()`" convention on top.

**`useToast` and `notify`.** X's 34 lines beat the byte-identical 15 in C and D. Strict superset: an optional
`ToastAction { label, keycap?, run }` for undo, and a `seq` counter bumped on every notice. That counter is a
real fix. Auto-dismiss lives in the component in all three, and C's and D's dismiss effects omit a nonce from
the dep array, so notifying the same string twice does not restart the countdown; the second toast inherits
the remainder of the first one's timer. The dwell times also differ for no reason: 5000ms, 4200ms, 6000ms.
M has no toast, only a private `notify` at `M/src/store/useBackup.ts:45` writing into `useBook`'s notice field.

## Theme: margin-docs wins, and it is not close

`D/src/theme.ts` is 167 lines against 16, and every extra line earns it: a seven-palette table with a `scheme`
per row; a real tri-state `ThemeChoice = Theme | "system"` with a remembered light/dark pair;
`storedPreference()` dropping a stored id that no longer names a theme (without it, a palette retired between
releases leaves the root with a `data-theme` no stylesheet answers, which is not one broken colour but all of
them); `watchSystemScheme()`, the only live `prefers-color-scheme` subscription in any app;
`saved()`/`store()` guarding `localStorage` behind `typeof` and `try`/`catch`; and `theme.test.ts` (172
lines), the only theme test, holding the TypeScript table and the boot script's copy of it to one table.

X fakes a tri-state at the UI layer: "System" means deleting the stored key (`forgetThemeChoice()`,
`X/src/appearance.ts:41`), so it is a snapshot, not a subscription. Pick System at night and it stays dark
through the morning.

```ts
export interface ThemeConfig<T extends string> {
  themes: readonly ThemeInfo<T>[];
  keyPrefix: string;
  fallback: Record<Scheme, T>;
}
export function createThemeStore<T extends string>(config: ThemeConfig<T>): ...;
export function bootScript<T extends string>(config: ThemeConfig<T>): string;
```

Generating the boot script from the same config is the part to insist on. All four apps hand-maintain an
inline `<script>` in `index.html` re-reading the theme keys before the bundle exists, and D re-encodes its
whole palette-to-scheme table there in plain JS.

## The root-setting pattern, six times over

Bigger than theme. Read a boot attribute first because `index.html` already applied it, fall back to
`localStorage`, apply to the root, write back. `src/theme.ts` in all four on `data-theme`; `X/src/pane.ts` (20
lines) on `data-no-pane`, its header saying it is "exactly the shape `src/theme.ts` uses"; `D/src/width.ts`
(52) on `data-width`; `M/src/width.ts` (28) doing the same job through a `--measure` custom property;
`M/src/panes.ts` on `--pane-sidebar`/`--pane-dock` with its own private `clamp`; `X/src/appearance.ts` (43) on
`--font-ui`, `--font-heading` and `--body-size`.
The rule these obey is stated three times in three files: a store may not touch the DOM, and a layout fact the
stylesheet needs on first paint has to be an attribute, not a class on a component. Write it down once.
Key naming is already strict: every key in every app is `<slug>-<setting>`, slugs `margin-`, `margincal-`,
`margindocs-`, `marginmail-`. Counted: 8 keys in M, 6 in C, 17 in D, 9 in X. That prefix is the only per-app
parameter a storage helper needs.

```ts
export function makeStorage(prefix: string): {
  readString(key: string, fallback: string | null): string | null;
  readJson<T>(key: string, fallback: T): T;
  write(key: string, value: string): void;
  remove(key: string): void;
};
export function rootSetting<T extends string>(opts: {
  attribute: string; key: string; values: readonly T[]; fallback: T;
}): { initial(): T; apply(value: T): void };
```

D has written the guarded accessor pair nine times inside one app: `theme.ts:105`,
`store/useUpdate.ts:64,73,85`, `store/useProofing.ts:102,111`, `store/useDocumentFonts.ts:58,77`,
`workspace.ts:60,70`, `width.ts:33`, with the catch comment ("A webview with storage denied still X, it just
forgets between launches") repeated four times with only the verb swapped. Adopting it also fixes unguarded
reads in `M/theme.ts:8`, `C/time.ts:16`, `C/store/useCalendarView.ts:13`, `X/theme.ts:13`, `X/pane.ts:14` and
`D/Outline.tsx:30`; several run during module initialisation and would take the whole app down on a throw in a
storage-denied webview, and C's is already why `components/overlayModel.test.ts:20-31` stubs a global.

Do not reach for zustand's `persist` middleware, nor a `useLocalStorage` hook: the boot script reads these
keys before any bundle exists, so the shapes must stay plain and hand-chosen. `X/pane.ts:1-8` and
`X/appearance.ts:1-7` both document the constraint. `width.ts` itself should not be shared either. M has four
named widths on a CSS variable, D five on an attribute plus command wiring; only the persistence overlaps, and
`rootSetting` covers it.

## The IPC layer

Uniform in three of four and worth stating as the target: a frozen `src/ipc.ts` holding DTOs mirroring
`src-tauri/src/dto.rs` plus `call<T>`, and thin per-domain modules in `src/api/` doing nothing but naming a
command, e.g. `export const labelsList = (accountId: string | null) => call<LabelInfo[]>("labels_list", {
accountId });`

C has 6 api modules and 41 lines, D 9 and 211, X 16 and 386. X's `ipc.ts` is 760 lines because it has the most
DTOs, not because it is structured differently. Only X states the rule explicitly ("Nothing outside src/api
may call `call` directly").

M is the outlier. No `src/api`, `invoke` imported directly in 7 files and called at 8 sites. Its 43-line
`ipc.ts` has no `isTauri`, no `live()`, no `isMacDesktop` and no dev-fixture branch, which is why it has no
browser dev harness either. **And a real bug**: `M/src/ipc.ts:3` names its constant `isDesktop` but computes
what C/D/X call `isTauri`. The same identifier means the opposite thing in different apps, and in M it gates
`runWritingTool`, `listSystemFonts` and `gdriveListBackups`. M is desktop-only today so it does not bite yet.

Shareable: the whole preamble plus `call<T>` as a factory, since the dynamic `import("./dev/mockIpc")` path is
necessarily per-app. X's version wins, a strict superset of the byte-identical C and D; the `log_note`
recursion guard is the detail nobody would re-derive. DTOs stay per-app. `C/src/ipc/` exists and is empty;
delete it.

## The dev harness

C, D and X each have `src/dev/fixture.ts` and `src/dev/mockIpc.ts`: 134/222 lines, 696/344, 1769/1572. Every
`mockCall` is `(command: string, args?: Record<string, unknown>) => Promise<T>`, a switch on `command` ending
in the same byte-identical `dev mock has no handler for ${command}` throw, but the bodies are entirely
app-specific. A `createMockIpc(handlers)` supplying the dispatch and default throw is marginal; the real
shared pieces are the mock branch inside `call<T>` and X's `onAppEvent` fallback, both covered above. M has
no dev harness and cannot be driven in a browser.

## Keyboard: three registries, one design, no chords

C, D and X each have `src/keys` with `bindings.ts`, `keymap.ts`, `commands.ts`, `menu.ts`. No file is
byte-identical, but the scaffolding is one module forked three ways and several blocks inside are identical
(listed above).

**X's registry should win.** Three reasons that matter.

Its `resolve()` layers contexts instead of replacing them (`X/keys/keymap.ts:94-109`). A `screener` or `focus`
frame overrides only the keys it declares and leaves the base `view` keymap live underneath; only `overlay`
and `editor` shadow wholesale, via an explicit `SHADOWS_VIEW` list. C and D fall from the top frame straight
to `global`, which kills the base keymap the moment any non-overlay frame is pushed. X subsumes them; they
cannot express X.

Its `normalizeCombo` treats shift as a first-class modifier, so `Cmd+A` and `Cmd+Shift+A` are distinct. D
preserves case instead (`cmd+F` vs `cmd+f`), which works for letters on a US layout and breaks for punctuation
that only exists shifted. **C's lowercases behind a modifier, so `cmd+F` and `cmd+f` collide silently.** That
is a live bug.

Its `bindings.ts` does not import `commands.ts`, so the table, the sheet and the palette are testable without
booting stores or Tauri; in C and D the dependency runs bindings to commands to every store. Its `commands.ts`
is 75 lines with zero store imports: a `Map<CommandId, Handler[]>`, `registerCommands` returning its own
teardown, last-registered wins, so a screen takes over a verb on mount and hands it back. C's and D's are
static tables reaching into the whole app (224 and 433 lines). D is halfway there with its `onCommand`
fan-out, worth keeping alongside the stack for cases needing multiple listeners.

Take `menu.ts` from D instead: the same three lines everywhere, but only D exports its id list and tests that
every menu id names a real command.

**No app supports chords.** All three carry the same header line: "Nothing is chorded and nothing is modal.
Two keys never combine into a third meaning." No pending prefix, no timeout, no sequence buffer. A `g i`
binding is new work; X's `Map<string, Binding[]>` index and single `comboOf` extend to it most cleanly.

**M has no registry and should adopt one.** Four unrelated mechanisms: an `if`/`else if` chain on a
capture-phase window listener at `M/components/EditorView.tsx:167-192`, a second competing window listener for
Cmd+K in `M/editor/FloatingToolbar.tsx:57-70`, TipTap extension shortcuts in four files, and two hand-rolled
`menu-action` chains in `App.tsx:25-35` and `EditorView.tsx:199-206` unaware of each other.

M has no platform detection at all: `grep navigator.` over its `src` returns two clipboard calls. The five
`e.metaKey` tests in `EditorView.tsx` are macOS-only and silently dead on Linux and Windows; `primaryHeld`
fixes that for free. The blocker is that M has no palette and no shortcut sheet, so the "generated, never
maintained" payoff has nowhere to land yet.

Stays per-app: `BINDINGS` (20 rows, 20, ~70), the `CommandId` union, `GROUPS`, `MENU_IDS`, the command
implementations, and app-specific `KeyContext` members. `KeyContext` has to become a type parameter and
`SHADOWS_VIEW` an app-supplied list. The two `isMac` regexes differ by design and confusingly little:
`keys/bindings.ts` uses `/mac|iphone|ipad/i`, `ipc.ts` uses `/mac/i` gated on `isDesktop`, both correct for
their purpose. One `margin-shared/platform` should export both, plus `isTauri`, `isDesktop`, `isMacDesktop`,
`live`, `PRIMARY_LABEL`, `primaryHeld` and `secondaryHeld`, with an injectable user agent so the non-Mac
branch is finally testable; no test exercises it today.

## Stores: the conventions are already uniform

All 42 stores checked. Every one uses the plain `create<State>((set, get) => ({ ... }))`. Not one uses curried
`create<T>()(...)`. **No middleware anywhere**: zero hits for `persist`, `subscribeWithSelector`, `immer`,
`devtools`, `useShallow` or `zustand/shallow` in any app. Nothing is imported from `zustand` except `create`.

Selectors are uniformly inline, `(s) => s.field`, one hook call per field rather than one destructured object.
No exported selector functions exist in any store directory in any app. That is why no shallow comparator is
needed: every subscription is to a primitive or a stable reference. About 620 inline selector sites and 676
`getState()` calls.

Two conventions worth writing down because they are universal and currently retyped everywhere: `if (!live())
return;` as the first line of every backend-touching action, about 40 places; and `error: String(e)` in state,
never `e.message`.

The async action shape repeats about 100 times: optimistic set, try, replace with the server's answer, catch,
roll back and a `Could not ...` toast. Counts: M 1, C 10, D 33, X 53. **I would not abstract it**: the bodies
are five lines and each message is bespoke. Share the `Phase` union and a `describe(e)` helper only.

`useSearch`, `useAccounts` and `useSync` look shareable by name and are not. The three

`useSearch` stores do three different jobs. `useAccounts` in C and X shares a real idea, an OAuth consent
promise bridged over a Tauri event with the resolver stashed in state, but it is on its third hand-copy
(`M/store/useBackup.ts:70` to C to X) and is ~60% app-specific. Share the bridge, not the store, plus
`openAuthUrl`/`copyAuthUrl`, character-identical in both and pure utility.

```ts
export function deferred<T>(): { promise: Promise<T>; settle: (value: T) => void };
export function latestOnly<A extends unknown[], R>(fn: (...a: A) => Promise<R>): (...a: A) => Promise<R | undefined>;
```

`latestOnly` covers the stale-response race both search stores solve differently: D with module-level
monotonic counters (`useSearch.ts:20-21`), X by re-comparing the query string (`useSearch.ts:108`). D's is
more general; X's breaks if two callers share a query.

X's `useSync` is the best sync store, because ~160 of its 210 lines are pure exported functions over
`SyncStatus[]` rather than store code, with a 9.6KB test behind them. C keeps the same dedupe logic as an
effect-local closure variable in `App.tsx`.

## Cross-cutting utilities

**Confirmed absent from all four**: any debounce or throttle utility; deep equality; a `safeParse`/`tryParse`
wrapper; class-name joining (no `cx`, no `clsx`, no `classNames`, and no such dependency); `measureText` or
any text-measurement helper; `Intl.RelativeTimeFormat`; `Intl.PluralRules`; `navigator.userAgentData`;
`nanoid`/`uuid` or any id counter; and `useLocalStorage`, `useInterval`, `useRaf`, `useEvent`, `useLatest`,
`useMountedRef` or an exported `sleep`. No truncation helper; truncation is done in CSS.

The class-name negative is a deliberate architectural choice, not an oversight: all four apps style off data
attributes, so no app ever concatenates class names. Do not introduce `cx`.
**debounce.** Written longhand at 15 sites across all four. The React-effect variant is the same five lines in
at least six places and is worth one `useDebounced<T>(value, ms)`; D's `QuickOpen.tsx:88` and
`FindInFiles.tsx:70` are already identical and name the constant `DEBOUNCE_MS`. Leave the class-field and
module-level timers alone; their cancel/flush semantics are the point.

**`clamp`: 6 definitions plus 12 inline sites, zero shared.** `C/grid/fit.ts:89` and
`C/components/QuickCreateModel.ts:147` are the identical one-liner duplicated *within C*:

```ts
const clamp = (n: number, lo: number, hi: number) => (n < lo ? lo : n > hi ? hi : n);
```

`C/components/EventDetailsModel.ts:45` should win: it is the only one guarding an inverted range, which
matters because half the call sites pass `length - 1` as the high bound and that goes negative on an empty
list. `QuickCreateModel.ts:156,163,171` already works around exactly this at every call. Add a `clampIndex(i,
length)` for the ten index sites. `M/ExportPreview.tsx:92` and `D/ExportPreview.tsx:143` are the
byte-identical zoom clamp.

**Byte size: four implementations, three spellings.** `D/UpdateDialog.tsx:21` says `kB`, `D/FileViewer.tsx:43`
says `bytes` and `KB` with one decimal, `X/screens/format.ts:52` says `B`/`KB`/`MB` with rounding,
`X/screens/Settings.tsx:940` adds GB and adaptive precision. 1536 bytes renders as "1.5 KB", "2 kB" and "2 KB"
in one product family. X's `space()` wins: the only one reaching GB, and its `mb < 10 ? toFixed(1) :
Math.round(mb)` rule actually solves what D's UpdateDialog comment states ("so the number under the bar stops
twitching"), by significant figures rather than fixed decimals.

**Relative time: three hand-rolled ladders, no two agreeing.** `M/src/time.ts:1` is the only standalone
module; `M/src/backup.ts:61` is a second copy in the same app with the prefix baked into every branch;
`D/components/Settings.tsx:45` is a third, inline, with "Checked" hardcoded throughout. They diverge in
behaviour, not just text: M floors, D rounds; M's cutover is 7 days, D's 30. D's rounding makes 89 seconds
"just now" and 91 seconds "2 minutes ago". M's wins: the only one guarding clock skew with `Math.max(0, now -
ts)`, and flooring is right for "how long ago". Callers compose their own prefix, deleting `backup.ts:61` and
reducing `Settings.tsx:45` to one line. X has no "X ago" at all; `rowTime`/`messageTime`
(`screens/format.ts:34-49`) go straight to calendar-day buckets and are the only implementation counting by
calendar day via local midnight rather than elapsed hours, which is the difference between "Yesterday" being
right and being off by a few hours every evening. Keep both.

**`useClock` is the missing half.** `C/src/useClock.ts` (`useTick<T>`, `useMinuteTick`, `useHourStart`)
re-schedules against wall-clock rather than a `setInterval` and treats `visibilitychange` and `focus` as
ticks, because a timer's deadline is measured in time the machine spent awake. C is its only consumer today,
but M's `relativeTime` callers both take a `now` prop that has to come from somewhere, and X's row formatters
default to `Date.now()` at call time and go stale on a window left open overnight. Ship it beside
`relativeTime`.

**`Intl.DateTimeFormat`: no shared factory.** The same `{ day: "numeric", month: "short" }` formatter is
constructed in 6 X files and the `hourCycle: "h23"` clock in 3. M and D use bare `toLocaleDateString()`. A
memoised `dateFormat(options)` collapses the lot; X's cached-module-constant style is the right pattern.

C's `src/time.ts` (136 lines) avoids `Intl` entirely with hand-written day and month arrays, a deliberate
product decision for a calendar grid that should stay. Its `startOfDay`, `addDays`, `isSameDay`, `toDateOnly`,
`parseDateOnly` are reusable date maths and should move; `startOfDay` is already written three times across C
and X (`C/time.ts:23`, `X/screens/format.ts:20`, `X/SnoozePicker.tsx:72`).

**Focus management: one app has it, three do not.** `python/margin/src/focus.ts` (56 lines) is a proper trap:
a `FOCUSABLE` selector, Tab wrapping both directions, opener restore on teardown, and a module-level
`focusTrapped()` so the global key handler can stand down. Five call sites in M.

```ts
export function useFocusTrap(ref: RefObject<HTMLElement | null>, active = true): void;
export function focusTrapped(): boolean;
```

C has autofocus only, no trap and no restore (`components/overlayShell.tsx:51-56`). D and X have neither: both
ship `role="dialog" aria-modal="true"` markup with imperative `.focus()` on mount and no trap behind it.
**This is the one item where sharing fixes an accessibility gap in three apps rather than removing
duplication.** The wrinkle: M's `focusTrapped()` and the other apps' context stack are two mechanisms for one
idea. Either the trap pushes an `overlay` frame, or the shared keymap takes a "something external owns the
keyboard" predicate.

**Scroll position restore: near-identical in M and D, and D says so.** `python/margin/src/editor/positions.ts`
(64 lines) and `rust/margin-editor/src/editor/positions.ts` (52) share an identical `{ from, to, scroll }`
interface, the same guarded `readAll`/`write`, and the same load/save API. D's header names the relationship:
M keys by book then chapter, D by absolute path, "and that path is the whole key". D adds an LRU trim at
`LIMIT = 200`; M's map grows unbounded. D wins, with a flat string key M composes as `${bookId}/${chapterId}`.

`scrollIntoView` is raw at 8 sites, never wrapped; `M/editor/search.ts:98` and `D/editor/search.ts:111` are
byte-identical. Worth extracting alongside it is `D/components/Outline.tsx:79-89`, the only implementation
avoiding `scrollIntoView` scrolling every ancestor, already duplicated once inside D at
`editor/linkPicker.ts:572`.

**JSON.** 10 `JSON.parse` sites, 8 guarded inline, 2 not: `M/library.ts:31` and `M/project.ts:19` parse a file
read off disk with no catch, so a truncated or hand-edited project file throws unhandled. Fold the guarded
ones into `readJson<T>(key, fallback)`; the file reads want `parseJson<T>(text): T | null`. D's `const parsed:
unknown = JSON.parse(...)` then narrow is the right discipline; M and X cast straight to the target type.
**`plural`** is the same function under different names in `M/store/useBackup.ts:56` and
`D/linkRewrite.ts:694`, plus 10 open-coded `${n === 1 ? "" : "s"}` sites including two byte-identical ones in
`X/screens/ReadingPane.tsx:235,502`. M's name wins.

**ResizeObserver**: 13 raw instantiations, no hook. `M/ExportPreview.tsx:64` and `D/ExportPreview.tsx:104` are
byte-identical, as are `M:238`/`D:339` and the `IntersectionObserver` at `M:286`/`D:395`. Any shared
`useResize` must carry the null guard `X/screens/MessageBody.tsx:207` documents and the others lack:
"`ResizeObserver.observe(null)` throws hard enough to take the screen with it". `getBoundingClientRect` has 32
inline sites, all positioning rather than text metrics; the popover-placement clamp is duplicated across four
apps but the anchoring rules differ meaningfully, so it is the lowest-confidence item here. Id generation is M
only, `crypto.randomUUID()` raw at 8 app-domain sites; C, D and X take ids from Rust, so there is nothing to
share.

## Updates: four apps, four answers

M has `src/updater.ts` (111 lines) plus `store/useUpdater.ts` (34), a `direct` vs `appstore` channel split,
and it holds the live `Update` resource handle in the zustand store. C has `keys/updates.ts` (41), toast-only,
"Ported from margin's `src/updater.ts`, minus its progress dialog"; it is the only one of the four with a
`packagedBy()` guard, so a nix or homebrew install is told to update through its package manager instead of
self-updating. X has no update module at all: `checkForUpdates` is inline at `X/src/App.tsx:98-118`, with a
second copy in `screens/Settings.tsx`.

D has `src/update.ts` (171) plus `store/useUpdate.ts` (129), the best of the four: named phase transitions
rather than a generic `set(partial)`; `total: number | null` so a missing content-length draws an
indeterminate bar instead of 0% forever; version and notes as plain strings so no Rust handle sits in the
store; a launch delay and 24-hour interval for automatic checks; a flush of the pending save before
`relaunch()`; and a discriminator for "this dev build has no updater plugin" so that reads as a sentence
about the build. Take D's store and driver, fold in C's `packagedBy` guard as an option.

## Bugs found, worth fixing regardless of any extraction

- `marginmail-theme` is declared as two constants in two files, `X/src/theme.ts:8` and
  `X/src/appearance.ts:14`.
- X's `checkForUpdates` lacks C's `packagedBy()` guard, so a package-manager-installed build will try to
  self-update over a path it does not own.
- C's `normalizeCombo` lowercases the key behind a modifier, so `cmd+F` and `cmd+f` are one binding.
- `M/src/ipc.ts:3` names `isDesktop` what the other three call `isTauri`, and it gates three IPC calls.
- `M/library.ts:31` and `M/project.ts:19` parse a file off disk with no catch.

## Ranked

1. `escape.ts`. ~144 lines, byte-identical in four apps.
2. `createOverlays<T>()`. ~130 lines, code-identical today.
3. `platform.ts` (both halves). ~50 lines, byte-identical in three, fixes two M bugs.
4. `onAppEvent`. ~60 lines, better teardown, unlocks browser testing for two apps.
5. `useMedia.ts`. ~120 lines, byte-identical bodies in three apps.
6. `useToast` plus `notify`. ~60 lines, strict superset, fixes a timer bug in two.
7. `makeStorage` and `rootSetting`. ~120 lines, deletes nine copies in D, fixes six unguarded reads.
8. `call<T>` factory plus the `ipc.ts` preamble. ~50 lines.
9. Theme, from D, with a generated boot script. ~250 lines, needs a per-app table.
10. Small utilities: `clamp`, `fileSize`, `relativeTime` plus `useClock`, `plural`, `positions.ts`,
    `useDebounced`, `dateFormat`, `latestOnly`, `deferred`. Collectively ~250 lines and several
    user-visible inconsistencies.
11. `useFocusTrap`. Not a saving; an accessibility fix for three apps.
12. The keyboard registry, from X. Largest and highest-value, but needs `KeyContext` parameterised and
    `SHADOWS_VIEW` injected, and M needs a palette before it benefits.
13. The update store and driver. Four designs to reconcile; do it last.

Items 1 to 6 are mechanically identical across apps today and drop into the existing package with no behaviour
change. The one prerequisite is adding `margin-shared` to margin-calendar.