pgkiln 0.52.0 → 0.54.0

package/docs/guide/06-processing.md

@@ -781,7 +781,12 @@ Microsoft retires basic authentication (a password) for SMTP in Exchange Online:
 or the Graph provider. Secrets are stored encrypted with `PGKILN_SECRET_KEY`, are write-only in the
 builder, never exported and never readable by applications. Each service lists the **From
 addresses** it may send as (an address, or `@example.com` for a whole domain); an administrator
-chooses each application's service, its From address and an optional **limit per day**.
+chooses each application's service, its From address and an optional **limit per day**. A
+workspace's administrators can also set up the [workspace's own mail
+service](03-builder.md#a-workspaces-own-mail-service) (sprint 118): the workspace's applications that
+an administrator gave no service send through it, with its default From address. Administration →
+[Mail queue](03-builder.md#mail-queue) shows the delivery per hour and per application, the slowest
+provider calls and the failures with the provider's answer, with Retry and Purge.
 
 **How mail is sent.** `meta.send_mail` and the others only *queue* the mail, in the caller's
 transaction: a transaction that rolls back sends nothing. After the commit, the server sends it at

package/docs/guide/08-security.md

@@ -540,6 +540,61 @@ quoted with `escapeIdentifier`, every value is checked (dates, numbers, schema n
 The page is for administrators only (others get 403), every change needs the CSRF token, and pgkiln's own roles can't
 be changed, dropped or granted from it, so the page can't take pgkiln's own connections away.
 
+## Data security per table: rows, columns and values
+
+(sprint 119) PostgreSQL has row level security but no column masking, so pgkiln puts a table's security in three
+layers, all ordinary database objects, and shows them on one page: **SQL Workshop → Object Browser → a table →
+Security** (also *Security…* in the table's ⋯ menu). It is pgkiln's answer to APEX 26.2's Deep Data Security.
+
+- **Rows**: the table's row level security policies (above), listed with a link to Table Properties to switch row
+  level security on and to *Add policy*.
+- **Columns**: a matrix of **database roles × columns** with *read* and *update* per cell. The rows are the roles
+  that have privileges on the table and the database roles of the workspace's applications (with the applications
+  that run as them). Apply writes `GRANT` / `REVOKE SELECT (c, …)` and `UPDATE (c, …)`. A column a role may not read
+  is refused by PostgreSQL ("permission denied") whoever sends the query. The table's owner, superusers and roles that
+  bypass row level security are listed apart: column privileges can't restrict them.
+- **Values**: masked columns per **application role** (`meta.has_role()` of the signed-in user). A column's mask is
+  *empty (null)*, `***` or `***` plus the last four characters; tick the application roles that see the real value,
+  and *Everyone else* for users with none of the listed roles. The masks live in a **masking view** next to the table
+  (default name `<table>_masked`):
+
+  ```sql
+  create view sales.orders_masked with (security_barrier) as
+  select t.id, t.customer,
+         case when (select meta.has_role('manager')) then t.amount end as amount,
+         case when false then t.iban::text else '***' || right(t.iban::text, 4) end as iban
+    from sales.orders t;
+  ```
+
+  The view is owned by a role per schema, `<schema>_masking` (nologin), which pgkiln creates the first time. That
+  role is no owner, superuser or role that bypasses row level security (Apply checks it), so the table's policies
+  still apply inside the view; and it is a member of the database roles that read the table, so policies written
+  `to <role>` apply as well. The configuration is kept in the view's comment, so it travels with `pg_dump`,
+  Generate DDL and the change log; there is no `meta` table for it.
+
+**Preview SQL** shows the statements, **Apply** runs them in one transaction (and records a change set in the
+Change Log), **Open in the worksheet** puts them there. Nothing is changed when one statement fails.
+
+**The mask holds only where the view is read.** As long as a role may still read the raw column on the table, its
+queries on the table see the value; the preview warns about each such column. Point the application's pages,
+REST handlers and AI tools at the view, then untick *read* of the masked columns for the role, and the value is
+masked everywhere that role connects.
+
+Every client meets the same rules because they all run as the application's database role with the same identity:
+
+| Client | Runs as | `meta.app_user()` / `meta.has_role()` from |
+|---|---|---|
+| Pages, processes, dynamic actions, AI assistant and AI agent tools | the application's role (`appTx`) | the session |
+| REST module handlers, AutoREST | the application's role | the bearer token (its user, the user's roles) |
+| The MCP server's `run_query` with `alias` (and `user`) | the application's role | the user's roles in the application ([chapter 20](20-ai-agents.md#safety)) |
+| psql, other tools | whatever role they log in as | — (only grants and policies apply) |
+
+Policies and masks that use `meta.has_role()` can be combined: with a policy that shows a manager the rows of their
+department, and `amount` masked for everyone but `manager`, a clerk reads their own rows with an empty amount.
+Policies written per database role (`to sales_app`) apply to the masking role for every role it is a member of, so
+prefer policies on `meta.app_user()` / `meta.has_role()` on tables with a masking view. The HR example's page 48
+*Salaries (masked)* reads `hr.emp_masked` (`examples/hr/hr_70_data_security.sql`).
+
 ## Session state protection
 
 - **URL items**: on pages with protection *Arguments must have checksum* (the default), item

package/docs/guide/09-reference.md

@@ -81,7 +81,9 @@ select meta.web_request_source('EXCHANGE', '{"currency": "EUR"}');
   must be on `PGKILN_REST_ALLOWED_HOSTS` (unset: no calls), private and loopback addresses are refused
   when the connection is made unless the host is in `PGKILN_REST_PRIVATE_HOSTS`, redirects (at most 3)
   go through the same checks, the response is cut off at `PGKILN_REST_MAX_BYTES` (default 5 MB) and
-  the time limit is 1–60 seconds.
+  the time limit is 1–60 seconds. A workspace's [network access list](03-builder.md#network-access)
+  (sprint 118) narrows the hosts for its applications: a refused request ends with `status` `error`
+  and the reason in `message`, and is logged (debug log, Refused calls).
 - **Web credentials** are named, never passed: `p_credential => 'NAME'` signs the request with a
   credential of the current application (basic, bearer, header, OAuth2), and only for the URLs it is
   valid for. The secret is decrypted by the server for the request only and is never stored with it

package/docs/guide/11-from-apex.md

@@ -65,6 +65,7 @@ What's missing is listed in the [feature parity matrix](../apex-feature-parity.m
 | Automatic Time Zone | Settings → Globalization → Time zone and Automatic time zone; My account → Time zone ([chapter 14](14-globalization.md#time-zones)) |
 | Universal Theme's default style (26.1: *Iris*) | Base style *Iris* (the default for new applications), *Lavender* or *Standard* ([chapter 14](14-globalization.md#base-styles-iris-lavender-and-standard)) |
 | Theme styles, *Enable End Users to Choose Theme Style* | Theme style (automatic/light/dark) and *Users may choose light or dark*; Theme Roller style variants with *Users may choose a style* ([chapter 14](14-globalization.md#style-variants-theme-roller)) |
+| Universal Theme 26.2: *Pillar Light* / *Pillar Dark*, Theme Roller's *Header Pillar Strip*, `u-color-*-subtle` | Theme Roller → *Navigation appearance* and *Header strip colour* (per application or style), the same utility classes ([chapter 14](14-globalization.md#navigation-appearances-pillar-light-and-pillar-dark)) |
 | Template Options (regions, buttons) | *Template options* in the Page Designer: CSS classes from a fixed list ([chapter 4](04-pages-and-regions.md#template-options)) |
 | ORDS | Not needed to serve apps; REST APIs with PostgREST, see [below](#ords-and-postgrest) |
 | Export `f123.sql` / APEXlang | `meta.export_app('alias')` (JSON) |

package/docs/guide/12-development.md

@@ -10,6 +10,7 @@ db/
   seed/*.sql               the HR sample (not for production)
 examples/                  example applications as SQL (the tutorial)
 examples/plugins/          plug-in files (template components) to import
+examples/gallery/          the App Gallery: gallery.json, starters/ and utilities/ (blueprints), samples/ (single-file sample apps)
 scripts/migrate.ts         migration/seed runner (src/migrate.ts does the work)
 website/                   the website pgkiln.vargar.eu (VitePress): landing page + this guide, synced from docs/ at build time;
                            cd website && npm install && npm run dev; scripts/deploy.sh publishes it (see website/deploy/)
@@ -42,7 +43,8 @@ src/
                            merge into the main application or refresh the copy, both through cli/replace.ts
   cli/                     the command line: main.ts (commands, help, exit codes), apps.ts (connect, export,
                            read, import), files.ts (directories, zip), diff.ts, replace.ts (import --replace in place),
-                           mcp.ts (`pgkiln mcp`: the MCP server for AI coding agents, chapter 20)
+                           mcp.ts (`pgkiln mcp`: the MCP server for AI coding agents, chapter 20), only.ts (sprint 116:
+                           `import --replace --only pages/12`, the named files merged over the application's current export)
   app.ts / server.ts       Fastify setup / entry point
   db.ts                    the owner and shared runtime pools, `runtime` (the current scope's: runtimeScope), appTx() (SET LOCAL ROLE + pgkiln.* settings, NOTICEs to the debug log), savepoints
   workspace-db.ts          isolated workspaces (090): the isolated applications (cached 5 s), a pool per workspace login (passwords from
@@ -95,6 +97,9 @@ src/
                            objects, type reporting, roles viewer/editor/administrator as schemes EDITOR and ADMIN, page 1 a Data
                            Reporter), reportingApps(), reportingAppCount() (meta.reporting_app_count, for the workspace home)
   tabledef.ts              (sprint 95) a table as a definition: readTable(), checkTable(), tableSql() (CREATE, or ALTER from the catalog's version)
+  datasec.ts               (sprint 119, WS-13) data security per table: readSecurity() (policies, column privileges per role, the
+                           masking view and its configuration in the view comment), checkSecurity(), securitySql() (GRANT / REVOKE,
+                           the masking view owned by <schema>_masking); the page is builder/data-security.ts
   sqlformat.ts             (sprint 93) formatSql(): the worksheet's Format (clauses per line, keyword case; strings and comments kept)
   sqlplan.ts               (sprint 92) EXPLAIN (FORMAT JSON) as a tree: parsePlan() (self time, slowest step, misestimates), planText()
   quicksql.ts              Quick SQL: shorthand parser and PostgreSQL DDL generator (unit tested)
@@ -110,7 +115,12 @@ src/
   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
+  webclient.ts             outgoing HTTP to web services: allow-list, address checks at connect time (SSRF), redirects, limits;
+                           (sprint 118) a request's scope (OutboundScope): the workspace's network access list, checked on every hop
+                           (checkUrl/scopeProblem), refusals reported to the scope
+  network-acl.ts           (sprint 118, WS-9) workspace network access lists (meta.workspace.network_*): scopeForApp/scopeForWorkspace
+                           (no cache), parseHostList, recordRefusal/purgeRefusals (meta.network_refusal, 7 days), mailHostAddress
+                           (a workspace mail service's SMTP host: both lists, resolved once, the checked address connected to)
   datapump.ts              (sprint 103, DA-16) Schema Export / Import jobs (meta.dump_job): findTools (pg_dump/pg_restore ≥ the
                            server's major), startExport (pg_dump, argument array, PGPASSWORD), readToc/parseToc (pg_restore --list),
                            startImport (pg_restore -f - run in one transaction between schema renames; data-only in FK order),
@@ -137,7 +147,10 @@ src/
                            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)
+                           send, retry after 1/4/16/64 minutes, purge after 30 days; the NOTIFY pgkiln_mail listener);
+                           (sprint 118) the service of meta.mail_service_for_app (the app's, else its workspace's own), each attempt's
+                           provider and duration, serviceSettings()/verifyService(): a workspace service's checks (no base or token URL,
+                           its SMTP host through network-acl.ts mailHostAddress)
   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
@@ -164,7 +177,8 @@ src/
     shortcuts.ts           (103) "NAME" shortcuts in static content, help texts and confirm messages
     render.ts              page chrome (nav, breadcrumb), dynamic action JSON, theme (the page's nonce'd <style>, light/dark and style switches)
     styles.ts              base styles (BASE_STYLES: Iris, Lavender, Standard; baseStyleOf → html data-style), Theme Roller style variants: fixed lists (fonts, sizes, corners), parseStyle/appStyles checks, the request's
-                           style (user choice, default), themeCss() (only hex values and constants reach the CSS)
+                           style (user choice, default), themeCss() (only hex values and constants reach the CSS); (sprint 117) NAV_APPEARANCES
+                           (Pillar Light / Dark), navAppearance() → the <body> classes nav-pillar-*, the header strip (--strip)
     template-options.ts    template options: the fixed CSS class list per region and button, templateClasses() (unknown values ignored)
     regions.ts             region shell + chart (drill-down links, gauge settings)/cards/dynamic dispatch with row limits, lazy placeholder and cache, buttons (menu buttons, badges; (124) menu entries {action} → data-menu-entry for menu_entry dynamic actions)
     report.ts, report-views.ts (group by, pivot, chart), compute.ts (computed column expressions), grid.ts (aggregates, row actions, Actions menu, single row view, layoutFromForm), grid-layout.ts (column layouts: clean, arrange, per user), master-detail.ts (signed master row selection, details), facets.ts (facetChart: a facet's counts as a chart, sprint 65), items.ts
@@ -253,7 +267,10 @@ src/
     wizards.ts             create page wizards: step 2 forms per page type (defaults from meta.wizard_defaults), POST → meta.generate_page
                            (the generators are PL/pgSQL in migration 047: catalog, defaults, form/cards/calendar/chart/map/facets/master-detail)
     home.ts                App Builder home at /builder/apps and /builder (tiles, applications report/cards, Recent; /builder redirects
-                           to the Workspace home when meta.workspace.builder_home = 'home'), Create, Import, Dashboard, Utilities
+                           to the Workspace home when meta.workspace.builder_home = 'home'), Create, Import, Dashboard, Utilities;
+                           (116) Updated by, working copies and the application lock in the report and the cards
+    app-updates.ts         (sprint 116, migration 125) who changed an application last: developer() notes a builder POST under
+                           /apps/:id or /pages/:pid (or a Create / Import), an onSend hook records a success in meta.app_change
     workspace-home.ts      (sprint 109, migration 119) the Workspace home /builder/home, opened after sign-in: tool cards (Data Reporter
                            when GET /builder/reporter exists), workspace message edited in place (workspaceAdmin), Summary, Top
                            applications / users / developers over meta.developer.home_timeframe, System message (src/release-check.ts),
@@ -286,7 +303,15 @@ src/
                            (Workspace home). Every id from a request is looked up in the current workspace
     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)
+                           applications with From and daily limit, test) and Applications → Activity → Mail (retry, cancel);
+                           serviceForm/formValues/runCheck shared with workspace-mail.ts (sprint 118)
+    mail-queue.ts          (sprint 118, WS-9) Administration → Mail queue (/builder/mail-queue): queueScope (administrators: all or
+                           ?ws=; workspace administrators: the current workspace), figures, per hour, per workspace / application,
+                           slowest provider calls, failures; Retry / Purge one or all failed, scope checked again per mail
+    network-access.ts      (sprint 118, WS-9) Administration → Network access (/builder/network): the installation's list, a workspace's
+                           list (workspaceAdmin), Check a URL (nothing called), the workspaces (administrators), refused calls
+    workspace-mail.ts      (sprint 118, WS-9) a workspace's own mail service (/builder/workspaces/:id/mail, WORKSPACE_<id>): its
+                           administrators only, write-only secret, checks through mail.ts runCheck with the workspace's guard
     shared.ts              Shared Components and access control
     designer.ts            page designer: component tree (with computations and branches), layout canvas and gallery, property editor, toolbar;
                            (sprint 86) GET /builder/apps/:app/pages/:no, /builder/pages/:id redirects browsers there (designerUrl in ui.ts)
@@ -304,6 +329,7 @@ src/
     object-browser.ts      (sprint 75) the Object Browser: objects by type, system objects hidden, a table in tabs, column actions as SQL to review
     table-editor.ts        (sprint 95) Table Properties: GET/POST /sql/objects/table (create, edit ?o=, ?template=), fromForm(), Preview / Apply
                            (one transaction) / Open in the worksheet
+    data-security.ts       (sprint 119) a table's Security: GET/POST /sql/objects/security?o= (policies, roles × columns, masks), Preview / Apply
     object-actions.ts      (sprint 94) an object's ⋯ menu (objectMenu) in the worksheet and the Object Browser: Quick DDL (objectDdl), Drop with
                            dependents, Add index / trigger / policy as drafts; GET /sql/objects/action, /sql/objects/panel (Open in a panel)
     data-modeler.ts        (sprint 98) SQL Workshop → Data Modeler: /sql/modeler (diagrams, meta.sql_diagram, 111), /:id (SVG), /:id/objects, /layout,
@@ -348,7 +374,8 @@ src/
     ldap.ts                Users → LDAP directories
     documents.ts           document template preview (Shared Components)
     pwa.ts                 Settings → Progressive Web App (icon upload)
-    themeroller.ts         Settings → Theme Roller: style variants (add, edit, rename, delete), default style, users may choose
+    themeroller.ts         Settings → Theme Roller: style variants (add, edit, rename, delete), default style, users may choose;
+                           (sprint 117) navigation appearance and header strip colours (application and per style), the preview's menu
     subscriptions.ts       Shared Components → Subscriptions: subscribe, refresh, unsubscribe, subscribers and publish; the note under a component
     reporter.ts            page designer: Data Reporter settings (sources: table or view, offered columns, labels, masks; sharing;
                            (sprint 110) a dataset as a source, who may edit, who may moderate, publishing)
@@ -374,8 +401,10 @@ src/
     templates.ts           template components: preview, plug-in export/import, region settings, report column templates
     code-editor.ts         code fields (data-code marks), /builder/code/completions (scoped to the app's role), /builder/code/check
     instance.ts            Workspace utilities → Instance settings (src/instance.ts: session and sign-in settings, configuration overview)
-    gallery.ts             the App Gallery (sprint 61): examples/gallery/gallery.json, sample apps (administrators, migrate --example),
-                           starter apps (blueprints → openBlueprint's review), custom apps (the workspace's boilerplates)
+    gallery.ts             the App Gallery (sprint 61, 120): examples/gallery/gallery.json, sample apps (administrators: migrate --example,
+                           or one SQL file of examples/ or examples/gallery/samples/ in one transaction), starter and utility apps
+                           (blueprints of starters/ and utilities/ → openBlueprint's review), custom apps (the workspace's boilerplates);
+                           four tabs with counts, ?q= search
     app-groups.ts          application groups (092): a workspace's groups, a group per application (the App Builder home filters)
     cross-app.ts           Cross Application Reports (sprint 61): REPORTS (one SQL per topic over the workspace's applications)
     workspaces.ts          workspaces (064): loadWorkspaces/appAllowed (checked in ui.ts developer() for every /apps/:id and /pages/:pid
@@ -396,7 +425,8 @@ src/
                            into agents and regions), toolCallTable() (Activity → AI usage → Tool calls), agentOptions()
     supporting.ts          supporting objects: review page, running the install/upgrade/deinstall scripts as the app's role in one transaction
 public/
-  app.css                  theme (light/dark, responsive; --font, --font-size, --radius for style variants; template option classes to-*)
+  app.css                  theme (light/dark, responsive; --font, --font-size, --radius for style variants; template option classes to-*;
+                           (sprint 117) navigation tree states, RTL via logical properties, body.nav-pillar-*, u-color-*-subtle, the busy bar)
   app.js                   client runtime: dialogs (dialog_closed actions), popup LOVs (sprint 115: the next page loads on scroll through an
                            IntersectionObserver, ‹/More without one), dynamic actions (focus, classes, messages; sprint 115: wait_popup /
                            remove_wait_popup as a modal <dialog class="wait-popup">, pgkiln.waitPopup(), the menu_entry event), grids (add/duplicate rows, master-detail refresh, move/resize columns, copy/paste of cell ranges), menus, lazy regions, maps (Leaflet layers, marker clusters, heat layer, layer legend, area/distance filter) (no inline JS)
@@ -455,6 +485,8 @@ test/
   page-logic.test.ts       download, chain (background jobs) and workflow processes, function/app branches, dialog_closed (HR page 28)
   code-editor.test.ts      code editor: completions scoped to the app's role, the check, marked fields
   builder-home.test.ts     App Builder home: search, sort, views, Recent, Create/Import pages, dashboard, utilities
+  app-list.test.ts         (116) the App Builder list's Updated by, working copies and lock; what counts as a change
+  import-only.test.ts      (116) pgkiln import --replace --only: a page or component file, refusals
   charts.test.ts           chart markup per kind (geometry as classes), gauges, Gantt time axis and dependencies, pyramid, polar, range, box plot, stock, drill-down links
   calendar.test.ts         calendar views, create links, moving events (pure and over HTTP)
   rest-sources.test.ts     REST data sources, web credentials, SSRF checks, invoke_api (mock service + HR page 23)
@@ -473,8 +505,14 @@ test/
   builder-parity.test.ts   lists (HR page 31), page and application locks, comments, developers, supporting objects
   page-wizards.test.ts     create page wizards: catalog defaults, every page type generated and rendered, refusals, the builder steps
   theme-styles.test.ts     Theme Roller style variants (checks, CSS, user choice per app, builder page), template options, base style Iris
+  theme-pillar.test.ts     (sprint 117) Pillar Light / Dark appearances and the header strip: checks, CSS, runtime classes, Theme Roller, export
   workspaces.test.ts       workspaces (064): Default, administrators' pages, current workspace, refused apps, imports and copies
-  gallery.test.ts          the App Gallery: every starter created from its review with all its pages rendering; sample apps (admins)
+  mail-network.test.ts     (sprint 118) network access lists (page process refused and logged in debug, narrowing only, redirects,
+                           the page), a workspace's mail service (sending, SMTP host on the list), the Mail queue (yesterday's
+                           SMTP failure, Retry, Purge, counts, scope)
+  gallery.test.ts          the App Gallery: every starter and utility created from its review and every sample app installed, with all
+                           their pages rendering; sample apps (admins), the search, a failing script leaves nothing
+  gallery-samples.ts       the gallery's shipped apps for the tests: SAMPLES (schema and role of each script), BLUEPRINTS, drop/install
   builder-apex-screens.test.ts sprint 61: sign-in with a workspace, message and banner, utilization, SQL Workshop home, groups, reports
   workspace-isolation.test.ts isolated workspaces (090): logins, RLS on meta, app_id, roles, SQL Workshop, scripts, imports
   ai.test.ts               AI services: Generate text with AI (text, structured outputs, errors, limits, keys), its dynamic action,
@@ -493,6 +531,9 @@ test/
   ai-mock.ts               a local mock of the Claude Messages API (SSE stream) and OpenAI Chat Completions
   helpers.ts               a cookie-keeping test browser
   e2e/responsive.test.ts   browser tests at phone/tablet/desktop widths (Playwright)
+  e2e/gallery.test.ts      (sprint 120) the gallery's sample apps: every page at 4 widths, CSP, axe; dynamic actions; the four tabs at 390 px
+  e2e/admin-mail-network.test.ts (sprint 118) Mail queue, Network access and a workspace's mail service at 390 px without JavaScript
+  e2e/pillar.test.ts       (sprint 117) Pillar appearances: axe in light and dark, subtle colours, current vs parent entry, Arabic RTL, 390 px, preview
   e2e/code-editor.test.ts  the code editor in a browser: highlighting, keys, suggestions, touch, screen readers, syntax colours at AA in both themes (sprint 108)
   e2e/data-modeler.test.ts (sprint 98) the Data Modeler in a browser: drag, save, reload, undo/redo, zoom, mini-map, exports, phone
   e2e/worksheet.test.ts    (sprint 91) the SQL Worksheet in a browser: run keys, tabs, navigator, drag and drop, splitters, phone, no JavaScript;

package/docs/guide/14-globalization.md

@@ -245,6 +245,8 @@ application. The base style and colours under Settings → Theme are the *Standa
 |---|---|
 | Accent colour, header colour | `#rrggbb` (or "as the base"), for the light theme |
 | Accent and header colour in dark mode | `#rrggbb` (or the base style's dark palette), for the dark theme; choose light colours (text on the accent is dark there) |
+| Navigation appearance | *As the application*, *Default* (the base style's header and menu), *Pillar Light* or *Pillar Dark*, see [below](#navigation-appearances-pillar-light-and-pillar-dark) |
+| Header strip colour, also for dark mode | `#rrggbb` or an item reference (else the application's strip, else the accent) |
 | Font | *System* (default), *Humanist sans*, *Geometric sans*, *Serif*, *Rounded*, *Monospace* (font stacks of fonts on the device; nothing is downloaded) |
 | Font size | 14, 15 (default), 16 or 17 px |
 | Corners | Square, 4, 8 (default) or 14 px, for regions, buttons and fields |
@@ -276,10 +278,56 @@ per tenant, environment or user group:
   a style themselves get the first style (in the list's order) whose condition holds, else the
   default style. The condition runs as the application's database role in the page's transaction;
   an error counts as *false* and is written to the [debug messages](06-processing.md#debug-messages).
-- **Dynamic colours.** Instead of a picked colour, any of a style's four colours may be an item
+- **Dynamic colours.** Instead of a picked colour, any of a style's colours may be an item
   reference such as `&APP_BRAND_COLOUR.`: the item's value in session state (set by a computation,
   an application process after login, a form…), used when it is a `#rrggbb` colour and ignored
   otherwise, so a stored value can never become anything but a colour in the CSS.
 
 Together: one style *Tenant brand* with condition `:APP_BRAND_COLOUR is not null` and accent
 `&APP_BRAND_COLOUR.` gives each tenant its colour from a table, read once after sign-in.
+
+## Navigation appearances: Pillar Light and Pillar Dark
+
+APEX 26.2's Universal Theme adds *Pillar* appearances for the header and the navigation menu. In pgkiln:
+**Theme Roller → Navigation appearance** (for the whole application) or a style's own *Navigation appearance*:
+
+| Appearance | Look |
+|---|---|
+| **Default** | The base style's header and menu (Iris: a dark header and menu; Standard: a navy header and a white menu) |
+| **Pillar Light** | Header and menu on the page's own light surfaces (in dark mode its dark ones), a line under the header |
+| **Pillar Dark** | Header and menu as one dark column in the header colour; in dark mode a darker one |
+
+Both have a **header pillar strip** across the top of the header, in the *Header strip colour* (light and dark mode,
+on the Theme Roller page or per style; a style may take it from an item, like its other colours), else the accent,
+and show the **current page as a filled pill** in the accent. Pillar Light replaces the header colour with the page's
+surface, so the strip carries the brand colour. A style's appearance wins over the application's; *Default* in a style
+switches a pillar appearance off. The appearance works with a side and a top menu, and on tablets and phones in the
+drawer. It is stored as `"appearance"`, `"strip"` and `"strip_dark"` in `meta.app.theme` (and in each style), so it
+travels with export and import; only the two keys of the list and `#rrggbb` colours reach the page (classes
+`nav-pillar nav-pillar-light` / `nav-pillar-dark` on `<body>`, `--strip` in the nonce'd `<style>`).
+
+### The navigation tree
+
+In every appearance (sprint 117) the menu tells three states apart: the **current page** is filled, in the accent,
+with a bar at the start of the entry (a pill in the pillar appearances); its **parent entries** (the trail) are bold
+with an accent icon but not filled, and the open parent's sub-menu hangs on an accent guide line; the **selected**
+entry (keyboard focus) has a ring inside the menu. A page that is not in the menu marks its nearest menu ancestor as
+the trail.
+
+### Right to left
+
+Arabic, Hebrew, Persian and Urdu pages (`dir="rtl"`) mirror the chrome: the menu sits on the right, the drawer
+slides in from the right on tablets and phones, the current page's bar, the guide lines and the menu's chevrons turn
+around, menus open from the other side and reflowed report cards are aligned to the start.
+
+### Subtle colour utilities and the processing indicator
+
+The classes `u-color-1-subtle` … `u-color-15-subtle` and `u-color-success-subtle`, `u-color-danger-subtle`,
+`u-color-warning-subtle`, `u-color-info-subtle`, `u-color-neutral-subtle` give an element a tinted background with
+readable text (WCAG AA in light and dark mode, in every base style), for static content, HTML expressions and
+template components, e.g. `<span class="u-color-4-subtle">Approved</span>`.
+
+A region that is busy (a dynamic action, a refresh) is dimmed slightly after 150 ms, so quick answers don't flicker,
+and shows a thin moving bar along its top (a still bar when the device asks for reduced motion); the wait popup's
+spinner is lighter too.
+

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] [--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 import <path> [--alias <alias>] [--replace [--only <file>]…] [--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)); with `--only pages/12` (repeatable) only that page or component file ([below](#importing-one-page-or-component)). `--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 ddl <schema> [--no-comments] [--no-grants] [--out <file>]` | The DDL of a schema's objects, in an order that runs (as SQL Workshop → DDL, [chapter 3](03-builder.md#sql-workshop)) |
 | `pgkiln compare <source> <target> [--script]` | Compares two schemas: `+` only in the source, `-` only in the target, `~` different; exit code 1 when they differ. `--script` writes the script that makes the target like the source (drops commented out); nothing is run |
@@ -210,6 +210,26 @@ pgkiln diff hr apps/hr                           # on the target: what would cha
 pgkiln import apps/hr --replace                  # deploy
 ```
 
+### Importing one page or component
+
+(sprint 116; APEX 26.2: APEXlang file-level import) With `--replace`, `--only` imports just the named files of a
+directory export (or a .zip of one) and leaves the rest of the application as it is in the database:
+
+```sh
+pgkiln import apps/hr --replace --only pages/12                 # page 12 with its regions, items, buttons …
+pgkiln import apps/hr --replace --only shared/lovs/jobs.yaml    # one shared component
+pgkiln import apps/hr --replace --only pages/12 --only shared/lovs   # several: repeat --only
+```
+
+`pages/12` (or just `12`) is page 12's folder whatever its name, so a renamed page still matches; any other value is
+a file or folder path inside the export. A page or file that the directory no longer has is removed from the
+application. How it works: pgkiln exports the application in the directory's style, takes the named files from the
+directory, and imports the result with `--replace` as usual: one transaction, a backup first, `--check` and
+`--dry-run` work the same, and what belongs to the installation is kept. It says how many of the named files differ
+(on standard error). `--only` refuses without `--replace`, for a JSON file, for a path outside the export and for a
+selection that matches nothing in the directory or the application (exit code 2). A component that another file
+refers to by name (a list of values used on a page, say) has to exist after the import, as with any import.
+
 ### Checking before an import
 
 An import doesn't need the application's tables, columns and functions to exist (neither does APEX's):

package/docs/guide/19-rest-data-sources.md

@@ -53,6 +53,16 @@ The checks on every outgoing request (`src/webclient.ts`), against server-side r
 Keep the allow-list as short as you can. `*` lets developers call any public host from the
 server; it never opens private addresses.
 
+**A workspace's network access list** (sprint 118; APEX 26.2 workspace network ACLs) narrows this
+list for one workspace: under Administration → [Network access](03-builder.md#network-access), its
+administrators can limit its applications to some hosts (same entry syntax, without `*`). A call made
+for an application of that workspace must then match the workspace's list *and* the installation's,
+on every redirect hop; the address checks above stay with `PGKILN_REST_PRIVATE_HOSTS` alone, so a
+workspace can never widen what the installation allows. It applies to every path above: REST data
+sources (including write-back, synchronisation and the response cache), `meta.web_request`, invoke
+API, token endpoints, object storage and REST source catalogs. Refusals are logged in the
+application's debug log and listed under *Refused calls*.
+
 **Changing `PGKILN_SECRET_KEY`** makes the stored secrets unreadable: pgkiln then reports that
 the secret must be entered again. Keep the key with your other server secrets, outside the
 database: a database dump alone does not reveal the secrets.
@@ -323,6 +333,8 @@ values, processes and workflow steps refer to sources and credentials by name, s
 
 - Outgoing calls are off until the administrator sets `PGKILN_REST_ALLOWED_HOSTS`; private and
   internal addresses need `PGKILN_REST_PRIVATE_HOSTS` as well.
+- A workspace's [network access list](03-builder.md#network-access) narrows the allow-list for its
+  applications (it can't widen it).
 - Secrets are encrypted with a key outside the database, write-only in the builder, excluded from
   exports and from the runtime role, and never logged. Use **Valid for URLs** so a credential is
   only ever sent to its own service.

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

@@ -52,7 +52,7 @@ directory the agent started the server in (the project).
 | `describe_schema` | schemas with tables, views and functions; or one table with columns, constraints, indexes, RLS policies and triggers | no |
 | `generate_ddl` | the DDL of a schema's objects, in an order that runs: a start for a migration script | no |
 | `compare_schemas` | the differences between two schemas and a script that makes the target like the source (not run) | no |
-| `run_query` | one SQL statement, read-only, rows as JSON | no |
+| `run_query` | one SQL statement, read-only, rows as JSON; with `alias` (and `user`) as that application's role and user | no |
 | `search_docs` | searches this user guide, the parity matrix and SECURITY.md | no |
 | `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 |
@@ -85,7 +85,13 @@ migration scripts, not in the application files (`run_query` can't change them a
   columns whose names contain *password*, *secret*, *token*, *hash* or *api_key* are shown as
   `(hidden)`. That keeps credentials out of the agent's context by accident; it is not an access
   control: the server runs as the owner role, like the command line, and is meant for a
-  developer's own machine. Don't point it at production; deploy with `pgkiln import --replace`
+  developer's own machine.
+- **As an application's user.** (sprint 119) `run_query` with `alias` runs the statement as that application's
+  database role, with `meta.app_id()`, `meta.app_user()` (`user`, default `nobody`) and `meta.has_role()` (the
+  user's roles in the application) set, so grants, column privileges, row level security and masking views apply as
+  on that user's pages ([chapter 8](08-security.md#data-security-per-table-rows-columns-and-values)). Use it to check
+  what a user sees, or let an agent look at data the way the application does. It is no sandbox either: the
+  connection is still the owner's. Don't point it at production; deploy with `pgkiln import --replace`
   from git instead.
 - **Writes** are only `export_app` (files; it refuses a non-empty directory that isn't an export,
   so it can't overwrite your project) and `import_app` (the database, in one transaction). Both are

package/examples/gallery/README.md

@@ -1,13 +1,44 @@
 # App Gallery
 
-The builder's **App Gallery** (`/builder/gallery`) lists what `gallery.json` names:
+The builder's **App Gallery** (`/builder/gallery`) lists what `gallery.json` names, in four tabs:
 
 - `samples`: applications shipped with pgkiln, installed by an administrator: `example` names a directory of
-  `examples/` (installed like `pgkiln migrate --example <name>`), `file` a single SQL file in `examples/`.
-  `alias` is the application they create (an installed one shows Run and Edit).
+  `examples/` (installed like `pgkiln migrate --example <name>`), `file` a single SQL file, in `examples/` (the
+  tutorial, `tasks-app.sql`) or in `samples/` here (`samples/sample-charts.sql`). A file runs in one transaction as the
+  owner, so a failing script leaves nothing behind. `alias` is the application it creates (an installed one shows Run
+  and Edit).
 - `starters`: [blueprints](../../docs/guide/03-builder.md#creating-an-application-from-a-blueprint) in `starters/`.
   Install opens the blueprint's review; the developer creates the application from it.
+- `utilities`: blueprints in `utilities/` of applications a workspace uses (lookup lists, release notes,
+  announcements), installed like starters.
+- Custom apps are not listed here: they are the workspace's boilerplate applications.
 
-Add a starter by writing a blueprint file in `starters/` and an entry in `gallery.json` (a key of lower-case
-letters, digits and `-`, a title, an [icon name](../../docs/guide/09-reference.md#icons) and a description).
-`test/gallery.test.ts` creates every starter and opens all its pages.
+## The sample apps in `samples/`
+
+| File | Application | Shows |
+|---|---|---|
+| `sample-charts.sql` | Sample Charts (`/a/sample-charts`) | the 22 chart types, a page per question, a drill-down to a report |
+| `sample-cards.sql` | Sample Cards | cards with a form, KPI tiles, lists as cards, built-in template components |
+| `sample-calendar.sql` | Sample Calendar | month, week, day and list views, create on click, drag and drop through a function |
+| `sample-grids.sql` | Sample Interactive Grids | an editable grid, select lists, totals, frozen column, row menu, master-detail, views |
+| `sample-dynamic-actions.sql` | Sample Dynamic Actions | show/hide/enable, set value, refresh, messages, wait popup, classes, inline dialog |
+| `sample-reporting.sql` | Sample Reporting | interactive report, faceted search, smart filters, a classic report with column options |
+| `ux-patterns.sql` | UX Pattern Catalog | region templates and options, buttons, items and form layouts, content and page patterns |
+
+Each script creates its own schema (`sample_charts`, …), a role (`app_sample_charts`, …) granted to the runtime, the
+application and one account, **demo** / **demo**. Without the builder:
+`psql "$DATABASE_URL" -1 -f examples/gallery/samples/sample-charts.sql`. To remove one, delete the application in the
+App Builder, then `drop schema sample_charts cascade; drop role app_sample_charts;`.
+
+A sample script follows the pattern of the HR example: plain SQL that inserts `meta.*` rows, using
+`meta.generate_page()` for wizard-made pages and two temporary helpers (`pg_temp.page_id`, `pg_temp.region_id`).
+Every page starts with a text that says how it is made.
+
+## Adding an entry
+
+Add a starter or utility by writing a blueprint file in `starters/` or `utilities/` and an entry in `gallery.json` (a
+key of lower-case letters, digits and `-`, a title, an [icon name](../../docs/guide/09-reference.md#icons) and a
+description). Add a sample by writing a script in `samples/` (no `begin`/`commit`: the gallery runs it in a
+transaction) and an entry with its `alias` and `file`. `test/gallery.test.ts` creates every starter and utility,
+installs every sample and opens all their pages; `test/e2e/gallery.test.ts` checks the samples' pages at four widths,
+for CSP violations and with axe-core.

package/examples/gallery/gallery.json

@@ -3,7 +3,21 @@
     {"key": "hr", "title": "HR Demo", "alias": "hr", "icon": "briefcase", "example": "hr",
      "description": "The showcase of pgkiln on the classic EMP and DEPT tables: reports and forms, an interactive grid, charts, maps, a calendar, faceted search, approvals and workflows, documents, a REST API, translations and a Progressive Web App. Demo accounts king, blake, jones, allen, scott and demo, with the username as password."},
     {"key": "tasks", "title": "Tasks", "alias": "tasks", "icon": "check", "file": "tasks-app.sql",
-     "description": "The tutorial application: a personal task list where every user sees only their own tasks (row level security), with a business rule in PL/pgSQL behind a button. Demo accounts ann and bob (password ann-password, bob-password)."}
+     "description": "The tutorial application: a personal task list where every user sees only their own tasks (row level security), with a business rule in PL/pgSQL behind a button. Demo accounts ann and bob (password ann-password, bob-password)."},
+    {"key": "sample-charts", "title": "Sample Charts", "alias": "sample-charts", "icon": "chart-column", "file": "samples/sample-charts.sql",
+     "description": "All 22 chart types on a page per question (comparing categories, change over time, parts of a whole, relations and spread, plans) and a drill-down from a chart to a report, each page explaining how the query shapes the chart. Demo account demo / demo."},
+    {"key": "sample-cards", "title": "Sample Cards", "alias": "sample-cards", "icon": "layout-grid", "file": "samples/sample-cards.sql",
+     "description": "Cards with a title, subtitle, body, badge and icon that open a form; KPI tiles; lists shown as cards, badges, links and tabs; and the built-in template components (metric cards, media list, badges, avatars). Demo account demo / demo."},
+    {"key": "sample-calendar", "title": "Sample Calendar", "alias": "sample-calendar", "icon": "calendar-days", "file": "samples/sample-calendar.sql",
+     "description": "The calendar region: month, week, day and list views, all-day, timed and multi-day events around today, create on click, drag and drop through a PL/pgSQL function with its own rule, and a calendar filtered by an item. Demo account demo / demo."},
+    {"key": "sample-grids", "title": "Sample Interactive Grids", "alias": "sample-grids", "icon": "table", "file": "samples/sample-grids.sql",
+     "description": "The interactive grid: an editable grid made by the wizard; select lists, required columns, totals, a frozen column, a row menu and a column layout; master-detail grids; and a read-only grid with the single row, group by and chart views. Demo account demo / demo."},
+    {"key": "sample-dynamic-actions", "title": "Sample Dynamic Actions", "alias": "sample-dynamic-actions", "icon": "zap", "file": "samples/sample-dynamic-actions.sql",
+     "description": "Behaviour without JavaScript of your own: show, hide, enable on a condition; values computed on the server; a report refreshed when an item changes; alerts, confirmations, a wait popup, classes, item errors and an inline dialog. Demo account demo / demo."},
+    {"key": "sample-reporting", "title": "Sample Reporting", "alias": "sample-reporting", "icon": "file-text", "file": "samples/sample-reporting.sql",
+     "description": "Reports and the ways to search them: an interactive report with its form, a faceted search, smart filters, and a classic report with column display options, a column template and a link. Demo account demo / demo."},
+    {"key": "ux-patterns", "title": "UX Pattern Catalog", "alias": "ux-patterns", "icon": "palette", "file": "samples/ux-patterns.sql",
+     "description": "The theme's building blocks to copy from: region templates and template options, button styles, item types and form layouts, alerts, badges, colour classes, lists, media lists, timelines, comments, avatars, metric cards, empty states, dialogs, drawers and side columns. Demo account demo / demo."}
   ],
   "starters": [
     {"key": "team-tasks", "title": "Team Tasks", "icon": "layout-grid", "file": "starters/team-tasks.json",
@@ -16,5 +30,13 @@
      "description": "Assets with their tags, locations, owners and purchase data: a faceted search, an editable grid of locations, a chart by category and a dashboard."},
     {"key": "event-registrations", "title": "Event Registrations", "icon": "calendar-days", "file": "starters/event-registrations.json",
      "description": "Events in a calendar and the people who registered for them, with reports, forms and a dashboard."}
+  ],
+  "utilities": [
+    {"key": "lookup-lists", "title": "Lookup Lists", "icon": "list-checks", "file": "utilities/lookup-lists.json",
+     "description": "The lists of values your applications share (priorities, statuses, countries) kept as data: lists and their values in a master-detail page and an editable grid, and how other applications of the workspace use them."},
+    {"key": "release-notes", "title": "Release Notes", "icon": "git-branch", "file": "utilities/release-notes.json",
+     "description": "The releases of your applications and what changed in each (features, fixes, security, breaking changes): reports and forms, releases with their changes, a faceted search of the changes, a release calendar and a dashboard."},
+    {"key": "announcements", "title": "Announcements", "icon": "megaphone", "file": "utilities/announcements.json",
+     "description": "A notice board for the workspace: planned maintenance, outages and new releases with their audience and dates, as cards, a calendar and a dashboard, and the query other applications use to show the current ones."}
   ]
 }