@xeplr/ui-factory 1.0.2 → 1.0.4

package/AUTHORING.md

@@ -11,25 +11,26 @@ A request for "a form for employees" is an **entity**, and an entity is **two sc
    ```sh
    npx xeplr-factory screens employee.entity.json -o src/screens/employee
    ```
-   This writes `employee-list.screen.json`, `employee-edit.screen.json`, `EmployeeList.jsx` and `EditEmployee.jsx`. Wire the two pages into the app's menu next to two `<FactoryBuilder>` pages for designing them (Screen · List, Screen · Edit, Designer · List, Designer · Edit). It refuses to overwrite existing files — they may have been refined in the designer — unless given `--force`.
+   This writes `employee-list.screen.json`, `employee-edit.screen.json`, `EmployeeList.jsx`, `EditEmployee.jsx` and an empty `employee.hooks.js`. Wire the two pages into the app's menu next to two `<FactoryBuilder>` pages for designing them (Screen · List, Screen · Edit, Designer · List, Designer · Edit). It refuses to overwrite existing files — they may have been refined in the designer — unless given `--force`.
 
    A single screen that is not an entity (a settings form, say) uses `npx xeplr-factory generate spec.json -o screen.json` with the screen spec below.
-3. **Write the table's migration.** Records live in a **real table** — `employees`, one column per field — never in JSON. Draft the migration from the edit screen into the app's migrations folder:
-   ```sh
-   npx xeplr-factory migration src/screens/employee/employee-edit.screen.json -o migrations
-   ```
-   It writes the next numbered file (`0067_factory_employees_create.sql`): a `CREATE TABLE` with a column per field, real foreign keys for table dropdowns, and the standard `id` / `isActive` / `mtId1–4` / audit columns. Read it, and apply it with the app's `migrate:up`.
+3. **The table comes from Publish.** Records live in a **real table** — `employees`, one column per field — never in JSON, and there are no migration files to write: **publishing** the edit screen creates its table (`CREATE TABLE`, a column per field, real foreign keys for table dropdowns, the standard `id` / `isActive` / `mtId1–4` / audit columns), and publishing a later version changes it:
+   - a new field → `ADD COLUMN`; a wider text or number → `ALTER COLUMN … TYPE`
+   - narrowing, or a different kind of value → **refused**; tell the person why
+   - a **removed field drops its column and all its data** — Publish asks the person to confirm first, showing how many values would go. Never confirm a drop on their behalf.
+   - a column not created by a screen, or still used by another company's screen, is never dropped
 
-   **Changing an existing form** is a migration too. Pass the version the table was built from: `--from employee-edit.published.json` (from git, or `GET /factory/screens/employee_edit`). New fields become `ADD COLUMN`; a wider text or number becomes `ALTER COLUMN … TYPE`. Narrowing, or changing a field to a different kind of value, is **refused** — explain why to the person and write that migration by hand only if they confirm. A removed field's column is kept.
+   Publish a table that others point at first: `departments` before `employees`. To preview the SQL without applying it: `npx xeplr-factory migration employee-edit.screen.json`.
 
-   **Never rename a field that is already a column** (the designer locks those names). Renaming would start a new empty column and strand the data in the old one.
+   **Never rename a field that is already a column** (the designer locks those names) — it would drop the old column and its data and start an empty one.
 4. **Validate** — `screens` and `generate` already refuse a bad spec, but check any document you edited by hand:
    ```sh
    npx xeplr-factory validate screen.json
    ```
    Every problem names a path (`nodes[3].props.data.table`) and what belongs there. Fix and re-run until it prints `ok`.
