@madojs/mado 0.5.0

package/ROADMAP.md

@@ -0,0 +1,52 @@
+# Roadmap
+
+Mado is pre-v1. The goal is not to grow sideways, but to keep the runtime small,
+readable and reliable under real application pressure.
+
+## Current Focus
+
+- Keep the public runtime API small: `html`, `component`, `routes`, `resource`,
+  `mutation`, `useForm`, `each`, `createContext`, `persisted`, `lazy`.
+- Use real apps and examples as pressure tests before adding primitives.
+- Keep runtime dependencies at zero.
+- Keep English as the public/default project language, with localized docs in
+  `docs/ru`, `docs/fr` and `docs/uk`.
+
+## Before v1
+
+- Browser compatibility pass across current Chrome, Edge, Firefox and Safari.
+- Accessibility pass for examples and common component patterns.
+- Public API audit: names, warnings, lifecycle rules, docs coverage.
+- Release hygiene: npm provenance, GitHub repo metadata, tags and changelog.
+- Size reporting command or CI summary with ESM and bundled/minified budgets.
+- Real commercial app test: validate auth, forms, tables, resources, route
+  transitions and long-lived sessions outside toy examples.
+
+## Explicitly Out Of Scope For Now
+
+- Runtime dependencies.
+- UI kit / component library.
+- SSR with hydration.
+- Large props API.
+- Framework-specific build tool.
+- Plugin ecosystem before the core is stable.
+
+## Release History
+
+| Date | Milestone | Notes |
+|---|---|---|
+| 2026-06-03 | Core stabilization | Parser rewritten as a state machine; keyed `each()` reconciliation; lifecycle-aware `resource()`; router isolation; lazy `computed()`; regression tests added. |
+| 2026-06-03 | Documentation foundation | Honest README, routing docs, static bake docs, IDE setup, “Why Mado”, backend mental model and LLM pitfalls. |
+| 2026-06-03 | Publish readiness | Package metadata, exports, MIT license, contributing guide, GitHub templates and CI scaffolding. |
+| 2026-06-03 | Cloudflare prerender PoC | Edge prerender example for SEO without SSR hydration. |
+| 2026-06-03 | AI-ready files | `AGENTS.md`, `llms.txt`, Copilot instructions and LLM-specific pitfalls. |
+| 2026-06-03 | v0.3 hardening | Nested template cleanup, stale async route guard, Shadow DOM link/prefetch tests, scroll behavior, `warnOnce`, component reconnect/style tests. |
+| 2026-06-05 | v0.4 showcase max | `examples/showcase` became a SaaS CRM pressure app with accounts, deals, activity, nested routes, context services and browser regression. |
+| 2026-06-06 | v0.5 project shape | Unified `mado` CLI, dev server logs, docs language skeleton, examples cleanup (`basic`, `tickets`, `showcase`, `cloudflare`). |
+| 2026-06-06 | Mado rebrand | Public package/import name `madojs`, CLI `mado`, brand/docs/examples updated, internal legacy markers cleaned. |
+| 2026-06-06 | Public polish | English public surface, localized docs, translated code comments/examples/templates/GitHub files. |
+
+## Future Ideas
+
+Ideas live in `TODO.md`. They are not commitments until a real app or issue
+proves the need.

