@arcforgelabs/flow 2026.10.44 → 2026.10.46

package/README.md

@@ -36,6 +36,7 @@ run a lab.
 | `docs/releases/` | One release notes page per version (`<version>.md`), shown on the docs site |
 | `docs/DESIGN.md` | The design systems (theme families), how pages and Clerk's components take them, and the screens |
 | `docs/DESIGN_SYSTEM.md` | The Flow Design System artifact: how `npm run design-system` builds it from the code, the card per shared component, publishing and review |
+| `docs/MOBILE_TESTS.md` | The phone suite: every screen at phone, tablet and desk sizes in WebKit and Chromium, its checks and budget, the three widths, saved images |
 | `docs/DATA_MODEL.md` | The PostgreSQL records, the rules the database holds, and how to change the schema |
 | `docs/DATA_SPINE.md` | The design of the tables and jobs every integration shares: mirror, identity map, job queue, outbox, review queue |
 | `docs/JOB_INVOICE_LINKS.md` | The pipeline: how each job links to its customer and to the accounting invoice that bills it |

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "@arcforgelabs/flow",
-  "version": "2026.10.44",
+  "version": "2026.10.46",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@arcforgelabs/flow",
-      "version": "2026.10.44",
+      "version": "2026.10.46",
       "license": "MIT",
       "dependencies": {
         "@clerk/backend": "3.25.0",
@@ -33,6 +33,8 @@
         "flow-server": "server/flow-server.js"
       },
       "devDependencies": {
+        "@axe-core/playwright": "4.13.0",
+        "@playwright/test": "1.56.1",
         "drizzle-kit": "0.31.11",
         "esbuild": "0.25.12"
       },
@@ -40,6 +42,19 @@
         "node": ">=24"
       }
     },
+    "node_modules/@axe-core/playwright": {
+      "version": "4.13.0",
+      "resolved": "https://registry.npmjs.org/@axe-core/playwright/-/playwright-4.13.0.tgz",
+      "integrity": "sha512-6YLx+kxXu5GJceG4ozFg+33a2EMTdjYwWGloJ3sb9Kta5pp+ZNS53uxGVog5JetIY8s++P5UrtX+cri+u0VAVg==",
+      "dev": true,
+      "license": "MPL-2.0",
+      "dependencies": {
+        "axe-core": "~4.13.0"
+      },
+      "peerDependencies": {
+        "playwright-core": ">= 1.0.0"
+      }
+    },
     "node_modules/@clerk/backend": {
       "version": "3.25.0",
       "resolved": "https://registry.npmjs.org/@clerk/backend/-/backend-3.25.0.tgz",
@@ -1029,6 +1044,22 @@
         "url": "https://github.com/sponsors/oxc-project"
       }
     },
+    "node_modules/@playwright/test": {
+      "version": "1.56.1",
+      "resolved": "https://registry.npmjs.org/@playwright/test/-/test-1.56.1.tgz",
+      "integrity": "sha512-vSMYtL/zOcFpvJCW71Q/OEGQb7KYBPAdKh35WNSkaZA75JlAO8ED8UN6GUNTm3drWomcbcqRPFqQbLae8yBTdg==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "dependencies": {
+        "playwright": "1.56.1"
+      },
+      "bin": {
+        "playwright": "cli.js"
+      },
+      "engines": {
+        "node": ">=18"
+      }
+    },
     "node_modules/@sentry/bundler-plugins": {
       "version": "11.8.0",
       "resolved": "https://registry.npmjs.org/@sentry/bundler-plugins/-/bundler-plugins-11.8.0.tgz",
@@ -1183,6 +1214,16 @@
         "node": ">= 0.6"
       }
     },
+    "node_modules/axe-core": {
+      "version": "4.13.0",
+      "resolved": "https://registry.npmjs.org/axe-core/-/axe-core-4.13.0.tgz",
+      "integrity": "sha512-UzGt8zg7Ny8djbYMhxl2zuEevVa7r2gJjYY5Lwr1xM7+XU2nd6CkIWFTVcCIbAP63vSz71NaVyyuSk9lHKcy0A==",
+      "dev": true,
+      "license": "MPL-2.0",
+      "engines": {
+        "node": ">=4"
+      }
+    },
     "node_modules/balanced-match": {
       "version": "4.0.4",
       "resolved": "https://registry.npmjs.org/balanced-match/-/balanced-match-4.0.4.tgz",
@@ -2380,6 +2421,67 @@
         "split2": "^4.1.0"
       }
     },
