transduck 0.3.1 → 0.4.1

package/dist/cli.js

@@ -454,7 +454,7 @@ export async function runStats(opts) {
 }
 // CLI entry point
 const program = new Command();
-program.name('transduck').description('AI-native translation tool').version('0.3.1');
+program.name('transduck').description('AI-native translation tool').version('0.4.1');
 program.command('init')
     .description('Initialize a new transduck project')
     .action(async () => {

package/dist/react/index.d.ts

@@ -1 +1,2 @@
-export { TransDuckProvider, t, ait, tPlural, aitPlural, useTransDuck, _resetReactState } from './provider.js';
+export { TransDuckProvider, t, ait, tPlural, aitPlural, useTransDuck, _resetReactState, _getReactState } from './provider.js';
+export type { UseTransDuckReturn } from './provider.js';

package/dist/react/index.js

@@ -1,2 +1,2 @@
 'use client';
-export { TransDuckProvider, t, ait, tPlural, aitPlural, useTransDuck, _resetReactState } from './provider.js';
+export { TransDuckProvider, t, ait, tPlural, aitPlural, useTransDuck, _resetReactState, _getReactState } from './provider.js';

package/dist/react/provider.d.ts

@@ -1,10 +1,34 @@
 import { type ReactNode } from 'react';
+interface ReactState {
+    language: string;
+    sourceLang: string;
+    endpoint: string;
+    projectName: string;
+    cache: Map<string, string>;
+    pluralCache: Map<string, Record<string, string>>;
+    pendingStrings: Set<string>;
+    pendingPlurals: Set<string>;
+    knownKeys: Set<string>;
+    knownPlurals: Set<string>;
+    isLanguageSwitch: boolean;
+    triggerFetch: (() => void) | null;
+}
 /**
- * Hook that subscribes to translation updates. Call this in any component
- * that uses t()/ait() to ensure it re-renders when translations are loaded.
+ * Hook that subscribes to translation updates and returns translation
+ * functions along with language state.
  */
-export declare function useTransDuck(): void;
+export interface UseTransDuckReturn {
+    t: typeof t;
+    tPlural: typeof tPlural;
+    ait: typeof t;
+    aitPlural: typeof tPlural;
+    language: string;
+    setLanguage: (lang: string) => void;
+    isLoading: boolean;
+}
+export declare function useTransDuck(): UseTransDuckReturn;
 export declare function _resetReactState(): void;
+export declare function _getReactState(): ReactState;
 export declare function t(sourceText: string, context?: string, vars?: Record<string, string | number>): string;
 export declare function tPlural(one: string, other: string, count: number, opts?: {
     context?: string;

package/dist/react/provider.js

@@ -1,39 +1,59 @@
 'use client';
 import { jsx as _jsx } from "react/jsx-runtime";
-import { createContext, useContext, useEffect, useState, useCallback } from 'react';
+import React, { createContext, useContext, useEffect, useState, useCallback } from 'react';
 let _state = {
     language: '',
     sourceLang: 'EN',
     endpoint: '/api/translations',
+    projectName: 'default',
     cache: new Map(),
     pluralCache: new Map(),
     pendingStrings: new Set(),
     pendingPlurals: new Set(),
+    knownKeys: new Set(),
+    knownPlurals: new Set(),
+    isLanguageSwitch: false,
     triggerFetch: null,
 };
-// --- Context for triggering child re-renders ---
-// The context value (a version counter) changes when translations are loaded.
-// Components that call useTransDuck() subscribe to this and re-render automatically.
-const TransDuckContext = createContext(0);
-/**
- * Hook that subscribes to translation updates. Call this in any component
- * that uses t()/ait() to ensure it re-renders when translations are loaded.
- */
+const defaultContext = {
+    version: 0,
+    language: '',
+    setLanguage: () => { },
+    isLoading: false,
+};
+const TransDuckContext = createContext(defaultContext);
 export function useTransDuck() {
-    useContext(TransDuckContext);
+    const ctx = useContext(TransDuckContext);
+    return {
+        t,
+        tPlural,
+        ait,
+        aitPlural,
+        language: ctx.language,
+        setLanguage: ctx.setLanguage,
+        isLoading: ctx.isLoading,
+    };
 }
 export function _resetReactState() {
+    flushScheduled = false;
     _state = {
         language: '',
         sourceLang: 'EN',
         endpoint: '/api/translations',
+        projectName: 'default',
         cache: new Map(),
         pluralCache: new Map(),
         pendingStrings: new Set(),
         pendingPlurals: new Set(),
+        knownKeys: new Set(),
+        knownPlurals: new Set(),
+        isLanguageSwitch: false,
         triggerFetch: null,
     };
 }
+export function _getReactState() {
+    return _state;
+}
 function interpolateVars(text, vars) {
     if (!vars)
         return text;
@@ -43,20 +63,35 @@ function interpolateVars(text, vars) {
     }
     return result;
 }
+// --- Self-flushing microtask scheduler ---
+// Ensures pending strings are fetched even when the provider doesn't re-render
+// (e.g., client-side navigation in Next.js App Router persistent layouts).
+let flushScheduled = false;
+function schedulePendingFlush() {
+    if (flushScheduled || !_state.triggerFetch || _state.isLanguageSwitch)
+        return;
+    flushScheduled = true;
+    queueMicrotask(() => {
+        flushScheduled = false;
+        _state.triggerFetch?.();
+    });
+}
 // --- Stable exported functions ---
 export function t(sourceText, context, vars) {
+    const key = `${sourceText}||${context ?? ''}`;
+    _state.knownKeys.add(key);
     // Same language — return source
     if (_state.language.toUpperCase() === _state.sourceLang.toUpperCase()) {
         return interpolateVars(sourceText, vars);
     }
-    const key = `${sourceText}||${context ?? ''}`;
     // Cache hit
     const cached = _state.cache.get(key);
     if (cached !== undefined) {
         return interpolateVars(cached, vars);
     }
-    // Queue for fetch (useEffect in provider will flush after render)
+    // Queue for fetch
     _state.pendingStrings.add(key);
+    schedulePendingFlush();
     // Return source text as fallback
     return interpolateVars(sourceText, vars);
 }
@@ -72,14 +107,15 @@ export function tPlural(one, other, count, opts) {
     else {
         vars = { ...opts.vars };
     }
+    const sourceKey = `${one}\x00${other}`;
+    const cacheKey = `${sourceKey}||${context ?? ''}`;
+    _state.knownPlurals.add(cacheKey);
     // Same language
     if (_state.language.toUpperCase() === _state.sourceLang.toUpperCase()) {
         const rules = new Intl.PluralRules(_state.sourceLang.toLowerCase());
         const form = rules.select(count) === 'one' ? one : other;
         return interpolateVars(form, vars);
     }
-    const sourceKey = `${one}\x00${other}`;
-    const cacheKey = `${sourceKey}||${context ?? ''}`;
     // Cache hit
     const cachedForms = _state.pluralCache.get(cacheKey);
     if (cachedForms) {
@@ -88,8 +124,9 @@ export function tPlural(one, other, count, opts) {
         const form = cachedForms[category] ?? cachedForms['other'] ?? other;
         return interpolateVars(form, vars);
     }
-    // Queue for fetch (useEffect in provider will flush after render)
+    // Queue for fetch
     _state.pendingPlurals.add(cacheKey);
+    schedulePendingFlush();
     // Fallback to source form
     const rules = new Intl.PluralRules(_state.sourceLang.toLowerCase());
     const form = rules.select(count) === 'one' ? one : other;
@@ -136,18 +173,52 @@ function saveToLocalStorage(projectName, language) {
 }
 export function TransDuckProvider({ language, sourceLang = 'EN', endpoint = '/api/translations', projectName = 'default', children, }) {
     const [version, setVersion] = useState(0);
+    const [languageState, setLanguageState] = useState(language.toUpperCase());
+    const [isLoading, setIsLoading] = useState(false);
     // Update module-level state synchronously so t() works during first render
     _state.endpoint = endpoint;
     _state.sourceLang = sourceLang;
+    _state.projectName = projectName;
+    // Synchronous first-render initialization only.
+    // Subsequent language changes are handled by switchLanguage / useEffect prop sync.
     const upperLang = language.toUpperCase();
-    if (_state.language !== upperLang) {
+    if (!_state.language) {
         _state.language = upperLang;
-        _state.cache.clear();
-        _state.pluralCache.clear();
         loadFromLocalStorage(projectName, upperLang);
     }
+    const switchLanguage = useCallback((lang) => {
+        const upper = lang.toUpperCase();
+        // Same-language no-op
+        if (upper === _state.language)
+            return;
+        // Update React state
+        setLanguageState(upper);
+        // Update module-level state synchronously
+        _state.language = upper;
+        _state.cache.clear();
+        _state.pluralCache.clear();
+        // Source-language guard: skip fetch, t() short-circuits
+        if (upper === _state.sourceLang.toUpperCase()) {
+            setVersion(v => v + 1);
+            return;
+        }
+        // Load cached translations from localStorage
+        loadFromLocalStorage(_state.projectName, upper);
+        // Mark as language switch and re-queue known keys
+        _state.isLanguageSwitch = true;
+        setIsLoading(true);
+        for (const key of _state.knownKeys) {
+            _state.pendingStrings.add(key);
+        }
+        for (const key of _state.knownPlurals) {
+            _state.pendingPlurals.add(key);
+        }
+        // Bump version to trigger re-render and useEffect flush
+        setVersion(v => v + 1);
+    }, []);
     // Set up trigger
     const doFetch = useCallback(async () => {
+        const fetchLanguage = _state.language;
         const stringsToFetch = new Set(_state.pendingStrings);
         const pluralsToFetch = new Set(_state.pendingPlurals);
         _state.pendingStrings.clear();
@@ -161,8 +232,13 @@ export function TransDuckProvider({ language, sourceLang = 'EN', endpoint = '/ap
             if (_state.pluralCache.has(key))
                 pluralsToFetch.delete(key);
         }
-        if (stringsToFetch.size === 0 && pluralsToFetch.size === 0)
+        if (stringsToFetch.size === 0 && pluralsToFetch.size === 0) {
+            if (_state.isLanguageSwitch && _state.language === fetchLanguage) {
+                _state.isLanguageSwitch = false;
+                setIsLoading(false);
+            }
             return;
+        }
         // Build request body
         const strings = Array.from(stringsToFetch).map(key => {
             const [text, context] = key.split('||');
@@ -188,6 +264,9 @@ export function TransDuckProvider({ language, sourceLang = 'EN', endpoint = '/ap
                 return;
             }
             const data = await response.json();
+            // Stale fetch protection: language changed while we were fetching
+            if (_state.language !== fetchLanguage)
+                return;
             // Store translations
             if (data.translations) {
                 for (const [key, value] of Object.entries(data.translations)) {
@@ -199,20 +278,41 @@ export function TransDuckProvider({ language, sourceLang = 'EN', endpoint = '/ap
                     _state.pluralCache.set(key, value);
                 }
             }
-            saveToLocalStorage(projectName, _state.language);
+            saveToLocalStorage(_state.projectName, _state.language);
             setVersion(v => v + 1);
         }
         catch (err) {
             console.warn('[transduck] Translation fetch error:', err);
         }
-    }, [endpoint, projectName]);
+        finally {
+            if (_state.isLanguageSwitch && _state.language === fetchLanguage) {
+                _state.isLanguageSwitch = false;
+                setIsLoading(false);
+            }
+        }
+    }, [endpoint]);
     // Register trigger
     _state.triggerFetch = doFetch;
+    // Sync language prop changes — only when the prop itself changes
+    const prevPropRef = React.useRef(upperLang);
+    useEffect(() => {
+        const upper = language.toUpperCase();
+        if (upper !== prevPropRef.current) {
+            prevPropRef.current = upper;
+            switchLanguage(upper);
+        }
+    }, [language, switchLanguage]);
     // Flush pending after render
     useEffect(() => {
         if (_state.pendingStrings.size > 0 || _state.pendingPlurals.size > 0) {
             doFetch();
         }
     });
-    return (_jsx(TransDuckContext.Provider, { value: version, children: children }));
+    const contextValue = {
+        version,
+        language: languageState,
+        setLanguage: switchLanguage,
+        isLoading,
+    };
+    return (_jsx(TransDuckContext.Provider, { value: contextValue, children: children }));
 }

package/dist/storage.js

@@ -29,7 +29,7 @@ export class TranslationStore {
         this.db = open({
             path: this.dbPath,
             mapSize: DEFAULT_MAP_SIZE,
-            // Use msgpack (default) for efficient storage
+            encoding: 'json',
         });
     }
     getDb() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "transduck",
-  "version": "0.3.1",
+  "version": "0.4.1",
   "description": "AI-native translation tool using source text as keys",
   "type": "module",
   "main": "./dist/index.js",

package/src/cli.ts

@@ -562,7 +562,7 @@ export async function runStats(opts: StatsOptions): Promise<string> {
 // CLI entry point
 const program = new Command();
 
-program.name('transduck').description('AI-native translation tool').version('0.3.1');
+program.name('transduck').description('AI-native translation tool').version('0.4.1');
 
 program.command('init')
   .description('Initialize a new transduck project')

package/src/react/index.ts

@@ -1,3 +1,4 @@
 'use client';
 
-export { TransDuckProvider, t, ait, tPlural, aitPlural, useTransDuck, _resetReactState } from './provider.js';
+export { TransDuckProvider, t, ait, tPlural, aitPlural, useTransDuck, _resetReactState, _getReactState } from './provider.js';
+export type { UseTransDuckReturn } from './provider.js';

package/src/react/provider.tsx

@@ -8,10 +8,14 @@ interface ReactState {
   language: string;
   sourceLang: string;
   endpoint: string;
+  projectName: string;
   cache: Map<string, string>;
   pluralCache: Map<string, Record<string, string>>;
   pendingStrings: Set<string>; // "text||context"
   pendingPlurals: Set<string>; // "one\x00other||context"
+  knownKeys: Set<string>;
+  knownPlurals: Set<string>;
+  isLanguageSwitch: boolean;
   triggerFetch: (() => void) | null;
 }
 
@@ -19,39 +23,86 @@ let _state: ReactState = {
   language: '',
   sourceLang: 'EN',
   endpoint: '/api/translations',
+  projectName: 'default',
   cache: new Map(),
   pluralCache: new Map(),
   pendingStrings: new Set(),
   pendingPlurals: new Set(),
+  knownKeys: new Set(),
+  knownPlurals: new Set(),
+  isLanguageSwitch: false,
   triggerFetch: null,
 };
 
 // --- Context for triggering child re-renders ---
-// The context value (a version counter) changes when translations are loaded.
+// The context value changes when translations are loaded or language switches.
 // Components that call useTransDuck() subscribe to this and re-render automatically.
-const TransDuckContext = createContext<number>(0);
+
+interface TransDuckContextValue {
+  version: number;
+  language: string;
+  setLanguage: (lang: string) => void;
+  isLoading: boolean;
+}
+
+const defaultContext: TransDuckContextValue = {
+  version: 0,
+  language: '',
+  setLanguage: () => {},
+  isLoading: false,
+};
+
+const TransDuckContext = createContext<TransDuckContextValue>(defaultContext);
 
 /**
- * Hook that subscribes to translation updates. Call this in any component
- * that uses t()/ait() to ensure it re-renders when translations are loaded.
+ * Hook that subscribes to translation updates and returns translation
+ * functions along with language state.
  */
-export function useTransDuck(): void {
-  useContext(TransDuckContext);
+export interface UseTransDuckReturn {
+  t: typeof t;
+  tPlural: typeof tPlural;
+  ait: typeof t;
+  aitPlural: typeof tPlural;
+  language: string;
+  setLanguage: (lang: string) => void;
+  isLoading: boolean;
+}
+
+export function useTransDuck(): UseTransDuckReturn {
+  const ctx = useContext(TransDuckContext);
+  return {
+    t,
+    tPlural,
+    ait,
+    aitPlural,
+    language: ctx.language,
+    setLanguage: ctx.setLanguage,
+    isLoading: ctx.isLoading,
+  };
 }
 
 export function _resetReactState(): void {
+  flushScheduled = false;
   _state = {
     language: '',
     sourceLang: 'EN',
     endpoint: '/api/translations',
+    projectName: 'default',
     cache: new Map(),
     pluralCache: new Map(),
     pendingStrings: new Set(),
     pendingPlurals: new Set(),
+    knownKeys: new Set(),
+    knownPlurals: new Set(),
+    isLanguageSwitch: false,
     triggerFetch: null,
   };
 }
 
+export function _getReactState(): ReactState {
+  return _state;
+}
+
 function interpolateVars(text: string, vars?: Record<string, string | number> | null): string {
   if (!vars) return text;
   let result = text;
@@ -61,6 +112,21 @@ function interpolateVars(text: string, vars?: Record<string, string | number> |
   return result;
 }
 
+// --- Self-flushing microtask scheduler ---
+// Ensures pending strings are fetched even when the provider doesn't re-render
+// (e.g., client-side navigation in Next.js App Router persistent layouts).
+
+let flushScheduled = false;
+
+function schedulePendingFlush() {
+  if (flushScheduled || !_state.triggerFetch || _state.isLanguageSwitch) return;
+  flushScheduled = true;
+  queueMicrotask(() => {
+    flushScheduled = false;
+    _state.triggerFetch?.();
+  });
+}
+
 // --- Stable exported functions ---
 
 export function t(
@@ -68,21 +134,23 @@ export function t(
   context?: string,
   vars?: Record<string, string | number>,
 ): string {
+  const key = `${sourceText}||${context ?? ''}`;
+  _state.knownKeys.add(key);
+
   // Same language — return source
   if (_state.language.toUpperCase() === _state.sourceLang.toUpperCase()) {
     return interpolateVars(sourceText, vars);
   }
 
-  const key = `${sourceText}||${context ?? ''}`;
-
   // Cache hit
   const cached = _state.cache.get(key);
   if (cached !== undefined) {
     return interpolateVars(cached, vars);
   }
 
-  // Queue for fetch (useEffect in provider will flush after render)
+  // Queue for fetch
   _state.pendingStrings.add(key);
+  schedulePendingFlush();
 
   // Return source text as fallback
   return interpolateVars(sourceText, vars);
@@ -104,6 +172,10 @@ export function tPlural(
     vars = { ...opts.vars };
   }
 
+  const sourceKey = `${one}\x00${other}`;
+  const cacheKey = `${sourceKey}||${context ?? ''}`;
+  _state.knownPlurals.add(cacheKey);
+
   // Same language
   if (_state.language.toUpperCase() === _state.sourceLang.toUpperCase()) {
     const rules = new Intl.PluralRules(_state.sourceLang.toLowerCase());
@@ -111,9 +183,6 @@ export function tPlural(
     return interpolateVars(form, vars);
   }
 
-  const sourceKey = `${one}\x00${other}`;
-  const cacheKey = `${sourceKey}||${context ?? ''}`;
-
   // Cache hit
   const cachedForms = _state.pluralCache.get(cacheKey);
   if (cachedForms) {
@@ -123,8 +192,9 @@ export function tPlural(
     return interpolateVars(form, vars);
   }
 
-  // Queue for fetch (useEffect in provider will flush after render)
+  // Queue for fetch
   _state.pendingPlurals.add(cacheKey);
+  schedulePendingFlush();
 
   // Fallback to source form
   const rules = new Intl.PluralRules(_state.sourceLang.toLowerCase());
@@ -191,21 +261,62 @@ export function TransDuckProvider({
   children,
 }: TransDuckProviderProps) {
   const [version, setVersion] = useState(0);
+  const [languageState, setLanguageState] = useState(language.toUpperCase());
+  const [isLoading, setIsLoading] = useState(false);
 
   // Update module-level state synchronously so t() works during first render
   _state.endpoint = endpoint;
   _state.sourceLang = sourceLang;
+  _state.projectName = projectName;
 
+  // Synchronous first-render initialization only.
+  // Subsequent language changes are handled by switchLanguage / useEffect prop sync.
   const upperLang = language.toUpperCase();
-  if (_state.language !== upperLang) {
+  if (!_state.language) {
     _state.language = upperLang;
-    _state.cache.clear();
-    _state.pluralCache.clear();
     loadFromLocalStorage(projectName, upperLang);
   }
 
+  const switchLanguage = useCallback((lang: string) => {
+    const upper = lang.toUpperCase();
+
+    // Same-language no-op
+    if (upper === _state.language) return;
+
+    // Update React state
+    setLanguageState(upper);
+
+    // Update module-level state synchronously
+    _state.language = upper;
+    _state.cache.clear();
+    _state.pluralCache.clear();
+
+    // Source-language guard: skip fetch, t() short-circuits
+    if (upper === _state.sourceLang.toUpperCase()) {
+      setVersion(v => v + 1);
+      return;
+    }
+
+    // Load cached translations from localStorage
+    loadFromLocalStorage(_state.projectName, upper);
+
+    // Mark as language switch and re-queue known keys
+    _state.isLanguageSwitch = true;
+    setIsLoading(true);
+    for (const key of _state.knownKeys) {
+      _state.pendingStrings.add(key);
+    }
+    for (const key of _state.knownPlurals) {
+      _state.pendingPlurals.add(key);
+    }
+
+    // Bump version to trigger re-render and useEffect flush
+    setVersion(v => v + 1);
+  }, []);
+
   // Set up trigger
   const doFetch = useCallback(async () => {
+    const fetchLanguage = _state.language;
     const stringsToFetch = new Set(_state.pendingStrings);
     const pluralsToFetch = new Set(_state.pendingPlurals);
     _state.pendingStrings.clear();
@@ -219,7 +330,13 @@ export function TransDuckProvider({
       if (_state.pluralCache.has(key)) pluralsToFetch.delete(key);
     }
 
-    if (stringsToFetch.size === 0 && pluralsToFetch.size === 0) return;
+    if (stringsToFetch.size === 0 && pluralsToFetch.size === 0) {
+      if (_state.isLanguageSwitch && _state.language === fetchLanguage) {
+        _state.isLanguageSwitch = false;
+        setIsLoading(false);
+      }
+      return;
+    }
 
     // Build request body
     const strings = Array.from(stringsToFetch).map(key => {
@@ -250,6 +367,9 @@ export function TransDuckProvider({
 
       const data = await response.json();
 
+      // Stale fetch protection: language changed while we were fetching
+      if (_state.language !== fetchLanguage) return;
+
       // Store translations
       if (data.translations) {
         for (const [key, value] of Object.entries(data.translations)) {
@@ -262,16 +382,31 @@ export function TransDuckProvider({
         }
       }
 
-      saveToLocalStorage(projectName, _state.language);
+      saveToLocalStorage(_state.projectName, _state.language);
       setVersion(v => v + 1);
     } catch (err) {
       console.warn('[transduck] Translation fetch error:', err);
+    } finally {
+      if (_state.isLanguageSwitch && _state.language === fetchLanguage) {
+        _state.isLanguageSwitch = false;
+        setIsLoading(false);
+      }
     }
-  }, [endpoint, projectName]);
+  }, [endpoint]);
 
   // Register trigger
   _state.triggerFetch = doFetch;
 
+  // Sync language prop changes — only when the prop itself changes
+  const prevPropRef = React.useRef(upperLang);
+  useEffect(() => {
+    const upper = language.toUpperCase();
+    if (upper !== prevPropRef.current) {
+      prevPropRef.current = upper;
+      switchLanguage(upper);
+    }
+  }, [language, switchLanguage]);
+
   // Flush pending after render
   useEffect(() => {
     if (_state.pendingStrings.size > 0 || _state.pendingPlurals.size > 0) {
@@ -279,8 +414,15 @@ export function TransDuckProvider({
     }
   });
 
+  const contextValue: TransDuckContextValue = {
+    version,
+    language: languageState,
+    setLanguage: switchLanguage,
+    isLoading,
+  };
+
   return (
-    <TransDuckContext.Provider value={version}>
+    <TransDuckContext.Provider value={contextValue}>
       {children}
     </TransDuckContext.Provider>
   );

package/src/storage.ts

@@ -73,7 +73,7 @@ export class TranslationStore {
     this.db = open<StoredEntry, string>({
       path: this.dbPath,
       mapSize: DEFAULT_MAP_SIZE,
-      // Use msgpack (default) for efficient storage
+      encoding: 'json',
     });
   }
 

package/tests/react-provider.test.tsx

@@ -1,7 +1,8 @@
 import { describe, it, expect, beforeEach, vi, afterEach } from 'vitest';
 import React from 'react';
-import { render, screen, cleanup, waitFor } from '@testing-library/react';
-import { TransDuckProvider, t, ait, tPlural, aitPlural, useTransDuck, _resetReactState } from '../src/react/index.js';
+import { render, screen, cleanup, waitFor, act } from '@testing-library/react';
+import { TransDuckProvider, t, ait, tPlural, aitPlural, useTransDuck, _resetReactState, _getReactState } from '../src/react/index.js';
+import type { UseTransDuckReturn } from '../src/react/index.js';
 
 // Mock fetch globally
 const mockFetch = vi.fn();
@@ -159,4 +160,364 @@ describe('TransDuckProvider + t()', () => {
     expect(mockFetch).not.toHaveBeenCalled();
     expect(screen.getByTestId('text').textContent).toBe('Hallo');
   });
+
+  it('t() tracks called keys in _state.knownKeys', async () => {
+    mockFetch.mockResolvedValue({
+      ok: true,
+      json: async () => ({ translations: { 'Hello||': 'Hallo' }, plurals: {} }),
+    });
+
+    function TestComp() {
+      useTransDuck();
+      return <span>{t('Hello')}</span>;
+    }
+
+    render(
+      <TransDuckProvider language="DE">
+        <TestComp />
+      </TransDuckProvider>
+    );
+
+    const state = _getReactState();
+    expect(state.knownKeys.has('Hello||')).toBe(true);
+  });
+
+  it('useTransDuck() returns t, tPlural, ait, aitPlural, language, setLanguage, isLoading', () => {
+    let hookResult: ReturnType<typeof useTransDuck> | null = null;
+
+    function TestComp() {
+      hookResult = useTransDuck();
+      return <span>test</span>;
+    }
+
+    render(
+      <TransDuckProvider language="DE">
+        <TestComp />
+      </TransDuckProvider>
+    );
+
+    expect(hookResult).not.toBeNull();
+    expect(hookResult!.t).toBe(t);
+    expect(hookResult!.tPlural).toBe(tPlural);
+    expect(hookResult!.ait).toBe(ait);
+    expect(hookResult!.aitPlural).toBe(aitPlural);
+    expect(hookResult!.language).toBe('DE');
+    expect(typeof hookResult!.setLanguage).toBe('function');
+    expect(hookResult!.isLoading).toBe(false);
+  });
+
+  it('setLanguage() switches language, clears cache, and re-fetches', async () => {
+    // First render in DE
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      json: async () => ({ translations: { 'Hello||': 'Hallo' }, plurals: {} }),
+    });
+    // After switch to ES
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      json: async () => ({ translations: { 'Hello||': 'Hola' }, plurals: {} }),
+    });
+
+    let hookRef: UseTransDuckReturn | null = null;
+
+    function TestComp() {
+      const hook = useTransDuck();
+      hookRef = hook;
+      return <span data-testid="text">{hook.t('Hello')}</span>;
+    }
+
+    render(
+      <TransDuckProvider language="DE">
+        <TestComp />
+      </TransDuckProvider>
+    );
+
+    // Wait for DE translations
+    await waitFor(() => {
+      expect(screen.getByTestId('text').textContent).toBe('Hallo');
+    });
+
+    // Switch to ES
+    await act(async () => {
+      hookRef!.setLanguage('ES');
+    });
+
+    // Wait for ES translations
+    await waitFor(() => {
+      expect(screen.getByTestId('text').textContent).toBe('Hola');
+    });
+
+    expect(hookRef!.language).toBe('ES');
+  });
+
+  it('setLanguage() with current language is a no-op', async () => {
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      json: async () => ({ translations: { 'Hello||': 'Hallo' }, plurals: {} }),
+    });
+
+    let hookRef: UseTransDuckReturn | null = null;
+
+    function TestComp() {
+      const hook = useTransDuck();
+      hookRef = hook;
+      return <span data-testid="text">{hook.t('Hello')}</span>;
+    }
+
+    render(
+      <TransDuckProvider language="DE">
+        <TestComp />
+      </TransDuckProvider>
+    );
+
+    await waitFor(() => {
+      expect(screen.getByTestId('text').textContent).toBe('Hallo');
+    });
+
+    mockFetch.mockClear();
+
+    await act(async () => {
+      hookRef!.setLanguage('DE');
+    });
+
+    expect(mockFetch).not.toHaveBeenCalled();
+    expect(screen.getByTestId('text').textContent).toBe('Hallo');
+  });
+
+  it('setLanguage() to source language skips fetch', async () => {
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      json: async () => ({ translations: { 'Hello||': 'Hallo' }, plurals: {} }),
+    });
+
+    let hookRef: UseTransDuckReturn | null = null;
+
+    function TestComp() {
+      const hook = useTransDuck();
+      hookRef = hook;
+      return <span data-testid="text">{hook.t('Hello')}</span>;
+    }
+
+    render(
+      <TransDuckProvider language="DE" sourceLang="EN">
+        <TestComp />
+      </TransDuckProvider>
+    );
+
+    await waitFor(() => {
+      expect(screen.getByTestId('text').textContent).toBe('Hallo');
+    });
+
+    mockFetch.mockClear();
+
+    await act(async () => {
+      hookRef!.setLanguage('EN');
+    });
+
+    await waitFor(() => {
+      expect(screen.getByTestId('text').textContent).toBe('Hello');
+    });
+    expect(mockFetch).not.toHaveBeenCalled();
+  });
+
+  it('isLoading is true during language switch fetch', async () => {
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      json: async () => ({ translations: { 'Hello||': 'Hallo' }, plurals: {} }),
+    });
+
+    let resolveSecondFetch: ((value: unknown) => void) | null = null;
+    mockFetch.mockImplementationOnce(() => new Promise(resolve => {
+      resolveSecondFetch = resolve;
+    }));
+
+    let hookRef: UseTransDuckReturn | null = null;
+
+    function TestComp() {
+      const hook = useTransDuck();
+      hookRef = hook;
+      return <span data-testid="text">{hook.t('Hello')}</span>;
+    }
+
+    render(
+      <TransDuckProvider language="DE">
+        <TestComp />
+      </TransDuckProvider>
+    );
+
+    await waitFor(() => {
+      expect(screen.getByTestId('text').textContent).toBe('Hallo');
+    });
+
+    await act(async () => {
+      hookRef!.setLanguage('ES');
+    });
+
+    expect(hookRef!.isLoading).toBe(true);
+
+    await act(async () => {
+      resolveSecondFetch!({
+        ok: true,
+        json: async () => ({ translations: { 'Hello||': 'Hola' }, plurals: {} }),
+      });
+    });
+
+    await waitFor(() => {
+      expect(hookRef!.isLoading).toBe(false);
+      expect(screen.getByTestId('text').textContent).toBe('Hola');
+    });
+  });
+
+  it('isLoading clears on fetch error during language switch', async () => {
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      json: async () => ({ translations: { 'Hello||': 'Hallo' }, plurals: {} }),
+    });
+    mockFetch.mockRejectedValueOnce(new Error('Network error'));
+
+    let hookRef: UseTransDuckReturn | null = null;
+
+    function TestComp() {
+      const hook = useTransDuck();
+      hookRef = hook;
+      return <span data-testid="text">{hook.t('Hello')}</span>;
+    }
+
+    render(
+      <TransDuckProvider language="DE">
+        <TestComp />
+      </TransDuckProvider>
+    );
+
+    await waitFor(() => {
+      expect(screen.getByTestId('text').textContent).toBe('Hallo');
+    });
+
+    await act(async () => {
+      hookRef!.setLanguage('ES');
+    });
+
+    await waitFor(() => {
+      expect(hookRef!.isLoading).toBe(false);
+    });
+  });
+
+  it('discards stale fetch response when language changes during fetch', async () => {
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      json: async () => ({ translations: { 'Hello||': 'Hallo' }, plurals: {} }),
+    });
+
+    let resolveFRFetch: ((value: unknown) => void) | null = null;
+    mockFetch.mockImplementationOnce(() => new Promise(resolve => {
+      resolveFRFetch = resolve;
+    }));
+
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      json: async () => ({ translations: { 'Hello||': 'Hola' }, plurals: {} }),
+    });
+
+    let hookRef: UseTransDuckReturn | null = null;
+
+    function TestComp() {
+      const hook = useTransDuck();
+      hookRef = hook;
+      return <span data-testid="text">{hook.t('Hello')}</span>;
+    }
+
+    render(
+      <TransDuckProvider language="DE">
+        <TestComp />
+      </TransDuckProvider>
+    );
+
+    await waitFor(() => {
+      expect(screen.getByTestId('text').textContent).toBe('Hallo');
+    });
+
+    await act(async () => {
+      hookRef!.setLanguage('FR');
+    });
+
+    await act(async () => {
+      hookRef!.setLanguage('ES');
+    });
+
+    await waitFor(() => {
+      expect(screen.getByTestId('text').textContent).toBe('Hola');
+    });
+
+    await act(async () => {
+      resolveFRFetch!({
+        ok: true,
+        json: async () => ({ translations: { 'Hello||': 'Bonjour' }, plurals: {} }),
+      });
+    });
+
+    expect(screen.getByTestId('text').textContent).toBe('Hola');
+    expect(hookRef!.language).toBe('ES');
+  });
+
+  it('changing language prop triggers switchLanguage with isLoading', async () => {
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      json: async () => ({ translations: { 'Hello||': 'Hallo' }, plurals: {} }),
+    });
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      json: async () => ({ translations: { 'Hello||': 'Hola' }, plurals: {} }),
+    });
+
+    let hookRef: UseTransDuckReturn | null = null;
+
+    function TestComp() {
+      const hook = useTransDuck();
+      hookRef = hook;
+      return <span data-testid="text">{hook.t('Hello')}</span>;
+    }
+
+    const { rerender } = render(
+      <TransDuckProvider language="DE">
+        <TestComp />
+      </TransDuckProvider>
+    );
+
+    await waitFor(() => {
+      expect(screen.getByTestId('text').textContent).toBe('Hallo');
+    });
+
+    rerender(
+      <TransDuckProvider language="ES">
+        <TestComp />
+      </TransDuckProvider>
+    );
+
+    await waitFor(() => {
+      expect(screen.getByTestId('text').textContent).toBe('Hola');
+      expect(hookRef!.language).toBe('ES');
+    });
+  });
+
+  it('useTransDuck() still works without destructuring (backward compat)', async () => {
+    mockFetch.mockResolvedValue({
+      ok: true,
+      json: async () => ({ translations: { 'Hello||': 'Hallo' }, plurals: {} }),
+    });
+
+    function TestComp() {
+      useTransDuck();
+      return <span data-testid="text">{t('Hello')}</span>;
+    }
+
+    render(
+      <TransDuckProvider language="DE">
+        <TestComp />
+      </TransDuckProvider>
+    );
+
+    await waitFor(() => {
+      expect(screen.getByTestId('text').textContent).toBe('Hallo');
+    });
+  });
 });