@arcforgelabs/flow 2026.10.32-beta.1 → 2026.10.32

package/server/integrations/xero/webhooks.js

@@ -0,0 +1,311 @@
+import { createHmac, timingSafeEqual } from 'node:crypto';
+import { sql } from 'drizzle-orm';
+import { isCallsStopped } from '../call-guard.js';
+import { lastSync, parseXeroDate, syncCatalogue } from './catalogue.js';
+import { withXeroLane } from './governor.js';
+import { mirrorState } from './lookup.js';
+import { mapRecords, mirrorXero, storeRows, toCents } from './mirror.js';
+import { checkSentInvoices } from './reconcile.js';
+
+// Xero's webhooks, and the daily check (issue #45). The poll (import.js) reads
+// Xero's changes every 15 minutes. Webhooks make a change reach Flow in
+// seconds, and the daily check finds what both of them missed.
+//
+//   1. Xero posts an event to /api/xero/webhooks: a record id and what
+//      happened, never the record. Flow checks the signature, saves the id in
+//      the inbox (xero_webhook_events) and answers 200 at once.
+//   2. The worker reads the waiting invoices by id, up to 50 a call, into the
+//      copy (mirror.js), then compares the sent invoices again (reconcile.js).
+//      Credit notes are read as changes since the cursor; contacts refresh the
+//      contacts and items copy.
+//   3. While webhooks arrive, the poll waits an hour instead of 15 minutes. If
+//      they stop, it goes back to 15 minutes by itself.
+//   4. Once a day, one summary read of every invoice (about 1,000 a call)
+//      finds each copy row whose status, amounts or change time differ from
+//      Xero, and each row Xero no longer lists. Those go into the inbox and are
+//      read by id like an event. This catches part payments that do not move
+//      Xero's change time, and a webhook that never came.
+//
+// Every read goes through the call guard and the governor's sync lane, and
+// leaves the mirror's reserve of the day's calls for drafts and people. Flow
+// never writes to Xero here.
+
+export const BY_ID_BATCH = 50;
+// The poll's wait while webhooks arrive, and how recent the last one must be.
+export const WEBHOOK_REFRESH_MS = 60 * 60 * 1000;
+export const WEBHOOK_ACTIVE_MS = 24 * 60 * 60 * 1000;
+export const DAILY_CHECK_EVERY_MS = 24 * 60 * 60 * 1000;
+// A daily check that failed is tried again after this wait.
+const DAILY_CHECK_RETRY_MS = 60 * 60 * 1000;
+const SUMMARY_PAGE = 1000;
+// At most this many records a day go back for a read by id (5 calls), so a
+// check that finds the whole copy different cannot spend the day. The rest
+// wait for the next day's check.
+export const DAILY_FLAG_MAX = 250;
+const MAX_SUMMARY_PAGES = 50;
+// Contacts and items are read again at most this often for contact events.
+const CONTACTS_EVERY_MS = 60 * 60 * 1000;
+
+const CATEGORIES = { INVOICE: 'invoices', CREDITNOTE: 'credit_notes', CREDIT_NOTE: 'credit_notes', CONTACT: 'contacts' };
+
+// Xero signs the raw body with HMAC-SHA256 and the webhook key, in base64
+// (x-xero-signature). Compared in constant time.
+export function signatureValid(key, rawBody, signature) {
+  if (!key || typeof signature !== 'string' || !signature) return false;
+  const expected = createHmac('sha256', key).update(rawBody).digest();
+  let given;
+  try {
+    given = Buffer.from(signature, 'base64');
+  } catch {
+    return false;
+  }
+  return given.length === expected.length && timingSafeEqual(given, expected);
+}
+
+// Saves the events of one verified delivery. An event for an organisation not
+// connected in this mode is dropped. Answers how many were saved.
+export async function saveEvents(db, runtime, payload, { now = new Date() } = {}) {
+  const events = Array.isArray(payload?.events) ? payload.events : [];
+  if (!events.length) return 0;
+  const { rows } = await db.execute(sql`select organisation_id, tenant_id from xero_connections where mode = ${runtime.settings.mode}`);
+  const byTenant = new Map(rows.map((r) => [r.tenant_id, r.organisation_id]));
+  let saved = 0;
+  for (const event of events) {
+    const organisationId = byTenant.get(event?.tenantId);
+    if (!organisationId || typeof event.resourceId !== 'string' || !event.resourceId) continue;
+    const resource = CATEGORIES[String(event.eventCategory ?? '').toUpperCase()] ?? 'other';
+    const at = Date.parse(`${String(event.eventDateUtc ?? '').replace(/Z?$/, 'Z')}`);
+    await flag(db, organisationId, resource, event.resourceId, {
+      source: 'webhook', eventType: event.eventType ?? null, eventAt: Number.isNaN(at) ? null : new Date(at), now,
+    });
+    saved += 1;
+  }
+  return saved;
+}
+
+// Marks one record as waiting to be read by id.
+async function flag(db, organisationId, resource, resourceId, { source, eventType = null, eventAt = null, now = new Date() }) {
+  await db.execute(sql`
+    insert into xero_webhook_events (organisation_id, resource, resource_id, event_type, source, event_at, received_at)
+    values (${organisationId}, ${resource}, ${resourceId}, ${eventType}, ${source}, ${eventAt}, ${now})
+    on conflict (organisation_id, resource, resource_id) do update set
+      event_type = excluded.event_type, source = excluded.source, event_at = excluded.event_at,
+      received_at = excluded.received_at, pending = true`);
+}
+
+async function markRead(db, organisationId, resource, ids = null) {
+  const only = ids ? sql`and resource_id = any(${sql.param(ids)}::text[])` : sql``;
+  await db.execute(sql`update xero_webhook_events set pending = false, read_at = now()
+    where organisation_id = ${organisationId} and resource = ${resource} and pending ${only}`);
+}
+
+// Whether a webhook for this organisation arrived recently: the poll can wait.
+export async function webhooksActive(db, runtime, organisationId, { now = Date.now() } = {}) {
+  if (!runtime.settings.webhookKey) return false;
+  const { rows: [row] } = await db.execute(sql`select max(received_at) as at from xero_webhook_events
+    where organisation_id = ${organisationId} and source = 'webhook'`);
+  return Boolean(row?.at && Number(now) - new Date(row.at).getTime() <= WEBHOOK_ACTIVE_MS);
+}
+
+// Calls left above the reserve the mirror keeps for drafts and people.
+function overReserve(runtime, tenantId) {
+  const budget = runtime.governor.status(tenantId);
+  return budget.dayRemaining > Math.ceil(budget.dayLimit * runtime.settings.mirrorReserveFraction);
+}
+
+async function pendingIds(db, organisationId) {
+  const { rows } = await db.execute(sql`select resource, resource_id from xero_webhook_events
+    where organisation_id = ${organisationId} and pending order by received_at`);
+  const out = new Map();
+  for (const r of rows) out.set(r.resource, [...(out.get(r.resource) ?? []), r.resource_id]);
+  return out;
+}
+
+// Reads every waiting record of one organisation. Answers counts, or a
+// `stopped` reason: 'calls_stopped' (the call guard) or 'budget'.
+export async function readInbox(db, runtime, organisationId, { now = Date.now } = {}) {
+  const waiting = await pendingIds(db, organisationId);
+  const result = { invoices: { read: 0, inserted: 0, changed: 0, unchanged: 0 }, creditNotes: 0, contacts: false, sent: null };
+  if (!waiting.size) return result;
+  const { rows: [connection] } = await db.execute(sql`select tenant_id from xero_connections
+    where organisation_id = ${organisationId} and mode = ${runtime.settings.mode}`);
+  if (!connection) return result;
+  try {
+    await runtime.guardFor(db).check(connection.tenant_id);
+  } catch (error) {
+    if (isCallsStopped(error)) return { ...result, stopped: 'calls_stopped' };
+    throw error;
+  }
+
+  const invoiceIds = waiting.get('invoices') ?? [];
+  if (invoiceIds.length) {
+    const counts = result.invoices;
+    const stopped = await runtime.serial(organisationId, () => withXeroLane('sync', async () => {
+      const { client } = await runtime.clientFor(db, organisationId);
+      for (let i = 0; i < invoiceIds.length; i += BY_ID_BATCH) {
+        if (!overReserve(runtime, client.tenantId)) return 'budget';
+        const batch = invoiceIds.slice(i, i + BY_ID_BATCH);
+        const rows = mapRecords('invoices', await client.listInvoicesByIds(batch), runtime.settings);
+        await db.transaction(async (tx) => {
+          await storeRows(tx, organisationId, 'invoices', rows, counts);
+          // An id Xero did not return is read too: there is nothing more to get.
+          await markRead(tx, organisationId, 'invoices', batch);
+        });
+        counts.read += rows.length;
+      }
+      return null;
+    }));
+    if (stopped) return { ...result, stopped };
+    if (counts.inserted || counts.changed) result.sent = await checkSentInvoices(db, runtime, organisationId);
+  }
+
+  if (waiting.get('credit_notes')?.length) {
+    // Credit notes are few: one read of the changes since the cursor gets them.
+    const [read] = await mirrorXero(db, runtime, organisationId, { resources: ['credit_notes'] });
+    if (read?.stopped === 'budget') return { ...result, stopped: 'budget' };
+    result.creditNotes = read?.read ?? 0;
+    await markRead(db, organisationId, 'credit_notes');
+  }
+
+  if (waiting.get('contacts')?.length) {
+    const last = await lastSync(db, organisationId);
+    const at = last?.finishedAt ?? last?.startedAt;
+    if (!at || Number(now()) - new Date(at).getTime() >= CONTACTS_EVERY_MS) {
+      await syncCatalogue(db, runtime, organisationId);
+      await markRead(db, organisationId, 'contacts');
+      result.contacts = true;
+    }
+  }
+
+  // Events Flow does not copy (other categories) need no read.
+  if (waiting.get('other')?.length) await markRead(db, organisationId, 'other');
+  return result;
+}
+
+// The daily check for one organisation: one summary read of every invoice,
+// compared with the copy. Each row that differs, and each live copy row Xero
+// no longer lists, waits in the inbox to be read by id. Answers counts, or
+// `stopped`.
+export async function dailyCheck(db, runtime, organisationId, { now = () => new Date() } = {}) {
+  await db.execute(sql`insert into xero_daily_checks (organisation_id, last_started_at) values (${organisationId}, ${now()})
+    on conflict (organisation_id) do update set last_started_at = excluded.last_started_at`);
+  try {
+    const seen = [];
+    const stopped = await runtime.serial(organisationId, () => withXeroLane('sync', async () => {
+      const { client } = await runtime.clientFor(db, organisationId);
+      for (let page = 1; page <= MAX_SUMMARY_PAGES; page += 1) {
+        if (!overReserve(runtime, client.tenantId)) return 'budget';
+        const list = await client.listInvoiceSummaries({ page, pageSize: SUMMARY_PAGE });
+        seen.push(...list.filter((i) => i.InvoiceID));
+        if (list.length < SUMMARY_PAGE) return null;
+      }
+      return 'max_pages';
+    }));
+    if (stopped) {
+      await db.execute(sql`update xero_daily_checks set last_error = ${stopped} where organisation_id = ${organisationId}`);
+      return { read: seen.length, flagged: 0, stopped };
+    }
+    const { rows: copy } = await db.execute(sql`select xero_invoice_id, status, total_cents, amount_due_cents,
+      amount_paid_cents, amount_credited_cents, xero_updated_at from xero_invoices where organisation_id = ${organisationId}`);
+    const byId = new Map(copy.map((r) => [r.xero_invoice_id, r]));
+    const flagged = new Set();
+    for (const x of seen) {
+      const row = byId.get(x.InvoiceID);
+      byId.delete(x.InvoiceID);
+      if (!row || summaryDiffers(row, x)) flagged.add(x.InvoiceID);
+    }
+    // A live copy row Xero no longer lists: read it by id to learn its state.
+    for (const row of byId.values()) if (!['DELETED', 'VOIDED'].includes(row.status)) flagged.add(row.xero_invoice_id);
+    const at = now();
+    const list = [...flagged].slice(0, DAILY_FLAG_MAX);
+    for (const id of list) await flag(db, organisationId, 'invoices', id, { source: 'daily_check', now: at });
+    await db.execute(sql`update xero_daily_checks set last_finished_at = ${at}, last_read = ${seen.length},
+      last_flagged = ${flagged.size}, last_error = null where organisation_id = ${organisationId}`);
+    return { read: seen.length, flagged: flagged.size, queued: list.length, stopped: null };
+  } catch (error) {
+    await db.execute(sql`update xero_daily_checks set last_error = ${`${error.code ?? 'error'}: ${String(error.message).slice(0, 300)}`}
+      where organisation_id = ${organisationId}`);
+    throw error;
+  }
+}
+
+const cents = (value) => (value === null || value === undefined ? null : Number(value));
+
+// Whether a summary from Xero differs from the copy row in what the summary
+// carries: status, money, and the change time.
+export function summaryDiffers(row, summary) {
+  if (row.status !== summary.Status) return true;
+  for (const [column, field] of [['total_cents', 'Total'], ['amount_due_cents', 'AmountDue'], ['amount_paid_cents', 'AmountPaid'], ['amount_credited_cents', 'AmountCredited']]) {
+    if (summary[field] !== undefined && cents(row[column]) !== toCents(summary[field])) return true;
+  }
+  // Xero changed it after the copy's version (whole seconds, as Xero compares).
+  const changed = parseXeroDate(summary.UpdatedDateUTC);
+  const copied = row.xero_updated_at ? new Date(row.xero_updated_at) : null;
+  return Boolean(changed && (!copied || Math.floor(changed / 1000) > Math.floor(copied / 1000)));
+}
+
+// The organisations whose daily check is due: a complete copy, and no check
+// finished in the last day (or none tried in the last hour after a failure).
+export async function dueDailyChecks(db, runtime, { now = Date.now() } = {}) {
+  const { rows } = await db.execute(sql`select c.organisation_id, c.tenant_id, d.last_started_at, d.last_finished_at
+    from xero_connections c left join xero_daily_checks d on d.organisation_id = c.organisation_id
+    where c.mode = ${runtime.settings.mode}`);
+  const due = [];
+  for (const r of rows) {
+    const finished = r.last_finished_at ? new Date(r.last_finished_at).getTime() : null;
+    const started = r.last_started_at ? new Date(r.last_started_at).getTime() : null;
+    if (finished && Number(now) - finished < DAILY_CHECK_EVERY_MS) continue;
+    if (started && (!finished || started > finished) && Number(now) - started < DAILY_CHECK_RETRY_MS) continue;
+    if (!(await mirrorState(db, r.organisation_id, { now: new Date(Number(now)) })).complete) continue;
+    due.push({ organisationId: r.organisation_id, tenantId: r.tenant_id });
+  }
+  return due;
+}
+
+// After a failed read, an organisation waits 1 minute, then 2, 4 and up to an
+// hour, so a failing read is never tried every tick.
+export const RETRY_FIRST_MS = 60 * 1000;
+export const RETRY_MAX_MS = 60 * 60 * 1000;
+
+// One worker step: reads each organisation's inbox, then runs any daily check
+// that is due. A stop by the call guard skips that organisation quietly; the
+// guard has reported it. A failure is logged once as an error; the same
+// failure again is a warning. `holds` keeps each organisation's wait between
+// steps.
+export async function runWebhookWork(db, runtime, { log = console, now = Date.now, holds = new Map() } = {}) {
+  const failed = (organisationId, what, error) => {
+    const held = holds.get(organisationId);
+    const failures = (held?.failures ?? 0) + 1;
+    holds.set(organisationId, { failures, until: Number(now()) + Math.min(RETRY_MAX_MS, RETRY_FIRST_MS * 2 ** (failures - 1)), code: error?.code ?? 'error' });
+    const line = `[xero] ${what} for organisation ${organisationId} failed: ${error?.code ?? 'error'}`;
+    if (held?.code === (error?.code ?? 'error')) log.warn?.(line);
+    else log.error?.(line);
+  };
+  const waiting = (organisationId) => (holds.get(organisationId)?.until ?? 0) > Number(now());
+
+  const { rows } = await db.execute(sql`select distinct e.organisation_id from xero_webhook_events e
+    join xero_connections c on c.organisation_id = e.organisation_id and c.mode = ${runtime.settings.mode}
+    where e.pending`);
+  for (const { organisation_id: organisationId } of rows) {
+    if (waiting(organisationId)) continue;
+    try {
+      const read = await readInbox(db, runtime, organisationId, { now });
+      holds.delete(organisationId);
+      if (read.invoices.read || read.creditNotes || read.contacts) {
+        log.info?.(`[xero] read waiting changes for organisation ${organisationId}: ${read.invoices.read} invoices, ${read.creditNotes} credit notes${read.contacts ? ', contacts' : ''}`);
+      }
+    } catch (error) {
+      if (!isCallsStopped(error)) failed(organisationId, 'reading waiting changes', error);
+    }
+  }
+  for (const { organisationId, tenantId } of await dueDailyChecks(db, runtime, { now: now() })) {
+    try {
+      await runtime.guardFor(db).check(tenantId);
+      const check = await dailyCheck(db, runtime, organisationId, { now: () => new Date(Number(now())) });
+      log.info?.(`[xero] daily check for organisation ${organisationId}: ${check.read} invoices, ${check.flagged} to read again${check.stopped ? `; stopped (${check.stopped})` : ''}`);
+    } catch (error) {
+      // dueDailyChecks waits an hour after a failed check.
+      if (!isCallsStopped(error)) log.error?.(`[xero] daily check for organisation ${organisationId} failed: ${error?.code ?? 'error'}`);
+    }
+  }
+}

