@k2b/cloud 0.39.0 → 0.40.0

package/src/ssr/help.ts

@@ -1,9 +1,13 @@
 import type { Context } from "hono";
+import { buildHelpDocumentPayload } from "../server/help-payload";
 import { getLocale } from "../server/locale";
 import { createHelpReader } from "../services/help";
 import type { HelpManifestResult } from "../services/help/types";
 import { logger } from "../services/logging";
+import type { HelpDocumentPayload } from "../shared/help";
 import { resolveCurrentApp } from "./app-appearance";
+import type { HelpArticleParts } from "./layout-help-article";
+import { helpArticlePartsServer } from "./layout-help-article.server";
 import { getRuntimeContext } from "./runtime";
 
 const manifests = new WeakMap<object, HelpManifestResult | null>();
@@ -30,3 +34,19 @@ export const preloadLayoutHelp = async (c: Context, appId?: string): Promise<Hel
     return null;
   }
 };
+
+export type LayoutHelpArticle = { payload: HelpDocumentPayload; parts: HelpArticleParts };
+
+/** An authorized initial article; failures leave the browser's on-demand reader available. */
+export const preloadLayoutHelpArticle = async (c: Context, appId: string, documentId: string): Promise<LayoutHelpArticle | null> => {
+  if (!c.get("user")) return null;
+  try {
+    const article = await createHelpReader(getLocale(c), c.get("actor")).read({ appId, documentId });
+    if (!article) return null;
+    const payload = buildHelpDocumentPayload(article, c.req.header("User-Agent") ?? "");
+    return { payload, parts: helpArticlePartsServer(payload.html) };
+  } catch (error) {
+    log.warn("Help article unavailable", { appId, documentId, error: error instanceof Error ? error.message : String(error) });
+    return null;
+  }
+};

package/src/ssr/hints.ts

@@ -0,0 +1,25 @@
+import type { Context } from "hono";
+import { isHintId, mergeSeenHints, parseSeenHintsCookieHeader, seenHintsSetCookie } from "../contracts/seen-hints";
+import { userFromActor } from "../server/actor";
+
+/** Ids marked seen earlier in the same request, so a second mark or a later check sees them too. */
+const marked = new WeakMap<Context, string[]>();
+
+const seenIds = (c: Context): string[] => marked.get(c) ?? parseSeenHintsCookieHeader(c.req.header("Cookie"));
+
+/** The caller checks access to the new path; anonymous visitors never see a hint. */
+export const hintOpen = (c: Context, id: string, options: { allowed: boolean }): boolean => {
+  if (!isHintId(id)) throw new Error(`Invalid hint id: ${id}`);
+  return options.allowed && !!userFromActor(c.get("actor")) && !seenIds(c).includes(id);
+};
+
+/**
+ * Call on the new path too: using it counts as having seen the hint. Each call writes the whole list seen so far in
+ * this request, so with several calls the browser keeps the last cookie and with it every id.
+ */
+export const markHintSeen = (c: Context, id: string): void => {
+  const ids = mergeSeenHints(seenIds(c), id);
+  marked.set(c, ids);
+  const secure = new URL(c.req.url).protocol === "https:" || c.req.header("x-forwarded-proto")?.split(",")[0]?.trim() === "https";
+  c.header("Set-Cookie", seenHintsSetCookie(ids, secure), { append: true });
+};

package/src/ssr/index.ts

@@ -11,6 +11,7 @@ export {
   visiblePanelProviders,
   visiblePwaParts,
 } from "./app-navigation";
