@madojs/mado 0.6.0 → 0.7.0

package/docs/uk/07-llm-pitfalls.md

@@ -27,10 +27,10 @@ count.set(1);
 
 ```ts
 // Ні
-count.value
+count.value;
 
 // Так
-count()
+count();
 ```
 
 ## Нереактивний child binding
@@ -60,7 +60,11 @@ html`<button ?disabled=${loading}>Save</button>`;
 items().map((item) => html`<li>${item.name}</li>`);
 
 // Так
-each(items(), (item) => item.id, (item) => html`<li>${item.name}</li>`);
+each(
+  items(),
+  (item) => item.id,
+  (item) => html`<li>${item.name}</li>`,
+);
 ```
 
 ## Imports
@@ -80,3 +84,60 @@ import "./components/x-card.js";
 
 Custom element name має містити дефіс. `x-*` — демо-конвенція; production може
 мати `app-*`, `crm-*`, `ticket-*`, `admin-*`.
+
+## `host.getAttribute()` у render — не реактивно
+
+```ts
+// Ні: читається один раз, не оновлюється
+component("x-badge", ({ host }) => () => {
+  const variant = host.getAttribute("variant") ?? "default";
+  return html`<span class=${variant}>...</span>`;
+});
+
+// Так: ctx.attr() — реактивний Signal
+component("x-badge", ({ attr }) => {
+  const variant = attr("variant", "default");
+  return () => html`<span class=${() => `badge-${variant()}`}>...</span>`;
+});
+```
+
+## Shadow DOM кнопка і submit форми
+
+`<button type="submit">` всередині Shadow DOM не тригерить submit `<form>` у Light DOM.
+Використовуйте `form.requestSubmit()` у click handler.
+
+```ts
+const handleClick = () => {
+  const form = host.closest("form");
+  if (form && !host.hasAttribute("disabled")) form.requestSubmit();
+};
+```
+
+## `useForm()` + Shadow DOM input
+
+Після ретаргетингу `e.target` — це `<x-input>`, у якого немає `.name`/`.value`.
+Додайте proxy-властивості на host:
+
+```ts
+Object.defineProperty(host, "name", {
+  get: () => host.getAttribute("name") ?? "",
+});
+Object.defineProperty(host, "value", {
+  get: () => host.shadowRoot?.querySelector("input")?.value ?? "",
+});
+```
+
+Детальніше: [`17-shadow-dom-forms.md`](./17-shadow-dom-forms.md).
+
+## Шпаргалка
+
+| React/інше                  | Mado                         |
+| --------------------------- | ---------------------------- |
+| `useState(0)`               | `signal(0)`                  |
+| `useEffect(() => {...})`    | `effect(() => {...})`        |
+| `useMemo(() => x)`          | `computed(() => x)`          |
+| `useQuery(['key'], fn)`     | `resource(() => 'key', fn)`  |
+| `useRouter().push('/')`     | `navigate('/')`              |
+| `class extends HTMLElement` | `component('x-name', setup)` |
+| `host.getAttribute('x')`    | `ctx.attr('x', default)`     |
+| `jsonFetcher()` з auth      | `apiFetcher()`               |

package/docs/uk/17-shadow-dom-forms.md

@@ -0,0 +1,193 @@
+# Shadow DOM + форми
+
+Використання `useForm()` з кастомними input-компонентами у Shadow DOM потребує
+знання двох поведінок на рівні браузера:
+
+1. **Ретаргетинг подій** — події, що спливають із Shadow DOM, мають
+   `e.target`, перенаправлений на host-елемент. `useForm().onInput` читає
+   `e.target.name` та `e.target.value`, але host-елемент `<x-input>`
+   не має цих властивостей нативно.
+
+2. **Асоціація з формою** — `<button type="submit">` всередині Shadow Root
+   НЕ бере участі в алгоритмі form-owner для `<form>` у Light DOM. Клік по ній
+   не тригерить submit форми.
+
+Обидва обмеження — на рівні специфікації, не баги Mado. Але фреймворк надає
+патерни, що роблять їх безболісними.
+
+## Патерн: Proxy-властивості на input-компонентах
+
+Обгортаючи `<input>` у Shadow DOM компонент, експонуйте `name` та `value`
+як DOM-властивості на host, щоб `useForm().onInput` працював після ретаргетингу:
+
+```ts
+import { component, css, html } from "@madojs/mado";
+
+component("x-input", ({ host, attr }) => {
+  const name = attr("name", "");
+  const type = attr("type", "text");
+  const value = attr("value", "");
+
+  // Proxy-властивості для сумісності з useForm().
+  // Після ретаргетингу Shadow DOM e.target з <input> → <x-input>,
+  // useForm читає e.target.name / e.target.value — ці геттери будують міст.
+  Object.defineProperty(host, "name", {
+    get: () => host.getAttribute("name") ?? "",
+    configurable: true,
+  });
+  Object.defineProperty(host, "value", {
+    get: () => host.shadowRoot?.querySelector("input")?.value ?? "",
+    set: (v: string) => {
+      const input = host.shadowRoot?.querySelector("input");
+      if (input) input.value = v;
+    },
+    configurable: true,
+  });
+
+  return () => html`<input name=${name} type=${type} .value=${value} />`;
+});
+```
+
+Подія `input` від внутрішнього `<input>` має `composed: true` за замовчуванням,
+тому вона спливає через межу shadow. Після ретаргетингу `e.target` —
+це `<x-input>`, але тепер у нього є геттери `.name` та `.value` → `useForm`
+працює.
+
+## Патерн: Submit форми з Shadow DOM кнопок
+
+`<button type="submit">` всередині Shadow DOM не може тригерити submit `<form>`
+у Light DOM. Міст через `requestSubmit()`:
+
+```ts
+import { component, css, html } from "@madojs/mado";
+
+component("x-button", ({ host, attr }) => {
+  const disabled = attr("disabled");
+
+  const handleClick = () => {
+    const typeAttr = host.getAttribute("type");
+    if (typeAttr === "button" || typeAttr === "reset") return;
+    const form = host.closest("form");
+    if (form && !host.hasAttribute("disabled")) form.requestSubmit();
+  };
+
+  return () => html`
+    <button ?disabled=${() => disabled() !== ""} @click=${handleClick}>
+      <slot></slot>
+    </button>
+  `;
+});
+```
+
+`host.closest("form")` працює, бо сам host-елемент живе в Light DOM
+(тільки його внутрішні елементи у тіні). `requestSubmit()` тригерить валідацію
+та подію `submit` точно так, ніби користувач клікнув нативну submit-кнопку
+всередині форми.
+
+## Патерн: Реактивні атрибути через ctx.attr()
+
+З версії 0.7 `ctx.attr(name, defaultValue?)` повертає `Signal<string>`,
+який автоматично оновлюється при зміні атрибута на host. Ніякого
+`MutationObserver` бойлерплейту:
+
+```ts
+component("x-badge", ({ attr }) => {
+  const variant = attr("variant", "default"); // Signal<string>
+
+  return () =>
+    html`<span class=${() => `badge badge-${variant()}`}>
+      <slot></slot>
+    </span>`;
+});
+```
+
+Батько може використовувати `?disabled=${() => !form.isValid()}` (boolean атрибут)
+або `.variant=${"danger"}` — компонент перерендерюється реактивно в обох випадках.
+
+## Повний приклад форми
+
+```ts
+import { page, html, useForm, navigate } from "@madojs/mado";
+import "../components/x-input.js";
+import "../components/x-button.js";
+
+export default page({
+  title: "Вхід",
+  view: () => {
+    const form = useForm({
+      email: { required: true, type: "email" },
+      password: { required: true, minLength: 6 },
+    });
+
+    const handleLogin = async (values) => {
+      await api("/auth/login", { method: "POST", json: values });
+      navigate("/admin");
+    };
+
+    return html`
+      <form @submit=${form.onSubmit(handleLogin)}>
+        <x-input
+          name="email"
+          type="email"
+          label="Email"
+          required
+          @input=${form.onInput}
+          @blur=${form.onBlur}
+        ></x-input>
+        ${() =>
+          form.errors().email
+            ? html`<small class="err">${form.errors().email}</small>`
+            : null}
+
+        <x-input
+          name="password"
+          type="password"
+          label="Пароль"
+          required
+          @input=${form.onInput}
+          @blur=${form.onBlur}
+        ></x-input>
+
+        <x-button type="submit" ?disabled=${() => !form.isValid()}>
+          Увійти
+        </x-button>
+      </form>
+    `;
+  },
+});
+```
+
+## Коли використовувати Light DOM
+
+Якщо ваш input-компонент — це просто стилізована обгортка без потреби в
+інкапсуляції, `shadow: false` уникає обох проблем (ретаргетинг та
+form-association):
+
+```ts
+component(
+  "x-field",
+  ({ attr }) => {
+    const label = attr("label", "");
+    return () => html`
+      <label>
+        <span>${label}</span>
+        <slot></slot>
+      </label>
+    `;
+  },
+  { shadow: false },
+);
+```
+
+З Light DOM нативний `<input>` — частина дерева документа, події не
+ретаргетуються, і submit форми працює нативно. Компроміс: стилі не
+інкапсульовані (треба скоупити самостійно).
+
+## Підсумок
+
+| Задача                      | Рішення Shadow DOM                     | Альтернатива Light DOM     |
+| --------------------------- | -------------------------------------- | -------------------------- |
+| `useForm` + кастомний input | Proxy `name`/`value` на host           | Нативний `<input>` у slot  |
+| Submit форми                | `form.requestSubmit()` у click handler | Нативна кнопка працює      |
+| Реактивні атрибути          | `ctx.attr()` → авто-сигнал             | `ctx.attr()` працює скрізь |
+| Інкапсуляція стилів         | Так (автоматично)                      | Ручний `@scope` або BEM    |

package/docs/uk/README.md

@@ -2,22 +2,23 @@
 
 Український комплект документації.
 
-| Розділ | Файл |
-|---|---|
-| Шлях Mado | [00-the-mado-way.md](./00-the-mado-way.md) |
-| Маршрутизація | [01-routing.md](./01-routing.md) |
-| Структура проєкту | [02-project-layout.md](./02-project-layout.md) |
-| Static bake & SEO | [03-static-bake.md](./03-static-bake.md) |
-| Налаштування IDE | [04-ide-setup.md](./04-ide-setup.md) |
-| Чому Mado | [05-why-mado.md](./05-why-mado.md) |
-| Для бекендерів | [06-for-backenders.md](./06-for-backenders.md) |
-| Типові помилки LLM | [07-llm-pitfalls.md](./07-llm-pitfalls.md) |
-| LLM zero-history тест | [08-llm-zero-history-test.md](./08-llm-zero-history-test.md) |
-| Shadow DOM vs Light DOM | [09-shadow-vs-light-dom.md](./09-shadow-vs-light-dom.md) |
-| Архітектура застосунку | [10-app-architecture.md](./10-app-architecture.md) |
-| Layouts | [11-layouts.md](./11-layouts.md) |
-| Auth та API | [12-auth-and-api.md](./12-auth-and-api.md) |
-| Deployment | [13-deployment.md](./13-deployment.md) |
-| Тестування | [14-testing.md](./14-testing.md) |
-| Обробка помилок | [15-error-handling.md](./15-error-handling.md) |
-| Bake cookbook | [16-bake-cookbook.md](./16-bake-cookbook.md) |
+| Розділ                  | Файл                                                         |
+| ----------------------- | ------------------------------------------------------------ |
+| Шлях Mado               | [00-the-mado-way.md](./00-the-mado-way.md)                   |
+| Маршрутизація           | [01-routing.md](./01-routing.md)                             |
+| Структура проєкту       | [02-project-layout.md](./02-project-layout.md)               |
+| Статичний bake & SEO    | [03-static-bake.md](./03-static-bake.md)                     |
+| Налаштування IDE        | [04-ide-setup.md](./04-ide-setup.md)                         |
+| Чому Mado               | [05-why-mado.md](./05-why-mado.md)                           |
+| Для бекендерів          | [06-for-backenders.md](./06-for-backenders.md)               |
+| Типові помилки LLM      | [07-llm-pitfalls.md](./07-llm-pitfalls.md)                   |
+| LLM zero-history тест   | [08-llm-zero-history-test.md](./08-llm-zero-history-test.md) |
+| Shadow DOM vs Light DOM | [09-shadow-vs-light-dom.md](./09-shadow-vs-light-dom.md)     |
+| Архітектура застосунку  | [10-app-architecture.md](./10-app-architecture.md)           |
+| Макети (layouts)        | [11-layouts.md](./11-layouts.md)                             |
+| Auth та API             | [12-auth-and-api.md](./12-auth-and-api.md)                   |
+| Розгортання             | [13-deployment.md](./13-deployment.md)                       |
+| Тестування              | [14-testing.md](./14-testing.md)                             |
+| Обробка помилок         | [15-error-handling.md](./15-error-handling.md)               |
+| Рецепти bake            | [16-bake-cookbook.md](./16-bake-cookbook.md)                 |
+| Shadow DOM + форми      | [17-shadow-dom-forms.md](./17-shadow-dom-forms.md)           |

package/llms.txt

@@ -13,6 +13,7 @@ Mado is a narrowly-focused frontend framework that deliberately avoids React pat
 - **Components are Web Components.** Registered via `component('x-name', setupFn, options)`. Names must include a hyphen (`x-foo`, `my-button`).
 - **Component files register tags as side effects.** The browser does not auto-import files by tag name. If `<x-card>` works, some imported module already ran `customElements.define("x-card", ...)`.
 - **Cleanup via `ctx.onDispose(fn)`** in setup, not via return from effect.
+- **Reactive attributes via `ctx.attr(name, default?)`** — returns a Signal<string> that auto-updates when the attribute changes. No MutationObserver needed.
 
 ## Critical template rules
 
@@ -64,6 +65,53 @@ import {
 } from "@madojs/mado";
 ```
 
