@jini-ai/ui 0.3.8 → 0.3.10

package/README.md

@@ -332,6 +332,12 @@ Real content has landed in several parallel passes — see
   See `packages/ui/source-map.md` for the consolidation evidence, a real
   infinite-render-loop bug found and fixed during this port, and full
   test/coverage numbers.
+- `src/features/folder-path-drop/` (2026-09-14) — dropping a folder onto a
+  host with native file access (e.g. an Electron preload exposing
+  `webUtils.getPathForFile` as a `FolderPathDropPort`) inserts the folder's
+  absolute path as text instead of uploading its contents. The
+  framework-free rules are also on `./core`; `useFolderPathDropCapture`
+  returns a stable `onDropCapture` handler. See `packages/ui/source-map.md`.
 - `src/utils/scroll-tabs-with-wheel.ts` and `src/utils/color-math.ts`
   (2026-07-18) — two flat bucket-A atoms from
   `ADS-memory/reports/jini-port/god-components-extraction-plan.md`'s Consolidation map §C:

package/dist/browser/useFileDropTarget.js

@@ -1,4 +1,4 @@
-import { useCallback, useRef, useState } from 'react';
+import { useCallback, useEffect, useRef, useState } from 'react';
 import { FILE_SYSTEM_READ_ERROR_MESSAGE, isFileSystemReadError } from '../utils/file-system-errors.js';
 import { filesFromDataTransfer } from '../utils/file-transfer.js';
 /**
@@ -21,6 +21,24 @@ export function useFileDropTarget(onUploadFiles) {
     const onUploadFilesRef = useRef(onUploadFiles);
     onUploadFilesRef.current = onUploadFiles;
     const clearDropReadError = useCallback(() => setDropReadError(null), []);
+    // This target's own `onDrop`/`onDragLeave` are not guaranteed to run when a drag ends: a host that
+    // handles a drop itself in the capture phase and stops propagation (a host's folder-drop-to-path) or a
+    // drag that ends elsewhere leaves the drag-over state stuck on. Window-capture listeners run before
+    // any element handler, so no `stopPropagation` can skip them. Registered only while dragging.
+    useEffect(() => {
+        if (!draggingFiles)
+            return undefined;
+        const reset = () => {
+            dragDepthRef.current = 0;
+            setDraggingFiles(false);
+        };
+        window.addEventListener('drop', reset, true);
+        window.addEventListener('dragend', reset, true);
+        return () => {
+            window.removeEventListener('drop', reset, true);
+            window.removeEventListener('dragend', reset, true);
+        };
+    }, [draggingFiles]);
     const onDragEnter = useCallback((event) => {
         event.preventDefault();
         dragDepthRef.current += 1;

package/dist/core.d.ts

@@ -24,6 +24,9 @@ export type { AgentMetaLabels } from './features/execution/rules.js';
 export type { ExecutionPort } from './features/execution/ports.js';
 export { createFakeExecutionPort } from './features/execution/dependencies.js';
 export type { FakeExecutionPortOptions } from './features/execution/dependencies.js';
+export type { FolderPathDropPort } from './features/folder-path-drop/ports.js';
+export type { CaptureFolderPathDropInput, FolderPathDropEvent, FolderPathDropInsertTarget, FolderPathDropInsertTargetRef, } from './features/folder-path-drop/types.js';
+export { captureFolderPathDrop, folderPathsFromDataTransfer, formatDroppedFolderPaths, } from './features/folder-path-drop/rules.js';
 export type { CodexInstallStatus, McpClientDescriptor, McpClientId, McpClientSnippet, McpInstallInfo, McpInstallPlatform, McpSnippetLanguage, McpStdioServerConfig, } from './features/integrations/types.js';
 export { DEFAULT_MCP_CLIENT_ID, DEFAULT_MCP_SERVER_NAME, MCP_CLIENTS } from './features/integrations/constants.js';
 export { buildClaudeCliSnippet, buildCodexEnvToml, buildCodexTomlSnippet, buildCursorDeeplink, buildMcpStdioServerConfig, buildSharedMcpJson, buildVsCodeSnippet, buildZedSnippet, commandPaletteShortcut, homeConfigPath, isMcpInstallPrerequisiteMissing, methodLabelForClient, settingsShortcut, snippetForClient, utf8Btoa, } from './features/integrations/rules.js';

package/dist/core.js

@@ -30,6 +30,7 @@ export * from './features/connectors/types.js';
 export { CUSTOM_MODEL_SENTINEL, CUSTOM_PRESET_ID, DEFAULT_AGENT_CLI_ENV_FIELDS, DEFAULT_AGENT_DESCRIPTIONS, DEFAULT_BASE_URL_BY_PROTOCOL, DEFAULT_PROVIDER_PRESETS, PROTOCOL_OPTIONS, } from './features/execution/constants.js';
 export { agentCliEnvValue, agentDiagnosticTooltip, agentExecutableRepairState, agentMetaLabel, agentModelSummary, binPathEnvField, cleanAgentVersionLabel, cliEnvFieldsForAgent, credentialsForPreset, customPreset, filterAgentModelOptions, groupPresets, isBaseUrlInvalid, isProviderConfigured, isValidApiBaseUrl, missingRequiredFields, nextConfigForAgentCliEnvChange, nextConfigForAgentModel, nextConfigForAgentReasoning, nextConfigForAgentSelect, nextConfigForModeChange, nextConfigForPresetSelect, nextConfigForProtocolSelect, parseMaxTokens, presetRequiresApiKey, presetsForProtocol, resolveSelectedPreset, selectedAgentModel, selectedAgentReasoning, shouldShowCustomModelInput, showsBaseUrlField, sortDetectedAgents, } from './features/execution/rules.js';
 export { createFakeExecutionPort } from './features/execution/dependencies.js';
+export { captureFolderPathDrop, folderPathsFromDataTransfer, formatDroppedFolderPaths, } from './features/folder-path-drop/rules.js';
 export { DEFAULT_MCP_CLIENT_ID, DEFAULT_MCP_SERVER_NAME, MCP_CLIENTS } from './features/integrations/constants.js';
 export { buildClaudeCliSnippet, buildCodexEnvToml, buildCodexTomlSnippet, buildCursorDeeplink, buildMcpStdioServerConfig, buildSharedMcpJson, buildVsCodeSnippet, buildZedSnippet, commandPaletteShortcut, homeConfigPath, isMcpInstallPrerequisiteMissing, methodLabelForClient, settingsShortcut, snippetForClient, utf8Btoa, } from './features/integrations/rules.js';
 export { createFakeMcpIntegrationsPort } from './features/integrations/dependencies.js';

package/dist/features/execution/constants.js

@@ -63,7 +63,7 @@ export const DEFAULT_PROVIDER_PRESETS = [
         title: 'Anthropic',
         protocol: 'anthropic',
         baseUrl: 'https://api.anthropic.com',
-        preferredModels: ['claude-sonnet-4-5', 'claude-opus-4-5', 'claude-haiku-4-5'],
+        preferredModels: ['claude-sonnet-5', 'claude-opus-5', 'claude-haiku-4-5'],
         kind: 'protocol',
         apiKeyPrefix: 'sk-ant-',
     },
@@ -72,7 +72,15 @@ export const DEFAULT_PROVIDER_PRESETS = [
         title: 'OpenAI',
         protocol: 'openai',
         baseUrl: 'https://api.openai.com/v1',
-        preferredModels: ['gpt-4o', 'gpt-4o-mini', 'o3', 'o4-mini'],
+        // `gpt-4o`/`gpt-4o-mini`/`o3`/`o4-mini` are stale: OpenAI's GPT-5.6 family
+        // (released 2026-07-09, per the API changelog) replaced the old
+        // flagship/mini/nano naming with named tiers — sol/terra/luna. `sol` is
+        // the one the changelog and pricing docs call out as "recommended for
+        // production API usage", so it leads (see `preferredModels[0]` default
+        // in `rules.ts`) rather than the newer, pricier `gpt-6-astra` flagship
+        // (released 2026-09-03) — picking that as the silent default would jump
+        // an existing user's cost without them choosing it.
+        preferredModels: ['gpt-5.6-sol', 'gpt-5.6-terra', 'gpt-5.6-luna'],
         kind: 'protocol',
         apiKeyPrefix: 'sk-',
     },
@@ -112,7 +120,7 @@ export const DEFAULT_PROVIDER_PRESETS = [
         title: 'OpenRouter',
         protocol: 'openai',
         baseUrl: 'https://openrouter.ai/api/v1',
-        preferredModels: ['anthropic/claude-3.7-sonnet', 'google/gemini-2.5-pro', 'openai/gpt-4o'],
+        preferredModels: ['anthropic/claude-sonnet-5', 'google/gemini-2.5-pro', 'openai/gpt-5.6-sol'],
         kind: 'gateway',
         // Longer than OpenAI's `sk-`, and deliberately so: `apiKeyFormatWarning` resolves a key to the
         // MOST specific prefix that claims it, so `sk-or-v1-…` is attributed here rather than to OpenAI.

package/dist/features/execution/react/components/ByokProviderForm.js

@@ -101,8 +101,8 @@ export function ByokProviderForm({ config, onConfigChange, preset, presets = DEF
             // child it grew the field and pushed the bottom-aligned button off the input's line every
             // time discovery failed. Same element, same `.jini-field-hint.is-error[role="status"]`
             // identity host suites locate it by — only its parent changed.
-            _jsx("span", { className: "jini-field-hint is-error", role: "status", children: t('Could not load live models: {message}', { message: modelDiscovery.message }) })) : null, canTestConnection && (connectionTest.status === 'ok' || connectionTest.status === 'error') ? (_jsx("div", { className: "jini-byok-test-row", children: _jsx("span", { className: `jini-byok-test-status is-${connectionTest.status}`, role: connectionTest.status === 'error' ? 'alert' : 'status', children: connectionTest.status === 'ok'
-                        ? (connectionTest.message ?? t('Connection succeeded'))
-                        : connectionTest.message }) })) : null, formFooter ? _jsx("div", { className: "jini-byok-form-footer", children: formFooter }) : null] }));
+            _jsx("span", { className: "jini-field-hint is-error", role: "status", children: t('Could not load live models: {message}', { message: t(modelDiscovery.message) }) })) : null, canTestConnection && (connectionTest.status === 'ok' || connectionTest.status === 'error') ? (_jsx("div", { className: "jini-byok-test-row", children: _jsx("span", { className: `jini-byok-test-status is-${connectionTest.status}`, role: connectionTest.status === 'error' ? 'alert' : 'status', children: connectionTest.status === 'ok'
+                        ? (connectionTest.message !== undefined ? t(connectionTest.message) : t('Connection succeeded'))
+                        : t(connectionTest.message) }) })) : null, formFooter ? _jsx("div", { className: "jini-byok-form-footer", children: formFooter }) : null] }));
 }
 //# sourceMappingURL=ByokProviderForm.js.map

package/dist/features/execution/react/components/ExecutionTab.d.ts

@@ -44,6 +44,24 @@ export interface ExecutionTabProps {
     formFooter?: ReactNode;
     apiKeyStoredExternally?: boolean;
     apiKeyPlaceholder?: string;
+    /**
+     * Whether the tab may run model discovery right now. Defaults to `true`.
+     *
+     * For a host that holds a key the browser cannot read and knows that key cannot be used at the
+     * selected endpoint, e.g. a key its backend saved for another provider and refuses to send anywhere
+     * else. With nothing typed, discovery then has nothing it may send, so the tab stays idle instead of
+     * showing that refusal.
+     *
+     * Read when discovery would run anyway (an endpoint change, a key typed or cleared, Test connection)
+     * and deliberately NOT a trigger of its own. A host flips it to `true` when its stored key is
+     * re-pointed at the selected endpoint, and probing on that flip alone would send the key there
+     * without the operator asking. Turning it `false` only resets discovery to idle and discards any
+     * response still in flight, which sends nothing.
+     */
+    canDiscoverModels?: boolean;
+    /** Pass-through to `useExecutionTab`'s `describeProbeError` — see that option's doc. Words a failed
+     *  model discovery and a failed Test connection. */
+    describeProbeError?: (error: unknown) => string;
     /**
      * This tab's own agent handle, published by the host. Every interactive control below — the mode
      * switch, every provider chip, the whole BYOK card, and every detected-CLI card — derives its own
@@ -64,5 +82,5 @@ export interface ExecutionTabProps {
  * wallet — balance polling, top-up, sign-in coachmarks — is deliberately not
  * ported; it is product-bound, not generic.
  */