package/dist/src/component.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Wrapper around Custom Elements.
+ *
+ *   component('x-counter', () => {
+ *     const count = signal(0);
+ *     return () => html`<button @click=${() => count.update(n=>n+1)}>${count}</button>`;
+ *   }, {
+ *     styles: css`button { padding: .5rem }`,
+ *   });
+ *
+ * The setup function is called once on the first connectedCallback.
+ * The returned render function is called via an effect, so any signals
+ * read inside it automatically re-render the template.
+ *
+ * Shadow DOM (open) is used by default. It can be disabled, and
+ * styles will be scoped via @scope (or a tag-prefix fallback).
+ */
+import { type Disposer } from "./signal.js";
+import { html, type TemplateResult } from "./html.js";
+import { type CSSResult } from "./css.js";
+export interface ComponentContext {
+    host: HTMLElement;
+    /** Run cleanup when the component is removed. */
+    onDispose(fn: Disposer): void;
+}
+export type SetupFn = (ctx: ComponentContext) => () => TemplateResult;
+export type StyleInput = string | CSSResult | Array<string | CSSResult>;
+export interface ComponentOptions {
+    /** Enable Shadow DOM (default: true). */
+    shadow?: boolean;
+    /**
+     * Component styles. Accepts:
+     *   - a CSS string (quick start)
+     *   - a CSSStyleSheet via `css\`...\`` (recommended — one copy in memory)
+     *   - an array of the above
+     */
+    styles?: StyleInput;
+    /**
+     * List of observed attributes.
+     *
+     * v0.3: this is plain reflection into host[attr], without a reactive props API.
+     * If you need to re-render the component when an attribute changes, create a signal()
+     * inside setup() and update it manually from your own wrapper/event.
+     */
+    observedAttributes?: readonly string[];
+}
+export declare function component(tagName: string, setup: SetupFn, options?: ComponentOptions): void;
+export { html };

package/dist/src/component.js

