@jini-ai/chat 0.3.7 → 0.3.8

package/dist/react/hooks/composer-draft-cache.js

@@ -1,89 +1,407 @@
 /**
  * @module composer-draft-cache
  *
- * Per-conversation composer draft cache, keyed by conversation id. Exists so switching away from a
- * conversation and back round-trips whatever the operator was typing — even when the host remounts
- * `ChatPane` on switch (a React `key` keyed to the selected conversation, so a user-initiated switch
- * re-seeds the transcript from `initialMessages` — a documented pattern for this component: the pane
- * owns its own transcript and takes no `conversationId`-change effect of its own) — with zero host
- * wiring required. `useComposer.ts` reads/writes this on every
- * `conversationId` it is given; a host that also wants the draft to survive a page *reload* layers
- * its own `persistence` (`ComposerDraftPersistence`) on top, unkeyed, exactly as documented there.
- *
- * This is intentionally NOT the same seam as `ComposerDraftPersistence`: that one is a single opaque
- * host-owned slot (e.g. localStorage) that `useComposer` must never touch directly (see that
- * module's doc). This cache lives in module scope instead, purely in memory, so it survives a
- * `ChatPane` remount within the same page session — it does not, and is not meant to, survive a
- * reload.
+ * Per-conversation composer draft cache, keyed by conversation id. Exists so whatever the operator
+ * was typing comes back — across a `ChatPane` remount (a host re-keying the pane on a conversation
+ * switch, so a user-initiated switch re-seeds the transcript from `initialMessages` — a documented
+ * pattern for this component: the pane owns its own transcript and takes no `conversationId`-change
+ * effect of its own), across a navigation away and back, and across a full page reload or a server
+ * restart that takes the page down with it. `useComposer.ts` reads/writes this on every
+ * `conversationId` it is given, with zero host wiring required.
+ *
+ * Two tiers, same key:
+ * - a module-level `Map`, which answers instantly and is the only tier that works when storage is
+ *   unavailable;
+ * - `localStorage` under {@link COMPOSER_DRAFT_STORAGE_PREFIX}, which is what actually survives a
+ *   reload. Every access is wrapped: a private window, blocked site data, a quota rejection, or a
+ *   non-browser runtime degrades this module to memory-only. It never throws at a caller and it
+ *   never returns a wiped draft in place of a live one — a failed read falls back to the in-memory
+ *   tier rather than reporting "no draft".
+ *
+ * Durability is deliberately NOT gated behind `ComposerDraftPersistence` (`useComposer`'s
+ * host-supplied port). That port is a single opaque host-owned slot with no conversation key, and
+ * grep across every known host finds nothing passing it — an opt-in seam nobody opted into would
+ * not have fixed the reported bug (an operator lost a half-written message to a site-server
+ * restart, 2026-09-18). The port still works and still takes precedence at mount for a host that
+ * wires one.
+ *
+ * Scope limits worth knowing: `localStorage` is per-browser and per-origin, so a draft never
+ * reaches the server, never follows the operator to another machine, and is visible to anything
+ * else running on that origin. Two tabs open on the same conversation last-write-wins. None of
+ * that is a regression — before this, the draft simply did not survive at all.
  *
  * @tradeoffs A module-level singleton (rather than a per-instance store a host constructs and
- * passes down) was chosen so the fix works for every host with no new prop plumbing — known hosts of
- * this package do not wire a `persistence` port today, so a purely opt-in fix would not have fixed
- * the reported bug. The risk a singleton usually carries — two unrelated call sites sharing
- * state that should be isolated (see `create-daemon-attachment-uploader.ts`'s per-uploader
- * `batchUsage` map, which exists for exactly that reason) — does not apply the same way here: the
- * partition key (`conversationId`) is already globally unique per backend, so two `ChatPane`
- * instances showing two different conversations can never collide on it. Tests must call
- * {@link __resetComposerDraftCacheForTests} between cases to avoid cross-test leakage; that is the
- * real cost of this choice.
- *
- * Bounded to `MAX_CACHED_CONVERSATION_DRAFTS` distinct conversations so a long session visiting many
- * conversations cannot grow this map without limit — the oldest-inserted entry is evicted once the
- * cap is exceeded. A cleared/empty draft is deleted outright rather than kept as `''`, so the common
- * case (drafted, then sent) does not linger in the cache at all.
- */
-/** Cap on distinct conversations tracked at once; see the module doc's `@tradeoffs`. */
+ * passes down) was chosen so the fix works for every host with no new prop plumbing. The risk a
+ * singleton usually carries — two unrelated call sites sharing state that should be isolated (see
+ * `create-daemon-attachment-uploader.ts`'s per-uploader `batchUsage` map, which exists for exactly
+ * that reason) — does not apply the same way here: the partition key (`conversationId`) is already
+ * globally unique per backend, so two `ChatPane` instances showing two different conversations can
+ * never collide on it. Tests must call {@link __resetComposerDraftCacheForTests} between cases to
+ * avoid cross-test leakage; that is the real cost of this choice.
+ *
+ * Both tiers are bounded to `MAX_CACHED_CONVERSATION_DRAFTS` distinct conversations so a long
+ * session visiting many conversations cannot grow without limit — the oldest entry is evicted once
+ * the cap is exceeded (insertion order in memory, stored timestamp in storage, since storage
+ * outlives insertion order). A cleared/empty draft is deleted from both tiers outright rather than
+ * kept as `''`, so the common case (drafted, then sent) leaves nothing behind to resurrect on the
+ * next load.
+ */
+/** Cap on distinct conversations tracked at once, per tier; see the module doc's `@tradeoffs`. */
 export const MAX_CACHED_CONVERSATION_DRAFTS = 50;