-5. **Save and publish.** Save the screens as drafts and publish them. Publishing refuses a screen whose table is missing a column, and returns the SQL that would add it — run the migration first.
-6. **Hand over.** The person opens the screens in the designer to move, resize and restyle controls.
+5. **Save and publish.** Save the screens as drafts, then publish — edit screens of referenced tables first. Publishing changes the table; if it would drop columns it returns them for the person to confirm.
+6. **Hooks, if the request needs them.** Anything beyond storing what the form shows — a value worked out on save, a check against other records, an email afterwards, a list narrowed to the user — goes in `employee.hooks.js`, never in the screen: `save`, `get` (list and one record) and `delete`, each with `before`, `after`, `error` and `override`. Register it with `factory.init({ hooks: { employee_edit: require('./employee.hooks') } })`. `override` replaces the whole operation — rules and the other hooks included — so use it only when the generic save / get / delete does not apply at all. The `screens` command never overwrites an existing hooks file, even with `--force`. Details: the [`@xeplr/factory` README](https://www.npmjs.com/package/@xeplr/factory#hooks).
+7. **Hand over.** The person opens the screens in the designer to move, resize and restyle controls.
 
 There is **no submit button** to add: a screen saves itself as it is filled in. If the request mentions seeing or editing what was entered ("…and show the employees below"), add a `list`.
 
@@ -211,7 +212,7 @@ Keep labels short and in sentence case ("Start date", not "START DATE:"). Mark o
 
 ```sh
 npx xeplr-factory screens <entity.json|-> [-o <dir>] [--force] # entity → list + edit screens and pages
-npx xeplr-factory migration <edit.screen.json> [--from <previous.screen.json>] [-o <migrations dir>]  # the table's SQL
+npx xeplr-factory migration <edit.screen.json> [--from <previous.screen.json>]   # preview a table's SQL (Publish applies it)
 npx xeplr-factory generate <spec.json|-> [-o <screen.json>]   # spec → document
 npx xeplr-factory validate <screen.json|->                    # exit 1 with every problem listed
 npx xeplr-factory controls                                     # controls, props, validation rules

package/README.md

@@ -17,6 +17,7 @@ It is built to work with Claude: ask for *"a form for employees with name, email
 npx xeplr-factory screens employee.entity.json -o src/screens/employee
 #  employee-list.screen.json   EmployeeList.jsx
 #  employee-edit.screen.json   EditEmployee.jsx
+#  employee.hooks.js           server hooks for its records: save / get / delete × before / after / error / override
 ```
 
 See [examples/](./examples) for exactly what it writes.
@@ -33,7 +34,7 @@ Most internal apps are a long tail of forms, and every one of them is hand-built
 
 **The factory never has a database.** Your app stores screen documents and supplies the rows dropdowns read. The factory draws, edits and validates.
 
-**Records live in real tables** — `employees`, one column per field — never in JSON, so `select * from employees` and ordinary reporting just work. `xeplr-factory migration` drafts each table's migration from its form, and [`@xeplr/factory`](https://www.npmjs.com/package/@xeplr/factory) is the server package that saves screens (draft / publish) and reads and writes those tables with the screen's own validation. `createFactoryApi({ fetch })` connects the components to it.
+**Records live in real tables** — `employees`, one column per field — never in JSON, so `select * from employees` and ordinary reporting just work. **Publishing** a screen creates or changes its table directly: new fields add columns, and a removed field drops its column and data only after you confirm. [`@xeplr/factory`](https://www.npmjs.com/package/@xeplr/factory) is the server package that does it, saves screens (draft / publish) and reads and writes those tables with the screen's own validation. `createFactoryApi({ fetch })` connects the components to it.
 
 ## Install
 
@@ -65,7 +66,7 @@ import { FactoryBuilder } from '@xeplr/ui-factory'
 - **Every look is a property:** font, size, weight, italic, alignment, text colour, background, border colour/width, corner radius — and for an input, its label's size, weight and colour.
 - With nothing selected, the panel shows the **screen**: the table it saves to, its width, and the font and colours every control inherits.
 - **No Save button.** Edits are saved (as a draft) a moment after you stop, whenever the screen is valid; problems are marked on the controls that have them until they are fixed.
-- **Publish** (when `onPublish` is given) makes the draft the version everyone sees. It may be refused — e.g. the table has no column for a new field — and the reason, with the migration to run, is shown.
+- **Publish** (when `onPublish` is given) makes the draft the version everyone sees and changes its table to match. If removed fields would drop columns, it asks first — "Publishing removes `phone` — 1,240 saved values" — with **Remove and publish** / **Cancel**. Unsafe changes (narrowing a field) are refused with the reason.
 - **`lockedNames`**: fields that are already columns of the table. Their names are read-only, because renaming one would leave its data behind.
 
 ## The screen
@@ -78,6 +79,7 @@ import { FactoryScreen } from '@xeplr/ui-factory'
   record={employee}                                   // optional: open an existing record
   onSave={async (values, { id, source }) => api.save(source, id, values)}  // returns the saved record, with its id
   fetchRecords={async ({ source }) => api.records(source)}
+  fetchRecord={async ({ screen, id }) => api.record(screen, id)}   // optional: Edit loads the record fresh
   onDelete={async ({ id, source }) => api.remove(source, id)}
   fetchOptions={async ({ table }) => api.options(table)}
   screens={{ employee_edit: editScreen }}             // what a list's Edit / New open in a popup
@@ -86,6 +88,8 @@ import { FactoryScreen } from '@xeplr/ui-factory'
 
 **There is no submit.** The screen saves itself in the background (one AJAX call to your `onSave`) a moment after a change, once the entered values are acceptable. Until then it says what is missing — "Fill in the required fields to save" — and a field's message appears once the person has been in it. The first save of a new record creates it: return the saved record and its `id` makes every later save an update.
 
+If `onSave` throws an error with `fields: [{ field, message }]` (what `createFactoryApi` does with the server's 422 — a rule, or a hook's `reject`), each message shows on its field until that field is changed.
+
 Values arrive typed: numbers as numbers, checkboxes as booleans, dates as `"YYYY-MM-DD"`, and a dropdown as the option's own `id` (a table's numeric id stays a number).
 
 ### Lists of saved records
@@ -156,7 +160,7 @@ It lays the fields out as a tidy one- or two-column form and returns a checked d
 
 ```sh
 npx xeplr-factory screens entity.json -o dir   # an entity → list + edit screens and pages
-npx xeplr-factory migration edit.screen.json -o migrations   # the entity's table, as a migration
+npx xeplr-factory migration edit.screen.json   # preview the SQL Publish would run
 npx xeplr-factory generate spec.json -o screen.json   # one screen from a spec
 npx xeplr-factory validate screen.json      # every problem, with its path
 npx xeplr-factory controls                   # controls, props and rules
@@ -207,8 +211,8 @@ src/
   validateDocument.js    ─ the document checker
   values.js              ─ values, validation, autosave readiness, records and list columns, formSchema
   generate.js            ─ screenFromSpec, screensFromSpec (list + edit), entity names
-  scaffold.js            ─ an entity → its screen JSON and .jsx pages
-  tableSchema.js         ─ a form → its table; CREATE / ALTER TABLE migrations, safe changes only
+  scaffold.js            ─ an entity → its screen JSON, .jsx pages and hooks stub
+  tableSchema.js         ─ a form → its table; the publish plan (create / add / widen / confirmed drops)
   remote.js              ─ createFactoryApi: the calls to @xeplr/factory's routes
   model.js               ─ everything above, React-free
   useFactoryBuilder.js   ─ builder controller

package/bin/xeplr-factory.js

@@ -5,7 +5,7 @@
 // turn a short spec into a laid-out document, and check a document before
 // handing it to an app, with errors precise enough to fix without guessing.
 //
-//   xeplr-factory screens entity.json [-o dir]           an entity → list + edit screens and their .jsx pages
+//   xeplr-factory screens entity.json [-o dir]           an entity → list + edit screens, their .jsx pages, a hooks stub
 //   xeplr-factory migration edit.screen.json [--from previous.screen.json] [-o migrations/]
 //                                                        the SQL that makes the table match the form
 //   xeplr-factory generate spec.json [-o screen.json]   spec → laid-out document
@@ -81,13 +81,18 @@ switch (cmd) {
     } catch (err) {
       fail(err.message)
     }
-    const targets = Object.keys(result.files).map((f) => path.join(dir, f))
+    // The hooks file is the app's own code — kept as it is, even with --force.
+    const hooksFile = Object.keys(result.files).find((f) => f.endsWith('.hooks.js'))
+    const keptHooks = hooksFile && existsSync(path.join(dir, hooksFile)) ? hooksFile : null
+    const writing = Object.keys(result.files).filter((f) => f !== keptHooks)
+    const targets = writing.map((f) => path.join(dir, f))
     // Never overwrite a screen someone has since refined in the designer.
     const existing = targets.filter((t) => existsSync(t))
     if (existing.length && !force) fail(`would overwrite ${existing.join(', ')} — pass --force to replace them`)
     mkdirSync(dir, { recursive: true })
-    Object.entries(result.files).forEach(([f, text]) => writeFileSync(path.join(dir, f), text))
+    writing.forEach((f) => writeFileSync(path.join(dir, f), result.files[f]))
     process.stderr.write(`wrote ${targets.join(', ')}\n`)
+    if (keptHooks) process.stderr.write(`kept ${path.join(dir, keptHooks)} — it is your code\n`)
     process.stderr.write(`list screen "${result.list.id}" opens "${result.edit.id}" for Edit / New; both use table "${result.edit.source}"\n`)
     break
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xeplr/ui-factory",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "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/BuilderSample.jsx

@@ -72,13 +72,33 @@ export default function BuilderSample({ ctrl, renderPreview, className, style })
           </button>
         )}
         {ctrl.canPublish && (
-          <button type="button" className="xeplr-factory-primary" onClick={ctrl.publish} disabled={ctrl.publishing}>
+          <button type="button" className="xeplr-factory-primary" onClick={() => ctrl.publish()} disabled={ctrl.publishing}>
             {ctrl.publishing ? 'Publishing…' : 'Publish'}
           </button>
         )}
       </header>
 
-      {ctrl.publishResult && (
+      {ctrl.publishResult && ctrl.publishResult.confirm && (
+        <div className="xeplr-factory-publish is-confirm" role="alertdialog" aria-label="Confirm removing columns">
+          <div className="xeplr-factory-confirm-text">
+            <strong>Publishing removes {ctrl.publishResult.confirm.length === 1 ? 'a column' : `${ctrl.publishResult.confirm.length} columns`} and all the data in {ctrl.publishResult.confirm.length === 1 ? 'it' : 'them'}.</strong>
+            <ul>
+              {ctrl.publishResult.confirm.map((c) => (
+                <li key={c.column}><code>{c.column}</code> — {c.records} saved value{c.records === 1 ? '' : 's'}, for every company using this table</li>
+              ))}
+            </ul>
+            This cannot be undone. To keep the data, put the field back before publishing.
+          </div>
+          <div className="xeplr-factory-confirm-actions">
+            <button type="button" className="xeplr-factory-danger" disabled={ctrl.publishing}
+              onClick={() => ctrl.publish(ctrl.publishResult.confirm.map((c) => c.column))}>
+              {ctrl.publishing ? 'Publishing…' : 'Remove and publish'}
+            </button>
+            <button type="button" className="xeplr-factory-secondary" onClick={ctrl.clearPublishResult}>Cancel</button>
+          </div>
+        </div>
+      )}
+      {ctrl.publishResult && !ctrl.publishResult.confirm && (
         <div className={`xeplr-factory-publish${ctrl.publishResult.ok ? ' is-ok' : ' is-error'}`} role="status">
           <span>{ctrl.publishResult.message}</span>
           {ctrl.publishResult.detail && <pre className="xeplr-factory-publish-detail">{ctrl.publishResult.detail}</pre>}

package/src/designs/factory.css

@@ -50,8 +50,11 @@
 .xeplr-factory-required { color: var(--xf-danger); }
 .xeplr-factory-input {
   flex: 1; min-height: 0; width: 100%; box-sizing: border-box;
-  font: inherit; color: var(--xf-ink); background: var(--xeplr-input-bg, var(--xf-surface));
-  border: 1px solid var(--xeplr-input-border, var(--xf-border)); border-radius: calc(6 * var(--xf-u));
+  /* The screen's own colours, never the host theme's input tokens: a dark theme
+     would give the box a dark background while the text stays the screen's
+     dark ink — unreadable. A screen's look is its style properties. */
+  font: inherit; color: var(--xf-ink); background: var(--xf-surface);
+  border: 1px solid var(--xf-border); border-radius: calc(6 * var(--xf-u));
   padding: 0 calc(10 * var(--xf-u));
 }
 .xeplr-factory-textarea { padding-block: calc(8 * var(--xf-u)); resize: none; }
@@ -89,7 +92,7 @@
 .xeplr-factory-list-mock { width: 100%; border-collapse: collapse; }
 .xeplr-factory-list-mock th { text-align: left; font-weight: 600; font-size: .9em; padding: calc(6 * var(--xf-u)) calc(10 * var(--xf-u)); border-bottom: 1px solid var(--xf-border); color: var(--xf-muted); }
 .xeplr-factory-list-mock td { padding: calc(8 * var(--xf-u)) calc(10 * var(--xf-u)); border-bottom: 1px solid var(--xf-border); }
-.xeplr-factory-list-bar { display: block; height: calc(8 * var(--xf-u)); width: 70%; border-radius: 4px; background: var(--xeplr-border-secondary, #ecebe4); }
+.xeplr-factory-list-bar { display: block; height: calc(8 * var(--xf-u)); width: 70%; border-radius: 4px; background: #ecebe4; }
 .xeplr-factory-list .xeplr-table-row.xeplr-factory-row-open td,
 .xeplr-factory-list tr.xeplr-factory-row-open td { background: color-mix(in srgb, var(--xf-accent) 10%, transparent); }
 
@@ -177,8 +180,8 @@
 .xeplr-factory-prop { margin-bottom: 10px; }
 .xeplr-factory-prop-label { display: block; margin-bottom: 3px; font-weight: 600; font-size: 12px; }
 .xeplr-factory-prop-input {
-  width: 100%; box-sizing: border-box; font: inherit; padding: 5px 7px; color: inherit;
-  border: 1px solid var(--xf-border); border-radius: 5px; background: var(--xeplr-input-bg, #fff);
+  width: 100%; box-sizing: border-box; font: inherit; padding: 5px 7px;
+  border: 1px solid var(--xf-border); border-radius: 5px; background: #fff; color: var(--xf-ink, #1a1a19);
 }
 .xeplr-factory-prop.has-error .xeplr-factory-prop-input { border-color: var(--xf-danger); }
 .xeplr-factory-prop-help { margin-top: 3px; color: var(--xf-muted); font-size: 11px; line-height: 1.4; }
@@ -223,3 +226,7 @@
 .xeplr-factory-publish.is-ok { color: var(--xeplr-status-good, #1d7a4c); background: color-mix(in srgb, var(--xeplr-status-good, #1d7a4c) 7%, transparent); }
 .xeplr-factory-publish.is-error { color: var(--xf-danger); background: color-mix(in srgb, var(--xf-danger) 7%, transparent); flex-wrap: wrap; }
 .xeplr-factory-publish-detail { flex-basis: 100%; order: 3; margin: 4px 0 0; padding: 8px; max-height: 220px; overflow: auto; font-size: 11.5px; color: var(--xeplr-text, #1a1a19); background: var(--xeplr-surface, #fff); border: 1px solid var(--xf-border); border-radius: 6px; white-space: pre; }
+.xeplr-factory-publish.is-confirm { align-items: center; color: var(--xeplr-text, #1a1a19); background: color-mix(in srgb, var(--xeplr-status-warn, #a86a00) 10%, transparent); border-bottom-color: color-mix(in srgb, var(--xeplr-status-warn, #a86a00) 40%, transparent); }
+.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; }

package/src/model.js

@@ -17,5 +17,6 @@ export { getAtPath, setAtPath } from './propertyPath.js'
 export { createFactoryApi } from './remote.js'
 export {
   STANDARD_COLUMNS, RESERVED_COLUMNS, MAX_IDENTIFIER,
-  columnForField, tableForScreen, columnSql, widening, diffTables, migrationFor, nextMigrationName
+  columnForField, tableForScreen, columnSql, widening, diffTables, migrationFor, nextMigrationName,
+  createStatements, addStatements, alterStatement, dropStatement, columnFromDatabase, planTableChange
 } from './tableSchema.js'

package/src/pages.jsx

@@ -47,6 +47,7 @@ export function FactoryBuilder(props) {
  * @prop onSave       async (values, { id, source, document }) → the saved record, with its id
  * @prop fetchOptions async ({ table }) → [{ id, name }] — rows for table dropdowns
  * @prop fetchRecords async ({ source }) → records — rows for lists
+ * @prop fetchRecord  async ({ screen, id }) → record — Edit loads the record fresh
  * @prop onDelete     async ({ id, source, record }) → void
  * @prop onChange     (values) → void
  * @prop screens      { id → document } — the screens a list's Edit / New open in a popup
@@ -78,6 +79,7 @@ export function FactoryScreen(props) {
               recordKey={props.recordKey}
               onSave={ctrl.popupSave}
               fetchOptions={props.fetchOptions}
+              fetchRecord={props.fetchRecord}
               fetchRecords={props.fetchRecords}
               onDelete={props.onDelete}
               screens={props.screens}

package/src/remote.js

@@ -16,22 +16,44 @@
 export function createFactoryApi({ fetch: doFetch, base = '' } = {}) {
   if (typeof doFetch !== 'function') throw new Error('createFactoryApi: pass { fetch } — usually authFetch from @xeplr/ui-account')
 
+  // Two kinds of fetch are accepted, because both are what apps have:
+  //   window.fetch-like  → a Response: read it, and throw on !res.ok
+  //   authFetch-like     → the PARSED body, and on failure it throws an Error
+  //                        carrying status and the body (err.status, err.body)
+  // Either way a failure becomes the same Error, with the server's fields,
+  // confirm and refused lists on it.
   async function call(method, path, body) {
-    const res = await doFetch(`${base}/factory${path}`, {
-      method,
-      headers: body === undefined ? undefined : { 'Content-Type': 'application/json' },
-      body: body === undefined ? undefined : JSON.stringify(body)
-    })
-    let json = null
-    try { json = await res.json() } catch (_) { /* not JSON — reported below */ }
-    if (!res.ok) {
-      const err = new Error((json && json.message) || `${method} ${path} failed (${res.status})`)
-      err.status = res.status
-      err.fields = json && json.error && json.error.fields
-      err.detail = json && json.dataArray && json.dataArray[0] && json.dataArray[0].migration
+    let res
+    try {
+      res = await doFetch(`${base}/factory${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
     }
-    return json ? json.dataArray : []
+    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 json ? json.dataArray : []
+    }
+    return res && Array.isArray(res.dataArray) ? res.dataArray : []
+  }
+
+  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
+    const extra = (json && json.dataArray && json.dataArray[0]) || {}
+    // Publish: columns it would drop, waiting for a yes — and what it keeps.
+    err.confirm = extra.confirm
+    err.keep = extra.keep
+    err.refused = extra.refused
+    if (extra.statements) err.detail = extra.statements.join('\n')
+    return err
   }
   const one = (rows) => (Array.isArray(rows) ? rows[0] : rows)
   const enc = encodeURIComponent
