@ai-matrx/design-system 0.18.2 → 0.18.4

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## 0.18.4 — 2026-09-12
+
+Alchemy custom exports now preserve the exact captured filename through
+preparation and delivery, with safe basename validation; omitting a filename
+keeps the existing default behavior. Tables gain the shared responsive
+`TableTitleRow`, canonical toolbar tooltips, a mobile-safe append footer, and
+collision-free Select labels and chevrons.
+
+### Consumer action
+
+Update to 0.18.4. No host configuration changes are required.
+
+## 0.18.3 — 2026-09-12
+
+Reopening an Alchemy preparation now checks the current source while retaining
+manual drafts. Changed direct sources offer an explicit keep-or-regenerate
+choice, all-matching sources detect identity changes without eagerly fetching
+pages, and failed refreshes remain visible instead of silently reusing stale
+content.
+
+### Consumer action
+
+Update to 0.18.3. No host configuration changes are required.
+
 ## 0.18.2 — 2026-09-12
 
 Alchemy copy sessions now reset only when their explicit identity changes,

package/README.md

@@ -4,6 +4,28 @@ The small, semantic UI foundation shared by AI Matrx React applications — prim
 
 **Controls:** Button, Badge, Label, Separator, the Input family, the Textarea family, Checkbox, Switch, RadioGroup, Slider, Toggle + ToggleGroup, Avatar, Progress.
 **Content transfer:** `@ai-matrx/design-system/content-transfer` supplies Matrx Alchemy's inlined glyph, accessible menu, projected capture workspace, optional AI capability seam, and locally scoped `SurfaceHandle` provider. Its source is captured on user action; preparation keeps an immutable original, preserves manual and alternate-source sessions, fences stale async results, and routes every copy/download through `Transport`. Import `@ai-matrx/design-system/content-transfer.css` with the package structural sheets.
+
+```tsx
+<MatrxCopyMenu
+  label="Log"
+  export={{
+    items: [
+      {
+        id: "raw",
+        label: "Download raw log",
+        build: () => ({
+          content: rawText,
+          filename: "worker.log",
+          extension: "txt",
+          mime: "text/plain",
+        }),
+      },
+    ],
+  }}
+/>
+```
+
+An explicit filename is an exact safe basename captured with its bytes. Omit it to use the label-derived default; unsafe values fail the export visibly.
 **Surfaces:** Card, Table, Tabs, Accordion, Collapsible, ScrollArea, Popover, Tooltip, HoverCard, Sheet, Dialog, AlertDialog, Drawer, BottomSheet + TabbedBottomSheet, Alert, Resizable, Skeleton.
 **Menus:** DropdownMenu, ContextMenu, Command / CommandDialog, Select, CreatablePicker.
 **Composed:** EditableLabel, SegmentedControl, ArchiveFilter, ScoreRing, OverflowToolbar, ConfirmDialog + ConfirmDialogHost.

package/dist/content-transfer.cjs

@@ -649,6 +649,7 @@ var actionDone = (message) => ({
   mimeTypes: [],
   message
 });
+var isSafeFilename = (filename) => filename === filename.trim() && filename.length > 0 && !/^\.+$/.test(filename) && !/[\\/\x00-\x1F\x7F]/.test(filename);
 var sourceFor = (id, label, build) => ({
   id,
   label,
@@ -797,7 +798,8 @@ function MatrxCopyMenuSession(props) {
                 value: {
                   bytes: Array.from(bytes),
                   mime: file.mime,
-                  extension: file.extension
+                  extension: file.extension,
+                  ...file.filename !== void 0 ? { filename: file.filename } : {}
                 }
               };
             },
@@ -814,12 +816,16 @@ function MatrxCopyMenuSession(props) {
             (byte) => typeof byte !== "number" || !Number.isInteger(byte) || byte < 0 || byte > 255
           ))
             throw new Error(`${item.label} did not capture a valid file.`);
+          if (value.filename !== void 0 && (typeof value.filename !== "string" || !isSafeFilename(value.filename)))
+            throw new Error(
+              `${item.label} has an unsafe filename. Use a nonempty basename without leading or trailing whitespace, dots only, path separators, or control characters.`
+            );
           if (draft.omissions.some((omission) => omission.reason !== "duplicate"))
             throw new Error(
               "This custom file exceeds the configured export limits or contains excluded content. Use a standard format or revise the source options."
             );
           const bytes = new Uint8Array(value.bytes);
