prosebook 0.2.0 → 0.4.0

package/README.md

@@ -32,11 +32,13 @@ const { t } = useCopy();
   2.5 KB gzipped.
 - **Checked.** Placeholders that drift between the source and a translation fail the build. A
   translation whose source has changed since is marked stale, automatically.
-- **Pruned.** A Vite build ships only the messages the code names, and fails on a read whose key
-  it can't see rather than show a key where a message was.
+- **Pruned.** A Vite, Next.js or Bun build ships only the messages the code names, and fails on a
+  read whose key it can't see rather than show a key where a message was.
 - **Written well.** An optional lint holds the words to a writing guide: word budgets per kind of
   string, periods, sentence case, banned filler, and `{count} files` outside a plural. Plugins add your
   own rules, scoped by kind, surface and locale, and translations are held to their source.
+- **Native too.** The same catalog generates Rust, Swift and Kotlin for a tray, a menu bar or a CLI,
+  with plurals and number formats that say what the browser says, and the string resources Android and Apple read.
 
 ## Quick start
 
@@ -68,6 +70,63 @@ export default defineConfig({ plugins: [react(), prosebook()] });
 Several apps that share one catalog each point the plugin at it: `prosebook({ root: '../../packages/copy' })`
 reads the config there and resolves its paths from there, so every app generates the same files.
 
