@design.estate/dees-catalog 9.8.0 → 11.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@design.estate/dees-catalog",
-  "version": "9.8.0",
+  "version": "11.0.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",
@@ -47,10 +47,10 @@
     "@design.estate/dees-wcctools": "^3.9.4",
     "@git.zone/tsbuild": "^4.4.3",
     "@git.zone/tsbundle": "^2.13.0",
-    "@git.zone/tstest": "^6.0.0",
+    "@git.zone/tstest": "^6.1.0",
     "@git.zone/tswatch": "^3.3.5",
     "@push.rocks/projectinfo": "^5.1.0",
-    "@types/node": "^26.4.1"
+    "@types/node": "^26.5.0"
   },
   "files": [
     "ts/**/*",
@@ -62,7 +62,6 @@
     "assets/**/*",
     "scripts/**/*",
     "cli.js",
-    ".smartconfig.json",
     "readme.md",
     "third-party-notices.md"
   ],

package/readme.md

@@ -229,7 +229,7 @@ task guide and examples deliberately; the generated table does not replace them.
 | `dees-storage-keys` | dataview | — | [Source](ts_web/elements/00group-dataview/dees-storage-browser/dees-storage-keys.ts) |
 | `dees-storage-preview` | dataview | — | [Source](ts_web/elements/00group-dataview/dees-storage-browser/dees-storage-preview.ts) |
 | `dees-table` | dataview | [DeesTable](#deestable) | [Source](ts_web/elements/00group-dataview/dees-table/dees-table.ts) |
-| `dees-terminal-view` | harness | — | [Source](ts_web/elements/00group-harness/dees-terminal-view/dees-terminal-view.ts) |
+| `dees-terminal-view` | harness | [DeesTerminalView](#deesterminalview) | [Source](ts_web/elements/00group-harness/dees-terminal-view/dees-terminal-view.ts) |
 | `dees-theme` | utility | [DeesTheme](#deestheme) | [Source](ts_web/elements/00group-utility/dees-theme/dees-theme.ts) |
 | `dees-thumbnail-audio` | media | [DeesThumbnailAudio](#deesthumbnailaudio) | [Source](ts_web/elements/00group-media/dees-thumbnail-audio/component.ts) |
 | `dees-thumbnail-folder` | media | [DeesThumbnailFolder](#deesthumbnailfolder) | [Source](ts_web/elements/00group-media/dees-thumbnail-folder/component.ts) |
@@ -257,6 +257,28 @@ task guide and examples deliberately; the generated table does not replace them.
 
 ## Component API
 
+### Failed actions
+
+Components that run an application callback — `dees-modal`'s `menuOptions[].action`
+and `dees-table`'s `dataActions[].actionFunc` — await it. A rejected callback is
+never dropped: the component dispatches the cancelable `dees-action-error` event
+(bubbling and composed) and, unless a listener cancels it, shows the error through
+`dees-toast`. Successful callbacks behave exactly as before and dispatch nothing.
+
+```typescript
+element.addEventListener('dees-action-error', (event: CustomEvent<IActionErrorDetail>) => {
+  const { error, action, source } = event.detail;
+  // source: 'modal-menu' | 'table-header' | 'table-footer' | 'table-row'
+  //       | 'table-rowmenu' | 'table-contextmenu' | 'table-doubleclick'
+  event.preventDefault();      // render your own error surface instead of the toast
+  reportToCrashService(error);
+});
+```
+
+`IActionErrorDetail`, `actionErrorEventName`, `actionErrorMessage`,
+`reportActionError` and `runAction` are exported from the package root, so a
+component outside the catalog can announce failures the same way.
+
 ### Core UI Components
 
 #### `DeesButton`
@@ -446,14 +468,21 @@ Consistent heading component with level and styling options.
 ```
 
 #### `DeesHint`
-Hint/tooltip component for providing contextual help.
+An inline advisory note next to the thing it explains. Use `text` for a plain
+sentence and the default slot for markup; both render when both are set. The
+`type` chooses the icon and the accent color. A hint with neither text nor
+slotted content renders nothing and reserves no space, so a conditional note
+needs no wrapper element.
 
 ```typescript
 <dees-hint
-  text="This field is required"
-  type="info"        // Options: info, warning, error, success
-  position="top"     // Options: top, bottom, left, right
+  text="Changing the URL breaks existing links."
+  type="info"        // Options: info, success, warning, error (default: info)
 ></dees-hint>
+
+<dees-hint type="warning">
+  Keys older than 90 days <strong>stop working</strong>.
+</dees-hint>
 ```
 
 #### `DeesPanel`
@@ -567,6 +596,7 @@ Text input field with validation, info tooltips, description text, and context m
 <dees-input-text
   key="email"           // Unique identifier for form data
   label="Email"         // Input label
+  type="email"          // Native input type: text (default), number, date, email, url, tel, password
   value="initial@value.com"  // Initial value
   required             // Makes the field required
   disabled            // Disables the input
@@ -585,6 +615,15 @@ Text input field with validation, info tooltips, description text, and context m
 ></dees-input-text>
 ```
 
+- `type` maps to the native input type and picks the matching keyboard hint; an
+  explicit `inputmode` on the element still wins. `value` is a string for every
+  type except `number`, where it is a `number`, or `null` while the field is
+  empty — so a form collects a number rather than a numeric string. A value bound
+  as the wrong shape is converted to the one the type promises.
+- `type="password"` masks the value. `isPasswordBool` masks it as well and adds
+  the reveal button that `showPasswordBool` toggles.
+- `validationFunction` always receives the value as text, whatever the type.
+
 > 💡 **All input components** share these common properties from `DeesInputBase`: `key`, `label`, `required`, `disabled`, `infoText`, `description`, `layoutMode`, `labelPosition`.
 
 #### `DeesInputTextarea`
@@ -1505,6 +1544,10 @@ appui.setBottomBarVisible(false);
 Content-panel navigation with native tab buttons, separate close controls and
 arrow/Home/End focus movement. Enter/Space select; Delete closes a closeable tab.
 `IMenuItem.key` remains the identity; optional `label` supplies display text.
+The selection follows that key, so a host that binds a literal `.tabs=${[...]}`
+keeps its open tab across rerenders: descriptors with the same key are adopted
+without re-running the tab's `action`. Only a key that is no longer present falls
+back to the first tab. Descriptors without a key fall back to their `label`.
 Use multitoggle for a view mode within the current panel.
 Both horizontal and vertical layouts use an inset selection surface.
 `showTabIndicator=false` hides that surface while retaining selected text and ARIA
@@ -1564,6 +1607,7 @@ html`<dees-table
 - Action `type` accepts `header`, `inRow`, `contextmenu`, `footer`, `doubleClick`, `preview`, and `keyCombination`. Use `actionRelevancyCheckFunc` for row-specific availability. Desktop rows show up to three relevant primary actions plus overflow; below 700px of table width, one Actions menu contains the row actions. Coarse pointers receive 44px targets independently of width. The opaque pinned column shows an edge shadow only while it covers scrolling columns.
 - `fixedHeight` uses internal scrolling with sticky headers and `--table-max-height`; the default uses a floating header while the page scrolls. `virtualized` limits rendered rows and retains spacer geometry.
 - Set a column's `editor` to `text`, `number`, `checkbox`, `dropdown`, `date`, or `tags`; `editable: true` defaults to text. Use `editorOptions`, `format`, `parse`, and `validate` for value handling. Double-click edits a cell; Enter/Tab commit and move, Escape cancels. `cellEdit` reports `{ row, key, oldValue, newValue }`; `cellEditError` reports validation failures.
+- Every `actionFunc` is awaited. A rejected action dispatches the cancelable `dees-action-error` event (see [Failed actions](#failed-actions)) instead of disappearing.
 - File drop onto rows and `highlightUpdates: 'flash'` remain available. Flashing respects reduced motion and stable row identity.
 
 #### `DeesDataviewCodebox`
@@ -2154,6 +2198,9 @@ runs before closing. Rejected operations leave the dialog open with their error,
 and repeated submission and dismissal are blocked while confirmation is pending.
 The modal emits `modal-close` when removed.
 
+Every `menuOptions` action is awaited. A rejected action keeps the dialog open and
+reports the failure through `dees-action-error` (see [Failed actions](#failed-actions)).
+
 The modal gallery includes a working settings draft: values survive navigation,
 Save returns the draft, and Cancel discards it. The example lives in
 `ts_web/elements/00group-overlay/dees-modal/dees-modal.demo.ts`.
@@ -2704,6 +2751,14 @@ Idle/busy/error line with animated dots and `aria-live="polite"`. Renders nothin
 
 Token usage chip (`in · out · total`, `compact` shows the total only); cache read/write detail in the tooltip.
 
+#### `DeesTerminalView`
+
+Transport-agnostic xterm.js surface. The host pipes remote PTY output in with `write(data)` and receives keystrokes as `terminal-input` (`{ data }`); there is no process, runtime or socket coupling. `terminal-resize` (`{ rows, cols }`) reports the grid after every refit so the host can negotiate a PTY size, and `currentSize` reads it back (`undefined` while no terminal is live). `fontSize` sets the grid font, `disabled` stops `terminal-input` from being emitted, and `focus()` focuses the grid. xterm is loaded through `DeesServiceLibLoader`; CSP-locked or offline hosts call `provideXtermModules()` first to supply their own bundled copy instead of the CDN.
+
+`write()` is safe before the terminal exists and while the element is detached: output is buffered and replayed in order on the next connection, bounded by the exported `maxPendingWriteBytes` (8 MiB — `Uint8Array` chunks count their `byteLength`, strings their UTF-16 memory). Past that bound the oldest chunks are dropped and the replay emits RIS first, so a truncated prefix is never rendered as if it were contiguous. `clear()` resets screen and scrollback through the write stream (RIS, `ESC c`) rather than around it, so it is ordered against output already queued in xterm — write, `clear()`, write leaves only the later output on screen.
+
+`ready` resolves once the terminal of the current connection is live; a fresh promise is created per connection, so a reattached element can be awaited again. Every connection builds a terminal and every disconnection disposes it, so an element moved between containers, or returned to, is a live surface rather than a dead one; buffered output survives the move. A failed xterm load is not an unhandled rejection: it dispatches the bubbling, composed `terminal-error` (`ITerminalErrorDetail { error }`), rejects `ready` with the same error, leaves the element writable, and is retried on the next connection. xterm's own flow-control refusal is reported the same way. Sizing comes from the host element — give it a bounded height, as the demo does.
+
 #### `DeesHarnessSessionSidebar`
 
 Generic session-detail panel that composes Tasks, Tools & Subagents, Tokens, Session Scratchpad, and Session Intelligence sections. Headings stay fixed in a single-open accordion; Session Intelligence splits its expanded body into independently scrolling history and a docked question composer. Set `.toolMessages` to top-level tool messages from the currently retained transcript window and `.toolRegistry` for matching labels/icons; active subagents use authoritative child status, and removed messages disappear without a second history cache. The host also supplies `IHarnessSessionMetrics`, `IHarnessScratchpad`, and `IHarnessIntelligenceExchange[]`; the component never loads or persists data itself. Context percentage and its progress bar render only when both `currentContextTokens` and a positive `maxContextTokens` are present.
@@ -2722,13 +2777,25 @@ Each card exposes an Actions button. Actions, right-click, and ContextMenu/Shift
 
 Attention and error rows retain a colored edge even when selected. Group headings count both states, including when collapsed. `working` controls the small activity pulse on normal/working rows, defaulting to `state === 'working'`; attention, error and finished indicators remain stationary. Reduced-motion preferences disable the pulse. State changes preserve row height, selection, expansion and host-provided order.
 
-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.
+**Sessions and resources are peers in one ordered list.** Every sortable row — conversation or resource — carries a focusable grip: drag it anywhere the other kind can go, including between sessions and into or out of groups, or reorder it with ArrowUp, ArrowDown, Home, and End. Pointer dragging moves a preview the size of the dragged row, opens a matching drop slot, and animates surrounding rows. Reordering does not require `enableGrouping`, which now only adds group chrome; an active search query renders one flat, non-sortable, recency-ordered section and cancels a drag in flight.
+
+Every move emits `harness-item-move` with `IHarnessItemMoveDetail`: `{ item, fromGroupId, toGroupId, beforeItem, source }`, where `item` and `beforeItem` are `IHarnessSessionListItemRef` values (`{ kind: 'session' | 'resource'; id }`) and a null `beforeItem` means append. Groups hold `itemIds: IHarnessSessionListItemRef[]`, and `ungroupedItemIds` controls the order outside groups; omitted or unknown entries of either kind fall back to `updatedAt ?? createdAt` recency. Set `draggable: false` on a session or a resource for pinned entries such as terminals; pinned entries sort first in the ungrouped section and stay outside the sortable order.
 
 The compact **New group** button sits beside search whenever `enableGrouping` is true, including while filtering, and emits `harness-group-create-request`. The host owns creation; the list keeps its current search until the host chooses to clear it. The demo clears search after adding the group. Both search and the group action use 44px targets for coarse pointers.
 
 The Sessions demo pairs the list with a selected-session workspace. Its controls step through starting, working, feedback, approval, completion and failure without timers or backend operations. Question and permission responses update the selected session; declining approval pauses it. The narrow layout switches between the preserved list and detail panes with an **All sessions** control that restores row focus.
 
-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.
+Generic host resources use the exported `IHarnessResourceMeta` and `IHarnessResourceAssociation` contracts. Set `.resources`, `.resourceAssociations`, `.selectedResourceId`, and `.eligibleTargetsByResourceId`. Resource rows render as top-level rows in the ordered list, never as children of a session. Resource metadata is presentation-only: the list never mounts a terminal, browser, file viewer, or other runtime.
+
+**Attaching is a separate explicit action, not a drop.** An association is an access grant: it shows as a decorative marker on the resource row (a link icon plus the target's title, resolved from `sessions` or `resources` regardless of search or collapse) and never moves the row. Dropping is purely positional and never attaches. The association stays single-valued — a resource has at most one target — and the target is any other item, so a resource may be attached to a session **or** to another resource such as a terminal:
+
+```typescript
+list.resourceAssociations = [
+  { resourceId: 'file:notes', target: { kind: 'resource', id: 'terminal:build' } },
+];
+```
+
+Association records are projected only when the resource exists, the target exists, the target is not the resource itself, and no earlier record claimed that resource. `eligibleTargetsByResourceId` restricts attach/reassign targets for host menus: a missing entry leaves the resource unrestricted, an empty array means no eligible target. Which resource kinds may host an attachment is the host's rule, not the component's.
 
 ```typescript
 import type {
@@ -2743,17 +2810,17 @@ list.resources = [
   { id: 'file:notes', kind: 'file', title: 'Release notes', preview: '6.7.0 draft' },
 ];
 list.resourceAssociations = [
-  { resourceId: 'shell:build', sessionId: 'session-1' },
+  { resourceId: 'shell:build', target: { kind: 'session', id: 'session-1' } },
 ];
-list.eligibleSessionIdsByResourceId = {
-  'shell:build': ['session-1', 'session-2'],
-  'file:notes': ['session-2'],
+list.eligibleTargetsByResourceId = {
+  'shell:build': [{ kind: 'session', id: 'session-1' }, { kind: 'session', id: 'session-2' }],
+  'file:notes': [{ kind: 'session', id: 'session-2' }, { kind: 'resource', id: 'shell:build' }],
 };
 
 list.addEventListener('harness-resource-association-request', async (event) => {
   const resourceEvent = event as CustomEvent<THarnessResourceAssociationRequestDetail>;
-  const { resource, toSessionId } = resourceEvent.detail;
-  await persistAssociation(resource.id, toSessionId);
+  const { resource, toTarget } = resourceEvent.detail;
+  await persistAssociation(resource.id, toTarget);
   list.resourceAssociations = await loadAssociations();
 });
 
@@ -2762,20 +2829,20 @@ list.addEventListener('harness-resource-context', (event) => {
   openHostMenu({
     x: resourceEvent.detail.clientX,
     y: resourceEvent.detail.clientY,
-    attach: (sessionId) => resourceEvent.detail.requestAssociation(sessionId),
+    attach: (target) => resourceEvent.detail.requestAssociation(target),
     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.
+`harness-resource-select` and `harness-resource-open` carry `{ resource, target }`, where `target` is the controlled association ref or null. `harness-resource-context` adds viewport coordinates, the pointer/Actions/keyboard source, the original event, `requestAssociation(toTarget)`, 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.
+All component-originated association request paths converge on the public `requestResourceAssociation(resourceId, toTarget, source?)` method. A valid change emits one bubbling/composed `harness-resource-association-request` discriminated by `intent: 'attach' | 'detach' | 'reassign'` and carrying `resource`, `fromTarget`, `toTarget`, and `source: 'action' | 'keyboard'`. The method returns `false` and emits nothing for unknown resources, unknown or ineligible targets, a target that is the resource itself, detach from an unattached resource, or the current target. It never mutates resources, associations, selection, groups, or 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.
+Association projection is deterministic and non-destructive: resource records without a non-empty ID, kind, or title, unknown resource/target references, self-targets, and later duplicate records for a resource are ignored; the first valid association wins. Duplicate resource metadata IDs likewise use the first resource. 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.
+Search covers resource ID, kind, title, and preview, and matches sessions and resources as peers — a matching session no longer reveals its attached resources, and a matching resource no longer reveals its target. Resources render with zero sessions. Resource dragging edge-scrolls the list exactly like session dragging and emits only `harness-item-move`. Use the Actions/context path for keyboard and mobile association workflows; coarse-pointer grip and Actions targets are at least 44px.
 
 ---
 
@@ -2949,9 +3016,19 @@ and selecting a kit with `dees-input-multitoggle`. Its Review bag action places
 The library exports unified interfaces for consistent API patterns:
 
 ```typescript
+// Detail of the cancelable `dees-action-error` event (see Failed actions)
+interface IActionErrorDetail<TAction = unknown> {
+  error: unknown;        // whatever the action callback rejected with
+  action: TAction;       // the action descriptor whose callback rejected
+  source: string;        // where it ran, e.g. 'modal-menu' or 'table-row'
+}
+
 // Base menu item interface (used by tabs, menus, etc.)
+// `key` is the stable identity: tab selection follows it across rerenders.
+// Give every tab a unique `key`: when it is absent the `label` is used, so two keyless tabs with the same label are the same tab.
 interface IMenuItem {
   key: string;
+  label?: string;        // display text; falls back to `key`
   iconName?: string;
   action: () => void;
   badge?: string | number;
@@ -3045,6 +3122,16 @@ module worker under the Apache License 2.0. The attribution and complete license
 provided in [third-party-notices.md](./third-party-notices.md) and copied into
 `dist_bundle/` for standalone bundle distributions.
 
+[third-party-notices.md](./third-party-notices.md) lists every library the package
+embeds in `dist_bundle/bundle.js` and every library it loads into the host page at
+runtime (ECharts, highlight.js, Lightweight Charts, Monaco, xterm). That list is
+generated from the built artifact and the installed packages — a dependency added,
+removed, or re-pinned without regenerating fails `pnpm test`:
+
+```sh
+node scripts/check-third-party-notices.mjs --write
+```
+
 ## License and Legal Information
 
 This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the [license](./license) file.

package/scripts/check-third-party-notices.mjs

@@ -0,0 +1,261 @@
+#!/usr/bin/env node
+/**
+ * Third-party notices for everything this package ships or loads.
+ *
+ * The embedded list is derived from dist_bundle itself: esbuild keeps a
+ * `// node_modules/...` comment per embedded module, so the set of embedded
+ * packages is read off the built artifact instead of a hand-kept list that
+ * silently rots when a dependency is added, removed, or made lazy. License
+ * metadata is read from the installed packages, never transcribed here.
+ *
+ * Usage:
+ *   node scripts/check-third-party-notices.mjs           # verify (also covered by tests)
+ *   node scripts/check-third-party-notices.mjs --write   # regenerate the managed section
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export const projectRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+export const noticesPath = path.join(projectRoot, 'third-party-notices.md');
+export const bundleDirectory = path.join(projectRoot, 'dist_bundle');
+export const startMarker = '<!-- bundled-notices:start -->';
+export const endMarker = '<!-- bundled-notices:end -->';
+
+/**
+ * Libraries the catalog does not embed but pins and loads into the host page at
+ * runtime (the CDN modules behind DeesServiceLibLoader and dees-workspace-monaco).
+ * Nothing in the built artifact carries their code, so they are named here; their
+ * license metadata still comes from the installed package where one exists.
+ * Mirrors ts_web/services/versions.ts.
+ */
+export const runtimeLoadedLibraries = [
+  { name: 'echarts' },
+  { name: 'highlight.js' },
+  { name: 'lightweight-charts' },
+  { name: 'monaco-editor' },
+  { name: 'xterm' },
+  { name: 'xterm-addon-fit' },
+  // Loaded by URL only; the catalog does not depend on it for types.
+  { name: 'xterm-addon-search', version: '0.13.0', license: 'MIT' },
+];
+
+const listJsFiles = (directoryArg) => {
+  const files = [];
+  for (const entry of fs.readdirSync(directoryArg, { withFileTypes: true })) {
+    const entryPath = path.join(directoryArg, entry.name);
+    if (entry.isDirectory()) files.push(...listJsFiles(entryPath));
+    else if (entry.name.endsWith('.js')) files.push(entryPath);
+  }
+  return files;
+};
+
+/** The package directory a bundled module path belongs to. */
+const packageDirectoryOf = (modulePathArg) => {
+  const marker = '/node_modules/';
+  const index = modulePathArg.lastIndexOf(marker);
+  if (index < 0) return null;
+  const rest = modulePathArg.slice(index + marker.length).split('/');
+  const name = rest[0].startsWith('@') ? `${rest[0]}/${rest[1]}` : rest[0];
+  if (!name || name.startsWith('.')) return null;
+  return modulePathArg.slice(0, index + marker.length) + name;
+};
+
+const readIfPresent = (directoryArg, matcherArg) => {
+  const entry = fs.readdirSync(directoryArg).find(matcherArg);
+  if (!entry) return null;
+  const text = fs.readFileSync(path.join(directoryArg, entry), 'utf8').replace(/\r\n/g, '\n').trim();
+  return text || null;
+};
+
+/** The license file that matches the elected license id, else the generic one. */
+const readLicenseText = (packageDirectoryArg, licenseIdArg) => {
+  const entries = fs.readdirSync(packageDirectoryArg);
+  const exact = entries.find((entry) => entry.toLowerCase() === `license.${licenseIdArg.toLowerCase()}`);
+  const generic = entries.find((entry) => /^(licen[cs]e|copying)(\.(md|txt))?$/i.test(entry));
+  const chosen = exact ?? generic;
+  if (!chosen) return null;
+  const text = fs.readFileSync(path.join(packageDirectoryArg, chosen), 'utf8').replace(/\r\n/g, '\n').trim();
+  // A stub that only points at a sibling file is not the license text.
+  return text.length < 200 ? null : text;
+};
+
+/**
+ * A copyright notice, not prose that happens to contain the word: license bodies
+ * wrap sentences onto lines starting with a lowercase "copyright", and the Apache
+ * appendix carries a bracketed placeholder.
+ */
+const isCopyrightLine = (lineArg) => /^\s*Copyright\b/.test(lineArg)
+  && !/\[yyyy\]|\[name of copyright owner\]/i.test(lineArg);
+
+const copyrightLinesOf = (...textsArg) => [...new Set(
+  textsArg.filter(Boolean).flatMap((text) => text.split('\n'))
+    .filter(isCopyrightLine)
+    .map((line) => line.replace(/^\s*[-*#>]*\s*/, '').trim())
+    .filter((line) => line.length > 4)
+)];
+
+/** A dual license is consumed under its first option; that election is recorded. */
+const electedLicense = (rawArg) => {
+  const raw = typeof rawArg === 'string' ? rawArg : rawArg?.type ?? 'UNKNOWN';
+  const options = raw.split(/\s+(?:or|OR)\s+|\//).map((option) => option.replace(/[()]/g, '').trim()).filter(Boolean);
+  return { elected: options[0] || 'UNKNOWN', raw, options };
+};
+
+const describePackage = (packageDirectoryArg, distributionArg) => {
+  const manifest = JSON.parse(fs.readFileSync(path.join(packageDirectoryArg, 'package.json'), 'utf8'));
+  const { elected, raw, options } = electedLicense(manifest.license ?? manifest.licenses?.[0]?.type);
+  const licenseText = readLicenseText(packageDirectoryArg, elected);
+  // Apache-2.0 section 4(d): a NOTICE file travels with the distribution.
+  const noticeText = readIfPresent(packageDirectoryArg, (entry) => /^notice(\.(md|txt))?$/i.test(entry));
+  return {
+    name: manifest.name,
+    version: manifest.version,
+    license: elected,
+    licenseRaw: raw,
+    dualLicensed: options.length > 1,
+    licenseText,
+    noticeText,
+    distribution: distributionArg,
+    copyrights: copyrightLinesOf(licenseText, noticeText),
+  };
+};
+
+const sortPackages = (entriesArg) => [...entriesArg].sort((a, b) =>
+  a.name.localeCompare(b.name, 'en') || a.version.localeCompare(b.version, 'en'));
+
+/** Every npm package whose code is embedded in the built bundle. */
+export const collectBundledPackages = () => {
+  if (!fs.existsSync(bundleDirectory)) {
+    throw new Error('dist_bundle is missing. Run pnpm build before checking third-party notices.');
+  }
+  const directories = new Set();
+  for (const file of listJsFiles(bundleDirectory)) {
+    const content = fs.readFileSync(file, 'utf8');
+    for (const match of content.matchAll(/^\/\/ (node_modules\/\S+)/gm)) {
+      const directory = packageDirectoryOf(match[1]);
+      if (directory) directories.add(directory);
+    }
+  }
+  const packages = new Map();
+  for (const directory of directories) {
+    const absolute = path.join(projectRoot, directory);
+    if (!fs.existsSync(path.join(absolute, 'package.json'))) {
+      throw new Error(`Bundled package without a manifest: ${directory}`);
+    }
+    const entry = describePackage(absolute, 'bundled');
+    packages.set(`${entry.name}@${entry.version}`, entry);
+  }
+  return sortPackages(packages.values());
+};
+
+/** The pinned libraries the catalog loads into the host page at runtime. */
+export const collectRuntimePackages = () => runtimeLoadedLibraries.map((library) => {
+  const directory = path.join(projectRoot, 'node_modules', library.name);
+  if (fs.existsSync(path.join(directory, 'package.json'))) {
+    return describePackage(directory, 'runtime');
+  }
+  if (!library.version || !library.license) {
+    throw new Error(`Runtime library ${library.name} is not installed and declares no version or license`);
+  }
+  return {
+    name: library.name, version: library.version, license: library.license, licenseRaw: library.license,
+    dualLicensed: false, licenseText: null, noticeText: null, distribution: 'runtime', copyrights: [],
+  };
+});
+
+export const collectPackages = () => [...collectBundledPackages(), ...collectRuntimePackages()];
+
+/**
+ * Identical license wording is printed once, with every copyright notice it
+ * covers. Two texts are the same terms when their operative part matches; the
+ * Apache appendix is instructions for applying the license, not a term, and
+ * packages ship it filled in, blank, or not at all. The longest text in a group
+ * is printed verbatim, so nothing is summarized away.
+ */
+const groupByLicenseText = (packagesArg) => {
+  const groups = new Map();
+  for (const entry of packagesArg) {
+    const normalized = (entry.licenseText ?? '')
+      .split('\n').filter((line) => !isCopyrightLine(line)).join('\n')
+      .replace(/\s+/g, ' ').trim();
+    const terminator = normalized.indexOf('END OF TERMS AND CONDITIONS');
+    const key = `${entry.license} ${terminator < 0 ? normalized : normalized.slice(0, terminator)}`;
+    if (!groups.has(key)) groups.set(key, { license: entry.license, text: entry.licenseText, packages: [] });
+    const group = groups.get(key);
+    group.packages.push(entry);
+    if ((entry.licenseText?.length ?? 0) > (group.text?.length ?? 0)) group.text = entry.licenseText;
+  }
+  return [...groups.values()].sort((a, b) =>
+    a.license.localeCompare(b.license, 'en') || a.packages[0].name.localeCompare(b.packages[0].name, 'en'));
+};
+
+const listEntry = (entryArg) => `- ${entryArg.name} ${entryArg.version} — `
+  + (entryArg.dualLicensed ? `${entryArg.licenseRaw}, used here under ${entryArg.license}` : entryArg.license);
+
+export const renderManagedSection = (packagesArg) => {
+  const bundled = packagesArg.filter((entry) => entry.distribution === 'bundled');
+  const runtime = packagesArg.filter((entry) => entry.distribution === 'runtime');
+  const lines = [startMarker, '', '## Third-party libraries', ''];
+  lines.push('This list is generated from the built artifact and the installed packages by');
+  lines.push('`scripts/check-third-party-notices.mjs`. License terms follow below, with identical');
+  lines.push('wording reproduced once and every copyright notice it covers listed with it.', '');
+  lines.push('### Embedded in the bundle', '');
+  lines.push('`dist_bundle/bundle.js` and its chunks contain the code of these packages.', '');
+  for (const entry of bundled) lines.push(listEntry(entry));
+  lines.push('', '### Loaded at runtime', '');
+  lines.push('These are not embedded. The catalog pins their versions and loads them into the host');
+  lines.push('page on demand, so their notices are reproduced here as well.', '');
+  for (const entry of runtime) lines.push(listEntry(entry));
+  lines.push('', '## License terms', '');
+  for (const group of groupByLicenseText(packagesArg)) {
+    const names = group.packages.map((entry) => `${entry.name} ${entry.version}`).join(', ');
+    const copyrights = [...new Set(group.packages.flatMap((entry) => entry.copyrights))].sort();
+    const notices = [...new Set(group.packages.filter((entry) => entry.noticeText).map((entry) => entry.noticeText))];
+    lines.push(`### ${group.license} — ${group.packages.length === 1 ? group.packages[0].name : `${group.packages.length} packages`}`, '');
+    lines.push(`Applies to: ${names}.`, '');
+    if (copyrights.length) {
+      lines.push('Copyright notices:', '');
+      for (const copyright of copyrights) lines.push(`- ${copyright}`);
+      lines.push('');
+    }
+    for (const notice of notices) lines.push('Attribution notice:', '', '```text', notice, '```', '');
+    if (group.text) {
+      // Verbatim, as published by the package: a license text is not ours to edit.
+      lines.push('```text', group.text, '```', '');
+    } else {
+      lines.push(`These packages publish no license file; they are distributed under ${group.license}.`, '');
+    }
+  }
+  lines.push(endMarker);
+  return lines.join('\n');
+};
+
+export const readNotices = () => fs.readFileSync(noticesPath, 'utf8');
+
+export const renderNotices = (currentArg, packagesArg) => {
+  const first = currentArg.indexOf(startMarker);
+  const last = currentArg.indexOf(endMarker);
+  if (first < 0 || last < first) {
+    throw new Error('third-party-notices.md is missing the bundled-notices markers');
+  }
+  return currentArg.slice(0, first) + renderManagedSection(packagesArg) + currentArg.slice(last + endMarker.length);
+};
+
+const isCli = process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (isCli) {
+  const packages = collectPackages();
+  const current = readNotices();
+  const generated = renderNotices(current, packages);
+  const counts = `${packages.filter((entry) => entry.distribution === 'bundled').length} bundled`
+    + ` and ${packages.filter((entry) => entry.distribution === 'runtime').length} runtime libraries`;
+  if (process.argv.includes('--write')) {
+    fs.writeFileSync(noticesPath, generated);
+    console.log(`[third-party-notices] wrote ${counts}`);
+  } else if (current !== generated) {
+    console.error('[third-party-notices] FAIL — the notices are stale. Run node scripts/check-third-party-notices.mjs --write');
+    process.exitCode = 1;
+  } else {
+    console.log(`[third-party-notices] OK — ${counts} listed`);
+  }
+}