@madojs/mado 0.5.0

package/AGENTS.md

@@ -0,0 +1,291 @@
+# Agent rules for Mado
+
+> This file is read by AI agents in IDEs (Cursor, Cline, Copilot, Continue, etc.).
+> Goal: prevent them from generating React-like code where Mado should be used.
+
+## Project at a glance
+
+- **Mado** — SPA framework built on Web Components + signals + tagged-template `html`.
+- No build system (only `tsc`), no runtime dependencies.
+- Small TypeScript core in `src/`; bundled/minified full API is roughly 11 KB gzip.
+
+## HARD RULES — violation = bug
+
+### 1. Templates — tagged template `html\`\`` only
+
+```ts
+// ❌ NO
+const view = <button onClick={fn}>{count}</button>;
+
+// ❌ NO (this is Vue)
+const view = `<button @click="fn">{{ count }}</button>`;
+
+// ✅ YES
+const view = html`<button @click=${fn}>${count}</button>`;
+```
+
+### 2. Reactivity — only via `signal()` / `computed()` / `effect()`
+
+```ts
+// ❌ NO (this is React)
+const [count, setCount] = useState(0);
+useEffect(() => { ... }, [count]);
+
+// ❌ NO (this is Vue/Svelte)
+let count = $state(0);
+const ref = ref(0);
+
+// ✅ YES
+const count = signal(0);
+const doubled = computed(() => count() * 2);
+effect(() => console.log(count()));
+count.set(5);
+count.update(n => n + 1);
+```
+
+**A signal is a getter function**: read as `count()`, not `count.value`.
+
+### 3. Components — Web Components via `component()`
+
+```ts
+// ❌ NO (classes / decorators / Lit-style)
+class MyButton extends HTMLElement { ... }
+@customElement('my-button')
+class MyButton extends LitElement { ... }
+
+// ❌ NO (React-style functional components)
+function Counter() { return <button>...</button>; }
+
+// ✅ YES
+component("x-counter", (ctx) => {
+  const count = signal(0);
+  // setup: return a renderer function
+  return () => html`<button @click=${() => count.update(n => n + 1)}>${count}</button>`;
+});
+```
+
+- The element name **must contain a hyphen** (`x-foo`, `my-btn`, `app-shell`).
+- `setup()` is called once on connect. Inside, we create signals and resources.
+- We return a renderer function — it is called reactively.
+
+### 4. Cleanup — `ctx.onDispose(fn)`
+
+```ts
+// ❌ NO (React)
+useEffect(() => {
+  const id = setInterval(...);
+  return () => clearInterval(id);
+}, []);
+
+// ✅ YES
+component("x-timer", (ctx) => {
+  const id = setInterval(..., 1000);
+  ctx.onDispose(() => clearInterval(id));
+  return () => html`...`;
+});
+```
+
+**`resource()`, `effect()`, and subscriptions inside `setup()` hook into the lifecycle automatically** — no need to write onDispose for them.
+
+### 5. Reactive value in template child position = function
+
+The most common AI mistake:
+
+```ts
+const count = signal(0);
+
+// ❌ NOT REACTIVE — count() is read once
+html`<div>${count() * 2}</div>`
+
+// ✅ REACTIVE — the function will be called when count changes
+html`<div>${() => count() * 2}</div>`
+
+// ✅ ALSO OK — the signal itself is a function, Mado recognizes it
+html`<div>${count}</div>`
+```
+
+**Rule of thumb:** if there is a signal call (with parentheses) inside `${...}`, wrap it in `() => ...`.
+
+### 6. Attribute bindings
+
+```ts
+// string/number → attribute
+html`<a href=${url}>...</a>`
+
+// DOM property (objects, numbers without serialization, .value for input)
+html`<input .value=${user.name}>`
+html`<my-list .items=${arr}>`
+
+// boolean attribute (toggle)
+html`<button ?disabled=${isLoading}>...</button>`
+
+// event
+html`<button @click=${fn}>...</button>`
+```
+
+Common mistake: `disabled=${loading()}` — this attempts to set a **string** attribute `disabled="true"` or `disabled="false"`, which does not work correctly. **Use `?disabled=`.**
+
+### 7. Lists — via `each()`
+
+```ts
+import { each } from "@madojs/mado";
+
+// ❌ Works, but no keyed reconciliation → loses focus on reorder
+html`<ul>${() => items().map(t => html`<li>${t.name}</li>`)}</ul>`
+
+// ✅ Correct: keyed, reuses DOM nodes
+html`<ul>${() => each(items(), t => t.id, t => html`<li>${t.name}</li>`)}</ul>`
+```
+
+### 8. Routing — `routes()` + `page()`
+
+```ts
+// routes.ts — manifest
+import { routes } from "@madojs/mado";
+export default routes({
+  "/": () => import("./pages/home.js"),
+  "/users/:id": () => import("./pages/user.js"),
+  "*": () => import("./pages/not-found.js"),
+});
+
+// page file
+import { page, html } from "@madojs/mado";
+export default page<{ id: string }>({
+  title: ({ id }) => `User ${id}`,
+  view: ({ params }) => html`<x-user data-id=${params.id}></x-user>`,
+});
+```
+
+- Each page is a **separate file** in `pages/` with `export default page({...})`.
+- Import via `() => import("./pages/foo.js")` — this enables code-splitting via ESM.
+- Programmatic navigation: `import { navigate } from "@madojs/mado"; navigate("/users/42")`.
+
+### 9. Data fetching — `resource()` / `mutation()`
+
+```ts
+// ❌ NO (React Query / SWR)
+const { data } = useQuery(['user', id], () => fetch(...));
+
+// ✅ YES
+import { resource, jsonFetcher, mutation, invalidate } from "@madojs/mado";
+
+const user = resource(
+  () => `/api/users/${userId()}`,   // key (reactive — will recreate on change)
+  jsonFetcher<User>(),               // how to load
+  { staleTime: 60_000 },
+);
+// user.data() / user.error() / user.loading() / user.refresh() / user.mutate()
+
+const save = mutation<User, User>(
+  (u) => fetch("/api/users", { method: "POST", body: JSON.stringify(u) }).then(r => r.json()),
+  { invalidates: ["/api/users*"] },  // glob invalidation
+);
+await save.run(newUser);
+```
+
+### 10. Forms — `useForm()`
+
+```ts
+// ❌ NO (Formik / RHF / Yup)
+const { register, handleSubmit } = useForm({ resolver: yupResolver(schema) });
+
+// ✅ YES
+import { useForm } from "@madojs/mado";
+
+const f = useForm({
+  email: { required: true, type: "email" },
+  age:   { required: true, type: "number", min: 18 },
+});
+
+html`
+  <form @submit=${f.onSubmit(async v => { await api.save(v); })}>
+    <input name="email" @input=${f.onInput} @blur=${f.onBlur}>
+    ${() => f.touched().email && f.errors().email
+      ? html`<small>${f.errors().email}</small>` : null}
+    <button ?disabled=${() => !f.isValid() || f.submitting()}>Save</button>
+  </form>
+`;
+```
+
+Custom validation — `validate: (values) => ({ field: 'error message' } | null)`.
+
+### 11. Styles — `css\`\`` + Shadow DOM by default
+
+```ts
+import { component, css, html } from "@madojs/mado";
+
+component("x-card", () => () => html`<div><slot></slot></div>`, {
+  styles: css`
+    :host { display: block; padding: 1rem; }
+    div { background: var(--bg); }
+    ::slotted(h2) { margin: 0; }
+  `,
+});
+
+// Light DOM (without Shadow), global styles:
+component("x-shell", () => () => html`...`, {
+  shadow: false,  // disables Shadow DOM
+  styles: css`x-shell header { ... }`,  // selectors are written as usual
+});
+```
+
+### 12. Context (DI) — `createContext` / `provide` / `inject`
+
+```ts
+import { createContext, provide, inject } from "@madojs/mado";
+
+const ApiCtx = createContext<ApiClient>(defaultApi);
+
+component("x-app", ({ host }) => {
+  provide(host, ApiCtx, new ApiClient(...));
+  return () => html`<x-child></x-child>`;
+});
+
+component("x-child", ({ host }) => {
+  const api = inject(host, ApiCtx);  // signal<ApiClient>
+  return () => html`<div>${() => api().version}</div>`;
+});
+```
+
+## SOFT GUIDELINES — recommended, but not critical
+
+- **TypeScript strict.** Use `noUncheckedIndexedAccess`-aware code (with `!` or a type guard).
+- **Import using `.js`** (not `.ts`) — this is required by ES modules in the browser: `import { foo } from "./bar.js"`.
+- **One file = one responsibility.** Don't put 5 components in one file "because they're all small".
+- **Do not add runtime dependencies** (`npm install` in `dependencies`). This violates the framework's principle.
+- **JSDoc on public functions** is required. Comments explain "why", not "what".
+
+## Project structure
+
+```
+src/
+├── routes.ts         ← route manifest, ONE file
+├── main.ts           ← entry: mount to #app
+├── pages/            ← one page = one file
+├── components/       ← reusable x-* components
+├── layouts/          ← layout for nested routes
+└── lib/              ← API client, contexts, pure logic
+```
+
+## Where to find specific answers
+
+| Question | File |
+|---|---|
+| How does reactivity work? | `src/signal.ts` (283 lines) |
+| How are templates parsed? | `src/html.ts` (1013 lines) |
+| How does the router work? | `src/router.ts` (~530 lines) |
+| How does resource + cache work? | `src/resource.ts` (297 lines) |
+| How do forms work? | `src/forms.ts` (212 lines) |
+| When something goes wrong | `docs/en/07-llm-pitfalls.md` |
+
+## Before committing
+
+```bash
+npm run typecheck   # must pass
+npm run build       # must build without warnings
+npm test            # all tests green
+```
+
+## TL;DR for the agent
+
+> If you are about to generate `useState`, JSX, `class extends HTMLElement`, `useEffect` with a return cleanup, `useForm` with yupResolver, `useQuery` with queryClient — **stop, you are not writing Mado**. Read this file again.

