feat(shared-slots): new package — typed pub/sub slots for extension points

Mirrors @statewalker/shared-intents one-for-one: `Slots` workspace adapter,
`newSlot<T>(key) → [provide, observe]` factory, `Slots.getSnapshot` with
referentially-stable arrays, plus a `useSlot` React hook on the `/react`
subpath. The hook reads the slot key from a hidden symbol attached by
`newSlot`, so consumers don't pass the key twice.

Implements the foundation primitive for Eclipse-style extension points
described in notes/2026-05/2026-05-06/03.dockview-json-render-intents-vision.md.

20/20 vitest tests covering provide/observe/dispose, reference dedupe,
observer-error isolation, getSnapshot stability and invalidation, and
useSlot re-render counts (related/unrelated/stable-ref).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: mkotelnikov

packages/shared-slots/README.md

@@ -0,0 +1,109 @@
+# @statewalker/shared-slots
+
+Typed pub/sub slots for cross-fragment extension points (Eclipse-style).
+
+## Installation
+
+```sh
+pnpm add @statewalker/shared-slots
+```
+
+## Why this exists
+
+Slots are the umbrella's primitive for **declared, reference-keyed
+extension points**. A fragment that owns a contract declares a slot;
+other fragments contribute values into it; the consumer iterates the
+contributions. The shape mirrors `@statewalker/shared-intents`
+exactly — one workspace = one bus, accessed via
+`workspace.requireAdapter(Slots)`.
+
+## Usage
+
+```ts
+import { newSlot, Slots } from "@statewalker/shared-slots";
+
+// Declaration site (the contract):
+interface MimeRenderer {
+  match: (mime: string) => number;
+  catalogId: string;
+}
+
+export const [provideMimeRenderer, observeMimeRenderers] =
+  newSlot<MimeRenderer>("files:mime-renderers");
+
+// Provider (any fragment):
+import { provideMimeRenderer } from "@my-app/files";
+const dispose = provideMimeRenderer(slots, {
+  match: (m) => (m === "text/markdown" ? 1 : 0),
+  catalogId: "markdown-viewer",
+});
+
+// Consumer (the files fragment, iterating contributions):
+const renderers = slots.getSnapshot<MimeRenderer>("files:mime-renderers");
+const best = renderers
+  .map((r) => ({ score: r.match(mime), id: r.catalogId }))
+  .sort((a, b) => b.score - a.score)[0];
+```
+
+## React
+
+```tsx
+import { useSlot } from "@statewalker/shared-slots/react";
+import { observeMimeRenderers } from "@my-app/files";
+
+function MyComponent({ slots }: { slots: Slots }) {
+  const renderers = useSlot(slots, observeMimeRenderers);
+  // re-renders when providers register/dispose; stable reference otherwise
+  return <ul>{renderers.map((r) => <li key={r.catalogId}>{r.catalogId}</li>)}</ul>;
+}
+```
+
+`useSlot` extracts the slot key from the `observe` function it
+receives (attached via a hidden symbol when `newSlot` builds it),
+so callers don't pass the key twice. Hand-rolled observers that
+didn't go through `newSlot` won't work with `useSlot` — by design.
+
+## API
+
+- `Slots` — the bus class. One workspace = one bus.
+  - `provide<T>(key, value): () => void`
+  - `observe<T>(key, cb): () => void` (synchronous immediate snapshot
+    + sync notifications)
+  - `getSnapshot<T>(key): readonly T[]` (referentially stable until
+    next `provide`/dispose for that key)
+- `newSlot<T>(key) → [provide, observe]` — typed declaration. The
+  returned tuple matches `newIntent` in shape.
+- `useSlot<T>(slots, observe): readonly T[]` — React hook
+  (subpath `/react`).
+
+## Identity & dependency direction
+
+**Reference identity.** Values are stored in a `Set`, deduped by
+reference. Providing the same object twice = one entry. Two
+structurally-equal-but-distinct objects = two entries. If you need
+identity-by-data, dedupe at provision time.
+
+**Dependency direction (the rule slots enforce).** The slot's
+declaring module is the contract owner. The owner must not depend
+on any specific provider or observer. Providers and observers may
+freely import the contract. This is the one-way arrow that makes
+slots Eclipse-style — a third-party plug-in can declare its own
+slot and other plug-ins can contribute without touching either the
+plug-in or the host.
+
+The asymmetry vs. `Intents`: intents are RPC (bidirectional
+dispatch is the point); slots are pub/sub containers (the
+declaring module reads its contents, so contents-readers being
+independent of contents-providers is what makes the slot
+extensible).
+
+## Related
+
+- `@statewalker/shared-intents` — the sibling RPC bus.
+- `@statewalker/shared-registry` — LIFO cleanup for
+  `provide` / `observe` disposers.
+- `@statewalker/workspace-api` — the `Workspace` adapter host.
+
+## License
+
+MIT — see the monorepo root `LICENSE`.

