@djangocfg/ui-tools 2.1.446 → 2.1.448

package/dist/composer-registry/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/tools/integration/ComposerRegistry/index.ts"],"names":["__name","useCallback","useSyncExternalStore"],"mappings":";;;;;AA6DA,IAAI,MAAA,GAAgC,IAAA;AACpC,IAAM,SAAA,uBAAgB,GAAA,EAAc;AAG7B,SAAS,iBAAiB,MAAA,EAAqC;AACpE,EAAA,MAAA,GAAS,MAAA;AACT,EAAA,KAAA,MAAW,EAAA,IAAM,SAAA,EAAW,EAAA,CAAG,MAAM,CAAA;AACvC;AAHgBA,wBAAA,CAAA,gBAAA,EAAA,kBAAA,CAAA;AAST,SAAS,eAAe,MAAA,EAAoC;AACjE,EAAA,gBAAA,CAAiB,MAAM,CAAA;AACvB,EAAA,OAAO,MAAM;AACX,IAAA,IAAI,MAAA,KAAW,MAAA,EAAQ,gBAAA,CAAiB,IAAI,CAAA;AAAA,EAC9C,CAAA;AACF;AALgBA,wBAAA,CAAA,cAAA,EAAA,gBAAA,CAAA;AAQT,SAAS,iBAAA,GAA2C;AACzD,EAAA,OAAO,MAAA;AACT;AAFgBA,wBAAA,CAAA,iBAAA,EAAA,mBAAA,CAAA;AAKT,SAAS,kBAAkB,QAAA,EAAgC;AAChE,EAAA,SAAA,CAAU,IAAI,QAAQ,CAAA;AACtB,EAAA,OAAO,MAAM;AACX,IAAA,SAAA,CAAU,OAAO,QAAQ,CAAA;AAAA,EAC3B,CAAA;AACF;AALgBA,wBAAA,CAAA,iBAAA,EAAA,mBAAA,CAAA;AAYT,SAAS,iBAAA,GAA2C;AACzD,EAAA,MAAM,SAAA,GAAYC,iBAAA,CAAY,CAAC,QAAA,KAAyB;AACtD,IAAA,OAAO,kBAAkB,QAAQ,CAAA;AAAA,EACnC,CAAA,EAAG,EAAE,CAAA;AACL,EAAA,OAAOC,0BAAA,CAAqB,SAAA,EAAW,iBAAA,EAAmB,MAAM,IAAI,CAAA;AACtE;AALgBF,wBAAA,CAAA,iBAAA,EAAA,mBAAA,CAAA","file":"index.cjs","sourcesContent":["'use client';\n\nimport { useCallback, useSyncExternalStore } from 'react';\n\n/**\n * Minimal imperative handle every text-editor surface implements so\n * an external tool (voice dictation, command palette, AI suggestion)\n * can read/write its text content without traversing React.\n *\n * Methods are optional so a host can register a partial handle\n * (e.g. only `getValue` + `setValue`), and the caller checks before use.\n */\nexport interface ComposerHandle {\n  /** Move keyboard focus into the composer's editable surface. */\n  focus: () => void;\n  /** Move the caret to the very end of the input. */\n  moveCursorToEnd?: () => void;\n  /** Read the current draft text. Voice dictation anchors partial\n   *  transcripts onto the user's already-typed prefix via this. */\n  getValue?: () => string;\n  /** Replace the current draft text. Voice dictation pushes interim\n   *  and final transcripts through this without owning a controlled\n   *  binding. */\n  setValue?: (value: string) => void;\n}\n\n/**\n * `@djangocfg/ui-tools/composer-registry`\n *\n * Cross-tool bridge: the currently-active text composer's handle.\n *\n * Producer side (`@djangocfg/ui-tools/chat` and TipTap hosts):\n *   register their composer's imperative handle via `attachComposer`.\n *\n * Consumer side (`@djangocfg/ui-tools/speech-recognition`):\n *   reads the active handle via `useActiveComposer`/`getActiveComposer`\n *   and pipes voice transcripts into it.\n *\n * Why this lives in its own subpath (not inside `chat`)\n * ----------------------------------------------------\n * `chat` and `speech-recognition` are sibling subpath exports. If the\n * registry lived inside `chat`, then `speech-recognition` would have\n * to reach into it via a cross-tool relative import — and under Vite\n * dev's dependency optimizer that file ends up loaded TWICE (once via\n * the `./chat` URL, once via the `./speech-recognition` relative-up\n * URL), giving the producer and the consumer two separate `let active`\n * slots. The active handle registered by chat would be invisible to\n * speech-recognition (and vice versa).\n *\n * Putting the registry in its own dedicated subpath (a single tool\n * that NEITHER chat nor speech-recognition cross-import — they both\n * import this one as their dependency) means Vite resolves it from a\n * single URL across the whole graph. One module instance, one shared\n * `active` slot.\n *\n * Semantics: one active composer per realm. The most recent\n * `registerComposer(handle)` wins; `registerComposer(null)` clears it.\n */\n\ntype Listener = (handle: ComposerHandle | null) => void;\n\nlet active: ComposerHandle | null = null;\nconst listeners = new Set<Listener>();\n\n/** Set or replace the active composer handle. Pass `null` to clear. */\nexport function registerComposer(handle: ComposerHandle | null): void {\n  active = handle;\n  for (const fn of listeners) fn(active);\n}\n\n/**\n * Convenience for components: register on mount, unregister on\n * unmount. Returns a cleanup function suitable for `useEffect`.\n */\nexport function attachComposer(handle: ComposerHandle): () => void {\n  registerComposer(handle);\n  return () => {\n    if (active === handle) registerComposer(null);\n  };\n}\n\n/** Read the current active handle (no subscription). */\nexport function getActiveComposer(): ComposerHandle | null {\n  return active;\n}\n\n/** Subscribe to handle changes; returns an unsubscribe fn. */\nexport function subscribeComposer(listener: Listener): () => void {\n  listeners.add(listener);\n  return () => {\n    listeners.delete(listener);\n  };\n}\n\n/**\n * React hook: re-renders the caller whenever the active composer\n * changes. Built on `useSyncExternalStore` so concurrent rendering,\n * SSR, and dev-mode strict-effects all behave correctly.\n */\nexport function useActiveComposer(): ComposerHandle | null {\n  const subscribe = useCallback((onChange: () => void) => {\n    return subscribeComposer(onChange);\n  }, []);\n  return useSyncExternalStore(subscribe, getActiveComposer, () => null);\n}\n"]}
+{"version":3,"sources":["../../src/tools/integration/ComposerRegistry/index.ts"],"names":["__name","useCallback","useSyncExternalStore"],"mappings":";;;;;AAoEA,IAAI,MAAA,GAAgC,IAAA;AACpC,IAAM,SAAA,uBAAgB,GAAA,EAAc;AAG7B,SAAS,iBAAiB,MAAA,EAAqC;AACpE,EAAA,MAAA,GAAS,MAAA;AACT,EAAA,KAAA,MAAW,EAAA,IAAM,SAAA,EAAW,EAAA,CAAG,MAAM,CAAA;AACvC;AAHgBA,wBAAA,CAAA,gBAAA,EAAA,kBAAA,CAAA;AAST,SAAS,eAAe,MAAA,EAAoC;AACjE,EAAA,gBAAA,CAAiB,MAAM,CAAA;AACvB,EAAA,OAAO,MAAM;AACX,IAAA,IAAI,MAAA,KAAW,MAAA,EAAQ,gBAAA,CAAiB,IAAI,CAAA;AAAA,EAC9C,CAAA;AACF;AALgBA,wBAAA,CAAA,cAAA,EAAA,gBAAA,CAAA;AAQT,SAAS,iBAAA,GAA2C;AACzD,EAAA,OAAO,MAAA;AACT;AAFgBA,wBAAA,CAAA,iBAAA,EAAA,mBAAA,CAAA;AAKT,SAAS,kBAAkB,QAAA,EAAgC;AAChE,EAAA,SAAA,CAAU,IAAI,QAAQ,CAAA;AACtB,EAAA,OAAO,MAAM;AACX,IAAA,SAAA,CAAU,OAAO,QAAQ,CAAA;AAAA,EAC3B,CAAA;AACF;AALgBA,wBAAA,CAAA,iBAAA,EAAA,mBAAA,CAAA;AAYT,SAAS,iBAAA,GAA2C;AACzD,EAAA,MAAM,SAAA,GAAYC,iBAAA,CAAY,CAAC,QAAA,KAAyB;AACtD,IAAA,OAAO,kBAAkB,QAAQ,CAAA;AAAA,EACnC,CAAA,EAAG,EAAE,CAAA;AACL,EAAA,OAAOC,0BAAA,CAAqB,SAAA,EAAW,iBAAA,EAAmB,MAAM,IAAI,CAAA;AACtE;AALgBF,wBAAA,CAAA,iBAAA,EAAA,mBAAA,CAAA","file":"index.cjs","sourcesContent":["'use client';\n\nimport { useCallback, useSyncExternalStore } from 'react';\n\n/**\n * Minimal imperative handle every text-editor surface implements so\n * an external tool (voice dictation, command palette, AI suggestion)\n * can read/write its text content without traversing React.\n *\n * Methods are optional so a host can register a partial handle\n * (e.g. only `getValue` + `setValue`), and the caller checks before use.\n */\nexport interface ComposerHandle {\n  /** Move keyboard focus into the composer's editable surface. */\n  focus: () => void;\n  /** Move the caret to the very end of the input. */\n  moveCursorToEnd?: () => void;\n  /** Read the current draft text. Voice dictation anchors partial\n   *  transcripts onto the user's already-typed prefix via this. */\n  getValue?: () => string;\n  /** Replace the current draft text. Voice dictation pushes interim\n   *  and final transcripts through this without owning a controlled\n   *  binding. */\n  setValue?: (value: string) => void;\n  /** Attach already-resolved files through the composer's validated attach\n   *  pipeline (size / type / count checks + upload + staging tray) — the\n   *  same entry point the paperclip, paste and drag-drop use. Present only\n   *  when the composer mounts the attach pipeline. A native shell (WKWebView /\n   *  WebView2) that intercepts an OS file drop hands the bytes here so a\n   *  native drop behaves exactly like an in-page one. */\n  attachFiles?: (files: File[]) => void;\n}\n\n/**\n * `@djangocfg/ui-tools/composer-registry`\n *\n * Cross-tool bridge: the currently-active text composer's handle.\n *\n * Producer side (`@djangocfg/ui-tools/chat` and TipTap hosts):\n *   register their composer's imperative handle via `attachComposer`.\n *\n * Consumer side (`@djangocfg/ui-tools/speech-recognition`):\n *   reads the active handle via `useActiveComposer`/`getActiveComposer`\n *   and pipes voice transcripts into it.\n *\n * Why this lives in its own subpath (not inside `chat`)\n * ----------------------------------------------------\n * `chat` and `speech-recognition` are sibling subpath exports. If the\n * registry lived inside `chat`, then `speech-recognition` would have\n * to reach into it via a cross-tool relative import — and under Vite\n * dev's dependency optimizer that file ends up loaded TWICE (once via\n * the `./chat` URL, once via the `./speech-recognition` relative-up\n * URL), giving the producer and the consumer two separate `let active`\n * slots. The active handle registered by chat would be invisible to\n * speech-recognition (and vice versa).\n *\n * Putting the registry in its own dedicated subpath (a single tool\n * that NEITHER chat nor speech-recognition cross-import — they both\n * import this one as their dependency) means Vite resolves it from a\n * single URL across the whole graph. One module instance, one shared\n * `active` slot.\n *\n * Semantics: one active composer per realm. The most recent\n * `registerComposer(handle)` wins; `registerComposer(null)` clears it.\n */\n\ntype Listener = (handle: ComposerHandle | null) => void;\n\nlet active: ComposerHandle | null = null;\nconst listeners = new Set<Listener>();\n\n/** Set or replace the active composer handle. Pass `null` to clear. */\nexport function registerComposer(handle: ComposerHandle | null): void {\n  active = handle;\n  for (const fn of listeners) fn(active);\n}\n\n/**\n * Convenience for components: register on mount, unregister on\n * unmount. Returns a cleanup function suitable for `useEffect`.\n */\nexport function attachComposer(handle: ComposerHandle): () => void {\n  registerComposer(handle);\n  return () => {\n    if (active === handle) registerComposer(null);\n  };\n}\n\n/** Read the current active handle (no subscription). */\nexport function getActiveComposer(): ComposerHandle | null {\n  return active;\n}\n\n/** Subscribe to handle changes; returns an unsubscribe fn. */\nexport function subscribeComposer(listener: Listener): () => void {\n  listeners.add(listener);\n  return () => {\n    listeners.delete(listener);\n  };\n}\n\n/**\n * React hook: re-renders the caller whenever the active composer\n * changes. Built on `useSyncExternalStore` so concurrent rendering,\n * SSR, and dev-mode strict-effects all behave correctly.\n */\nexport function useActiveComposer(): ComposerHandle | null {\n  const subscribe = useCallback((onChange: () => void) => {\n    return subscribeComposer(onChange);\n  }, []);\n  return useSyncExternalStore(subscribe, getActiveComposer, () => null);\n}\n"]}