@@ -42,16 +64,20 @@ export function createFactoryApi({ fetch: doFetch, base = '' } = {}) {
     loadScreen: async (key) => one(await call('GET', `/screens/${enc(key)}`)).document,
     loadDraft: async (key) => one(await call('GET', `/screens/${enc(key)}?draft=true`)),
     saveDraft: (doc) => call('PUT', `/screens/${enc(doc.id)}/draft`, { document: doc }),
-    publish: async (doc) => one(await call('POST', `/screens/${enc(doc.id)}/publish`)),
+    // Changes the screen's table directly. Rejects with err.confirm = [{ column, records }]
+    // when a removed field would drop a column; call again with { confirmDrop: [names] }.
+    publish: async (doc, options) => one(await call('POST', `/screens/${enc(doc.id)}/publish`, { confirmDrop: (options && options.confirmDrop) || [] })),
     listTables: () => call('GET', '/tables'),
 
     // records
     fetchRecords: ({ screen }) => call('GET', `/records/${enc(screen)}`),
+    // One record, through the screen's get hooks — what Edit opens.
+    fetchRecord: async ({ screen, id }) => one(await call('GET', `/records/${enc(screen)}/${enc(id)}`)),
     onSave: async (values, { id, screen }) => one(await call('POST', `/records/${enc(screen)}/save`, { id, values })),
     onDelete: ({ id, screen }) => call('POST', `/records/${enc(screen)}/delete`, { id }),
     fetchOptions: ({ table }) => call('GET', `/options/${enc(table)}`)
   }
