@k2b/cloud 0.39.0 → 0.41.0

package/src/shared-text/documents.ts

@@ -0,0 +1,142 @@
+import type { Topic } from "@k2b/sync";
+import * as Y from "yjs";
+import { compareStreamCursor } from "./cursor";
+import { SHARED_TEXT_NAME, sharedTextNodeId, toBase64 } from "./events";
+import { minimalTextDiff } from "./text-diff";
+import type {
+  SharedTextActor,
+  SharedTextContributor,
+  SharedTextEditResult,
+  SharedTextSnapshot,
+  SharedTextStore,
+  SharedTextStoredState,
+  SharedTextSyncEvent,
+} from "./types";
+
+type DocumentLog = {
+  topic(): Pick<Topic<SharedTextSyncEvent>, "latestCursor" | "publish">;
+  replay(config: {
+    docId: string;
+    after: string | null;
+    until: string;
+    doc: Y.Doc;
+    signal?: AbortSignal;
+  }): Promise<SharedTextContributor[]>;
+};
+
+/**
+ * Fallback text becomes the same Yjs items in every copy: an update published
+ * against one copy then applies to the next one, which a random client ID
+ * would leave pending and silently drop from the saved state.
+ */
+const FALLBACK_CLIENT_ID = 0;
+
+const createDoc = (stored: SharedTextStoredState): Y.Doc => {
+  const doc = new Y.Doc({ gc: true });
+  try {
+    if (stored.state) Y.applyUpdate(doc, stored.state, "snapshot");
+    else if (stored.text) {
+      const clientID = doc.clientID;
+      doc.clientID = FALLBACK_CLIENT_ID;
+      doc.getText(SHARED_TEXT_NAME).insert(0, stored.text);
+      doc.clientID = clientID;
+    }
+    return doc;
+  } catch (error) {
+    doc.destroy();
+    throw error;
+  }
+};
+
+export const bindDocuments = <Saved, Context>({ topic, replay }: DocumentLog, store: SharedTextStore<Saved, Context>) => {
+  return {
+    async read(docId: string, options: { signal?: AbortSignal } = {}): Promise<SharedTextSnapshot | null> {
+      const stored = await store.load(docId, options);
+      if (!stored) return null;
+      const latest = await topic().latestCursor({ tenantId: docId });
+      if (!latest || (stored.cursor && compareStreamCursor(latest, stored.cursor) <= 0))
+        return { state: stored.state, text: stored.text, cursor: stored.cursor };
+      const doc = createDoc(stored);
+      try {
+        await replay({ docId, after: stored.cursor, until: latest, doc, signal: options.signal });
+        return { state: Y.encodeStateAsUpdate(doc), text: doc.getText(SHARED_TEXT_NAME).toString(), cursor: latest };
+      } finally {
+        doc.destroy();
+      }
+    },
+    async edit(
+      docId: string,
+      options: { actor: SharedTextActor | null; context?: Context; signal?: AbortSignal },
+      update: (current: { text: string; contributors: SharedTextContributor[]; state(): Uint8Array }) => string | Promise<string>,
+    ): Promise<SharedTextEditResult<Saved>> {
+      const requestedAt = Date.now();
+      const stored = await store.load(docId, { signal: options.signal });
+      if (!stored) return { status: "notFound" };
+      const handle = topic();
+      const target = await handle.latestCursor({ tenantId: docId });
+      const doc = createDoc(stored);
+      try {
+        let contributors: SharedTextContributor[] = [];
+        try {
+          if (target) contributors = await replay({ docId, after: stored.cursor, until: target, doc, signal: options.signal });
+        } catch (error) {
+          // A cancelled request is not a sync failure: it throws like every other abort before publication.
+          options.signal?.throwIfAborted();
+          return { status: "syncFailed", error };
+        }
+        options.signal?.throwIfAborted();
+        const ytext = doc.getText(SHARED_TEXT_NAME);
+        const text = ytext.toString();
+        const next = await update({ text, contributors, state: () => Y.encodeStateAsUpdate(doc) });
+        if (next === text) return { status: "unchanged", text };
+        // A request cancelled while the callback ran must not publish a write.
+        options.signal?.throwIfAborted();
+        const diff = minimalTextDiff(text, next);
+        const beforeEditState = Y.encodeStateVector(doc);
+        doc.transact(() => {
+          if (diff.deleteCount > 0) ytext.delete(diff.index, diff.deleteCount);
+          if (diff.insert.length > 0) ytext.insert(diff.index, diff.insert);
+        }, "cli-edit");
+        const actor = options.actor;
+        const published = await handle.publish({
+          tenantId: docId,
+          data: {
+            kind: "sync",
+            payload: toBase64(Y.encodeStateAsUpdate(doc, beforeEditState)),
+            originNodeId: sharedTextNodeId,
+            originPeerId: null,
+            ...(actor ? { actor } : {}),
+          },
+        });
+        let persistedDoc: Y.Doc | undefined;
+        try {
+          persistedDoc = createDoc(stored);
+          await replay({ docId, after: stored.cursor, until: published.cursor, doc: persistedDoc, signal: options.signal });
+          const persistedText = persistedDoc.getText(SHARED_TEXT_NAME).toString();
+          const credited = new Map(contributors.map((contributor) => [`${contributor.kind}:${contributor.id}`, contributor]));
+          if (actor) credited.set(`${actor.kind}:${actor.id}`, { ...actor, lastContributedAt: new Date(requestedAt) });
+          const saved = await store.save(
+            docId,
+            {
+              state: Y.encodeStateAsUpdate(persistedDoc),
+              text: persistedText,
+              cursor: published.cursor,
+              restoreRevision: stored.restoreRevision,
+              requestedAt,
+              actor,
+              contributors: [...credited.values()],
+            },
+            options.context,
+          );
+          return { status: "edited", text: persistedText, cursor: published.cursor, saved };
+        } catch (error) {
+          return { status: "persistFailed", cursor: published.cursor, error };
+        } finally {
+          persistedDoc?.destroy();
+        }
+      } finally {
+        doc.destroy();
+      }
+    },
+  };
+};

