@k2b/cloud 0.42.0 → 0.44.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/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-text/documents.ts

@@ -2,7 +2,7 @@ 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 { textDiffHunks } from "./text-diff";
 import type {
   SharedTextActor,
   SharedTextContributor,
@@ -14,6 +14,8 @@ import type {
 } from "./types";
 
 type DocumentLog = {
+  /** Omitted logs use Sync’s default message payload limit (128 KiB). */
+  maxPayloadBytes?: number;
   topic(): Pick<Topic<SharedTextSyncEvent>, "latestCursor" | "publish">;
   replay(config: {
     docId: string;
@@ -48,7 +50,10 @@ export const createDoc = (stored: SharedTextStoredState): Y.Doc => {
   }
 };
 
-export const bindDocuments = <Saved, Context>({ topic, replay }: DocumentLog, store: SharedTextStore<Saved, Context>) => {
+export const bindDocuments = <Saved, Context>(
+  { topic, replay, maxPayloadBytes = 128 * 1024 }: DocumentLog,
+  store: SharedTextStore<Saved, Context>,
+) => {
   return {
     async read(docId: string, options: { signal?: AbortSignal } = {}): Promise<SharedTextSnapshot | null> {
       const stored = await store.load(docId, options);
@@ -67,7 +72,11 @@ export const bindDocuments = <Saved, Context>({ topic, replay }: DocumentLog, st
     async edit(
       docId: string,
       options: { actor: SharedTextActor | null; context?: Context; signal?: AbortSignal },
-      update: (current: { text: string; contributors: SharedTextContributor[]; state(): Uint8Array }) => string | Promise<string>,
+      update: (current: {
+        text: string;
+        contributors: SharedTextContributor[];
+        state(): Uint8Array;
+      }) => string | { update: Uint8Array } | Promise<string | { update: Uint8Array }>,
     ): Promise<SharedTextEditResult<Saved>> {
       const requestedAt = Date.now();
       const stored = await store.load(docId, { signal: options.signal });
@@ -91,12 +100,20 @@ export const bindDocuments = <Saved, Context>({ topic, replay }: DocumentLog, st
         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");
+        if (typeof next === "string") {
+          const hunks = textDiffHunks(text, next, maxPayloadBytes);
+          doc.transact(() => {
+            for (const diff of hunks.reverse()) {
+              if (diff.deleteCount > 0) ytext.delete(diff.index, diff.deleteCount);
+              if (diff.insert.length > 0) ytext.insert(diff.index, diff.insert);
+            }
+          }, "cli-edit");
+        } else {
+          // Application-prepared transactions preserve exact item identities and
+          // may be replayed after a partial publication/persistence failure.
+          Y.applyUpdate(doc, next.update, "server-edit");
+        }
         const actor = options.actor;
         const published = await handle.publish({
           tenantId: docId,

package/src/shared-text/log.ts

@@ -87,7 +87,7 @@ const define = (topicConfig: Readonly<Pick<TopicConfig, "id" | "retention" | "de
       return 0;
     },
     withStore<Saved, Context>(store: SharedTextStore<Saved, Context>) {
-      return bindDocuments({ topic, replay }, store);
+      return bindDocuments({ topic, replay, maxPayloadBytes: topicConfig.maxPayloadBytes }, store);
     },
   };
 };

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

@@ -1,3 +1,7 @@
+import { type ArrayChange, diffArrays } from "diff";
+
+type TextDiff = { index: number; deleteCount: number; insert: string };
+
 const splitsSurrogatePair = (text: string, index: number): boolean => {
   const before = text.charCodeAt(index - 1);
   const after = text.charCodeAt(index);
@@ -21,3 +25,74 @@ export const minimalTextDiff = (before: string, after: string): { index: number;
 
   return { index, deleteCount: before.length - index - suffix, insert: after.slice(index, after.length - suffix) };
 };
+
+/** Convert adjacent additions/deletions into replacements in the original text's UTF-16 offsets. */
+const replacements = (parts: ArrayChange<string>[], offset: number): TextDiff[] => {
+  const hunks: TextDiff[] = [];
+  let index = offset;
+  let pending: TextDiff | undefined;
+  for (const part of parts) {
+    const value = part.value.join("");
+    if (!part.added && !part.removed) {
+      if (pending) hunks.push(pending);
+      pending = undefined;
+      index += value.length;
+    } else {
+      pending ??= { index, deleteCount: 0, insert: "" };
+      if (part.removed) {
+        pending.deleteCount += value.length;
+        index += value.length;
+      } else pending.insert += value;
+    }
+  }
+  if (pending) hunks.push(pending);
+  return hunks;
+};
+
+/**
+ * Ascending, non-overlapping hunks. Unchanged lines are matched first; only
+ * changed blocks are refined into Unicode code points (never half a surrogate).
+ * The log's payload budget bounds comparisons across both passes; comparing two
+ * tokens of equal length costs one more unit per 64 characters, since only those
+ * compare beyond their length. The square root bounds Myers's quadratic edit frontier.
+ * When either budget runs out, retain the old prefix/suffix replacement for
+ * that region: text correctness takes precedence over best-effort item identity.
+ */
+export const textDiffHunks = (before: string, after: string, maxPayloadBytes: number): TextDiff[] => {
+  if (before === after) return [];
+  let remaining = maxPayloadBytes;
+  const exhausted = Symbol("diff budget exhausted");
+  const compare = (a: string, b: string) => {
+    remaining -= 1 + (a.length === b.length ? a.length >> 6 : 0);
+    if (remaining < 0) throw exhausted;
+    return a === b;
+  };
+  const diff = (a: string[], b: string[]) => {
+    if (remaining <= 0) return undefined;
+    try {
+      return diffArrays(a, b, { comparator: compare, maxEditLength: Math.floor(Math.sqrt(maxPayloadBytes)) });
+    } catch (error) {
+      if (error !== exhausted) throw error;
+      return undefined;
+    }
+  };
+  const lines = (text: string) => text.match(/[^\n]*\n|[^\n]+$/g) ?? [];
+  // Lines both texts share at the start and end cost no budget, so a large note with small edits still diffs.
+  const a = lines(before);
+  const b = lines(after);
+  let start = 0;
+  while (start < a.length && start < b.length && a[start] === b[start]) start++;
+  let end = 0;
+  while (end < a.length - start && end < b.length - start && a[a.length - 1 - end] === b[b.length - 1 - end]) end++;
+  const offset = a.slice(0, start).reduce((length, line) => length + line.length, 0);
+  const lineParts = diff(a.slice(start, a.length - end), b.slice(start, b.length - end));
+  if (!lineParts) return [minimalTextDiff(before, after)];
+  return replacements(lineParts, offset).flatMap((block) => {
+    const oldText = before.slice(block.index, block.index + block.deleteCount);
+    const trimmed = minimalTextDiff(oldText, block.insert);
+    const index = block.index + trimmed.index;
+    const removed = oldText.slice(trimmed.index, trimmed.index + trimmed.deleteCount);
+    const charParts = remaining > 0 && removed && trimmed.insert ? diff(Array.from(removed), Array.from(trimmed.insert)) : undefined;
+    return charParts ? replacements(charParts, index) : [{ ...trimmed, index }];
+  });
+};

package/src/ssr/AdminArea.tsx

@@ -0,0 +1,131 @@
+import { AppWorkspace, StatusBadge } from "@k2b/ui";
+import type { JSX } from "solid-js";
+import AdminLayout from "./AdminLayout";
+import SettingsSaveStatus from "./SettingsSaveStatus.island";
+
+/** One row of an area's first column. `mark` shows a dot when the section needs attention. */
+export type AdminAreaItem = {
+  id: string;
+  label: string;
+  href: string;
+  icon: string;
+  description?: string;
+  mark?: "warning" | "error";
+};
+export type AdminAreaGroup = { title?: string; items: AdminAreaItem[] };
+
+type AdminAreaProps = {
+  c: Parameters<typeof AdminLayout>[0]["c"];
+  /** The area's name, the head of the first column. */
+  label: string;
+  /** Accessible name of the first column's navigation, for example "Observability sections". */
+  sectionsLabel: string;
+  /** The area's start; the first column's head links there. */
+  href: string;
+  groups: AdminAreaGroup[];
+  /** Id of the open section's item. */
+  current: string;
+  /** Page title, usually the open section's label. */
+  title: string;
+  /** Spoken with a mark in the first column, for example "Needs attention". */
+  markLabel?: string;
+  /** Id of the deepest open level: "section", or a deeper pane id the page adds. */
+  level?: string;
+  /** The section's panes, starting with one whose id is "section". */
+  children: JSX.Element;
+};
+
+/**
+ * An administration area: the admin layout, the area's sections as the first column, and the open section beside
+ * it as `AppWorkspace` levels. The owner builds each section's content by hand; a wide list adds `minSize`, so it
+ * pushes the first column aside instead of being squeezed.
+ */
+export function AdminArea(props: AdminAreaProps) {
+  return (
+    <AdminLayout c={props.c} title={props.title} ownMain>
+      <AppWorkspace.Main level={props.level ?? "section"}>
+        <AppWorkspace.MainPane id="area" label={props.label} href={props.href} defaultSize={248} minSize={232} maxSize={320}>
+          <nav aria-label={props.sectionsLabel}>
+            {props.groups.map((group) => (
+              <AppWorkspace.SidebarSection title={group.title}>
+                {group.items.map((item) => (
+                  <AppWorkspace.SidebarItem
+                    href={item.href}
+                    navigation="document"
+                    active={props.current === item.id}
+                    icon={item.icon}
+                    description={item.description}
+                    meta={
+                      item.mark ? (
+                        <span title={props.markLabel}>
+                          <StatusBadge tone={item.mark} variant="dot" label="" />
+                          <span class="sr-only">{props.markLabel}</span>
+                        </span>
+                      ) : undefined
+                    }
+                  >
+                    {item.label}
+                  </AppWorkspace.SidebarItem>
+                ))}
+              </AppWorkspace.SidebarSection>
+            ))}
+          </nav>
+        </AppWorkspace.MainPane>
+        {props.children}
+      </AppWorkspace.Main>
+    </AdminLayout>
+  );
+}
+
+/** The save status in a level head. A phone has no room there; `AdminAreaSaveStatusFoot` shows it at the bottom. */
+export const AdminAreaSaveStatusHead = () => (
+  <div class="hidden md:block">
+    <SettingsSaveStatus />
+  </div>
+);
+export const AdminAreaSaveStatusFoot = () => (
+  <div class="sticky bottom-0 flex justify-end bg-(--k2b-surface) px-4 py-3 md:hidden">
+    <SettingsSaveStatus />
+  </div>
+);
+
+/** A section that fills the width beside the first column, such as a dashboard or one form. */
+export function AdminAreaPane(props: {
+  label: string;
+  description?: JSX.Element;
+  /** Before the title, such as a step back inside the section. */
+  lead?: JSX.Element;
+  actions?: JSX.Element;
+  /** A form that saves with a button: its status, Discard and Save sit in the head, on a phone at the bottom. */
+  saveStatus?: boolean;
+  /** With a detail level beside it: the address of this level without the selection. */
+  href?: string;
+  /** A wide list declares the room it needs; the first column then gives way before the list is squeezed. */
+  minSize?: number;
+  children: JSX.Element;
+}) {
+  return (
+    <AppWorkspace.MainPane
+      id="section"
+      label={props.label}
+      description={props.description}
+      lead={props.lead}
+      actions={
+        props.saveStatus ? (
+          <div class="flex items-center gap-2">
+            {props.actions}
+            <AdminAreaSaveStatusHead />
+          </div>
+        ) : (
+          props.actions
+        )
+      }
+      href={props.href}
+      minSize={props.minSize}
+      defaultSize={props.minSize}
+    >
+      <div class="app-rows px-[var(--ui-space-shell)] pb-[var(--ui-space-shell)]">{props.children}</div>
+      {props.saveStatus ? <AdminAreaSaveStatusFoot /> : null}
+    </AppWorkspace.MainPane>
+  );
+}

package/src/ssr/AdminLayout.tsx

@@ -28,6 +28,10 @@ type Props = {
   title: string;
   /** Disable when a bounded child such as SettingsPage owns scrolling. */
   scroll?: boolean;
+  /** Page-owned insets when its layout needs more room than the default shell spacing. */
+  contentClass?: string;
+  /** The page renders its own `AppWorkspace.Main`, such as one in level mode. */
+  ownMain?: boolean;
 };
 export default function AdminLayout(props: Props) {
   // Keep children lazy so Layout installs the request locale before rendering them.
@@ -46,9 +50,13 @@ export default function AdminLayout(props: Props) {
       <AppWorkspace mobileSurface="flush" class="min-h-0 flex-1" resizable={false}>
         <AdminSidebar currentPath={currentPath} apps={runtime.apps} />
         <AppWorkspace.Content>
-          <AppWorkspace.Main scroll={scroll} class={scroll ? "p-[var(--ui-space-shell)]" : undefined}>
-            {props.children}
-          </AppWorkspace.Main>
+          {props.ownMain ? (
+            props.children
+          ) : (
+            <AppWorkspace.Main scroll={scroll} class={props.contentClass ?? (scroll ? "p-[var(--ui-space-shell)]" : undefined)}>
+              {props.children}
+            </AppWorkspace.Main>
+          )}
         </AppWorkspace.Content>
       </AppWorkspace>
     </Layout>

package/src/ssr/AdminSidebar.tsx

@@ -1,15 +1,15 @@
 import { AppWorkspace, useLocale } from "@k2b/ui";
-import { activeAdminHref } from "./admin-active-link";
+import { activeAdminLink } from "./admin-active-link";
 import { type AdminLink, buildAdminGroups } from "./admin-navigation";
 import { platformMessages } from "./platform-messages";
 import type { RuntimeContext } from "./runtime";
 import WorkspaceNavigation from "./WorkspaceNavigation.island";
 
 const AdminNavigation = (props: { currentPath: string; groups: ReturnType<typeof buildAdminGroups> }) => {
-  const activeHref = activeAdminHref(
+  const activeHref = activeAdminLink(
     props.currentPath,
-    props.groups.flatMap((group) => group.links.map((link: AdminLink) => link.href)),
-  );
+    props.groups.flatMap((group) => group.links),
+  )?.href;
   return (
     <>
       {props.groups.map((group) => (
@@ -45,10 +45,10 @@ export default function AdminSidebar({ currentPath, apps }: { currentPath: strin
             icon: `ti ${link.icon}`,
             active:
               link.href ===
-              activeAdminHref(
+              activeAdminLink(
                 currentPath,
-                groups().flatMap((entry) => entry.links.map((entry) => entry.href)),
-              ),
+                groups().flatMap((entry) => entry.links),
+              )?.href,
           })),
         }))}
       />