@jini-ai/agent-plugins 0.6.16 → 0.6.19

package/google-workspace/tovu-connections.json

@@ -0,0 +1,35 @@
+{
+  "schemaVersion": 1,
+  "connections": [
+    {
+      "id": "account",
+      "module": "lib/auth.mjs",
+      "label": "Google Workspace",
+      "authorizationEndpoint": "https://accounts.google.com/o/oauth2/v2/auth",
+      "tokenEndpoint": "https://oauth2.googleapis.com/token",
+      "authorizationParams": {
+        "public": { "access_type": "offline", "prompt": "consent" },
+        "confidential": { "access_type": "offline", "include_granted_scopes": "true" }
+      },
+      "forceConsentParams": { "prompt": "consent" },
+      "startParams": [
+        { "name": "trigger_onepick", "maxLength": 8 },
+        { "name": "mimetypes", "maxLength": 256 }
+      ],
+      "callbackFields": [
+        { "name": "picked_file_ids", "maxLength": 4096 }
+      ],
+      "budgets": [
+        { "scope": "connection", "perMinute": 45 },
+        { "scope": "instance", "perMinute": 240 }
+      ],
+      "scopeSets": ["sheets"],
+      "apiOrigins": ["https://sheets.googleapis.com", "https://www.googleapis.com"],
+      "byoClient": true,
+      "clients": {
+        "web": { "clientIdEnv": "TOVU_GOOGLE_WORKSPACE_OAUTH_WEB_CLIENT_ID", "clientSecretEnv": "TOVU_GOOGLE_WORKSPACE_OAUTH_WEB_CLIENT_SECRET" },
+        "desktop": { "clientIdEnv": "TOVU_GOOGLE_WORKSPACE_OAUTH_DESKTOP_CLIENT_ID", "clientSecretEnv": "TOVU_GOOGLE_WORKSPACE_OAUTH_DESKTOP_CLIENT_SECRET" }
+      }
+    }
+  ]
+}

package/google-workspace/tovu-form-destinations.json

@@ -0,0 +1,10 @@
+{
+  "schemaVersion": 1,
+  "destinations": [
+    {
+      "id": "google-sheets",
+      "label": "Google Sheets",
+      "module": "form-destinations/sheets.mjs"
+    }
+  ]
+}

package/google-workspace/ui/README.md

