@escalated-dev/escalated 0.8.0 → 0.9.0

package/src/composables/useRealtime.js

@@ -1,182 +1,182 @@
-import { ref, onUnmounted, readonly } from 'vue';
-
-/**
- * Composable for real-time WebSocket event listening via Laravel Echo.
- *
- * If `window.Echo` is available (provided by the host app), this composable
- * subscribes to private channels and listens for broadcast events. When Echo
- * is not present, it silently falls back - the caller can check `echoAvailable`
- * and implement polling as needed.
- *
- * Usage:
- *   const { echoAvailable, subscribeToTicket, subscribeToTickets, subscribeToAgent } = useRealtime();
- *
- * All subscriptions are automatically cleaned up on component unmount.
- */
-export function useRealtime() {
-    const echoAvailable = ref(typeof window !== 'undefined' && !!window.Echo);
-    const subscriptions = [];
-
-    /**
-     * Subscribe to a private channel and listen for an event.
-     * Returns an unsubscribe function.
-     */
-    function listen(channelName, eventName, callback) {
-        if (!echoAvailable.value) return () => {};
-
-        const channel = window.Echo.private(channelName);
-        channel.listen(eventName, callback);
-
-        const unsub = () => {
-            channel.stopListening(eventName, callback);
-            window.Echo.leave(channelName);
-        };
-        subscriptions.push(unsub);
-        return unsub;
-    }
-
-    /**
-     * Subscribe to a specific ticket's channel for real-time updates.
-     *
-     * @param {number|string} ticketId - The ticket ID
-     * @param {Object} handlers - Event handler callbacks
-     * @param {Function} [handlers.onReplyCreated] - Called when a new reply is added
-     * @param {Function} [handlers.onTicketUpdated] - Called when ticket fields are updated
-     * @param {Function} [handlers.onStatusChanged] - Called when ticket status changes
-     * @param {Function} [handlers.onTicketAssigned] - Called when ticket is assigned
-     * @param {Function} [handlers.onTicketEscalated] - Called when ticket is escalated
-     * @returns {Function} Unsubscribe function
-     */
-    function subscribeToTicket(ticketId, handlers = {}) {
-        if (!echoAvailable.value) return () => {};
-
-        const channelName = `escalated.tickets.${ticketId}`;
-        const channel = window.Echo.private(channelName);
-        const listeners = [];
-
-        if (handlers.onReplyCreated) {
-            channel.listen('.reply.created', handlers.onReplyCreated);
-            listeners.push(['.reply.created', handlers.onReplyCreated]);
-        }
-        if (handlers.onTicketUpdated) {
-            channel.listen('.ticket.updated', handlers.onTicketUpdated);
-            listeners.push(['.ticket.updated', handlers.onTicketUpdated]);
-        }
-        if (handlers.onStatusChanged) {
-            channel.listen('.ticket.status_changed', handlers.onStatusChanged);
-            listeners.push(['.ticket.status_changed', handlers.onStatusChanged]);
-        }
-        if (handlers.onTicketAssigned) {
-            channel.listen('.ticket.assigned', handlers.onTicketAssigned);
-            listeners.push(['.ticket.assigned', handlers.onTicketAssigned]);
-        }
-        if (handlers.onTicketEscalated) {
-            channel.listen('.ticket.escalated', handlers.onTicketEscalated);
-            listeners.push(['.ticket.escalated', handlers.onTicketEscalated]);
-        }
-
-        const unsub = () => {
-            listeners.forEach(([event, cb]) => channel.stopListening(event, cb));
-            window.Echo.leave(channelName);
-        };
-        subscriptions.push(unsub);
-        return unsub;
-    }
-
-    /**
-     * Subscribe to the global tickets channel for new ticket notifications.
-     *
-     * @param {Object} handlers - Event handler callbacks
-     * @param {Function} [handlers.onTicketCreated] - Called when a new ticket is created
-     * @returns {Function} Unsubscribe function
-     */
-    function subscribeToTickets(handlers = {}) {
-        if (!echoAvailable.value) return () => {};
-
-        const channelName = 'escalated.tickets';
-        const channel = window.Echo.private(channelName);
-        const listeners = [];
-
-        if (handlers.onTicketCreated) {
-            channel.listen('.ticket.created', handlers.onTicketCreated);
-            listeners.push(['.ticket.created', handlers.onTicketCreated]);
-        }
-
-        const unsub = () => {
-            listeners.forEach(([event, cb]) => channel.stopListening(event, cb));
-            window.Echo.leave(channelName);
-        };
-        subscriptions.push(unsub);
-        return unsub;
-    }
-
-    /**
-     * Subscribe to an agent's personal channel for assignment notifications.
-     *
-     * @param {number|string} agentId - The agent's user ID
-     * @param {Object} handlers - Event handler callbacks
-     * @param {Function} [handlers.onTicketAssigned] - Called when a ticket is assigned to this agent
-     * @returns {Function} Unsubscribe function
-     */
-    function subscribeToAgent(agentId, handlers = {}) {
-        if (!echoAvailable.value) return () => {};
-
-        const channelName = `escalated.agents.${agentId}`;
-        const channel = window.Echo.private(channelName);
-        const listeners = [];
-
-        if (handlers.onTicketAssigned) {
-            channel.listen('.ticket.assigned', handlers.onTicketAssigned);
-            listeners.push(['.ticket.assigned', handlers.onTicketAssigned]);
-        }
-
-        const unsub = () => {
-            listeners.forEach(([event, cb]) => channel.stopListening(event, cb));
-            window.Echo.leave(channelName);
-        };
-        subscriptions.push(unsub);
-        return unsub;
-    }
-
-    /**
-     * Get a presence channel for a ticket (if Echo supports it).
-     * Returns the channel instance or null.
-     */
-    function joinTicketPresence(ticketId, callbacks = {}) {
-        if (!echoAvailable.value) return null;
-
-        const channelName = `escalated.tickets.${ticketId}`;
-        const channel = window.Echo.join(channelName);
-
-        if (callbacks.here) channel.here(callbacks.here);
-        if (callbacks.joining) channel.joining(callbacks.joining);
-        if (callbacks.leaving) channel.leaving(callbacks.leaving);
-
-        const unsub = () => {
-            window.Echo.leave(`presence-${channelName}`);
-        };
-        subscriptions.push(unsub);
-        return { channel, unsubscribe: unsub };
-    }
-
-    // Cleanup all subscriptions on component unmount
-    onUnmounted(() => {
-        subscriptions.forEach((unsub) => {
-            try {
-                unsub();
-            } catch {
-                /* ignore */
-            }
-        });
-        subscriptions.length = 0;
-    });
-
-    return {
-        echoAvailable: readonly(echoAvailable),
-        listen,
-        subscribeToTicket,
-        subscribeToTickets,
-        subscribeToAgent,
-        joinTicketPresence,
-    };
-}
+import { ref, onUnmounted, readonly } from 'vue';
+
+/**
+ * Composable for real-time WebSocket event listening via Laravel Echo.
+ *
+ * If `window.Echo` is available (provided by the host app), this composable
+ * subscribes to private channels and listens for broadcast events. When Echo
+ * is not present, it silently falls back - the caller can check `echoAvailable`
+ * and implement polling as needed.
+ *
+ * Usage:
+ *   const { echoAvailable, subscribeToTicket, subscribeToTickets, subscribeToAgent } = useRealtime();
+ *
+ * All subscriptions are automatically cleaned up on component unmount.
+ */
+export function useRealtime() {
+    const echoAvailable = ref(typeof window !== 'undefined' && !!window.Echo);
+    const subscriptions = [];
+
+    /**
+     * Subscribe to a private channel and listen for an event.
+     * Returns an unsubscribe function.
+     */
+    function listen(channelName, eventName, callback) {
+        if (!echoAvailable.value) return () => {};
+
+        const channel = window.Echo.private(channelName);
+        channel.listen(eventName, callback);
+
+        const unsub = () => {
+            channel.stopListening(eventName, callback);
+            window.Echo.leave(channelName);
+        };
+        subscriptions.push(unsub);
+        return unsub;
+    }
+
+    /**
+     * Subscribe to a specific ticket's channel for real-time updates.
+     *
+     * @param {number|string} ticketId - The ticket ID
+     * @param {Object} handlers - Event handler callbacks
+     * @param {Function} [handlers.onReplyCreated] - Called when a new reply is added
+     * @param {Function} [handlers.onTicketUpdated] - Called when ticket fields are updated
+     * @param {Function} [handlers.onStatusChanged] - Called when ticket status changes
+     * @param {Function} [handlers.onTicketAssigned] - Called when ticket is assigned
+     * @param {Function} [handlers.onTicketEscalated] - Called when ticket is escalated
+     * @returns {Function} Unsubscribe function
+     */
+    function subscribeToTicket(ticketId, handlers = {}) {
+        if (!echoAvailable.value) return () => {};
+
+        const channelName = `escalated.tickets.${ticketId}`;
+        const channel = window.Echo.private(channelName);
+        const listeners = [];
+
+        if (handlers.onReplyCreated) {
+            channel.listen('.reply.created', handlers.onReplyCreated);
+            listeners.push(['.reply.created', handlers.onReplyCreated]);
+        }
+        if (handlers.onTicketUpdated) {
+            channel.listen('.ticket.updated', handlers.onTicketUpdated);
+            listeners.push(['.ticket.updated', handlers.onTicketUpdated]);
+        }
+        if (handlers.onStatusChanged) {
+            channel.listen('.ticket.status_changed', handlers.onStatusChanged);
+            listeners.push(['.ticket.status_changed', handlers.onStatusChanged]);
+        }
+        if (handlers.onTicketAssigned) {
+            channel.listen('.ticket.assigned', handlers.onTicketAssigned);
+            listeners.push(['.ticket.assigned', handlers.onTicketAssigned]);
+        }
+        if (handlers.onTicketEscalated) {
+            channel.listen('.ticket.escalated', handlers.onTicketEscalated);
+            listeners.push(['.ticket.escalated', handlers.onTicketEscalated]);
+        }
+
+        const unsub = () => {
+            listeners.forEach(([event, cb]) => channel.stopListening(event, cb));
+            window.Echo.leave(channelName);
+        };
+        subscriptions.push(unsub);
+        return unsub;
+    }
+
+    /**
+     * Subscribe to the global tickets channel for new ticket notifications.
+     *
+     * @param {Object} handlers - Event handler callbacks
+     * @param {Function} [handlers.onTicketCreated] - Called when a new ticket is created
+     * @returns {Function} Unsubscribe function
+     */
+    function subscribeToTickets(handlers = {}) {
+        if (!echoAvailable.value) return () => {};
+
+        const channelName = 'escalated.tickets';
+        const channel = window.Echo.private(channelName);
+        const listeners = [];
+
+        if (handlers.onTicketCreated) {
+            channel.listen('.ticket.created', handlers.onTicketCreated);
+            listeners.push(['.ticket.created', handlers.onTicketCreated]);
+        }
+
+        const unsub = () => {
+            listeners.forEach(([event, cb]) => channel.stopListening(event, cb));
+            window.Echo.leave(channelName);
+        };
+        subscriptions.push(unsub);
+        return unsub;
+    }
+
+    /**
+     * Subscribe to an agent's personal channel for assignment notifications.
+     *
+     * @param {number|string} agentId - The agent's user ID
+     * @param {Object} handlers - Event handler callbacks
+     * @param {Function} [handlers.onTicketAssigned] - Called when a ticket is assigned to this agent
+     * @returns {Function} Unsubscribe function
+     */
+    function subscribeToAgent(agentId, handlers = {}) {
+        if (!echoAvailable.value) return () => {};
+
+        const channelName = `escalated.agents.${agentId}`;
+        const channel = window.Echo.private(channelName);
+        const listeners = [];
+
+        if (handlers.onTicketAssigned) {
+            channel.listen('.ticket.assigned', handlers.onTicketAssigned);
+            listeners.push(['.ticket.assigned', handlers.onTicketAssigned]);
+        }
+
+        const unsub = () => {
+            listeners.forEach(([event, cb]) => channel.stopListening(event, cb));
+            window.Echo.leave(channelName);
+        };
+        subscriptions.push(unsub);
+        return unsub;
+    }
+
+    /**
+     * Get a presence channel for a ticket (if Echo supports it).
+     * Returns the channel instance or null.
+     */
+    function joinTicketPresence(ticketId, callbacks = {}) {
+        if (!echoAvailable.value) return null;
+
+        const channelName = `escalated.tickets.${ticketId}`;
+        const channel = window.Echo.join(channelName);
+
+        if (callbacks.here) channel.here(callbacks.here);
+        if (callbacks.joining) channel.joining(callbacks.joining);
+        if (callbacks.leaving) channel.leaving(callbacks.leaving);
+
+        const unsub = () => {
+            window.Echo.leave(`presence-${channelName}`);
+        };
+        subscriptions.push(unsub);
+        return { channel, unsubscribe: unsub };
+    }
+
+    // Cleanup all subscriptions on component unmount
+    onUnmounted(() => {
+        subscriptions.forEach((unsub) => {
+            try {
+                unsub();
+            } catch {
+                /* ignore */
+            }
+        });
+        subscriptions.length = 0;
+    });
+
+    return {
+        echoAvailable: readonly(echoAvailable),
+        listen,
+        subscribeToTicket,
+        subscribeToTickets,
+        subscribeToAgent,
+        joinTicketPresence,
+    };
+}