+### With Next.js
+
+```ts
+// next.config.ts
+import { withProsebook } from 'prosebook/next';
+
+export default withProsebook({/* the rest of your Next config */});
+```
+
+`next dev` and `next build` generate first, and dev regenerates on every catalog edit: server
+components read the new text on their next render, and in the browser the messages change in
+place. A build ships only the messages the code names. It works with Turbopack, Next's default
+bundler, which doesn't resolve `./en.js` to `en.ts`, so set `importExtension: ''` in the prosebook
+config. In dev the [inspector](#finding-a-strings-entry) comes with it, with nothing to add to the app.
+
+### With Bun
+
+`Bun.serve`'s dev server bundles a page with the plugins bunfig.toml names, and regenerates and
+swaps the messages in place with this one:
+
+```toml
+# bunfig.toml
+[serve.static]
+plugins = ["prosebook/bun"]
+```
+
+In dev the page gets the [inspector](#finding-a-strings-entry) too. Its endpoints are routes for
+`Bun.serve` to spread into its own, imported only in dev:
+
+```ts
+// src/server.ts
+const dev = process.env.NODE_ENV !== 'production';
+
+Bun.serve({
+  routes: { ...(dev ? (await import('prosebook/bun')).inspector() : {}), '/': index },
+  development: dev && { hmr: true },
+});
+```
+
+The `bun build` command reads no plugins, so a build that prunes calls `Bun.build`, with
+`prosebook/bun` left `external` so the dev-only routes stay out of the bundle:
+
+```ts
+// build.ts
+import { prosebook } from 'prosebook/bun';
+
+await Bun.build({
+  entrypoints: ['./src/server.ts'],
+  target: 'bun',
+  outdir: './dist',
+  external: ['prosebook/bun'],
+  plugins: [prosebook()],
+});
+```
+
+TanStack Start, React Router and other frameworks built on Vite take the Vite plugin as it is.
+
 ### In React
 
 ```tsx
@@ -108,8 +167,204 @@ document.title = copy.t('app.title');
 copy.subscribe(() => render()); // after a locale switch, and in dev after a catalog edit
 ```
 
-Set `language: 'js'` in the config to generate `.js` modules with a `.d.ts` beside the index. On a
-server, create one `copy` per request.
+Set `language: 'js'` in the config to generate `.js` modules with a `.d.ts` beside the index, or
+`importExtension: '.ts'` to run the generated TypeScript in Node as it is.
+
+A message never throws. A placeholder with no value, or with one `Intl` refuses (an invalid date,
+`currency: 'euro'`), shows as `{name}` (`{$name}` in MF2), and the rest of the message renders. The
+problem goes to `console.error`, or to `onError` if you pass one:
+
+```js
+createCopy(catalog, { onError: (error, key, locale) => report(error, { key, locale }) });
+```
+
+### On a server
+
+Create one `copy` per request, in the locale it asks for, and wait for its messages.
+`acceptedLocales` reads an `Accept-Language` header into the locales it asks for, by weight, so
+`de;q=0.1, en;q=0.9` asks for English first:
+
+```ts
+import { acceptedLocales, createCopy } from 'prosebook';
+
+const copy = createCopy(catalog, { locale: acceptedLocales(request.headers.get('accept-language')) });
+await copy.ready;
+```
+
+**React Server Components** can't read context, so `prosebook/react/server` hands each request one
+copy that every server component in it shares. Your function is asked for the locale once per
+request, and React's `cache` keeps one request's copy from reaching another's:
+
+```ts
+// server-copy.ts, here with Next.js
+import { cookies, headers } from 'next/headers';
+import { acceptedLocales } from 'prosebook';
+import { createServerCopy } from 'prosebook/react/server';
+
+export const serverCopy = createServerCopy(catalog, async () => {
+  const picked = (await cookies()).get('locale')?.value;
+  const asked = acceptedLocales((await headers()).get('accept-language'));
+  return picked === undefined ? asked : [picked, ...asked];
+});
+```
+
+```tsx
+export default async function Page() {
+  const { t, locale } = await serverCopy(); // ready, in the locale negotiated for the request
+  return <h1 lang={locale}>{t('app.title')}</h1>;
+}
+```
+
+It's its own entry because `prosebook/react` creates a context when it loads, which the server
+build of React refuses. It needs React 19, where `cache` is.
+
+A page rendered on the server must hydrate in the same locale, so the browser's copy waits for its
+messages too. Create it above a `<Suspense>` boundary and wait below it: a component that suspends
+before it first mounts loses its state, copy included.
+
+```tsx
+function Providers({ locale, children }: { locale: Locale; children: ReactNode }) {
+  const [copy] = useState(() => createCopy(catalog, { locale }));
+  return (
+    <Suspense>
+      <Ready copy={copy}>{children}</Ready>
+    </Suspense>
+  );
+}
+
+function Ready({ copy, children }: { copy: Copy; children: ReactNode }) {
+  use(copy.ready);
+  return <CopyProvider copy={copy}>{children}</CopyProvider>;
+}
+```
+
+### Outside the browser: Rust, Swift, Kotlin, Android and Apple
+
+The parts of an app the browser doesn't draw, a tray, a menu bar, a CLI, an Android shell, can read
+the same catalog. `generate` writes one file per target in `native`, holding every locale:
+
+```ts
+// prosebook.config.ts
+export default defineConfig({
+  native: [
+    { language: 'rust', out: 'src-tauri/src/copy.rs', keys: ['tray', 'menu'] },
+    { language: 'swift', out: 'mac/Sources/Copy.swift' },
+    { language: 'kotlin', out: 'android/app/src/main/java/shop/Copy.kt', package: 'shop' },
+  ],
+});
+```
+
+Each is an enum of the locales with a member per message, named for its key (`tray.recordings` is
+`tray_recordings` in Rust, `trayRecordings` in Swift and Kotlin). `keys` takes only the keys under
+those prefixes and names them without the prefix, so `tray.quit` above is `quit`:
+
+```rust
+mod copy;
+use copy::Locale;
+
+let copy = Locale::negotiate(&["de-AT", "en"]); // de-AT, then de, then the source
+let quit: &'static str = copy.quit();
+let count = copy.recordings(3); // "3 Aufnahmen": any integer or float
+```
+
+```swift
+let copy = Copy.negotiate(Locale.preferredLanguages)
+menu.title = copy.trayQuit
+label.stringValue = copy.trayRecordings(count: 3)
+```
+
+```kotlin
+val copy = Copy.negotiate(listOf(Locale.getDefault().toLanguageTag()))
+item.title = copy.trayQuit
+label.text = copy.trayRecordings(3)
+```
+
+A message with no placeholders is a `&'static str` in Rust and a property in Swift and Kotlin; one
+with placeholders is a function taking them in order, a string or a number of any integer or float type. Each member's doc comment
+is the source text, its context and what each argument holds.
+
+The files need nothing beside them: each brings the plural rules of its locales, compiled from CLDR's
+(the data `Intl.PluralRules` is built on), and its number formats, taken apart from `Intl` when it is
+generated: the digits, the separators, how integers group, the text around a currency or a percent.
+Each format is checked against `Intl` before any code is written, so native code writes what the
+browser does, Arabic digits and Indian grouping included. A key with no translation falls back
+through its parents to the source as the runtime's do, resolved when the file is written.
+
+What can't be written that way fails `generate`, with the fix: a date (pass it formatted, as a plain
+`{when}`), a tag, compact notation, significant digits, a unit or currency name that changes with the
+count (`unitDisplay: 'long'`), and an MF2 option read from an argument. Leave such keys out of the
+target's `keys`.
+
+#### Android resources
+
+An Android app needs string resources even with the Kotlin target: its manifest, launcher shortcuts,
+an accessibility service's description and every other XML resource name strings as `@string/…`, and
+only a resource answers that. The `android` target writes them, with `out` naming the `res` folder:
+
+```ts
+native: [{ language: 'android', out: 'android/app/src/main/res', keys: ['android'] }],
+```
+
+`values/strings.xml` holds the source locale, and each other locale gets a folder named as Android
+names it (`values-de`, `values-pt-rBR`, `values-b+sr+Latn` for a script), holding what that locale
+shows, every fallback resolved. `name` renames the file, `strings` by default, so it can sit beside
+strings you write yourself. A resource is named for its key, less the prefix, with `.` and `-` as
+`_`: `android.sign-in.denied` is `R.string.sign_in_denied`. Above each is a comment with its context
+and what each argument holds.
+
+```xml
+<!-- Counts the cart. count: how many items the cart holds. -->
+<plurals name="cart_items">
+    <item quantity="one">%1$d item in the cart.</item>
+    <item quantity="other">%1$d items in the cart.</item>
+</plurals>
+<!-- Greets the person signed in. firstName: the person's first name. -->
+<string name="hello">Hello, %1$s!</string>
+```
+
+Android fills placeholders in with `String.format` and picks a plural's arm itself, so a resource
+holds less than the other targets: text, plain `{name}` placeholders, written `%1$s` by their place in
+the source so a translation can reorder them, and one plural, which becomes `<plurals>` with its count
+as `%1$d` (the text around it goes into each arm). Call it as Android does,
+`resources.getQuantityString(R.plurals.cart_items, count, count)`. `String.format` isn't `Intl`, so
+nothing here is checked against it: `%d` writes 1234 without grouping. Android picks the arm by the
+device's language, so a plural a locale doesn't translate picks among the source's arms by that
+language's rules. Escaping is done for you: quotes, apostrophes, `\`, `&`, `<`, a newline, a leading
+`@` or `?`, `%` where the string is formatted, and spaces Android would collapse or trim.
+
+What a resource can't hold fails `generate`, with the fix: a select, a date, a formatted number, a
+second plural, an ordinal, an offset, an exact arm such as `=0` (Android's `zero` is a category, which
+English never picks), a selector other than a bare `:number` or `:integer`, and a tag.
+
+#### Apple string tables
+
+An Apple app has the same gap: macOS and iOS read the permission prompts, the app's name and other
+Info.plist strings from the bundle, never from Swift. The `apple` target writes `.strings` tables, a
+`<locale>.lproj/<name>.strings` per locale under `out`, each holding what that locale shows. They are
+plain `.strings` files, not a String Catalog, which only Xcode compiles: an app bundled by Tauri or a
+script copies the `.lproj` folders into `Contents/Resources` as they are.
+
+With `plist`, the table is `InfoPlist` and translates that Info.plist. A catalog key can't be written
+`NSCameraUsageDescription`, so its words spell the plist key: `macos.ns-camera-usage-description` is
+`NSCameraUsageDescription`. The key must be in the plist, since the system reads only the keys there,
+and the plist's own text must be the source's, since it shows where no `.lproj` matches. Either way
+round, `generate` fails with the fix:
+
+```ts
+native: [{ language: 'apple', out: 'src-tauri/Resources', keys: ['macos'], plist: 'src-tauri/Info.plist' }],
+```
+
+```c
+/* Asks for the camera. */
+"NSCameraUsageDescription" = "Corner Shop scans a product's barcode with the camera.";
+```
+
+Without `plist`, the table is `Localizable`, for what the system looks up by key, such as a push
+notification's `loc-key`. An entry is named for its key less the prefix, as written (`tray.quit` is
+`"quit"` under `['tray']`), and placeholders are written `%1$@` by their place in the source, filled
+in by `String(format:)`, not `Intl`. A table holds text and plain `{name}` placeholders; a plural (it
+would take a `.stringsdict`), a select, a date, a formatted number and a tag fail `generate`, and an
+Info.plist string takes no placeholders at all. Show those from the Swift target.
 
 ## The catalog
 