-export declare function ExecutionTab({ config, onConfigChange, port, presets, cliEnvFields, localCliUnavailableReason, renderAgentIcon, localCliScopeLabel, autoDetect, ariaLabel, apiKeyFooter, formFooter, apiKeyStoredExternally, apiKeyPlaceholder, agentHandle, }: ExecutionTabProps): import("react").JSX.Element;
+export declare function ExecutionTab({ config, onConfigChange, port, presets, cliEnvFields, localCliUnavailableReason, renderAgentIcon, localCliScopeLabel, autoDetect, ariaLabel, apiKeyFooter, formFooter, apiKeyStoredExternally, apiKeyPlaceholder, canDiscoverModels, describeProbeError, agentHandle, }: ExecutionTabProps): import("react").JSX.Element;
 //# sourceMappingURL=ExecutionTab.d.ts.map

package/dist/features/execution/react/components/ExecutionTab.js

@@ -20,11 +20,12 @@ import { ProviderChipGroup } from './ProviderChipGroup.js';
  * wallet — balance polling, top-up, sign-in coachmarks — is deliberately not
  * ported; it is product-bound, not generic.
  */
-export function ExecutionTab({ config, onConfigChange, port, presets = DEFAULT_PROVIDER_PRESETS, cliEnvFields = DEFAULT_AGENT_CLI_ENV_FIELDS, localCliUnavailableReason, renderAgentIcon, localCliScopeLabel, autoDetect = true, ariaLabel, apiKeyFooter, formFooter, apiKeyStoredExternally, apiKeyPlaceholder, agentHandle, }) {
+export function ExecutionTab({ config, onConfigChange, port, presets = DEFAULT_PROVIDER_PRESETS, cliEnvFields = DEFAULT_AGENT_CLI_ENV_FIELDS, localCliUnavailableReason, renderAgentIcon, localCliScopeLabel, autoDetect = true, ariaLabel, apiKeyFooter, formFooter, apiKeyStoredExternally, apiKeyPlaceholder, canDiscoverModels = true, describeProbeError, agentHandle, }) {
     const t = useT();
-    const { agents, scan, connectionTest, modelDiscovery, agentTest, rescan, testConnection, testAgent, loadModels, canRescan, canTestAgent, } = useExecutionTab({
+    const { agents, scan, connectionTest, modelDiscovery, agentTest, rescan, testConnection, testAgent, loadModels, resetModelDiscovery, canRescan, canTestAgent, } = useExecutionTab({
         port,
         autoDetect: autoDetect && config.mode === 'local-cli',
+        ...(describeProbeError ? { describeProbeError } : {}),
     });
     const selectedPreset = resolveSelectedPreset(presets, config.byok);
     /**
@@ -52,12 +53,21 @@ export function ExecutionTab({ config, onConfigChange, port, presets = DEFAULT_P
     // `gemini-2.5-flash` even though `Test Key` — the one control that did force
     // a fresh attempt, see `ByokProviderForm`'s `onTestConnection` below —
     // returned 42 models.
+    //
+    // `canDiscoverModels` is read here but is deliberately not a dependency — see that prop's doc for why
+    // its turning `true` on its own must never probe.
     useEffect(() => {
-        if (config.mode !== 'byok' || typeof port.listModels !== 'function')
+        if (config.mode !== 'byok' || typeof port.listModels !== 'function' || !canDiscoverModels)
             return;
         loadModels(config.byok);
         // eslint-disable-next-line react-hooks/exhaustive-deps
     }, [config.mode, port, loadModels, config.byok.protocol, config.byok.baseUrl, config.byok.providerId, hasApiKey]);
+    // All a turn to "cannot discover" does: drop the current result and any response still in flight —
+    // e.g. one started before the host learned that its stored key belongs to another endpoint.
+    useEffect(() => {
+        if (!canDiscoverModels)
+            resetModelDiscovery();
+    }, [canDiscoverModels, resetModelDiscovery]);
     const { protocols, gateways } = groupPresets(presets);
     const configuredPresetIds = new Set(presets.filter((preset) => isProviderConfigured(config.byok, preset)).map((preset) => preset.id));
     const localCliDisabled = Boolean(localCliUnavailableReason);
@@ -89,7 +99,7 @@ export function ExecutionTab({ config, onConfigChange, port, presets = DEFAULT_P
                         // itself goes green with the same config.
                         onTestConnection: () => {
                             testConnection(config.byok);
-                            if (typeof port.listModels === 'function')
+                            if (canDiscoverModels && typeof port.listModels === 'function')
                                 loadModels(config.byok);
                         }, ...(apiKeyFooter !== undefined ? { apiKeyFooter } : {}), ...(formFooter !== undefined ? { formFooter } : {}), ...(apiKeyStoredExternally !== undefined ? { apiKeyStoredExternally } : {}), ...(apiKeyPlaceholder !== undefined ? { apiKeyPlaceholder } : {}) })] }))] }));
 }

package/dist/features/execution/react/hooks/useExecutionTab.d.ts

@@ -5,6 +5,18 @@ export interface UseExecutionTabOptions {
     /** Skips the mount-time detection call — useful when the host already has
      *  agents in hand, or when the tab is rendered but not visible. */
     autoDetect?: boolean;
+    /**
+     * Turns a rejected BYOK probe (`testConnection` or `listModels`) into the message the tab shows.
+     * Defaults to the error's own message.
+     *
+     * For a host whose backend refuses some probes in words written for API callers. The host knows its
+     * own error codes and the operator's locale; this package knows neither.
+     *
+     * Read through a ref when the probe settles, so it never becomes part of `testConnection`'s or
+     * `loadModels`'s identity. Hosts pass inline arrows, and `ExecutionTab`'s discovery effect depends on
+     * `loadModels`: an identity that followed this function would re-probe on every render.
+     */
+    describeProbeError?: (error: unknown) => string;
 }
 export interface UseExecutionTabResult {
     agents: readonly DetectedAgent[];
@@ -23,6 +35,9 @@ export interface UseExecutionTabResult {
     testConnection: (config: ByokConfig) => void;
     testAgent: (agentId: string, model?: string | undefined) => void;
     loadModels: (config: ByokConfig) => void;
+    /** Returns `modelDiscovery` to `idle` and discards any `loadModels` response still in flight. Sends
+     *  nothing. For a host that says discovery cannot run — see `ExecutionTab`'s `canDiscoverModels`. */
+    resetModelDiscovery: () => void;
     canRescan: boolean;
     canTestAgent: boolean;
 }
@@ -34,5 +49,5 @@ export interface UseExecutionTabResult {
  * Every async result is dropped if the hook unmounted first, so a slow probe
  * can't set state on a torn-down tree.
  */
-export declare function useExecutionTab({ port, autoDetect }: UseExecutionTabOptions): UseExecutionTabResult;
+export declare function useExecutionTab({ port, autoDetect, describeProbeError, }: UseExecutionTabOptions): UseExecutionTabResult;
 //# sourceMappingURL=useExecutionTab.d.ts.map

package/dist/features/execution/react/hooks/useExecutionTab.js

@@ -1,5 +1,9 @@
 import { useCallback, useEffect, useRef, useState } from 'react';
 import { sortDetectedAgents } from '../../rules.js';
+/** A rejected async edge's default message: the error's own text. */
+function describeErrorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
 /**
  * Owns the tab's async edges: local-agent detection, rescan, connection test,
  * and optional model discovery. Config state itself stays with the host — the
@@ -8,7 +12,7 @@ import { sortDetectedAgents } from '../../rules.js';
  * Every async result is dropped if the hook unmounted first, so a slow probe
  * can't set state on a torn-down tree.
  */
-export function useExecutionTab({ port, autoDetect = true }) {
+export function useExecutionTab({ port, autoDetect = true, describeProbeError = describeErrorMessage, }) {
     const [agents, setAgents] = useState([]);
     const [scan, setScan] = useState({ status: 'idle' });
     const [connectionTest, setConnectionTest] = useState({ status: 'idle' });
@@ -30,6 +34,9 @@ export function useExecutionTab({ port, autoDetect = true }) {
     const connectionTestTicket = useRef(0);
     const agentTestTicket = useRef(0);
     const modelDiscoveryTicket = useRef(0);
+    /** The host's describer as of the latest render — see `UseExecutionTabOptions.describeProbeError`. */
+    const describeProbeErrorRef = useRef(describeProbeError);
+    describeProbeErrorRef.current = describeProbeError;
     const alive = useRef(true);
     useEffect(() => {
         alive.current = true;
@@ -50,7 +57,7 @@ export function useExecutionTab({ port, autoDetect = true }) {
         }, (error) => {
             if (!isCurrent())
                 return;
-            setScan({ status: 'error', message: error instanceof Error ? error.message : String(error) });
+            setScan({ status: 'error', message: describeErrorMessage(error) });
         });
     }, []);
     useEffect(() => {
@@ -77,10 +84,7 @@ export function useExecutionTab({ port, autoDetect = true }) {
         }, (error) => {
             if (!isCurrent())
                 return;
-            setConnectionTest({
-                status: 'error',
-                message: error instanceof Error ? error.message : String(error),
-            });
+            setConnectionTest({ status: 'error', message: describeProbeErrorRef.current(error) });
         });
     }, [port]);
     const testAgent = useCallback((agentId, model) => {
@@ -108,11 +112,7 @@ export function useExecutionTab({ port, autoDetect = true }) {
         }, (error) => {
             if (!isCurrent())
                 return;
-            setAgentTest({
-                status: 'error',
-                agentId,
-                message: error instanceof Error ? error.message : String(error),
-            });
+            setAgentTest({ status: 'error', agentId, message: describeErrorMessage(error) });
         });
     }, [port]);
     const loadModels = useCallback((config) => {
@@ -135,12 +135,14 @@ export function useExecutionTab({ port, autoDetect = true }) {
             // actionable and must not read as "this provider has no models."
             if (!isCurrent())
                 return;
-            setModelDiscovery({
-                status: 'error',
-                message: error instanceof Error ? error.message : String(error),
-            });
+            setModelDiscovery({ status: 'error', message: describeProbeErrorRef.current(error) });
         });
     }, [port]);
+    const resetModelDiscovery = useCallback(() => {
+        // Taking a new ticket is what discards a response still in flight: its `isCurrent()` goes false.
+        ++modelDiscoveryTicket.current;
+        setModelDiscovery({ status: 'idle' });
+    }, []);
     return {
         agents,
         scan,
@@ -151,6 +153,7 @@ export function useExecutionTab({ port, autoDetect = true }) {
         testConnection,
         testAgent,
         loadModels,
+        resetModelDiscovery,
         canRescan: typeof port.rescanLocalAgents === 'function',
         canTestAgent: typeof port.testAgent === 'function',
     };

package/dist/features/folder-path-drop/index.d.ts

@@ -0,0 +1,6 @@
+export type { FolderPathDropPort } from './ports.js';
+export type { CaptureFolderPathDropInput, FolderPathDropEvent, FolderPathDropInsertTarget, FolderPathDropInsertTargetRef, } from './types.js';
+export { captureFolderPathDrop, folderPathsFromDataTransfer, formatDroppedFolderPaths } from './rules.js';
+export { useFolderPathDropCapture } from './react/hooks/useFolderPathDropCapture.js';
+export type { UseFolderPathDropCaptureOptions } from './react/hooks/useFolderPathDropCapture.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/features/folder-path-drop/index.js

@@ -0,0 +1,3 @@
+export { captureFolderPathDrop, folderPathsFromDataTransfer, formatDroppedFolderPaths } from './rules.js';
+export { useFolderPathDropCapture } from './react/hooks/useFolderPathDropCapture.js';
+//# sourceMappingURL=index.js.map

package/dist/features/folder-path-drop/ports.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The host-specific half of a folder-path drop: resolving a dropped `File` to its absolute OS path.
+ * Browsers never expose one (`File` has no path by design — see `utils/file-transfer.ts`'s header),
+ * so only a host with native file access can supply this, e.g. an Electron preload passing
+ * `webUtils.getPathForFile` through `contextBridge`. A page with no such host has no port at all,
+ * and every drop falls through to its ordinary file handling.
+ */
+export interface FolderPathDropPort {
+    /**
+     * Synchronous on purpose: the path must be read off the raw drop before any bubble-phase handler
+     * expands the folder into synthesized leaf files (see `rules.ts`'s header). Returns `''` for a
+     * `File` it cannot resolve — Electron's `webUtils.getPathForFile` contract.
+     */
+    getPathForFile(file: File): string;
+}
+//# sourceMappingURL=ports.d.ts.map

package/dist/features/folder-path-drop/ports.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=ports.js.map

package/dist/features/folder-path-drop/react/hooks/useFolderPathDropCapture.d.ts

@@ -0,0 +1,24 @@
+import type { DragEvent } from 'react';
+import type { FolderPathDropPort } from '../../ports.js';
+import type { FolderPathDropInsertTargetRef } from '../../types.js';
+export interface UseFolderPathDropCaptureOptions {
+    /** The host's path lookup; `null`/`undefined` leaves every drop alone. Read at drop time, latest render wins. */
+    readonly port: FolderPathDropPort | null | undefined;
+    /** The text target, e.g. the ref a chat pane populates with its composer handle. */
+    readonly composer: FolderPathDropInsertTargetRef;
+    /**
+     * Host follow-up for a swallowed folder drop, called after the text is inserted with every
+     * recovered path in drop order. Never called for a drop that passed through.
+     */
+    readonly onFolderPaths?: (paths: readonly string[]) => void;
+}
+/**
+ * A capture-phase drop handler (`onDropCapture`) that turns a folder drop into its path text via
+ * `captureFolderPathDrop`. The returned handler's identity never changes, whatever the caller passes
+ * each render, so a host that publishes it to another component (or lists it as an effect
+ * dependency) is not re-triggered by re-renders.
+ *
+ * @complexity Time: O(n) in the number of dragged items per drop; space: O(n).
+ */
+export declare function useFolderPathDropCapture({ port, composer, onFolderPaths, }: UseFolderPathDropCaptureOptions): (event: DragEvent<Element>) => void;
+//# sourceMappingURL=useFolderPathDropCapture.d.ts.map

package/dist/features/folder-path-drop/react/hooks/useFolderPathDropCapture.js

@@ -0,0 +1,18 @@
+import { useStableHandler } from '../../../../react/hooks/useStableHandler.js';
+import { captureFolderPathDrop } from '../../rules.js';
+/**
+ * A capture-phase drop handler (`onDropCapture`) that turns a folder drop into its path text via
+ * `captureFolderPathDrop`. The returned handler's identity never changes, whatever the caller passes
+ * each render, so a host that publishes it to another component (or lists it as an effect
+ * dependency) is not re-triggered by re-renders.
+ *
+ * @complexity Time: O(n) in the number of dragged items per drop; space: O(n).
+ */
+export function useFolderPathDropCapture({ port, composer, onFolderPaths, }) {
+    return useStableHandler((event) => {
+        const paths = captureFolderPathDrop({ event, port, composer });
+        if (paths.length > 0)
+            onFolderPaths?.(paths);
+    });
+}
+//# sourceMappingURL=useFolderPathDropCapture.js.map

package/dist/features/folder-path-drop/rules.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Pure logic for the folder-path-drop feature: recover the absolute OS path of every FOLDER in a raw
+ * drop and write those paths into a text target, instead of letting the drop upload the folder's
+ * contents. No React, no DOM globals — every DOM-shaped value arrives as a parameter.
+ *
+ * Why the read has to happen in the capture phase: a bubble-phase drop handler that expands folders
+ * (this package's `useFileDropTarget`, via `filesFromDataTransfer`) turns each dropped folder into
+ * synthesized per-leaf `File`s through the `FileSystemEntry` API. Those are not the `File`s
+ * `dataTransfer.files` handed the page, and a host lookup such as Electron's
+ * `webUtils.getPathForFile` resolves `''` for them. So the folder's own path is only recoverable
+ * synchronously, off the raw event, before that expansion runs.
+ *
+ * Consolidated from two identical host copies (a desktop chat pane and a web admin chat dock).
+ */
+import type { FolderPathDropPort } from './ports.js';
+import type { CaptureFolderPathDropInput } from './types.js';
+/**
+ * Recovers the absolute OS path of every FOLDER in a raw drop, in drop order.
+ *
+ * @param dataTransfer the raw `DragEvent.dataTransfer`, read before any folder expansion.
+ * @param port the host's path lookup. Called as a method, so a class-based port keeps its `this`.
+ * @returns every recovered folder path; `[]` when nothing dropped was a folder with a recoverable path.
+ * @complexity Time: O(n) in the number of dragged items; space: O(n).
+ */
+export declare function folderPathsFromDataTransfer(dataTransfer: DataTransfer, port: FolderPathDropPort): string[];
+/**
+ * The text a folder drop inserts: every path, space-joined, in drop order. The one place the format
+ * lives — a path that itself contains a space is ambiguous in this format, so any change to quoting
+ * or separators belongs here and nowhere else.
+ *
+ * @complexity Time/space: O(total path length).
+ */
+export declare function formatDroppedFolderPaths(paths: readonly string[]): string;
+/**
+ * A capture-phase drop handler's whole decision. A drop carrying at least one folder with a
+ * recoverable path is swallowed (`preventDefault` + `stopPropagation`, so no later handler uploads
+ * the folder's contents) and its paths are inserted as text. Any other drop — no port, no folder, or
+ * no recoverable path — is left untouched for the ordinary file handling.
+ *
+ * @returns the recovered paths when the drop was swallowed, `[]` when it passed through.
+ * @complexity Time: O(n) in the number of dragged items; space: O(n).
+ */
+export declare function captureFolderPathDrop({ event, port, composer }: CaptureFolderPathDropInput): string[];
+//# sourceMappingURL=rules.d.ts.map

package/dist/features/folder-path-drop/rules.js

@@ -0,0 +1,83 @@
+/**
+ * Pairs each `kind === 'file'` item with the `File` at the matching position in `files`.
+ *
+ * `.items` and `.files` are NOT index-aligned: `.items` also holds `kind === 'string'` entries (a
+ * macOS Finder drag commonly adds a `text/uri-list`/`text/plain` item beside a dropped folder),
+ * while `.files` holds only the file-kind ones, in the same relative order. A separate counter,
+ * advanced only for file-kind items, keeps the two aligned whatever else the drag carries.
+ */
+function pairFileItemsWithFiles(items, files) {
+    const pairs = [];
+    let fileIndex = 0;
+    for (const item of items) {
+        if (item.kind !== 'file')
+            continue;
+        const file = files[fileIndex];
+        fileIndex += 1;
+        if (file !== undefined)
+            pairs.push({ item, file });
+    }
+    return pairs;
+}
+/**
+ * A pair's folder path, or `undefined` when the item is not a directory or its path is unrecoverable.
+ * Chromium hands a dropped folder a file-kind item too; `webkitGetAsEntry().isDirectory` is what
+ * tells it apart from a loose file.
+ */
+function folderPathForItem(item, file, port) {
+    const entry = item.webkitGetAsEntry?.();
+    if (entry?.isDirectory !== true)
+        return undefined;
+    const path = port.getPathForFile(file);
+    return path === '' ? undefined : path;
+}
+/**
+ * Recovers the absolute OS path of every FOLDER in a raw drop, in drop order.
+ *
+ * @param dataTransfer the raw `DragEvent.dataTransfer`, read before any folder expansion.
+ * @param port the host's path lookup. Called as a method, so a class-based port keeps its `this`.
+ * @returns every recovered folder path; `[]` when nothing dropped was a folder with a recoverable path.
+ * @complexity Time: O(n) in the number of dragged items; space: O(n).
+ */
+export function folderPathsFromDataTransfer(dataTransfer, port) {
+    const items = Array.from(dataTransfer.items ?? []);
+    const files = Array.from(dataTransfer.files ?? []);
+    const paths = [];
+    for (const { item, file } of pairFileItemsWithFiles(items, files)) {
+        const path = folderPathForItem(item, file, port);
+        if (path !== undefined)
+            paths.push(path);
+    }
+    return paths;
+}
+/**
+ * The text a folder drop inserts: every path, space-joined, in drop order. The one place the format
+ * lives — a path that itself contains a space is ambiguous in this format, so any change to quoting
+ * or separators belongs here and nowhere else.
+ *
+ * @complexity Time/space: O(total path length).
+ */
+export function formatDroppedFolderPaths(paths) {
+    return paths.join(' ');
+}
+/**
+ * A capture-phase drop handler's whole decision. A drop carrying at least one folder with a
+ * recoverable path is swallowed (`preventDefault` + `stopPropagation`, so no later handler uploads
+ * the folder's contents) and its paths are inserted as text. Any other drop — no port, no folder, or
+ * no recoverable path — is left untouched for the ordinary file handling.
+ *
+ * @returns the recovered paths when the drop was swallowed, `[]` when it passed through.
+ * @complexity Time: O(n) in the number of dragged items; space: O(n).
+ */
+export function captureFolderPathDrop({ event, port, composer }) {
+    if (port === null || port === undefined)
+        return [];
+    const paths = folderPathsFromDataTransfer(event.dataTransfer, port);
+    if (paths.length === 0)
+        return [];
+    event.preventDefault();
+    event.stopPropagation();
+    composer.current?.insertText(formatDroppedFolderPaths(paths));
+    return paths;
+}
+//# sourceMappingURL=rules.js.map

package/dist/features/folder-path-drop/types.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Pure types for the folder-path-drop feature. No React, no DOM globals.
+ */
+import type { FolderPathDropPort } from './ports.js';
+/** Exactly what `captureFolderPathDrop` reads off a drop, so a React `DragEvent` and a plain object both fit. */
+export interface FolderPathDropEvent {
+    readonly dataTransfer: DataTransfer;
+    preventDefault(): void;
+    stopPropagation(): void;
+}
+/** Where recovered paths go as text. `@jini-ai/chat`'s `ChatPaneComposerHandle` fits structurally. */
+export interface FolderPathDropInsertTarget {
+    insertText(text: string): void;
+}
+/** A React `RefObject`-shaped handle to the insert target, without importing React. `null` before it mounts. */
+export interface FolderPathDropInsertTargetRef {
+    readonly current: FolderPathDropInsertTarget | null;
+}
+export interface CaptureFolderPathDropInput {
+    /** The raw drop, from a CAPTURE-phase listener (see `rules.ts`'s header for why). */
+    readonly event: FolderPathDropEvent;
+    /** `null`/`undefined` when the host has no path lookup: every drop then passes through untouched. */
+    readonly port: FolderPathDropPort | null | undefined;
+    /** A folder drop with `current === null` is still swallowed; nothing is inserted. */
+    readonly composer: FolderPathDropInsertTargetRef;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/features/folder-path-drop/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/features/html-editor/canvas-embed-placeholders.d.ts

@@ -29,6 +29,10 @@
  * (untouched, still literally empty) marker means there is nothing inside the marker for that re-parse
  * to ever pick up, regardless of whether that `isProtectedElement` gap is ever closed.
  *
+ * **Safe to call again after every structural edit** (the hook does, on the tick after any component
+ * add or remove): each pass first drops cards whose marker has gone (see `removeStaleCards`), then
+ * wraps any marker not already inside a card.
+ *
  * Re-entrancy (defensive, mirroring `canvas-content-wrapper.ts`'s own `WRAPPER_ROOT_MARKER` guard): a
  * marker already sitting inside a placeholder card (`el.closest('[' + CARD_ROOT_MARKER + ']')`) is
  * skipped, so a second call — or a caller's own `load` handler firing twice — cannot nest a second card