kamansoft · lemyskaman · Jun 20, 2026 · Jun 20, 2026
diff --git a/.marscode/deviceInfo.json b/.marscode/deviceInfo.json
@@ -0,0 +1,3 @@
+{
+  "deviceId": "ce4213f018b569a39c36d114e75a90a6638a3814823583044604aa6aa17d2094"
+}
diff --git a/README.md b/README.md
@@ -270,7 +270,7 @@ Trusted publishing requires the package to already exist on npm, so a maintainer
 
 1. Publish the initial version once to create the package on npm.
 2. Add the **Trusted Publisher** on npmjs.com → package **Settings → Trusted Publisher → GitHub Actions**: user/org `kamansoft`, repo `vite-plugin-flatwave-react`, workflow `release.yml`.
-3. Push the baseline tag `v0.1.0` so semantic-release continues the 0.x line (otherwise the first automated release defaults to `1.0.0`).
+3. Push the baseline tag `v1.0.0` so semantic-release continues the 0.x line (otherwise the first automated release defaults to `1.0.0`).
 
 After that, every merge to `main` releases automatically — no tokens, no manual version edits.
 
@@ -294,6 +294,73 @@ dev-notes/publish-to-npm/scripts/dry-run-release.sh
 
 ---
 
-## License
+## Appendix B – SSG Extensibility (`./ssg`)
 
-MIT © 2026 – Flatwave contributors.
+This section covers the new `./ssg` public API added in this release.
+
+### 13.1 SSG options and capabilities
+
+`SsgOptions` let you replace the built‑in renderer, inject hook phases, and override templates.
+
+```ts
+import { flatwaveContent } from 'vite-plugin-flatwave-react';
+import { DefaultRenderStrategy, RenderPipeline } from './ssg'; // adjust path
+
+flatwaveContent({
+  contentDir: './src/content',
+  locales: ['es', 'pt'],
+  defaultLocale: 'es',
+  ssg: {
+    enabled: true,
+    compileMarkdown: { allowRawHtml: true },
+    strategy: new MyCustomStrategy(),
+    hooks: {
+      beforeRender: [
+        (ctx) => {
+          /* … */ return ctx;
+        },
+      ],
+      transformMarkdown: [(md, ctx) => md.replace(/foo/g, 'bar')],
+    },
+    template: {
+      indexHtml: fs.readFileSync('./custom/layout.html', 'utf-8'),
+    },
+  },
+});
+```
+
+### 13.2 `RenderStrategy` interface
+
+```ts
+import type { RenderContext } from './ssg';
+
+export interface RenderStrategy {
+  render(context: RenderContext): Promise<string>;
+}
+```
+
+`DefaultRenderStrategy` renders a React component with `renderToString`; you can implement async rendering, micro-frontend composition, or server-side data fetching by swapping this implementation.
+
+### 13.3 Hook phases
+
+| Phase               | Signature             | Use case                                |
+| ------------------- | --------------------- | --------------------------------------- |
+| `beforeRender`      | `(ctx) => ctx`        | inject CSP headers, auth tokens, locale |
+| `transformMarkdown` | `(md, ctx) => md`     | preprocess markdown before compilation  |
+| `transformHtml`     | `(html, ctx) => html` | inject analytics, minify, rewrite links |
+| `afterRender`       | `(html, ctx) => void` | side effects (logging, audit events)    |
+| `onError`           | `(err, ctx) => html`  | recover with safe fallback HTML         |
+
+### 13.4 Template overrides
+
+```ts
+ssg: {
+  template: {
+    indexHtml: fs.readFileSync('./my-layout.html', 'utf-8'),
+  },
+}
+```
+
+Setting **only** the files you need keeps the default built‑in templates for the rest.
+
+---
diff --git a/examples/basic-react-site/dist/es/about/index.html b/examples/basic-react-site/dist/es/about/index.html
@@ -14,7 +14,13 @@
   <link rel="alternate" hreflang="pt" href="/pt/about">
 </head>
 <body>
-  <div id="root"></div>
+  <div id="root"><h1>Acerca de</h1>
+<p>Esta página demuestra Markdown válido y frontmatter adicional preservado por el plugin.</p>
+<pre><code class="language-md"># Markdown válido
+</code></pre>
+<hr>
+<p><em>This page was built with <strong>Flatwave SSG 1.0.0</strong>.</em></p></div>
 