package/src/shared-text/events.ts

@@ -0,0 +1,43 @@
+import { fromBase64Strict } from "@k2b/stdlib";
+import * as Y from "yjs";
+import type { SharedTextEvent } from "./types";
+
+export const SHARED_TEXT_NAME = "codemirror";
+export const sharedTextNodeId = crypto.randomUUID();
+export const toBase64 = (data: Uint8Array): string => Buffer.from(data).toString("base64");
+export const fromBase64 = fromBase64Strict;
+
+/** A retained event cannot be decoded as a Yjs update: retrying never helps, no replay can pass it. */
+export class MalformedSharedTextEventError extends Error {
+  constructor(
+    readonly docId: string,
+    readonly cursor: string,
+    cause: unknown,
+  ) {
+    super(`Malformed sync event for document ${docId} at cursor ${cursor}: ${cause instanceof Error ? cause.message : String(cause)}`);
+    this.name = "MalformedSharedTextEventError";
+  }
+}
+
+/** Ingress check: a publish is accepted only when it is base64 of a decodable Yjs update. */
+export const isValidSharedTextUpdate = (payload: string): boolean => {
+  try {
+    Y.decodeUpdate(fromBase64(payload));
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+export const applySharedTextEvent = (doc: Y.Doc, event: { cursor: string; data: SharedTextEvent }, docId: string): void => {
+  if (event.data.kind !== "sync") return;
+  try {
+    const update = fromBase64(event.data.payload);
+    // Decode completely before mutating the document: malformed bytes must not
+    // partially integrate state before recovery skips the invalid event.
+    Y.decodeUpdate(update);
+    Y.applyUpdate(doc, update, `replay:${event.cursor}`);
+  } catch (error) {
+    throw new MalformedSharedTextEventError(docId, event.cursor, error);
+  }
+};

package/src/shared-text/index.ts

@@ -0,0 +1,12 @@
+export { compareStreamCursor, maxStreamCursor, parseStreamCursor } from "./cursor";
+export {
+  applySharedTextEvent,
+  fromBase64,
+  isValidSharedTextUpdate,
+  MalformedSharedTextEventError,
+  SHARED_TEXT_NAME,
+  sharedTextNodeId,
+  toBase64,
+} from "./events";
+export { sharedText } from "./log";
+export * from "./types";

package/src/shared-text/log.ts

@@ -0,0 +1,48 @@
+import type { TopicConfig } from "@k2b/sync";
+import type * as Y from "yjs";
+import { getProcessSync } from "../_internal/process-sync";
+import { compareStreamCursor } from "./cursor";
+import { bindDocuments } from "./documents";
+import { applySharedTextEvent } from "./events";
+import type { SharedTextContributor, SharedTextStore, SharedTextSyncEvent } from "./types";
+
+const define = (topicConfig: Readonly<Pick<TopicConfig, "id" | "retention" | "deadLetterRetention" | "maxPayloadBytes">>) => {
+  const topic = () => getProcessSync().topic<SharedTextSyncEvent>(topicConfig);
+  const replay = async (config: {
+    docId: string;
+    after: string | null;
+    until: string;
+    doc: Y.Doc;
+    signal?: AbortSignal;
+  }): Promise<SharedTextContributor[]> => {
+    const contributors = new Map<string, SharedTextContributor>();
+    const handle = topic();
+    const after = config.after ?? handle.cursorAt(0);
+    if (compareStreamCursor(after, config.until) >= 0) return [];
+    let reachedTarget = false;
+    for await (const event of handle.replay({ tenantId: config.docId, after, until: config.until, signal: config.signal })) {
+      applySharedTextEvent(config.doc, event, config.docId);
+      if (event.data.actor)
+        contributors.set(`${event.data.actor.kind}:${event.data.actor.id}`, {
+          ...event.data.actor,
+          lastContributedAt: event.publishedAt,
+        });
+      reachedTarget = event.cursor === config.until;
+    }
+    if (!reachedTarget) throw new Error(`Target cursor "${config.until}" was not reached during replay`);
+    return [...contributors.values()];
+  };
+
+  return {
+    id: topicConfig.id,
+    topicConfig,
+    topic,
+    replay,
+    withStore<Saved, Context>(store: SharedTextStore<Saved, Context>) {
+      return bindDocuments({ topic, replay }, store);
+    },
+  };
+};
+
+/** Server-only document logs. Applications authorize callers before read/edit. */
+export const sharedText = { define };

package/src/shared-text/text-diff.ts

@@ -0,0 +1,23 @@
+const splitsSurrogatePair = (text: string, index: number): boolean => {
+  const before = text.charCodeAt(index - 1);
+  const after = text.charCodeAt(index);
+  return before >= 0xd800 && before <= 0xdbff && after >= 0xdc00 && after <= 0xdfff;
+};
+
+/** One replacement retaining the shared prefix and suffix at Unicode boundaries. */
+export const minimalTextDiff = (before: string, after: string): { index: number; deleteCount: number; insert: string } => {
+  let index = 0;
+  while (index < before.length && index < after.length && before[index] === after[index]) index++;
+  if (splitsSurrogatePair(before, index) || splitsSurrogatePair(after, index)) index--;
+
+  let suffix = 0;
+  while (
+    suffix < before.length - index &&
+    suffix < after.length - index &&
+    before[before.length - suffix - 1] === after[after.length - suffix - 1]
+  )
+    suffix++;
+  if (splitsSurrogatePair(before, before.length - suffix) || splitsSurrogatePair(after, after.length - suffix)) suffix--;
+
+  return { index, deleteCount: before.length - index - suffix, insert: after.slice(index, after.length - suffix) };
+};

package/src/shared-text/types.ts

@@ -0,0 +1,41 @@
+export type SharedTextActor = { kind: "user" | "service_account"; id: string };
+
+/** Actor is optional so events retained from older deployments remain readable. */
+export type SharedTextEvent = {
+  kind: "sync" | "awareness";
+  payload: string;
+  originNodeId: string;
+  originPeerId: string | null;
+  actor?: SharedTextActor;
+};
+export type SharedTextSyncEvent = SharedTextEvent & { kind: "sync" };
+export type SharedTextContributor = SharedTextActor & { lastContributedAt: Date };
+
+/** The store anchors legacy cursors to this log before returning a snapshot. */
+export type SharedTextStoredState = {
+  state: Uint8Array | null;
+  cursor: string | null;
+  restoreRevision: string;
+  text: string | null;
+};
+export type SharedTextSaveInput = {
+  state: Uint8Array;
+  text: string;
+  cursor: string;
+  restoreRevision: string;
+  requestedAt: number;
+  actor: SharedTextActor | null;
+  contributors: SharedTextContributor[];
+};
+export type SharedTextSnapshot = { state: Uint8Array | null; text: string | null; cursor: string | null };
+export type SharedTextEditResult<Saved> =
+  | { status: "notFound" }
+  | { status: "unchanged"; text: string }
+  | { status: "syncFailed"; error: unknown }
+  | { status: "persistFailed"; cursor: string; error: unknown }
+  | { status: "edited"; text: string; cursor: string; saved: Saved };
+
+export type SharedTextStore<Saved, Context> = {
+  load(docId: string, options: { signal?: AbortSignal }): Promise<SharedTextStoredState | null>;
+  save(docId: string, input: SharedTextSaveInput, context: Context | undefined): Promise<Saved>;
+};

package/src/ssr/AdminLayout.tsx

@@ -1,5 +1,6 @@
 import { AppWorkspace } from "@k2b/ui";
 import type { JSX } from "solid-js/jsx-runtime";
+import type { PanelConsentSnapshot } from "../contracts/panel-context";
 import type { RailSnapshot } from "../contracts/rail-preferences";
 import { getLocale } from "../server/locale";
 import type { LayoutAnnouncementsState } from "../server/middleware/settings";
@@ -10,6 +11,7 @@ import { getLocalizedRuntimeContext, type RuntimeContext } from "./runtime";
 
 type Breadcrumb = { title: string; href?: string };
 type AdminLayoutContext = {
+  get(key: "panelConsent"): PanelConsentSnapshot | undefined;
   get(key: "railPreferences"): RailSnapshot | undefined;
   get(key: "user"): any;
   get(key: "page"): any;

package/src/ssr/AppLaunchpadPanel.tsx

@@ -143,7 +143,7 @@ export const AppLaunchpadPanel = (
                       <i class={shortcut.iconClass} aria-hidden="true" />
                       <AppBadge endpoint={shortcut.badge} appId={shortcut.appId} />
                     </span>
-                    <span class="max-w-full truncate text-[11px] font-medium text-primary dark:text-white">
+                    <span class="max-w-full k2b-truncate-fade text-[11px] font-medium text-primary dark:text-white">
                       {shortcut.label}
                       <Show when={badge()}>
                         <span class="sr-only">, {badge()}</span>
@@ -173,7 +173,7 @@ export const AppLaunchpadPanel = (
                   <i class={app.iconClass} />
                   <AppBadge endpoint={app.badge} appId={app.id} />
                 </span>
-                <span class="max-w-full truncate text-[11px] font-medium text-primary sm:text-xs dark:text-white">
+                <span class="max-w-full k2b-truncate-fade text-[11px] font-medium text-primary sm:text-xs dark:text-white">
                   {app.label}
                   <Show when={badge()}>
                     <span class="sr-only">, {badge()}</span>

package/src/ssr/CloudShell.island.tsx

@@ -95,7 +95,11 @@ function RailNavigation(props: { currentPath: string; panelOpen?: boolean }) {
       <div class="mt-auto shrink-0 flex flex-col items-center gap-1">
         {(data.panel?.providers.length ?? 0) > 1 && <PanelTrigger variant="rail" open={props.panelOpen} />}
         <GlobalSearchTrigger variant="rail" />
-        <LayoutHelpTrigger variant="rail" />
+        <LayoutHelpTrigger
+          variant="rail"
+          panel={data.panel?.providers.some((provider) => provider.id === "core")}
+          helpOpen={!!props.panelOpen && data.panel?.provider === "core"}
+        />
         <ProfilePreferences
           appHref={data.profile.appHref}
           avatarSrc={data.profile.avatarSrc}
@@ -148,7 +152,11 @@ function HeaderControls(props: {
         <div class="flex items-center gap-1 lg:hidden">
           {(data.panel?.providers.length ?? 0) > 1 && <PanelTrigger variant="header" open={props.panelOpen} />}
           {props.authenticated && <GlobalSearchTrigger variant="header" />}
-          <LayoutHelpTrigger variant="header" />
+          <LayoutHelpTrigger
+            variant="header"
+            panel={data.panel?.providers.some((provider) => provider.id === "core")}
+            helpOpen={!!props.panelOpen && data.panel?.provider === "core"}
+          />
           {props.launchpad && (
             <AppLaunchpadButton
               profile={