fimo 0.9.0-experimental.1 → 0.9.0-experimental.10

package/assets/agent-templates/content-translator/scripts/write-locale-files.ts

@@ -0,0 +1,66 @@
+/**
+ * Tool: write-locale-files
+ *
+ * For locale-keyed JSON files in `src/locales/<locale>.json`, fill in
+ * missing keys from the default-locale file using the configured
+ * translation provider. Run after translate-entries when projects mix
+ * CMS-driven copy with hardcoded i18n strings.
+ */
+
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+
+interface Catalog {
+  [key: string]: string;
+}
+
+async function readCatalog(file: string): Promise<Catalog> {
+  try {
+    const text = await fs.readFile(file, 'utf8');
+    return JSON.parse(text) as Catalog;
+  } catch {
+    return {};
+  }
+}
+
+async function writeCatalog(file: string, catalog: Catalog): Promise<void> {
+  await fs.writeFile(file, JSON.stringify(catalog, null, 2) + '\n', 'utf8');
+}
+
+async function translate(text: string, _to: string): Promise<string> {
+  // Stub — provider-specific call.
+  return text;
+}
+
+async function main(): Promise<void> {
+  const defaultLocale = process.env.FIMO_DEFAULT_LOCALE ?? 'en';
+  const targetLocales = (process.env.FIMO_TARGET_LOCALES ?? '').split(',').filter(Boolean);
+  const localesDir = process.env.FIMO_LOCALES_DIR ?? 'src/locales';
+
+  const defaultFile = path.join(localesDir, `${defaultLocale}.json`);
+  const defaultCatalog = await readCatalog(defaultFile);
+
+  for (const target of targetLocales) {
+    const targetFile = path.join(localesDir, `${target}.json`);
+    const targetCatalog = await readCatalog(targetFile);
+    let dirty = false;
+
+    for (const [key, sourceValue] of Object.entries(defaultCatalog)) {
+      if (targetCatalog[key]) {
+        continue;
+      }
+      targetCatalog[key] = await translate(sourceValue, target);
+      dirty = true;
+    }
+
+    if (dirty) {
+      await writeCatalog(targetFile, targetCatalog);
+      console.log(`Wrote ${targetFile}`);
+    }
+  }
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/assets/agents-starter/claude/settings.json

@@ -0,0 +1,19 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(fimo:*)",
+      "Bash(npx fimo:*)",
+      "Bash(pnpm:*)",
+      "Bash(pnpm dlx:*)",
+      "Bash(npx:*)",
+      "Bash(git status)",
+      "Bash(git status:*)",
+      "Bash(git diff)",
+      "Bash(git diff:*)",
+      "Bash(git log:*)",
+      "Bash(git add:*)",
+      "Bash(git restore:*)",
+      "Bash(mkdir:*)"
+    ]
+  }
+}

package/assets/content-templates/types-template.eta

@@ -8,6 +8,7 @@
  *          }
  */
 %>
+// @ts-nocheck — generated internals are exempt from the app's own tsconfig strictness; exported types still work
 // AUTO-GENERATED ⚠️ – do not edit by hand
 import { type Fields, type FimoBoolean, type FimoMedia, type FimoPolymorphicReference, type FimoReference, type FimoRichText, type FimoRichTextContent, type FimoString, type Populate, type PopulatedResult, type ProjectedWithPopulate, type Query, type Sort, type Where, type WithReferences } from "fimo/ui";
 <%

package/assets/skills/fimo/references/translations.md