+/**
+ * Key prefix for the `localStorage` tier. Versioned (`.v1.`) so a future change to the stored shape
+ * can be introduced without having to interpret, or mis-interpret, entries written by this one.
+ */
+export const COMPOSER_DRAFT_STORAGE_PREFIX = 'jini.chat.composer-draft.v1.';
+/**
+ * Key prefix for a conversation's staged attachment REFERENCES. Deliberately a separate entry from
+ * the draft text rather than one combined record: text and attachments must degrade independently,
+ * so a corrupt or unwritable attachment entry can never cost the operator their words, and vice
+ * versa. See {@link readCachedAttachments} for what these references are and are not.
+ */
+export const COMPOSER_ATTACHMENTS_STORAGE_PREFIX = 'jini.chat.composer-attachments.v1.';
 const drafts = new Map();
+const stagedAttachments = new Map();
 /**
- * Reads the cached draft for `conversationId`.
+ * The origin's `localStorage`, or `null` when it cannot be used.
  *
- * @returns The cached draft, or `null` when there is none — including when `conversationId` itself
- * is absent (an untitled/new conversation has nothing to key on yet).
+ * @returns `null` in a non-browser runtime (SSR, a node-environment test) and in a browser that
+ * throws on the property access itself — Safari and Chrome both do that with site data blocked,
+ * which is why this is a try/catch rather than a `typeof` check alone.
  * @complexity Time/space: O(1).
  */