package/server/ui/app.js

@@ -216,7 +216,7 @@ const ICON_PATHS = {
   person: '<circle cx="12" cy="8" r="4"/><path d="M4 21c0-4 3.6-7 8-7s8 3 8 7"/>',
   flag: '<path d="M5 21V4M5 4h11l-2 4 2 4H5"/>',
   search: '<circle cx="11" cy="11" r="6.5"/><path d="M16 16l4.5 4.5"/>',
-  menu: '<path d="M4 6h16M4 12h16M4 18h16"/>',
+  sidebar: '<rect x="3" y="4" width="18" height="16" rx="2.5"/><path d="M9.5 4v16"/>',
   palette: '<path d="M12 3a9 9 0 100 18c1.1 0 1.5-.8 1.5-1.6 0-1-.8-1.4-.8-2.4 0-.9.7-1.5 1.6-1.5H17a4 4 0 004-4c0-4.7-4-8.5-9-8.5z"/><circle cx="7.5" cy="11" r="1"/><circle cx="10" cy="7" r="1"/><circle cx="15" cy="7" r="1"/>',
 };
 
@@ -226,10 +226,12 @@ function icon(name) {
   return node;
 }
 
-// The menu button at the top of the sidebar. On a wide screen it folds the
-// sidebar to its icons and back, and the choice stays in this browser. On a
-// narrow screen the sidebar is a bar across the top, and the button opens
-// the menu below it; choosing a page, Escape or a click outside closes it.
+// The sidebar button at the top of the sidebar (a panel icon, not a
+// hamburger; folded or narrow, the logo stands in for it). On a wide screen it folds the sidebar to its icons and back,
+// and the choice stays in this browser. On a narrow screen the sidebar is a
+// bar across the top, and the button slides the menu in from the left as a
+// drawer over a dimmed page; choosing a page, Escape or a click on the page
+// closes it.
 const NARROW = window.matchMedia('(max-width: 820px)');
 const FOLDED_KEY = 'flow_sidebar_folded';
 
