canopy-i18n 0.7.0 → 0.8.0

package/README.md

@@ -2,9 +2,6 @@
 
 A tiny, type-safe i18n library for building localized messages with builder pattern and applying locales across nested data structures.
 
-![スクリーンショット](https://raw.githubusercontent.com/mohhh-ok/canopy-i18n/main/docs/images/hero.gif)
-
-
 ## Features
 - **AI-friendly**: Full type safety and single-file colocation give AI assistants complete context for accurate code generation.
 - **Type-safe**: Compile-time safety for locale keys with full TypeScript IntelliSense support.
@@ -348,6 +345,117 @@ console.log(localized.content.sidebar.widget()); // "Widget"
 ```
 
 
+## React Integration
+
+`canopy-i18n/react` provides a tiny factory that returns a Provider, hooks, and a pre-bound `defineMessage` — all sharing the same `Locale` type.
+
+```tsx
+// i18n.ts
+import { createI18nReact } from 'canopy-i18n/react';
+
+export const LOCALES = ['en', 'ja'] as const;
+
+export const { i18n, LocaleProvider, useLocale, useBindLocale } =
+  createI18nReact(LOCALES);
+
+export const appI18n = i18n({
+  title: { en: 'My App', ja: 'マイアプリ' },
+  greeting: (ctx: { name: string }) => ({
+    en: `Hello, ${ctx.name}!`,
+    ja: `こんにちは、${ctx.name}さん！`,
+  }),
+});
+```
+
+```tsx
+// main.tsx
+import { LocaleProvider } from './i18n';
+
+<LocaleProvider defaultLocale="en">
+  <App />
+</LocaleProvider>
+```
+
+`LocaleProvider` also supports a controlled mode for integrating with URL routing, cookies, or external state:
+
+```tsx
+// Controlled mode: locale is owned by the parent
+<LocaleProvider locale={currentLocale} onLocaleChange={setCurrentLocale}>
+  <App />
+</LocaleProvider>
+```
+
+In controlled mode, `setLocale` from `useLocale()` calls your `onLocaleChange` handler instead of mutating internal state.
+
+`createI18nReact` also accepts a factory-level `useLocaleSource` for source-driven locale (e.g. external store, URL hook, cookie). When set, the Provider reads the locale from this hook and `setLocale` calls `onLocaleChange` instead of mutating internal state:
+
+```tsx
+export const { LocaleProvider, useLocale } = createI18nReact(LOCALES, {
+  useLocaleSource: () => useMyStore((s) => s.locale),
+  onLocaleChange: (l) => useMyStore.getState().setLocale(l),
+});
+
+<LocaleProvider>
+  <App />
+</LocaleProvider>
+```
+
+For common sources, `canopy-i18n/react` ships ready-made factories. Each returns the same shape as `createI18nReact` and operates in source-driven mode:
+
+```tsx
+import {
+  createHashI18nReact,     // URL hash (#ja)
+  createSearchI18nReact,   // URL search param (?lang=ja, configurable via { param })
+  createPathnameI18nReact, // URL pathname prefix (/ja/..., configurable via { basePath })
+  createStorageI18nReact,  // localStorage (configurable via { key })
+  createCookieI18nReact,   // Cookie (configurable via { key, maxAge, path, sameSite })
+} from 'canopy-i18n/react';
+
+export const { LocaleProvider, useLocale, useBindLocale } =
+  createHashI18nReact(LOCALES);
+
+// Render <LocaleProvider> with no props.
+```
+
+```tsx
+// App.tsx
+import { appI18n, useBindLocale, useLocale } from './i18n';
+
+function App() {
+  const m = useBindLocale({ appI18n });
+  const { locale, setLocale } = useLocale();
+
+  return (
+    <div>
+      <h1>{m.appI18n.title()}</h1>
+      <p>{m.appI18n.greeting({ name: 'Taro' })}</p>
+      <button onClick={() => setLocale(locale === 'en' ? 'ja' : 'en')}>
+        {locale}
+      </button>
+    </div>
+  );
+}
+```
+
+### Factory return value
+
+```ts
+const {
+  locales,         // the LOCALES tuple you passed in
+  i18n,            // function: i18n(entries) → ChainBuilder bound to LOCALES
+  LocaleProvider,  // uncontrolled or controlled (see above)
+  useLocale,       // () => { locale, setLocale }
+  useBindLocale,   // memoized bindLocale, locale type-checked
+} = createI18nReact(['en', 'ja'] as const);
+```
+
+`i18n` is a shorthand for `ChainBuilder.add` bound to a base builder. Each `i18n({...})` call returns an independent `ChainBuilder`, so you can keep chaining `.add({...}).add({...})` for additional entries.
+
+- `useBindLocale(msgsDef)` is memoized per `(msgsDef, locale)` pair.
+- The `Locale` type is derived from the `LOCALES` tuple. Passing a `ChainBuilder` whose locales differ from the Provider's locales is rejected at compile time.
+- `createI18nReact` itself has no built-in persistence. Use a built-in wrapper (`createHash/Search/Pathname/Storage/CookieI18nReact`) for common sources, or pass your own `useLocaleSource` / `onLocaleChange` for anything else.
+- React is a `peerDependency` (`>=18`). Non-React users can ignore the `/react` subpath entirely.
+
 ## Repository
 
 https://github.com/MOhhh-ok/canopy-i18n

package/dist/adaptors/next/_client.d.ts

@@ -0,0 +1,32 @@
+import Link from "next/link";
+import { type ComponentProps, type ReactNode } from "react";
+import type { UseLocaleSource } from "../react/createI18nReact.js";
+export type { UseLocaleSource };
+export interface SetLocaleOptions {
+    mode?: "push" | "replace";
+}
+export interface LocaleContextValue {
+    locale: string;
+    setLocale: (locale: string, options?: SetLocaleOptions) => void;
+    locales: readonly string[];
+    pathPrefix: string;
+}
+export declare function swapLocaleInPath(pathname: string, locale: string, pathPrefix?: string): string;
+export declare function createParamsLocaleSource(paramKey: string): UseLocaleSource;
+export interface ClientLocaleProviderProps {
+    children: ReactNode;
+    locales: readonly string[];
+    fallbackLocale?: string;
+    paramKey?: string;
+    useLocaleSource?: UseLocaleSource;
+    pathPrefix?: string;
+}
+export declare function ClientLocaleProvider({ children, locales, fallbackLocale, paramKey, useLocaleSource, pathPrefix, }: ClientLocaleProviderProps): import("react/jsx-runtime").JSX.Element;
+export declare function useLocaleClient(): LocaleContextValue;
+export declare function useBindLocaleClient<T extends object>(messages: T): unknown;
+export interface ClientLocaleLinkProps extends Omit<ComponentProps<typeof Link>, "href" | "locale"> {
+    locale: string;
+    href?: string;
+    children?: ReactNode;
+}
+export declare function ClientLocaleLink({ locale, href, children, ...rest }: ClientLocaleLinkProps): import("react/jsx-runtime").JSX.Element;

package/dist/adaptors/next/_client.js

@@ -0,0 +1,61 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import Link from "next/link";
+import { useParams, usePathname, useRouter } from "next/navigation";
+import { createContext, useCallback, useContext, useMemo, } from "react";
+import { bindLocale } from "../../bindLocale.js";
+const LocaleContext = createContext(undefined);
+export function swapLocaleInPath(pathname, locale, pathPrefix = "/") {
+    const prefixSegments = pathPrefix.split("/").filter(Boolean);
+    const localeIndex = prefixSegments.length + 1;
+    const parts = pathname.split("/");
+    while (parts.length <= localeIndex) {
+        parts.push("");
+    }
+    parts[localeIndex] = locale;
+    return parts.join("/") || "/";
+}
+export function createParamsLocaleSource(paramKey) {
+    return () => {
+        const params = useParams();
+        return params?.[paramKey];
+    };
+}
+export function ClientLocaleProvider({ children, locales, fallbackLocale, paramKey = "locale", useLocaleSource, pathPrefix = "/", }) {
+    const router = useRouter();
+    const pathname = usePathname();
+    const params = useParams();
+    const sourceLocale = useLocaleSource
+        ? useLocaleSource()
+        : params?.[paramKey];
+    const locale = sourceLocale ?? fallbackLocale ?? locales[0];
+    const setLocale = useCallback((next, options) => {
+        const target = swapLocaleInPath(pathname, next, pathPrefix);
+        if (options?.mode === "replace") {
+            router.replace(target);
+        }
+        else {
+            router.push(target);
+        }
+    }, [pathname, router, pathPrefix]);
+    const value = useMemo(() => ({ locale, setLocale, locales, pathPrefix }), [locale, setLocale, locales, pathPrefix]);
+    return (_jsx(LocaleContext.Provider, { value: value, children: children }));
+}
+export function useLocaleClient() {
+    const ctx = useContext(LocaleContext);
+    if (!ctx) {
+        throw new Error("useLocale must be used within a LocaleProvider");
+    }
+    return ctx;
+}
+export function useBindLocaleClient(messages) {
+    const { locale } = useLocaleClient();
+    return useMemo(() => bindLocale(messages, locale), [messages, locale]);
+}
+export function ClientLocaleLink({ locale, href, children, ...rest }) {
+    const pathname = usePathname();
+    const ctx = useContext(LocaleContext);
+    const pathPrefix = ctx?.pathPrefix ?? "/";
+    const target = useMemo(() => href ?? swapLocaleInPath(pathname, locale, pathPrefix), [href, pathname, locale, pathPrefix]);
+    return (_jsx(Link, { href: target, ...rest, children: children }));
+}

package/dist/adaptors/next/createI18nNext.d.ts

@@ -0,0 +1,53 @@
+import type { ComponentProps, ReactElement, ReactNode } from "react";
+import type Link from "next/link";
+import { type ChainBuilder } from "../../chainBuilder.js";
+import type { DeepLocaleConstraint, DeepUnwrap, ResolveServerLocale } from "../react/createI18nReact.js";
+import { type SetLocaleOptions, swapLocaleInPath, type UseLocaleSource } from "./_client.js";
+export type { ResolveServerLocale, SetLocaleOptions, UseLocaleSource };
+export { swapLocaleInPath };
+export declare function createParamsResolveServerLocale(paramKey: string): ResolveServerLocale;
+export interface NextLocaleProviderProps<Locale extends string> {
+    children: ReactNode;
+    fallbackLocale?: Locale;
+}
+export interface LocaleLinkProps<Locale extends string> extends Omit<ComponentProps<typeof Link>, "href" | "locale"> {
+    locale: Locale;
+    href?: string;
+    children?: ReactNode;
+}
+export interface LocaleContextValue<Locale extends string> {
+    locale: Locale;
+    setLocale: (locale: Locale, options?: SetLocaleOptions) => void;
+    locales: readonly Locale[];
+    pathPrefix: string;
+}
+export type LocalePageParams<L extends readonly string[], K extends string = "locale"> = Promise<{
+    [P in K]: L[number];
+}>;
+export type LocalePageProps<L extends readonly string[], K extends string = "locale"> = {
+    params: LocalePageParams<L, K>;
+};
+export interface CreateI18nNextOptions<K extends string = string> {
+    paramKey?: K;
+    pathPrefix?: string;
+    resolveServerLocale?: ResolveServerLocale;
+}
+export interface I18nNextInstance<L extends readonly string[], K extends string = "locale"> {
+    locales: L;
+    paramKey: K;
+    pathPrefix: string;
+    i18n: ChainBuilder<L, {}>["add"];
+    bindLocale: {
+        <T extends object>(messages: T & DeepLocaleConstraint<T, L[number]>, locale: L[number]): DeepUnwrap<T>;
+        <T extends object>(messages: T & DeepLocaleConstraint<T, L[number]>, params: LocalePageParams<L, K>): Promise<DeepUnwrap<T>>;
+        <T extends object>(messages: T & DeepLocaleConstraint<T, L[number]>, input: unknown): Promise<DeepUnwrap<T>>;
+    };
+    generateStaticParams: () => Array<{
+        [P in K]: L[number];
+    }>;
+    LocaleProvider: (props: NextLocaleProviderProps<L[number]>) => ReactElement;
+    LocaleLink: (props: LocaleLinkProps<L[number]>) => ReactElement;
+    useLocale: () => LocaleContextValue<L[number]>;
+    useBindLocale: <T extends object>(messages: T & DeepLocaleConstraint<T, L[number]>) => DeepUnwrap<T>;
+}
+export declare function createI18nNext<const L extends readonly string[], const K extends string = "locale">(locales: L, options?: CreateI18nNextOptions<K>): I18nNextInstance<L, K>;

package/dist/adaptors/next/createI18nNext.js

@@ -0,0 +1,45 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { bindLocale as plainBindLocale } from "../../bindLocale.js";
+import { createI18n } from "../../chainBuilder.js";
+import { ClientLocaleLink, ClientLocaleProvider, swapLocaleInPath, useBindLocaleClient, useLocaleClient, } from "./_client.js";
+export { swapLocaleInPath };
+export function createParamsResolveServerLocale(paramKey) {
+    return async (input) => {
+        if (input == null)
+            return undefined;
+        const resolved = await input;
+        return resolved?.[paramKey];
+    };
+}
+export function createI18nNext(locales, options) {
+    const paramKey = (options?.paramKey ?? "locale");
+    const pathPrefix = options?.pathPrefix ?? "/";
+    const resolveServerLocale = options?.resolveServerLocale ?? createParamsResolveServerLocale(paramKey);
+    function LocaleProvider({ children, fallbackLocale }) {
+        return (_jsx(ClientLocaleProvider, { locales: locales, fallbackLocale: fallbackLocale, paramKey: paramKey, pathPrefix: pathPrefix, children: children }));
+    }
+    const builder = createI18n(locales);
+    const i18n = (entries) => builder.add(entries);
+    return {
+        locales,
+        paramKey,
+        pathPrefix,
+        i18n,
+        bindLocale: ((messages, input) => {
+            if (typeof input === "string") {
+                return plainBindLocale(messages, input);
+            }
+            const resolved = resolveServerLocale(input);
+            if (resolved &&
+                typeof resolved.then === "function") {
+                return resolved.then((locale) => plainBindLocale(messages, locale));
+            }
+            return plainBindLocale(messages, resolved);
+        }),
+        generateStaticParams: () => locales.map((locale) => ({ [paramKey]: locale })),
+        LocaleProvider,
+        LocaleLink: ClientLocaleLink,
+        useLocale: useLocaleClient,
+        useBindLocale: useBindLocaleClient,
+    };
+}

package/dist/adaptors/next/index.d.ts

@@ -0,0 +1,2 @@
+export { createI18nNext, createParamsResolveServerLocale, swapLocaleInPath, } from "./createI18nNext.js";
+export type { CreateI18nNextOptions, I18nNextInstance, LocaleContextValue, LocaleLinkProps, LocalePageParams, LocalePageProps, NextLocaleProviderProps, ResolveServerLocale, SetLocaleOptions, UseLocaleSource, } from "./createI18nNext.js";

package/dist/adaptors/next/index.js

@@ -0,0 +1 @@
+export { createI18nNext, createParamsResolveServerLocale, swapLocaleInPath, } from "./createI18nNext.js";

package/dist/adaptors/react/createCookieI18nReact.d.ts

@@ -0,0 +1,8 @@
+import { type I18nReactInstance } from "./createI18nReact.js";
+export interface CreateCookieI18nReactOptions {
+    key?: string;
+    maxAge?: number;
+    path?: string;
+    sameSite?: "Strict" | "Lax" | "None";
+}
+export declare function createCookieI18nReact<const L extends readonly string[]>(locales: L, options?: CreateCookieI18nReactOptions): I18nReactInstance<L>;

package/dist/adaptors/react/createCookieI18nReact.js

@@ -0,0 +1,47 @@
+import { useSyncExternalStore } from "react";
+import { createI18nReact } from "./createI18nReact.js";
+const CHANGE_EVENT = "canopy-i18n-cookie-change";
+const ONE_YEAR_SECONDS = 60 * 60 * 24 * 365;
+function readCookie(key) {
+    for (const c of document.cookie.split("; ")) {
+        const eq = c.indexOf("=");
+        if (eq < 0)
+            continue;
+        if (c.slice(0, eq) === key)
+            return decodeURIComponent(c.slice(eq + 1));
+    }
+    return undefined;
+}
+function writeCookie(key, value, options) {
+    const parts = [
+        `${key}=${encodeURIComponent(value)}`,
+        `path=${options.path ?? "/"}`,
+        `max-age=${options.maxAge ?? ONE_YEAR_SECONDS}`,
+        `SameSite=${options.sameSite ?? "Lax"}`,
+    ];
+    document.cookie = parts.join("; ");
+}
+export function createCookieI18nReact(locales, options = {}) {
+    const key = options.key ?? "canopy-i18n-locale";
+    function read() {
+        const v = readCookie(key);
+        return v && locales.includes(v)
+            ? v
+            : undefined;
+    }
+    function subscribe(callback) {
+        window.addEventListener(CHANGE_EVENT, callback);
+        return () => window.removeEventListener(CHANGE_EVENT, callback);
+    }
+    function useCookieLocale() {
+        return useSyncExternalStore(subscribe, read, () => undefined);
+    }
+    function setCookieLocale(locale) {
+        writeCookie(key, locale, options);
+        window.dispatchEvent(new Event(CHANGE_EVENT));
+    }
+    return createI18nReact(locales, {
+        useLocaleSource: useCookieLocale,
+        onLocaleChange: setCookieLocale,
+    });
+}

package/dist/adaptors/react/createHashI18nReact.d.ts

@@ -0,0 +1,2 @@
+import { type I18nReactInstance } from "./createI18nReact.js";
+export declare function createHashI18nReact<const L extends readonly string[]>(locales: L): I18nReactInstance<L>;

package/dist/adaptors/react/createHashI18nReact.js

@@ -0,0 +1,24 @@
+import { useSyncExternalStore } from "react";
+import { createI18nReact } from "./createI18nReact.js";
+function subscribe(callback) {
+    window.addEventListener("hashchange", callback);
+    return () => window.removeEventListener("hashchange", callback);
+}
+export function createHashI18nReact(locales) {
+    function read() {
+        const hash = window.location.hash.slice(1);
+        return locales.includes(hash)
+            ? hash
+            : undefined;
+    }
+    function useHashLocale() {
+        return useSyncExternalStore(subscribe, read, () => undefined);
+    }
+    function setHashLocale(locale) {
+        window.location.hash = locale;
+    }
+    return createI18nReact(locales, {
+        useLocaleSource: useHashLocale,
+        onLocaleChange: setHashLocale,
+    });
+}

package/dist/adaptors/react/createI18nReact.d.ts

@@ -0,0 +1,50 @@
+import { type ReactElement, type ReactNode } from "react";
+import { ChainBuilder } from "../../chainBuilder.js";
+import { I18nMessage, type LocalizedMessage } from "../../message.js";
+type Equal<A, B> = [A] extends [B] ? ([B] extends [A] ? true : false) : false;
+export type DeepLocaleConstraint<T, Locale extends string> = T extends ChainBuilder<infer LL, any> ? Equal<LL[number], Locale> extends true ? T : never : T extends I18nMessage<infer LL, any> ? Equal<LL[number], Locale> extends true ? T : never : T extends (...args: any[]) => any ? T : T extends readonly any[] ? {
+    readonly [K in keyof T]: DeepLocaleConstraint<T[K], Locale>;
+} : T extends object ? {
+    [K in keyof T]: DeepLocaleConstraint<T[K], Locale>;
+} : T;
+export type DeepUnwrap<T> = T extends I18nMessage<infer Ls, infer C> ? LocalizedMessage<Ls, C> : T extends ChainBuilder<infer Ls, infer Messages> ? {
+    [K in keyof Messages]: Messages[K] extends I18nMessage<Ls, infer C> ? LocalizedMessage<Ls, C> : never;
+} : T extends readonly any[] ? {
+    [K in keyof T]: DeepUnwrap<T[K]>;
+} : T extends object ? {
+    [K in keyof T]: DeepUnwrap<T[K]>;
+} : T;
+export interface LocaleContextValue<Locale extends string> {
+    locale: Locale;
+    setLocale: (locale: Locale) => void;
+}
+export type UseLocaleSource<Locale extends string = string> = () => Locale | undefined;
+export type ResolveServerLocale<Locale extends string = string> = (input: unknown) => Locale | undefined | Promise<Locale | undefined>;
+export type LocaleProviderProps<Locale extends string> = {
+    children: ReactNode;
+} & ({
+    defaultLocale: Locale;
+    locale?: undefined;
+    onLocaleChange?: undefined;
+} | {
+    locale: Locale;
+    onLocaleChange: (locale: Locale) => void;
+    defaultLocale?: undefined;
+} | {
+    defaultLocale?: undefined;
+    locale?: undefined;
+    onLocaleChange?: undefined;
+});
+export interface CreateI18nReactOptions<Locale extends string = string> {
+    useLocaleSource?: UseLocaleSource<Locale>;
+    onLocaleChange?: (locale: Locale) => void;
+}
+export interface I18nReactInstance<L extends readonly string[]> {
+    locales: L;
+    i18n: ChainBuilder<L, {}>["add"];
+    LocaleProvider: (props: LocaleProviderProps<L[number]>) => ReactElement;
+    useLocale: () => LocaleContextValue<L[number]>;
+    useBindLocale: <T extends object>(msgsDef: T & DeepLocaleConstraint<T, L[number]>) => DeepUnwrap<T>;
+}
+export declare function createI18nReact<const L extends readonly string[]>(locales: L, options?: CreateI18nReactOptions<L[number]>): I18nReactInstance<L>;
+export {};

package/dist/adaptors/react/createI18nReact.js

@@ -0,0 +1,55 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useContext, useMemo, useState, } from "react";
+import { bindLocale } from "../../bindLocale.js";
+import { createI18n } from "../../chainBuilder.js";
+export function createI18nReact(locales, options) {
+    const Context = createContext(undefined);
+    const factorySource = options?.useLocaleSource;
+    const factoryOnChange = options?.onLocaleChange;
+    function LocaleProvider(props) {
+        const { children } = props;
+        const sourceLocale = factorySource?.();
+        const isControlled = props.locale !== undefined;
+        const [internalLocale, setInternalLocale] = useState((props.defaultLocale ?? props.locale ?? sourceLocale ?? locales[0]));
+        const locale = factorySource
+            ? (sourceLocale ?? locales[0])
+            : isControlled
+                ? props.locale
+                : internalLocale;
+        const setLocale = (next) => {
+            factoryOnChange?.(next);
+            if (factorySource)
+                return;
+            if (isControlled) {
+                props.onLocaleChange(next);
+            }
+            else {
+                setInternalLocale(next);
+            }
+        };
+        const value = useMemo(() => ({ locale, setLocale }), 
+        // controlled では onLocaleChange の参照変化にも追従する
+        [locale, isControlled, isControlled ? props.onLocaleChange : null]);
+        return _jsx(Context.Provider, { value: value, children: children });
+    }
+    function useLocale() {
+        const ctx = useContext(Context);
+        if (!ctx) {
+            throw new Error("useLocale must be used within a LocaleProvider");
+        }
+        return ctx;
+    }
+    function useBindLocale(msgsDef) {
+        const { locale } = useLocale();
+        return useMemo(() => bindLocale(msgsDef, locale), [msgsDef, locale]);
+    }
+    const builder = createI18n(locales);
+    const i18n = (entries) => builder.add(entries);
+    return {
+        locales,
+        i18n,
+        LocaleProvider,
+        useLocale,
+        useBindLocale,
+    };
+}

package/dist/adaptors/react/createPathnameI18nReact.d.ts

@@ -0,0 +1,5 @@
+import { type I18nReactInstance } from "./createI18nReact.js";
+export interface CreatePathnameI18nReactOptions {
+    basePath?: string;
+}
+export declare function createPathnameI18nReact<const L extends readonly string[]>(locales: L, options?: CreatePathnameI18nReactOptions): I18nReactInstance<L>;

package/dist/adaptors/react/createPathnameI18nReact.js

@@ -0,0 +1,45 @@
+import { useSyncExternalStore } from "react";
+import { createI18nReact } from "./createI18nReact.js";
+const CHANGE_EVENT = "canopy-i18n-pathname-change";
+function subscribe(callback) {
+    window.addEventListener("popstate", callback);
+    window.addEventListener(CHANGE_EVENT, callback);
+    return () => {
+        window.removeEventListener("popstate", callback);
+        window.removeEventListener(CHANGE_EVENT, callback);
+    };
+}
+export function createPathnameI18nReact(locales, options = {}) {
+    const basePath = (options.basePath ?? "").replace(/\/$/, "");
+    function getSegments() {
+        const path = window.location.pathname;
+        const matchesBase = !basePath || path === basePath || path.startsWith(`${basePath}/`);
+        const stripped = matchesBase ? path.slice(basePath.length) : path;
+        return stripped.split("/").filter(Boolean);
+    }
+    function read() {
+        const seg = getSegments()[0];
+        return seg && locales.includes(seg)
+            ? seg
+            : undefined;
+    }
+    function usePathnameLocale() {
+        return useSyncExternalStore(subscribe, read, () => undefined);
+    }
+    function setPathnameLocale(locale) {
+        const segments = getSegments();
+        const head = segments[0];
+        const replaced = head && locales.includes(head)
+            ? [locale, ...segments.slice(1)]
+            : [locale, ...segments];
+        const newPath = `${basePath}/${replaced.join("/")}`;
+        const url = new URL(window.location.href);
+        url.pathname = newPath;
+        window.history.pushState({}, "", url);
+        window.dispatchEvent(new Event(CHANGE_EVENT));
+    }
+    return createI18nReact(locales, {
+        useLocaleSource: usePathnameLocale,
+        onLocaleChange: setPathnameLocale,
+    });
+}

package/dist/adaptors/react/createSearchI18nReact.d.ts

@@ -0,0 +1,5 @@
+import { type I18nReactInstance } from "./createI18nReact.js";
+export interface CreateSearchI18nReactOptions {
+    param?: string;
+}
+export declare function createSearchI18nReact<const L extends readonly string[]>(locales: L, options?: CreateSearchI18nReactOptions): I18nReactInstance<L>;

package/dist/adaptors/react/createSearchI18nReact.js

@@ -0,0 +1,33 @@
+import { useSyncExternalStore } from "react";
+import { createI18nReact } from "./createI18nReact.js";
+const CHANGE_EVENT = "canopy-i18n-search-change";
+function subscribe(callback) {
+    window.addEventListener("popstate", callback);
+    window.addEventListener(CHANGE_EVENT, callback);
+    return () => {
+        window.removeEventListener("popstate", callback);
+        window.removeEventListener(CHANGE_EVENT, callback);
+    };
+}
+export function createSearchI18nReact(locales, options = {}) {
+    const param = options.param ?? "lang";
+    function read() {
+        const v = new URLSearchParams(window.location.search).get(param);
+        return v && locales.includes(v)
+            ? v
+            : undefined;
+    }
+    function useSearchLocale() {
+        return useSyncExternalStore(subscribe, read, () => undefined);
+    }
+    function setSearchLocale(locale) {
+        const url = new URL(window.location.href);
+        url.searchParams.set(param, locale);
+        window.history.pushState({}, "", url);
+        window.dispatchEvent(new Event(CHANGE_EVENT));
+    }
+    return createI18nReact(locales, {
+        useLocaleSource: useSearchLocale,
+        onLocaleChange: setSearchLocale,
+    });
+}

package/dist/adaptors/react/createStorageI18nReact.d.ts

@@ -0,0 +1,5 @@
+import { type I18nReactInstance } from "./createI18nReact.js";
+export interface CreateStorageI18nReactOptions {
+    key?: string;
+}
+export declare function createStorageI18nReact<const L extends readonly string[]>(locales: L, options?: CreateStorageI18nReactOptions): I18nReactInstance<L>;

package/dist/adaptors/react/createStorageI18nReact.js

@@ -0,0 +1,35 @@
+import { useSyncExternalStore } from "react";
+import { createI18nReact } from "./createI18nReact.js";
+export function createStorageI18nReact(locales, options = {}) {
+    const key = options.key ?? "canopy-i18n-locale";
+    const listeners = new Set();
+    function read() {
+        const v = localStorage.getItem(key);
+        return v && locales.includes(v)
+            ? v
+            : undefined;
+    }
+    function subscribe(callback) {
+        listeners.add(callback);
+        const onStorage = (e) => {
+            if (e.key === key)
+                callback();
+        };
+        window.addEventListener("storage", onStorage);
+        return () => {
+            listeners.delete(callback);
+            window.removeEventListener("storage", onStorage);
+        };
+    }
+    function useStorageLocale() {
+        return useSyncExternalStore(subscribe, read, () => undefined);
+    }
+    function setStorageLocale(locale) {
+        localStorage.setItem(key, locale);
+        listeners.forEach((l) => l());
+    }
+    return createI18nReact(locales, {
+        useLocaleSource: useStorageLocale,
+        onLocaleChange: setStorageLocale,
+    });
+}

package/dist/adaptors/react/index.d.ts

@@ -0,0 +1,11 @@
+export { createI18nReact } from "./createI18nReact.js";
+export type { CreateI18nReactOptions, LocaleContextValue, LocaleProviderProps, ResolveServerLocale, UseLocaleSource, } from "./createI18nReact.js";
+export { createCookieI18nReact } from "./createCookieI18nReact.js";
+export type { CreateCookieI18nReactOptions } from "./createCookieI18nReact.js";
+export { createHashI18nReact } from "./createHashI18nReact.js";
+export { createPathnameI18nReact } from "./createPathnameI18nReact.js";
+export type { CreatePathnameI18nReactOptions } from "./createPathnameI18nReact.js";
+export { createSearchI18nReact } from "./createSearchI18nReact.js";
+export type { CreateSearchI18nReactOptions } from "./createSearchI18nReact.js";
+export { createStorageI18nReact } from "./createStorageI18nReact.js";
+export type { CreateStorageI18nReactOptions } from "./createStorageI18nReact.js";

package/dist/adaptors/react/index.js

@@ -0,0 +1,6 @@
+export { createI18nReact } from "./createI18nReact.js";
+export { createCookieI18nReact } from "./createCookieI18nReact.js";
+export { createHashI18nReact } from "./createHashI18nReact.js";
+export { createPathnameI18nReact } from "./createPathnameI18nReact.js";
+export { createSearchI18nReact } from "./createSearchI18nReact.js";
+export { createStorageI18nReact } from "./createStorageI18nReact.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "canopy-i18n",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "The Type-Safe i18n library that your IDE will Love",
   "type": "module",
   "main": "dist/index.js",
@@ -10,6 +10,28 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
       "default": "./dist/index.js"
+    },
+    "./react": {
+      "types": "./dist/adaptors/react/index.d.ts",
+      "import": "./dist/adaptors/react/index.js",
+      "default": "./dist/adaptors/react/index.js"
+    },
+    "./unstable_next": {
+      "types": "./dist/adaptors/next/index.d.ts",
+      "import": "./dist/adaptors/next/index.js",
+      "default": "./dist/adaptors/next/index.js"
+    }
+  },
+  "peerDependencies": {
+    "next": ">=14",
+    "react": ">=18"
+  },
+  "peerDependenciesMeta": {
+    "next": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
     }
   },
   "sideEffects": false,
@@ -23,16 +45,18 @@
   "scripts": {
     "dev": "tsc --watch",
     "build": "tsc",
-    "prepublishOnly": "pnpm run build",
+    "prepublishOnly": "bun run build",
     "type-check": "tsc -p . --noEmit",
     "test": "vitest run",
     "test:watch": "vitest",
-    "release": "release-it"
+    "_publish": "npm publish && git push --follow-tags && gh release create \"$(node -p \"require('./package.json').version\")\" --generate-notes"
   },
   "devDependencies": {
     "@tsconfig/node20": "^20.1.9",
     "@types/node": "^25.3.0",
-    "release-it": "^19.2.4",
+    "@types/react": "^19.2.14",
+    "next": "16",
+    "react": "^19.2.6",
     "typescript": "^5.9.3",
     "vitest": "^4.0.18"
   },

package/skills/SKILL.md

@@ -21,18 +21,9 @@ A type-safe i18n library using the builder pattern. This reference helps AI assi
 
 ```bash
 npm install canopy-i18n
-# or
-pnpm add canopy-i18n
-bun add canopy-i18n
 ```
 
-`package.json` must include `"type": "module"`:
-
-```json
-{
-  "type": "module"
-}
-```
+`package.json` must include `"type": "module"`.
 
 ---
 
@@ -40,213 +31,71 @@ bun add canopy-i18n
 
 ### `createI18n(locales)`
 
-Creates a builder instance. **`as const` is required** for type inference.
+Creates a builder. **`as const` is required** for type inference.
 
 ```ts
 import { createI18n } from 'canopy-i18n';
 
-// ✅ Correct: use as const
 const builder = createI18n(['en', 'ja'] as const);
-
-// ❌ Wrong: without as const, type becomes string[] and type inference is lost
-const builder = createI18n(['en', 'ja']);
 ```
 
-- **Argument**: `readonly string[]` — allowed locale keys
-- **Returns**: `ChainBuilder<Locales, {}>` — a chain builder instance
-
----
-
 ### `.add(entries)`
 
-Adds multiple messages at once. Each entry can be a static locale record or a template function.
+Adds messages. Each entry can be a static locale record or a template function. Static and template can be mixed in a single `.add()`.
 
 ```ts
-// Static messages
 const builder = createI18n(['en', 'ja'] as const)
   .add({
     title: { en: 'Title', ja: 'タイトル' },
-    greeting: { en: 'Hello', ja: 'こんにちは' },
-  });
-
-// Template functions
-const builder2 = createI18n(['en', 'ja'] as const)
-  .add({
     greeting: (ctx: { name: string; age: number }) => ({
       en: `Hello, ${ctx.name}. You are ${ctx.age}.`,
       ja: `こんにちは、${ctx.name}さん。${ctx.age}歳です。`,
     }),
   });
-
-// Mixing static and template messages in a single add()
-const builder3 = createI18n(['en', 'ja'] as const)
-  .add({
-    title: { en: 'Title', ja: 'タイトル' },
-    greeting: (ctx: { name: string }) => ({
-      en: `Hello, ${ctx.name}`,
-      ja: `こんにちは、${ctx.name}さん`,
-    }),
-  });
 ```
 
-- **entries**: `Record<K, Record<Locale, string> | ((ctx: C) => Record<Locale, string>)>`
-- **Returns**: new `ChainBuilder` (immutable)
-
----
+Returns a new `ChainBuilder` (immutable).
 
 ### `.build(locale)`
 
-Builds the final messages object.
+Builds the final messages object. Does not mutate the builder — you can build multiple locales from one builder. All messages are called as functions.
 
 ```ts
-const builder = createI18n(['en', 'ja'] as const)
-  .add({ title: { en: 'Title', ja: 'タイトル' } });
-
 const enMessages = builder.build('en');
-const jaMessages = builder.build('ja');
-
-// All messages are called as functions
-console.log(enMessages.title()); // "Title"
-console.log(jaMessages.title()); // "タイトル"
+console.log(enMessages.title());                          // "Title"
+console.log(enMessages.greeting({ name: 'Taro', age: 25 })); // "Hello, Taro. You are 25."
 ```
 
-- **Argument `locale`**: required
-- **Returns**: `{ [key]: () => R }` or `{ [key]: (ctx: C) => R }`
-- **Immutable**: `.build()` does not mutate the builder — you can generate multiple locales from one builder
-
----
-
 ### `bindLocale(obj, locale)`
 
-Recursively traverses an object/array and calls `.build(locale)` on all `ChainBuilder` instances found. Used for the namespace pattern (split files). Since `build()` requires a locale, `bindLocale` provides it at the point of use.
+Recursively traverses an object/array and calls `.build(locale)` on every `ChainBuilder` it finds. Used for the namespace pattern.
 
 ```ts
 import { bindLocale } from 'canopy-i18n';
 
-const data = {
-  common: commonBuilder,
-  nested: {
-    user: userBuilder,
-  },
-};
-
+const data = { common: commonBuilder, user: userBuilder };
 const messages = bindLocale(data, 'en');
-console.log(messages.common.hello());                    // "Hello"
-console.log(messages.nested.user.welcome({ name: 'John' })); // "Welcome, John"
+console.log(messages.common.hello());
 ```
 
-- **Argument `obj`**: any object/array containing `ChainBuilder` instances
-- **Argument `locale`**: locale string to apply
-- **Returns**: new structure with all builders resolved
-
 ---
 
 ## Critical Gotchas
 
-### 1. `as const` is required
-
-```ts
-// ✅ Correct
-createI18n(['en', 'ja'] as const)
-
-// ❌ Type error — locale keys become string, inference breaks
-createI18n(['en', 'ja'])
-```
-
-### 2. `.build()` is immutable
-
-```ts
-const builder = createI18n(['en', 'ja'] as const).add({ ... });
-
-// ✅ Multiple locales from one builder
-const enMessages = builder.build('en');
-const jaMessages = builder.build('ja');
-```
-
-### 3. ESM only
-
-```json
-// Required in package.json
-{ "type": "module" }
-```
-
-### 4. All messages must be called as functions
-
-```ts
-const m = builder.build('en');
-
-// ✅ Call as a function
-m.title()
-m.greeting({ name: 'Alice' })
-
-// ❌ Do not access as property — it is a function object, not a string
-m.title
-```
+| Mistake | Fix |
+|---------|-----|
+| `createI18n(['en', 'ja'])` | `createI18n(['en', 'ja'] as const)` — without `as const`, locale keys become `string` and inference breaks |
+| `messages.title` | `messages.title()` — all messages are functions, not strings |
+| Mutating builder via `build()` | `.build()` is immutable; build multiple locales from one builder |
+| CommonJS `require()` | ESM only; use `import` |
 
 ---
 
-## Common Patterns
-
-### Basic String Messages
-
-```ts
-import { createI18n } from 'canopy-i18n';
-
-const messages = createI18n(['en', 'ja'] as const)
-  .add({
-    title: { en: 'Title', ja: 'タイトル' },
-    greeting: { en: 'Hello', ja: 'こんにちは' },
-    farewell: { en: 'Goodbye', ja: 'さようなら' },
-  })
-  .build('en');
-
-console.log(messages.title());    // "Title"
-console.log(messages.greeting()); // "Hello"
-```
-
-### Template Functions (Variable Interpolation)
-
-```ts
-import { createI18n } from 'canopy-i18n';
-
-const messages = createI18n(['en', 'ja'] as const)
-  .add({
-    profile: (ctx: { name: string; age: number }) => ({
-      en: `Name: ${ctx.name}, Age: ${ctx.age}`,
-      ja: `名前: ${ctx.name}、年齢: ${ctx.age}歳`,
-    }),
-  })
-  .build('en');
-
-console.log(messages.profile({ name: 'Taro', age: 25 }));
-// "Name: Taro, Age: 25"
-```
-
-### Mixing Static and Template Messages
-
-```ts
-import { createI18n } from 'canopy-i18n';
-
-const messages = createI18n(['en', 'ja'] as const)
-  .add({
-    title: { en: 'Items', ja: 'アイテム' },
-    count: (ctx: { count: number }) => ({
-      en: `${ctx.count} items`,
-      ja: `${ctx.count}個のアイテム`,
-    }),
-  })
-  .build('en');
-
-console.log(messages.title());             // "Items"
-console.log(messages.count({ count: 5 })); // "5 items"
-```
-
-### Namespace Pattern (Split Files + bindLocale)
+## Namespace Pattern (Split Files + bindLocale)
 
 ```ts
 // i18n/locales.ts
 export const LOCALES = ['en', 'ja'] as const;
-export type Locale = (typeof LOCALES)[number];
 
 // i18n/common.ts
 import { createI18n } from 'canopy-i18n';
@@ -254,223 +103,143 @@ import { LOCALES } from './locales';
 
 export const common = createI18n(LOCALES).add({
   hello: { en: 'Hello', ja: 'こんにちは' },
-  goodbye: { en: 'Goodbye', ja: 'さようなら' },
 });
 
 // i18n/user.ts
-import { createI18n } from 'canopy-i18n';
-import { LOCALES } from './locales';
-
-export const user = createI18n(LOCALES)
-  .add({
-    welcome: (ctx: { name: string }) => ({
-      en: `Welcome, ${ctx.name}`,
-      ja: `ようこそ、${ctx.name}さん`,
-    }),
-  });
-
-// i18n/index.ts
-export { common } from './common';
-export { user } from './user';
+export const user = createI18n(LOCALES).add({
+  welcome: (ctx: { name: string }) => ({
+    en: `Welcome, ${ctx.name}`,
+    ja: `ようこそ、${ctx.name}さん`,
+  }),
+});
 
 // app.ts
 import { bindLocale } from 'canopy-i18n';
 import * as i18n from './i18n';
 
 const messages = bindLocale(i18n, 'en');
-console.log(messages.common.hello());                    // "Hello"
-console.log(messages.user.welcome({ name: 'John' }));   // "Welcome, John"
-```
-
-### Deep Nested Structures
-
-```ts
-import { createI18n, bindLocale } from 'canopy-i18n';
-
-const structure = {
-  header: createI18n(['en', 'ja'] as const)
-    .add({ title: { en: 'Header', ja: 'ヘッダー' } }),
-  content: {
-    main: createI18n(['en', 'ja'] as const)
-      .add({ body: { en: 'Body', ja: '本文' } }),
-    sidebar: createI18n(['en', 'ja'] as const)
-      .add({ widget: { en: 'Widget', ja: 'ウィジェット' } }),
-  },
-};
-
-const localized = bindLocale(structure, 'en');
-console.log(localized.header.title());           // "Header"
-console.log(localized.content.main.body());      // "Body"
-console.log(localized.content.sidebar.widget()); // "Widget"
+console.log(messages.common.hello());
+console.log(messages.user.welcome({ name: 'John' }));
 ```
 
 ---
 
 ## React Integration
 
-### Locale Context
+`canopy-i18n/react` exposes `createI18nReact(LOCALES)`, returning a Provider, hooks, and a pre-bound `i18n` shorthand.
+
+### Setup
 
 ```tsx
-// LocaleContext.tsx
-import { bindLocale } from 'canopy-i18n';
-import { createContext, useContext, useState } from 'react';
+// i18n.ts
+import { createI18nReact } from 'canopy-i18n/react';
 
-type Locale = 'en' | 'ja';
+export const LOCALES = ['en', 'ja'] as const;
 
-type ContextType = {
-  locale: Locale;
-  setLocale: (locale: Locale) => void;
-};
+export const { i18n, LocaleProvider, useLocale, useBindLocale } =
+  createI18nReact(LOCALES);
 
-const LocaleContext = createContext<ContextType | undefined>(undefined);
+// `i18n(...)` is `ChainBuilder.add(...)` pre-bound to LOCALES.
+export const appI18n = i18n({
+  title: { en: 'My App', ja: 'マイアプリ' },
+  greeting: (ctx: { name: string }) => ({
+    en: `Hello, ${ctx.name}!`,
+    ja: `こんにちは、${ctx.name}さん！`,
+  }),
+});
+```
 
-export function LocaleProvider({ children }: { children: React.ReactNode }) {
-  const [locale, setLocale] = useState<Locale>('en');
-  return (
-    <LocaleContext.Provider value={{ locale, setLocale }}>
-      {children}
-    </LocaleContext.Provider>
-  );
-}
+### Provider — three modes
 
-export function useLocale() {
-  const ctx = useContext(LocaleContext);
-  if (!ctx) throw new Error('useLocale must be used within a LocaleProvider');
-  return ctx;
-}
+**Uncontrolled** (in-memory, no persistence):
 
-// Reactively applies bindLocale based on current locale
-export function useBindLocale<T extends object>(msgsDef: T) {
-  const { locale } = useLocale();
-  return bindLocale(msgsDef, locale);
-}
+```tsx
+<LocaleProvider defaultLocale="en">
+  <App />
+</LocaleProvider>
 ```
 
-### Usage in Components
+**Controlled** (locale lives outside React):
 
 ```tsx
-// i18n.ts — export ChainBuilders (not yet built)
-import { createI18n } from 'canopy-i18n';
-
-const LOCALES = ['en', 'ja'] as const;
-export const defineMessage = () => createI18n(LOCALES);
-
-export const appI18n = defineMessage()
-  .add({
-    title: { en: 'My App', ja: 'マイアプリ' },
-    description: { en: 'Welcome!', ja: 'ようこそ！' },
-    greeting: (ctx: { name: string }) => ({
-      en: `Hello, ${ctx.name}!`,
-      ja: `こんにちは、${ctx.name}さん！`,
-    }),
-  });
+<LocaleProvider locale={currentLocale} onLocaleChange={setCurrentLocale}>
+  <App />
+</LocaleProvider>
+```
 
-// App.tsx — apply locale with useBindLocale
-import { useBindLocale } from './LocaleContext';
-import { appI18n } from './i18n';
+**Source-driven** (factory option `useLocaleSource`). The Provider reads locale from the hook on every render; `setLocale` calls `onLocaleChange`.
 
-export default function App() {
-  const m = useBindLocale(appI18n);
+```tsx
+export const { LocaleProvider, useLocale } = createI18nReact(LOCALES, {
+  useLocaleSource: () => useMyStore((s) => s.locale),
+  onLocaleChange: (l) => useMyStore.getState().setLocale(l),
+});
 
-  return (
-    <div>
-      <h1>{m.title()}</h1>
-      <p>{m.description()}</p>
-      <p>{m.greeting({ name: 'Taro' })}</p>
-    </div>
-  );
-}
+<LocaleProvider><App /></LocaleProvider>
 ```
 
-### Component-Local i18n (Colocation)
+### Built-in source wrappers
 
-```tsx
-// ProfileCard.tsx — define and use i18n in the same file
-import { createI18n } from 'canopy-i18n';
-import type { JSX } from 'react';
-import { useBindLocale } from './LocaleContext';
-
-const profileI18n = createI18n(['en', 'ja'] as const)
-  .add({
-    title: { en: 'User Profile', ja: 'ユーザープロフィール' },
-    editButton: { en: 'Edit Profile', ja: 'プロフィール編集' },
-    greeting: (ctx: { name: string }) => ({
-      en: `Welcome, ${ctx.name}!`,
-      ja: `ようこそ、${ctx.name}さん！`,
-    }),
-  });
+Ready-made factories for common sources. Each returns the same shape as `createI18nReact` and operates in source-driven mode (`<LocaleProvider>` with no props).
 
