@k2b/cloud 0.43.0 → 0.45.0

package/src/shared/ai-models.ts

@@ -0,0 +1,274 @@
+import { z } from "zod";
+import { PrincipalSchema } from "../contracts/shared";
+import { AiModelPricingSchema } from "./ai-costs";
+import { AiExtraBodySchema, AiReasoningEffortSchema } from "./ai-request-options";
+
+export const AI_MODEL_CLASSES = ["fast", "balanced", "thorough", "maximum"] as const;
+export type AiModelClass = (typeof AI_MODEL_CLASSES)[number];
+export const AI_MODEL_SLOTS = [...AI_MODEL_CLASSES, "vision", "audio"] as const;
+export type AiModelSlot = (typeof AI_MODEL_SLOTS)[number];
+export const AiModelRequestSchema = z.union([
+  z.object({ class: z.enum(AI_MODEL_CLASSES) }).strict(),
+  z.object({ id: z.string().trim().min(1).max(241) }).strict(),
+]);
+export type AiModelRequest = z.infer<typeof AiModelRequestSchema>;
+export const AiResolvedModelRefSchema = z
+  .object({
+    requestedClass: z.enum(AI_MODEL_CLASSES).optional(),
+    class: z.enum(AI_MODEL_CLASSES).optional(),
+    id: z.string().min(1).max(241),
+  })
+  .strict();
+export type AiResolvedModelRef = { requestedClass?: AiModelClass; class?: AiModelClass; id: string };
+/** Only empty assignments fall back; policy and budget failures never do. */
+export const aiModelClassFallbackChain = (modelClass: AiModelClass): AiModelClass[] => {
+  const index = AI_MODEL_CLASSES.indexOf(modelClass);
+  return [...AI_MODEL_CLASSES.slice(0, index).reverse(), ...AI_MODEL_CLASSES.slice(index + 1)];
+};
+export const parseAiModelChoice = (value: string): AiModelRequest => {
+  const modelClass = z.enum(AI_MODEL_CLASSES).safeParse(value);
+  return modelClass.success ? { class: modelClass.data } : AiModelRequestSchema.parse({ id: value });
+};
+
+const slug = z
+  .string()
+  .trim()
+  .regex(/^[a-z0-9][a-z0-9._-]*$/)
+  .max(120);
+const image = z
+  .string()
+  .trim()
+  .regex(/^data:image\//)
+  .max(28_000);
+const httpUrl = z
+  .string()
+  .url()
+  .refine((value) => ["http:", "https:"].includes(new URL(value).protocol));
+export const AiProviderTypeSchema = z.enum([
+  "openai",
+  "openrouter",
+  "anthropic",
+  "mistral",
+  "gemini",
+  "ollama",
+  "vllm",
+  "openai-compatible",
+]);
+export type AiProviderType = z.infer<typeof AiProviderTypeSchema>;
+/** Hosted APIs refuse requests without a key; self-hosted endpoints may run without one. */
+export const providerRequiresCredential = (provider: AiProviderType): boolean =>
+  ["openai", "openrouter", "anthropic", "mistral", "gemini"].includes(provider);
+export const providerSupportsCredential = (provider: AiProviderType): boolean =>
+  providerRequiresCredential(provider) || provider === "vllm" || provider === "openai-compatible";
+export const AiProviderStatusSchema = z.enum(["unknown", "ok", "unreachable", "key_rejected", "error"]);
+export const AiProviderInputSchema = z
+  .object({
+    id: slug,
+    type: AiProviderTypeSchema,
+    label: z.string().trim().min(1),
+    baseUrl: httpUrl.nullable().default(null),
+    dataBoundary: z.enum(["hosted", "private"]),
+    enabled: z.boolean().default(true),
+    logo: image.nullable().default(null),
+  })
+  .strict();
+export const AiModelIconSchema = z.discriminatedUnion("kind", [
+  z.object({ kind: z.literal("provider") }).strict(),
+  z.object({ kind: z.literal("emoji"), emoji: z.string().min(1).max(64) }).strict(),
+  z.object({ kind: z.literal("image"), dataUrl: image }).strict(),
+]);
+export type AiModelIcon = z.infer<typeof AiModelIconSchema>;
+export const AiModelInputSchema = z
+  .object({
+    id: slug.refine((value) => !AI_MODEL_CLASSES.some((modelClass) => modelClass === value), "Model IDs cannot be class names."),
+    providerModel: z.string().trim().min(1),
+    label: z.string().trim().min(1),
+    description: z.string().default(""),
+    kind: z.enum(["chat", "transcription"]).default("chat"),
+    capabilities: z.array(z.enum(["tools", "vision", "transcription"])).default([]),
+    contextWindow: z.number().int().positive().nullable().default(null),
+    maxOutputTokens: z.number().int().positive().nullable().default(null),
+    temperature: z.number().min(0).max(2).nullable().default(null),
+    extraBody: AiExtraBodySchema.nullable().default(null),
+    maxLoadedTools: z.number().int().nullable().default(null),
+    maxToolRounds: z.number().int().nullable().default(null),
+    pricing: AiModelPricingSchema.nullable().default(null),
+    icon: AiModelIconSchema.default({ kind: "provider" }),
+    enabled: z.boolean().default(true),
+  })
+  .strict();
+export const AiVariantInputSchema = z
+  .object({
+    slug,
+    label: z.string().trim().min(1),
+    hint: z.string().default(""),
+    reasoningEffort: AiReasoningEffortSchema.nullable().default(null),
+    maxOutputTokens: z.number().int().positive().nullable().default(null),
+    pricing: AiModelPricingSchema.nullable().default(null),
+    extraBody: AiExtraBodySchema.nullable().default(null),
+    showInPicker: z.boolean().default(true),
+    position: z.number().int().default(0),
+  })
+  .strict();
+export const AiProviderPatchSchema = AiProviderInputSchema.omit({ id: true })
+  .partial()
+  .extend({
+    baseUrl: AiProviderInputSchema.shape.baseUrl.removeDefault().optional(),
+    enabled: AiProviderInputSchema.shape.enabled.removeDefault().optional(),
+    logo: AiProviderInputSchema.shape.logo.removeDefault().optional(),
+  })
+  .strict();
+export const AiModelPatchSchema = AiModelInputSchema.omit({ id: true })
+  .partial()
+  .extend({
+    description: AiModelInputSchema.shape.description.removeDefault().optional(),
+    kind: AiModelInputSchema.shape.kind.removeDefault().optional(),
+    capabilities: AiModelInputSchema.shape.capabilities.removeDefault().optional(),
+    contextWindow: AiModelInputSchema.shape.contextWindow.removeDefault().optional(),
+    maxOutputTokens: AiModelInputSchema.shape.maxOutputTokens.removeDefault().optional(),
+    temperature: AiModelInputSchema.shape.temperature.removeDefault().optional(),
+    extraBody: AiModelInputSchema.shape.extraBody.removeDefault().optional(),
+    maxLoadedTools: AiModelInputSchema.shape.maxLoadedTools.removeDefault().optional(),
+    maxToolRounds: AiModelInputSchema.shape.maxToolRounds.removeDefault().optional(),
+    pricing: AiModelInputSchema.shape.pricing.removeDefault().optional(),
+    icon: AiModelInputSchema.shape.icon.removeDefault().optional(),
+    enabled: AiModelInputSchema.shape.enabled.removeDefault().optional(),
+  })
+  .strict();
+export const AiVariantPatchSchema = AiVariantInputSchema.omit({ slug: true })
+  .partial()
+  .extend({
+    hint: AiVariantInputSchema.shape.hint.removeDefault().optional(),
+    reasoningEffort: AiVariantInputSchema.shape.reasoningEffort.removeDefault().optional(),
+    maxOutputTokens: AiVariantInputSchema.shape.maxOutputTokens.removeDefault().optional(),
+    pricing: AiVariantInputSchema.shape.pricing.removeDefault().optional(),
+    extraBody: AiVariantInputSchema.shape.extraBody.removeDefault().optional(),
+    showInPicker: AiVariantInputSchema.shape.showInPicker.removeDefault().optional(),
+    position: AiVariantInputSchema.shape.position.removeDefault().optional(),
+  })
+  .strict();
+const revisionFields = {
+  revision: z.number().int(),
+  createdAt: z.string(),
+  updatedAt: z.string(),
+  updatedBy: z.string().nullable(),
+};
+export const AiProviderSchema = AiProviderInputSchema.extend({
+  ...revisionFields,
+  status: AiProviderStatusSchema,
+  statusCode: z.string().nullable(),
+  statusMessage: z.string().nullable(),
+  statusCheckedAt: z.string().nullable(),
+  credentialSet: z.boolean(),
+  requestHeaderNames: z.array(z.string()),
+});
+export const AiModelSchema = AiModelInputSchema.extend({ ...revisionFields, providerId: z.string() });
+export const AiVariantSchema = AiVariantInputSchema.extend({ ...revisionFields, id: z.string(), modelId: z.string() });
+export const AiAssignmentSchema = z.object({
+  slot: z.enum(AI_MODEL_SLOTS),
+  variantId: z.string().nullable(),
+  revision: z.number().int(),
+  updatedAt: z.string(),
+  updatedBy: z.string().nullable(),
+});
+export type AiProvider = z.infer<typeof AiProviderSchema>;
+export type AiModel = z.infer<typeof AiModelSchema>;
+export type AiModelVariant = z.infer<typeof AiVariantSchema>;
+export type AiModelAssignment = z.infer<typeof AiAssignmentSchema>;
+export type AiModelUnavailableReason =
+  | { code: "budget_exhausted"; resetsAt: string }
+  | { code: "provider_unreachable" | "key_rejected" | "access_revoked" };
+export type AiPeopleModelIcon =
+  | { kind: "emoji"; emoji: string }
+  | { kind: "image"; src: string }
+  | { kind: "mark"; text: string; color: string };
+/** Neutral provider marks: Cloud ships no brand logos, so a provider shows its initials on one of these colours. */
+export const AI_PROVIDER_MARK_COLORS = ["#0f766e", "#6d28d9", "#475569", "#15803d", "#1d4ed8", "#c2410c", "#be123c", "#a16207"] as const;
+/** The initials and colour a provider shows wherever it has no logo, the same in the AI area and in every chooser. */
+export const aiProviderMark = (provider: { id: string; label: string }): { text: string; color: string } => {
+  const words = provider.label.split(/\s+/).filter(Boolean);
+  const capitals = words[0]?.match(/\p{Lu}/gu) ?? [];
+  const text =
+    words.length > 1
+      ? `${words[0]![0]}${words[1]![0]}`
+      : capitals.length >= 2
+        ? capitals.slice(0, 2).join("")
+        : (words[0] ?? "").slice(0, 2);
+  return {
+    text: text.toUpperCase() || "AI",
+    color:
+      AI_PROVIDER_MARK_COLORS[
+        Array.from(provider.id).reduce((sum, letter) => (sum * 31 + letter.charCodeAt(0)) >>> 0, 0) % AI_PROVIDER_MARK_COLORS.length
+      ]!,
+  };
+};
+export type AiPeopleModels = {
+  status: "ok";
+  selection: AiModelRequest | null;
+  effectiveDefault: AiModelRequest;
+  classes: { class: AiModelClass; variantId: string; unavailable?: AiModelUnavailableReason }[];
+  options: {
+    id: string;
+    label: string;
+    variantLabel?: string;
+    description: string;
+    icon: AiPeopleModelIcon;
+    classes: AiModelClass[];
+    unavailable?: AiModelUnavailableReason;
+  }[];
+};
+export const AiDeleteModelSchema = z
+  .object({
+    revision: z.number().int(),
+    replacements: z.partialRecord(z.enum(AI_MODEL_SLOTS), z.string().nullable()),
+    retarget: z.boolean(),
+    retargetTo: z.string().nullable(),
+  })
+  .strict();
+export type AiDeleteModelInput = z.infer<typeof AiDeleteModelSchema>;
+export type AiModelUsage = {
+  assignments: AiModelSlot[];
+  projects: { id: string; name: string }[];
+  workflows: { id: string; name: string }[];
+  scheduledTasks: { id: string; name: string }[];
+  chats: number;
+  budgetRules: { id: string; label: string }[];
+  peopleAtLimit: number;
+  stats: { answers14d: number; avgCostPerAnswer: number | null; avgSecondsPerAnswer: number | null };
+};
+
+const AiModelGrantSchema = z
+  .object({
+    principal: PrincipalSchema.refine((principal) => principal.type !== "public", "Assistant models cannot be public."),
+    permission: z.literal("read"),
+  })
+  .strict();
+export const AiModelAccessDraftSchema = z
+  .object({
+    expectedRevision: z.number().int().positive().max(Number.MAX_SAFE_INTEGER).nullable(),
+    entries: z.array(AiModelGrantSchema),
+  })
+  .strict();
+export type AiModelAccessDraft = z.infer<typeof AiModelAccessDraftSchema>;
+
+/** Whether a model supports a catalog assignment; safe to use in browser pickers. */
+export const aiModelSupportsSlot = (slot: AiModelSlot, model: Pick<AiModel, "kind" | "capabilities">): boolean =>
+  slot === "audio" ? model.kind === "transcription" : model.kind === "chat" && (slot !== "vision" || model.capabilities.includes("vision"));
+
+/** The same replacement requirements apply to deletion previews and committed retargeting. */
+export const aiReplacementProblem = (
+  source: Pick<AiProvider, "dataBoundary">,
+  target: Pick<AiProvider, "dataBoundary" | "enabled">,
+  original: Pick<AiModel, "kind" | "capabilities">,
+  replacement: Pick<AiModel, "kind" | "capabilities" | "enabled">,
+): "private_boundary" | "incompatible_model" | null => {
+  if (source.dataBoundary === "private" && target.dataBoundary !== "private") return "private_boundary";
+  if (
+    !target.enabled ||
+    !replacement.enabled ||
+    original.kind !== replacement.kind ||
+    original.capabilities.some((capability) => !replacement.capabilities.includes(capability))
+  )
+    return "incompatible_model";
+  return null;
+};

package/src/shared/ai-quotas.ts

@@ -143,7 +143,7 @@ export type AiQuotaReport = {
   perPage: number;
 };
 export const aiQuotaHref = (query: Partial<AiQuotaReportQuery>) => {
-  const params = new URLSearchParams({ tab: "ai-quotas" });
+  const params = new URLSearchParams({ sec: "budgets", ...(query.view === "rules" ? {} : { rule: "people" }) });
   for (const [key, value] of Object.entries(query)) if (value !== undefined && value !== "") params.set(key, String(value));
-  return `/admin/settings?${params}`;
+  return `/admin/ai?${params}`;
 };

package/src/shared/ai-usage.ts

@@ -8,7 +8,7 @@ export const AiUsageQuerySchema = z.object({
   range: z.enum(AI_USAGE_RANGES).default("30d"),
   until: z.iso.datetime({ offset: true }).optional(),
   userId: z.union([z.uuid(), z.literal("unassigned")]).optional(),
-  modelProfileId: text,
+  modelId: text,
   providerModel: text,
   appId: text,
   workflowId: z.uuid().optional(),
@@ -36,4 +36,4 @@ export const aiUsageSearchParams = (query: Partial<AiUsageQuery>): URLSearchPara
   for (const [key, value] of Object.entries(query)) if (value !== undefined && value !== "") params.set(key, String(value));
   return params;
 };
-export const aiUsageHref = (query: Partial<AiUsageQuery>) => `/admin/settings?tab=ai-usage&${aiUsageSearchParams(query)}`;
+export const aiUsageHref = (query: Partial<AiUsageQuery>) => `/admin/ai?sec=usage&${aiUsageSearchParams(query)}`;

package/src/shared/email-html.ts

@@ -6,6 +6,7 @@ export const EMAIL_HTML_TAGS = [
   "br",
   "code",
   "div",
+  "del",
   "em",
   "h1",
   "h2",

package/src/shared/index.ts

@@ -13,6 +13,8 @@ export {
 export * from "./account-display";
 export * from "./account-session";
 export * from "./ai-costs";
+export * from "./ai-models";
+export * from "./ai-models";
 export type { AiPromptContextInput, AiToolPromptHint } from "./ai-platform-prompt";
 export {
   AI_LOCAL_CLIENT_DEFAULT_INSTRUCTIONS,

package/src/shared/markdown/extensions/katex.ts

@@ -8,6 +8,7 @@
 
 import katex from "katex";
 import type { MarkedExtension, Tokens } from "marked";
+import { escapeHtml } from "../shared";
 
 /**
  * Token shape produced by the math tokenizers below. The marked extension API
@@ -40,7 +41,7 @@ function renderInlineMath(latex: string): string {
   }
 }
 
-export function katexExtension(): MarkedExtension {
+export function katexExtension(literal = false): MarkedExtension {
   return {
     extensions: [
       // ```math code blocks
@@ -63,6 +64,10 @@ export function katexExtension(): MarkedExtension {
           return undefined;
         },
         renderer(token: Tokens.Generic) {
+          if (literal) {
+            const source = token.raw.slice("```math\n".length, -"\n```".length);
+            return `<pre>${escapeHtml(source)}</pre>\n`;
+          }
           const latex = (token as MathToken).latex;
           return renderBlockMath(latex);
         },
@@ -87,6 +92,7 @@ export function katexExtension(): MarkedExtension {
           return undefined;
         },
         renderer(token: Tokens.Generic) {
+          if (literal) return `<p>${escapeHtml(token.raw)}</p>\n`;
           const latex = (token as MathToken).latex;
           return renderBlockMath(latex);
         },
@@ -111,6 +117,7 @@ export function katexExtension(): MarkedExtension {
           return undefined;
         },
         renderer(token: Tokens.Generic) {
+          if (literal) return escapeHtml(token.raw);
           const latex = (token as MathToken).latex;
           return renderInlineMath(latex);
         },

package/src/shared/markdown/extensions/tables.ts

@@ -66,11 +66,24 @@ const renderCell = (alignCls: string, originalText: string, ctx: EvalContext, ht
   return `<td><span class="md-table-cell md-formula-error${alignCls}" title="${escapeHtml(tooltip)}">⚠ ${escapeHtml(originalText)}</span></td>`;
 };
 
-export function tablesExtension(): MarkedExtension {
+export function tablesExtension(plain = false): MarkedExtension {
   return {
     renderer: {
       table(token: Tokens.Table): string {
         const align = token.align ?? [];
+        // Email has no Cloud stylesheet or formula widgets. Keep alignment on the
+        // structural cells and escape formula source before Markdown can interpret it.
+        if (plain) {
+          const cellHtml = (cell: Tokens.TableCell, tag: "th" | "td", column: number): string => {
+            const alignment = align[column];
+            const attribute = alignment ? ` align="${alignment}"` : "";
+            const content = isFormula(cell.text) ? escapeHtml(cell.text) : this.parser.parseInline(cell.tokens);
+            return `<${tag}${attribute}>${content}</${tag}>`;
+          };
+          const header = token.header.map((cell, column) => cellHtml(cell, "th", column)).join("");
+          const rows = token.rows.map((row) => `<tr>${row.map((cell, column) => cellHtml(cell, "td", column)).join("")}</tr>`).join("");
+          return `<table><thead><tr>${header}</tr></thead><tbody>${rows}</tbody></table>`;
+        }
 
         // Build the EvalContext once per table — formulas reference
         // raw cell text, not other formulas' results, so a single pass

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);
+};