pgkiln 0.83.0 → 0.85.0

package/src/runtime/lists.ts

@@ -28,6 +28,8 @@ export interface ListNode {
   external: boolean;
   icon: string | null;
   badge: string | null;
+  /** (154) the entry's id (a query's id column, else its label): finds its badge again for a live refresh */
+  key: string;
   description: string | null;
   /** the entry's page is the current page */
   current: boolean;
@@ -50,6 +52,8 @@ interface Entry {
   url: string | null;
   icon: string | null;
   badge: string | null;
+  /** (154) a SELECT whose first value is the badge (static entries; wins over badge) */
+  badge_query?: string | null;
   description: string | null;
   condition?: string | null;
   authz?: string | null;
@@ -105,7 +109,7 @@ async function entriesOf(ctx: PageContext, name: string): Promise<Entry[] | null
   }
   const rows = (
     await runtime.query(
-      `select id, parent_id, label, target_page, target_items, target_url, icon, badge, description, condition, authz
+      `select id, parent_id, label, target_page, target_items, target_url, icon, badge, badge_query, description, condition, authz
          from meta.list_entry where app_id = $1 and list_name = $2 and meta.build_option_on(app_id, build_option)
         order by seq, id`,
       [ctx.app.id, name.toUpperCase()],
@@ -113,10 +117,28 @@ async function entriesOf(ctx: PageContext, name: string): Promise<Entry[] | null
   ).rows;
   return rows.map((r) => ({
     id: r.id, parent_id: r.parent_id, label: ctx.locale.tr(r.label), page: r.target_page, items: r.target_items ?? {}, url: r.target_url,
-    icon: r.icon, badge: r.badge, description: r.description ? ctx.locale.tr(r.description) : null, condition: r.condition, authz: r.authz,
+    icon: r.icon, badge: r.badge, badge_query: r.badge_query, description: r.description ? ctx.locale.tr(r.description) : null, condition: r.condition, authz: r.authz,
   }));
 }
 
+/**
+ * (029, 154) A badge from SQL: the first value of the query's first row, run as the application's
+ * role with the page's binds; an error is a page error and no badge. Empty values give no badge.
+ */
+export async function queryBadge(ctx: PageContext, query: string, what: string): Promise<string | null> {
+  const c = ctx.client;
+  if (!c) return null;
+  try {
+    const sql = stripSemicolon(applyBinds(query, bindValues(ctx)));
+    const res = await savepoint(c, () => c.query({ text: sql, rowMode: 'array' }));
+    const v = res.rows[0]?.[0];
+    return v === null || v === undefined ? null : String(v).trim().slice(0, 100) || null;
+  } catch (e) {
+    ctx.errors.page.push(await publicError(ctx, e, what));
+    return null;
+  }
+}
+
 /** The current page and its parent pages (for "in trail"). */
 function trail(ctx: PageContext) {
   const pages = new Set<number>();
@@ -156,7 +178,10 @@ export async function listTree(ctx: PageContext, name: string): Promise<ListNode
       modal: !!e.page && isModal(ctx, e.page),
       external,
       icon: e.icon,
-      badge: e.badge === null ? null : substitute(e.badge, ctx, (x) => x),
+      badge: e.badge_query?.trim()
+        ? await queryBadge(ctx, e.badge_query, `badge of list entry "${e.label}"`)
+        : e.badge === null ? null : substitute(e.badge, ctx, (x) => x),
+      key: String(e.id ?? e.label),
       description: e.description === null ? null : substitute(e.description, ctx, (x) => x),
       current: isCurrent,
       inTrail: isCurrent || (e.page !== null && current.has(e.page)) || children.some((c) => c.inTrail),
@@ -179,15 +204,22 @@ export async function listTree(ctx: PageContext, name: string): Promise<ListNode
 
 const linkAttrs = (n: ListNode, cls?: string) =>
   html`href="${n.href}"${cls ? html` class="${cls}"` : ''}${n.current ? raw(' aria-current="page"') : ''}${n.modal ? raw(' data-dialog') : ''}${n.external ? raw(' rel="noopener noreferrer"') : ''}`;
-const badge = (n: ListNode) => (n.badge !== null ? html` <span class="badge">${n.badge}</span>` : '');
+/**
+ * An entry's badge. live: the prefix of the badge's data-badge key when the application refreshes
+ * badges (154); an empty badge is then a hidden placeholder the refresh can fill.
+ */
+const badge = (n: ListNode, live?: string) =>
+  n.badge !== null
+    ? html` <span class="badge"${live ? html` data-badge="${live}${n.key}"` : ''}>${n.badge}</span>`
+    : live ? html` <span class="badge" data-badge="${live}${n.key}" hidden></span>` : '';
 
 /** Entries as the navigation menu (the same markup as navigation entries). */
-export function navMarkup(nodes: ListNode[], topNav: boolean): Raw[] {
+export function navMarkup(nodes: ListNode[], topNav: boolean, live?: string): Raw[] {
   return nodes.map((n) => {
-    const label = html`${icon(n.icon ?? 'chevron')}<span>${n.label}</span>${badge(n)}`;
+    const label = html`${icon(n.icon ?? 'chevron')}<span>${n.label}</span>${badge(n, live)}`;
     if (n.children.length)
       return html`<li><details${n.inTrail && !topNav ? raw(' open') : ''}><summary class="${n.inTrail ? 'in-trail' : null}">${label}</summary><ul>${
-        n.href ? html`<li><a ${linkAttrs(n)}>${label}</a></li>` : ''}${navMarkup(n.children, topNav)}</ul></details></li>`;
+        n.href ? html`<li><a ${linkAttrs(n)}>${label}</a></li>` : ''}${navMarkup(n.children, topNav, live)}</ul></details></li>`;
     return html`<li><a ${linkAttrs(n, !n.current && n.inTrail ? 'in-trail' : undefined)}>${label}</a></li>`;
   });
 }