@@ -0,0 +1,75 @@
+# Translations — package surface
+
+> For the CLI workflow (`fimo validate`, when to run validation, what sync does), see **`fimo-cli/references/translations.md`**.
+
+This file covers the **package surface**: the `t()` helper, the `useTranslations()` hook, and the code-side rules for wrapping strings.
+
+## The rule
+
+Every piece of **user-facing static text** in the app (page titles, button labels, nav items, form placeholders, empty-state copy, alt text, meta tags) MUST be wrapped in `t('key', 'Default text')`.
+
+Raw string literals in JSX are a bug — they won't show up in the Fimo admin as editable content and won't be translatable. **Hard-coded JSX text (`<h1>Welcome</h1>`) skips the entire i18n + inline-editing pipeline and becomes invisible to the editor.**
+
+## Setup (already wired)
+
+Translations are wired automatically by the `fimo/vite` build plugin. It exposes a `virtual:translations` module sourced from `<projectRoot>/translations/en.json`, and `useTranslations()` reads from that virtual module — there's no provider to add or remove. The app entry is `src/root.tsx`, which wraps the app in `<FimoProviders>` from `fimo/react-router`; you never import `translations/en.json` in app code. Pages and components only call `useTranslations()`.
+
+## Usage
+
+```tsx
+import { useTranslations, Text } from 'fimo/ui';
+
+export function Hero() {
+  const { t } = useTranslations();
+  return (
+    <section>
+      <h1>
+        <Text value={t('hero.title', 'Welcome to Acme')} />
+      </h1>
+      <p>
+        <Text value={t('hero.subtitle', 'The fastest way to ship your idea.')} />
+      </p>
+      <input placeholder={String(t('hero.emailPlaceholder', 'you@example.com'))} />
+      <img alt={String(t('hero.imageAlt', 'Team collaborating'))} src="..." />
+    </section>
+  );
+}
+```
+
+- `t(key, default)` returns a `FimoString` (wrapped for source tracking). Render it via `<Text value={...} />` inside JSX.
+- For HTML attributes (`placeholder`, `alt`, `title`, `aria-label`) cast with `String(t(...))` — the attribute can't accept a `FimoString` object directly.
+
+## Hard rules (enforced by the pre-build linter)
+
+**The first argument to `t()` MUST be a string literal.** Dynamic keys break source tracking and fail the lint step.
+
+```tsx
+// ❌ BAD — variable key
+t(item.key, item.label);
+
+// ❌ BAD — template with expression
+t(`nav.${page}`, 'Page');
+
+// ✅ GOOD — put the t() call where the literal lives
+const items = [{ label: t('nav.home', 'Home') }, { label: t('nav.about', 'About') }];
+items.map((item) => <li>{item.label}</li>);
+```
+
+## Key naming
+
+- Dot-namespaced, lowercase, kebab or camelCase leaves: `hero.title`, `nav.signIn`, `footer.copyright`, `errors.required`.
+- Namespace by **page/section/component**, not by feature (`contact.form.submitLabel`, not `forms.contactSubmit`).
+- The default (second arg) is the English copy — make it final, not a TODO; it ships to production if no translation exists for the active locale.
+
+## What NOT to translate
+
+- Dynamic content from entries or forms — that's already stored in the DB (content via schemas, submissions via forms).
+- Content-type field values rendered via `fimo/ui` primitives (`<Text>`, `<RichText>`, …) — those carry their own admin-editing metadata.
+- Purely decorative / non-text (icons, logos).
+- Developer-only strings (`console.log`, error messages thrown for debugging).
+
+## Rule of thumb
+
+If a human reader sees the text AND the project owner might want to reword it in the admin, it goes through `t()`. When in doubt: wrap it.
+
+After adding or changing `t()` calls, run `fimo validate` (or rely on `fimo deploy` doing it). See `fimo-cli/references/translations.md`.

package/assets/skills/fimo-migration/SKILL.md

@@ -117,6 +117,8 @@ node <this-skill>/scripts/write-migration-report.mjs <project-root>
 - `references/wrap.md` - wrap mode: adopt a working JS codebase and wrap its
   content in place (default for source-backed JS sites).
 - `references/manifest.md` - canonical migration ledger schema.
+- `references/pages.md` - the page registry (templates, schema bindings,
+  instances), Studio preview navigation, and the opt-in per-page SEO recipes.
 - `references/content.md` - CMS, entries, references, and source value rules.
 - `references/media.md` - media inventory, upload, dedupe, and replacement rules.
 - `references/forms.md` - form classification and Fimo replacement rules.

package/assets/skills/fimo-migration/references/manifest.md