packages/shared-slots/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@statewalker/shared-slots",
+  "version": "0.1.0",
+  "private": false,
+  "type": "module",
+  "description": "Typed pub/sub slots for cross-fragment extension points (Eclipse-style).",
+  "homepage": "https://github.com/statewalker/statewalker-shared",
+  "author": {
+    "name": "Mikhail Kotelnikov",
+    "email": "mikhail.kotelnikov@gmail.com"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com/statewalker/statewalker-shared.git"
+  },
+  "exports": {
+    ".": "./src/index.ts",
+    "./react": "./src/react.ts"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "test": "vitest run --passWithNoTests",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "clean": "rimraf dist",
+    "lint": "biome check --write .",
+    "format": "biome format --write ."
+  },
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@testing-library/react": "^16.3.0",
+    "@types/react": "^19.2.5",
+    "happy-dom": "^17.5.7",
+    "react": "^19.2.5",
+    "react-dom": "^19.2.5",
+    "rimraf": "catalog:",
+    "tsdown": "catalog:",
+    "typescript": "catalog:",
+    "vitest": "catalog:"
+  },
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  }
+}

packages/shared-slots/src/index.ts

@@ -0,0 +1,3 @@
+export type { SlotObserve, SlotProvide } from "./new-slot.js";
+export { getSlotKey, newSlot, SLOT_KEY } from "./new-slot.js";
+export { Slots } from "./types.js";

packages/shared-slots/src/new-slot.ts

@@ -0,0 +1,43 @@
+import type { Slots } from "./types.js";
+
+export type SlotProvide<T> = (slots: Slots, value: T) => () => void;
+export type SlotObserve<T> = (slots: Slots, cb: (values: T[]) => void) => () => void;
+
+/**
+ * Hidden symbol used to attach the slot's string key to the typed
+ * `provide` / `observe` functions returned by `newSlot`. The `useSlot`
+ * React hook reads the key back so it can call `Slots.getSnapshot(key)`
+ * for `useSyncExternalStore`'s snapshot getter without forcing every
+ * consumer to pass the key twice.
+ */
+export const SLOT_KEY: unique symbol = Symbol("statewalker:shared-slots:key");
+
+interface KeyBound {
+  [SLOT_KEY]?: string;
+}
+
+/**
+ * Declare a typed slot by stable string key. Returns a `[provide, observe]`
+ * tuple where each function takes the workspace's `Slots` bus as its first
+ * argument — same shape as `newIntent` from `@statewalker/shared-intents`.
+ *
+ * The string key is erased from the consumer's surface; every site that
+ * contributes to or observes the slot uses the typed `provide` / `observe`
+ * functions, not the underlying string.
+ */
+export function newSlot<T>(key: string): [provide: SlotProvide<T>, observe: SlotObserve<T>] {
+  const provide: SlotProvide<T> = (slots, value) => slots.provide<T>(key, value);
+  const observe: SlotObserve<T> = (slots, cb) => slots.observe<T>(key, cb);
+  (provide as unknown as KeyBound)[SLOT_KEY] = key;
+  (observe as unknown as KeyBound)[SLOT_KEY] = key;
+  return [provide, observe];
+}
+
+/**
+ * Read the slot key from a `provide` / `observe` function returned by
+ * `newSlot`. Returns `undefined` for hand-rolled functions that didn't go
+ * through `newSlot`. Used by the React `useSlot` hook.
+ */
+export function getSlotKey(fn: SlotProvide<unknown> | SlotObserve<unknown>): string | undefined {
+  return (fn as unknown as KeyBound)[SLOT_KEY];
+}

packages/shared-slots/src/react.test.tsx

