@ai-matrx/agents 0.59.260 → 0.59.262

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 0.59.262
+### no second star read after a catalog or search read (FW-014)
+
+- `ensureLoaded()` and `searchServer()` no longer follow each read with `ues_get_bulk('agent', every id)`.
+  Every catalog read (`agx_get_list_full`, `agx_search`, `agent.agx_get_by_ids`) already returns
+  `is_favorite` computed server-side from `platform.user_entity_state` (`platform.my_favorite`), so
+  `toAgentSummary` now reads it. Saves one sequential request uploading every agent id (673 ids for an
+  ordinary account, 1,478 for admin) on every picker load and search.
+- Removed: `overlayAgentFavorites` (internal) and the `favorite_read_failed` error code. The favorites
+  port's `getBulk` is no longer called by the catalog. Consumer action: none.
+
+## 0.59.261
+
+Automatic changed-only republish (docs/metadata drift since the last published version; verified: `git diff 9a4fd3053c c006aa4394 -- apps/shared/matrx-agents/src`
+has no shipped-source changes outside tests, fixtures and docs). No consumer action required.
+
 ## 0.59.260
 ### the pinned read asks the server for those agents only (FW-015)
 
@@ -10,6 +26,16 @@
 - The narrow read needs a client with `schema()` (supabase-js has it); without one the store falls back to the
   whole catalog and reports `pinned_read_unsupported`, as before. Consumer action: none.
 
