Mental Model

Four execution contexts — module, outer setup, inner template, and handlers — and what you may create, read, and clean up in each.

import { atom, html, onMount, renderApp } from 'mates';

// 1) ES module scope — SPA: shared client singleton (OK)
//    SSR App.ts: throws — that module is shared across all users
const theme = atom('light');

const Counter = () => {
  // 2) Outer (setup) — runs ONCE on mount; safe in SPA and SSR
  const count = atom(0);
  onMount(() => console.log('mounted'));

  // 3) Inner (template) — re-runs on tracked reads
  return () => html`
    <button @click=${() => {
      // 4) Handler — mutate existing state; don't create atoms here
      count.set(n => n + 1);
    }}>${count()} · ${theme()}</button>
  `;
};

renderApp(Counter, document.getElementById('app'));

Overview

Mates has four execution contexts. Rules for creating primitives, tracking reads, and cleanup all depend on which one you are in.

1. ES module scope — top of the file, outside any function. Runs once on import. On a SPA, fine for shared atoms/events (no component lifecycle — __subscribe cleanup is manual). During SSR, App.ts is evaluated once per Node process and reused for every GET — module-level atoms/stores/actions throw. Full table: Restricted Usage.

2. Component outer (setup) — the outer function of a component. Runs once on mount. The safe default in SPA and SSR. Create atoms, effects, events, and on* hooks here. Lifecycle-aware APIs (on(), effect(), on-hooks) auto-clean on unmount.

3. Component inner (template) — the function returned by the outer. Re-runs on every reactive update. Read atoms here (tracked). Never create primitives or call on-hooks — that throws.

4. Handler / callback — event handlers, action callbacks, timers, promises. Safe to mutate existing state. Creating primitives works but is discouraged (no lifecycle). Creating inside effect()/memo() callbacks throws.

Creation rules (what can be created where)

Primitive	Module / Outer	Template / Handler
`atom` / `memo` / `effect`	/	throws in template · don't create in handlers · throws inside effect/memo callbacks
`event` / `channel` / `action`	/	throws in template · don't create in handlers
`scope` / `useScope`	/	Outer only — needs an active component host
On hooks (`onMount`, `on`, …)	/	Outer only — throws in template; no host in handlers

Correct: create in outer, read in template

Atoms live in the setup closure. The template only reads count() — that read is tracked, so the button label updates on set.

import { html, atom, renderApp } from 'mates';

const App = () => {

// ✅ Outer: create once for the component lifetime

const count = atom(0);

return () => html`

<h1>${count()}</h1>

<button class="btn-primary" @click=${() => count.set(n => n + 1)}>

</button>

</div>

};

renderApp(App, document.getElementById('app'));

Anti-pattern avoided: never atom() in template

Do not call atom() (or onMount) inside the inner function — it throws. Create in outer, read in template, mutate in handlers.

import { html, atom, renderApp } from 'mates';

const App = () => {

// ❌ Never: atom() / onMount() inside the template (throws)

// ✅ Always: create in outer, read in template, mutate in handlers

const count = atom(0);

return () => html`

<p class="muted m-t-5">Template only reads — no atom()</p>

<h1>${count()}</h1>

<button class="btn-primary" @click=${() => count.set(n => n + 1)}>

Inc

</button>

</div>

};

renderApp(App, document.getElementById('app'));

API — Four contexts

// Conceptual guide — no single import

Prop / Option	Type	Default	Description
`1. ES module scope`	`once on import`	—	Create shared atoms/events/actions on a SPA. Reads are untracked. No auto-cleanup — manage __subscribe yourself. on* hooks and scope() are not allowed. During SSR App load this same site throws for factories.
`2. Component outer (setup)`	`once on mount`	—	Create local atoms, memo, effect, events, actions, scope. Call onMount/on/onCleanup here. on() and effect() auto-dispose on unmount. Reads are untracked (setup runs once).
`3. Component inner (template)`	`every reactive update`	—	Read atoms with count() — tracked; component re-renders on change. Creating primitives or calling on* hooks throws. Prefer mutating via handlers, not allocating.
`4. Handler / callback`	`on event / async`	—	Mutate existing atoms, call actions, trigger events. Creating primitives is discouraged (no lifecycle). Creating inside effect/memo callbacks throws. __subscribe → you own unsub.

Reads & subscriptions

Prop / Option	Type	Default	Description
`Tracked read`	`template · effect · memo`	—	count() / .get() / .val registers a dependency. Template re-renders; effect/memo re-run when the value changes.
`Untracked read`	`module · outer · handler`	—	Returns the current value with no subscription. Safe snapshot; will not re-run the enclosing context on change.
`on(fn, deps) / effect(fn)`	`auto-cleanup`	—	Lifecycle-aware subscriptions. Prefer these in the outer function over raw __subscribe.
`__subscribe(fn)`	`manual unsub`	—	Low-level listener. Caller must call the returned unsubscribe. No host cleanups registration.