@arcforgelabs/flow 2026.10.32 → 2026.10.34

package/server/integrations/sentry/index.js

@@ -1,16 +1,27 @@
 import * as SentryNode from '@sentry/node';
+import { scrubSpan } from '../../ui/monitoring.js';
 
-// The Sentry adapter (docs/SENTRY.md). It sends the errors Flow logs, and the
-// browser's errors and problem reports, to the installation's own Sentry
+// The Sentry adapter (docs/SENTRY.md). It sends the errors Flow logs, the
+// browser's errors and problem reports, and performance traces from both
+// (when SENTRY_TRACES_SAMPLE_RATE is above 0), to the installation's own Sentry
 // project. Flow ships no DSN: each installation enters its own, here or as
 // the host setting SENTRY_DSN. It has no tables.
 
 // The browser SDK, loaded from Sentry's CDN only while this adapter is on
-// (server/ui/monitoring.js). Pinned, with its integrity hash.
+// (server/ui/monitoring.js). Pinned, with its integrity hash. With traces on,
+// the bundle that also traces; Sentry ships it only with session replay in
+// it too, which Flow never turns on.
 export const SENTRY_BROWSER = Object.freeze({
   src: 'https://browser.sentry-cdn.com/11.4.0/bundle.feedback.min.js',
   integrity: 'sha384-H9RmZ/VaqOPZrUezgCSqHp4t3LoQMd/5+0Y4oEGUB2bddZzSnwZiOYoWneK4diWt',
 });
+export const SENTRY_BROWSER_TRACING = Object.freeze({
+  src: 'https://browser.sentry-cdn.com/11.4.0/bundle.tracing.replay.feedback.min.js',
+  integrity: 'sha384-LjwHQKAojcITl6Q7innDSAFjziFnqV9ovZBNXnXnQwub1VXIdBMJnYrQNihtxSa6',
+});
+
+// The share of requests and page loads traced when the setting is empty.
+export const DEFAULT_TRACES_SAMPLE_RATE = 0.2;
 
 // A DSN is https://<public key>@<host>/<project id>.
 const DSN_PATTERN = /^https:\/\/[0-9a-f]{16,64}@[a-z0-9.-]+(:\d+)?\/(\d+)$/i;
@@ -31,6 +42,7 @@ export const SENTRY_SETUP = {
     { name: 'SENTRY_DSN', label: 'DSN', kind: 'url', help: 'From the Sentry project\'s Client Keys. Browsers see it, so it is not a secret.' },
     { name: 'SENTRY_ENVIRONMENT', label: 'Environment', help: 'How Sentry labels this installation, for example production. Empty: production.' },
     { name: 'SENTRY_FEEDBACK', label: 'Report a problem button', kind: 'onoff', help: 'On: everyone signed in can send a report, with a screenshot, to this Sentry project.' },
+    { name: 'SENTRY_TRACES_SAMPLE_RATE', label: 'Traces', help: 'The share of clicks, page loads and requests timed, from 0 (off) to 1 (all). Empty: 0.2.' },
   ],
 };
 
@@ -40,9 +52,17 @@ export function readSentrySettings(env) {
   if (!DSN_PATTERN.test(dsn)) throw new Error('SENTRY_DSN is not a Sentry DSN (https://<key>@<host>/<project id>).');
   const environment = String(env.SENTRY_ENVIRONMENT ?? '').trim() || 'production';
   const feedback = String(env.SENTRY_FEEDBACK ?? 'on').trim() !== 'off';
-  return { dsn, environment, feedback };
+  const rate = String(env.SENTRY_TRACES_SAMPLE_RATE ?? '').trim();
+  const tracesSampleRate = rate === '' ? DEFAULT_TRACES_SAMPLE_RATE : Number(rate);
+  if (!/^\d*\.?\d+$/.test(rate || '0') || !(tracesSampleRate >= 0 && tracesSampleRate <= 1)) {
+    throw new Error('SENTRY_TRACES_SAMPLE_RATE must be a number from 0 to 1, such as 0.2.');
+  }
+  return { dsn, environment, feedback, tracesSampleRate };
 }
 
