Update package version to 0.0.8, enhance README with a new section on global components, and improve inline Svelte plugin to support global component declarations and better script content injection.

Author: hanielu

README.md

@@ -6,20 +6,19 @@
 
 ## 📖 Table of Contents
 
-- [✨ What it does](https://www.google.com/search?q=%23-what-it-does)
-- [🔧 Installation](https://www.google.com/search?q=%23-installation)
-- [🚀 Usage](https://www.google.com/search?q=%23-usage)
-  - [vite.config.ts / vite.config.js](https://www.google.com/search?q=%23viteconfigts--viteconfigjs)
-  - [Declaring the global tag helper](https://www.google.com/search?q=%23declaring-the-global-tag-helper)
-- [🧩 Named Exports & Snippets](https://www.google.com/search?q=%23-named-exports--snippets)
-  - [Typing Named Exports](https://www.google.com/search?q=%23typing-named-exports)
-- [🧪 Testing Inline & Reactive Components](https://www.google.com/search?q=%23-testing-inline--reactive-components)
-- [🚦 Import Fences](https://www.google.com/search?q=%23-import-fences)
-- [🛠️ API](https://www.google.com/search?q=%23-api)
-  - [`InlineSvelteOptions`](https://www.google.com/search?q=%23inlinesvelteoptions)
-- [🧐 How it works (nutshell)](https://www.google.com/search?q=%23-how-it-works-nutshell)
-- [⚠️ Caveats](https://www.google.com/search?q=%23-caveats)
-- [📝 License](https://www.google.com/search?q=%23-license)
+- [✨ What it does](#-what-it-does)
+- [🔧 Installation](#-installation)
+- [🚀 Usage](#-usage)
+  - [vite.config.ts / vite.config.js](#viteconfigts--viteconfigjs)
+- [🌍 Global Components](#-global-components)
+- [🚦 Import Fences](#-import-fences)
+- [🧩 Named Exports & Snippets](#-named-exports--snippets)
+- [🧪 Testing Inline & Reactive Components](#-testing-inline--reactive-components)
+- [🛠️ API](#️-api)
+  - [`InlineSvelteOptions`](#inlinesvelteoptions)
+- [🧐 How it works (nutshell)](#-how-it-works-nutshell)
+- [⚠️ Caveats](#️-caveats)
+- [📝 License](#-license)
 
 ---
 
@@ -59,6 +58,27 @@ export default defineConfig(({ mode }) => ({
 
 ---
 
+## 🌍 Global Components
+
+You can define components inside a special `/* svelte:globals */` fence to make them automatically available to all other inline components in the same file. This is perfect for defining shared UI elements or mocks without manual imports.
+
+```typescript
+/* svelte:globals
+  // Any component defined here is "global" to this file.
+  const GlobalButton = html`<button on:click>Click Me!</button>`;
+*/
+
+// ✅ GlobalButton is now available here automatically.
+const Page = html`
+  <section>
+    <p>Welcome to the page.</p>
+    <GlobalButton />
+  </section>
+`;
+```
+
+---
+
 ## 🧩 Named Exports & Snippets
 
 Just like regular Svelte files, you can use `<script context="module">` (or `<script module>`) to export values from an inline component. This is especially useful for **Svelte 5 snippets**.
@@ -181,37 +201,37 @@ const Thing1 = html`
 
 ## 🛠️ API
 
-```ts
-inlineSveltePlugin(options?: InlineSvelteOptions): Plugin;
-```
+`inlineSveltePlugin(options?: InlineSvelteOptions): Plugin;`
 
 ### `InlineSvelteOptions`
 
-| option       | type       | default              | description                                                            |
-| :----------- | :--------- | :------------------- | :--------------------------------------------------------------------- |
-| `tags`       | `string[]` | `["html", "svelte"]` | Names of template‑tags that should be treated as inline Svelte markup. |
-| `fenceStart` | `string`   | `/* svelte:imports`  | The comment that _starts_ an import fence.                             |
-| `fenceEnd`   | `string`   | `*/`                 | The comment that _ends_ an import fence.                               |
+| option              | type       | default              | description                                        |
+| :------------------ | :--------- | :------------------- | :------------------------------------------------- |
+| `tags`              | `string[]` | `["html", "svelte"]` | Tag names to be treated as inline Svelte markup.   |
+| `fenceStart`        | `string`   | `/* svelte:imports`  | The comment that starts a standard import fence.   |
+| `globalsFenceStart` | `string`   | `/* svelte:globals`  | The comment that starts a global components fence. |
+| `fenceEnd`          | `string`   | `*/`                 | The comment that ends any fence.                   |
 
 ---
 
 ## 🧐 How it works (nutshell)
 
-1.  **Scan** each user source file (`.js`, `.ts`, `.jsx`, `.tsx`).
-2.  **Match** template literals whose tag name is in `options.tags`.
-3.  **Hash** the template content (including any fenced imports) to create a stable virtual module ID.
-4.  **Replace** the literal with a variable that imports the virtual module. Named exports (like snippets) are merged onto the default component export using `Object.assign`.
-5.  **Compile** the markup with Svelte when Vite requests the virtual module ID.
+The plugin uses a multi-stage process to transform your code:
+
+1.  **Scan for Fences:** The plugin first looks for `/* svelte:globals */` and `/* svelte:imports */` fences to identify shared components and imports.
+2.  **Process Globals:** It compiles any components found inside the `globals` fence.
+3.  **Process Locals:** It then compiles the remaining "local" components, injecting the standard imports and the compiled global components into each one's script scope.
+4.  **Replace Literals:** Finally, it replaces all the original `html\`...\`\` literals in your code with variables that point to the newly created virtual components.
 
-The result behaves just like a normal Svelte component import, so SSR, hydration, and Hot Module Replacement work as expected.
+The result behaves just like a normal Svelte component import.
 
 ---
 
 ## ⚠️ Caveats
 
 - The plugin only transforms your application's source code, ignoring anything inside `node_modules`.
 - The template content must be valid Svelte component markup. Syntax errors will surface during compilation.
-- Because each inline component gets a unique hash, HMR will re‑render the whole component tree containing it. Keep inline components small for best performance.
+- Because each inline component gets a unique hash, HMR will re-render the whole component tree containing it. Keep inline components small for best performance.
 
 ---
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hvniel/vite-plugin-svelte-inline-component",
-  "version": "0.0.7",
+  "version": "0.0.8",
   "license": "MIT",
   "author": "Haniel Ubogu <https://github.com/HanielU>",
   "repository": {

src/lib/plugin/index.ts

@@ -4,30 +4,34 @@ import MagicString from "magic-string";
 import type { Plugin } from "vite";
 
 export interface InlineSvelteOptions {
-  /** Template‑tag names treated as Svelte markup – default `["html", "svelte"]` */
+  /** Template-tag names treated as Svelte markup. Default: `["html", "svelte"]` */
   tags?: string[];
-  /** Comment that *starts* an import fence – default `/* svelte:imports` */
+  /** Comment that *starts* an import fence. Default: `/* svelte:imports` */
   fenceStart?: string;
-  /** Comment that *ends* an import fence – default `*\/` */
+  /** Comment that *ends* an import fence. Default: `*\/` */
   fenceEnd?: string;
+  /** Comment that *starts* a global components fence. Default: `/* svelte:globals` */
+  globalsFenceStart?: string;
 }
 
 /* ───────── helpers ───────── */
 
 const esc = (s: string) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 const isUserSource = (id: string) => !id.includes("/node_modules/") && /\.(c?[tj]sx?)$/.test(id);
 
-/** Inject shared imports without duplicating instance `<script>` blocks */
-function applyImports(markup: string, imports: string): string {
-  if (!imports) return markup;
+/** Injects a string of script content into a Svelte component's markup. */
+function applyScriptContent(markup: string, scriptContent: string): string {
+  if (!scriptContent) return markup;
 
   const scriptRE = /<script(?![^>]*context=["']module["'])[^>]*>/i;
-  const m = scriptRE.exec(markup);
-  if (m) {
-    const idx = m.index + m[0].length;
-    return markup.slice(0, idx) + "\n" + imports + "\n" + markup.slice(idx);
+  const match = scriptRE.exec(markup);
+
+  if (match) {
+    const idx = match.index + match[0].length;
+    return `${markup.slice(0, idx)}\n${scriptContent}\n${markup.slice(idx)}`;
+  } else {
+    return `<script>\n${scriptContent}\n</script>\n${markup}`;
   }
-  return `<script>\n${imports}\n</script>\n` + markup;
 }
 
 /* ───────── plugin ───────── */
@@ -36,68 +40,149 @@ export default function inlineSveltePlugin({
   tags = ["html", "svelte"],
   fenceStart = "/* svelte:imports",
   fenceEnd = "*/",
+  globalsFenceStart = "/* svelte:globals",
 }: InlineSvelteOptions = {}): Plugin {
   const tagGroup = tags.map(esc).join("|");
-  const tplRE = new RegExp(`(?:${tagGroup})\\s*\`([\\s\\S]*?)\``, "g");
-  const fenceRE = new RegExp(`${esc(fenceStart)}([\\s\\S]*?)${esc(fenceEnd)}`, "m");
+  const tplRE = new RegExp(
+    `(?:const|let|var)\\s+([a-zA-Z0-9_$]+)\\s*=\\s*(?:${tagGroup})\\s*\`([\\s\\S]*?)\``,
+    "g"
+  );
+  const importsFenceRE = new RegExp(`${esc(fenceStart)}([\\s\\S]*?)${esc(fenceEnd)}`, "m");
+  const globalsFenceRE = new RegExp(`${esc(globalsFenceStart)}([\\s\\S]*?)${esc(fenceEnd)}`, "m");
 
-  const VIRT = "virtual:inline-svelte/";
-  const RSLV = "\0" + VIRT;
+  const VIRT_PREFIX = "virtual:inline-svelte/";
+  const RSLV_PREFIX = `\0${VIRT_PREFIX}`;
 
-  /** virtualId → full markup (with injected imports) */
   const cache = new Map<string, string>();
 
   return {
-    name: "@hvniel/vite-plugin-svelte-inline-component",
+    name: "@hvniel/vite-plugin-svelte-inline-component-v3",
     enforce: "pre",
 
     transform(code, id) {
-      if (!isUserSource(id)) return;
-
-      /* file‑level shared imports (may be empty) */
-      const imports = (fenceRE.exec(code)?.[1] ?? "").trim();
+      if (!isUserSource(id) || !tags.some(tag => code.includes(tag))) {
+        return;
+      }
 
       const ms = new MagicString(code);
-      const hashToLocal = new Map<string, string>(); // dedupe within THIS pass
-      let edited = false,
-        m: RegExpExecArray | null;
+      let edited = false;
+
+      // === STAGE 1: Process `svelte:imports` fence ===
+      const importsMatch = importsFenceRE.exec(code);
+      const standardImports = (importsMatch?.[1] ?? "").trim();
+
+      // === STAGE 2: Process `svelte:globals` fence ===
+      const globalsMatch = globalsFenceRE.exec(code);
+      // This will hold the full script block (imports + consts) for global components
+      let globalScriptBlock = "";
+      const hashToLocal = new Map<string, string>();
+
+      if (globalsMatch) {
+        const globalsContent = globalsMatch[1];
+        const globalsStartIndex = globalsMatch.index;
+        let match: RegExpExecArray | null;
+
+        tplRE.lastIndex = 0; // Reset regex before scanning fence content
+        while ((match = tplRE.exec(globalsContent))) {
+          const [fullMatch, componentName, rawMarkup] = match;
+
+          const finalMarkup = applyScriptContent(rawMarkup, standardImports);
+          const hash = createHash("sha1").update(finalMarkup).digest("hex").slice(0, 8);
+
+          let local = hashToLocal.get(hash);
+          if (!local) {
+            local = `_Inline_${hash}`;
+            hashToLocal.set(hash, local);
+
+            const virtId = `${VIRT_PREFIX}${hash}.js`;
+            if (!cache.has(virtId)) cache.set(virtId, finalMarkup);
+
+            const ns = `_InlineNS_${hash}`;
+            const importStatement = `import * as ${ns} from '${virtId}';`;
+            const localDefStatement = `const ${local} = Object.assign(${ns}.default, ${ns});`;
+
+            // Prepend the import to the top of the file for resolution
+            ms.prepend(`${importStatement}\n${localDefStatement}\n`);
+
+            // **FIX**: Build a full script block to inject into local components
+            // This includes the necessary import and the const declarations.
+            const aliasStatement = `const ${componentName} = ${local};`;
+            globalScriptBlock += `${importStatement}\n${localDefStatement}\n${aliasStatement}\n`;
+          } else {
+            // If the component was already processed, just add its alias declaration
+            globalScriptBlock += `const ${componentName} = ${local};\n`;
+          }
+
+          ms.overwrite(
+            globalsStartIndex + match.index,
+            globalsStartIndex + match.index + fullMatch.length,
+            `const ${componentName} = ${local};`
+          );
+          edited = true;
+        }
+        ms.remove(globalsStartIndex, globalsStartIndex + globalsMatch[0].length);
+      }
 
-      while ((m = tplRE.exec(code))) {
-        const rawMarkup = m[1];
-        const markup = applyImports(rawMarkup, imports);
-        const hash = createHash("sha1").update(markup).digest("hex").slice(0, 8);
+      // === STAGE 3: Process remaining "local" inline components ===
+      let match: RegExpExecArray | null;
+      tplRE.lastIndex = 0;
+
+      while ((match = tplRE.exec(code))) {
+        if (
+          globalsMatch &&
+          match.index >= globalsMatch.index &&
+          match.index < globalsMatch.index + globalsMatch[0].length
+        ) {
+          continue;
+        }
+
+        const [fullMatch, componentName, rawMarkup] = match;
+
+        // Inject standard imports AND the full script block for global components
+        const scriptToInject = `${standardImports}\n${globalScriptBlock}`;
+        const finalMarkup = applyScriptContent(rawMarkup, scriptToInject);
+
+        const hash = createHash("sha1").update(finalMarkup).digest("hex").slice(0, 8);
 
-        /* reuse the same local var if this hash appears again in the file */
         let local = hashToLocal.get(hash);
         if (!local) {
-          local = `Inline_${hash}`;
+          local = `_Inline_${hash}`;
           hashToLocal.set(hash, local);
 
-          const virt = `${VIRT}${hash}.js`;
-          if (!cache.has(virt)) cache.set(virt, markup);
+          const virtId = `${VIRT_PREFIX}${hash}.js`;
+          if (!cache.has(virtId)) cache.set(virtId, finalMarkup);
 
-          const ns = `__InlineNS_${hash}`;
+          const ns = `_InlineNS_${hash}`;
           ms.prepend(
-            `import * as ${ns} from '${virt}';\n` +
-              `const ${local}=Object.assign(${ns}.default, ${ns});\n`
+            `import * as ${ns} from '${virtId}';\n` +
+              `const ${local} = Object.assign(${ns}.default, ${ns});\n`
           );
         }
 
-        ms.overwrite(m.index, tplRE.lastIndex, local);
+        ms.overwrite(
+          match.index,
+          match.index + fullMatch.length,
+          `const ${componentName} = ${local};`
+        );
         edited = true;
       }
 
-      return edited ? { code: ms.toString(), map: ms.generateMap({ hires: true }) } : null;
+      if (!edited) return null;
+
+      return {
+        code: ms.toString(),
+        map: ms.generateMap({ hires: true }),
+      };
     },
 
     resolveId(id) {
-      return id.startsWith(VIRT) ? RSLV + id.slice(VIRT.length) : undefined;
+      return id.startsWith(VIRT_PREFIX) ? RSLV_PREFIX + id.slice(VIRT_PREFIX.length) : undefined;
     },
 
     load(id) {
-      if (!id.startsWith(RSLV)) return;
+      if (!id.startsWith(RSLV_PREFIX)) return;
 
-      const markup = cache.get(VIRT + id.slice(RSLV.length))!;
+      const markup = cache.get(VIRT_PREFIX + id.slice(RSLV_PREFIX.length))!;
       return compile(markup, {
         generate: "client",
         css: "injected",

src/plugin.svelte.test.ts

@@ -8,6 +8,10 @@ import { page } from "@vitest/browser/context";
 import { MemoryRouter, Routes, Route } from "@hvniel/svelte-router";
 */
 
+/* svelte:globals
+const Frank = html`<h1>Frank</h1>`;
+*/
+
 describe("Inline Svelte Components with sv", () => {
   it("renders a simple component", () => {
     const SimpleComponent = html`<h1>Hello World</h1>`;
@@ -193,4 +197,18 @@ describe("Inline Svelte Components with sv", () => {
       </header>
     `);
   });
+
+  it("supports global components", () => {
+    const Page = html`<div><Frank /></div>`;
+    const renderer = render(Page);
+
+    expect(renderer.container.firstElementChild).toMatchInlineSnapshot(`
+      <div>
+        <h1>
+          Frank
+        </h1>
+        <!---->
+      </div>
+    `);
+  });
 });