@@ -0,0 +1,103 @@
+import { act, cleanup, render } from "@testing-library/react";
+import { useRef } from "react";
+import { afterEach, describe, expect, it } from "vitest";
+import { newSlot } from "./new-slot.js";
+import { useSlot } from "./react.js";
+import { Slots } from "./types.js";
+
+interface Thing {
+  id: string;
+}
+
+const [provideThing, observeThing] = newSlot<Thing>("test:thing");
+const [provideOther] = newSlot<Thing>("test:other");
+
+afterEach(() => {
+  cleanup();
+});
+
+interface ProbeProps {
+  slots: Slots;
+}
+
+function ThingsProbe({ slots }: ProbeProps): React.ReactElement {
+  const renderCount = useRef(0);
+  renderCount.current += 1;
+  const things = useSlot(slots, observeThing);
+  const lastRef = useRef<readonly Thing[]>(things);
+  if (lastRef.current !== things) {
+    lastRef.current = things;
+  }
+  return (
+    <div data-testid="things" data-render-count={renderCount.current} data-len={things.length} />
+  );
+}
+
+describe("useSlot", () => {
+  it("re-renders when a related provider registers", () => {
+    const slots = new Slots();
+    const { getByTestId } = render(<ThingsProbe slots={slots} />);
+    expect(getByTestId("things").getAttribute("data-len")).toBe("0");
+    expect(getByTestId("things").getAttribute("data-render-count")).toBe("1");
+
+    act(() => {
+      provideThing(slots, { id: "a" });
+    });
+    expect(getByTestId("things").getAttribute("data-len")).toBe("1");
+    expect(getByTestId("things").getAttribute("data-render-count")).toBe("2");
+  });
+
+  it("does not re-render when an unrelated provider registers", () => {
+    const slots = new Slots();
+    const { getByTestId } = render(<ThingsProbe slots={slots} />);
+    expect(getByTestId("things").getAttribute("data-render-count")).toBe("1");
+
+    act(() => {
+      provideOther(slots, { id: "z" });
+    });
+    expect(getByTestId("things").getAttribute("data-render-count")).toBe("1");
+    expect(getByTestId("things").getAttribute("data-len")).toBe("0");
+  });
+
+  it("returns a stable array reference between unrelated re-renders", () => {
+    const slots = new Slots();
+    let lastSeen: readonly Thing[] | null = null;
+    let sameRefCount = 0;
+
+    function ParentProbe(): React.ReactElement {
+      const things = useSlot(slots, observeThing);
+      if (lastSeen !== null && lastSeen === things) {
+        sameRefCount += 1;
+      }
+      lastSeen = things;
+      return <div />;
+    }
+
+    const { rerender } = render(<ParentProbe />);
+    // Force a parent re-render with no slot mutation in between.
+    rerender(<ParentProbe />);
+    rerender(<ParentProbe />);
+    expect(sameRefCount).toBeGreaterThanOrEqual(1);
+  });
+
+  it("releases the subscription on unmount", () => {
+    const slots = new Slots();
+    const { unmount } = render(<ThingsProbe slots={slots} />);
+    unmount();
+    // After unmount there should be no live observers; provide does not throw.
+    expect(() => provideThing(slots, { id: "after-unmount" })).not.toThrow();
+  });
+
+  it("throws if observe was not produced by newSlot", () => {
+    const slots = new Slots();
+    const handRolled = ((s: Slots, cb: (v: Thing[]) => void) =>
+      s.observe<Thing>("hand-rolled", cb)) as unknown as typeof observeThing;
+
+    function BadProbe(): React.ReactElement {
+      useSlot(slots, handRolled);
+      return <div />;
+    }
+
+    expect(() => render(<BadProbe />)).toThrow(/observe function was not produced by newSlot/);
+  });
+});

packages/shared-slots/src/react.ts

@@ -0,0 +1,37 @@
+import { useSyncExternalStore } from "react";
+import { getSlotKey, type SlotObserve } from "./new-slot.js";
+import type { Slots } from "./types.js";
+
+/**
+ * React hook: subscribe to a slot's contributions on the given `Slots` bus.
+ * Returns a referentially-stable readonly array — the same reference is
+ * returned across renders unless the slot has been mutated since the last
+ * snapshot, so `useSyncExternalStore` does not loop.
+ *
+ * Pass the typed `observe` function returned by `newSlot`; `useSlot`
+ * extracts the slot key from it so callers do not have to pass the key
+ * twice.
+ *
+ * @example
+ * const [provideThing, observeThing] = newSlot<Thing>("k:thing");
+ *
+ * function Component() {
+ *   const slots = useWorkspace().requireAdapter(Slots);
+ *   const things = useSlot(slots, observeThing);
+ *   // things is a readonly Thing[] — re-renders when providers register/dispose
+ * }
+ */
+export function useSlot<T>(slots: Slots, observe: SlotObserve<T>): readonly T[] {
+  const key = getSlotKey(observe);
+  if (!key) {
+    throw new Error(
+      "useSlot: the observe function was not produced by newSlot(...). " +
+        "useSlot only works with typed slot observers because it needs the " +
+        "slot key to read a stable getSnapshot() reference.",
+    );
+  }
+  return useSyncExternalStore(
+    (notify) => observe(slots, () => notify()),
+    () => slots.getSnapshot<T>(key),
+  );
+}