@@ -243,7 +245,7 @@ function drawMenu() {
   shell.toggleAttribute('data-folded', folded);
   const open = NARROW.matches ? shell.hasAttribute('data-menu-open') : !folded;
   const toggle = $('menu-toggle');
-  const label = NARROW.matches ? (open ? 'Close the menu' : 'Open the menu') : (folded ? 'Show the menu' : 'Fold the menu');
+  const label = NARROW.matches ? (open ? 'Close the menu' : 'Open the menu') : (folded ? 'Show the sidebar' : 'Hide the sidebar');
   toggle.setAttribute('aria-expanded', String(open));
   toggle.setAttribute('aria-label', label);
   toggle.title = label;
@@ -384,7 +386,13 @@ function renderShell() {
   const report = h('button', { type: 'button', class: 'fx-nav__report', 'data-nav': 'report', 'data-label': 'Report a problem', hidden: true },
     icon('flag'), h('span', { class: 'fx-nav__label' }, 'Report a problem'));
   nav.replaceChildren(...items, report);
-  $('menu-toggle').replaceChildren(icon('menu'));
+  // Folded or narrow, the logo is the sidebar button: it shows the mark and
+  // turns into the sidebar icon under the pointer or keyboard focus.
+  const mark = h('span', { class: 'fx-toggle__mark', 'aria-hidden': 'true' });
+  mark.innerHTML = document.querySelector('.fx-side__head .fx-brand svg')?.outerHTML ?? '';
+  const sidebar = icon('sidebar');
+  sidebar.classList.add('fx-toggle__icon');
+  $('menu-toggle').replaceChildren(mark, sidebar);
   $('menu-toggle').onclick = toggleMenu;
   drawMenu();
   // The sidebar foot shows who is signed in: photo or initial, then the name

package/server/ui/flow.css

@@ -113,10 +113,17 @@ body:is([data-state="off"], [data-state="error"], [data-state="no-access"]) .fx-
   display: flex; flex-direction: column; gap: 4px; flex: none;
   width: 232px; height: 100vh; padding: 16px 12px 12px;
   background: var(--t-s1); border-right: 1px solid var(--fx-line);
+  transition: width .18s ease;
 }
 .fx-side__head { display: flex; align-items: center; justify-content: space-between; gap: 8px; padding: 0 0 14px 8px; }
 .fx-side__head .fx-brand { min-width: 0; font-size: 19px; }
 .fx-side__head .fx-mark { width: 26px; height: 26px; }
+/* The sidebar button. Open, it shows the sidebar icon beside the brand.
+   Folded or narrow, the brand is hidden and the button shows the logo, which
+   turns into the sidebar icon on hover or focus (and while the drawer is
+   open), so the two never sit side by side. */
+.fx-toggle__mark { display: none; }
+.fx-toggle__mark .fx-mark { display: block; }
 .fx-nav { display: flex; flex-direction: column; gap: 2px; flex: 1; min-height: 0; overflow-y: auto; }
 .fx-nav__group { padding: 16px 10px 6px; color: var(--t-dim); font: var(--t-label-weight) var(--t-label-size)/1.3 var(--t-body); letter-spacing: var(--t-label-spacing); text-transform: var(--t-label-case); }
 .fx-nav__group:first-child { padding-top: 4px; }
@@ -141,7 +148,7 @@ body:is([data-state="off"], [data-state="error"], [data-state="no-access"]) .fx-
 @media (min-width: 821px) {
   .fx-shell[data-folded] .fx-side { width: 64px; padding-inline: 10px; }
   .fx-shell[data-folded] .fx-side__head { flex-direction: column; gap: 10px; padding: 0 0 14px; }
-  .fx-shell[data-folded] .fx-brand span { display: none; }
+  .fx-shell[data-folded] .fx-side__head .fx-brand { display: none; }
   .fx-shell[data-folded] .fx-nav__group { height: 1px; margin: 10px 6px; padding: 0; overflow: hidden; background: var(--fx-line); color: transparent; }
   .fx-shell[data-folded] :is(.fx-nav a, .fx-nav__report) { justify-content: center; padding: 9px 0; }
   .fx-shell[data-folded] .fx-nav__label { position: absolute; width: 1px; height: 1px; overflow: hidden; clip-path: inset(50%); }
@@ -659,19 +666,41 @@ body[data-state="loading"] .fx-loading { display: grid; justify-items: center; }
   .fx-shell { flex-direction: column; }
   .fx-side { flex-direction: row; align-items: center; width: auto; height: 60px; padding: 0 12px; border-right: 0; border-bottom: 1px solid var(--fx-line); }
   .fx-side__head { flex-direction: row-reverse; gap: 6px; padding: 0; }
-  .fx-side__head .fx-brand span { display: none; }
-  /* The menu opens as a panel below the bar. */
+  .fx-side__head .fx-brand { display: none; }
+  /* The menu is a drawer: it slides in from the left, below the bar, over
+     a dimmed page. A click on the dimmed page closes it (app.js). */
   .fx-nav {
-    display: none; position: absolute; top: 60px; left: 0; right: 0;
-    max-height: calc(100vh - 60px); padding: 4px 12px 12px;
-    background: var(--t-s1); border-bottom: 1px solid var(--fx-line); box-shadow: var(--t-shadow);
+    position: fixed; top: 60px; bottom: 0; left: 0; z-index: 2;
+    width: min(280px, 85vw); padding: 8px 12px 12px;
+    background: var(--t-s1); border-right: 1px solid var(--fx-line); box-shadow: var(--t-shadow);
+    transform: translateX(-100%); visibility: hidden;
+    transition: transform .2s ease, visibility .2s;
+  }
+  .fx-shell[data-menu-open] .fx-nav { transform: none; visibility: visible; }
+  .fx-shell[data-menu-open]::after {
+    content: ""; position: fixed; inset: 60px 0 0; z-index: 9;
+    background: rgba(0, 0, 0, .32);
   }
-  .fx-shell[data-menu-open] .fx-nav { display: flex; }
   .fx-nav__report { margin-top: 8px; }
   .fx-side__end { margin-left: auto; padding: 0; border-top: 0; }
   #user-button { flex: none; }
 }
 
+/* Collapsed (folded on wide screens, or narrow): logo at rest, sidebar icon
+   on hover, focus or while open. */
+@media (min-width: 821px) {
+  .fx-shell[data-folded] .fx-toggle__mark { display: block; }
+  .fx-shell[data-folded] .fx-toggle__icon { display: none; }
+  .fx-shell[data-folded] #menu-toggle:is(:hover, :focus-visible) .fx-toggle__mark { display: none; }
+  .fx-shell[data-folded] #menu-toggle:is(:hover, :focus-visible) .fx-toggle__icon { display: inline-flex; }
+}
+@media (max-width: 820px) {
+  .fx-toggle__mark { display: block; }
+  .fx-toggle__icon { display: none; }
+  #menu-toggle:is(:hover, :focus-visible, [aria-expanded="true"]) .fx-toggle__mark { display: none; }
+  #menu-toggle:is(:hover, :focus-visible, [aria-expanded="true"]) .fx-toggle__icon { display: inline-flex; }
+}
+
 /* ── Phones ─────────────────────────────────────────────────────────────── */
 @media (max-width: 640px) {
   .fx-main { padding-top: 20px; }
@@ -778,3 +807,14 @@ body[data-state="loading"] .fx-loading { display: grid; justify-items: center; }
   color-scheme: light;
 }
 [data-mode="dark"] #sentry-feedback { --interactive-filter: brightness(150%); color-scheme: dark; }
+
+/* The bar above one invoice: Back, its place in the list, previous and next.
+   Quiet: no frame, dim text, round icon buttons. */
+.fx-pager { display: grid; grid-template-columns: 1fr auto 1fr; align-items: center; gap: 12px; min-height: 32px; }
+.fx-pager__back { justify-self: start; background: none; border: 0; padding: 4px 0; color: var(--t-dim); font: inherit; font-size: 13.5px; cursor: pointer; transition: color 120ms var(--fx-ease); }
+.fx-pager__back:hover, .fx-pager__back:focus-visible { color: var(--t-strong); }
+.fx-pager__count { grid-column: 2; color: var(--t-dim); font-size: 13px; font-variant-numeric: tabular-nums; }
+.fx-pager__steps { grid-column: 3; justify-self: end; display: flex; gap: 4px; }
+.fx-pager__step { display: inline-grid; place-items: center; width: 30px; height: 30px; padding: 0; border: 1px solid var(--fx-line-soft); border-radius: 999px; background: transparent; color: var(--t-text); cursor: pointer; transition: background 120ms var(--fx-ease), border-color 120ms var(--fx-ease); }
+.fx-pager__step:hover:not(:disabled) { background: var(--fx-hover); border-color: var(--fx-line); }
+.fx-pager__step:disabled { opacity: 0.35; cursor: default; }

package/server/ui/invoice-notes.js

@@ -0,0 +1,26 @@
+// The notes on the Invoices page and on one invoice (invoicing.js). One fact
+// per sentence; they follow the accounting integration's settings. Kept apart
+// so tests can load them without a browser.
+
+// What happens to a ready invoice in the accounting system, one fact per
+// sentence. It follows the integration's settings: its connection, whether it
+// takes writes, and the send mode on its page. `what` names the invoices:
+// "each invoice" on the list, "this invoice" on one invoice.
+export function sendModeNote(to, sendMode, what = 'each invoice') {
+  if (!to) return 'No accounting system is on. Flow keeps each invoice here only.';
+  if (sendMode && !sendMode.connected) return `${to} is not connected. Connect it in Integrations before you send.`;
+  if (sendMode && !sendMode.writesAllowed) return `${to} does not take invoices from Flow yet. Turn this on in Integrations, ${to}.`;
+  const text = sendMode?.mode === 'approve_and_email'
+    ? [`Flow sends ${what} to ${to} as approved.`, `${to} emails it to the customer at once.`]
+    : [`Flow sends ${what} to ${to} as a draft.`, `You approve and send it in ${to}.`];
+  const others = sendMode?.otherCustomers ?? 0;
+  if (others) text.push(`${others} ${others === 1 ? 'customer has' : 'customers have'} a different setting.`);
+  return text.join(' ');
+}
+
+// The line under a draft's title, one fact per sentence.
+export function draftNote(to, invoice, ready) {
+  if (!to) return ready ? 'A person checked it. A saved change keeps it ready.' : 'Flow gives it a number when you issue it.';
+  if (!ready) return `Mark it ready, then send it to ${to}.`;
+  return sendModeNote(to, invoice?.sendMode, 'this invoice');
+}

package/server/ui/invoicing-settings.js

@@ -66,7 +66,9 @@ export async function renderInvoicingSettings(main, ui) {
   host.replaceChildren(...[
     disabled ? notice('Only an owner or admin can change these.', 'info') : null,
     section('Drafts',
-      row('Payment terms', 'Days from invoice to due date.', days('paymentTermsDays', 'Payment terms in days'))),
+      row('Payment terms', 'Days from invoice to due date.', days('paymentTermsDays', 'Payment terms in days')),
+      row('Reference', 'The Reference on each invoice. Use {practitioner} and {patient}.',
+        box('referenceTemplate', 'Reference rule', { placeholder: '{practitioner} - {patient}' }))),
     lineMappingSection(ui),
     automationSection(ui, 'invoicing', 'Automations'),
     rulesSection(ui),