@@ -0,0 +1,140 @@
+/**
+ * Wrapper around Custom Elements.
+ *
+ *   component('x-counter', () => {
+ *     const count = signal(0);
+ *     return () => html`<button @click=${() => count.update(n=>n+1)}>${count}</button>`;
+ *   }, {
+ *     styles: css`button { padding: .5rem }`,
+ *   });
+ *
+ * The setup function is called once on the first connectedCallback.
+ * The returned render function is called via an effect, so any signals
+ * read inside it automatically re-render the template.
+ *
+ * Shadow DOM (open) is used by default. It can be disabled, and
+ * styles will be scoped via @scope (or a tag-prefix fallback).
+ */
+import { effect } from "./signal.js";
+import { html, render } from "./html.js";
+import { adopt, scopeStyles } from "./css.js";
+import { createLifecycle, runInLifecycle } from "./lifecycle.js";
+import { warnOnce } from "./diagnostics.js";
+export function component(tagName, setup, options = {}) {
+    if (!tagName.includes("-")) {
+        warnOnce(`component-invalid-tag-${tagName}`, `component("${tagName}") skipped: Custom Element names must contain a hyphen.`);
+        return;
+    }
+    const existingMeta = registered.get(tagName);
+    if (customElements.get(tagName)) {
+        if (!existingMeta ||
+            existingMeta.setup !== setup ||
+            !sameComponentOptions(existingMeta.options, options)) {
+            warnOnce(`component-duplicate-${tagName}`, `component("${tagName}") is already registered. Re-registration with different setup/options is ignored.`);
+        }
+        return; // idempotent hot-reload
+    }
+    const useShadow = options.shadow !== false;
+    const observed = options.observedAttributes ?? [];
+    // Normalize styles to an array of CSSStyleSheet once.
+    // Sheets are shared across all instances — memory is not duplicated.
+    const stylesheets = normalizeStyles(options.styles, tagName, useShadow);
+    class MadoElement extends HTMLElement {
+        static get observedAttributes() {
+            return [...observed];
+        }
+        #root;
+        #renderer = null;
+        #effectDispose = null;
+        #lifecycle = null;
+        #connected = false;
+        constructor() {
+            super();
+            this.#root = useShadow ? this.attachShadow({ mode: "open" }) : this;
+        }
+        connectedCallback() {
+            if (this.#connected)
+                return;
+            this.#connected = true;
+            if (stylesheets.length > 0) {
+                if (useShadow) {
+                    adopt(this.#root, ...stylesheets);
+                }
+                else {
+                    installGlobalSheets(stylesheets);
+                }
+            }
+            // create a lifecycle for this component. Any function
+            // called from setup() (resource, ...) will see it via
+            // getCurrentLifecycle() and register its own cleanup.
+            const lifecycle = createLifecycle();
+            this.#lifecycle = lifecycle;
+            const ctx = {
+                host: this,
+                // ctx.onDispose proxies to lifecycle — the single source of truth
+                // for component cleanups (including auto-cleanup from
+                // resource(), navigator listeners, etc.).
+                onDispose: (fn) => lifecycle.onDispose(fn),
+            };
+            this.#renderer = runInLifecycle(lifecycle, () => setup(ctx));
+            this.#effectDispose = effect(() => {
+                render(this.#renderer(), this.#root);
+            });
+        }
+        disconnectedCallback() {
+            this.#effectDispose?.();
+            this.#effectDispose = null;
+            this.#lifecycle?.dispose();
+            this.#lifecycle = null;
+            this.#connected = false;
+        }
+        attributeChangedCallback(name, _old, value) {
+            // reflect attribute to property — user can bind a signal to it
+            this[name] = value;
+        }
+    }
+    customElements.define(tagName, MadoElement);
+    registered.set(tagName, { setup, options });
+}
+// ---------- helpers ----------
+function normalizeStyles(input, tagName, useShadow) {
+    if (!input)
+        return [];
+    const arr = Array.isArray(input) ? input : [input];
+    return arr.map((s) => {
+        let sheet;
+        if (typeof s === "string") {
+            sheet = new CSSStyleSheet();
+            sheet.replaceSync(s);
+        }
+        else {
+            sheet = s;
+        }
+        // light DOM: scope by tag name
+        return useShadow ? sheet : scopeStyles(tagName, sheet);
+    });
+}
+const installedGlobal = new WeakSet();
+const registered = new Map();
+function sameComponentOptions(a, b) {
+    if (a.shadow !== b.shadow)
+        return false;
+    if (a.styles !== b.styles)
+        return false;
+    const aa = a.observedAttributes ?? [];
+    const bb = b.observedAttributes ?? [];
+    if (aa.length !== bb.length)
+        return false;
+    return aa.every((name, i) => name === bb[i]);
+}
+function installGlobalSheets(sheets) {
+    const toAdd = sheets.filter((s) => !installedGlobal.has(s));
+    if (toAdd.length === 0)
+        return;
+    for (const s of toAdd)
+        installedGlobal.add(s);
+    document.adoptedStyleSheets = [...document.adoptedStyleSheets, ...toAdd];
+}
+// Convenience re-export.
+export { html };
+//# sourceMappingURL=component.js.map

package/dist/src/component.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"component.js","sourceRoot":"","sources":["../../src/component.ts"],"names":[],"mappings":"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"}

package/dist/src/context.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Context (DI) without props drilling. A native pattern from Lit / Open Web Components.
+ *
+ *   const ThemeCtx = createContext<'light'|'dark'>('light');
+ *
+ *   component('x-app', ({ host }) => {
+ *     provide(host, ThemeCtx, signal('dark'));
+ *     return () => html`<x-child/>`;
+ *   });
+ *
+ *   component('x-child', ({ host }) => {
+ *     const theme = inject(host, ThemeCtx);   // signal: () => 'dark' | 'light'
+ *     return () => html`<div data-theme=${theme}>...</div>`;
+ *   });
+ *
+ * How it works:
+ *   provide() listens for the 'mado:context' event on the host — when a child
+ *   component dispatches it (bubbles), the parent writes the current signal
+ *   into the event detail and calls preventDefault.
+ *   inject() dispatches the event and reads the result.
+ *   This fully conforms to the Web Components Community Context Protocol.
+ */
+import { type Signal } from "./signal.js";
+export interface Context<T> {
+    readonly _ctx: true;
+    readonly key: symbol;
+    readonly defaultValue: T;
+}
+export declare function createContext<T>(defaultValue: T): Context<T>;
+/**
+ * Declare that this host provides a value for the given context.
+ * Returns the signal itself so the provider can update it.
+ */
+export declare function provide<T>(host: HTMLElement, ctx: Context<T>, initial: T | Signal<T>): Signal<T>;
+/**
+ * Request a context value. Walks up the DOM tree (including
+ * Shadow DOM via composed) to the first provider. If not found —
+ * returns the defaultValue wrapped in a signal.
+ */
+export declare function inject<T>(host: HTMLElement, ctx: Context<T>): Signal<T>;

