@skillcdn/console 0.4.3 → 0.4.5

package/src/plugin/rest-schemas.ts

@@ -7,6 +7,7 @@ import {
   MAX_PROJECT_DESCRIPTION_LENGTH,
   MAX_PROJECT_KEY_LENGTH,
   MAX_PROJECT_NAME_LENGTH,
+  MAX_TEAM_KEY_LENGTH,
 } from "../limits.js";
 import { PLUGIN_STATES } from "../vocabulary.js";
 import { ARG_TYPES } from "./args.js";
@@ -21,6 +22,7 @@ import {
   PLUGIN_PAGE_LEVELS,
   PLUGIN_SETTING_TYPES,
   PLUGIN_WIDGET_PLACES,
+  PLUGIN_WIDGET_SIZE_NAMES,
   PLUGIN_WIDGET_SIZES,
   SETTING_KEY_PATTERN,
 } from "./manifest.js";
@@ -91,7 +93,11 @@ export const restPluginWidgetSchema = z.object({
   key: z.string(),
   name: localized,
   place: z.enum(PLUGIN_WIDGET_PLACES),
+  /** The size of before nearest to the one it starts at, for a reader of before. */
   size: z.enum(PLUGIN_WIDGET_SIZES),
+  /** The sizes the widget comes in (ADR-0059) and the one it starts at; answered from 0.4.4 and read as optional. */
+  sizes: z.optional(z.array(z.enum(PLUGIN_WIDGET_SIZE_NAMES))),
+  defaultSize: z.optional(z.enum(PLUGIN_WIDGET_SIZE_NAMES)),
 });
 export type RestPluginWidget = z.infer<typeof restPluginWidgetSchema>;
 
