@k2b/cloud 0.33.0 → 0.34.0

package/src/services/pwa-devices.ts

@@ -1,6 +1,7 @@
 import { timingSafeEqual } from "node:crypto";
 import { type SQL, sql } from "bun";
 import type { Context } from "hono";
+import { lazySync } from "../_internal/process-sync";
 import { PWA_LIMITS as limits, type PwaDeviceView, type PwaErrorCode, type PwaPairingState, type PwaPlatform } from "../contracts/pwa";
 import { isAccountCategoryAllowed } from "./account-category-policy";
 import { audit } from "./audit";
@@ -30,6 +31,13 @@ const fail = (code: PwaErrorCode, status: PwaError["status"], attemptsLeft?: num
 
 /** The initiating web session of a pairing. */
 export type PwaWebActor = { userId: string; sid: string };
+/** Best-effort wake-ups for browsers waiting on a pairing claim. Postgres stays authoritative. */
+export type PwaPairingClaimHints = {
+  /** Call after the claim commits. Must not throw or delay the caller. */
+  publish(pairingId: string): void;
+  /** Settles on the first hint for this pairing, or when `signal` aborts. */
+  wait(pairingId: string, signal: AbortSignal): Promise<void>;
+};
 /** Administration of another account's phones needs current admin authority. */
 export type PwaDeviceAdministrator = { userId: string; admin: boolean };
 export type PwaRevocationReason = "user" | "unpaired" | "admin" | "replaced" | "account_expired";
@@ -87,6 +95,25 @@ type UserRow = {
 };
 
 const log = logger("pwa-devices");
+const claimTopic = lazySync((sync) =>
+  sync.topic<null>({
+    id: "cloud:pwa-pairing-claims",
+    owner: "cloud",
+    retention: { maxAgeMs: 120_000, maxBytes: 1_048_576 },
+    maxPayloadBytes: 2000,
+  }),
+);
+/** Core NATS broadcast reaches the waiting browser on any replica. */
+export const syncPairingClaimHints: PwaPairingClaimHints = {
+  publish: (pairingId) => {
+    void Promise.resolve()
+      .then(() => claimTopic().publish({ tenantId: pairingId, data: null }))
+      .catch((error) => log.warn("App pairing claim hint failed", { error: error instanceof Error ? error.name : "UnknownError" }));
+  },
+  wait: async (pairingId, signal) => {
+    for await (const _event of claimTopic().live({ tenantId: pairingId, signal })) return;
+  },
+};
 const iso = (value: Date | string) => new Date(value).toISOString();
 const passed = (value: Date | string) => new Date(value).getTime() <= Date.now();
 const DEVICE_KEY = /^([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\.([A-Za-z0-9_-]{43})$/;
@@ -243,7 +270,7 @@ export type PwaCompletion =
   | { state: "paired"; credentials: PwaCredentials | null; platform: PwaPlatform }
   | { state: "waiting"; code: string; account: { name: string }; expiresAt: string };
 
-export const createPwaDeviceService = () => {
+export const createPwaDeviceService = (hints: PwaPairingClaimHints = syncPairingClaimHints) => {
   const appSession = (deviceId: string) => ({ ttlSeconds: limits.sessionSeconds, pwaDeviceId: deviceId, recordLogin: false });
 
   /**
@@ -334,21 +361,46 @@ export const createPwaDeviceService = () => {
     },
 
     /** Never returns the code: the person types what the phone shows. */
-    inspectPairing: async (actor: PwaWebActor, id: string) => {
-      const [p] = await sql<(PairingRow & { current_epoch: string })[]>`
-        SELECT p.*, u.auth_epoch AS current_epoch FROM auth.pwa_pairings p JOIN auth.users u ON u.id = p.user_id
-        WHERE p.id = ${id}::uuid AND p.user_id = ${actor.userId}::uuid AND p.initiator_sid = ${actor.sid}::uuid
-      `;
-      if (!p) return fail("NOT_FOUND", 404);
-      if (passed(p.expires_at) || p.current_epoch !== p.auth_epoch || (p.state === "pending" && passed(p.claim_until)))
-        return fail("EXPIRED", 410);
-      return {
-        state: p.state,
-        claimUntil: iso(p.claim_until),
-        expiresAt: iso(p.expires_at),
-        device: p.state === "pending" || !p.device_name || !p.platform ? null : { name: p.device_name, platform: p.platform },
-        attemptsLeft: Math.max(0, limits.confirmAttempts - p.failed_attempts),
+    inspectPairing: async (actor: PwaWebActor, id: string, hold?: { ms: number; signal?: AbortSignal }) => {
+      const read = async (validateInitiator = false) => {
+        const [p] = await sql<(PairingRow & { current_epoch: string })[]>`
+          SELECT p.*, u.auth_epoch AS current_epoch FROM auth.pwa_pairings p JOIN auth.users u ON u.id = p.user_id
+          WHERE p.id = ${id}::uuid AND p.user_id = ${actor.userId}::uuid AND p.initiator_sid = ${actor.sid}::uuid
+        `;
+        if (!p) return fail("NOT_FOUND", 404);
+        if (passed(p.expires_at) || p.current_epoch !== p.auth_epoch || (p.state === "pending" && passed(p.claim_until)))
+          return fail("EXPIRED", 410);
+        if (validateInitiator && !(await initiatorValid(sql, p))) return fail("EXPIRED", 410);
+        return {
+          state: p.state,
+          claimUntil: iso(p.claim_until),
+          expiresAt: iso(p.expires_at),
+          device: p.state === "pending" || !p.device_name || !p.platform ? null : { name: p.device_name, platform: p.platform },
+          attemptsLeft: Math.max(0, limits.confirmAttempts - p.failed_attempts),
+        };
       };
+      if (!hold) return read();
+      // Listen before the first read so a claim committed in between usually wakes this request.
+      // live() has no subscription-ready barrier, so the hint is best effort; the deadline re-read is the guarantee.
+      // The read after the hold also checks the initiating web session, which may have ended meanwhile.
+      const waiting = new AbortController();
+      const ended = new Promise((resolve) => waiting.signal.addEventListener("abort", resolve, { once: true }));
+      const stop = () => waiting.abort();
+      hold.signal?.addEventListener("abort", stop, { once: true });
+      if (hold.signal?.aborted) stop();
+      const hint = hints.wait(id, waiting.signal).catch(() => {});
+      let timer: ReturnType<typeof setTimeout> | undefined;
+      try {
+        const first = await read();
+        if (first.state !== "pending") return first;
+        timer = setTimeout(stop, Math.min(hold.ms, new Date(first.claimUntil).getTime() - Date.now()));
+        await Promise.race([hint, ended]);
+        return await read(true);
+      } finally {
+        clearTimeout(timer);
+        hold.signal?.removeEventListener("abort", stop);
+        stop();
+      }
     },
 
     confirmPairing: async (actor: PwaWebActor, id: string, code: string) => {
@@ -438,6 +490,7 @@ export const createPwaDeviceService = () => {
           WHERE id = ${p.id}::uuid`;
         return { account: { name: accountName(user) }, expiresAt: p.expires_at };
       });
+      hints.publish(snapshot.id);
       return { code, account: result.account, expiresAt: iso(result.expiresAt), completionSecret };
     },
 

package/src/shared/app-presentation.ts

@@ -26,7 +26,22 @@ const mergedTranslation = (catalog: AppPresentationCatalog, requestedLocale: str
       widgets: Object.fromEntries(
         [...new Set([...Object.keys(current.widgets ?? {}), ...Object.keys(next.widgets ?? {})])].map((id) => [
           id,
-          { ...current.widgets?.[id], ...next.widgets?.[id] },
+          {
+            ...current.widgets?.[id],
+            ...next.widgets?.[id],
+            settings: Object.fromEntries(
+              [...new Set([...Object.keys(current.widgets?.[id]?.settings ?? {}), ...Object.keys(next.widgets?.[id]?.settings ?? {})])].map(
+                (name) => [
+                  name,
+                  {
+                    ...current.widgets?.[id]?.settings?.[name],
+                    ...next.widgets?.[id]?.settings?.[name],
+                    options: { ...current.widgets?.[id]?.settings?.[name]?.options, ...next.widgets?.[id]?.settings?.[name]?.options },
+                  },
+                ],
+              ),
+            ),
+          },
         ]),
       ),
     };
@@ -65,6 +80,39 @@ export const resolveAppPresentation = <T extends AppMeta>(app: T, requestedLocal
       ...widget,
       title: translation.widgets?.[widget.id]?.title ?? widget.title,
       description: translation.widgets?.[widget.id]?.description ?? widget.description,
+      ...(widget.settings && typeof widget.settings === "object" && !Array.isArray(widget.settings)
+        ? {
+            settings: Object.fromEntries(
+              Object.entries(widget.settings).map(([name, field]) => {
+                if (!field || typeof field !== "object") return [name, field];
+                const translated = translation.widgets?.[widget.id]?.settings?.[name];
+                return [
+                  name,
+                  {
+                    ...field,
+                    label: translated?.label ?? field.label,
+                    ...(field.kind === "text" ? { placeholder: translated?.placeholder ?? field.placeholder } : {}),
+                    ...(field.kind === "choice" && Array.isArray(field.options)
+                      ? {
+                          options: field.options.map((option) =>
+                            option && typeof option === "object"
+                              ? {
+                                  ...option,
+                                  label:
+                                    translated?.options && Object.hasOwn(translated.options, option.value)
+                                      ? (translated.options[option.value] ?? option.label)
+                                      : option.label,
+                                }
+                              : option,
+                          ),
+                        }
+                      : {}),
+                  },
+                ];
+              }),
+            ),
+          }
+        : {}),
     })),
   };
 };

package/src/shared/index.ts

@@ -44,6 +44,7 @@ export * from "./locale";
 export * from "./locale-preference";
 export * from "./login-method";
 export { markdown } from "./markdown";
+export { markdownCalloutSanitizeOptions } from "./markdown/callout-sanitizer";
 export type { ErrorCode, EvalContext, EvalError, EvalResult, EvalValue, ProgressValue } from "./markdown/formula";
 export { createProgressValue, evaluateFormula, formatValue, isFormula, isTotalRow, parseProgressValue } from "./markdown/formula";
 export type { MockCover, MockCoverIcon, MockCoverOptions, MockCoverTheme } from "./mock-cover";

package/src/shared/markdown/callout-sanitizer.ts

@@ -0,0 +1,37 @@
+import { MARKDOWN_CALLOUT_ICON_ATTRIBUTES } from "@k2b/ui";
+import type sanitizeHtml from "sanitize-html";
+
+/** Fresh sanitize-html options for one document: SVG is limited to fixed callout icons. */
+export const markdownCalloutSanitizeOptions = () => {
+  const elements: { inIcon: boolean; discard: boolean }[] = [];
+  let closed: { inIcon: boolean; discard: boolean } | undefined;
+  return {
+    allowedTags: ["svg", "path"],
+    allowedAttributes: { svg: Object.keys(MARKDOWN_CALLOUT_ICON_ATTRIBUTES), path: ["d"] },
+    // onOpenTag sees raw attributes before transforms; discarded SVG must keep ordinary HTML and text.
+    onOpenTag: (tag, attrs) => {
+      const parent = elements.at(-1);
+      elements.push({
+        inIcon: !!parent?.inIcon || (tag === "svg" && attrs.class === MARKDOWN_CALLOUT_ICON_ATTRIBUTES.class),
+        discard: !!parent?.discard || (!!parent?.inIcon && tag !== "path"),
+      });
+    },
+    // sanitize-html closes a tag before calling exclusiveFilter for that element.
+    onCloseTag: () => {
+      closed = elements.pop();
+    },
+    // excludeTag preserves ordinary content, including after an unclosed author SVG.
+    exclusiveFilter: ({ tag }) => closed?.discard || ((tag === "svg" || tag === "path") && !closed?.inIcon ? "excludeTag" : false),
+    textFilter: (text) => (elements.at(-1)?.inIcon ? "" : text),
+    transformTags: {
+      svg: (tagName) => ({
+        tagName,
+        attribs: { ...MARKDOWN_CALLOUT_ICON_ATTRIBUTES },
+      }),
+      path: (tagName, attrs) => ({
+        tagName,
+        attribs: Object.fromEntries(Object.entries(attrs).filter(([name]) => name === "d")),
+      }),
+    },
+  } satisfies sanitizeHtml.IOptions;
+};

package/src/shared/markdown/index.ts

@@ -8,6 +8,7 @@
 import { markdownInfoBlocks } from "@k2b/ui";
 import { Marked, type MarkedExtension } from "marked";
 import sanitizeHtml from "sanitize-html";
+import { markdownCalloutSanitizeOptions } from "./callout-sanitizer";
 import { markdownClient } from "./client";
 import { codeExtension, plainCodeExtension } from "./extensions/code";
 import { guidedHelpExtension } from "./extensions/guided-help";
@@ -73,8 +74,10 @@ export type MarkdownRenderOptions = {
   locale?: string;
 };
 
-const sanitizeRenderedHtml = (html: string): string =>
-  sanitizeHtml(html, {
+const sanitizeRenderedHtml = (html: string): string => {
+  const callouts = markdownCalloutSanitizeOptions();
+  return sanitizeHtml(html, {
+    ...callouts,
     allowedTags: [
       ...sanitizeHtml.defaults.allowedTags,
       "annotation",
@@ -101,6 +104,7 @@ const sanitizeRenderedHtml = (html: string): string =>
       "mtext",
       "semantics",
       "span",
+      ...callouts.allowedTags,
       "sub",
       "sup",
       "table",
@@ -129,6 +133,7 @@ const sanitizeRenderedHtml = (html: string): string =>
       input: ["checked", "class", "disabled", "type"],
       math: ["xmlns"],
       pre: ["class"],
+      ...callouts.allowedAttributes,
       span: ["aria-hidden", "class", "style", "title"],
     },
     allowedSchemes: ["http", "https", "mailto", "tel", "note", "attach"],
@@ -150,6 +155,7 @@ const sanitizeRenderedHtml = (html: string): string =>
       },
     },
   });
+};
 
 /**
  * Render markdown to HTML for server-side display.

package/src/ssr/Layout.tsx

@@ -11,9 +11,8 @@ import { getDateConfig } from "../server/time";
 import { dates } from "../shared";
 import { readThemePreferenceFromCookieHeader } from "../shared/theme";
 import AnnouncementBanners from "./AnnouncementBanners";
-import { appAppearanceStyle } from "./app-appearance";
+import { appAppearanceStyle, resolveCurrentApp } from "./app-appearance";
 import { resolveRuntimeRoute, visibleNavigationApps } from "./app-navigation";
-import type { GlobalSearchHelpApp } from "./GlobalSearchHelpDialog";
 import { getLayoutHelp } from "./help";
 import LayoutFooter from "./LayoutFooter";
 import LayoutHeader from "./LayoutHeader";
@@ -151,7 +150,7 @@ export default function Layout(props: LayoutProps) {
   const user = c.get("user");
   const pathname = new URL(c.req.raw.url).pathname;
   const currentRoute = resolveRuntimeRoute(runtime.apps, pathname);
-  const currentApp = currentRoute?.app;
+  const currentApp = resolveCurrentApp(runtime.apps, pathname);
   const registeredHelp = getLayoutHelp(c);
   const runtimeHelp = registeredHelp ? { documents: registeredHelp.documents, pageBase: registeredHelp.pageBase } : undefined;
   const workspaceLayout = resolveAppWorkspaceLayoutForSidebar(
@@ -164,17 +163,6 @@ export default function Layout(props: LayoutProps) {
   const searchLinks = Object.fromEntries(
     runtime.apps.flatMap((app) => (visibleAppIds.has(app.id) && app.searchLinks?.length ? [[app.id, app.searchLinks] as const] : [])),
   );
-  const searchHelpApps: GlobalSearchHelpApp[] = runtime.apps
-    .filter((app) => (app.searchTags?.length ?? 0) > 0)
-    .map((app) => ({
-      appId: app.id,
-      appName: app.name,
-      appIcon: app.icon,
-      help: app.searchHelp,
-      tags: [...new Set((app.searchTags ?? []).map((tag) => tag.toLowerCase()))],
-      tagHelp: [...(app.searchTagHelp ?? [])],
-    }))
-    .sort((a, b) => a.appName.localeCompare(b.appName));
   const settings = c.get("settings");
   const announcements = c.get("announcements");
   const appName = settings?.app?.name || "Cloud";
@@ -223,7 +211,7 @@ export default function Layout(props: LayoutProps) {
     theme,
     accent: currentApp?.appearance?.accent,
     searchLinks,
-    searchHelpApps,
+    appId: currentApp?.id,
   };
   if (focusMode) {
     return (

package/src/ssr/LayoutHelp.browser-harness.tsx

@@ -0,0 +1,43 @@
+import { LocaleProvider } from "@k2b/ui";
+import { render } from "solid-js/web";
+import type { HelpDocumentManifest, HelpDocumentPayload } from "../shared/help";
+import { LayoutHelpPage } from "./LayoutHelp";
+
+const documents: HelpDocumentManifest[] = Array.from({ length: 8 }, (_, index) => ({
+  id: `topic-${index}`,
+  title: `Topic ${index}`,
+  description: "Help browser fixture",
+  order: index,
+  url: `/api/help/topic-${index}`,
+  searchUrl: "/api/help/search",
+}));
+const html = Array.from(
+  { length: 8 },
+  (_, index) =>
+    `<h2 id="section-${index}" class="help-section-title" data-help-icon="ti ti-point">Section ${index}</h2>${Array.from({ length: 18 }, () => "<p>Read this guidance to finish the task and understand how the app works.</p>").join("")}`,
+).join("");
+window.fetch = Object.assign(
+  async (input: URL | RequestInfo) => {
+    await new Promise((resolve) => setTimeout(resolve, 80));
+    const path = String(input);
+    if (path.includes("/search")) return Response.json({ locale: "en", ids: ["topic-0", "topic-1"] });
+    const id = path.split("/").at(-1) ?? "topic-0";
+    const payload: HelpDocumentPayload = { id, locale: "en", title: id, markdown: "Help", html };
+    return Response.json(payload);
+  },
+  { preconnect: () => {} },
+);
+const main = document.querySelector<HTMLElement>(".layout-content-main");
+if (!main) throw new Error("Missing Layout main");
+const embedded = new URL(location.href).searchParams.has("embedded");
+const host = document.createElement("div");
+if (embedded) host.style.cssText = "width:360px;height:700px";
+main.append(host);
+render(
+  () => (
+    <LocaleProvider locale="en">
+      <LayoutHelpPage documents={documents} embedded={embedded} pageBase="/app/spaces/help" />
+    </LocaleProvider>
+  ),
+  host,
+);