+export { hintOpen, markHintSeen } from "./hints";
 export { default as Layout } from "./Layout";
 export {
   default as MinimalLayout,
@@ -19,6 +20,7 @@ export {
 } from "./MinimalLayout";
 export { default as PanelLayout, type PanelLayoutProps } from "./PanelLayout";
 export { default as PwaLayout, type PwaLayoutProps } from "./PwaLayout";
+export { readPanelContext } from "./panel-context";
 export { requestPath } from "./request-path";
 export { getLocalizedRuntimeContext, getRuntimeContext, type RuntimeContext } from "./runtime";
 export type { UrlFilterField } from "./url-filter";

package/src/ssr/islands/index.ts

@@ -4,19 +4,20 @@ export { provideWorkspaceNavigation } from "../workspace-navigation";
 export { default as SearchBar } from "./SearchBar";
 
 import { AppLaunchpadButton, AppLaunchpadProvider } from "../app-launchpad";
-import { LayoutHelpPage } from "../LayoutHelp";
+import { LayoutHelpPage, LayoutHelpPanel } from "../LayoutHelp";
 import { LayoutHelpDocuments } from "../layout-help-registry";
 
 export type { AppLaunchpadApp, AppLaunchpadLegalLink } from "../app-launchpad";
 export { AppLaunchpadButton, AppLaunchpadProvider, openAppLaunchpad, setAppLaunchpadContext } from "../app-launchpad";
-export type { LayoutHelpPageProps } from "../LayoutHelp";
-export { LayoutHelpPage, openLayoutHelpDialog } from "../LayoutHelp";
+export type { LayoutHelpPageProps, LayoutHelpPanelProps } from "../LayoutHelp";
+export { LayoutHelpPage, LayoutHelpPanel, openLayoutHelpDialog } from "../LayoutHelp";
 export type { LayoutHelpDocumentsProps } from "../layout-help-registry";
 export { LayoutHelpDocuments } from "../layout-help-registry";
 
 export const Layout = {
   HelpDocuments: LayoutHelpDocuments,
   HelpPage: LayoutHelpPage,
+  HelpPanel: LayoutHelpPanel,
   AppLaunchpadButton,
   AppLaunchpadProvider,
 };

package/src/ssr/layout-context.ts

@@ -1,3 +1,4 @@
+import type { PanelConsentSnapshot } from "../contracts/panel-context";
 import type { RailSnapshot } from "../contracts/rail-preferences";
 import type { User } from "../contracts/shared";
 import type { LayoutAnnouncementsState } from "../server/middleware/settings";
@@ -5,6 +6,7 @@ import type { RuntimeContext } from "./runtime";
 
 export type LayoutContext = {
   get(key: "user"): User | undefined;
+  get(key: "panelConsent"): PanelConsentSnapshot | undefined;
   get(key: "railPreferences"): RailSnapshot | undefined;
   get(key: "page"): { theme?: "light" | "dark"; title?: string; pwa?: { name: string } };
   get(key: "runtime"): RuntimeContext;

package/src/ssr/layout-help-article.server.ts

@@ -0,0 +1,50 @@
+import type * as Htmlparser2 from "htmlparser2";
+import type { HelpArticleParts } from "./layout-help-article";
+
+// Keep the same synchronous import path as sanitize-html (see ai/readable-html.ts).
+const { parseDocument, DomUtils, ElementType }: typeof Htmlparser2 = require("htmlparser2");
+type HtmlNode = ReturnType<typeof parseDocument>["children"][number];
+
+const insideDetails = (node: HtmlNode): boolean => {
+  for (let parent = node.parent; parent; parent = parent.parent) if ("name" in parent && parent.name === "details") return true;
+  return false;
+};
+const spokenText = (node: HtmlNode): string => {
+  if (node.type === ElementType.Text) return node.data;
+  if (!("children" in node)) return "";
+  return node.children
+    .filter((child) => !("attribs" in child) || child.attribs["aria-hidden"] !== "true")
+    .map(spokenText)
+    .join("");
+};
+
+/** Server-only equivalent of the browser's inert-template splitter. Never import into an island. */
+export const helpArticlePartsServer = (html: string): HelpArticleParts => {
+  const body = parseDocument(html);
+  const first = body.children.find((node) => "attribs" in node);
+  const lead = first?.name === "p" && !first.attribs.class ? DomUtils.getOuterHTML(first) : undefined;
+  if (lead && first) DomUtils.removeElement(first);
+  const elements = DomUtils.findAll(() => true, body.children);
+  return {
+    lead,
+    body: DomUtils.getInnerHTML(body),
+    sections: elements
+      .filter((element) => element.name === "h2" && "id" in element.attribs && !insideDetails(element))
+      .map((element) => ({ id: element.attribs.id ?? "", label: spokenText(element).replace(/\s+/g, " ").trim() }))
+      .filter((section) => section.label),
+    steps: elements.filter((element) => {
+      const list = element.parent;
+      const wrapper = list?.parent;
+      return (
+        element.name === "li" &&
+        list &&
+        "name" in list &&
+        list.name === "ol" &&
+        wrapper &&
+        "attribs" in wrapper &&
+        (wrapper.attribs.class ?? "").split(/\s+/).includes("help-steps") &&
+        !insideDetails(element)
+      );
+    }).length,
+  };
+};

package/src/ssr/layout-help-start.ts

@@ -1,10 +1,10 @@
-import type { HelpKind } from "../shared/help";
+import { HELP_VIEW_LIMIT, type HelpKind } from "../shared/help";
 import { SHELL_SHORTCUT_ORDER } from "./shell-shortcuts";
 
 /** The concept asks for at most eight tasks as tiles; more task articles follow as a list. */
 export const HELP_START_TILE_LIMIT = 8;
 /** "For this view" shows two or three articles the page names. */
-export const HELP_VIEW_LIMIT = 3;
+export { HELP_VIEW_LIMIT } from "../shared/help";
 export const HELP_START_GROUP_KINDS = ["start", "reference", "troubleshoot"] as const;
 export type HelpStartGroupKind = (typeof HELP_START_GROUP_KINDS)[number];
 export type HelpStartTopic = { id: string; title: string; order?: number; kind?: HelpKind };
@@ -41,19 +41,42 @@ export const helpStart = <T extends HelpStartTopic>(topics: readonly T[], viewId
 };
 
 export type HelpShortcutScope = "everywhere" | "app" | "selection";
+// Three groups, each as scannable as HELP_START_TILE_LIMIT (8) task tiles: 3 x 8 rows.
+// Today's largest real page is well below this (shell 3 + Spaces about 8).
+export const HELP_START_SHORTCUT_LIMIT = 24;
+// Qualified command ids share CAPABILITY_QUALIFIED_ID_MAX_LENGTH.
+export const HELP_SHORTCUT_ID_MAX_LENGTH = 180;
+// One row label: the platform's CapabilityLink title / human-readable label bound.
+export const HELP_SHORTCUT_TITLE_MAX_LENGTH = 120;
+// Row tooltip: the platform's plain-text Action review message bound.
+export const HELP_SHORTCUT_DESCRIPTION_MAX_LENGTH = 1000;
+// command-shortcuts grammar: five distinct modifier tokens "ctrl+alt+shift+meta+mod+" (24 chars)
+// plus the longest standard KeyboardEvent.key name "TVAudioDescriptionMixDown" (25 chars).
+export const HELP_SHORTCUT_KEYS_MAX_LENGTH = 49;
+export type HelpShortcut = { id: string; title: string; description?: string; shortcut: string; scope?: "selection" | "page" };
 export type HelpShortcutCommand = { id: string; title: string; description?: string; shortcut?: string; scope?: "selection" | "page" };
 /**
  * Group commands with a shortcut: scope "selection" -> "selection"; id starting with "cloud." -> "everywhere"; the rest -> "app".
  * Group order everywhere, app, selection; empty groups are absent. Inside "everywhere", the ids of SHELL_SHORTCUT_ORDER come first in that
  * order (so rows rendered on the server keep their place when the browser adds more), then the rest in input order; other groups keep input order.
- * Commands without a shortcut are dropped.
+ * Commands without a shortcut, with empty ids/titles or exceeding the string bounds are dropped.
+ * Keep at most HELP_START_SHORTCUT_LIMIT rows across groups in group order.
  */
 export const helpShortcutGroups = <T extends HelpShortcutCommand>(
   commands: readonly T[],
 ): { scope: HelpShortcutScope; shortcuts: (T & { shortcut: string })[] }[] => {
   const groups: Record<HelpShortcutScope, (T & { shortcut: string })[]> = { everywhere: [], app: [], selection: [] };
   for (const command of commands) {
-    if (!command.shortcut) continue;
+    if (
+      !command.shortcut ||
+      !command.id ||
+      !command.title ||
+      command.id.length > HELP_SHORTCUT_ID_MAX_LENGTH ||
+      command.title.length > HELP_SHORTCUT_TITLE_MAX_LENGTH ||
+      (command.description?.length ?? 0) > HELP_SHORTCUT_DESCRIPTION_MAX_LENGTH ||
+      command.shortcut.length > HELP_SHORTCUT_KEYS_MAX_LENGTH
+    )
+      continue;
     const scope = command.scope === "selection" ? "selection" : command.id.startsWith("cloud.") ? "everywhere" : "app";
     groups[scope].push({ ...command, shortcut: command.shortcut });
   }
@@ -62,7 +85,10 @@ export const helpShortcutGroups = <T extends HelpShortcutCommand>(
     return index < 0 ? SHELL_SHORTCUT_ORDER.length : index;
   };
   groups.everywhere.sort((a, b) => rank(a.id) - rank(b.id));
-  return (["everywhere", "app", "selection"] as const).flatMap((scope) =>
-    groups[scope].length ? [{ scope, shortcuts: groups[scope] }] : [],
-  );
+  let remaining = HELP_START_SHORTCUT_LIMIT;
+  return (["everywhere", "app", "selection"] as const).flatMap((scope) => {
+    const shortcuts = groups[scope].slice(0, remaining);
+    remaining -= shortcuts.length;
+    return shortcuts.length ? [{ scope, shortcuts }] : [];
+  });
 };

package/src/ssr/panel-consent.ts

@@ -0,0 +1,29 @@
+import type { Context } from "hono";
+import { readPanelCookie } from "../_internal/panel-cookie";
+import { getLocale } from "../server/locale";
+import { panelContextConsent } from "../services/panel-context-consent";
+import { visiblePanelProviders } from "./app-navigation";
+import { getRuntimeContext } from "./runtime";
+
+/** One read, only for a host page with the slot open on a consent provider. Fail closed when the store is unavailable. */
+export async function preloadPanelConsent(c: Context): Promise<void> {
+  const user = c.get("user");
+  if (!user || !c.get("runtime")) return;
+  const providers = visiblePanelProviders(getRuntimeContext(c).apps, user, getLocale(c));
+  const state = readPanelCookie(
+    c.req.header("Cookie"),
+    providers.map((provider) => provider.id),
+  );
+  const provider = state.open && providers.find((provider) => provider.id === state.provider);
+  if (!provider || !provider.consent) return;
+  // The provider's own page below its panel path renders in PanelLayout, which has no slot and never asks.
+  const scope = new URL(provider.href, "https://panel.invalid").pathname.replace(/\/$/, "");
+  if (c.req.path === scope || c.req.path.startsWith(`${scope}/`)) return;
+  let answer: { allowed: boolean; revision: number } | null = null;
+  try {
+    answer = await panelContextConsent.get(user.id, provider.id);
+  } catch {
+    // The shell shows the unanswered question, without context in the URL or messages.
+  }
+  c.set("panelConsent", { provider: provider.id, allowed: answer?.allowed ?? null, revision: answer?.revision ?? 0 });
+}

package/src/ssr/panel-context.ts

@@ -0,0 +1,10 @@
+import { PANEL_CONTEXT_PARAM, type PanelPageContext, parsePanelContextParam } from "../contracts/panel-context";
+
+/** Untrusted URL input: a selector only. Read through your server using the session's actor/accessSubject. */
+export function readPanelContext(c: { req: { raw: { url: string } } }): PanelPageContext | null {
+  try {
+    return parsePanelContextParam(new URL(c.req.raw.url).searchParams.get(PANEL_CONTEXT_PARAM));
+  } catch {
+    return null;
+  }
+}

package/src/ssr/panel-slot.browser-harness.tsx

@@ -2,12 +2,35 @@ import { AppWorkspace } from "@k2b/ui";
 import { Hono } from "hono";
 import { defineApp } from "../_internal/define-app";
 import { person } from "../_internal/define-app.test-fixture";
+import { createMePanelConsentRoutes } from "../api/me-panel-consent";
 import type { RuntimeAppMeta } from "../contracts/app";
 import type { User } from "../contracts/shared";
 import Layout from "./Layout";
 import PanelLayout from "./PanelLayout";
+import { readPanelContext } from "./panel-context";
 import type { RuntimeContext } from "./runtime";
 
+type ConsentAnswer = { allowed: boolean; revision: number };
+export const consentAnswers = new Map<string, Map<string, ConsentAnswer>>();
+export const fixtureConsent = {
+  get: async (userId: string, provider: string) => consentAnswers.get(userId)?.get(provider) ?? null,
+  list: async (userId: string, providers: string[]) =>
+    Object.fromEntries(
+      providers.flatMap((id) => {
+        const answer = consentAnswers.get(userId)?.get(id);
+        return answer === undefined ? [] : [[id, answer]];
+      }),
+    ),
+  set: async (userId: string, provider: string, allowed: boolean, revision: number) => {
+    const answers = consentAnswers.get(userId) ?? new Map<string, ConsentAnswer>();
+    if ((answers.get(provider)?.revision ?? 0) !== revision) return null;
+    const saved = { allowed, revision: revision + 1 };
+    answers.set(provider, saved);
+    consentAnswers.set(userId, answers);
+    return saved;
+  },
+};
+
 const apps: RuntimeAppMeta[] = ["fixture", "second"].map((id) => ({
   id,
   name: id === "fixture" ? "Fixture" : "Second",
@@ -29,13 +52,21 @@ type Environment = { Variables: { runtime: RuntimeContext; user: User } };
 export const server = new Hono<Environment>()
   .use(async (c, next) => {
     c.set("runtime", { apps });
-    c.set("user", person);
+    const id = c.req
+      .header("cookie")
+      ?.split(";")
+      .map((value) => value.trim())
+      .find((value) => value.startsWith("fixture_person="))
+      ?.slice("fixture_person=".length);
+    c.set("user", { ...person, ...(id ? { id } : {}) });
     await next();
   })
+  .route("/api/me", createMePanelConsentRoutes(fixtureConsent))
   .get(
     "/app/:provider/panel",
     ...probe.ssr<Environment>((c) => () => (
       <PanelLayout c={c} title="Fixture panel">
+        <output id="panel-context-probe">{JSON.stringify(readPanelContext(c))}</output>
         <label>
           Panel input
           <input aria-label="Panel input" />
@@ -52,7 +83,7 @@ export const server = new Hono<Environment>()
   .get(
     "/app/fixture/long",
     ...probe.ssr<Environment>((c) => () => (
-      <Layout c={c} title="Long fixture">
+      <Layout context={{ scope: { type: "fixture.place", id: "place1" } }} c={c} title="Long fixture">
         <button type="button" id="open-panel">
           Open fixture
         </button>
@@ -67,7 +98,7 @@ export const server = new Hono<Environment>()
   .get(
     "/app/fixture/:page?",
     ...probe.ssr<Environment>((c) => () => (
-      <Layout c={c} fullWidth fullPage title="Panel fixture">
+      <Layout context={{ scope: { type: "fixture.place", id: "place1" } }} c={c} fullWidth fullPage title="Panel fixture">
         <AppWorkspace mobileSurface="flush" class="min-h-0 flex-1">
           <AppWorkspace.Sidebar id="panel-navigation" label="Navigation">
             <AppWorkspace.SidebarDesktop>
@@ -87,6 +118,9 @@ export const server = new Hono<Environment>()
               <a href="/app/fixture/next" id="next-page">
                 Next page
               </a>
+              <button type="button" id="change-context">
+                Change place
+              </button>
               <textarea aria-label="App editor" />
             </AppWorkspace.Main>
             <AppWorkspace.Detail id="panel-fixture-detail" width="lg" open>
@@ -103,7 +137,22 @@ export const server = new Hono<Environment>()
 
 /** Runs inline during parsing and again immediately after mounting the real runtime. */
 export function panelGeometry() {
-  return [".layout-shell-content", "#cloud-panel", ".k2b-app-workspace"].map((selector) => {
+  return [
+    ".layout-shell-content",
+    "#cloud-panel",
+    ".k2b-app-workspace",
+    ".k2b-app-workspace__main",
+    ".k2b-app-workspace__detail",
+    "[data-app-workspace-detail-toggle]",
+  ].map((selector) => {
+    const rect = document.querySelector(selector)?.getBoundingClientRect();
+    return rect && { x: rect.x, y: rect.y, width: rect.width, height: rect.height };
+  });
+}
+
+/** The question, provider frame and app area stay in the same reserved rectangles through hydration. */
+export function consentGeometry() {
+  return ["[data-cloud-panel-consent]", "[data-cloud-panel-frame]", "[data-cloud-app-area]"].map((selector) => {
     const rect = document.querySelector(selector)?.getBoundingClientRect();
     return rect && { x: rect.x, y: rect.y, width: rect.width, height: rect.height };
   });

package/src/ssr/platform-messages.ts

@@ -19,6 +19,15 @@ export const platformMessages = i18n.define({
       panelLoading: ({ label }: { label: string }) => `${label} is loading`,
       enlargePanel: "Enlarge panel",
       shrinkPanel: "Shrink panel",
+      panelConsentTitle: ({ app }: { app: string }) => `May ${app} see where you are?`,
+      panelConsentBody: ({ app }: { app: string }) =>
+        `${app} only learns which place you are at. It can read only what you may read yourself. You can change this in the ⋯ menu at any time.`,
+      panelConsentAllow: "Allow",
+      panelConsentDeny: "Don't share",
+      panelMenu: "Panel menu",
+      panelFrom: ({ app }: { app: string }) => `Panel from ${app}`,
+      panelShareContext: "Share context",
+      panelConsentSaveError: "Not saved. Try again.",
       printFallbackTitle: "This view does not print well.",
       printFallbackHint: "Open the item you want to print, or use the app's export.",
       admin: "Admin",
@@ -108,6 +117,15 @@ export const platformMessages = i18n.define({
       panelLoading: ({ label }: { label: string }) => `${label} lädt`,
       enlargePanel: "Panel vergrößern",
       shrinkPanel: "Panel verkleinern",
+      panelConsentTitle: ({ app }: { app: string }) => `Darf ${app} sehen, wo du gerade bist?`,
+      panelConsentBody: ({ app }: { app: string }) =>
+        `${app} erfährt nur, an welchem Ort du gerade bist. Lesen kann es nur, was du selbst lesen darfst. Du kannst das im Menü ⋯ jederzeit ändern.`,
+      panelConsentAllow: "Erlauben",
+      panelConsentDeny: "Nicht teilen",
+      panelMenu: "Panel-Menü",
+      panelFrom: ({ app }: { app: string }) => `Panel von ${app}`,
+      panelShareContext: "Kontext teilen",
+      panelConsentSaveError: "Nicht gespeichert. Versuche es erneut.",
       printFallbackTitle: "Diese Ansicht lässt sich nicht gut drucken.",
       printFallbackHint: "Öffne den Eintrag, den du drucken möchtest, oder nutze den Export der App.",
       admin: "Administration",

package/src/ssr/shell-data.tsx

@@ -1,6 +1,7 @@
 import type { KeyboardPlatform } from "@k2b/ui";
 import { createContext, type JSX, useContext } from "solid-js";
 import type { AppSearchLink } from "../contracts/app";
+import type { PanelConsentSnapshot, PanelPageContext } from "../contracts/panel-context";
 import type { RailSnapshot } from "../contracts/rail-preferences";
 import type { CloudThemePreference } from "../shared/theme";
 import type { AppLaunchpadLegalLink } from "./app-launchpad";
@@ -8,7 +9,7 @@ import type { PanelProvider } from "./app-navigation";
 import type { RailApp } from "./rail-navigation";
 
 export type ShellData = {
-  panel?: { providers: PanelProvider[]; provider?: string };
+  panel?: { providers: PanelProvider[]; provider?: string; context: PanelPageContext | null; consent?: PanelConsentSnapshot };
   /** The authorized navigation catalog, sorted for the request locale: the rail, the app grid and the phone menu show it. */
   apps: RailApp[];
   /** Signed-in pages: the person's rail preferences. */