@makinbakin/sdk 0.0.1-rc.20 → 0.0.1-rc.21

package/internal/index.d.ts

@@ -0,0 +1,70 @@
+/**
+ * `@makinbakin/sdk/internal` — host-shell plumbing. NOT plugin-author API.
+ *
+ * Everything here exists so the Bakin host shell (PluginHost, sidebar,
+ * router catch-all, ⌘K overlay, drift checker) can drive the shared
+ * client-side registries that `registerPlugin` populates. Plugin authors
+ * never import this entry; the author surface is the root barrel plus the
+ * documented sub-paths. Excluded from the generated SDK reference docs.
+ *
+ * Breaking changes here only ever affect the host shell, which ships in
+ * lockstep with the SDK — there is no compatibility contract on this entry.
+ */
+/** Tear down all registrations owned by a plugin (dev hot-swap teardown). */
+export { unregisterPlugin } from '../register';
+/** Current registry version — bumps on every mutation (for useSyncExternalStore). */
+export { getRegistryVersion } from '../register';
+/** Subscribe to registry-version changes. */
+export { subscribeRegistry } from '../register';
+/** Get every registered nav item across all plugins. */
+export { getAllNavItems } from '../register';
+/** Get a snapshot of the current nav items (non-subscribing). */
+export { getNavItemsSnapshot } from '../register';
+/** Get nav items contributed by a specific plugin. */
+export { getPluginNavItems } from '../register';
+/** Stable snapshot of every active nav badge keyed by navItemId. */
+export { getNavBadgesSnapshot } from '../register';
+/** Subscribe to nav-badge mutations (separate channel from `subscribeRegistry`). */
+export { subscribeNavBadges } from '../register';
+/** Look up a specific client route by plugin id + path. */
+export { getPluginRoute } from '../register';
+/** Get all registered client routes (across all plugins). */
+export { getPluginRoutes } from '../register';
+/** Seed a plugin's declarative nav from its manifest (survives unregisterPlugin). */
+export { setManifestNav } from '../register';
+/** Read the manifest nav currently seeded for a plugin (drift validation). */
+export { getManifestNav } from '../register';
+/** Look up the ⌘K hit renderer registered for a content type. */
+export { getSearchHitRenderer } from '../register';
+/** Stable snapshot of all registered hit renderers keyed by content type. */
+export { getSearchHitRenderersSnapshot } from '../register';
+/** Subscribe to hit-renderer mutations (own channel). */
+export { subscribeSearchHitRenderers } from '../register';
+export type { ClientRouteEntry, MatchedPluginRoute } from '../register';
+/** Install the manifest-derived slot/route ownership index for lazy loading. */
+export { configureLazyPlugins } from '../lazy/index';
+/** Install the demand loader that imports a plugin's client bundle. */
+export { setLazyPluginLoader } from '../lazy/index';
+/** Report a plugin client's load progress: idle → loading → loaded | error. */
+export { setPluginLoadState } from '../lazy/index';
+/** Current load state for a plugin client. Unknown plugins report 'idle'. */
+export { getPluginLoadState } from '../lazy/index';
+/** Last load error message for a plugin whose state is 'error', if any. */
+export { getPluginLoadError } from '../lazy/index';
+/** Plugins whose manifests declare the given slot in `contributes.slots`. */
+export { getSlotOwners } from '../lazy/index';
+/** Plugins whose manifest `contributes.routes` patterns match a pathname. */
+export { getRouteOwners } from '../lazy/index';
+/** Ask the host to lazy-load every idle plugin that fills the named slot. */
+export { requestSlotPlugins } from '../lazy/index';
+/** Ask the host to lazy-load every idle plugin whose route patterns match the pathname. */
+export { requestRoutePlugins } from '../lazy/index';
+/** Ask the host to lazy-load every idle plugin — cross-plugin surfaces (⌘K search). */
+export { requestAllPlugins } from '../lazy/index';
+/** Reset a failed plugin to idle and re-request its client bundle. */
+export { retryPluginLoad } from '../lazy/index';
+/** Monotonic lazy-store version for useSyncExternalStore consumers. */
+export { getLazyPluginsVersion } from '../lazy/index';
+/** Subscribe to lazy-plugin store mutations. Returns an unsubscribe fn. */
+export { subscribeLazyPlugins } from '../lazy/index';
+export type { LazyPluginIndex, PluginLoadState } from '../lazy/index';