@@ -195,13 +227,13 @@ export function navMarkup(nodes: ListNode[], topNav: boolean): Raw[] {
 const hasIcon = (n: ListNode) => isIcon(n.icon);
 
 /** Entries as the navigation bar in the header: links, with a menu for entries with children (labels of entries with an icon hide on small screens). */
-export function navbarMarkup(nodes: ListNode[], label: string): Raw {
+export function navbarMarkup(nodes: ListNode[], label: string, live?: string): Raw {
   if (!nodes.length) return raw('');
   return html`<nav class="t-navbar" aria-label="${label}"><ul>${nodes.map((n) =>
     n.children.length
-      ? html`<li><details class="menu"><summary${hasIcon(n) ? html` class="nb-icon" aria-label="${n.label}"` : ''}>${icon(n.icon)}<span>${n.label}</span>${badge(n)}</summary><div class="menu-panel align-right"><ul class="t-navbar-menu">${
-          [...(n.href ? [n] : []), ...n.children].map((c) => html`<li><a ${linkAttrs(c)}>${icon(c.icon)}<span>${c.label}</span>${badge(c)}</a></li>`)}</ul></div></details></li>`
-      : html`<li><a ${linkAttrs(n, hasIcon(n) ? 'nb-icon' : undefined)}${hasIcon(n) ? html` aria-label="${n.label}"` : ''}>${icon(n.icon)}<span>${n.label}</span>${badge(n)}</a></li>`)}</ul></nav>`;
+      ? html`<li><details class="menu"><summary${hasIcon(n) ? html` class="nb-icon" aria-label="${n.label}"` : ''}>${icon(n.icon)}<span>${n.label}</span>${badge(n, live)}</summary><div class="menu-panel align-right"><ul class="t-navbar-menu">${
+          [...(n.href ? [n] : []), ...n.children].map((c) => html`<li><a ${linkAttrs(c)}>${icon(c.icon)}<span>${c.label}</span>${badge(c, live)}</a></li>`)}</ul></div></details></li>`
+      : html`<li><a ${linkAttrs(n, hasIcon(n) ? 'nb-icon' : undefined)}${hasIcon(n) ? html` aria-label="${n.label}"` : ''}>${icon(n.icon)}<span>${n.label}</span>${badge(n, live)}</a></li>`)}</ul></nav>`;
 }
 
 function linksMarkup(nodes: ListNode[]): Raw {

package/src/runtime/notifications.ts

@@ -0,0 +1,237 @@
+import type { FastifyInstance, FastifyReply } from 'fastify';
+import { appTx, runtime } from '../db.ts';
+import { html, raw, type Raw } from '../html.ts';
+import { icon } from '../icons.ts';
+import { checkPageAccess, computeVisibility, Forbidden } from './authz.ts';
+import { publicError, type PageContext } from './context.ts';
+import { listTree, queryBadge, type ListNode } from './lists.ts';
+import { buttonBadgeKey } from './regions.ts';
+import { chrome, clientTexts } from './render.ts';
+import { safeNext } from './signin.ts';
+import { saveState, takeFlash } from '../session.ts';
+import { loadContext, txContext, type Req } from './routes.ts';
+
+// (sprint 165, migration 154) In-app notifications and live badges (APEX: a notification bell in the
+// header, navigation menu badges, badges refreshed with dynamic actions and JavaScript).
+//
+// Application code adds notifications with meta.notify() or the send_notification process. With
+// meta.app.notifications on, signed-in users get a bell in the header: the number of unread
+// notifications and the newest ones. Opening one (a POST with the session's CSRF token) marks it read
+// and goes to its page (a link signed for the recipient when it was made). /a/<alias>/notifications
+// lists them all. Only the user's own notifications of this application are ever read or changed:
+// every query has the application's id and the session's user name.
+//
+// With meta.app.live_badges_s set, the page asks GET /a/<alias>/<page>/live every so many seconds for
+// the badges of its navigation menu and bar (list entries), of its buttons with a badge query, and for
+// the bell. These requests don't keep an idle session alive (loadContext touch: false).
+
+/** Newest notifications in the bell's menu. */
+const BELL_ROWS = 8;
+/** Notifications on the notifications page. */
+const PAGE_ROWS = 100;
+
+interface Row {
+  id: string;
+  title: string;
+  body: string | null;
+  url: string | null;
+  icon: string | null;
+  created_at: Date | string;
+  read_at: Date | string | null;
+}
+
+const signedIn = (ctx: PageContext) => ctx.app.authentication !== 'none' && ctx.user !== 'nobody';
+/** The bell is shown: notifications on, a signed-in user, a page with the header. */
+export const hasBell = (ctx: PageContext) => !!ctx.app.notifications && signedIn(ctx);
+
+async function rows(ctx: PageContext, limit: number): Promise<Row[]> {
+  return (
+    await runtime.query<Row>(
+      `select id::text, title, body, url, icon, created_at, read_at from meta.notification
+        where app_id = $1 and lower(username) = lower($2) order by id desc limit $3`,
+      [ctx.app.id, ctx.user, limit],
+    )
+  ).rows;
+}
+
+async function unreadCount(ctx: PageContext): Promise<number> {
+  const r = await runtime.one<{ n: number }>(
+    'select count(*)::int as n from meta.notification where app_id = $1 and lower(username) = lower($2) and read_at is null',
+    [ctx.app.id, ctx.user],
+  );
+  return r?.n ?? 0;
+}
+
+const shown = (n: number) => (n > 99 ? '99+' : String(n));
+
+/** A notification's time in the user's language and time zone (the pool gives timestamps as text). */
+function when(ctx: PageContext, value: Date | string) {
+  const d = value instanceof Date ? value : new Date(value);
+  if (Number.isNaN(d.getTime())) return String(value);
+  try {
+    return new Intl.DateTimeFormat(ctx.locale.lang, { dateStyle: 'medium', timeStyle: 'short', timeZone: ctx.locale.timeZone ?? undefined }).format(d);
+  } catch {
+    return d.toISOString().slice(0, 16).replace('T', ' ');
+  }
+}
+
+/** A notification as a button that opens it (a form: it marks the notification read). */
+function entry(ctx: PageContext, r: Row, cls: string): Raw {
+  const t = ctx.locale.t;
+  return html`<li class="${cls}${r.read_at ? '' : ' is-unread'}"><form method="post" action="${ctx.base}/notifications/${r.id}/open">
+      <input type="hidden" name="__csrf" value="${ctx.session.csrf_token}">
+      <button class="t-notification">${icon(r.icon ?? 'bell')}<span class="t-notification-text">
+        <span class="t-notification-title">${r.read_at ? '' : html`<span class="sr-only">${t('notify.unread_one')}: </span>`}${r.title}</span>
+        ${r.body ? html`<span class="t-notification-body">${r.body}</span>` : ''}
+        <span class="t-notification-time">${when(ctx, r.created_at)}</span></span></button>
+    </form></li>`;
+}
+
+/** "Mark all read", back to next. */
+function markAllForm(ctx: PageContext, next: string): Raw {
+  return html`<form method="post" action="${ctx.base}/notifications/read" class="t-bell-read">
+      <input type="hidden" name="__csrf" value="${ctx.session.csrf_token}"><input type="hidden" name="next" value="${next}">
+      <button class="link-button">${icon('check')} ${ctx.locale.t('notify.mark_all_read')}</button></form>`;
+}
+
+/** The bell's menu: the newest notifications, Mark all read, All notifications. */
+async function bellPanel(ctx: PageContext, unread: number): Promise<Raw> {
+  const t = ctx.locale.t;
+  const list = await rows(ctx, BELL_ROWS);
+  return html`<div class="menu-section t-bell-head"><strong>${t('notify.title')}</strong>${unread ? markAllForm(ctx, `${ctx.base}/${ctx.page.page_no}`) : ''}</div>
+    ${list.length ? html`<ul class="t-bell-list">${list.map((r) => entry(ctx, r, 't-bell-entry'))}</ul>` : html`<p class="muted t-bell-none">${t('notify.none')}</p>`}
+    <div class="menu-section"><a href="${ctx.base}/notifications">${icon('arrow-right')} ${t('notify.all')}</a></div>`;
+}
+
+const bellLabel = (ctx: PageContext, unread: number) =>
+  unread ? ctx.locale.t(unread === 1 ? 'notify.bell_one' : 'notify.bell_n', { n: unread }) : ctx.locale.t('notify.title');
+
+/** The bell in the header (empty when the application has no notifications or nobody is signed in). */
+export async function bellMarkup(ctx: PageContext): Promise<Raw | ''> {
+  if (!hasBell(ctx)) return '';
+  const unread = await unreadCount(ctx);
+  return html`<details class="menu t-bell" data-bell>
+      <summary class="icon-button" title="${bellLabel(ctx, unread)}" aria-label="${bellLabel(ctx, unread)}">${icon('bell')}<span class="t-bell-count" data-badge="bell"${unread ? '' : raw(' hidden')}>${unread ? shown(unread) : ''}</span></summary>
+      <div class="menu-panel align-right t-bell-panel" data-bell-panel>${await bellPanel(ctx, unread)}</div>
+    </details>`;
+}
+
+/** Every node of a list tree, depth first. */
+const allNodes = (nodes: ListNode[]): ListNode[] => nodes.flatMap((n) => [n, ...allNodes(n.children)]);
+
+export interface LiveState {
+  /** data-badge key → its text (null: no badge) */
+  badges: Record<string, string | null>;
+  bell: { unread: number; label: string; panel: string } | null;
+}
+
+/** The page's badges now (navigation menu and bar, buttons with a badge query) and the bell. */
+export async function liveState(ctx: PageContext): Promise<LiveState> {
+  const badges: Record<string, string | null> = {};
+  for (const [list, prefix] of [[ctx.app.nav_list, 'n:'], [ctx.app.navbar_list, 'b:']] as const) {
+    if (!list) continue;
+    for (const n of allNodes((await listTree(ctx, list)) ?? [])) badges[`${prefix}${n.key}`] = n.badge;
+  }
+  for (const b of ctx.vis!.buttons.values())
+    if (b.badge_query?.trim() && b.id > 0) badges[buttonBadgeKey(b)] = await queryBadge(ctx, b.badge_query, `badge of button ${b.name}`);
+  return { badges, bell: null };
+}
+
+export async function notificationRoutes(app: FastifyInstance) {
+  /** A signed-in user of an application with notifications on (else a 404). */
+  const context = async (req: Req, reply: FastifyReply) => {
+    const ctx = await loadContext(req, reply, { pageNo: 'home' });
+    if (!ctx) return null;
+    if (!hasBell(ctx)) {
+      reply.code(404).type('text/plain').send('Not found');
+      return null;
+    }
+    return ctx;
+  };
+
+  app.get('/a/:alias/notifications', async (req: Req, reply) => {
+    const ctx = await context(req, reply);
+    if (!ctx) return;
+    const t = ctx.locale.t;
+    const list = await rows(ctx, PAGE_ROWS);
+    const unread = list.some((r) => !r.read_at);
+    const flash = takeFlash(ctx.session);
+    const main = html`<div class="t-titlebar"><h1>${t('notify.title')}</h1></div>
+      <div class="t-content notifications-page">
+        <div class="messages" aria-live="polite">${flash ? html`<div class="alert alert-success" role="status">${flash}</div>` : ''}</div>
+        <section class="region region-standard"><div class="region-body">
+          ${unread ? html`<div class="buttons u-mt0">${markAllForm(ctx, `${ctx.base}/notifications`)}</div>` : ''}
+          ${list.length ? html`<ul class="t-notification-list">${list.map((r) => entry(ctx, r, 't-notification-entry'))}</ul>` : html`<p class="muted">${t('notify.none')}</p>`}
+        </div></section>
+      </div>
+      <script type="application/json" id="pgkiln-meta">${raw(JSON.stringify({ csrf: ctx.session.csrf_token, das: [], texts: clientTexts(ctx) }).replace(/</g, '\\u003c'))}</script>`;
+    ctx.vis = { regions: new Set(), items: new Set(), editable: new Set(), buttons: new Map(), dynamicActions: new Set() };
+    const body = await appTx(txContext(ctx), async (c) => {
+      ctx.client = c;
+      return chrome(ctx, main, t('notify.title'));
+    });
+    await saveState(ctx.session);
+    return reply.header('cache-control', 'private, no-store').type('text/html').send(body);
+  });
+
+  // open a notification: mark it read, go to its page (or the list when it has none)
+  app.post('/a/:alias/notifications/:id/open', async (req: Req, reply) => {
+    const ctx = await context(req, reply);
+    if (!ctx) return;
+    if (req.body?.__csrf !== ctx.session.csrf_token) return reply.redirect(`${ctx.base}/notifications`, 303);
+    const id = /^[1-9][0-9]{0,17}$/.test(String(req.params.id)) ? String(req.params.id) : null;
+    const row = id
+      ? await runtime.one<{ url: string | null }>(
+          `update meta.notification set read_at = coalesce(read_at, now())
+            where id = $1 and app_id = $2 and lower(username) = lower($3) returning url`,
+          [id, ctx.app.id, ctx.user],
+        )
+      : null;
+    if (!row) {
+      ctx.session.state.__FLASH = ctx.locale.t('notify.gone');
+      await saveState(ctx.session);
+      return reply.redirect(`${ctx.base}/notifications`, 303);
+    }
+    // the link was made under the application's alias then; it goes to the same page now
+    const rest = row.url?.replace(/^\/a\/[^/]+\//, '');
+    return reply.redirect(rest ? `${ctx.base}/${rest}` : `${ctx.base}/notifications`, 303);
+  });
+
+  app.post('/a/:alias/notifications/read', async (req: Req, reply) => {
+    const ctx = await context(req, reply);
+    if (!ctx) return;
+    const next = safeNext(ctx.app, typeof req.body?.next === 'string' ? req.body.next : `${ctx.base}/notifications`);
+    if (req.body?.__csrf !== ctx.session.csrf_token) return reply.redirect(next, 303);
+    await runtime.query(
+      'update meta.notification set read_at = now() where app_id = $1 and lower(username) = lower($2) and read_at is null',
+      [ctx.app.id, ctx.user],
+    );
+    ctx.session.state.__FLASH = ctx.locale.t('notify.marked');
+    await saveState(ctx.session);
+    return reply.redirect(next, 303);
+  });
+
+  // live badges: what the page shows now; never extends the session
+  app.get('/a/:alias/:page/live', async (req: Req, reply) => {
+    const ctx = await loadContext(req, reply, { json: true, touch: false });
+    if (!ctx) return;
+    reply.header('cache-control', 'private, no-store');
+    if (!ctx.app.live_badges_s) return reply.code(404).send({ error: 'not found' });
+    try {
+      const state = await appTx(txContext(ctx), async (c) => {
+        ctx.client = c;
+        await checkPageAccess(ctx);
+        ctx.vis = await computeVisibility(ctx);
+        return liveState(ctx);
+      });
+      if (hasBell(ctx)) {
+        const unread = await unreadCount(ctx);
+        state.bell = { unread, label: bellLabel(ctx, unread), panel: (await bellPanel(ctx, unread)).toString() };
+      }
+      return reply.send(state);
+    } catch (e) {
+      if (e instanceof Forbidden) return reply.code(403).send({ error: e.message });
+      return reply.code(400).send({ error: await publicError(ctx, e, 'live badges') });
+    }
+  });
+}

package/src/runtime/processes.ts

@@ -176,7 +176,7 @@ export function chainProblems(conf: unknown): string[] {
 }
 
 /** Process types a background chain can run (nothing that needs the request: forms, grids, uploads, files). */
-export const BACKGROUND_TYPES = new Set<Process['type']>(['sql', 'invoke_api', 'workflow', 'chain', 'send_push', 'send_email']);
+export const BACKGROUND_TYPES = new Set<Process['type']>(['sql', 'invoke_api', 'workflow', 'chain', 'send_push', 'send_email', 'send_notification']);
 
 // ---------------------------------------------------------------- workflows
 
@@ -248,6 +248,7 @@ export function processProblems(type: string, conf: unknown): string[] {
   if (type === 'chain') return chainProblems(conf);
   if (type === 'workflow') return workflowProblems(conf);
   if (type === 'send_push') return sendPushProblems(conf);
+  if (type === 'send_notification') return sendNotificationProblems(conf);
   if (type === 'send_email') return sendEmailProblems(conf);
   if (DECLARATIVE_PROCESS_TYPES.has(type)) return declarativeProblems(type, conf);
   return [];
@@ -298,6 +299,49 @@ export async function sendPushProcess(ctx: PageContext, p: Process): Promise<str
   return p.success_message ?? null;
 }
 
+// ---------------------------------------------------------------- send_notification (154)
+
+interface SendNotificationConfig {
+  to: string;
+  title: string;
+  body?: string;
+  page?: number;
+  items?: Record<string, string>;
+  icon?: string;
+  push?: boolean;
+}
+
+export function sendNotificationProblems(conf: unknown): string[] {
+  const c = (conf ?? {}) as Record<string, any>;
+  const out: string[] = [];
+  if (typeof c.to !== 'string' || !c.to.trim()) out.push('"to" is the user name, e.g. "&P5_OWNER." or "&APP_USER.".');
+  if (typeof c.title !== 'string' || !c.title.trim()) out.push('"title" is the notification\'s title.');
+  if (c.body !== undefined && typeof c.body !== 'string') out.push('"body" is text.');
+  if (c.page !== undefined && !(Number.isInteger(c.page) && c.page > 0)) out.push('"page" is a page number of this application.');
+  if (c.items !== undefined && (typeof c.items !== 'object' || Array.isArray(c.items) || c.items === null || Object.entries(c.items).some(([k, v]) => !ITEM.test(k.toUpperCase()) || typeof v !== 'string')))
+    out.push('"items" maps item names of the page to values, e.g. {"P5_ID": "&P5_ID."}.');
+  if (c.items !== undefined && c.page === undefined) out.push('"items" needs a "page".');
+  if (c.icon !== undefined && (typeof c.icon !== 'string' || !/^[a-z0-9-]{1,40}$/.test(c.icon))) out.push('"icon" is an icon name, e.g. "bell" or "check".');
+  if (c.push !== undefined && typeof c.push !== 'boolean') out.push('"push" is true or false (also to the user\'s devices when push notifications are on).');
+  return out;
+}
+
+/**
+ * send_notification: adds an in-app notification (the bell) for a user with meta.notify, in the page's
+ * transaction, so it exists only when the submit commits. Values take &ITEM. substitutions.
+ */
+export async function sendNotificationProcess(ctx: PageContext, p: Process): Promise<string | null> {
+  const conf = (p.config ?? {}) as unknown as SendNotificationConfig;
+  const problems = sendNotificationProblems(conf);
+  if (problems.length) throw new Error(`Process "${p.name}": ${problems.join(' ')}`);
+  const value = (s: string | undefined) => (s === undefined ? null : substitute(s, ctx, (x) => x));
+  const items = Object.fromEntries(Object.entries(conf.items ?? {}).map(([k, v]) => [k.toUpperCase(), value(v) ?? '']));
+  await ctx.client!.query('select meta.notify($1, $2, $3, $4, $5::jsonb, $6, $7)', [
+    (value(conf.to) ?? '').trim(), value(conf.title)?.slice(0, 200), value(conf.body)?.slice(0, 1000) || null, conf.page ?? null, JSON.stringify(items), conf.icon ?? null, conf.push === true,
+  ]);
+  return p.success_message ?? null;
+}
+
 // ---------------------------------------------------------------- send_email (081)
 
 interface SendEmailConfig {

package/src/runtime/regions.ts

@@ -16,7 +16,7 @@ import { CHART_KINDS, renderChartBody, wallClockIn, type GaugeConfig } from './c
 import { databaseTimeZone } from './locale.ts';
 import { renderFacets } from './facets.ts';
 import { renderSmartFilters } from './smart-filters.ts';
-import { renderListRegion } from './lists.ts';
+import { queryBadge, renderListRegion } from './lists.ts';
 import { renderDisplaySelector } from './display-selector.ts';
 import { renderGrid } from './grid.ts';
 import { masterItemOf, mastersOf } from './master-detail.ts';
@@ -44,22 +44,18 @@ import { renderBreadcrumbRegion, renderHelpTextRegion } from './page-regions.ts'
 
 /** A button's badge: the badge query's first value, or the badge text with &ITEM. substitutions. */
 async function badgeOf(ctx: PageContext, b: Button): Promise<Raw | ''> {
-  let value: string | null = null;
-  if (b.badge_query?.trim()) {
-    const c = ctx.client!;
-    const sql = stripSemicolon(applyBinds(b.badge_query, bindValues(ctx)));
-    try {
-      const res = await savepoint(c, () => c.query({ text: sql, rowMode: 'array' }));
-      const v = res.rows[0]?.[0];
-      value = v === null || v === undefined ? null : String(v);
-    } catch (e) {
-      ctx.errors.page.push(await publicError(ctx, e, `badge of button ${b.name}`));
-    }
-  } else if (b.badge) value = substitute(b.badge, ctx, (x) => x);
-  value = value?.trim().slice(0, 100) || null;
-  return value ? html` <span class="btn-badge">${value}</span>` : '';
+  const value = b.badge_query?.trim()
+    ? await queryBadge(ctx, b.badge_query, `badge of button ${b.name}`)
+    : b.badge ? substitute(b.badge, ctx, (x) => x).trim().slice(0, 100) || null : null;
+  // (154) with live badges, a badge from a query keeps a place the refresh can fill
+  const live = ctx.app.live_badges_s && b.badge_query?.trim() ? html` data-badge="${buttonBadgeKey(b)}"` : '';
+  if (!value) return live ? html` <span class="btn-badge"${live} hidden></span>` : '';
+  return html` <span class="btn-badge"${live}>${value}</span>`;
 }
 
+/** (154) The data-badge key of a button's badge (live badges). */
+export const buttonBadgeKey = (b: { id: number }) => `btn:${b.id}`;
+
 /**
  * A menu button: a <details> dropdown (works without JavaScript) with links
  * to pages (signed item values, only pages the user may open), submit

package/src/runtime/render.ts

@@ -19,6 +19,7 @@ import { runtime, savepoint } from '../db.ts';
 import { renderItems } from './items.ts';
 import { buttonsFor, renderRegion } from './regions.ts';
 import { listTree, navbarMarkup, navMarkup } from './lists.ts';
+import { bellMarkup } from './notifications.ts';
 import { aiInputs, aiOutputs, aiProcessOf } from './ai.ts';
 import { frameOrigins } from './url-region.ts';
 import { breadcrumbLinks, hasBreadcrumbRegion } from './page-regions.ts';
@@ -108,7 +109,8 @@ async function navTree(ctx: PageContext, topNav = false) {
   // a list as the navigation menu (falls back to the navigation entries when the list is missing)
   if (ctx.app.nav_list) {
     const nodes = await listTree(ctx, ctx.app.nav_list);
-    if (nodes) return navMarkup(nodes, topNav);
+    // (154) with live badges, every entry's badge has a key the refresh finds it by
+    if (nodes) return navMarkup(nodes, topNav, ctx.app.live_badges_s ? 'n:' : undefined);
   }
   const current = new Set<number>();
   for (let p: number | null | undefined = ctx.page.page_no, guard = 0; p && guard < 10; guard++) {
@@ -267,7 +269,9 @@ export async function chrome(ctx: PageContext, main: Raw, title: string) {
   // (084) the Feedback entry, after the application's own navigation bar list
   const feedback = feedbackNode(ctx);
   const navbarNodes = listNodes || feedback ? [...(listNodes ?? []), ...(feedback ? [feedback] : [])] : null;
-  const navbar = navbarNodes ? navbarMarkup(navbarNodes, t('list.navbar')) : '';
+  const navbar = navbarNodes ? navbarMarkup(navbarNodes, t('list.navbar'), ctx.app.live_badges_s ? 'b:' : undefined) : '';
+  // (154) the notification bell
+  const bell = await bellMarkup(ctx);
   // (sprint 72) the account's display name in the user menu
   const shown = signedIn ? ((await displayName(ctx.user)) ?? ctx.user) : ctx.user;
   // (sprint 88, GEN-4; APEX: the page footer) under the content: the application's version and "Back to top" (to the header, #top)
@@ -280,6 +284,7 @@ export async function chrome(ctx: PageContext, main: Raw, title: string) {
       <span class="t-spacer"></span>
       ${ctx.app.pwa ? html`<button type="button" class="icon-button t-install" data-pwa-install hidden title="${t('pwa.install')}" aria-label="${t('pwa.install')}">${icon('download')}</button>` : ''}
       ${navbar}
+      ${bell}
       ${ctx.app.authentication !== 'none'
         ? signedIn
           ? html`<details class="menu t-user">
@@ -314,7 +319,11 @@ export async function chrome(ctx: PageContext, main: Raw, title: string) {
     </div>
     ${devbarHtml(ctx)}`,
     `t-app${topNav ? ' nav-top' : ''}${appearance ? ` nav-pillar nav-${appearance === 'pillar_dark' ? 'pillar-dark' : 'pillar-light'}` : ''}`,
-    { 'data-base': ctx.base, 'data-page': String(ctx.page.page_no), ...pwaBody(ctx.app, ctx.user), ...(await pushBody(ctx.app, ctx.session.username)) },
+    {
+      'data-base': ctx.base, 'data-page': String(ctx.page.page_no), ...pwaBody(ctx.app, ctx.user), ...(await pushBody(ctx.app, ctx.session.username)),
+      // (154) live badges: the page asks for its badges again every so many seconds
+      ...(ctx.app.live_badges_s ? { 'data-live': String(ctx.app.live_badges_s) } : {}),
+    },
     html`${pageStyle(ctx)}${pwaHead(ctx.app)}${mapHead(ctx)}${staticHead(ctx)}`,
     root,
   );

package/src/runtime/routes.ts

@@ -229,13 +229,21 @@ export const txContext = (ctx: PageContext) => ({
 });
 
 /** Load app, page, session and user; handles 404 and the login redirect. */
-export async function loadContext(req: Req, reply: FastifyReply, { json = false, pageNo: fixedPage }: { json?: boolean; pageNo?: 'home' } = {}): Promise<PageContext | null> {
+export async function loadContext(
+  req: Req,
+  reply: FastifyReply,
+  { json = false, pageNo: fixedPage, touch = true }: { json?: boolean; pageNo?: 'home'; touch?: boolean } = {},
+): Promise<PageContext | null> {
   const app = await loadApp(req.params.alias);
   if (!app) return simplePage(reply, 404, english('error.not_found'), english('error.app_not_found', { app: req.params.alias })), null;
   const base = `/a/${app.alias}`;
-  let session = await getSession(req, reply, app.id, base);
+  // (154) touch false: a request the page makes by itself (live badges) neither keeps an idle session
+  // alive nor starts one (no sign-in from a remembered browser either)
+  const existing = touch ? await getSession(req, reply, app.id, base) : await getSession(req, reply, app.id, base, { touch: false });
+  if (!existing) return reply.code(401).send({ error: english('error.session_ended') }), null;
+  let session = existing;
   // the session ended, but the browser was remembered: sign in again silently (a new token each time)
-  if (app.authentication === 'app_users' && !session.username) {
+  if (touch && app.authentication === 'app_users' && !session.username) {
     const remembered = await useRemember(req, reply, app);
     // (sprint 130) one made before the application asked this user for a second step doesn't stand in for it
     if (remembered && (await carriesSecondStep(app, remembered.username, remembered.roles, remembered.method)))
@@ -245,7 +253,7 @@ export async function loadContext(req: Req, reply: FastifyReply, { json = false,
       });
   }
   // (067) another application of the session sharing group was signed in to: sign in here too
-  if (!session.username && sharingGroup(app)) {
+  if (touch && !session.username && sharingGroup(app)) {
     const shared = await useShared(req, reply, app);
     if (shared && (await carriesSecondStep(app, shared.username, shared.roles, shared.method)))
       session = await signIn(req, reply, app, session, shared.username, {

package/src/runtime/signin.ts

@@ -19,7 +19,8 @@ import { languagePicker } from './render.ts';
 
 /** Where to go after signing in: a path of this application, else its home page. */
 export const safeNext = (app: App, next: string | undefined) =>
-  next && next.startsWith(`/a/${app.alias}/`) && !/[\\\r\n]/.test(next) && !next.includes('//') ? next : `/a/${app.alias}/${app.home_page}`;
+  // (sprint 165) no dot segments either: /a/<alias>/../../builder stays inside the application
+  next && next.startsWith(`/a/${app.alias}/`) && !/[\\\r\n]/.test(next) && !next.includes('//') && !/\/(\.|%2e){1,2}(\/|$|\?|#)/i.test(next) ? next : `/a/${app.alias}/${app.home_page}`;
 
 /** "Forgot password?" is offered: turned on, app users with passwords, an enabled mail service. */
 export async function passwordResetAvailable(app: App) {

package/src/session.ts

@@ -53,10 +53,11 @@ export const cookieName = (appId: number | null) => (appId === null ? 'pgkiln_de
 /** The idle and maximum session length (minutes, hours), for lookups outside this file. */
 export const sessionLimits = () => ({ idleMinutes: IDLE_MINUTES(), maxHours: MAX_HOURS() });
 
-async function find(token: string | undefined, appId: number | null) {
+/** A live session of the token; touch (the default): the request counts as activity (last_seen). */
+async function find(token: string | undefined, appId: number | null, touch = true) {
   if (!token || token.length > 100) return undefined;
   return runtime.one<Session>(
-    `update meta.session set last_seen = now()
+    `update meta.session set last_seen = ${touch ? 'now()' : 'last_seen'}
       where token_hash = $1 and app_id is not distinct from $2
         and last_seen > now() - make_interval(mins => $3)
         and created_at > now() - make_interval(hours => $4)
@@ -84,8 +85,16 @@ export async function createSession(reply: FastifyReply, appId: number | null, p
   return { ...s, isNew: true };
 }
 
-export async function getSession(req: FastifyRequest, reply: FastifyReply, appId: number | null, path: string) {
-  return (await find(req.cookies[cookieName(appId)], appId)) ?? createSession(reply, appId, path);
+/**
+ * The request's session, or a new one. (154) touch false: a request the browser makes by itself (live
+ * badges) doesn't keep an idle session alive, and makes no new session when there is none (null).
+ */
+export async function getSession(req: FastifyRequest, reply: FastifyReply, appId: number | null, path: string): Promise<Session>;
+export async function getSession(req: FastifyRequest, reply: FastifyReply, appId: number | null, path: string, opts: { touch: false }): Promise<Session | null>;
+export async function getSession(req: FastifyRequest, reply: FastifyReply, appId: number | null, path: string, opts?: { touch: false }) {
+  const found = await find(req.cookies[cookieName(appId)], appId, !opts);
+  if (found || opts) return found ?? null;
+  return createSession(reply, appId, path);
 }
 
 export async function saveState(s: Session) {