@k2b/cloud 0.30.0 → 0.32.0

package/src/cli/index.ts

@@ -51,6 +51,12 @@ export type CloudCliContext = {
   profiles?: {
     saveClientCredentials: (input: CloudCliClientCredentialsProfile) => Promise<void>;
   };
+  /**
+   * Open an `http:` or `https:` URL in the user's browser, when the host can.
+   * Resolves `false` when nothing was opened, so the command still prints the
+   * link. Absent in hosts without a local browser.
+   */
+  openUrl?: (url: string) => Promise<boolean>;
 };
 
 /** A profile that signs in with the OAuth client-credentials grant. */
@@ -70,6 +76,16 @@ export type CloudCliClientCredentialsProfile = {
 export type CloudCliModule = {
   name: string;
   summary: string;
+  /**
+   * `cld <alias> …` runs `cld <name> …`. Names match CLOUD_CLI_MODULE_NAME;
+   * cld uses them only when exactly one installed module claims them and no built-in or module has that name.
+   */
+  alias?: string;
+  /**
+   * Top-level names mapped to space-separated command paths relative to this module, never preset flags or args.
+   * Names match CLOUD_CLI_MODULE_NAME; cld uses them only when exactly one installed module claims them and no built-in or module has that name.
+   */
+  shortcuts?: Readonly<Record<string, string>>;
   booleanFlags?: readonly string[];
   requiresCloud?: boolean;
   requiresCloudFor?: (args: string[], flags: CloudCliFlags) => boolean;

package/src/cli/plugin.ts

@@ -67,6 +67,27 @@ export const cloudCliPluginDigest = (files: readonly Pick<CloudCliPluginFile, "p
 
 const isRecord = (value: unknown): value is Record<string, unknown> => typeof value === "object" && value !== null && !Array.isArray(value);
 
+/** Whether an alias is a valid extra name for this module. */
+export const isCloudCliAlias = (value: unknown, name: string): value is string =>
+  typeof value === "string" && CLOUD_CLI_MODULE_NAME.test(value) && value !== name;
+
+/** Validate short names and command-path syntax without loading a module's command tree. */
+export const isCloudCliShortcuts = (value: unknown, name: string, alias?: string): value is Record<string, string> =>
+  isRecord(value) &&
+  (Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null) &&
+  Object.entries(value).every(
+    ([key, target]) =>
+      CLOUD_CLI_MODULE_NAME.test(key) &&
+      key !== name &&
+      key !== alias &&
+      typeof target === "string" &&
+      target.trim() !== "" &&
+      target
+        .trim()
+        .split(/\s+/)
+        .every((segment) => !segment.startsWith("-")),
+  );
+
 /** Validate a served manifest, including its digest. Throws an `Error` naming the first problem. */
 export const parseCloudCliPluginManifest = (value: unknown): CloudCliPluginManifest => {
   if (!isRecord(value)) throw new Error("plugin manifest is not an object");
@@ -111,6 +132,15 @@ export const validateCloudCliModule = (value: unknown): CloudCliModule => {
   if (typeof value.name !== "string" || !CLOUD_CLI_MODULE_NAME.test(value.name)) {
     throw new Error("default export needs a lowercase kebab-case name");
   }
+  if (value.alias !== undefined && !isCloudCliAlias(value.alias, value.name)) {
+    throw new Error("alias must be a lowercase kebab-case name different from the module name");
+  }
+  if (
+    value.shortcuts !== undefined &&
+    !isCloudCliShortcuts(value.shortcuts, value.name, typeof value.alias === "string" ? value.alias : undefined)
+  ) {
+    throw new Error("shortcuts must be a plain object with unique kebab-case names and non-empty command paths without flags");
+  }
   if (typeof value.summary !== "string") throw new Error("default export needs a string summary");
   if (typeof value.run !== "function") throw new Error("default export needs a run function");
   for (const key of ["help", "requiresCloudFor"] as const) {

package/src/contracts/app-approval.ts

@@ -14,10 +14,29 @@ export const APP_APPROVAL_LIMITS = {
   pageSize: 20,
   pollSeconds: 5,
 } as const;
+/**
+ * Bounds of Action approvals on a device. Kept apart from `APP_APPROVAL_LIMITS`, whose every value a version 1
+ * authenticator checks when it connects. The texts are cut so that a whole inbox or Action stays within `bodyBytes`.
+ */
+export const APP_ACTION_LIMITS = {
+  inboxActions: 5,
+  nameChars: 60,
+  titleChars: 80,
+  summaryChars: 120,
+  sentenceChars: 280,
+  messageChars: 500,
+  details: 8,
+  labelChars: 40,
+  valueChars: 300,
+} as const;
+/** Commands a Cloud serves beyond the first version, announced in `/info` as `features`. */
+export const APP_APPROVAL_FEATURES = ["actions"] as const;
 
 const Id = z.string().uuid();
 const Secret = z.string().regex(/^[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048]$/);
 const Signature = z.string().regex(/^[A-Za-z0-9_-]{85}[AQgw]$/);
+/** Unpadded base64url of a SHA-256 hash. */
+const Digest = Secret;
 export const AppDevicePublicKeySchema = z
   .object({
     kty: z.literal("EC"),
@@ -57,6 +76,12 @@ export const AppDeviceCommandSchema = z.discriminatedUnion("operation", [
   z.object({ operation: z.literal("account") }).strict(),
   /** Stores the authenticator's opaque push token for sign-in wake-ups on this device. */
   z.object({ operation: z.literal("push"), token: z.string().regex(/^[A-Za-z0-9_-]{43}$/) }).strict(),
+  /** Pending sign-ins and the newest open Action approvals of the signing device's account in one call. */
+  z.object({ operation: z.literal("inbox") }).strict(),
+  /** One open Action approval as the device shows it, with the digest the device recomputes before it decides. */
+  z.object({ operation: z.literal("action"), actionId: Id }).strict(),
+  /** Decides an Action approval. `digest` binds the decision to exactly the view the person saw. */
+  z.object({ operation: z.literal("act"), actionId: Id, digest: Digest, decision: z.enum(["approve", "deny"]) }).strict(),
   z
     .object({
       operation: z.literal("decide"),
@@ -96,6 +121,8 @@ export const appDeviceProofMessage = (proof: AppDeviceProof): string => {
     c.operation,
     ...(c.operation === "decide" ? [c.requestId, c.challenge, c.comparison, c.decision] : []),
     ...(c.operation === "push" ? [c.token] : []),
+    ...(c.operation === "action" ? [c.actionId] : []),
+    ...(c.operation === "act" ? [c.actionId, c.digest, c.decision] : []),
   ]);
 };
 export const appPairingProofMessage = (issuer: string, claim: Omit<z.infer<typeof AppPairingClaimSchema>, "signature">): string =>
@@ -188,6 +215,97 @@ export const AppDeviceAccountSchema = z
   })
   .strict();
 export type AppDeviceAccount = z.infer<typeof AppDeviceAccountSchema>;
+/** Plain text on one line: no control, format or bidirectional characters, so an app cannot fake Cloud's own frame. */
+const PlainText = (max: number) =>
+  z
+    .string()
+    .refine((value) => Array.from(value).length <= max, `Must contain at most ${max} code points`)
+    .regex(/^[^\p{Cc}\p{Cf}\p{Zl}\p{Zp}]*$/u);
+const ActionApp = z
+  .object({ id: PlainText(APP_ACTION_LIMITS.nameChars).min(1), name: PlainText(APP_ACTION_LIMITS.nameChars).min(1) })
+  .strict();
+const actionFields = {
+  actionId: Id,
+  /** The app that owns the effect, named from the Cloud's registry, never from the request. */
+  app: ActionApp,
+  /** The app that asked, such as the Assistant, and the title of its chat. The title is chat content, not Cloud's words. */
+  requester: z.object({ app: ActionApp, title: PlainText(APP_ACTION_LIMITS.titleChars).nullable() }).strict(),
+  /** `confirm` asks every time; `standard` could also be remembered in Cloud. A device decides both alike. */
+  assurance: z.enum(["standard", "confirm"]),
+  createdAt: DateTime,
+  expiresAt: DateTime,
+};
+/** One inbox row. `sentence` is the start of the app's sentence; read the Action for everything the person approves. */
+export const AppActionSummarySchema = z.object({ ...actionFields, sentence: PlainText(APP_ACTION_LIMITS.summaryChars).min(1) }).strict();
+export const AppActionViewSchema = z
+  .object({
+    ...actionFields,
+    /** What the Action does, in the app's words and the person's language. */
+    sentence: PlainText(APP_ACTION_LIMITS.sentenceChars).min(1),
+    /** The app's review of this call, or `null`. */
+    message: PlainText(APP_ACTION_LIMITS.messageChars).nullable(),
+    details: z
+      .array(
+        z
+          .object({
+            label: PlainText(APP_ACTION_LIMITS.labelChars).min(1),
+            value: PlainText(APP_ACTION_LIMITS.valueChars),
+            /** A date (`YYYY-MM-DD` or RFC 3339) or an RFC 3339 date-time the device shows in its own locale and time zone. */
+            format: z.enum(["date", "date-time"]).optional(),
+          })
+          .strict(),
+      )
+      .max(APP_ACTION_LIMITS.details),
+    /** Cloud shortened or left out text; the complete request is in Cloud. */
+    truncated: z.boolean(),
+    /** SHA-256 of the Action's real input. The device cannot check it; it binds the decision to that input. */
+    argsDigest: z.string().min(1).max(128),
+    digest: Digest,
+  })
+  .strict();
+export type AppActionSummary = z.infer<typeof AppActionSummarySchema>;
+export type AppActionView = z.infer<typeof AppActionViewSchema>;
+export const AppDeviceInboxSchema = z
+  .object({
+    logins: z.array(AppPendingLoginSchema).max(APP_APPROVAL_LIMITS.pendingPerAccount),
+    /** Newest first. */
+    actions: z.array(AppActionSummarySchema).max(APP_ACTION_LIMITS.inboxActions),
+    /** Open Action approvals beyond `actions`. */
+    moreActions: z.number().int().nonnegative(),
+    pollAfterSeconds: z.number().positive(),
+  })
+  .strict();
+export type AppDeviceInbox = z.infer<typeof AppDeviceInboxSchema>;
+
+/** UTF-8 of this exact JSON array is hashed into an Action's `digest`. Every field the device shows is part of it. */
+export const appActionDigestMessage = (issuer: string, view: Omit<AppActionView, "digest">): string =>
+  JSON.stringify([
+    "cloud-action-v1",
+    issuer,
+    view.actionId,
+    view.app.id,
+    view.app.name,
+    view.requester.app.id,
+    view.requester.app.name,
+    view.requester.title,
+    view.assurance,
+    view.sentence,
+    view.message,
+    view.details.map((detail) => [detail.label, detail.value, detail.format ?? null]),
+    view.truncated,
+    view.createdAt,
+    view.expiresAt,
+    view.argsDigest,
+  ]);
+/** Unpadded base64url of SHA-256 over `appActionDigestMessage`. Cloud and the device compute it alike. */
+export const appActionDigest = async (issuer: string, view: Omit<AppActionView, "digest">): Promise<string> => {
+  const hash = new Uint8Array(await crypto.subtle.digest("SHA-256", new TextEncoder().encode(appActionDigestMessage(issuer, view))));
+  return btoa(String.fromCharCode(...hash))
+    .replaceAll("+", "-")
+    .replaceAll("/", "_")
+    .replaceAll("=", "");
+};
+
 export const AppDeviceResponseSchema = z.union([
   z
     .object({
@@ -197,6 +315,8 @@ export const AppDeviceResponseSchema = z.union([
     .strict(),
   z.object({ state: z.enum(["approved", "denied", "revoked", "updated"]) }).strict(),
   AppDeviceAccountSchema,
+  AppDeviceInboxSchema,
+  AppActionViewSchema,
 ]);
 export const AppLoginStartResultSchema = z
   .object({ requestId: Id, browserSecret: Secret, comparison: Comparison, expiresAt: DateTime, pollAfterSeconds: z.number().positive() })

package/src/contracts/app.ts

@@ -2,7 +2,7 @@ import type { Sync } from "@k2b/sync";
 import type { PlatformPermission } from "./outgoing-mail";
 import type { AppRegistryHelpSummary } from "./registry";
 import type { Role } from "./shared";
-import type { DashboardWidgetPresentation } from "./widgets";
+import type { DashboardWidgetPresentation, DashboardWidgetSize } from "./widgets";
 
 /**
  * One link entry contributed by an app to the global legal/info footer
@@ -69,6 +69,13 @@ export type AppPresentationTranslation = {
   searchLinks?: Readonly<Record<string, string>>;
   /** Search-link descriptions keyed by their stable same-origin href. */
   searchLinkDescriptions?: Readonly<Record<string, string>>;
+  /** Dashboard widget titles and descriptions keyed by `widgets[].id`. */
+  widgets?: Readonly<Record<string, AppWidgetTranslation>>;
+};
+
+export type AppWidgetTranslation = {
+  title?: string;
+  description?: string;
 };
 
 export type AppPresentationCatalog = {
@@ -161,7 +168,32 @@ export type WidgetEndpoint = {
   id: string;
   /** Absolute path on the app's HTTP service, e.g. "/api/accounts/widget/open-requests". */
   path: string;
-  /** Optional initial layout recommendation. Explicit user choices win. */
+  /**
+   * Name of the widget in the dashboard and its widget gallery, up to 80 characters, in the app's `baseLocale`;
+   * translate it with `presentation.translations[locale].widgets[id].title`. Defaults to the app's name.
+   */
+  title?: string;
+  /** One sentence for the widget gallery, up to 200 characters; translated like `title`. Defaults to the app's description. */
+  description?: string;
+  /** Sizes the widget offers on the board. Defaults to `["large"]`; offer smaller sizes only when the handler fills them. */
+  sizes?: readonly DashboardWidgetSize[];
+  /** Size the widget starts in, one of `sizes`. Defaults to the largest offered size. */
+  defaultSize?: DashboardWidgetSize;
+  /**
+   * Put the widget on the default board of everyone who may see it and list it under "Suggested for you" in the
+   * gallery. Suggest only widgets that are useful without any setup.
+   */
+  suggest?: boolean;
+  /**
+   * Show the widget in the gallery and on the default board only to people with one of these roles, like
+   * `nav.requiresRoles`. Visibility only: the handler still authorizes every request and answers `403`.
+   */
+  requiresRoles?: readonly Role[];
+  /**
+   * @deprecated The dashboard has no zones or widths any more; declare `sizes` and `defaultSize` instead. Keep an
+   * existing value: the dashboard reads it only to convert a board saved before sizes existed into the one the person
+   * saw.
+   */
   presentation?: DashboardWidgetPresentation;
 };
 

package/src/contracts/approval-paths.ts

@@ -0,0 +1,4 @@
+export const APPROVALS_API_PATH = "/api/approvals";
+export const APPROVAL_COUNTS_PATH = `${APPROVALS_API_PATH}/counts`;
+/** The Core page that lists every app's open approvals; `?app=<id>` narrows it to one app. */
+export const APPROVALS_PAGE_PATH = "/me/approvals";

package/src/contracts/approvals.ts

@@ -0,0 +1,81 @@
+import { z } from "zod";
+import { APP_APPROVAL_LIMITS } from "./app-approval";
+import { CapabilityActionReviewSchema, CapabilityAppIdSchema } from "./capabilities";
+
+export { APPROVAL_COUNTS_PATH, APPROVALS_API_PATH, APPROVALS_PAGE_PATH } from "./approval-paths";
+
+/**
+ * Pending Action approvals as every app lists and decides them: one Core route under `/api/approvals` and the
+ * `Approvals` component from `@k2b/cloud/approvals/ui`. A list shows only the signed-in person's own open requests.
+ */
+
+/** One page of a list, the same as a Cloud Login inbox page. */
+export const APPROVALS_PAGE_SIZE = APP_APPROVAL_LIMITS.pageSize;
+
+/**
+ * A client that relays decisions from an editor over the Agent Client Protocol sends this header with the value
+ * `acp`. Such a client may reject any request, but approves only `standard` ones. Cloud cannot verify the header: it is
+ * the bridge's own declaration, which keeps the editor that drives the bridge from approving a `confirm` request.
+ */
+export const APPROVAL_CLIENT_HEADER = "x-cloud-client";
+export const APPROVAL_ACP_CLIENT = "acp";
+
+export const ApprovalListQuerySchema = z
+  .object({
+    /** Requests whose effect belongs to this app, or that this app asked for. */
+    app: CapabilityAppIdSchema.optional(),
+    /** Requests whose review links to this same-origin path, such as the draft a send Action would send. */
+    link: z.string().startsWith("/").max(2048).optional(),
+    cursor: z.string().min(1).max(200).optional(),
+  })
+  .strict();
+export type ApprovalListQuery = z.infer<typeof ApprovalListQuerySchema>;
+
+export const PendingApprovalSchema = z
+  .object({
+    id: z.uuid(),
+    /** The app that owns the effect, named from the registry in the reader's language. */
+    app: z.object({ id: z.string(), name: z.string(), icon: z.string().nullable() }).strict(),
+    action: z.string(),
+    /** `confirm` asks every time and never offers to remember; `standard` may offer it. */
+    assurance: z.enum(["standard", "confirm"]),
+    /** What the person reads: the first line names the app and the Action, later lines add `Label: value` details. */
+    sentence: z.string(),
+    /** The owning app's review as the person saw it when Cloud asked. */
+    review: CapabilityActionReviewSchema.nullable(),
+    /** Where the request waits. The title is chat content, written by a person or a model, never Cloud's own words. */
+    requester: z.object({ kind: z.literal("chat"), appId: z.string(), title: z.string().nullable(), href: z.string() }).strict(),
+    /** Ways the person may remember this approval, the same the chat card offers. */
+    remember: z.object({ chat: z.boolean(), always: z.boolean(), website: z.boolean() }).strict(),
+    createdAt: z.string(),
+    expiresAt: z.string(),
+  })
+  .strict();
+export type PendingApproval = z.infer<typeof PendingApprovalSchema>;
+
+export const ApprovalPageSchema = z
+  .object({
+    items: z.array(PendingApprovalSchema).max(APPROVALS_PAGE_SIZE),
+    nextCursor: z.string().nullable(),
+    /** Open requests that match the query, across all pages. */
+    count: z.number().int().nonnegative(),
+    /** Open requests of the person that do not match the query; 0 without `app` or `link`. */
+    elsewhere: z.number().int().nonnegative(),
+  })
+  .strict();
+export type ApprovalPage = z.infer<typeof ApprovalPageSchema>;
+
+export const ApprovalCountsSchema = z
+  .object({
+    total: z.number().int().nonnegative(),
+    /** Per app ID: open requests whose effect belongs to the app or that the app asked for, as `?app=` lists them. */
+    apps: z.record(z.string(), z.number().int().positive()),
+  })
+  .strict();
+export type ApprovalCounts = z.infer<typeof ApprovalCountsSchema>;
+
+export const ApprovalDecisionInputSchema = z.object({ approved: z.boolean(), remember: z.enum(["chat", "always"]).optional() }).strict();
+export type ApprovalDecisionInput = z.infer<typeof ApprovalDecisionInputSchema>;
+
+export const ApprovalDecisionResultSchema = z.object({ status: z.enum(["approved", "rejected"]) }).strict();
+export type ApprovalDecisionResult = z.infer<typeof ApprovalDecisionResultSchema>;

package/src/contracts/command-path.ts

@@ -0,0 +1,17 @@
+/** Commands carry small public references/options, never document bodies or secrets. */
+export const COMMAND_MAX_URL_LENGTH = 8192;
+
+/** The same-origin path rule of `CommandPathSchema`, without its length limit. */
+export const isCommandPathSyntax = (value: string): boolean => {
+  if (!value.startsWith("/") || /[\\\u0000-\u0020]/u.test(value)) return false;
+  try {
+    const url = new URL(value, "https://cloud.invalid");
+    // Dot segments can resolve to `//host`, which a browser reads as another host.
+    return url.origin === "https://cloud.invalid" && !url.pathname.startsWith("//");
+  } catch {
+    return false;
+  }
+};
+
+/** Whether `value` is a Cloud path that `CommandPathSchema` accepts; loads no validators. */
+export const isCommandPath = (value: string): boolean => (value.length <= 2000 || [...value].length <= 2000) && isCommandPathSyntax(value);

package/src/contracts/commands.ts

@@ -1,20 +1,10 @@
 import { z } from "zod";
+import { COMMAND_MAX_URL_LENGTH, isCommandPathSyntax } from "./command-path";
 
-/** Commands carry small public references/options, never document bodies or secrets. */
-export const COMMAND_MAX_URL_LENGTH = 8192;
-export const CommandPathSchema = z
-  .string()
-  .max(2000)
-  .refine((value) => {
-    if (!value.startsWith("/") || /[\\\u0000-\u0020]/u.test(value)) return false;
-    try {
-      const url = new URL(value, "https://cloud.invalid");
-      // Dot segments can resolve to `//host`, which a browser reads as another host.
-      return url.origin === "https://cloud.invalid" && !url.pathname.startsWith("//");
-    } catch {
-      return false;
-    }
-  }, "Expected a Cloud path");
+export { COMMAND_MAX_URL_LENGTH, isCommandPath } from "./command-path";
+
+// Keep the size error separate from the syntax error, as before.
+export const CommandPathSchema = z.string().max(2000).refine(isCommandPathSyntax, "Expected a Cloud path");
 
 export const CommandOptionsSchema = z.object({ returnTo: CommandPathSchema.optional() }).strict();
 export type CommandOptions = z.infer<typeof CommandOptionsSchema>;

package/src/contracts/registry.ts

@@ -2,7 +2,7 @@ import type { AppAdminNavigationGroup, AppAppearance, AppAppearanceColor, AppPre
 import type { CapabilityManifest, CapabilityPresentationCatalog } from "./capabilities";
 import type { PlatformPermission } from "./outgoing-mail";
 import type { Role } from "./shared";
-import type { DashboardWidgetPresentation } from "./widgets";
+import type { DashboardWidgetPresentation, DashboardWidgetSize } from "./widgets";
 
 /**
  * App-registry entry type. Populated internally by `defineApp()` + the
@@ -52,10 +52,18 @@ export type AppRegistryLegalLink = {
   icon?: string;
 };
 
+/** A widget declaration as the registry carries it; see `WidgetEndpoint`. Older apps send only `id` and `path`. */
 export type AppRegistryWidget = {
   id: string;
   /** Absolute path on the app's HTTP service, e.g. "/api/quotes/widget/random". */
   path: string;
+  title?: string;
+  description?: string;
+  sizes?: readonly DashboardWidgetSize[];
+  defaultSize?: DashboardWidgetSize;
+  suggest?: boolean;
+  requiresRoles?: readonly Role[];
+  /** @deprecated Read only to convert dashboard boards saved before sizes existed. */
   presentation?: DashboardWidgetPresentation;
 };
 

package/src/contracts/shared.ts

@@ -248,7 +248,12 @@ export const ServiceAccountCredentialSchema = z.object({
 });
 export type ServiceAccountCredential = z.infer<typeof ServiceAccountCredentialSchema>;
 
+export const AI_INFERENCE_SCOPE = "ai:inference" as const;
+
+export const isModelsOnlyApiKey = (credential: { scopes: readonly string[] }): boolean => credential.scopes.includes(AI_INFERENCE_SCOPE);
+
 export const CreateUserApiKeySchema = z.object({
+  access: z.enum(["full", "models"]).optional(),
   name: z.string().trim().min(1).max(120),
   expiresAt: z.string().datetime().nullable().optional(),
 });

package/src/contracts/widgets.ts

@@ -38,18 +38,63 @@ const WidgetHrefSchema = z
 export const WidgetToneSchema = z.enum(["emerald", "amber", "red", "blue", "zinc"]);
 export type WidgetTone = z.infer<typeof WidgetToneSchema>;
 
+/** @deprecated The dashboard no longer has zones; declare `sizes` and `defaultSize` instead. */
 export type DashboardWidgetZone = "focus" | "overview" | "context";
+/** @deprecated The dashboard no longer has spans; declare `sizes` and `defaultSize` instead. */
 export type DashboardWidgetSpan = "standard" | "wide";
 
 /**
- * Stable, app-owned recommendation for a widget's initial dashboard layout.
- * Explicit user layout settings always take precedence.
+ * @deprecated The dashboard has no zones or widths any more. Declare `sizes` and `defaultSize` on the widget instead;
+ * the dashboard reads this recommendation only to convert a board saved before sizes existed.
  */
 export type DashboardWidgetPresentation = {
   defaultZone?: DashboardWidgetZone;
   defaultSpan?: DashboardWidgetSpan;
 };
 
+/**
+ * The three sizes a widget can take on the dashboard board, which has four columns on wider screens and two on
+ * phones: `small` is one column and one row, `medium` two columns and one row, and `large` two columns and two rows.
+ * On a phone, `small` takes half the width and `medium` and `large` the full width.
+ */
+export const DASHBOARD_WIDGET_SIZES = ["small", "medium", "large"] as const;
+export type DashboardWidgetSize = (typeof DASHBOARD_WIDGET_SIZES)[number];
+
+/** Longest declared widget title, in characters, the same bound as a shortcut title. */
+export const WIDGET_TITLE_MAX_LENGTH = 80;
+/** Longest declared widget description, in characters: one sentence in the widget gallery. */
+export const WIDGET_DESCRIPTION_MAX_LENGTH = 200;
+
+export const isDashboardWidgetSize = (value: unknown): value is DashboardWidgetSize =>
+  DASHBOARD_WIDGET_SIZES.some((size) => size === value);
+
+/**
+ * The sizes a widget offers and the size it starts with. A widget that declares no valid size offers only `large`,
+ * the height every widget had before sizes existed; without a valid `defaultSize`, it starts at its largest size.
+ */
+export const resolveWidgetSizes = (declaration: {
+  sizes?: readonly unknown[];
+  defaultSize?: unknown;
+}): { sizes: DashboardWidgetSize[]; defaultSize: DashboardWidgetSize } => {
+  const declared = DASHBOARD_WIDGET_SIZES.filter((size) => declaration.sizes?.includes(size));
+  const sizes: DashboardWidgetSize[] = declared.length > 0 ? declared : ["large"];
+  const defaultSize =
+    isDashboardWidgetSize(declaration.defaultSize) && sizes.includes(declaration.defaultSize) ? declaration.defaultSize : sizes.at(-1)!;
+  return { sizes, defaultSize };
+};
+
+/** `requested` when the widget offers it, otherwise the widget's default size. */
+export const fitWidgetSize = (
+  requested: unknown,
+  widget: { sizes: readonly DashboardWidgetSize[]; defaultSize: DashboardWidgetSize },
+): DashboardWidgetSize => (isDashboardWidgetSize(requested) && widget.sizes.includes(requested) ? requested : widget.defaultSize);
+
+/** What the dashboard asks a widget handler for, read with `getWidgetRequest(c)`. */
+export type WidgetRequest = {
+  /** The size the widget is shown in, always one the widget declares. */
+  size: DashboardWidgetSize;
+};
+
 export const WidgetAccentSchema = z
   .object({
     tone: WidgetToneSchema,

package/src/desktop/solid.tsx

@@ -1,3 +1,4 @@
+import { suppressTextSelection } from "@k2b/ui";
 import { deserialize as deserializeProps, serialize as serializeProps } from "seroval";
 import type { Component, JSX, ParentProps } from "solid-js";
 import { children, createContext, createMemo, createSignal, For, onCleanup, onMount, Show, useContext } from "solid-js";
@@ -483,10 +484,11 @@ const startDesktopResize = (event: PointerEvent, onMove: (dx: number, dy: number
   const startX = event.clientX;
   const startY = event.clientY;
   const move = (next: PointerEvent) => onMove(next.clientX - startX, next.clientY - startY);
+  const releaseTextSelection = suppressTextSelection(event.pointerId);
   const stop = () => {
     window.removeEventListener("pointermove", move);
     window.removeEventListener("pointerup", stop);
-    document.body.style.userSelect = "";
+    releaseTextSelection();
     document.body.style.cursor = "";
   };
   window.addEventListener("pointermove", move);
@@ -631,10 +633,9 @@ export const DesktopWorkspace = ((props: DesktopWorkspaceProps) => {
 
   const resizeSidebar = (event: PointerEvent) => {
     const pane = sidebar();
-    if (!pane?.resizable) return;
+    if (!pane?.resizable || event.button !== 0) return;
     const start = sidebarOpen() ? sidebarSize() : sidebarColumnSize();
     document.body.style.cursor = "col-resize";
-    document.body.style.userSelect = "none";
     startDesktopResize(event, (dx) => {
       const raw = start + dx;
       if (shouldRail(pane, raw)) {
@@ -650,10 +651,9 @@ export const DesktopWorkspace = ((props: DesktopWorkspaceProps) => {
 
   const resizeRight = (event: PointerEvent) => {
     const pane = right();
-    if (!pane?.resizable) return;
+    if (!pane?.resizable || event.button !== 0) return;
     const start = rightOpen() ? rightSize() : rightColumnSize();
     document.body.style.cursor = "col-resize";
-    document.body.style.userSelect = "none";
     startDesktopResize(event, (dx) => {
       const raw = start - dx;
       if (shouldRail(pane, raw)) {
@@ -669,10 +669,9 @@ export const DesktopWorkspace = ((props: DesktopWorkspaceProps) => {
 
   const resizeBottom = (event: PointerEvent) => {
     const pane = bottom();
-    if (!pane?.resizable) return;
+    if (!pane?.resizable || event.button !== 0) return;
     const start = bottomOpen() ? bottomSize() : bottomRowSize();
     document.body.style.cursor = "row-resize";
-    document.body.style.userSelect = "none";
     startDesktopResize(event, (_dx, dy) => {
       const raw = start - dy;
       if (shouldRail(pane, raw)) {

package/src/events/live-protocol.ts

@@ -1,5 +1,7 @@
 import { z } from "zod";
 
+export type { LiveServerMessage } from "./live-server-message";
+
 /** Messages a live socket accepts: subscriptions only. Writes go over HTTP. */
 export const LiveClientMessageSchema = z.discriminatedUnion("t", [
   z
@@ -28,4 +30,3 @@ export const LiveServerMessageSchema = z.discriminatedUnion("t", [
   z.object({ t: z.literal("revoked"), id: z.string(), code: z.enum(["not_found", "access_denied"]) }),
   z.object({ t: z.literal("error"), code: z.string(), message: z.string() }),
 ]);
-export type LiveServerMessage = z.infer<typeof LiveServerMessageSchema>;

package/src/events/live-server-message.ts

@@ -0,0 +1,40 @@
+/** The server's live wire messages; validation equivalence is checked against live-protocol. */
+export type LiveServerMessage =
+  | { t: "ready"; id: string; cursor: string }
+  | { t: "event"; id: string; cursor: string; data: unknown }
+  | { t: "progress"; cursor: string }
+  | { t: "resync"; id: string; cursor: string }
+  | { t: "revoked"; id: string; code: "not_found" | "access_denied" }
+  | { t: "error"; code: string; message: string };
+
+/** Strip undeclared keys just like the server-message schema. */
+export const parseLiveServerMessage = (value: unknown): LiveServerMessage | null => {
+  if (typeof value !== "object" || value === null || Array.isArray(value) || !("t" in value)) return null;
+  switch (value.t) {
+    case "ready":
+    case "resync":
+    case "event": {
+      if (!("id" in value) || typeof value.id !== "string" || !("cursor" in value) || typeof value.cursor !== "string") return null;
+      if (value.t === "event") {
+        // Zod v4 requires the key even though its value is unknown (and may be undefined).
+        return "data" in value ? { t: value.t, id: value.id, cursor: value.cursor, data: value.data } : null;
+      }
+      return { t: value.t, id: value.id, cursor: value.cursor };
+    }
+    case "progress":
+      return "cursor" in value && typeof value.cursor === "string" ? { t: value.t, cursor: value.cursor } : null;
+    case "revoked":
+      return "id" in value &&
+        typeof value.id === "string" &&
+        "code" in value &&
+        (value.code === "not_found" || value.code === "access_denied")
+        ? { t: value.t, id: value.id, code: value.code }
+        : null;
+    case "error":
+      return "code" in value && typeof value.code === "string" && "message" in value && typeof value.message === "string"
+        ? { t: value.t, code: value.code, message: value.message }
+        : null;
+    default:
+      return null;
+  }
+};