+    "node_modules/playwright": {
+      "version": "1.56.1",
+      "resolved": "https://registry.npmjs.org/playwright/-/playwright-1.56.1.tgz",
+      "integrity": "sha512-aFi5B0WovBHTEvpM3DzXTUaeN6eN0qWnTkKx4NQaH4Wvcmc153PdaY2UBdSYKaGYw+UyWXSVyxDUg5DoPEttjw==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "dependencies": {
+        "playwright-core": "1.56.1"
+      },
+      "bin": {
+        "playwright": "cli.js"
+      },
+      "engines": {
+        "node": ">=18"
+      },
+      "optionalDependencies": {
+        "fsevents": "2.3.2"
+      }
+    },
+    "node_modules/playwright-core": {
+      "version": "1.64.1",
+      "resolved": "https://registry.npmjs.org/playwright-core/-/playwright-core-1.64.1.tgz",
+      "integrity": "sha512-BC4s8y6SEVA6Q1rSxZTto8hI1KUI3xXlHGZgvGqP4IqPdI/a6FX9H29IDNz7vKo9l21b6LfYosScPL6M3xxyDQ==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "peer": true,
+      "bin": {
+        "playwright-core": "cli.js"
+      },
+      "engines": {
+        "node": ">=20"
+      }
+    },
+    "node_modules/playwright/node_modules/fsevents": {
+      "version": "2.3.2",
+      "resolved": "https://registry.npmjs.org/fsevents/-/fsevents-2.3.2.tgz",
+      "integrity": "sha512-xiqMQR4xAeHTuB9uWm+fFRcIOgKBMiOBP+eXiyT7jsgVCq1bkVygt00oASowB7EdtpOHaaPgKt812P9ab+DDKA==",
+      "dev": true,
+      "hasInstallScript": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": "^8.16.0 || ^10.6.0 || >=11.0.0"
+      }
+    },
+    "node_modules/playwright/node_modules/playwright-core": {
+      "version": "1.56.1",
+      "resolved": "https://registry.npmjs.org/playwright-core/-/playwright-core-1.56.1.tgz",
+      "integrity": "sha512-hutraynyn31F+Bifme+Ps9Vq59hKuUCz7H1kDOcBs+2oGguKkWTU50bBWrtz34OUWmIwpBTWDxaRPXrIXkgvmQ==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "bin": {
+        "playwright-core": "cli.js"
+      },
+      "engines": {
+        "node": ">=18"
+      }
+    },
     "node_modules/png-js": {
       "version": "2.0.0",
       "resolved": "https://registry.npmjs.org/png-js/-/png-js-2.0.0.tgz",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arcforgelabs/flow",
-  "version": "2026.10.44",
+  "version": "2026.10.46",
   "description": "Invoicing, bill entry and a financial dashboard for labs, with Seazona and Xero integrations.",
   "license": "MIT",
   "repository": {
@@ -37,7 +37,9 @@
     "db:generate": "drizzle-kit generate && node scripts/db-guard-migrations.js",
     "db:follow-production": "node scripts/replit-workspace-db.js sync",
     "db:follow-production:status": "node scripts/replit-workspace-db.js status",
-    "design-system": "node scripts/design-system/build.mjs"
+    "design-system": "node scripts/design-system/build.mjs",
+    "test:mobile": "playwright test -c test/mobile/playwright.config.js",
+    "test:mobile:budget": "node test/mobile/budget.mjs"
   },
   "dependencies": {
     "@clerk/backend": "3.25.0",
@@ -61,6 +63,8 @@
     "pg": "8.23.1"
   },
   "devDependencies": {
+    "@axe-core/playwright": "4.13.0",
+    "@playwright/test": "1.56.1",
     "drizzle-kit": "0.31.11",
     "esbuild": "0.25.12"
   },

package/server/api/invoicing.js

@@ -1,5 +1,6 @@
 import { and, asc, desc, eq, ilike, inArray, isNull, or, sql } from 'drizzle-orm';
 import express from 'express';
+import { invoicePage, INVOICE_SORTS, normaliseInvoicesView } from '../ui/list-views.js';
 import { FlowError } from '../core/errors.js';
 import { createActionGuard } from '../integrations/call-guard.js';
 import {
@@ -165,6 +166,21 @@ function limitOf(raw, fallback, max) {
   return Math.min(n, max);
 }
 
+function offsetOf(raw) {
+  if (raw === undefined) return 0;
+  const n = Number(text(raw));
+  if (!Number.isInteger(n) || n < 0) throw invalid('offset must be a whole number from 0');
+  return n;
+}
+
+// The Filter chip's view, sent as JSON (list-views.js keeps only what it knows).
+function filterViewOf(raw) {
+  if (raw === undefined || text(raw) === '') return normaliseInvoicesView({});
+  let value;
+  try { value = JSON.parse(String(raw)); } catch { throw invalid('filter must be JSON'); }
+  return normaliseInvoicesView(value);
+}
+
 // A LIKE pattern that matches the text anywhere, with its wildcards escaped.
 const containing = (q) => `%${q.replace(/[\\%_]/g, (c) => `\\${c}`)}%`;
 
@@ -404,7 +420,20 @@ export function createInvoicingRouter({
       throw invalid(`status must be one of ${TABS.join(', ')}`);
     }
     const q = text(req.query.q);
+    // The list pages on the server, so it works with any number of invoices:
+    // the tab and the search pick rows, the Filter chip's view and the sort
+    // (job-view.js, the page's own rules) run over all of them, and one page
+    // goes back with the total.
     const limit = limitOf(req.query.limit, 200, 500);
+    const offset = offsetOf(req.query.offset);
+    const view = filterViewOf(req.query.filter);
+    const sort = text(req.query.sort) || null;
+    if (sort && !INVOICE_SORTS.includes(sort)) throw invalid(`sort must be one of ${INVOICE_SORTS.join(', ')}`);
+    const dir = text(req.query.dir) || 'asc';
+    if (!['asc', 'desc'].includes(dir)) throw invalid('dir must be asc or desc');
+    // The person's own day, for date filters such as This week.
+    const day = text(req.query.today) || new Date().toISOString().slice(0, 10);
+    if (!isRealDate(day)) throw invalid('today must be a date (yyyy-mm-dd)');
     // Each tab switch runs this, so the independent reads run side by side.
     const system = accounting();
     const sendMode = system
@@ -420,11 +449,25 @@ export function createInvoicingRouter({
       const pattern = containing(q);
       where.push(or(ilike(invoices.number, pattern), ilike(invoices.reference, pattern), ilike(contacts.name, pattern)));
     }
-    const rows = await db.select({ invoice: invoices, contactName: contacts.name }).from(invoices)
+    // First the few columns the filter and sort read, for every row; then
+    // the whole rows of the one page.
+    const light = (await db.select({
+      id: invoices.id, number: invoices.number, reference: invoices.reference, issueDate: invoices.issueDate,
+      createdAt: invoices.createdAt, totalCents: invoices.totalCents, contactName: contacts.name,
+    }).from(invoices)
       .leftJoin(contacts, eq(contacts.id, invoices.contactId))
       .where(and(...where))
-      .orderBy(desc(invoices.createdAt), desc(invoices.id))
-      .limit(limit);
+      .orderBy(desc(invoices.createdAt), desc(invoices.id)))
+      .map((row) => ({ ...row, problems: tabs.problems.get(row.id) ?? [] }));
+    const page = invoicePage(light, { view, sort, dir, offset, limit, today: day });
+    const pageIds = page.rows.map((r) => r.id);
+    const full = pageIds.length
+      ? await db.select({ invoice: invoices, contactName: contacts.name }).from(invoices)
+        .leftJoin(contacts, eq(contacts.id, invoices.contactId))
+        .where(and(eq(invoices.organisationId, organisationId), inArray(invoices.id, pageIds)))
+      : [];
+    const byId = new Map(full.map((r) => [r.invoice.id, r]));
+    const rows = pageIds.map((id) => byId.get(id)).filter(Boolean);
     const jobs = await jobsByInvoice(db, organisationId, rows.map((r) => r.invoice.id));
     const systems = work();
     res.json({
@@ -438,6 +481,13 @@ export function createInvoicingRouter({
         problems: tabs.problems.get(invoice.id) ?? [],
       })),
       counts: Object.fromEntries(TABS.map((t) => [t, tabs.ids[t].length])),
+      // The page: where it starts, its size, and every row the filter keeps.
+      offset,
+      limit,
+      total: page.total,
+      totalCents: page.totalCents,
+      // The Filter chip's Client choices: every client of the tab.
+      clients: [...new Set(light.map((r) => r.contactName).filter(Boolean))].sort((a, b) => a.localeCompare(b)),
       sendsTo: system?.name ?? null,
       sendMode: mode,
       // The Linked column: one icon for each connected system.

package/server/app.js

@@ -26,7 +26,8 @@ import { createUiAssetsRouter } from './ui/routes.js';
 // per client, sized for a lab of a few people: `rateLimitPerMinute` for /api,
 // `signInRateLimitPerMinute` for the sign-in page and its config, and
 // `clerkProxyRateLimitPerMinute` for Clerk's Frontend API, which a signed-in
-// browser calls often. `build` is what GET /health reports
+// browser calls often, and `assetRateLimitPerMinute` for the scripts, styles
+// and faces every page loads. `build` is what GET /health reports
 // (server/deployed-build.js); `updates` is a server/update-check.js checker.
 // `integrations` is the started registry (server/integrations/index.js); each
 // adapter's own routes are mounted under /api/<id>, and GET /health reports
@@ -51,6 +52,7 @@ export function createApp({
   rateLimitPerMinute = 120,
   signInRateLimitPerMinute = 30,
   clerkProxyRateLimitPerMinute = 300,
+  assetRateLimitPerMinute = 600,
   defaultFamily = DEFAULT_FAMILY,
   // Buttons that call Xero or Seazona wait between presses (the action
   // guard, server/integrations/call-guard.js). Off only in tests.
@@ -95,7 +97,7 @@ export function createApp({
   }
 
   // The design systems, Flow's components and the faces every page loads.
-  app.use(createUiAssetsRouter());
+  app.use(createUiAssetsRouter({ rateLimitPerMinute: assetRateLimitPerMinute }));
 
   app.use('/api', rateLimit({ limit: rateLimitPerMinute, windowMs: 60_000 }));
 

package/server/auth/people.js

@@ -2,7 +2,7 @@ import { and, asc, eq, isNull, ne, sql } from 'drizzle-orm';
 import { people, PERSON_ROLES } from '../db/schema.js';
 import { FlowError } from '../core/errors.js';
 import { isThemeFamily, normalizeAccent } from '../theme/themes.js';
-import { INVOICE_COLUMNS, normaliseJobsView, normaliseListView, RECONCILE_COLUMNS } from '../ui/job-view.js';
+import { invoiceColumnsView, normaliseJobsView, normaliseListView, PRICE_COLUMNS, RECONCILE_COLUMNS } from '../ui/job-view.js';
 import { normaliseSavedViews, SAVED_VIEW_PAGES } from '../ui/list-views.js';
 import { isPlainEmail } from './settings.js';
 
@@ -58,12 +58,13 @@ export async function setPersonAppearance(db, { id, appearance }) {
 function viewCheck(page) {
   switch (page) {
     case 'jobs': return normaliseJobsView;
-    case 'invoices': return (view) => normaliseListView(view, INVOICE_COLUMNS);
+    case 'invoices': return invoiceColumnsView;
     case 'reconcile': return (view) => normaliseListView(view, RECONCILE_COLUMNS);
+    case 'price-list': return (view) => normaliseListView(view, PRICE_COLUMNS);
     default: return null;
   }
 }
-const VIEW_PAGE_NAMES = ['jobs', 'invoices', 'reconcile'];
+const VIEW_PAGE_NAMES = ['jobs', 'invoices', 'reconcile', 'price-list'];
 
 // A person's saved views as Flow sends them: only the known pages, each
 // checked, so a view saved by an older Flow still loads.

package/server/integrations/call-guard.js

@@ -203,6 +203,10 @@ export function createCallGuard({
   lockName = `${integration}-call-guard`,
   report: reports = true,
   policy: overrides = {},
+  // Optional columns on this adapter's call table, filled from record().
+  // `lane` is the allow-list (anything else is stored null). `rateLimitProblem`
+  // keeps a short token such as Xero's X-Rate-Limit-Problem.
+  telemetry = {},
   now = Date.now,
   log = console,
 } = {}) {
@@ -215,6 +219,14 @@ export function createCallGuard({
   const C = { key: sql.identifier(columns.key ?? 'key'), at: sql.identifier(columns.at ?? 'at') };
   const tag = `[${integration}]`;
   const failed = sql`(failure_kind is not null or status_code >= 500 or (status_code >= 400 and status_code <> 404))`;
+  const laneAllowed = Array.isArray(telemetry.lane) ? telemetry.lane : null;
+  const keepProblem = telemetry.rateLimitProblem === true;
+  const cleanLane = (value) => (laneAllowed?.includes(value) ? value : null);
+  const cleanProblem = (value) => {
+    if (!keepProblem || typeof value !== 'string') return null;
+    const text = value.trim();
+    return /^[A-Za-z][A-Za-z0-9_-]{0,39}$/.test(text) ? text : null;
+  };
 
   const lock = (tx, key) => tx.execute(sql`select pg_advisory_xact_lock(hashtext(${`${lockName}:${key}`}))`);
   const extraColumns = Object.keys(callDefaults).map((column) => sql`, ${sql.identifier(column)}`);
@@ -263,12 +275,17 @@ export function createCallGuard({
   // resourceResumed, opened, closed, budgetSpent }),
   // each of which was just reported once. `callId` names a call row the
   // adapter wrote when it admitted the call: that row is updated, not added.
-  async function record(rawKey, { callId = null, resource = null, path = null, statusCode = null, failureKind = null, durationMs = null } = {}) {
+  async function record(rawKey, { callId = null, resource = null, path = null, statusCode = null, failureKind = null, durationMs = null, lane: laneRaw = null, rateLimitProblem = null } = {}) {
     const key = cleanKey(rawKey);
     const where = cleanResource(resource);
     const nowMs = Number(now());
     const nowAt = new Date(nowMs);
     const status = Number.isInteger(statusCode) ? statusCode : null;
+    const lane = cleanLane(laneRaw);
+    const problem = cleanProblem(rateLimitProblem);
+    const extraCols = sql`${laneAllowed ? sql`, lane` : sql``}${keepProblem ? sql`, rate_limit_problem` : sql``}`;
+    const extraVals = sql`${laneAllowed ? sql`, ${lane}` : sql``}${keepProblem ? sql`, ${problem}` : sql``}`;
+    const extraSet = sql`${laneAllowed ? sql`, lane = ${lane}` : sql``}${keepProblem ? sql`, rate_limit_problem = ${problem}` : sql``}`;
     const outcome = await db.transaction(async (tx) => {
       await lock(tx, key);
       await ensureRow(tx, key);
@@ -276,10 +293,10 @@ export function createCallGuard({
       const took = Number.isFinite(durationMs) ? Math.max(0, Math.round(durationMs)) : null;
       if (callId !== null) {
         await tx.execute(sql`update ${T.calls} set resource = ${where}, request_path = ${normaliseRequestPath(path)}, status_code = ${status},
-          failure_kind = ${kind}, duration_ms = ${took} where id = ${callId} and ${C.key} = ${key}`);
+          failure_kind = ${kind}, duration_ms = ${took}${extraSet} where id = ${callId} and ${C.key} = ${key}`);
       } else {
-        await tx.execute(sql`insert into ${T.calls} (${C.key}, ${C.at}, resource, request_path, status_code, failure_kind, duration_ms${sql.join(extraColumns, sql``)})
-          values (${key}, ${nowAt}, ${where}, ${normaliseRequestPath(path)}, ${status}, ${kind}, ${took}${sql.join(extraValues, sql``)})`);
+        await tx.execute(sql`insert into ${T.calls} (${C.key}, ${C.at}, resource, request_path, status_code, failure_kind, duration_ms${extraCols}${sql.join(extraColumns, sql``)})
+          values (${key}, ${nowAt}, ${where}, ${normaliseRequestPath(path)}, ${status}, ${kind}, ${took}${extraVals}${sql.join(extraValues, sql``)})`);
       }
       const state = await readState(tx, key);
       if (!countsAsFailure({ statusCode: status, failureKind })) {

package/server/integrations/xero/client.js

@@ -1,4 +1,5 @@
 import { FlowError } from '../../core/errors.js';
+import { currentXeroLane } from './governor.js';
 import { XERO_ENDPOINTS } from './settings.js';
 
 // The Xero Accounting API client. Every call goes through the rate-limit
@@ -130,7 +131,7 @@ export function createXeroClient({
       } catch (error) {
         if (error?.code === 'xero_replay_no_match') throw error;
         const timedOut = error?.name === 'AbortError';
-        await guard?.record(tenantId, { ...call, failureKind: timedOut ? 'timeout' : 'network', durationMs: Date.now() - startedAt });
+        await guard?.record(tenantId, { ...call, failureKind: timedOut ? 'timeout' : 'network', durationMs: Date.now() - startedAt, lane: currentXeroLane() });
         throw xeroError(timedOut ? 'xero_timeout' : 'xero_unreachable',
           timedOut ? `Xero did not answer within ${timeoutMs} ms.` : 'Flow could not reach Xero.',
           { status: timedOut ? 504 : 503 });
@@ -169,7 +170,16 @@ export function createXeroClient({
       // A first 401 usually means the access token expired: it is not counted,
       // and the call is tried once more with a fresh token.
       const expiredToken = response.status === 401 && !refreshed;
-      if (!expiredToken) await guard?.record(tenantId, { ...call, statusCode: response.status, durationMs });
+      const problem = response.status === 429 ? response.headers?.get?.('x-rate-limit-problem')?.trim() || null : null;
+      if (!expiredToken) {
+        await guard?.record(tenantId, {
+          ...call,
+          statusCode: response.status,
+          durationMs,
+          lane: currentXeroLane(),
+          rateLimitProblem: problem,
+        });
+      }
       if (response.ok) return payload ?? {};
 
       const error = apiError(response, payload);

package/server/integrations/xero/migrations/0010_xero_call_usage.sql

@@ -0,0 +1,11 @@
+-- The lane a call counted against, and a 429's X-Rate-Limit-Problem, so the
+-- Xero card can show the day's calls without asking Xero. A row from before
+-- this column has no lane: the card does not guess one.
+ALTER TABLE "xero_calls" ADD COLUMN IF NOT EXISTS "lane" text;
+--> statement-breakpoint
+ALTER TABLE "xero_calls" ADD COLUMN IF NOT EXISTS "rate_limit_problem" text;
+--> statement-breakpoint
+DO $flow_guard$ BEGIN
+	ALTER TABLE "xero_calls" ADD CONSTRAINT "xero_calls_lane_valid" CHECK ("lane" is null or "lane" in ('writes', 'sync', 'reads', 'other'));
+EXCEPTION WHEN duplicate_object OR duplicate_table OR invalid_table_definition THEN NULL;
+END $flow_guard$;

package/server/integrations/xero/migrations/meta/_journal.json

@@ -71,6 +71,13 @@
       "when": 1792520000000,
       "tag": "0009_xero_sent_to_contact",
       "breakpoints": true
+    },
+    {
+      "idx": 10,
+      "version": "7",
+      "when": 1792530000000,
+      "tag": "0010_xero_call_usage",
+      "breakpoints": true
     }
   ]
 }

package/server/integrations/xero/routes.js

@@ -14,6 +14,7 @@ import { accountingStatus, checkSentInvoices } from './reconcile.js';
 import { decryptToken, deleteConnection, describeConnection, readConnection, saveConnection } from './connections.js';
 import { authorizeUrl, exchangeCode, fetchConnections, revokeToken, selectConnection } from './oauth.js';
 import { writesAllowed } from './settings.js';
+import { readXeroUsage } from './usage.js';
 import { saveEvents, signatureValid } from './webhooks.js';
 import { DEFAULT_FAMILY } from '../../theme/themes.js';
 import { messagePage as themedMessagePage } from '../../ui/page.js';
@@ -109,8 +110,12 @@ export function callsState(status) {
   return { stopped: Boolean(status.haltedReason) || resources.length > 0, all: Boolean(status.haltedReason), resources, since };
 }
 
+const XERO_INTEGRATION = Object.freeze({ name: 'Xero', logo: 'xero.svg' });
+
 export function createXeroRouter({ db, personAuth, runtime, log = console, buttonCooldowns = true, actions = createActionGuard({ integration: 'xero', actions: XERO_ACTIONS, off: !buttonCooldowns }), messagePage = (options) => themedMessagePage({ ...options, defaultFamily: DEFAULT_FAMILY }) }) {
-  const page = (title, text, tone) => messagePage({ title, text, tone });
+  // Shared callback card (server/ui/page.js): integration marks, status line,
+  // and a short auto-return on success only (issue #211).
+  const page = (title, text, tone, extra = {}) => messagePage({ title, text, tone, integration: XERO_INTEGRATION, ...extra });
   const { settings } = runtime;
   const router = express.Router();
   const act = (name, key) => actions.route(name, { key });
@@ -144,16 +149,29 @@ export function createXeroRouter({ db, personAuth, runtime, log = console, butto
   router.get('/status', ...signedIn, handle(log, async (req, res) => {
     const organisationId = await requireOrganisation(db, req.query.organisationId);
     const connection = await readConnection(db, organisationId);
+    const connected = Boolean(connection && connection.mode === settings.mode);
+    const picture = connected
+      ? await readXeroUsage(db, {
+        organisationId,
+        tenantId: connection.tenantId,
+        governor: runtime.governor.status(connection.tenantId),
+        warningFraction: settings.usageWarningFraction,
+        refreshedAt: connection.refreshedAt,
+        now: runtime.now(),
+      })
+      : { usage: null, freshness: null };
     res.json({
       ok: true,
       mode: settings.mode,
       writesAllowed: writesAllowed(settings),
       redirectUri: settings.redirectUri,
-      connected: Boolean(connection && connection.mode === settings.mode),
+      connected,
       connection: describeConnection(connection),
-      rateLimit: connection ? runtime.governor.status(connection.tenantId) : null,
-      calls: connection ? callsState(await runtime.guardFor(db).status(connection.tenantId)) : null,
+      rateLimit: connected ? runtime.governor.status(connection.tenantId) : null,
+      calls: connected ? callsState(await runtime.guardFor(db).status(connection.tenantId)) : null,
       lastSync: await lastSync(db, organisationId),
+      usage: picture.usage,
+      freshness: picture.freshness,
     });
   }));
 
@@ -213,7 +231,13 @@ export function createXeroRouter({ db, personAuth, runtime, log = console, butto
       if (previous && previous.tenantId !== connection.tenantId) await resetImport(db, entry.organisationId);
       await queueHistoryImport(db, entry.organisationId, { reason: 'connected' });
       log.info?.(`[xero] organisation ${entry.organisationId} connected to Xero tenant ${connection.tenantId} (${settings.mode}) by person ${entry.personId}`);
-      return res.type('html').send(page('Xero is connected', `Flow is connected to ${connection.tenantName || 'your Xero organisation'} (${settings.mode}). Flow is now copying its invoice and payment history in the background. You can close this tab.`, 'success'));
+      const organisation = connection.tenantName || 'your Xero organisation';
+      return res.type('html').send(page(
+        'Xero is connected',
+        'Flow is now copying its invoice and payment history in the background.',
+        'success',
+        { organisation, mode: settings.mode, autoReturnSeconds: 5 },
+      ));
     } catch (error) {
       log.error?.(`[xero] connect failed: ${error.code ?? 'error'}: ${error.message}`);
       const message = error instanceof FlowError ? error.message : 'Something went wrong talking to Xero. Try again.';

package/server/integrations/xero/runtime.js

@@ -21,6 +21,11 @@ export const XERO_CALL_GUARD = Object.freeze({
   name: 'Xero',
   tables: Object.freeze({ state: 'xero_call_guard', calls: 'xero_calls' }),
   policy: Object.freeze({ authStops: 'resource' }),
+  // Kept on the call row so the Xero card can show lanes and 429s after a restart.
+  telemetry: Object.freeze({
+    lane: Object.freeze(['writes', 'sync', 'reads', 'other']),
+    rateLimitProblem: true,
+  }),
 });
 
 export function requireXeroSettings(env = process.env) {

package/server/integrations/xero/usage.js

@@ -0,0 +1,74 @@
+import { sql } from 'drizzle-orm';
+import { assembleUsage, startOfUtcDay } from '../../ui/xero-usage-model.js';
+
+// What the Xero card draws. Read from counters Flow already keeps: the
+// governor's budget, the call log, and the copy's own timestamps. No Xero call.
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+const iso = (value) => (value ? new Date(value).toISOString() : null);
+
+// Calls that count toward the day's budget. A token refresh is recorded, and
+// it is not an Accounting API call, so it stays out of the lanes.
+const BUDGET_CALL = sql`lane is not null and coalesce(resource, '') <> 'token'`;
+
+export async function readXeroUsage(db, { organisationId, tenantId, governor, warningFraction, refreshedAt, now = Date.now() }) {
+  const at = Number(now);
+  const dayStart = startOfUtcDay(at);
+  const weekStart = new Date(dayStart - 6 * DAY_MS);
+  const dayEnd = new Date(dayStart + DAY_MS);
+  const today = new Date(dayStart);
+
+  const [hours, days, tasks, limited, freshness] = await Promise.all([
+    db.execute(sql`
+      select to_char(date_trunc('hour', "at" at time zone 'UTC'), 'YYYY-MM-DD"T"HH24:00:00"Z"') as hour,
+             lane, count(*)::int as n
+      from xero_calls
+      where key = ${tenantId} and "at" >= ${today} and "at" < ${dayEnd} and ${BUDGET_CALL}
+      group by 1, 2`),
+    db.execute(sql`
+      select to_char("at" at time zone 'UTC', 'YYYY-MM-DD') as day, count(*)::int as n
+      from xero_calls
+      where key = ${tenantId} and "at" >= ${weekStart} and "at" < ${dayEnd} and ${BUDGET_CALL}
+      group by 1`),
+    db.execute(sql`
+      select coalesce(nullif(resource, ''), 'call') as task, count(*)::int as n
+      from xero_calls
+      where key = ${tenantId} and "at" >= ${today} and "at" < ${dayEnd} and coalesce(resource, '') <> 'token'
+      group by 1
+      order by n desc, task
+      limit 8`),
+    db.execute(sql`
+      select "at", rate_limit_problem as problem, lane, resource as task
+      from xero_calls
+      where key = ${tenantId} and status_code = 429 and "at" >= ${weekStart}
+      order by "at" desc
+      limit 12`),
+    db.execute(sql`
+      select
+        (select max(received_at) from xero_webhook_events where organisation_id = ${organisationId} and source = 'webhook') as webhook_at,
+        (select max(last_read_at) from xero_mirror_cursors where organisation_id = ${organisationId}) as poll_at,
+        (select last_finished_at from xero_daily_checks where organisation_id = ${organisationId}) as nightly_at,
+        (select max(read_at) from xero_webhook_events where organisation_id = ${organisationId}) as read_at`),
+  ]);
+
+  const fresh = freshness.rows[0] ?? {};
+  const copyCandidates = [fresh.poll_at, fresh.nightly_at, fresh.read_at].filter(Boolean).map((value) => new Date(value).getTime());
+  return {
+    usage: assembleUsage({
+      hourRows: hours.rows,
+      dayRows: days.rows,
+      taskRows: tasks.rows,
+      limitRows: limited.rows,
+      governor,
+      warningFraction,
+      now: at,
+    }),
+    freshness: {
+      webhookAt: iso(fresh.webhook_at),
+      pollAt: iso(fresh.poll_at),
+      nightlyAt: iso(fresh.nightly_at),
+      copyAt: copyCandidates.length ? new Date(Math.max(...copyCandidates)).toISOString() : null,
+      tokenRefreshedAt: iso(refreshedAt),
+    },
+  };
+}