package/dist/src/context.js

@@ -0,0 +1,67 @@
+/**
+ * Context (DI) without props drilling. A native pattern from Lit / Open Web Components.
+ *
+ *   const ThemeCtx = createContext<'light'|'dark'>('light');
+ *
+ *   component('x-app', ({ host }) => {
+ *     provide(host, ThemeCtx, signal('dark'));
+ *     return () => html`<x-child/>`;
+ *   });
+ *
+ *   component('x-child', ({ host }) => {
+ *     const theme = inject(host, ThemeCtx);   // signal: () => 'dark' | 'light'
+ *     return () => html`<div data-theme=${theme}>...</div>`;
+ *   });
+ *
+ * How it works:
+ *   provide() listens for the 'mado:context' event on the host — when a child
+ *   component dispatches it (bubbles), the parent writes the current signal
+ *   into the event detail and calls preventDefault.
+ *   inject() dispatches the event and reads the result.
+ *   This fully conforms to the Web Components Community Context Protocol.
+ */
+import { signal } from "./signal.js";
+const CONTEXT_EVENT = "mado:context";
+export function createContext(defaultValue) {
+    return {
+        _ctx: true,
+        key: Symbol("madoctx"),
+        defaultValue,
+    };
+}
+/**
+ * Declare that this host provides a value for the given context.
+ * Returns the signal itself so the provider can update it.
+ */
+export function provide(host, ctx, initial) {
+    const sig = typeof initial === "function"
+        ? initial
+        : signal(initial);
+    const handler = (e) => {
+        const ce = e;
+        if (ce.detail.key !== ctx.key)
+            return;
+        ce.detail.value = sig;
+        e.stopPropagation();
+    };
+    host.addEventListener(CONTEXT_EVENT, handler);
+    return sig;
+}
+/**
+ * Request a context value. Walks up the DOM tree (including
+ * Shadow DOM via composed) to the first provider. If not found —
+ * returns the defaultValue wrapped in a signal.
+ */
+export function inject(host, ctx) {
+    const detail = { key: ctx.key };
+    host.dispatchEvent(new CustomEvent(CONTEXT_EVENT, {
+        detail,
+        bubbles: true,
+        composed: true,
+        cancelable: true,
+    }));
+    if (detail.value)
+        return detail.value;
+    return signal(ctx.defaultValue);
+}
+//# sourceMappingURL=context.js.map

