pgkiln 0.31.0 → 0.35.0

package/src/builder/components.ts

@@ -3,6 +3,8 @@
 // from this spec, and SQL column names only ever come from here (never from
 // the request).
 
+import { ALL_REGION_CONFIG_HELP, regionConfigHelp } from './region-help.ts';
+import { searchConfigProblems } from '../runtime/search.ts';
 import { objectStoreProblem } from '../objectstore.ts';
 import { formatSettingsProblem } from '../runtime/format.ts';
 import { scheduleProblem } from '../automations.ts';
@@ -49,6 +51,8 @@ export interface Field {
   group?: string;
   /** shown, not editable (the form still posts it) */
   readonly?: boolean;
+  /** (sprint 51) help that depends on the component being edited (wins over `help` when it gives some) */
+  helpBy?: (row: any) => { text: string; url: string | null } | null;
 }
 
 export interface ComponentSpec {
@@ -100,9 +104,9 @@ export const COMPONENTS: Record<string, ComponentSpec> = {
       { name: 'title', label: 'Title', kind: 'text', group: 'Identification' },
       { name: 'static_id', label: 'Static ID', kind: 'text', group: 'Identification',
         help: 'Optional, unique on the page: lower case letters, digits, _ and -, starting with a letter. Names the region in exported files (so renaming it keeps them) and is data-static-id on the page, for CSS and JavaScript.' },
-      { name: 'type', label: 'Type', kind: 'select', options: ['report', 'grid', 'form', 'chart', 'cards', 'calendar', 'facets', 'smart_filters', 'display_selector', 'tasks', 'workflows', 'map', 'tree', 'template_component', 'list', 'static', 'dynamic', 'data_reporter', 'ai_assistant', 'plugin'], group: 'Identification' },
+      { name: 'type', label: 'Type', kind: 'select', options: ['report', 'grid', 'form', 'chart', 'cards', 'calendar', 'facets', 'smart_filters', 'display_selector', 'tasks', 'workflows', 'map', 'tree', 'template_component', 'list', 'static', 'dynamic', 'data_reporter', 'ai_assistant', 'plugin', 'url', 'search'], group: 'Identification' },
       { name: 'source', label: 'Source', kind: 'code', wide: true, group: 'Source',
-        help: 'report/grid: a SELECT (use :ITEM binds) · chart: label column + one numeric column per series · cards: title, subtitle, body, badge, icon · calendar: start_date, end_date, title · map: lat and lng (or location "lat,lng"), title, body, geojson · tree: id, parent_id, label, icon · template_component: any SELECT (its columns are #COLUMN# in the template), or empty for one instance · dynamic: a SELECT returning HTML (escape with meta.html_escape) · static: HTML with &ITEM. substitutions.' },
+        help: 'report/grid: a SELECT (use :ITEM binds) · chart: label column + one numeric column per series · cards: title, subtitle, body, badge, icon · calendar: start_date, end_date, title · map: lat and lng (or location "lat,lng"), title, body, geojson · tree: id, parent_id, label, icon · template_component: any SELECT (its columns are #COLUMN# in the template), or empty for one instance · dynamic: a SELECT returning HTML (escape with meta.html_escape) · static: HTML with &ITEM. substitutions · url: the page to show, https://host/path?q=&P1_ITEM. (the host is written out; items are URL-encoded) or a path on this server (/a/other/1).' },
       { name: 'rest_source', label: 'REST data source', kind: 'rest_source', group: 'Source',
         help: 'Read the rows of a REST data source (Shared Components) instead of a table: the source above is then optional SQL over them, e.g. select * from rest where price > 10. Parameters: {"rest_params": {"city": "&P1_CITY."}} in the attributes.' },
       { name: 'table_name', label: 'Table (form, grid)', kind: 'text', help: 'e.g. sales.orders', group: 'Source' },
@@ -117,7 +121,7 @@ export const COMPONENTS: Record<string, ComponentSpec> = {
       { name: 'authz', label: 'Authorization', kind: 'authz', group: 'Security', help: AUTHZ_HELP },
       buildOption('Security'),
       { name: 'config', label: 'Attributes (JSON)', kind: 'json', wide: true, group: 'Attributes',
-        help: 'report: {"page_size":15,"pagination":"range" (rows X–Y without a total),"keyset":["id"] (with range: Next/Previous seek on these unique columns),"max_rows":10000,"searchable":true,"sortable":true,"interactive":true,"mobile":"reflow"|"scroll","hidden":["col"],"headings":{"col":"Label"},"link":{"column":"id","page":3,"items":{"P3_ID":"#id#"}},"empty":"No rows","pdf":{"layout":"NAME","columns":["col"],"widths":{"col":40},"align":{"col":"right"}}} (pdf widths in mm; layouts under Shared Components → Report layouts) · report, grid, cards: {"formats":{"sal":"FML999G990D00","hiredate":"DD-MON-YYYY"}} (number or date format masks per column) · chart: {"kind":"bar"|"column"|"line"|"area"|"donut","max_rows":1000,"format_mask":"FML999G990"} · cards: {"style":"metric","link":{...},"max_rows":500} · dynamic: {"max_rows":1000} · grid: {"page_size":25,"allow":{"insert":true,"update":true,"delete":true},"readonly":["col"],"columns":{"deptno":{"lov":"LOV:DEPARTMENTS","required":true}},"aggregates":{"sal":["sum","avg"]},"layout":{"order":["col"],"hidden":["col"],"widths":{"col":160},"frozen":1},"row_actions":{"edit":{"page":3,"items":{"P3_ID":"#id#"}},"duplicate":true,"delete":true,"links":[{"label":"…","page":4,"items":{}}]},"select_row":{"column":"id","item":"P1_ID"} (a master),"master":{"item":"P1_ID","column":"parent_id"} (a detail; any region type),"actions":true,"saved_reports":true,"public_reports":"SCHEME"} · calendar: {"link":{...}} · facets: {"report":<region id>,"search":true,"facets":[{"column":"job","label":"Job","exclude":true},{"column":"sal","type":"range","ranges":[{"to":1000},{"from":1000}],"custom":true},{"column":"rating","type":"star","max":5}]} · smart_filters: {"report":<region id>,"suggestions":3,"placeholder":"…","facets":[…as facets]} · display_selector: {"style":"tabs"|"select","show_all":true,"remember":true} · list: {"list":"NAME","template":"links"|"badges"|"cards"|"tabs"} (lists under Shared Components → Lists); any region: {"display_selector":true} puts it in the page\'s display selector; report, chart, cards, dynamic, tree and template component regions: {"lazy":true} loads it after the page shows, {"cache":{"scope":"user"|"session"|"all","seconds":300}} keeps its HTML (a submit of the page empties it) · data_reporter: {"sources":[{"id":"orders","label":"Orders","description":"…","schema":"sales","table":"order_v","columns":[{"name":"total","label":"Total","format":"FML999G990D00"}]}],"sharing":true,"share_authz":"SCHEME","page_size":25} (the Data Reporter settings below edit it) · ai_assistant: {"service":"NAME","system":"…","welcome":"…","context":[{"name":"policy","sql":"select … :AI_PROMPT …"}],"tools":[{"name":"my_leave","description":"…","sql":"select … where status = :STATUS","parameters":{"STATUS":{"type":"string","enum":["PENDING"]}}},{"name":"dept","type":"rest","source":"DEPARTMENT","description":"…"}],"max_rounds":5,"max_turns":20} (the AI assistant settings below edit it) · report: {"ai_filter":{"service":"NAME"}} adds an "Ask in your own words" box (natural-language filters) · plugin: {"plugin":"name","attributes":{"NAME":"value"}} (a region plug-in; a Source SELECT feeds its template)' },
+        help: ALL_REGION_CONFIG_HELP, helpBy: (row: any) => regionConfigHelp(row?.type) },
     ],
   },
   item: {
@@ -131,7 +135,7 @@ export const COMPONENTS: Record<string, ComponentSpec> = {
     validate: (v) => formatSettingsProblem(v.config),
     fields: [
       { name: 'name', label: 'Name', kind: 'upper', help: 'Referenced in SQL as :NAME, e.g. P3_NAME', group: 'Identification' },
-      { name: 'type', label: 'Type', kind: 'select', options: ['text', 'textarea', 'number', 'date', 'datetime', 'select', 'popup_lov', 'radio', 'checkbox', 'switch', 'checkbox_group', 'multiselect', 'email', 'tel', 'url', 'color', 'file', 'location', 'richtext', 'markdown', 'rating', 'combobox', 'daterange', 'qrcode', 'hidden', 'display', 'password', 'plugin'], group: 'Identification' },
+      { name: 'type', label: 'Type', kind: 'select', options: ['text', 'textarea', 'number', 'date', 'datetime', 'select', 'popup_lov', 'radio', 'checkbox', 'switch', 'checkbox_group', 'multiselect', 'email', 'tel', 'url', 'color', 'file', 'location', 'richtext', 'markdown', 'rating', 'combobox', 'daterange', 'qrcode', 'image', 'address', 'hidden', 'display', 'password', 'plugin'], group: 'Identification' },
       { name: 'label', label: 'Label', kind: 'text', group: 'Identification' },
       { name: 'region_id', label: 'Region', kind: 'region', group: 'Layout' },
       { name: 'seq', label: 'Sequence', kind: 'int', group: 'Layout' },
@@ -145,7 +149,7 @@ export const COMPONENTS: Record<string, ComponentSpec> = {
       { name: 'readonly_condition', label: 'Read-only condition (SQL)', kind: 'code', group: 'Security', help: 'When true the item is shown read-only and ignored on submit.' },
       { name: 'authz', label: 'Authorization', kind: 'authz', group: 'Security', help: AUTHZ_HELP },
       buildOption('Security'),
-      { name: 'config', label: 'Attributes (JSON)', kind: 'json', group: 'Attributes', help: '{"submit_on_change":true,"null_label":"- All -","cascade_parents":"P3_DEPTNO","wide":true}. Lists of values read at most {"max_rows":5000} rows. File items: {"filename_column":"photo_name","mime_column":"photo_mime","accept":"image/*,.pdf","max_mb":2,"capture":"environment","max_px":1600} (capture opens the camera on phones; max_px makes photos smaller before upload). {"crop":"1:1"} lets the user crop a picture before upload (free, 1:1, 4:3, 3:4, 16:9, 3:2, 2:3). Several files: {"multiple":true,"max_files":5,"table":"doc.attachment","parent_column":"ticket_id","key_column":"id"} with the content column as source (one row per file). Text items: {"scan":true} adds a barcode/QR scan button where the browser can read codes. Location items hold "lat,lng" with a "Use my location" button. Rich text: sanitised HTML; markdown: Markdown text ({"rows":10}). Rating: {"max":5} stars, stored as 1..max. Combobox: free text with list-of-values suggestions, values colon-separated ({"multiple":false} for one value). Date range: "from:to" (ISO dates; split_part(:P1_X, \':\', 1)). QR code: shows the value as a QR code ({"ecc":"M","size":200,"show_value":true}). Password: {"reveal":true} adds a show/hide button. Number and display items: {"format_mask":"999G999G990D00"} shows the number in the language\'s notation (FML999G990D00 adds the currency) and reads it back on submit. · plugin: {"plugin":"name","attributes":{"NAME":"value"}} (an item plug-in: a text field its JavaScript enhances)' },
+      { name: 'config', label: 'Attributes (JSON)', kind: 'json', group: 'Attributes', help: '{"submit_on_change":true,"null_label":"- All -","cascade_parents":"P3_DEPTNO","wide":true}. {"warn_unsaved":false}: a change of this item doesn\'t count for the page\'s "Warn on unsaved changes". Lists of values read at most {"max_rows":5000} rows. File items: {"filename_column":"photo_name","mime_column":"photo_mime","accept":"image/*,.pdf","max_mb":2,"capture":"environment","max_px":1600} (capture opens the camera on phones; max_px makes photos smaller before upload). {"crop":"1:1"} lets the user crop a picture before upload (free, 1:1, 4:3, 3:4, 16:9, 3:2, 2:3). Several files: {"multiple":true,"max_files":5,"table":"doc.attachment","parent_column":"ticket_id","key_column":"id"} with the content column as source (one row per file). Text items: {"scan":true} adds a barcode/QR scan button where the browser can read codes. Location items hold "lat,lng" with a "Use my location" button. Rich text: sanitised HTML; markdown: Markdown text ({"rows":10}). Rating: {"max":5} stars, stored as 1..max. Combobox: free text with list-of-values suggestions, values colon-separated ({"multiple":false} for one value). Date range: "from:to" (ISO dates; split_part(:P1_X, \':\', 1)). QR code: shows the value as a QR code ({"ecc":"M","size":200,"show_value":true}). Password: {"reveal":true} adds a show/hide button. Image (display image): the value is an https URL, a path or a data:image URL; or {"sql":"select photo, photo_mime from hr.emp where id = :P3_ID"} shows the first column of the first row (a BLOB); {"alt":"Photo of &P3_NAME.","width":160,"height":160}. Address: {"coordinates_item":"P3_LOCATION","country":"nl"} (a "Check address" button where the installation has a geocoder, GEOCODER_URL; the chosen address\'s position goes into the item as "lat,lng"). Any item: {"persist":"user"} keeps its value per user across sessions (a user preference named like the item). Number and display items: {"format_mask":"999G999G990D00"} shows the number in the language\'s notation (FML999G990D00 adds the currency) and reads it back on submit. · plugin: {"plugin":"name","attributes":{"NAME":"value"}} (an item plug-in: a text field its JavaScript enhances)' },
     ],
   },
   button: {
@@ -195,13 +199,13 @@ export const COMPONENTS: Record<string, ComponentSpec> = {
           : null,
     fields: [
       { name: 'name', label: 'Name', kind: 'text', group: 'When' },
-      { name: 'event', label: 'Event', kind: 'select', options: ['change', 'click', 'load', 'dialog_closed'], group: 'When',
-        help: 'dialog_closed: a modal dialog opened from this page was submitted and closed (instead of reloading the page), e.g. refresh a region.' },
-      { name: 'trigger_element', label: 'Item(s) / button / dialog page', kind: 'upper', group: 'When', help: 'Comma separated item names, or a button name for click, or for dialog_closed the dialog page numbers (empty: any dialog).' },
+      { name: 'event', label: 'Event', kind: 'select', options: ['change', 'click', 'load', 'dialog_closed', 'focus', 'blur', 'key_release', 'after_refresh', 'selection_change', 'before_submit', 'custom'], group: 'When',
+        help: 'dialog_closed: a modal dialog opened from this page was submitted and closed (instead of reloading the page), e.g. refresh a region. focus / blur / key_release: an item gets or loses the focus, a key is released in it. after_refresh: a region was refreshed or loaded. selection_change: rows were selected in a report (row selection) or a grid\'s master row. before_submit: the page is about to be submitted (a declined confirm keeps it). custom: JavaScript raised it with pgkiln.trigger(\'NAME\', value). The actions of one event and trigger run in sequence order; a declined confirm stops the ones after it.' },
+      { name: 'trigger_element', label: 'Item(s) / button / region / page / event', kind: 'upper', group: 'When', help: 'Comma separated: item names (change, focus, blur, key_release), a button name (click), region ids or static ids (after_refresh, selection_change), dialog page numbers (dialog_closed; empty: any dialog), event names (custom). Empty for load and before_submit.' },
       { name: 'condition_type', label: 'Client-side condition', kind: 'select', options: ['', 'equals', 'not_equals', 'in_list', 'is_null', 'is_not_null'], group: 'When' },
       { name: 'condition_value', label: 'Condition value', kind: 'text', group: 'When' },
-      { name: 'action', label: 'Action', kind: 'select', options: ['show', 'hide', 'enable', 'disable', 'set_value', 'execute_sql', 'refresh_region', 'refresh_item', 'alert', 'submit', 'set_focus', 'add_class', 'remove_class', 'show_success', 'show_error', 'clear_errors', 'ai_generate', 'execute_javascript', 'plugin', 'push_subscribe'], group: 'Action',
-        help: 'show/hide/enable/disable reverse automatically when the condition is false. set_focus: the first affected item (or the region). show_error: on the affected items, or at the top. clear_errors: of the affected items, or all. ai_generate: runs the "Generate text with AI" process named in Code through AJAX, without submitting the page (on a submit button, the button submits instead when JavaScript is off). execute_javascript: calls the function named in Code, registered by a static application file (Shared Components → Static Application Files). push_subscribe: turns on push notifications on the user\'s device (use it on click: browsers ask only after one; the app needs push notifications on in Settings → Progressive Web App); Message is shown when it worked.' },
+      { name: 'action', label: 'Action', kind: 'select', options: ['show', 'hide', 'enable', 'disable', 'set_value', 'execute_sql', 'refresh_region', 'refresh_item', 'alert', 'submit', 'set_focus', 'add_class', 'remove_class', 'show_success', 'show_error', 'clear_errors', 'ai_generate', 'execute_javascript', 'plugin', 'push_subscribe', 'confirm', 'close_dialog', 'cancel_dialog', 'clear', 'open_region', 'close_region', 'download', 'print', 'current_position', 'share'], group: 'Action',
+        help: 'show/hide/enable/disable reverse automatically when the condition is false. set_focus: the first affected item (or the region). show_error: on the affected items, or at the top. clear_errors: of the affected items, or all. ai_generate: runs the "Generate text with AI" process named in Code through AJAX, without submitting the page (on a submit button, the button submits instead when JavaScript is off). execute_javascript: calls the function named in Code, registered by a static application file (Shared Components → Static Application Files). push_subscribe: turns on push notifications on the user\'s device (use it on click: browsers ask only after one; the app needs push notifications on in Settings → Progressive Web App); Message is shown when it worked. confirm: asks Message; No stops the actions after it. close_dialog / cancel_dialog: close the modal page this runs on (close_dialog refreshes the page below and runs its dialog_closed actions). clear: empties the affected items. open_region / close_region: a collapsible region opens or closes (another region shows or hides). download: the file of the download process named in Code (Items to submit are sent first). print: the browser\'s print dialog. current_position: the device\'s position as latitude,longitude into the first affected item. share: the device\'s share sheet for this page (Message as the text), or the link copied.' },
       { name: 'affected_items', label: 'Affected items', kind: 'upper', group: 'Action' },
       { name: 'affected_region_id', label: 'Affected region', kind: 'region', group: 'Action' },
       { name: 'code', label: 'SQL', kind: 'code', wide: true, group: 'Action', help: 'set_value: a SELECT whose columns set the affected items · execute_sql: any SQL; returned columns named like items set them · ai_generate: the name of an ai_generate process on this page (its output items are updated; items to submit default to the items its prompts use) · execute_javascript: the name of a function registered with pgkiln.actions.register(name, fn) in a static file the page loads.' },
@@ -249,15 +253,15 @@ export const COMPONENTS: Record<string, ComponentSpec> = {
     },
     fields: [
       { name: 'name', label: 'Name', kind: 'text' },
-      { name: 'type', label: 'Type', kind: 'select', options: ['sql', 'form_dml', 'grid_dml', 'data_load', 'invoke_api', 'download', 'chain', 'workflow', 'ai_generate', 'plugin', 'send_push'],
+      { name: 'type', label: 'Type', kind: 'select', options: ['sql', 'form_dml', 'grid_dml', 'data_load', 'invoke_api', 'download', 'chain', 'workflow', 'ai_generate', 'plugin', 'send_push', 'send_email'],
         help: 'download: a file from the query in Code · chain: runs the processes that name it as their chain, in sequence (optionally in the background) · workflow: start, terminate or retry a workflow · ai_generate: Generate text with AI (an AI service the application may use) · send_push: a push notification to a user\'s devices (Settings → Progressive Web App → push notifications)' },
-      { name: 'point', label: 'Point', kind: 'select', options: ['submit', 'load'], help: 'A chain\'s processes run when the chain does (their own point is not used).' },
+      { name: 'point', label: 'Point', kind: 'select', options: ['submit', 'load', 'ajax'], help: 'A chain\'s processes run when the chain does (their own point is not used). ajax: an Ajax callback (APEX: On Demand) that JavaScript calls by name with pgkiln.server.process(\'NAME\', {items: [\'P1_X\'], x01: …}); SQL processes only; the last statement\'s rows come back as JSON, and the items it sets are set on the page.' },
       { name: 'parent_process', label: 'Chain (parent process)', kind: 'text', help: 'The name of a chain process on this page: this process then runs only inside that chain, in its sequence.' },
       { name: 'code', label: 'Code (SQL / PL/pgSQL call)', kind: 'code', wide: true,
         help: 'e.g. select sales.ship_order(:P3_ID::int) as p3_status — returned columns named like items set them. RAISE EXCEPTION messages are shown to the user; USING COLUMN = \'sal\' puts it on that field. · download: a query returning the file\'s content (bytea or text), file name and MIME type, e.g. select content, filename, mime_type from docs.file where id = :P5_ID::int — several rows are sent as one zip file.' },
       { name: 'region_id', label: 'Form / grid region (form_dml, grid_dml)', kind: 'region' },
-      { name: 'config', label: 'Configuration (data_load, invoke_api, download, chain, workflow, ai_generate, plugin, send_push)', kind: 'json', wide: true,
-        help: 'data_load: {"file_item":"P5_FILE","definition":"ORDERS_LOAD"} (a data load definition: table, format, mapping, transformations) or {"file_item":"P5_FILE","table":"sales.orders","mode":"append | merge | replace","skip_errors":false,"headers":true,"format":"auto | csv | xlsx | json | xml","row_tag":"order","columns":{"Heading in file":"column"}} — runs as the app\'s database role; columns match by name unless mapped. · invoke_api: {"source":"WEATHER","params":{"city":"&P5_CITY."},"items":{"P5_TEMP":"current.temp"},"status_item":"P5_STATUS"} or {"url":"https://api.example.com/orders/&P5_ID.","method":"POST","credential":"SHOP_API","body":"{\\"note\\": &P5_NOTE.}","items":{…}} — without "items", the first row\'s columns set the items named like them. · download: {"content_column":"content","filename_column":"filename","mime_column":"mime_type","zip_name":"files-&P5_ID..zip","disposition":"attachment | inline"} (all optional; default: the first three columns). · chain: {"background": true, "status_item": "P5_JOB_ID"} runs it after the submit, on the server (status in meta.process_jobs). · workflow: {"action":"start","definition":"APPROVAL","version":"2","detail_pk":"&P5_ID.","variables":{"AMOUNT":"&P5_AMOUNT."},"id_item":"P5_WORKFLOW_ID"} or {"action":"terminate | retry","instance":"&P5_WORKFLOW_ID.","comment":"…"} · send_push: {"to":"&P5_OWNER.","title":"Order &P5_ID. needs approval","body":"…","page":5,"items":{"P5_ID":"&P5_ID."},"tag":"order-&P5_ID.","urgency":"normal | high | low | very-low"} — to the user\'s devices that turned notifications on; the link is signed for that user · ai_generate: {"service":"CLAUDE","system":"You write short, friendly summaries.","prompt":"Summarise: &P5_NOTES.","output_item":"P5_SUMMARY"} (text), {"service":…,"prompt":"Extract the contact from: &P5_TEXT.","output_items":["P5_NAME","P5_EMAIL"]} (structured: a JSON schema built from the items, their labels describe the fields) or {"service":…,"prompt":…,"schema":{"type":"object","properties":{"name":{"type":"string"}},"required":["name"],"additionalProperties":false},"items":{"P5_NAME":"name"}} (your schema; items map to properties or paths); optional "max_tokens", "error_message". &ITEM. values are sent as delimited data, never as instructions. · plugin: {"plugin":"name","attributes":{"NAME":"value or &ITEM."}} (a process plug-in: its function returns the message)' },
+      { name: 'config', label: 'Configuration (data_load, invoke_api, download, chain, workflow, ai_generate, plugin, send_push, send_email)', kind: 'json', wide: true,
+        help: 'data_load: {"file_item":"P5_FILE","definition":"ORDERS_LOAD"} (a data load definition: table, format, mapping, transformations) or {"file_item":"P5_FILE","table":"sales.orders","mode":"append | merge | replace","skip_errors":false,"headers":true,"format":"auto | csv | xlsx | json | xml","row_tag":"order","columns":{"Heading in file":"column"}} — runs as the app\'s database role; columns match by name unless mapped. · invoke_api: {"source":"WEATHER","params":{"city":"&P5_CITY."},"items":{"P5_TEMP":"current.temp"},"status_item":"P5_STATUS"} or {"url":"https://api.example.com/orders/&P5_ID.","method":"POST","credential":"SHOP_API","body":"{\\"note\\": &P5_NOTE.}","items":{…}} — without "items", the first row\'s columns set the items named like them. · download: {"content_column":"content","filename_column":"filename","mime_column":"mime_type","zip_name":"files-&P5_ID..zip","disposition":"attachment | inline"} (all optional; default: the first three columns). Or {"export":"csv | json | xml | html | xlsx | pdf","file_name":"orders-&P5_ID.","title":"Orders","layout":"A4_LANDSCAPE","separator":";"}: the query\'s rows as one file (APEX_DATA_EXPORT; meta.data_export does csv, json, xml and html from SQL). · chain: {"background": true, "status_item": "P5_JOB_ID"} runs it after the submit, on the server (status in meta.process_jobs). · workflow: {"action":"start","definition":"APPROVAL","version":"2","detail_pk":"&P5_ID.","variables":{"AMOUNT":"&P5_AMOUNT."},"id_item":"P5_WORKFLOW_ID"} or {"action":"terminate | retry","instance":"&P5_WORKFLOW_ID.","comment":"…"} · send_push: {"to":"&P5_OWNER.","title":"Order &P5_ID. needs approval","body":"…","page":5,"items":{"P5_ID":"&P5_ID."},"tag":"order-&P5_ID.","urgency":"normal | high | low | very-low"} — to the user\'s devices that turned notifications on; the link is signed for that user · ai_generate: {"service":"CLAUDE","system":"You write short, friendly summaries.","prompt":"Summarise: &P5_NOTES.","output_item":"P5_SUMMARY"} (text), {"service":…,"prompt":"Extract the contact from: &P5_TEXT.","output_items":["P5_NAME","P5_EMAIL"]} (structured: a JSON schema built from the items, their labels describe the fields) or {"service":…,"prompt":…,"schema":{"type":"object","properties":{"name":{"type":"string"}},"required":["name"],"additionalProperties":false},"items":{"P5_NAME":"name"}} (your schema; items map to properties or paths); optional "max_tokens", "error_message". &ITEM. values are sent as delimited data, never as instructions. · plugin: {"plugin":"name","attributes":{"NAME":"value or &ITEM."}} (a process plug-in: its function returns the message) · send_email: {"to":"&P5_EMAIL.","cc":"…","bcc":"…","from":"…","reply_to":"…","subject":"Order &P5_ID.","body":"plain text","body_html":"<p>HTML (item values escaped)</p>"} or {"to":"&P5_EMAIL.","template":"ORDER_SHIPPED","placeholders":{"NAME":"&P5_NAME."}}; "attachments":"select content, filename, mime from sales.invoice where order_id = :P5_ID" — queued in the page\'s transaction, sent after the commit through the application\'s mail service' },
       { name: 'when_button', label: 'When button pressed', kind: 'upper' },
       ...conditionFields('Condition'),
       { name: 'success_message', label: 'Success message', kind: 'text' },
@@ -437,7 +441,7 @@ export const COMPONENTS: Record<string, ComponentSpec> = {
     defaults: { point: 'after_login' },
     fields: [
       { name: 'name', label: 'Name', kind: 'text' },
-      { name: 'point', label: 'Point', kind: 'select', options: ['after_login', 'before_page'] },
+      { name: 'point', label: 'Point', kind: 'select', options: ['after_login', 'before_page', 'ajax'], help: 'ajax: an Ajax callback every page can call with pgkiln.server.process(\'NAME\') (a page\'s own ajax process of that name wins).' },
       { name: 'code', label: 'Code (SQL)', kind: 'code', wide: true, help: 'Returned columns named like application items set them, e.g. select id as ai_customer_id from sales.customer where lower(username) = lower(:APP_USER)' },
       { name: 'seq', label: 'Sequence', kind: 'int' },
       { name: 'authz', label: 'Authorization', kind: 'authz', help: AUTHZ_HELP },
@@ -572,6 +576,96 @@ export const COMPONENTS: Record<string, ComponentSpec> = {
       { name: 'authz', label: 'Authorization', kind: 'authz', group: 'Security', help: AUTHZ_HELP },
     ],
   },
+  // (080) search configurations: what a search region searches
+  search_config: {
+    table: 'meta.search_config',
+    scope: 'app',
+    label: 'Search configuration',
+    plural: 'Search configurations',
+    icon: 'search',
+    summary: (c) => `${c.name} (${c.source_type})`,
+    defaults: { source_type: 'table', seq: 10, max_results: 10, searchable_columns: [] },
+    validate: (v) => searchConfigProblems(v as never).join(' ') || null,
+    fields: [
+      { name: 'name', label: 'Name (static ID)', kind: 'upper', group: 'Identification', help: 'e.g. CUSTOMERS; a search region names it in {"configs": ["CUSTOMERS"]}.' },
+      { name: 'label', label: 'Label', kind: 'text', group: 'Identification', help: 'The heading of its results, e.g. Customers.' },
+      { name: 'seq', label: 'Sequence', kind: 'int', group: 'Identification', help: 'The order of the groups of results.' },
+      { name: 'source_type', label: 'Source type', kind: 'select', options: ['table', 'sql', 'list'], group: 'Source',
+        help: 'table: a table or view · sql: a SELECT (:ITEM binds allowed) · list: the entries of a list (Shared Components → Lists) the user may see.' },
+      { name: 'source', label: 'Source', kind: 'code', wide: true, group: 'Source', help: 'table: sales.customers · sql: select id, name, city from sales.customers where active · list: the list\'s name.' },
+      { name: 'searchable_columns', label: 'Searchable columns', kind: 'list', group: 'Source',
+        help: 'Comma-separated columns the search text is looked for in (each word must be found in one of them). Empty: the title, subtitle and description columns.' },
+      { name: 'title_column', label: 'Title column', kind: 'text', group: 'Result', help: 'Required (table, sql); results are ordered by it.' },
+      { name: 'subtitle_column', label: 'Subtitle column', kind: 'text', group: 'Result' },
+      { name: 'description_column', label: 'Description column', kind: 'text', group: 'Result' },
+      { name: 'badge_column', label: 'Badge column', kind: 'text', group: 'Result' },
+      { name: 'icon', label: 'Icon', kind: 'text', group: 'Result', help: 'An icon name (e.g. user), or #COLUMN# for a column that holds icon names.' },
+      { name: 'link', label: 'Link', kind: 'json', wide: true, group: 'Result', help: 'Where a result goes: {"page": 3, "items": {"P3_ID": "#ID#"}} (#COLUMN# is the row\'s value). Empty: no link.' },
+      { name: 'max_results', label: 'Maximum results', kind: 'int', group: 'Result', help: '1–100 (default 10).' },
+      buildOption('Result'),
+    ],
+  },
+  // (081) e-mail templates: meta.send_mail_template and the send_email process fill them
+  email_template: {
+    table: 'meta.email_template',
+    scope: 'app',
+    label: 'E-mail template',
+    plural: 'E-mail templates',
+    icon: 'send',
+    summary: (t) => t.name,
+    defaults: { subject: 'Order #ORDER_ID# shipped', html_body: '<p>Dear #NAME#,</p>\n<p>Your order #ORDER_ID# is on its way.</p>', text_body: 'Dear #NAME#,\n\nYour order #ORDER_ID# is on its way.' },
+    validate: (v) => (typeof v.subject !== 'string' || !v.subject.trim() || /[\r\n]/.test(v.subject) ? 'The subject is required, on one line.' : !v.html_body && !v.text_body ? 'Write an HTML or a plain text body (or both).' : null),
+    fields: [
+      { name: 'name', label: 'Name (static ID)', kind: 'upper', help: 'e.g. ORDER_SHIPPED: meta.send_mail_template(\'ORDER_SHIPPED\', …) and the Send e-mail process name it.' },
+      { name: 'subject', label: 'Subject', kind: 'text', wide: true, help: 'One line; #PLACEHOLDERS# are filled in.' },
+      { name: 'html_body', label: 'HTML body', kind: 'code', wide: true,
+        help: '#NAME# is the value, HTML-escaped; #NAME!RAW# the value as it is (trusted HTML only). Mail clients ignore most CSS: keep it simple (tables, inline formatting).' },
+      { name: 'text_body', label: 'Plain text body', kind: 'textarea', wide: true, help: 'For mail clients that show no HTML. #NAME# is the value as it is.' },
+    ],
+  },
+  // (086) application settings: meta.get_app_setting / meta.set_app_setting
+  app_setting: {
+    table: 'meta.app_setting',
+    scope: 'app',
+    label: 'Application setting',
+    plural: 'Application settings',
+    icon: 'settings',
+    summary: (x) => x.name,
+    defaults: { keep_on_upgrade: true },
+    // no valid values: any value (null, not an empty list)
+    beforeSave: async (v) => {
+      if (Array.isArray(v.valid_values) && !v.valid_values.length) v.valid_values = null;
+    },
+    validate: (v) =>
+      v.required && !String(v.value ?? '').trim()
+        ? 'A required setting needs a value.'
+        : v.value && Array.isArray(v.valid_values) && v.valid_values.length && !v.valid_values.includes(v.value)
+          ? `The value is one of the valid values: ${v.valid_values.join(', ')}.`
+          : null,
+    fields: [
+      { name: 'name', label: 'Name', kind: 'upper', help: 'e.g. SUPPORT_EMAIL: meta.get_app_setting(\'SUPPORT_EMAIL\') reads it, meta.set_app_setting(\'SUPPORT_EMAIL\', …) changes it.' },
+      { name: 'value', label: 'Value', kind: 'text', wide: true },
+      { name: 'description', label: 'Description', kind: 'text', wide: true },
+      { name: 'valid_values', label: 'Valid values', kind: 'list', help: 'Comma-separated; empty: any value.' },
+      { name: 'required', label: 'Value required', kind: 'bool' },
+      { name: 'keep_on_upgrade', label: 'Keep the installed value on upgrade', kind: 'bool', help: 'An import over this application keeps the value set here (on), or takes the value from the file (off).' },
+    ],
+  },
+  // (086) dynamic translations: meta.lang(text)
+  dynamic_translation: {
+    table: 'meta.dynamic_translation',
+    scope: 'app',
+    label: 'Dynamic translation',
+    plural: 'Dynamic translations',
+    icon: 'file',
+    summary: (x) => `${x.language}: ${x.source}`,
+    validate: (v) => (!/^[a-z]{2,3}(-[A-Za-z0-9]{2,8}){0,2}$/.test(String(v.language ?? '')) ? 'Language: a code such as nl, de or pt-BR.' : null),
+    fields: [
+      { name: 'language', label: 'Language', kind: 'text', help: 'e.g. nl, de, pt-BR' },
+      { name: 'source', label: 'Text (as stored)', kind: 'text', wide: true, help: 'The value as the table holds it, e.g. Sales; select meta.lang(dname) from hr.dept shows the translation.' },
+      { name: 'target', label: 'Translation', kind: 'text', wide: true },
+    ],
+  },
   report_layout: {
     table: 'meta.report_layout',
     scope: 'app',

package/src/builder/designer.ts

@@ -227,7 +227,10 @@ export async function designerRoutes(app: FastifyInstance) {
       </form>`;
     // a lock of another developer (on this page or the whole application) makes the page read-only
     const locks = (await appLocks(p.app_id)).filter((l) => l.page_no === 0 || l.page_no === p.page_no);
-    const blocking = locks.find((l) => l.locked_by !== s.username);
+    // (083) a Run only application refuses every change, like a lock
+    const runOnly = (await owner.one(`select build_status = 'run_only' as ok from meta.app where id = $1`, [p.app_id]))?.ok
+      ? { app_id: p.app_id, page_no: 0, locked_by: '', locked_at: '', note: null, run_only: true } : undefined;
+    const blocking = runOnly ?? locks.find((l) => l.locked_by !== s.username);
     const mine = locks.find((l) => l.locked_by === s.username);
     const commentCount = (await owner.one('select count(*)::int as n from meta.dev_comment where app_id = $1 and page_no = $2', [p.app_id, p.page_no])).n;
     const center = html`${blocking ? html`<div class="alert alert-error pd-lock" role="status">${icon('key')} ${lockText(blocking)} Your changes will be refused.</div>` : ''}
@@ -301,6 +304,8 @@ export async function designerRoutes(app: FastifyInstance) {
             ${select('dialog_position', 'Dialog position', p.dialog_position ?? 'center', [['center', 'Centred dialog'], ['right', 'Drawer from the right'], ['left', 'Drawer from the left'], ['top', 'Drawer from the top'], ['bottom', 'Drawer from the bottom']], 'Modal pages only. On phones dialogs and side drawers fill the screen.')}
             ${select('dialog_size', 'Dialog size', p.dialog_size ?? 'medium', [['small', 'Small'], ['medium', 'Medium'], ['large', 'Large']], 'The width (the height of top and bottom drawers).')}
             ${input('static_includes', 'JavaScript and CSS files', (p.static_includes ?? []).join(', '), { placeholder: 'e.g. page-3.js, page-3.css', help: 'Static application files (.js, .css) this page loads after the application\'s own, in this order.' })}
+            <div class="field"><span class="label" aria-hidden="true"></span><label class="check"><input type="checkbox" name="warn_unsaved" value="true"${p.warn_unsaved ? raw(' checked') : ''}> Warn on unsaved changes</label>
+              <small class="help">Ask before the user leaves the page (a link, a redirect button, closing the tab) while an item has a changed value. Submitting doesn't ask. Leave an item out with {"warn_unsaved": false} in its attributes.</small></div>
             ${select('parent_page', 'Breadcrumb parent', p.parent_page ?? '', [['', '- none -'], ...lk.pages.filter((x) => x.page_no !== p.page_no).map((x): [string, string] => [String(x.page_no), `${x.page_no}. ${x.name}`])])}
           </div></fieldset>
           <fieldset class="prop-group"><legend>Security</legend><div class="form-grid">
@@ -383,9 +388,9 @@ export async function designerRoutes(app: FastifyInstance) {
       const before = await owner.one('select app_id, page_no from meta.page where id = $1', [req.params.pid]);
       await owner.query(
         `update meta.page set page_no = $2, name = $3, title = $4, requires_auth = $5, mode = $6, parent_page = $7, authz = $8, protection = $9, build_option = $10,
-                dialog_position = $11, dialog_size = $12, static_includes = $13 where id = $1`,
+                dialog_position = $11, dialog_size = $12, static_includes = $13, warn_unsaved = $14 where id = $1`,
         [req.params.pid, Number(b.page_no), b.name?.trim(), b.title?.trim() || null, b.requires_auth === 'true', b.mode, b.parent_page ? Number(b.parent_page) : null, b.authz || null, b.protection, b.build_option?.trim().toUpperCase() || null,
-         ['left', 'right', 'top', 'bottom'].includes(b.dialog_position ?? '') ? b.dialog_position : 'center', ['small', 'large'].includes(b.dialog_size ?? '') ? b.dialog_size : 'medium', parseIncludes(b.static_includes)],
+         ['left', 'right', 'top', 'bottom'].includes(b.dialog_position ?? '') ? b.dialog_position : 'center', ['small', 'large'].includes(b.dialog_size ?? '') ? b.dialog_size : 'medium', parseIncludes(b.static_includes), b.warn_unsaved === 'true'],
       );
       // the page's lock and comments follow a new page number
       if (before && before.page_no !== Number(b.page_no))

package/src/builder/feedback.ts

@@ -0,0 +1,82 @@
+import type { FastifyInstance } from 'fastify';
+import { owner } from '../db.ts';
+import { html, raw } from '../html.ts';
+import { icon } from '../icons.ts';
+import { appOr404 } from './forms.ts';
+import { appHeader, back, BASE, csrf, developer, flash, region, select, send, shell, type Req } from './ui.ts';
+
+// Application → Feedback (APEX: Team Development → Feedback, migration 084):
+// switch the application's Feedback link on or off, read what users sent
+// (newest first, filtered by status and kind), and answer it with a status
+// and a response the user sees on the feedback page. Answers are data, not
+// a change of the application: allowed while it is locked or Run only.
+
+const STATUSES: [string, string][] = [['open', 'Open'], ['in_progress', 'In progress'], ['done', 'Done'], ['declined', 'Declined']];
+const KINDS: [string, string][] = [['comment', 'Comment'], ['idea', 'Idea'], ['problem', 'Problem']];
+const when = (d: string | Date) => new Date(d).toISOString().slice(0, 16).replace('T', ' ');
+
+export async function feedbackRoutes(app: FastifyInstance) {
+  app.get(`${BASE}/apps/:id(^\\d+$)/feedback`, async (req: Req, reply) => {
+    const s = await developer(req, reply);
+    if (!s) return;
+    const a = await appOr404(req.params.id);
+    if (!a) return reply.code(404).send('Not found');
+    const status = STATUSES.some(([v]) => v === req.query.status) ? String(req.query.status) : '';
+    const kind = KINDS.some(([v]) => v === req.query.kind) ? String(req.query.kind) : '';
+    const rows = (await owner.query(
+      `select * from meta.feedback where app_id = $1 and ($2 = '' or status = $2) and ($3 = '' or kind = $3) order by created_at desc limit 300`,
+      [a.id, status, kind])).rows;
+    const counts = (await owner.query(`select status, count(*)::int as n from meta.feedback where app_id = $1 group by 1`, [a.id])).rows;
+    const count = (st: string) => counts.find((c) => c.status === st)?.n ?? 0;
+    const body = html`
+      ${region('Feedback', html`
+        <form method="post" action="${BASE}/apps/${a.id}/feedback/settings" class="u-mb1">${csrf(s)}
+          <label class="check"><input type="checkbox" name="feedback" value="true"${a.feedback ? raw(' checked') : ''}> Users can send feedback</label>
+          <small class="help">A <b>Feedback</b> link in the application's navigation bar opens a page for a comment, an idea or a problem about the page the user came from, with their earlier feedback and your answers.</small>
+          <div class="buttons"><button class="btn btn-sm">Save</button></div></form>
+        <p class="muted">${count('open')} open, ${count('in_progress')} in progress, ${count('done')} done, ${count('declined')} declined.</p>
+        <form method="get" class="filter-row">
+          ${select('status', 'Status', status, [['', 'All'], ...STATUSES])}
+          ${select('kind', 'Kind', kind, [['', 'All'], ...KINDS])}
+          <button class="btn btn-sm">${icon('filter')} Show</button></form>
+        ${rows.length ? html`<ul class="feedback-admin">${rows.map((f) => html`<li class="feedback-item">
+          <div class="feedback-meta"><span class="tag">${KINDS.find(([v]) => v === f.kind)?.[1]}</span>
+            <b>${f.username}</b> <span class="muted">${when(f.created_at)}${f.page_no ? html` · <a href="/a/${a.alias}/${f.page_no}" target="_blank" rel="noopener">page ${f.page_no}</a>` : ''}${f.rating ? ` · ${'★'.repeat(f.rating)}` : ''}${f.user_agent ? ` · ${f.user_agent}` : ''}</span></div>
+          <p class="feedback-body">${f.body}</p>
+          <form method="post" action="${BASE}/apps/${a.id}/feedback/${f.id}">${csrf(s)}
+            <div class="form-grid">
+              ${select('status', 'Status', f.status, STATUSES)}
+              <div class="field" data-wide><label class="label" for="f_response_${f.id}">Answer (the user sees it)</label>
+                <textarea id="f_response_${f.id}" name="response" rows="2" maxlength="4000">${f.response ?? ''}</textarea>
+                ${f.responded_by ? html`<small class="help">By ${f.responded_by}, ${when(f.responded_at)}</small>` : ''}</div>
+            </div>
+            <div class="buttons"><button class="btn btn-sm btn-hot">Save</button></div></form>
+        </li>`)}</ul>` : html`<p class="muted">No feedback${status || kind ? ' with these filters' : ' yet'}.</p>`}`)}`;
+    const main = html`${appHeader(a, 'activity')}<div class="ide-body">${body}</div>`;
+    return send(reply, s, shell(s, `${a.name} feedback`, [['App Builder', BASE], [a.name, `${BASE}/apps/${a.id}`], ['Activity', `${BASE}/apps/${a.id}/activity`], ['Feedback']], main));
+  });
+
+  app.post(`${BASE}/apps/:id(^\\d+$)/feedback/settings`, async (req: Req, reply) => {
+    const s = await developer(req, reply);
+    if (!s) return;
+    await owner.query('update meta.app set feedback = $2, updated_at = now() where id = $1', [req.params.id, req.body?.feedback === 'true']);
+    flash(s, 'Saved.');
+    return back(reply, s, `${BASE}/apps/${req.params.id}/feedback`);
+  });
+
+  app.post(`${BASE}/apps/:id(^\\d+$)/feedback/:fid(^\\d+$)`, async (req: Req, reply) => {
+    const s = await developer(req, reply);
+    if (!s) return;
+    const b = req.body ?? {};
+    const status = STATUSES.some(([v]) => v === b.status) ? b.status : 'open';
+    const response = String(b.response ?? '').replace(/\r\n?/g, '\n').trim().slice(0, 4000) || null;
+    const r = await owner.query(
+      `update meta.feedback set status = $3, response = $4,
+              responded_by = case when $4::text is distinct from response then $5 else responded_by end,
+              responded_at = case when $4::text is distinct from response then now() else responded_at end
+        where id = $2 and app_id = $1`,
+      [req.params.id, req.params.fid, status, response, s.username]);
+    flash(s, r.rowCount ? 'Saved.' : 'Not found.', r.rowCount ? 'ok' : 'error');
+    return back(reply, s, `${BASE}/apps/${req.params.id}/feedback`);
+  });
+}

package/src/builder/forms.ts

@@ -74,7 +74,10 @@ export function iconPicker(id: string, name: string, label: string, current: str
 export function componentForm(spec: ComponentSpec, kind: string, row: any, lk: Lookups, action: string, s: Session, submit: string, opts: { id?: string } = {}) {
   const field = (f: Field) => {
     const v = row?.[f.name];
-    const help = f.help ? html`<small class="help">${f.help}</small>` : '';
+    const own = row?.id ? f.helpBy?.(row) : null;
+    const help = own
+      ? html`<small class="help">${own.text}${own.url ? html` <a href="${own.url}" target="_blank" rel="noopener">Guide ▸</a>` : ''}</small>`
+      : f.help ? html`<small class="help">${f.help}</small>` : '';
     const id = `f_${kind}_${f.name}`;
     let control: Raw;
     const opts = (list: [string, string][]) =>

package/src/builder/home.ts

@@ -219,6 +219,8 @@ export async function homeRoutes(app: FastifyInstance) {
       ${region('Export file', html`<form method="post" action="${BASE}/import">${csrf(s)}
         <div class="field" data-wide><label class="label" for="f_doc">Export JSON</label><textarea id="f_doc" name="doc" class="code" rows="14" required data-code="json"></textarea></div>
         ${input('alias', 'New alias (optional)', '', { help: 'Leave empty to keep the alias in the export.' })}
+        <div class="field"><label class="check"><input type="checkbox" name="check" value="true" checked> Check the application before importing</label>
+          <small class="help">The Advisor plans its SQL as the application's database role and checks its references before anything is saved: errors (a missing table, column or function, a wrong type, a missing grant) refuse the import.</small></div>
         <div class="buttons"><a class="btn" href="${BASE}">Cancel</a><button class="btn btn-hot">Import</button></div>
       </form>`)}
     </div>`;
@@ -285,6 +287,7 @@ export async function homeRoutes(app: FastifyInstance) {
         ${(await isAdmin(s.username)) ? card(`${BASE}/instance`, icon('settings'), 'Instance settings', 'Session length, sign-in throttling and the server\'s configuration (administrators).') : ''}
         ${(await isAdmin(s.username)) ? card(`${BASE}/workspaces`, icon('layers'), 'Workspaces', 'Groups of applications and their developers (administrators).') : ''}
         ${(await isAdmin(s.username)) ? card(`${BASE}/ai`, icon('bolt'), 'AI services', 'Claude and OpenAI for the applications: models, keys, limits and usage (administrators).') : ''}
+        ${(await isAdmin(s.username)) ? card(`${BASE}/mail`, icon('send'), 'Mail services', 'SMTP, Microsoft 365, Amazon SES, Resend, Postmark, SendGrid or Mailgun for the applications\' e-mail (administrators).') : ''}
         ${(await isAdmin(s.username)) ? card(`${BASE}/installation`, icon('history'), 'Installation', 'Version, install and upgrade runs, applied migrations (administrators).') : ''}
       </div>`;
     return send(reply, s, shell(s, 'Workspace utilities', [['App Builder', BASE], ['Workspace utilities']], main));

package/src/builder/locks.ts

@@ -21,6 +21,8 @@ export interface Lock {
   locked_by: string;
   locked_at: string;
   note: string | null;
+  /** (083) not a developer's lock: the application's build status is Run only */
+  run_only?: boolean;
 }
 
 export const isAdmin = async (username: string | null | undefined) =>
@@ -31,7 +33,10 @@ export const appLocks = async (appId: number) =>
   (await owner.query<Lock>('select app_id, page_no, locked_by, locked_at::text, note from meta.builder_lock where app_id = $1 order by page_no', [appId])).rows;
 
 /** Builder POSTs that are allowed on a locked page or application (locking, unlocking, comments). */
-const EXEMPT = /^\/apps\/\d+\/(lock|unlock|comments(\/\d+\/delete)?)$/;
+const EXEMPT = /^\/apps\/\d+\/(lock|unlock|comments(\/\d+\/delete)?|feedback\/\d+)$/;
+/** (083) Builder POSTs allowed on a Run only application: its availability and build status, a backup, locks and comments. */
+// (086) an existing application setting stays editable: settings are what an administrator changes after deployment
+const RUN_ONLY_EXEMPT = /^\/apps\/\d+\/(availability|backups|backups\/settings|lock|unlock|comments(\/\d+\/delete)?|feedback\/\d+|shared\/app_setting\/\d+)$/;
 
 /** The application (and page) a builder URL under /apps/:id or /pages/:pid is about, or null. */
 export async function appOfPath(path: string): Promise<{ appId: number; pageNo: number | null; pageId: number | null } | null> {
@@ -50,10 +55,13 @@ export async function appOfPath(path: string): Promise<{ appId: number; pageNo:
  */
 export async function blockingLock(username: string, path: string): Promise<{ lock: Lock; appId: number; pageId: number | null } | null> {
   const rel = path.split('?')[0].slice(BASE.length);
-  if (EXEMPT.test(rel)) return null;
   const target = await appOfPath(path);
   if (!target) return null;
   const { appId, pageNo, pageId } = target;
+  // (083) a Run only application refuses changes, whoever asks
+  if (!RUN_ONLY_EXEMPT.test(rel) && (await owner.one<{ ok: boolean }>(`select build_status = 'run_only' as ok from meta.app where id = $1`, [appId]))?.ok)
+    return { lock: { app_id: appId, page_no: 0, locked_by: '', locked_at: '', note: null, run_only: true }, appId, pageId };
+  if (EXEMPT.test(rel)) return null;
   const lock = await owner.one<Lock>(
     `select app_id, page_no, locked_by, locked_at::text, note from meta.builder_lock
       where app_id = $1 and (page_no = 0 or page_no = $2) and locked_by <> $3 order by page_no limit 1`,
@@ -62,12 +70,14 @@ export async function blockingLock(username: string, path: string): Promise<{ lo
   return lock ? { lock, appId, pageId } : null;
 }
 
-export const lockText = (l: Pick<Lock, 'page_no' | 'locked_by' | 'locked_at' | 'note'>) =>
-  `${l.page_no ? `Page ${l.page_no}` : 'The application'} is locked by ${l.locked_by} since ${l.locked_at.slice(0, 16)}${l.note ? ` (${l.note})` : ''}.`;
+export const lockText = (l: Pick<Lock, 'page_no' | 'locked_by' | 'locked_at' | 'note' | 'run_only'>) =>
+  l.run_only
+    ? 'The application is Run only (Availability → Build status).'
+    : `${l.page_no ? `Page ${l.page_no}` : 'The application'} is locked by ${l.locked_by} since ${l.locked_at.slice(0, 16)}${l.note ? ` (${l.note})` : ''}.`;
 
 /** Refuse a change to a locked page or application: a JSON error or a message on the page it came from. */
 export async function refuseLocked(req: Req, reply: FastifyReply, s: Session, hit: NonNullable<Awaited<ReturnType<typeof blockingLock>>>) {
-  const message = `${lockText(hit.lock)} Changes are refused until it is unlocked.`;
+  const message = hit.lock.run_only ? `${lockText(hit.lock)} Set it back to Run and build to change it.` : `${lockText(hit.lock)} Changes are refused until it is unlocked.`;
   if (String(req.headers.accept ?? '').includes('application/json')) return reply.code(423).send({ ok: false, error: message });
   flash(s, message, 'error');
   return back(reply, s, hit.pageId ? `${BASE}/pages/${hit.pageId}` : `${BASE}/apps/${hit.appId}`);