@@ -0,0 +1,73 @@
+# `ui/` - the Google Workspace admin panels
+
+## Purpose
+
+The plugin's own admin screens, declared in `../tovu-admin-surfaces.json` and mounted by the host as
+sandboxed frames (Jini `@jini-ai/agent-plugins/admin-surfaces`; in Tovu,
+`apps/website/src/features/agent-plugins/admin-surfaces/`). Three surfaces:
+
+| surface id | entry | what the person does there |
+|---|---|---|
+| `connection` | `connection-panel.html` | Connect, reconnect, switch account (staged, confirm/cancel; confirming moves only the form destinations the person ticked, each after the new account opened its spreadsheet), disconnect and retry a pending revocation, turn Sheets on/off, grant a product's permission. |
+| `picker` | `picker.html` | Choose a spreadsheet with Google's Picker; see the spreadsheets chosen so far. |
+| `form-destinations` | `destination-panel.html` | Per form: spreadsheet (chosen one or the Picker) + tab (numeric sheet id); save or remove. |
+
+## How it fits
+
+```
+frame (static files, served without credentials, CSP-locked)        server (handlerModule, never served)
+  <name>.mjs ── dom.mjs ── surface-client.mjs ── action-request ──▶ host dispatcher ──▶ <name>.handler.mjs
+                                             ◀── action-response ──                       │
+                                                                       lib/surface-actions.mjs, lib/picker-flow.mjs,
+                                                                       lib/form-destination-settings.mjs, lib/picker-selection.mjs
+```
+
+- Frame files: `*.html` entries, `*.mjs` frame scripts, `panel.css`. Text is always set with
+  `textContent` (`dom.mjs`); no inline script or style (the CSP forbids both).
+- `surface-client.mjs` is a verbatim copy of Jini's self-contained protocol client (see its header);
+  refresh it when the protocol changes.
+- `connection-view.mjs` and `picker-view.mjs` are pure wording modules (no DOM): the honesty rules
+  ("Disconnected locally; Google revocation pending", "cancel changes nothing") live there and are
+  tested there.
+- Sign-in links: the frame has no `allow-popups`, so a handler's `begin` link is opened by the host
+  page ("Continue to sign-in"); no handler returns the link.
+
+## Public API (handler modules)
+
+Form destinations declares the read-only `forms: ["list"]` capability. Its list/save/remove
+results optionally include `forms: [{slug,title}]` (at most 200), so the panel offers site forms by
+title and saves the chosen slug. An empty list keeps an empty selector; a failed initial read shows
+the error without an editor. Only hosts without the capability use the typed short-name fallback.
+The server's existing binding writer still checks that the selected form belongs to this workspace.
+
+Each `*.handler.mjs` default-exports `{ actions, bootstrap? }` for its surface and exports its factory
+(`createConnectionPanelHandlers()`, `createPickerHandlers({}, { now, randomId })`,
+`createDestinationPanelHandlers({}, { now, randomId })`) for tests.
+
+| surface | actions |
+|---|---|
+| `connection` | `status`, `sign-in { action }`, `confirm-switch { reassign: formSlug[] }` (result adds `reassignment: { moved, failed[{ formSlug, code, message }] }`), `cancel-switch`, `disconnect` (result adds `revocation: confirmed \| pending \| not-needed`), `set-product { productId, enabled }` |
+| `picker` | bootstrap; `list-picked`, `verify-picked { sessionId, fileId }`, `start-system-picker`, `finish-system-picker` |
+| `form-destinations` | the Picker's bootstrap and actions, plus `list-destinations`, `list-tabs { spreadsheetId }`, `save-destination { formSlug, spreadsheetId, sheetId, confirmExternalRows }`, `remove-destination { formSlug }` |
+
+Plugin settings keys written here: `products` (`{ sheets: true }`), `picked-spreadsheets` (newest
+first, at most 10, metadata + account), `form-destinations` (`{ <formSlug>: { spreadsheetId, title,
+url, sheetId, tabTitle, accountId } }`, at most 50), and the transient `picker-session:<surface>` /
+`picker-attempt:<surface>`. None holds a token.
+
+## Hosted vs desktop Picker
+
+The host decides (the handler call's `context.hostKind`), and the bootstrap's `mode` tells the frame:
+`system-browser` on a desktop host (Google's native Picker as a code + PKCE sign-in with
+`trigger_onepick` and the spreadsheet MIME filter; `picked_file_ids` comes back through the host's
+callback inbox), `hosted` on a hosted site (the JS Picker inside the frame, with the bootstrap's
+short-lived access token and the public `TOVU_GOOGLE_PICKER_BROWSER_KEY` / `TOVU_GOOGLE_PICKER_APP_ID`).
+`unavailable` names why (not connected, permission missing, Sheets off, or a hosted site without both
+Picker values: `picker-not-configured`). Every selection is verified by `lib/picker-selection.mjs` before it is saved.
+
+## Extension points
+
+A new product adds its switch automatically (the connection panel lists `products.json`); a new
+action needs a declaration in `tovu-admin-surfaces.json` (closed schemas) and a handler in the
+surface's module. Another provider plugin builds its own panels on the same host seam; nothing here
+is imported by a host or Jini.

package/google-workspace/ui/connection-panel.handler.mjs

@@ -0,0 +1,167 @@
+/**
+ * @file Server-side handlers of the Google Workspace connection panel (`ui/connection-panel.html`),
+ * loaded by the host as this surface's `handlerModule` (never served to the frame).
+ *
+ * Exists so the account lifecycle has one honest screen: connect, reconnect (same account, same
+ * connection), switch account (staged: the new account is shown and must be confirmed), turn a
+ * product on or off (a settings write, never a change to what Google granted), grant a product's
+ * permission (a separate sign-in), and revoke. Confirming a switch also moves the form destinations
+ * the person ticked to the new account, each only after the new account opened its spreadsheet; the
+ * rest stay frozen to the old account (a switch never silently changes where rows go). Revocation is reported exactly as the host reports it:
+ * `confirmed` only when Google confirmed; `pending` means the site stopped using the sign-in but Google
+ * has not confirmed, so the panel says so and offers a retry. No result carries a token, a
+ * connection ref or a raw Google scope; scope sets are the plugin's own product ids.
+ */
+import { GOOGLE_ACCOUNT_ACCESS_PAGE } from '../lib/auth.mjs';
+import { verifySpreadsheetAccess } from '../lib/picker-selection.mjs';
+import { PRODUCTS, PRODUCT_STATE_KEY } from '../lib/product-state.mjs';
+import { GoogleWorkspaceError } from '../lib/request-policy.mjs';
+import { assertSpreadsheetId } from '../lib/sheets-client.mjs';
+import { CONNECTION_ID, surfaceAccount, surfaceSheetsClient, withSurfaceFailures } from '../lib/surface-actions.mjs';
+import { readFormDestinations, saveFormDestination } from '../lib/form-destination-settings.mjs';
+
+/** The connection status the frame sees; empty labels are left out (the schemas have no null). @complexity O(1). */
+function connectionView(status) {
+  return {
+    status: status.status,
+    grantedProducts: [...status.grantedScopeSetIds],
+    ...(status.accountLabel ? { accountLabel: status.accountLabel } : {}),
+    ...(status.pendingSwitchAccountLabel ? { pendingSwitchAccountLabel: status.pendingSwitchAccountLabel } : {}),
+  };
+}
+
+/** The stored product switches, as `{ <productId>: boolean }` for catalog products only. @complexity O(p). */
+async function productSwitches(state) {
+  const stored = await state.get({ key: PRODUCT_STATE_KEY });
+  return Object.fromEntries(PRODUCTS.products.map((product) => [product.id, stored?.[product.id] === true]));
+}
+
+/**
+ * Everything the panel shows: connection, products (on/off and whether Google granted their
+ * permission), the form destinations (delivery bindings) a switch would affect, and the Google page where a
+ * person can remove access themselves.
+ * @complexity O(p + d): one status read, two state reads.
+ */
+async function panelView(capabilities) {
+  const status = await capabilities.connections.status({ connectionId: CONNECTION_ID });
+  const enabled = await productSwitches(capabilities.state);
+  const destinations = await readFormDestinations({ deliveryBindings: capabilities.deliveryBindings });
+  return {
+    connection: connectionView(status),
+    products: PRODUCTS.products.map((product) => ({ id: product.id, label: product.label, enabled: enabled[product.id], granted: status.grantedScopeSetIds.includes(product.id) })),
+    destinations: Object.entries(destinations).map(([formSlug, saved]) => ({ formSlug, title: saved.title, tabTitle: saved.tabTitle })),
+    accountAccessUrl: GOOGLE_ACCOUNT_ACCESS_PAGE,
+  };
+}
+
+/**
+ * The scope sets a sign-in asks for: what Google already granted plus every product that is on, in
+ * catalog order. Desktop installed apps have no incremental consent, so even "grant a permission" is
+ * a re-consent for the full intended set, never a smaller one that would drop a granted product.
+ * @complexity O(p).
+ */
+async function intendedScopeSets(capabilities) {
+  const status = await capabilities.connections.status({ connectionId: CONNECTION_ID });
+  const enabled = await productSwitches(capabilities.state);
+  return PRODUCTS.products.filter((product) => enabled[product.id] || status.grantedScopeSetIds.includes(product.id)).map((product) => product.id);
+}
+
+/** Fixed sentences for a destination that was not moved; plugin errors keep their own fixed message. */
+const NOT_FOUND = { code: 'destination-not-found', message: 'This form destination is no longer saved. Reload the panel and check Form destinations.' };
+const NOT_MOVED = { code: 'reassign-failed', message: 'This site could not check this spreadsheet with the new account. Choose its spreadsheet again in Form destinations.' };
+
+/** Why one destination was not moved, as the frame may see it (never Google's text). @complexity O(1). */
+function notMoved(formSlug, error) {
+  return { formSlug, ...(error instanceof GoogleWorkspaceError ? { code: error.code, message: error.message } : NOT_MOVED) };
+}
+
+/**
+ * Moves one destination to `accountId`, only after that account opened its spreadsheet through
+ * Drive and the Sheets API; the tab (numeric sheet id) and enabled state stay as chosen.
+ * @complexity O(1): two requests, one binding write.
+ */
+async function moveDestination(capabilities, accountId, formSlug, destination) {
+  const fileId = assertSpreadsheetId({ id: destination.spreadsheetId }, { code: 'invalid-selection' });
+  const verified = await verifySpreadsheetAccess({ client: surfaceSheetsClient({ capabilities }), connectionRef: CONNECTION_ID, fileId });
+  const moved = { spreadsheetId: fileId, title: verified.title, sheetId: destination.sheetId, tabTitle: destination.tabTitle, accountId };
+  await saveFormDestination({ deliveryBindings: capabilities.deliveryBindings, formSlug, destination: moved }, { bindingId: destination.bindingId, enabled: destination.enabled });
+}
+
+/** Tries each ticked destination in turn; a failure leaves that binding exactly as it was. @complexity O(t) moves. */
+async function moveEach(capabilities, accountId, formSlugs) {
+  const destinations = await readFormDestinations({ deliveryBindings: capabilities.deliveryBindings });
+  const outcome = { moved: [], failed: [] };
+  for (const formSlug of formSlugs) {
+    if (!Object.hasOwn(destinations, formSlug)) { outcome.failed.push({ formSlug, ...NOT_FOUND }); continue; }
+    try {
+      await moveDestination(capabilities, accountId, formSlug, destinations[formSlug]);
+      outcome.moved.push(formSlug);
+    } catch (error) {
+      outcome.failed.push(notMoved(formSlug, error));
+    }
+  }
+  return outcome;
+}
+
+/**
+ * After a confirmed switch: the ticked destinations (form slugs) move to the new account; unticked
+ * ones keep the old account, so their deliveries are refused until the person re-picks them.
+ * @complexity O(t): one account read, then two requests and one write per ticked destination.
+ */
+async function reassignDestinations(capabilities, formSlugs) {
+  if (formSlugs.length === 0) return { moved: [], failed: [] };
+  let account;
+  try {
+    account = await surfaceAccount({ capabilities });
+  } catch (error) {
+    return { moved: [], failed: formSlugs.map((formSlug) => notMoved(formSlug, error)) };
+  }
+  return moveEach(capabilities, account.accountId, formSlugs);
+}
+
+/**
+ * Builds the panel's handler module.
+ * @returns {{ actions: Record<string, Function> }} The `handlerModule` default export shape.
+ * @complexity O(1) to build; each action is a bounded number of host calls.
+ */
+export function createConnectionPanelHandlers(_required = {}, _optional = {}) {
+  const act = (fail, run) => withSurfaceFailures({ fail, run });
+  return {
+    actions: {
+      status: ({ capabilities, fail }) => act(fail, () => panelView(capabilities)),
+
+      /** Starts a sign-in; the HOST page offers it (the frame cannot open links). The URL is never returned. */
+      'sign-in': ({ capabilities, input, fail }) => act(fail, async () => {
+        const started = await capabilities.connections.begin({ connectionId: CONNECTION_ID, action: input.action }, { scopeSetIds: await intendedScopeSets(capabilities) });
+        return { expiresAt: started.expiresAt };
+      }),
+
+      /** `reassign`: the form slugs whose destinations move to the new account (none by default). */
+      'confirm-switch': ({ capabilities, input, fail }) => act(fail, async () => {
+        await capabilities.connections.confirmSwitch({ connectionId: CONNECTION_ID });
+        const reassignment = await reassignDestinations(capabilities, [...new Set(input.reassign)]);
+        return { ...(await panelView(capabilities)), reassignment };
+      }),
+
+      'cancel-switch': ({ capabilities, fail }) => act(fail, async () => {
+        await capabilities.connections.cancelSwitch({ connectionId: CONNECTION_ID });
+        return panelView(capabilities);
+      }),
+
+      /** Revoke (and retry a pending revocation): the host's outcome passes through unchanged. */
+      disconnect: ({ capabilities, fail }) => act(fail, async () => {
+        const outcome = await capabilities.connections.disconnect({ connectionId: CONNECTION_ID });
+        return { ...(await panelView(capabilities)), revocation: outcome.revocation };
+      }),
+
+      /** Turns a product on or off. Only the settings change: Google's grant stays as it is. */
+      'set-product': ({ capabilities, input, fail }) => act(fail, async () => {
+        const switches = await productSwitches(capabilities.state);
+        await capabilities.state.set({ key: PRODUCT_STATE_KEY, value: { ...switches, [input.productId]: input.enabled } });
+        return panelView(capabilities);
+      }),
+    },
+  };
+}
+
+export default createConnectionPanelHandlers();

package/google-workspace/ui/connection-panel.html

@@ -0,0 +1,17 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Google Workspace</title>
+<!-- Static and secret-free: served without credentials. Start data arrives in the host's init message. -->
+<link rel="stylesheet" href="panel.css">
+<script type="module" src="connection-panel.mjs"></script>
+</head>
+<body>
+<main>
+<h1 class="sr-only">Google Workspace connection</h1>
+<div id="app" aria-live="polite"><p class="muted">Loading…</p></div>
+</main>
+</body>
+</html>

package/google-workspace/ui/connection-panel.mjs

@@ -0,0 +1,189 @@
+/**
+ * @file The connection panel in the browser: renders the handler's panel view (account, products,
+ * revocation state) and sends the person's choices as declared actions. All wording comes from
+ * `connection-view.mjs`; this file only wires buttons to actions.
+ *
+ * Sign-ins: the panel is a sandboxed frame that cannot open links or popups, so `sign-in` only asks
+ * the server to start one; the admin page above the panel then offers "Continue to sign-in" (in the
+ * desktop app it opens the system browser). The panel polls the status until the sign-in finishes or
+ * its link expires. The Google Account page (to remove access by hand while a revocation is
+ * pending) is opened the same way, through the surface client's `openLink`.
+ */
+import { DISCONNECT_CONFIRM_TEXT, REASSIGN_HINT, connectionSummary, productRows, reassignmentMessage, revocationMessage } from './connection-view.mjs';
+import { busy, connectToHost, failureText, h, notice as noticeLine, show, tip, wait } from './dom.mjs';
+
+const POLL_MS = 4000;
+let client;
+let app;
+let notice = null;
+/** True while the panel asks "Disconnect and revoke?"; the revocation is sent only from that step. */
+let confirmingDisconnect = false;
+
+const call = (action, payload = {}) => client.call({ action, payload });
+
+/** Polls the status after a sign-in started, until the connection changes or the link expires. */
+async function followSignIn(before, expiresAt) {
+  while (Date.now() < Date.parse(expiresAt)) {
+    await wait(POLL_MS);
+    const view = await call('status');
+    // The sign-in finished: the "continue to sign-in" instruction no longer applies.
+    if (JSON.stringify(view.connection) !== JSON.stringify(before.connection)) { notice = null; return render(view); }
+  }
+  notice = { text: 'The sign-in link expired. Start it again if you still want to change the connection.', tone: 'warn' };
+  return render(await call('status'));
+}
+
+/** Runs one action from a button; failures become the notice (with "Try again" when the host says
+ * a retry can help), never a thrown page error. */
+async function run(work) {
+  try {
+    await busy(app, work);
+  } catch (error) {
+    notice = { text: failureText(error), retry: error?.retryable === true ? () => run(work) : undefined };
+    render(lastView);
+  }
+}
+
+const SIGN_IN_ACTIONS = { connect: 'connect', reconnect: 'reconnect', switch: 'switch', grant: 'add-scopes' };
+
+/** What each summary button does. */
+function onAction(action, view) {
+  if (action in SIGN_IN_ACTIONS) return run(async () => {
+    const started = await call('sign-in', { action: SIGN_IN_ACTIONS[action] });
+    notice = { text: 'Continue with the "Continue to sign-in" button the admin page shows above this panel. This panel updates when you are done.', tone: 'info' };
+    render(view);
+    await followSignIn(view, started.expiresAt);
+  });
+  if (action === 'disconnect') { confirmingDisconnect = true; notice = null; return render(view); }
+  if (action === 'confirm-disconnect' || action === 'retry-revocation') return run(async () => {
+    confirmingDisconnect = false;
+    const result = await call('disconnect');
+    notice = { text: revocationMessage({ revocation: result.revocation }), tone: result.revocation === 'confirmed' ? 'ok' : 'warn' };
+    render(result);
+  });
+  if (action === 'confirm-switch') return run(async () => {
+    const result = await call('confirm-switch', { reassign: tickedDestinations() });
+    notice = { text: reassignmentMessage({ reassignment: result.reassignment, destinations: view.destinations }), tone: result.reassignment.failed.length === 0 ? 'ok' : 'warn' };
+    render(result);
+  });
+  return run(async () => { notice = null; render(await call(action)); });
+}
+
+/** The form slugs whose "move to the new account" box is ticked right now. */
+function tickedDestinations() {
+  return [...app.querySelectorAll('input[name="reassign"]')].filter((box) => box.checked).map((box) => box.value);
+}
+
+/** One unticked checkbox per destination while a switch is staged: moving one is always a choice. */
+function reassignList(destinations) {
+  return h('fieldset', { class: 'list reassign' }, [
+    h('legend', {}, [REASSIGN_HINT]),
+    ...destinations.map((entry) => h('label', { class: 'check' }, [
+      h('input', { type: 'checkbox', name: 'reassign', value: entry.formSlug }),
+      `${entry.formSlug}: ${entry.title} / ${entry.tabTitle}`,
+    ])),
+  ]);
+}
+
+/**
+ * The Google Account page, opened by the admin page (the frame cannot open links): only this
+ * surface's declared `linkOrigins` open. The address stays visible in case the host refuses.
+ */
+function accountAccessLink(url) {
+  const open = () => client.openLink({ url }).catch((error) => { notice = { text: failureText(error) }; render(lastView); });
+  return h('p', { class: 'account-link' }, [
+    'Or remove access yourself:', ' ',
+    h('button', { type: 'button', class: 'small', onClick: open }, ['Open Google Account page']),
+    ' ', h('span', { class: 'url' }, [url]),
+  ]);
+}
+
+/** The second step of "Disconnect and revoke": nothing is sent until the person confirms here. */
+function disconnectConfirmation(view) {
+  const cancel = () => { confirmingDisconnect = false; render(view); };
+  return h('div', { class: 'confirm', role: 'group', 'aria-label': 'Confirm disconnect' }, [
+    h('p', {}, [DISCONNECT_CONFIRM_TEXT]),
+    h('div', { class: 'actions' }, [
+      h('button', { type: 'button', class: 'danger', onClick: () => onAction('confirm-disconnect', view) }, ['Yes, disconnect and revoke']),
+      h('button', { type: 'button', onClick: cancel }, ['Cancel']),
+    ]),
+  ]);
+}
+
+function connectionCard(view) {
+  const summary = connectionSummary({ connection: view.connection });
+  const switching = Boolean(view.connection.pendingSwitchAccountLabel);
+  // At most one primary action, and none while all is well (connected); the irreversible one reads
+  // as dangerous and sits apart at the end.
+  const buttonClass = (entry, index) => {
+    if (entry.action === 'disconnect') return 'danger-quiet';
+    return index === 0 && summary.tone !== 'ok' ? 'primary' : undefined;
+  };
+  return h('section', { class: 'card', 'aria-labelledby': 'account-heading' }, [
+    h('div', { class: 'head' }, [
+      h('span', { class: `dot ${summary.tone}`, 'aria-hidden': 'true' }),
+      h('h2', { id: 'account-heading' }, [summary.heading]),
+      tip('About the Google connection', summary.detail),
+    ]),
+    switching && view.destinations.length > 0 ? reassignList(view.destinations) : null,
+    h('div', { class: 'actions' }, summary.buttons.map((entry, index) => h('button', { type: 'button', class: buttonClass(entry, index), onClick: () => onAction(entry.action, view) }, [entry.label]))),
+    confirmingDisconnect ? disconnectConfirmation(view) : null,
+    view.connection.status === 'revocation-pending' ? accountAccessLink(view.accountAccessUrl) : null,
+  ]);
+}
+
+function productsCard(view) {
+  const rows = productRows({ products: view.products, connection: view.connection });
+  return h('section', { class: 'card', 'aria-labelledby': 'products-heading' }, [
+    h('div', { class: 'head' }, [
+      h('h2', { id: 'products-heading' }, ['Products']),
+      tip('About products', 'Turning a product on or off changes only what this site does; it never changes what Google granted.'),
+    ]),
+    h('ul', { class: 'rows' }, rows.map((row) => h('li', { class: 'product' }, [
+      h('div', { class: 'product-name' }, [
+        h('span', { class: 'name-line' }, [h('strong', {}, [row.label]), tip(`About ${row.label}`, row.note)]),
+        h('span', { class: row.grant ? 'state warn' : 'state' }, [row.state]),
+      ]),
+      row.grant ? h('button', { type: 'button', class: 'primary small', onClick: () => onAction('grant', view) }, ['Grant permission']) : null,
+      // A switch drawn from the toggle button: the visible track is decoration; its text is the action.
+      h('button', { type: 'button', class: 'switch', 'aria-pressed': String(row.enabled), onClick: () => run(async () => { notice = null; render(await call('set-product', { productId: row.id, enabled: !row.enabled })); }) }, [
+        h('span', { class: 'sr-only' }, [row.toggleLabel]),
+      ]),
+    ]))),
+  ]);
+}
+
+let lastView = null;
+
+function render(view) {
+  lastView = view;
+  // A null view only comes from a failed first `status`, which always sets the notice first (and
+  // with no view there are no buttons, so no later action can render null again).
+  if (view === null) return show(app, noticeLine(notice));
+  return show(app,
+    notice ? noticeLine(notice) : null,
+    connectionCard(view),
+    productsCard(view));
+}
+
+/**
+ * Starts the panel in a frame: connects to the host and renders the status once the host's init
+ * arrives. Exported so a test can start a fresh panel (fresh state) in its own jsdom window; the
+ * last line starts the real one.
+ * @param {{ window: Window, document: Document }} required
+ */
+export function initConnectionPanel(required) {
+  client = connectToHost({ window: required.window });
+  app = required.document.getElementById('app');
+  notice = null;
+  confirmingDisconnect = false;
+  lastView = null;
+  client.ready.then(load);
+}
+
+/** The first `status`; a failure the host calls retryable offers "Try again" (another `status`). */
+function load() {
+  return call('status').then(render, (error) => { notice = { text: failureText(error), retry: error?.retryable === true ? load : undefined }; render(null); });
+}
+
+initConnectionPanel({ window, document });

package/google-workspace/ui/connection-view.mjs

@@ -0,0 +1,120 @@
+/**
+ * @file What the connection panel says and offers for each connection state: pure functions from
+ * the handler's panel view to text and buttons, with no DOM, so the honesty rules are testable.
+ *
+ * Exists because the wording IS the security property here: a revocation Google has not confirmed
+ * must read "Disconnected locally; Google revocation pending" (never "revoked"), turning a product
+ * off must not read like removing Google's permission, and a staged account switch must name the
+ * new account before anything changes.
+ */
+
+export const REVOCATION_PENDING_TEXT = 'Disconnected locally; Google revocation pending';
+
+const REVOCATION_TEXT = Object.freeze({
+  confirmed: 'Disconnected. Google confirmed that this site\'s access to the account was removed.',
+  pending: `${REVOCATION_PENDING_TEXT}. This site no longer uses this sign-in, but Google has not confirmed removing its access. Retry below, or remove this site's access yourself on your Google Account page.`,
+  'not-needed': 'Disconnected. There was no Google access left to remove.',
+});
+
+/**
+ * Shown while a switch is staged. The panel lists this plugin's form destinations (its delivery
+ * bindings), and each stays with the account its spreadsheet was chosen with unless the person ticks it.
+ */
+export const SWITCH_NOTE = 'After the switch, the Google Workspace tools act as the new account. Form destinations stay with the account their spreadsheet was chosen with: tick the ones below that should deliver as the new account, and this site first checks that the new account can open each spreadsheet. A destination you leave unticked, or that the new account cannot open, keeps the old account: its deliveries fail with "Reconnect required" until you choose its spreadsheet again in Form destinations. Deliveries already queued keep the old account and are not sent again.';
+
+/** What the panel says under the destination checkboxes: nothing is ticked until the person ticks it. */
+export const REASSIGN_HINT = 'Move to the new account (nothing is moved unless you tick it):';
+
+/**
+ * The panel's own second step before a revocation (the sandboxed frame has no `confirm()`): it is
+ * irreversible at Google, so one click must never do it.
+ */
+export const DISCONNECT_CONFIRM_TEXT = 'Disconnect and revoke? This site stops using this Google account at once and asks Google to remove its access. This cannot be undone: using Google Workspace again needs a new sign-in, and form deliveries fail until then.';
+
+const button = (action, label) => ({ action, label });
+
+const STATES = Object.freeze({
+  disconnected: () => ({ heading: 'Not connected', tone: 'neutral', detail: 'Connect a Google account to let this site work with the spreadsheets you choose or create. It asks only for access to files you pick or it creates.', buttons: [button('connect', 'Connect Google account')] }),
+  connected: ({ accountLabel }) => ({ heading: `Connected as ${accountLabel ?? 'a Google account'}`, tone: 'ok', detail: 'Reconnect keeps this account and its settings. Switch account asks you to confirm the new account before anything changes.', buttons: [button('reconnect', 'Reconnect'), button('switch', 'Switch account'), button('disconnect', 'Disconnect and revoke')] }),
+  'reconnect-required': () => ({ heading: 'Reconnect required', tone: 'warn', detail: 'Google no longer accepts the saved sign-in. Form deliveries fail while it is like this and stay listed as failed; they are not sent again after you reconnect. Reconnect the same account so new submissions are delivered.', buttons: [button('reconnect', 'Reconnect'), button('disconnect', 'Disconnect and revoke')] }),
+  'revocation-pending': () => ({ heading: REVOCATION_PENDING_TEXT, tone: 'warn', detail: REVOCATION_TEXT.pending, buttons: [button('retry-revocation', 'Retry Google revocation'), button('connect', 'Connect again')] }),
+});
+
+/**
+ * Heading, status tone (the dot beside the heading), explanation and buttons for the connection; a
+ * staged switch takes precedence.
+ * @param {{ connection: { status: string, accountLabel?: string, pendingSwitchAccountLabel?: string } }} required
+ * @returns {{ heading: string, tone: 'ok' | 'warn' | 'info' | 'neutral', detail: string, buttons: Array<{ action: string, label: string }> }}
+ * @complexity O(1).
+ */
+export function connectionSummary(required, _optional = {}) {
+  const { connection } = required;
+  if (connection.pendingSwitchAccountLabel) {
+    return {
+      heading: `Switch to ${connection.pendingSwitchAccountLabel}?`,
+      tone: 'info',
+      detail: `Signed in now as ${connection.accountLabel ?? 'the current account'}. Nothing changes until you confirm. ${SWITCH_NOTE}`,
+      buttons: [button('confirm-switch', `Use ${connection.pendingSwitchAccountLabel}`), button('cancel-switch', 'Keep the current account')],
+    };
+  }
+  return (STATES[connection.status] ?? STATES.disconnected)(connection);
+}
+
+/**
+ * The sentence after a disconnect, exactly as the host reported the remote outcome.
+ * @param {{ revocation: 'confirmed' | 'pending' | 'not-needed' }} required
+ * @returns {string} An unknown value reads as pending: never claim a revocation nobody confirmed.
+ * @complexity O(1).
+ */
+export function revocationMessage(required, _optional = {}) {
+  return REVOCATION_TEXT[required.revocation] ?? REVOCATION_TEXT.pending;
+}
+
+/**
+ * The sentence after a confirmed switch: which destinations moved, which did not and why (the
+ * plugin's fixed messages only), and that the rest still use the old account.
+ * @param {{ reassignment: { moved: string[], failed: Array<{ formSlug: string, message: string }> }, destinations: Array<{ formSlug: string }> }} required
+ * @returns {string}
+ * @complexity O(d).
+ */
+export function reassignmentMessage(required, _optional = {}) {
+  const { moved, failed } = required.reassignment;
+  const kept = required.destinations.filter((entry) => !moved.includes(entry.formSlug)).map((entry) => entry.formSlug);
+  return [
+    'Switched account.',
+    moved.length > 0 ? `Now delivering as the new account: ${moved.join(', ')}.` : null,
+    ...failed.map((entry) => `Not moved, ${entry.formSlug}: ${entry.message}`),
+    kept.length > 0 ? `Still using the old account (deliveries fail until you choose the spreadsheet again in Form destinations): ${kept.join(', ')}.` : null,
+  ].filter(Boolean).join(' ');
+}
+
+/** A product's state line: on/off is a setting; Google's permission is a separate fact. @complexity O(1). */
+function productNote(product, connected) {
+  // Neutral wording: on a fresh install "off" is the normal starting point, not a failure.
+  if (!product.enabled) return `Not in use. Turn it on to use ${product.label} in assistant tools and form deliveries. Turning it off later keeps the Google sign-in; deliveries already queued retry for about a day.`;
+  if (!connected) return 'On. Connect a Google account to use it.';
+  return product.granted ? 'On. Google has granted the permission it needs.' : 'On, but Google has not granted its permission yet. Grant it to use this product.';
+}
+
+/** The few words under a product's name; the full sentence (`productNote`) is its explanation. @complexity O(1). */
+function productState(product, connected) {
+  if (!product.enabled) return 'Not in use';
+  if (!connected) return 'Needs a Google account';
+  return product.granted ? 'Ready' : 'Needs Google permission';
+}
+
+/**
+ * One row per product: label, short state, note, the on/off toggle and, when on but not granted,
+ * the separate "Grant permission" sign-in.
+ * @param {{ products: Array<{ id: string, label: string, enabled: boolean, granted: boolean }>, connection: { status: string } }} required
+ * @returns {Array<{ id: string, label: string, state: string, note: string, enabled: boolean, toggleLabel: string, grant: boolean }>}
+ * @complexity O(p).
+ */
+export function productRows(required, _optional = {}) {
+  const connected = required.connection.status === 'connected';
+  return required.products.map((product) => ({
+    id: product.id, label: product.label, enabled: product.enabled, state: productState(product, connected), note: productNote(product, connected),
+    toggleLabel: product.enabled ? `Turn ${product.label} off` : `Turn ${product.label} on`,
+    grant: connected && product.enabled && !product.granted,
+  }));
+}