+function storage() {
+    try {
+        return typeof localStorage === 'undefined' ? null : localStorage;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Reads and validates the stored draft for `conversationId`.
+ *
+ * Anything that does not parse as this module's own envelope is treated as foreign or corrupt and
+ * deleted rather than returned — a stale format, another tool writing under a colliding key, or a
+ * truncated write must not surface as composer text.
+ *
+ * @returns The stored draft, or `null` when there is none, storage is unavailable, or the entry
+ * failed validation.
+ * @complexity Time/space: O(n) in the stored draft's length (the JSON parse).
+ */
+function readStoredDraft(conversationId) {
+    const store = storage();
+    if (!store)
+        return null;
+    const key = `${COMPOSER_DRAFT_STORAGE_PREFIX}${conversationId}`;
+    try {
+        const raw = store.getItem(key);
+        if (raw === null)
+            return null;
+        const parsed = JSON.parse(raw);
+        const draft = parsed?.d;
+        if (typeof draft !== 'string' || draft === '') {
+            store.removeItem(key);
+            return null;
+        }
+        return draft;
+    }
+    catch {
+        // A parse failure leaves the bad entry behind on purpose when `removeItem` is what threw —
+        // there is nothing further this module can do, and memory-only is still a working composer.
+        try {
+            store.removeItem(key);
+        }
+        catch {
+            /* storage is unusable; the in-memory tier still serves this conversation */
+        }
+        return null;
+    }
+}
+/**
+ * Deletes every stored draft past the cap, oldest write first, so an operator who abandons drafts
+ * in many conversations cannot fill the origin's quota and silently break persistence for the
+ * conversation they actually care about.
+ *
+ * @param keep How many entries may remain. Entries whose envelope does not parse are treated as
+ * oldest (timestamp `0`) so corrupt rows are the first to go.
+ * @complexity Time O(n log n) in the number of this module's stored keys (a sort), bounded in
+ * practice by `MAX_CACHED_CONVERSATION_DRAFTS` plus whatever a previous session left behind. Space
+ * O(n) in the same.
+ */
+function pruneStored(prefix, keep) {
+    const store = storage();
+    if (!store)
+        return;
+    try {
+        const entries = [];
+        for (let i = 0; i < store.length; i += 1) {
+            const key = store.key(i);
+            if (key === null || !key.startsWith(prefix))
+                continue;
+            let at = 0;
+            try {
+                const parsed = JSON.parse(store.getItem(key) ?? '');
+                at = typeof parsed?.t === 'number' ? parsed.t : 0;
+            }
+            catch {
+                at = 0;
+            }
+            entries.push({ key, at });
+        }
+        if (entries.length <= keep)
+            return;
+        entries.sort((a, b) => a.at - b.at);
+        for (const entry of entries.slice(0, entries.length - keep))
+            store.removeItem(entry.key);
+    }
+    catch {
+        /* storage is unusable; nothing to prune and nothing to report */
+    }
+}
+/**
+ * Writes or removes the stored copy for `conversationId`.
+ *
+ * @param draft A blank draft removes the entry. A quota rejection is swallowed: the in-memory tier
+ * has already accepted the draft, so the composer keeps working and only reload-survival is lost.
+ * @complexity Time O(n) in the draft's length, plus a prune (see {@link pruneStored}) only
+ * when this introduces a new key at the cap. Space O(n) in the draft's length.
+ */
+function writeStoredDraft(conversationId, draft) {
+    const store = storage();
+    if (!store)
+        return;
+    const key = `${COMPOSER_DRAFT_STORAGE_PREFIX}${conversationId}`;
+    try {
+        if (draft === '') {
+            store.removeItem(key);
+            return;
+        }
+        if (store.getItem(key) === null)
+            pruneStored(COMPOSER_DRAFT_STORAGE_PREFIX, MAX_CACHED_CONVERSATION_DRAFTS - 1);
+        const envelope = { v: 1, t: Date.now(), d: draft };
+        store.setItem(key, JSON.stringify(envelope));
+    }
+    catch {
+        /* blocked, full, or unusable storage — memory-only is the documented degraded mode */
+    }
+}
+/**
+ * Records `draft` in the in-memory tier, evicting the oldest-inserted conversation first if this
+ * would introduce a new entry past {@link MAX_CACHED_CONVERSATION_DRAFTS}.
+ * @complexity Time/space: O(1) amortized.
+ */
+function rememberInMemory(conversationId, draft) {
+    if (!drafts.has(conversationId) && drafts.size >= MAX_CACHED_CONVERSATION_DRAFTS) {
+        const oldest = drafts.keys().next().value;
+        if (oldest !== undefined)
+            drafts.delete(oldest);
+    }
+    drafts.set(conversationId, draft);
+}
+/**
+ * Reads the cached draft for `conversationId`, in memory first and storage second.
+ *
+ * A storage hit is promoted into memory so the reload-survival path costs one read, not one per
+ * keystroke-triggered re-render.
+ *
+ * @returns The cached draft, or `null` when there is none — including when `conversationId` itself
+ * is absent (an untitled/new conversation has nothing to key on yet). Never returns `''`; callers
+ * treat `null` as "nothing to restore".
+ * @complexity Time/space: O(1) on an in-memory hit, O(n) in the stored draft's length otherwise.
+ */
 export function readCachedDraft(conversationId) {
     if (!conversationId)
         return null;
-    return drafts.get(conversationId) ?? null;
+    const remembered = drafts.get(conversationId);
+    if (remembered !== undefined)
+        return remembered;
+    const stored = readStoredDraft(conversationId);
+    if (stored === null)
+        return null;
+    rememberInMemory(conversationId, stored);
+    return stored;
 }
 /**
- * Stores `draft` for `conversationId`, evicting the oldest tracked conversation first if this would
- * introduce a new entry past {@link MAX_CACHED_CONVERSATION_DRAFTS}.
+ * Stores `draft` for `conversationId` in both tiers.
  *
  * @param conversationId No-ops when absent (`null`/`undefined`) — there is nothing to key on yet.
- * @param draft A blank (or whitespace-only) draft deletes the entry instead of storing `''`; see the
- * module doc's cleanup note.
- * @complexity Time/space: O(1) amortized.
+ * `useComposer` covers that window by adopting the typed text once an id arrives; see its own doc.
+ * @param draft A blank (or whitespace-only) draft deletes the entry from both tiers instead of
+ * storing `''`. This is what makes a successful send clear the draft for free: `useComposer.reset`
+ * writes `''` here.
+ * @complexity Time/space: O(n) in the draft's length; see {@link writeStoredDraft}.
  */
 export function writeCachedDraft(conversationId, draft) {
     if (!conversationId)
         return;
     if (draft.trim() === '') {
         drafts.delete(conversationId);
+        writeStoredDraft(conversationId, '');
         return;
     }
-    if (!drafts.has(conversationId) && drafts.size >= MAX_CACHED_CONVERSATION_DRAFTS) {
-        const oldest = drafts.keys().next().value;
-        if (oldest !== undefined)
-            drafts.delete(oldest);
-    }
-    drafts.set(conversationId, draft);
+    rememberInMemory(conversationId, draft);
+    writeStoredDraft(conversationId, draft);
 }
 /**
- * Explicitly evicts `conversationId`'s cached draft, for a host that wants to free it immediately
- * (e.g. on conversation delete) rather than waiting for the cap-triggered eviction above. Not
- * currently called by any host — a host's own conversation-delete flow is a candidate follow-up
- * caller, out of scope here (that flow lives outside this package).
+ * Explicitly evicts `conversationId`'s draft from both tiers, for a host that wants to free it
+ * immediately (e.g. on conversation delete) rather than waiting for the cap-triggered eviction.
+ * Not currently called by any host — a host's own conversation-delete flow is a candidate
+ * follow-up caller, out of scope here (that flow lives outside this package).
  * @complexity Time/space: O(1).
  */
 export function clearCachedDraft(conversationId) {
     if (!conversationId)
         return;
     drafts.delete(conversationId);
+    writeStoredDraft(conversationId, '');
+    writeCachedAttachments(conversationId, []);
 }
-/** Test-only: empties the module-level cache so test cases cannot leak drafts into each other. */
-export function __resetComposerDraftCacheForTests() {
+/**
+ * Narrows one parsed array element to a `ChatAttachment`.
+ *
+ * Validated field by field rather than trusted, for the same reason the draft envelope is: this
+ * data came back from storage, where anything on the origin could have written it. `size`/`order`
+ * are optional in the type, so they are checked only when present.
+ * @complexity Time/space: O(1).
+ */
+function isChatAttachment(candidate) {
+    if (typeof candidate !== 'object' || candidate === null)
+        return false;
+    const { path, name, kind, size, order } = candidate;
+    if (typeof path !== 'string' || path === '')
+        return false;
+    if (typeof name !== 'string')
+        return false;
+    if (kind !== 'image' && kind !== 'file')
+        return false;
+    if (size !== undefined && typeof size !== 'number')
+        return false;
+    if (order !== undefined && typeof order !== 'number')
+        return false;
+    return true;
+}
+/**
+ * Reads the stored attachment references for `conversationId`.
+ *
+ * Elements that do not validate are dropped individually rather than failing the whole entry — one
+ * malformed row should cost the operator that row, not every attachment on the turn.
+ *
+ * @returns The stored references, or `null` when there are none, storage is unavailable, or nothing
+ * in the entry validated.
+ * @complexity Time/space: O(n) in the number of stored references.
+ */
+function readStoredAttachments(conversationId) {
+    const store = storage();
+    if (!store)
+        return null;
+    const key = `${COMPOSER_ATTACHMENTS_STORAGE_PREFIX}${conversationId}`;
+    try {
+        const raw = store.getItem(key);
+        if (raw === null)
+            return null;
+        const parsed = JSON.parse(raw);
+        const list = parsed?.a;
+        if (!Array.isArray(list)) {
+            store.removeItem(key);
+            return null;
+        }
+        const valid = list.filter(isChatAttachment);
+        if (valid.length === 0) {
+            store.removeItem(key);
+            return null;
+        }
+        return valid;
+    }
+    catch {
+        try {
+            store.removeItem(key);
+        }
+        catch {
+            /* storage is unusable; the in-memory tier still serves this conversation */
+        }
+        return null;
+    }
+}
+/**
+ * Reads the cached attachment references for `conversationId`, in memory first, storage second.
+ *
+ * **These are references, never bytes.** By the time an attachment reaches the composer it has
+ * already been uploaded (`ChatPane` blocks sending while uploads are in flight), so what is cached
+ * here is the server-side record — a path, a name, a kind. The file itself lives wherever the host
+ * put it and is subject to that host's retention, which is why a caller must not treat a returned
+ * reference as proof the file still exists. `useComposer` restores these only when the host supplies
+ * a validator; see its `validateAttachments` option.
+ *
+ * @returns The cached references, or `null` when there are none.
+ * @complexity Time/space: O(1) on an in-memory hit, O(n) in the stored count otherwise.
+ */
+export function readCachedAttachments(conversationId) {
+    if (!conversationId)
+        return null;
+    const remembered = stagedAttachments.get(conversationId);
+    if (remembered !== undefined)
+        return remembered;
+    const stored = readStoredAttachments(conversationId);
+    if (stored === null)
+        return null;
+    stagedAttachments.set(conversationId, stored);
+    return stored;
+}
+/**
+ * Stores `attachments` for `conversationId` in both tiers.
+ *
+ * @param attachments An empty list deletes the entry, so a sent or cleared turn leaves nothing to
+ * restore — the same rule the draft text follows.
+ * @complexity Time/space: O(n) in the number of references.
+ */
+export function writeCachedAttachments(conversationId, attachments) {
+    if (!conversationId)
+        return;
+    const key = `${COMPOSER_ATTACHMENTS_STORAGE_PREFIX}${conversationId}`;
+    const store = storage();
+    if (attachments.length === 0) {
+        stagedAttachments.delete(conversationId);
+        try {
+            store?.removeItem(key);
+        }
+        catch {
+            /* blocked storage; the in-memory tier is already correct */
+        }
+        return;
+    }
+    if (!stagedAttachments.has(conversationId) && stagedAttachments.size >= MAX_CACHED_CONVERSATION_DRAFTS) {
+        const oldest = stagedAttachments.keys().next().value;
+        if (oldest !== undefined)
+            stagedAttachments.delete(oldest);
+    }
+    stagedAttachments.set(conversationId, attachments);
+    if (!store)
+        return;
+    try {
+        if (store.getItem(key) === null)
+            pruneStored(COMPOSER_ATTACHMENTS_STORAGE_PREFIX, MAX_CACHED_CONVERSATION_DRAFTS - 1);
+        const envelope = { v: 1, t: Date.now(), a: attachments };
+        store.setItem(key, JSON.stringify(envelope));
+    }
+    catch {
+        /* blocked, full, or unusable storage — memory-only is the documented degraded mode */
+    }
+}
+/**
+ * Test-only: empties the cache so test cases cannot leak drafts into each other.
+ *
+ * @param options `keepStorage: true` empties only the in-memory tier, leaving `localStorage`
+ * intact. That is the honest simulation of a page reload — fresh module scope, storage that
+ * outlived it — and is how the durability tests reproduce the bug this module exists to fix.
+ * @complexity Time O(n) in the number of this module's stored keys; space O(n) in the same.
+ */
+export function __resetComposerDraftCacheForTests(options) {
     drafts.clear();
+    stagedAttachments.clear();
+    if (options?.keepStorage === true)
+        return;
+    pruneStored(COMPOSER_DRAFT_STORAGE_PREFIX, 0);
+    pruneStored(COMPOSER_ATTACHMENTS_STORAGE_PREFIX, 0);
 }
 //# sourceMappingURL=composer-draft-cache.js.map

package/dist/react/hooks/composer-draft-cache.js.map

@@ -1 +1 @@
-{"version":3,"file":"composer-draft-cache.js","sourceRoot":"","sources":["../../../src/react/hooks/composer-draft-cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,wFAAwF;AACxF,MAAM,CAAC,MAAM,8BAA8B,GAAG,EAAE,CAAC;AAEjD,MAAM,MAAM,GAAG,IAAI,GAAG,EAAkB,CAAC;AAEzC;;;;;;GAMG;AACH,MAAM,UAAU,eAAe,CAAC,cAAyC;IACvE,IAAI,CAAC,cAAc;QAAE,OAAO,IAAI,CAAC;IACjC,OAAO,MAAM,CAAC,GAAG,CAAC,cAAc,CAAC,IAAI,IAAI,CAAC;AAC5C,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,gBAAgB,CAAC,cAAyC,EAAE,KAAa;IACvF,IAAI,CAAC,cAAc;QAAE,OAAO;IAC5B,IAAI,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;QACxB,MAAM,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC;QAC9B,OAAO;IACT,CAAC;IACD,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,cAAc,CAAC,IAAI,MAAM,CAAC,IAAI,IAAI,8BAA8B,EAAE,CAAC;QACjF,MAAM,MAAM,GAAG,MAAM,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC;QAC1C,IAAI,MAAM,KAAK,SAAS;YAAE,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAClD,CAAC;IACD,MAAM,CAAC,GAAG,CAAC,cAAc,EAAE,KAAK,CAAC,CAAC;AACpC,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,gBAAgB,CAAC,cAAyC;IACxE,IAAI,CAAC,cAAc;QAAE,OAAO;IAC5B,MAAM,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC;AAChC,CAAC;AAED,kGAAkG;AAClG,MAAM,UAAU,iCAAiC;IAC/C,MAAM,CAAC,KAAK,EAAE,CAAC;AACjB,CAAC"}
+{"version":3,"file":"composer-draft-cache.js","sourceRoot":"","sources":["../../../src/react/hooks/composer-draft-cache.ts"],"names":[],"mappings":"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"}

package/dist/react/hooks/useComposer.d.ts

@@ -17,6 +17,23 @@ export interface UseComposerOptions {
      * exists.
      */
     conversationId?: string | null;
+    /**
+     * Confirms which of a conversation's previously staged attachments still exist, so a restored
+     * draft never shows a chip for a file the host has since garbage-collected — that looks intact and
+     * then fails at send, which is worse than not restoring it at all.
+     *
+     * Receives the cached references and returns the subset still valid (order need not be preserved;
+     * an empty array means none survived). A rejection is treated as "none survived" — restoring
+     * unverified references is the failure mode this option exists to prevent.
+     *
+     * **Omitting it disables attachment persistence entirely** — nothing is written and nothing is
+     * restored, which is exactly the behavior before this option existed. Only the draft TEXT is
+     * persisted then, so a host that cannot answer the liveness question loses nothing and risks
+     * nothing. Text and attachments are stored under separate keys and degrade independently.
+     *
+     * Captured in a ref, so an inline arrow is safe and will not re-run the restore on every render.
+     */
+    validateAttachments?: (attachments: readonly ChatAttachment[]) => Promise<readonly ChatAttachment[]>;
 }
 export interface MentionPopoverState {
     open: boolean;

package/dist/react/hooks/useComposer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useComposer.d.ts","sourceRoot":"","sources":["../../../src/react/hooks/useComposer.ts"],"names":[],"mappings":"AA8BA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAG1D,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAErG,MAAM,WAAW,wBAAwB;IACvC,IAAI,EAAE,MAAM,MAAM,GAAG,IAAI,CAAC;IAC1B,KAAK,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;CAChC;AAED,MAAM,WAAW,kBAAkB;IACjC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,YAAY,CAAC,EAAE,cAAc,CAAC;IAC9B,OAAO,CAAC,EAAE,mBAAmB,CAAC;IAC9B,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B,WAAW,CAAC,EAAE,wBAAwB,CAAC;IACvC;;;;;OAKG;IACH,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAChC;AAED,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,OAAO,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,aAAa,EAAE,CAAC;CAC1B;AAED,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACjC,WAAW,EAAE,cAAc,EAAE,CAAC;IAC9B,+IAA+I;IAC/I,cAAc,EAAE,CAAC,KAAK,EAAE,IAAI,EAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACjD,aAAa,EAAE,CAAC,UAAU,EAAE,cAAc,KAAK,IAAI,CAAC;IACpD,gBAAgB,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;IACvC,gBAAgB,EAAE,MAAM,IAAI,CAAC;IAC7B,KAAK,EAAE,cAAc,GAAG,SAAS,CAAC;IAClC,QAAQ,EAAE,CAAC,IAAI,EAAE,cAAc,KAAK,IAAI,CAAC;IACzC,OAAO,EAAE,mBAAmB,CAAC;IAC7B,WAAW,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9C,YAAY,EAAE,MAAM,IAAI,CAAC;IACzB,gHAAgH;IAChH,aAAa,EAAE,CAAC,MAAM,EAAE,aAAa,KAAK,IAAI,CAAC;IAC/C,yGAAyG;IACzG,SAAS,EAAE,OAAO,CAAC;IACnB,gFAAgF;IAChF,KAAK,EAAE,MAAM,IAAI,CAAC;CACnB;AAID,wBAAgB,WAAW,CAAC,OAAO,GAAE,kBAAuB,GAAG,iBAAiB,CA6H/E"}
+{"version":3,"file":"useComposer.d.ts","sourceRoot":"","sources":["../../../src/react/hooks/useComposer.ts"],"names":[],"mappings":"AA8BA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAQ1D,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAErG,MAAM,WAAW,wBAAwB;IACvC,IAAI,EAAE,MAAM,MAAM,GAAG,IAAI,CAAC;IAC1B,KAAK,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;CAChC;AAED,MAAM,WAAW,kBAAkB;IACjC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,YAAY,CAAC,EAAE,cAAc,CAAC;IAC9B,OAAO,CAAC,EAAE,mBAAmB,CAAC;IAC9B,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B,WAAW,CAAC,EAAE,wBAAwB,CAAC;IACvC;;;;;OAKG;IACH,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B;;;;;;;;;;;;;;;OAeG;IACH,mBAAmB,CAAC,EAAE,CAAC,WAAW,EAAE,SAAS,cAAc,EAAE,KAAK,OAAO,CAAC,SAAS,cAAc,EAAE,CAAC,CAAC;CACtG;AAED,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,OAAO,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,aAAa,EAAE,CAAC;CAC1B;AAED,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACjC,WAAW,EAAE,cAAc,EAAE,CAAC;IAC9B,+IAA+I;IAC/I,cAAc,EAAE,CAAC,KAAK,EAAE,IAAI,EAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACjD,aAAa,EAAE,CAAC,UAAU,EAAE,cAAc,KAAK,IAAI,CAAC;IACpD,gBAAgB,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;IACvC,gBAAgB,EAAE,MAAM,IAAI,CAAC;IAC7B,KAAK,EAAE,cAAc,GAAG,SAAS,CAAC;IAClC,QAAQ,EAAE,CAAC,IAAI,EAAE,cAAc,KAAK,IAAI,CAAC;IACzC,OAAO,EAAE,mBAAmB,CAAC;IAC7B,WAAW,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9C,YAAY,EAAE,MAAM,IAAI,CAAC;IACzB,gHAAgH;IAChH,aAAa,EAAE,CAAC,MAAM,EAAE,aAAa,KAAK,IAAI,CAAC;IAC/C,yGAAyG;IACzG,SAAS,EAAE,OAAO,CAAC;IACnB,gFAAgF;IAChF,KAAK,EAAE,MAAM,IAAI,CAAC;CACnB;AAID,wBAAgB,WAAW,CAAC,OAAO,GAAE,kBAAuB,GAAG,iBAAiB,CAgN/E"}