@@ -199,14 +454,40 @@ en: |-
 
 A message with `.match` holds whole sentences per variant, so a translator never stitches a sentence
 from an arm and the text around it. Several selectors pick the variant MF2's rules pick: the best
-match on the first, then the next, an exact number beating its plural category. `:offset` covers
-MF1's plural offset.
+match on the first, then the next, an exact number beating its plural category. A number is matched
+as it's shown: under `.input {$n :number minimumFractionDigits=1}`, 1 shows as "1.0", which English
+counts as `other`. `:integer` matches the value rounded, and `:percent` matches it times 100.
+`:offset` covers MF1's plural offset.
 
 The functions are MF2's defaults: `:string`, `:number`, `:integer`, `:percent`, `:currency`, `:unit`,
 `:offset`, and the date and time functions `:date`, `:time` and `:datetime`, which are still a draft
-in the spec and follow it as the `messageformat` package does. Option values are literals, since
-formatting is settled at build time; `currency=$code` is refused with that reason. Placeholders
-aren't wrapped in bidi isolation marks.
+in the spec and follow it as the `messageformat` package does. `.match` selects with `:number`,
+`:integer`, `:percent` or `:string`.
+
+**Text direction.** In a locale written right to left, each placeholder is wrapped in Unicode
+isolation marks, so a value written the other way can't reorder the text around it. Without them, a
+Latin name in a Hebrew sentence can pull the punctuation after it to the wrong side. `u:dir` on an
+expression picks its direction (`{$name :string u:dir=ltr}`) and asks for isolation in any locale.
+`isolate: 'always'` in the config also isolates every string placeholder in left-to-right locales,
+as the spec's default does. `isolate: false` turns it off.
+
+**Options from arguments.** An option can take its value from an argument, so one message formats
+whatever currency the order is in:
+
+```yaml
+en: 'Total: {$price :currency currency=$code}' # t('cart.total', { price: 9, code: 'USD' }): $9.00
+en: 'Due {$when :time timeZone=$tz}'
+```
+
+The argument is typed with the rest (`code: string`; `currencyDisplay=$d` takes only the values the
+option does), and a translation must use it too. These options can come from an argument: `currency`,
+`currencyDisplay`, `currencySign`, `unit`, `unitDisplay`, `signDisplay`, `fractionDigits` and the
+other digit counts, `timeZone` and `calendar`. The rest, such as a date's `fields` or a number's
+`select`, decide what the formatter is, so they're written in the message and the message says so.
+Literal options are still settled at build time. The ones from arguments are merged in as the
+message renders, and each locale keeps one formatter per distinct value. A value `Intl` refuses,
+such as `code: 'euro'`, throws a `RangeError` there. MF1 has no way to say this, so `migrate 1`
+stops at such a message.
 
 **Switching.** `prosebook migrate 2` rewrites the catalog and every translation in MF2, and
 `prosebook migrate 1` goes back. It's a dry run unless `--write`; then set `messageFormat` in the