package/dist/src/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../../src/context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAAE,MAAM,EAAe,MAAM,aAAa,CAAC;AAElD,MAAM,aAAa,GAAG,cAAc,CAAC;AAQrC,MAAM,UAAU,aAAa,CAAI,YAAe;IAC9C,OAAO;QACL,IAAI,EAAE,IAAI;QACV,GAAG,EAAE,MAAM,CAAC,SAAS,CAAC;QACtB,YAAY;KACb,CAAC;AACJ,CAAC;AAOD;;;GAGG;AACH,MAAM,UAAU,OAAO,CACrB,IAAiB,EACjB,GAAe,EACf,OAAsB;IAEtB,MAAM,GAAG,GACP,OAAO,OAAO,KAAK,UAAU;QAC3B,CAAC,CAAE,OAAqB;QACxB,CAAC,CAAC,MAAM,CAAC,OAAY,CAAC,CAAC;IAE3B,MAAM,OAAO,GAAG,CAAC,CAAQ,EAAE,EAAE;QAC3B,MAAM,EAAE,GAAG,CAAoC,CAAC;QAChD,IAAI,EAAE,CAAC,MAAM,CAAC,GAAG,KAAK,GAAG,CAAC,GAAG;YAAE,OAAO;QACtC,EAAE,CAAC,MAAM,CAAC,KAAK,GAAG,GAAsB,CAAC;QACzC,CAAC,CAAC,eAAe,EAAE,CAAC;IACtB,CAAC,CAAC;IACF,IAAI,CAAC,gBAAgB,CAAC,aAAa,EAAE,OAAO,CAAC,CAAC;IAE9C,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,MAAM,CAAI,IAAiB,EAAE,GAAe;IAC1D,MAAM,MAAM,GAAuB,EAAE,GAAG,EAAE,GAAG,CAAC,GAAG,EAAE,CAAC;IACpD,IAAI,CAAC,aAAa,CAChB,IAAI,WAAW,CAAC,aAAa,EAAE;QAC7B,MAAM;QACN,OAAO,EAAE,IAAI;QACb,QAAQ,EAAE,IAAI;QACd,UAAU,EAAE,IAAI;KACjB,CAAC,CACH,CAAC;IACF,IAAI,MAAM,CAAC,KAAK;QAAE,OAAO,MAAM,CAAC,KAAkB,CAAC;IACnD,OAAO,MAAM,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;AAClC,CAAC"}

package/dist/src/css.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Styles without CSS-in-JS, but ergonomic.
+ *
+ * Idea:
+ *   1. `css\`...\`` — tagged literal, returns a CSSStyleSheet (Constructable Stylesheet).
+ *   2. Sheet is shared across all component instances (one copy in memory).
+ *   3. Component applies the sheet via `shadowRoot.adoptedStyleSheets`.
+ *   4. No runtime CSS parsers, no className hashes —
+ *      the browser does all the work.
+ *
+ * Theming:
+ *   - change CSS variables on :host or :root — no re-renders needed.
+ *   - `cssVars({ '--accent': color })` → ready string for style="...".
+ *
+ * Optional scope without Shadow DOM:
+ *   - if the browser has @scope (Chrome 118+, Safari 17.4+), we wrap styles.
+ *   - fallback: prefix selectors with the tag — a simple regex at string level.
+ */
+export type CSSResult = CSSStyleSheet;
+/**
+ * Tagged literal for CSS. Returns a CSSStyleSheet ready for
+ * adoptedStyleSheets. Value interpolation — only primitives or
+ * other CSSResult (for composition).
+ *
+ * Injection guard: strings with `<` or `>` are forbidden so that
+ * script tags cannot accidentally be injected through styles.
+ */
+export declare function css(strings: TemplateStringsArray, ...values: unknown[]): CSSResult;
+/**
+ * Build an inline-style string from a CSS variables object.
+ *
+ *   cssVars({ '--accent': '#f00', '--pad': '1rem' })
+ *     → '--accent: #f00; --pad: 1rem;'
+ *
+ * Usage:
+ *   html`<div style=${cssVars({ '--accent': color })}>...</div>`
+ *   html`<x-app style=${cssVars(theme())}>...</x-app>`   // signal — auto-update
+ */
+export declare function cssVars(vars: Record<string, string | number>): string;
+/**
+ * Apply sheets to a ShadowRoot. Idempotent: the same sheet
+ * can be adopted into dozens of components without duplicating styles.
+ */
+export declare function adopt(root: ShadowRoot, ...sheets: CSSResult[]): void;
+/**
+ * Build scoped style text limited to a selector (for light DOM).
+ * Uses native @scope if the browser supports it.
+ * Otherwise — naive selector prefixing.
+ *
+ *   scopeStyles('x-button', 'button { color: red }')
+ *     → '@scope (x-button) { button { color: red } }'  // or
+ *     → 'x-button button { color: red }'
+ */
+export declare function scopeStyles(tagName: string, sheet: CSSResult): CSSResult;