-  api.screenProps = { loadScreen: api.loadScreen, onSave: api.onSave, fetchRecords: api.fetchRecords, onDelete: api.onDelete, fetchOptions: api.fetchOptions }
+  api.screenProps = { loadScreen: api.loadScreen, onSave: api.onSave, fetchRecords: api.fetchRecords, fetchRecord: api.fetchRecord, onDelete: api.onDelete, fetchOptions: api.fetchOptions }
   api.builderProps = { onSave: api.saveDraft, onPublish: api.publish, listTables: api.listTables, fetchOptions: api.fetchOptions, fetchRecords: api.fetchRecords }
   return api
 }

package/src/scaffold.js

@@ -5,6 +5,7 @@
 //
 //   employee-list.screen.json   EmployeeList.jsx   — the list; Edit / New open a popup
 //   employee-edit.screen.json   EditEmployee.jsx   — the add / edit form, also a page on its own
+//   employee.hooks.js                              — the server's hooks for its records (all empty)
 //
 // The pages are thin on purpose: a screen document and the app's data calls,
 // nothing else. Changing what a screen shows is editing its JSON in the
@@ -28,7 +29,8 @@ export function scaffoldEntity(spec, controls) {
     [listJson]: JSON.stringify(list, null, 2) + '\n',
     [editJson]: JSON.stringify(edit, null, 2) + '\n',
     [`${names.listComponent}.jsx`]: listPage(names, listJson, editJson, list, edit),
-    [`${names.editComponent}.jsx`]: editPage(names, editJson, edit)
+    [`${names.editComponent}.jsx`]: editPage(names, editJson, edit),
+    [`${names.file}.hooks.js`]: hooksFile(names, edit)
   }
   return { files, names, list, edit }
 }
