pgkiln 0.31.0 → 0.35.0

package/docs/guide/12-development.md

@@ -68,6 +68,7 @@ src/
   css.ts                   PageCss: data-dependent styles as classes in the page's nonce'd <style> (CSP)
   metadata.ts              types + loaders for apps and pages (components of excluded build options are left out here)
   maptiles.ts              map tile server URL, attribution and CSP origin
+  geocode.ts               the installation's geocoder for address items (GEOCODER_URL, Nominatim search API)
   mvt.ts                   Mapbox Vector Tile encoding for map layers served as tiles
   yamltext.ts              the text style of the directory export: a strict YAML subset, written and read
   webclient.ts             outgoing HTTP to web services: allow-list, address checks at connect time (SSRF), redirects, limits
@@ -80,6 +81,11 @@ src/
   webrequests.ts           web requests from SQL (meta.web_request, migration 052): runPending() after each sql page process
                            (same transaction), webRequestTick() for committed ones (automations scheduler), retention purge;
                            calls go through websources.ts call()/invoke() (allow-list, SSRF checks, credentials)
+  mail/                    e-mail (migration 081): providers.ts (one deliver() per provider: SMTP through nodemailer with a password
+                           or XOAUTH2, Microsoft Graph sendMail, Amazon SES v2 raw MIME with signV4, Resend, Postmark, SendGrid,
+                           Mailgun, log; MailError says whether a retry may help; client-credentials token cache; settingsProblems),
+                           mail.ts (sendWith(): service enabled, allowed sender, secret decrypted; mailTick(): claim with SKIP LOCKED,
+                           send, retry after 1/4/16/64 minutes, purge after 30 days; the NOTIFY pgkiln_mail listener)
   ai/                      AI services (migration 060): types.ts (the provider interface, AiError kinds),
                            anthropic.ts (Claude through @anthropic-ai/sdk: streamed, effort, structured outputs via
                            output_config.format, refusal fallbacks, stop_reason checks, typed SDK errors), openai.ts (the openai
@@ -142,6 +148,21 @@ src/
                            session, formatAnswer (escaped), send/clear routes
     ai-filter.ts           natural-language filters on a report ("ai_filter"): columns → structured output → checked → r<id>_f/q/s/d
     pdf.ts                 report PDFs with report layouts (pdfkit); rows from a cursor in batches (tablePdf takes batches)
+    search.ts              search region and search configurations (migration 080): words as ILIKE parameters, table/sql/list
+                           sources as the app role in savepoints, marked results, configColumns/searchConfigProblems for the Advisor
+    url-region.ts          URL region (migration 078): literal origins only (urlTarget), &ITEM. URL-encoded, sandbox and height,
+                           frameOrigins() for the CSP's frame-src (security.ts)
+    ajax.ts                Ajax callbacks (migration 085: POST …/ajax/:name, point "ajax" processes, x01 … x10 binds) and the
+                           download dynamic action (POST …/da/:id/download)
+    availability.ts        availabilityRefusal(): who may use an application (migration 083); loadContext, the login page
+                           and REST modules ask it (PostgREST: meta.api_check)
+    feedback.ts            users' feedback page and the navigation bar entry (migration 084)
+    data-items.ts          display image and address items (migration 086): imageUrl (https origins into the CSP's img-src),
+                           GET …/image/:item (a BLOB from the item's query), POST …/geocode/:item, and items kept per user
+                           (loadPreferences / savePreferences through meta.get_preference / set_preference)
+    data-export.ts         the download process's {"export": …}: meta.data_export for csv/json/xml/html, Excel and PDF here
+    devbar.ts              developer toolbar and session state viewer (migration 079): the pgkiln_devbar token of a builder
+                           session (ensureDevbar/devbarOf), the toolbar markup, the viewer, clear and per-session debug routes
   builder/
     components.ts          property spec of every component (drives the property editor)
     ui.ts                  IDE shell (icon rail, toolbar, breadcrumb, status bar), builder theme, form helpers, CSRF check, app tabs
@@ -158,6 +179,14 @@ src/
     appwizard.ts           Create → From pasted data (kept as a temp file, then the From a file steps) and From existing tables
                            (a schema's tables/views → report+form or report pages, navigation, dashboard)
     forms.ts               generic component property form (lookups, render, save)
+    backups.ts             Application → Backups (migration 082): list, back up now, download, restore (replaceApp), keep N;
+                           backupTick() for the scheduler's daily backups of changed applications
+    availability.ts        Application → Availability (migration 083): status, message, users, build status (Run only is
+                           enforced by locks.ts blockingLock); availabilityBadge() in the application header
+    feedback.ts            Application → Feedback (migration 084): the setting, the list with filters, status and answers
+    region-help.ts         the Attributes (JSON) help per region type, with links to the guide
+    mail.ts                Workspace utilities → Mail services (administrators: providers, write-only secret, allowed senders,
+                           applications with From and daily limit, test) and Applications → Activity → Mail (retry, cancel)
     shared.ts              Shared Components and access control
     designer.ts            page designer: component tree (with computations and branches), layout canvas and gallery, property editor, toolbar
     arrange.ts             page designer layout changes: move, column span, create from the gallery, undo / redo
@@ -377,5 +406,8 @@ browser enhancements at the end of `public/app.js` (the item must work without t
 1. Update `CHANGELOG.md` and the version in `package.json`.
 2. Merge to `main`; CI must be green (every job). The `main` branch should be protected on
    GitHub (Settings → Branches → rule for `main`: require the CI checks).
-3. Tag: `git tag -a vX.Y.Z -m vX.Y.Z && git push origin vX.Y.Z`.
+3. Tag: `git tag -a vX.Y.Z -m vX.Y.Z && git push origin vX.Y.Z`. The tag publishes the Docker image
+   (`docker-publish.yml`: `pgkiln/pgkiln` and `ghcr.io/pgkiln/pgkiln`, amd64 and arm64) and the npm package
+   (`npm-publish.yml`, trusted publishing with provenance; it refuses a tag that doesn't match
+   `package.json`). Then `gh release create vX.Y.Z` with the changelog section as notes.
 4. Add the new tag to the `upgrade` job's matrix in `.github/workflows/ci.yml` (see above).

package/docs/guide/14-globalization.md

@@ -98,6 +98,21 @@ raise exception '%', meta.message('LEAVE_OVERLAP', to_char(p_start, 'DD-MM-YYYY'
 
 The HR sample's dashboard uses them for its key figures (`examples/hr/hr_04_i18n.sql`).
 
+### Dynamic translations
+
+For **values from tables** (department names, statuses, list of values entries), use dynamic
+translations (APEX: *Dynamic Translations*, `APEX_LANG.LANG`): **Shared Components → Dynamic
+translations** holds a language, the text as stored and its translation, and `meta.lang` returns
+the text in the session's language:
+
+```sql
+select meta.lang(dname) as d, deptno as r from hr.dept order by 1   -- a list of values
+```
+
+An exact language match wins, then the base language (`nl-BE` → `nl`), else the text as it is.
+`meta.lang(text, 'de')` asks for another language. Dynamic translations are exported with the
+application (`globalization/dynamic-translations.yaml` in an application's files).
+
 ### Date formats
 
 Dates and timestamps in reports, grids and display items are formatted with a **mask**:

package/docs/guide/15-extensions.md

@@ -109,7 +109,7 @@ Audit triggers record such changes as made by `nobody`, which is what you want f
 | **[pgmq](https://github.com/pgmq/pgmq)** | A message queue in Postgres for background work handled by a worker service | Like AWS SQS, transactional |
 | **pg_partman** | Partition big append-only tables such as `meta.activity_log` by month | Only needed at high volume |
 | **[plv8](https://github.com/plv8/plv8)** | Server-side JavaScript functions | Like APEX's MLE JavaScript. Maintained upstream, but some hosts (e.g. Supabase on PostgreSQL 17) no longer offer it, so check before depending on it |
-| **[pg_smtp_client](https://github.com/brianpursley/pg_smtp_client)** | Sending e-mail from SQL, if your team needs it | pgkiln deliberately doesn't send mail ([chapter 11](11-from-apex.md)). This keeps mail out of pgkiln and in your own schema |
+| **[pg_smtp_client](https://github.com/brianpursley/pg_smtp_client)** | Sending e-mail synchronously from SQL, outside an application | pgkiln itself sends mail queued with `meta.send_mail` after the commit, through SMTP, Microsoft Graph, Amazon SES or an HTTP API ([chapter 6](06-processing.md#sending-e-mail)); this extension talks SMTP from the database itself |
 
 ## Security notes
 

package/docs/guide/18-cli.md

@@ -35,7 +35,7 @@ any (see [what is not exported](03-builder.md#export-format)).
 | `pgkiln migrate [--example <name>]` | Applies the migrations that were not applied yet, then optionally `examples/<name>/` (same as `npm run db:migrate` / `npm run example:hr`; `--root` and `--seed` as in `scripts/migrate.ts`) |
 | `pgkiln apps [--json]` | Lists the applications: alias, number of pages, name |
 | `pgkiln export <alias> [--format json\|dir\|text] [--out <path>]` | `json` (default): the `pgkiln/2` document with sorted keys, to `--out` or standard output. `dir`: a directory (default `./<alias>`), see below. `text`: the same directory in YAML with the code inline ([text files](#text-files-apexlang)) |
-| `pgkiln import <path> [--alias <alias>] [--replace]` | Imports a JSON export, an application directory or a `.zip` of one. `--alias` gives the copy another alias. `--replace` updates the application with that alias in place |
+| `pgkiln import <path> [--alias <alias>] [--replace] [--check [--force] \| --dry-run]` | Imports a JSON export, an application directory or a `.zip` of one. `--alias` gives the copy another alias. `--replace` updates the application with that alias in place (after a [backup](03-builder.md#backups)). `--check` checks the application before it commits, `--dry-run` only checks ([below](#checking-before-an-import)) |
 | `pgkiln diff <alias> <path> [--name-only \| --quiet]` | What differs between the application in the database and a directory (or JSON file, or zip) |
 | `pgkiln mcp` | An MCP server on standard input/output for AI coding agents, see [chapter 20](20-ai-agents.md) |
 | `pgkiln plugin build <dir> [-o <file>]` | Builds a plug-in file (`pgkiln-plugin/2`) from a source directory, see [plug-ins](04-pages-and-regions.md#plug-ins-with-their-own-code) |
@@ -187,6 +187,9 @@ the files any more are removed. What belongs to this installation stays:
   [chapter 19](19-rest-data-sources.md#web-credentials)).
 - the **style variant each user chose** ([chapter 14](14-globalization.md#style-variants-theme-roller));
   a style that the file no longer has falls back to the default.
+- its **availability and build status** ([chapter 3](03-builder.md#availability-and-build-status)): exports
+  leave them out, so a deployment doesn't open an application you closed, or close one;
+- its **backups**: the version the import replaces is the newest one ([chapter 3](03-builder.md#backups)).
 
 It all happens in one transaction; any error leaves the application unchanged. Without an
 application with that alias, `--replace` simply imports, so the same command deploys the first
@@ -201,6 +204,32 @@ pgkiln diff hr apps/hr                           # on the target: what would cha
 pgkiln import apps/hr --replace                  # deploy
 ```
 
+### Checking before an import
+
+An import doesn't need the application's tables, columns and functions to exist (neither does APEX's):
+a page whose SQL names a missing table imports fine and fails when it runs. `--check` asks the
+[Advisor](03-builder.md#advisor) first, inside the import's transaction, before anything is committed:
+every SQL fragment is planned as the application's database role (unknown tables, columns,
+functions and types, missing grants), PL/pgSQL blocks are compiled, and references to pages,
+items, lists of values, schemes and search configurations are checked.
+
+```sh
+pgkiln import apps/hr --replace --check      # errors: nothing changes, exit code 1
+pgkiln import apps/hr --replace --dry-run    # only check (exit code 0 without errors)
+pgkiln import apps/hr --replace --check --force   # report, import anyway
+```
+
+```text
+ERROR  page 2, region Employees (Source): relation "hr.employee" does not exist
+WARNING  page 3, item P3_SAL (Default value): …
+Check: 1 error(s), 1 warning(s), 0 note(s).
+Not imported: the check found 1 error(s). Fix them, or use --force.
+```
+
+Deploy the database changes (your migration scripts) before the application, so the check sees
+the tables the new version needs. The MCP server's `import_app` checks by default; the builder's
+Import page has the check ticked.
+
 `export --format dir` into an existing directory removes the files of deleted components and
 leaves dot files (`.git`, `.gitattributes`) alone; it refuses a non-empty directory without a
 `pgkiln.json`, so a typo can't empty the wrong folder.

package/docs/guide/20-ai-agents.md

@@ -53,7 +53,7 @@ directory the agent started the server in (the project).
 | `recent_errors` | the latest errors and refused requests from the activity log | no |
 | `export_app` | writes an application to a directory (default `apps/<alias>`, format `text`) | files on disk |
 | `diff_app` | what an import of a directory would change (A/D/M with unified diffs); also reports files it can't read | no |
-| `import_app` | imports a directory, zip or JSON file; `replace: true` updates the application in place | the database |
+| `import_app` | imports a directory, zip or JSON file; `replace: true` updates the application in place. It checks the application first (the Advisor, in the import's transaction): errors refuse the import and are listed; `force: true` imports anyway, `dry_run: true` only checks | the database |
 
 The files are the [directory format](18-cli.md#the-directory-format) of the command line, in the
 [text style](18-cli.md#text-files-apexlang): one YAML file per component, with SQL, PL/pgSQL and
@@ -67,7 +67,8 @@ users, sessions and saved reports kept, supporting objects and plug-in install S
    `describe_schema` for the tables; `search_docs` before guessing a property or region type.
 2. `export_app` to `apps/<alias>`, then edit the YAML files there.
 3. `diff_app`, so you (and it) see exactly what will change.
-4. `import_app` with `replace: true`. Open the page in the browser to check.
+4. `import_app` with `replace: true`. When it names errors (a missing column, a typo in SQL), the agent fixes
+   the files and imports again; nothing was changed. Open the page in the browser to check.
 
 Tables, views and functions are ordinary PostgreSQL objects: an agent changes them in your
 migration scripts, not in the application files (`run_query` can't change them anyway).

package/examples/hr/hr_50_search.sql

@@ -0,0 +1,47 @@
+-- =====================================================================
+-- HR example, part 50: search configurations and the search region
+-- (migration 080; docs/guide/04-pages-and-regions.md, search region)
+--
+-- Page 42 "Search": one field searches three sources as you type:
+--   - EMPLOYEES: a query (employees with their department), each result
+--     opens the employee's form (page 3);
+--   - DEPARTMENTS: the table hr.dept, each result opens page 5;
+--   - SHORTCUTS: the entries of the list HR_SHORTCUTS the user may see.
+-- =====================================================================
+
+insert into meta.search_config (app_id, name, label, seq, source_type, source, searchable_columns,
+                                title_column, subtitle_column, badge_column, icon, link)
+select a.id, c.name, c.label, c.seq, c.source_type, c.source, c.searchable, c.title, c.subtitle, c.badge, c.icon, c.link::jsonb
+  from meta.app a, (values
+  ('EMPLOYEES', 'Employees', 10, 'sql',
+   $q$select e.empno, initcap(e.ename) as name, initcap(e.job) as job, initcap(d.dname) as department
+  from hr.emp e left join hr.dept d on d.deptno = e.deptno$q$,
+   '{name,job,department}'::text[], 'name', 'job', 'department', 'user', '{"page": 3, "items": {"P3_EMPNO": "#EMPNO#"}}'),
+  ('DEPARTMENTS', 'Departments', 20, 'table', 'hr.dept', '{dname,loc}'::text[], 'dname', 'loc', null, 'building',
+   '{"page": 5, "items": {"P5_DEPTNO": "#DEPTNO#"}}'),
+  ('SHORTCUTS', 'Shortcuts', 30, 'list', 'HR_SHORTCUTS', '{}'::text[], null, null, null, 'link', null)
+  ) as c (name, label, seq, source_type, source, searchable, title, subtitle, badge, icon, link)
+ where a.alias = 'hr';
+
+insert into meta.page (app_id, page_no, name, title, parent_page)
+select id, 42, 'Search', 'Search', 1 from meta.app where alias = 'hr';
+
+insert into meta.region (page_id, seq, title, type, columns, template, config)
+select p.id, 10, 'Search', 'search', 12, 'standard',
+       '{"configs": ["EMPLOYEES", "DEPARTMENTS", "SHORTCUTS"], "placeholder": "Search employees, departments and shortcuts…"}'
+  from meta.page p join meta.app a on a.id = p.app_id where a.alias = 'hr' and p.page_no = 42;
+
+insert into meta.nav_entry (app_id, seq, label, icon, target_page)
+select id, 2, 'Search', 'search', 42 from meta.app where alias = 'hr';
+
+insert into meta.translation (app_id, language, source, target)
+select a.id, 'nl', t.source, t.target
+  from meta.app a, (values
+  ('Search', 'Zoeken'),
+  ('Employees', 'Medewerkers'),
+  ('Departments', 'Afdelingen'),
+  ('Shortcuts', 'Snelkoppelingen'),
+  ('Search employees, departments and shortcuts…', 'Zoek medewerkers, afdelingen en snelkoppelingen…')
+  ) as t (source, target)
+ where a.alias = 'hr'
+on conflict do nothing;

package/examples/hr/hr_51_mail.sql

@@ -0,0 +1,70 @@
+-- =====================================================================
+-- HR example, part 51: e-mail (migration 081; docs/guide/06-processing.md,
+-- "Sending e-mail")
+--
+-- The example sends through a mail service of provider "log": the server
+-- writes each mail to its log and sends nothing, so the example works on
+-- any installation. An administrator points HR at a real service under
+-- Workspace utilities → Mail services (SMTP, Microsoft 365, Amazon SES,
+-- Resend, Postmark, SendGrid or Mailgun).
+--
+-- The template LEAVE_DECIDED tells an employee that a leave request was
+-- approved or rejected; a trigger queues it from the running application
+-- when the status changes (the decision's transaction: a rollback sends
+-- nothing). A mail that can't be queued never stops the decision.
+-- =====================================================================
+
+insert into meta.mail_service (name, description, provider, senders, settings)
+values ('DEVELOPMENT_LOG', 'Writes mail to the server log; sends nothing', 'log', '{@example.com}', '{"default_from": "hr@example.com"}')
+on conflict (name) do nothing;
+
+insert into meta.app_mail_service (app_id, service_id, from_address, max_per_day)
+select a.id, s.id, 'hr@example.com', 500
+  from meta.app a, meta.mail_service s
+ where a.alias = 'hr' and s.name = 'DEVELOPMENT_LOG'
+on conflict (app_id) do nothing;
+
+insert into meta.email_template (app_id, name, subject, html_body, text_body)
+select id, 'LEAVE_DECIDED', 'Your leave request was #STATUS#',
+$h$<p>Dear #NAME#,</p>
+<p>Your leave request from <b>#START#</b> to <b>#END#</b> was <b>#STATUS#</b> by #DECIDED_BY#.</p>
+<p>Kind regards,<br>HR</p>$h$,
+$t$Dear #NAME#,
+
+Your leave request from #START# to #END# was #STATUS# by #DECIDED_BY#.
+
+Kind regards,
+HR$t$
+  from meta.app where alias = 'hr';
+
+create function hr.mail_leave_decided() returns trigger
+language plpgsql security definer set search_path = hr, pg_catalog as $$
+declare
+  v_email text;
+  v_name  text;
+begin
+  if new.status not in ('APPROVED', 'REJECTED') or meta.app_id() is null then
+    return new;
+  end if;
+  select a.email, initcap(e.ename) into v_email, v_name
+    from hr.emp e join meta.account a on lower(a.username) = lower(e.username)
+   where e.empno = new.empno;
+  if v_email is null then
+    return new;
+  end if;
+  perform meta.send_mail_template('LEAVE_DECIDED', jsonb_build_object(
+    'NAME', v_name,
+    'STATUS', lower(new.status),
+    'START', to_char(new.start_date, 'DD Mon YYYY'),
+    'END', to_char(new.end_date, 'DD Mon YYYY'),
+    'DECIDED_BY', coalesce(new.decided_by, 'HR')), v_email);
+  return new;
+exception when others then
+  raise warning 'hr.mail_leave_decided: %', sqlerrm;
+  return new;
+end
+$$;
+
+create trigger leave_decided_mail after update of status on hr.leave_request
+  for each row when (old.status is distinct from new.status)
+  execute function hr.mail_leave_decided();

package/examples/hr/hr_52_feedback.sql

@@ -0,0 +1,15 @@
+-- =====================================================================
+-- HR example, part 52: feedback (migration 084; docs/guide/03-builder.md,
+-- "Feedback")
+--
+-- Users send feedback about a page from the navigation bar's Feedback link;
+-- developers answer under Application → Activity → Feedback. One answered
+-- example from the user king.
+-- =====================================================================
+
+update meta.app set feedback = true where alias = 'hr';
+
+insert into meta.feedback (app_id, page_no, username, kind, rating, body, status, response, responded_by, responded_at)
+select id, 2, 'king', 'idea', 4, 'Could the employee list show the hire date as well?', 'done',
+       'Added in the column list: open Actions → Columns and show "Hiredate".', 'admin', now()
+  from meta.app where alias = 'hr';

package/examples/hr/hr_53_data_settings.sql

@@ -0,0 +1,108 @@
+-- =====================================================================
+-- HR example, part 53: data and settings (migration 086;
+-- docs/guide/06-processing.md "Application settings", "User preferences",
+-- "Data export"; docs/guide/14-globalization.md "Dynamic translations";
+-- docs/guide/05-items.md "Display image", "Geocoded address")
+--
+-- Application settings SUPPORT_EMAIL and LEAVE_APPROVAL (Shared
+-- Components → Application settings), read with meta.get_app_setting.
+-- Dynamic translations of the department names in Dutch and German:
+-- meta.lang(dname). Page 43 "Data and settings" (Administration):
+--   - P43_DEPTNO, a department (names through meta.lang), kept per user
+--     across sessions ({"persist": "user"});
+--   - P43_EMPNO, an employee of that department, also kept per user, and
+--     P43_PHOTO, the employee's photo from hr.emp.photo (display image);
+--   - P43_ADDRESS, a geocoded address whose position goes into P43_LOCATION
+--     (the "Check address" button shows where the server has GEOCODER_URL);
+--   - Excel and CSV downloads of the department's employees (the download
+--     process with {"export": …}, APEX_DATA_EXPORT).
+-- =====================================================================
+
+insert into meta.app_setting (app_id, name, value, description, required, valid_values)
+select a.id, s.name, s.value, s.description, s.required, s.valid_values
+  from meta.app a, (values
+  ('SUPPORT_EMAIL', 'hr-support@example.com', 'Where users write with questions; shown on page 43.', true, null::text[]),
+  ('LEAVE_APPROVAL', 'manager', 'Who approves leave requests: the manager, or the HR department.', true, '{manager,hr}'::text[])
+  ) as s (name, value, description, required, valid_values)
+ where a.alias = 'hr';
+
+insert into meta.dynamic_translation (app_id, language, source, target)
+select a.id, t.language, t.source, t.target
+  from meta.app a, (values
+  ('nl', 'ACCOUNTING', 'BOEKHOUDING'), ('nl', 'RESEARCH', 'ONDERZOEK'), ('nl', 'SALES', 'VERKOOP'), ('nl', 'OPERATIONS', 'BEDRIJFSVOERING'),
+  ('de', 'ACCOUNTING', 'BUCHHALTUNG'), ('de', 'RESEARCH', 'FORSCHUNG'), ('de', 'SALES', 'VERTRIEB'), ('de', 'OPERATIONS', 'BETRIEB')
+  ) as t (language, source, target)
+ where a.alias = 'hr';
+
+insert into meta.page (app_id, page_no, name, title, parent_page)
+select id, 43, 'Data and settings', 'Data and settings', 1 from meta.app where alias = 'hr';
+
+insert into meta.region (page_id, seq, title, type, columns, template)
+select p.id, r.seq, r.title, 'static', 12, 'standard'
+  from meta.page p join meta.app a on a.id = p.app_id, (values (10, 'Employee'), (20, 'Visit address')) as r (seq, title)
+ where a.alias = 'hr' and p.page_no = 43;
+
+insert into meta.item (page_id, region_id, seq, name, label, type, lov, help, config)
+select p.id, (select r.id from meta.region r where r.page_id = p.id and r.title = i.region), i.seq, i.name, i.label, i.type, i.lov, i.help, i.config::jsonb
+  from meta.page p join meta.app a on a.id = p.app_id, (values
+  ('Employee', 10, 'P43_DEPTNO', 'Department', 'select',
+   'select meta.lang(dname), deptno from hr.dept order by 1', 'Remembered for you, also after you sign out.',
+   '{"persist": "user", "submit_on_change": true, "null_label": "- All -"}'),
+  ('Employee', 20, 'P43_EMPNO', 'Employee', 'select',
+   'select initcap(ename), empno from hr.emp where :P43_DEPTNO is null or deptno = :P43_DEPTNO::int order by 1', null,
+   '{"persist": "user", "submit_on_change": true, "null_label": "- Choose -"}'),
+  ('Employee', 30, 'P43_PHOTO', 'Photo', 'image', null, null,
+   '{"sql": "select photo, photo_mime from hr.emp where empno = :P43_EMPNO::int", "alt": "Photo of the employee", "width": 160}'),
+  ('Employee', 40, 'P43_SUPPORT', 'Questions?', 'display', null, 'The application setting SUPPORT_EMAIL.', '{}'),
+  ('Visit address', 50, 'P43_ADDRESS', 'Address', 'address', null, 'Type the address and choose it from the list.',
+   '{"coordinates_item": "P43_LOCATION"}'),
+  ('Visit address', 60, 'P43_LOCATION', 'Position', 'location', null, null, '{}')
+  ) as i (region, seq, name, label, type, lov, help, config)
+ where a.alias = 'hr' and p.page_no = 43;
+
+insert into meta.button (page_id, region_id, seq, name, label, action)
+select p.id, (select r.id from meta.region r where r.page_id = p.id and r.title = 'Employee'), b.seq, b.name, b.label, 'submit'
+  from meta.page p join meta.app a on a.id = p.app_id, (values (10, 'EXPORT_XLSX', 'Download Excel'), (20, 'EXPORT_CSV', 'Download CSV')) as b (seq, name, label)
+ where a.alias = 'hr' and p.page_no = 43;
+
+insert into meta.process (page_id, seq, name, type, point, code, when_button, config)
+select p.id, x.seq, x.name, x.type, x.point, x.code, x.button, x.config::jsonb
+  from meta.page p join meta.app a on a.id = p.app_id, (values
+  (10, 'Support address', 'sql', 'load', 'select meta.get_app_setting(''SUPPORT_EMAIL'') as p43_support', null, '{}'),
+  (20, 'Employees as Excel', 'download', 'submit',
+   'select e.empno, initcap(e.ename) as name, initcap(e.job) as job, e.hiredate, e.sal as salary, meta.lang(d.dname) as department
+  from hr.emp e left join hr.dept d on d.deptno = e.deptno
+ where :P43_DEPTNO is null or e.deptno = :P43_DEPTNO::int
+ order by e.ename', 'EXPORT_XLSX', '{"export": "xlsx", "file_name": "employees", "title": "Employees"}'),
+  (30, 'Employees as CSV', 'download', 'submit',
+   'select e.empno, initcap(e.ename) as name, initcap(e.job) as job, e.hiredate, e.sal as salary, meta.lang(d.dname) as department
+  from hr.emp e left join hr.dept d on d.deptno = e.deptno
+ where :P43_DEPTNO is null or e.deptno = :P43_DEPTNO::int
+ order by e.ename', 'EXPORT_CSV', '{"export": "csv", "file_name": "employees"}')
+  ) as x (seq, name, type, point, code, button, config)
+ where a.alias = 'hr' and p.page_no = 43;
+
+insert into meta.nav_entry (app_id, parent_id, seq, label, icon, target_page)
+select a.id, n.id, 40, 'Data and settings', 'settings', 43
+  from meta.app a join meta.nav_entry n on n.app_id = a.id and n.label = 'Administration' and n.parent_id is null
+ where a.alias = 'hr';
+
+insert into meta.translation (app_id, language, source, target)
+select a.id, 'nl', t.source, t.target
+  from meta.app a, (values
+  ('Data and settings', 'Gegevens en instellingen'),
+  ('Employee', 'Medewerker'),
+  ('Visit address', 'Bezoekadres'),
+  ('Department', 'Afdeling'),
+  ('Photo', 'Foto'),
+  ('Questions?', 'Vragen?'),
+  ('Address', 'Adres'),
+  ('Position', 'Positie'),
+  ('Download Excel', 'Excel downloaden'),
+  ('Download CSV', 'CSV downloaden'),
+  ('Remembered for you, also after you sign out.', 'Wordt voor u onthouden, ook na afmelden.'),
+  ('The application setting SUPPORT_EMAIL.', 'De applicatie-instelling SUPPORT_EMAIL.'),
+  ('Type the address and choose it from the list.', 'Typ het adres en kies het uit de lijst.')
+  ) as t (source, target)
+ where a.alias = 'hr'
+on conflict do nothing;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pgkiln",
-  "version": "0.31.0",
+  "version": "0.35.0",
   "description": "Open source low-code, SQL-driven application builder for PostgreSQL, inspired by Oracle APEX",
   "keywords": [
     "postgresql",
@@ -73,6 +73,7 @@
     "ldapts": "^9.2.0",
     "leaflet": "^1.9.4",
     "lucide-static": "^1.52.0",
+    "nodemailer": "^10.0.12",
     "openai": "^7.28.0",
     "pdfkit": "^0.20.2",
     "pg": "^8.23.0",
@@ -81,6 +82,7 @@
   },
   "devDependencies": {
     "@types/node": "^26.6.3",
+    "@types/nodemailer": "^8.0.2",
     "@types/pdfkit": "^0.17.6",
     "@types/pg": "^8.23.1",
     "axe-core": "^4.14.0",

package/public/app.css

@@ -265,6 +265,9 @@ details.menu > summary::-webkit-details-marker { display: none; }
 .region-toolbar { display: flex; justify-content: flex-end; margin-bottom: 0.75rem; }
 .region-static p:first-child { margin-top: 0; }
 .region-static p:last-child { margin-bottom: 0; }
+/* (078) URL region: the framed page fills the region's width; its height is a class per region (PageCss) */
+.url-frame { display: block; width: 100%; border: 1px solid var(--border, #d0d7de); border-radius: 6px; background: var(--surface, #fff); }
+.url-open { margin: 0.5rem 0 0; font-size: 0.875rem; }
 .columns { display: grid; grid-template-columns: repeat(auto-fit, minmax(min(100%, 420px), 1fr)); gap: 1rem; margin-top: 1rem; }
 .columns .region { margin: 0; }
 
@@ -1416,6 +1419,12 @@ td.tc-cell { overflow-wrap: anywhere; }
 
 .qr { display: flex; flex-direction: column; align-items: flex-start; gap: 0.3rem; padding: 0.3rem 0; }
 .qr-code { max-width: 100%; height: auto; border-radius: 4px; }
+/* (086) display image and address items */
+.display-image { padding: 0.3rem 0; }
+.display-image img { max-width: 100%; height: auto; border-radius: 4px; }
+.geocode-places { list-style: none; margin: 0.3rem 0 0; padding: 0.3rem 0; border: 1px solid var(--border); border-radius: 4px; background: var(--surface); }
+.geocode-places li { padding: 0.15rem 0.6rem; }
+.geocode-places .link-button { text-align: start; }
 
 /* ---------- lists (list regions, navigation bar) ---------- */
 .list-links { list-style: none; margin: 0; padding: 0; display: flex; flex-direction: column; gap: 0.1rem; }
@@ -1550,3 +1559,56 @@ dialog.crop-dialog::backdrop { background: rgb(15 20 30 / 55%); }
 .crop-handle { position: absolute; right: -8px; bottom: -8px; width: 16px; height: 16px; border-radius: 50%; background: #fff; border: 2px solid var(--accent); cursor: nwse-resize; }
 .crop-stage { overflow: hidden; }
 .crop-dialog .buttons { display: flex; justify-content: flex-end; gap: 0.5rem; }
+
+/* (079) Developer toolbar: shown to developers with a builder session in the same browser.
+   Fixed at the bottom left, collapsible (a <details>, so it works without JavaScript). */
+.devbar { position: fixed; left: 0.75rem; bottom: 0.75rem; z-index: 900; max-width: calc(100vw - 1.5rem);
+  background: #1b2330; color: #fff; border-radius: var(--radius); box-shadow: 0 4px 16px rgb(0 0 0 / 25%); font-size: 0.8125rem; }
+.devbar summary { cursor: pointer; padding: 0.4rem 0.75rem; font-weight: 600; list-style: none; }
+.devbar summary::-webkit-details-marker { display: none; }
+.devbar summary::before { content: '▸ '; }
+.devbar[open] summary::before { content: '▾ '; }
+.devbar ul { display: flex; flex-wrap: wrap; align-items: center; gap: 0.25rem 0.75rem; list-style: none; margin: 0; padding: 0 0.75rem 0.5rem; }
+.devbar a { color: #9cc8ff; }
+.devbar a:focus-visible, .devbar button:focus-visible, .devbar select:focus-visible { outline: 2px solid #9cc8ff; outline-offset: 2px; }
+.devbar-debug { display: flex; align-items: center; gap: 0.35rem; margin: 0; }
+.devbar-debug select, .devbar-debug button { font: inherit; font-size: 0.8125rem; padding: 0.1rem 0.3rem; border-radius: 4px; border: 1px solid #5e6a7a; background: #2b3340; color: #fff; }
+.devbar-debug button { cursor: pointer; }
+.devbar-page .t-main { max-width: 72rem; margin: 0 auto; padding: 1rem; }
+.devbar-facts { display: grid; grid-template-columns: max-content 1fr; gap: 0.25rem 1rem; }
+.devbar-facts dd { margin: 0; overflow-wrap: anywhere; }
+.devbar-session code { overflow-wrap: anywhere; }
+@media print { .devbar { display: none; } }
+
+/* (080) Search region: one field, results grouped per search configuration */
+.search-form { margin-bottom: 1rem; }
+.search-group + .search-group { margin-top: 1rem; }
+.search-group h3 { font-size: 0.875rem; text-transform: uppercase; letter-spacing: 0.04em; color: var(--muted); margin: 0 0 0.4rem; }
+.search-hits { list-style: none; margin: 0; padding: 0; border: 1px solid var(--border); border-radius: var(--radius); }
+.search-hits li + li { border-top: 1px solid var(--border); }
+.search-hit { display: flex; align-items: flex-start; gap: 0.75rem; padding: 0.6rem 0.8rem; color: inherit; text-decoration: none; }
+a.search-hit:hover, a.search-hit:focus-visible { background: var(--accent-soft); }
+.search-icon { flex: none; color: var(--accent); }
+.search-text { display: flex; flex-direction: column; gap: 0.1rem; min-width: 0; flex: 1; overflow-wrap: anywhere; }
+.search-title { font-weight: 600; }
+.search-subtitle, .search-description { color: var(--muted); font-size: 0.875rem; }
+.search-hit mark { background: #fff3a3; color: inherit; border-radius: 2px; padding: 0 1px; }
+:root[data-theme="dark"] .search-hit mark { background: #6b5a00; }
+@media (prefers-color-scheme: dark) { :root:not([data-theme="light"]) .search-hit mark { background: #6b5a00; } }
+.search-hit .badge-pill { flex: none; }
+.search-more, .search-empty { margin: 0.4rem 0 0; }
+
+/* (084) Feedback: the users' page and the builder's list */
+.feedback-form .choices { display: flex; flex-wrap: wrap; gap: 0.5rem 1rem; }
+.feedback-list, .feedback-admin { list-style: none; margin: 0; padding: 0; }
+.feedback-list > li, .feedback-admin > li { border-top: 1px solid var(--border); padding: 0.75rem 0; }
+.feedback-list > li:first-child, .feedback-admin > li:first-child { border-top: 0; }
+.feedback-meta { display: flex; flex-wrap: wrap; align-items: center; gap: 0.35rem; overflow-wrap: anywhere; }
+.feedback-body { white-space: pre-wrap; overflow-wrap: anywhere; margin: 0.4rem 0; }
+.feedback-response { background: var(--surface-2); border-radius: var(--radius); padding: 0.5rem 0.75rem; }
+.feedback-response p { white-space: pre-wrap; overflow-wrap: anywhere; margin: 0.25rem 0 0; }
+
+/* (085) Session timeout warning */
+.session-dialog { max-width: min(28rem, calc(100vw - 2rem)); border: 1px solid var(--border); border-radius: var(--radius); background: var(--surface); color: var(--text); padding: 1.25rem; }
+.session-dialog::backdrop { background: rgb(0 0 0 / 40%); }
+.session-dialog p { margin: 0 0 1rem; }