@xeplr/cli 0.1.11 → 0.3.0

package/templates/api/routes/flows.js

@@ -0,0 +1,47 @@
+// FLOWS — screens one after another, run by Xeplr Workflow (@xeplr/workflow).
+//
+// WHERE IT RUNS. By default INSIDE THIS API, in this app's own database:
+// bin/www starts it (registerWorkflow) after the screens and plugs its flows
+// router in here. With WORKFLOW_PORT set in development.env / production.env it
+// runs as its own service instead (npm run start-workflow → bin/workflow), at
+// the SAME path — /api/workflow/flows — and this route answers 404 so a
+// misrouted request says where it should have gone. The front door routes
+// /api/workflow to it: ui/.env WORKFLOW_URL for Vite, nginx in production.
+//
+//   ONE DATABASE     workflow's tables (workflows, workflow_steps,
+//                    workflow_runs…) sit beside the forms' tables, with their
+//                    own migration record (workflow_migrations).
+//   THIS APP'S       embedded workflow registers no tenancy of its own. Its
+//   TENANCY          rows are filtered by the levels this app registered — or
+//                    none, in an app without tenancy — and the membership gate
+//                    below is the app's own. It never creates companies or
+//                    workspaces tables.
+//   PERMISSIONS      every route checks the caller's permissions ("List flows",
+//                    "Start flow run"…), granted by @xeplr/workflow's
+//                    migrations-auth — in XEPLR_AUTH_MIGRATIONS.
+//
+// Mounted by routes/index.js at /api/workflow, behind this app's auth gate.
+// Everything Workflow serves lives under it:
+//   /api/workflow/flows       the flows people walk through (Journey)
+//   /api/workflow/workflows   the designer's document API
+//   /api/workflow/actions     what a step can DO, for the palette
+var express = require('express');
+
+var router = express.Router();
+var workflow = null;
+
+router.use(function(req, res, next) {
+  if (process.env.WORKFLOW_PORT) {
+    return res.status(404).json({ message: 'Workflow runs on its own port (WORKFLOW_PORT) — route /api/workflow there (ui/.env WORKFLOW_URL, or nginx)' });
+  }
+  // Only before startup has finished — bin/www mounts it before listening.
+  if (!workflow) return res.status(503).json({ message: 'Flows are still starting' });
+  return workflow(req, res, next);
+});
+
+/** bin/www hands over registerWorkflow's router, already gated. */
+router.mount = function(workflowRouter) {
+  workflow = workflowRouter;
+};
+
+module.exports = router;

package/templates/api/routes/index.js

