@k2b/cloud 0.38.0 → 0.40.0

package/src/browser/hints.ts

@@ -0,0 +1,6 @@
+import { mergeSeenHints, parseSeenHintsCookieHeader, seenHintsSetCookie } from "../contracts/seen-hints";
+
+/** Persist dismissal before navigating or closing the hint. */
+export const markHintSeen = (id: string): void => {
+  document.cookie = seenHintsSetCookie(mergeSeenHints(parseSeenHintsCookieHeader(document.cookie), id), location.protocol === "https:");
+};

package/src/browser/live-connection.ts

@@ -10,6 +10,8 @@ export type LiveSubscriptionHandlers<T> = {
   apply: (events: { data: T; cursor: string }[]) => Promise<void>;
   /** Loads the canonical state again; events after it follow. */
   resync: () => Promise<void>;
+  /** Reports changes in whether the subscription is confirmed and has no pending work. Never called after `close()`. */
+  caughtUp?: (caughtUp: boolean) => void;
   /** The subscription ended because its resource is gone or no longer readable. */
   revoked?: (code: "not_found" | "access_denied") => void;
   /** Live updates stopped: the session ended, or `apply` or `resync` kept failing. Never called after `close()`. */
@@ -25,6 +27,7 @@ export type LiveConnection = {
 type Subscriber = {
   frame: () => unknown;
   confirmed: boolean;
+  report: () => void;
   receive: (message: LiveServerMessage) => void;
   end: () => void;
 };
@@ -56,9 +59,17 @@ const connect = (url: string, activity: "visible" | "always"): Shared => {
     onOpen: (controls) => {
       for (const subscriber of subscribers.values()) {
         subscriber.confirmed = false;
+        subscriber.report();
         controls.send(subscriber.frame());
       }
     },
+    onStatus: (status) => {
+      if (status === "open") return;
+      for (const subscriber of subscribers.values()) {
+        subscriber.confirmed = false;
+        subscriber.report();
+      }
+    },
     onMessage: (message) => {
       if (message.t === "progress") {
         for (const subscriber of subscribers.values()) if (subscriber.confirmed) subscriber.receive(message);
@@ -96,8 +107,16 @@ export const liveConnection = (url: string, options: { activity?: "visible" | "a
     let resyncAt: string | null = null;
     let ended = false;
     let running = false;
+    let caughtUp = false;
     const work: Work<T>[] = [];
 
+    const report = () => {
+      const next = !ended && subscriber.confirmed && !running && work.length === 0;
+      if (next === caughtUp) return;
+      caughtUp = next;
+      handlers.caughtUp?.(next);
+    };
+
     const attempt = async (run: () => Promise<void>): Promise<boolean> => {
       for (let tries = 0; ; tries++) {
         try {
@@ -122,6 +141,7 @@ export const liveConnection = (url: string, options: { activity?: "visible" | "a
             cursor = item.cursor;
             continue;
           }
+          report();
           const applied = item.kind === "events" ? await attempt(() => handlers.apply(item.events)) : await attempt(handlers.resync);
           if (!applied) {
             // A closed subscription reports nothing: its owner ended it.
@@ -135,6 +155,7 @@ export const liveConnection = (url: string, options: { activity?: "visible" | "a
         }
       } finally {
         running = false;
+        report();
       }
     };
 
@@ -153,6 +174,7 @@ export const liveConnection = (url: string, options: { activity?: "visible" | "a
         return { t: "sub", id, channel, scope, ...(after ? { after } : {}) };
       },
       confirmed: false,
+      report,
       receive: (message) => {
         if (ended) return;
         if (message.t === "revoked") {
@@ -189,10 +211,12 @@ export const liveConnection = (url: string, options: { activity?: "visible" | "a
       },
     };
 
-    const stop = () => {
+    const stop = (notify = true) => {
       if (ended) return;
       ended = true;
       work.length = 0;
+      if (notify) report();
+      else caughtUp = false;
       if (subscribers.get(id) !== subscriber) return;
       subscribers.delete(id);
       socket.send({ t: "unsub", id });
@@ -205,6 +229,6 @@ export const liveConnection = (url: string, options: { activity?: "visible" | "a
     subscribers.set(id, subscriber);
     if (subscribers.size === 1) socket.connect();
     else socket.send(subscriber.frame());
-    return { close: stop };
+    return { close: () => stop(false) };
   },
 });

package/src/browser/navigation-apps.ts

@@ -0,0 +1,7 @@
+import { readShellData } from "../ssr/shell-data";
+
+/** Navigation controls discoverability, never authorization; the target application still checks access. */
+export const navigationApps = (): { appIds: ReadonlySet<string>; currentAppId?: string } => {
+  const shell = readShellData();
+  return { appIds: new Set(shell?.apps.map((app) => app.id) ?? []), currentAppId: shell?.appId };
+};

package/src/browser/panel-context-bridge.ts

@@ -0,0 +1,30 @@
+import type { CloudResourceRef } from "../contracts/capabilities";
+import type { PanelPageContext } from "../contracts/panel-context";
+
+export const PAGE_CONTEXT_COLLECT = "cloud.page-context.collect";
+export const PAGE_CONTEXT_CHANGED = "cloud.page-context.changed";
+export const PANEL_CONTEXT_CHANGED = "cloud.panel.context.changed";
+export const PANEL_CONTEXT_ELEMENT = "cloud-panel-context";
+export const PANEL_SHORTCUTS_ELEMENT = "cloud-panel-shortcuts";
+export const PANEL_SHORTCUTS_CHANGED = "cloud.panel.shortcuts.changed";
+export type PageContextSource = { scope?: CloudResourceRef };
+export type PageContextCollection = { sources: PageContextSource[] };
+export type PanelConsentRequest = { provider: string; allowed: boolean };
+export type PanelState = { provider: string; appName: string; consent: boolean; allowed: boolean; saving: boolean; open: boolean };
+
+declare global {
+  interface WindowEventMap {
+    "cloud.panel.consent": CustomEvent<PanelConsentRequest>;
+    "cloud.panel.state": CustomEvent<PanelState>;
+  }
+}
+
+/** Framework-validated SSR data, then receiver-validated messages. Shared DOM state survives independent bundles. */
+export function readProviderContext(): PanelPageContext | null {
+  if (typeof document === "undefined") return null;
+  try {
+    return JSON.parse(document.getElementById(PANEL_CONTEXT_ELEMENT)?.textContent ?? "null");
+  } catch {
+    return null;
+  }
+}

package/src/browser/panel-context-receiver.ts

@@ -0,0 +1,53 @@
+import { isPanelContextMessage } from "../contracts/panel-context-plain";
+import {
+  PANEL_CONTEXT_CHANGED,
+  PANEL_CONTEXT_ELEMENT,
+  PANEL_SHORTCUTS_CHANGED,
+  PANEL_SHORTCUTS_ELEMENT,
+  readProviderContext,
+} from "./panel-context-bridge";
+
+/** Installed only by an embedded PanelRuntime; the public page publisher never imports validation. */
+export function installPanelContextReceiver(): () => void {
+  let element = document.getElementById(PANEL_CONTEXT_ELEMENT);
+  if (!element) {
+    element = document.createElement("script");
+    element.id = PANEL_CONTEXT_ELEMENT;
+    element.setAttribute("type", "application/json");
+    element.textContent = "null";
+    document.body.append(element);
+  }
+  let shortcutsElement = document.getElementById(PANEL_SHORTCUTS_ELEMENT);
+  if (!shortcutsElement) {
+    shortcutsElement = document.createElement("script");
+    shortcutsElement.id = PANEL_SHORTCUTS_ELEMENT;
+    shortcutsElement.setAttribute("type", "application/json");
+    shortcutsElement.textContent = "[]";
+    document.body.append(shortcutsElement);
+  }
+  const first = readProviderContext();
+  let pageId = first?.pageId;
+  let seq = first?.seq ?? 0;
+  const receive = (event: MessageEvent<unknown>) => {
+    if (event.source !== window.parent || event.origin !== location.origin || !isPanelContextMessage(event.data)) return;
+    const context = event.data.context;
+    if (context) {
+      if ((pageId !== undefined && context.pageId !== pageId) || context.seq < seq) return;
+      pageId = context.pageId;
+      seq = context.seq;
+    }
+    // Null revokes the current context without forgetting document identity or ordering.
+    const contextJson = JSON.stringify(context);
+    const contextChanged = element.textContent !== contextJson;
+    element.textContent = contextJson;
+    const shortcuts = JSON.stringify(context ? (event.data.shortcuts ?? []) : []);
+    const shortcutsChanged = shortcutsElement.textContent !== shortcuts;
+    shortcutsElement.textContent = shortcuts;
+    // Remember accepted snapshots, including empty ones, across Help remounts.
+    shortcutsElement.setAttribute("data-received", "");
+    if (shortcutsChanged) window.dispatchEvent(new Event(PANEL_SHORTCUTS_CHANGED));
+    if (contextChanged || !shortcutsChanged) window.dispatchEvent(new Event(PANEL_CONTEXT_CHANGED));
+  };
+  window.addEventListener("message", receive);
+  return () => window.removeEventListener("message", receive);
+}

package/src/browser/panel-menu.tsx

@@ -0,0 +1,56 @@
+import { Dropdown } from "@k2b/ui";
+import { createSignal, onCleanup, onMount } from "solid-js";
+import { platformMessages } from "../ssr/platform-messages";
+import type { PanelState } from "./panel-context-bridge";
+
+/**
+ * The slot head's ⋯ menu for providers that need consent. The lazy slot controller mounts it over the server's
+ * placeholder button, so it costs no island and can never change an answer before the controller listens. Only
+ * document events cross the menu/controller boundary.
+ */
+export default function PanelMenu(props: { initial: PanelState; locale: string }) {
+  const t = () => platformMessages.resolve([props.locale]).t;
+  const [state, setState] = createSignal(props.initial);
+  const [open, setOpen] = createSignal(false);
+  onMount(() => {
+    const changed = (event: CustomEvent<PanelState>) => {
+      // A closed slot, another provider or one without consent leaves no reason for the menu to stay expanded.
+      if (!event.detail.open || event.detail.provider !== state().provider || !event.detail.consent) setOpen(false);
+      setState(event.detail);
+    };
+    window.addEventListener("cloud.panel.state", changed);
+    onCleanup(() => window.removeEventListener("cloud.panel.state", changed));
+  });
+  return (
+    <Dropdown.Root
+      open={open()}
+      onOpenChange={setOpen}
+      label={t().panelMenu}
+      position="bottom-left"
+      items={[
+        {
+          sectionLabel: t().panelFrom({ app: state().appName }),
+          items: [
+            {
+              label: t().panelShareContext,
+              choice: "checkbox",
+              // A getter: the menu keeps its rows, so a plain value would show the answer from when it opened.
+              checked: () => state().allowed,
+              disabled: state().saving,
+              action: () =>
+                window.dispatchEvent(
+                  new CustomEvent("cloud.panel.consent", {
+                    detail: { provider: state().provider, allowed: !state().allowed },
+                  }),
+                ),
+            },
+          ],
+        },
+      ]}
+    >
+      <Dropdown.Trigger iconOnly label={t().panelMenu} disabled={!state().consent}>
+        <i class="ti ti-dots" aria-hidden="true" />
+      </Dropdown.Trigger>
+    </Dropdown.Root>
+  );
+}

package/src/browser/panel-messages.ts

@@ -0,0 +1,35 @@
+const isRecord = (value: unknown): value is Record<string, unknown> => typeof value === "object" && value !== null && !Array.isArray(value);
+
+export function isPanelReadyMessage(value: unknown, provider: string): value is { type: "cloud.panel.ready"; v: 1; provider: string } {
+  return (
+    isRecord(value) &&
+    Reflect.ownKeys(value).length === 3 &&
+    Object.hasOwn(value, "type") &&
+    Object.hasOwn(value, "v") &&
+    Object.hasOwn(value, "provider") &&
+    value.type === "cloud.panel.ready" &&
+    value.v === 1 &&
+    typeof value.provider === "string" &&
+    value.provider === provider
+  );
+}
+
+export function isPanelSearchMessage(value: unknown): value is { type: "cloud.panel.search"; v: 1 } {
+  return (
+    isRecord(value) &&
+    Reflect.ownKeys(value).length === 2 &&
+    Object.hasOwn(value, "type") &&
+    Object.hasOwn(value, "v") &&
+    value.type === "cloud.panel.search" &&
+    value.v === 1
+  );
+}
+
+export function isPanelCloseMessage(value: unknown): value is { type: "cloud.panel.close"; v?: 1 } {
+  return (
+    isRecord(value) &&
+    Object.hasOwn(value, "type") &&
+    value.type === "cloud.panel.close" &&
+    (Reflect.ownKeys(value).length === 1 || (Reflect.ownKeys(value).length === 2 && Object.hasOwn(value, "v") && value.v === 1))
+  );
+}

package/src/browser/panel-shortcuts.ts

@@ -0,0 +1,31 @@
+import { isPanelContextMessage } from "../contracts/panel-context-plain";
+import type { HelpShortcut } from "../ssr/layout-help-start";
+import { PANEL_SHORTCUTS_CHANGED, PANEL_SHORTCUTS_ELEMENT, readProviderContext } from "./panel-context-bridge";
+
+/** Only platform Help code imports this module; third-party providers never receive a list. */
+export function readPanelShortcuts(): HelpShortcut[] {
+  if (typeof document === "undefined") return [];
+  try {
+    const shortcuts: unknown = JSON.parse(document.getElementById(PANEL_SHORTCUTS_ELEMENT)?.textContent ?? "[]");
+    const message = {
+      type: "cloud.panel.context",
+      v: 1,
+      context: readProviderContext(),
+      shortcuts,
+    };
+    return isPanelContextMessage(message) ? (message.shortcuts ?? []) : [];
+  } catch {
+    return [];
+  }
+}
+
+export function panelShortcutsReceived(): boolean {
+  if (typeof document === "undefined") return false;
+  return document.getElementById(PANEL_SHORTCUTS_ELEMENT)?.hasAttribute("data-received") ?? false;
+}
+
+export function onPanelShortcutsChange(cb: (shortcuts: HelpShortcut[]) => void): () => void {
+  const changed = () => cb(readPanelShortcuts());
+  window.addEventListener(PANEL_SHORTCUTS_CHANGED, changed);
+  return () => window.removeEventListener(PANEL_SHORTCUTS_CHANGED, changed);
+}