@@ -236,7 +517,8 @@ still hold:
 
 ```bash
 prosebook status            # coverage and stale counts per locale
-prosebook todo de           # missing and stale entries, with context, ready to translate
+prosebook todo de > de.yaml # missing and stale entries, with context, ready to translate
+prosebook import de de.yaml # each filled-in entry into its file, checked first
 prosebook accept de cart.items
 ```
 
@@ -251,6 +533,7 @@ de           13/14  92%        1      2
 
 $ prosebook todo de
 # The button on a product that adds one to the cart.
+# kind: action, surface: action
 # en: Add one to cart
 # stale, the source changed: Add {+one +}to cart
 cart.add: In den Warenkorb
@@ -258,6 +541,23 @@ cart.add: In den Warenkorb
 
 Stale translations still show by default; `stale: 'fallback'` shows the source instead.
 
+**Translating with a model.** prosebook calls no model itself. `prosebook todo de --prompt` prints
+the same entries as a prompt for whichever model you use: how to reply, the plural forms German
+takes, what each kind of string and surface asks for, and how to treat a stale entry. Hand it to the
+model and give its reply to `import`, as a file or on stdin:
+
+```bash
+prosebook todo de --prompt | pbcopy  # paste into a chat, or hand it to an agent
+prosebook import de reply.md         # the YAML block is read out of the reply
+```
+
+`import` checks every entry as the whole catalog before writing it. One whose placeholders, tags
+or syntax don't hold is left out with its fix, which you can give back to the model, and the rest
+are written. A stale translation given back unchanged is accepted as still right. The imported
+translations are then linted, as a person's would be. An agent working in the repository needs none
+of this: it can read `prosebook todo de`, write the translation files itself, and run
+`prosebook check`.
+
 **Pseudo-locale.** `pseudo: 'en-XA'` generates `⟦Ýóóúúŕ çááŕţ⟧` from the source. Switch to it and
 any plain text on screen is hardcoded, a missing bracket is clipped text, and brackets inside
 brackets are a sentence spliced from fragments.
@@ -496,7 +796,8 @@ the singular is the plural less its `s`, `es` or `ies`.
 ## Pruning
 
 The Vite plugin replaces each locale module in a build with only the messages some module
-references. A reference is any string literal equal to a key, so keys kept in arrays or maps count;
+references. Next's Turbopack and Bun load a locale before the code that reads it, so their
+integrations read the source under `scan.dirs` instead, and every key a file there names is kept. A reference is any string literal equal to a key, so keys kept in arrays or maps count;
 ``t(`status.${state}`)`` and `t('status.' + state)` keep every key under `status.`. For keys built
 some other way, list them: `prosebook({ keep: ['plan.*'] })`.
 
@@ -506,10 +807,11 @@ or, where every key it reads is written elsewhere (in an array, say) or listed i
 line with `prosebook-ignore`. Reads are known by name: `t` and `rich` alone or as methods, the names
 they're destructured to (`const { rich: tRich } = copy`) in any module, and `<Text>` from
 `prosebook/react`. `prune: 'loose'` prunes without the check, and `prune: false` ships everything.
+`prune` and `keep` are options of each integration.
 
 ## Finding a string's entry
 
-In dev, hold Alt (Option on a Mac) and point at text on the page: the Vite plugin outlines the
+In dev, hold Alt (Option on a Mac) and point at text on the page: the inspector outlines the
 string and names its key and the locale it came from. Alt-click opens its entry in your editor: the
 translation for a translated string, the catalog entry for one that fell back. Alt-Shift-click opens
 the catalog entry either way. Save, and the string changes on the page, which keeps its locale and
@@ -539,10 +841,17 @@ Nothing is added to the page to make this work. In dev the runtime reports each
 and the inspector matches the text under the pointer back to it, so `t()`, `<Text>`, a sentence with
 a link inside it and readable attributes (`placeholder`, `title`, `aria-label`, `alt`) all work. Text
 the code changes after reading it (`t('…').toUpperCase()`) can't be traced. Where two keys read the
