@design.estate/dees-catalog 6.6.0 → 6.7.0

package/dist_ts_web/elements/00group-harness/interfaces.d.ts

@@ -280,6 +280,62 @@ export interface IHarnessSessionMeta {
     /** Set false for pinned, non-sortable entries such as terminals. Defaults to true. */
     draggable?: boolean;
 }
+/** Host-owned metadata for a resource that can be associated with a harness session. */
+export interface IHarnessResourceMeta<TState extends string = string> {
+    /** Stable identity used by selection and association records. */
+    id: string;
+    /** Open resource kind supplied by the host, for example `terminal`, `file`, or `browser`. */
+    kind: string;
+    title: string;
+    /** Optional dees-icon name (e.g. `lucide:FileText`). */
+    icon?: string;
+    preview?: string;
+    createdAt?: number;
+    updatedAt?: number;
+    /** Optional host-defined display state. */
+    state?: TState;
+}
+/** A controlled zero-or-one session association for one resource. */
+export interface IHarnessResourceAssociation {
+    resourceId: string;
+    sessionId: string;
+}
+export interface IHarnessResourceEventDetail<TState extends string = string> {
+    resource: IHarnessResourceMeta<TState>;
+    sessionId: string | null;
+}
+export type THarnessResourceAssociationInteractionSource = 'drop' | 'action' | 'keyboard';
+export type THarnessResourceAssociationRequestDetail<TState extends string = string> = {
+    intent: 'attach';
+    resource: IHarnessResourceMeta<TState>;
+    fromSessionId: null;
+    toSessionId: string;
+    source: THarnessResourceAssociationInteractionSource;
+} | {
+    intent: 'detach';
+    resource: IHarnessResourceMeta<TState>;
+    fromSessionId: string;
+    toSessionId: null;
+    source: THarnessResourceAssociationInteractionSource;
+} | {
+    intent: 'reassign';
+    resource: IHarnessResourceMeta<TState>;
+    fromSessionId: string;
+    toSessionId: string;
+    source: THarnessResourceAssociationInteractionSource;
+};
+export type THarnessResourceContextSource = 'pointer' | 'action' | 'keyboard';
+/** Detail of `harness-resource-context`; the host owns the actual menu. */
+export interface IHarnessResourceContextDetail<TState extends string = string> extends IHarnessResourceEventDetail<TState> {
+    clientX: number;
+    clientY: number;
+    source: THarnessResourceContextSource;
+    originalEvent: MouseEvent | KeyboardEvent;
+    /** Routes a host menu choice through the component's validated controlled request event. */
+    requestAssociation: (toSessionId: string | null) => boolean;
+    /** Closes the external-menu disclosure state and restores focus to its invoking control. */
+    close: () => void;
+}
 /** Detail of `harness-session-context`, fired on right-click of a session item. */
 export interface IHarnessSessionContextDetail {
     session: IHarnessSessionMeta;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@design.estate/dees-catalog",
-  "version": "6.6.0",
+  "version": "6.7.0",
   "private": false,
   "description": "A comprehensive library that provides dynamic web components for building sophisticated and modern web applications using JavaScript and TypeScript.",
   "main": "dist_ts_web/index.js",

package/readme.hints.md

@@ -5,6 +5,9 @@
 
 ## Agent Chat Architecture
 
+- `DeesHarnessSessionList` resource associations are controlled projections. Resources and associations remain host-owned; component-originated attach, detach, and reassign requests use `requestResourceAssociation()` and reconcile only when fresh `resourceAssociations` arrive.
+- Resource association normalization accepts the first valid record per known resource and ignores incomplete metadata, unknown references, or later duplicate records without mutating inputs. A missing `eligibleSessionIdsByResourceId` entry means no attach/reassign target; existing authoritative associations still render and can detach.
+- Resource pointer dragging is a separate gesture from session grip reordering. It targets an eligible whole session article, never creates a session drop slot, and never emits `harness-session-move`.
 - `DeesHarnessMessageList` owns transcript ordering and responsive tool grouping. Consecutive tools use one generic keyed-grid pipeline partitioned by descriptor layout: compact with compact, subtask with subtask, and full-row tools spanning every column. Never move cards between active and historical owners when status changes.
 - The transcript scroll box is the named inline-size container. Tool columns must respond to its content width so opening the session panel naturally reduces the column count.
 - Group identity is retained through front-window eviction while any card remains. Untouched projected subtasks collapse individually on completion without adding a second grid-level disclosure; other tools keep descriptor or user disclosure state.

package/readme.md

@@ -1912,6 +1912,55 @@ Searchable, card-based conversation column for sidebars or a `DeesModal` (`harne
 
 `IHarnessSessionMeta.state` accepts `normal`, `working`, `finished`, `attention`, or `error`; `working` remains an independent activity signal and does not change card expansion. With `enableGrouping`, sortable cards can move within and between groups. Drag from a card's focusable grip, or use its ArrowUp, ArrowDown, Home, and End keys. Pointer dragging moves a full-card preview, opens a matching drop slot, and animates surrounding cards; `harness-session-move` includes both the compatibility `index` and a stable optional `beforeSessionId` anchor. Set `draggable: false` for pinned entries such as terminals. Pass `ungroupedSessionIds` to control the order outside groups; omitted or unknown entries fall back to recency order.
 
+Generic host resources use the exported `IHarnessResourceMeta` and `IHarnessResourceAssociation` contracts. Set `.resources`, `.resourceAssociations`, `.selectedResourceId`, and `.eligibleSessionIdsByResourceId`. Unattached resources render in a labelled **Resources** list; attached resources render as compact persistent child rows inside their exact session article and stay visible while session details are collapsed. Resource metadata is presentation-only: the list never mounts a terminal, browser, file viewer, or other runtime.
+
+```typescript
+import type {
+  IHarnessResourceContextDetail,
+  THarnessResourceAssociationRequestDetail,
+} from '@design.estate/dees-catalog';
+
+const list = document.querySelector('dees-harness-session-list')!;
+
+list.resources = [
+  { id: 'shell:build', kind: 'terminal', title: 'Build shell', icon: 'lucide:Terminal' },
+  { id: 'file:notes', kind: 'file', title: 'Release notes', preview: '6.7.0 draft' },
+];
+list.resourceAssociations = [
+  { resourceId: 'shell:build', sessionId: 'session-1' },
+];
+list.eligibleSessionIdsByResourceId = {
+  'shell:build': ['session-1', 'session-2'],
+  'file:notes': ['session-2'],
+};
+
+list.addEventListener('harness-resource-association-request', async (event) => {
+  const resourceEvent = event as CustomEvent<THarnessResourceAssociationRequestDetail>;
+  const { resource, toSessionId } = resourceEvent.detail;
+  await persistAssociation(resource.id, toSessionId);
+  list.resourceAssociations = await loadAssociations();
+});
+
+list.addEventListener('harness-resource-context', (event) => {
+  const resourceEvent = event as CustomEvent<IHarnessResourceContextDetail>;
+  openHostMenu({
+    x: resourceEvent.detail.clientX,
+    y: resourceEvent.detail.clientY,
+    attach: (sessionId) => resourceEvent.detail.requestAssociation(sessionId),
+    detach: () => resourceEvent.detail.requestAssociation(null),
+    onClose: resourceEvent.detail.close,
+  });
+});
+```
+
+`harness-resource-select` and `harness-resource-open` carry `{ resource, sessionId }`. `harness-resource-context` adds viewport coordinates, the pointer/Actions/keyboard source, the original event, `requestAssociation(toSessionId)`, and `close()` for focus restoration. The visible Actions button has menu disclosure semantics; native `ContextMenu` and `Shift+F10` invoke the same host-owned path. The component does not require `DeesContextmenu` and does not own menu choices.
+
+All component-originated association request paths converge on the public `requestResourceAssociation(resourceId, toSessionId, source?)` method. A valid change emits one bubbling/composed `harness-resource-association-request` discriminated by `intent: 'attach' | 'detach' | 'reassign'` and carrying `resource`, `fromSessionId`, `toSessionId`, and `source: 'drop' | 'action' | 'keyboard'`. The method returns `false` and emits nothing for unknown resources/sessions, ineligible targets, detach from an unattached resource, or the current target. It never mutates resources, associations, selection, session groups, or session order.
+
+Association projection is deterministic and non-destructive: resource records without a non-empty ID, kind, or title, unknown resource/session references, and later duplicate records for a resource are ignored; the first valid association wins. Duplicate resource metadata IDs likewise use the first resource. Missing eligibility entries mean no eligible attach/reassign target. Eligibility does not hide an existing authoritative association, which remains visible and detachable. Requested changes are announced separately from completion; completion is announced only after the controlled association input reflects the requested target.
+
+Search covers resource ID, kind, title, and preview. A matching attached resource reveals its parent session and only matching children; a matching session reveals all its resources; matching unattached resources remain in **Resources**. Resources render with zero sessions. Resource grip dragging edge-scrolls the list and targets only eligible whole session cards, including hits on nested card content, while never creating session reorder placeholders or emitting `harness-session-move`. Use the Actions/context path for keyboard and mobile association workflows; coarse-pointer grip and Actions targets are at least 44px.
+
 ---
 
 ### Pre-built Templates

package/ts_web/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@design.estate/dees-catalog',
-  version: '6.6.0',
+  version: '6.7.0',
   description: 'A comprehensive library that provides dynamic web components for building sophisticated and modern web applications using JavaScript and TypeScript.'
 }

package/ts_web/elements/00group-harness/dees-harness-session-list/dees-harness-session-list.demo.ts

@@ -1,8 +1,13 @@
 import { html } from '@design.estate/dees-element';
 import type {
+  IHarnessResourceAssociation,
+  IHarnessResourceContextDetail,
+  IHarnessResourceEventDetail,
+  IHarnessResourceMeta,
   IHarnessSessionGroup,
   IHarnessSessionMeta,
   IHarnessSessionMoveDetail,
+  THarnessResourceAssociationRequestDetail,
 } from '../interfaces.js';
 
 const demoSessions: IHarnessSessionMeta[] = Array.from({ length: 24 }, (_, index) => ({
@@ -28,8 +33,48 @@ const demoGroups: IHarnessSessionGroup[] = [
   { id: 'review', name: 'Review', sessionIds: ['session-3', 'session-4'] },
 ];
 
+const demoResources: IHarnessResourceMeta[] = [
+  {
+    id: 'terminal:build',
+    kind: 'terminal',
+    title: 'Build shell',
+    icon: 'lucide:Terminal',
+    preview: 'pnpm run build',
+    updatedAt: Date.now() - 90_000,
+    state: 'ready',
+  },
+  {
+    id: 'file:release-notes',
+    kind: 'file',
+    title: 'Release notes',
+    icon: 'lucide:FileText',
+    preview: '6.7.0 controlled resource draft',
+    updatedAt: Date.now() - 180_000,
+  },
+  {
+    id: 'browser:preview',
+    kind: 'browser',
+    title: 'Documentation preview',
+    icon: 'lucide:Globe',
+    preview: 'localhost:3000',
+    updatedAt: Date.now() - 240_000,
+  },
+];
+
+const demoResourceAssociations: IHarnessResourceAssociation[] = [
+  { resourceId: 'terminal:build', sessionId: 'session-0' },
+  { resourceId: 'file:release-notes', sessionId: 'session-0' },
+];
+
+const demoResourceEligibleSessionIds = Object.fromEntries(
+  demoResources.map((resource) => [resource.id, ['session-0', 'session-1', 'session-2']]),
+);
+
 type TDemoSessionList = HTMLElement & {
   groups: IHarnessSessionGroup[];
+  resources: IHarnessResourceMeta[];
+  resourceAssociations: IHarnessResourceAssociation[];
+  selectedResourceId: string;
   selectedSessionId: string;
   ungroupedSessionIds: string[];
 };
@@ -57,6 +102,72 @@ const handleSessionMove = (event: CustomEvent<IHarnessSessionMoveDetail>): void
   list.ungroupedSessionIds = ungroupedSessionIds;
 };
 
+const handleResourceAssociation = (
+  event: CustomEvent<THarnessResourceAssociationRequestDetail>,
+): void => {
+  const list = event.currentTarget as TDemoSessionList;
+  const next = list.resourceAssociations.filter(
+    (association) => association.resourceId !== event.detail.resource.id,
+  );
+  if (event.detail.toSessionId) {
+    next.push({
+      resourceId: event.detail.resource.id,
+      sessionId: event.detail.toSessionId,
+    });
+  }
+  list.resourceAssociations = next;
+};
+
+const handleResourceContext = async (
+  event: CustomEvent<IHarnessResourceContextDetail>,
+): Promise<void> => {
+  const list = event.currentTarget as TDemoSessionList;
+  const { DeesContextmenu } = await import('../../00group-overlay/dees-contextmenu/dees-contextmenu.js');
+  const currentSessionId = event.detail.sessionId;
+  const eligibleSessionIds = ['session-0', 'session-1', 'session-2'];
+  const menu = await DeesContextmenu.openContextMenuWithOptions(
+    new MouseEvent('contextmenu', {
+      clientX: event.detail.clientX,
+      clientY: event.detail.clientY,
+    }),
+    [
+      ...eligibleSessionIds
+        .filter((sessionId) => sessionId !== currentSessionId)
+        .map((sessionId) => ({
+          name: `${currentSessionId ? 'Reassign' : 'Attach'} to ${
+            demoSessions.find((session) => session.id === sessionId)?.title
+          }`,
+          iconName: 'lucide:Link',
+          action: async () => {
+            event.detail.requestAssociation(sessionId);
+            event.detail.close();
+          },
+        })),
+      ...(currentSessionId
+        ? [{
+            name: 'Detach',
+            iconName: 'lucide:Unlink',
+            action: async () => {
+              event.detail.requestAssociation(null);
+              event.detail.close();
+            },
+          }]
+        : []),
+    ],
+  );
+  if (!menu) {
+    event.detail.close();
+  } else {
+    const observer = new MutationObserver(() => {
+      if (menu.isConnected) return;
+      observer.disconnect();
+      event.detail.close();
+    });
+    observer.observe(document.body, { childList: true });
+  }
+  list.selectedResourceId = event.detail.resource.id;
+};
+
 const openModal = async () => {
   const { DeesModal } = await import('../../00group-overlay/dees-modal/dees-modal.js');
   const content = document.createElement('dees-harness-session-list');
@@ -95,15 +206,26 @@ export const demoFunc = () => html`
   </style>
   <div class="sessionDemo">
     <dees-button @clicked=${openModal}>Open in a DeesModal</dees-button>
-    <div class="demoHint">Drag the grip to reorder conversations or move them between groups.</div>
+    <div class="demoHint">
+      Use a conversation grip to reorder sessions. Use a resource grip to associate it with a
+      session, or open Actions with click, ContextMenu, or Shift+F10 for attach, reassign, and detach.
+    </div>
     <dees-harness-session-list
       .sessions=${demoSessions}
       .groups=${demoGroups}
       .ungroupedSessionIds=${demoSessions.slice(5).map((session) => session.id)}
+      .resources=${demoResources}
+      .resourceAssociations=${demoResourceAssociations}
+      .eligibleSessionIdsByResourceId=${demoResourceEligibleSessionIds}
       .enableGrouping=${true}
       selectedSessionId="session-2"
       @harness-session-select=${handleSessionSelect}
       @harness-session-move=${handleSessionMove}
+      @harness-resource-select=${(event: CustomEvent<IHarnessResourceEventDetail>) => {
+        (event.currentTarget as TDemoSessionList).selectedResourceId = event.detail.resource.id;
+      }}
+      @harness-resource-context=${handleResourceContext}
+      @harness-resource-association-request=${handleResourceAssociation}
     ></dees-harness-session-list>
   </div>
 `;