@@ -103,13 +109,28 @@ export const restPluginSchema = z.object({
   /** The sentence agents read with the rules, or `null` for the description. */
   agentNote: z.nullable(localized),
   version: z.string(),
+  /**
+   * The consoles the plugin declares it runs on, a semver range of the console's version, or
+   * `null` where the manifest names none; a console outside it fails the plugin with the reason
+   * in `problems`. Answered from 0.4.4 and read as optional, so that a console built on this
+   * package still reads an older console's answer.
+   */
+  console: z.optional(z.nullable(z.string())),
   state: z.enum(PLUGIN_STATES),
   /** Why the plugin failed, or waits for consent; empty otherwise. */
   problems: z.array(z.string()),
   /** The asker's roles in the plugin; every role for an administrator. */
   roles: z.array(z.string()),
   /** The roles the plugin declares, by key, with their names. */
-  declaredRoles: z.array(z.object({ key: z.string(), name: localized, description: localized })),
+  declaredRoles: z.array(
+    z.object({
+      key: z.string(),
+      name: localized,
+      description: localized,
+      /** What the role follows, held with no grant: `reports`, whoever manages someone (ADR-0068); answered from 0.4.5 and read as optional. */
+      follows: z.optional(z.nullable(z.literal("reports"))),
+    }),
+  ),
   /** The role every member holds without a grant, or `null` where the manifest names none. */
   defaultRole: z.nullable(z.string()),
   menu: z.nullable(z.object({ group: z.string(), order: z.int(), name: z.nullable(localized) })),
@@ -121,6 +142,8 @@ export const restPluginSchema = z.object({
   boardNeeds: z.enum(PLUGIN_BOARD_NEEDS),
   /** What the plugin asks, and what was consented to; `consent` is `null` to a member. */
   capabilities: z.array(z.string()),
+  /** What it can go without (ADR-0060), an administrator's to turn on; a console older than them names none. */
+  optionalCapabilities: z.optional(z.array(z.string())),
   consent: z.nullable(z.array(z.string())),
   /** The projects the plugin is on: all, their keys, or `null` to a member. */
   projects: z.nullable(z.union([z.literal("all"), z.array(z.string())])),
@@ -149,11 +172,21 @@ export const restPluginSettingSchema = z.object({
   max: z.nullable(z.number()),
   options: z.nullable(z.array(z.object({ value: z.string(), name: localized }))),
   of: z.nullable(z.string()),
+  /** The group the setting is shown under, or `null` for above every group; answered from 0.4.4 and read as optional. */
+  group: z.optional(z.nullable(z.string())),
   /** Whether a value is set; a secret's value is never here. */
   set: z.boolean(),
   value: z.nullable(z.unknown()),
   /** When a secret was set, or `null`. */
   setAt: z.nullable(instant),
+  /** When a secret expires, or `null` (ADR-0070); answered from 0.4.5 and read as optional. */
+  expiresAt: z.optional(z.nullable(instant)),
+  /** `administrator` for a secret an administrator set, the host of the answer it was sealed from otherwise, `null` while unset. */
+  source: z.optional(z.nullable(z.string())),
+  /** The hosts a secret is pinned to, or `null` for any the plugin reaches. */
+  hosts: z.optional(z.nullable(z.array(z.string()))),
+  /** `verify` for a secret that verifies and signs nothing, or `null`. */
+  use: z.optional(z.nullable(z.literal("verify"))),
 });
 export type RestPluginSetting = z.infer<typeof restPluginSettingSchema>;
 
@@ -164,6 +197,10 @@ export const restPluginGrantSchema = z.object({
   person: z.nullable(z.object({ id: uuid, login: z.string(), name: z.nullable(z.string()) })),
   project: z.nullable(z.object({ key: z.string(), name: z.string() })),
   everyone: z.boolean(),
+  /** The plugin the role went to (ADR-0072), by key, or `null`; answered from 0.4.5 and read as optional. */
+  plugin: z.optional(z.nullable(z.string())),
+  /** The team the role went to (ADR-0073), whose members hold it, or `null`; answered from 0.4.5 and read as optional. */
+  team: z.optional(z.nullable(z.object({ key: z.string(), name: z.string() }))),
   createdAt: instant,
 });
 export type RestPluginGrant = z.infer<typeof restPluginGrantSchema>;
@@ -179,16 +216,42 @@ export const restPluginDetailSchema = z.extend(restPluginSchema, {
   /** The board project the manifest proposes, for an administrator who makes it; `null` where it proposes none. */
   boardDefaults: z.nullable(z.object({ key: z.string(), name: localized, description: localized })),
   settings: z.array(restPluginSettingSchema),
+  /** The groups the settings form is divided into, in the manifest's order; answered from 0.4.4 and read as optional. */
+  settingGroups: z.optional(
+    z.array(z.object({ key: z.string(), name: localized, description: z.nullable(localized) })),
+  ),
   /** The grants, to an administrator; `null` to a member. */
   grants: z.nullable(z.array(restPluginGrantSchema)),
   /** The plugin's own events are at this path. */
   events: z.string(),
+  /**
+   * Whether the plugin reads a time of day (a job at a time, a `time` setting) while the
+   * workspace has no time zone, so that its times run on UTC with nobody having said so: the
+   * pages and the command tell an administrator to set one. Answered from 0.4.5 and read as optional.
+   */
+  needsTimeZone: z.optional(z.boolean()),
+  /** The collections the plugin keeps for a while only, each with its days, so that an administrator reads what it forgets; answered from 0.4.5 and read as optional. */
+  keeps: z.optional(z.array(z.object({ collection: z.string(), days: z.int() }))),
+  /**
+   * What the manifest asks of other plugins (ADR-0072): a role of a plugin, why, and how it
+   * stands: granted, not yet, or the plugin is not enabled. Answered from 0.4.5 and read as optional.
+   */
+  asks: z.optional(
+    z.array(
+      z.object({
+        plugin: z.string(),
+        role: z.string(),
+        why: localized,
+        state: z.enum(["granted", "ungranted", "unavailable"]),
+      }),
+    ),
+  ),
 });
 export type RestPluginDetail = z.infer<typeof restPluginDetailSchema>;
 
 /** What `POST /api/v1/plugins/<key>/enable` is sent. */
 export const restPluginEnableInputSchema = z.object({
-  /** Every capability the manifest asks, named again: consent. */
+  /** Every capability the manifest requires, named again, and the optional ones to turn on: consent. */
   consent: z.array(z.string().check(z.maxLength(300))).check(z.maxLength(50)),
   /** The board project: one to make, one that exists, or none. */
   board: z.nullable(
@@ -216,6 +279,12 @@ export const restPluginSettingsPatchSchema = z.object({
 });
 export type RestPluginSettingsPatch = z.infer<typeof restPluginSettingsPatchSchema>;
 
+/** What `PATCH /api/v1/plugins/<key>/consent` is sent: what the plugin holds from now on, those it requires named again. */
+export const restPluginConsentPatchSchema = z.object({
+  consent: z.array(z.string().check(z.maxLength(300))).check(z.maxLength(50)),
+});
+export type RestPluginConsentPatch = z.infer<typeof restPluginConsentPatchSchema>;
+
 /** What `PUT /api/v1/plugins/<key>/secrets/<name>` is sent. */
 export const restPluginSecretInputSchema = z.object({
   value: z.string().check(z.minLength(1), z.maxLength(MAX_PLUGIN_SECRET_LENGTH)),
@@ -228,15 +297,23 @@ export const restPluginGrantInputSchema = z
     role: pluginKey,
     person: z.optional(uuid),
     project: z.optional(projectKey),
+    /** A plugin, by key, to hold the role as itself (ADR-0072). */
+    plugin: z.optional(pluginKey),
+    /** A team, by its key (ADR-0074), whose members hold the role (ADR-0073). */
+    team: z.optional(z.string().check(z.minLength(1), z.maxLength(MAX_TEAM_KEY_LENGTH))),
     everyone: z.optional(z.literal(true)),
   })
   .check(
     z.refine(
       (input) =>
-        [input.person !== undefined, input.project !== undefined, input.everyone === true].filter(
-          Boolean,
-        ).length === 1,
-      "names a person, a project or everyone, one of the three",
+        [
+          input.person !== undefined,
+          input.project !== undefined,
+          input.plugin !== undefined,
+          input.team !== undefined,
+          input.everyone === true,
+        ].filter(Boolean).length === 1,
+      "names a person, a project, a plugin, a team or everyone, one of the five",
     ),
   );
 export type RestPluginGrantInput = z.infer<typeof restPluginGrantInputSchema>;
@@ -285,6 +362,12 @@ export const restPluginInvocationSchema = z.object({
   text: z.string(),
   data: z.unknown(),
   waiting: z.nullable(z.string()),
+  /**
+   * The key of the project the decision in `waiting` waits in, the one it was raised in, where
+   * the caller reaches it, else `null`; with nothing waiting, the plugin's board project's, or
+   * `null`. Answered from 0.4.5 and read as optional.
+   */
+  project: z.optional(z.nullable(z.string())),
 });
 export type RestPluginInvocation = z.infer<typeof restPluginInvocationSchema>;
 

package/src/plugin/sandbox.ts

@@ -13,6 +13,15 @@ export const FORBIDDEN_BUILTINS: readonly string[] = [
   "dgram",
   "dns",
   "dns/promises",
+  // The same network, under the names Node keeps for compatibility.
+  "_http_agent",
+  "_http_client",
+  "_http_common",
+  "_http_incoming",
+  "_http_outgoing",
+  "_http_server",
+  "_tls_common",
+  "_tls_wrap",
   "child_process",
   "cluster",
   "worker_threads",
@@ -67,6 +76,15 @@ export interface HardenedThread {
   readonly removed: readonly string[];
 }
 
+/** What a plugin is told of a built-in it may not have, by whichever way it asked. */
+function refusedBuiltin(specifier: string): Error {
+  const error = new Error(
+    `the host refuses ${specifier}: a plugin reaches the console through ctx alone`,
+  );
+  (error as { code?: string }).code = "ERR_PLUGIN_FORBIDDEN_BUILTIN";
+  return error;
+}
+
 /** The module hook: refuses the forbidden built-ins and lets everything else resolve as it would. */
 export function forbiddingResolve<C, R>(
   specifier: string,
@@ -74,19 +92,16 @@ export function forbiddingResolve<C, R>(
   nextResolve: (specifier: string, context: C) => R,
 ): R {
   if (isForbiddenBuiltin(specifier)) {
-    const error = new Error(
-      `the host refuses ${specifier}: a plugin reaches the console through ctx alone`,
-    );
-    (error as { code?: string }).code = "ERR_PLUGIN_FORBIDDEN_BUILTIN";
-    throw error;
+    throw refusedBuiltin(specifier);
   }
   return nextResolve(specifier, context);
 }
 
 /**
- * Hardens the current thread: refuses the forbidden built-ins through the module hooks, removes
- * the globals, empties the environment, and blocks `process.binding`. Call it in a worker thread
- * before importing plugin code; it reaches nothing outside that thread.
+ * Hardens the current thread: refuses the forbidden built-ins through the module hooks and through
+ * `process.getBuiltinModule`, which goes round them, removes the globals, empties the environment,
+ * and blocks `process.binding`. Call it in a worker thread before importing plugin code; it reaches
+ * nothing outside that thread.
  */
 export function hardenThread(
   moduleApi: Pick<typeof import("node:module"), "registerHooks">,
@@ -112,6 +127,19 @@ export function hardenThread(
     for (const name of ["binding", "_linkedBinding", "dlopen"]) {
       Object.defineProperty(proc, name, { value: refuse, writable: false, configurable: false });
     }
+    const getBuiltinModule = proc.getBuiltinModule;
+    if (typeof getBuiltinModule === "function") {
+      Object.defineProperty(proc, "getBuiltinModule", {
+        value: (specifier: string): unknown => {
+          if (isForbiddenBuiltin(specifier)) {
+            throw refusedBuiltin(specifier);
+          }
+          return getBuiltinModule.call(proc, specifier);
+        },
+        writable: false,
+        configurable: false,
+      });
+    }
     const env = proc.env as Record<string, unknown> | undefined;
     if (env !== undefined) {
       for (const key of Object.keys(env)) {

package/src/plugin/semver.ts

@@ -0,0 +1,89 @@
+// Versions and ranges as a manifest spells them (docs/specs/plugins.md, "The manifest"): the
+// range of another plugin's version in `requires`, and the range of the console's version in
+// `console`. Read loosely, as npm spells the common ones, with no library: a plugin declares
+// `>=0.4.3 <0.6`, and the console, the authoring command and the tests compare the same way.
+
+export type Triple = readonly [number, number, number];
+
+/**
+ * A version read loosely: `0.4.3`, `v0.4.3`, `0.6` (as `0.6.0`), `1` (as `1.0.0`), a prerelease or
+ * a build after the numbers ignored; nothing for anything else.
+ */
+export function parseLooseVersion(text: string): Triple | undefined {
+  const match = /^v?(\d+)(?:\.(\d+))?(?:\.(\d+))?(?:[-+].*)?$/.exec(text.trim());
+  return match === null
+    ? undefined
+    : [Number(match[1]), Number(match[2] ?? "0"), Number(match[3] ?? "0")];
+}
+
+export function compareTriples(a: Triple, b: Triple): number {
+  return a[0] - b[0] || a[1] - b[1] || a[2] - b[2];
+}
+
+/**
+ * Whether a version is within a range as npm spells the common ones: `*`, exact, `^`, `~`, `>=`,
+ * `>`, `<=`, `<`, several with spaces between (all must hold) and alternatives with `||` between
+ * (one must hold). A partial version in the range is read as `.0` filled in: `<0.6` is `<0.6.0`.
+ */
+export function satisfiesRange(version: string, range: string): boolean {
+  const have = parseLooseVersion(version);
+  const trimmed = range.trim();
+  if (trimmed === "*" || trimmed === "" || trimmed === "x" || trimmed === "latest") {
+    return true;
+  }
+  if (have === undefined) {
+    return false;
+  }
+  return trimmed.split(/\s*\|\|\s*/).some((alternative) =>
+    alternative.split(/\s+/).every((part) => {
+      const operator = /^(\^|~|>=|<=|>|<|=)?(.*)$/.exec(part);
+      const wanted = parseLooseVersion(operator?.[2] ?? "");
+      if (wanted === undefined) {
+        return false;
+      }
+      switch (operator?.[1]) {
+        case "^":
+          return (
+            compareTriples(have, wanted) >= 0 &&
+            (wanted[0] === 0 ? have[0] === 0 && have[1] === wanted[1] : have[0] === wanted[0])
+          );
+        case "~":
+          return (
+            compareTriples(have, wanted) >= 0 && have[0] === wanted[0] && have[1] === wanted[1]
+          );
+        case ">=":
+          return compareTriples(have, wanted) >= 0;
+        case ">":
+          return compareTriples(have, wanted) > 0;
+        case "<=":
+          return compareTriples(have, wanted) <= 0;
+        case "<":
+          return compareTriples(have, wanted) < 0;
+        default:
+          return compareTriples(have, wanted) === 0;
+      }
+    }),
+  );
+}
+
+/**
+ * The version a dependency spells, read loosely: `^0.4.3`, `~0.4.3`, `>=0.4.3` and `0.4.3` are
+ * all `0.4.3`; `workspace:*`, `*`, `latest` and a tag name none.
+ */
+export function versionOfDependency(spec: string): Triple | undefined {
+  return parseLooseVersion(spec.trim().replace(/^(?:\^|~|>=|=)\s*/, ""));
+}
+
+export function formatTriple(version: Triple): string {
+  return `${version[0]}.${version[1]}.${version[2]}`;
+}
+
+/**
+ * The range of consoles a plugin written against `version` runs on, as `console-plugin init`
+ * writes it: from that version on, within its line, since the plugin API moves with the console's
+ * line before 1.0 (`>=0.4.3 <0.5.0`), and within its major from 1.0 (`>=1.2.0 <2.0.0`).
+ */
+export function lineRangeFrom(version: Triple): string {
+  const below: Triple = version[0] === 0 ? [0, version[1] + 1, 0] : [version[0] + 1, 0, 0];
+  return `>=${formatTriple(version)} <${formatTriple(below)}`;
+}

package/src/plugin/testing.ts

@@ -38,6 +38,7 @@ import { PluginRefusal } from "./refusals.js";
 export interface TestConsoleOptions {
   readonly workspace?: PluginConsole["workspace"];
   readonly people?: Partial<PluginConsole["people"]>;
+  readonly teams?: Partial<PluginConsole["teams"]>;
   readonly projects?: Partial<PluginConsole["projects"]>;
   readonly tasks?: Partial<PluginConsole["tasks"]>;
   readonly decisions?: Partial<PluginConsole["decisions"]>;
@@ -45,6 +46,16 @@ export interface TestConsoleOptions {
   readonly runs?: Partial<PluginConsole["runs"]>;
 }
 
+/**
+ * Another plugin as a test gives it: its version and its api; and, where `for` is given, what it
+ * answers when called for a person. Without `for`, it answers the same for anyone.
+ */
+export interface TestOtherPlugin {
+  readonly version: string;
+  readonly api: OtherPlugin["api"];
+  readonly for?: ((personId: string) => TestOtherPlugin) | undefined;
+}
+
 export interface TestContextOptions {
   readonly plugin?: Partial<PluginInfo>;
   readonly caller?: PluginCaller;
@@ -56,7 +67,11 @@ export interface TestContextOptions {
   readonly fetch?: (url: string, init?: PluginFetchInit) => Promise<PluginFetchResponse>;
   /** The secrets by name; `sign` and `verify` use them, and never hand them over. */
   readonly secrets?: Readonly<Record<string, string>>;
-  readonly plugins?: Readonly<Record<string, OtherPlugin>>;
+  readonly plugins?: Readonly<Record<string, TestOtherPlugin>>;
+  /** The console's public origin, from which `ctx.endpoints.url` is answered; left out, it is `plugin.unavailable`. */
+  readonly publicUrl?: string;
+  /** The endpoints the plugin defines, by name, which `ctx.endpoints.url` answers for; any name when left out. */
+  readonly endpoints?: readonly string[];
   readonly now?: () => Date;
   readonly language?: string;
 }
@@ -226,7 +241,7 @@ function memoryRecords<T extends Record<string, unknown>>(
     }
     return found;
   };
-  const by = caller.kind === "person" ? caller.person.id : null;
+  const by = actingPersonOf(caller)?.id ?? null;
   const indexed = (field: string) => {
     if (
       collection !== undefined &&
@@ -519,15 +534,35 @@ function refusingConsole(given: TestConsoleOptions | undefined): PluginConsole {
   return {
     workspace:
       given?.workspace ?? (async () => forbidden("console.workspace", "console.workspace")),
-    people: fill("people", ["list", "get"], given?.people),
+    people: fill("people", ["list", "get", "granted"], given?.people),
+    teams: fill("teams", ["list", "get"], given?.teams),
     projects: fill("projects", ["list", "get", "members"], given?.projects),
     tasks: fill("tasks", ["list", "get", "create", "update", "comment"], given?.tasks),
-    decisions: fill("decisions", ["list", "get", "ask"], given?.decisions),
+    decisions: fill("decisions", ["list", "get", "ask", "answer"], given?.decisions),
     documents: fill("documents", ["list", "read", "write"], given?.documents),
     runs: fill("runs", ["list", "get"], given?.runs),
   };
 }
 
+/** The person a caller acts as: themselves, or the one a plugin acts for; none for the console or a plugin as itself. */
+function actingPersonOf(caller: PluginCaller) {
+  return caller.kind === "person"
+    ? caller.person
+    : caller.kind === "plugin"
+      ? (caller.for ?? undefined)
+      : undefined;
+}
+
+/** Another plugin as the context hands it over: `for` answers as the test said, or the same as for anyone. */
+function withFor(other: TestOtherPlugin): OtherPlugin {
+  const built: OtherPlugin = {
+    version: other.version,
+    api: other.api,
+    for: (personId) => (other.for === undefined ? built : withFor(other.for(personId))),
+  };
+  return built;
+}
+
 function build(store: Store, options: TestContextOptions, caller: PluginCaller): TestContext {
   const now = options.now ?? (() => new Date());
   const collections = new Map(
@@ -538,8 +573,10 @@ function build(store: Store, options: TestContextOptions, caller: PluginCaller):
     version: "0.0.0",
     dataVersion: 1,
     settings: {},
+    capabilities: [],
     board: null,
     projects: "all",
+    grants: [],
     ...options.plugin,
   };
   const secrets = options.secrets ?? {};
@@ -570,6 +607,12 @@ function build(store: Store, options: TestContextOptions, caller: PluginCaller):
     fetch: options.fetch ?? (async () => forbidden("fetch", "fetch")),
     secrets: {
       has: async (name) => name in secrets,
+      status: async (name) => ({
+        set: name in secrets,
+        setAt: name in secrets ? now().toISOString() : null,
+        expiresAt: null,
+        source: name in secrets ? "administrator" : null,
+      }),
       sign: async (name, payload) => {
         const secret = secrets[name];
         if (secret === undefined) {
@@ -590,12 +633,26 @@ function build(store: Store, options: TestContextOptions, caller: PluginCaller):
         if (other === undefined) {
           forbidden(`plugins.get(${key})`, `plugins.${key}`);
         }
-        return other;
+        return withFor(other);
+      },
+    },
+    endpoints: {
+      async url(name) {
+        if (options.endpoints !== undefined && !options.endpoints.includes(name)) {
+          throw new PluginRefusal("plugin.not_found", `the plugin defines no endpoint ${name}`);
+        }
+        if (options.publicUrl === undefined) {
+          throw new PluginRefusal(
+            "plugin.unavailable",
+            "this console has no public address (PUBLIC_URL) to reach its endpoints at",
+          );
+        }
+        return `${options.publicUrl}/api/v1/plugins/${encodeURIComponent(plugin.key)}/x/${encodeURIComponent(name)}`;
       },
     },
     log: { info: log("info"), warn: log("warn"), error: log("error") },
     now,
-    language: options.language ?? (caller.kind === "person" ? caller.person.language : "en"),
+    language: options.language ?? actingPersonOf(caller)?.language ?? "en",
     signal: new AbortController().signal,
     emitted: store.emitted,
     logged: store.logged,

package/src/plugin/web.ts

@@ -11,11 +11,14 @@ import {
   type BridgeFile,
   type BridgeInit,
   type BridgeMethod,
+  type BridgePicture,
   type BridgeToPage,
   isBridgePath,
   isBridgeToFrame,
+  isBridgeUrl,
   MAX_BRIDGE_TITLE_LENGTH,
   PLUGIN_BRIDGE_VERSION,
+  type PluginWidgetSizeName,
 } from "./bridge.js";
 import type { PluginRecord, RecordPage, RecordVersion } from "./context.js";
 
@@ -111,8 +114,21 @@ export interface PluginFrame {
       type: string,
     ): Promise<{ readonly handle: string }>;
   };
+  readonly people: {
+    /**
+     * An address to put in an image, of the person of that id (ADR-0063), with `people:read`; or
+     * `null` for a person with no picture to show. Kept for the life of the frame.
+     */
+    picture(id: string): Promise<string | null>;
+  };
   /** The console's page follows a path of the console's in place; a URL is refused. */
   navigate(path: string): void;
+  /**
+   * The console's page opens a web or a mail address in a new tab (ADR-0067), for a link a
+   * person pressed: call it from the press itself, since the page opens nothing but right after
+   * one. Anything else, a path of the console's included, is refused; `navigate` takes those.
+   */
+  open(url: string): void;
   /** The console's page downloads a file of this plugin. */
   download(id: string): void;
   setTitle(text: string): void;
@@ -125,12 +141,21 @@ export interface PluginFrame {
   onTheme(handler: (theme: Readonly<Record<string, string>>) => void): () => void;
   /** The console navigated within this page's address. */
   onPath(handler: (path: string) => void): () => void;
+  /** The person gave the widget another size (ADR-0059); `context.size` was the first. */
+  onSize(handler: (size: PluginWidgetSizeName) => void): () => void;
   /** Stops listening to the console's page. */
   close(): void;
 }
 
 const DEFAULT_CONNECT_MS = 10_000;
 
+/** What a page is told for a person with no picture to show, which is no failure of the page's. */
+const NO_PICTURE: ReadonlySet<string> = new Set([
+  "plugin.not_found",
+  "picture.refused",
+  "picture.unavailable",
+]);
+
 function globalWindow(): FrameWindow {
   const candidate = (globalThis as { window?: FrameWindow }).window;
   if (candidate === undefined) {
@@ -219,7 +244,9 @@ export function connect(options: ConnectOptions = {}): Promise<PluginFrame> {
   const eventHandlers = new Set<(kind: BridgeEventKind, data: unknown) => void>();
   const themeHandlers = new Set<(theme: Readonly<Record<string, string>>) => void>();
   const pathHandlers = new Set<(path: string) => void>();
+  const sizeHandlers = new Set<(size: PluginWidgetSizeName) => void>();
   const subscribed = new Set<BridgeEventKind>();
+  const pictures = new Map<string, Promise<string | null>>();
   let counter = 0;
   let stopHeight: (() => void) | undefined;
 
@@ -301,6 +328,26 @@ export function connect(options: ConnectOptions = {}): Promise<PluginFrame> {
                 }>;
               },
             },
+            people: {
+              picture: (id) => {
+                const kept = pictures.get(id);
+                if (kept !== undefined) {
+                  return kept;
+                }
+                const asked = (call("people.picture", { id }) as Promise<BridgePicture>).then(
+                  ({ type, bytes }) => URL.createObjectURL(new Blob([bytes], { type })),
+                  (error: unknown) => {
+                    if (error instanceof PluginBridgeError && NO_PICTURE.has(error.code)) {
+                      return null;
+                    }
+                    pictures.delete(id);
+                    throw error;
+                  },
+                );
+                pictures.set(id, asked);
+                return asked;
+              },
+            },
             navigate: (path) => {
               if (!isBridgePath(path)) {
                 throw new PluginBridgeError({
@@ -310,6 +357,16 @@ export function connect(options: ConnectOptions = {}): Promise<PluginFrame> {
               }
               post({ v: PLUGIN_BRIDGE_VERSION, t: "navigate", path });
             },
+            open: (url) => {
+              if (!isBridgeUrl(url)) {
+                throw new PluginBridgeError({
+                  code: "plugin.forbidden",
+                  message:
+                    "open takes a web or a mail address; navigate takes a path of the console's",
+                });
+              }
+              post({ v: PLUGIN_BRIDGE_VERSION, t: "open", url });
+            },
             download: (id) => post({ v: PLUGIN_BRIDGE_VERSION, t: "download", id }),
             setTitle: (text) => {
               const title = text.slice(0, MAX_BRIDGE_TITLE_LENGTH).replace(/[\r\n]+/g, " ");
@@ -338,6 +395,10 @@ export function connect(options: ConnectOptions = {}): Promise<PluginFrame> {
               pathHandlers.add(handler);
               return () => pathHandlers.delete(handler);
             },
+            onSize: (handler) => {
+              sizeHandlers.add(handler);
+              return () => sizeHandlers.delete(handler);
+            },
             close: () => {
               win.removeEventListener("message", listener);
               stopHeight?.();
@@ -393,6 +454,11 @@ export function connect(options: ConnectOptions = {}): Promise<PluginFrame> {
             handler(message.path);
           }
           return;
+        case "size":
+          for (const handler of sizeHandlers) {
+            handler(message.size);
+          }
+          return;
         default:
           return;
       }