@k2b/cloud 0.33.0 → 0.35.0

package/src/browser/widgets.ts

@@ -1,17 +1,29 @@
-import type { DashboardWidgetSize, WidgetStreamLine } from "../contracts/widgets";
+import type { DashboardWidgetSize, WidgetSettings, WidgetStreamLine } from "../contracts/widgets";
 import { LOCALE_HEADER } from "../shared/locale";
 import { NDJSON_CONTENT_TYPE, readNdjsonLines } from "./ndjson";
 
-export type { DashboardWidgetSize, WidgetResponse, WidgetStreamLine, WidgetStreamStatus } from "../contracts/widgets";
+export type {
+  DashboardWidgetSize,
+  WidgetResponse,
+  WidgetSettingField,
+  WidgetSettings,
+  WidgetSettingsDeclaration,
+  WidgetSettingValue,
+  WidgetStreamLine,
+  WidgetStreamStatus,
+} from "../contracts/widgets";
 
 /**
  * Asks Core for dashboard widgets and hands over each one as soon as it answers: `start` names the widgets, one
  * `widget` line follows per widget in the order they finish, then `done`. `keys` (`<appId>/<widgetId>`) limits the
  * request, for example to retry one widget; without it Core asks every declared widget. `sizes` names the size to ask
  * a widget for; a widget without one, or with a size it does not offer, answers in its default size. Aborting `signal`
- * stops every widget Core still waits for. Rejects when the request fails or the stream breaks off.
+ * stops every widget Core still waits for. When `requests` is given, POST sends one invocation per entry with its
+ * settings, ignoring `keys` and `sizes`; start and widget lines identify entries by id. Rejects when the request fails
+ * or the stream breaks off.
  */
 export const streamWidgets = async (options: {
+  requests?: readonly { id: string; key: string; size?: DashboardWidgetSize; settings?: WidgetSettings }[];
   keys?: readonly string[];
   sizes?: Readonly<Record<string, DashboardWidgetSize>>;
   signal: AbortSignal;
@@ -19,11 +31,17 @@ export const streamWidgets = async (options: {
   onLine: (line: WidgetStreamLine) => void;
 }): Promise<void> => {
   const query = new URLSearchParams();
-  for (const key of options.keys ?? []) query.append("widget", options.sizes?.[key] ? `${key}@${options.sizes[key]}` : key);
+  for (const key of options.requests ? [] : (options.keys ?? []))
+    query.append("widget", options.sizes?.[key] ? `${key}@${options.sizes[key]}` : key);
   const search = query.toString();
   const response = await fetch(`/api/widgets/v1${search ? `?${search}` : ""}`, {
+    ...(options.requests ? { method: "POST", body: JSON.stringify({ widgets: options.requests }) } : {}),
     signal: options.signal,
-    headers: { accept: NDJSON_CONTENT_TYPE, [LOCALE_HEADER]: options.locale },
+    headers: {
+      accept: NDJSON_CONTENT_TYPE,
+      [LOCALE_HEADER]: options.locale,
+      ...(options.requests ? { "content-type": "application/json" } : {}),
+    },
   });
   if (!response.ok) throw new Error(`Widgets failed with ${response.status}`);
   await readNdjsonLines(response, options.onLine, "Widgets");

package/src/capabilities/testing.ts

@@ -1,5 +1,10 @@
 import { capabilityManifestEvolutionIssues, compileCapabilities } from "../_internal/capabilities";
-import type { CapabilityDefinitions, CapabilityManifest } from "../contracts/capabilities";
+import {
+  type CapabilityDefinitions,
+  type CapabilityManifest,
+  type CapabilityResult,
+  CapabilitySemanticLinkSchema,
+} from "../contracts/capabilities";
 
 /** Compile and validate the public manifest an app would register at startup. */
 export const compileCapabilityManifest = (appId: string, definitions: CapabilityDefinitions): CapabilityManifest =>
@@ -10,3 +15,10 @@ export const assertCapabilityManifestEvolution = (previous: CapabilityManifest,
   const issues = capabilityManifestEvolutionIssues(previous, next);
   if (issues.length > 0) throw new Error(`Breaking Capability manifest evolution:\n- ${issues.join("\n- ")}`);
 };
+
+/** Assert that a reader result exposes a valid destination for its resource permalink. */
+export const assertResourceOpenLink = (result: Pick<CapabilityResult<unknown>, "links">) => {
+  const link = result.links?.find((link) => link.rel === "open");
+  if (!link) throw new Error("Resource reader must return a top-level open link");
+  return CapabilitySemanticLinkSchema.parse(link);
+};

package/src/cli/capabilities.ts

@@ -6,6 +6,8 @@ import {
   CAPABILITY_MAX_RESULT_BYTES,
   CapabilityCatalogSchema,
   CapabilityErrorSchema,
+  type CapabilityManifest,
+  CapabilitySemanticLinkSchema,
   CapabilityStreamSchema,
   CloudResourceRefSchema,
   capabilityResultSchema,
@@ -14,6 +16,7 @@ import {
 } from "../contracts/capabilities";
 import { saveCapabilityStream } from "./capability-streams";
 import { arg, type CliInputFlagValue, type CloudCliContext, command, defineCliCommands, flag, readCliInput } from "./index";
+import { cloudResourceUrl } from "./resource-links";
 
 const parseInput = async (input: CliInputFlagValue): Promise<unknown> => {
   const raw = await readCliInput(input, {
@@ -65,6 +68,26 @@ const readCapabilityJson = async (response: Response, maxBytes: number): Promise
   return parsed.data;
 };
 
+const findCatalogApps = async (ctx: CloudCliContext, appIds: ReadonlySet<string>) => {
+  const wantedApps = new Set(appIds);
+  const apps: z.infer<typeof CapabilityCatalogSchema>["apps"] = [];
+  let cursor: string | undefined;
+  const seenCursors = new Set<string>();
+  while (wantedApps.size) {
+    const query = new URLSearchParams({ limit: "25" });
+    if (cursor) query.set("cursor", cursor);
+    const page = CapabilityCatalogSchema.parse(
+      await readCapabilityJson(await ctx.fetch(`/api/capabilities/v1/catalog?${query}`), CAPABILITY_MAX_CATALOG_BYTES),
+    );
+    for (const app of page.apps) if (wantedApps.delete(app.appId)) apps.push(app);
+    if (!wantedApps.size || !page.page.hasMore) break;
+    cursor = page.page.nextCursor;
+    if (seenCursors.has(cursor)) throw new Error("Capability catalog returned a repeated cursor.");
+    seenCursors.add(cursor);
+  }
+  return apps;
+};
+
 const invoke = async (config: {
   ctx: CloudCliContext;
   kind: "queries" | "actions";
@@ -72,6 +95,7 @@ const invoke = async (config: {
   capabilityId: string;
   input?: CliInputFlagValue;
   inputValue?: unknown;
+  manifest?: CapabilityManifest;
   idempotencyKey?: string;
 }) => {
   const headers = new Headers({ "content-type": "application/json" });
@@ -113,7 +137,40 @@ const invoke = async (config: {
     }
     throw error;
   }
-  printGenericResult(config.ctx, capabilityResultSchema(z.unknown()).parse(body));
+  const result = capabilityResultSchema(z.unknown()).parse(body);
+  const manifests = config.manifest ? [config.manifest] : [];
+  const wantedApps = new Set((result.refs ?? []).map(cloudResourceRefAppId));
+  for (const manifest of manifests) wantedApps.delete(manifest.appId);
+  if (wantedApps.size) {
+    try {
+      const apps = await findCatalogApps(config.ctx, wantedApps);
+      manifests.push(...apps.map((app) => app.manifest));
+    } catch {
+      config.ctx.error("The capability catalog is unavailable; some resource permalinks could not be added.");
+    }
+  }
+  const absoluteLinks = (value: unknown): unknown => {
+    if (Array.isArray(value)) return value.map(absoluteLinks);
+    if (!value || typeof value !== "object") return value;
+    const link = CapabilitySemanticLinkSchema.safeParse(value);
+    if (link.success) return { ...link.data, href: new URL(link.data.href, config.ctx.options.server).href };
+    return Object.fromEntries(Object.entries(value).map(([key, nested]) => [key, absoluteLinks(nested)]));
+  };
+  printGenericResult(
+    config.ctx,
+    absoluteLinks({
+      ...result,
+      ...(result.refs
+        ? {
+            refs: result.refs.map((ref) =>
+              ref.id.isWellFormed() && manifests.some((manifest) => resolveCapabilityResourceReader(manifest, ref))
+                ? { ...ref, permalink: cloudResourceUrl(config.ctx, ref) }
+                : ref,
+            ),
+          }
+        : {}),
+    }),
+  );
 };
 
 export default defineCliCommands({
@@ -230,25 +287,12 @@ export default defineCliCommands({
       run: async ({ ctx, args }) => {
         const ref = CloudResourceRefSchema.parse({ type: args.type, id: args.id });
         const appId = cloudResourceRefAppId(ref);
-        let cursor: string | undefined;
-        const seenCursors = new Set<string>();
-        let app: z.infer<typeof CapabilityCatalogSchema>["apps"][number] | undefined;
-        do {
-          const query = new URLSearchParams({ limit: "25" });
-          if (cursor) query.set("cursor", cursor);
-          const page = CapabilityCatalogSchema.parse(
-            await readCapabilityJson(await ctx.fetch(`/api/capabilities/v1/catalog?${query}`), CAPABILITY_MAX_CATALOG_BYTES),
-          );
-          app = page.apps.find((candidate) => candidate.appId === appId);
-          const nextCursor = page.page.hasMore ? page.page.nextCursor : undefined;
-          if (nextCursor && seenCursors.has(nextCursor)) throw new Error("Capability catalog returned a repeated cursor.");
-          if (nextCursor) seenCursors.add(nextCursor);
-          cursor = nextCursor;
-        } while (!app && cursor);
+        const apps = await findCatalogApps(ctx, new Set([appId]));
+        const app = apps.find((candidate) => candidate.appId === appId);
         if (!app) throw new Error(`Capability app ${appId} is unavailable.`);
         const reader = resolveCapabilityResourceReader(app.manifest, ref);
         if (!reader) throw new Error(`Cloud resource type ${ref.type} is unknown or has no reader.`);
-        await invoke({ ctx, kind: "queries", appId, capabilityId: reader.localId, inputValue: { id: ref.id } });
+        await invoke({ ctx, kind: "queries", appId, capabilityId: reader.localId, inputValue: { id: ref.id }, manifest: app.manifest });
       },
     }),
     command("action", {

package/src/cli/index.ts

@@ -100,3 +100,5 @@ export * from "./commands";
 export * from "./locale";
 export * from "./output";
 export * from "./plugin";
+
+export * from "./resource-links";

package/src/cli/resource-links.ts

@@ -0,0 +1,13 @@
+import type { CloudResourceRef } from "../contracts/capabilities";
+import { cloudResourceHref } from "../contracts/resource-href";
+import type { CloudCliContext } from "./index";
+
+export const cloudResourceUrl = (ctx: Pick<CloudCliContext, "options">, ref: CloudResourceRef): string =>
+  new URL(cloudResourceHref(ref), ctx.options.server).href;
+
+/** The resource id must be the id its Type's reader accepts. */
+export const withCloudResourcePermalink = <T extends { id: string }>(
+  ctx: Pick<CloudCliContext, "options">,
+  type: CloudResourceRef["type"],
+  resource: T,
+) => ({ ...resource, permalink: cloudResourceUrl(ctx, { type, id: resource.id }) });

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, DashboardWidgetSize } from "./widgets";
+import type { DashboardWidgetPresentation, DashboardWidgetSize, WidgetSettingsDeclaration } from "./widgets";
 
 /**
  * One link entry contributed by an app to the global legal/info footer
@@ -73,9 +73,12 @@ export type AppPresentationTranslation = {
   widgets?: Readonly<Record<string, AppWidgetTranslation>>;
 };
 
+/** Translated widget presentation, keyed by stable widget, setting, and option identifiers. */
 export type AppWidgetTranslation = {
   title?: string;
   description?: string;
+  /** Setting presentation keyed by setting name, with option labels keyed by option value. */
+  settings?: Readonly<Record<string, { label?: string; placeholder?: string; options?: Readonly<Record<string, string>> }>>;
 };
 
 export type AppPresentationCatalog = {
@@ -163,6 +166,7 @@ export type AppMeta = {
  */
 export type AppNavBadge = { count: number };
 
+/** A widget endpoint and its board presentation; the handler owns resource authorization. */
 export type WidgetEndpoint = {
   /** Unique-within-the-app id, e.g. "open-requests". */
   id: string;
@@ -179,6 +183,8 @@ export type WidgetEndpoint = {
   sizes?: readonly DashboardWidgetSize[];
   /** Size the widget starts in, one of `sizes`. Defaults to the largest offered size. */
   defaultSize?: DashboardWidgetSize;
+  /** Optional per-entry settings; handlers must work without them and authorize selected resources. */
+  settings?: WidgetSettingsDeclaration;
   /**
    * 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.

package/src/contracts/capabilities.ts

@@ -15,6 +15,8 @@ export const CAPABILITY_PROTOCOL_VERSION = 2 as const;
 export const CAPABILITY_MAX_REQUEST_BYTES = 256 * 1024;
 export const CAPABILITY_MAX_RESULT_BYTES = 256 * 1024;
 export const CAPABILITY_MAX_CATALOG_BYTES = 2 * 1024 * 1024;
+export const CAPABILITY_QUALIFIED_ID_MAX_LENGTH = 180;
+export const CLOUD_RESOURCE_ID_MAX_LENGTH = 512;
 
 export const CAPABILITY_FRAMEWORK_ERROR_CODES = {
   appUnavailable: "APP_UNAVAILABLE",
@@ -75,18 +77,20 @@ export const CapabilityLocalIdSchema = z
 export const CapabilityQualifiedIdSchema = z
   .string()
   .min(3)
-  .max(180)
+  .max(CAPABILITY_QUALIFIED_ID_MAX_LENGTH)
   .regex(CAPABILITY_QUALIFIED_ID_PATTERN, "Expected a namespaced capability id such as contacts.contact");
 
 export const CloudResourceRefSchema = z
   .object({
     type: CapabilityQualifiedIdSchema.describe("Namespaced resource type declared by the owning app."),
-    id: z.string().min(1).max(512).describe("Stable app-owned resource identifier."),
+    id: z.string().min(1).max(CLOUD_RESOURCE_ID_MAX_LENGTH).describe("Stable app-owned resource identifier."),
   })
   .strict();
 
 export type CloudResourceRef = z.infer<typeof CloudResourceRefSchema>;
 
+export { cloudResourceHref } from "./resource-href";
+
 export const CloudResourceReferenceSchema = CloudResourceRefSchema.extend({
   title: z.string().min(1).max(500).optional().describe("Optional current user-facing resource label."),
   preview: z.string().max(2000).optional().describe("Optional short plain-text context for the resource."),
@@ -95,6 +99,13 @@ export const CloudResourceReferenceSchema = CloudResourceRefSchema.extend({
 
 export type CloudResourceReference = z.infer<typeof CloudResourceReferenceSchema>;
 
+// Consumer permalinks may encode all 512 UTF-16 units of an id (up to 4,608 characters).
+export const CloudResourceHrefSchema = z.string().min(1).max(8192).regex(CLOUD_PATH_PATTERN);
+
+export const LinkedCloudResourceReferenceSchema = CloudResourceReferenceSchema.extend({
+  href: z.union([CloudResourceHrefSchema, z.url({ protocol: /^https?$/ }).max(8192)]).optional(),
+}).strict();
+
 export const CapabilitySemanticLinkSchema = z
   .object({
     rel: z.enum(["open", "edit", "status", "preview", "download"]).describe("Semantic relationship; clients decide how to present it."),
@@ -219,7 +230,10 @@ export const capabilityResultSchema = <T extends z.ZodType>(
       data,
       stream: CapabilityStreamSchema.optional(),
       summary: z.string().trim().min(1).max(500).optional(),
-      refs: z.array(CloudResourceReferenceSchema).max(100).optional(),
+      refs: z
+        .array(options?.consumer ? LinkedCloudResourceReferenceSchema : CloudResourceReferenceSchema)
+        .max(100)
+        .optional(),
       page: CapabilityPageSchema.optional(),
       links: z.array(CapabilitySemanticLinkSchema).max(20).optional(),
       presentation: options?.consumer
@@ -241,8 +255,14 @@ export const capabilityResultSchema = <T extends z.ZodType>(
       }
     }) as unknown as z.ZodType<CapabilityResult<z.output<T>>>;
 
-export const capabilityResultJsonSchema = (dataSchema: Record<string, unknown>): Record<string, unknown> =>
-  z.toJSONSchema(capabilityResultSchema(z.fromJSONSchema(structuredClone(dataSchema))), { io: "output" }) as Record<string, unknown>;
+export const capabilityResultJsonSchema = (
+  dataSchema: Record<string, unknown>,
+  options?: { consumer?: boolean },
+): Record<string, unknown> =>
+  z.toJSONSchema(capabilityResultSchema(z.fromJSONSchema(structuredClone(dataSchema)), options), { io: "output" }) as Record<
+    string,
+    unknown
+  >;
 
 export const CapabilityErrorSchema = z
   .object({

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, DashboardWidgetSize } from "./widgets";
+import type { DashboardWidgetPresentation, DashboardWidgetSize, WidgetSettingsDeclaration } from "./widgets";
 
 /**
  * App-registry entry type. Populated internally by `defineApp()` + the
@@ -54,6 +54,8 @@ export type AppRegistryLegalLink = {
 
 /** A widget declaration as the registry carries it; see `WidgetEndpoint`. Older apps send only `id` and `path`. */
 export type AppRegistryWidget = {
+  /** Per-entry setting declaration, validated again when listed. */
+  settings?: WidgetSettingsDeclaration;
   id: string;
   /** Absolute path on the app's HTTP service, e.g. "/api/quotes/widget/random". */
   path: string;

package/src/contracts/resource-href.ts

@@ -0,0 +1,7 @@
+import type { CloudResourceRef } from "./capabilities";
+
+/**
+ * The permanent Cloud path of a resource. The fixed `~` keeps the ids `.` and `..` from being read as dot segments.
+ * This module stays free of runtime imports: the `cld` host loads it at startup.
+ */
+export const cloudResourceHref = (ref: CloudResourceRef): string => `/open/${ref.type}/~${encodeURIComponent(ref.id)}`;

package/src/contracts/widgets.ts

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { CAPABILITY_QUALIFIED_ID_MAX_LENGTH, CLOUD_RESOURCE_ID_MAX_LENGTH, type CloudResourceRef } from "./capabilities";
 
 /**
  * Widget JSON contract — what an app's widget endpoint must return when the
@@ -64,6 +65,59 @@ export type DashboardWidgetSize = (typeof DASHBOARD_WIDGET_SIZES)[number];
 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;
+/**
+ * Core signs `widget.read:<widgetId>`; the invocation token's OperationSchema limits operations to 200 characters
+ * matching /^[a-z][a-z0-9:._-]*$/ (services/identity/invocation-token.ts). Longer IDs or other characters cannot be invoked.
+ */
+export const WIDGET_ID_MAX_LENGTH = 188;
+/** `<appId>/<widgetId>`; the invocation token's audience rule limits app IDs to 80 characters. */
+export const WIDGET_KEY_MAX_LENGTH = 80 + 1 + WIDGET_ID_MAX_LENGTH;
+
+/** Maximum settings a widget can declare. */
+export const WIDGET_SETTINGS_MAX_FIELDS = 4;
+/** Maximum setting name length, matching /^[a-z][a-zA-Z0-9]{0,31}$/. */
+export const WIDGET_SETTING_NAME_MAX_LENGTH = 32;
+/** Maximum options in a choice setting; at least one is required. */
+export const WIDGET_SETTING_MAX_OPTIONS = 6;
+/** Maximum text setting length, also used when no maxLength is declared. */
+export const WIDGET_SETTING_TEXT_MAX_LENGTH = 200;
+/** Maximum board entries in one widget stream request. */
+export const WIDGET_REQUEST_MAX_ENTRIES = 100;
+/** Maximum board entry identifier length, in characters. */
+export const WIDGET_REQUEST_MAX_ID_LENGTH = 120;
+const jsonCodeUnitMaxBytes = "\\u001f".length;
+const resourceRefMaxBytes =
+  '{"type":"","id":""}'.length + CAPABILITY_QUALIFIED_ID_MAX_LENGTH + CLOUD_RESOURCE_ID_MAX_LENGTH * jsonCodeUnitMaxBytes;
+const settingMemberMaxBytes = '"":'.length + WIDGET_SETTING_NAME_MAX_LENGTH + resourceRefMaxBytes;
+const settingsMaxBytes = "{}".length + WIDGET_SETTINGS_MAX_FIELDS * settingMemberMaxBytes + (WIDGET_SETTINGS_MAX_FIELDS - 1) * ",".length;
+const sizeNameMaxBytes = Math.max(...DASHBOARD_WIDGET_SIZES.map((size) => size.length));
+const requestEntryMaxBytes =
+  '{"id":"","key":"","size":"","settings":}'.length +
+  WIDGET_REQUEST_MAX_ID_LENGTH * jsonCodeUnitMaxBytes +
+  WIDGET_KEY_MAX_LENGTH +
+  sizeNameMaxBytes +
+  settingsMaxBytes;
+/**
+ * Largest compact JSON POST body in UTF-8: 100 entries with maximum IDs, keys, size names and four settings.
+ * Free-form entry and resource IDs need up to six bytes per UTF-16 code unit (e.g. `\u001f`); keys, size names,
+ * setting names and resource types are ASCII. A resource reference is larger than 200 text characters at six bytes
+ * each. Include every object's punctuation and the commas between entries and settings.
+ */
+export const WIDGET_REQUEST_MAX_BYTES =
+  '{"widgets":['.length + WIDGET_REQUEST_MAX_ENTRIES * requestEntryMaxBytes + (WIDGET_REQUEST_MAX_ENTRIES - 1) * ",".length + "]}".length;
+
+/** A widget's editable setting; resource values carry identity, never authorization. */
+export type WidgetSettingField =
+  | { kind: "choice"; label: string; options: readonly { label: string; value: string }[]; default?: string }
+  | { kind: "resource"; label: string; type: string }
+  | { kind: "toggle"; label: string; default?: boolean }
+  | { kind: "text"; label: string; placeholder?: string; maxLength?: number };
+/** Settings keyed by short camelCase names, shared by discovery and request validation. */
+export type WidgetSettingsDeclaration = Readonly<Record<string, WidgetSettingField>>;
+/** A validated setting value; a handler must still authorize every resource reference. */
+export type WidgetSettingValue = string | boolean | CloudResourceRef;
+/** Validated widget settings; handlers must also work when values are missing. */
+export type WidgetSettings = Readonly<Record<string, WidgetSettingValue>>;
 
 export const isDashboardWidgetSize = (value: unknown): value is DashboardWidgetSize =>
   DASHBOARD_WIDGET_SIZES.some((size) => size === value);
@@ -89,10 +143,15 @@ export const fitWidgetSize = (
   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)`. */
+/**
+ * What the dashboard asks a widget handler for, read with `getWidgetRequest(c)`. Settings are validated against the
+ * declaration; handlers must still authorize every chosen resource and work without settings.
+ */
 export type WidgetRequest = {
   /** The size the widget is shown in, always one the widget declares. */
   size: DashboardWidgetSize;
+  /** Declared, validated values with choice and toggle defaults filled. */
+  settings: WidgetSettings;
 };
 
 export const WidgetAccentSchema = z
@@ -237,12 +296,27 @@ export const widgetKey = (appId: string, widgetId: string): string => `${appId}/
 export type WidgetStreamStatus = "ok" | "empty" | "forbidden" | "timeout" | "error";
 
 /**
- * One line of `GET /api/widgets/v1` (`application/x-ndjson`): `start` names the widgets Core asks, in registry
- * order; one `widget` line follows per widget in the order they finish; `done` closes the stream. Every widget named
- * in `start` gets exactly one line.
+ * One line of `GET` or `POST /api/widgets/v1` (`application/x-ndjson`). GET names widget keys in registry order; POST
+ * names entry ids in request order. One `widget` line follows per entry in the order they finish; `done` closes the
+ * stream. Every name in `start` gets exactly one line. Only POST widget lines include a board entry id.
  */
 export type WidgetStreamLine =
   | { type: "start"; widgets: string[] }
-  | { type: "widget"; key: string; status: "ok"; widget: WidgetResponse; ms: number }
-  | { type: "widget"; key: string; status: Exclude<WidgetStreamStatus, "ok">; ms: number }
+  | {
+      type: "widget";
+      /** Board entry id, set only for POST entries. */
+      id?: string;
+      key: string;
+      status: "ok";
+      widget: WidgetResponse;
+      ms: number;
+    }
+  | {
+      type: "widget";
+      /** Board entry id, set only for POST entries. */
+      id?: string;
+      key: string;
+      status: Exclude<WidgetStreamStatus, "ok">;
+      ms: number;
+    }
   | { type: "done"; status: "complete" | "partial" };

package/src/desktop/index.ts

@@ -304,8 +304,9 @@ let sqlInstance: DesktopSql | null = null;
 
 const getSql = (): DesktopSql => {
   if (sqlInstance) return sqlInstance;
-  const req = runtimeRequire();
-  if (!req || typeof window !== "undefined") throw new Error("desktop.sql is only available in the Bun desktop process.");
+  // Checked before `runtimeRequire`: its `Function` probe would report a `script-src` violation under a CSP without 'unsafe-eval'.
+  const req = typeof window === "undefined" ? runtimeRequire() : null;
+  if (!req) throw new Error("desktop.sql is only available in the Bun desktop process.");
   const requireFn = req as (id: string) => unknown;
 
   const { Database } = requireFn("bun:sqlite") as { Database: new (path: string) => any };

package/src/desktop/solid.tsx

@@ -1,5 +1,5 @@
 import { suppressTextSelection } from "@k2b/ui";
-import { deserialize as deserializeProps, serialize as serializeProps } from "seroval";
+import { fromJSON, toJSON } from "seroval";
 import type { Component, JSX, ParentProps } from "solid-js";
 import { children, createContext, createMemo, createSignal, For, onCleanup, onMount, Show, useContext } from "solid-js";
 import { Dynamic, Portal } from "solid-js/web";
@@ -48,7 +48,7 @@ export const defineDesktopWindows = <Definitions extends Record<string, DesktopW
       ({
         kind: desktopWindowDescriptorKind,
         name,
-        props: serializeProps(props ?? {}),
+        props: JSON.stringify(toJSON(props ?? {})),
       }) satisfies DesktopWindowDescriptor as unknown as JSX.Element;
   }
 
@@ -69,12 +69,14 @@ export function DesktopWindowHost<Definitions extends Record<string, DesktopWind
   const descriptor = createMemo(() => nativeDescriptor());
   const component = createMemo(() => {
     const current = descriptor();
-    return current ? props.windows.__desktopWindowDefinitions[current.name] : null;
+    if (!current) return null;
+    // The name comes from the URL: only a registered window resolves, never an inherited member such as `constructor`.
+    const definitions = props.windows.__desktopWindowDefinitions;
+    return Object.hasOwn(definitions, current.name) ? definitions[current.name] : null;
   });
   const windowProps = createMemo(() => {
     const current = descriptor();
-    if (!current) return {};
-    return deserializeProps<Record<string, unknown>>(current.props);
+    return current && component() ? fromJSON<Record<string, unknown>>(JSON.parse(current.props)) : {};
   });
 
   return createMemo(() => {

package/src/server/widget-request.ts

@@ -1,8 +1,24 @@
 import type { Context } from "hono";
-import { type DashboardWidgetSize, fitWidgetSize, resolveWidgetSizes, type WidgetRequest } from "../contracts/widgets";
+import { parseWidgetSettings } from "../_internal/widget-settings";
+import {
+  type DashboardWidgetSize,
+  fitWidgetSize,
+  resolveWidgetSizes,
+  type WidgetRequest,
+  type WidgetSettingsDeclaration,
+} from "../contracts/widgets";
 
 /** The query parameter Core uses to ask a widget handler for one size. */
 export const WIDGET_SIZE_PARAM = "size";
+/** The query parameter Core uses to send one entry's validated settings. */
+export const WIDGET_SETTINGS_PARAM = "settings";
+/**
+ * Bun's default maximum request head is 16 KiB (a 17,000-character query was verified to return 431). The invocation
+ * JWT uses up to 4 KiB (IDENTITY_MAX_COMPACT_TOKEN_BYTES), and the path and other forwarded headers use about 1–2 KiB,
+ * leaving headroom for 8 KiB of URL-encoded settings. Core measures that encoding and never forwards more. A decoded
+ * value is never longer than its encoding, so the app never drops settings Core sends; longer input counts as missing.
+ */
+export const WIDGET_SETTINGS_PARAM_MAX_LENGTH = 8 * 1024;
 
 const requests = new WeakMap<Request, WidgetRequest>();
 
@@ -12,9 +28,21 @@ const requests = new WeakMap<Request, WidgetRequest>();
  */
 export const setWidgetRequest = (
   c: Context,
-  declaration: { sizes?: readonly DashboardWidgetSize[]; defaultSize?: DashboardWidgetSize },
+  declaration: { sizes?: readonly DashboardWidgetSize[]; defaultSize?: DashboardWidgetSize; settings?: WidgetSettingsDeclaration },
 ): WidgetRequest => {
-  const request = { size: fitWidgetSize(c.req.query(WIDGET_SIZE_PARAM), resolveWidgetSizes(declaration)) };
+  const param = c.req.query(WIDGET_SETTINGS_PARAM);
+  let raw: unknown;
+  if (param !== undefined && param.length <= WIDGET_SETTINGS_PARAM_MAX_LENGTH) {
+    try {
+      raw = JSON.parse(param);
+    } catch {
+      /* Malformed settings are treated as missing values. */
+    }
+  }
+  const request = {
+    size: fitWidgetSize(c.req.query(WIDGET_SIZE_PARAM), resolveWidgetSizes(declaration)),
+    settings: parseWidgetSettings(declaration.settings, raw),
+  };
   requests.set(c.req.raw, request);
   return request;
 };
@@ -22,6 +50,7 @@ export const setWidgetRequest = (
 /**
  * What the dashboard asks this widget handler for. `size` is always one of the sizes the widget declares; return the
  * content that fits it, for example only the one number in `small`. Outside a dashboard invocation, such as a request
- * to the handler's own public route, the request is `large`, the height every widget had before sizes existed.
+ * to the handler's own public route, the request is `{ size: "large", settings: {} }`. Settings are validated against
+ * the declaration. The handler must still authorize every chosen resource on every call and work without settings.
  */
-export const getWidgetRequest = (c: Context): WidgetRequest => requests.get(c.req.raw) ?? { size: "large" };
+export const getWidgetRequest = (c: Context): WidgetRequest => requests.get(c.req.raw) ?? { size: "large", settings: {} };

package/src/services/app-approval.ts

@@ -296,7 +296,8 @@ export const createAppApprovalService = (
           UPDATE auth.app_devices d SET action_wake_at=now(), action_wake_ref=${approvalId}::uuid
           WHERE d.id IN (
             SELECT device.id FROM auth.app_devices device JOIN approvals.requests r ON r.approver_user_id=device.user_id
-            WHERE r.id=${approvalId}::uuid AND r.status='pending' AND r.expires_at > now()
+            JOIN auth.users u ON u.id=r.approver_user_id
+            WHERE r.id=${approvalId}::uuid AND r.status='pending' AND r.expires_at > now() AND r.approver_auth_epoch=u.auth_epoch
               AND EXISTS (SELECT 1 FROM ai.pending_actions p JOIN ai.turns t ON t.id=p.turn_id
                 WHERE p.approval_id=r.id AND p.status='pending' AND t.run_config->>'signedInSession' IS NULL)
               AND device.issuer=${cfg.issuer} AND device.revoked_at IS NULL AND device.push_token IS NOT NULL
@@ -661,7 +662,8 @@ export const createAppApprovalService = (
       };
       const result = (state: string) => ({ state, pollAfterSeconds: limits.pollSeconds });
       if (!hold) return result((await read()).state);
-      // Listen before the first read so a decision committed in between still wakes this request.
+      // Listen before the first read so a decision committed in between usually wakes this request.
+      // live() has no subscription-ready barrier, so the hint is best effort; the deadline re-read is the guarantee.
       const waiting = new AbortController();
       const ended = new Promise((resolve) => waiting.signal.addEventListener("abort", resolve, { once: true }));
       const stop = () => waiting.abort();