@k2b/cloud 0.44.0 → 0.46.0

package/src/shared/markdown/index.ts

@@ -25,8 +25,15 @@ import { escapeHtml } from "./shared";
 // Create a configured marked instance
 type MarkdownProfile = "content" | "help";
 type LinkStyle = "widget" | "plain";
+type MarkdownOutput = "cloud" | "email";
 
-const createMarked = (profile: MarkdownProfile, links: LinkStyle, infoBlocks: MarkedExtension, locale?: string) => {
+const createMarked = (
+  profile: MarkdownProfile,
+  links: LinkStyle,
+  infoBlocks: MarkedExtension,
+  locale?: string,
+  output: MarkdownOutput = "cloud",
+) => {
   const marked = new Marked();
 
   marked.use({
@@ -38,12 +45,12 @@ const createMarked = (profile: MarkdownProfile, links: LinkStyle, infoBlocks: Ma
   // Note: katexExtension must come before codeExtension to handle ```math blocks
   marked.use(infoBlocks);
   marked.use(taskListExtension());
-  marked.use(tablesExtension());
+  marked.use(tablesExtension(output === "email"));
   // Plain output keeps marked's own link renderer and renders code blocks as a bare `pre`.
   // Cloud links are calm reference pills and quiet web links from `@k2b/ui`.
   if (links === "widget") marked.use(linksExtension({ internalTarget: profile === "help" ? "_self" : "_blank", locale }));
   marked.use(imagesExtension());
-  marked.use(katexExtension());
+  marked.use(katexExtension(output === "email"));
   marked.use(links === "widget" ? codeExtension() : plainCodeExtension());
   // Inline-style decorators come last so they run after structural tokenizers.
   marked.use(markExtension());
@@ -57,12 +64,12 @@ const createMarked = (profile: MarkdownProfile, links: LinkStyle, infoBlocks: Ma
 // headers choose the locale, and `markdownInfoBlocks()` returns one extension
 // for every locale that shares a catalog, so the cache stays bounded.
 const instances = new Map<MarkedExtension, Map<string, Marked>>();
-const markedFor = (profile: MarkdownProfile, links: LinkStyle = "widget", locale?: string): Marked => {
+const markedFor = (profile: MarkdownProfile, links: LinkStyle = "widget", locale?: string, output: MarkdownOutput = "cloud"): Marked => {
   const infoBlocks = markdownInfoBlocks({ locale });
   const byStyle = instances.get(infoBlocks) ?? new Map<string, Marked>();
   instances.set(infoBlocks, byStyle);
-  const key = `${profile}:${links}`;
-  const instance = byStyle.get(key) ?? createMarked(profile, links, infoBlocks, locale);
+  const key = `${profile}:${links}:${output}`;
+  const instance = byStyle.get(key) ?? createMarked(profile, links, infoBlocks, locale, output);
   byStyle.set(key, instance);
   return instance;
 };
@@ -70,18 +77,21 @@ const markedFor = (profile: MarkdownProfile, links: LinkStyle = "widget", locale
 const marked = markedFor("content");
 
 export type MarkdownRenderOptions = {
+  /** `"email"` keeps strikethrough and structural table alignment, and renders table formulas and math as literal source. Defaults to Cloud's styled output with formula evaluation. */
+  output?: MarkdownOutput;
   /** `"plain"` renders each link as an ordinary anchor around its text, for HTML read outside Cloud such as email. It also renders a code block, fenced or indented and including a Mermaid fence, as its source in a `pre` without the language label. The default renders references to Cloud content as calm pills and web links as quiet text links. */
   links?: LinkStyle;
   /** Request locale for the screen-reader names of untitled info blocks. Defaults to English on the server and the page language in the browser. */
   locale?: string;
 };
 
-const sanitizeRenderedHtml = (html: string, profile: MarkdownProfile = "content"): string => {
+const sanitizeRenderedHtml = (html: string, profile: MarkdownProfile = "content", output: MarkdownOutput = "cloud"): string => {
   const callouts = markdownCalloutSanitizeOptions();
   return sanitizeHtml(html, {
     ...callouts,
     allowedTags: [
       ...sanitizeHtml.defaults.allowedTags,
+      ...(output === "email" ? ["del"] : []),
       "annotation",
       "aside",
       "br",
@@ -137,6 +147,7 @@ const sanitizeRenderedHtml = (html: string, profile: MarkdownProfile = "content"
       input: ["checked", "class", "disabled", "type"],
       math: ["xmlns"],
       pre: ["class"],
+      ...(output === "email" ? { th: ["align"], td: ["align"] } : {}),
       ...callouts.allowedAttributes,
       span: ["aria-hidden", "class", "style", "title"],
     },
@@ -192,10 +203,10 @@ const sanitizeRenderedHtml = (html: string, profile: MarkdownProfile = "content"
 export function renderMarkdown(content: string, options: MarkdownRenderOptions = {}): string {
   if (!content || typeof content !== "string") return "";
 
-  const html = markedFor("content", options.links, options.locale).parse(content);
+  const html = markedFor("content", options.links, options.locale, options.output).parse(content);
   if (typeof html !== "string") return "";
 
-  return sanitizeRenderedHtml(html);
+  return sanitizeRenderedHtml(html, "content", options.output);
 }
 
 /**
@@ -204,10 +215,10 @@ export function renderMarkdown(content: string, options: MarkdownRenderOptions =
 export function renderMarkdownSync(content: string, options: MarkdownRenderOptions = {}): string {
   if (!content || typeof content !== "string") return "";
 
-  const html = markedFor("content", options.links, options.locale).parse(content);
+  const html = markedFor("content", options.links, options.locale, options.output).parse(content);
   if (typeof html !== "string") return "";
 
-  return sanitizeRenderedHtml(html);
+  return sanitizeRenderedHtml(html, "content", options.output);
 }
 
 /**

package/src/shared-text/anchors.ts

@@ -0,0 +1,29 @@
+import * as Y from "yjs";
+
+/** Capture an existing character, never a boundary that could drift to a neighbour. */
+export const captureTextAnchor = (text: Y.Text, index: number): Uint8Array => {
+  if (!text.doc || !Number.isSafeInteger(index) || index < 0 || index >= text.length)
+    throw new RangeError("A text anchor must identify an existing character in an attached Y.Text");
+  return Y.encodeRelativePosition(Y.createRelativePositionFromTypeIndex(text, index, 0));
+};
+
+/**
+ * Resolve only the original live character. Ordinary relative positions also
+ * resolve beside deleted characters and follow undo replacements; neither is
+ * a safe target for a delayed structural action.
+ */
+export const resolveTextAnchor = (text: Y.Text, bytes: Uint8Array): number | null => {
+  if (!text.doc) return null;
+  try {
+    const anchor = Y.decodeRelativePosition(bytes);
+    if (!anchor.item || anchor.assoc !== 0) return null;
+    const position = Y.createAbsolutePositionFromRelativePosition(anchor, text.doc, false);
+    if (!position || position.type !== text || position.index < 0 || position.index >= text.length) return null;
+    // Item encodings omit the root type name. Compare two decoded positions,
+    // rather than a decoded anchor with a fresh position containing that name.
+    const live = Y.decodeRelativePosition(captureTextAnchor(text, position.index));
+    return Y.compareRelativePositions(anchor, live) ? position.index : null;
+  } catch {
+    return null;
+  }
+};

package/src/shared-text/awareness.ts

@@ -0,0 +1,87 @@
+import * as decoding from "lib0/decoding";
+import * as encoding from "lib0/encoding";
+import { z } from "zod";
+
+const unsigned = z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER);
+const positionId = z.strictObject({ client: unsigned, clock: unsigned });
+const relativePosition = z
+  .strictObject({
+    type: positionId.nullable().optional(),
+    tname: z.string().nullable().optional(),
+    item: positionId.nullable().optional(),
+    assoc: z.number().int().min(Number.MIN_SAFE_INTEGER).max(Number.MAX_SAFE_INTEGER).optional(),
+  })
+  .refine((position) => position.type != null || position.tname != null);
+const stateSchema = z
+  .strictObject({
+    // Identity is supplied by the authenticated transport, never copied from here.
+    user: z.unknown().optional(),
+    cursor: z.strictObject({ anchor: relativePosition, head: relativePosition }).nullable().optional(),
+  })
+  .nullable();
+
+export class InvalidSharedTextAwarenessError extends Error {
+  constructor() {
+    super("Invalid shared text awareness update");
+    this.name = "InvalidSharedTextAwarenessError";
+  }
+}
+
+const encode = (clientId: number, clock: number, state: unknown): Uint8Array => {
+  const encoder = encoding.createEncoder();
+  encoding.writeVarUint(encoder, 1);
+  encoding.writeVarUint(encoder, clientId);
+  encoding.writeVarUint(encoder, clock);
+  encoding.writeVarString(encoder, JSON.stringify(state));
+  return encoding.toUint8Array(encoder);
+};
+
+/** One authorized connection, with an ID allocated uniquely by its transport. */
+export const createTrustedTextAwareness = (config: {
+  clientId: number;
+  textName: string;
+  user: { userId: string; name: string; color: string };
+}) => {
+  if (!Number.isSafeInteger(config.clientId) || config.clientId < 2 ** 32) throw new RangeError("Invalid server awareness ID");
+  const user = { userId: config.user.userId, name: config.user.name, color: config.user.color };
+  let localClientId: number | undefined;
+  let clock = 0;
+  let active = false;
+  const next = (state: unknown): Uint8Array => {
+    if (clock === Number.MAX_SAFE_INTEGER) throw new RangeError("Awareness clock exhausted");
+    return encode(config.clientId, ++clock, state);
+  };
+  return {
+    /** Validate one local state and replace its envelope and identity. Throws on invalid input. */
+    publish(bytes: Uint8Array): Uint8Array {
+      try {
+        const decoder = decoding.createDecoder(bytes);
+        if (decoding.readVarUint(decoder) !== 1) throw new InvalidSharedTextAwarenessError();
+        const clientId = decoding.readVarUint(decoder);
+        const clientClock = decoding.readVarUint(decoder);
+        if (!Number.isSafeInteger(clientId) || !Number.isSafeInteger(clientClock)) throw new InvalidSharedTextAwarenessError();
+        const state = stateSchema.parse(JSON.parse(decoding.readVarString(decoder)));
+        if (decoder.pos !== bytes.length || (localClientId !== undefined && localClientId !== clientId))
+          throw new InvalidSharedTextAwarenessError();
+        if (
+          state?.cursor &&
+          [state.cursor.anchor, state.cursor.head].some((position) => position.tname !== config.textName || position.type != null)
+        )
+          throw new InvalidSharedTextAwarenessError();
+        const result = next(state === null ? null : { user, writerId: clientId, cursor: state.cursor ?? null });
+        localClientId = clientId;
+        active = state !== null;
+        return result;
+      } catch {
+        throw new InvalidSharedTextAwarenessError();
+      }
+    },
+    /** Publish on leave/close, including when the browser cannot send its own null state. */
+    remove(): Uint8Array | null {
+      if (!active) return null;
+      const result = next(null);
+      active = false;
+      return result;
+    },
+  };
+};

package/src/shared-text/changes.ts

@@ -0,0 +1,27 @@
+import type { SharedTextChange } from "./types";
+
+export const validateChanges = (text: string, changes: readonly SharedTextChange[], maxLength: number): SharedTextChange[] => {
+  const sorted = [...changes].sort((a, b) => a.from - b.from || a.to - b.to);
+  let length = text.length;
+  const splitsCharacter = (at: number) =>
+    at > 0 && at < text.length && /[\uD800-\uDBFF]/.test(text[at - 1]!) && /[\uDC00-\uDFFF]/.test(text[at]!);
+  for (let index = 0; index < sorted.length; index++) {
+    const change = sorted[index]!;
+    const previous = sorted[index - 1];
+    if (
+      !Number.isSafeInteger(change.from) ||
+      !Number.isSafeInteger(change.to) ||
+      change.from < 0 ||
+      change.to < change.from ||
+      change.to > text.length ||
+      (change.recreate === true && change.to === change.from) ||
+      (previous && (change.from < previous.to || change.from === previous.from))
+    )
+      throw new RangeError("Shared text changes must have distinct, non-overlapping original-source ranges");
+    if (splitsCharacter(change.from) || splitsCharacter(change.to) || !change.insert.isWellFormed())
+      throw new RangeError("Shared text changes must preserve Unicode characters");
+    length += change.insert.length - (change.to - change.from);
+  }
+  if (length > maxLength) throw new RangeError("Shared text changes exceed maxLength");
+  return sorted.filter((change) => change.recreate === true || text.slice(change.from, change.to) !== change.insert);
+};