-same text, the label says so and the click opens the one read last.
-
-The editor is the one Vite's `/__open-in-editor` launches: one it finds running, or the command in
-`LAUNCH_EDITOR`. Turn the inspector off with `prosebook({ inspect: false })`.
+same text, the label says so and the click opens the one read last. Under Next.js, only text read in
+the browser is found: a server component's reads happen where the inspector can't see them.
+
+The inspector comes with each integration, in dev only, and opens the editor its dev server already
+launches. Under Vite, and so in any framework built on it, TanStack Start among them, that is the one
+`/__open-in-editor` launches: one it finds running, or the command in `LAUNCH_EDITOR`. Under Next.js
+it is the one `/__nextjs_launch-editor` launches, from `REACT_EDITOR` or one it finds running; the
+endpoints are served on a local port of their own, which a rewrite of `/__prosebook/*` sends to.
+Under Bun it is the one `Bun.openInEditor` finds, from `VISUAL`, `EDITOR` or bunfig.toml's
+`[debug] editor`, and the endpoints are the `inspector()` routes [above](#with-bun). Turn it off with
+`inspect: false` in the options of the Vite plugin, `withProsebook` or the Bun plugin.
 
 ## Config
 
@@ -557,6 +866,7 @@ export default defineConfig({
   lock: 'copy/lock.json',
   source: 'en',
   messageFormat: 1, // or 2, for Unicode MessageFormat 2
+  isolate: 'rtl', // MF2: isolate placeholders in right-to-left locales; 'always', or false
   bundled: [], // locales shipped in the main bundle; the rest load on first use
   pseudo: false, // or 'en-XA'
   stale: 'use', // or 'fallback'
@@ -576,29 +886,35 @@ export default defineConfig({
     properNouns: [],
     pathSeparator: '›',
   },
+  native: [], // Rust, Swift or Kotlin files, Android's res or Apple's .lproj: { language: 'rust', out: 'src/copy.rs', keys: ['tray'] }
   scan: { dirs: ['src'] },
 });
 ```
 
-## Example
+## Examples
+
+Each is a small shop in English, German and the pseudo-locale, and uses prosebook as an app would,
+from the package. CI generates, lints, typechecks and builds each one, then checks what its build
+serves.
 
-[`examples/react-app`](examples/react-app) is a small shop in English, German, a part-translated
-Turkish and the pseudo-locale.
+| Example                                              |                                                                                             |
+| ---------------------------------------------------- | ------------------------------------------------------------------------------------------- |
+| [`examples/vite`](examples/vite)                     | React with Vite, and a part-translated Turkish. The inspector is on.                        |
+| [`examples/next`](examples/next)                     | Next.js: server components read a copy per request, client components the provider's.       |
+| [`examples/tanstack-start`](examples/tanstack-start) | TanStack Start, rendered on the server in the request's locale with the Vite plugin.        |
+| [`examples/bun`](examples/bun)                       | `Bun.serve` with a React page, a route that answers in the request's locale, the inspector. |
+| [`examples/node`](examples/node)                     | No framework and no bundler: a Node script prints a receipt from the generated TypeScript.  |
 
 ```bash
-bun run example
+bun run build                      # the examples import prosebook from dist
+bun run --cwd examples/next dev
 ```
 
 ## Further
 
 Ideas not built yet, roughly in order of value:
 
-1. **Draft translations with an LLM**: `prosebook translate de --draft`, prompted with `context`,
-   `kind`, `surface` and `args`, written to a draft file a person reviews before it ships.
-2. **Exchange formats**: XLIFF 2 and JSON export and import for translation tools.
-3. **Per-area splitting**: one chunk per area and locale, so a lazy route loads only its own messages.
-4. **Server rendering helpers**: `Accept-Language` negotiation and a React Server Components reader.
-5. **Native targets**: generate Rust, Swift or Kotlin from the same catalog, for the parts of an app
-   outside the browser, such as a tray or native menus.
-6. **Variable MF2 options**: `{$price :currency currency=$code}`, compiled to a formatter cached per
-   value.
+1. **Exchange formats**: XLIFF 2 and JSON export and import for translation tools.
+2. **Per-area splitting**: one chunk per area and locale, so a lazy route loads only its own messages.
+3. **Dates in native targets**: date and time formats taken apart from `Intl` as number formats are,
+   so a Rust, Swift or Kotlin message can say when.

package/dist/bun.d.ts

@@ -0,0 +1,34 @@
+import { t as Prune } from "./bundle-CpUIWb9j.js";
+import { i as ProsebookConfig } from "./config-CzaJJQ60.js";
+import { BunPlugin } from "bun";
+export interface ProsebookBunOptions {
+  /** The config, inline. Without it, `prosebook.config.*` at `root` is read. */
+  config?: ProsebookConfig;
+  /** The folder the config's paths resolve from, and where its file is found: the working directory when unset. */
+  root?: string;
+  /**
+   * In `Bun.build`, ship only the messages the code names. `strict`, the default, also fails the
+   * build on a read whose key it can't see, such as `t(item.key)`. `loose` prunes without that
+   * check; `false` ships every message.
+   */
+  prune?: Prune;
+  /** Keys a build always keeps, exactly or as `prefix.*`: for keys built at runtime from data. */
+  keep?: string[];
+  /** Under the dev server, Alt-click a string on the page to open its entry in the editor. On by default. */
+  inspect?: boolean;
+}
+export declare function prosebook(options?: ProsebookBunOptions): BunPlugin;
+export interface InspectorRoutesOptions {
+  /** The config, inline. Without it, `prosebook.config.*` at `root` is read. */
+  config?: ProsebookConfig;
+  /** The folder the config's paths resolve from, and where its file is found: the working directory when unset. */
+  root?: string;
+}
+/**
+ * The inspector's endpoints as `Bun.serve` routes: `routes: { ...inspector(), '/': index }`. For dev
+ * only: they read and write the catalog.
+ */
+export declare function inspector(options?: InspectorRoutesOptions): Record<string, (req: Request) => Promise<Response>>;
+declare const _default: BunPlugin;
+export { _default as default };
+//# sourceMappingURL=bun.d.ts.map

package/dist/bun.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bun.d.ts","names":[],"sources":["../src/bun.ts"],"mappings":";;;iBAqCiB;;EAEf,SAAS;;EAET;;;;;;EAMA,QAAQ;;EAER;;EAEA;;wBAQc,UAAU,UAAS,sBAA2B;iBA6C7C;;EAEf,SAAS;;EAET;;;;;;wBAOc,UAAU,UAAS,yBAA8B,gBAAgB,KAAK,YAAY,QAAQ"}

package/dist/bun.js

@@ -0,0 +1,98 @@
+import { a as installInspector, c as prunedModule, f as watchCatalog, i as hotLocale, l as scanSources, n as HOT_SET, o as keeper, r as beside, t as HOT_INDEX, u as unseenMessage } from "./bundle-DboItAre.js";
+import { n as generate, x as CatalogError } from "./generate-BW3N8EGb.js";
+import { r as loadConfig } from "./config-nWZf9QmF.js";
+import { t as inspectorEndpoints } from "./endpoints-BgG_5Vpm.js";
+import { basename, resolve } from "node:path";
+import { readFileSync } from "node:fs";
+// src/bun.ts
+/**
+* `prosebook/bun`: the catalog as part of a Bun build, or of Bun's dev server.
+*
+* Generates when the plugin is set up. Given to `Bun.build`, it ships only the messages the code
+* names: Bun loads a locale module before it has seen the code that reads it, so the keys come from
+* the source under `scan.dirs` (`tools/bundle.ts`) and each locale loads already pruned. The `bun
+* build` command reads no plugins, so a build that prunes is a script that calls `Bun.build`.
+*
+* Named in bunfig.toml's `[serve.static] plugins`, it serves `Bun.serve`'s bundler instead, which
+* names no entry points: it regenerates whenever a catalog or translation file changes, and each
+* locale module accepts its own update and hands the new messages to every copy, as under Vite. The
+* index starts the inspector on the page too, whose endpoints are `inspector()`'s routes, spread into
+* `Bun.serve`'s; an entry opens in the editor `Bun.openInEditor` finds.
+*/
+const inspectorPath = beside(import.meta.url, "inspector");
+const describe = (e) => e instanceof CatalogError ? e.message : e instanceof Error ? e.stack ?? e.message : String(e);
+const escape = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+function prosebook(options = {}) {
+	return {
+		name: "prosebook",
+		async setup(build) {
+			const config = await loadConfig(resolve(options.root ?? process.cwd()), options.config);
+			let generated = generate(config);
+			const folder = config.out.split(/[\\/]/).map(escape).join("[\\\\/]");
+			const filter = new RegExp(`^${folder}[\\\\/][^\\\\/]+\\.[jt]s$`);
+			const nameOf = (path) => basename(path).replace(/\.[jt]s$/, "");
+			if ("entrypoints" in build.config) {
+				const prune = options.prune ?? "strict";
+				if (prune === false) return;
+				const { refs, unseen } = scanSources(config, prune === "strict");
+				if (unseen.length > 0) throw new Error(unseenMessage(unseen, config.root));
+				const kept = keeper(refs, options.keep);
+				build.onLoad({ filter }, ({ path }) => {
+					const entries = generated.entries.get(nameOf(path));
+					return entries === void 0 ? void 0 : {
+						contents: prunedModule(entries, kept),
+						loader: "js"
+					};
+				});
+				return;
+			}
+			const dev = process.env.NODE_ENV !== "production";
+			const inspector = dev && options.inspect !== false ? installInspector(inspectorPath, "/") : "";
+			if (dev) watchCatalog(config, () => {
+				try {
+					generated = generate(config);
+				} catch (e) {
+					console.error(describe(e));
+				}
+			});
+			build.onLoad({ filter }, ({ path }) => {
+				const name = nameOf(path);
+				const loader = path.endsWith(".ts") ? "ts" : "js";
+				if (generated.entries.has(name)) return {
+					contents: readFileSync(path, "utf8") + hotLocale(name),
+					loader
+				};
+				return name === "index" ? {
+					contents: HOT_SET + inspector + readFileSync(path, "utf8") + HOT_INDEX,
+					loader
+				} : void 0;
+			});
+		}
+	};
+}
+/**
+* The inspector's endpoints as `Bun.serve` routes: `routes: { ...inspector(), '/': index }`. For dev
+* only: they read and write the catalog.
+*/
+function inspector(options = {}) {
+	const handle = inspectorEndpoints(loadConfig(resolve(options.root ?? process.cwd()), options.config), { open: ({ file, line, column }) => {
+		try {
+			Bun.openInEditor(file, {
+				line,
+				column
+			});
+			return new Response(null, { status: 204 });
+		} catch (e) {
+			return new Response(`${e instanceof Error ? e.message : String(e)}: set VISUAL or EDITOR to the editor's command`, { status: 500 });
+		}
+	} });
+	const route = async (req) => await handle(req) ?? new Response(null, { status: 404 });
+	return {
+		"/__prosebook/open": route,
+		"/__prosebook/entry": route
+	};
+}
+var bun_default = prosebook();
+export { bun_default as default, inspector, prosebook };
+
+//# sourceMappingURL=bun.js.map