@@ -58,6 +60,47 @@ export default function ${n.listComponent}({ api }) {
 `
 }
 
+function hooksFile(n, edit) {
+  return `// Server hooks for ${n.singular} records — screen "${edit.id}" (and "${n.key}_list", which edits in it).
+//
+// Register with @xeplr/factory:
+//   factory.init({ knex, hooks: { ${edit.id}: require('./${n.file}.hooks') } })
+//
+// Each operation has four hooks. Delete the ones you do not need.
+//   before(ctx)       first — save: return new values to replace them (they are then checked
+//                     against the screen's rules); get: narrow ctx.query; any: ctx.reject(message, { field })
+//   after(ctx)        once it succeeded — ctx.id, ctx.result; return a value to replace the result.
+//                     If it throws, the operation still happened (and error is told).
+//   error(ctx, err)   when the operation failed
+//   override(ctx)     does the WHOLE operation instead — no rules, no before / after / error,
+//                     no generic query. What it returns is the response.
+//
+// ctx: op, screenKey, screen, table, id, isNew (save), many (get), input (what the UI sent, read-only),
+//      values (save), previous (save / delete: the row before), result, user, tenant, knex, query (get), reject
+
+module.exports = {
+  save: {
+    // before: async function(ctx) { return ctx.values },
+    // after: async function(ctx) {},
+    // error: async function(ctx, err) {},
+    // override: async function(ctx) { return savedRecord },
+  },
+  get: {
+    // before: async function(ctx) { /* ctx.query.where(...) */ },
+    // after: async function(ctx) { return ctx.result },
+    // error: async function(ctx, err) {},
+    // override: async function(ctx) { return ctx.id ? record : records },
+  },
+  delete: {
+    // before: async function(ctx) {},
+    // after: async function(ctx) {},
+    // error: async function(ctx, err) {},
+    // override: async function(ctx) { return { id: ctx.id } },
+  }
+}
+`
+}
+
 function editPage(n, editJson, edit) {
   return `import { FactoryScreen } from '@xeplr/ui-factory'
 import editScreen from './${editJson}'

package/src/tableSchema.js

@@ -181,32 +181,136 @@ export function migrationFor(previous, next, controls = CONTROLS) {
   lines.push(...header, '')
 
   if (diff.create) {
-    const cols = [...STANDARD_COLUMNS.slice(0, 1), ...after.columns.map((c) => ({ name: c.name, sql: columnSql(c), label: c.label })), ...STANDARD_COLUMNS.slice(1)]
-    const width = Math.max(...cols.map((c) => c.name.length)) + 2
-    lines.push(`CREATE TABLE IF NOT EXISTS ${q(t)} (`)
-    cols.forEach((c, i) => {
-      const comma = i < cols.length - 1 ? ',' : ''
-      const note = c.label ? `  -- ${c.label}` : ''
-      lines.push(`  ${q(c.name).padEnd(width)} ${c.sql}${comma}${note}`)
-    })
-    lines.push(');', '')
-    lines.push(`CREATE INDEX IF NOT EXISTS ${q(`${t}_mt_index`)} ON ${q(t)} ("mtId1", "mtId2");`)
-    after.columns.filter((c) => c.references).forEach((c) => {
-      lines.push(`CREATE INDEX IF NOT EXISTS ${q(`${t}_${c.name}_index`)} ON ${q(t)} (${q(c.name)});`)
-    })
+    lines.push(...createStatements(after, { annotate: true }))
   } else {
-    diff.add.forEach((c) => {
-      lines.push(`ALTER TABLE ${q(t)} ADD COLUMN IF NOT EXISTS ${q(c.name)} ${columnSql(c)};  -- ${c.label}`)
-      if (c.references) lines.push(`CREATE INDEX IF NOT EXISTS ${q(`${t}_${c.name}_index`)} ON ${q(t)} (${q(c.name)});`)
-    })
-    diff.alter.forEach(({ from, to }) => {
-      const type = to.type === 'varchar' ? `varchar(${to.length})` : to.type
-      lines.push(`ALTER TABLE ${q(t)} ALTER COLUMN ${q(to.name)} TYPE ${type};  -- was ${describe(from)}`)
-    })
+    diff.add.forEach((c) => lines.push(...addStatements(t, c, { annotate: true })))
+    diff.alter.forEach(({ from, to }) => lines.push(alterStatement(t, from, to, { annotate: true })))
   }
   return { sql: lines.join('\n') + '\n', diff, table: t, empty: false }
 }
 
+// ── statements ───────────────────────────────────────────────────────────
+
+/** CREATE TABLE with the fields and the standard columns, and its indexes. */
+export function createStatements(after, { annotate } = {}) {
+  const t = after.table
+  const cols = [...STANDARD_COLUMNS.slice(0, 1), ...after.columns.map((c) => ({ name: c.name, sql: columnSql(c), label: c.label })), ...STANDARD_COLUMNS.slice(1)]
+  const width = Math.max(...cols.map((c) => c.name.length)) + 2
+  const body = cols.map((c, i) => {
+    const comma = i < cols.length - 1 ? ',' : ''
+    const note = annotate && c.label ? `  -- ${c.label}` : ''
+    return `  ${q(c.name).padEnd(width)} ${c.sql}${comma}${note}`
+  })
+  const out = [`CREATE TABLE IF NOT EXISTS ${q(t)} (\n${body.join('\n')}\n);`]
+  out.push(`CREATE INDEX IF NOT EXISTS ${q(`${t}_mt_index`)} ON ${q(t)} ("mtId1", "mtId2");`)
+  after.columns.filter((c) => c.references).forEach((c) => {
+    out.push(`CREATE INDEX IF NOT EXISTS ${q(`${t}_${c.name}_index`)} ON ${q(t)} (${q(c.name)});`)
+  })
+  return out
+}
+
+export function addStatements(t, c, { annotate } = {}) {
+  const out = [`ALTER TABLE ${q(t)} ADD COLUMN IF NOT EXISTS ${q(c.name)} ${columnSql(c)};${annotate && c.label ? `  -- ${c.label}` : ''}`]
+  if (c.references) out.push(`CREATE INDEX IF NOT EXISTS ${q(`${t}_${c.name}_index`)} ON ${q(t)} (${q(c.name)});`)
+  return out
+}
+
+export function alterStatement(t, from, to, { annotate } = {}) {
+  const type = to.type === 'varchar' ? `varchar(${to.length})` : to.type
+  return `ALTER TABLE ${q(t)} ALTER COLUMN ${q(to.name)} TYPE ${type};${annotate ? `  -- was ${describe(from)}` : ''}`
+}
+
+/** Drops the column and every value in it. Its foreign key and index go with it. */
+export function dropStatement(t, name) {
+  return `ALTER TABLE ${q(t)} DROP COLUMN IF EXISTS ${q(name)};`
+}
+
+// ── publish: apply directly ──────────────────────────────────────────────
+//
+// Publishing a screen changes its table straight away — no migration files.
+// It compares the screen with the table AS IT IS in the database (not with
+// the previous version), so a table changed by hand, or a publish that failed
+// halfway, is still seen for what it is.
+//
+// A REMOVED FIELD DROPS ITS COLUMN AND ITS DATA — only after the person
+// confirms, and never for a column this factory did not create:
+//   managed  names that were fields of a published version of a screen on this
+//            table. A column somebody added by hand is not in it, and is left alone.
+//   inUse    names another published screen on the same table still has —
+//            another company's screen, say. The column is shared; it stays.
+
+/** A column as Postgres describes it → the shape columnForField returns. */
+export function columnFromDatabase(c) {
+  const base = { name: c.name }
+  if (c.references) base.references = c.references
+  switch (c.udtName) {
+    case 'varchar': return { ...base, type: 'varchar', length: c.maxLength }
+    case 'text': return { ...base, type: 'text' }
+    case 'int2':
+    case 'int4': return { ...base, type: 'integer' }
+    case 'numeric': return { ...base, type: 'numeric' }
+    case 'date': return { ...base, type: 'date' }
+    case 'bool': return { ...base, type: 'boolean' }
+    // Anything else (a timestamp, a bigint someone chose) is not a type a field
+    // makes — so any change to it is refused rather than guessed at.
+    default: return { ...base, type: c.udtName }
+  }
+}
+
+/**
+ * What publishing `next` does to its table.
+ *
+ * @param current  { table, columns: [{ name, udtName, maxLength, references }] }
+ *                 as the database describes it, or null when the table does not exist
+ * @param options.managed      names ever published as fields on this table
+ * @param options.inUse        names other published screens on this table still use
+ * @param options.confirmDrop  names the person has confirmed dropping
+ * @returns {{
+ *   table, create,
+ *   add, alter,             what will change
+ *   drop,                   columns to drop: [{ name }]
+ *   unconfirmed,            of those, the ones not yet confirmed — nothing runs until this is empty
+ *   keep,                   columns left in place, with why: [{ name, reason }]
+ *   refused,                changes that cannot be made safely: [{ column, reason }] — nothing runs
+ *   statements              the SQL, in order — empty while anything is refused or unconfirmed
+ * }}
+ */
+export function planTableChange(current, next, options = {}, controls = CONTROLS) {
+  const after = tableForScreen(next, controls)
+  const managed = new Set(options.managed || [])
+  const inUse = new Set(options.inUse || [])
+  const confirmed = new Set(options.confirmDrop || [])
+  const plan = { table: after.table, create: false, add: [], alter: [], drop: [], unconfirmed: [], keep: [], refused: [], statements: [] }
+
+  if (!current) {
+    plan.create = true
+    plan.add = after.columns
+    plan.statements = createStatements(after)
+    return plan
+  }
+
+  const existing = current.columns
+    .filter((c) => !RESERVED_COLUMNS.includes(c.name))
+    .map(columnFromDatabase)
+  const diff = diffTables({ table: after.table, columns: existing }, after)
+  plan.add = diff.add
+  plan.alter = diff.alter
+  plan.refused = diff.refused
+
+  diff.unused.forEach((c) => {
+    if (!managed.has(c.name)) plan.keep.push({ name: c.name, reason: 'not created by a screen — left as it is' })
+    else if (inUse.has(c.name)) plan.keep.push({ name: c.name, reason: 'another published screen on this table still uses it' })
+    else plan.drop.push({ name: c.name })
+  })
+  plan.unconfirmed = plan.drop.filter((d) => !confirmed.has(d.name)).map((d) => d.name)
+
+  if (plan.refused.length || plan.unconfirmed.length) return plan
+  plan.add.forEach((c) => plan.statements.push(...addStatements(after.table, c)))
+  plan.alter.forEach(({ from, to }) => plan.statements.push(alterStatement(after.table, from, to)))
+  plan.drop.forEach((d) => plan.statements.push(dropStatement(after.table, d.name)))
+  return plan
+}
+
 /** Next migration file name in a folder of NNNN_*.sql files. */
 export function nextMigrationName(existingFiles, table, create) {
   const top = (existingFiles || []).reduce((m, f) => {

package/src/useFactoryBuilder.js

@@ -29,8 +29,10 @@ import { validateDocument } from './validateDocument.js'
  * @param screens     [{ id, name, document? }] — other screens, offered for a list's "Edit in";
  *                    with its document, a list screen can pick columns from its fields
  * @param lockedNames field names that are already columns of the table — they cannot be renamed
- * @param onPublish   async (document) → { version } — makes the saved draft the version everyone sees.
- *                    It may refuse (e.g. the table is missing columns) by throwing; the message is shown.
+ * @param onPublish   async (document, { confirmDrop }) → { version } — makes the saved draft the version
+ *                    everyone sees, and changes its table to match. Throw to refuse (the message is
+ *                    shown); throw with `confirm: [{ column, records }]` when removed fields would drop
+ *                    columns — the builder asks, and calls again with confirmDrop naming them.
  * @param controls    the control registry (default: the built-ins)
  */
 export function useFactoryBuilder({ document: given, name, onSave, onChange, onPublish, listTables, screens, lockedNames, controls = CONTROLS, autosaveDelay = 800 } = {}) {
@@ -196,7 +198,7 @@ export function useFactoryBuilder({ document: given, name, onSave, onChange, onP
   const onPublishRef = useRef(onPublish); onPublishRef.current = onPublish
   const [publishing, setPublishing] = useState(false)
   const [publishResult, setPublishResult] = useState(null)   // { ok, message, version?, detail? }
-  const publish = useCallback(async () => {
+  const publish = useCallback(async (confirmDrop) => {
     if (!onPublishRef.current) return { ok: false }
     const check = validateDocument(docRef.current, controls)
     if (!check.ok) {
@@ -209,12 +211,21 @@ export function useFactoryBuilder({ document: given, name, onSave, onChange, onP
     try {
       const saved = await save()
       if (!saved.ok && !saved.busy) throw new Error((saved.errors && saved.errors[0] && saved.errors[0].message) || 'Could not save the draft')
-      const res = await onPublishRef.current(docRef.current)
-      const r = { ok: true, version: res && res.version, message: res && res.version ? `Published version ${res.version}` : 'Published' }
+      const res = await onPublishRef.current(docRef.current, { confirmDrop: Array.isArray(confirmDrop) ? confirmDrop : [] })
+      const kept = (res && res.keep) || []
+      const r = {
+        ok: true,
+        version: res && res.version,
+        message: (res && res.version ? `Published version ${res.version}` : 'Published') +
+          (kept.length ? ` — kept ${kept.map((k) => k.name).join(', ')} (${kept[0].reason})` : '')
+      }
       setPublishResult(r)
       return r
     } catch (err) {
-      const r = { ok: false, message: err.message || 'Could not publish', detail: err.detail }
+      // A removed field would drop a column: not an error, a question.
+      const r = Array.isArray(err.confirm) && err.confirm.length
+        ? { ok: false, confirm: err.confirm, message: err.message }
+        : { ok: false, message: err.message || 'Could not publish', detail: err.detail }
       setPublishResult(r)
       return r
     } finally {

package/src/useFactoryScreen.js

@@ -36,13 +36,14 @@ export const AUTOSAVE_DELAY = 700
  * @param fetchRecords  async ({ source, node }) → records, for lists
  * @param onDelete      async ({ id, source, record }) → void
  * @param onChange      (values) → void — every change, before any save
+ * @param fetchRecord   async ({ screen, id }) → record — Edit loads the record fresh (through the server's get hooks)
  * @param screens       { id → document } — screens a list's Edit / New can open
  * @param loadScreen    async (id) → document — for screens not in `screens`
  * @param autosaveDelay ms (default 700)
  * @param controls      the control registry (default: the built-ins)
  */
 export function useFactoryScreen({
-  document: doc, record, recordKey = 'id', onSave, fetchOptions, fetchRecords, onDelete, onChange, screens, loadScreen,
+  document: doc, record, recordKey = 'id', onSave, fetchOptions, fetchRecords, fetchRecord, onDelete, onChange, screens, loadScreen,
   autosaveDelay = AUTOSAVE_DELAY, controls = CONTROLS
 } = {}) {
   const check = useMemo(() => validateDocument(doc, controls), [doc, controls])
@@ -52,11 +53,32 @@ export function useFactoryScreen({
   // `department` is a dropdown whose 2 reads "Finance" — lives on the screen it
   // edits in. Those fields are borrowed for display, and their table options
   // loaded alongside this screen's own.
+  //
+  // An edit screen not passed in `screens` is fetched with loadScreen as soon
+  // as the list shows — not when Edit is first pressed — or the list's columns
+  // would show stored values ("in_progress") until then.
+  const [loadedScreens, setLoadedScreens] = useState({})
+  const knownScreens = useMemo(() => ({ ...loadedScreens, ...(screens || {}) }), [loadedScreens, screens])
+  const editScreenIds = check.ok && !inputs.length
+    ? [...new Set(doc.nodes.filter((n) => n.type === 'list' && n.props.editScreen).map((n) => n.props.editScreen))].join('|')
+    : ''
+  useEffect(() => {
+    if (!editScreenIds || !loadScreen) return undefined
+    let cancelled = false
+    editScreenIds.split('|').filter((id) => !(screens && screens[id])).forEach((id) => {
+      loadScreen(id).then(
+        (found) => { if (!cancelled && found) setLoadedScreens((m) => (m[id] ? m : { ...m, [id]: found })) },
+        () => { /* shown when Edit is pressed, where the person is looking */ }
+      )
+    })
+    return () => { cancelled = true }
+  }, [editScreenIds])                                          // eslint-disable-line react-hooks/exhaustive-deps
+
   const fieldsFor = useCallback((node) => {
     if (inputs.length || !node || !node.props.editScreen) return inputs
-    const editDoc = screens && screens[node.props.editScreen]
+    const editDoc = knownScreens[node.props.editScreen]
     return editDoc && validateDocument(editDoc, controls).ok ? inputNodes(editDoc, controls) : []
-  }, [inputs, screens, controls])
+  }, [inputs, knownScreens, controls])
   const optionNodes = useMemo(() => {
     if (!check.ok) return []
     const borrowed = doc.nodes.filter((n) => n.type === 'list').flatMap((n) => (inputs.length ? [] : fieldsFor(n)))
@@ -76,6 +98,9 @@ export function useFactoryScreen({
   const [saveError, setSaveError] = useState(null)
   const [savedAt, setSavedAt] = useState(null)
   const [listVersion, setListVersion] = useState(0)
+  // Messages the SERVER put on fields — a hook's reject, a rule only it knows.
+  // Shown like the form's own, and cleared as soon as that field is changed.
+  const [serverErrors, setServerErrors] = useState({})
 
   // Latest of everything a delayed save needs, read at the moment it runs.
   const live = useRef({})
@@ -155,8 +180,15 @@ export function useFactoryScreen({
         setStatus('saved')
         return { ok: true, record: saved }
       } catch (err) {
-        setSaveError(err.message || 'Could not save')
-        setStatus('error')
+        const onFields = Array.isArray(err.fields) ? err.fields.filter((f) => f && f.field && f.message) : []
+        if (onFields.length) {
+          setServerErrors(Object.fromEntries(onFields.map((f) => [f.field, f.message])))
+          setStatus('invalid')
+          setSaveError(null)
+        } else {
+          setSaveError(err.message || 'Could not save')
+          setStatus('error')
+        }
         return { ok: false, error: err }
       } finally {
         inFlight.current = null
@@ -193,6 +225,12 @@ export function useFactoryScreen({
     else next[name] = value
     live.current.values = next
     setValues(next)
+    setServerErrors((e) => {
+      if (!(name in e)) return e
+      const rest = { ...e }
+      delete rest[name]
+      return rest
+    })
     if (!live.current.touched.has(name)) {
       const t = new Set(live.current.touched); t.add(name)
       live.current.touched = t
@@ -222,6 +260,7 @@ export function useFactoryScreen({
     setRecordId(live.current.recordId)
     setTouched(new Set())
     setSaveError(null)
+    setServerErrors({})
     setStatus('idle')
   }, [flush, startValues, recordKey])
 
@@ -272,7 +311,8 @@ export function useFactoryScreen({
 
   // ── popup: a list's Edit / New in its edit screen ─────────────────────
   const [popup, setPopup] = useState(null)   // { node, screenId, record, document, loading, error }
-  const screensRef = useRef(screens); screensRef.current = screens
+  const screensRef = useRef(knownScreens); screensRef.current = knownScreens
+  const fetchRecordRef = useRef(fetchRecord); fetchRecordRef.current = fetchRecord
   const loadScreenRef = useRef(loadScreen); loadScreenRef.current = loadScreen
 
   /** Edit (a record) or New (null) in the list's edit screen. */
@@ -286,7 +326,13 @@ export function useFactoryScreen({
       if (!found) throw new Error(`Screen "${screenId}" was not provided — pass it in \`screens\` or supply loadScreen`)
       const checked = validateDocument(found, live.current.controls)
       if (!checked.ok) throw new Error(`Screen "${screenId}" is not valid: ${checked.errors[0].path} ${checked.errors[0].message}`)
-      setPopup((p) => (p && p.screenId === screenId ? { ...p, document: found, loading: false } : p))
+      // Edit opens the record as it is NOW, through the server's get hooks —
+      // not the list's copy, which may be stale or shaped for the list.
+      let fresh = rec || null
+      if (rec && fetchRecordRef.current && rec[live.current.recordKey] !== undefined) {
+        fresh = await fetchRecordRef.current({ screen: screenId, id: rec[live.current.recordKey] })
+      }
+      setPopup((p) => (p && p.screenId === screenId ? { ...p, document: found, record: fresh, loading: false } : p))
     } catch (err) {
       setPopup((p) => (p && p.screenId === screenId ? { ...p, loading: false, error: err.message } : p))
     }
@@ -315,7 +361,7 @@ export function useFactoryScreen({
     popupSave,
     values,
     recordId,
-    errors: state.shown,
+    errors: { ...state.shown, ...serverErrors },
     allErrors: state.errors,
     status,
     saveError,