+<script>/* flatwave-analytics */console.info('[flatwave] page rendered:', '/es/about', 'locale:', 'es');</script>
 </body>
-</html>
+</html>
diff --git a/examples/basic-react-site/dist/es/index.html b/examples/basic-react-site/dist/es/index.html
@@ -14,7 +14,16 @@
   <link rel="alternate" hreflang="pt" href="/pt/">
 </head>
 <body>
-  <div id="root"></div>
+  <div id="root"><h1>Inicio</h1>
+<p>Este es el sitio de ejemplo para probar el plugin de contenido Flatwave.</p>
+<ul>
+<li>Rutas localizadas.</li>
+<li>Frontmatter flexible.</li>
+<li>Sitemap y robots generados.</li>
+</ul>
+<hr>
+<p><em>This page was built with <strong>Flatwave SSG 1.0.0</strong>.</em></p></div>
 
+<script>/* flatwave-analytics */console.info('[flatwave] page rendered:', '/es/', 'locale:', 'es');</script>
 </body>
-</html>
+</html>
diff --git a/examples/basic-react-site/dist/es/program/index.html b/examples/basic-react-site/dist/es/program/index.html
@@ -14,7 +14,13 @@
   <link rel="alternate" hreflang="pt" href="/pt/program">
 </head>
 <body>
-  <div id="root"></div>
+  <div id="root"><h1>Programa</h1>
+<p>Esta página usa un componente diferente y frontmatter adicional como <code>date</code> y <code>schedule</code>.</p>
+<h2>Horario</h2>
+<p>El horario se conserva en <code>attributes</code> para que el componente lo use.</p>
+<hr>
+<p><em>This page was built with <strong>Flatwave SSG 1.0.0</strong>.</em></p></div>
 
+<script>/* flatwave-analytics */console.info('[flatwave] page rendered:', '/es/program', 'locale:', 'es');</script>
 </body>
-</html>
+</html>
diff --git a/examples/basic-react-site/dist/index.html b/examples/basic-react-site/dist/index.html
@@ -4,7 +4,7 @@
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>Flatwave React Example</title>
-    <script type="module" crossorigin src="/assets/index-CwWY7Za8.js"></script>
+    <script type="module" crossorigin src="/assets/index-DC-Nt68_.js"></script>
     <link rel="stylesheet" crossorigin href="/assets/index-D2TjNoXN.css">
   </head>
   <body>

diff --git a/examples/basic-react-site/dist/pt/about/index.html b/examples/basic-react-site/dist/pt/about/index.html
@@ -14,7 +14,13 @@
   <link rel="alternate" hreflang="pt" href="/pt/about">
 </head>
 <body>
-  <div id="root"></div>
+  <div id="root"><h1>Sobre</h1>
+<p>Esta página demonstra Markdown válido e frontmatter adicional preservado pelo plugin.</p>
+<pre><code class="language-md"># Markdown válido
+</code></pre>
+<hr>
+<p><em>This page was built with <strong>Flatwave SSG 1.0.0</strong>.</em></p></div>
 
+<script>/* flatwave-analytics */console.info('[flatwave] page rendered:', '/pt/about', 'locale:', 'pt');</script>
 </body>
-</html>
+</html>
diff --git a/examples/basic-react-site/dist/pt/index.html b/examples/basic-react-site/dist/pt/index.html
@@ -14,7 +14,16 @@
   <link rel="alternate" hreflang="pt" href="/pt/">
 </head>
 <body>
-  <div id="root"></div>
+  <div id="root"><h1>Início</h1>
+<p>Este é o site de exemplo para testar o plugin de conteúdo Flatwave.</p>
+<ul>
+<li>Rotas localizadas.</li>
+<li>Frontmatter flexível.</li>
+<li>Sitemap e robots gerados.</li>
+</ul>
+<hr>
+<p><em>This page was built with <strong>Flatwave SSG 1.0.0</strong>.</em></p></div>
 
+<script>/* flatwave-analytics */console.info('[flatwave] page rendered:', '/pt/', 'locale:', 'pt');</script>
 </body>
