@xeplr/ui-factory 1.0.12 → 1.0.14

package/README.md

@@ -178,6 +178,55 @@ import schemaHandler from '@xeplr/schema-handler'          // CommonJS: default
 const clean = schemaHandler.applySchema(formSchema(screen), req.body)   // throws ValidationError listing each field
 ```
 
+## Flows — screens, one after another
+
+A screen is a form; a **flow** is the journey across several of them. Design it
+the same way you design a form — screens on a canvas, arrows between them:
+
+```jsx
+import { FlowBuilder, FlowRunner, createFlowsApi } from '@xeplr/ui-factory'
+const flows = createFlowsApi({ fetch: authFetch, base: '/api' })
+
+<FlowBuilder {...flows.builderProps} flow={flow} screens={published} loadScreen={factory.loadScreen} />
+<FlowRunner  {...flows.runnerProps} {...factory.screenProps} flowKey="employee_registration" runId={runId} />
+```
+
+An arrow is a question asked once its screen is filled in — the first one that
+fits wins, and the one with no test ("otherwise") catches the rest:
+
+```json
+{ "stepKey": "details", "screen": "employee_edit",
+  "transitions": [
+    { "when": { "field": "type", "op": "=", "value": "contractor" }, "target": "contract" },
+    { "when": null, "target": "payroll" }
+  ] }
+```
+
+**The browser does not run the journey.** `createFlowsApi` talks to a service
+that does — Xeplr Workflow — so a run remembers where it got to: a journey can
+be left and picked up later, by someone else, on another day. Without such a
+service there are no flows; the factory has no engine of its own, on purpose.
+
+**Each screen still saves itself, into its own table.** What travels with the
+run is only what the arrows need and the id of the row that was written
+(`recordId`), so the data is exactly where it would be without a flow.
+
+`validateFlow(flow, { screens })` is the same check on both sides: a screen
+that exists, arrows that point somewhere, one "otherwise" at the end, and
+nothing unreachable.
+
+### A flow and a stepper
+
+Both walk someone through something, and they answer different questions:
+
+| | stepper | flow |
+|---|---|---|
+| where | steps of ONE screen | several screens |
+| when | one sitting | over days, if need be |
+| who | one person | can change hands |
+| decides | a `step` hook, in the browser | the engine, on the server |
+| needs | nothing | a workflow service |
+
 ## Controls
 
 | type | value | validation |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xeplr/ui-factory",
-  "version": "1.0.12",
+  "version": "1.0.14",
   "description": "Design data-entry screens on @xeplr/ui-canvas, save them as JSON, run them as auto-saving forms with lists of saved records — built for Claude to draft and people to refine",
   "type": "module",
   "main": "src/index.js",

package/src/designs/FlowBuilderSample.jsx

@@ -0,0 +1,274 @@
+import { XeplrCanvas } from '@xeplr/ui-canvas'
+import { FLOW_END, FLOW_OPERATORS, VALUELESS_OPERATORS, describeWhen } from '../flow.js'
+
+// THE FLOW DESIGNER — screens on a canvas, arrows between them.
+//
+// A box is a screen. An arrow leaving it is a question asked once the screen
+// is filled in: the first arrow whose test passes wins, and the one with no
+// test — "otherwise" — catches the rest. That is the whole language, and it is
+// the same one the engine runs.
+//
+// Presentation only: everything comes from useFlowBuilder.
+
+const STEP_W = 200
+const STEP_H = 86
+
+const STATUS = {
+  saved: 'All changes saved',
+  pending: 'Unsaved changes…',
+  saving: 'Saving…',
+  invalid: 'Not saved — finish the flow first',
+  error: 'Not saved'
+}
+
+export default function FlowBuilderSample({ ctrl, className, style }) {
+  const { flow } = ctrl
+  const items = flow.steps.map((s) => ({
+    id: s.stepKey,
+    x: (s.layout && s.layout.x) || 40,
+    y: (s.layout && s.layout.y) || 40,
+    w: STEP_W,
+    h: STEP_H
+  }))
+  // One arrow per transition. A step that ends the journey gets a stub to a
+  // "Finished" pill, the way the workflow editor draws its ends.
+  const edges = flow.steps.flatMap((s) => s.transitions.map((t, i) => ({
+    id: `${s.stepKey}-${i}`,
+    from: s.stepKey,
+    ...(t.target === FLOW_END || !flow.steps.some((x) => x.stepKey === t.target)
+      ? { toOffset: { x: 90, y: 0 }, done: true }
+      : { to: t.target }),
+    variant: t.when ? undefined : 'dashed',
+    label: describeWhen(t.when, labelOf(ctrl, s.stepKey, t.when))
+  })))
+
+  return (
+    <div className={'xeplr-factory-flow-builder' + (className ? ' ' + className : '')} style={style}>
+      <header className="xeplr-factory-bar">
+        <input
+          className="xeplr-factory-name"
+          value={flow.name}
+          onChange={(e) => ctrl.rename(e.target.value)}
+          placeholder="What is this journey called?"
+          aria-label="Flow name"
+        />
+        <code className="xeplr-factory-flow-key" title="The key this flow is known by — it never changes">{flow.key}</code>
+        <div className={`xeplr-factory-bar-status xeplr-factory-bar-status--${ctrl.status}`} role="status" aria-live="polite">
+          {ctrl.status === 'error' ? `Not saved — ${ctrl.saveError}` : STATUS[ctrl.status]}
+        </div>
+        {ctrl.validation.errors.length > 0 && (
+          <span className="xeplr-factory-problems" title={ctrl.validation.errors.map((x) => `${x.path}: ${x.message}`).join('\n')}>
+            {ctrl.validation.errors.length} problem{ctrl.validation.errors.length === 1 ? '' : 's'}
+          </span>
+        )}
+        {flow.steps.length > 1 && (
+          <button type="button" className="xeplr-factory-secondary" onClick={ctrl.tidy} title="Lay the screens out as the journey reads">Tidy</button>
+        )}
+        {ctrl.canPublish && (
+          <button type="button" className="xeplr-factory-primary" onClick={ctrl.publish} disabled={ctrl.publishing || !ctrl.validation.ok}>
+            {ctrl.publishing ? 'Publishing…' : 'Publish'}
+          </button>
+        )}
+      </header>
+
+      {ctrl.publishResult && (
+        <div className={`xeplr-factory-publish${ctrl.publishResult.ok ? ' is-ok' : ' is-error'}`} role="status">
+          <span>{ctrl.publishResult.message}</span>
+          <button type="button" className="xeplr-factory-icon-button" aria-label="Dismiss" onClick={ctrl.clearPublishResult}>×</button>
+        </div>
+      )}
+
+      <div className="xeplr-factory-body">
+        <aside className="xeplr-factory-palette" aria-label="Screens">
+          <div className="xeplr-factory-palette-group">
+            <h3 className="xeplr-factory-palette-title">Screens</h3>
+            {ctrl.screens.length === 0 && <p className="xeplr-factory-hint">No published forms yet.</p>}
+            {ctrl.screens.map((s) => (
+              <button
+                key={s.id}
+                type="button"
+                className="xeplr-factory-palette-item"
+                onClick={() => ctrl.addStep(s.id, nextPlace(flow))}
+                title={`Add ${s.name || s.id} to the journey`}
+              >
+                {s.name || s.id}
+              </button>
+            ))}
+          </div>
+        </aside>
+
+        <div className="xeplr-factory-stage">
+          <XeplrCanvas
+            className="xeplr-factory-flow-canvas"
+            items={items}
+            edges={edges}
+            features={{ drag: true, snap: true }}
+            selection={ctrl.selected ? [ctrl.selected] : []}
+            onSelectionChange={(ids) => ctrl.setSelected([...ids][0] || null)}
+            onItemChange={(id, patch) => ctrl.moveStep(id, patch)}
+            onItemClick={(id) => ctrl.setSelected(id)}
+            renderItem={(item) => {
+              const step = flow.steps.find((s) => s.stepKey === item.id)
+              if (!step) return null
+              const problems = ctrl.errorsByStep[step.stepKey] || []
+              return (
+                <div className={`xeplr-factory-step-card${ctrl.selected === step.stepKey ? ' is-selected' : ''}${problems.length ? ' has-error' : ''}`}>
+                  <span className="xeplr-factory-step-card-name">{step.label || step.stepKey}</span>
+                  <span className="xeplr-factory-step-card-screen">{screenName(ctrl, step.screen)}</span>
+                  {ctrl.first && ctrl.first.stepKey === step.stepKey && <span className="xeplr-factory-step-card-first">starts here</span>}
+                </div>
+              )
+            }}
+            renderEdgeLabel={(edge, { mid }) => (
+              <span className="xeplr-factory-edge-label" style={{ position: 'absolute', left: mid.x, top: mid.y, transform: 'translate(-50%, -50%)' }}>
+                {edge.done ? 'Finished' : edge.label}
+              </span>
+            )}
+            underlay={flow.steps.length === 0 && (
+              <div className="xeplr-factory-empty">Add a screen from the left to start the journey</div>
+            )}
+          />
+        </div>
+
+        <StepPanel ctrl={ctrl} />
+      </div>
+    </div>
+  )
+}
+
+/** What a step does, and where it goes next. */
+function StepPanel({ ctrl }) {
+  const step = ctrl.selectedStep
+  if (!step) {
+    return (
+      <aside className="xeplr-factory-panel" aria-label="Step">
+        <p className="xeplr-factory-panel-empty">
+          Pick a screen on the canvas to say what happens after it.
+          <br /><br />
+          Each arrow is a question asked once that screen is filled in — the first one that fits wins, and “otherwise” catches the rest.
+        </p>
+      </aside>
+    )
+  }
+  const fields = ctrl.fieldsFor(step.stepKey)
+  const others = ctrl.flow.steps.filter((s) => s.stepKey !== step.stepKey)
+
+  return (
+    <aside className="xeplr-factory-panel" aria-label="Step">
+      <div className="xeplr-factory-panel-head">
+        <span className="xeplr-factory-panel-type">{step.label || step.stepKey}</span>
+        <button type="button" className="xeplr-factory-danger-link" onClick={() => ctrl.removeStep(step.stepKey)}>Remove</button>
+      </div>
+
+      <fieldset className="xeplr-factory-group">
+        <legend>Step</legend>
+        <div className="xeplr-factory-prop">
+          <label className="xeplr-factory-prop-label" htmlFor="xf-step-label">Name</label>
+          <input id="xf-step-label" className="xeplr-factory-prop-input" value={step.label || ''} onChange={(e) => ctrl.setStep(step.stepKey, { label: e.target.value })} />
+        </div>
+        <div className="xeplr-factory-prop">
+          <label className="xeplr-factory-prop-label" htmlFor="xf-step-screen">Shows</label>
+          <select id="xf-step-screen" className="xeplr-factory-prop-input" value={step.screen} onChange={(e) => ctrl.setStep(step.stepKey, { screen: e.target.value })}>
+            {ctrl.screens.map((s) => <option key={s.id} value={s.id}>{s.name || s.id}</option>)}
+          </select>
+        </div>
+      </fieldset>
+
+      <fieldset className="xeplr-factory-group">
+        <legend>Then</legend>
+        {step.transitions.length === 0 && <p className="xeplr-factory-hint">The journey ends here.</p>}
+        {step.transitions.map((t, i) => (
+          <div key={i} className="xeplr-factory-arrow">
+            {t.when === null ? (
+              <span className="xeplr-factory-arrow-when">Otherwise</span>
+            ) : (
+              <div className="xeplr-factory-arrow-test">
+                <select
+                  className="xeplr-factory-prop-input"
+                  value={t.when.field || ''}
+                  onChange={(e) => ctrl.setTransition(step.stepKey, i, { when: { ...t.when, field: e.target.value } })}
+                  aria-label="Field"
+                >
+                  <option value="">Which field…</option>
+                  {fields.map((f) => <option key={f.name} value={f.name}>{f.label}</option>)}
+                </select>
+                <select
+                  className="xeplr-factory-prop-input"
+                  value={t.when.op}
+                  onChange={(e) => ctrl.setTransition(step.stepKey, i, { when: { ...t.when, op: e.target.value } })}
+                  aria-label="Test"
+                >
+                  {FLOW_OPERATORS.map((o) => <option key={o.op} value={o.op}>{o.label}</option>)}
+                </select>
+                {!VALUELESS_OPERATORS.includes(t.when.op) && (
+                  <input
+                    className="xeplr-factory-prop-input"
+                    value={t.when.value ?? ''}
+                    placeholder="value"
+                    onChange={(e) => ctrl.setTransition(step.stepKey, i, { when: { ...t.when, value: e.target.value } })}
+                    aria-label="Value"
+                  />
+                )}
+              </div>
+            )}
+            <div className="xeplr-factory-arrow-target">
+              <span>go to</span>
+              <select
+                className="xeplr-factory-prop-input"
+                value={t.target}
+                onChange={(e) => ctrl.setTransition(step.stepKey, i, { target: e.target.value })}
+                aria-label="Goes to"
+              >
+                {others.map((s) => <option key={s.stepKey} value={s.stepKey}>{s.label || s.stepKey}</option>)}
+                <option value={FLOW_END}>Finish</option>
+              </select>
+              <button type="button" className="xeplr-factory-icon-button" aria-label="Remove this arrow" onClick={() => ctrl.disconnect(step.stepKey, i)}>×</button>
+            </div>
+          </div>
+        ))}
+        <div className="xeplr-factory-arrow-add">
+          <button
+            type="button"
+            className="xeplr-factory-add"
+            onClick={() => ctrl.connect(step.stepKey, others.length ? others[0].stepKey : FLOW_END, { field: fields[0] ? fields[0].name : '', op: '=', value: '' })}
+          >
+            + If a field says…
+          </button>
+          {!step.transitions.some((t) => t.when === null) && (
+            <button
+              type="button"
+              className="xeplr-factory-add"
+              onClick={() => ctrl.connect(step.stepKey, others.length ? others[0].stepKey : FLOW_END, null)}
+            >
+              + Otherwise
+            </button>
+          )}
+        </div>
+      </fieldset>
+
+      {(ctrl.errorsByStep[step.stepKey] || []).length > 0 && (
+        <div className="xeplr-factory-panel-errors" role="alert">
+          {ctrl.errorsByStep[step.stepKey].map((e, i) => <div key={i}>{e.message}</div>)}
+        </div>
+      )}
+    </aside>
+  )
+}
+
+/** Where the next screen goes: to the right of the last one, a row lower after four. */
+function nextPlace(flow) {
+  const n = flow.steps.length
+  return { x: 60 + (n % 4) * (STEP_W + 90), y: 80 + Math.floor(n / 4) * (STEP_H + 110) }
+}
+
+function screenName(ctrl, id) {
+  const hit = ctrl.screens.find((s) => s.id === id)
+  return (hit && hit.name) || id
+}
+
+/** A field's label, for an arrow that tests it — the person never sees column names. */
+function labelOf(ctrl, stepKey, when) {
+  if (!when) return null
+  const hit = ctrl.fieldsFor(stepKey).find((f) => f.name === when.field)
+  return hit ? hit.label : when.field
+}

package/src/designs/FlowRunnerSample.jsx

@@ -0,0 +1,69 @@
+import { useRef } from 'react'
+import ScreenSample from './ScreenSample.jsx'
+
+// A flow, running: the screen the run is parked on, and one button forward.
+//
+// Presentation only — everything comes from useFlowRun and useFactoryScreen.
+// The screen saves itself into its own table exactly as it does anywhere else;
+// "Next" hands the run what was filled in, and the run says which screen comes
+// after it. Nothing here knows the journey.
+
+export default function FlowRunnerSample({ run, screen, className, style, title, renderDone }) {
+  const values = useRef({})
+  const record = useRef(null)
+
+  if (run.loading) return <div className="xeplr-factory-flow-loading">Opening…</div>
+  if (run.error) {
+    return (
+      <div className="xeplr-factory-invalid" role="alert">
+        <strong>This journey cannot go on:</strong> {run.error}
+      </div>
+    )
+  }
+  if (run.status === 'done') {
+    return (
+      <div className={'xeplr-factory-flow' + (className ? ' ' + className : '')} style={style}>
+        {renderDone
+          ? renderDone(run)
+          : <div className="xeplr-factory-flow-done" role="status"><strong>All done.</strong> Nothing more to fill in.</div>}
+      </div>
+    )
+  }
+  if (!run.document) return null
+
+  return (
+    <div className={'xeplr-factory-flow' + (className ? ' ' + className : '')} style={style}>
+      {title && (
+        <div className="xeplr-factory-flow-head">
+          <span className="xeplr-factory-flow-where">{title}</span>
+          {run.sending && <span className="xeplr-factory-flow-sending">Working out what comes next…</span>}
+        </div>
+      )}
+      <ScreenSample
+        // A new step is a new form: the key stops the screen keeping the last
+        // one's values while the document changes under it.
+        key={run.stepKey}
+        ctrl={{
+          ...screen,
+          // The flow's forward button IS the screen's own, renamed: one button,
+          // not two that both look like the way on.
+          done: () => run.submit(values.current, record.current),
+          doneLabel: run.sending ? 'Saving…' : 'Next'
+        }}
+      />
+      <FlowValues screen={screen} values={values} record={record} />
+    </div>
+  )
+}
+
+/**
+ * The bridge between the screen and the run: what is filled in, and the row
+ * the screen saved. Kept in refs — the run reads them when the person moves
+ * on, and a re-render on every keystroke would be the form's business, not
+ * the journey's.
+ */
+function FlowValues({ screen, values, record }) {
+  values.current = screen.values
+  record.current = screen.recordId
+  return null
+}

package/src/designs/ScreenSample.jsx

@@ -44,12 +44,20 @@ function StepNav({ ctrl, node, children }) {
   // "Step 2 of 4" counts the steps that apply, not the ones ruled out.
   const live = total - off.length
   const place = at - off.filter((i) => i < at).length + 1
+  // A screen that moves on to something else when it is finished — the next
+  // screen of a flow — has ONE way forward: this form's own steps first, then
+  // that. Two buttons both called Next, one of which skips the steps still to
+  // do, is how a journey gets left half filled in.
+  const handsOn = Boolean(children) && Boolean(ctrl.doneLabel)
+  const lastStep = forward === null
   return (
     <div className="xeplr-factory-stepnav">
       <button type="button" className="xeplr-factory-secondary" onClick={() => go(back, 'back')} disabled={back === null}>Back</button>
       <span className="xeplr-factory-stepnav-where">Step {place} of {live}</span>
-      <button type="button" className="xeplr-factory-primary" onClick={() => go(forward, 'next')} disabled={forward === null}>Next</button>
-      {children}
+      {!(handsOn && lastStep) && (
+        <button type="button" className="xeplr-factory-primary" onClick={() => go(forward, 'next')} disabled={lastStep}>Next</button>
+      )}
+      {(!handsOn || lastStep) && children}
     </div>
   )
 }
@@ -58,8 +66,13 @@ function StepNav({ ctrl, node, children }) {
 function DoneButton({ ctrl }) {
   const saving = ctrl.status === 'pending' || ctrl.status === 'saving'
   return (
-    <button type="button" className="xeplr-factory-secondary" onClick={() => ctrl.flush().then(ctrl.done, ctrl.done)}>
-      {saving ? 'Saving…' : 'Done'}
+    <button
+      type="button"
+      className={ctrl.doneLabel ? 'xeplr-factory-primary' : 'xeplr-factory-secondary'}
+      disabled={!ctrl.canSave && ctrl.status === 'invalid'}
+      onClick={() => ctrl.flush().then(ctrl.done, ctrl.done)}
+    >
+      {saving ? 'Saving…' : (ctrl.doneLabel || 'Done')}
     </button>
   )
 }

package/src/designs/factory.css

@@ -8,7 +8,8 @@
    it shrinks, so the layout keeps its proportions. */
 
 .xeplr-factory-screen,
-.xeplr-factory-canvas {
+.xeplr-factory-canvas,
+.xeplr-factory-flow-builder {
   container-type: inline-size;
   --xf-u: min(1px, calc(100cqw / var(--xf-width, 800)));
   --xf-accent: var(--xeplr-accent, #2563eb);
@@ -318,3 +319,50 @@
 .xeplr-factory-confirm-text { flex: 1; line-height: 1.5; }
 .xeplr-factory-confirm-text ul { margin: 4px 0; padding-left: 18px; }
 .xeplr-factory-confirm-actions { display: flex; gap: 8px; flex-shrink: 0; }
+
+/* ── flows: screens joined by arrows ──────────────────────────────────────
+   The designer wears the builder's chrome (bar, palette, panel); what is new
+   is the step card on the canvas, the label on an arrow, and the rows that
+   say where a step goes next. */
+.xeplr-factory-flow-builder { display: flex; flex-direction: column; height: 100%; min-height: 0; color: var(--xeplr-text-primary, #1a1a19); }
+.xeplr-factory-flow-key { margin-right: auto; padding: 2px 6px; border-radius: 4px; background: var(--xf-border); font-size: 11px; }
+.xeplr-factory-flow-canvas { height: 100%; }
+
+.xeplr-factory-step-card {
+  display: flex; flex-direction: column; justify-content: center; gap: 2px;
+  width: 100%; height: 100%; box-sizing: border-box; padding: 10px 12px;
+  border: 1px solid var(--xf-border); border-radius: 10px; background: var(--xf-surface);
+  box-shadow: 0 1px 2px rgba(0, 0, 0, 0.06);
+}
+.xeplr-factory-step-card.is-selected { border-color: var(--xf-accent); box-shadow: 0 0 0 2px color-mix(in srgb, var(--xf-accent) 30%, transparent); }
+.xeplr-factory-step-card.has-error { border-color: var(--xf-danger); }
+.xeplr-factory-step-card-name { font-weight: 640; color: var(--xf-ink); }
+.xeplr-factory-step-card-screen { color: var(--xf-muted); font-size: 12px; }
+.xeplr-factory-step-card-first { color: var(--xf-accent); font-size: 11px; font-weight: 600; text-transform: uppercase; letter-spacing: 0.05em; }
+
+.xeplr-factory-edge-label {
+  /* Above the curve's midpoint rather than on it, so a label never sits on the
+     card an arrow is arriving at. */
+  margin-top: -12px;
+  padding: 1px 6px; border-radius: 999px; background: var(--xf-surface);
+  border: 1px solid var(--xf-border); color: var(--xf-muted); font-size: 11px; white-space: nowrap;
+}
+
+.xeplr-factory-arrow { padding: 8px 0; border-top: 1px dashed var(--xf-border); }
+.xeplr-factory-arrow:first-of-type { border-top: none; }
+.xeplr-factory-arrow-when { font-weight: 600; font-size: 12px; }
+.xeplr-factory-arrow-test { display: grid; gap: 4px; }
+.xeplr-factory-arrow-target { display: flex; align-items: center; gap: 6px; margin-top: 6px; color: var(--xf-muted); font-size: 12px; }
+.xeplr-factory-arrow-target select { flex: 1; }
+.xeplr-factory-arrow-add { display: flex; gap: 6px; flex-wrap: wrap; margin-top: 8px; }
+.xeplr-factory-danger-link { border: none; background: none; color: var(--xf-danger); font: inherit; cursor: pointer; padding: 0; }
+
+/* ── a flow, running ─────────────────────────────────────────────────────── */
+.xeplr-factory-flow { display: flex; flex-direction: column; gap: 8px; }
+.xeplr-factory-flow-head { display: flex; align-items: baseline; justify-content: space-between; gap: 12px; }
+.xeplr-factory-flow-where { font-weight: 640; }
+.xeplr-factory-flow-sending, .xeplr-factory-flow-loading { color: var(--xf-muted); font-size: 12px; }
+.xeplr-factory-flow-done {
+  padding: 16px; border-radius: 8px; border: 1px solid var(--xf-border);
+  background: var(--xf-surface); color: var(--xf-ink);
+}

package/src/designs/index.js

@@ -4,6 +4,8 @@ export { default as BuilderSample } from './BuilderSample.jsx'
 export { default as ScreenSample } from './ScreenSample.jsx'
 export { default as ListView } from './ListView.jsx'
 export { default as ScreenModal } from './ScreenModal.jsx'
+export { default as FlowRunnerSample } from './FlowRunnerSample.jsx'
+export { default as FlowBuilderSample } from './FlowBuilderSample.jsx'
 export { default as ControlView, VIEWS } from './ControlView.jsx'
 export { default as Palette, DRAG_TYPE } from './Palette.jsx'
 export { default as PropertyPanel, EDITORS } from './PropertyPanel.jsx'

package/src/flow.js

@@ -0,0 +1,318 @@
+// A FLOW — screens, one after another, and what decides which comes next.
+//
+// A screen is a form; a flow is the journey across several of them. Each step
+// shows one screen, and the arrows leaving it say where to go once it is
+// filled in: the first arrow whose test passes, and failing all of them, the
+// one with no test — "otherwise". A step with no arrows ends the journey.
+//
+// Pure data, like controls.js: no React, no requests. The designer edits this
+// shape, the server is handed the same shape, and both sides check it with
+// validateFlow().
+//
+//   { kind: 'xeplr-flow', version: 1, key: 'employee_registration',
+//     name: 'Employee registration',
+//     steps: [
+//       { stepKey: 'details', screen: 'employee_edit', label: 'Details',
+//         layout: { x: 40, y: 40 },
+//         transitions: [
+//           { when: { field: 'type', op: '=', value: 'contractor' }, target: 'contract' },
+//           { when: null, target: 'payroll' }
+//         ] },
+//       …
+//     ] }
+//
+// WHO RUNS IT: the workflow engine, not the browser. A run remembers where it
+// got to, so a journey can be left and picked up later — by someone else, on
+// another day. The browser only shows the screen it is told to and sends back
+// what was typed.
+
+export const FLOW_KIND = 'xeplr-flow'
+export const FLOW_VERSION = 1
+
+/** Where a journey can end, instead of another step — the engine's own word for a journey that finished. */
+export const FLOW_END = 'end_success'
+
+/**
+ * The tests an arrow can carry, spelled the way the workflow engine accepts
+ * them. One comparison per arrow; more than one is more steps.
+ */
+export const FLOW_OPERATORS = [
+  { op: '=', label: 'is' },
+  { op: '!=', label: 'is not' },
+  { op: '>', label: 'is more than' },
+  { op: '>=', label: 'is at least' },
+  { op: '<', label: 'is less than' },
+  { op: '<=', label: 'is at most' },
+  { op: 'contains', label: 'contains' },
+  { op: 'notContains', label: 'does not contain' },
+  { op: 'startsWith', label: 'starts with' },
+  { op: 'endsWith', label: 'ends with' },
+  { op: 'isEmpty', label: 'is empty' },
+  { op: 'isNotEmpty', label: 'is not empty' }
+]
+
+/** The comparisons that need no value typed beside them. */
+export const VALUELESS_OPERATORS = ['isEmpty', 'isNotEmpty']
+
+const KEY = /^[A-Za-z][A-Za-z0-9_]*$/
+const MAX_KEY = 63
+
+/** An empty flow, ready to have screens dropped on it. */
+export function createFlow({ key, name } = {}) {
+  const flowName = name || 'New flow'
+  return {
+    kind: FLOW_KIND,
+    version: FLOW_VERSION,
+    key: key || flowKey(flowName),
+    name: flowName,
+    steps: []
+  }
+}
+
+/** "Employee registration" → "employee_registration". */
+export function flowKey(name) {
+  const out = String(name || '')
+    .normalize('NFKD').replace(/[̀-ͯ]/g, '')
+    .replace(/[^A-Za-z0-9]+/g, '_')
+    .replace(/^_+|_+$/g, '')
+    .toLowerCase()
+    .slice(0, MAX_KEY)
+  return KEY.test(out) ? out : 'flow_' + out.replace(/^[^A-Za-z]+/, '')
+}
+
+/** Adds a step showing `screen`, at `at` (canvas pixels). Returns { flow, step }. */
+export function addStep(flow, screen, { at, label, stepKey } = {}) {
+  const base = stepKey || uniqueStepKey(flow, flowKey(screen))
+  const step = {
+    stepKey: base,
+    screen,
+    label: label || screen,
+    layout: { x: Math.round((at && at.x) || 40), y: Math.round((at && at.y) || 40) },
+    transitions: []
+  }
+  const steps = [...flow.steps, step]
+  // The step before it, if it ended the journey, now leads here: dropping a
+  // second screen on an empty canvas means "and then this one".
+  const previous = flow.steps[flow.steps.length - 1]
+  if (previous && !previous.transitions.length) {
+    return { flow: { ...flow, steps: steps.map((s) => (s.stepKey === previous.stepKey ? { ...s, transitions: [{ when: null, target: step.stepKey }] } : s)) }, step }
+  }
+  return { flow: { ...flow, steps }, step }
+}
+
+/** A step key nothing else in the flow is using. */
+export function uniqueStepKey(flow, base) {
+  const taken = new Set(flow.steps.map((s) => s.stepKey))
+  const stem = KEY.test(base) ? base : 'step'
+  if (!taken.has(stem)) return stem
+  let n = 2
+  while (taken.has(`${stem}_${n}`)) n++
+  return `${stem}_${n}`
+}
+
+/** Moves a step on the canvas. */
+export function moveStep(flow, stepKey, at) {
+  return mapStep(flow, stepKey, (s) => ({ ...s, layout: { x: Math.round(at.x), y: Math.round(at.y) } }))
+}
+
+/** Changes one thing about a step — its screen, its label. */
+export function setStep(flow, stepKey, patch) {
+  return mapStep(flow, stepKey, (s) => ({ ...s, ...patch }))
+}
+
+/** Removes a step, and every arrow pointing at it. */
+export function removeStep(flow, stepKey) {
+  return {
+    ...flow,
+    steps: flow.steps
+      .filter((s) => s.stepKey !== stepKey)
+      .map((s) => ({ ...s, transitions: s.transitions.filter((t) => t.target !== stepKey) }))
+  }
+}
+
+/**
+ * Draws an arrow from one step to another (or to the end). A step's LAST
+ * arrow is the one with no test — "otherwise" — so a new arrow goes in front
+ * of it and the flow always has somewhere to go.
+ */
+export function addTransition(flow, fromKey, target, when = null) {
+  return mapStep(flow, fromKey, (s) => {
+    const rest = s.transitions.filter((t) => t.when !== null)
+    const otherwise = s.transitions.find((t) => t.when === null)
+    const next = when === null
+      ? [...rest, { when: null, target }]
+      : [...rest, { when, target }, ...(otherwise ? [otherwise] : [])]
+    return { ...s, transitions: next }
+  })
+}
+
+/** Changes one arrow of a step, by its position. */
+export function setTransition(flow, fromKey, index, patch) {
+  return mapStep(flow, fromKey, (s) => ({
+    ...s,
+    transitions: s.transitions.map((t, i) => (i === index ? { ...t, ...patch } : t))
+  }))
+}
+
+/** Removes one arrow of a step, by its position. */
+export function removeTransition(flow, fromKey, index) {
+  return mapStep(flow, fromKey, (s) => ({ ...s, transitions: s.transitions.filter((_, i) => i !== index) }))
+}
+
+/** The step a journey starts at: the first one that nothing else points to, else the first. */
+export function firstStep(flow) {
+  if (!flow.steps.length) return null
+  const pointedAt = new Set(flow.steps.flatMap((s) => s.transitions.map((t) => t.target)))
+  return flow.steps.find((s) => !pointedAt.has(s.stepKey)) || flow.steps[0]
+}
+
+/** Every step that can be reached from the first one. */
+export function reachableSteps(flow) {
+  const start = firstStep(flow)
+  if (!start) return new Set()
+  const byKey = new Map(flow.steps.map((s) => [s.stepKey, s]))
+  const seen = new Set()
+  const walk = (key) => {
+    if (!key || key === FLOW_END || seen.has(key)) return
+    const step = byKey.get(key)
+    if (!step) return
+    seen.add(key)
+    step.transitions.forEach((t) => walk(t.target))
+  }
+  walk(start.stepKey)
+  return seen
+}
+
+/**
+ * Lays the steps out as the journey reads: the first on the left, each step
+ * one column right of the step that leads to it, and the branches of one step
+ * stacked in the same column — so an arrow runs forward and never crosses a
+ * card to reach the one it means.
+ * @param size  { w, h, gapX, gapY, left, top } in pixels
+ */
+export function layoutFlow(flow, size = {}) {
+  const { w = 200, h = 86, gapX = 110, gapY = 50, left = 60, top = 60 } = size
+  const start = firstStep(flow)
+  if (!start) return flow
+  const byKey = new Map(flow.steps.map((s) => [s.stepKey, s]))
+  const depth = new Map([[start.stepKey, 0]])
+  const queue = [start.stepKey]
+  while (queue.length) {
+    const key = queue.shift()
+    ;(byKey.get(key).transitions || []).forEach((t) => {
+      if (!byKey.has(t.target) || depth.has(t.target)) return
+      depth.set(t.target, depth.get(key) + 1)
+      queue.push(t.target)
+    })
+  }
+  // Steps nothing reaches go in a column of their own at the end, where they
+  // are easy to see and to connect.
+  const deepest = Math.max(0, ...depth.values())
+  flow.steps.forEach((s) => { if (!depth.has(s.stepKey)) depth.set(s.stepKey, deepest + 1) })
+  const rows = new Map()
+  return {
+    ...flow,
+    steps: flow.steps.map((s) => {
+      const d = depth.get(s.stepKey)
+      const row = rows.get(d) || 0
+      rows.set(d, row + 1)
+      return { ...s, layout: { x: left + d * (w + gapX), y: top + row * (h + gapY) } }
+    })
+  }
+}
+
+/**
+ * What is wrong with this flow, in the words of the person drawing it.
+ * @param options.screens  the screen keys that exist, so a step cannot point at one that does not
+ * @returns {{ ok, errors: [{ path, message }] }}
+ */
+export function validateFlow(flow, options = {}) {
+  const errors = []
+  const err = (path, message) => errors.push({ path, message })
+
+  if (!flow || typeof flow !== 'object' || Array.isArray(flow)) {
+    err('', 'A flow must be an object')
+    return { ok: false, errors }
+  }
+  if (flow.kind !== FLOW_KIND) err('kind', `must be "${FLOW_KIND}"`)
+  if (flow.version !== FLOW_VERSION) err('version', `must be ${FLOW_VERSION}`)
+  if (!KEY.test(String(flow.key || ''))) err('key', 'must start with a letter and contain only letters, digits and _')
+  else if (String(flow.key).length > MAX_KEY) err('key', `is longer than ${MAX_KEY} characters`)
+  if (!String(flow.name || '').trim()) err('name', 'is required — what this journey is called')
+  if (!Array.isArray(flow.steps)) {
+    err('steps', 'must be an array of steps')
+    return { ok: false, errors }
+  }
+  if (!flow.steps.length) err('steps', 'a flow needs at least one screen')
+
+  const keys = new Map()
+  const screens = options.screens ? new Set(options.screens) : null
+
+  flow.steps.forEach((step, i) => {
+    const at = `steps[${i}]`
+    if (!step || typeof step !== 'object') { err(at, 'must be an object'); return }
+    if (!KEY.test(String(step.stepKey || ''))) err(`${at}.stepKey`, 'must start with a letter and contain only letters, digits and _')
+    else if (keys.has(step.stepKey)) err(`${at}.stepKey`, `"${step.stepKey}" is already used by steps[${keys.get(step.stepKey)}]`)
+    else keys.set(step.stepKey, i)
+    if (!String(step.screen || '').trim()) err(`${at}.screen`, 'must name the screen this step shows')
+    else if (screens && !screens.has(step.screen)) err(`${at}.screen`, `"${step.screen}" is not a published screen`)
+    if (step.layout && (!Number.isFinite(step.layout.x) || !Number.isFinite(step.layout.y))) {
+      err(`${at}.layout`, 'must be { x, y } in pixels')
+    }
+    if (!Array.isArray(step.transitions)) { err(`${at}.transitions`, 'must be an array'); return }
+    let otherwiseAt = -1
+    step.transitions.forEach((t, j) => {
+      const tp = `${at}.transitions[${j}]`
+      if (!t || typeof t !== 'object') { err(tp, 'must be { when, target }'); return }
+      if (!String(t.target || '').trim()) err(`${tp}.target`, `must name the step this arrow goes to, or "${FLOW_END}"`)
+      if (t.when === null || t.when === undefined) {
+        if (otherwiseAt !== -1) err(tp, 'a step can have only one "otherwise" — the others need a test')
+        otherwiseAt = j
+      } else {
+        checkWhen(t.when, tp, err)
+        if (otherwiseAt !== -1) err(tp, '"otherwise" must be the last arrow, or the ones after it are never tried')
+      }
+    })
+  })
+
+  // Targets are checked once every step key is known.
+  flow.steps.forEach((step, i) => {
+    ;(step.transitions || []).forEach((t, j) => {
+      const target = t && t.target
+      if (!target || target === FLOW_END) return
+      if (!keys.has(target)) err(`steps[${i}].transitions[${j}].target`, `"${target}" is not a step of this flow`)
+    })
+  })
+
+  const reachable = reachableSteps(flow)
+  flow.steps.forEach((step, i) => {
+    if (step && step.stepKey && !reachable.has(step.stepKey)) {
+      err(`steps[${i}]`, `nothing leads to "${step.label || step.stepKey}" — draw an arrow to it, or remove it`)
+    }
+  })
+
+  return { ok: errors.length === 0, errors }
+}
+
+function checkWhen(when, at, err) {
+  if (typeof when !== 'object' || Array.isArray(when)) { err(at + '.when', 'must be { field, op, value }'); return }
+  if (!String(when.field || '').trim()) err(`${at}.when.field`, 'must name a field of the screen this step shows')
+  const known = FLOW_OPERATORS.some((o) => o.op === when.op)
+  if (!known) err(`${at}.when.op`, `must be one of: ${FLOW_OPERATORS.map((o) => o.op).join(', ')}`)
+  if (known && !VALUELESS_OPERATORS.includes(when.op) && (when.value === undefined || when.value === null || when.value === '')) {
+    err(`${at}.when.value`, 'needs a value to compare with')
+  }
+}
+
+/** A test in words: "Type is contractor". */
+export function describeWhen(when, fieldLabel) {
+  if (!when) return 'otherwise'
+  const op = FLOW_OPERATORS.find((o) => o.op === when.op)
+  const name = fieldLabel || when.field
+  if (VALUELESS_OPERATORS.includes(when.op)) return `${name} ${op ? op.label : when.op}`
+  return `${name} ${op ? op.label : when.op} ${when.value}`
+}
+
+function mapStep(flow, stepKey, fn) {
+  return { ...flow, steps: flow.steps.map((s) => (s.stepKey === stepKey ? fn(s) : s)) }
+}

package/src/flows.js

@@ -0,0 +1,112 @@
+// The browser side of FLOWS: designing a chain of screens, and running one.
+//
+// The factory does not run a flow — the app's workflow service does, which is
+// why every call here goes to endpoints the app supplies. A run remembers
+// where it got to, so a journey can be left and picked up later; the browser
+// only asks "what should this person see now" and sends back what was typed.
+//
+//   import { authFetch } from '@xeplr/ui-account'
+//   const flows = createFlowsApi({ fetch: authFetch, base: '/api' })
+//   <FlowRunner {...flows.runnerProps} flowKey="employee_registration" />
+//
+// Answers may come as xeplr's { code, message, dataArray } or as the plain
+// object or list itself — the workflow service speaks the second. Both are read
+// the same way (payload()), so a client never cares which service it is talking to.
+
+import { FLOW_KIND, FLOW_VERSION } from './flow.js'
+
+/**
+ * A flow as the server sends it → the document the designer edits. The server
+ * stores steps, not the document's envelope, so the envelope is put back here
+ * and a step with no label is named after its screen.
+ */
+export function asFlow(row) {
+  if (!row) return row
+  return {
+    kind: FLOW_KIND,
+    version: FLOW_VERSION,
+    key: row.key,
+    name: row.name,
+    status: row.status,
+    // A list or a publish answer counts the steps rather than listing them.
+    ...(Array.isArray(row.steps) ? {} : { stepCount: Number(row.steps) || 0 }),
+    steps: (Array.isArray(row.steps) ? row.steps : []).map((s) => ({
+      stepKey: s.stepKey,
+      screen: s.screen,
+      label: s.label || s.screen,
+      layout: s.layout || { x: 40, y: 40 },
+      transitions: s.transitions || []
+    }))
+  }
+}
+
+/**
+ * @param options.fetch  a fetch that adds auth and tenant headers (authFetch)
+ * @param options.base   prefix before /flows (default '')
+ */
+export function createFlowsApi({ fetch: doFetch, base = '' } = {}) {
+  if (typeof doFetch !== 'function') throw new Error('createFlowsApi: pass { fetch } — usually authFetch from @xeplr/ui-account')
+
+  async function call(method, path, body) {
+    let res
+    try {
+      res = await doFetch(`${base}/flows${path}`, {
+        method,
+        headers: body === undefined ? undefined : { 'Content-Type': 'application/json' },
+        body: body === undefined ? undefined : JSON.stringify(body)
+      })
+    } catch (err) {
+      if (err && err.body !== undefined && err.status) throw failure(method, path, err.status, err.body, err.message)
+      throw err
+    }
+    if (res && typeof res.json === 'function' && typeof res.ok === 'boolean') {
+      let json = null
+      try { json = await res.json() } catch (_) { /* not JSON — reported below */ }
+      if (!res.ok) throw failure(method, path, res.status, json)
+      return payload(json)
+    }
+    return payload(res)
+  }
+
+  /** The payload, enveloped or not. */
+  function payload(json) {
+    if (json === null || json === undefined) return []
+    if (typeof json === 'object' && !Array.isArray(json) && Array.isArray(json.dataArray)) return json.dataArray
+    return json
+  }
+
+  function failure(method, path, status, json, fallback) {
+    const err = new Error((json && json.message) || fallback || `${method} ${path} failed (${status})`)
+    err.status = status
+    err.fields = json && json.error && json.error.fields
+    err.code = json && json.code
+    return err
+  }
+  const one = (rows) => (Array.isArray(rows) ? rows[0] : rows)
+  const enc = encodeURIComponent
+
+  const api = {
+    // designing
+    listFlows: () => call('GET', ''),
+    createFlow: async (spec) => asFlow(one(await call('POST', '', spec))),
+    loadFlow: async (key) => asFlow(one(await call('GET', `/${enc(key)}`))),
+    saveFlow: async (flow) => asFlow(one(await call('PUT', `/${enc(flow.key)}`, {
+      name: flow.name,
+      steps: flow.steps.map((s) => ({ stepKey: s.stepKey, label: s.label, screen: s.screen, layout: s.layout, transitions: s.transitions }))
+    }))),
+    // Answers with the flow's status, not its steps — nothing to rebuild from it.
+    publishFlow: async (key) => one(await call('POST', `/${enc(key)}/publish`)),
+
+    // running
+    startRun: async (key) => one(await call('POST', `/${enc(key)}/runs`)),
+    loadRun: async (runId) => one(await call('GET', `/runs/${enc(runId)}`)),
+    /** What the person filled in. Answers with the next screen, or that it is done. */
+    submitRun: async (runId, values, recordId) => one(await call('POST', `/runs/${enc(runId)}/submit`, { values, recordId })),
+    /** Journeys of this flow that are still going — "in progress". */
+    myRuns: (key) => call('GET', `/${enc(key)}/runs?mine=1`)
+  }
+
+  api.builderProps = { listFlows: api.listFlows, loadFlow: api.loadFlow, onSave: api.saveFlow, onPublish: api.publishFlow, onCreate: api.createFlow }
+  api.runnerProps = { startRun: api.startRun, loadRun: api.loadRun, submitRun: api.submitRun, myRuns: api.myRuns }
+  return api
+}

package/src/index.js

@@ -11,12 +11,14 @@ export * from './model.js'
 // Controllers
 export { useFactoryBuilder } from './useFactoryBuilder.js'
 export { useFactoryScreen, normaliseOptions, AUTOSAVE_DELAY } from './useFactoryScreen.js'
+export { useFlowRun } from './useFlowRun.js'
+export { useFlowBuilder, FLOW_AUTOSAVE_DELAY } from './useFlowBuilder.js'
 
 // Designs
-export { BuilderSample, ScreenSample, ListView, ScreenModal, ControlView, VIEWS, Palette, DRAG_TYPE, PropertyPanel, EDITORS } from './designs/index.js'
+export { BuilderSample, ScreenSample, ListView, ScreenModal, FlowRunnerSample, FlowBuilderSample, ControlView, VIEWS, Palette, DRAG_TYPE, PropertyPanel, EDITORS } from './designs/index.js'
 
 // Front-end hooks — extend FactoryHooks, override what you need, call super
 export { FactoryHooks } from './hooks.js'
 
 // Ready-made
-export { FactoryBuilder, FactoryScreen } from './pages.jsx'
+export { FactoryBuilder, FactoryScreen, FlowRunner, FlowBuilder } from './pages.jsx'

package/src/model.js

@@ -21,3 +21,9 @@ export {
   columnForField, tableForScreen, columnSql, widening, diffTables, migrationFor, nextMigrationName,
   createStatements, addStatements, alterStatement, dropStatement, columnFromDatabase, planTableChange
 } from './tableSchema.js'
+export { createFlowsApi } from './flows.js'
+export {
+  FLOW_KIND, FLOW_VERSION, FLOW_END, FLOW_OPERATORS, VALUELESS_OPERATORS,
+  createFlow, flowKey, addStep, uniqueStepKey, moveStep, setStep, removeStep,
+  addTransition, setTransition, removeTransition, firstStep, reachableSteps, layoutFlow, validateFlow, describeWhen
+} from './flow.js'

package/src/pages.jsx

@@ -1,6 +1,8 @@
 import { useFactoryBuilder } from './useFactoryBuilder.js'
 import { useFactoryScreen } from './useFactoryScreen.js'
-import { BuilderSample, ScreenSample, ScreenModal } from './designs/index.js'
+import { useFlowRun } from './useFlowRun.js'
+import { useFlowBuilder } from './useFlowBuilder.js'
+import { BuilderSample, ScreenSample, ScreenModal, FlowRunnerSample, FlowBuilderSample } from './designs/index.js'
 
 /**
  * The builder, ready-made. Saves itself — there is no Save button.
@@ -94,3 +96,66 @@ export function FactoryScreen(props) {
     />
   )
 }
+
+/**
+ * A FLOW, running: one screen at a time, and the run decides which comes next.
+ *
+ * The journey is not in this page. It asks the run what to show, renders that
+ * screen — which saves itself into its own table, as anywhere else — and hands
+ * back what was filled in; the arrows leaving that step decide the rest.
+ *
+ * @prop flowKey    the flow to start
+ * @prop runId      a run to pick up instead of starting one
+ * @prop startRun   async (flowKey) → { runId, status, stepKey, screen }
+ * @prop loadRun    async (runId) → { runId, status, stepKey, screen, values }
+ * @prop submitRun  async (runId, values, recordId) → { status, stepKey, screen }
+ * @prop onStep     (step) → void — each move, for the address bar
+ * @prop onFinish   (run) → void — the journey is over
+ * @prop renderDone what to show at the end (default: a plain "All done")
+ * Everything a screen needs — loadScreen, onSave, fetchOptions, uploadFile… —
+ * is passed straight through, so `{...factory.screenProps}` covers it.
+ */
+export function FlowRunner(props) {
+  const run = useFlowRun(props)
+  const screen = useFactoryScreen({
+    ...props,
+    document: run.document || EMPTY_SCREEN,
+    record: run.values || undefined
+  })
+  return (
+    <FlowRunnerSample
+      run={run}
+      screen={screen}
+      title={props.title}
+      renderDone={props.renderDone}
+      className={props.className}
+      style={props.style}
+    />
+  )
+}
+
+// A screen the runner can hold before the run has said what to show. Valid, so
+// the controller has nothing to complain about, and never drawn.
+const EMPTY_SCREEN = {
+  kind: 'xeplr-screen', version: 1, id: 'flow_waiting', name: 'Waiting',
+  units: 'fraction', aspect: 1, width: 800, nodes: []
+}
+
+/**
+ * The FLOW designer, ready-made: screens on a canvas, arrows between them.
+ *
+ * Saves itself once what is drawn makes sense; Publish is deliberate, because
+ * a published flow is what people walk through.
+ *
+ * @prop flow       the flow to edit (omit for a new one)
+ * @prop name       name for a new flow
+ * @prop screens    [{ id, name }] — the published screens a step can show
+ * @prop loadScreen async (id) → the screen document, so an arrow can offer its fields
+ * @prop onSave     async (flow) → void
+ * @prop onPublish  async (key) → void
+ * @prop onChange   (flow) → void
+ */
+export function FlowBuilder(props) {
+  const ctrl = useFlowBuilder(props)
+  return <FlowBuilderSample ctrl={ctrl} className={props.className} style={props.style} />
+}

package/src/useFlowBuilder.js

@@ -0,0 +1,186 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
+import {
+  createFlow, addStep, moveStep, setStep, removeStep,
+  addTransition, setTransition, removeTransition, validateFlow, firstStep, layoutFlow, FLOW_END
+} from './flow.js'
+import { inputNodes } from './document.js'
+
+// DESIGNING a flow: which screens, in what order, and what decides the order.
+//
+// The same shape as useFactoryBuilder, so the two designers feel like one
+// product: the document, what is selected, and a save that happens by itself
+// once what is drawn makes sense. Publishing is separate and deliberate — a
+// flow that is published is what people actually walk through.
+
+/** Quiet time after the last change before a save goes out. */
+export const FLOW_AUTOSAVE_DELAY = 800
+
+/**
+ * @param flow        the flow to edit (omit for a new one)
+ * @param name        name for a new flow
+ * @param screens     [{ id, name }] — the published screens a step can show
+ * @param loadScreen  async (id) → the screen document, so a condition can offer its fields
+ * @param onSave      async (flow) → void — called after edits, only with a flow that makes sense
+ * @param onPublish   async (key) → void — shows a Publish button
+ * @param onChange    (flow) → void — every edit
+ */
+export function useFlowBuilder({ flow: given, name, screens = [], loadScreen, onSave, onPublish, onChange } = {}) {
+  const [flow, setFlow] = useState(() => given || createFlow({ name }))
+  const [selected, setSelected] = useState(null)          // a step key
+  const [dirty, setDirty] = useState(false)
+  const [saving, setSaving] = useState(false)
+  const [saveError, setSaveError] = useState(null)
+  const [publishing, setPublishing] = useState(false)
+  const [publishResult, setPublishResult] = useState(null)
+
+  // A flow handed in from outside replaces what is being edited only when it
+  // is a different flow — otherwise a re-render would undo what was typed.
+  const givenKey = given && given.key
+  useEffect(() => { if (given) { setFlow(given); setDirty(false) } }, [givenKey])   // eslint-disable-line react-hooks/exhaustive-deps
+
+  const live = useRef({})
+  live.current = { flow, onSave, onChange }
+
+  const check = useMemo(() => validateFlow(flow, { screens: screens.map((s) => s.id) }), [flow, screens])
+  const errorsByStep = useMemo(() => {
+    const out = {}
+    check.errors.forEach((e) => {
+      const m = /^steps\[(\d+)\]/.exec(e.path || '')
+      if (!m) return
+      const step = flow.steps[Number(m[1])]
+      if (!step) return
+      out[step.stepKey] = [...(out[step.stepKey] || []), e]
+    })
+    return out
+  }, [check, flow])
+
+  // ── the fields a condition can test ───────────────────────────────────
+  // A condition reads what the person filled in on THAT step's screen, so the
+  // designer offers exactly those fields, by name, with their labels.
+  const [fields, setFields] = useState({})                // screen id → [{ name, label }]
+  const loadRef = useRef(loadScreen); loadRef.current = loadScreen
+  useEffect(() => {
+    const wanted = [...new Set(flow.steps.map((s) => s.screen).filter(Boolean))]
+    const missing = wanted.filter((id) => !fields[id])
+    if (!missing.length || !loadRef.current) return undefined
+    let cancelled = false
+    Promise.all(missing.map((id) => Promise.resolve()
+      .then(() => loadRef.current(id))
+      .then((doc) => [id, inputNodes(doc).map((n) => ({ name: n.props.name, label: n.props.label || n.props.name }))])
+      .catch(() => [id, []])))
+      .then((pairs) => { if (!cancelled) setFields((f) => ({ ...f, ...Object.fromEntries(pairs) })) })
+    return () => { cancelled = true }
+  }, [flow.steps, fields])
+
+  /** The fields of the screen a step shows — what its arrows can test. */
+  const fieldsFor = useCallback((stepKey) => {
+    const step = flow.steps.find((s) => s.stepKey === stepKey)
+    return (step && fields[step.screen]) || []
+  }, [flow, fields])
+
+  // ── edits ─────────────────────────────────────────────────────────────
+  const update = useCallback((fn) => {
+    setFlow((f) => {
+      const next = fn(f)
+      if (next === f) return f
+      live.current.flow = next
+      setDirty(true)
+      if (live.current.onChange) live.current.onChange(next)
+      return next
+    })
+  }, [])
+
+  const rename = useCallback((value) => update((f) => ({ ...f, name: value })), [update])
+  const screensRef = useRef(screens); screensRef.current = screens
+  const add = useCallback((screen, at) => {
+    let added = null
+    const known = screensRef.current.find((x) => x.id === screen)
+    update((f) => {
+      const r = addStep(f, screen, { at, label: known && known.name ? known.name : undefined })
+      added = r.step
+      return r.flow
+    })
+    if (added) setSelected(added.stepKey)
+    return added
+  }, [update])
+  const move = useCallback((stepKey, at) => update((f) => moveStep(f, stepKey, at)), [update])
+  const change = useCallback((stepKey, patch) => update((f) => setStep(f, stepKey, patch)), [update])
+  const remove = useCallback((stepKey) => {
+    update((f) => removeStep(f, stepKey))
+    setSelected((s) => (s === stepKey ? null : s))
+  }, [update])
+  const connect = useCallback((fromKey, target, when = null) => update((f) => addTransition(f, fromKey, target, when)), [update])
+  const changeTransition = useCallback((fromKey, index, patch) => update((f) => setTransition(f, fromKey, index, patch)), [update])
+  const disconnect = useCallback((fromKey, index) => update((f) => removeTransition(f, fromKey, index)), [update])
+  /** Lays every step out by where it falls in the journey. */
+  const tidy = useCallback(() => update((f) => layoutFlow(f)), [update])
+
+  // ── saving ────────────────────────────────────────────────────────────
+  const timer = useRef(null)
+  useEffect(() => {
+    if (!dirty || !onSave) return undefined
+    clearTimeout(timer.current)
+    timer.current = setTimeout(() => {
+      const f = live.current.flow
+      if (!validateFlow(f, { screens: screens.map((s) => s.id) }).ok) return       // saved once it makes sense
+      setSaving(true)
+      setSaveError(null)
+      Promise.resolve()
+        .then(() => live.current.onSave(f))
+        .then(() => { setDirty(false) })
+        .catch((err) => setSaveError(err.message || 'Could not save'))
+        .finally(() => setSaving(false))
+    }, FLOW_AUTOSAVE_DELAY)
+    return () => clearTimeout(timer.current)
+  }, [flow, dirty, onSave, screens])
+
+  const publish = useCallback(async () => {
+    if (!onPublish) return
+    setPublishing(true)
+    setPublishResult(null)
+    try {
+      clearTimeout(timer.current)
+      if (dirty && onSave) await onSave(live.current.flow)
+      await onPublish(live.current.flow.key)
+      setDirty(false)
+      setPublishResult({ ok: true, message: 'Published — people can walk through it now' })
+    } catch (err) {
+      setPublishResult({ ok: false, message: err.message || 'Could not publish' })
+    } finally {
+      setPublishing(false)
+    }
+  }, [onPublish, onSave, dirty])
+
+  const status = saveError ? 'error' : saving ? 'saving' : dirty ? (check.ok ? 'pending' : 'invalid') : 'saved'
+
+  return {
+    flow,
+    screens,
+    selected,
+    setSelected,
+    selectedStep: flow.steps.find((s) => s.stepKey === selected) || null,
+    first: firstStep(flow),
+    validation: check,
+    errorsByStep,
+    fieldsFor,
+    rename,
+    addStep: add,
+    moveStep: move,
+    setStep: change,
+    removeStep: remove,
+    connect,
+    setTransition: changeTransition,
+    disconnect,
+    tidy,
+    end: FLOW_END,
+    status,
+    saving,
+    saveError,
+    dirty,
+    canPublish: Boolean(onPublish),
+    publish,
+    publishing,
+    publishResult,
+    clearPublishResult: () => setPublishResult(null)
+  }
+}

package/src/useFlowRun.js

@@ -0,0 +1,86 @@
+import { useCallback, useEffect, useRef, useState } from 'react'
+
+// RUNNING a flow: one screen at a time, and the run decides which.
+//
+// The browser holds no route through the journey. It asks the run what to
+// show, renders that screen, and when the person is finished with it sends
+// the values back — the engine tests the arrows leaving that step and answers
+// with the next screen, or that the journey is done.
+//
+// The record itself is saved the ordinary way, by the screen, into its own
+// table. What travels with the run is only what the arrows need to decide,
+// plus the id of the row that was written.
+
+/**
+ * @param flowKey    which flow to run (starting one, or picking up a run)
+ * @param runId      an existing run to continue — omit to start one
+ * @param startRun   async (flowKey) → { runId, status, stepKey, screen }
+ * @param loadRun    async (runId) → { runId, status, stepKey, screen, values }
+ * @param submitRun  async (runId, values, recordId) → { status, stepKey, screen }
+ * @param loadScreen async (key) → the screen document
+ * @param onStep     (step) → void — told each time the run moves, for the address bar
+ * @param onFinish   (run) → void — the journey is over
+ */
+export function useFlowRun({ flowKey, runId, startRun, loadRun, submitRun, loadScreen, onStep, onFinish } = {}) {
+  const [state, setState] = useState({ loading: true, error: null, runId: runId || null, status: null, stepKey: null, screen: null, document: null, values: null })
+  const [sending, setSending] = useState(false)
+  const live = useRef({})
+  live.current = { startRun, loadRun, submitRun, loadScreen, onStep, onFinish, flowKey }
+
+  /** A step the run reports → the screen to draw. */
+  const open = useCallback(async (run) => {
+    if (!run) throw new Error('The run said nothing about what to show')
+    if (run.status === 'done' || !run.screen) {
+      setState((s) => ({ ...s, loading: false, error: null, runId: run.runId || s.runId, status: 'done', stepKey: null, screen: null, document: null }))
+      if (live.current.onFinish) live.current.onFinish(run)
+      return
+    }
+    if (!live.current.loadScreen) throw new Error('No loadScreen was provided, so the flow cannot show "' + run.screen + '"')
+    const doc = await live.current.loadScreen(run.screen)
+    setState({
+      loading: false, error: null,
+      runId: run.runId, status: run.status || 'running', stepKey: run.stepKey, screen: run.screen,
+      document: doc, values: run.values || null
+    })
+    if (live.current.onStep) live.current.onStep(run)
+  }, [])
+
+  // Start, or pick up where a run got to.
+  useEffect(() => {
+    let cancelled = false
+    setState((s) => ({ ...s, loading: true, error: null }))
+    const begin = async () => {
+      if (runId) {
+        if (!live.current.loadRun) throw new Error('No loadRun was provided')
+        return live.current.loadRun(runId)
+      }
+      if (!live.current.startRun) throw new Error('No startRun was provided')
+      return live.current.startRun(live.current.flowKey)
+    }
+    begin()
+      .then((run) => { if (!cancelled) return open(run) })
+      .catch((err) => { if (!cancelled) setState((s) => ({ ...s, loading: false, error: err.message || 'The flow could not be opened' })) })
+    return () => { cancelled = true }
+  }, [flowKey, runId, open])
+
+  /**
+   * Done with this screen. The values go to the run, which decides what comes
+   * next; `recordId` is the row the screen just saved, so later steps and
+   * their arrows can refer to it.
+   */
+  const submit = useCallback(async (values, recordId) => {
+    if (!live.current.submitRun) throw new Error('No submitRun was provided')
+    setSending(true)
+    try {
+      const next = await live.current.submitRun(state.runId, values || {}, recordId)
+      await open({ runId: state.runId, ...next })
+    } catch (err) {
+      setState((s) => ({ ...s, error: err.message || 'That could not be sent' }))
+      throw err
+    } finally {
+      setSending(false)
+    }
+  }, [state.runId, open])
+
+  return { ...state, sending, submit }
+}