-          const filename = `${props.label.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "") || "export"}.${value.extension.replace(/[^a-zA-Z0-9.-]/g, "") || "bin"}`;
+          const filename = typeof value.filename === "string" ? value.filename : `${props.label.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "") || "export"}.${value.extension.replace(/[^a-zA-Z0-9.-]/g, "") || "bin"}`;
           return transport.download(
             (0, import_content_transfer.sealTransferArtifact)({
               snapshotId: snapshot.id,
@@ -1250,6 +1256,10 @@ function materialIdentity(material) {
   }
   return `payload:${id}`;
 }
+function snapshotContent(snapshot) {
+  const { sourceId, label, payload, coverage, unsavedChanges, omissions, sections, limits } = snapshot;
+  return JSON.stringify({ sourceId, label, payload, coverage, unsavedChanges, omissions, sections, limits });
+}
 function useFence() {
   const mounted = React8.useRef(true);
   const nextId = React8.useRef(0);
@@ -1352,7 +1362,7 @@ function ContentTransferMenuSession({ source, surface, label, projection, sectio
       const captured = await material.capture(signal);
       sourceMaterial = { id: captured.snapshot.sourceId, label: captured.snapshot.label, capture: async () => captured };
     } else if ("kind" in material) {
-      sourceMaterial = applyMenuProjection ? { id: "direct", label: sourceLabel, capture: async () => (0, import_content_transfer2.directSource)(material, { label: sourceLabel, ...projection ? { projection } : {}, ...sections ? { sections } : {} }) } : material;
+      sourceMaterial = { id: materialIdentity(material), label: sourceLabel, capture: async () => (0, import_content_transfer2.directSource)(material, { sourceId: materialIdentity(material), label: sourceLabel, ...applyMenuProjection && projection ? { projection } : {}, ...applyMenuProjection && sections ? { sections } : {} }) };
     } else if (applyMenuProjection && (projection || sections)) {
       sourceMaterial = {
         id: material.id,
@@ -1369,7 +1379,7 @@ function ContentTransferMenuSession({ source, surface, label, projection, sectio
     } else {
       sourceMaterial = material;
     }
-    const raw = "kind" in sourceMaterial ? (0, import_content_transfer2.directSource)(sourceMaterial) : await sourceMaterial.capture({ scope, signal });
+    const raw = await sourceMaterial.capture({ scope, signal });
     const constrained = (0, import_content_transfer2.resolveTransferPreferences)(providerPreferences, preferences, raw.snapshot.limits);
     const result = await (0, import_content_transfer2.capture)({ id: raw.snapshot.sourceId, label: raw.snapshot.label, capture: async () => ({ ...raw, snapshot: { ...raw.snapshot, limits: constrained.limits } }) }, signal, scope);
     if (scope !== "all-matching" || !collectPages) return result;
@@ -1429,31 +1439,117 @@ function ContentTransferMenuSession({ source, surface, label, projection, sectio
       fence.finish(controller);
     }
   }, [captureOne, capturePrimary, fence, formatSources, initialScope, preferences, providerPreferences, report, transport]);
-  const openWorkspace = React8.useCallback(async (key = primaryWorkspaceKey, variant) => {
-    const variantMaterial = variant && "kind" in variant.source ? { id: `variant:${key}`, label: variant.label, capture: async () => (0, import_content_transfer2.directSource)(variant.source, { label: variant.label }) } : variant?.source;
-    const captureWorkspace = variantMaterial ? (scope, signal) => captureOne(variantMaterial, scope, signal, true) : capturePrimary;
-    workspaceCaptures.current.set(key, captureWorkspace);
-    if (workspaces[key]) {
-      setWorkspaceKey(key);
-      setWorkspaceOpen(true);
-      return;
-    }
-    const { controller, id } = fence.begin();
-    try {
-      const result = await captureWorkspace(initialScope, controller.signal);
-      if (!fence.valid(id, controller)) return;
-      const resolved = (0, import_content_transfer2.resolveTransferPreferences)(providerPreferences, preferences, result.snapshot.limits);
-      const original = (0, import_content_transfer2.createDraft)(result.snapshot);
-      const base = { ...result, key, original, draft: original, scope: initialScope, preferences: resolved, ...result.collectionError ? { error: result.collectionError } : {} };
-      setWorkspaces((current) => ({ ...current, [key]: { ...base, draft: rebuild(base, initialControls(base)) } }));
-      setWorkspaceKey(key);
-      setWorkspaceOpen(true);
-    } catch (error) {
-      if (fence.valid(id, controller)) setNotice(errorMessage(error, "Could not capture content"));
-    } finally {
-      fence.finish(controller);
-    }
-  }, [captureOne, capturePrimary, fence, initialScope, preferences, primaryWorkspaceKey, providerPreferences, workspaces]);
+  const openWorkspace = React8.useCallback(
+    async (key = primaryWorkspaceKey, variant) => {
+      const variantMaterial = variant && "kind" in variant.source ? {
+        id: `variant:${key}`,
+        label: variant.label,
+        capture: async () => (0, import_content_transfer2.directSource)(variant.source, {
+          sourceId: `variant:${key}`,
+          label: variant.label
+        })
+      } : variant?.source;
+      const captureWorkspace = (scope, signal, collectPages = true) => captureOne(variantMaterial ?? primary, scope, signal, true, collectPages);
+      workspaceCaptures.current.set(key, captureWorkspace);
+      const existing = workspaces[key];
+      const { controller, id } = fence.begin();
+      if (existing) {
+        try {
+          const allMatching = existing.scope === "all-matching";
+          const fresh = await captureWorkspace(
+            existing.scope,
+            controller.signal,
+            !allMatching
+          );
+          if (!fence.valid(id, controller) || !workspaceCaptures.current.has(key))
+            return;
+          if (allMatching && (!existing.allMatching || !fresh.allMatching))
+            throw new Error(
+              "This source can no longer provide an all-matching snapshot."
+            );
+          const collectionIdentity = (value) => value && {
+            query: value.source.query,
+            projection: value.projection,
+            columns: value.columns,
+            limits: value.limits
+          };
+          const changed = allMatching ? JSON.stringify(collectionIdentity(existing.allMatching)) !== JSON.stringify(collectionIdentity(fresh.allMatching)) : snapshotContent(existing.snapshot) !== snapshotContent(fresh.snapshot);
+          setWorkspaces((current) => {
+            const retained = current[key];
+            if (!retained) return current;
+            return {
+              ...current,
+              [key]: {
+                ...retained,
+                error: fresh.collectionError,
+                ...allMatching ? { sourceStale: changed } : changed ? { pending: { ...fresh, scope: retained.scope } } : { pending: void 0 }
+              }
+            };
+          });
+          setWorkspaceKey(key);
+          setWorkspaceOpen(true);
+        } catch (error) {
+          if (fence.valid(id, controller) && workspaceCaptures.current.has(key)) {
+            setWorkspaces(
+              (current) => current[key] ? {
+                ...current,
+                [key]: {
+                  ...current[key],
+                  error: errorMessage(error, "Could not refresh source")
+                }
+              } : current
+            );
+            setWorkspaceKey(key);
+            setWorkspaceOpen(true);
+          }
+        } finally {
+          fence.finish(controller);
+        }
+        return;
+      }
+      try {
+        const result = await captureWorkspace(initialScope, controller.signal);
+        if (!fence.valid(id, controller)) return;
+        const resolved = (0, import_content_transfer2.resolveTransferPreferences)(
+          providerPreferences,
+          preferences,
+          result.snapshot.limits
+        );
+        const original = (0, import_content_transfer2.createDraft)(result.snapshot);
+        const base = {
+          ...result,
+          key,
+          original,
+          draft: original,
+          scope: initialScope,
+          preferences: resolved,
+          ...result.collectionError ? { error: result.collectionError } : {}
+        };
+        setWorkspaces((current) => ({
+          ...current,
+          [key]: { ...base, draft: rebuild(base, initialControls(base)) }
+        }));
+        setWorkspaceKey(key);
+        setWorkspaceOpen(true);
+      } catch (error) {
+        if (fence.valid(id, controller))
+          setNotice(errorMessage(error, "Could not capture content"));
+      } finally {
+        fence.finish(controller);
+      }
+    },
+    [
+      captureOne,
+      capturePrimary,
+      fence,
+      initialScope,
+      preferences,
+      primaryWorkspaceKey,
+      primary,
+      providerPreferences,
+      workspaces
+    ]
+  );
   React8.useImperativeHandle(controllerRef, () => ({
     focusTrigger: () => triggerRef.current?.focus(),
     prepare: async (requestedSource, options) => {
@@ -1676,7 +1772,7 @@ function PreparationWorkspace({ restoreFocus, open, state, scopes, onClose, onCh
     setBusy("capture");
     try {
       const result = await captureScope(scope, controller.signal);
-      if (fence.valid(id, controller) && latest.current.draft.revision === revision) onChange({ ...latest.current, pending: { ...result, scope }, error: result.collectionError });
+      if (fence.valid(id, controller) && latest.current.draft.revision === revision) onChange({ ...latest.current, pending: { ...result, scope }, sourceStale: false, error: result.collectionError });
     } catch (error) {
       if (fence.valid(id, controller)) onChange({ ...latest.current, error: errorMessage(error, "Refresh failed") });
     } finally {
@@ -1919,6 +2015,7 @@ function PreparationWorkspace({ restoreFocus, open, state, scopes, onClose, onCh
       /* @__PURE__ */ (0, import_jsx_runtime8.jsx)(Button, { type: "button", variant: "outline", onClick: () => setPendingControls(null), children: "Keep edited draft" }),
       /* @__PURE__ */ (0, import_jsx_runtime8.jsx)(Button, { type: "button", onClick: applyPendingControls, children: "Rebuild from source" })
     ] }) : null,
+    state.sourceStale ? /* @__PURE__ */ (0, import_jsx_runtime8.jsx)("p", { role: "alert", className: "matrx-alchemy-decision", children: "The source changed since this draft. Use Refresh source to review the latest data." }) : null,
     state.pending ? /* @__PURE__ */ (0, import_jsx_runtime8.jsxs)("div", { className: "matrx-alchemy-decision", role: "alert", children: [
       /* @__PURE__ */ (0, import_jsx_runtime8.jsx)("p", { children: "A fresh source snapshot is ready." }),
       /* @__PURE__ */ (0, import_jsx_runtime8.jsx)(Button, { type: "button", variant: "outline", onClick: () => resolveCapture("keep"), children: "Keep current snapshot and draft" }),