package/dist/bun.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bun.js","names":[],"sources":["../src/bun.ts"],"sourcesContent":["/**\n * `prosebook/bun`: the catalog as part of a Bun build, or of Bun's dev server.\n *\n * Generates when the plugin is set up. Given to `Bun.build`, it ships only the messages the code\n * names: Bun loads a locale module before it has seen the code that reads it, so the keys come from\n * the source under `scan.dirs` (`tools/bundle.ts`) and each locale loads already pruned. The `bun\n * build` command reads no plugins, so a build that prunes is a script that calls `Bun.build`.\n *\n * Named in bunfig.toml's `[serve.static] plugins`, it serves `Bun.serve`'s bundler instead, which\n * names no entry points: it regenerates whenever a catalog or translation file changes, and each\n * locale module accepts its own update and hands the new messages to every copy, as under Vite. The\n * index starts the inspector on the page too, whose endpoints are `inspector()`'s routes, spread into\n * `Bun.serve`'s; an entry opens in the editor `Bun.openInEditor` finds.\n */\nimport { readFileSync } from 'node:fs';\nimport { basename, resolve } from 'node:path';\n\nimport type { BunPlugin } from 'bun';\n\nimport {\n  beside,\n  HOT_INDEX,\n  HOT_SET,\n  hotLocale,\n  installInspector,\n  keeper,\n  prunedModule,\n  scanSources,\n  unseenMessage,\n  watchCatalog,\n  type Prune,\n} from './tools/bundle.ts';\nimport { CatalogError } from './tools/catalog.ts';\nimport { loadConfig, type ProsebookConfig } from './tools/config.ts';\nimport { inspectorEndpoints } from './tools/endpoints.ts';\nimport { generate } from './tools/generate.ts';\n\nexport interface ProsebookBunOptions {\n  /** The config, inline. Without it, `prosebook.config.*` at `root` is read. */\n  config?: ProsebookConfig;\n  /** The folder the config's paths resolve from, and where its file is found: the working directory when unset. */\n  root?: string;\n  /**\n   * In `Bun.build`, ship only the messages the code names. `strict`, the default, also fails the\n   * build on a read whose key it can't see, such as `t(item.key)`. `loose` prunes without that\n   * check; `false` ships every message.\n   */\n  prune?: Prune;\n  /** Keys a build always keeps, exactly or as `prefix.*`: for keys built at runtime from data. */\n  keep?: string[];\n  /** Under the dev server, Alt-click a string on the page to open its entry in the editor. On by default. */\n  inspect?: boolean;\n}\n\nconst inspectorPath = beside(import.meta.url, 'inspector');\n\nconst describe = (e: unknown) => (e instanceof CatalogError ? e.message : e instanceof Error ? (e.stack ?? e.message) : String(e));\nconst escape = (s: string) => s.replace(/[.*+?^${}()|[\\]\\\\]/g, '\\\\$&');\n\nexport function prosebook(options: ProsebookBunOptions = {}): BunPlugin {\n  return {\n    name: 'prosebook',\n    async setup(build) {\n      const config = await loadConfig(resolve(options.root ?? process.cwd()), options.config);\n      let generated = generate(config);\n      // The generated modules, by path as Bun gives it: either separator on Windows.\n      const folder = config.out.split(/[\\\\/]/).map(escape).join('[\\\\\\\\/]');\n      const filter = new RegExp(`^${folder}[\\\\\\\\/][^\\\\\\\\/]+\\\\.[jt]s$`);\n      const nameOf = (path: string) => basename(path).replace(/\\.[jt]s$/, '');\n\n      if ('entrypoints' in build.config) {\n        const prune = options.prune ?? 'strict';\n        if (prune === false) return;\n        const { refs, unseen } = scanSources(config, prune === 'strict');\n        if (unseen.length > 0) throw new Error(unseenMessage(unseen, config.root));\n        const kept = keeper(refs, options.keep);\n        build.onLoad({ filter }, ({ path }) => {\n          const entries = generated.entries.get(nameOf(path));\n          return entries === undefined ? undefined : { contents: prunedModule(entries, kept), loader: 'js' };\n        });\n        return;\n      }\n\n      const dev = process.env.NODE_ENV !== 'production';\n      const inspector = dev && options.inspect !== false ? installInspector(inspectorPath, '/') : '';\n      if (dev) {\n        watchCatalog(config, () => {\n          try {\n            generated = generate(config);\n          } catch (e) {\n            console.error(describe(e));\n          }\n        });\n      }\n      build.onLoad({ filter }, ({ path }) => {\n        const name = nameOf(path);\n        const loader = path.endsWith('.ts') ? 'ts' : 'js';\n        if (generated.entries.has(name)) return { contents: readFileSync(path, 'utf8') + hotLocale(name), loader };\n        return name === 'index' ? { contents: HOT_SET + inspector + readFileSync(path, 'utf8') + HOT_INDEX, loader } : undefined;\n      });\n    },\n  };\n}\n\nexport interface InspectorRoutesOptions {\n  /** The config, inline. Without it, `prosebook.config.*` at `root` is read. */\n  config?: ProsebookConfig;\n  /** The folder the config's paths resolve from, and where its file is found: the working directory when unset. */\n  root?: string;\n}\n\n/**\n * The inspector's endpoints as `Bun.serve` routes: `routes: { ...inspector(), '/': index }`. For dev\n * only: they read and write the catalog.\n */\nexport function inspector(options: InspectorRoutesOptions = {}): Record<string, (req: Request) => Promise<Response>> {\n  const handle = inspectorEndpoints(loadConfig(resolve(options.root ?? process.cwd()), options.config), {\n    open: ({ file, line, column }) => {\n      try {\n        Bun.openInEditor(file, { line, column });\n        return new Response(null, { status: 204 });\n      } catch (e) {\n        return new Response(`${e instanceof Error ? e.message : String(e)}: set VISUAL or EDITOR to the editor's command`, { status: 500 });\n      }\n    },\n  });\n  const route = async (req: Request) => (await handle(req)) ?? new Response(null, { status: 404 });\n  return { '/__prosebook/open': route, '/__prosebook/entry': route };\n}\n\n// bunfig.toml names the module, and Bun takes its default export as the plugin.\nexport default prosebook();\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;AAsDA,MAAM,gBAAgB,OAAO,YAAY,KAAK,WAAW;AAEzD,MAAM,YAAY,MAAgB,aAAa,eAAe,EAAE,UAAU,aAAa,QAAS,EAAE,SAAS,EAAE,UAAW,OAAO,CAAC;AAChI,MAAM,UAAU,MAAc,EAAE,QAAQ,uBAAuB,MAAM;AAErE,SAAgB,UAAU,UAA+B,CAAC,GAAc;CACtE,OAAO;EACL,MAAM;EACN,MAAM,MAAM,OAAO;GACjB,MAAM,SAAS,MAAM,WAAW,QAAQ,QAAQ,QAAQ,QAAQ,IAAI,CAAC,GAAG,QAAQ,MAAM;GACtF,IAAI,YAAY,SAAS,MAAM;GAE/B,MAAM,SAAS,OAAO,IAAI,MAAM,OAAO,CAAC,CAAC,IAAI,MAAM,CAAC,CAAC,KAAK,SAAS;GACnE,MAAM,SAAS,IAAI,OAAO,IAAI,OAAO,0BAA0B;GAC/D,MAAM,UAAU,SAAiB,SAAS,IAAI,CAAC,CAAC,QAAQ,YAAY,EAAE;GAEtE,IAAI,iBAAiB,MAAM,QAAQ;IACjC,MAAM,QAAQ,QAAQ,SAAS;IAC/B,IAAI,UAAU,OAAO;IACrB,MAAM,EAAE,MAAM,WAAW,YAAY,QAAQ,UAAU,QAAQ;IAC/D,IAAI,OAAO,SAAS,GAAG,MAAM,IAAI,MAAM,cAAc,QAAQ,OAAO,IAAI,CAAC;IACzE,MAAM,OAAO,OAAO,MAAM,QAAQ,IAAI;IACtC,MAAM,OAAO,EAAE,OAAO,IAAI,EAAE,WAAW;KACrC,MAAM,UAAU,UAAU,QAAQ,IAAI,OAAO,IAAI,CAAC;KAClD,OAAO,YAAY,KAAA,IAAY,KAAA,IAAY;MAAE,UAAU,aAAa,SAAS,IAAI;MAAG,QAAQ;KAAK;IACnG,CAAC;IACD;GACF;GAEA,MAAM,MAAM,QAAQ,IAAI,aAAa;GACrC,MAAM,YAAY,OAAO,QAAQ,YAAY,QAAQ,iBAAiB,eAAe,GAAG,IAAI;GAC5F,IAAI,KACF,aAAa,cAAc;IACzB,IAAI;KACF,YAAY,SAAS,MAAM;IAC7B,SAAS,GAAG;KACV,QAAQ,MAAM,SAAS,CAAC,CAAC;IAC3B;GACF,CAAC;GAEH,MAAM,OAAO,EAAE,OAAO,IAAI,EAAE,WAAW;IACrC,MAAM,OAAO,OAAO,IAAI;IACxB,MAAM,SAAS,KAAK,SAAS,KAAK,IAAI,OAAO;IAC7C,IAAI,UAAU,QAAQ,IAAI,IAAI,GAAG,OAAO;KAAE,UAAU,aAAa,MAAM,MAAM,IAAI,UAAU,IAAI;KAAG;IAAO;IACzG,OAAO,SAAS,UAAU;KAAE,UAAU,UAAU,YAAY,aAAa,MAAM,MAAM,IAAI;KAAW;IAAO,IAAI,KAAA;GACjH,CAAC;EACH;CACF;AACF;;;;;AAaA,SAAgB,UAAU,UAAkC,CAAC,GAAwD;CACnH,MAAM,SAAS,mBAAmB,WAAW,QAAQ,QAAQ,QAAQ,QAAQ,IAAI,CAAC,GAAG,QAAQ,MAAM,GAAG,EACpG,OAAO,EAAE,MAAM,MAAM,aAAa;EAChC,IAAI;GACF,IAAI,aAAa,MAAM;IAAE;IAAM;GAAO,CAAC;GACvC,OAAO,IAAI,SAAS,MAAM,EAAE,QAAQ,IAAI,CAAC;EAC3C,SAAS,GAAG;GACV,OAAO,IAAI,SAAS,GAAG,aAAa,QAAQ,EAAE,UAAU,OAAO,CAAC,EAAE,iDAAiD,EAAE,QAAQ,IAAI,CAAC;EACpI;CACF,EACF,CAAC;CACD,MAAM,QAAQ,OAAO,QAAkB,MAAM,OAAO,GAAG,KAAM,IAAI,SAAS,MAAM,EAAE,QAAQ,IAAI,CAAC;CAC/F,OAAO;EAAE,qBAAqB;EAAO,sBAAsB;CAAM;AACnE;AAGA,IAAA,cAAe,UAAU"}

package/dist/bundle-CpUIWb9j.d.ts

@@ -0,0 +1,6 @@
+import "./compile-ClK9htKr.js";
+import "./config-CzaJJQ60.js";
+/** How a build prunes: `strict` also fails on a read whose key it can't see. */
+type Prune = 'strict' | 'loose' | false;
+export { Prune as t };
+//# sourceMappingURL=bundle-CpUIWb9j.d.ts.map

package/dist/bundle-CpUIWb9j.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bundle-CpUIWb9j.d.ts","names":[],"sources":["../src/tools/bundle.ts"],"mappings":";;;KAiBY"}