package/src/index.js

@@ -1,84 +1,85 @@
-// Plugin
-export { EscalatedPlugin } from './plugin';
-
-// Components
-export { default as ActiveChatsPanel } from './components/ActiveChatsPanel.vue';
-export { default as ActivityTimeline } from './components/ActivityTimeline.vue';
-export { default as AgentLoadIndicator } from './components/AgentLoadIndicator.vue';
-export { default as AgentPerformanceCard } from './components/AgentPerformanceCard.vue';
-export { default as ArticleEditor } from './components/ArticleEditor.vue';
-export { default as AssigneeSelect } from './components/AssigneeSelect.vue';
-export { default as AttachmentList } from './components/AttachmentList.vue';
-export { default as AuditLogEntry } from './components/AuditLogEntry.vue';
-export { default as BulkActionBar } from './components/BulkActionBar.vue';
-export { default as CategoryTree } from './components/CategoryTree.vue';
-export { default as ChatActionBar } from './components/ChatActionBar.vue';
-export { default as ChatBubble } from './components/ChatBubble.vue';
-export { default as ChatComposer } from './components/ChatComposer.vue';
-export { default as ChatQueue } from './components/ChatQueue.vue';
-export { default as ChatThread } from './components/ChatThread.vue';
-export { default as ChartWidget } from './components/ChartWidget.vue';
-export { default as CollisionWarning } from './components/CollisionWarning.vue';
-export { default as ConditionalFieldRules } from './components/ConditionalFieldRules.vue';
-export { default as ContextPanel } from './components/ContextPanel.vue';
-export { default as ContextPanelSection } from './components/ContextPanelSection.vue';
-export { default as CustomFieldRenderer } from './components/CustomFieldRenderer.vue';
-export { default as EscalatedLayout } from './components/EscalatedLayout.vue';
-export { default as FileDropzone } from './components/FileDropzone.vue';
-export { default as FollowButton } from './components/FollowButton.vue';
-export { default as KeyboardShortcutHelp } from './components/KeyboardShortcutHelp.vue';
-export { default as KnowledgePanel } from './components/KnowledgePanel.vue';
-export { default as KpiCard } from './components/KpiCard.vue';
-export { default as MacroDropdown } from './components/MacroDropdown.vue';
-export { default as MentionDropdown } from './components/MentionDropdown.vue';
-export { default as PermissionMatrix } from './components/PermissionMatrix.vue';
-export { default as PinnedNotes } from './components/PinnedNotes.vue';
-export { default as PluginSlot } from './components/PluginSlot.vue';
-export { default as PresenceIndicator } from './components/PresenceIndicator.vue';
-export { default as PriorityBadge } from './components/PriorityBadge.vue';
-export { default as QuickFilters } from './components/QuickFilters.vue';
-export { default as ReplyComposer } from './components/ReplyComposer.vue';
-export { default as ReplyThread } from './components/ReplyThread.vue';
-export { default as SavedViewSidebar } from './components/SavedViewSidebar.vue';
-export { default as SaveViewDialog } from './components/SaveViewDialog.vue';
-export { default as SatisfactionRating } from './components/SatisfactionRating.vue';
-export { default as ScheduleEditor } from './components/ScheduleEditor.vue';
-export { default as SideConversation } from './components/SideConversation.vue';
-export { default as SideConversationList } from './components/SideConversationList.vue';
-export { default as SkillTagManager } from './components/SkillTagManager.vue';
-export { default as SlaComplianceChart } from './components/SlaComplianceChart.vue';
-export { default as SlaTimer } from './components/SlaTimer.vue';
-export { default as StatsCard } from './components/StatsCard.vue';
-export { default as StatusBadge } from './components/StatusBadge.vue';
-export { default as TagSelect } from './components/TagSelect.vue';
-export { default as TicketFilters } from './components/TicketFilters.vue';
-export { default as TicketLinkPanel } from './components/TicketLinkPanel.vue';
-export { default as TicketList } from './components/TicketList.vue';
-export { default as TicketMergeDialog } from './components/TicketMergeDialog.vue';
-export { default as TicketSidebar } from './components/TicketSidebar.vue';
-export { default as TicketTypeSelector } from './components/TicketTypeSelector.vue';
-export { default as TotpInput } from './components/TotpInput.vue';
-export { default as TwoFactorSetup } from './components/TwoFactorSetup.vue';
-
-// Composables
-export { useDebouncedSearch } from './composables/useDebouncedSearch';
-export { useKeyboardShortcuts } from './composables/useKeyboardShortcuts';
-export { useMentions } from './composables/useMentions';
-export { usePluginExtensions } from './composables/usePluginExtensions';
-export { usePluginHooks } from './composables/usePluginHooks';
-export { useChat } from './composables/useChat';
-export { useRealtime } from './composables/useRealtime';
-
-// Utilities
-export { TICKET_STATUSES, TICKET_PRIORITIES, TICKET_TYPES, TICKET_TYPE_COLORS } from './utils/constants';
-export { timeAgo, slaClass } from './utils/formatting';
-
-// Plugin authoring helper
-export { defineEscalatedPlugin } from './defineEscalatedPlugin';
-
-// Import pages
-export { default as AdminImportIndex } from './pages/Admin/Import/Index.vue';
-export { default as AdminImportConnect } from './pages/Admin/Import/Connect.vue';
-export { default as AdminImportMapping } from './pages/Admin/Import/Mapping.vue';
-export { default as AdminImportReview } from './pages/Admin/Import/Review.vue';
-export { default as AdminImportProgress } from './pages/Admin/Import/Progress.vue';
+// Plugin
+export { EscalatedPlugin } from './plugin';
+
+// Components
+export { default as ActiveChatsPanel } from './components/ActiveChatsPanel.vue';
+export { default as ActivityTimeline } from './components/ActivityTimeline.vue';
+export { default as AgentLoadIndicator } from './components/AgentLoadIndicator.vue';
+export { default as AgentPerformanceCard } from './components/AgentPerformanceCard.vue';
+export { default as ArticleEditor } from './components/ArticleEditor.vue';
+export { default as AssigneeSelect } from './components/AssigneeSelect.vue';
+export { default as AttachmentList } from './components/AttachmentList.vue';
+export { default as AuditLogEntry } from './components/AuditLogEntry.vue';
+export { default as BulkActionBar } from './components/BulkActionBar.vue';
+export { default as CategoryTree } from './components/CategoryTree.vue';
+export { default as ChatActionBar } from './components/ChatActionBar.vue';
+export { default as ChatBubble } from './components/ChatBubble.vue';
+export { default as ChatComposer } from './components/ChatComposer.vue';
+export { default as ChatQueue } from './components/ChatQueue.vue';
+export { default as ChatThread } from './components/ChatThread.vue';
+export { default as ChartWidget } from './components/ChartWidget.vue';
+export { default as CollisionWarning } from './components/CollisionWarning.vue';
+export { default as ConditionalFieldRules } from './components/ConditionalFieldRules.vue';
+export { default as ContextPanel } from './components/ContextPanel.vue';
+export { default as ContextPanelSection } from './components/ContextPanelSection.vue';
+export { default as CustomFieldRenderer } from './components/CustomFieldRenderer.vue';
+export { default as CustomTicketActions } from './components/CustomTicketActions.vue';
+export { default as EscalatedLayout } from './components/EscalatedLayout.vue';
+export { default as FileDropzone } from './components/FileDropzone.vue';
+export { default as FollowButton } from './components/FollowButton.vue';
+export { default as KeyboardShortcutHelp } from './components/KeyboardShortcutHelp.vue';
+export { default as KnowledgePanel } from './components/KnowledgePanel.vue';
+export { default as KpiCard } from './components/KpiCard.vue';
+export { default as MacroDropdown } from './components/MacroDropdown.vue';
+export { default as MentionDropdown } from './components/MentionDropdown.vue';
+export { default as PermissionMatrix } from './components/PermissionMatrix.vue';
+export { default as PinnedNotes } from './components/PinnedNotes.vue';
+export { default as PluginSlot } from './components/PluginSlot.vue';
+export { default as PresenceIndicator } from './components/PresenceIndicator.vue';
+export { default as PriorityBadge } from './components/PriorityBadge.vue';
+export { default as QuickFilters } from './components/QuickFilters.vue';
+export { default as ReplyComposer } from './components/ReplyComposer.vue';
+export { default as ReplyThread } from './components/ReplyThread.vue';
+export { default as SavedViewSidebar } from './components/SavedViewSidebar.vue';
+export { default as SaveViewDialog } from './components/SaveViewDialog.vue';
+export { default as SatisfactionRating } from './components/SatisfactionRating.vue';
+export { default as ScheduleEditor } from './components/ScheduleEditor.vue';
+export { default as SideConversation } from './components/SideConversation.vue';
+export { default as SideConversationList } from './components/SideConversationList.vue';
+export { default as SkillTagManager } from './components/SkillTagManager.vue';
+export { default as SlaComplianceChart } from './components/SlaComplianceChart.vue';
+export { default as SlaTimer } from './components/SlaTimer.vue';
+export { default as StatsCard } from './components/StatsCard.vue';
+export { default as StatusBadge } from './components/StatusBadge.vue';
+export { default as TagSelect } from './components/TagSelect.vue';
+export { default as TicketFilters } from './components/TicketFilters.vue';
+export { default as TicketLinkPanel } from './components/TicketLinkPanel.vue';
+export { default as TicketList } from './components/TicketList.vue';
+export { default as TicketMergeDialog } from './components/TicketMergeDialog.vue';
+export { default as TicketSidebar } from './components/TicketSidebar.vue';
+export { default as TicketTypeSelector } from './components/TicketTypeSelector.vue';
+export { default as TotpInput } from './components/TotpInput.vue';
+export { default as TwoFactorSetup } from './components/TwoFactorSetup.vue';
+
+// Composables
+export { useDebouncedSearch } from './composables/useDebouncedSearch';
+export { useKeyboardShortcuts } from './composables/useKeyboardShortcuts';
+export { useMentions } from './composables/useMentions';
+export { usePluginExtensions } from './composables/usePluginExtensions';
+export { usePluginHooks } from './composables/usePluginHooks';
+export { useChat } from './composables/useChat';
+export { useRealtime } from './composables/useRealtime';
+
+// Utilities
+export { TICKET_STATUSES, TICKET_PRIORITIES, TICKET_TYPES, TICKET_TYPE_COLORS } from './utils/constants';
+export { timeAgo, slaClass } from './utils/formatting';
+
+// Plugin authoring helper
+export { defineEscalatedPlugin } from './defineEscalatedPlugin';
+
+// Import pages
+export { default as AdminImportIndex } from './pages/Admin/Import/Index.vue';
+export { default as AdminImportConnect } from './pages/Admin/Import/Connect.vue';
+export { default as AdminImportMapping } from './pages/Admin/Import/Mapping.vue';
+export { default as AdminImportReview } from './pages/Admin/Import/Review.vue';
+export { default as AdminImportProgress } from './pages/Admin/Import/Progress.vue';