@@ -34,6 +34,9 @@ router.get('/whoami', function(req, res) {
 //   var { genericRoute } = require('@xeplr/base-apis');
 //   router.use('/api/things', genericRoute({ key: 'thing', model: require('../models').Thing }));
 
-__WF_API_ROUTE__
+// Flows: Xeplr Workflow, at /api/workflow — inside this API, or on its
+// own port with WORKFLOW_PORT (see routes/flows.js). The path is the same
+// either way: the browser never knows which.
+router.use('/api/workflow', require('./flows'));
 
 module.exports = router;

package/templates/api/screens/task/task-edit.screen.json

@@ -77,7 +77,7 @@
       "z": 4,
       "props": {
         "label": "Status",
-        "placeholder": "Select…",
+        "placeholder": "Select\u2026",
         "data": {
           "source": "static",
           "options": [
@@ -109,7 +109,7 @@
       "x": 0.5125,
       "y": 0.4,
       "w": 0.4475,
-      "h": 0.065,
+      "h": 0.08,
       "z": 5,
       "props": {
         "label": "Priority",

package/templates/api/workflow.js

@@ -0,0 +1,34 @@
+// FLOWS — how @xeplr/workflow starts, in ONE place, for both ways it runs:
+//
+//   inside the API     bin/www calls this when WORKFLOW_PORT is blank
+//   its own service    bin/workflow (npm run start-workflow) when it is set
+//
+// Either way: this app's own database (its tables beside the forms', with its
+// own migration record), this app's tenancy (it creates no companies or
+// workspaces of its own), and a permission check on every route — granted by
+// @xeplr/workflow's migrations-auth, which XEPLR_AUTH_MIGRATIONS loads.
+var { registerWorkflow } = require('@xeplr/workflow');
+
+/**
+ * Runs workflow's migrations and returns its ROUTER — already gated.
+ *
+ * The whole router, not just the flows facade: it carries `/flows` (the
+ * screens a person walks through) AND `/workflows` (the designer's own
+ * document API). One designer serves both — @xeplr/ui-workflow's canvas, the
+ * same one every xeplr product uses — so the app has to serve what it reads.
+ */
+module.exports = async function startWorkflow(memberGate) {
+  var workflow = await registerWorkflow({
+    applicationId: '__NAME__',
+    db: {
+      name: process.env.DB_API,
+      connection: process.env.__PREFIX___CONNECTION,
+      connectionName: 'workflow',
+      migrationsTable: 'workflow_migrations'
+    },
+    tenantTables: false,
+    access: true,
+    mtMembershipGate: memberGate
+  });
+  return workflow.router;
+};

package/templates/ui/README.md

@@ -24,5 +24,6 @@ npm run build     # → dist/
 ## Rules
 
 - `authFetch` returns the **parsed body**, not a Response — no `.json()`.
-- A side-rail item needs an **icon** (a collapsed rail shows icons only) and its key must exist as a menu row, or it is dropped silently.
+- A side-rail item needs an **icon** (a collapsed rail shows icons only) and its key must exist as a menu row, or it is dropped silently. Give it its **`path`** too: that is how the rail marks the page you are on.
+- The rail is 48px when collapsed; `--app-rail-width` in `src/index.css` reserves the same space and must match it.
 - Set page backgrounds on a container inside the theme, never on `body`.

package/templates/ui/dotenv.tpl

@@ -1,4 +1,4 @@
-# __NAME__ UI — dev port and the two services it talks to.
+# __NAME__ UI — dev port and the services it talks to.
 #
 # Read by vite.config.js, so no port is written in code. Change a number here
 # and the dev server and every proxy target follow.
@@ -6,3 +6,4 @@
 UI_PORT=__UI_PORT__
 AUTH_URL=http://localhost:__AUTH_PORT__
 API_URL=http://localhost:__API_PORT__
+__WF_UI_ENV__

package/templates/ui/package.json

@@ -11,12 +11,14 @@
   "dependencies": {
     "@tanstack/react-table": "^8.21.3",
     "@xeplr/ui-account": "^1.0.9",
-    "@xeplr/ui-canvas": "^1.0.2",
-    "@xeplr/ui-factory": "^1.0.14",
+    "@xeplr/ui-canvas": "^1.1.0",
+    "@xeplr/ui-factory": "^1.1.0",
     "@xeplr/ui-table": "^1.0.6",
     "react": "^19.2.4",
     "react-dom": "^19.2.4",
-    "react-router-dom": "^7.13.2"
+    "react-router-dom": "^7.13.2",
+    "@xeplr/ui-workflow": "^1.2.0",
+    "@xeplr/ui-utils": "^1.0.2"
   },
   "devDependencies": {
     "@vitejs/plugin-react": "^5.2.0",

package/templates/ui/src/App.jsx

@@ -4,7 +4,9 @@ import { authRoutes, authPath, NavPage, ProtectedRoute, useAccess } from '@xeplr
 import Home from './pages/Home.jsx'
 import Tasks from './pages/Tasks.jsx'
 import EditTask from './pages/EditTask.jsx'
-__WF_UI_IMPORTS__
+import FlowDesigner from './pages/FlowDesigner.jsx'
+import Journey from './pages/Journey.jsx'
+import FlowsHome from './pages/FlowsHome.jsx'
 import ConfigureUI from './pages/ConfigureUI.jsx'
 import { FORM_MENU_PREFIX } from './menu.js'
 import FormDesigner from './pages/FormDesigner.jsx'
@@ -22,6 +24,15 @@ const TasksIcon = (
   </svg>
 )
 
+const FlowsIcon = (
+  <svg viewBox="0 0 24 24" width="18" height="18" fill="none" stroke="currentColor"
+       strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
+    <rect x="3" y="3" width="6" height="6" rx="1" />
+    <rect x="15" y="15" width="6" height="6" rx="1" />
+    <path d="M9 6h4a2 2 0 0 1 2 2v7" />
+  </svg>
+)
+
 const FormsIcon = (
   <svg viewBox="0 0 24 24" width="18" height="18" fill="none" stroke="currentColor"
        strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
@@ -64,14 +75,19 @@ function Shell() {
   // The drawer's catalog, by KEY. A key must match a `menus` row's name —
   // @xeplr/ui-account drops unknown keys SILENTLY, so a typo removes the item
   // with no error anywhere. The text shown is the row's label (Configure UI →
-  // Menu), in the order set there — never written here.
+  // Menu), in the order set there — never written here. `path` is how the rail
+  // marks the page you are on (and /tasks/12 still counts as Tasks).
   const drawerItems = useMemo(() => [
-    { key: 'Home', icon: HomeIcon, clickHandler: () => navigate('/home') },
-    { key: 'Tasks', icon: TasksIcon, clickHandler: () => navigate('/tasks') },
+    { key: 'Home', icon: HomeIcon, path: '/home', clickHandler: () => navigate('/home') },
+    { key: 'Tasks', icon: TasksIcon, path: '/tasks', clickHandler: () => navigate('/tasks') },
+    // Always in the rail — the page says when Xeplr Workflow is not connected.
+    { key: 'Flows', icon: FlowsIcon, path: '/flows', clickHandler: () => navigate('/flows') },
 __MT_DRAWER_ITEM__
     // Every form added to the menu, with no code: "form:crop" opens /forms/crop.
     ...menus.filter((key) => key.startsWith(FORM_MENU_PREFIX)).map((key) => ({
-      key, icon: FormsIcon, clickHandler: () => navigate('/forms/' + key.slice(FORM_MENU_PREFIX.length))
+      key, icon: FormsIcon,
+      path: '/forms/' + key.slice(FORM_MENU_PREFIX.length),
+      clickHandler: () => navigate('/forms/' + key.slice(FORM_MENU_PREFIX.length))
     }))
   ], [navigate, menus])
 
@@ -113,7 +129,12 @@ __MT_SELECT_ROUTE__
         <Route path="/forms/:form" element={<FormRecords />} />
         <Route path="/configure" element={<ConfigureUI />} />
         <Route path="/configure/forms/:form/design/:part" element={<FormDesigner />} />
-__WF_UI_ROUTES__
+        {/* Flows — run by @xeplr/workflow inside this app's own API. */}
+        <Route path="/flows" element={<FlowsHome />} />
+        <Route path="/configure/flows/:flow" element={<FlowDesigner />} />
+        {/* A journey: its run id joins the address once it starts, so it can be resumed. */}
+        <Route path="/journey/:flow" element={<Journey />} />
+        <Route path="/journey/:flow/:run" element={<Journey />} />
       </Route>
 
       <Route path="*" element={<Navigate to="/auth/login" replace />} />

package/templates/ui/src/api/flows.js

@@ -0,0 +1,8 @@
+// Flows are at /api/workflow/flows — served by @xeplr/workflow inside this
+// app's API, or on its own port; the dev proxy (vite.config.js) and nginx
+// decide which, never this file. authFetch carries the same sign-in and
+// company as every other call.
+import { authFetch } from '@xeplr/ui-account'
+import { createFlowsApi } from '@xeplr/ui-factory'
+
+export const flows = createFlowsApi({ fetch: authFetch, base: '/api/workflow' })

package/templates/ui/src/index.css

@@ -5,8 +5,9 @@
      of the page rather than pushing it along — the app has to leave the room
      itself. Without this the rail covers the first 60px of every screen, which
      reads as text mysteriously cut off down the left edge rather than as a
-     layout problem. */
-  --app-rail-width: 60px;
+     layout problem. 48px: compact, like VS Code's activity bar — it must
+     match @xeplr/ui-account's collapsed rail. */
+  --app-rail-width: 48px;
 }
 
 body { margin: 0; }
@@ -357,3 +358,19 @@ body { margin: 0; }
 .app-menu-shown { display: inline-flex; gap: 6px; align-items: center; }
 
 .app-menu-settings .app-table { margin-bottom: 14px; }
+
+/* ── Flows, before Workflow is connected (src/pages/Flows.jsx) ─────────────── */
+.app-connect {
+  max-width: 720px;
+  padding: 22px 24px;
+  border: 1px solid var(--xeplr-border-primary);
+  border-radius: 10px;
+  background: var(--xeplr-bg-tertiary);
+  line-height: 1.55;
+}
+.app-connect h2 { margin: 0 0 8px; font-size: 18px; }
+.app-connect p { margin: 0 0 14px; }
+.app-connect-steps { margin: 0 0 14px; padding-left: 20px; }
+.app-connect-steps li { margin-bottom: 14px; }
+.app-connect code { font-size: 12.5px; padding: 1px 5px; border-radius: 4px; background: var(--xeplr-bg-secondary); border: 1px solid var(--xeplr-border-primary); }
+.app-connect pre { margin: 6px 0 0; font-size: 12.5px; }

package/templates/ui/src/menu.js

@@ -11,6 +11,7 @@ export const FORM_MENU_PREFIX = 'form:'
 export const APP_MENU_KEYS = [
   'Home',
   'Tasks',
+  'Flows',
 __MT_MENU_KEY__
   'Admin',
   'Configure UI'

package/templates/ui/src/pages/ConfigureUI.jsx

@@ -3,18 +3,19 @@
 //   Forms  every UI in the app: make one, design it, publish it, open it, add it
 //          to the side rail
 //   Menu   the side rail's items: rename, reorder, hide
-__WF_TAB_NOTE__
+//   Flows  forms one after another — what is filled in decides the next; run by
+//          Xeplr Workflow, and says how to connect it until it is
 //
 // Configuration lives here, not in the side rail — the rail is for the pages
 // people use.
 import { useSearchParams } from 'react-router-dom'
 import Forms from './Forms.jsx'
 import MenuSettings from './MenuSettings.jsx'
-__WF_TAB_IMPORT__
+import Flows from './Flows.jsx'
 
 const TABS = [
   { id: 'forms', label: 'Forms', Page: Forms },
-__WF_TAB__
+  { id: 'flows', label: 'Flows', Page: Flows },
   { id: 'menu', label: 'Menu', Page: MenuSettings }
 ]
 

package/templates/ui/src/pages/EditTask.jsx

@@ -26,7 +26,7 @@ export class TaskHooks extends FactoryHooks {
     return super.get(ctx)
   }
 
-  /** Every autosave — keep it quick. Returns the saved record. */
+  /** The Save button — one AJAX call. Returns the saved record. */
   save(values, ctx) {
     return super.save(values, ctx)
   }
@@ -65,11 +65,11 @@ export const taskHooks = new TaskHooks()
 
 /**
  * The task form on a page of its own — /tasks/new, or /tasks/:id for a task
- * that exists. The list sends people here (its "Opens in" is a page), and
- * Done brings them back.
+ * that exists. The list sends people here (its "Opens in" is a page).
  *
- * There is no Save button: the form saves itself a moment after each change.
- * Done only waits for anything still in flight, then leaves.
+ * Nothing is written while typing. Save sends the task (one AJAX call, never
+ * a form submit) and comes back to the list; Cancel comes back without
+ * saving, asking first if anything is unsaved. Both go through onDone.
  */
 export default function EditTask({ record }) {
   const { id } = useParams()

package/templates/ui/src/pages/FlowDesigner.jsx

@@ -0,0 +1,54 @@
+// ONE FLOW, ON WORKFLOW'S OWN CANVAS.
+//
+// The designer is a component from @xeplr/ui-workflow — the same one BI and
+// every other xeplr product uses — dropped straight onto this page. It is not
+// a section mounted at URLs of its own: this app already has a page for it,
+// inside its own shell, and the designer renders where it is put.
+//
+// There used to be a second, screens-only builder here (@xeplr/ui-factory's
+// FlowBuilder). One designer over one engine is the point: the trigger box,
+// the condition boxes and the reference pickers are built once, and this app
+// gets them by upgrading a package.
+//
+// THIS APP'S FORMS ARE THE FLOW'S SCREENS. A step can show one and wait for
+// somebody to fill it in, and `useScreenSource` is @xeplr/ui-factory's answer
+// to the two things the designer asks its host: which screens exist (with
+// what each one hands back, so a later step can pick `title` by name) and how
+// to design one without leaving the flow. Two props, because the alternative
+// was the same twenty lines in every app — and a copy in your app could never
+// be fixed once.
+//
+// WHERE THE API IS: /api/workflow, always — the dev proxy (vite.config.js) or
+// nginx decides whether that is this API or Workflow on its own port.
+import { useParams, useNavigate } from 'react-router-dom'
+import { WorkflowDesigner } from '@xeplr/ui-workflow'
+import { useScreenSource, FactoryBuilder } from '@xeplr/ui-factory'
+import { factory } from '../api/factory.js'
+
+export default function FlowDesigner() {
+  const { flow: key } = useParams()
+  const navigate = useNavigate()
+  const { screens, screenEditor } = useScreenSource(factory, { Builder: FactoryBuilder })
+
+  return (
+    <div className="app-designer">
+      <WorkflowDesigner
+        apiBase="/api/workflow"
+        screens={screens}
+        screenEditor={screenEditor}
+        // BY KEY, because that is what this app's URLs carry:
+        // /configure/flows/leave_request. A flow is created on the Flows page
+        // with a key made from its name, and that key is how it is addressed
+        // for the rest of its life — a readable link that survives a rebuild
+        // minting new ids.
+        workflowKey={key === 'new' ? undefined : key}
+        newKind={key === 'new' ? 'workflow' : undefined}
+        // Only reachable from /configure/flows/new, which this app does not
+        // link to — the Flows page creates the flow first, so the designer
+        // always opens on one that exists.
+        onOpened={(saved) => navigate('/configure/flows/' + saved, { replace: true })}
+        onBack={() => navigate('/configure?tab=flows')}
+      />
+    </div>
+  )
+}

package/templates/ui/src/pages/Flows.jsx

@@ -0,0 +1,125 @@
+// CONFIGURE UI → FLOWS — every journey across the app's forms.
+//
+// A flow is what someone is walked through: screens one after another, and
+// whatever has to happen between them. What they fill in on one decides which
+// comes next. Xeplr Workflow runs it, so a journey can be left and picked up
+// later — by someone else, on another day. Design it here; open it at
+// /journey/<key>.
+//
+// A FLOW IS AN ORDINARY WORKFLOW, addressed by a key this page makes from its
+// name. It used to be created as kind 'screens', which is a workflow whose
+// steps are GENERATED from a design held in another app — and that app was
+// the screens-only builder this one replaced. The designer then had to refuse
+// to edit its own flows ("designed in Configure UI"), which is how a flow
+// became a page you could open and not change.
+//
+// So a flow is a workflow now, and every kind of step is available inside it:
+// a Screen for the part a person fills in, an Action for the email that goes
+// out after it, a Condition for where it goes next. Flows created the old way
+// still appear here and still run; the designer shows them read-only.
+import { useEffect, useState } from 'react'
+import { Link, useNavigate } from 'react-router-dom'
+import { listWorkflows, saveWorkflow, configureWorkflowApi } from '@xeplr/ui-workflow'
+
+// The same mount the designer uses. Said here as well because this page can
+// be the first one to ask, and a base set after the first request is too late.
+configureWorkflowApi('/api/workflow')
+
+export default function Flows() {
+  const [list, setList] = useState(null)
+  const [error, setError] = useState(null)
+  const [offline, setOffline] = useState(null)   // API_NOT_RESTARTED
+  const [name, setName] = useState('')
+  const navigate = useNavigate()
+
+  const load = () => listWorkflows().then(setList, (e) => {
+    const off = flowsOffline(e)
+    if (off) setOffline(off)
+    else setError(e.message)
+  })
+  useEffect(() => { load() }, [])
+
+  const create = async (e) => {
+    e.preventDefault()
+    const label = name.trim()
+    if (!label) return
+    const key = label.toLowerCase().replace(/[^a-z0-9]+/g, '_').replace(/^_+|_+$/g, '')
+    try {
+      // No steps: the designer is where those come from, and it opens on the
+      // flow this creates. `key` is what every link to it uses from here on.
+      await saveWorkflow({ name: label, key, kind: 'workflow', status: 'draft' })
+      navigate(`/configure/flows/${key}`)
+    } catch (err) {
+      setError(err.message)
+    }
+  }
+
+  if (offline) return <NotConnected offline={offline} />
+
+  return (
+    <div className="app-forms">
+      <p className="app-page-lead">
+        A flow is your forms, one after another — what someone fills in decides the next one.
+        Xeplr Workflow runs it, so a journey can be left and picked up later.
+      </p>
+      {error && <div className="app-error">{error}</div>}
+
+      <form className="app-forms-new" onSubmit={create}>
+        <label className="app-forms-field">
+          <span>Name</span>
+          <input value={name} onChange={(e) => setName(e.target.value)} placeholder="Employee registration" />
+        </label>
+        <button type="submit" className="app-btn" disabled={!name.trim()}>New flow</button>
+      </form>
+
+      {list && list.length === 0 && <p className="app-sub">No flows yet.</p>}
+      {list && list.length > 0 && (
+        <table className="app-table">
+          <thead><tr><th>Flow</th><th>Key</th><th>Status</th><th>Screens</th><th /></tr></thead>
+          <tbody>
+            {list.map((f) => (
+              <tr key={f.id || f.key}>
+                <td><strong>{f.name}</strong></td>
+                <td className="app-sub">{f.key || '—'}</td>
+                <td>{f.kind === 'screens' ? f.status + ' · read-only' : f.status}</td>
+                <td>{typeof f.steps === 'number' ? f.steps : (f.steps || []).length}</td>
+                <td className="app-row-actions">
+                  {f.key && <Link to={`/configure/flows/${f.key}`}>Design</Link>}
+                  {/* PUBLISHING IS A SCREENS-FLOW IDEA: there, publish is what
+                      checks the design before somebody is walked through it.
+                      A flow drawn in the designer has no such step, so it can
+                      be opened as soon as it has one. */}
+                  {(f.kind === 'screens' ? f.status === 'published' : (f.steps || []).length > 0) && f.key && (
+                    <Link to={`/journey/${f.key}`}>Open</Link>
+                  )}
+                </td>
+              </tr>
+            ))}
+          </tbody>
+        </table>
+      )}
+    </div>
+  )
+}
+
+/**
+ * Why flows cannot run right now, or null when the error is something else.
+ * Workflow runs inside this app's API, so there is one such case left: an API
+ * started before flows existed (404 on /api/flows) — restart it.
+ */
+export function flowsOffline(err) {
+  if (err && err.status === 404) return { code: 'API_NOT_RESTARTED', message: 'This app\'s API does not have the flows route yet.' }
+  return null
+}
+
+/** Flows before the API has been restarted with them. */
+export function NotConnected({ offline }) {
+  return (
+    <div className="app-forms">
+      <div className="app-connect">
+        <h2>Restart the API to use flows</h2>
+        <p>{offline.message} It was started before flows were added — restart it, then reload this page.</p>
+      </div>
+    </div>
+  )
+}

package/templates/ui/src/pages/FlowsHome.jsx

@@ -0,0 +1,65 @@
+// FLOWS — the side-rail page: the journeys people can start, one click each.
+//
+// Always in the rail. Flows are run by @xeplr/workflow inside this app's own
+// API, so they are simply there. Designing them is Configure UI → Flows.
+import { useEffect, useState } from 'react'
+import { Link, useNavigate } from 'react-router-dom'
+import { useAccess } from '@xeplr/ui-account'
+import { flows } from '../api/flows.js'
+import { NotConnected, flowsOffline } from './Flows.jsx'
+
+export default function FlowsHome() {
+  const [list, setList] = useState(null)
+  const [error, setError] = useState(null)
+  const [offline, setOffline] = useState(null)
+  const navigate = useNavigate()
+  const { access } = useAccess()
+  // Whoever may open Configure UI may design flows and connect Workflow.
+  const admin = ((access && access.menus) || []).includes('Configure UI')
+
+  useEffect(() => {
+    flows.listFlows().then(setList, (e) => {
+      const off = flowsOffline(e)
+      if (off) setOffline(off)
+      else setError(e.message)
+    })
+  }, [])
+
+  const published = (list || []).filter((f) => f.status === 'published')
+
+  return (
+    <div className="app-page">
+      <h1>Flows</h1>
+      <p className="app-page-lead">
+        Forms one after another — what you fill in on one decides which comes next. A journey you
+        leave is kept, and picks up where it stopped.
+      </p>
+      {offline && <NotConnected offline={offline} />}
+      {error && <div className="app-error">{error}</div>}
+      {list && published.length === 0 && (
+        <p className="app-sub">
+          No flows to start yet.{admin && <> <Link to="/configure?tab=flows">Design one</Link> in Configure UI.</>}
+        </p>
+      )}
+      {published.length > 0 && (
+        <table className="app-table">
+          <thead><tr><th>Flow</th><th>Screens</th><th /></tr></thead>
+          <tbody>
+            {published.map((f) => (
+              <tr key={f.key}>
+                <td><strong>{f.name}</strong></td>
+                <td>{typeof f.steps === 'number' ? f.steps : (f.steps || []).length}</td>
+                <td className="app-row-actions">
+                  <button type="button" className="app-btn" onClick={() => navigate(`/journey/${f.key}`)}>Start</button>
+                </td>
+              </tr>
+            ))}
+          </tbody>
+        </table>
+      )}
+      {admin && list && published.length > 0 && (
+        <p className="app-sub" style={{ marginTop: 16 }}><Link to="/configure?tab=flows">Design flows</Link> in Configure UI.</p>
+      )}
+    </div>
+  )
+}

package/templates/ui/src/pages/Journey.jsx

@@ -0,0 +1,33 @@
+// A FLOW, being walked through — /journey/<key>, and /journey/<key>/<run> once
+// it has started. The run id in the address is what lets a journey be
+// reloaded, left, or handed to someone else and opened on the step it is on.
+//
+// This page holds no route through the journey: Workflow says which screen
+// comes next, from what was filled in.
+import { useNavigate, useParams } from 'react-router-dom'
+import { FlowRunner } from '@xeplr/ui-factory'
+import { flows } from '../api/flows.js'
+import { factory } from '../api/factory.js'
+
+export default function Journey() {
+  const { flow, run } = useParams()
+  const navigate = useNavigate()
+  return (
+    <div className="app-page">
+      <FlowRunner
+        {...flows.runnerProps}
+        {...factory.screenProps}
+        flowKey={flow}
+        runId={run}
+        onStep={(step) => { if (step.runId && step.runId !== run) navigate(`/journey/${flow}/${step.runId}`, { replace: true }) }}
+        renderDone={() => (
+          <div className="app-help">
+            <h2>All done</h2>
+            <p>Everything in this journey is filled in.</p>
+            <button type="button" className="app-btn" onClick={() => navigate(`/journey/${flow}`)}>Start another</button>
+          </div>
+        )}
+      />
+    </div>
+  )
+}

package/templates/ui/src/pages/Tasks.jsx

@@ -1,6 +1,6 @@
 // THE SAMPLE — a list of tasks. New and Edit open the task form on a PAGE of
-// its own, where it saves itself as you type; there is no Save button, and
-// Done goes back here. (A list can open its form in a popup instead: Configure
+// its own. Its Save button saves over AJAX (never a form submit) and comes
+// back here; Cancel comes back without saving. (A list can open its form in a popup instead: Configure
 // UI → Forms → the list → Opens in.)
 //
 // Nothing about tasks is written in this file. The list and the form are

package/templates/ui/src/pages/TasksHelp.jsx

@@ -47,7 +47,8 @@ export default function TasksHelp() {
       </p>
       <p>
         <strong>New</strong> and <strong>Edit</strong> open the form on a page
-        of its own, and <strong>Done</strong> comes back here. A list can open
+        of its own. Nothing is saved while you type: <strong>Save</strong> saves
+        and comes back here, <strong>Cancel</strong> comes back without saving. A list can open
         it in a popup instead — that is its <strong>Opens in</strong> setting.
       </p>
 

package/templates/ui/vite.config.js

@@ -35,7 +35,13 @@ export default defineConfig(({ mode }) => {
     // Only the real network calls (/auth/api/*), NOT bare /auth — that prefix
     // is also used by client-side routes (/auth/login, /auth/profile), which
     // must fall through to Vite's SPA index.html rather than the auth backend.
-    '/auth/api': authUrl
+    '/auth/api': authUrl,
+    // A SERVICE THAT MAY RUN ON ITS OWN PORT, before the /api it sits under —
+    // the first matching prefix wins. Blank WORKFLOW_URL: it runs inside the
+    // API, so the API answers. The browser always calls /api/workflow/…; which
+    // process serves it is decided here (and by nginx in production), never in
+    // the UI's code.
+    '/api/workflow': env.WORKFLOW_URL || apiUrl
   }
   API_PATHS.forEach((p) => { proxy[p] = apiUrl })