@abraca/nuxt 1.8.2 → 2.0.0

package/dist/runtime/plugin-abracadabra.client.js

@@ -136,16 +136,26 @@ async function fetchServerInfo(baseUrl) {
   }
   return {};
 }
-async function fetchSpacesInfo(baseUrl) {
+function spaceMetaFromDoc(doc) {
+  return {
+    id: doc.id,
+    name: doc.label ?? "",
+    description: doc.description ?? null,
+    visibility: doc.public_access === "observer" ? "public" : "private",
+    owner_id: doc.owner_id ?? null,
+    public_access: doc.public_access ?? null
+  };
+}
+async function fetchSpacesInfo(baseUrl, token) {
   try {
-    const [spacesRes, hubRes] = await Promise.all([
-      fetch(`${baseUrl}/spaces`),
-      fetch(`${baseUrl}/spaces/hub`)
-    ]);
-    if (!spacesRes.ok) return null;
-    const spacesData = await spacesRes.json();
-    const hubDocId = hubRes.ok ? (await hubRes.json()).doc_id : void 0;
-    return { spaces: spacesData.spaces, hubDocId };
+    const headers = {};
+    if (token) headers.Authorization = `Bearer ${token}`;
+    const res = await fetch(`${baseUrl}/docs?root=true`, { headers });
+    if (!res.ok) return null;
+    const data = await res.json();
+    const docs = Array.isArray(data) ? data : data.documents ?? [];
+    const spaces = docs.filter((d) => d.kind === "space").map(spaceMetaFromDoc);
+    return { spaces };
   } catch {
     return null;
   }
@@ -228,6 +238,23 @@ export default defineNuxtPlugin({
     const userColor = ref("hsl(217, 70%, 75%)");
     const userColorName = ref("blue");
     const userNeutralColorName = ref("zinc");
+    const userStatusIcon = ref(localStorage.getItem("abracadabra_status_icon") ?? "");
+    const userStatusText = ref(localStorage.getItem("abracadabra_status_text") ?? "");
+    const userStatusAsAvatar = ref(localStorage.getItem("abracadabra_status_as_avatar") === "1");
+    watch([status, synced], ([s, sy]) => {
+      try {
+        const ready = s === "connected" && sy;
+        window.__abracaReady = ready ? Date.now() : false;
+      } catch {
+      }
+    }, { immediate: true });
+    watch(unsyncedChanges, (n) => {
+      try {
+        ;
+        window.__abracaUnsynced = n;
+      } catch {
+      }
+    }, { immediate: true });
     const currentServerUrl = ref(defaultUrl);
     const savedServers = ref([]);
     let _serversLoaded = false;
@@ -275,12 +302,10 @@ export default defineNuxtPlugin({
       }
       const entry = { url, label };
       const [info, spacesInfo] = await Promise.all([fetchServerInfo(url), fetchSpacesInfo(url)]);
-      if (info.index_doc_id) entry.entryDocId = info.index_doc_id;
+      if (info.root_doc_id) entry.entryDocId = info.root_doc_id;
       if (info.name) entry.label = info.name;
       if (spacesInfo) {
-        entry.spacesEnabled = true;
         entry.cachedSpaces = spacesInfo.spaces;
-        if (spacesInfo.hubDocId) entry.hubDocId = spacesInfo.hubDocId;
       }
       savedServers.value = [...savedServers.value, entry];
       persistServers();
@@ -293,42 +318,59 @@ export default defineNuxtPlugin({
     const currentServerSpaces = computed(
       () => savedServers.value.find((s) => s.url === currentServerUrl.value)?.cachedSpaces ?? []
     );
-    const currentServerSpacesEnabled = computed(
-      () => savedServers.value.find((s) => s.url === currentServerUrl.value)?.spacesEnabled ?? false
-    );
     async function refreshSpaces() {
       const url = currentServerUrl.value;
       if (!url) return;
-      const spacesInfo = await fetchSpacesInfo(url);
+      let spaces = null;
+      if (client.value) {
+        try {
+          const docs = await client.value.listSpaces();
+          spaces = docs.map(spaceMetaFromDoc);
+        } catch (e) {
+          if (import.meta.dev) console.warn("[abracadabra] refreshSpaces: client.listSpaces failed", e);
+        }
+      }
+      if (spaces === null) {
+        const spacesInfo = await fetchSpacesInfo(url);
+        spaces = spacesInfo?.spaces ?? null;
+      }
+      if (spaces === null) return;
       const idx = savedServers.value.findIndex((s) => s.url === url);
       if (idx !== -1) {
-        if (spacesInfo) {
-          savedServers.value[idx] = { ...savedServers.value[idx], spacesEnabled: true, cachedSpaces: spacesInfo.spaces, hubDocId: spacesInfo.hubDocId ?? savedServers.value[idx].hubDocId };
-        }
+        savedServers.value[idx] = { ...savedServers.value[idx], cachedSpaces: spaces };
         persistServers();
       }
     }
     async function createSpace(opts) {
       if (!client.value) throw new Error("Not connected");
-      const result = await client.value.createSpace(opts);
+      const doc2 = await client.value.createSpace(opts);
       await refreshSpaces();
-      return result;
+      return spaceMetaFromDoc(doc2);
     }
     async function updateSpace(id, opts) {
       if (!client.value) throw new Error("Not connected");
-      const result = await client.value.updateSpace(id, opts);
+      await client.value.updateSpace(id, opts);
       await refreshSpaces();
-      return result;
     }
     async function deleteSpace(id) {
       if (!client.value) throw new Error("Not connected");
       await client.value.deleteSpace(id);
       await refreshSpaces();
     }
+    function publishAwarenessUser() {
+      const payload = {
+        name: userName.value,
+        color: userColor.value,
+        publicKey: publicKeyB64.value
+      };
+      if (userStatusIcon.value) payload.statusIcon = userStatusIcon.value;
+      if (userStatusText.value) payload.statusText = userStatusText.value;
+      provider.value?.setAwarenessField("user", payload);
+    }
     function setUserName(name) {
       userName.value = name;
       localStorage.setItem("abracadabra_username", name);
-      provider.value?.setAwarenessField("user", { name, color: userColor.value, publicKey: publicKeyB64.value });
+      publishAwarenessUser();
       client.value?.updateMe({ displayName: name }).catch(() => {
       });
     }
@@ -340,7 +382,7 @@ export default defineNuxtPlugin({
       localStorage.setItem("abracadabra_usercolor", colorName);
       const appConfig = useAppConfig();
       if (appConfig.ui?.colors) appConfig.ui.colors.primary = toNuxtUIPrimary(colorName);
-      provider.value?.setAwarenessField("user", { name: userName.value, color: hsl, publicKey: publicKeyB64.value });
+      publishAwarenessUser();
     }
     function setNeutralColor(colorName) {
       userNeutralColorName.value = colorName;
@@ -348,6 +390,25 @@ export default defineNuxtPlugin({
       const appConfig = useAppConfig();
       if (appConfig.ui?.colors) appConfig.ui.colors.neutral = toNuxtUINeutral(colorName);
     }
+    function setUserStatusIcon(icon) {
+      const normalized = icon.replace(/^i-lucide-/, "");
+      userStatusIcon.value = normalized;
+      if (normalized) localStorage.setItem("abracadabra_status_icon", normalized);
+      else localStorage.removeItem("abracadabra_status_icon");
+      publishAwarenessUser();
+    }
+    function setUserStatusText(text) {
+      const trimmed = (text ?? "").slice(0, 80);
+      userStatusText.value = trimmed;
+      if (trimmed) localStorage.setItem("abracadabra_status_text", trimmed);
+      else localStorage.removeItem("abracadabra_status_text");
+      publishAwarenessUser();
+    }
+    function setUserStatusAsAvatar(enabled) {
+      userStatusAsAvatar.value = enabled;
+      if (enabled) localStorage.setItem("abracadabra_status_as_avatar", "1");
+      else localStorage.removeItem("abracadabra_status_as_avatar");
+    }
     function setRequirePasskey(enabled) {
       requirePasskeyOnLogin.value = enabled;
       localStorage.setItem(REQUIRE_PASSKEY_KEY, enabled ? "1" : "0");
@@ -505,6 +566,67 @@ export default defineNuxtPlugin({
       localStorage.removeItem(PUBKEY_KEY);
       window.location.reload();
     }
+    async function logoutServer() {
+      addLog("Revoking session on server...", "auth");
+      if (client.value) {
+        try {
+          await client.value.logoutServer();
+        } catch (e) {
+          if (import.meta.dev) console.warn("[abracadabra] logoutServer failed", e);
+        }
+      }
+      await logout();
+    }
+    async function logoutAll() {
+      addLog("Revoking all sessions for user...", "auth");
+      if (client.value) {
+        try {
+          await client.value.logoutAll();
+        } catch (e) {
+          if (import.meta.dev) console.warn("[abracadabra] logoutAll failed", e);
+        }
+      }
+      await logout();
+    }
+    async function requestPasswordReset(opts) {
+      if (!client.value) throw new Error("Not connected");
+      await client.value.requestPasswordReset(opts);
+      addLog("Password reset email requested", "auth");
+    }
+    async function loginWithPassword(opts) {
+      if (!client.value) throw new Error("Not connected");
+      await client.value.login(opts);
+      addLog(`Logged in as ${opts.username}`, "auth");
+      if (_wsp) {
+        _wsp.disconnect();
+        setTimeout(() => _wsp?.connect(), 300);
+      }
+    }
+    async function registerWithPassword(opts) {
+      if (!client.value) throw new Error("Not connected");
+      await client.value.register(opts);
+      await client.value.login({ username: opts.username, password: opts.password });
+      addLog(`Registered + logged in as ${opts.username}`, "auth");
+      if (_wsp) {
+        _wsp.disconnect();
+        setTimeout(() => _wsp?.connect(), 300);
+      }
+    }
+    async function confirmPasswordReset(opts) {
+      if (!client.value) throw new Error("Not connected");
+      await client.value.confirmPasswordReset(opts);
+      addLog("Password reset confirmed", "auth");
+    }
+    async function changePassword(opts) {
+      if (!client.value) throw new Error("Not connected");
+      await client.value.changePassword(opts);
+      addLog("Password changed", "auth");
+    }
+    async function setPassword(newPassword) {
+      if (!client.value) throw new Error("Not connected");
+      await client.value.setPassword(newPassword);
+      addLog("Password set", "auth");
+    }
     async function redeemInvite(code) {
       if (!client.value) throw new Error("Not connected");
       await client.value.redeemInvite(code);
@@ -592,7 +714,9 @@ export default defineNuxtPlugin({
         ]);
         setSdkModule(sdkModule);
         const { AbracadabraClient, AbracadabraProvider, AbracadabraWS, CryptoIdentityKeystore } = sdkModule;
-        ed.hashes.sha512 = (m) => sha512(m);
+        const edEtc = ed.etc;
+        edEtc.sha512Sync = (...m) => sha512(edEtc.concatBytes(...m));
+        edEtc.sha512Async = (...m) => Promise.resolve(edEtc.sha512Sync(...m));
         const ks = new CryptoIdentityKeystore();
         keystore.value = ks;
         let privKey = null;
@@ -618,7 +742,7 @@ export default defineNuxtPlugin({
             privKey = fromBase64Url(storedPrivKey);
             addLog("Using guest identity (soft key)", "auth");
           } else {
-            privKey = ed.utils.randomSecretKey();
+            privKey = ed.utils.randomPrivateKey();
             localStorage.setItem("abracadabra_privkey", toBase64Url(privKey));
             addLog("Created new guest identity (soft key)", "auth");
           }
@@ -663,7 +787,28 @@ export default defineNuxtPlugin({
         const _client = new AbracadabraClient({ url: serverUrl, persistAuth, storageKey: authStorageKey });
         client.value = _client;
         addLog(`Server: ${serverUrl}`, "connection");
-        if (_client.isTokenValid() && identityState.value === "claimed") {
+        let useExistingToken = _client.isTokenValid();
+        if (useExistingToken) {
+          try {
+            await _client.getMe();
+          } catch (e) {
+            const status2 = e?.status ?? 0;
+            if (status2 === 401) {
+              const msg = e instanceof Error ? e.message : String(e);
+              addLog(`Persisted JWT no longer valid on ${serverUrl} (${msg.slice(0, 80)}) \u2014 re-registering`, "auth");
+              try {
+                localStorage.removeItem(authStorageKey);
+              } catch {
+              }
+              ;
+              _client.token = null;
+              useExistingToken = false;
+            }
+          }
+        }
+        if (useExistingToken && identityState.value === "claimed") {
+          addLog("Resumed session from persisted token", "auth");
+        } else if (useExistingToken) {
           addLog("Resumed session from persisted token", "auth");
         } else if (identityState.value === "claimed" && !requirePasskeyOnLogin.value) {
           identityState.value = "needsReauth";
@@ -694,18 +839,20 @@ export default defineNuxtPlugin({
         }
         _client.updateMe({ displayName: userName.value }).catch(() => {
         });
-        const [info, spacesInfo] = await Promise.all([
+        const [info, spaceDocs] = await Promise.all([
           fetchServerInfo(serverUrl),
-          fetchSpacesInfo(serverUrl)
+          _client.listSpaces().catch((e) => {
+            if (import.meta.dev) console.warn("[abracadabra] init: client.listSpaces failed", e);
+            return null;
+          })
         ]);
+        const spacesInfo = spaceDocs ? { spaces: spaceDocs.map(spaceMetaFromDoc) } : null;
         const idx = savedServers.value.findIndex((s) => s.url === serverUrl);
         if (idx >= 0) {
           const updates = {};
           if (info.name && info.name !== savedServers.value[idx].label) updates.label = info.name;
           if (spacesInfo) {
-            updates.spacesEnabled = true;
             updates.cachedSpaces = spacesInfo.spaces;
-            if (spacesInfo.hubDocId) updates.hubDocId = spacesInfo.hubDocId;
           }
           if (Object.keys(updates).length) {
             savedServers.value[idx] = { ...savedServers.value[idx], ...updates };
@@ -713,9 +860,9 @@ export default defineNuxtPlugin({
           }
         }
         const server = savedServers.value.find((s) => s.url === serverUrl);
-        const docId = configEntryDocId ?? server?.hubDocId ?? spacesInfo?.hubDocId ?? server?.cachedSpaces?.[0]?.doc_id ?? spacesInfo?.spaces?.[0]?.doc_id ?? server?.entryDocId ?? info.index_doc_id ?? void 0;
+        const docId = configEntryDocId ?? server?.entryDocId ?? server?.cachedSpaces?.[0]?.id ?? spacesInfo?.spaces?.[0]?.id ?? void 0;
         if (!docId) {
-          connectionError.value = "No entry document found. Configure entryDocId or ensure the server has spaces or an index document.";
+          connectionError.value = "No entry document found. Configure entryDocId or ensure the server has spaces.";
           addLog("No entry document \u2014 cannot connect", "system");
           try {
             const imports = await import("#imports");
@@ -872,12 +1019,38 @@ export default defineNuxtPlugin({
             }
           }
         });
-        _provider.setAwarenessField("user", { name: userName.value, color: userColor.value, publicKey: publicKeyB64.value });
+        {
+          const initial = {
+            name: userName.value,
+            color: userColor.value,
+            publicKey: publicKeyB64.value
+          };
+          if (userStatusIcon.value) initial.statusIcon = userStatusIcon.value;
+          if (userStatusText.value) initial.statusText = userStatusText.value;
+          _provider.setAwarenessField("user", initial);
+        }
         _provider.on("unsyncedChanges", ({ number }) => {
           unsyncedChanges.value = number;
         });
         _provider.attach();
         provider.value = _provider;
+        try {
+          const onPointerLeave = (e) => {
+            if (e.relatedTarget !== null) return;
+            try {
+              _provider.awareness?.setLocalStateField("hover", null);
+            } catch {
+            }
+          };
+          document.addEventListener("pointerleave", onPointerLeave);
+          window.addEventListener("beforeunload", () => {
+            try {
+              _provider.awareness?.setLocalState(null);
+            } catch {
+            }
+          });
+        } catch {
+        }
         try {
           const { FileBlobStore } = await import("@abraca/dabra");
           const blobStore = new FileBlobStore(serverUrl, _client);
@@ -895,9 +1068,16 @@ export default defineNuxtPlugin({
           isReady.value = true;
         }, () => null);
         watch(
-          [userName, userColor, publicKeyB64],
+          [userName, userColor, publicKeyB64, userStatusIcon, userStatusText],
           () => {
-            _provider.setAwarenessField("user", { name: userName.value, color: userColor.value, publicKey: publicKeyB64.value });
+            const payload = {
+              name: userName.value,
+              color: userColor.value,
+              publicKey: publicKeyB64.value
+            };
+            if (userStatusIcon.value) payload.statusIcon = userStatusIcon.value;
+            if (userStatusText.value) payload.statusText = userStatusText.value;
+            _provider.setAwarenessField("user", payload);
           },
           { immediate: true }
         );
@@ -922,6 +1102,9 @@ export default defineNuxtPlugin({
       userColorName,
       userNeutralColorName,
       userCount,
+      userStatusIcon,
+      userStatusText,
+      userStatusAsAvatar,
       publicKeyB64,
       connectionError,
       identityState,
@@ -935,7 +1118,6 @@ export default defineNuxtPlugin({
       currentServerUrl,
       savedServers,
       currentServerSpaces,
-      currentServerSpacesEnabled,
       pendingInviteCode,
       registry,
       addLog,
@@ -943,10 +1125,21 @@ export default defineNuxtPlugin({
       setUserColor,
       setNeutralColor,
       setRequirePasskey,
+      setUserStatusIcon,
+      setUserStatusText,
+      setUserStatusAsAvatar,
       claimAccount,
       loginWithHardware,
+      loginWithPassword,
+      registerWithPassword,
       logout,
       reconnect,
+      logoutServer,
+      logoutAll,
+      requestPasswordReset,
+      confirmPasswordReset,
+      changePassword,
+      setPassword,
       addServer,
       removeServer,
       switchServer,
@@ -969,6 +1162,26 @@ export default defineNuxtPlugin({
       watch(abra.status, (s) => console.log("[abracadabra] status \u2192", s));
       watch(abra.synced, (s) => console.log("[abracadabra] synced \u2192", s));
     }
+    function _kickConnection() {
+      if (!_wsp) return;
+      if (identityState.value === "connectionBlocked") {
+        unblockConnection();
+        return;
+      }
+      if (status.value === "disconnected") {
+        authFailureCount = 0;
+        connectionError.value = null;
+        try {
+          _wsp.connect();
+        } catch {
+        }
+      }
+    }
+    window.addEventListener("focus", _kickConnection);
+    window.addEventListener("online", _kickConnection);
+    document.addEventListener("visibilitychange", () => {
+      if (document.visibilityState === "visible") _kickConnection();
+    });
     loadServers();
     const storedServer = localStorage.getItem(CURRENT_SERVER_KEY);
     const initialUrl = storedServer && savedServers.value.some((s) => s.url === storedServer) ? storedServer : currentServerUrl.value || savedServers.value[0]?.url || defaultUrl;

package/dist/runtime/plugin-abracadabra.server.js

@@ -39,7 +39,6 @@ export default defineNuxtPlugin({
       currentServerUrl: ref(""),
       savedServers: ref([]),
       currentServerSpaces: computed(() => []),
-      currentServerSpacesEnabled: computed(() => false),
       // Misc
       pendingInviteCode: ref(null),
       logs: ref([]),

package/dist/runtime/plugins/core.plugin.js

@@ -1,4 +1,22 @@
 import { DOC_TYPES } from "../utils/docTypes.js";
+import { useRuntimeConfig } from "#imports";
+const OPTIONAL_BUILTIN_EXTENSIONS = /* @__PURE__ */ new Set([
+  "divider",
+  "quote",
+  "figure",
+  "embed",
+  "video",
+  "stat",
+  "statGroup",
+  "button",
+  "buttonGroup",
+  "progress",
+  "spoiler",
+  "colorSwatch",
+  "mathBlock",
+  "mathInline",
+  "diff"
+]);
 async function loadClientExtensions() {
   const [
     { default: TaskList },
@@ -35,12 +53,25 @@ async function loadClientExtensions() {
     { FileBlock },
     { MetaField },
     { DocEmbed },
+    { DocLink },
     { DocLinkDrop },
     { MentionDrop },
     { SelectionDrag },
     { Field, FieldGroup },
     { CodePreview },
-    { CodeTree }
+    { CodeTree },
+    { Divider },
+    { Quote },
+    { Figure },
+    { Embed },
+    { Video },
+    { Stat, StatGroup },
+    { Button, ButtonGroup },
+    { Progress },
+    { Spoiler },
+    { ColorSwatch },
+    { MathBlock, MathInline },
+    { Diff }
   ] = await Promise.all([
     import("@tiptap/extension-task-list"),
     import("@tiptap/extension-task-item"),
@@ -76,12 +107,25 @@ async function loadClientExtensions() {
     import("../extensions/file-block.js"),
     import("../extensions/meta-field.js"),
     import("../extensions/doc-embed.js"),
+    import("../extensions/doc-link.js"),
     import("../extensions/doc-link-drop.js"),
     import("../extensions/mention-drop.js"),
     import("../extensions/selection-drag.js"),
     import("../extensions/field.js"),
     import("../extensions/code-preview.js"),
-    import("../extensions/code-tree.js")
+    import("../extensions/code-tree.js"),
+    import("../extensions/divider.js"),
+    import("../extensions/quote.js"),
+    import("../extensions/figure.js"),
+    import("../extensions/embed.js"),
+    import("../extensions/video.js"),
+    import("../extensions/stat.js"),
+    import("../extensions/button.js"),
+    import("../extensions/progress.js"),
+    import("../extensions/spoiler.js"),
+    import("../extensions/color-swatch.js"),
+    import("../extensions/math.js"),
+    import("../extensions/diff.js")
   ]);
   const lowlight = createLowlight(common);
   const extensions = [
@@ -129,6 +173,7 @@ async function loadClientExtensions() {
     MetaField,
     // Document embeds & linking
     DocEmbed,
+    DocLink,
     DocLinkDrop,
     MentionDrop,
     SelectionDrag,
@@ -137,7 +182,23 @@ async function loadClientExtensions() {
     FieldGroup,
     // Advanced code blocks
     CodePreview,
-    CodeTree
+    CodeTree,
+    // Visual blocks
+    Divider,
+    Quote,
+    Figure,
+    Embed,
+    Video,
+    Stat,
+    StatGroup,
+    Button,
+    ButtonGroup,
+    Progress,
+    Spoiler,
+    ColorSwatch,
+    MathBlock,
+    MathInline,
+    Diff
   ];
   try {
     const emojiPkg = "@tiptap/extension-emoji";
@@ -207,7 +268,18 @@ export const corePlugin = {
     ])
   ),
   extensions() {
-    return _cachedClient ?? [];
+    if (!_cachedClient) return [];
+    let disabled = [];
+    try {
+      disabled = useRuntimeConfig().public?.abracadabra?.disabledBuiltins ?? [];
+    } catch {
+    }
+    if (!disabled.length) return _cachedClient;
+    return _cachedClient.filter((ext) => {
+      const name = ext?.name;
+      if (!name || !OPTIONAL_BUILTIN_EXTENSIONS.has(name)) return true;
+      return !disabled.includes(name);
+    });
   },
   serverExtensions() {
     if (_cachedServer) return _cachedServer;

package/dist/runtime/server/plugins/abracadabra-service.js

@@ -42,7 +42,9 @@ export default defineNitroPlugin(async (nitroApp) => {
       import("@noble/hashes/sha512"),
       import("yjs")
     ]);
-    ed.hashes.sha512 = (m) => sha512(m);
+    const edEtc = ed.etc;
+    edEtc.sha512Sync = (...m) => sha512(edEtc.concatBytes(...m));
+    edEtc.sha512Async = (...m) => Promise.resolve(edEtc.sha512Sync(...m));
     const privKey = fromBase64Url(privKeyB64);
     const client = new AbracadabraClient({
       // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Nuxt runtime config augmentation not resolved in Nitro
@@ -68,7 +70,7 @@ export default defineNitroPlugin(async (nitroApp) => {
     if (!rootDocId) {
       try {
         const info = await $fetch(`${config.public?.abracadabra?.url}/info`);
-        rootDocId = info?.index_doc_id ?? "";
+        rootDocId = info?.root_doc_id ?? "";
       } catch {
       }
     }

package/dist/runtime/server/utils/rpcHandler.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Server-side RPC v1 handler registry for `@abraca/nuxt`.
+ *
+ * Wraps `provider.rpc.handle(...)` from `@abraca/dabra` with a Nuxt-flavoured
+ * shape: schema validation (Zod-compatible — anything with `.parse()`),
+ * structured logging, and lifecycle hooks. Handlers register against the
+ * service provider's root-doc subscription, which is where service-role
+ * runners advertise capabilities.
+ *
+ * Usage from a Nitro plugin:
+ *
+ *   export default defineNitroPlugin((nitroApp) => {
+ *     nitroApp.hooks.hook('abracadabra:before-runners', () => {
+ *       registerServerPlugin({
+ *         name: 'my-plugin',
+ *         serverRunners: [
+ *           defineRpcRunner({
+ *             handlers: [
+ *               defineRpcHandler({
+ *                 method: 'ai.summarize@1',
+ *                 schema: z.object({ docId: z.string() }),
+ *                 async handler(args, ctx) {
+ *                   return await summarize(args.docId)
+ *                 },
+ *               }),
+ *             ],
+ *           }),
+ *         ],
+ *       })
+ *     })
+ *   })
+ */
+import type { RpcHandlerContext } from '@abraca/dabra';
+import { RpcError as RpcErrorClass } from '@abraca/dabra';
+import type { ServerRunnerDefinition, ServerRunnerContext } from '../../types.js';
+/** Anything with a `.parse(value): T` method — Zod, Valibot, ArkType, … */
+export interface RpcSchema<T> {
+    parse(value: unknown): T;
+}
+export interface RpcHandlerDefinition<TArgs = unknown, TResult = unknown> {
+    /** Method name. Convention: `<namespace>.<verb>@<version>`, e.g. `ai.summarize@1`. */
+    method: string;
+    /** Optional schema for `args`. Validation failure → `SCHEMA` error result. */
+    schema?: RpcSchema<TArgs>;
+    /**
+     * The actual handler. Throw an `RpcError` for typed failures; any other
+     * thrown value becomes `INTERNAL`. Returning an async generator turns each
+     * `yield` into a `rpc:progress` frame; the generator's return value is the
+     * final result.
+     */
+    handler: (args: TArgs, ctx: RpcHandlerContext) => TResult | Promise<TResult> | AsyncGenerator<unknown, TResult, void>;
+}
+/**
+ * Define a single RPC handler. The return value is consumed by
+ * `defineRpcRunner({ handlers })`.
+ */
+export declare function defineRpcHandler<TArgs, TResult>(def: RpcHandlerDefinition<TArgs, TResult>): RpcHandlerDefinition<TArgs, TResult>;
+export interface RpcRunnerOptions {
+    /** Optional unique runner name (defaults to `abracadabra:rpc`). */
+    name?: string;
+    handlers: RpcHandlerDefinition<any, any>[];
+    /** Called once before any handler is registered. */
+    onStart?: (ctx: ServerRunnerContext) => void | Promise<void>;
+}
+/**
+ * Define a server runner that wires every handler to the root provider's
+ * RPC client and unregisters them on shutdown.
+ *
+ * Returns a `ServerRunnerDefinition` you can list under
+ * `AbracadabraPlugin.serverRunners`.
+ */
+export declare function defineRpcRunner(options: RpcRunnerOptions): ServerRunnerDefinition;
+export { RpcErrorClass as RpcError };
+export type { RpcHandler, RpcHandlerContext } from '@abraca/dabra';