package/src/locales/README.md

@@ -1,13 +1,13 @@
-# Local locale overrides
-
-The JSON files in this directory (`en.json`, `de.json`, …) are **local overrides** that win over the central source published by [`@escalated-dev/locale`](https://github.com/escalated-dev/escalated-locale).
-
-The composable in `src/composables/useI18n.js` resolves keys in this order:
-
-1. Host-app `customMessages` for the current locale
-2. Local override (these JSON files) for the current locale
-3. Central source (`@escalated-dev/locale`) for the current locale
-4. Same three layers, but English fallback
-5. Raw key
-
-After the central package is populated with the canonical strings, files here can be trimmed to contain only the keys this plugin needs to phrase differently from the central source. Keys not present locally fall through to the central source unchanged.
+# Local locale overrides
+
+The JSON files in this directory (`en.json`, `de.json`, …) are **local overrides** that win over the central source published by [`@escalated-dev/locale`](https://github.com/escalated-dev/escalated-locale).
+
+The composable in `src/composables/useI18n.js` resolves keys in this order:
+
+1. Host-app `customMessages` for the current locale
+2. Local override (these JSON files) for the current locale
+3. Central source (`@escalated-dev/locale`) for the current locale
+4. Same three layers, but English fallback
+5. Raw key
+
+After the central package is populated with the canonical strings, files here can be trimmed to contain only the keys this plugin needs to phrase differently from the central source. Keys not present locally fall through to the central source unchanged.