package/dist/src/css.js

@@ -0,0 +1,137 @@
+/**
+ * Styles without CSS-in-JS, but ergonomic.
+ *
+ * Idea:
+ *   1. `css\`...\`` — tagged literal, returns a CSSStyleSheet (Constructable Stylesheet).
+ *   2. Sheet is shared across all component instances (one copy in memory).
+ *   3. Component applies the sheet via `shadowRoot.adoptedStyleSheets`.
+ *   4. No runtime CSS parsers, no className hashes —
+ *      the browser does all the work.
+ *
+ * Theming:
+ *   - change CSS variables on :host or :root — no re-renders needed.
+ *   - `cssVars({ '--accent': color })` → ready string for style="...".
+ *
+ * Optional scope without Shadow DOM:
+ *   - if the browser has @scope (Chrome 118+, Safari 17.4+), we wrap styles.
+ *   - fallback: prefix selectors with the tag — a simple regex at string level.
+ */
+/**
+ * Tagged literal for CSS. Returns a CSSStyleSheet ready for
+ * adoptedStyleSheets. Value interpolation — only primitives or
+ * other CSSResult (for composition).
+ *
+ * Injection guard: strings with `<` or `>` are forbidden so that
+ * script tags cannot accidentally be injected through styles.
+ */
+export function css(strings, ...values) {
+    let text = "";
+    for (let i = 0; i < strings.length; i++) {
+        text += strings[i];
+        if (i < strings.length - 1) {
+            const v = values[i];
+            if (v == null)
+                continue;
+            if (v instanceof CSSStyleSheet) {
+                // composition — insert all rules
+                for (const rule of v.cssRules)
+                    text += rule.cssText;
+                continue;
+            }
+            const s = String(v);
+            if (/[<>]/.test(s)) {
+                throw new Error("css``: `<` and `>` are forbidden in interpolations");
+            }
+            text += s;
+        }
+    }
+    const sheet = new CSSStyleSheet();
+    sheet.replaceSync(text);
+    return sheet;
+}
+/**
+ * Build an inline-style string from a CSS variables object.
+ *
+ *   cssVars({ '--accent': '#f00', '--pad': '1rem' })
+ *     → '--accent: #f00; --pad: 1rem;'
+ *
+ * Usage:
+ *   html`<div style=${cssVars({ '--accent': color })}>...</div>`
+ *   html`<x-app style=${cssVars(theme())}>...</x-app>`   // signal — auto-update
+ */
+export function cssVars(vars) {
+    let out = "";
+    for (const k in vars) {
+        const v = vars[k];
+        if (v == null)
+            continue;
+        const name = k.startsWith("--") ? k : `--${k}`;
+        out += `${name}:${v};`;
+    }
+    return out;
+}
+/**
+ * Apply sheets to a ShadowRoot. Idempotent: the same sheet
+ * can be adopted into dozens of components without duplicating styles.
+ */
+export function adopt(root, ...sheets) {
+    // append rather than overwrite — user may have already adopted something
+    const existing = root.adoptedStyleSheets;
+    const toAdd = sheets.filter((s) => !existing.includes(s));
+    if (toAdd.length === 0)
+        return;
+    root.adoptedStyleSheets = [...existing, ...toAdd];
+}
+// ---------- Scope for light DOM (without Shadow DOM) ----------
+const hasScope = (() => {
+    try {
+        return CSS.supports("selector(:scope)") &&
+            // @scope at-rule support check
+            typeof CSSRule.SCOPE_RULE !==
+                "undefined";
+    }
+    catch {
+        return false;
+    }
+})();
+/**
+ * Build scoped style text limited to a selector (for light DOM).
+ * Uses native @scope if the browser supports it.
+ * Otherwise — naive selector prefixing.
+ *
+ *   scopeStyles('x-button', 'button { color: red }')
+ *     → '@scope (x-button) { button { color: red } }'  // or
+ *     → 'x-button button { color: red }'
+ */
+export function scopeStyles(tagName, sheet) {
+    let text = "";
+    for (const rule of sheet.cssRules)
+        text += rule.cssText;
+    let scoped;
+    if (hasScope) {
+        scoped = `@scope (${tagName}) { ${text} }`;
+    }
+    else {
+        // naive: prefix every top-level selector with `tagName `.
+        // Works for simple cases "button {...}", "p, span {...}".
+        // Does not touch @-rules.
+        scoped = text.replace(/(^|\})\s*([^{}@][^{}]*)\{/g, (_m, brace, sel) => {
+            const prefixed = sel
+                .split(",")
+                .map((s) => {
+                const trimmed = s.trim();
+                if (!trimmed)
+                    return trimmed;
+                if (trimmed.startsWith(tagName))
+                    return trimmed;
+                return `${tagName} ${trimmed}`;
+            })
+                .join(", ");
+            return `${brace} ${prefixed} {`;
+        });
+    }
+    const out = new CSSStyleSheet();
+    out.replaceSync(scoped);
+    return out;
+}
+//# sourceMappingURL=css.js.map