+## Component ctx.attr() — reactive attributes
+
+```ts
+component("x-badge", ({ attr }) => {
+  const variant = attr("variant", "default"); // Signal<string>, auto-updates
+  const size = attr("size", "md");
+
+  return () => html`<span class=${() => `badge-${variant()} size-${size()}`}>
+    <slot></slot>
+  </span>`;
+});
+```
+
+No MutationObserver boilerplate. The parent can bind with `?disabled=${...}` or
+plain attribute changes and the component re-renders reactively.
+
+## Shadow DOM + Forms
+
+Custom inputs in Shadow DOM need two things for `useForm()` compatibility:
+
+1. **Proxy properties** — expose `name` and `value` on the host:
+   ```ts
+   Object.defineProperty(host, "name", { get: () => host.getAttribute("name") ?? "" });
+   Object.defineProperty(host, "value", { get: () => host.shadowRoot?.querySelector("input")?.value ?? "" });
+   ```
+
+2. **Form submit bridge** — buttons inside Shadow DOM can't submit Light DOM forms:
+   ```ts
+   @click=${() => { const form = host.closest("form"); if (form) form.requestSubmit(); }}
+   ```
+
+See `docs/en/17-shadow-dom-forms.md` for the full recipe.
+
+## Auth fetcher for resource()
+
+The admin starter provides `apiFetcher<T>()` in `lib/api.ts` for protected endpoints:
+
+```ts
+import { resource } from "@madojs/mado";
+import { apiFetcher } from "../lib/api.js";
+
+const stats = resource(() => "/api/admin/stats", apiFetcher<Stats>());
+```
+
+Unlike `jsonFetcher()`, `apiFetcher()` attaches the Bearer token from memory.
+Use `jsonFetcher()` for public endpoints, `apiFetcher()` for anything behind auth.
+
 ## Canonical "Hello world"
 
 ```ts
@@ -150,6 +198,7 @@ export default page({
 - docs/en/14-testing.md — testing strategy and commands
 - docs/en/15-error-handling.md — route/data/action error boundaries
 - docs/en/16-bake-cookbook.md — static bake recipes and failure modes
+- docs/en/17-shadow-dom-forms.md — Shadow DOM + useForm() patterns (proxy properties, form submit bridge)
 - examples/basic/ — minimal API tour
 - examples/tickets/ — LLM zero-history CRUD validation
 - examples/showcase/ — flagship CRM pressure app (auth, nested routes, forms, mutations)
@@ -170,7 +219,7 @@ export default page({
 
 ## Version
 
-`0.6.0` — pre-1.0 product-surface release. API may still change before 1.0.
+`0.7.0` — pre-1.0 product-surface release. API may still change before 1.0.
 Semver is not guaranteed on minor versions before 1.0.
 
 ## License

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@madojs/mado",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Mado — a small native-web SPA framework with Web Components, signals, tagged-template html, router, resources, and forms. TypeScript-only build, zero runtime dependencies.",
   "type": "module",
   "license": "MIT",
@@ -80,4 +80,4 @@
   "engines": {
     "node": ">=20"
   }
-}
+}

package/scripts/bake.mjs

@@ -41,19 +41,19 @@ const { flags } = parseFlags(process.argv.slice(2));
 const cfg = loadConfig({
   overrides: {
     bake: {
-      entry:    typeof flags.entry    === "string" ? flags.entry    : undefined,
+      entry: typeof flags.entry === "string" ? flags.entry : undefined,
       template: typeof flags.template === "string" ? flags.template : undefined,
-      baseUrl:  typeof flags["base-url"] === "string" ? flags["base-url"] : undefined,
-      outDir:   typeof flags.out      === "string" ? flags.out      : undefined,
+      baseUrl: typeof flags["base-url"] === "string" ? flags["base-url"] : undefined,
+      outDir: typeof flags.out === "string" ? flags.out : undefined,
     },
   },
 });
 
 // Env vars are legacy escape hatches (kept so old CI keeps working).
-const ENTRY     = process.env.ENTRY     ?? resolveProjectPath(cfg, cfg.bake.entry);
-const TEMPLATE  = process.env.TEMPLATE  ?? resolveProjectPath(cfg, cfg.bake.template);
-const BASE_URL  = process.env.BASE_URL  ?? cfg.bake.baseUrl;
-const OUT_DIR   = process.env.OUT_DIR
+const ENTRY = process.env.ENTRY ?? resolveProjectPath(cfg, cfg.bake.entry);
+const TEMPLATE = process.env.TEMPLATE ?? resolveProjectPath(cfg, cfg.bake.template);
+const BASE_URL = process.env.BASE_URL ?? cfg.bake.baseUrl;
+const OUT_DIR = process.env.OUT_DIR
   ?? resolveProjectPath(cfg, cfg.bake.outDir ?? join(cfg.build.out, "baked"));
 
 /** Write message to stderr and exit. Sync write keeps CI/execFile output reliable. */
@@ -85,14 +85,26 @@ let parseHTML;
 try {
   ({ parseHTML } = await import("linkedom"));
 } catch {
-  fatal("[bake] package 'linkedom' is required:  npm i -D linkedom");
+  fatal(
+    "[bake] package 'linkedom' is required.",
+    "[bake] Install it as a dev dependency in this project:",
+    "[bake]   npm i -D linkedom esbuild",
+    "[bake] (esbuild is also required, see next check).",
+    "[bake] These are not bundled into @madojs/mado on purpose: bake is an",
+    "[bake] optional build step and we don't want to add transitive deps to",
+    "[bake] every Mado install.",
+  );
 }
 
 let esbuild;
 try {
   esbuild = await import("esbuild");
 } catch {
-  fatal("[bake] package 'esbuild' is required:  npm i -D esbuild");
+  fatal(
+    "[bake] package 'esbuild' is required.",
+    "[bake] Install it as a dev dependency in this project:",
+    "[bake]   npm i -D esbuild linkedom",
+  );
 }
 
 // ---------- DOM polyfills for Node ----------
@@ -107,21 +119,21 @@ const { window: linkedomWindow } = parseHTML(baseHtml);
 globalThis.window = linkedomWindow;
 globalThis.document = linkedomWindow.document;
 globalThis.location = new URL("http://localhost/");
-globalThis.history = { pushState: () => {}, replaceState: () => {} };
+globalThis.history = { pushState: () => { }, replaceState: () => { } };
 globalThis.customElements = {
-  define: () => {},
+  define: () => { },
   get: () => undefined,
   whenDefined: () => Promise.resolve(),
 };
-globalThis.HTMLElement = linkedomWindow.HTMLElement ?? class {};
+globalThis.HTMLElement = linkedomWindow.HTMLElement ?? class { };
 globalThis.CSSStyleSheet = globalThis.CSSStyleSheet ?? class {
   cssRules = [];
-  replaceSync() {}
+  replaceSync() { }
 };
 globalThis.matchMedia = () => ({
   matches: false,
-  addEventListener: () => {},
-  removeEventListener: () => {},
+  addEventListener: () => { },
+  removeEventListener: () => { },
 });
 if (!globalThis.queueMicrotask) {
   globalThis.queueMicrotask = (fn) => Promise.resolve().then(fn);
@@ -155,7 +167,7 @@ await esbuild.build({
 
 const routesUrl = pathToFileURL(tmpFile).href;
 const routesModule = await import(routesUrl);
-await rm(tmpFile).catch(() => {});
+await rm(tmpFile).catch(() => { });
 const routeApi = routesModule.default;
 
 if (!routeApi) {
@@ -183,13 +195,19 @@ const TEMPLATE_HTML = baseHtml;
 const sitemapEntries = [];
 let total = 0;
 let bakedErrors = 0;
+let bakeablePages = 0;
+const skippedNoBake = [];
 
 for (const [pattern, entry] of Object.entries(manifest)) {
   if (pattern === "*") continue;
 
   const pg = await resolvePage(entry);
   if (!pg) continue;
-  if (!pg.bake) continue;
+  if (!pg.bake) {
+    skippedNoBake.push(pattern);
+    continue;
+  }
+  bakeablePages++;
 
   console.log(`[bake] ${pattern}`);
 
@@ -214,6 +232,12 @@ for (const [pattern, entry] of Object.entries(manifest)) {
     }
     const headMeta = pg.head ? pg.head(params, data) : {};
 
+    // Ensure <title> is always set in baked HTML. page.title is the primary
+    // source (string or function of params); head().title overrides it.
+    if (!headMeta.title && pg.title) {
+      headMeta.title = typeof pg.title === "function" ? pg.title(params) : pg.title;
+    }
+
     const tpl = pg.view({
       params,
       data,
@@ -255,11 +279,11 @@ for (const [pattern, entry] of Object.entries(manifest)) {
 const sitemap = `<?xml version="1.0" encoding="UTF-8"?>
 <urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
 ${sitemapEntries
-  .map(
-    (e) =>
-      `  <url><loc>${escapeXml(e.loc)}</loc><changefreq>${e.changefreq}</changefreq></url>`,
-  )
-  .join("\n")}
+    .map(
+      (e) =>
+        `  <url><loc>${escapeXml(e.loc)}</loc><changefreq>${e.changefreq}</changefreq></url>`,
+    )
+    .join("\n")}
 </urlset>
 `;
 await writeFile(join(OUT_DIR, "sitemap.xml"), sitemap);
@@ -268,6 +292,36 @@ console.log(`[bake] done: ${total} pages + sitemap.xml → ${OUT_DIR}`);
 if (bakedErrors > 0) {
   fatal(`[bake] ${bakedErrors} route(s) failed; see errors above.`);
 }
+// Loud diagnostic when the manifest exists but no page declares `bake`.
+// Previously bake silently produced 0 pages + an empty sitemap and exited
+// 0, which made `mado release` look successful while shipping no static
+// HTML for crawlers. Fail loudly so the user notices.
+if (bakeablePages === 0) {
+  error("");
+  error(
+    `[bake] WARNING: no page in ${ENTRY} declares \`bake: { paths, data }\`.`,
+  );
+  error(
+    `[bake] ${skippedNoBake.length} route(s) skipped: ${skippedNoBake
+      .slice(0, 6)
+      .join(", ")}${skippedNoBake.length > 6 ? ", …" : ""}`,
+  );
+  error("[bake] Add `bake` to at least one page (e.g. your landing route):");
+  error("[bake]   export default page({");
+  error("[bake]     view: …,");
+  error("[bake]     bake: { paths: () => [{}], data: () => ({}) },");
+  error("[bake]   });");
+  error(
+    "[bake] Without bake the build ships only the SPA shell — search engines",
+  );
+  error("[bake] and link previews see an empty <body>.");
+  // Exit non-zero so `mado release` halts and the user is forced to address
+  // it. If you intentionally have an SPA-only deploy, drop `mado bake` from
+  // the release pipeline (or set MADO_BAKE_ALLOW_EMPTY=1).
+  if (process.env.MADO_BAKE_ALLOW_EMPTY !== "1") {
+    process.exit(1);
+  }
+}
 
 // ---------- Helpers ----------
 

