feat(workspaces): add persistent notes widget

Eva · Eva · commit ed69acd55a07 · 2026-07-13T17:56:33.000+07:00
diff --git a/extensions/workspaces/src/schema.test.ts b/extensions/workspaces/src/schema.test.ts
@@ -42,6 +42,13 @@ describe("Workspaces document schema", () => {
     }, "widgets[0].kind");
   });
 
+  it("accepts the trusted notes builtin", () => {
+    const doc = validDoc();
+    doc.tabs[0]!.widgets[0]!.kind = "builtin:notes";
+
+    expect(validateWorkspaceDoc(doc).tabs[0]?.widgets[0]?.kind).toBe("builtin:notes");
+  });
+
   it("rejects a prototype-setter custom widget kind", () => {
     expectInvalid((doc) => {
       doc.tabs[0]!.widgets[0]!.kind = "custom:__proto__";
diff --git a/extensions/workspaces/src/schema.ts b/extensions/workspaces/src/schema.ts
@@ -70,6 +70,7 @@ export const BUILTIN_WIDGET_KINDS = [
   "builtin:cron",
   "builtin:instances",
   "builtin:activity",
+  "builtin:notes",
 ] as const;
 
 const BUILTIN_KINDS = new Set<string>(BUILTIN_WIDGET_KINDS);
diff --git a/extensions/workspaces/src/tools.ts b/extensions/workspaces/src/tools.ts
@@ -59,7 +59,7 @@ const WIDGET_KIND_DESCRIPTION = [
   "builtin:markdown (props {markdown} or {text}, or a file binding of a .md file),",
   "builtin:table (binding id `rows`; props {columns: string[]}),",
   "builtin:iframe-embed (props {url}),",
-  "builtin:sessions, builtin:usage, builtin:cron, builtin:instances, builtin:activity",
+  "builtin:sessions, builtin:usage, builtin:cron, builtin:instances, builtin:activity, builtin:notes",
   "(each reads its own rpc binding; see workspace_get for a worked example).",
   "Charts are not builtins — author one with workspace_widget_scaffold and use custom:<name>.",
 ].join(" ");
diff --git a/ui/src/i18n/locales/en.ts b/ui/src/i18n/locales/en.ts
@@ -2190,6 +2190,12 @@ export const en: TranslationMap = {
       activity: {
         empty: "No recent activity.",
       },
+      notes: {
+        placeholder: "Write a note…",
+        readonlyHint: "Connect to the gateway to edit and save notes.",
+        saveError: "Your note couldn’t be saved. Keep editing and try again.",
+        conflict: "This note changed somewhere else. Copy your edits before reloading.",
+      },
       embed: {
         missing: "This embed has no URL yet.",
         blockedExternal: "External embeds are disabled by your gateway policy.",
diff --git a/ui/src/lib/workspace/widgets/context.ts b/ui/src/lib/workspace/widgets/context.ts
@@ -0,0 +1,85 @@
+import type { GatewayBrowserClient } from "../../../api/gateway.ts";
+import type { WorkspaceWidget } from "../types.ts";
+import type { BuiltinWidgetContext } from "./types.ts";
+
+type BuiltinContextProps = {
+  client: GatewayBrowserClient | null;
+  connected: boolean;
+  basePath?: string;
+  embed?: BuiltinWidgetContext["embed"];
+};
+
+const DEFAULT_EMBED_CONTEXT: BuiltinWidgetContext["embed"] = {
+  embedSandboxMode: "strict",
+  allowExternalEmbedUrls: false,
+};
+
+const builtinStateByClient = new WeakMap<
+  GatewayBrowserClient,
+  Map<string, NonNullable<BuiltinWidgetContext["state"]>>
+>();
+
+function getBuiltinState(
+  client: GatewayBrowserClient,
+  widgetId: string,
+): NonNullable<BuiltinWidgetContext["state"]> {
+  let states = builtinStateByClient.get(client);
+  if (!states) {
+    states = new Map();
+    builtinStateByClient.set(client, states);
+  }
+  const existing = states.get(widgetId);
+  if (existing) {
+    return existing;
+  }
+  const state: NonNullable<BuiltinWidgetContext["state"]> = {
+    get: async () => {
+      const payload = (await client.request("workspaces.widget.state.get", {
+        widgetId,
+      })) as { state?: unknown; version?: unknown } | null;
+      if (
+        typeof payload?.version !== "number" ||
+        !Number.isInteger(payload.version) ||
+        payload.version < 0
+      ) {
+        throw new Error("Invalid widget state response.");
+      }
+      return { state: payload.state ?? null, version: payload.version };
+    },
+    set: async (value, expectedVersion) => {
+      const payload = (await client.request("workspaces.widget.state.set", {
+        widgetId,
+        state: value,
+        expectedVersion,
+      })) as { version?: unknown } | null;
+      if (
+        typeof payload?.version !== "number" ||
+        !Number.isInteger(payload.version) ||
+        payload.version < 1
+      ) {
+        throw new Error("Invalid widget state response.");
+      }
+      return { version: payload.version };
+    },
+  };
+  states.set(widgetId, state);
+  return state;
+}
+
+/** Bind trusted builtin persistence to the host-owned widget id. */
+export function buildBuiltinContext(
+  props: BuiltinContextProps,
+  widget: WorkspaceWidget,
+): BuiltinWidgetContext {
+  const context: BuiltinWidgetContext = {
+    basePath: props.basePath ?? "",
+    embed: props.embed ?? DEFAULT_EMBED_CONTEXT,
+  };
+  if (!props.client || !props.connected) {
+    return context;
+  }
+  return {
+    ...context,
+    state: getBuiltinState(props.client, widget.id),
+  };
+}
diff --git a/ui/src/lib/workspace/widgets/index.ts b/ui/src/lib/workspace/widgets/index.ts
@@ -9,6 +9,7 @@ import { renderCron } from "./cron.ts";
 import { renderIframeEmbed } from "./iframe-embed.ts";
 import { renderInstances } from "./instances.ts";
 import { renderMarkdown } from "./markdown.ts";
+import { renderNotes } from "./notes.ts";
 import { renderSessions } from "./sessions.ts";
 import { renderStatCard } from "./stat-card.ts";
 import { renderTable } from "./table.ts";
@@ -25,6 +26,7 @@ export const BUILTIN_WIDGET_RENDERERS: Record<string, BuiltinWidgetRenderer> = {
   cron: (widget, value) => renderCron(widget, value),
   instances: (widget, value) => renderInstances(widget, value),
   activity: (widget, value) => renderActivity(widget, value),
+  notes: renderNotes,
 };
 
 export function getBuiltinRenderer(kind: string): BuiltinWidgetRenderer | undefined {
diff --git a/ui/src/lib/workspace/widgets/notes.ts b/ui/src/lib/workspace/widgets/notes.ts
@@ -0,0 +1,203 @@
+import { html, type TemplateResult } from "lit";
+import { ref } from "lit/directives/ref.js";
+import { t } from "../../../i18n/index.ts";
+import type { WorkspaceWidget } from "../types.ts";
+import type { BuiltinWidgetContext, BuiltinWidgetState } from "./types.ts";
+import { widgetProps } from "./types.ts";
+
+const NOTES_PERSIST_DEBOUNCE_MS = 500;
+
+function seedText(widget: WorkspaceWidget): string {
+  const text = widgetProps(widget).text;
+  return typeof text === "string" ? text : "";
+}
+
+function isConflict(error: unknown): boolean {
+  return error instanceof Error && /version conflict/i.test(error.message);
+}
+
+const editorBindings = new WeakMap<BuiltinWidgetState, (element: Element | undefined) => void>();
+
+function bindEditor(state: BuiltinWidgetState): (element: Element | undefined) => void {
+  const existing = editorBindings.get(state);
+  if (existing) {
+    return existing;
+  }
+  let textarea: HTMLTextAreaElement | null = null;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let dirty = false;
+  let disconnected = false;
+  let disconnectRevision = 0;
+  let saving = false;
+  let queued = false;
+  let latest = "";
+  let version: number | undefined;
+  let hydrationPending = true;
+  let hydrationStarted = false;
+
+  const showStatus = (key: "saveError" | "conflict" | null): void => {
+    const status = textarea?.parentElement?.querySelector<HTMLElement>(
+      "[data-test-id='workspace-notes-status']",
+    );
+    if (!status) {
+      return;
+    }
+    status.dataset.state = key ? "error" : "idle";
+    status.textContent =
+      key === "conflict"
+        ? t("workspaces.widget.notes.conflict")
+        : key === "saveError"
+          ? t("workspaces.widget.notes.saveError")
+          : "";
+  };
+
+  const persist = async (): Promise<void> => {
+    timer = undefined;
+    if (disconnected) {
+      return;
+    }
+    if (saving) {
+      queued = true;
+      return;
+    }
+    if (version === undefined) {
+      if (hydrationPending) {
+        queued = true;
+        return;
+      }
+      showStatus("saveError");
+      return;
+    }
+    saving = true;
+    queued = false;
+    const value = latest;
+    try {
+      const result = await state.set(value, version);
+      version = result.version;
+      if (latest === value) {
+        dirty = false;
+      }
+      showStatus(null);
+    } catch (error) {
+      showStatus(isConflict(error) ? "conflict" : "saveError");
+    } finally {
+      saving = false;
+      if (!disconnected && queued && latest !== value) {
+        void persist();
+      }
+    }
+  };
+
+  const onInput = (): void => {
+    if (!textarea) {
+      return;
+    }
+    dirty = true;
+    latest = textarea.value;
+    showStatus(null);
+    if (timer !== undefined) {
+      clearTimeout(timer);
+    }
+    timer = setTimeout(() => void persist(), NOTES_PERSIST_DEBOUNCE_MS);
+  };
+
+  const binding = (element: Element | undefined): void => {
+    if (!(element instanceof HTMLTextAreaElement)) {
+      disconnected = true;
+      const revision = ++disconnectRevision;
+      queueMicrotask(() => {
+        if (!disconnected || revision !== disconnectRevision) {
+          return;
+        }
+        if (timer !== undefined) {
+          clearTimeout(timer);
+          timer = undefined;
+        }
+        queued ||= dirty;
+        textarea?.removeEventListener("input", onInput);
+        textarea = null;
+      });
+      return;
+    }
+    disconnected = false;
+    disconnectRevision += 1;
+    if (textarea === element) {
+      return;
+    }
+    textarea?.removeEventListener("input", onInput);
+    textarea = element;
+    if (dirty) {
+      element.value = latest;
+    } else {
+      latest = element.value;
+    }
+    element.addEventListener("input", onInput);
+    if (version !== undefined) {
+      if (dirty && queued && timer === undefined && !saving) {
+        timer = setTimeout(() => void persist(), NOTES_PERSIST_DEBOUNCE_MS);
+      }
+      return;
+    }
+    if (hydrationStarted) {
+      return;
+    }
+    hydrationStarted = true;
+    hydrationPending = true;
+    void state
+      .get()
+      .then((result) => {
+        hydrationPending = false;
+        if (disconnected) {
+          hydrationStarted = false;
+          return;
+        }
+        version = result.version;
+        if (!dirty && typeof result.state === "string" && textarea) {
+          textarea.value = result.state;
+          latest = result.state;
+        }
+        if (dirty && queued) {
+          void persist();
+        }
+      })
+      .catch(() => {
+        hydrationPending = false;
+        hydrationStarted = false;
+        if (dirty) {
+          showStatus("saveError");
+        }
+      });
+  };
+  editorBindings.set(state, binding);
+  return binding;
+}
+
+export function renderNotes(
+  widget: WorkspaceWidget,
+  _value: unknown,
+  context: BuiltinWidgetContext,
+): TemplateResult {
+  const seed = seedText(widget);
+  const status = context.state ? "" : t("workspaces.widget.notes.readonlyHint");
+  return html`
+    <div class="workspace-notes" data-test-id="workspace-notes">
+      <textarea
+        class="workspace-notes__pad"
+        data-test-id="workspace-notes-pad"
+        aria-label=${widget.title ?? t("workspaces.widget.notes.placeholder")}
+        placeholder=${t("workspaces.widget.notes.placeholder")}
+        ?readonly=${!context.state}
+        .value=${seed}
+        ${context.state ? ref(bindEditor(context.state)) : null}
+      ></textarea>
+      <div
+        class="workspace-notes__status"
+        data-test-id="workspace-notes-status"
+        data-state=${context.state ? "idle" : "readonly"}
+        role=${context.state ? "alert" : "status"}
+      >
+        ${status}
+      </div>
+    </div>
+  `;
+}
diff --git a/ui/src/lib/workspace/widgets/types.ts b/ui/src/lib/workspace/widgets/types.ts
@@ -13,6 +13,11 @@ import type { TemplateResult } from "lit";
 import type { ApplicationConfigCapability } from "../../../app/config.ts";
 import type { WorkspaceWidget } from "../types.ts";
 
+export type BuiltinWidgetState = {
+  get(): Promise<{ state: unknown; version: number }>;
+  set(state: unknown, expectedVersion: number): Promise<{ version: number }>;
+};
+
 /** Ambient context a builtin may need beyond its own binding value. */
 export type BuiltinWidgetContext = {
   /** Control UI mount path used by builtins that link to another app route. */
@@ -22,6 +27,8 @@ export type BuiltinWidgetContext = {
     ApplicationConfigCapability["current"],
     "embedSandboxMode" | "allowExternalEmbedUrls"
   >;
+  /** Host-bound persistence for trusted builtins; absent without a gateway client. */
+  state?: BuiltinWidgetState;
 };
 
 /** A builtin widget renderer: pure, side-effect-free, throws only on real bugs. */
diff --git a/ui/src/lib/workspace/widgets/widgets.test.ts b/ui/src/lib/workspace/widgets/widgets.test.ts
diff --git a/ui/src/pages/plugin/workspace-view.ts b/ui/src/pages/plugin/workspace-view.ts
diff --git a/ui/src/styles/workspace.css b/ui/src/styles/workspace.css