package/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+## 0.5.0
+
+First public release preparation for Mado.
+
+### Added
+
+- `mado init <name>` project creation command.
+- `minimal` and `crud` starters included in the npm package.
+- GitHub CI workflow with typecheck, build, tests, package dry-run and tarball starter smoke.
+- Tag-based release workflow for npm publishing after Trusted Publishing is configured.
+- Manual browser regression workflow.
+- Release notes generator based on Conventional Commit subjects.
+
+### Changed
+
+- Package version is set to `0.5.0`.
+- npm package files include starters, AI-agent docs and changelog.
+
+### Release Notes
+
+- First npm publish is intended to be manual.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 madojs contributors
+
+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,371 @@
+<div align="center">
+  <img
+    src="./docs/assets/brand/mado-logo-light.png"
+    alt="MadoJS"
+    width="560"
+  />
+
+  <p>
+    <strong>A small native-web SPA framework you can read in an evening.</strong>
+  </p>
+
+  <p>
+    <code>tsc → browser</code> · Zero runtime dependencies · No required bundler
+  </p>
+</div>
+
+
+# Mado
+
+> A small native-web SPA framework you can read in an evening.
+
+Mado is a thin TypeScript framework on top of the browser platform: Web
+Components, signals, tagged-template `html`, a router, resources, forms,
+context, persisted state and static prerender. No runtime dependencies, no
+required bundler, no hidden build pipeline: `tsc → browser`.
+
+Mado (`窓`) means “window” in Japanese: a calm native-web window into an app,
+without dragging a whole frontend factory into the room.
+
+```txt
+Runtime budget after build:
+  native ESM graph: ~60 KB raw, ~24 KB gzip across separate modules
+  bundled/minified full API: ~32 KB raw, ~11 KB gzip, ~10 KB brotli
+Runtime dependencies: 0
+Required dev dependency: typescript
+```
+
+## Who It Is For
+
+- Backend developers who need admin panels, dashboards or internal tools
+  without learning another build stack first.
+- Frontend developers who like the browser platform and want a compact,
+  readable tool instead of a large ecosystem contract.
+- Small teams that value ownership: if something breaks, `src/` is small
+  enough to inspect and patch.
+- Landing pages, widgets, embedded tools and CRUD-heavy SPA surfaces where
+  predictable code matters more than framework fashion.
+
+## Who It Is Not For
+
+- Beginners learning frontend for the first time. React, Vue and Svelte have
+  far larger learning ecosystems.
+- Teams that need a ready-made UI-kit ecosystem comparable to React.
+- Products that require SSR with hydration as a hard requirement.
+- Projects that need a mature plugin marketplace today.
+- Teams that are uncomfortable using a pre-v1 framework.
+
+## Why Not Lit, Solid Or htmx?
+
+Short honest version:
+
+- **Lit** is better for design systems and reusable components that must live
+  inside many host frameworks. Mado is for whole apps: router, data, forms and
+  SEO tools in one small package.
+- **Solid** is faster and more mature. It also expects a JSX transform and a
+  build pipeline. Mado intentionally works with browser ESM and `tsc`.
+- **htmx** is excellent when your backend wants to own HTML fragments. Mado is
+  for cases where you still want an SPA: local state, optimistic updates,
+  cached resources, query params, lazy modules and persisted UI state.
+
+Mado does not try to win synthetic benchmark marketing. It avoids a Virtual DOM,
+uses fine-grained signals and keyed DOM reconciliation, and aims to stay fast
+enough for serious admin apps while remaining small and readable.
+
+## Quick Start
+
+### Start a new app
+
+```bash
+npm exec --package @madojs/mado@latest -- mado init my-app
+cd my-app
+npm install
+npm run build
+npm run serve
+```
+
+Use the CRUD starter when you want a compact admin-style example with
+`resource()`, `mutation()`, `useForm()`, `each()` and `queryParam()`:
+
+```bash
+npm exec --package @madojs/mado@latest -- mado init my-app --starter crud
+```
+
+### Try the repository examples
+
+```bash
+git clone https://github.com/madojs/mado.git
+cd mado
+npm install
+npm run build
+npm run serve -- basic
+```
+
+### Small component example
+
+```ts
+// src/pages/counter.ts
+import { component, css, html, page, signal } from "@madojs/mado";
+
+component(
+  "x-counter",
+  () => {
+    const count = signal(0);
+    return () => html`
+      <button @click=${() => count.update((n) => n + 1)}>${count}</button>
+    `;
+  },
+  { styles: css`button { padding: .5rem 1rem; }` },
+);
+
+export default page({
+  title: "Counter",
+  view: () => html`<x-counter></x-counter>`,
+});
+```
+
+```ts
+// src/routes.ts
+import { routes } from "@madojs/mado";
+
+export const manifest = {
+  "/": () => import("./pages/counter.js"),
+  "*": () => import("./pages/not-found.js"),
+};
+
+export default routes(manifest);
+```
+
+The developer convenience CLI is available as `mado`:
+
+```bash
+mado init my-app
+mado init my-app --starter crud
+mado build
+mado typecheck
+mado test
+mado serve basic
+mado dev showcase
+mado examples
+```
+
+The CLI is useful before v1, but its command polish may still change.
+
+## Documentation
+
+- [Language index](./docs/README.md)
+- [English docs](./docs/en/README.md)
+- [Russian docs](./docs/ru/README.md)
+- [Documentation française](./docs/fr/README.md)
+- [Ukrainian docs](./docs/uk/README.md)
+
+Core topics:
+
+- [The Mado way](./docs/en/00-the-mado-way.md)
+- [Routing](./docs/en/01-routing.md)
+- [Project layout](./docs/en/02-project-layout.md)
+- [Static bake & SEO](./docs/en/03-static-bake.md)
+- [IDE setup](./docs/en/04-ide-setup.md)
+- [Why Mado](./docs/en/05-why-mado.md)
+- [For backenders](./docs/en/06-for-backenders.md)
+- [LLM pitfalls](./docs/en/07-llm-pitfalls.md)
+- [Shadow DOM vs Light DOM](./docs/en/09-shadow-vs-light-dom.md)
+
+AI-agent entrypoints:
+
+- [AGENTS.md](./AGENTS.md)
+- [llms.txt](./llms.txt)
+
+## Examples
+
+- [`examples/basic`](./examples/basic/) — minimal API tour.
+- [`examples/tickets`](./examples/tickets/) — LLM zero-history CRUD validation.
+- [`examples/showcase`](./examples/showcase/) — flagship SaaS CRM pressure app.
+- [`examples/cloudflare`](./examples/cloudflare/) — edge prerender / deployment PoC.
+
+## Core API
+
+### Signals
+
+```ts
+import { batch, computed, effect, flushSync, signal } from "@madojs/mado";
+
+const count = signal(0);
+const doubled = computed(() => count() * 2);
+
+effect(() => console.log(count()));
+
+batch(() => {
+  count.set(1);
+  count.set(2);
+});
+
+flushSync();
+```
+
+Signals are getter functions: read with `count()`, write with `count.set(next)`
+or `count.update(fn)`.
+
+### Templates
+
+```ts
+html`<button @click=${fn} ?disabled=${loading} class=${className}>${label}</button>`;
+```
+
+- Child bindings accept text, nodes, arrays, nested `html```, and `each(...)`.
+- `attr=${v}` writes an attribute.
+- `@event=${fn}` attaches an event listener.
+- `.prop=${v}` writes a DOM property.
+- `?attr=${flag}` toggles a boolean attribute.
+- Function values, including signals and computed values, are tracked
+  reactively.
+
+### Components
+
+```ts
+import { component, css, html } from "@madojs/mado";
+
+component(
+  "x-card",
+  () => () => html`<section><slot></slot></section>`,
+  {
+    styles: css`
+      :host { display: block; }
+      section { padding: 1rem; border: 1px solid var(--border); }
+    `,
+  },
+);
+```
+
+Components are Custom Elements. Shadow DOM is enabled by default. Use
+`{ shadow: false }` for app shells and admin layouts that should inherit global
+utility classes.
+
+### Lists
+
+```ts
+import { each } from "@madojs/mado";
+
+html`
+  <ul>
+    ${() => each(items(), (item) => item.id, (item) => html`<li>${item.name}</li>`)}
+  </ul>
+`;
+```
+
+`each()` performs keyed reconciliation and reuses DOM nodes across reorder,
+insert and delete operations.
+
+### Routing
+
+```ts
+import { routes } from "@madojs/mado";
+
+export const manifest = {
+  "/": () => import("./pages/home.js"),
+  "/users/:id": () => import("./pages/user-detail.js"),
+  "*": () => import("./pages/not-found.js"),
+};
+
+export default routes(manifest);
+```
+
+The router provides lazy page loading, nested routes, query params, hover
+prefetch, async stale guards, loading delay, View Transitions support and
+`dispose()` for tests/dev overlays.
+
+### Data
+
+```ts
+import { invalidate, jsonFetcher, mutation, resource } from "@madojs/mado";
+
+const user = resource(
+  () => `/api/users/${userId()}`,
+  jsonFetcher<User>(),
+  { staleTime: 60_000 },
+);
+
+const save = mutation(api.saveUser, {
+  invalidates: ["/api/users*"],
+});
+
+await save.run(values);
+invalidate("/api/users*");
+```
+
+`resource()` handles cache, loading/error state, aborts, refresh and optimistic
+local `mutate()`. Inside `component()` setup it is lifecycle-aware.
+
+### Forms
+
+```ts
+import { html, useForm } from "@madojs/mado";
+
+const form = useForm({
+  email: { required: true, type: "email" },
+  age: { type: "number", min: 18 },
+});
+
+html`
+  <form @submit=${form.onSubmit(async (values) => api.save(values))}>
+    <input name="email" @input=${form.onInput} @blur=${form.onBlur}>
+    <button ?disabled=${() => !form.isValid() || form.submitting()}>Save</button>
+  </form>
+`;
+```
+
+Validation is based on native HTML constraint validation plus optional custom
+`validate(values)`.
+
+## Static HTML Without Hydration
+
+Mado intentionally does not ship SSR with hydration. For SEO-oriented pages it
+offers `bake`: build-time prerender of finite routes into HTML with meta tags,
+JSON-LD and baked data. For very large or changing catalogs, see the
+Cloudflare Worker edge-prerender PoC in [`examples/cloudflare`](./examples/cloudflare/).
+
+## Production Bundle
+
+Native ESM is the default development and demo path. When a bundled production
+artifact is useful, run:
+
+```bash
+npm run bundle
+npm run preview
+```
+
+`bundle` uses optional `esbuild` for code splitting, SRI, `.gz` and `.br`
+outputs. `preview` emulates the provided `nginx.conf` with `node:http`.
+
+## Tests
+
+```bash
+npm run typecheck
+npm run build
+npm test
+npm run test:browser
+```
+
+The test suite covers signals, computed values, effects, dynamic dependencies,
+the html parser, keyed reconciliation, resources, mutations, forms, router
+isolation, component lifecycle and example smoke tests.
+
+## Known Limits
+
+| Limit | Meaning |
+|---|---|
+| No SSR hydration | Use `bake` or edge prerender for SEO. Per-user server rendering is intentionally out of scope for now. |
+| Small ecosystem | No plugin marketplace or UI-kit ecosystem comparable to React. |
+| Template IDE support needs plugins | `html`` syntax highlighting/type tooling usually needs lit-plugin or similar tooling. |
+| Evergreen browsers | Targets modern Chrome/Edge/Firefox/Safari. Legacy browsers are out of scope. |
+| Pre-v1 API | Public API is intentionally small, but v0.x may still change before v1. |
+
+## Contributing
+
+Read [CONTRIBUTING.md](./CONTRIBUTING.md). The short version: bug fixes with
+tests, docs improvements, examples and carefully discussed small core changes
+are welcome. Runtime dependencies are not.
+
+## License
+
+MIT.