-</html>
+</html>
diff --git a/examples/basic-react-site/dist/pt/program/index.html b/examples/basic-react-site/dist/pt/program/index.html
@@ -14,7 +14,13 @@
   <link rel="alternate" hreflang="pt" href="/pt/program">
 </head>
 <body>
-  <div id="root"></div>
+  <div id="root"><h1>Programa</h1>
+<p>Esta página usa um componente diferente e frontmatter adicional como <code>date</code> e <code>schedule</code>.</p>
+<h2>Horário</h2>
+<p>O horário é preservado em <code>attributes</code> para que o componente o utilize.</p>
+<hr>
+<p><em>This page was built with <strong>Flatwave SSG 1.0.0</strong>.</em></p></div>
 
+<script>/* flatwave-analytics */console.info('[flatwave] page rendered:', '/pt/program', 'locale:', 'pt');</script>
 </body>
-</html>
+</html>
diff --git a/examples/basic-react-site/dist/sitemap.xml b/examples/basic-react-site/dist/sitemap.xml
@@ -1,2 +1,2 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"><url><loc>http://localhost:4173/es/</loc><lastmod>2026-06-17</lastmod><changefreq>weekly</changefreq><priority>0.8</priority></url><url><loc>http://localhost:4173/es/about</loc><lastmod>2026-06-17</lastmod><changefreq>weekly</changefreq><priority>0.8</priority></url><url><loc>http://localhost:4173/es/program</loc><lastmod>2026-06-17</lastmod><changefreq>weekly</changefreq><priority>0.8</priority></url><url><loc>http://localhost:4173/pt/</loc><lastmod>2026-06-17</lastmod><changefreq>weekly</changefreq><priority>0.8</priority></url><url><loc>http://localhost:4173/pt/about</loc><lastmod>2026-06-17</lastmod><changefreq>weekly</changefreq><priority>0.8</priority></url><url><loc>http://localhost:4173/pt/program</loc><lastmod>2026-06-17</lastmod><changefreq>weekly</changefreq><priority>0.8</priority></url></urlset>
+<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"><url><loc>http://localhost:4173/es/</loc><lastmod>2026-06-20</lastmod><changefreq>weekly</changefreq><priority>0.8</priority></url><url><loc>http://localhost:4173/es/about</loc><lastmod>2026-06-20</lastmod><changefreq>weekly</changefreq><priority>0.8</priority></url><url><loc>http://localhost:4173/es/program</loc><lastmod>2026-06-20</lastmod><changefreq>weekly</changefreq><priority>0.8</priority></url><url><loc>http://localhost:4173/pt/</loc><lastmod>2026-06-20</lastmod><changefreq>weekly</changefreq><priority>0.8</priority></url><url><loc>http://localhost:4173/pt/about</loc><lastmod>2026-06-20</lastmod><changefreq>weekly</changefreq><priority>0.8</priority></url><url><loc>http://localhost:4173/pt/program</loc><lastmod>2026-06-20</lastmod><changefreq>weekly</changefreq><priority>0.8</priority></url></urlset>
diff --git a/examples/basic-react-site/package.json b/examples/basic-react-site/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@flatwave/example-basic-react-site",
-  "version": "0.1.0",
+  "version": "1.0.0",
   "private": true,
   "type": "module",
   "scripts": {

diff --git a/examples/basic-react-site/vite.config.ts b/examples/basic-react-site/vite.config.ts
@@ -15,6 +15,20 @@ export default defineConfig({
       sitemap: {
         hostname: 'http://localhost:4173',
       },
+      ssg: {
+        enabled: true,
+        hooks: {
+          // 12.2 — transformMarkdown: append a built-with note to every page body
+          transformMarkdown: async (markdown, _context) => {
+            return markdown + '\n\n---\n\n*This page was built with **Flatwave SSG 1.0.0**.*';
+          },
+          // 12.3 — transformHtml: inject a lightweight analytics beacon before </body>
+          transformHtml: async (html, context) => {
+            const beacon = `<script>/* flatwave-analytics */console.info('[flatwave] page rendered:', '${context.route.path}', 'locale:', '${context.route.locale}');</script>`;
+            return html.replace('</body>', beacon + '\n</body>');
+          },
+        },
+      },
     }),
   ],
   build: {

diff --git a/node_modules/.bin/flatwave-validate b/node_modules/.bin/flatwave-validate