+// No trace for the host's health check: it is not a person waiting.
+const UNTRACED_PATHS = new Set(['/health']);
+
 // The release Sentry groups events by: Flow's release tag, else its commit.
 export function sentryRelease(env) {
   const read = (value) => String(value ?? '').trim() || null;
@@ -51,7 +71,7 @@ export function sentryRelease(env) {
   return release ? `flow@${release.replace(/^v/, '')}` : revision ? `flow@${revision.slice(0, 12)}` : null;
 }
 
-// `sdk` is for tests: anything with init, captureMessage, captureException
+// `sdk` is for tests: anything with init, captureEvent, captureException
 // and close, as @sentry/node has.
 export function createSentryAdapter({ sdk = SentryNode, env: hostEnv = process.env } = {}) {
   let settings = null;
@@ -71,10 +91,14 @@ export function createSentryAdapter({ sdk = SentryNode, env: hostEnv = process.e
         release: release ?? undefined,
         // Flow sends what it logs; no request bodies, cookies or IP addresses.
         sendDefaultPii: false,
-        tracesSampleRate: 0,
-        skipOpenTelemetrySetup: true,
+        // A request the browser traced keeps the browser's choice, so a
+        // click and the server work it caused stay one trace.
+        tracesSampler: ({ attributes, inheritOrSampleWith }) => (
+          UNTRACED_PATHS.has(attributes?.['url.path']) ? 0 : inheritOrSampleWith(settings.tracesSampleRate)
+        ),
+        beforeSendSpan: scrubSpan,
       });
-      log.info?.(`[sentry] on: environment ${settings.environment}; report button ${settings.feedback ? 'on' : 'off'}`);
+      log.info?.(`[sentry] on: environment ${settings.environment}; report button ${settings.feedback ? 'on' : 'off'}; traces ${settings.tracesSampleRate > 0 ? settings.tracesSampleRate : 'off'}`);
     },
     async stop() {
       if (settings) await sdk.close(2000);
@@ -90,13 +114,40 @@ export function createSentryAdapter({ sdk = SentryNode, env: hostEnv = process.e
         if (!settings) return;
         const scope = { level: 'error', tags: { source } };
         if (error instanceof Error) sdk.captureException(error, { ...scope, extra: { log: message } });
-        else sdk.captureMessage(message, scope);
+        // Not captureMessage: the SDK adds a stack to it, and Sentry then
+        // names the issue after its top frame ("Object.captureError"), not
+        // the line Flow logged. A plain event keeps the line as the title.
+        else sdk.captureEvent({ message, ...scope });
       },
       // What the browser needs to report to the same project. The DSN is
       // meant for browsers.
       browserMonitoring() {
         if (!settings) return null;
-        return { dsn: settings.dsn, environment: settings.environment, release, feedback: settings.feedback, script: SENTRY_BROWSER };
+        const { tracesSampleRate } = settings;
+        return {
+          dsn: settings.dsn,
+          environment: settings.environment,
+          release,
+          feedback: settings.feedback,
+          tracesSampleRate,
+          script: tracesSampleRate > 0 ? SENTRY_BROWSER_TRACING : SENTRY_BROWSER,
+        };
+      },
+      // Runs `work` in a span of the current trace (server/core/tracing.js).
+      // Work outside a traced request (the pipeline, the workers) starts no
+      // trace of its own.
+      traceSpan({ name, op, attributes }, work) {
+        if (!settings?.tracesSampleRate) return work();
+        return sdk.startSpan({ name, op, attributes, onlyIfParent: true }, work);
+      },
+      // At a request's start: a function that names its trace once the route
+      // is known, or null when this request is not traced.
+      traceRequest() {
+        if (!settings?.tracesSampleRate) return null;
+        const span = sdk.getActiveSpan();
+        if (!span) return null;
+        const root = sdk.getRootSpan(span);
+        return (name) => sdk.updateSpanName(root, name);
       },
     },
   };

package/server/integrations/xero/index.js

@@ -9,6 +9,7 @@ import { findInvoices, listCustomers, listPriceItems, mirrorState } from './look
 import { createXeroRouter } from './routes.js';
 import { createXeroRuntime, requireXeroSettings, XERO_CALL_GUARD } from './runtime.js';
 import { writesAllowed } from './settings.js';
+import { readChangesFirst } from './webhooks.js';
 
 // The Xero adapter (docs/XERO.md). FLOW_INTEGRATIONS=xero turns it on and
 // XERO_MODE says which Xero it acts on. Its tables are created only while it
@@ -131,6 +132,9 @@ export function createXeroAdapter({ runtime: given = null } = {}) {
       // Xero's invoice for one billable job, looked up live (ledger.js): the
       // `liveCheck` for draftInvoiceForObligation.
       checkInvoice: ({ organisationId, obligation }) => xeroLiveCheck(database, current(), organisationId)(obligation),
+      // Xero's latest changes into the copy just before Flow drafts by rule or
+      // sends (webhooks.js); no call when the copy is current.
+      readChanges: ({ organisationId }) => readChangesFirst(database, current(), organisationId),
       // Active Xero contacts, from Flow's copy (lookup.js).
       listCustomers: ({ organisationId }) => listCustomers(database, organisationId),
       // Sales invoices from the mirror, with the mirror's state (lookup.js).

package/server/integrations/xero/webhooks.js

@@ -262,6 +262,41 @@ export async function dueDailyChecks(db, runtime, { now = Date.now() } = {}) {
   return due;
 }
 
+// Read before act (issue #45, step 5): just before Flow drafts by rule or
+// sends a batch, Xero's latest changes reach the copy. The copy counts as
+// current when webhooks arrive and none waits, or when it read Xero's changes
+// in the last READ_FIRST_MS. Otherwise this reads the waiting records and the
+// invoice and credit note changes now: about two calls. Answers { state }:
+//   fresh        no call was needed
+//   read         the copy read Xero now; `changed` counts invoices that changed
+//   unavailable  the read could not run (`reason`); act on nothing
+export const READ_FIRST_MS = 10 * 60 * 1000;
+
+export async function readChangesFirst(db, runtime, organisationId, { now = Date.now } = {}) {
+  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 { state: 'unavailable', reason: 'Xero is not connected' };
+  const { rows: [{ waiting }] } = await db.execute(sql`select count(*)::int as waiting from xero_webhook_events
+    where organisation_id = ${organisationId} and pending`);
+  if (!waiting && await webhooksActive(db, runtime, organisationId, { now: Number(now()) })) return { state: 'fresh' };
+  const { rows: [{ oldest }] } = await db.execute(sql`select min(last_read_at) as oldest from xero_mirror_cursors
+    where organisation_id = ${organisationId} and resource in ('invoices', 'credit_notes')`);
+  if (!waiting && oldest && Number(now()) - new Date(oldest).getTime() <= READ_FIRST_MS) return { state: 'fresh' };
+  try {
+    const inbox = await readInbox(db, runtime, organisationId, { now });
+    if (inbox.stopped) return { state: 'unavailable', reason: inbox.stopped === 'budget' ? 'the day\'s Xero calls are kept for people' : 'Xero calls are stopped' };
+    const reads = await mirrorXero(db, runtime, organisationId, { resources: ['invoices', 'credit_notes'], maxPages: 5 });
+    const short = reads.find((r) => !['done', 'refused'].includes(r.stopped));
+    if (short) return { state: 'unavailable', reason: short.stopped === 'budget' ? 'the day\'s Xero calls are kept for people' : 'Xero has more changes than one read takes' };
+    const invoices = reads.find((r) => r.resource === 'invoices');
+    const changed = inbox.invoices.inserted + inbox.invoices.changed + (invoices?.inserted ?? 0) + (invoices?.changed ?? 0);
+    if (changed && !inbox.sent) await checkSentInvoices(db, runtime, organisationId);
+    return { state: 'read', changed };
+  } catch (error) {
+    return { state: 'unavailable', reason: isCallsStopped(error) ? 'Xero calls are stopped' : `reading Xero failed (${error?.code ?? 'error'})` };
+  }
+}
+
 // 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;

package/server/ui/app-page.js

@@ -51,7 +51,7 @@ const BODY = `<div class="fx-app">
   <div id="toasts" class="fx-toasts" aria-live="polite"></div>
 </div>`;
 
-export const APP_PATHS = ['/sign-in', '/jobs', '/invoices', '/invoices/:id', '/people', '/integrations', '/integrations/:id', '/account', '/appearance', '/invoicing-settings', '/price-list'];
+export const APP_PATHS = ['/sign-in', '/jobs', '/invoices', '/invoices/:id', '/people', '/integrations', '/integrations/:id', '/account', '/appearance', '/invoicing-settings', '/price-list', '/custom-fields'];
 
 export function appPage({ defaultFamily }) {
   return renderPage({

package/server/ui/app.js

@@ -13,6 +13,7 @@ import { renderInvoice, renderInvoiceList } from '/assets/ui/invoicing.js';
 import { automationSection } from '/assets/ui/automations.js';
 import { renderInvoicingSettings, sendModeSection } from '/assets/ui/invoicing-settings.js';
 import { renderPriceList } from '/assets/ui/price-list.js';
+import { renderCustomFields } from '/assets/ui/custom-fields.js';
 import { renderJobs } from '/assets/ui/jobs.js';
 import { startMonitoring } from '/assets/ui/monitoring.js';
 import { openSearch } from '/assets/ui/search.js';
@@ -198,6 +199,7 @@ const VIEWS = {
   invoices: { label: 'Invoices', icon: 'invoices', group: 'Work', render: (main, id) => (id ? renderInvoice(main, ui(), id) : renderInvoiceList(main, ui())) },
   'invoicing-settings': { label: 'Invoice rules', icon: 'invoices', group: 'Settings', render: (main) => renderInvoicingSettings(main, ui()) },
   'price-list': { label: 'Price list', icon: 'tag', group: 'Settings', render: (main) => renderPriceList(main, ui()) },
+  'custom-fields': { label: 'Custom fields', icon: 'fields', group: 'Settings', render: (main) => renderCustomFields(main, ui()) },
   people: { label: 'People', icon: 'people', group: 'Settings', ownerOnly: true, render: renderPeople },
   integrations: { label: 'Integrations', icon: 'plug', group: 'Settings', ownerOnly: true, render: (main, id) => (id ? renderIntegration(main, id) : renderIntegrations(main)) },
   // Not in the sidebar: "Manage account" in the account menu opens the same
@@ -212,6 +214,7 @@ const ICON_PATHS = {
   invoices: '<path d="M6 3h9l4 4v14H6z"/><path d="M14 3v5h5M9 13h7M9 17h5"/>',
   people: '<circle cx="9" cy="8" r="3"/><path d="M3 20c0-3.5 2.7-6 6-6s6 2.5 6 6"/><path d="M16 5a3 3 0 010 6M21 20c0-3-1.6-5-4-5.7"/>',
   tag: '<path d="M3 12V4h8l10 10-8 8z"/><circle cx="7.5" cy="8.5" r="1.5"/>',
+  fields: '<rect x="3" y="4" width="18" height="5" rx="1.5"/><rect x="3" y="13" width="18" height="5" rx="1.5"/><path d="M7 6.5h4M7 15.5h7"/>',
   plug: '<path d="M9 3v5M15 3v5M6 8h12v3a6 6 0 01-12 0zM12 17v4"/>',
   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"/>',
@@ -309,11 +312,15 @@ function reportMenuItem(openReport) {
   };
 }
 
+// The page a person lands on after sign-in, and for / or an unknown path.
+// Invoices opens on its Ready tab. A home page can take this over later.
+const START_VIEW = 'invoices';
+
 // The view and, for one record, its id: /invoices/<id> is ['invoices', '<id>'].
 function currentView() {
   const [name, id = null] = location.pathname.replace(/^\/+|\/+$/g, '').split('/');
   if (VIEWS[name] && (!VIEWS[name].ownerOnly || me?.person.role === 'owner')) return [name, id];
-  return ['jobs', null];
+  return [START_VIEW, null];
 }
 
 async function route() {
@@ -533,7 +540,7 @@ const STATE_TONE = { ready: 'success', disabled: 'mute', failed: 'danger', resta
 const CATALOGUE = {
   xero: { maker: 'Xero', category: 'accounting', blurb: 'Send invoices to Xero as drafts and bring payments back.', logo: 'xero.svg' },
   seazona: { maker: 'Seazona', category: 'lab', blurb: 'Bring lab cases and orders into Flow as jobs.', logo: 'seazona.svg' },
-  sentry: { maker: 'Sentry', category: 'monitoring', blurb: 'Send errors and problem reports to your own Sentry project.', logo: 'sentry.svg' },
+  sentry: { maker: 'Sentry', category: 'monitoring', blurb: 'Send errors, problem reports and speed traces to your own Sentry project.', logo: 'sentry.svg' },
 };
 const CATEGORIES = [['all', 'All'], ['accounting', 'Accounting'], ['lab', 'Lab software'], ['monitoring', 'Monitoring']];
 const CATEGORY_LABEL = Object.fromEntries(CATEGORIES);
@@ -774,6 +781,7 @@ async function renderIntegration(main, id) {
           current.state === 'failed' && current.error ? notice(current.error, 'danger', 'It could not start.') : null,
           current.id === 'xero' && current.state === 'ready' ? h('section', { class: 'fx-int-section' }, xeroConnection(body.organisations, canChange)) : null,
           current.id === 'seazona' ? h('section', { class: 'fx-int-section fx-card', style: { padding: '8px 20px 16px' } }, automationSection(ui(), 'seazona', 'Ready to invoice')) : null,
+          on && current.state === 'ready' ? personSettingsSection(current) : null,
           current.id === 'xero' ? h('section', { class: 'fx-int-section fx-card', style: { padding: '8px 20px 16px' } }, sendModeSection(ui())) : null,
           guide ? h('section', { class: 'fx-int-section' },
             h('h2', { class: 'fx-int-section__title' }, 'Set up'),
@@ -798,6 +806,36 @@ async function renderIntegration(main, id) {
   draw(found);
 }
 
+// "Your settings": this person's own choices in one integration
+// (GET /api/work/my-settings), such as Seazona's "Ask before stage moves".
+// Each person sees and changes only their own.
+function personSettingsSection(integration) {
+  const section = h('section', { class: 'fx-int-section' },
+    h('h2', { class: 'fx-int-section__title' }, 'Your settings'), h('div', { class: 'fx-skeleton' }));
+  flow(`/api/work/my-settings?integration=${encodeURIComponent(integration.id)}`).then(({ integrations }) => {
+    const settings = integrations[0]?.settings ?? [];
+    if (!settings.length) { section.remove(); return; }
+    const rows = settings.map((setting) => {
+      const input = h('select', { class: 'fx-select' },
+        [{ value: 'off', label: 'Off' }, { value: 'on', label: 'On' }].map((c) => h('option', { value: c.value, selected: (setting.value ? 'on' : 'off') === c.value }, c.label)));
+      input.addEventListener('change', async () => {
+        input.disabled = true;
+        try {
+          await flow('/api/work/my-settings', { method: 'PUT', body: JSON.stringify({ integration: integration.id, key: setting.key, value: input.value === 'on' }) });
+          toast('Saved for you.', 'success');
+        } catch (error) {
+          input.value = setting.value ? 'on' : 'off';
+          toast(error.message, 'danger');
+        }
+        input.disabled = false;
+      });
+      return settingRow({ label: setting.label, hint: setting.hint, control: input });
+    });
+    section.replaceChildren(section.firstChild, h('div', { class: 'fx-settings' }, rows));
+  }).catch(() => section.remove());
+  return section;
+}
+
 // One setting, laid out the same on every settings screen: a short name, one
 // line of smaller text under it, and the control on the right. Longer help
 // lives behind a link, not here. A wide control (a grid of choices) sits on

package/server/ui/custom-fields.js

@@ -0,0 +1,190 @@
+// Settings, Custom fields (/custom-fields; server/core/custom-fields.js,
+// docs/CUSTOM_FIELDS.md). The fields a lab makes for its jobs, like ClickUp's
+// custom fields: each row is one field, with its type and, for a dropdown,
+// its options in lane order. Create field and Edit open a dialog. The work
+// systems' own fields (Seazona's stage) show below, read only: Flow reads
+// them and never changes them here. Everyone can read the page; an owner or
+// admin changes it. The caller passes in app.js's shared pieces as `ui`.
+
+const DOCS = 'https://github.com/arcforgelabs/flow/blob/main/docs/CUSTOM_FIELDS.md';
+const TYPE_LABELS = {
+  dropdown: 'Dropdown', person: 'Person', checkbox: 'Checkbox', date: 'Date', number: 'Number', text: 'Text',
+};
+const TYPE_HINTS = {
+  dropdown: 'One option from a list. Makes board lanes.',
+  person: 'One person in Flow. Makes board lanes.',
+  checkbox: 'Yes or no. Makes board lanes.',
+  date: 'A day, for example a promised date.',
+  number: 'A number, for example units.',
+  text: 'A short note.',
+};
+
+export async function renderCustomFields(main, ui) {
+  const { h, flow, toast, notice, dialog, pageHeader, me } = ui;
+  const disabled = !['owner', 'admin'].includes(me?.person.role);
+  const host = h('div', { class: 'fx-card', style: { padding: '8px 20px 16px' } }, h('div', { class: 'fx-skeleton' }));
+  const addButton = h('button', { class: 'fx-btn fx-btn--primary', type: 'button', disabled }, 'Create field');
+  main.append(pageHeader('Custom fields', { subtitle: 'Fields for your jobs. They stay in Flow and never change Seazona or Xero.', actions: [addButton] }), host);
+
+  let data = null;
+
+  async function send(path, method, payload, done = 'Saved.') {
+    try {
+      const body = await flow(path, { method, ...(payload ? { body: JSON.stringify(payload) } : {}) });
+      if (done) toast(done, 'success');
+      return body;
+    } catch (error) {
+      toast(error.message, 'danger');
+      return null;
+    }
+  }
+
+  const row = (name, hint, control) => h('div', { class: 'fx-set__row' },
+    h('div', { class: 'fx-set__text' }, h('span', { class: 'fx-set__name' }, name), hint),
+    h('div', { class: 'fx-set__control fx-rule__controls' }, control));
+  const optionChip = (o) => h('span', { class: 'fx-cf__opt', 'data-color': o.color ?? 'gray' }, o.name);
+  const typeChip = (type) => h('span', { class: 'fx-chip fx-chip--static' }, TYPE_LABELS[type] ?? type);
+
+  // The option list editor for a dropdown: one line per option (name,
+  // colour, move up, remove), in lane order.
+  function optionsEditor(start) {
+    let options = start.filter((o) => !o.archived).map((o) => ({ ...o }));
+    const list = h('div', { class: 'fx-fields fx-cf__options' });
+    const add = h('button', { class: 'fx-btn fx-btn--ghost fx-btn--sm', type: 'button' }, 'Add option');
+    function draw() {
+      list.replaceChildren(...options.map((o, i) => {
+        const name = h('input', { class: 'fx-input', maxlength: '40', value: o.name, 'aria-label': `Option ${i + 1}`, placeholder: 'Option name' });
+        name.addEventListener('input', () => { o.name = name.value; });
+        const color = h('select', { class: 'fx-select fx-cf__color', 'aria-label': `Colour of option ${i + 1}`, 'data-color': o.color },
+          data.colors.map((c) => h('option', { value: c }, c[0].toUpperCase() + c.slice(1))));
+        color.value = o.color ?? 'gray';
+        color.addEventListener('change', () => { o.color = color.value; color.dataset.color = color.value; });
+        const up = h('button', { class: 'fx-btn fx-btn--ghost fx-btn--sm', type: 'button', 'aria-label': `Move option ${i + 1} up`, disabled: i === 0 }, '↑');
+        up.addEventListener('click', () => { [options[i - 1], options[i]] = [options[i], options[i - 1]]; draw(); });
+        const remove = h('button', { class: 'fx-btn fx-btn--ghost fx-btn--sm fx-rule__delete', type: 'button', 'aria-label': `Remove option ${i + 1}` }, 'Remove');
+        remove.addEventListener('click', () => { options.splice(i, 1); draw(); });
+        return h('div', { class: 'fx-cf__line' }, name, color, up, remove);
+      }));
+      if (!options.length) list.append(h('span', { class: 'fx-dim' }, 'No options yet.'));
+    }
+    add.addEventListener('click', () => {
+      options.push({ name: '', color: data.colors[options.length % data.colors.length] });
+      draw();
+      list.querySelector('.fx-cf__line:last-child input')?.focus();
+    });
+    draw();
+    return {
+      element: h('div', { class: 'fx-fields' }, list, add),
+      value: () => options.filter((o) => o.name.trim()).map(({ id, name, color }) => ({ ...(id ? { id } : {}), name, color })),
+    };
+  }
+
+  // The dialog for a new field (field null) or an existing one. The type is
+  // fixed once the field exists.
+  async function edit(field, draft = field) {
+    const label = (text, control, hint) => h('div', { class: 'fx-field' }, h('span', { class: 'fx-label' }, text), control, hint ?? null);
+    const name = h('input', { class: 'fx-input', required: true, maxlength: '60', value: draft?.name ?? '', 'aria-label': 'Field name', placeholder: 'For example Priority' });
+    const type = h('select', { class: 'fx-select', 'aria-label': 'Type', disabled: Boolean(field) },
+      data.types.map((t) => h('option', { value: t }, TYPE_LABELS[t] ?? t)));
+    type.value = draft?.type ?? 'dropdown';
+    const typeHint = h('span', { class: 'fx-dim' }, TYPE_HINTS[type.value]);
+    const editor = optionsEditor(draft?.options ?? [
+      { name: 'To do', color: 'gray' }, { name: 'Doing', color: 'blue' }, { name: 'Done', color: 'green' },
+    ]);
+    const optionsField = label('Options', editor.element, h('span', { class: 'fx-dim' }, 'Board lanes follow this order. A removed option is kept for old jobs.'));
+    const showOptions = () => { optionsField.hidden = type.value !== 'dropdown'; typeHint.textContent = TYPE_HINTS[type.value]; };
+    type.addEventListener('change', showOptions);
+    showOptions();
+
+    let action = null;
+    const parts = [label('Name', name), label('Type', type, typeHint), optionsField];
+    if (field) {
+      const archive = h('button', { class: 'fx-btn fx-btn--ghost fx-btn--sm fx-rule__delete', type: 'button' }, 'Archive field');
+      archive.addEventListener('click', () => { action = 'archive'; archive.closest('dialog').close(); });
+      parts.push(archive);
+    }
+    const ok = await dialog({ title: field ? `Edit ${field.name}` : 'Create field', body: h('div', { class: 'fx-fields fx-rule__dialog' }, ...parts), confirm: field ? 'Save' : 'Create field' });
+    if (action === 'archive') {
+      if (await send(`/api/custom-fields/${field.id}/archive`, 'POST', { archived: true }, 'Archived. Its values are kept.')) return load();
+      return null;
+    }
+    if (!ok) return null;
+    const payload = { name: name.value };
+    if (!field) payload.type = type.value;
+    if (type.value === 'dropdown') payload.options = editor.value();
+    const body = field
+      ? await send(`/api/custom-fields/${field.id}`, 'PUT', payload)
+      : await send('/api/custom-fields', 'POST', payload, 'Field created.');
+    if (!body) return edit(field, { ...draft, ...payload, type: type.value });
+    return load();
+  }
+
+  async function move(index, by) {
+    const ids = data.fields.map((f) => f.id);
+    [ids[index], ids[index + by]] = [ids[index + by], ids[index]];
+    if (await send('/api/custom-fields/order', 'PUT', { ids }, null)) await load();
+  }
+
+  function fieldRow(field, index) {
+    const hint = h('div', { class: 'fx-price__hint' }, typeChip(field.type),
+      ...(field.type === 'dropdown' ? field.options.filter((o) => !o.archived).map(optionChip) : [h('span', { class: 'fx-set__hint' }, TYPE_HINTS[field.type])]));
+    const controls = [];
+    if (index !== null) {
+      const up = h('button', { class: 'fx-btn fx-btn--ghost fx-btn--sm', type: 'button', disabled: disabled || index === 0, 'aria-label': `Move ${field.name} up` }, '↑');
+      up.addEventListener('click', () => move(index, -1));
+      const down = h('button', { class: 'fx-btn fx-btn--ghost fx-btn--sm', type: 'button', disabled: disabled || index === data.fields.length - 1, 'aria-label': `Move ${field.name} down` }, '↓');
+      down.addEventListener('click', () => move(index, 1));
+      const editButton = h('button', { class: 'fx-btn fx-btn--ghost fx-btn--sm', type: 'button', disabled }, 'Edit');
+      editButton.addEventListener('click', () => edit(field));
+      controls.push(up, down, editButton);
+    } else {
+      const back = h('button', { class: 'fx-btn fx-btn--ghost fx-btn--sm', type: 'button', disabled }, 'Bring back');
+      back.addEventListener('click', async () => {
+        if (await send(`/api/custom-fields/${field.id}/archive`, 'POST', { archived: false }, 'Brought back.')) await load();
+      });
+      controls.push(back);
+    }
+    return row(field.name, hint, h('div', { class: 'fx-row' }, ...controls));
+  }
+
+  function systemRow(field) {
+    const options = field.options.slice(0, 12).map((o) => h('span', { class: 'fx-cf__opt', 'data-color': o.final ? 'green' : 'gray' }, o.name));
+    if (field.options.length > 12) options.push(h('span', { class: 'fx-set__hint' }, `${field.options.length - 12} more`));
+    return row(`${field.sourceLabel} ${field.name.toLowerCase()}`, h('div', { class: 'fx-price__hint' }, typeChip(field.type), ...options),
+      h('span', { class: 'fx-status', 'data-tone': 'mute' }, `Read only · from ${field.sourceLabel}`));
+  }
+
+  function draw() {
+    const archived = data.archived.filter((f) => f.archived);
+    const sections = [
+      disabled ? notice('Only an owner or admin can change these. Everyone can set a job\'s values.', 'info') : null,
+      h('section', { class: 'fx-set' }, h('h2', { class: 'fx-set__title' }, `Your fields · ${data.fields.length}`),
+        ...(data.fields.length ? data.fields.map(fieldRow)
+          : [h('p', { class: 'fx-dim' }, 'No fields yet. Create one, for example Priority or Technician, to group the Jobs board by it.')])),
+    ];
+    if (data.systemFields.length) {
+      sections.push(h('section', { class: 'fx-set' }, h('h2', { class: 'fx-set__title' }, 'From integrations'),
+        ...data.systemFields.map(systemRow),
+        h('p', { class: 'fx-dim', style: { margin: '8px 0 0' } }, 'Flow reads these. Change them in their own system.')));
+    }
+    if (archived.length) {
+      sections.push(h('section', { class: 'fx-set' }, h('h2', { class: 'fx-set__title' }, `Archived · ${archived.length}`), ...archived.map((f) => fieldRow(f, null))));
+    }
+    sections.push(h('p', { class: 'fx-dim', style: { margin: '8px 0 0' } }, h('a', { href: DOCS, target: '_blank', rel: 'noopener' }, 'How custom fields work')));
+    host.replaceChildren(...sections.filter(Boolean));
+  }
+
+  async function load() {
+    try {
+      const [live, all] = await Promise.all([flow('/api/custom-fields'), flow('/api/custom-fields?archived=1')]);
+      data = { ...live, archived: all.fields };
+    } catch (error) {
+      host.replaceChildren(notice(error.message, 'danger'));
+      return;
+    }
+    draw();
+  }
+
+  addButton.addEventListener('click', () => edit(null));
+  await load();
+}

package/server/ui/flow.css

@@ -105,6 +105,15 @@ body:is([data-state="off"], [data-state="error"], [data-state="no-access"]) .fx-
   border-radius: var(--t-radius-lg); box-shadow: var(--t-shadow);
 }
 .fx-panel { overflow: hidden; }
+/* A list that is loading: a thin moving line on top. A list from another
+   tab, shown until the new one comes, is dimmed and cannot be clicked. */
+.fx-panel[aria-busy="true"] { position: relative; }
+.fx-panel[aria-busy="true"]::before {
+  content: ""; position: absolute; inset: 0 0 auto; height: 2px; z-index: 1;
+  background: linear-gradient(90deg, transparent, var(--t-accent), transparent) 0 0 / 200% 100%;
+  animation: fx-shimmer 1s linear infinite;
+}
+.fx-panel[data-stale] { opacity: .5; pointer-events: none; transition: opacity .15s; }
 
 /* The signed-in app: a standard left sidebar, then the view. */
 .fx-shell { min-height: 100vh; }
@@ -430,14 +439,23 @@ a.fx-strong:hover { text-decoration: underline; }
 .fx-toolbar--plain .fx-search { margin-bottom: 0; }
 .fx-empty .fx-btn { margin-top: 12px; }
 .fx-panel.fx-empty { display: grid; justify-items: center; }
+.fx-toolbar--end { justify-content: flex-end; }
 /* The board never scrolls sideways: its columns (one per work system status)
-   wrap onto more rows when the page is narrow, and stack on a phone. A long
-   column scrolls inside itself. */
-.fx-board { display: grid; grid-template-columns: repeat(auto-fill, minmax(min(100%, 210px), 1fr)); gap: 10px; align-items: start; }
-.fx-board__col { display: grid; gap: 8px; align-content: start; min-width: 0; padding: 10px 8px 8px; border-radius: var(--t-radius-lg); background: var(--t-s1); }
-.fx-board__head { display: flex; align-items: center; gap: 8px; min-width: 0; padding: 2px 2px 4px; }
+   are about a phone wide, wrap onto more rows when the page is narrow, and
+   stack on a phone. On a wide, tall screen the board fills the page down to
+   its bottom edge, and each column scrolls inside itself (jobs.js sets
+   fx-main--board while the board shows). */
+.fx-board { display: grid; grid-template-columns: repeat(auto-fill, minmax(min(100%, 256px), 1fr)); gap: 12px; align-items: start; }
+.fx-board__col { display: flex; flex-direction: column; gap: 8px; min-width: 0; min-height: 0; padding: 10px 6px 6px 8px; border-radius: var(--t-radius-lg); background: var(--t-s1); }
+.fx-board__head { display: flex; flex: none; align-items: center; gap: 8px; min-width: 0; padding: 2px 4px 4px 2px; }
 .fx-board__sum { flex: none; margin-left: auto; color: var(--t-dim); font-size: 12px; font-variant-numeric: tabular-nums; }
-.fx-board__cards { display: grid; gap: 8px; max-height: 70vh; overflow-y: auto; }
+.fx-board__cards { display: grid; gap: 8px; align-content: start; min-height: 0; max-height: 70vh; padding-right: 2px; overflow-y: auto; scrollbar-width: thin; }
+@media (min-width: 821px) and (min-height: 560px) {
+  .fx-main--board { height: 100vh; height: 100dvh; padding: 24px 24px 16px; grid-template-rows: auto auto minmax(0, 1fr); align-content: stretch; }
+  .fx-main--board > .fx-jobs { min-height: 0; }
+  .fx-main--board .fx-board { height: 100%; overflow-y: auto; grid-auto-rows: 100%; align-items: stretch; }
+  .fx-main--board .fx-board__cards { flex: 1; max-height: none; }
+}
 .fx-board__none { padding: 8px 4px; color: var(--t-dim); font-size: 13px; }
 .fx-table--jobs tbody tr { cursor: pointer; }
 
@@ -467,9 +485,10 @@ a.fx-strong:hover { text-decoration: underline; }
 .fx-job { position: relative; display: grid; min-width: 0; padding: 11px 12px 9px; border: 1px solid var(--fx-line); border-radius: var(--t-radius); background: var(--t-paper); box-shadow: var(--t-shadow); font-size: 13px; cursor: pointer; }
 .fx-job:hover { border-color: var(--t-brd-hi, var(--fx-line)); }
 .fx-job:focus-visible { outline: 2px solid var(--t-ring, var(--t-accent)); outline-offset: 2px; }
-.fx-job__client { display: -webkit-box; overflow: hidden; color: var(--t-strong); font-size: 14px; font-weight: 600; line-height: 1.3; -webkit-line-clamp: 2; -webkit-box-orient: vertical; overflow-wrap: anywhere; }
-.fx-job__who { display: flex; align-items: center; gap: 6px; min-width: 0; margin-top: 5px; color: var(--t-dim); font-size: 12.5px; }
-.fx-job__who span { min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.fx-job__client { color: var(--t-strong); font-size: 14px; font-weight: 600; line-height: 1.3; overflow-wrap: anywhere; }
+.fx-job__who { display: flex; align-items: flex-start; gap: 6px; min-width: 0; margin-top: 5px; color: var(--t-dim); font-size: 12.5px; }
+.fx-job__who span { min-width: 0; overflow-wrap: anywhere; }
+.fx-job__who svg { margin-top: 2px; }
 .fx-job__who svg, .fx-job__date svg { flex: none; color: var(--t-mute); }
 .fx-job__foot { display: flex; align-items: center; gap: 8px; margin-top: 10px; padding-top: 8px; border-top: 1px solid var(--fx-line-soft); color: var(--t-dim); font-size: 12px; }
 .fx-job__date { display: inline-flex; align-items: center; gap: 5px; min-width: 0; overflow: hidden; white-space: nowrap; }
@@ -746,6 +765,18 @@ body[data-state="loading"] .fx-loading { display: grid; justify-items: center; }
 .fx-price__systems { display: flex; flex-wrap: wrap; gap: 6px; margin: 0 0 10px; }
 .fx-set__control .fx-price__link { width: 260px; min-width: 0; }
 @media (max-width: 560px) { .fx-set__control .fx-price__link { width: 150px; } }
+/* Custom fields (custom-fields.js): option chips with a colour dot, and the
+   dialog's option lines. The option colours are fixed, like ClickUp's. */
+.fx-cf__opt { display: inline-flex; align-items: center; gap: 6px; padding: 2px 9px; border: 1px solid var(--fx-line); border-radius: 999px; font-size: 12.5px; color: var(--t-text); white-space: nowrap; }
+.fx-cf__opt::before { content: ""; width: 8px; height: 8px; border-radius: 50%; background: var(--cf); flex: none; }
+[data-color="gray"] { --cf: #8a8f98; } [data-color="blue"] { --cf: #3b82f6; } [data-color="teal"] { --cf: #14b8a6; }
+[data-color="green"] { --cf: #22a35a; } [data-color="amber"] { --cf: #e0a019; } [data-color="red"] { --cf: #e5484d; }
+[data-color="purple"] { --cf: #8b5cf6; } [data-color="pink"] { --cf: #e5469a; }
+.fx-cf__options { display: grid; gap: 8px; }
+.fx-cf__line { display: grid; grid-template-columns: minmax(0, 1fr) 120px auto auto; gap: 8px; align-items: center; }
+.fx-cf__line .fx-input, .fx-cf__line .fx-select { width: 100%; min-width: 0; }
+.fx-cf__color { border-left: 4px solid var(--cf); }
+@media (max-width: 560px) { .fx-cf__line { grid-template-columns: minmax(0, 1fr) 96px; } }
 /* Invoice rules (invoice-rules.js): a row's Edit button and switch, and the
    rule dialog's condition lines. */
 .fx-rule__controls { align-items: center; gap: 10px; }
@@ -818,3 +849,20 @@ body[data-state="loading"] .fx-loading { display: grid; justify-items: center; }
 .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; }
+
+/* New invoice from a job: a quiet strip above the form, and a searchable
+   list of jobs with no invoice. */
+.fx-fromjob {
+  display: flex; flex-wrap: wrap; align-items: center; justify-content: space-between; gap: 10px 16px;
+  padding: 12px 16px; border: 1px dashed var(--fx-line); border-radius: var(--t-radius);
+}
+.fx-fromjob__text { display: grid; gap: 2px; font-size: 14px; }
+.fx-dialog:has(.fx-pick__body) { width: min(620px, calc(100vw - 32px)); }
+.fx-pick__body { display: grid; gap: 12px; }
+.fx-pick { display: grid; max-height: min(420px, 55vh); overflow-y: auto; border: 1px solid var(--fx-line); border-radius: var(--t-radius); }
+.fx-pick__row { display: grid; grid-template-columns: auto 1fr auto; align-items: center; gap: 12px; padding: 10px 14px; border-bottom: 1px solid var(--fx-line); cursor: pointer; }
+.fx-pick__row:last-child { border-bottom: 0; }
+.fx-pick__row:hover, .fx-pick__row:has(input:checked) { background: var(--fx-hover); }
+.fx-pick__row[hidden] { display: none; }
+.fx-pick__main { display: grid; gap: 2px; min-width: 0; }
+.fx-pick > .fx-dim { padding: 14px; }