package/scripts/bundle.mjs

@@ -25,7 +25,7 @@
 // its biggest example.
 
 import { build } from "esbuild";
-import { readFile, writeFile, mkdir, cp, stat, readdir } from "node:fs/promises";
+import { readFile, writeFile, mkdir, cp, stat, readdir, rm } from "node:fs/promises";
 import { createHash } from "node:crypto";
 import { gzipSync, brotliCompressSync, constants as zlibConst } from "node:zlib";
 import { join, basename, resolve, dirname } from "node:path";
@@ -74,6 +74,29 @@ if (!existsSync(HTML)) {
   process.exit(1);
 }
 
+// Clean stale assets from previous bundles.
+//
+// Without this step, hashed chunks from prior runs (main-<oldhash>.js,
+// chunk-<oldhash>.js) accumulate in ASSETS_DIR. We later list ASSETS_DIR
+// (via readdir below) and emit <link rel="modulepreload"> for every
+// .js file we find — so stale chunks would be preloaded as if they were
+// still part of the app, polluting the production HTML and shipping dead
+// code over the wire. SRI is also only computed for the fresh entry, so
+// stale preloads would lack integrity checks.
+//
+// In app-mode the entire <out>/assets/ folder is owned by the bundler,
+// so wiping it is safe. In repo-mode the historical layout drops assets
+// directly into <out>/ alongside non-bundle artifacts, so we only remove
+// the recognisable hashed files there.
+if (ASSETS_REL) {
+  await rm(ASSETS_DIR, { recursive: true, force: true });
+} else if (existsSync(ASSETS_DIR)) {
+  for (const f of await readdir(ASSETS_DIR)) {
+    if (/^(main|chunk|asset)-[A-Z0-9]+\.(js|css)(\.map|\.gz|\.br)?$/i.test(f)) {
+      await rm(join(ASSETS_DIR, f), { force: true });
+    }
+  }
+}
 await mkdir(ASSETS_DIR, { recursive: true });
 
 console.log(`[bundle] entry:    ${ENTRY}`);