package/dist/composer-registry/index.d.cts

@@ -18,6 +18,13 @@ interface ComposerHandle {
      *  and final transcripts through this without owning a controlled
      *  binding. */
     setValue?: (value: string) => void;
+    /** Attach already-resolved files through the composer's validated attach
+     *  pipeline (size / type / count checks + upload + staging tray) — the
+     *  same entry point the paperclip, paste and drag-drop use. Present only
+     *  when the composer mounts the attach pipeline. A native shell (WKWebView /
+     *  WebView2) that intercepts an OS file drop hands the bytes here so a
+     *  native drop behaves exactly like an in-page one. */
+    attachFiles?: (files: File[]) => void;
 }
 /**
  * `@djangocfg/ui-tools/composer-registry`

package/dist/composer-registry/index.d.ts

@@ -18,6 +18,13 @@ interface ComposerHandle {
      *  and final transcripts through this without owning a controlled
      *  binding. */
     setValue?: (value: string) => void;
+    /** Attach already-resolved files through the composer's validated attach
+     *  pipeline (size / type / count checks + upload + staging tray) — the
+     *  same entry point the paperclip, paste and drag-drop use. Present only
+     *  when the composer mounts the attach pipeline. A native shell (WKWebView /
+     *  WebView2) that intercepts an OS file drop hands the bytes here so a
+     *  native drop behaves exactly like an in-page one. */
+    attachFiles?: (files: File[]) => void;
 }
 /**
  * `@djangocfg/ui-tools/composer-registry`

package/dist/composer-registry/index.mjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/tools/integration/ComposerRegistry/index.ts"],"names":[],"mappings":";;;AA6DA,IAAI,MAAA,GAAgC,IAAA;AACpC,IAAM,SAAA,uBAAgB,GAAA,EAAc;AAG7B,SAAS,iBAAiB,MAAA,EAAqC;AACpE,EAAA,MAAA,GAAS,MAAA;AACT,EAAA,KAAA,MAAW,EAAA,IAAM,SAAA,EAAW,EAAA,CAAG,MAAM,CAAA;AACvC;AAHgB,MAAA,CAAA,gBAAA,EAAA,kBAAA,CAAA;AAST,SAAS,eAAe,MAAA,EAAoC;AACjE,EAAA,gBAAA,CAAiB,MAAM,CAAA;AACvB,EAAA,OAAO,MAAM;AACX,IAAA,IAAI,MAAA,KAAW,MAAA,EAAQ,gBAAA,CAAiB,IAAI,CAAA;AAAA,EAC9C,CAAA;AACF;AALgB,MAAA,CAAA,cAAA,EAAA,gBAAA,CAAA;AAQT,SAAS,iBAAA,GAA2C;AACzD,EAAA,OAAO,MAAA;AACT;AAFgB,MAAA,CAAA,iBAAA,EAAA,mBAAA,CAAA;AAKT,SAAS,kBAAkB,QAAA,EAAgC;AAChE,EAAA,SAAA,CAAU,IAAI,QAAQ,CAAA;AACtB,EAAA,OAAO,MAAM;AACX,IAAA,SAAA,CAAU,OAAO,QAAQ,CAAA;AAAA,EAC3B,CAAA;AACF;AALgB,MAAA,CAAA,iBAAA,EAAA,mBAAA,CAAA;AAYT,SAAS,iBAAA,GAA2C;AACzD,EAAA,MAAM,SAAA,GAAY,WAAA,CAAY,CAAC,QAAA,KAAyB;AACtD,IAAA,OAAO,kBAAkB,QAAQ,CAAA;AAAA,EACnC,CAAA,EAAG,EAAE,CAAA;AACL,EAAA,OAAO,oBAAA,CAAqB,SAAA,EAAW,iBAAA,EAAmB,MAAM,IAAI,CAAA;AACtE;AALgB,MAAA,CAAA,iBAAA,EAAA,mBAAA,CAAA","file":"index.mjs","sourcesContent":["'use client';\n\nimport { useCallback, useSyncExternalStore } from 'react';\n\n/**\n * Minimal imperative handle every text-editor surface implements so\n * an external tool (voice dictation, command palette, AI suggestion)\n * can read/write its text content without traversing React.\n *\n * Methods are optional so a host can register a partial handle\n * (e.g. only `getValue` + `setValue`), and the caller checks before use.\n */\nexport interface ComposerHandle {\n  /** Move keyboard focus into the composer's editable surface. */\n  focus: () => void;\n  /** Move the caret to the very end of the input. */\n  moveCursorToEnd?: () => void;\n  /** Read the current draft text. Voice dictation anchors partial\n   *  transcripts onto the user's already-typed prefix via this. */\n  getValue?: () => string;\n  /** Replace the current draft text. Voice dictation pushes interim\n   *  and final transcripts through this without owning a controlled\n   *  binding. */\n  setValue?: (value: string) => void;\n}\n\n/**\n * `@djangocfg/ui-tools/composer-registry`\n *\n * Cross-tool bridge: the currently-active text composer's handle.\n *\n * Producer side (`@djangocfg/ui-tools/chat` and TipTap hosts):\n *   register their composer's imperative handle via `attachComposer`.\n *\n * Consumer side (`@djangocfg/ui-tools/speech-recognition`):\n *   reads the active handle via `useActiveComposer`/`getActiveComposer`\n *   and pipes voice transcripts into it.\n *\n * Why this lives in its own subpath (not inside `chat`)\n * ----------------------------------------------------\n * `chat` and `speech-recognition` are sibling subpath exports. If the\n * registry lived inside `chat`, then `speech-recognition` would have\n * to reach into it via a cross-tool relative import — and under Vite\n * dev's dependency optimizer that file ends up loaded TWICE (once via\n * the `./chat` URL, once via the `./speech-recognition` relative-up\n * URL), giving the producer and the consumer two separate `let active`\n * slots. The active handle registered by chat would be invisible to\n * speech-recognition (and vice versa).\n *\n * Putting the registry in its own dedicated subpath (a single tool\n * that NEITHER chat nor speech-recognition cross-import — they both\n * import this one as their dependency) means Vite resolves it from a\n * single URL across the whole graph. One module instance, one shared\n * `active` slot.\n *\n * Semantics: one active composer per realm. The most recent\n * `registerComposer(handle)` wins; `registerComposer(null)` clears it.\n */\n\ntype Listener = (handle: ComposerHandle | null) => void;\n\nlet active: ComposerHandle | null = null;\nconst listeners = new Set<Listener>();\n\n/** Set or replace the active composer handle. Pass `null` to clear. */\nexport function registerComposer(handle: ComposerHandle | null): void {\n  active = handle;\n  for (const fn of listeners) fn(active);\n}\n\n/**\n * Convenience for components: register on mount, unregister on\n * unmount. Returns a cleanup function suitable for `useEffect`.\n */\nexport function attachComposer(handle: ComposerHandle): () => void {\n  registerComposer(handle);\n  return () => {\n    if (active === handle) registerComposer(null);\n  };\n}\n\n/** Read the current active handle (no subscription). */\nexport function getActiveComposer(): ComposerHandle | null {\n  return active;\n}\n\n/** Subscribe to handle changes; returns an unsubscribe fn. */\nexport function subscribeComposer(listener: Listener): () => void {\n  listeners.add(listener);\n  return () => {\n    listeners.delete(listener);\n  };\n}\n\n/**\n * React hook: re-renders the caller whenever the active composer\n * changes. Built on `useSyncExternalStore` so concurrent rendering,\n * SSR, and dev-mode strict-effects all behave correctly.\n */\nexport function useActiveComposer(): ComposerHandle | null {\n  const subscribe = useCallback((onChange: () => void) => {\n    return subscribeComposer(onChange);\n  }, []);\n  return useSyncExternalStore(subscribe, getActiveComposer, () => null);\n}\n"]}
+{"version":3,"sources":["../../src/tools/integration/ComposerRegistry/index.ts"],"names":[],"mappings":";;;AAoEA,IAAI,MAAA,GAAgC,IAAA;AACpC,IAAM,SAAA,uBAAgB,GAAA,EAAc;AAG7B,SAAS,iBAAiB,MAAA,EAAqC;AACpE,EAAA,MAAA,GAAS,MAAA;AACT,EAAA,KAAA,MAAW,EAAA,IAAM,SAAA,EAAW,EAAA,CAAG,MAAM,CAAA;AACvC;AAHgB,MAAA,CAAA,gBAAA,EAAA,kBAAA,CAAA;AAST,SAAS,eAAe,MAAA,EAAoC;AACjE,EAAA,gBAAA,CAAiB,MAAM,CAAA;AACvB,EAAA,OAAO,MAAM;AACX,IAAA,IAAI,MAAA,KAAW,MAAA,EAAQ,gBAAA,CAAiB,IAAI,CAAA;AAAA,EAC9C,CAAA;AACF;AALgB,MAAA,CAAA,cAAA,EAAA,gBAAA,CAAA;AAQT,SAAS,iBAAA,GAA2C;AACzD,EAAA,OAAO,MAAA;AACT;AAFgB,MAAA,CAAA,iBAAA,EAAA,mBAAA,CAAA;AAKT,SAAS,kBAAkB,QAAA,EAAgC;AAChE,EAAA,SAAA,CAAU,IAAI,QAAQ,CAAA;AACtB,EAAA,OAAO,MAAM;AACX,IAAA,SAAA,CAAU,OAAO,QAAQ,CAAA;AAAA,EAC3B,CAAA;AACF;AALgB,MAAA,CAAA,iBAAA,EAAA,mBAAA,CAAA;AAYT,SAAS,iBAAA,GAA2C;AACzD,EAAA,MAAM,SAAA,GAAY,WAAA,CAAY,CAAC,QAAA,KAAyB;AACtD,IAAA,OAAO,kBAAkB,QAAQ,CAAA;AAAA,EACnC,CAAA,EAAG,EAAE,CAAA;AACL,EAAA,OAAO,oBAAA,CAAqB,SAAA,EAAW,iBAAA,EAAmB,MAAM,IAAI,CAAA;AACtE;AALgB,MAAA,CAAA,iBAAA,EAAA,mBAAA,CAAA","file":"index.mjs","sourcesContent":["'use client';\n\nimport { useCallback, useSyncExternalStore } from 'react';\n\n/**\n * Minimal imperative handle every text-editor surface implements so\n * an external tool (voice dictation, command palette, AI suggestion)\n * can read/write its text content without traversing React.\n *\n * Methods are optional so a host can register a partial handle\n * (e.g. only `getValue` + `setValue`), and the caller checks before use.\n */\nexport interface ComposerHandle {\n  /** Move keyboard focus into the composer's editable surface. */\n  focus: () => void;\n  /** Move the caret to the very end of the input. */\n  moveCursorToEnd?: () => void;\n  /** Read the current draft text. Voice dictation anchors partial\n   *  transcripts onto the user's already-typed prefix via this. */\n  getValue?: () => string;\n  /** Replace the current draft text. Voice dictation pushes interim\n   *  and final transcripts through this without owning a controlled\n   *  binding. */\n  setValue?: (value: string) => void;\n  /** Attach already-resolved files through the composer's validated attach\n   *  pipeline (size / type / count checks + upload + staging tray) — the\n   *  same entry point the paperclip, paste and drag-drop use. Present only\n   *  when the composer mounts the attach pipeline. A native shell (WKWebView /\n   *  WebView2) that intercepts an OS file drop hands the bytes here so a\n   *  native drop behaves exactly like an in-page one. */\n  attachFiles?: (files: File[]) => void;\n}\n\n/**\n * `@djangocfg/ui-tools/composer-registry`\n *\n * Cross-tool bridge: the currently-active text composer's handle.\n *\n * Producer side (`@djangocfg/ui-tools/chat` and TipTap hosts):\n *   register their composer's imperative handle via `attachComposer`.\n *\n * Consumer side (`@djangocfg/ui-tools/speech-recognition`):\n *   reads the active handle via `useActiveComposer`/`getActiveComposer`\n *   and pipes voice transcripts into it.\n *\n * Why this lives in its own subpath (not inside `chat`)\n * ----------------------------------------------------\n * `chat` and `speech-recognition` are sibling subpath exports. If the\n * registry lived inside `chat`, then `speech-recognition` would have\n * to reach into it via a cross-tool relative import — and under Vite\n * dev's dependency optimizer that file ends up loaded TWICE (once via\n * the `./chat` URL, once via the `./speech-recognition` relative-up\n * URL), giving the producer and the consumer two separate `let active`\n * slots. The active handle registered by chat would be invisible to\n * speech-recognition (and vice versa).\n *\n * Putting the registry in its own dedicated subpath (a single tool\n * that NEITHER chat nor speech-recognition cross-import — they both\n * import this one as their dependency) means Vite resolves it from a\n * single URL across the whole graph. One module instance, one shared\n * `active` slot.\n *\n * Semantics: one active composer per realm. The most recent\n * `registerComposer(handle)` wins; `registerComposer(null)` clears it.\n */\n\ntype Listener = (handle: ComposerHandle | null) => void;\n\nlet active: ComposerHandle | null = null;\nconst listeners = new Set<Listener>();\n\n/** Set or replace the active composer handle. Pass `null` to clear. */\nexport function registerComposer(handle: ComposerHandle | null): void {\n  active = handle;\n  for (const fn of listeners) fn(active);\n}\n\n/**\n * Convenience for components: register on mount, unregister on\n * unmount. Returns a cleanup function suitable for `useEffect`.\n */\nexport function attachComposer(handle: ComposerHandle): () => void {\n  registerComposer(handle);\n  return () => {\n    if (active === handle) registerComposer(null);\n  };\n}\n\n/** Read the current active handle (no subscription). */\nexport function getActiveComposer(): ComposerHandle | null {\n  return active;\n}\n\n/** Subscribe to handle changes; returns an unsubscribe fn. */\nexport function subscribeComposer(listener: Listener): () => void {\n  listeners.add(listener);\n  return () => {\n    listeners.delete(listener);\n  };\n}\n\n/**\n * React hook: re-renders the caller whenever the active composer\n * changes. Built on `useSyncExternalStore` so concurrent rendering,\n * SSR, and dev-mode strict-effects all behave correctly.\n */\nexport function useActiveComposer(): ComposerHandle | null {\n  const subscribe = useCallback((onChange: () => void) => {\n    return subscribeComposer(onChange);\n  }, []);\n  return useSyncExternalStore(subscribe, getActiveComposer, () => null);\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/ui-tools",
-  "version": "2.1.446",
+  "version": "2.1.448",
   "description": "Heavy React tools with lazy loading - for Electron, Vite, CRA, Next.js apps",
   "keywords": [
     "ui-tools",
@@ -334,8 +334,8 @@
     "test:watch": "vitest"
   },
   "peerDependencies": {
-    "@djangocfg/i18n": "^2.1.446",
-    "@djangocfg/ui-core": "^2.1.446",
+    "@djangocfg/i18n": "^2.1.448",
+    "@djangocfg/ui-core": "^2.1.448",
     "consola": "^3.4.2",
     "lodash-es": "^4.18.1",
     "lucide-react": "^0.545.0",
@@ -418,9 +418,9 @@
     "@maplibre/maplibre-gl-geocoder": "^1.7.0"
   },
   "devDependencies": {
-    "@djangocfg/i18n": "^2.1.446",
-    "@djangocfg/typescript-config": "^2.1.446",
-    "@djangocfg/ui-core": "^2.1.446",
+    "@djangocfg/i18n": "^2.1.448",
+    "@djangocfg/typescript-config": "^2.1.448",
+    "@djangocfg/ui-core": "^2.1.448",
     "@types/lodash-es": "^4.17.12",
     "@types/mapbox__mapbox-gl-draw": "^1.4.8",
     "@types/node": "^25.2.3",

package/src/tools/chat/composer/Composer.tsx

@@ -19,6 +19,7 @@ import { SlashMenu } from './slash/SlashMenu';
 import { useSlashCommands } from './slash/useSlashCommands';
 import { useComposerActions } from './useComposerActions';
 import { useComposerAttach } from './useComposerAttach';
+import { usePaneDrop } from './usePaneDrop';
 import type {
   ComposerAppearance,
   ComposerAttachConfig,
@@ -43,6 +44,21 @@ export interface ComposerProps {
   /** Tune the built-in attach pipeline — accepted types, size / count
    *  caps, paste, and the optional upload transport. */
   attach?: ComposerAttachConfig;
+  /**
+   * How large the file-drop target is.
+   *
+   * - `'composer'` (default) — only the composer surface accepts a drop
+   *   (the historical behaviour).
+   * - `'pane'` — the WHOLE chat pane is a drop target: dragging a file
+   *   anywhere over the chat shows a full-pane "Drop files here" overlay
+   *   and drops route through the same validated `attachFiles` pipeline.
+   *   Right when a pane hosts a single conversation (one chat open at a
+   *   time) — a small composer-only target is easy to miss. The overlay
+   *   covers the nearest positioned ancestor of the composer, so the host
+   *   must give that ancestor `position: relative` (the chat pane usually
+   *   already is). Falls back to the viewport if none is found.
+   */
+  dropScope?: 'composer' | 'pane';
   /** Override the built-in file picker. When set, the paperclip and the
    *  `+`-menu attach item call this instead of opening the native picker
    *  — for hosts that drive their own (e.g. a Wails native dialog). */
@@ -162,6 +178,7 @@ export const Composer = forwardRef<HTMLDivElement, ComposerProps>(function Compo
     disabled,
     showAttachmentButton = false,
     attach,
+    dropScope = 'composer',
     onPickFiles,
     className,
     textareaClassName,
@@ -213,6 +230,13 @@ export const Composer = forwardRef<HTMLDivElement, ComposerProps>(function Compo
   // In that case the slot registers its own imperative handle; skip
   // ours so we don't overwrite it (child effects run before parent).
   const hasCustomTextarea = !!slots?.Textarea;
+  // The plain-textarea handle. `attachFiles` is threaded in via a ref (set
+  // once `attachHandle` exists, below) so the native OS-drop bridge
+  // (getActiveComposer().attachFiles) works for this path too, without a
+  // temporal-dead-zone on `attachHandle` (declared further down). The
+  // custom-textarea (TipTap) path carries attach the same way via
+  // ComposerRichTextarea reading the attach context.
+  const attachFilesRef = useRef<((files: File[]) => void) | undefined>(undefined);
   useEffect(() => {
     if (hasCustomTextarea) return;
     return attachComposer({
@@ -225,6 +249,7 @@ export const Composer = forwardRef<HTMLDivElement, ComposerProps>(function Compo
       },
       getValue: () => getValueRef.current(),
       setValue: composerSetValue,
+      attachFiles: (files) => attachFilesRef.current?.(files),
     });
   }, [hasCustomTextarea, composerFocus, composerSetValue, textareaRef]);
 
@@ -338,6 +363,9 @@ export const Composer = forwardRef<HTMLDivElement, ComposerProps>(function Compo
     disabled: isDisabled,
     pasteScopeRef: surfaceRef,
   });
+  // Feed the plain-textarea registry handle its attach entry (see the
+  // attachComposer effect above — it reads through this ref to dodge a TDZ).
+  attachFilesRef.current = attachEnabled ? attachHandle.attachFiles : undefined;
   // The resolved click handler: host override wins, else the built-in
   // picker. `undefined` when attaching is not enabled at all.
   const pickFiles = !attachEnabled
@@ -365,17 +393,38 @@ export const Composer = forwardRef<HTMLDivElement, ComposerProps>(function Compo
     dragDepth.current = Math.max(0, dragDepth.current - 1);
     if (dragDepth.current === 0) setIsDragging(false);
   };
+  // When `dropScope==='pane'` the pane-level hook (usePaneDrop) owns the drop
+  // for the WHOLE pane, including the composer surface. Skip the composer's own
+  // surface drop then so a file landing on the composer isn't attached twice.
+  const paneScope = dropScope === 'pane' && attachEnabled && !isDisabled;
   const handleDrop = (e: React.DragEvent) => {
-    if (!attachEnabled || isDisabled) return;
+    if (!attachEnabled || isDisabled || paneScope) return;
     e.preventDefault();
     dragDepth.current = 0;
     setIsDragging(false);
     const dropped = Array.from(e.dataTransfer.files ?? []);
-    // eslint-disable-next-line no-console
-    console.log('[composer] handleDrop files=%d names=%o', dropped.length, dropped.map((f) => f.name));
     if (dropped.length > 0) attachHandle.attachFiles(dropped);
   };
 
+  // Pane-wide drop target: dragging a file anywhere over the chat pane shows a
+  // full-pane overlay and routes the drop through the same validated pipeline.
+  const rootRef = useRef<HTMLDivElement>(null);
+  const { paneOverlay } = usePaneDrop({
+    enabled: paneScope,
+    composerRef: rootRef,
+    onFiles: attachHandle.attachFiles,
+  });
+  // Merge the internal root ref (pane-drop needs the composer node to locate
+  // its pane) with the caller's forwarded ref.
+  const setRootRef = useCallback(
+    (node: HTMLDivElement | null) => {
+      rootRef.current = node;
+      if (typeof ref === 'function') ref(node);
+      else if (ref) (ref as React.MutableRefObject<HTMLDivElement | null>).current = node;
+    },
+    [ref],
+  );
+
   // Send, then return focus to the composer. Clicking the Send button
   // moves focus to that button; after the message goes the caret should
   // be back in the input so the user can keep typing without reaching for
@@ -618,7 +667,7 @@ export const Composer = forwardRef<HTMLDivElement, ComposerProps>(function Compo
       <ComposerSizeProvider value={size}>
        <AttachProvider value={attachHandle}>
         <div
-          ref={ref}
+          ref={setRootRef}
           {...dragProps}
           onKeyDownCapture={handleSlashKeyDownCapture}
           className={cn(
@@ -632,7 +681,8 @@ export const Composer = forwardRef<HTMLDivElement, ComposerProps>(function Compo
           )}
         >
           {hiddenFileInput}
-          {dragOverlay}
+          {!paneScope && dragOverlay}
+          {paneOverlay}
           {slashOverlay}
           {trayNode ? <div className="mb-1.5">{trayNode}</div> : null}
           <div
@@ -743,7 +793,7 @@ export const Composer = forwardRef<HTMLDivElement, ComposerProps>(function Compo
     <ComposerSizeProvider value={size}>
      <AttachProvider value={attachHandle}>
       <div
-        ref={ref}
+        ref={setRootRef}
         {...dragProps}
         onKeyDownCapture={handleSlashKeyDownCapture}
         className={cn(
@@ -756,7 +806,8 @@ export const Composer = forwardRef<HTMLDivElement, ComposerProps>(function Compo
         )}
       >
         {hiddenFileInput}
-        {dragOverlay}
+        {!paneScope && dragOverlay}
+        {paneOverlay}
         {slashOverlay}
         {trayNode ? <div className="mb-2">{trayNode}</div> : null}
         {surfaceWrapper}

package/src/tools/chat/composer/ComposerRichTextarea.tsx

@@ -9,6 +9,7 @@ import {
   type SlashCommandInfo,
 } from '@djangocfg/ui-tools/markdown-editor';
 
+import { useComposerAttachContext } from './AttachContext';
 import { useRegisterComposer } from '../hooks/useAutoFocusOnStreamEnd';
 import type { ComposerSize, ComposerTextareaProps } from './types';
 
@@ -95,11 +96,19 @@ export function ComposerRichTextarea({
     [],
   );
   const getValue = useCallback(() => composer.value, [composer.value]);
+  // This TipTap slot OWNS the active composer handle (it wins over the
+  // plain-textarea registration in Composer.tsx for a custom textarea). So it
+  // must also carry `attachFiles`, else a native shell's OS-drop bridge
+  // (window.__cmdopFileDrop → getActiveComposer().attachFiles) finds no attach
+  // entry. Read it from the attach context the composer provides.
+  const attach = useComposerAttachContext();
+  const attachFiles = attach?.attachFiles;
   useRegisterComposer({
     focus,
     moveCursorToEnd,
     getValue,
     setValue: composer.setValue,
+    attachFiles,
   });
 
   return (

package/src/tools/chat/composer/useComposerAttach.tsx

@@ -2,6 +2,8 @@
 
 import { useCallback, useEffect, useMemo, useRef, type RefObject } from 'react';
 
+import { getActiveComposer } from '@djangocfg/ui-tools/composer-registry';
+
 import { buildAcceptString, useClipboardPaste } from '../../forms/Uploader';
 import type { UseChatComposerReturn } from '../hooks/useChatComposer';
 import { fileToAttachment, revokeAttachmentUrl } from './fileToAttachment';
@@ -126,6 +128,7 @@ export function useComposerAttach({
       const cap = maxFiles ?? Number.POSITIVE_INFINITY;
 
       let slots = cap - c.attachments.length;
+      let staged = 0;
       for (const file of files) {
         if (slots <= 0) {
           onRejectRef.current?.(file, 'count');
@@ -147,6 +150,17 @@ export function useComposerAttach({
           runUpload(file, attachment.id, attachment.url);
         }
         slots -= 1;
+        staged += 1;
+      }
+
+      // After a successful attach (drop / paste / picker all land here), move
+      // the caret into the composer so the user can type the message
+      // immediately without reaching for the mouse — a dropped file is the
+      // start of composing, not the end. Route through the registry (not the
+      // plain-textarea `c.focus()`), so it also focuses the TipTap rich
+      // editor. rAF lets the staging tray commit first.
+      if (staged > 0) {
+        requestAnimationFrame(() => getActiveComposer()?.focus?.());
       }
     },
     [disabled, maxFiles, maxSizeBytes, accept, runUpload],

package/src/tools/chat/composer/usePaneDrop.tsx

@@ -0,0 +1,208 @@
+'use client';
+
+/**
+ * usePaneDrop — widen the composer's file-drop target to the whole chat pane.
+ *
+ * The composer's own drag surface (`data-wails-dropzone` div) is a small
+ * target easy to miss. When a pane hosts one conversation at a time,
+ * dropping a file anywhere over the chat should attach it — the ChatGPT /
+ * Telegram / Slack model. This hook implements that WITHOUT the composer
+ * needing to own the pane's DOM:
+ *
+ *  - It listens for drag events at the WINDOW level (capture) and gates on
+ *    `dataTransfer.types.includes('Files')` — so a text/selection drag never
+ *    triggers it.
+ *  - The overlay is positioned over the composer's nearest POSITIONED
+ *    ancestor (the chat pane, normally `position: relative`). If none is
+ *    found it falls back to the viewport. A ResizeObserver + scroll/resize
+ *    listeners keep the rect fresh while a drag is in flight.
+ *  - The drop routes through the SAME `onFiles` (the composer's validated
+ *    `attachFiles`) as the paperclip / paste / composer-drop paths — no
+ *    second attach lane.
+ *
+ * Enabled only when `dropScope === 'pane'` and attaching is on; otherwise the
+ * hook is inert and returns a null overlay (the composer keeps its own
+ * surface-scoped drop).
+ */
+
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { createPortal } from 'react-dom';
+
+import { cn } from '@djangocfg/ui-core/lib';
+
+export interface UsePaneDropOptions {
+  /** Master switch — only bind when the host asked for pane scope + attach on. */
+  enabled: boolean;
+  /** The composer root — used to find the pane (nearest positioned ancestor). */
+  composerRef: React.RefObject<HTMLElement | null>;
+  /** Funnel dropped files through the composer's validated attach pipeline. */
+  onFiles: (files: File[]) => void;
+  /** Overlay caption. Defaults to a plain English string. */
+  label?: string;
+}
+
+export interface UsePaneDropReturn {
+  /** Portal overlay node (or null). Render it anywhere — it portals to body. */
+  paneOverlay: React.ReactNode;
+}
+
+/** Walk up to the nearest ancestor establishing a positioning context. */
+function nearestPositionedAncestor(el: HTMLElement | null): HTMLElement | null {
+  let node = el?.parentElement ?? null;
+  while (node) {
+    const pos = getComputedStyle(node).position;
+    if (pos === 'relative' || pos === 'absolute' || pos === 'fixed' || pos === 'sticky') {
+      return node;
+    }
+    node = node.parentElement;
+  }
+  return null;
+}
+
+export function usePaneDrop(options: UsePaneDropOptions): UsePaneDropReturn {
+  const { enabled, composerRef, onFiles, label = 'Drop files here' } = options;
+
+  const [dragging, setDragging] = useState(false);
+  const [rect, setRect] = useState<DOMRect | null>(null);
+  // Counter of enter/leave — a single boolean flickers as the cursor crosses
+  // child element boundaries (each generates leave→enter). Depth hits 0 only
+  // when the pointer truly left the window.
+  const depth = useRef(0);
+  const paneRef = useRef<HTMLElement | null>(null);
+
+  const measure = useCallback(() => {
+    const pane = paneRef.current;
+    setRect(pane ? pane.getBoundingClientRect() : null);
+  }, []);
+
+  useEffect(() => {
+    if (!enabled) {
+      // Ensure a scope flip mid-drag can't leave a stuck overlay.
+      depth.current = 0;
+      setDragging(false);
+      return;
+    }
+
+    const hasFiles = (e: DragEvent) =>
+      Array.from(e.dataTransfer?.types ?? []).includes('Files');
+
+    const onDragEnter = (e: DragEvent) => {
+      if (!hasFiles(e)) return;
+      // Resolve the pane lazily on the first enter (the composer is mounted by now).
+      paneRef.current = nearestPositionedAncestor(composerRef.current);
+      depth.current += 1;
+      if (!dragging) {
+        measure();
+        setDragging(true);
+      }
+    };
+    const onDragOver = (e: DragEvent) => {
+      if (!hasFiles(e)) return;
+      // Allow the drop (else the browser rejects it and onDrop never fires).
+      e.preventDefault();
+      if (e.dataTransfer) e.dataTransfer.dropEffect = 'copy';
+    };
+    const onDragLeave = (e: DragEvent) => {
+      if (!hasFiles(e)) return;
+      depth.current = Math.max(0, depth.current - 1);
+      if (depth.current === 0) setDragging(false);
+    };
+    const onDrop = (e: DragEvent) => {
+      if (!hasFiles(e)) return;
+      e.preventDefault();
+      depth.current = 0;
+      setDragging(false);
+      const files = Array.from(e.dataTransfer?.files ?? []);
+      if (files.length > 0) onFiles(files);
+    };
+
+    // Native-shell drag signal. WKWebView / WebView2 intercept an OS file drag
+    // natively and NEVER emit DOM dragenter/leave, so the listeners above can't
+    // light the overlay. The native side instead fans out a `cmdop:native-drag`
+    // window event (see cmdop transport `native-drop.ts`) as the drag enters /
+    // leaves; we drive the overlay off that. The actual files still arrive via
+    // the native `window.__cmdopFileDrop` → attachFiles path, not a DOM drop.
+    const onNativeDrag = (e: Event) => {
+      const active = !!(e as CustomEvent<{ active?: boolean }>).detail?.active;
+      if (active) {
+        paneRef.current = nearestPositionedAncestor(composerRef.current);
+        measure();
+        setDragging(true);
+      } else {
+        depth.current = 0;
+        setDragging(false);
+      }
+    };
+
+    // Capture phase so we see the drag before any inner handler stops it.
+    window.addEventListener('dragenter', onDragEnter, true);
+    window.addEventListener('dragover', onDragOver, true);
+    window.addEventListener('dragleave', onDragLeave, true);
+    window.addEventListener('drop', onDrop, true);
+    window.addEventListener('cmdop:native-drag', onNativeDrag);
+    return () => {
+      window.removeEventListener('dragenter', onDragEnter, true);
+      window.removeEventListener('dragover', onDragOver, true);
+      window.removeEventListener('dragleave', onDragLeave, true);
+      window.removeEventListener('drop', onDrop, true);
+      window.removeEventListener('cmdop:native-drag', onNativeDrag);
+    };
+  }, [enabled, composerRef, onFiles, measure, dragging]);
+
+  // Keep the overlay aligned with the pane while a drag is in flight.
+  useEffect(() => {
+    if (!dragging) return;
+    const onChange = () => measure();
+    window.addEventListener('scroll', onChange, true);
+    window.addEventListener('resize', onChange);
+    const ro = paneRef.current ? new ResizeObserver(onChange) : null;
+    if (ro && paneRef.current) ro.observe(paneRef.current);
+    return () => {
+      window.removeEventListener('scroll', onChange, true);
+      window.removeEventListener('resize', onChange);
+      ro?.disconnect();
+    };
+  }, [dragging, measure]);
+
+  if (!enabled || !dragging || typeof document === 'undefined') {
+    return { paneOverlay: null };
+  }
+
+  // Cover the pane rect (or the viewport if we couldn't find a positioned
+  // ancestor). `pointer-events-none` so the underlying drop target still
+  // receives the drop event — the overlay is a pure visual affordance.
+  const style: React.CSSProperties = rect
+    ? { position: 'fixed', top: rect.top, left: rect.left, width: rect.width, height: rect.height }
+    : { position: 'fixed', inset: 0 };
+
+  const overlay = (
+    <div
+      aria-hidden
+      className="pointer-events-none z-50"
+      style={style}
+    >
+      <div
+        className={cn(
+          'absolute inset-2 flex flex-col items-center justify-center gap-3 rounded-2xl',
+          'border-2 border-dashed border-primary/50 bg-primary/5 backdrop-blur-[2px]',
+          'transition-opacity duration-150',
+        )}
+      >
+        <div className="flex h-14 w-14 items-center justify-center rounded-full bg-primary/10 ring-1 ring-primary/30">
+          <svg
+            width="26" height="26" viewBox="0 0 24 24" fill="none"
+            stroke="currentColor" strokeWidth="1.8" strokeLinecap="round" strokeLinejoin="round"
+            className="text-primary"
+          >
+            <path d="M12 3v12" />
+            <path d="m7 10 5 5 5-5" />
+            <path d="M5 21h14" />
+          </svg>
+        </div>
+        <span className="text-sm font-medium text-foreground/90">{label}</span>
+      </div>
+    </div>
+  );
+
+  return { paneOverlay: createPortal(overlay, document.body) };
+}

package/src/tools/chat/context/ChatProvider.tsx

@@ -12,7 +12,7 @@ import {
 
 import { getActiveComposer } from '@djangocfg/ui-tools/composer-registry';
 
-import type { ChatConfig, ChatLabels, ChatTransport } from '../types';
+import type { ChatConfig, ChatLabels, ChatMessage, ChatTransport } from '../types';
 import { DEFAULT_LABELS } from '../types';
 import type { BlockRegistry } from '../messages/blocks';
 
@@ -63,6 +63,15 @@ export interface ChatProviderProps {
   transport: ChatTransport;
   config?: ChatConfig;
   initialSessionId?: string;
+  /**
+   * Warm transcript rendered instantly on mount while the resume-path
+   * `loadHistory` revalidates in the background (see `useChat`). Pair with
+   * `initialSessionId`: the host caches the last-seen transcript per room and
+   * passes it here so returning to a conversation shows content immediately
+   * instead of a cold refetch Spinner. The server read remains the source of
+   * truth — this is a visual head-start, replaced by the loaded page.
+   */
+  initialMessages?: readonly ChatMessage[];
   autoCreateSession?: boolean;
   streaming?: boolean;
   /** Audio-trigger configuration. Off by default (no `sounds` map). */
@@ -110,6 +119,7 @@ export function ChatProvider({
   transport,
   config = {},
   initialSessionId,
+  initialMessages,
   autoCreateSession,
   streaming,
   audio,
@@ -136,6 +146,7 @@ export function ChatProvider({
   const chat = useChat({
     transport,
     initialSessionId,
+    initialMessages,
     autoCreateSession,
     streaming,
     debug,

package/src/tools/chat/hooks/__tests__/useChat.initialMessages.test.tsx

@@ -0,0 +1,161 @@
+// @vitest-environment jsdom
+//
+// F5 Part 2a — the `initialMessages` warm-hydrate seam.
+//
+// Contract under test (see useChat bootstrap):
+//   1. With `initialSessionId` + non-empty `initialMessages`, the engine renders
+//      the seed synchronously on first commit — `historyLoaded` is already true,
+//      so the host never paints a Spinner (which gates on `!historyLoaded`).
+//   2. The resume-path `loadHistory` STILL runs and REPLACES the seed with the
+//      server's authoritative page (server = source of truth; no stale-read).
+//   3. Empty `initialMessages` (or the create path) is a no-op — normal
+//      loading behaviour, seed ignored.
+import { act, createElement } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+// React needs this global to accept act(...) outside a test-runner integration.
+(globalThis as Record<string, unknown>).IS_REACT_ACT_ENVIRONMENT = true;
+
+import { useChat, type UseChatReturn } from '../useChat';
+import type { ChatMessage } from '../../types';
+import type { ChatTransport } from '../../types/transport';
+import type { HistoryPage, SessionInfo } from '../../types/session';
+
+function msg(id: string, content: string, role: ChatMessage['role'] = 'user'): ChatMessage {
+  return { id, role, content, createdAt: 1 };
+}
+
+/** Transport whose loadHistory resolves only when the test releases it — lets us
+ *  observe the synchronous-seed render BEFORE the server page lands. */
+function deferredTransport(page: HistoryPage): {
+  transport: ChatTransport;
+  resolveHistory: () => void;
+  historyCalls: () => number;
+} {
+  let release!: () => void;
+  const gate = new Promise<void>((r) => {
+    release = r;
+  });
+  let calls = 0;
+  const transport: ChatTransport = {
+    async createSession(): Promise<SessionInfo> {
+      return { sessionId: 'new-session' };
+    },
+    async loadHistory(): Promise<HistoryPage> {
+      calls += 1;
+      await gate;
+      return page;
+    },
+    async *stream() {
+      /* unused */
+    },
+    async send(): Promise<ChatMessage> {
+      return msg('x', 'x', 'assistant');
+    },
+    async closeSession() {
+      /* unused */
+    },
+  };
+  return { transport, resolveHistory: release, historyCalls: () => calls };
+}
+
+describe('useChat — initialMessages warm-hydrate seam', () => {
+  let roots: Root[] = [];
+  beforeEach(() => {
+    roots = [];
+  });
+  afterEach(() => {
+    act(() => roots.forEach((r) => r.unmount()));
+  });
+
+  it('renders the seed synchronously (historyLoaded true, seed messages) on the resume path', async () => {
+    const seed = [msg('s1', 'cached hello'), msg('s2', 'cached reply', 'assistant')];
+    const { transport, historyCalls } = deferredTransport({
+      messages: [msg('h1', 'server hello')],
+      hasMore: false,
+      nextCursor: null,
+    });
+
+    const snaps: UseChatReturn[] = [];
+    const root = createRoot(document.createElement('div'));
+    roots.push(root);
+    await act(async () => {
+      root.render(createElement(function W() {
+        const chat = useChat({ transport, initialSessionId: 'room-1', initialMessages: seed });
+        snaps.push(chat);
+        return null;
+      }));
+    });
+
+    // The seed was committed and the load settled flag is true → no Spinner.
+    const seededSnap = snaps.find((s) => s.messages.length === 2 && s.historyLoaded);
+    expect(seededSnap, 'a snapshot with the 2 seed messages + historyLoaded=true').toBeDefined();
+    expect(seededSnap!.messages.map((m) => m.content)).toEqual(['cached hello', 'cached reply']);
+    expect(seededSnap!.sessionId).toBe('room-1');
+    // loadHistory was invoked (background revalidation is in flight, still gated).
+    expect(historyCalls()).toBe(1);
+  });
+
+  it('replaces the seed with the server page once loadHistory resolves', async () => {
+    const seed = [msg('s1', 'STALE cached')];
+    const serverPage: HistoryPage = {
+      messages: [msg('h1', 'fresh server a'), msg('h2', 'fresh server b', 'assistant')],
+      hasMore: false,
+      nextCursor: null,
+    };
+    const { transport, resolveHistory } = deferredTransport(serverPage);
+
+    const snaps: UseChatReturn[] = [];
+    const root = createRoot(document.createElement('div'));
+    roots.push(root);
+    await act(async () => {
+      root.render(createElement(function W() {
+        const chat = useChat({ transport, initialSessionId: 'room-1', initialMessages: seed });
+        snaps.push(chat);
+        return null;
+      }));
+    });
+    // Release the background load and let the reducer commit HISTORY_LOAD_DONE.
+    await act(async () => {
+      resolveHistory();
+      await Promise.resolve();
+    });
+
+    const last = snaps[snaps.length - 1];
+    expect(last.messages.map((m) => m.content)).toEqual(['fresh server a', 'fresh server b']);
+    expect(last.messages.some((m) => m.content === 'STALE cached')).toBe(false);
+    expect(last.historyLoaded).toBe(true);
+  });
+
+  it('ignores an empty initialMessages array (normal load path)', async () => {
+    const loadHistory = vi.fn(async (): Promise<HistoryPage> => ({
+      messages: [msg('h1', 'server only')],
+      hasMore: false,
+      nextCursor: null,
+    }));
+    const transport = {
+      createSession: async () => ({ sessionId: 'x' }),
+      loadHistory,
+      async *stream() {},
+      send: async () => msg('a', 'a', 'assistant'),
+      closeSession: async () => {},
+    } as unknown as ChatTransport;
+
+    const snaps: UseChatReturn[] = [];
+    const root = createRoot(document.createElement('div'));
+    roots.push(root);
+    await act(async () => {
+      root.render(createElement(function W() {
+        const chat = useChat({ transport, initialSessionId: 'room-1', initialMessages: [] });
+        snaps.push(chat);
+        return null;
+      }));
+    });
+
+    // Empty seed: the load still drives the transcript, no seed shortcut.
+    const last = snaps[snaps.length - 1];
+    expect(last.messages.map((m) => m.content)).toEqual(['server only']);
+    expect(loadHistory).toHaveBeenCalledTimes(1);
+  });
+});

package/src/tools/chat/hooks/useAutoFocusOnStreamEnd.ts

@@ -171,7 +171,12 @@ export function useRegisterComposer(handle: ComposerHandle): void {
   // custom composers (e.g. the TipTap MarkdownEditor wrapper).
   const getValue = handle.getValue;
   const setValue = handle.setValue;
+  // Forward `attachFiles` too — the native OS-drop bridge routes an
+  // intercepted file drop through `getActiveComposer().attachFiles`, so a
+  // custom composer (TipTap MarkdownEditor wrapper) that owns the active
+  // handle must carry it or native drops silently no-op.
+  const attachFiles = handle.attachFiles;
   useEffect(() => {
-    return attachComposer({ focus, moveCursorToEnd, getValue, setValue });
-  }, [focus, moveCursorToEnd, getValue, setValue]);
+    return attachComposer({ focus, moveCursorToEnd, getValue, setValue, attachFiles });
+  }, [focus, moveCursorToEnd, getValue, setValue, attachFiles]);
 }

package/src/tools/chat/hooks/useChat.ts

@@ -25,6 +25,21 @@ import { resolveSendMetadata } from '../core/metadata';
 export interface UseChatConfig {
   transport: ChatTransport;
   initialSessionId?: string;
+  /**
+   * Warm transcript to render synchronously on mount, before the resume-path
+   * `loadHistory` round-trip resolves. When set alongside `initialSessionId`,
+   * the engine seeds these messages and flips `historyLoaded` true immediately
+   * — no blocking Spinner — then still runs `loadHistory` in the background and
+   * REPLACES the seed with the server's authoritative page (via the normal
+   * `HISTORY_LOAD_DONE`). This makes "hydrate instant, revalidate in background"
+   * a first-class engine capability: the host caches the last-seen transcript
+   * (e.g. a per-room store) and passes it here so returning to a conversation
+   * shows content immediately instead of a cold refetch. The server read stays
+   * the source of truth — the seed is a visual head-start, never the last word.
+   *
+   * Ignored on the create path (no `initialSessionId`) and when empty.
+   */
+  initialMessages?: readonly ChatMessage[];
   autoCreateSession?: boolean;
   streaming?: boolean;
   pageSize?: number;
@@ -128,9 +143,34 @@ export function useChat(config: UseChatConfig): UseChatReturn {
       return;
     }
 
+    // Warm-hydrate: on the resume path, if the host handed us a cached
+    // transcript, commit it synchronously so the very first paint shows content
+    // (historyLoaded flips true via SESSION_SET) — no blocking Spinner. The
+    // resume-path `loadHistory` below still runs and REPLACES this seed with the
+    // server's authoritative page (HISTORY_LOAD_DONE), so the server stays the
+    // source of truth; the seed is only a visual head-start.
+    const warmSeed =
+      config.initialSessionId &&
+      config.initialMessages !== undefined &&
+      config.initialMessages.length > 0
+        ? config.initialMessages
+        : null;
+    if (warmSeed) {
+      dispatch({
+        type: 'SESSION_SET',
+        sessionId: config.initialSessionId!,
+        // Copy to a mutable array — the reducer stores it as owned state and the
+        // caller's array may be a frozen cache entry.
+        messages: [...warmSeed],
+      });
+    }
+
     // Show "loading" state immediately so the UI doesn't look idle while we
-    // wait for createSession / loadHistory to come back.
-    if (config.initialSessionId || autoCreateSession) {
+    // wait for createSession / loadHistory to come back. Skipped when we just
+    // warm-seeded — HISTORY_LOAD_START would set isLoading without clearing the
+    // seed, and the UI already has content to show; the background loadHistory
+    // reconciles without a spinner.
+    if (!warmSeed && (config.initialSessionId || autoCreateSession)) {
       dispatch({ type: 'HISTORY_LOAD_START' });
     }
 

package/src/tools/chat/messages/Attachments.tsx

@@ -130,6 +130,10 @@ function ImageLightboxProvider({
               initialIndex={index}
               lightbox
               autoFocus
+              // Open at 80% of the viewport so the image sits with a comfortable
+              // margin (Preview / Quick Look) instead of slamming edge-to-edge;
+              // zoom/pan still reach full size from there.
+              fitScale={0.8}
               onRequestClose={() => setOpen(false)}
             />
           )}

package/src/tools/chat/messages/MessageList.tsx

@@ -140,7 +140,26 @@ export const MessageList = forwardRef<MessageListHandle, MessageListProps>(funct
   // ResizeObserver (to correct virtuoso's `followOutput:'auto'`, which
   // settles a few px short on the final streamed chunk) and any other
   // "land exactly at end" path.
+  //
+  // The INSTANT pin (smooth=false) — which the ResizeObserver fires on every
+  // last-bubble size change and on the send transition — writes `scrollTop`
+  // DIRECTLY rather than going through `scrollToIndex`. This is the same
+  // technique the initial-landing phase uses (see the land loop below) and for
+  // the same reason: `scrollToIndex` re-enters virtuoso's initial-location
+  // SEEK, which on a list whose new last item is still being measured (exactly
+  // the send moment, when the empty assistant placeholder just mounted) can
+  // momentarily reflow/blank rows — visible as a twitch. A direct scrollTop
+  // write is an ordinary scroll to virtuoso, never a seek, so it lands cleanly.
+  // The smooth path (user tapped "jump to latest") keeps `scrollToIndex` — a
+  // seek is fine there because it's a deliberate one-shot, not a per-frame pin.
   const pinToBottom = useCallback((smooth = false) => {
+    if (!smooth) {
+      const el = scrollerRef.current;
+      if (el != null && el !== window && el instanceof HTMLElement) {
+        el.scrollTop = el.scrollHeight - el.clientHeight;
+        return;
+      }
+    }
     virtuosoRef.current?.scrollToIndex({
       index: 'LAST',
       align: 'end',
@@ -277,9 +296,26 @@ export const MessageList = forwardRef<MessageListHandle, MessageListProps>(funct
   // otherwise the call lands on the previous height and clips the new
   // message under the composer. The initial-mount effect above handles
   // first paint, so we skip until it has run.
+  //
+  // JITTER on send (live incident 2026-07-05: "чат дёргается при отправке"):
+  // a send appends TWO items a tick apart — the user bubble, then the empty
+  // assistant placeholder (STREAM_START). When the user is already at the
+  // bottom (the common case — they just sent), the last-item ResizeObserver's
+  // `pinToBottom` INSTANTLY lands them on the placeholder as it mounts/grows.
+  // A SECOND, `smooth` `scrollToIndex('LAST')` fired from here then animates
+  // into that instant pin — the smooth glide gets yanked mid-flight and reads
+  // as a twitch. Two corrections:
+  //   1. When the user is following (`isFollowingRef`), the sticky corrector
+  //      already owns the landing — DON'T also fire the anchor scroll. It is
+  //      only needed to pull a SCROLLED-UP user back down on their own send.
+  //   2. Use `behavior:'auto'` (instant), not `'smooth'`: a send should snap,
+  //      and an instant scroll can't be visibly interrupted by the pin.
   useEffect(() => {
     if (scrollAnchorId == null) return;
     if (!didInitialScrollRef.current) return;
+    // At-bottom users are landed by the sticky corrector; re-issuing a scroll
+    // here only collides with it. Skip — the pin has it covered.
+    if (isFollowingRef.current) return;
     let raf1 = 0;
     let raf2 = 0;
     raf1 = requestAnimationFrame(() => {
@@ -288,7 +324,7 @@ export const MessageList = forwardRef<MessageListHandle, MessageListProps>(funct
           index: 'LAST',
           align: 'end',
           offset: BOTTOM_GAP_PX,
-          behavior: 'smooth',
+          behavior: 'auto',
         });
       });
     });

package/src/tools/chat/shell/ChatRoot.tsx

@@ -136,8 +136,18 @@ export interface ChatRootProps {
    */
   transport?: ChatTransport;
   config?: ChatConfig;
-  /** Session wiring — pre-existing id to attach, auto-create toggle. */
-  session?: { initialId?: string; autoCreate?: boolean };
+  /**
+   * Session wiring — pre-existing id to attach, auto-create toggle, and an
+   * optional warm transcript. `initialMessages` (with `initialId`) renders the
+   * cached conversation instantly on mount while the server history revalidates
+   * in the background — see `ChatProvider` / `useChat`. The host owns the cache
+   * (e.g. a per-room store); the server load stays the source of truth.
+   */
+  session?: {
+    initialId?: string;
+    autoCreate?: boolean;
+    initialMessages?: readonly ChatMessage[];
+  };
   streaming?: boolean;
   /** Audio-trigger configuration. Off by default (no `sounds` map). */
   audio?: ChatAudioConfig;
@@ -210,6 +220,7 @@ export function ChatRoot(props: ChatRootProps) {
       transport={transport}
       config={config}
       initialSessionId={session?.initialId}
+      initialMessages={session?.initialMessages}
       autoCreateSession={session?.autoCreate}
       streaming={streaming}
       audio={audio}

package/src/tools/integration/ComposerRegistry/index.ts

@@ -22,6 +22,13 @@ export interface ComposerHandle {
    *  and final transcripts through this without owning a controlled
    *  binding. */
   setValue?: (value: string) => void;
+  /** Attach already-resolved files through the composer's validated attach
+   *  pipeline (size / type / count checks + upload + staging tray) — the
+   *  same entry point the paperclip, paste and drag-drop use. Present only
+   *  when the composer mounts the attach pipeline. A native shell (WKWebView /
+   *  WebView2) that intercepts an OS file drop hands the bytes here so a
+   *  native drop behaves exactly like an in-page one. */
+  attachFiles?: (files: File[]) => void;
 }
 
 /**

package/src/tools/media/ImageViewer/components/ImageViewer.tsx

@@ -56,12 +56,22 @@ export function ImageViewer({
   lightbox = false,
   onRequestClose,
   autoFocus = false,
+  fitScale = 1,
 }: ImageViewerProps) {
   const t = useAppT();
 
   // `lightbox` implies the in-dialog presentation.
   const isLightbox = lightbox || inDialog;
 
+  // Cap the at-rest image size to `fitScale` of the viewport in the lightbox so
+  // it opens with a margin instead of edge-to-edge. Clamp to a sane range; a
+  // value of 1 (the default) is a no-op (falls back to the max-w/h-full class).
+  const fit = Math.min(1, Math.max(0.1, fitScale));
+  const fitStyle: React.CSSProperties | undefined =
+    isLightbox && fit < 1
+      ? { maxWidth: `${fit * 100}%`, maxHeight: `${fit * 100}%` }
+      : undefined;
+
   const [currentIndex, setCurrentIndex] = useState(() =>
     Math.max(0, Math.min(initialIndex, images.length - 1))
   );
@@ -80,6 +90,7 @@ export function ImageViewer({
   const [imgDecoded, setImgDecoded] = useState(false);
   const containerRef = useRef<HTMLDivElement>(null);
   const controlsRef = useRef<ReactZoomPanPinchRef | null>(null);
+  const imgRef = useRef<HTMLImageElement>(null);
 
   // Idle-fading chrome (lightbox only). Pointer movement over the canvas keeps
   // the controls visible; resting for CHROME_IDLE_MS fades them out.
@@ -107,10 +118,25 @@ export function ImageViewer({
     src: current?.src,
   });
 
-  // Reset per-source load flags whenever the source changes
+  // Reset per-source load flags whenever the source changes.
+  //
+  // Race guard (first-open stuck on "Loading…"): the `<img onLoad>` handler is
+  // the ONLY thing that clears `imgDecoded`, but the browser can finish
+  // decoding — and fire `load` — BEFORE React commits the element and attaches
+  // that handler (a same-origin blob/attachment URL that resolves synchronously,
+  // or an already-cached image). The event is then missed and the spinner hangs
+  // forever; reopening "fixes" it only because the fresh mount happens to win
+  // the race. So after resetting, synchronously reconcile against the live img:
+  // if it's already `complete` with real pixels, mark it decoded now instead of
+  // waiting for an onLoad that already fired.
   useEffect(() => {
     setLoadError(false);
-    setImgDecoded(false);
+    const img = imgRef.current;
+    if (img && img.complete && img.naturalWidth > 0) {
+      setImgDecoded(true);
+    } else {
+      setImgDecoded(false);
+    }
   }, [src]);
 
   const { transform, rotate, flipH, flipV, transformStyle } = useImageTransform({
@@ -344,12 +370,13 @@ export function ImageViewer({
                 alt=""
                 aria-hidden="true"
                 className="absolute max-w-full max-h-full object-contain select-none"
-                style={{ transform: transformStyle, filter: 'blur(20px)', transition: 'opacity 0.3s ease-out', opacity: isFullyLoaded ? 0 : 1 }}
+                style={{ transform: transformStyle, filter: 'blur(20px)', transition: 'opacity 0.3s ease-out', opacity: isFullyLoaded ? 0 : 1, ...fitStyle }}
                 draggable={false}
               />
             )}
             {src && (
               <img
+                ref={imgRef}
                 src={src}
                 alt={current.file.name}
                 className={cn(
@@ -363,6 +390,7 @@ export function ImageViewer({
                   transition: 'transform 0.15s ease-out, opacity 0.3s ease-out',
                   opacity:
                     (useProgressiveLoading && !isFullyLoaded) || !imgDecoded ? 0 : 1,
+                  ...fitStyle,
                 }}
                 draggable={false}
                 onLoad={() => setImgDecoded(true)}

package/src/tools/media/ImageViewer/types.ts

@@ -53,6 +53,15 @@ export interface ImageViewerProps {
   lightbox?: boolean;
   /** Close request from the lightbox chrome (Esc / close button). */
   onRequestClose?: () => void;
+  /**
+   * Fraction of the viewport the image may occupy at rest, in the LIGHTBOX
+   * presentation only (0 < fitScale ≤ 1). `1` (default) lets the image fill
+   * edge-to-edge; `0.8` caps it at 80% so it opens with a comfortable margin
+   * (Preview / Quick Look style) instead of slamming into the window edges.
+   * Zoom / pan still operate from this fitted size. Ignored in the embedded
+   * (non-lightbox) presentation.
+   */
+  fitScale?: number;
   /** Focus the viewer container on mount so its keyboard scope is active
    *  immediately (zoom/rotate/gallery hotkeys). Pair with `key={src}`
    *  upstream when the parent wants a fresh focus per source change. */