+## 0.59.259
+
+Automatic changed-only republish (docs/metadata drift since the last published version; verified: `git diff 48dc0c53e7 c3bd77d32a -- apps/shared/matrx-agents/src`
+has no shipped-source changes outside tests, fixtures and docs). No consumer action required.
+
+## 0.59.258
+
+Automatic changed-only republish (docs/metadata drift since the last published version; verified: `git diff 0a2b8c9356 48dc0c53e7 -- apps/shared/matrx-agents/src`
+has no shipped-source changes outside tests, fixtures and docs). No consumer action required.
+
 ## 0.59.257
 
 Automatic changed-only republish (docs/metadata drift since the last published version; verified: `git diff 76b41cb76b 0a2b8c9356 -- apps/shared/matrx-agents/src`

package/dist/catalog/index.cjs

@@ -239,9 +239,11 @@ function toAgentSummary(raw) {
     modelId: str(raw["model_id"]),
     isActive: bool(raw["is_active"]),
     isArchived: bool(raw["is_archived"]),
-    // Stars are per-person (platform.user_entity_state) and are overlaid by
-    // `overlayAgentFavorites` — a list row never carries the caller's star.
-    isFavorite: false,
+    // The caller's star. Every read this module maps (agx_get_list_full,
+    // agx_search, agent.agx_get_by_ids) computes it server-side with
+    // platform.my_favorite — platform.user_entity_state for auth.uid(), the
+    // same table the favorites port reads — so no second read is needed (FW-014).
+    isFavorite: bool(raw["is_favorite"]),
     createdBy: str(raw["created_by"]),
     organizationId: str(raw["organization_id"]),
     taskId: str(raw["task_id"]),
@@ -354,29 +356,6 @@ async function readSingleAgentRow(client, agentId) {
   return null;
 }
 var AGENT_FAVORITE_ENTITY_TYPE = "agent";
-async function overlayAgentFavorites(favorites, rows, onError) {
-  if (rows.length === 0) return rows;
-  let starred = null;
-  try {
-    const result = await favorites.getBulk(
-      AGENT_FAVORITE_ENTITY_TYPE,
-      rows.map((r) => r.id)
-    );
-    if (result.ok) {
-      starred = new Set(
-        result.data.items.filter((s) => s.isFavorite).map((s) => s.entityId)
-      );
-    } else {
-      onError(result.error.message);
-    }
-  } catch (e) {
-    onError(e instanceof Error ? e.message : String(e));
-  }
-  return rows.map((r) => {
-    const isFavorite2 = starred?.has(r.id) ?? false;
-    return r.isFavorite === isFavorite2 ? r : { ...r, isFavorite: isFavorite2 };
-  });
-}
 async function writeAgentFavorite(favorites, agentId, isFavorite2) {
   const result = await favorites.setFavorite(
     AGENT_FAVORITE_ENTITY_TYPE,
@@ -832,13 +811,6 @@ function createAgentCatalog(config) {
     identity,
     errorSink
   }).favorites;
-  function reportFavoriteReadFailure(message) {
-    errorSink({
-      code: "favorite_read_failed",
-      message: `your starred agents could not be read (${message}); every star is shown unset until the next catalog load`,
-      context: { catalogId }
-    });
-  }
   const labels = {
     ...DEFAULT_AGENT_CATALOG_LABELS,
     ...config.labels ?? {}
@@ -910,11 +882,7 @@ function createAgentCatalog(config) {
     }
     publish({ ...state, status: "loading", error: null });
     try {
-      const rows = await overlayAgentFavorites(
-        favorites,
-        await readAgentCatalogRows(client),
-        reportFavoriteReadFailure
-      );
+      const rows = await readAgentCatalogRows(client);
       replaceRows(rows);
       publish({ ...state, status: "succeeded", error: null, favoriteRowsStatus: "succeeded" });
       globalState.listFetchedAt.set(catalogId, Date.now());
@@ -1064,13 +1032,7 @@ function createAgentCatalog(config) {
   }
   async function searchServer(query, deep = false) {
     const result = await searchAgentsOnServer(client, { query, deep });
-    mergeRows(
-      await overlayAgentFavorites(
-        favorites,
-        result.rows,
-        reportFavoriteReadFailure
-      )
-    );
+    mergeRows(result.rows);
     return result.ids;
   }
   async function setFavorite(agentId, isFavorite2) {

package/dist/catalog/index.d.cts

@@ -809,9 +809,10 @@ declare function getRegisteredAgentCatalog(catalogId?: string): AgentCatalog | u
  *   2. `agx_search(p_query, p_deep, p_limit, p_offset)` — tier-2 server search.
  *   3. `agx_resolve_agent_address(p_ids)` — the single-agent name read, used
  *      when a mandate's Holder is not in the caller's own catalog.
- *   4. The caller's stars: `ues_get_bulk('agent', ids)` through the
- *      favorites port (`platform.user_entity_state`), overlaid on every row
- *      set this module returns to the store.
+ *   4. The caller's stars arrive ON the rows: every read above computes
+ *      `is_favorite` server-side from `platform.user_entity_state`
+ *      (`platform.my_favorite`). There is no second star read (FW-014; the
+ *      `ues_get_bulk` overlay over every id was retired 2026-10-23).
  *   5. ONE write: the caller's star, `ues_set` through the same port. The
  *      retired `agent.definition.is_favorite` column is never read or written.
  *   6. THE PINNED READ (2026-10-09; by-ids 2026-10-23): the caller's starred

package/dist/catalog/index.d.ts

@@ -809,9 +809,10 @@ declare function getRegisteredAgentCatalog(catalogId?: string): AgentCatalog | u
  *   2. `agx_search(p_query, p_deep, p_limit, p_offset)` — tier-2 server search.
  *   3. `agx_resolve_agent_address(p_ids)` — the single-agent name read, used
  *      when a mandate's Holder is not in the caller's own catalog.
- *   4. The caller's stars: `ues_get_bulk('agent', ids)` through the
- *      favorites port (`platform.user_entity_state`), overlaid on every row
- *      set this module returns to the store.
+ *   4. The caller's stars arrive ON the rows: every read above computes
+ *      `is_favorite` server-side from `platform.user_entity_state`
+ *      (`platform.my_favorite`). There is no second star read (FW-014; the
+ *      `ues_get_bulk` overlay over every id was retired 2026-10-23).
  *   5. ONE write: the caller's star, `ues_set` through the same port. The
  *      retired `agent.definition.is_favorite` column is never read or written.
  *   6. THE PINNED READ (2026-10-09; by-ids 2026-10-23): the caller's starred

package/dist/catalog/index.js

@@ -133,9 +133,11 @@ function toAgentSummary(raw) {
     modelId: str(raw["model_id"]),
     isActive: bool(raw["is_active"]),
     isArchived: bool(raw["is_archived"]),
-    // Stars are per-person (platform.user_entity_state) and are overlaid by
-    // `overlayAgentFavorites` — a list row never carries the caller's star.
-    isFavorite: false,
+    // The caller's star. Every read this module maps (agx_get_list_full,
+    // agx_search, agent.agx_get_by_ids) computes it server-side with
+    // platform.my_favorite — platform.user_entity_state for auth.uid(), the
+    // same table the favorites port reads — so no second read is needed (FW-014).
+    isFavorite: bool(raw["is_favorite"]),
     createdBy: str(raw["created_by"]),
     organizationId: str(raw["organization_id"]),
     taskId: str(raw["task_id"]),
@@ -248,29 +250,6 @@ async function readSingleAgentRow(client, agentId) {
   return null;
 }
 var AGENT_FAVORITE_ENTITY_TYPE = "agent";
-async function overlayAgentFavorites(favorites, rows, onError) {
-  if (rows.length === 0) return rows;
-  let starred = null;
-  try {
-    const result = await favorites.getBulk(
-      AGENT_FAVORITE_ENTITY_TYPE,
-      rows.map((r) => r.id)
-    );
-    if (result.ok) {
-      starred = new Set(
-        result.data.items.filter((s) => s.isFavorite).map((s) => s.entityId)
-      );
-    } else {
-      onError(result.error.message);
-    }
-  } catch (e) {
-    onError(e instanceof Error ? e.message : String(e));
-  }
-  return rows.map((r) => {
-    const isFavorite2 = starred?.has(r.id) ?? false;
-    return r.isFavorite === isFavorite2 ? r : { ...r, isFavorite: isFavorite2 };
-  });
-}
 async function writeAgentFavorite(favorites, agentId, isFavorite2) {
   const result = await favorites.setFavorite(
     AGENT_FAVORITE_ENTITY_TYPE,
@@ -726,13 +705,6 @@ function createAgentCatalog(config) {
     identity,
     errorSink
   }).favorites;
-  function reportFavoriteReadFailure(message) {
-    errorSink({
-      code: "favorite_read_failed",
-      message: `your starred agents could not be read (${message}); every star is shown unset until the next catalog load`,
-      context: { catalogId }
-    });
-  }
   const labels = {
     ...DEFAULT_AGENT_CATALOG_LABELS,
     ...config.labels ?? {}
@@ -804,11 +776,7 @@ function createAgentCatalog(config) {
     }
     publish({ ...state, status: "loading", error: null });
     try {
-      const rows = await overlayAgentFavorites(
-        favorites,
-        await readAgentCatalogRows(client),
-        reportFavoriteReadFailure
-      );
+      const rows = await readAgentCatalogRows(client);
       replaceRows(rows);
       publish({ ...state, status: "succeeded", error: null, favoriteRowsStatus: "succeeded" });
       globalState.listFetchedAt.set(catalogId, Date.now());
@@ -958,13 +926,7 @@ function createAgentCatalog(config) {
   }
   async function searchServer(query, deep = false) {
     const result = await searchAgentsOnServer(client, { query, deep });
-    mergeRows(
-      await overlayAgentFavorites(
-        favorites,
-        result.rows,
-        reportFavoriteReadFailure
-      )
-    );
+    mergeRows(result.rows);
     return result.ids;
   }
   async function setFavorite(agentId, isFavorite2) {

package/dist/context/react/index.cjs

@@ -43,11 +43,13 @@ __export(react_exports, {
   InlineMaxInput: () => InlineMaxInput,
   PAGE_LEVEL: () => PAGE_LEVEL,
   buildContextLevels: () => buildContextLevels,
+  buildContextTree: () => buildContextTree,
   includeChanges: () => includeChanges,
   inheritedInclude: () => inheritedInclude,
   levelRows: () => levelRows,
   placeByOrigin: () => placeByOrigin,
-  summarizeContextRows: () => summarizeContextRows
+  summarizeContextRows: () => summarizeContextRows,
+  treeLevels: () => treeLevels
 });
 module.exports = __toCommonJS(react_exports);
 
@@ -203,6 +205,41 @@ function buildContextLevels(rows, hierarchy) {
   for (const level of out) level.groups = stableSort(level.groups, (g) => g.ref);
   return stableSort(out, (level) => level.ref);
 }
+function buildContextTree(levels) {
+  const roots = [];
+  const byId = /* @__PURE__ */ new Map();
+  const rank = /* @__PURE__ */ new Map();
+  for (const level of levels) {
+    const labels = level.ref.path.length > 0 ? level.ref.path : [""];
+    let siblings = roots;
+    let last = null;
+    const ids = [];
+    for (let i = 0; i < labels.length; i++) {
+      ids.push(labels[i].trim().toLowerCase());
+      const id = ids.join("
");
+      let hit = byId.get(id);
+      if (!hit) {
+        hit = { id, label: labels[i], path: labels.slice(0, i + 1), level: null, children: [] };
+        byId.set(id, hit);
+        siblings.push(hit);
+      }
+      const order = level.ref.order ?? 0;
+      rank.set(hit, Math.min(rank.get(hit) ?? order, order));
+      last = hit;
+      siblings = hit.children;
+    }
+    if (last) last.level = level;
+  }
+  const sort = (list) => {
+    const sorted = stableSort(list, (n) => ({ order: rank.get(n) ?? 0 }));
+    for (const n of sorted) n.children = sort(n.children);
+    return sorted;
+  };
+  return sort(roots);
+}
+function treeLevels(node) {
+  return [...node.level ? [node.level] : [], ...node.children.flatMap(treeLevels)];
+}
 function levelRows(level) {
   return [...level.rows, ...level.groups.flatMap((g) => g.rows)];
 }
@@ -463,16 +500,6 @@ function useNarrow(ref) {
 }
 var INDENT = ["", "pl-2", "pl-4", "pl-6"];
 var indent = (depth) => INDENT[Math.min(depth, INDENT.length - 1)];
-function sectionsOf(levels) {
-  const out = [];
-  for (const level of levels) {
-    const label = level.ref.path.length > 1 ? level.ref.path[0] : null;
-    const last = out[out.length - 1];
-    if (label !== null && last && last.label === label) last.levels.push(level);
-    else out.push({ id: label === null ? `level:${level.ref.id}` : `section:${label}`, label, levels: [level] });
-  }
-  return out;
-}
 function ContextRulesTable({
   rows,
   cap,
@@ -517,14 +544,13 @@ function ContextRulesTable({
     rowId(row)
   );
   const heading = (props) => /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(Heading, { ...props, grid, narrow, comfortable, readOnly }, props.id);
-  const renderLevel = (level, depth) => {
+  const renderLevelBody = (level, depth, label) => {
     const all = levelRows(level);
-    const name = level.ref.path[level.ref.path.length - 1] ?? "";
-    return /* @__PURE__ */ (0, import_jsx_runtime3.jsxs)("div", { role: "rowgroup", "aria-label": headed ? level.ref.path.join(" \u203A ") : void 0, "data-level": level.ref.id, children: [
+    return /* @__PURE__ */ (0, import_jsx_runtime3.jsxs)(import_jsx_runtime3.Fragment, { children: [
       headed ? heading({
         id: `h:${level.ref.id}`,
         kind: "level",
-        label: name,
+        label,
         switchName: level.ref.path.join(" \u203A "),
         depth,
         rows: all,
@@ -544,7 +570,51 @@ function ContextRulesTable({
         }),
         group.rows.map((row) => renderRow(row, depth + 2))
       ] }, group.ref.id))
-    ] }, level.ref.id);
+    ] });
+  };
+  const renderNode = (node, depth) => {
+    const { level } = node;
+    const below = node.children.map((child) => renderNode(child, depth + 1));
+    if (level) {
+      return /* @__PURE__ */ (0, import_jsx_runtime3.jsxs)(
+        "div",
+        {
+          role: "rowgroup",
+          "aria-label": headed ? level.ref.path.join(" \u203A ") : void 0,
+          "data-level": level.ref.id,
+          children: [
+            renderLevelBody(level, depth, node.label),
+            below
+          ]
+        },
+        level.ref.id
+      );
+    }
+    const covered = treeLevels(node);
+    const all = covered.flatMap(levelRows);
+    const several = covered.length > 1;
+    const toggleSection = several && !readOnly ? (next) => {
+      const changes = [];
+      for (const lv of covered) {
+        if (lv.master) lv.master.onToggle?.(next);
+        else changes.push(...bulkChanges(levelRows(lv), next));
+      }
+      if (changes.length > 0) onSetInclude?.(changes);
+    } : void 0;
+    return /* @__PURE__ */ (0, import_jsx_runtime3.jsxs)("div", { role: "rowgroup", "aria-label": node.label, "data-section": node.label, children: [
+      heading({
+        id: `h:section:${node.id}`,
+        kind: "section",
+        label: node.label,
+        switchName: node.path.join(" \u203A "),
+        depth,
+        rows: all,
+        checked: covered.some((l) => l.master ? l.master.on : levelRows(l).some((r) => r.include)),
+        onToggle: toggleSection,
+        noSwitch: !several
+      }),
+      below
+    ] }, `section:${node.id}`);
   };
   return /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(import_design_system3.TooltipProvider, { delayDuration: 300, titleTooltips: false, children: /* @__PURE__ */ (0, import_jsx_runtime3.jsxs)(
     "div",
@@ -569,33 +639,7 @@ function ContextRulesTable({
             ]
           }
         ),
-        levels.length === 0 ? /* @__PURE__ */ (0, import_jsx_runtime3.jsx)("div", { className: "px-2 py-3 text-center text-muted-foreground", children: "None" }) : sectionsOf(levels).map((section) => {
-          if (section.label === null || !headed) return renderLevel(section.levels[0], 0);
-          const all = section.levels.flatMap(levelRows);
-          const several = section.levels.length > 1;
-          const toggleSection = several && !readOnly ? (next) => {
-            const changes = [];
-            for (const level of section.levels) {
-              if (level.master) level.master.onToggle?.(next);
-              else changes.push(...bulkChanges(levelRows(level), next));
-            }
-            if (changes.length > 0) onSetInclude?.(changes);
-          } : void 0;
-          return /* @__PURE__ */ (0, import_jsx_runtime3.jsxs)("div", { role: "rowgroup", "aria-label": section.label, "data-section": section.label, children: [
-            heading({
-              id: `h:${section.id}`,
-              kind: "section",
-              label: section.label,
-              switchName: section.label,
-              depth: 0,
-              rows: all,
-              checked: section.levels.some((l) => l.master ? l.master.on : levelRows(l).some((r) => r.include)),
-              onToggle: toggleSection,
-              noSwitch: !several
-            }),
-            section.levels.map((level) => renderLevel(level, 1))
-          ] }, section.id);
-        })
+        levels.length === 0 ? /* @__PURE__ */ (0, import_jsx_runtime3.jsx)("div", { className: "px-2 py-3 text-center text-muted-foreground", children: "None" }) : headed ? buildContextTree(levels).map((node) => renderNode(node, 0)) : levels.map((level) => /* @__PURE__ */ (0, import_jsx_runtime3.jsx)("div", { role: "rowgroup", "data-level": level.ref.id, children: renderLevelBody(level, 0, level.ref.path[level.ref.path.length - 1] ?? "") }, level.ref.id))
       ]
     }
   ) });

package/dist/context/react/index.d.cts

@@ -238,6 +238,31 @@ declare const PAGE_LEVEL: ContextLevelRef;
 declare function placeByOrigin(row: ResolvedContextRow): ContextRowPlace;
 /** Rows → levels → groups, in the host's order (stable within equal orders). */
 declare function buildContextLevels(rows: readonly ResolvedContextRow[], hierarchy?: ContextHierarchy | null): ContextLevelNode[];
+/**
+ * A heading of the table: one label of a level's path. A node with a `level`
+ * IS that level (its rows, groups, switch); a node without one is a section
+ * that only names the labels above deeper levels.
+ */
+interface ContextTreeNode {
+    /** The path up to and including this label, lower-cased: one node per distinct path. */
+    id: string;
+    /** This node's own label (the last one of its path). */
+    label: string;
+    /** The full heading path to this node, root first. */
+    path: readonly string[];
+    level: ContextLevelNode | null;
+    children: ContextTreeNode[];
+}
+/**
+ * Levels → ONE tree by path (Arman, 2026-10-21: "UNIFY and eliminate" — one
+ * AI Matrx root, whatever the levels' paths): `["AI Matrx"]`,
+ * `["AI Matrx", "Marketing"]` and `["AI Matrx", "Marketing", "Brands"]` nest as
+ * AI Matrx → Marketing → Brands; a root named by two levels is still one root.
+ * Order: a node sorts by the lowest `order` found in it or below it.
+ */
+declare function buildContextTree(levels: readonly ContextLevelNode[]): ContextTreeNode[];
+/** Every level at or below a node. */
+declare function treeLevels(node: ContextTreeNode): ContextLevelNode[];
 /** Every row of a level, groups included. */
 declare function levelRows(level: ContextLevelNode): ResolvedContextRow[];
 /** What the row's include would be with no rule of the person's. */
@@ -455,4 +480,4 @@ declare function ContextReceiptBlockDetail({ block, load, className, }: {
     className?: string;
 }): React.JSX.Element;
 
-export { AI_MATRX_LEVEL, ATTACHED_LEVEL, ContextDeliveredValue, type ContextGroupNode, type ContextGroupRef, type ContextHierarchy, type ContextLevelMaster, type ContextLevelNode, type ContextLevelRef, ContextReceiptBlockDetail, ContextReceiptBlocks, type ContextReceiptBlocksProps, type ContextRowPlace, type ContextRuleChange, ContextRulesChip, type ContextRulesChipProps, type ContextRulesDensity, ContextRulesPanelBody, type ContextRulesPanelBodyProps, ContextRulesTable, type ContextRulesTableProps, DeliveredSection, InlineMaxInput, type InlineMaxInputProps, PAGE_LEVEL, buildContextLevels, includeChanges, inheritedInclude, levelRows, placeByOrigin, summarizeContextRows };
+export { AI_MATRX_LEVEL, ATTACHED_LEVEL, ContextDeliveredValue, type ContextGroupNode, type ContextGroupRef, type ContextHierarchy, type ContextLevelMaster, type ContextLevelNode, type ContextLevelRef, ContextReceiptBlockDetail, ContextReceiptBlocks, type ContextReceiptBlocksProps, type ContextRowPlace, type ContextRuleChange, ContextRulesChip, type ContextRulesChipProps, type ContextRulesDensity, ContextRulesPanelBody, type ContextRulesPanelBodyProps, ContextRulesTable, type ContextRulesTableProps, type ContextTreeNode, DeliveredSection, InlineMaxInput, type InlineMaxInputProps, PAGE_LEVEL, buildContextLevels, buildContextTree, includeChanges, inheritedInclude, levelRows, placeByOrigin, summarizeContextRows, treeLevels };

package/dist/context/react/index.d.ts

@@ -238,6 +238,31 @@ declare const PAGE_LEVEL: ContextLevelRef;
 declare function placeByOrigin(row: ResolvedContextRow): ContextRowPlace;
 /** Rows → levels → groups, in the host's order (stable within equal orders). */
 declare function buildContextLevels(rows: readonly ResolvedContextRow[], hierarchy?: ContextHierarchy | null): ContextLevelNode[];
+/**
+ * A heading of the table: one label of a level's path. A node with a `level`
+ * IS that level (its rows, groups, switch); a node without one is a section
+ * that only names the labels above deeper levels.
+ */
+interface ContextTreeNode {
+    /** The path up to and including this label, lower-cased: one node per distinct path. */
+    id: string;
+    /** This node's own label (the last one of its path). */
+    label: string;
+    /** The full heading path to this node, root first. */
+    path: readonly string[];
+    level: ContextLevelNode | null;
+    children: ContextTreeNode[];
+}
+/**
+ * Levels → ONE tree by path (Arman, 2026-10-21: "UNIFY and eliminate" — one
+ * AI Matrx root, whatever the levels' paths): `["AI Matrx"]`,
+ * `["AI Matrx", "Marketing"]` and `["AI Matrx", "Marketing", "Brands"]` nest as
+ * AI Matrx → Marketing → Brands; a root named by two levels is still one root.
+ * Order: a node sorts by the lowest `order` found in it or below it.
+ */
+declare function buildContextTree(levels: readonly ContextLevelNode[]): ContextTreeNode[];
+/** Every level at or below a node. */
+declare function treeLevels(node: ContextTreeNode): ContextLevelNode[];
 /** Every row of a level, groups included. */
 declare function levelRows(level: ContextLevelNode): ResolvedContextRow[];
 /** What the row's include would be with no rule of the person's. */
@@ -455,4 +480,4 @@ declare function ContextReceiptBlockDetail({ block, load, className, }: {
     className?: string;
 }): React.JSX.Element;
 
-export { AI_MATRX_LEVEL, ATTACHED_LEVEL, ContextDeliveredValue, type ContextGroupNode, type ContextGroupRef, type ContextHierarchy, type ContextLevelMaster, type ContextLevelNode, type ContextLevelRef, ContextReceiptBlockDetail, ContextReceiptBlocks, type ContextReceiptBlocksProps, type ContextRowPlace, type ContextRuleChange, ContextRulesChip, type ContextRulesChipProps, type ContextRulesDensity, ContextRulesPanelBody, type ContextRulesPanelBodyProps, ContextRulesTable, type ContextRulesTableProps, DeliveredSection, InlineMaxInput, type InlineMaxInputProps, PAGE_LEVEL, buildContextLevels, includeChanges, inheritedInclude, levelRows, placeByOrigin, summarizeContextRows };
+export { AI_MATRX_LEVEL, ATTACHED_LEVEL, ContextDeliveredValue, type ContextGroupNode, type ContextGroupRef, type ContextHierarchy, type ContextLevelMaster, type ContextLevelNode, type ContextLevelRef, ContextReceiptBlockDetail, ContextReceiptBlocks, type ContextReceiptBlocksProps, type ContextRowPlace, type ContextRuleChange, ContextRulesChip, type ContextRulesChipProps, type ContextRulesDensity, ContextRulesPanelBody, type ContextRulesPanelBodyProps, ContextRulesTable, type ContextRulesTableProps, type ContextTreeNode, DeliveredSection, InlineMaxInput, type InlineMaxInputProps, PAGE_LEVEL, buildContextLevels, buildContextTree, includeChanges, inheritedInclude, levelRows, placeByOrigin, summarizeContextRows, treeLevels };

package/dist/context/react/index.js

@@ -167,6 +167,41 @@ function buildContextLevels(rows, hierarchy) {
   for (const level of out) level.groups = stableSort(level.groups, (g) => g.ref);
   return stableSort(out, (level) => level.ref);
 }
+function buildContextTree(levels) {
+  const roots = [];
+  const byId = /* @__PURE__ */ new Map();
+  const rank = /* @__PURE__ */ new Map();
+  for (const level of levels) {
+    const labels = level.ref.path.length > 0 ? level.ref.path : [""];
+    let siblings = roots;
+    let last = null;
+    const ids = [];
+    for (let i = 0; i < labels.length; i++) {
+      ids.push(labels[i].trim().toLowerCase());
+      const id = ids.join("
");
+      let hit = byId.get(id);
+      if (!hit) {
+        hit = { id, label: labels[i], path: labels.slice(0, i + 1), level: null, children: [] };
+        byId.set(id, hit);
+        siblings.push(hit);
+      }
+      const order = level.ref.order ?? 0;
+      rank.set(hit, Math.min(rank.get(hit) ?? order, order));
+      last = hit;
+      siblings = hit.children;
+    }
+    if (last) last.level = level;
+  }
+  const sort = (list) => {
+    const sorted = stableSort(list, (n) => ({ order: rank.get(n) ?? 0 }));
+    for (const n of sorted) n.children = sort(n.children);
+    return sorted;
+  };
+  return sort(roots);
+}
+function treeLevels(node) {
+  return [...node.level ? [node.level] : [], ...node.children.flatMap(treeLevels)];
+}
 function levelRows(level) {
   return [...level.rows, ...level.groups.flatMap((g) => g.rows)];
 }
@@ -403,7 +438,7 @@ function summarizeContextRows(rows) {
 }
 
 // context/react/ContextRulesTable.tsx
-import { jsx as jsx3, jsxs as jsxs3 } from "react/jsx-runtime";
+import { Fragment, jsx as jsx3, jsxs as jsxs3 } from "react/jsx-runtime";
 var CONTEXT_RULES_GRID = {
   compact: "grid grid-cols-[minmax(0,1fr)_2.75rem_4rem_6.5rem] items-center gap-x-2 px-2",
   comfortable: "grid grid-cols-[minmax(0,1fr)_2.75rem_3.5rem_6.75rem] items-center gap-x-1.5 px-3"
@@ -433,16 +468,6 @@ function useNarrow(ref) {
 }
 var INDENT = ["", "pl-2", "pl-4", "pl-6"];
 var indent = (depth) => INDENT[Math.min(depth, INDENT.length - 1)];
-function sectionsOf(levels) {
-  const out = [];
-  for (const level of levels) {
-    const label = level.ref.path.length > 1 ? level.ref.path[0] : null;
-    const last = out[out.length - 1];
-    if (label !== null && last && last.label === label) last.levels.push(level);
-    else out.push({ id: label === null ? `level:${level.ref.id}` : `section:${label}`, label, levels: [level] });
-  }
-  return out;
-}
 function ContextRulesTable({
   rows,
   cap,
@@ -487,14 +512,13 @@ function ContextRulesTable({
     rowId(row)
   );
   const heading = (props) => /* @__PURE__ */ jsx3(Heading, { ...props, grid, narrow, comfortable, readOnly }, props.id);
-  const renderLevel = (level, depth) => {
+  const renderLevelBody = (level, depth, label) => {
     const all = levelRows(level);
-    const name = level.ref.path[level.ref.path.length - 1] ?? "";
-    return /* @__PURE__ */ jsxs3("div", { role: "rowgroup", "aria-label": headed ? level.ref.path.join(" \u203A ") : void 0, "data-level": level.ref.id, children: [
+    return /* @__PURE__ */ jsxs3(Fragment, { children: [
       headed ? heading({
         id: `h:${level.ref.id}`,
         kind: "level",
-        label: name,
+        label,
         switchName: level.ref.path.join(" \u203A "),
         depth,
         rows: all,
@@ -514,7 +538,51 @@ function ContextRulesTable({
         }),
         group.rows.map((row) => renderRow(row, depth + 2))
       ] }, group.ref.id))
-    ] }, level.ref.id);
+    ] });
+  };
+  const renderNode = (node, depth) => {
+    const { level } = node;
+    const below = node.children.map((child) => renderNode(child, depth + 1));
+    if (level) {
+      return /* @__PURE__ */ jsxs3(
+        "div",
+        {
+          role: "rowgroup",
+          "aria-label": headed ? level.ref.path.join(" \u203A ") : void 0,
+          "data-level": level.ref.id,
+          children: [
+            renderLevelBody(level, depth, node.label),
+            below
+          ]
+        },
+        level.ref.id
+      );
+    }
+    const covered = treeLevels(node);
+    const all = covered.flatMap(levelRows);
+    const several = covered.length > 1;
+    const toggleSection = several && !readOnly ? (next) => {
+      const changes = [];
+      for (const lv of covered) {
+        if (lv.master) lv.master.onToggle?.(next);
+        else changes.push(...bulkChanges(levelRows(lv), next));
+      }
+      if (changes.length > 0) onSetInclude?.(changes);
+    } : void 0;
+    return /* @__PURE__ */ jsxs3("div", { role: "rowgroup", "aria-label": node.label, "data-section": node.label, children: [
+      heading({
+        id: `h:section:${node.id}`,
+        kind: "section",
+        label: node.label,
+        switchName: node.path.join(" \u203A "),
+        depth,
+        rows: all,
+        checked: covered.some((l) => l.master ? l.master.on : levelRows(l).some((r) => r.include)),
+        onToggle: toggleSection,
+        noSwitch: !several
+      }),
+      below
+    ] }, `section:${node.id}`);
   };
   return /* @__PURE__ */ jsx3(TooltipProvider2, { delayDuration: 300, titleTooltips: false, children: /* @__PURE__ */ jsxs3(
     "div",
@@ -539,33 +607,7 @@ function ContextRulesTable({
             ]
           }
         ),
-        levels.length === 0 ? /* @__PURE__ */ jsx3("div", { className: "px-2 py-3 text-center text-muted-foreground", children: "None" }) : sectionsOf(levels).map((section) => {
-          if (section.label === null || !headed) return renderLevel(section.levels[0], 0);
-          const all = section.levels.flatMap(levelRows);
-          const several = section.levels.length > 1;
-          const toggleSection = several && !readOnly ? (next) => {
-            const changes = [];
-            for (const level of section.levels) {
-              if (level.master) level.master.onToggle?.(next);
-              else changes.push(...bulkChanges(levelRows(level), next));
-            }
-            if (changes.length > 0) onSetInclude?.(changes);
-          } : void 0;
-          return /* @__PURE__ */ jsxs3("div", { role: "rowgroup", "aria-label": section.label, "data-section": section.label, children: [
-            heading({
-              id: `h:${section.id}`,
-              kind: "section",
-              label: section.label,
-              switchName: section.label,
-              depth: 0,
-              rows: all,
-              checked: section.levels.some((l) => l.master ? l.master.on : levelRows(l).some((r) => r.include)),
-              onToggle: toggleSection,
-              noSwitch: !several
-            }),
-            section.levels.map((level) => renderLevel(level, 1))
-          ] }, section.id);
-        })
+        levels.length === 0 ? /* @__PURE__ */ jsx3("div", { className: "px-2 py-3 text-center text-muted-foreground", children: "None" }) : headed ? buildContextTree(levels).map((node) => renderNode(node, 0)) : levels.map((level) => /* @__PURE__ */ jsx3("div", { role: "rowgroup", "data-level": level.ref.id, children: renderLevelBody(level, 0, level.ref.path[level.ref.path.length - 1] ?? "") }, level.ref.id))
       ]
     }
   ) });
@@ -1438,9 +1480,11 @@ export {
   InlineMaxInput,
   PAGE_LEVEL,
   buildContextLevels,
+  buildContextTree,
   includeChanges,
   inheritedInclude,
   levelRows,
   placeByOrigin,
-  summarizeContextRows
+  summarizeContextRows,
+  treeLevels
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-matrx/agents",
-  "version": "0.59.260",
+  "version": "0.59.262",
   "description": "Portable AI Matrx agent stream protocol, event projection, and safe result-presentation primitives.",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -562,5 +562,5 @@
     "verify:tarball": "node ./scripts/verify-tarball.mjs",
     "typegen:self-test": "node scripts/typegen/drop-guard.self-test.mjs && node scripts/typegen/check-api-types-fresh.mjs --self-test"
   },
-  "gitHead": "9a4fd3053c05194032de663989ec2f851ab0db6c"
+  "gitHead": "de2b95873473d1fd1878b0e3b06ce75570190a1b"
 }