@@ -66,11 +66,22 @@ rebuild migrations:
       "wrappedMedia": 3,
       "wrappedRichText": 1
     },
+    "seo": { "decision": "external", "decidedBy": "default" },
     "planPath": ".fimo/migration/plan.json"
   }
 }
 ```
 
+`wrap.seo` records who owns the site's SEO metadata — a USER decision, like
+`wrap.dataSources`: `decision` is `"fimo"` (Fimo manages per-page SEO,
+editable in the Studio) or `"external"` (the code / an external SEO tool
+keeps ownership — the DEFAULT, nothing is ever wired on it). `decidedBy` is
+`"default"` until the user actually answered; relay defaulted records and
+rewrite them with `decidedBy: "user"`. Page bindings themselves live in the
+page registry (`fimo-config.json#routes` →
+`params: { "<param>": { "schema", "queryField", "displayField" } }`), not in
+the manifest — see `references/pages.md`.
+
 `coverage` mirrors the final `fimo migrate wrap --check` output: `wrappable`
 must be 0 (or fully accounted for by `ignored` + `unresolvedItems`, each with a
 ledger entry). `seeded` counts must match what `fimo labels list` /

package/assets/skills/fimo-migration/references/pages.md

@@ -0,0 +1,234 @@
+# Pages — the page registry, Preview navigation, and opt-in SEO
+
+A **Page** is a navigable URL surface of the site, in two forms:
+
+- **Page template** — what the app's routing declares: `/pricing` (static),
+  `/blog/:slug` (dynamic). The app's CODE is the source of truth for page
+  structure; `fimo migrate` discovers templates per framework and reconciles
+  them into the registry, `fimo-config.json#routes` (manual entries are
+  preserved). Param syntax is ALWAYS `:param` / catch-all `:param*` — never
+  `[param]`.
+- **Page instance** — a concrete page: template × content entry
+  (`/blog/:slug` × `hello-world`). Instances are NEVER stored; they derive
+  from entries through the template's binding, so they cannot drift.
+
+The registry entry shape:
+
+```json
+"blog-post": {
+  "label": "Blog post",
+  "path": "/blog/:slug",
+  "params": { "slug": { "schema": "BlogPost", "queryField": "slug", "displayField": "title" } },
+  "seo": { "title": "{{blog-post.title}} — {{siteName}}" }
+}
+```
+
+- `params[<param>]` is the **binding**: the schema whose entries materialize
+  the instances. `queryField` = the entry field substituted into the URL
+  (entry `slug` metadata always qualifies); `displayField` = the label the
+  Studio's page picker shows.
+- The Studio preview navigates ONLY what the registry describes: static pages
+  as-is, dynamic pages once bound. An unbound dynamic page navigates to a
+  literal `/blog/:slug` URL — broken by definition.
+- Locale params (`:locale`, `:lang`) are never schema-bound; tooling
+  substitutes the project's default locale. (Studio locale switching for
+  dynamic pages is a platform follow-up, not your problem.)
+
+## Completing the bindings (agent workflow)
+
+`fimo migrate` writes strong-evidence bindings itself (a rewired parent list
+page; a wired CMS with a single page-builder type) and lists candidates +
+unbound pages in the generated prompt. Your job:
+
+1. `npx fimo pages list` — see every template and its status
+   (`static | dynamic:bound | dynamic:unbound`).
+2. For each candidate/unbound page, find the schema whose entries the page
+   renders (read the page component's fetch). Apply with
+   `npx fimo pages set <id> --params '{"<param>":{"schema":"<Type>","queryField":"slug","displayField":"<field>"}}'`
+   — it validates the schema and both fields against the server. Never
+   hand-edit the JSON. If drafts are not adopted yet, run
+   `schemas adopt-drafts` FIRST and bind with the FINAL names.
+3. Add pages the scanner missed (SPA relative/wildcard routes):
+   `npx fimo pages set <id> --path /the/path --label "Label"`.
+   Never repeat the folder/category in the label: the `/features/agents` page
+   is labeled "Agents", NOT "Feature: Agents" — the Studio tree already nests
+   it under Features.
+   Labels must read like a human wrote them: acronyms uppercase ("Agentic
+   CMS", "AI Stack", "SEO GEO" — never "Agentic Cms"), no two sibling pages
+   with the same name (a bound template is named after its schema — "Blog
+   Post" next to the "Blog" index; the machine does this when it binds, fix
+   any leftover with `--label`).
+   When the site's NAV groups flat pages editorially (a "Resources" menu over
+   /for-developers, /for-founders…), mirror it with
+   `npx fimo pages set <id> --group "Resources"` — the Studio Pages tree
+   folds them under that group even without a shared URL segment.
+4. Map each page to its label keys when they diverge. The Studio shows a
+   page's labels by key prefix, defaulting to `<pageId>.` — but wrapped keys
+   derive from FILE names (`AiCms.tsx` → `ai-cms.*`) or data files
+   (`personas.*`), which can differ from the URL-derived page id
+   (`agentic-cms`). A page whose Studio view is EMPTY almost always means
+   this mismatch. `fimo migrate` PREFILLS `labelPrefixes` wherever it can
+   prove the join (a staged key appears verbatim in the route's component
+   file) and the prompt § Routes & pages lists every UNCLAIMED prefix left.
+   Your job: place each unclaimed prefix — claim it with
+   `npx fimo pages set <id> --label-prefix "<prefix>"` (comma-separated for
+   several; claims MERGE into the existing list so machine-prefilled
+   prefixes survive, `""` clears the whole list) when one page renders those keys, or leave it
+   deliberately when it is shared (chrome, multi-page data files) and say so
+   in your report. No prefix may end up merely forgotten.
+5. Give each page the Lucide icon that best matches its CONTENT:
+   `npx fimo pages set <id> --icon <kebab-name>` (pricing → `tag`, blog →
+   `newspaper`, contact → `mail`, legal pages → `scale`, team/about →
+   `users`, docs → `book-open`). Read the page component to judge. Use
+   well-known Lucide names only — an unknown name silently falls back to
+   the default file icon in the Studio. Skip the flag when nothing clearly
+   fits.
+6. Verify: `npx fimo pages list --expand` materializes every instance —
+   each page the site's nav links to must appear as a real URL.
+
+## Shared chrome → Single Types (the content-model rule)
+
+A site's content model must read like a CMS, not like an implementation:
+
+- **Chrome** (header, footer, nav, menus, banners) is edited as ONE thing →
+  a SINGLE TYPE per piece (`src/schemas/<Name>.json` with
+  `"isSingleton": true`, real fields mirroring the source: nav items as an
+  array/blocks field, logo as media), pushed with `npx fimo schemas push`,
+  its ONE document written from the source values with
+  `npx fimo documents set <Name> --body '<json>'` (singletons REJECT the
+  entries endpoints), component rewired to read it. Never a loose label
+  pile, never a collection.
+- **Page-scoped structure** (a pricing page's FAQ list) → a component array
+  on that page's Single, or a collection + reference when genuinely reused
+  across pages. Never an orphan collection nobody can situate. CLAIM the
+  single on its page (`npx fimo pages set pricing --single Pricing`) — it
+  then edits inline in the page's Studio view and leaves the Singles tab.
+- **Real repeating content** (blog posts, team members) → a collection, with
+  HUMAN slugs derived from the display field (never `faq-item-<hash>`), and
+  schema field order matching reading order (question before answer).
+- **A page's SECTIONS are its Single's nested blocks.** A marketing page is
+  a sequence of sections (hero, logo strip, features grid with grouped
+  cards, testimonials, integrations, stats, FAQ) — model the page as ONE
+  Single whose fields are nested block components mirroring that structure
+  (blocks nest: a `features` field holds groups, each group holds cards).
+  Section card lists are NEVER "page furniture" exemptions when they carry
+  real copy — an exemption hides marketing content from the editor, which
+  is a failed migration for that section. Claim the Single on its page.
+  **The machine BUILDS this model for you**: `fimo migrate` writes, per
+  multi-section page, an analysis draft (`.fimo/migration/page-drafts/`,
+  regenerate with `npx fimo pages draft`) AND a ready page Single
+  (`.fimo/migration/page-singles/<Uid>.json` — singleton schema + document
+  filled with the staged label values and the source block rows). Sections
+  flagged `"shared": true` render on several pages — that is chrome: model
+  each once as a Single Type, never as a per-page block. The `wrap --check`
+  Content-model gate fails while a built Single is neither claimed
+  (`pages set <id> --single <Uid>`) nor recorded under
+  `wrap.modelDeviations` (`{"page": "<id>", "reason": "…"}`) — a reason the
+  user would accept; "faster as labels" is not one. Your work per page:
+  rename machine field keys to editorial names, push, `documents set`,
+  rewire the reads with source fallback, claim.
+
+  **Worked real example** (the Fimo homepage, the model the user ratified):
+  the page renders hero → logo strip → features grid (3 groups, each with
+  cards) → testimonials → integrations → stats bar → FAQ. Its Single:
+
+  ```json
+  {
+    "uid": "Home",
+    "isSingleton": true,
+    "fields": {
+      "builtOnTheBest": {
+        "type": "blocks",
+        "schema": { "fields": { "name": { "type": "string" }, "domain": { "type": "string" } } }
+      },
+      "features": {
+        "type": "blocks",
+        "schema": {
+          "fields": {
+            "title": { "type": "string" },
+            "subtitle": { "type": "string" },
+            "cards": {
+              "type": "blocks",
+              "schema": { "fields": { "title": { "type": "string" }, "description": { "type": "text" } } }
+            }
+          }
+        }
+      },
+      "testimonials": {
+        "type": "blocks",
+        "schema": {
+          "fields": {
+            "quote": { "type": "text" },
+            "metricValue": { "type": "string" },
+            "metricLabel": { "type": "string" },
+            "author": { "type": "string" },
+            "role": { "type": "string" }
+          }
+        }
+      },
+      "ecosystem": {
+        "type": "blocks",
+        "max": 1,
+        "schema": {
+          "fields": {
+            "title": { "type": "string" },
+            "stats": { "type": "blocks", "schema": { "fields": { "label": { "type": "string" } } } }
+          }
+        }
+      },
+      "faqs": { "type": "blocks", "schema": { "fields": { "q": { "type": "string" }, "a": { "type": "text" } } } }
+    }
+  }
+  ```
+
+  Note what made it right: block names are the on-page section titles
+  ("Built on top of the best" → `builtOnTheBest`), field names are ROLES
+  (`title`, `quote`, `author`) never copy slugs, a logo strip carries its
+  ITEMS (not just its heading), computed live values (stat numbers) stay in
+  code, and the whole thing was claimed on the page. Smart deviations were
+  reported, not silent.
+
+- **Plumbing** (`WrappedRichText`, `WrappedMedia`) is storage — the Studio
+  hides it from Collections and shows the entries under their pages; never
+  present it as content in your report.
+
+## SEO — a USER decision, never wired by default
+
+Who owns SEO metadata is recorded in `.fimo/migration/manifest.json` →
+`wrap.seo` (`{ "decision": "fimo" | "external", "decidedBy": "user" | "default" }`).
+The default is ALWAYS `external` (nothing touched — the site's code or an
+external SEO tool keeps ownership). When the prompt shows the decision as
+DEFAULTED, relay it to the user once; only an explicit user "fimo" unlocks
+wiring. Never migrate, edit, or inject metadata on the default.
+
+When the user opted into Fimo-managed SEO, the engine is the neutral
+`fimo/seo` export — pure resolution over the registry, no framework coupling:
+
+```ts
+import { getFimoSeoForPath } from 'fimo/seo';
+const seo = getFimoSeoForPath(pathname, { routeData: { 'blog-post': entry } });
+// seo.title / seo.description / seo.image / seo.robots …
+```
+
+Per-framework injection (map the resolved values to the framework's head API):
+
+- **Next (app router)** — in the layout or page, `generateMetadata()` calls
+  `getFimoSeoForPath` with the resolved pathname (+ the entry as `routeData`
+  on dynamic pages) and returns `{ title, description, openGraph: {...} }`.
+- **React Router** — already shipped: `loadFimoMetaData` / `buildFimoMeta` /
+  `fimoHtmlProps` from `fimo/react-router`.
+- **Astro** — a head partial calling `getFimoSeoForPath(Astro.url.pathname)`
+  server-side and rendering the `<meta>` tags.
+- **Nuxt** — `useSeoMeta()` fed from a server util wrapping `getFimoSeoForPath`.
+- **SvelteKit** — resolve in `+layout.server` load, render in the root
+  layout's `<svelte:head>`.
+
+Route-level `seo` blocks support `{{variables}}` resolved against
+`routeData` — per-INSTANCE metadata from one template.
+
+## Sitemap / robots
+
+Once bindings exist, `getFimoPaths` (from `fimo/paths`) materializes the full
+instance list for prerender/sitemap use. It reads the API base URL from
+`VITE_API_URL` (a plain env var or `.env` line works outside Vite). The
+`fimo pages list --expand` output is the same list, CLI-side.

package/assets/skills/fimo-migration/references/wrap.md

@@ -318,6 +318,35 @@ four gates pass:
    SPA); the gate enforces the rest. Enforced only once items are wrapped;
    Next pages-router-only projects get a warning, not a failure.
 
+**When a CMS was scaffolded, the four gates do NOT prove the reads resolve from
+Fimo.** Parity drift from real→example content is expected and gets ignored, so
+a wiring that silently falls through to the live CMS passes every gate while the
+page renders the CMS's own content (or 404s when the CMS is down). This is the
+CMS analog of the mandatory browser check — prove Fimo _ownership_ by hand:
+load the homepage plus one page per scaffolded type and confirm the rendered
+value is a scaffolded EXAMPLE marker (`Title example 1`, `Meta Title example 1`,
+a `<type>-example-1` slug), NOT real CMS content and NOT a 404. Then confirm in
+Studio Edit mode that a scaffolded block is selectable, not just rendered (a
+block item with no stable id renders but cannot be edited — editability is the
+whole point). **A single type (`Global`, `Header`, `Footer`) that reads empty
+while collections render is the singular-vs-plural keying bug**: the generated
+`fimo-strapi.ts` must key single types by their singular path (`'global'`, not
+`'globals'`), and in dev the adapter logs `/api/global looks like a scaffolded
+type but is not in the type map` on that fallthrough. Fix it in the CLI
+(`scripts/cms/strapi/schema-map.ts`) and regenerate with
+`fimo migrate --scaffold-cms` — never hand-edit the generated module.
+
+**Populate real routes** (scaffolded CMS only): example entries carry generated
+slugs, so only unfiltered reads (the homepage) resolve — every real route the
+site links to misses its slug filter and 404s (the adapter answers a filtered
+miss on a Fimo-owned type with an empty envelope; it never leaks the read to
+the old CMS). Harvest the site's real slugs (live production `sitemap.xml`,
+else nav/footer links in the code, else ask the user) and create one entry of
+the routed type per linked route — matching slug + path field, distinct title,
+varied block subset. Then click through the nav: every linked page renders,
+none 404. This is navigability, not the content migration (the real pull is a
+later, separate step).
+
 **Config-driven sites** (all copy in a data file, templates render only
 expressions): the scanner lists copy-bearing `.json`/`.yml` files and
 markdown groups in the plan (`dataFiles`) and the coverage gate fails until
@@ -594,6 +623,22 @@ framework — nothing above this section should name a specific framework.
   </FimoSpaProviders>;
   ```
 
+- Instant content: the provider paints synchronously from
+  `window.__FIMO_CONTENT__` (baked) or the last visit's localStorage cache,
+  then revalidates in the background (Studio preview saves and window focus
+  trigger refetches — no reload needed). Only the FIRST EVER visit to a
+  non-baked site flashes inline fallbacks for one network round trip. If the
+  project prerenders its `index.html` (any SSG/prerender step), close that
+  gap by baking the payload at build time:
+
+  ```js
+  // e.g. scripts/bake-fimo-content.mjs — run AFTER the build/prerender step
+  import { fetchFimoSpaContent, serializeFimoSpaContent } from 'fimo/react';
+
+  const payload = await fetchFimoSpaContent(process.env.VITE_API_URL, config);
+  html = html.replace('</head>', `${serializeFimoSpaContent(payload)}</head>`);
+  ```
+
 - Routes: no file convention — the scan reads LITERAL ABSOLUTE paths from
   react-router (`<Route path="/x">` and `createBrowserRouter([{ path: '/x' }])`)
   into the fimo-config route registry. Relative child paths, `index` routes,

package/dist/build/vite/plugins/translations.js

@@ -14,6 +14,12 @@ export default function translationsPlugin() {
     let reconnectTimer;
     let refreshTimer;
     let pollTimer;
+    // Set on closeBundle. Without it, closing a socket fires its own onclose,
+    // which schedules a reconnect AFTER the cleanup ran — resurrecting the
+    // event sockets forever and pinning the event loop. That is exactly how a
+    // prerender script using `createServer({ middlewareMode: true })` finished
+    // its work and then never exited.
+    let disposed = false;
     const refreshLabels = async () => {
         bundle = await loadLabelBundle(rootDir);
         return bundle;
@@ -49,6 +55,9 @@ export default function translationsPlugin() {
         });
     };
     const scheduleRefresh = () => {
+        if (disposed) {
+            return;
+        }
         if (refreshTimer) {
             clearTimeout(refreshTimer);
         }
@@ -56,6 +65,17 @@ export default function translationsPlugin() {
             void refreshLabelsAndInvalidateIfChanged().catch(() => undefined);
         }, 150);
     };
+    const adoptEventSockets = (sockets) => {
+        if (disposed) {
+            // The server closed while the async connect was in flight — sockets
+            // landing now must close immediately or they outlive the cleanup.
+            for (const socket of sockets) {
+                socket.close();
+            }
+            return;
+        }
+        eventSockets = sockets;
+    };
     return {
         name: 'fimo-virtual-translations',
         enforce: 'pre',
@@ -76,11 +96,7 @@ export default function translationsPlugin() {
             devServer = server;
             server.watcher.add([join(rootDir, 'fimo-config.json'), join(rootDir, '.env'), join(rootDir, '.env.local')]);
             void refreshLabelsAndInvalidateIfChanged().catch(() => undefined);
-            connectLabelEvents(rootDir, scheduleRefresh)
-                .then((sockets) => {
-                eventSockets = sockets;
-            })
-                .catch(() => undefined);
+            connectLabelEvents(rootDir, scheduleRefresh).then(adoptEventSockets).catch(() => undefined);
             pollTimer = setInterval(() => {
                 void refreshLabelsAndInvalidateIfChanged().catch(() => undefined);
             }, 2000);
@@ -126,6 +142,9 @@ export default function translationsPlugin() {
             return [];
         },
         closeBundle() {
+            // Order matters: dispose FIRST so the onclose handlers fired by the
+            // socket closes below (and any in-flight connect) cannot reschedule.
+            disposed = true;
             for (const socket of eventSockets) {
                 socket.close();
             }
@@ -192,12 +211,11 @@ export default function translationsPlugin() {
                 }
             };
             socket.onclose = () => {
+                if (disposed) {
+                    return;
+                }
                 reconnectTimer = setTimeout(() => {
-                    void connectLabelEvents(root, onLabelsChanged)
-                        .then((nextSockets) => {
-                        eventSockets = nextSockets;
-                    })
-                        .catch(() => undefined);
+                    void connectLabelEvents(root, onLabelsChanged).then(adoptEventSockets).catch(() => undefined);
                 }, 2000);
             };
             socket.onerror = () => undefined;

package/dist/cli/bundle.json

@@ -1,7 +1,7 @@
 {
   "bundled": true,
   "bundler": "esbuild",
-  "bundledAt": "2026-07-23T17:15:28.604Z",
+  "bundledAt": "2026-07-29T15:37:14.073Z",
   "cliVersion": "0.8.0",
   "external": [
     "oxc-parser",