@k2b/cloud 0.22.0 → 0.24.0

package/src/ssr/ProfilePreferences.island.tsx

@@ -3,6 +3,8 @@ import type { CloudTheme } from "../shared/theme";
 import { createProfileActions } from "./profile-actions";
 
 type ProfilePreferencesProps = {
+  /** Set while the installation offers the mobile app. */
+  appHref?: string;
   avatarSrc?: string;
   initialTheme: CloudTheme;
   name: string;
@@ -10,7 +12,7 @@ type ProfilePreferencesProps = {
 };
 
 export default function ProfilePreferences(props: ProfilePreferencesProps) {
-  const { preferences, items, signOut, signingOut } = createProfileActions(props.initialTheme);
+  const { preferences, items, signOut, signingOut } = createProfileActions(props.initialTheme, props.appHref);
 
   const avatar = () => <Avatar name={props.name} src={props.avatarSrc} size="xs" />;
 
@@ -32,6 +34,12 @@ export default function ProfilePreferences(props: ProfilePreferencesProps) {
           <i class="ti ti-user-circle" aria-hidden="true" />
           <span>{preferences.messages().profileSettings}</span>
         </a>
+        {props.appHref && (
+          <a href={props.appHref} class="menu-item">
+            <i class="ti ti-device-mobile" aria-hidden="true" />
+            <span>{preferences.messages().app}</span>
+          </a>
+        )}
         <button type="button" class="menu-item" onClick={signOut} disabled={signingOut()}>
           <i class="ti ti-logout" aria-hidden="true" />
           <span>{preferences.messages().signOut}</span>

package/src/ssr/PwaLayout.tsx

@@ -0,0 +1,70 @@
+import { LocaleProvider, MobileShell, TabBar, type TabBarItem } from "@k2b/ui";
+import type { JSX } from "solid-js";
+import { PWA_SCOPE } from "../contracts/pwa";
+import { getLocale } from "../server/locale";
+import { readThemeFromCookieHeader } from "../shared/theme";
+import { visiblePwaParts } from "./app-navigation";
+import type { LayoutContext } from "./layout-context";
+import PwaRuntime from "./PwaRuntime.island";
+import { pwaMessages } from "./pwa-messages";
+import { getRuntimeContext } from "./runtime";
+import TimezoneCookie from "./TimezoneCookie.island";
+
+/** Parts with their own tab; Start lists every part and doubles as "More". */
+const TAB_PARTS = 3;
+
+export type PwaLayoutProps = {
+  /** The request context; the layout also sets the page's framing and referrer headers. */
+  c: LayoutContext & { header(name: string, value: string): void };
+  /** Header heading and document title. */
+  title: string;
+  /** Up-navigation inside the part, for example from a detail back to its list. */
+  back?: { href: string; label: string };
+  /** At most two icon buttons at the header end. */
+  actions?: JSX.Element;
+  children: JSX.Element;
+};
+
+/**
+ * The frame of every page in the installable mobile app (preview): the app's document head, a phone shell with a
+ * tab bar of Start and the first parts, and the browser runtime (service worker, offline notice, session keepalive).
+ * Pages render it below `/pwa/` with `ssr.pwaAccess`.
+ */
+export default function PwaLayout(props: PwaLayoutProps) {
+  const { c } = props;
+  const locale = getLocale(c);
+  const t = pwaMessages.resolve([locale]).t;
+  const user = c.get("user");
+  const cloud = c.get("settings")?.app?.name || "Cloud";
+  const page = c.get("page");
+  page.theme = readThemeFromCookieHeader(c.req.raw.headers.get("Cookie"));
+  page.title = props.title;
+  page.pwa = { name: cloud };
+  // No app page may be framed, and none leaks its address to another site.
+  c.header("Referrer-Policy", "no-referrer");
+  c.header("Content-Security-Policy", "frame-ancestors 'none'");
+
+  const parts = visiblePwaParts(getRuntimeContext(c).apps, user, locale);
+  const path = new URL(c.req.raw.url).pathname;
+  const tabs = parts.slice(0, TAB_PARTS);
+  const currentTab = tabs.find((part) => path === part.pwa.href || path.startsWith(`${part.pwa.href}/`));
+  // Start is titled with the installation's name; a part's first page carries the part's name.
+  const items: TabBarItem[] = [
+    { id: "start", label: t.start, title: cloud, icon: "ti ti-home", href: PWA_SCOPE, current: !currentTab },
+    ...tabs.map((part) => ({ id: part.id, label: part.name, icon: part.icon, href: part.pwa.href, current: part === currentTab })),
+  ];
+
+  return (
+    <LocaleProvider locale={locale}>
+      {/* Pages without a person show no times. Their pairing link lives only in memory, and a reload would lose it. */}
+      <TimezoneCookie reload={!!user} />
+      <MobileShell
+        header={<MobileShell.Header title={props.title} back={props.back} actions={props.actions} />}
+        footer={user && parts.length > 0 ? <TabBar label={t.tabs} items={items} /> : undefined}
+      >
+        {props.children}
+      </MobileShell>
+      <PwaRuntime keepalive={!!user} cloud={cloud} />
+    </LocaleProvider>
+  );
+}

package/src/ssr/PwaRuntime.island.tsx

@@ -0,0 +1,105 @@
+import { observeMobileShell, syncThemeColor, type ToastHandle, toast, useLocale } from "@k2b/ui";
+import { onCleanup, onMount } from "solid-js";
+import { renewAppSession } from "../browser/app-session";
+import { PWA_SCOPE, PWA_SERVICE_WORKER_PATH } from "../contracts/pwa";
+import { pwaMessages } from "./pwa-messages";
+
+/** Set once per browsing session, so the first page renews and later navigations do not. */
+const RENEWED_MARKER = "cloud.pwa.renewed";
+const KEEPALIVE_INTERVAL_MS = 60 * 60 * 1000;
+/** Matches `cloud:theme-preference` in the preference controller. */
+const THEME_PREFERENCE_EVENT = "cloud:theme-preference";
+
+export type PwaRuntimeProps = {
+  /** A person uses the app: keep the app session alive. */
+  keepalive: boolean;
+  /** The installation name, for the account notice. */
+  cloud: string;
+};
+
+const firstPageOfSession = (): boolean => {
+  try {
+    if (window.sessionStorage.getItem(RENEWED_MARKER)) return false;
+    window.sessionStorage.setItem(RENEWED_MARKER, "1");
+  } catch {}
+  return true;
+};
+
+/**
+ * The browser side of every mobile app page: the service worker, the offline notice, the app session keepalive,
+ * the status bar colour after a theme change, and the server-rendered shell's measurements.
+ */
+export default function PwaRuntime(props: PwaRuntimeProps) {
+  const locale = useLocale();
+  const t = () => pwaMessages.resolve([locale()]).t;
+
+  onMount(() => {
+    const cleanups: (() => void)[] = [];
+    onCleanup(() => {
+      for (const cleanup of cleanups) cleanup();
+    });
+
+    const shell = document.querySelector<HTMLElement>(".k2b-mobile-shell");
+    if (shell) cleanups.push(observeMobileShell(shell));
+
+    // The launch bounce marks its return; the page is here now, so the marker leaves the address.
+    const url = new URL(location.href);
+    if (url.searchParams.has("pwa_launch")) {
+      url.searchParams.delete("pwa_launch");
+      history.replaceState(history.state, "", url.pathname + url.search + url.hash);
+    }
+
+    // Registration fails in private windows and insecure contexts; the app then simply works online only.
+    void navigator.serviceWorker?.register(PWA_SERVICE_WORKER_PATH, { scope: PWA_SCOPE, updateViaCache: "none" }).catch(() => undefined);
+
+    let offlineToast: ToastHandle | undefined;
+    const offline = () => {
+      offlineToast ??= toast(t().offline, { duration: 0, iconClass: "ti ti-wifi-off" });
+    };
+    const online = () => {
+      offlineToast?.dismiss();
+      offlineToast = undefined;
+    };
+    if (!navigator.onLine) offline();
+    window.addEventListener("offline", offline);
+    window.addEventListener("online", online);
+    cleanups.push(() => {
+      window.removeEventListener("offline", offline);
+      window.removeEventListener("online", online);
+      offlineToast?.dismiss();
+    });
+
+    const syncTheme = () => syncThemeColor();
+    window.addEventListener(THEME_PREFERENCE_EVENT, syncTheme);
+    cleanups.push(() => window.removeEventListener(THEME_PREFERENCE_EVENT, syncTheme));
+
+    if (!props.keepalive) return;
+
+    let otherAccountShown = false;
+    let disposed = false;
+    cleanups.push(() => {
+      disposed = true;
+    });
+    const renew = async () => {
+      const { otherAccount } = await renewAppSession();
+      if (disposed || !otherAccount || otherAccountShown) return;
+      otherAccountShown = true;
+      toast(t().otherAccount({ cloud: props.cloud, name: otherAccount.name }), { duration: 0, iconClass: "ti ti-alert-triangle" });
+    };
+
+    if (firstPageOfSession()) void renew();
+    const visible = () => {
+      if (document.visibilityState === "visible") void renew();
+    };
+    document.addEventListener("visibilitychange", visible);
+    const timer = setInterval(() => {
+      if (document.visibilityState === "visible") void renew();
+    }, KEEPALIVE_INTERVAL_MS);
+    cleanups.push(() => {
+      document.removeEventListener("visibilitychange", visible);
+      clearInterval(timer);
+    });
+  });
+
+  return null;
+}

package/src/ssr/TimezoneCookie.island.tsx

@@ -2,12 +2,18 @@ import { cookies } from "@k2b/stdlib/browser";
 import { onMount } from "solid-js";
 import { TIMEZONE_COOKIE } from "../shared/time";
 
-export default function TimezoneCookie() {
+export type TimezoneCookieProps = {
+  /** Reload once after a timezone change, so the page shows times in the browser's zone. Defaults to `true`. */
+  reload?: boolean;
+};
+
+export default function TimezoneCookie(props: TimezoneCookieProps) {
   onMount(() => {
     const timeZone = Intl.DateTimeFormat().resolvedOptions().timeZone;
     const current = cookies.readCookie(TIMEZONE_COOKIE);
     if (timeZone && current !== timeZone) {
       cookies.writeCookie(TIMEZONE_COOKIE, timeZone);
+      if (props.reload === false) return;
       try {
         if (sessionStorage.getItem("cloud.timezone.reload") !== timeZone) {
           sessionStorage.setItem("cloud.timezone.reload", timeZone);

package/src/ssr/app-navigation.ts

@@ -1,5 +1,7 @@
 import type { RuntimeAppMeta } from "../contracts/app";
-import { hasRole, type User } from "../contracts/shared";
+import { isPwaPartId } from "../contracts/pwa";
+import { hasRole, type Role, type User } from "../contracts/shared";
+import { resolveAppPresentation } from "../shared/app-presentation";
 
 export type VisibleNavigationApp = RuntimeAppMeta & {
   nav: NonNullable<RuntimeAppMeta["nav"]>;
@@ -25,17 +27,30 @@ export const hasDedicatedRuntimeRoute = (apps: readonly RuntimeAppMeta[], pathna
   return !!match && match.app.id !== currentAppId;
 };
 
+const hasAnyRole = (user: User | undefined, roles: readonly Role[] | undefined): boolean =>
+  !roles || (!!user && roles.some((role) => (role === "guest" ? user.profile === "guest" : hasRole(user, role))));
+
 /** Apps rendered in the navigation for a given authenticated user. */
 export const visibleNavigationApps = (apps: readonly RuntimeAppMeta[], user: User | undefined): VisibleNavigationApp[] =>
   apps.filter(
     (app): app is VisibleNavigationApp =>
-      !!app.nav &&
-      app.nav.section !== "hidden" &&
-      (!app.nav.requiresAuth || !!user) &&
-      (!app.nav.requiresRoles ||
-        (!!user &&
-          app.nav.requiresRoles.some((role) => {
-            if (role === "guest") return user.profile === "guest";
-            return hasRole(user, role);
-          }))),
+      !!app.nav && app.nav.section !== "hidden" && (!app.nav.requiresAuth || !!user) && hasAnyRole(user, app.nav.requiresRoles),
   );
+
+export type VisiblePwaPart = RuntimeAppMeta & { pwa: NonNullable<RuntimeAppMeta["pwa"]> };
+
+/**
+ * Parts of the mobile app the user may see, localized and sorted by name. Empty without a user. The roles are
+ * coarse visibility like the navigation's; part routes and services still authorize.
+ */
+export const visiblePwaParts = (apps: readonly RuntimeAppMeta[], user: User | undefined, locale: string): VisiblePwaPart[] => {
+  if (!user) return [];
+  // Like the gateway, which routes /pwa/<id> only to a valid part id that claims it.
+  return apps
+    .filter(
+      (app): app is VisiblePwaPart =>
+        !!app.pwa && isPwaPartId(app.id) && app.routes.includes(app.pwa.href) && hasAnyRole(user, app.pwa.requiresRoles),
+    )
+    .map((app) => resolveAppPresentation(app, locale))
+    .sort((a, b) => a.name.localeCompare(b.name, locale) || a.id.localeCompare(b.id));
+};

package/src/ssr/index.ts

@@ -2,13 +2,20 @@
 // Do NOT import from this barrel in .island.tsx or .client.tsx files!
 
 export { default as AdminLayout } from "./AdminLayout";
-export { hasDedicatedRuntimeRoute, resolveRuntimeRoute, visibleNavigationApps } from "./app-navigation";
+export {
+  hasDedicatedRuntimeRoute,
+  resolveRuntimeRoute,
+  type VisiblePwaPart,
+  visibleNavigationApps,
+  visiblePwaParts,
+} from "./app-navigation";
 export { default as Layout } from "./Layout";
 export {
   default as MinimalLayout,
   type MinimalLayoutPreferencePosition,
   type MinimalLayoutProps,
 } from "./MinimalLayout";
+export { default as PwaLayout, type PwaLayoutProps } from "./PwaLayout";
 export { requestPath } from "./request-path";
 export { getLocalizedRuntimeContext, getRuntimeContext, type RuntimeContext } from "./runtime";
 export type { UrlFilterField } from "./url-filter";

package/src/ssr/layout-context.ts

@@ -6,7 +6,7 @@ import type { RuntimeContext } from "./runtime";
 export type LayoutContext = {
   get(key: "user"): User | undefined;
   get(key: "railPreferences"): RailSnapshot | undefined;
-  get(key: "page"): { theme?: "light" | "dark" };
+  get(key: "page"): { theme?: "light" | "dark"; title?: string; pwa?: { name: string } };
   get(key: "runtime"): RuntimeContext;
   get(key: "announcements"): LayoutAnnouncementsState | undefined;
   /** Every application settings snapshot includes Core's app metadata. */

package/src/ssr/preference-controller.ts

@@ -1,6 +1,6 @@
 import type { DropdownItem } from "@k2b/ui";
 import { createMemo, createSignal, onCleanup, onMount } from "solid-js";
-import { profilePreferenceLocale, setLocalePreference } from "../browser/locale-preference";
+import { profilePreferenceLocale, setLocalePreference } from "../shared/locale-preference";
 import { type CloudTheme, getCurrentThemePreference, setThemePreference } from "../shared/theme";
 import { profilePreferencesMessages } from "./profile-preferences-messages";
 
@@ -40,5 +40,5 @@ export const createPreferenceController = (initialTheme: CloudTheme, locale: ()
     },
   ]);
 
-  return { items, languageLabel, messages, theme, themeLabel, toggleLanguage, toggleTheme };
+  return { items, language, languageLabel, messages, theme, themeLabel, toggleLanguage, toggleTheme };
 };

package/src/ssr/profile-actions.ts

@@ -5,7 +5,8 @@ import { apiClient } from "../clients/core";
 import type { CloudTheme } from "../shared/theme";
 import { createPreferenceController } from "./preference-controller";
 
-export function createProfileActions(initialTheme: CloudTheme) {
+/** `appHref` is set while the installation offers the mobile app; the item then leads to `/me/app`. */
+export function createProfileActions(initialTheme: CloudTheme, appHref?: string) {
   const locale = useLocale();
   const preferences = createPreferenceController(initialTheme, locale);
   const [signingOut, setSigningOut] = createSignal(false);
@@ -30,6 +31,7 @@ export function createProfileActions(initialTheme: CloudTheme) {
       icon: "ti ti-user-circle",
       label: preferences.messages().profileSettings,
     },
+    ...(appHref ? [{ href: appHref, icon: "ti ti-device-mobile", label: preferences.messages().app }] : []),
     {
       action: signOut,
       icon: "ti ti-logout",

package/src/ssr/profile-preferences-messages.ts

@@ -9,6 +9,7 @@ export const profilePreferencesMessages = i18n.define({
       language: "Language",
       legalLinks: "Legal",
       profileSettings: "Profile settings",
+      app: "App",
       signOut: "Sign out",
       signOutFailed: "Sign out failed. Please try again.",
       switchToDark: "Dark mode",
@@ -22,6 +23,7 @@ export const profilePreferencesMessages = i18n.define({
       language: "Sprache",
       legalLinks: "Rechtliches",
       profileSettings: "Profileinstellungen",
+      app: "App",
       signOut: "Abmelden",
       signOutFailed: "Abmelden fehlgeschlagen. Bitte versuche es erneut.",
       switchToDark: "Dunkler Modus",

package/src/ssr/pwa-messages.ts

@@ -0,0 +1,24 @@
+import { i18n } from "@k2b/stdlib";
+
+/** Strings of the mobile app's frame: the tab bar, the offline notice and the account notice. */
+export const pwaMessages = i18n.define({
+  baseLocale: "en",
+  messages: {
+    en: {
+      tabs: "App",
+      start: "Start",
+      offline: "You're offline",
+      otherAccount: ({ cloud, name }: { cloud: string; name: string }) =>
+        `Chrome on this phone is signed in to ${cloud} as ${name}. Changes in the app may be saved to that account. Sign out of ${cloud} in Chrome.`,
+      errorAction: "Back to Start",
+    },
+    de: {
+      tabs: "App",
+      start: "Start",
+      offline: "Du bist offline",
+      otherAccount: ({ cloud, name }: { cloud: string; name: string }) =>
+        `Chrome auf diesem Telefon ist bei ${cloud} als ${name} angemeldet. Änderungen in der App werden womöglich in diesem Konto gespeichert. Melde dich in Chrome von ${cloud} ab.`,
+      errorAction: "Zurück zum Start",
+    },
+  },
+});

package/src/styles/global.css

@@ -239,6 +239,12 @@ body {
   color: rgb(244 244 245); /* zinc-100 */
 }
 
+/* Pages of the mobile app paint the shell canvas, which their theme-color and
+   html background repeat for the status bar. */
+html:has(.k2b-mobile-shell) body {
+  background-color: var(--k2b-surface-canvas);
+}
+
 .dark {
   color-scheme: dark;
   --color-selection-bg: rgb(59 130 246 / 0.5);

package/src/styles/resource-search.css

@@ -214,6 +214,24 @@
   color: var(--k2b-text-muted);
   font-size: 0.8125rem;
 }
+/* Apps still searching and apps that did not answer: one calm line each, below the results. */
+.cloud-resource-search__status {
+  display: grid;
+  gap: 0.125rem;
+  padding: 0 1.125rem 1.5rem;
+  color: var(--k2b-text-muted);
+  font-size: 0.8125rem;
+}
+.cloud-resource-search__status p {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 0.375rem;
+  min-height: 1.75rem;
+}
+.cloud-resource-search__status i {
+  font-size: 0.875rem;
+}
 .cloud-resource-search__tag-heading {
   display: flex;
   align-items: center;
@@ -386,6 +404,7 @@
     padding-inline: 0;
   }
   .cloud-resource-search__hint,
+  .cloud-resource-search__status,
   .cloud-resource-search__idle,
   .cloud-resource-search__footer,
   .cloud-resource-search__count,

package/src/styles/utilities-feedback.css

@@ -237,8 +237,8 @@
 }
 .k2b-ui .cloud-announcement > .k2b-icon-button {
   position: absolute;
-  top: 0.4375rem;
-  right: 0.4375rem;
+  top: 0.875rem;
+  right: 0.875rem;
 }
 
 /* Approval prose follows the surrounding review fields, not document typography. */

package/scripts/build-pdf-renderer.ts

@@ -1,39 +0,0 @@
-import { cp, mkdir } from "node:fs/promises";
-import { dirname, resolve } from "node:path";
-import { fileURLToPath } from "node:url";
-import { z } from "zod";
-
-/** Package the decoder and native assets only for bundles importing PDF vision. */
-export async function buildPdfRenderer(dist: string) {
-  const framework = resolve(dirname(fileURLToPath(import.meta.url)), "..");
-  const out = resolve(dist, "pdf-render");
-  await mkdir(out, { recursive: true });
-  const worker = await Bun.build({
-    entrypoints: [resolve(framework, "src/ai/pdf-render-worker.ts")],
-    target: "bun",
-    outdir: out,
-    naming: "worker.js",
-    external: ["pdfjs-dist", "@napi-rs/canvas"],
-  });
-  if (!worker.success) throw new Error(`PDF decoder build failed: ${worker.logs.join("\n")}`);
-  for (const name of ["pdfjs-dist", "@napi-rs/canvas"]) {
-    const source = dirname(Bun.resolveSync(`${name}/package.json`, framework));
-    await cp(source, resolve(out, "node_modules", name), { recursive: true, dereference: true });
-    if (name !== "@napi-rs/canvas") continue;
-    const manifest = z
-      .object({ optionalDependencies: z.record(z.string(), z.string()) })
-      .parse(await Bun.file(resolve(source, "package.json")).json());
-    let nativePackages = 0;
-    for (const dependency of Object.keys(manifest.optionalDependencies)) {
-      let location: string;
-      try {
-        location = dirname(Bun.resolveSync(`${dependency}/package.json`, source));
-      } catch {
-        continue;
-      } // Only the installed target-platform binary is needed.
-      await cp(location, resolve(out, "node_modules", dependency), { recursive: true, dereference: true });
-      nativePackages++;
-    }
-    if (!nativePackages) throw new Error("PDF decoder needs an installed native canvas binary for the build platform.");
-  }
-}

package/src/ai/client/live-connection.ts

@@ -1,141 +0,0 @@
-import {
-  createLiveWebSocket,
-  type LiveWebSocket,
-  type LiveWebSocketClose,
-  type LiveWebSocketError,
-  type LiveWebSocketStatus,
-} from "../../browser/live-websocket";
-import { AI_LIVE_WS_TYPE, type AiLiveServerMessage, parseAiLiveServerMessage } from "../live-events";
-import type { AiConversationStreamTransport, AiStreamConnectionStatus } from "./transport";
-
-type TurnSubscription = {
-  conversationId: string;
-  generation: number;
-  onEvent: Parameters<AiConversationStreamTransport["subscribe"]>[0]["onEvent"];
-  onStatus?: Parameters<AiConversationStreamTransport["subscribe"]>[0]["onStatus"];
-  onError?: Parameters<AiConversationStreamTransport["subscribe"]>[0]["onError"];
-};
-
-export type AiLiveConnection = {
-  connect: () => void;
-  markApplied: (cursor: string | null | undefined) => void;
-  streamTransport: AiConversationStreamTransport;
-  dispose: () => void;
-};
-
-export type CreateAiLiveConnectionOptions = {
-  url?: string;
-  initialCursor: string;
-  onLiveMessage: (message: AiLiveServerMessage) => void;
-  onLiveStatus?: (status: LiveWebSocketStatus) => void;
-  onFatal?: (error: LiveWebSocketError) => void;
-};
-
-const reconnectableAiClose = (close: LiveWebSocketClose): LiveWebSocketError | null =>
-  close.code === 1008 ? { code: close.reason || "access_denied", message: "Live access changed or expired." } : null;
-
-const streamStatus = (status: LiveWebSocketStatus): AiStreamConnectionStatus | null => {
-  if (status === "connecting" || status === "reconnecting") return status;
-  if (status === "paused") return "reconnecting";
-  return null;
-};
-
-/** One browser connection for AI invalidations and the currently visible turn. */
-export const createAiLiveConnection = (options: CreateAiLiveConnectionOptions): AiLiveConnection => {
-  let socket: LiveWebSocket;
-  let turn: TurnSubscription | null = null;
-  let turnGeneration = 0;
-  let connected = false;
-  let disposed = false;
-  let liveSubscribeCount = 0;
-
-  const sendTurnSubscription = () => {
-    if (!connected || !turn) return;
-    if (
-      !socket.send({
-        type: AI_LIVE_WS_TYPE.turnSubscribe,
-        payload: { conversationId: turn.conversationId },
-      })
-    ) {
-      turn.onStatus?.("reconnecting");
-    }
-  };
-
-  socket = createLiveWebSocket<AiLiveServerMessage>({
-    url: options.url ?? "/api/ai/live",
-    activity: "always",
-    initialCursor: options.initialCursor,
-    subscribe: (cursor) => ({
-      type: AI_LIVE_WS_TYPE.subscribe,
-      payload: { fromCursor: cursor, recover: liveSubscribeCount++ > 0 },
-    }),
-    parse: parseAiLiveServerMessage,
-    classifyClose: reconnectableAiClose,
-    onOpen: sendTurnSubscription,
-    onStatus: (status) => {
-      connected = status === "open";
-      options.onLiveStatus?.(status);
-      const next = streamStatus(status);
-      if (next) turn?.onStatus?.(next);
-    },
-    onMessage: (message) => {
-      if (message.type === AI_LIVE_WS_TYPE.turnEvent) {
-        if (!turn || turn.conversationId !== message.payload.conversationId) return;
-        if (message.payload.event.type === "state") turn.onStatus?.("open");
-        turn.onEvent(message.payload.event);
-        return;
-      }
-      if (message.type === AI_LIVE_WS_TYPE.turnError) {
-        if (!turn || turn.conversationId !== message.payload.conversationId) return;
-        const current = turn;
-        turn = null;
-        current.onError?.(new Error(message.payload.message));
-        return;
-      }
-      options.onLiveMessage(message);
-    },
-    onFatal: (error) => {
-      connected = false;
-      const current = turn;
-      turn = null;
-      current?.onError?.(new Error(error.message));
-      options.onFatal?.(error);
-    },
-  });
-
-  const streamTransport: AiConversationStreamTransport = {
-    subscribe: ({ conversationId, onEvent, onStatus, onError }) => {
-      const generation = ++turnGeneration;
-      const subscription: TurnSubscription = { conversationId, generation, onEvent, onStatus, onError };
-      turn = subscription;
-      onStatus?.("connecting");
-      sendTurnSubscription();
-      return {
-        close: () => {
-          if (turn?.generation !== generation) return;
-          turn = null;
-          if (connected) {
-            socket.send({
-              type: AI_LIVE_WS_TYPE.turnUnsubscribe,
-              payload: { conversationId },
-            });
-          }
-        },
-      };
-    },
-  };
-
-  return {
-    connect: () => {
-      if (!disposed) socket.connect();
-    },
-    markApplied: (cursor) => socket.markApplied(cursor),
-    streamTransport,
-    dispose: () => {
-      if (disposed) return;
-      disposed = true;
-      turn = null;
-      socket.dispose();
-    },
-  };
-};