@ai-matrx/associations 0.2.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,154 @@
 # Changelog — @ai-matrx/associations
 
+## 0.4.0 — 2026-08-29 (unreleased; W4 completion)
+
+The three faces STOPPED at the W3+W4 build for missing design-system
+primitives, now built against `@ai-matrx/design-system` 0.3.0 (Command
+family incl. CommandDialog, the Select family, the CreatablePicker
+composite) — the optional peer floor moves to **`>=0.3.0`**. Behavior ported
+VERBATIM from the matrx-frontend originals (each re-read in full
+2026-08-29); only the measured seams inverted, chrome never vendored.
+
+- **`AssociationEntitySelect` (`src/react/components/AssociationEntitySelect.tsx`)**
+  — the canonical "name dropdown" (display / inline rename / switch / add new
+  / unlink), adapter-driven via the already-shipping
+  `AssociationEntitySelectAdapter` contract + default adapter hook. Seams:
+  `getEntityInfo` → the store's registry merge engine (`Icon: null` →
+  `DefaultEntityIcon`); `@/lib/toast` → the notifier port;
+  `EntityDoorControls` → the entityDoors port's `DoorControls` (absent → the
+  name and rows render without doors, matching the picker precedent); lucide
+  → inlined glyphs (C19).
+- **`CategorySelect` (`src/react/components/CategorySelect.tsx`)** — THE
+  single-value picker over one `platform.categories` dimension, the
+  CreatablePicker composite with the hierarchy parent-select in
+  `createExtra`. Seams: the Redux active-organization read
+  (`selectOrganizationId`) → the identity port's optional `ensureOrgId()`
+  (`orgId` prop wins; with neither, create refuses LOUDLY — notifier + no
+  RPC); toasts → notifier. NOTE: the origin's two-part success toast
+  (message + description) is joined into the notifier's single success
+  message (the port's `success(msg)` carries no description); content
+  preserved.
+- **`CategoryTagPicker` (`src/react/components/CategoryTagPicker.tsx`)** —
+  THE multi-select tagger over the canonical `entity → category` edge
+  (full-role `setTargets` semantics verbatim, one write at a time). Seams:
+  the host-shaped `ensureOrgId` (`@/lib/organizations/personalOrg`) →
+  `identity.ensureOrgId` per the design's seam table, with the loud
+  `ensure_org_missing` refusal when neither the `orgId` prop nor the port
+  can answer; `console.error` → errorSink
+  (`category_tag_set_targets_failed` / `category_tag_create_failed`);
+  toasts → notifier; the `icon` prop's `LucideIcon` type → the structural
+  `TagPickerIcon`.
+- **`buildCategoryHierarchy` → `/core`
+  (`src/core/categoryHierarchy.ts`)** — the two-level display-order util
+  both category faces consume, ported verbatim from
+  `features/scopes/utils/categoryHierarchy.ts` (pure, React-free), exported
+  from `/core`.
+- **Four new inlined glyphs (C19)**: `ChevronDownIcon`,
+  `ChevronsUpDownIcon`, `CornerDownRightIcon`, `TagIcon`.
+- **Token vocabulary regenerated from the live registry: 651 → 654 tokens**
+  (`platform_continued_access`, `route_manifest_entry`, `short_link` landed
+  after the 0.3.0 generation; caught by the W5 swap agent's token-parity
+  gate). `check:entity-types` green against live.
+- 16 new jsdom behavioral tests (render + interaction + degradations against
+  fake ports) → 147 total; full gate green (`typecheck`, `test`,
+  `check:package` incl. the packed-tarball canary).
+
+
+## 0.3.0 — 2026-08-29 (unreleased; W3 + W4 of the extraction)
+
+Waves 3 and 4: the `/react` subpath — the seven hooks riding the /core store
+via `useSyncExternalStore`, and the faces/pickers/capture toolbar. Behavior
+ported VERBATIM from the matrx-frontend originals (re-read in full
+2026-08-29); only the measured seams inverted onto the W1 ports. `/react` is
+the package's ONE banner group: its dist chunks carry `"use client"` (tsup
+banner + `scripts/stamp-client-boundary.mjs` belt); the root and `/core`
+stay pure, and `verify-tarball` now proves both directions.
+
+- **`AssociationsProvider` (`src/react/context.tsx`)** — the one React
+  binding point: the host constructs the /core store in its binding module
+  and mounts the provider with the five UI ports (notifier / windowShell /
+  capture / pickerOverrides / entityDoors). Every hook/face reaches the
+  store via `useAssociationsStore()`, which THROWS with a precise message
+  when no provider is mounted. `useNotifier()` implements the notifier
+  degradation: absent → warn ONCE via errorSink, every user-facing failure
+  still screams to the sink.
+- **W3 hooks, signatures byte-compatible with the originals** (the W5 swap
+  is a re-export flip + Redux-fragment deletion, call sites unchanged):
+  `useAssociations` (+ `useEntityRelationships` alias + re-exported
+  `AssociationWriteResult`), `useContainerLinks` (incl. the viewer-aware
+  `conversation_files` branch, generation/stale guards verbatim),
+  `useEntityTitles` (labels never exempt the liveness read; one settled
+  round proves absence), `useCategories`, `useUniversalEntitySearch`
+  (debounce + recents via `ues_list`), `useAssociationCandidates`,
+  `useAssociationEntitySelectAdapter` (+ the
+  `AssociationEntitySelectAdapter` contract, which now lives with the
+  hook). Redux selectors/thunks → `useSyncExternalStore` over the store;
+  `@/lib/toast` → notifier; `console.error` → errorSink; the host `Json`
+  type → `unknown` (`ContainerLink.metadata`, `attach` metadata).
+  `useAssociationCandidates`' Redux `selectUserId` read became a LENIENT
+  identity-port read (null when unauthenticated): `ownerId` is a
+  candidate-read filter, not an auth gate — write paths keep the loud
+  `requireUserId` contract.
+- **W4 faces**: `AssociationCard`, `AssociationCardGrid`, `AssociationList`
+  (+ `ContainerResourcesAdapter` + `useContainerLinksAdapter`),
+  `AssociationPicker` (+ `AssociationCandidateBody` + the
+  create-then-associate footer), `UniversalAssociationPicker`,
+  `AttachedItemsSheet`, `AssociationCaptureToolbar`, `AssociationWindow`,
+  `PrimaryEntityProvider`/`usePrimaryEntity`, plus the content-role chrome
+  (`CONTENT_ROLES`/`getContentRoleMeta` — display metadata is /react's;
+  the classification stays /core's) and the door-seam helpers
+  (`DoorRef`/`UnresolvedRef`).
+- **Seam inversions (deliberate, per the design's Decision 2 table)**:
+  - the hardcoded `token === "file"` → FilePickerWindow branch became the
+    `pickerOverrides` port: `AssociationPicker` routes a registered token to
+    its override component (same `AssociationPickerProps` contract);
+    `UniversalAssociationPicker`'s browse mode opens the override too, so
+    "file enumeration only happens through the canonical picker" survives
+    the inversion; with no override the generic candidate list serves every
+    token (the documented degradation);
+  - `WindowPanel` → the `windowShell` port; absent → a package-internal
+    fixed centered overlay (non-draggable, same anatomy, page behind stays
+    interactive);
+  - `EntityRef`/`EntityDoorControls`/access-gate `UnresolvedEntityRef` →
+    the `entityDoors` port; absent → title text with the overlay `hrefFor`
+    anchor when present, plain text otherwise, and the package's plain
+    "Unavailable" chip for unreadable targets;
+  - the capture toolbar's `features/files` + `features/data-tables` imports
+    → the `capture` port, PER-HANDLER optional: chips render only when
+    their handler exists, zero handlers → no toolbar and no drop zone
+    (never dead buttons, never a drop that swallows files). The original's
+    "Add document" picker (a host command palette over
+    `listAccessibleDocuments`) has no capture handler by design — hosts
+    append it via `extraActions`. "New document" collects its name with an
+    inline input row (the original's `TextInputDialog` is host chrome) and
+    opens the created document through the registry's `hrefFor` overlay
+    instead of a hardcoded `/documents/…` route;
+  - lucide icons → the package's own inlined SVGs (C19); host shadcn
+    `Input`/`Skeleton`/`Button`/`cn` → `@ai-matrx/design-system` (new
+    OPTIONAL peer at the `>=0.2.0` floor, per C18 — never vendored twins).
+- **Store additions (additive, /core)**: `AssociationsStore` now exposes
+  the bound `errorSink` and `identity` so /react surfaces scream and read
+  identity without a second binding.
+- **W4 gaps (deliberately NOT built — design-system 0.2.0 lacks the
+  primitives; vendoring twins is banned)**: `AssociationEntitySelect`,
+  `CategorySelect`, `CategoryTagPicker`. They need a Command/combobox
+  family (cmdk-style CommandInput/List/Item/Group/Empty + CommandDialog),
+  a Select, and the CreatablePicker composite. The
+  `AssociationEntitySelectAdapter` contract + default adapter hook (the
+  Redux-free seam) shipped anyway, so those faces are a pure-chrome build
+  once design-system grows.
+- Tests: 131 (from 97) — jsdom behavioral suites per hook (subscription
+  updates, in-flight dedup across two consumers, error surfaces,
+  create-then-attach retry + loud outcome) and per face (render +
+  interaction against fake ports, every degradation branch: no windowShell,
+  no entityDoors, picker override routing, zero capture handlers,
+  created-but-unlinked screams).
+- Gate: `pnpm typecheck && pnpm test && pnpm check:package` green; the
+  tarball canary installs react + react-dom + `@ai-matrx/design-system`
+  (npm, 0.2.0) into the empty project and imports AND requires `/react`,
+  proves the `"use client"` banner on both /react chunks and its absence
+  on all four pure chunks.
+
 ## 0.2.0 — 2026-08-29 (unreleased; W2 of the extraction)
 
 Wave 2: the headless owns-persistence `/core` subpath — the service

package/README.md

@@ -4,11 +4,12 @@ THE one way to relate two entities on the AI Matrx platform: association edges,
 categories, favorites/recents, and the generated entity-type vocabulary — shipped
 as one package a Matrx client or enterprise app installs.
 
-**v0.2 ships the types root and the headless `/core`** — the service
-chokepoint, guards, the never-throw result funnel, the registry merge engine,
-and the subscribable cache store. The React faces (`/react`: hooks, cards,
-list, pickers, capture toolbar) arrive in the next waves. Everything below
-about the schema is binding — it is the package's product.
+**v0.3 ships the types root, the headless `/core`, and the React binding
+`/react`** — the service chokepoint, guards, the never-throw result funnel,
+the registry merge engine, the subscribable cache store, the seven hooks, and
+the association faces (cards, list, pickers, attached-items sheet, capture
+toolbar). Everything below about the schema is binding — it is the package's
+product.
 
 ```ts
 import {
@@ -46,6 +47,35 @@ await store.favorites.setFavorite("note", noteId, true);
 await assertDemandedSchema(supabase, { selfTest: true });
 ```
 
+```tsx
+// /react — the banner'd React binding (peer: react >=18 and
+// @ai-matrx/design-system >=0.2.0 for the faces' chrome). Bind ONCE:
+import {
+  AssociationsProvider,
+  useAssociations,              // the seven hooks keep the app originals' exact signatures
+  AssociationCardGrid,          // + AssociationCard / AssociationList / pickers / capture toolbar
+  PrimaryEntityProvider,
+} from "@ai-matrx/associations/react";
+
+<AssociationsProvider
+  store={store}                 // the /core store from createAssociationsStore
+  notifier={toastAdapter}       // optional — absent warns once, failures still hit errorSink
+  windowShell={windowAdapter}   // optional — absent falls back to a fixed overlay
+  capture={captureHandlers}     // optional, per-handler — chips render only when bound
+  pickerOverrides={{ file: FilePickerWindowAdapter }} // optional per-token pickers
+  entityDoors={{ EntityRef, DoorControls, UnresolvedRef }} // optional doors
+>
+  <PrimaryEntityProvider value={{ type: "organization", id, orgId, label }}>
+    <AssociationCardGrid />
+  </PrimaryEntityProvider>
+</AssociationsProvider>;
+```
+
+The faces style with Tailwind semantic tokens (`bg-card`,
+`text-muted-foreground`, …): register this package as a Tailwind v4 source in
+the consuming app (`@source "../node_modules/@ai-matrx/associations/dist"`)
+the same way `@ai-matrx/design-system` documents.
+
 ## The demanded schema — read this first
 
 This package is **opinionated like the Python `matrx-*` packages**: it does not

package/dist/core/index.cjs

@@ -26,6 +26,7 @@ __export(core_exports, {
   SELF_TEST_MISSING_RPC: () => SELF_TEST_MISSING_RPC,
   assertDemandedSchema: () => assertDemandedSchema,
   associationsKey: () => associationsKey,
+  buildCategoryHierarchy: () => buildCategoryHierarchy,
   createAssociationGuards: () => createAssociationGuards,
   createAssociationHelpers: () => createAssociationHelpers,
   createAssociationsService: () => createAssociationsService,
@@ -475,6 +476,7 @@ var ENTITY_TYPE_METADATA = {
   "platform_actor_session": { token: "platform_actor_session", schema: "platform", table: "actor_session", label: "Actor session", baseTier: 1, isComponent: false, isModule: false, isListed: false, scopeable: true, category: null, referencePickable: false, titleColumn: null, contentRole: null, referenceCategory: null },
   "platform_actor_token": { token: "platform_actor_token", schema: "platform", table: "actor_token", label: "Actor token", baseTier: 1, isComponent: false, isModule: false, isListed: false, scopeable: true, category: null, referencePickable: false, titleColumn: null, contentRole: null, referenceCategory: null },
   "platform_actor_token_event": { token: "platform_actor_token_event", schema: "platform", table: "actor_token_event", label: "Actor token event", baseTier: 1, isComponent: false, isModule: false, isListed: false, scopeable: true, category: null, referencePickable: false, titleColumn: null, contentRole: null, referenceCategory: null },
+  "platform_continued_access": { token: "platform_continued_access", schema: "platform", table: "continued_access", label: "Continued Access", baseTier: 1, isComponent: false, isModule: false, isListed: false, scopeable: true, category: null, referencePickable: false, titleColumn: null, contentRole: null, referenceCategory: null },
   "platform_outcome_event": { token: "platform_outcome_event", schema: "platform", table: "outcome_event", label: "Outcome Event", baseTier: 1, isComponent: false, isModule: false, isListed: true, scopeable: true, category: null, referencePickable: false, titleColumn: null, contentRole: null, referenceCategory: null },
   "platform_outsider_consumer": { token: "platform_outsider_consumer", schema: "platform", table: "outsider_consumer", label: "Outsider consumer", baseTier: 1, isComponent: false, isModule: false, isListed: false, scopeable: true, category: null, referencePickable: false, titleColumn: null, contentRole: null, referenceCategory: null },
   "platform_saved_view": { token: "platform_saved_view", schema: "platform", table: "saved_view", label: "Saved view", baseTier: 1, isComponent: false, isModule: false, isListed: true, scopeable: true, category: null, referencePickable: false, titleColumn: null, contentRole: null, referenceCategory: null },
@@ -503,6 +505,7 @@ var ENTITY_TYPE_METADATA = {
   "research_tag": { token: "research_tag", schema: "research", table: "rs_tag", label: "Research Tag", baseTier: 1, isComponent: true, isModule: false, isListed: false, scopeable: true, category: null, referencePickable: false, titleColumn: "name", contentRole: null, referenceCategory: null },
   "research_template": { token: "research_template", schema: "research", table: "rs_template", label: "Research Template", baseTier: 1, isComponent: false, isModule: false, isListed: false, scopeable: true, category: null, referencePickable: true, titleColumn: "name", contentRole: null, referenceCategory: null },
   "research_topic": { token: "research_topic", schema: "research", table: "rs_topic", label: "Research Topic", baseTier: 1, isComponent: false, isModule: false, isListed: false, scopeable: true, category: null, referencePickable: true, titleColumn: "name", contentRole: null, referenceCategory: null },
+  "route_manifest_entry": { token: "route_manifest_entry", schema: "platform", table: "route_manifest", label: "Route Manifest Entry", baseTier: 1, isComponent: false, isModule: false, isListed: false, scopeable: true, category: null, referencePickable: false, titleColumn: null, contentRole: null, referenceCategory: null },
   "rulebook": { token: "rulebook", schema: "platform", table: "rulebook", label: "Rulebook", baseTier: 1, isComponent: false, isModule: false, isListed: true, scopeable: true, category: "Knowledge", referencePickable: true, titleColumn: "name", contentRole: "source", referenceCategory: null },
   "sandbox_instance": { token: "sandbox_instance", schema: "public", table: "sandbox_instances", label: "Sandbox Instance", baseTier: 1, isComponent: false, isModule: false, isListed: false, scopeable: true, category: null, referencePickable: false, titleColumn: null, contentRole: null, referenceCategory: null },
   "sch_agent_task": { token: "sch_agent_task", schema: "scheduler", table: "sch_agent_task", label: "Agent Task Config", baseTier: 1, isComponent: true, isModule: false, isListed: false, scopeable: true, category: null, referencePickable: false, titleColumn: null, contentRole: null, referenceCategory: null },
@@ -581,6 +584,7 @@ var ENTITY_TYPE_METADATA = {
   "seo_topic": { token: "seo_topic", schema: "seo", table: "topic", label: "SEO Topic", baseTier: 1, isComponent: false, isModule: false, isListed: false, scopeable: true, category: "seo", referencePickable: true, titleColumn: "name", contentRole: null, referenceCategory: null },
   "seo_web_analytics_daily": { token: "seo_web_analytics_daily", schema: "seo", table: "web_analytics_daily", label: "Web Analytics Daily", baseTier: 1, isComponent: true, isModule: false, isListed: false, scopeable: true, category: "marketing", referencePickable: false, titleColumn: null, contentRole: null, referenceCategory: null },
   "shared_canvas_item": { token: "shared_canvas_item", schema: "canvas", table: "shared_canvas_items", label: "Shared Canvas Item", baseTier: 1, isComponent: false, isModule: false, isListed: false, scopeable: true, category: null, referencePickable: true, titleColumn: "title", contentRole: null, referenceCategory: null },
+  "short_link": { token: "short_link", schema: "platform", table: "short_links", label: "Short Link", baseTier: 1, isComponent: false, isModule: false, isListed: false, scopeable: true, category: null, referencePickable: false, titleColumn: null, contentRole: null, referenceCategory: null },
   "skill": { token: "skill", schema: "skill", table: "definition", label: "Skill", baseTier: 1, isComponent: false, isModule: false, isListed: false, scopeable: true, category: "Skills", referencePickable: true, titleColumn: "label", contentRole: "utility", referenceCategory: null },
   "skill_render_definition": { token: "skill_render_definition", schema: "skill", table: "render_definition", label: "Skill Render Definition", baseTier: 1, isComponent: false, isModule: false, isListed: false, scopeable: true, category: "Skills", referencePickable: true, titleColumn: "label", contentRole: null, referenceCategory: null },
   "sms_consent": { token: "sms_consent", schema: "communication", table: "sms_consent", label: "SMS Consent", baseTier: 1, isComponent: false, isModule: false, isListed: false, scopeable: true, category: null, referencePickable: false, titleColumn: null, contentRole: null, referenceCategory: null },
@@ -1128,6 +1132,7 @@ var ENTITY_TYPE_TOKENS = [
   "platform_actor_session",
   "platform_actor_token",
   "platform_actor_token_event",
+  "platform_continued_access",
   "platform_outcome_event",
   "platform_outsider_consumer",
   "platform_saved_view",
@@ -1156,6 +1161,7 @@ var ENTITY_TYPE_TOKENS = [
   "research_tag",
   "research_template",
   "research_topic",
+  "route_manifest_entry",
   "rulebook",
   "sandbox_instance",
   "sch_agent_task",
@@ -1234,6 +1240,7 @@ var ENTITY_TYPE_TOKENS = [
   "seo_topic",
   "seo_web_analytics_daily",
   "shared_canvas_item",
+  "short_link",
   "skill",
   "skill_render_definition",
   "sms_consent",
@@ -3019,7 +3026,9 @@ function createAssociationsStore(config) {
     helpers,
     registry,
     services: { associations, categories },
-    registerEntityOverlay: registry.registerEntityOverlay
+    registerEntityOverlay: registry.registerEntityOverlay,
+    errorSink,
+    identity: config.identity
   };
 }
 
@@ -3188,4 +3197,68 @@ function isContentSourceEdge(sourceType, metadata) {
   if (isMembershipMetadata(metadata)) return false;
   return true;
 }
+
+// src/core/categoryHierarchy.ts
+function buildCategoryHierarchy(categories) {
+  const byId = new Map(categories.map((category) => [category.id, category]));
+  const hasHierarchy = categories.some(
+    (category) => category.parentId !== null && byId.has(category.parentId)
+  );
+  if (!hasHierarchy) {
+    return {
+      items: categories.map((category) => ({
+        category,
+        depth: 0,
+        parent: null,
+        displayName: category.name
+      })),
+      roots: categories.filter((category) => category.parentId === null),
+      hasHierarchy: false
+    };
+  }
+  const roots = categories.filter(
+    (category) => category.parentId === null || !byId.has(category.parentId)
+  );
+  const childrenByParent = /* @__PURE__ */ new Map();
+  for (const category of categories) {
+    if (!category.parentId || !byId.has(category.parentId)) continue;
+    const children = childrenByParent.get(category.parentId) ?? [];
+    children.push(category);
+    childrenByParent.set(category.parentId, children);
+  }
+  const items = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const root of roots) {
+    items.push({
+      category: root,
+      depth: 0,
+      parent: null,
+      displayName: root.name
+    });
+    seen.add(root.id);
+    for (const child of childrenByParent.get(root.id) ?? []) {
+      items.push({
+        category: child,
+        depth: 1,
+        parent: root,
+        displayName: `${root.name} / ${child.name}`
+      });
+      seen.add(child.id);
+    }
+  }
+  for (const category of categories) {
+    if (seen.has(category.id)) continue;
+    items.push({
+      category,
+      depth: 0,
+      parent: null,
+      displayName: category.name
+    });
+  }
+  return {
+    items,
+    roots: categories.filter((category) => category.parentId === null),
+    hasHierarchy: true
+  };
+}
 //# sourceMappingURL=index.cjs.map