aimeat 2.4.0 → 2.6.0

package/dist/src/utils/build-stamp.js

@@ -0,0 +1,142 @@
+/**
+ * @file build-stamp.ts
+ * @description Read the stamp that `pnpm build` writes into dist/, and answer one question: is the
+ *   artifact we are executing older than the source it was built from? The CLI daemon consumers
+ *   spawn (`aimeat connect serve`) runs from dist/, and a stale dist does not fail — it silently
+ *   drops fields that exist in source, which has now cost three debugging rounds.
+ *
+ *   Deliberately NOT modelled on getSoftwareVersion() in version.ts. That resolver climbs OUT of
+ *   dist/ to read the live package.json, which is right for advertising a version and precisely
+ *   why it can never detect staleness: it always reports the source. This one resolves a single
+ *   path inside dist/ and nowhere else, so "no stamp" unambiguously means "not running from dist".
+ * @structure readBuildStamp(): BuildStamp | null; checkBuildFreshness(): BuildFreshness
+ * @usage import { checkBuildFreshness } from '../utils/build-stamp.js';
+ * @version-history
+ *   v1.0.0 — 2026-08-02 — Initial stale-dist detection for the serve daemon.
+ */
+import { readFileSync, readdirSync, statSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+/** dist/src/utils/build-stamp.js → dist/. In dev (src/utils) this points at a path that does not exist. */
+function stampPath() {
+    const here = dirname(fileURLToPath(import.meta.url));
+    return join(here, '..', '..', 'build-stamp.json');
+}
+let cached;
+/** The stamp written into dist/ at build time, or null when not running from a stamped dist. */
+export function readBuildStamp() {
+    if (cached !== undefined)
+        return cached;
+    try {
+        cached = JSON.parse(readFileSync(stampPath(), 'utf-8'));
+        // eslint-disable-next-line aimeat/no-silent-catch -- absent stamp is the normal dev (tsx) case
+    }
+    catch {
+        cached = null;
+    }
+    return cached;
+}
+/** Newest mtime (epoch ms) in a tree, or 0 when absent. Mirrors scripts/write-build-stamp.mjs. */
+function newestMtime(dir) {
+    let newest = 0;
+    let entries;
+    try {
+        entries = readdirSync(dir, { withFileTypes: true });
+    }
+    // eslint-disable-next-line aimeat/no-silent-catch -- unreadable dir contributes nothing
+    catch {
+        return 0;
+    }
+    for (const entry of entries) {
+        if (entry.isSymbolicLink())
+            continue;
+        const full = join(dir, entry.name);
+        if (entry.isDirectory()) {
+            newest = Math.max(newest, newestMtime(full));
+        }
+        else if (entry.isFile()) {
+            try {
+                newest = Math.max(newest, statSync(full).mtimeMs);
+            }
+            // eslint-disable-next-line aimeat/no-silent-catch -- vanished mid-walk
+            catch { /* vanished mid-walk */ }
+        }
+    }
+    return newest;
+}
+/**
+ * Slack for mtime comparison, in ms. Some filesystems round mtimes to whole seconds, so a build
+ * that recompiled everything correctly must not report itself stale over sub-second jitter.
+ */
+export const MTIME_SLACK_MS = 1000;
+/**
+ * The freshness decision, with the filesystem already reduced to one number. Pure so the rules —
+ * no stamp means source, no source means unknown, and only a real gap means stale — can be tested
+ * without a fixture tree.
+ *
+ * `newestOnDisk` is the newest source mtime in epoch ms, or 0 when there is no source to compare
+ * (a published tarball ships dist/ only). That case answers `unknown`, not `fresh`: we decline to
+ * claim a freshness we cannot verify.
+ */
+export function compareFreshness(stamp, newestOnDisk) {
+    if (!stamp)
+        return { state: 'source', stamp: null, message: null };
+    if (newestOnDisk === 0)
+        return { state: 'unknown', stamp, message: null };
+    if (newestOnDisk > stamp.newest_source_mtime + MTIME_SLACK_MS) {
+        return {
+            state: 'stale',
+            stamp,
+            message: `built ${stamp.built_at} from source last touched ${new Date(stamp.newest_source_mtime).toISOString()}, `
+                + `but source on disk is newer (${new Date(newestOnDisk).toISOString()}). `
+                + 'This process is running OLD code — run `pnpm build`.',
+        };
+    }
+    return { state: 'fresh', stamp, message: null };
+}
+/**
+ * Announce which artifact is running, and shout when it is behind its source. Lives here rather
+ * than at the call site because describing a build is this module's job, and because every
+ * long-running entry point that runs from dist/ wants the same two lines.
+ *
+ * Warns; never exits. A stale build still serves everything that has not changed, so refusing to
+ * start would turn a missing-field bug into an outage.
+ */
+export function announceBuild(freshness, write) {
+    if (freshness.state === 'stale') {
+        write(`[serve] STALE BUILD — ${freshness.message}`);
+        write('[serve] Fields added to source since that build will be dropped without an error.');
+        return;
+    }
+    if (!freshness.stamp) {
+        write('[serve] build: running from source (tsx) — no dist to be stale');
+        return;
+    }
+    const { version, commit, dirty, built_at: builtAt } = freshness.stamp;
+    const short = commit ? commit.slice(0, 8) + (dirty ? '-dirty' : '') : 'no-git';
+    write(`[serve] build: v${version} ${short} built ${builtAt}${freshness.state === 'fresh' ? ' (fresh)' : ''}`);
+}
+/**
+ * Build identity for a status payload. A client that sees `state === 'stale'` knows a missing field
+ * is the local daemon dropping it, not the node refusing it — the question that has cost three
+ * debugging rounds, each ending at a dist/ older than the merge.
+ */
+export function buildIdentity(freshness) {
+    return {
+        state: freshness.state,
+        version: freshness.stamp?.version ?? null,
+        commit: freshness.stamp?.commit ?? null,
+        dirty: freshness.stamp?.dirty ?? null,
+        built_at: freshness.stamp?.built_at ?? null,
+    };
+}
+/** Compare the stamped source state against what is on disk now. */
+export function checkBuildFreshness() {
+    const stamp = readBuildStamp();
+    if (!stamp)
+        return compareFreshness(null, 0);
+    const pkgRoot = join(dirname(stampPath()), '..');
+    const dirs = stamp.source_dirs ?? ['src', 'bin', 'scripts'];
+    return compareFreshness(stamp, Math.max(0, ...dirs.map((d) => newestMtime(join(pkgRoot, d)))));
+}
+//# sourceMappingURL=build-stamp.js.map

package/dist/src/utils/build-stamp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-stamp.js","sourceRoot":"","sources":["../../../src/utils/build-stamp.ts"],"names":[],"mappings":"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"}

package/dist/src/utils/messaging.d.ts

@@ -21,4 +21,18 @@ export declare function deliveryTargetFor(recipientGhii: string): string;
 export declare function conversationIdFor(a: string, b: string): string;
 /** Short single-line preview of a (markdown) message body for notifications + thread lists. */
 export declare function messagePreview(body: string, max?: number): string;
+/**
+ * Preview for a message that may have nothing to preview.
+ *
+ * A voice message is attachments and no body, so the plain body preview is an empty string — which
+ * reads on a notification as a message that arrived with nothing in it. Falls back to describing what
+ * was actually sent: a sender-supplied transcript first (it IS what they said), then the attachment.
+ */
+export declare function messagePreviewWithAttachments(body: string, attachments?: Array<{
+    kind?: string;
+    name?: string;
+    transcript?: {
+        text?: string;
+    };
+}>, max?: number): string;
 //# sourceMappingURL=messaging.d.ts.map

package/dist/src/utils/messaging.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"messaging.d.ts","sourceRoot":"","sources":["../../../src/utils/messaging.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAKH;;;kGAGkG;AAClG,wBAAgB,iBAAiB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAI/D;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAG9D;AAED,+FAA+F;AAC/F,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,SAAM,GAAG,MAAM,CAG9D"}
+{"version":3,"file":"messaging.d.ts","sourceRoot":"","sources":["../../../src/utils/messaging.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAKH;;;kGAGkG;AAClG,wBAAgB,iBAAiB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAI/D;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAG9D;AAED,+FAA+F;AAC/F,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,SAAM,GAAG,MAAM,CAG9D;AAED;;;;;;GAMG;AACH,wBAAgB,6BAA6B,CAC3C,IAAI,EAAE,MAAM,EACZ,WAAW,CAAC,EAAE,KAAK,CAAC;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,CAAC,EACrF,GAAG,SAAM,GACR,MAAM,CAUR"}

package/dist/src/utils/messaging.js.map

@@ -1 +1 @@
-{"version":3,"file":"messaging.js","sourceRoot":"","sources":["../../../src/utils/messaging.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAE3C;;;kGAGkG;AAClG,MAAM,UAAU,iBAAiB,CAAC,aAAqB;IACrD,MAAM,CAAC,GAAG,cAAc,CAAC,aAAa,CAAC,CAAC;IACxC,IAAI,CAAC,CAAC,CAAC,KAAK,IAAI,aAAa,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,IAAI;QAAE,OAAO,GAAG,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC;IACtG,OAAO,aAAa,CAAC;AACvB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAAC,CAAS,EAAE,CAAS;IACpD,MAAM,CAAC,EAAE,EAAE,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IAC1C,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,GAAG,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;AAC/E,CAAC;AAED,+FAA+F;AAC/F,MAAM,UAAU,cAAc,CAAC,IAAY,EAAE,GAAG,GAAG,GAAG;IACpD,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;IAC9C,OAAO,IAAI,CAAC,MAAM,GAAG,GAAG,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC;AACjE,CAAC"}
+{"version":3,"file":"messaging.js","sourceRoot":"","sources":["../../../src/utils/messaging.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAE3C;;;kGAGkG;AAClG,MAAM,UAAU,iBAAiB,CAAC,aAAqB;IACrD,MAAM,CAAC,GAAG,cAAc,CAAC,aAAa,CAAC,CAAC;IACxC,IAAI,CAAC,CAAC,CAAC,KAAK,IAAI,aAAa,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,IAAI;QAAE,OAAO,GAAG,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC;IACtG,OAAO,aAAa,CAAC;AACvB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAAC,CAAS,EAAE,CAAS;IACpD,MAAM,CAAC,EAAE,EAAE,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IAC1C,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,GAAG,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;AAC/E,CAAC;AAED,+FAA+F;AAC/F,MAAM,UAAU,cAAc,CAAC,IAAY,EAAE,GAAG,GAAG,GAAG;IACpD,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;IAC9C,OAAO,IAAI,CAAC,MAAM,GAAG,GAAG,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC;AACjE,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,6BAA6B,CAC3C,IAAY,EACZ,WAAqF,EACrF,GAAG,GAAG,GAAG;IAET,MAAM,IAAI,GAAG,cAAc,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IACvC,IAAI,IAAI;QAAE,OAAO,IAAI,CAAC;IACtB,MAAM,KAAK,GAAG,WAAW,EAAE,CAAC,CAAC,CAAC,CAAC;IAC/B,IAAI,CAAC,KAAK;QAAE,OAAO,EAAE,CAAC;IACtB,IAAI,KAAK,CAAC,UAAU,EAAE,IAAI;QAAE,OAAO,cAAc,CAAC,KAAK,CAAC,UAAU,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IAC9E,IAAI,KAAK,CAAC,IAAI,KAAK,OAAO;QAAE,OAAO,kBAAkB,CAAC;IACtD,IAAI,KAAK,CAAC,IAAI,KAAK,OAAO;QAAE,OAAO,UAAU,CAAC;IAC9C,IAAI,KAAK,CAAC,IAAI,KAAK,OAAO;QAAE,OAAO,UAAU,CAAC;IAC9C,OAAO,MAAM,KAAK,CAAC,IAAI,IAAI,YAAY,EAAE,CAAC;AAC5C,CAAC"}

package/dist/static/sdk-libs/connect/index.js

@@ -0,0 +1,199 @@
+/**
+ * @file connect/index.js
+ * @description The aimeat-connect client library. Exposes `AIMEAT.connect` — the browser side of a
+ *   principal's own accounts at external services (TARGET-057).
+ *
+ *   WHAT THIS LIBRARY NEVER HAS. A token. Not the access token, not the refresh token, not the
+ *   ciphertext. The node holds the credential and an app receives provider, label and status; when
+ *   an app needs to know whether an account can do something, it ASKS, because it cannot know what
+ *   a provider's own scope names mean. That is not a limitation of this library, it is the point of
+ *   it, and it is the whole difference from pasting a bearer key into a config file.
+ *
+ *   WHAT IT OWNS instead is the set of things every app would otherwise get wrong: opening the
+ *   provider window and noticing when it closes, showing `needs_reauth` as something a person can
+ *   act on rather than a red error, telling a Bluesky user where an app password comes from BEFORE
+ *   they go looking, and warning an Instagram user about the Business-account requirement BEFORE
+ *   the attempt rather than after it fails for a reason nobody can read.
+ * @structure list() · providers() · start() · attach() · revoke() · on()/off() · panel()
+ * @usage <script src="/v1/libs/aimeat-auth.js"></script><script src="/v1/libs/aimeat-connect.js"></script>
+ *   const accounts = await AIMEAT.connect.list();
+ *   await AIMEAT.connect.start('mastodon', { instance: 'mastodon.social' });
+ * @version-history
+ *   v1.0.0 — 2026-08-02 — Initial (TARGET-057 phase 3).
+ */
+import { makeSession } from '../_core/session.js';
+import { attach } from '../_core/namespace.js';
+import { mountConnectPanel } from './panel.js';
+import { PROVIDER_NOTES } from './notes.js';
+
+const { authFetch } = makeSession('aimeat-connect.js');
+
+/**
+ * @typedef {Object} Connection
+ * @property {string} id
+ * @property {string} provider
+ * @property {'personal'|'shared'} mode
+ * @property {string} accountLabel  What the provider calls this account. Never app-supplied.
+ * @property {'active'|'needs_reauth'|'revoked'} status
+ */
+
+/** Listeners for "the set of connections changed". */
+const listeners = new Set();
+
+function announce() {
+  for (const fn of listeners) {
+    try { fn(); } catch (err) {
+      // One bad listener must not stop the others, but a swallowed handler error is how a panel
+      // silently stops updating, so it is reported.
+      console.warn('[aimeat-connect] a change listener threw', err);
+    }
+  }
+}
+
+/** The caller's own connections. Never anyone else's — the node scopes this, not the caller. */
+async function list() {
+  const res = await authFetch('/v1/connections');
+  return (res?.data?.connections ?? []);
+}
+
+/** Providers this node can connect to. An unconfigured one is simply absent. */
+async function providers() {
+  const res = await authFetch('/v1/connections/providers');
+  return (res?.data?.providers ?? []);
+}
+
+/**
+ * Begin connecting an account, and resolve when the round has finished.
+ *
+ * The consent happens at the PROVIDER in a window this opens; nothing about the user's credentials
+ * passes through the page. Resolution is detected by the window closing plus a re-read of the list,
+ * because a cross-origin child window cannot be asked what happened to it — and a promise that
+ * resolved on the window opening would report success for a cancelled connection.
+ *
+ * @param {string} provider
+ * @param {{instance?: string, mode?: 'personal'|'shared', signal?: AbortSignal}} [opts]
+ * @returns {Promise<{connected: boolean, connection?: Connection}>}
+ */
+async function start(provider, opts = {}) {
+  const before = await list();
+  const res = await authFetch('/v1/connections/start', {
+    method: 'POST',
+    body: JSON.stringify({
+      provider,
+      instance: opts.instance,
+      mode: opts.mode ?? 'personal',
+      // The callback returns the browser here; a same-origin path only, which the node enforces.
+      // A static page whose only job is to close the pop-up, because the backend renders no HTML.
+      return_url: '/connection-done.html',
+    }),
+  });
+  const url = res?.data?.authorize_url;
+  if (!url) throw new Error('the node did not return an authorization URL');
+
+  const win = window.open(url, 'aimeat-connect', 'width=620,height=760,noopener=no');
+  if (!win) throw new Error('the connect window was blocked; allow pop-ups for this site');
+
+  await waitForRound(before.length, opts.signal);
+
+  const after = await list();
+  const known = new Set(before.map((c) => c.id));
+  const added = after.find((c) => !known.has(c.id));
+  // A re-authorisation repairs an existing row rather than adding one, so "nothing new appeared"
+  // is not the same as "nothing happened" — a status that moved off needs_reauth counts too.
+  const repaired = after.find((c) => {
+    const prev = before.find((p) => p.id === c.id);
+    return prev && prev.status !== 'active' && c.status === 'active';
+  });
+  announce();
+  const connection = added ?? repaired;
+  return { connected: Boolean(connection), connection };
+}
+
+/**
+ * Wait for the round to finish, WITHOUT touching the pop-up window.
+ *
+ * This node sets a Cross-Origin-Opener-Policy, which severs the opener relationship as soon as the
+ * pop-up navigates to the provider. `win.closed` is then unreadable — the first version of this
+ * polled it and logged ten "COOP would block the window.closed call" errors per connection while
+ * appearing to work, because the flow completed for other reasons.
+ *
+ * Two signals instead, and neither goes near the window:
+ *   - the done page announces on a same-origin BroadcastChannel, which COOP does not affect
+ *   - the connection list is polled, which is what ACTUALLY decides success and also covers the
+ *     user who closes the pop-up before it ever reaches the done page
+ *
+ * Resolves either way; gives up after the timeout rather than waiting forever on a cancelled round.
+ */
+async function waitForRound(countBefore, signal) {
+  const DEADLINE = Date.now() + 180_000;
+  let channel = null;
+  let announced = false;
+  let aborted = false;
+  try {
+    channel = new BroadcastChannel('aimeat-connect');
+    channel.onmessage = () => { announced = true; };
+  } catch (err) {
+    console.warn('[aimeat-connect] BroadcastChannel unavailable; falling back to polling', err);
+  }
+  if (signal) signal.addEventListener('abort', () => { aborted = true; }, { once: true });
+  try {
+    while (Date.now() < DEADLINE && !aborted) {
+      await new Promise((r) => setTimeout(r, 1200));
+      if (announced) return true;
+      const now = await list();
+      if (now.length > countBefore) return true;
+    }
+    return false;
+  } finally {
+    if (channel) channel.close();
+  }
+}
+
+/**
+ * Connect an account by SUPPLYING a credential, for a provider with no authorization round.
+ *
+ * Separate from start() because the two must never overlap: attaching a provider that HAS a consent
+ * screen would be a way to skip it, and the node refuses that in both directions. A provider's
+ * `attachFields` (from providers()) is what tells them apart.
+ *
+ * @param {string} provider
+ * @param {Record<string,string>} fields
+ */
+async function attachAccount(provider, fields) {
+  const res = await authFetch('/v1/connections/attach', {
+    method: 'POST',
+    body: JSON.stringify({ provider, mode: 'personal', fields }),
+  });
+  announce();
+  return { connected: true, connection: res?.data?.connection };
+}
+
+/**
+ * Disconnect an account. The node tells the provider first where it can, and removes the credential
+ * either way — so this always ends with the account disconnected here.
+ */
+async function revoke(connectionId) {
+  const res = await authFetch(`/v1/connections/${encodeURIComponent(connectionId)}`, { method: 'DELETE' });
+  announce();
+  return { revoked: true, toldProvider: Boolean(res?.data?.told_provider) };
+}
+
+/** Subscribe to "the set of connections changed". Returns an unsubscribe function. */
+function on(fn) {
+  listeners.add(fn);
+  return () => listeners.delete(fn);
+}
+
+function off(fn) { listeners.delete(fn); }
+
+const connect = {
+  list, providers, start, attach: attachAccount, revoke, on, off,
+  /** Per-provider things a user must be told BEFORE they try. See notes.js. */
+  notes: PROVIDER_NOTES,
+  /** Mount the ready-made panel. See panel.js. */
+  panel: (opts) => mountConnectPanel(connect, opts),
+};
+
+attach('connect', connect);
+
+export default connect;

package/dist/static/sdk-libs/connect/notes.js

@@ -0,0 +1,47 @@
+/**
+ * @file connect/notes.js
+ * @description What a user has to be told BEFORE they try to connect a provider (TARGET-057).
+ *
+ *   Every note here exists because the failure it prevents is unreadable when it happens. An
+ *   Instagram personal account authorises perfectly and then cannot publish, with an error that
+ *   names neither the account type nor the fix. A Bluesky user hunting for a password that is not
+ *   their password finds their password. A Telegram bot that was never added to the channel fails
+ *   at the last step of the flow rather than the first.
+ *
+ *   These are strings and not logic on purpose: they are the copy the panel shows, and an app that
+ *   builds its own surface should be able to show the same words rather than invent worse ones.
+ * @structure PROVIDER_NOTES — keyed by provider id
+ * @usage import { PROVIDER_NOTES } from './notes.js';  PROVIDER_NOTES.bluesky.before
+ * @version-history
+ *   v1.0.0 — 2026-08-02 — Initial (TARGET-057 phase 3).
+ */
+
+/**
+ * @typedef {Object} ProviderNote
+ * @property {string} [needs]   What the user must supply, if anything beyond pressing the button.
+ * @property {string} [before]  Shown BEFORE the attempt. The failure it prevents is unreadable.
+ * @property {string} [where]   Where in the provider's own UI to find what they need.
+ */
+
+/** @type {Record<string, ProviderNote>} */
+export const PROVIDER_NOTES = {
+  mastodon: {
+    needs: 'The address of your instance, for example mastodon.social.',
+    before: 'Your account lives at one instance, and the same name at another instance is a different account.',
+  },
+  youtube: {
+    before: 'Sign in with the Google account that owns the channel. A Google account with no YouTube channel will connect and then have nowhere to publish.',
+  },
+  bluesky: {
+    needs: 'An app password. This is NOT your Bluesky password.',
+    where: 'Bluesky → Settings → Privacy and security → App passwords.',
+    before: 'This is the one provider that asks you to copy a secret to us instead of approving on their site. You can revoke it from Bluesky at any time, and it cannot be used to sign in as you.',
+  },
+  instagram: {
+    before: 'Instagram publishing needs a Business or Creator account linked to a Facebook Page. A personal account will connect and then refuse to publish, with an error that does not say why.',
+  },
+  telegram: {
+    needs: 'A bot token from @BotFather, and the bot added to your channel with permission to post.',
+    before: 'Adding the bot to the channel is a step only you can do; without it the connection works and publishing does not.',
+  },
+};

package/dist/static/sdk-libs/connect/panel.js

@@ -0,0 +1,238 @@
+/**
+ * @file connect/panel.js
+ * @description The ready-made connected-accounts panel (TARGET-057). Mounted by the profile's
+ *   Access tab and available to any app that wants the same surface.
+ *
+ *   THE STATUS ROW IS THE POINT. A connection that needs re-authorising is not an error and must not
+ *   look like one: it is a thing the owner can fix in two clicks, and it is shown as a button that
+ *   fixes it. Rendering it as red text is how a working feature becomes a support question.
+ *
+ *   Like the IAM panel, this emits neutral `aim-*` hooks and a stylesheet built on `currentColor`
+ *   and inherited font, so it takes the host page's design instead of imposing one. Nothing here
+ *   hardcodes a brand colour.
+ * @structure mountConnectPanel(connect, opts)
+ * @usage AIMEAT.connect.panel({ target: '#accounts' })
+ * @version-history
+ *   v1.0.0 — 2026-08-02 — Initial (TARGET-057 phase 3).
+ */
+
+const STYLE_ID = 'aimeat-connect-style';
+
+function el(tag, opts, children) {
+  const node = document.createElement(tag);
+  const o = opts || {};
+  if (o.cls) node.className = o.cls;
+  if (o.text != null) node.textContent = o.text;
+  if (o.attrs) for (const k of Object.keys(o.attrs)) node.setAttribute(k, o.attrs[k]);
+  if (o.on) for (const k of Object.keys(o.on)) node.addEventListener(k, o.on[k]);
+  for (const c of children || []) if (c) node.appendChild(c);
+  return node;
+}
+
+/**
+ * Plain, inherited, and scrollable in its own right. The horizontal scroll lives on the list rather
+ * than the page: a long account label must not make the whole profile scroll sideways.
+ */
+function injectStyle() {
+  if (document.getElementById(STYLE_ID)) return;
+  const css = `
+.aim-conn { font: inherit; color: inherit; }
+.aim-conn-list { display: flex; flex-direction: column; gap: .5rem; margin: .75rem 0; }
+.aim-conn-row { display: flex; flex-wrap: wrap; align-items: center; gap: .5rem .75rem;
+  padding: .6rem .75rem; border: 1px solid currentColor; border-radius: .5rem; opacity: .95; }
+.aim-conn-main { display: flex; flex-direction: column; min-width: 0; flex: 1 1 12rem; }
+.aim-conn-label { font-weight: 600; overflow-wrap: anywhere; }
+.aim-conn-meta { font-size: .85em; opacity: .7; }
+.aim-conn-actions { display: flex; gap: .5rem; flex-wrap: wrap; }
+.aim-conn-btn { font: inherit; color: inherit; background: transparent; cursor: pointer;
+  border: 1px solid currentColor; border-radius: .4rem; padding: .35rem .7rem; }
+.aim-conn-btn[disabled] { opacity: .5; cursor: default; }
+.aim-conn-note { font-size: .85em; opacity: .75; margin: .35rem 0 0; }
+.aim-conn-empty { opacity: .7; margin: .75rem 0; }
+.aim-conn-add { display: flex; flex-wrap: wrap; gap: .5rem; align-items: center; margin-top: .75rem; }
+.aim-conn-input { font: inherit; color: inherit; background: transparent; padding: .35rem .5rem;
+  border: 1px solid currentColor; border-radius: .4rem; min-width: 0; flex: 1 1 12rem; }
+.aim-conn-err { font-size: .9em; margin: .5rem 0 0; }
+`;
+  const style = document.createElement('style');
+  style.id = STYLE_ID;
+  style.textContent = css;
+  document.head.appendChild(style);
+}
+
+const DEFAULT_STRINGS = {
+  title: 'Connected accounts',
+  intro: 'Accounts you have connected so apps can act at those services on your behalf. The account credential stays on this node; an app is only ever told which account it may use.',
+  empty: 'You have not connected any accounts yet.',
+  add: 'Connect',
+  connecting: 'Connecting…',
+  disconnect: 'Disconnect',
+  reconnect: 'Reconnect',
+  needsReauth: 'needs reconnecting',
+  instancePlaceholder: 'instance address, e.g. mastodon.social',
+  confirm: 'Disconnect this account? Apps that publish to it will stop being able to.',
+  toldProvider: 'Disconnected, and the service was told.',
+  notToldProvider: 'Disconnected here. The service could not be reached to be told, so check it there too.',
+  unavailable: 'Connecting accounts is not enabled on this node.',
+};
+
+/**
+ * Mount the panel.
+ *
+ * @param {any} connect  The AIMEAT.connect surface.
+ * @param {{target?: string|Element, strings?: Record<string,string>, styles?: boolean}} [opts]
+ */
+export async function mountConnectPanel(connect, opts = {}) {
+  const host = typeof opts.target === 'string' ? document.querySelector(opts.target) : opts.target;
+  // Named rather than a bare null-deref: "target not found" is the only thing that goes wrong here
+  // and the selector is usually a typo.
+  if (!host) throw new Error('aimeat-connect: panel target not found');
+  if (opts.styles !== false) injectStyle();
+  const s = { ...DEFAULT_STRINGS, ...(opts.strings || {}) };
+
+  const root = el('div', { cls: 'aim-conn' });
+  host.replaceChildren(root);
+
+  let providers = [];
+  let busy = false;
+
+  async function render() {
+    let accounts;
+    try {
+      [accounts, providers] = await Promise.all([connect.list(), connect.providers()]);
+    } catch (err) {
+      // A capability that is switched off answers 503; saying so beats an empty panel that looks
+      // like "you have no accounts".
+      root.replaceChildren(el('p', { cls: 'aim-conn-err', text: `${s.unavailable} (${(err && err.message) || err})` }));
+      return;
+    }
+
+    const rows = accounts.map((c) => {
+      const needsReauth = c.status === 'needs_reauth';
+      return el('div', { cls: 'aim-conn-row' }, [
+        el('div', { cls: 'aim-conn-main' }, [
+          el('span', { cls: 'aim-conn-label', text: c.accountLabel }),
+          el('span', {
+            cls: 'aim-conn-meta',
+            text: needsReauth ? `${c.provider} · ${s.needsReauth}` : c.provider,
+          }),
+        ]),
+        el('div', { cls: 'aim-conn-actions' }, [
+          // Shown as a FIX, not as an error. Two clicks and it works again.
+          needsReauth
+            ? el('button', {
+              cls: 'aim-conn-btn', text: s.reconnect, attrs: { type: 'button' },
+              on: { click: () => void beginConnect(c.provider, null) },
+            })
+            : null,
+          el('button', {
+            cls: 'aim-conn-btn', text: s.disconnect, attrs: { type: 'button' },
+            on: {
+              click: () => {
+                if (!window.confirm(s.confirm)) return;
+                void (async () => {
+                  const r = await connect.revoke(c.id);
+                  await render();
+                  // Honest about which half happened: a token still live at the provider is
+                  // something the owner may want to go and remove there.
+                  window.alert(r.toldProvider ? s.toldProvider : s.notToldProvider);
+                })();
+              },
+            },
+          }),
+        ]),
+      ]);
+    });
+
+    const list = rows.length
+      ? el('div', { cls: 'aim-conn-list' }, rows)
+      : el('p', { cls: 'aim-conn-empty', text: s.empty });
+
+    root.replaceChildren(
+      el('p', { cls: 'aim-conn-note', text: s.intro }),
+      list,
+      ...providers.map(renderAdd),
+    );
+  }
+
+  function renderAdd(p) {
+    const note = (connect.notes && connect.notes[p.id]) || {};
+    let instanceInput = null;
+    if (p.instanceScoped) {
+      instanceInput = el('input', {
+        cls: 'aim-conn-input',
+        attrs: { type: 'text', placeholder: s.instancePlaceholder, 'aria-label': s.instancePlaceholder },
+      });
+    }
+    // A provider with attachFields is connected by supplying a credential; one without has a
+    // consent screen. Rendering from the declaration means the panel needs to know nothing about
+    // any particular provider, and a provider with NEITHER cannot get a button at all.
+    const attachInputs = (p.attachFields || []).map((f) => el('input', {
+      cls: 'aim-conn-input',
+      attrs: {
+        type: f.secret ? 'password' : 'text',
+        autocomplete: f.secret ? 'new-password' : 'off',
+        placeholder: f.placeholder || f.label,
+        'aria-label': f.label,
+        'data-field': f.name,
+      },
+    }));
+    const btn = el('button', {
+      cls: 'aim-conn-btn',
+      text: `${s.add} ${p.label}`,
+      attrs: { type: 'button' },
+      on: {
+        click: () => {
+          if (!p.attachFields) return void beginConnect(p.id, instanceInput);
+          const fields = {};
+          for (const input of attachInputs) fields[input.getAttribute('data-field')] = input.value;
+          void beginAttach(p.id, fields, attachInputs);
+        },
+      },
+    });
+    return el('div', {}, [
+      el('div', { cls: 'aim-conn-add' }, [instanceInput, ...attachInputs, btn]),
+      // Before the attempt, always. Each of these prevents a failure whose message does not
+      // explain itself.
+      note.needs ? el('p', { cls: 'aim-conn-note', text: note.needs }) : null,
+      note.where ? el('p', { cls: 'aim-conn-note', text: note.where }) : null,
+      note.before ? el('p', { cls: 'aim-conn-note', text: note.before }) : null,
+    ]);
+  }
+
+  async function beginConnect(providerId, instanceInput) {
+    if (busy) return;
+    busy = true;
+    const instance = instanceInput ? instanceInput.value.trim() : undefined;
+    try {
+      await connect.start(providerId, { instance });
+    } catch (err) {
+      const msg = (err && err.message) || String(err);
+      root.appendChild(el('p', { cls: 'aim-conn-err', text: msg }));
+    } finally {
+      busy = false;
+      await render();
+    }
+  }
+
+  async function beginAttach(providerId, fields, inputs) {
+    if (busy) return;
+    busy = true;
+    try {
+      await connect.attach(providerId, fields);
+      // Cleared on success, so a secret does not sit in a form field after it has been stored.
+      for (const i of inputs) i.value = '';
+    } catch (err) {
+      // The node's reason is the useful half: "that is your account password, not an app password"
+      // is actionable in a way that a generic failure is not.
+      root.appendChild(el('p', { cls: 'aim-conn-err', text: (err && err.message) || String(err) }));
+    } finally {
+      busy = false;
+      await render();
+    }
+  }
+
+  connect.on(() => void render());
+  await render();
+  return { refresh: render };
+}