-export function ProfileCard({ name }: { name: string }) {
-  const m = useBindLocale(profileI18n);
+```tsx
+import {
+  createHashI18nReact,     // URL hash (#ja)
+  createSearchI18nReact,   // URL search param (?lang=ja)
+  createPathnameI18nReact, // URL pathname prefix (/ja/...)
+  createStorageI18nReact,  // localStorage
+  createCookieI18nReact,   // Cookie
+} from 'canopy-i18n/react';
 
-  return (
-    <div>
-      <h2>{m.title()}</h2>
-      <p>{m.greeting({ name })}</p>
-      <button>{m.editButton()}</button>
-    </div>
-  );
-}
+export const { LocaleProvider, useLocale, useBindLocale } =
+  createHashI18nReact(LOCALES);
 ```
 
-### Language Switcher Component
+Options:
+- `createSearchI18nReact(LOCALES, { param })` — defaults to `lang`
+- `createPathnameI18nReact(LOCALES, { basePath })` — defaults to `""`
+- `createStorageI18nReact(LOCALES, { key })` — defaults to `canopy-i18n-locale`
+- `createCookieI18nReact(LOCALES, { key, maxAge, path, sameSite })` — defaults to `canopy-i18n-locale` / 1 year / `/` / `Lax`
+
+### Components
 
 ```tsx
-// LanguageSwitcher.tsx
-import { useLocale } from './LocaleContext';
+import { appI18n, useBindLocale, useLocale } from './i18n';
 
-export function LanguageSwitcher() {
+export default function App() {
+  const m = useBindLocale({ appI18n });
   const { locale, setLocale } = useLocale();
-
   return (
     <div>
-      <button onClick={() => setLocale('en')} disabled={locale === 'en'}>EN</button>
-      <button onClick={() => setLocale('ja')} disabled={locale === 'ja'}>JA</button>
+      <h1>{m.appI18n.title()}</h1>
+      <p>{m.appI18n.greeting({ name: 'Taro' })}</p>
+      <button onClick={() => setLocale(locale === 'en' ? 'ja' : 'en')}>{locale}</button>
     </div>
   );
 }
 ```
 
----
+`useBindLocale(msgsDef)` is memoized per `(msgsDef, locale)`. The `Locale` of every nested `ChainBuilder` must match the Provider's `LOCALES`; mismatches fail at compile time.
 
-## Exports Reference
+React is a `peerDependency` (`>=18`).
 
-```ts
-// Functions & Classes
-export { createI18n } from 'canopy-i18n';      // create a builder
-export { ChainBuilder } from 'canopy-i18n';    // builder class
-export { I18nMessage } from 'canopy-i18n';     // message class
-export { isI18nMessage } from 'canopy-i18n';   // type guard
-export { bindLocale } from 'canopy-i18n';      // apply locale to nested structure
-export { isChainBuilder } from 'canopy-i18n';  // type guard
-
-// Types
-export type { Template } from 'canopy-i18n';         // R | ((ctx: C) => R)
-export type { LocalizedMessage } from 'canopy-i18n'; // built message function type
-```
+---
 
-### Type Details
+## Exports
 
 ```ts
-// Template<C, R>: a static value or a function that receives context
-type Template<C, R = string> = R | ((ctx: C) => R);
-
-// LocalizedMessage<Ls, C, R>: the function type after build()
-// - when C is void: () => R
-// - when C is present: (ctx: C) => R
-type LocalizedMessage<Ls, C, R = string> =
-  C extends void
-    ? (() => R) & { __brand: "I18nMessage" }
-    : ((ctx: C) => R) & { __brand: "I18nTemplateMessage" };
+// Core
+export { createI18n, ChainBuilder, bindLocale } from 'canopy-i18n';
+export { I18nMessage, isI18nMessage, isChainBuilder } from 'canopy-i18n';
+export type { Template, LocalizedMessage } from 'canopy-i18n';
+
+// React subpath
+export {
+  createI18nReact,
+  createHashI18nReact,
+  createSearchI18nReact,
+  createPathnameI18nReact,
+  createStorageI18nReact,
+  createCookieI18nReact,
+} from 'canopy-i18n/react';
 ```
-
----
-
-## Common Mistakes
-
-| Mistake | Fix |
-|---------|-----|
-| `createI18n(['en', 'ja'])` | `createI18n(['en', 'ja'] as const)` |
-| `messages.title` | `messages.title()` (call as function) |
-| CommonJS `require()` | Use ESM `import` |
-| Typo in locale key | TypeScript catches it at compile time |