package/dist/src/css.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"css.js","sourceRoot":"","sources":["../../src/css.ts"],"names":[],"mappings":"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"}

package/dist/src/devtools.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Dev logger for signals and effects.
+ *
+ * Enabled by a flag in localStorage:
+ *   localStorage.madoDebug = '1'
+ *
+ * What it does:
+ *   - wraps signal/effect/computed for logging
+ *   - shows [signal] name: old → new
+ *   - groups effects via console.group / console.groupEnd
+ *
+ * Setup:
+ *   import '@madojs/mado/devtools.js';  // at the very top of app.ts
+ *
+ * In production — just don't import this file, and all dev code will be
+ * tree-shaken (or simply absent from the module graph).
+ *
+ * Implementation: imports the already-initialised signal module and
+ * patches the factory. A simple proof-of-concept approach; for production-
+ * grade DevTools a full hook is needed, but that's a different story.
+ */
+export {};

package/dist/src/devtools.js

@@ -0,0 +1,63 @@
+/**
+ * Dev logger for signals and effects.
+ *
+ * Enabled by a flag in localStorage:
+ *   localStorage.madoDebug = '1'
+ *
+ * What it does:
+ *   - wraps signal/effect/computed for logging
+ *   - shows [signal] name: old → new
+ *   - groups effects via console.group / console.groupEnd
+ *
+ * Setup:
+ *   import '@madojs/mado/devtools.js';  // at the very top of app.ts
+ *
+ * In production — just don't import this file, and all dev code will be
+ * tree-shaken (or simply absent from the module graph).
+ *
+ * Implementation: imports the already-initialised signal module and
+ * patches the factory. A simple proof-of-concept approach; for production-
+ * grade DevTools a full hook is needed, but that's a different story.
+ */
+import * as signalModule from "./signal.js";
+const ENABLED = typeof localStorage !== "undefined" &&
+    localStorage.getItem("madoDebug") === "1";
+if (ENABLED) {
+    // eslint-disable-next-line no-console
+    console.info("%c[mado] devtools enabled", "color: #888");
+    const origSignal = signalModule.signal;
+    let counter = 0;
+    // @ts-expect-error patching module live
+    signalModule.signal = function patchedSignal(initial) {
+        const name = `s${++counter}`;
+        const sig = origSignal(initial);
+        const origSet = sig.set;
+        sig.set = (next) => {
+            const prev = sig.peek();
+            if (!Object.is(prev, next)) {
+                // eslint-disable-next-line no-console
+                console.log(`%c[signal ${name}]`, "color: #888", prev, "→", next);
+            }
+            origSet(next);
+        };
+        return sig;
+    };
+    const origEffect = signalModule.effect;
+    // @ts-expect-error patching module live
+    signalModule.effect = function patchedEffect(fn) {
+        let id = 0;
+        return origEffect(() => {
+            const tag = `[effect #${++id}]`;
+            // eslint-disable-next-line no-console
+            console.groupCollapsed(tag);
+            try {
+                return fn();
+            }
+            finally {
+                // eslint-disable-next-line no-console
+                console.groupEnd();
+            }
+        });
+    };
+}
+//# sourceMappingURL=devtools.js.map