package/internal/index.js

@@ -0,0 +1,409 @@
+// @bun
+// packages/sdk/src/slots/registry.ts
+function getRegistry() {
+  const g = globalThis;
+  if (!g.__bakinSlotRegistry) {
+    g.__bakinSlotRegistry = new Map;
+  }
+  return g.__bakinSlotRegistry;
+}
+function clearSlotsOwnedBy(pluginId) {
+  const reg = getRegistry();
+  for (const [name, entries] of reg.entries()) {
+    const filtered = entries.filter((e) => e.owner !== pluginId);
+    if (filtered.length === 0)
+      reg.delete(name);
+    else
+      reg.set(name, filtered);
+  }
+}
+
+// packages/sdk/src/register.ts
+"use client";
+function buildNavItemsSnapshot(registry) {
+  const items = [];
+  for (const [pluginId, navItems] of registry.manifestNavByPlugin.entries()) {
+    if (registry.navByPlugin.has(pluginId))
+      continue;
+    items.push(...navItems);
+  }
+  for (const navItems of registry.navByPlugin.values()) {
+    items.push(...navItems);
+  }
+  return items.sort((a, b) => (a.order ?? 100) - (b.order ?? 100));
+}
+function getRegistry2() {
+  const g = globalThis;
+  if (!g.__bakinClientRegistry) {
+    g.__bakinClientRegistry = {
+      navByPlugin: new Map,
+      manifestNavByPlugin: new Map,
+      routesByPlugin: new Map,
+      cleanupByPlugin: new Map,
+      navItemsSnapshot: [],
+      version: 0,
+      listeners: new Set,
+      badgesByPlugin: new Map,
+      badgesSnapshot: new Map,
+      badgeListeners: new Set,
+      hitRenderersByPlugin: new Map,
+      hitRenderersSnapshot: new Map,
+      hitRendererListeners: new Set
+    };
+  }
+  const registry = g.__bakinClientRegistry;
+  if (!registry.manifestNavByPlugin)
+    registry.manifestNavByPlugin = new Map;
+  if (!Array.isArray(registry.navItemsSnapshot)) {
+    registry.navItemsSnapshot = buildNavItemsSnapshot(registry);
+  }
+  if (!registry.badgesByPlugin)
+    registry.badgesByPlugin = new Map;
+  if (!registry.badgesSnapshot)
+    registry.badgesSnapshot = buildBadgesSnapshot(registry);
+  if (!registry.badgeListeners)
+    registry.badgeListeners = new Set;
+  if (!registry.hitRenderersByPlugin)
+    registry.hitRenderersByPlugin = new Map;
+  if (!registry.hitRenderersSnapshot)
+    registry.hitRenderersSnapshot = buildHitRenderersSnapshot(registry);
+  if (!registry.hitRendererListeners)
+    registry.hitRendererListeners = new Set;
+  return registry;
+}
+function buildHitRenderersSnapshot(registry) {
+  const snapshot = new Map;
+  for (const byType of registry.hitRenderersByPlugin.values()) {
+    for (const [type, renderer] of byType) {
+      if (!snapshot.has(type))
+        snapshot.set(type, renderer);
+    }
+  }
+  return snapshot;
+}
+function bumpHitRenderers() {
+  const registry = getRegistry2();
+  registry.hitRenderersSnapshot = buildHitRenderersSnapshot(registry);
+  for (const l of registry.hitRendererListeners) {
+    try {
+      l();
+    } catch (err) {
+      console.error("[bakin] hit-renderer listener threw:", err);
+    }
+  }
+}
+function buildBadgesSnapshot(registry) {
+  const snapshot = new Map;
+  for (const byNavItemId of registry.badgesByPlugin.values()) {
+    for (const [navItemId, badge] of byNavItemId) {
+      if (!snapshot.has(navItemId))
+        snapshot.set(navItemId, badge);
+    }
+  }
+  return snapshot;
+}
+function bumpBadges() {
+  const registry = getRegistry2();
+  registry.badgesSnapshot = buildBadgesSnapshot(registry);
+  for (const l of registry.badgeListeners) {
+    try {
+      l();
+    } catch (err) {
+      console.error("[bakin] badge listener threw:", err);
+    }
+  }
+}
+function bumpVersion() {
+  const registry = getRegistry2();
+  registry.navItemsSnapshot = buildNavItemsSnapshot(registry);
+  registry.version++;
+  for (const l of registry.listeners) {
+    try {
+      l();
+    } catch (err) {
+      console.error("[bakin] registry listener threw:", err);
+    }
+  }
+}
+function unregisterPlugin(id) {
+  const registry = getRegistry2();
+  const cleanups = registry.cleanupByPlugin.get(id);
+  if (cleanups) {
+    for (const fn of cleanups) {
+      try {
+        fn();
+      } catch (err) {
+        console.error(`[bakin] cleanup fn for ${id} threw:`, err);
+      }
+    }
+    registry.cleanupByPlugin.delete(id);
+  }
+  registry.navByPlugin.delete(id);
+  registry.routesByPlugin.delete(id);
+  clearSlotsOwnedBy(id);
+  const hadBadges = registry.badgesByPlugin.delete(id);
+  const hadRenderers = registry.hitRenderersByPlugin.delete(id);
+  bumpVersion();
+  if (hadBadges)
+    bumpBadges();
+  if (hadRenderers)
+    bumpHitRenderers();
+}
+function setManifestNav(pluginId, navItems) {
+  const registry = getRegistry2();
+  if (!navItems || navItems.length === 0) {
+    if (!registry.manifestNavByPlugin.delete(pluginId))
+      return;
+    bumpVersion();
+    return;
+  }
+  const prev = registry.manifestNavByPlugin.get(pluginId);
+  if (prev && JSON.stringify(prev) === JSON.stringify(navItems))
+    return;
+  registry.manifestNavByPlugin.set(pluginId, navItems);
+  bumpVersion();
+}
+function getManifestNav(pluginId) {
+  return getRegistry2().manifestNavByPlugin.get(pluginId) ?? [];
+}
+function getRegistryVersion() {
+  return getRegistry2().version;
+}
+function subscribeRegistry(listener) {
+  const registry = getRegistry2();
+  registry.listeners.add(listener);
+  return () => {
+    registry.listeners.delete(listener);
+  };
+}
+function getAllNavItems() {
+  return [...getRegistry2().navItemsSnapshot];
+}
+function getNavItemsSnapshot() {
+  return getRegistry2().navItemsSnapshot;
+}
+function getPluginNavItems(pluginId) {
+  return getRegistry2().navByPlugin.get(pluginId) ?? [];
+}
+function getNavBadgesSnapshot() {
+  return getRegistry2().badgesSnapshot;
+}
+function subscribeNavBadges(listener) {
+  const registry = getRegistry2();
+  registry.badgeListeners.add(listener);
+  return () => {
+    registry.badgeListeners.delete(listener);
+  };
+}
+function getSearchHitRenderer(type) {
+  return getRegistry2().hitRenderersSnapshot.get(type);
+}
+function getSearchHitRenderersSnapshot() {
+  return getRegistry2().hitRenderersSnapshot;
+}
+function subscribeSearchHitRenderers(listener) {
+  const registry = getRegistry2();
+  registry.hitRendererListeners.add(listener);
+  return () => {
+    registry.hitRendererListeners.delete(listener);
+  };
+}
+function normalizePattern(pattern) {
+  return pattern.split("/").filter(Boolean);
+}
+function matchRoutePattern(pattern, pathname) {
+  const patternSegments = normalizePattern(pattern);
+  const pathSegments = normalizePattern(pathname);
+  if (patternSegments.length !== pathSegments.length)
+    return null;
+  const params = {};
+  let score = 0;
+  for (let i = 0;i < patternSegments.length; i++) {
+    const patternSegment = patternSegments[i];
+    const pathSegment = pathSegments[i];
+    const bracket = patternSegment.match(/^\[([^\]]+)\]$/);
+    const isColon = patternSegment.startsWith(":");
+    const isDollar = patternSegment.startsWith("$");
+    if (bracket || isColon || isDollar) {
+      const key = bracket?.[1] ?? patternSegment.slice(1);
+      params[key] = decodeURIComponent(pathSegment);
+      continue;
+    }
+    if (patternSegment !== pathSegment)
+      return null;
+    score += 1;
+  }
+  return { params, score };
+}
+function getPluginRoute(pathname) {
+  const registry = getRegistry2();
+  let best = null;
+  for (const [pluginId, routes] of registry.routesByPlugin.entries()) {
+    for (const route2 of routes) {
+      const match = matchRoutePattern(route2.path, pathname);
+      if (!match)
+        continue;
+      if (!best || match.score > best.score) {
+        best = {
+          pluginId,
+          path: route2.path,
+          component: route2.component,
+          params: match.params,
+          score: match.score
+        };
+      }
+    }
+  }
+  if (!best)
+    return null;
+  const { score: _score, ...route } = best;
+  return route;
+}
+function getPluginRoutes(pluginId) {
+  const registry = getRegistry2();
+  if (pluginId)
+    return registry.routesByPlugin.get(pluginId) ?? [];
+  return [...registry.routesByPlugin.values()].flat();
+}
+// packages/sdk/src/lazy.ts
+"use client";
+function getStore() {
+  const g = globalThis;
+  if (!g.__bakinLazyPluginStore) {
+    g.__bakinLazyPluginStore = {
+      ownersBySlot: new Map,
+      routeOwners: [],
+      states: new Map,
+      errors: new Map,
+      loader: null,
+      version: 0,
+      listeners: new Set
+    };
+  }
+  return g.__bakinLazyPluginStore;
+}
+function bump() {
+  const store = getStore();
+  store.version++;
+  for (const l of store.listeners) {
+    try {
+      l();
+    } catch (err) {
+      console.error("[bakin] lazy-plugin listener threw:", err);
+    }
+  }
+}
+function configureLazyPlugins(index) {
+  const store = getStore();
+  store.ownersBySlot = new Map(index.slotOwners);
+  store.routeOwners = [...index.routeOwners];
+  bump();
+}
+function setLazyPluginLoader(loader) {
+  getStore().loader = loader;
+}
+function setPluginLoadState(pluginId, state, error) {
+  const store = getStore();
+  if (store.states.get(pluginId) === state && store.errors.get(pluginId) === error)
+    return;
+  store.states.set(pluginId, state);
+  if (state === "error" && error)
+    store.errors.set(pluginId, error);
+  else
+    store.errors.delete(pluginId);
+  bump();
+}
+function getPluginLoadState(pluginId) {
+  return getStore().states.get(pluginId) ?? "idle";
+}
+function getPluginLoadError(pluginId) {
+  return getStore().errors.get(pluginId);
+}
+function getSlotOwners(name) {
+  return getStore().ownersBySlot.get(name) ?? [];
+}
+function getRouteOwners(pathname) {
+  const owners = [];
+  for (const { pattern, pluginId } of getStore().routeOwners) {
+    if (matchRoutePattern(pattern, pathname) && !owners.includes(pluginId)) {
+      owners.push(pluginId);
+    }
+  }
+  return owners;
+}
+function demand(pluginIds) {
+  const store = getStore();
+  if (!store.loader)
+    return;
+  for (const pluginId of pluginIds) {
+    if ((store.states.get(pluginId) ?? "idle") !== "idle")
+      continue;
+    store.loader(pluginId);
+  }
+}
+function requestSlotPlugins(name) {
+  demand(getSlotOwners(name));
+}
+function requestRoutePlugins(pathname) {
+  demand(getRouteOwners(pathname));
+}
+function requestAllPlugins() {
+  const store = getStore();
+  const ids = new Set;
+  for (const owners of store.ownersBySlot.values()) {
+    for (const id of owners)
+      ids.add(id);
+  }
+  for (const { pluginId } of store.routeOwners)
+    ids.add(pluginId);
+  demand([...ids]);
+}
+function retryPluginLoad(pluginId) {
+  const store = getStore();
+  if (store.states.get(pluginId) !== "error")
+    return;
+  store.states.set(pluginId, "idle");
+  store.errors.delete(pluginId);
+  bump();
+  demand([pluginId]);
+}
+function getLazyPluginsVersion() {
+  return getStore().version;
+}
+function subscribeLazyPlugins(listener) {
+  const store = getStore();
+  store.listeners.add(listener);
+  return () => {
+    store.listeners.delete(listener);
+  };
+}
+export {
+  unregisterPlugin,
+  subscribeSearchHitRenderers,
+  subscribeRegistry,
+  subscribeNavBadges,
+  subscribeLazyPlugins,
+  setPluginLoadState,
+  setManifestNav,
+  setLazyPluginLoader,
+  retryPluginLoad,
+  requestSlotPlugins,
+  requestRoutePlugins,
+  requestAllPlugins,
+  getSlotOwners,
+  getSearchHitRenderersSnapshot,
+  getSearchHitRenderer,
+  getRouteOwners,
+  getRegistryVersion,
+  getPluginRoutes,
+  getPluginRoute,
+  getPluginNavItems,
+  getPluginLoadState,
+  getPluginLoadError,
+  getNavItemsSnapshot,
+  getNavBadgesSnapshot,
+  getManifestNav,
+  getLazyPluginsVersion,
+  getAllNavItems,
+  configureLazyPlugins
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@makinbakin/sdk",
-  "version": "0.0.1-rc.20",
+  "version": "0.0.1-rc.21",
   "description": "SDK for building Bakin plugins — UI components, slot types, hooks, and the runtime registerPlugin helper.",
   "type": "module",
   "sideEffects": false,
@@ -42,6 +42,14 @@
     "./routing": {
       "import": "./routing/index.js",
       "types": "./routing/index.d.ts"
+    },
+    "./testing": {
+      "import": "./testing/index.js",
+      "types": "./testing/index.d.ts"
+    },
+    "./internal": {
+      "import": "./internal/index.js",
+      "types": "./internal/index.d.ts"
     }
   },
   "files": [
@@ -58,7 +66,6 @@
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
     "cmdk": "^1.1.1",
-    "lucide-react": "^0.577.0",
     "react-hook-form": "^7.72.0",
     "zod": "^4.3.0",
     "zustand": "^5.0.12"

package/register.d.ts

@@ -17,7 +17,7 @@
  * nav + slot trees re-render when plugins come or go at runtime.
  */
 import type { ComponentType } from 'react';
-import type { NavBadge, NavItem } from './types/index';
+import type { NavBadge, NavItem, SearchHitRenderer } from './types/index';
 interface PluginRegistration {
     id: string;
     navItems?: NavItem[];
@@ -35,6 +35,14 @@ interface PluginRegistration {
      * directly from the plugin's client.tsx alongside registerPlugin.
      */
     slots?: Record<string, ComponentType<any>>;
+    /**
+     * Global-search contributions: content type (bare table name, e.g.
+     * 'assets') → hit renderer for the ⌘K overlay. Plain data-mapping
+     * functions, not components.
+     */
+    search?: {
+        hitRenderers: Record<string, SearchHitRenderer>;
+    };
 }
 interface ClientRouteEntry {
     path: string;
@@ -120,6 +128,16 @@ export declare function getNavBadgesSnapshot(): ReadonlyMap<string, NavBadge>;
  * so high-frequency badge ticks don't force the whole nav to re-render.
  */
 export declare function subscribeNavBadges(listener: () => void): () => void;
+/** Renderer for a content type (bare table name), or undefined if none. */
+export declare function getSearchHitRenderer(type: string): SearchHitRenderer | undefined;
+/**
+ * Stable snapshot of every registered hit renderer keyed by content type.
+ * Identity changes only on register/unregister — safe for
+ * `useSyncExternalStore`. The ⌘K overlay derives its type chips from this.
+ */
+export declare function getSearchHitRenderersSnapshot(): ReadonlyMap<string, SearchHitRenderer>;
+/** Subscribe to hit-renderer mutations (own channel, like nav badges). */
+export declare function subscribeSearchHitRenderers(listener: () => void): () => void;
 /**
  * Match a route pattern (`/projects/[id]`, `/x/:id`, `/y/$id`) against a
  * concrete pathname. Internal SDK helper shared with the lazy-loading index.