zintljs 0.1.0-alpha.7

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026-present Khalid F. Shuhail
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,253 @@
+<p align="center">
+  <br>
+  <br>
+  <a href="https://github.com/zintljs/zintl" target="_blank" rel="noopener noreferrer">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/zintljs/zintl/main/examples/website/public/favicon.svg">
+      <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/zintljs/zintl/main/examples/website/public/favicon.svg">
+      <img alt="Zintl logo" src="https://raw.githubusercontent.com/zintljs/zintl/main/examples/website/public/favicon.svg" height="80">
+    </picture>
+  </a>
+  <br>
+  <br>
+</p>
+
+<h1 align="center">Zintl ⚡</h1>
+
+<p align="center">
+  <strong>Compiler-driven internationalization system for modern web applications.</strong>
+</p>
+
+<p align="center">
+  <a href="https://npmjs.com/package/zintljs"><img src="https://img.shields.io/npm/v/zintljs.svg?color=863bff&label=" alt="npm package"></a>
+  <a href="https://nodejs.org/en/about/previous-releases"><img src="https://img.shields.io/node/v/zintljs.svg?color=6a2ee3&label=node" alt="node compatibility"></a>
+  <a href="https://github.com/zintljs/zintl/actions"><img src="https://img.shields.io/badge/build-passing-success" alt="build status"></a>
+</p>
+
+<br/>
+
+Zintl (pronounced [`/tsɪntl/`]) is a compile-time internationalization engine built to provide a faster, leaner, and zero-config localization experience for modern web projects. It moves internationalization from a runtime lookup bottleneck to a compile-time optimization pipeline.
+
+It consists of two major parts:
+
+- **A Vite Plugin & Runtime:** Integrates seamlessly into Vite's module graph to perform surgical code replacement, inlining, and HMR catalog updates.
+- **A Compiler Core:** Builds dependency graphs, splits localized content into optimized translation chunks, and compiles target ICU formats into ultra-fast JS conditional branches at build time.
+
+---
+
+## Features
+
+- ⚡ **Zero-Runtime Overhead (ZCU Baking):** Compiles ICU MessageFormat expressions (plurals, select enums, nesting) into pure JavaScript conditions at build time. No heavy parsing libraries are shipped to the client.
+- 📂 **Smart Chunking & Code Splitting:** A graph-based boundary algorithm automatically partitions translations into entry-specific, lazy-loaded, and shared catalog chunks matching your bundler's code-splitting boundaries.
+- 🔍 **Zero-Config Extraction:** Automatically extracts strings from JSX, template literals, and HTML structures. No manual translation key mapping or tedious function wrappers are required.
+- 👻 **Zero-Disk Source Locale (Ghost Mode):** The source locale (typically English) is completely diskless. The compiler virtualizes it on-the-fly from the extraction manifest, eliminating redundant `{ "key": "key" }` files from your repository.
+- 🌐 **HTML Metadata Projections:** Automatically extracts and translates standard HTML head tags (`title`, `meta[name="description"]`, and directionality `dir`). It bakes translations directly for static targets or injects a minimal head-blocking bootstrap script for dynamic targets.
+- 🏷️ **Surgical Comment Directives:** Control translation behavior with inline code comments (`@zintl-ignore` with HTML tag scoping, `@zintl-note` for translator context, and `@zintl-pass` to pass grammatical context variables).
+- 🔄 **Lightning Fast HMR:** Surgical invalidation of translation catalogs. Accept hot updates in-place during development with zero page reloads.
+
+---
+
+## Core Architecture
+
+Zintl operates as a **Three-Package Monorepo** separating extraction, compilation, and runtime logic:
+
+```
+Source Code ──▶ @zintljs/extractor (AST Scan) ──▶ @zintljs/compiler (Graph & Baking) ──▶ zintl (Vite Plugin & Runtime)
+```
+
+1. **`@zintljs/extractor`:** A pure metadata provider. It scans code syntax using high-performance AST parsers to identify translation anchors (`zintl()`), template literals, and HTML sinks without modifying source files.
+2. **`@zintljs/compiler`:** The transformation orchestrator. It builds boundary graphs, resolves file dependencies, manages Levenshtein-based typo reconciliation, and generates chunked catalogs.
+3. **`zintl`:** The developer-facing entry point. It exports the Vite plugin and runtime macros (`zintl()`, `t()`, `getLocale()`) used in code.
+
+---
+
+## Quick Start
+
+### 1. Installation
+
+Install the main Zintl package using Vite+:
+
+```bash
+vp install -D zintljs
+```
+
+### 2. Configure the Vite Plugin
+
+Add the plugin to your `vite.config.ts` configuration file:
+
+```typescript
+import { defineConfig } from "vite";
+import zintl from "zintljs/vite"; // the plugin — a default export
+
+export default defineConfig({
+  plugins: [
+    zintl({
+      sourceLocale: "en",
+      locales: ["en", "ar", "fr"],
+      outputDir: "locales",
+    }),
+  ],
+});
+```
+
+> The plugin lives at `zintl/vite`. The bare `zintl` entry is the **macro** you call in application code (step 3) — importing that one into `vite.config.ts` gives you an async no-op, not a plugin.
+
+#### Plugin Options
+
+Every option is optional; most projects only set `locales`. Full documentation, including what each option does to your build, is on the `Options` type — hover or ctrl+click it in your editor.
+
+| Option                | Type                              | Default                          | What it does                                                                     |
+| --------------------- | --------------------------------- | -------------------------------- | -------------------------------------------------------------------------------- |
+| `locales`             | `string[]`                        | `["en"]`                         | Every locale the app ships, including the source locale.                         |
+| `sourceLocale`        | `string`                          | `"en"`                           | The locale your source is written in. Never written to disk (Ghost Mode).        |
+| `outputDir`           | `string`                          | `"./zintl"`                      | Where catalogs are written, relative to the project root.                        |
+| `catalogFormat`       | `string \| (ctx) => string`       | `<path>[.<func>].<locale>.json`  | Catalog file naming. Tokens: `[locale] [path] [dir] [name] [func] [bId] [hash]`. |
+| `facets`              | `FacetsInput[]`                   | `["auto"]`                       | Which capabilities the compiler is built with. `"auto"` detects your framework.  |
+| `assetsTarget`        | `(string \| AssetTargetConfig)[]` | `["md", "txt"]`                  | Static content files to localize alongside code.                                 |
+| `virtualAssets`       | `boolean`                         | `false`                          | Serve localized assets from virtual modules instead of writing them to disk.     |
+| `prune`               | `boolean`                         | `true`                           | Remove catalog keys once no source string produces them.                         |
+| `debug`               | `boolean \| string`               | `false`                          | Verbose tracing. A string filters to one subsystem.                              |
+| `logLevel`            | `LogLevel`                        | Vite's `logLevel`, then `"info"` | How much Zintl prints.                                                           |
+| `similarityThreshold` | `number`                          | `0.6`                            | How similar an edited string must be to keep its translation.                    |
+| `verifyIntegrity`     | `boolean`                         | `true` on build, `false` on dev  | Verify catalogs against the manifest and repair drift.                           |
+| `multiplex`           | `boolean`                         | auto-detected                    | Build each locale as its own set of HTML entries.                                |
+| `metadataDir`         | `string`                          | `<root>/node_modules/.zintl`     | Where the compiler keeps its own bookkeeping.                                    |
+
+### 3. Initialize in Source Code
+
+Establish a **Trust Anchor** in your application entry point. Every file or function calling `zintl()` forms an independent translation boundary with its own lazy catalog loading:
+
+```typescript
+// src/main.ts
+import { zintl } from "zintljs/macro";
+
+async function initApp() {
+  const userLang = new URLSearchParams(window.location.search).get("lang") || "en";
+
+  // Sets the active locale and loads necessary catalog chunks
+  await zintl(userLang);
+
+  document.querySelector("#app")!.innerHTML = `
+    <h1>Welcome back!</h1>
+    <p>You have successfully logged in.</p>
+  `;
+}
+
+initApp();
+```
+
+---
+
+## The Comment Directive System
+
+Use comments directly in your source code (JavaScript `//`, `/* */` or HTML `<!-- -->`) to guide the compiler surgically:
+
+### `@zintl-ignore`
+
+Suppresses translation extraction for the immediate next node or HTML tag and its nested subtree:
+
+```jsx
+<div>
+  {/* @zintl-ignore */}
+  <span>This text will not be extracted</span>
+  <span>This text will be extracted</span>
+</div>
+```
+
+### `@zintl-note`
+
+Attaches translator notes that are automatically injected into the generated translation schema:
+
+```typescript
+// @zintl-note Welcome message on the user's dashboard
+const welcomeMsg = `Hello, user!`;
+```
+
+### `@zintl-pass`
+
+Binds invisible grammatical context variables (like gender, role, or counts) to the extraction scope. This allows target languages to use advanced grammatical logic (e.g., ICU Plurals or Select) even if they aren't visible in the source English text:
+
+```typescript
+// @zintl-pass role={user.role}
+const dashboardTitle = `Welcome to your dashboard!`;
+```
+
+---
+
+## The ZCU (Component-based ICU) Agreement
+
+Zintl implements a **Source Purity** philosophy. Developers do not write complex grammatical logic inside their source code. Instead, source files contain simple template literals, and grammatical variations are managed as catalog data:
+
+1. **Source Code:** Write clean, standard JS template literals:
+   ```typescript
+   const msg = `You have ${count} items in your cart`;
+   ```
+2. **Target Translation Catalog (`locales/ar.json`):** Translators write standard ICU MessageFormat syntax inside the JSON files, backed by IDE auto-complete schemas:
+   ```json
+   {
+     "$schema": "./.schemas/locales.schema.json",
+     "You have {count} items in your cart": "{count, plural, =0 {سلتك فارغة} one {لديك عنصر واحد في سلتك} other {لديك {count} عناصر في سلتك}}"
+   }
+   ```
+3. **Compilation:** At build time, the Zintl compiler parses the ICU syntax and compiles ("bakes") it into optimized JavaScript conditional logic:
+   ```javascript
+   // Compiled output (Smart Manager)
+   (params) => {
+     const { count } = params;
+     if (count === 0) return `سلتك فارغة`;
+     if (count === 1) return `لديك عنصر واحد في سلتك`;
+     return `لديك ${count} عناصر في سلتك`;
+   };
+   ```
+
+---
+
+## Packages
+
+| Package                                        | Version                                                                                                                   | Description                                              |
+| :--------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------ | :------------------------------------------------------- |
+| [**`zintl`**](packages/zintl)                  | [![version](https://img.shields.io/npm/v/zintljs.svg?color=863bff&label=%20)](packages/zintl/CHANGELOG.md)                | Vite plugin & macro runtime library.                     |
+| [**`@zintljs/compiler`**](packages/compiler)   | [![version](https://img.shields.io/npm/v/@zintljs/compiler.svg?color=863bff&label=%20)](packages/compiler/CHANGELOG.md)   | Graph management, HTML projection & ICU baking compiler. |
+| [**`@zintljs/extractor`**](packages/extractor) | [![version](https://img.shields.io/npm/v/@zintljs/extractor.svg?color=863bff&label=%20)](packages/extractor/CHANGELOG.md) | AST-based string & dependency extraction utility.        |
+
+---
+
+## Contributing
+
+Contributions are welcome! Please read the [Contributing Guide](CONTRIBUTING.md) to learn about the monorepo setup, development commands, and codebase guidelines.
+
+## License
+
+[MIT](LICENSE).
+
+---
+
+## What's genuinely brilliant
+
+**The Boundary Graph is a paradigm shift.** Most i18n systems are flat dictionaries. Zintl treats translations as a _dependency graph problem_ — the same mental model bundlers use for code splitting. The idea that "a file with a `zintl()` call becomes a trust anchor, and only strings reachable from that anchor need to be translated" is deeply correct and eliminates an entire class of bloat that ships in every other i18n library.
+
+**Ghost Mode (Zero-Disk Source Locale) is elegant.** Generating `{ "key": "key" }` for English is genuinely redundant — the AST already has the strings. Virtualizing the source locale from the extraction manifest instead of materializing it to disk is the kind of insight that only comes from thinking about the problem correctly from first principles.
+
+**The Intelligent Stitching engine** — treating template literals, JSX fragments, and HTML strings as _logical units_ rather than raw strings — is what separates Zintl from simple `i18next.t()` wrappers. Most systems make you manually wrap every string. Zintl reads intent from structure.
+
+**Hive (translation memory) with fuzzy recovery** is seriously underrated. The idea that a minor edit to a source string should forward-port the existing translation (with a warning) instead of wiping it is exactly how professional translators think. Most tools just orphan translations on source changes.
+
+---
+
+## Where I see real risk
+
+**The phantom boundary class of bugs is a structural vulnerability.** The aggressive extraction heuristic (`/zintl|loadI18nInstance|t\(|<|innerHTML/.test(ctx.code)`) runs on every file before the graph is built. The fix we applied today — gating at `verifyIntegrity` and `syncSingleAsset` — is correct, but it means phantom extractions _exist silently in the manifest_ even when they're eventually blocked from writing. In a large project with many non-anchored files, this is unneeded memory and CPU pressure on every build. The longer-term fix would be to not extract at all when there are no entries — but that requires knowing the graph before extracting, which is a chicken-and-egg problem with the current sequential pipeline.
+
+**The `resolve.ts` hook is doing too much.** That file is 636 lines handling multiplexing, asset registration, SFC proxy files, HTML fanning, virtual module resolution, AND the translation-neutrality traversal. It's a load-bearing monolith. Any new framework (vinext, Nuxt, Astro) that has a slightly different module resolution model will cause subtle bugs here. Each concern deserves its own hook.
+
+**The "special cases" are accumulating.** HTML projections, SSR boundaries, HTML fanning, zero-config mode, zintl markers vs. macros vs. anchors — each is individually justified, but the interaction surface is growing. The test suite is the only thing holding this together right now, and there are already 5 skipped tests.
+
+---
+
+## The meta-observation
+
+Zintl is solving the _right_ problem — most i18n tools treat internationalization as a runtime lookup problem, when it's actually a **compilation and bundling problem**. The strings that need to be translated are known at build time. The code-splitting boundary that determines which strings load when is known at build time. Zintl is the only system I know of that treats both of these facts seriously.
+
+The risk is that the implementation complexity is approaching the complexity of the problem it's solving. That's usually a sign that the abstraction layer needs a checkpoint — either a stricter API surface (fewer escape hatches), or a cleaner separation between the extractor (which should be dumb and greedy), the compiler (which should be the authority on what's "real"), and the runtime (which should be minimal and trust the compiler completely).
+
+The bones are exceptional. The muscle needs careful discipline as the feature surface grows.

package/dist/assemble-DJKgHgSM.mjs

@@ -0,0 +1,348 @@
+import { compileExtractionState } from "@zintljs/compiler";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { assetsFacet, clientSpaFacet, htmlFacet, nextjsFacet, reactFacet, ssrFacet, svelteFacet, vanillaFacet, viteFacet, vueFacet } from "@zintljs/compiler/facets";
+//#region src/facets/resolve.ts
+/**
+* Facet resolution — the orchestration layer.
+*
+* This is deliberately part of the *plugin*, not the compiler. Resolution is the
+* act of deciding what the compiler will be, and that decision belongs to the
+* layer that knows about the host toolchain:
+*
+*   extractor  ←  compiler (core)  ←  compiler/facets  ←  zintl (plugin)
+*
+* The compiler receives the output of this function and executes it. It never
+* calls in here, and it has no idea that React, Vue, Svelte, Next, SSR or Vite
+* exist.
+*
+* Merge semantics:
+* - Arrays (targets, extensions, rules, ssr entry targets/exports) union.
+* - Runtime booleans OR together.
+* - Function hooks resolve by highest priority, and a tie is a hard error.
+* - Codegen facets stay a list, matched per-file; two facets claiming the same
+*   extension at the same priority is a hard error.
+*/
+/**
+* Highest-priority-wins for function hooks, with conflict detection on ties.
+*/
+function mergeHook(existing, existingPriority, candidate, candidatePriority, hookName, existingFacetName, candidateFacetName) {
+	if (candidate === void 0) return existing;
+	if (existing === void 0) return candidate;
+	if (candidatePriority > existingPriority) return candidate;
+	if (existingPriority > candidatePriority) return existing;
+	throw new Error(`[Zintl] Facet conflict: both "${existingFacetName}" and "${candidateFacetName}" provide "${hookName}" at the same priority (${existingPriority}). Only one facet may contribute this hook. Increase priority on one, or remove the other.`);
+}
+/**
+* Merge codegen facets with file extension conflict detection.
+*/
+function mergeCodegenFacets(existing, candidate, candidateName) {
+	if (!candidate) return existing;
+	for (const existing_codegen of existing) for (const ext of candidate.extensions) if (existing_codegen.extensions.includes(ext)) {
+		const existingPriority = existing_codegen.priority ?? 0;
+		if (existingPriority === (candidate.priority ?? 0)) throw new Error(`[Zintl] Facet conflict: codegen facets from "${existing_codegen.name}" and "${candidateName}" both claim extension "${ext}" at the same priority (${existingPriority}). Only one codegen facet may handle a given extension at the same priority.`);
+	}
+	return [...existing, candidate];
+}
+function createEmptyState() {
+	return {
+		codegenFacets: [],
+		extractionTargets: [],
+		extensions: [],
+		sfcRules: [],
+		suppressionRules: [],
+		mustacheRules: [],
+		clientReactivityImports: {},
+		contentFacets: [],
+		ssrEntryTargets: [],
+		ssrWrapCode: void 0,
+		ssrWrapCodeProvider: "",
+		ssrWrapCodePriority: -1,
+		ssrWrapExports: [],
+		ssrWrapDefault: void 0,
+		clientLocaleSync: false,
+		serverRequestScope: false,
+		streamInjection: false,
+		detectLocaleChain: [],
+		resolveVirtualPath: void 0,
+		resolveVirtualPathProvider: "",
+		resolveVirtualPathPriority: -1,
+		dynamicImportTemplate: void 0,
+		dynamicImportTemplateProvider: "",
+		dynamicImportTemplatePriority: -1,
+		hmrInjectionCode: void 0,
+		hmrInjectionCodeProvider: "",
+		hmrInjectionCodePriority: -1,
+		getProtectedCatalogKeysChain: []
+	};
+}
+function mergeFacet(state, facet) {
+	const name = facet.name;
+	const priority = facet.priority ?? 0;
+	switch (facet.concern) {
+		case "extraction":
+			for (const t of facet.targets) if (!state.extractionTargets.includes(t)) state.extractionTargets.push(t);
+			for (const e of facet.extensions ?? []) if (!state.extensions.includes(e)) state.extensions.push(e);
+			if (facet.sfcRules) state.sfcRules.push(...facet.sfcRules);
+			if (facet.suppressionRules) state.suppressionRules.push(...facet.suppressionRules);
+			if (facet.mustacheRegex) state.mustacheRules.push({
+				extensions: facet.extensions || [],
+				pattern: facet.mustacheRegex
+			});
+			break;
+		case "content":
+			state.contentFacets.push(facet);
+			if (facet.getProtectedCatalogKeys) state.getProtectedCatalogKeysChain.push(facet.getProtectedCatalogKeys);
+			break;
+		case "codegen":
+			state.codegenFacets = mergeCodegenFacets(state.codegenFacets, facet, name);
+			for (const [source, specifiers] of Object.entries(facet.clientReactivityImports ?? {})) {
+				const existing = state.clientReactivityImports[source] ??= [];
+				for (const spec of specifiers) if (!existing.includes(spec)) existing.push(spec);
+			}
+			for (const e of facet.extensions) if (!state.extensions.includes(e)) state.extensions.push(e);
+			break;
+		case "ssr":
+			if (facet.entryTargets) state.ssrEntryTargets.push(...facet.entryTargets);
+			if (facet.wrapCode !== void 0) {
+				state.ssrWrapCode = mergeHook(state.ssrWrapCode, state.ssrWrapCodePriority, facet.wrapCode, priority, "ssr.wrapCode", state.ssrWrapCodeProvider, name);
+				if (state.ssrWrapCode === facet.wrapCode) {
+					state.ssrWrapCodeProvider = name;
+					state.ssrWrapCodePriority = priority;
+				}
+			}
+			if (facet.wrapExports) state.ssrWrapExports.push(...facet.wrapExports);
+			if (facet.wrapDefault !== void 0 && state.ssrWrapDefault === void 0) state.ssrWrapDefault = facet.wrapDefault;
+			break;
+		case "runtime":
+			if (facet.clientLocaleSync) state.clientLocaleSync = true;
+			if (facet.serverRequestScope) state.serverRequestScope = true;
+			if (facet.streamInjection) state.streamInjection = true;
+			if (facet.detectLocale) state.detectLocaleChain.push(facet.detectLocale);
+			break;
+		case "bundler":
+			if (facet.resolveVirtualPath !== void 0) {
+				state.resolveVirtualPath = mergeHook(state.resolveVirtualPath, state.resolveVirtualPathPriority, facet.resolveVirtualPath, priority, "bundler.resolveVirtualPath", state.resolveVirtualPathProvider, name);
+				if (state.resolveVirtualPath === facet.resolveVirtualPath) {
+					state.resolveVirtualPathProvider = name;
+					state.resolveVirtualPathPriority = priority;
+				}
+			}
+			if (facet.dynamicImportTemplate !== void 0) {
+				state.dynamicImportTemplate = mergeHook(state.dynamicImportTemplate, state.dynamicImportTemplatePriority, facet.dynamicImportTemplate, priority, "bundler.dynamicImportTemplate", state.dynamicImportTemplateProvider, name);
+				if (state.dynamicImportTemplate === facet.dynamicImportTemplate) {
+					state.dynamicImportTemplateProvider = name;
+					state.dynamicImportTemplatePriority = priority;
+				}
+			}
+			if (facet.hmrInjectionCode !== void 0) {
+				state.hmrInjectionCode = mergeHook(state.hmrInjectionCode, state.hmrInjectionCodePriority, facet.hmrInjectionCode, priority, "bundler.hmrInjectionCode", state.hmrInjectionCodeProvider, name);
+				if (state.hmrInjectionCode === facet.hmrInjectionCode) {
+					state.hmrInjectionCodeProvider = name;
+					state.hmrInjectionCodePriority = priority;
+				}
+			}
+			break;
+	}
+}
+function stateToCapabilities(state) {
+	return {
+		jsx: state.codegenFacets.some((a) => a.wrapJsxRichText !== void 0 || a.serializeTags !== void 0),
+		sfc: state.codegenFacets.some((a) => a.wrapSfcScript !== void 0),
+		jsxRichText: state.codegenFacets.some((a) => a.wrapJsxRichText !== void 0),
+		clientLocaleSync: state.clientLocaleSync,
+		serverRequestScope: state.serverRequestScope,
+		streaming: state.streamInjection,
+		ssr: state.ssrEntryTargets.length > 0 || state.ssrWrapCode !== void 0 || state.serverRequestScope || state.streamInjection,
+		hmr: state.hmrInjectionCode !== void 0,
+		localeRouting: state.clientLocaleSync || state.serverRequestScope
+	};
+}
+const DEFAULT_RESOLVE_VIRTUAL_PATH = (id) => id;
+const DEFAULT_DYNAMIC_IMPORT_TEMPLATE = (path, _isDev) => `import(${JSON.stringify(path)})`;
+function stateToHooks(state) {
+	const chain = state.detectLocaleChain;
+	const detectLocale = chain.length === 0 ? void 0 : (context) => {
+		for (const fn of chain) {
+			const result = fn(context);
+			if (result !== void 0) return result;
+		}
+	};
+	const virtualBoundaries = [];
+	for (const facet of state.contentFacets) if (facet.virtualBoundaries) virtualBoundaries.push(...facet.virtualBoundaries);
+	const getProtectedCatalogKeysChain = state.getProtectedCatalogKeysChain;
+	const getProtectedCatalogKeys = async (boundaryId, context) => {
+		const allKeys = /* @__PURE__ */ new Set();
+		for (const fn of getProtectedCatalogKeysChain) {
+			const keys = await fn(boundaryId, context);
+			if (keys) for (const k of keys) allKeys.add(k);
+		}
+		return Array.from(allKeys);
+	};
+	return {
+		codegenFacets: state.codegenFacets,
+		extractionTargets: state.extractionTargets,
+		extensions: state.extensions,
+		sfcRules: state.sfcRules,
+		suppressionRules: state.suppressionRules,
+		mustacheRules: state.mustacheRules,
+		clientReactivityImports: state.clientReactivityImports,
+		contentFacets: state.contentFacets,
+		virtualBoundaries,
+		ssrEntryTargets: state.ssrEntryTargets,
+		ssrWrapCode: state.ssrWrapCode,
+		ssrWrapExports: state.ssrWrapExports,
+		ssrWrapDefault: state.ssrWrapDefault,
+		resolveVirtualPath: state.resolveVirtualPath ?? DEFAULT_RESOLVE_VIRTUAL_PATH,
+		dynamicImportTemplate: state.dynamicImportTemplate ?? DEFAULT_DYNAMIC_IMPORT_TEMPLATE,
+		hmrInjectionCode: state.hmrInjectionCode,
+		detectLocale,
+		getProtectedCatalogKeys
+	};
+}
+/**
+* Resolve a flat list of facet objects into the capabilities handed to the compiler.
+*/
+function resolveFacets(facets = []) {
+	const sorted = [...[...facets]].sort((a, b) => {
+		const pA = a.priority ?? 0;
+		return (b.priority ?? 0) - pA;
+	});
+	const uniqueFacets = [];
+	const seen = /* @__PURE__ */ new Set();
+	for (const a of sorted) if (!seen.has(a.name)) {
+		seen.add(a.name);
+		uniqueFacets.push(a);
+	}
+	const state = createEmptyState();
+	for (const facet of uniqueFacets) mergeFacet(state, facet);
+	const flags = stateToCapabilities(state);
+	const system = stateToHooks(state);
+	return {
+		flags,
+		system,
+		facets: uniqueFacets,
+		extraction: compileExtractionState(system)
+	};
+}
+//#endregion
+//#region src/facets/detect.ts
+/**
+* Framework detection.
+*
+* Part of the orchestration layer: deciding *which* facets a project needs is
+* the plugin's job. Neither the compiler nor the extractor may contain this
+* knowledge.
+*/
+/** The framework assumed when detection finds nothing. */
+const FALLBACK_FRAMEWORK = "react";
+/**
+* Detect frameworks from bundler plugin names and the project's package.json.
+*
+* Returns an empty array when nothing matched — callers decide whether to apply
+* {@link FALLBACK_FRAMEWORK}, so the guess stays visible rather than buried.
+*/
+function detectFrameworks({ pluginNames = [], root }) {
+	const frameworks = /* @__PURE__ */ new Set();
+	for (const raw of pluginNames) {
+		if (!raw) continue;
+		const name = raw.toLowerCase();
+		if (name.includes("vue")) frameworks.add("vue");
+		if (name.includes("react")) frameworks.add("react");
+		if (name.includes("svelte")) frameworks.add("svelte");
+		if (name.includes("next") || name.includes("vinext")) frameworks.add("nextjs");
+	}
+	if (root) try {
+		const pkgPath = join(root, "package.json");
+		if (existsSync(pkgPath)) {
+			const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+			const allDeps = {
+				...pkg.dependencies,
+				...pkg.devDependencies,
+				...pkg.peerDependencies
+			};
+			if (allDeps["vue"]) frameworks.add("vue");
+			if (allDeps["react"]) frameworks.add("react");
+			if (allDeps["svelte"] || allDeps["@sveltejs/kit"]) frameworks.add("svelte");
+			if (allDeps["next"] || allDeps["vinext"]) frameworks.add("nextjs");
+		}
+	} catch {}
+	return Array.from(frameworks);
+}
+/** Detect, falling back to {@link FALLBACK_FRAMEWORK} when nothing matched. */
+function detectFrameworksOrFallback(input) {
+	const detected = detectFrameworks(input);
+	return detected.length > 0 ? detected : [FALLBACK_FRAMEWORK];
+}
+//#endregion
+//#region src/facets/assemble.ts
+/**
+* Facet assembly — turning detected frameworks and user input into a flat facet
+* list, ready for resolution.
+*
+* This is the one place that decides which facets a project gets. Every
+* previously-implicit default now lives here, in the open:
+*
+* - the `"auto"` sentinel expands to the detected framework set plus baselines;
+* - `vanillaFacet`, `htmlFacet` and `assetsFacet` are always part of `"auto"`;
+* - `clientSpaFacet` is added unless the project is Next.js;
+* - `ssrFacet` is added for SSR builds that are not Next.js;
+* - `viteFacet` is always appended, and cannot be opted out of.
+*/
+/**
+* The facet set that `"auto"` expands to.
+*/
+function autoFacets(input) {
+	const { frameworks, ssr = false, assetsTarget, virtualAssets } = input;
+	const out = [];
+	for (const f of frameworks) if (f === "vue") out.push(vueFacet());
+	else if (f === "react") out.push(reactFacet());
+	else if (f === "svelte") out.push(svelteFacet());
+	else if (f === "nextjs") out.push(reactFacet(), nextjsFacet());
+	const isNext = frameworks.includes("nextjs");
+	if (ssr && !isNext) out.push(ssrFacet());
+	if (!isNext) out.push(clientSpaFacet());
+	out.push(vanillaFacet(), htmlFacet(), assetsFacet({
+		targets: assetsTarget,
+		virtualAssets
+	}));
+	return out.flat(Infinity);
+}
+/**
+* Flatten user facet input, expanding `"auto"`, thunks and nested arrays.
+*/
+function flattenFacets(inputs, auto) {
+	const result = [];
+	function processInput(input) {
+		if (!input) return;
+		if (input === "auto") {
+			for (const f of auto) processInput(f);
+			return;
+		}
+		if (typeof input === "function") {
+			processInput(input());
+			return;
+		}
+		if (Array.isArray(input)) {
+			for (const item of input) processInput(item);
+			return;
+		}
+		if (typeof input === "object") {
+			result.push(input);
+			return;
+		}
+	}
+	for (const input of inputs) processInput(input);
+	return result;
+}
+/**
+* The complete facet list for a project: user input (with `"auto"` expanded)
+* plus the always-injected Vite bundler facet.
+*/
+function assembleFacets(input) {
+	const facets = flattenFacets(input.facets ?? ["auto"], autoFacets(input));
+	facets.push(viteFacet());
+	return facets;
+}
+//#endregion
+export { detectFrameworks as a, FALLBACK_FRAMEWORK as i, autoFacets as n, detectFrameworksOrFallback as o, flattenFacets as r, resolveFacets as s, assembleFacets as t };