package/dist/src/devtools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"devtools.js","sourceRoot":"","sources":["../../src/devtools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,YAAY,MAAM,aAAa,CAAC;AAE5C,MAAM,OAAO,GACX,OAAO,YAAY,KAAK,WAAW;IACnC,YAAY,CAAC,OAAO,CAAC,WAAW,CAAC,KAAK,GAAG,CAAC;AAE5C,IAAI,OAAO,EAAE,CAAC;IACZ,sCAAsC;IACtC,OAAO,CAAC,IAAI,CAAC,2BAA2B,EAAE,aAAa,CAAC,CAAC;IAEzD,MAAM,UAAU,GAAG,YAAY,CAAC,MAAM,CAAC;IACvC,IAAI,OAAO,GAAG,CAAC,CAAC;IAEhB,wCAAwC;IACxC,YAAY,CAAC,MAAM,GAAG,SAAS,aAAa,CAAI,OAAU;QACxD,MAAM,IAAI,GAAG,IAAI,EAAE,OAAO,EAAE,CAAC;QAC7B,MAAM,GAAG,GAAG,UAAU,CAAC,OAAO,CAAC,CAAC;QAChC,MAAM,OAAO,GAAG,GAAG,CAAC,GAAG,CAAC;QACxB,GAAG,CAAC,GAAG,GAAG,CAAC,IAAO,EAAE,EAAE;YACpB,MAAM,IAAI,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC;YACxB,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE,CAAC;gBAC3B,sCAAsC;gBACtC,OAAO,CAAC,GAAG,CAAC,aAAa,IAAI,GAAG,EAAE,aAAa,EAAE,IAAI,EAAE,GAAG,EAAE,IAAI,CAAC,CAAC;YACpE,CAAC;YACD,OAAO,CAAC,IAAI,CAAC,CAAC;QAChB,CAAC,CAAC;QACF,OAAO,GAAG,CAAC;IACb,CAAC,CAAC;IAEF,MAAM,UAAU,GAAG,YAAY,CAAC,MAAM,CAAC;IACvC,wCAAwC;IACxC,YAAY,CAAC,MAAM,GAAG,SAAS,aAAa,CAAC,EAAiB;QAC5D,IAAI,EAAE,GAAG,CAAC,CAAC;QACX,OAAO,UAAU,CAAC,GAAG,EAAE;YACrB,MAAM,GAAG,GAAG,YAAY,EAAE,EAAE,GAAG,CAAC;YAChC,sCAAsC;YACtC,OAAO,CAAC,cAAc,CAAC,GAAG,CAAC,CAAC;YAC5B,IAAI,CAAC;gBACH,OAAO,EAAE,EAAU,CAAC;YACtB,CAAC;oBAAS,CAAC;gBACT,sCAAsC;gBACtC,OAAO,CAAC,QAAQ,EAAE,CAAC;YACrB,CAAC;QACH,CAAC,CAAC,CAAC;IACL,CAAC,CAAC;AACJ,CAAC"}

package/dist/src/diagnostics.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Internal dev diagnostics.
+ *
+ * Warnings are intentionally best-effort: they never throw and they are printed
+ * once per code so noisy app renders do not flood the console.
+ */
+export declare function warnOnce(code: string, message: string): void;
+export declare const _testHooks: {
+    resetWarnings(): void;
+    seenWarnings(): string[];
+};