aktion-runtime 0.5.0 → 0.5.1

package/README.md

@@ -94,9 +94,12 @@ Everything you need at runtime ships in a single bundle:
   work — anonymous blocks where the dependency list mixes state triggers
   (`$atom`), lifecycle triggers (`on:mount`, `on:unmount`, `on:every(N)`),
   and rate-limit modifiers (`debounce(N)`, `throttle(N)`). `effect { … }`
-  with an empty list is equivalent to `effect [on:mount] { … }`.
-  `action Name(args) { … }` declares click-driven mutations and may
-  optionally `return` a value.
+  with an empty list is equivalent to `effect [on:mount] { … }`. Declare
+  an effect **at the top level** for program-wide work, or **inside a
+  `component { … }` body** to scope it to a single instance — timers,
+  watched atoms, and `cleanup(fn)` registrations tear down when the
+  component leaves the tree. `action Name(args) { … }` declares
+  click-driven mutations and may optionally `return` a value.
 - **A built-in router.** `pages = _router_({ "/path": Component(), "/users/:id": UserPage(id: params.id), default: NotFound() })` plus
   `NavLink(label, to)` and a reserved `_route_` handle that exposes
   `_route_.path`, `_route_.params`, `_route_.query`, `_route_.pattern`,
@@ -147,26 +150,26 @@ For non-module setups (older bundlers, embedded contexts) use the IIFE build:
 …or install from npm and import once from your client-side entry point:
 
 ```bash
-npm install @aktion/runtime
-# yarn add @aktion/runtime
-# pnpm add @aktion/runtime
+npm install aktion-runtime
+# yarn add aktion-runtime
+# pnpm add aktion-runtime
 ```
 
 ```js
-import "@aktion/runtime";
+import "aktion-runtime";
 ```
 
 The package is published as
-[`@aktion/runtime`](https://www.npmjs.com/package/@aktion/runtime). The
+[`aktion-runtime`](https://www.npmjs.com/package/aktion-runtime). The
 npm tarball ships only the compiled `dist/` output (ESM + CJS + UMD +
 IIFE bundles, type declarations, the stylesheet, and the two
 `system_prompt*.txt` files), so installs stay small. Subpath imports
 are available for convenience:
 
 ```js
-import "@aktion/runtime/style.css";
+import "aktion-runtime/style.css";
 const SYSTEM_PROMPT = await fetch(
-  new URL("@aktion/runtime/system_prompt.txt", import.meta.url),
+  new URL("aktion-runtime/system_prompt.txt", import.meta.url),
 ).then((r) => r.text());
 ```
 
@@ -385,7 +388,11 @@ _app_ = pages
   lifecycle / interval triggers (`on:mount`, `on:unmount`,
   `on:every(N)`), and rate-limit modifiers (`debounce(N)`,
   `throttle(N)`). `effect { ... }` (no brackets) is equivalent to
-  `effect [on:mount] { ... }`.
+  `effect [on:mount] { ... }`. Declare at the program top level for
+  global work, or inside a `component { … }` body to scope the effect
+  to that instance — the runtime mounts it on first render and tears
+  down its timers / subscriptions / `cleanup(fn)` handlers when the
+  instance leaves the tree.
 - Expression-form control flow: `if cond { … } else { … }`,
   `match expr { "a": A() default: Else() }`, `for x in xs { Row(x) }`.
   Match and router arms use `:` and `default:` (not `->` / `_`).
@@ -489,6 +496,33 @@ component TaskRow(task) {
 }
 ```
 
+### Component-scoped effects
+
+`effect [ ...deps ] { … }` blocks can live at the program top level
+**or** inside a `component { … }` body. Inside a component body the
+runtime mounts the effect when the instance first renders and tears it
+down (clearing timers, unsubscribing watched atoms, firing every
+registered `cleanup(fn)`) the moment the instance disappears from the
+tree. Two `LiveClock()` calls produce two independent intervals — and
+removing one stops only that one:
+
+```text
+_app_ = Stack([LiveClock("UTC"), LiveClock("Local")])
+
+component LiveClock(label) {
+  $now = @Now()
+  effect [on:every(1000)] {
+    $now = @Now()
+  }
+  return Stack([Text(label), Text(@FormatDate($now, "time"))])
+}
+```
+
+Use a top-level `effect [...] { … }` for global work (analytics,
+app-wide keyboard shortcuts, hydration of shared atoms); use a
+component-local effect whenever the background work logically belongs
+to the UI it serves.
+
 ### Schema-as-truth diagnostics
 
 `validateProgramSchema(program, library)` (exported from
@@ -947,7 +981,7 @@ import {
   getDiagnostics,  // merged parse + schema errors (LSP-ready)
   getCompletions,  // context-aware completions
   getHoverInfo,    // hover docs for symbols
-} from "@aktion/runtime";
+} from "aktion-runtime";
 ```
 
 - `formatProgram` projects the parsed AST back to canonical source —
@@ -981,7 +1015,7 @@ consumes from the CDN.
 | `language.html`                     | Full Aktion language reference.                                            |
 | `components.html`                   | Every built-in component with a live preview, positional signatures, prop tables, and enum values. |
 | `actions.html`                      | `action Name() { … }` guide — declarative state mutations, optimistic snapshot/rollback, lambda-based click handlers, navigation, and end-to-end examples. |
-| `side-effects.html`                 | `effect [ ...deps ] { … }` guide — anonymous side effects, dependency entries (state, lifecycle, intervals, debounce/throttle), cleanup, and effect vs. action. |
+| `side-effects.html`                 | `effect [ ...deps ] { … }` guide — anonymous side effects, dependency entries (state, lifecycle, intervals, debounce/throttle), top-level vs. component-local scope, cleanup, and effect vs. action. |
 | `javascript-interactions.html`      | `effect [ ...deps ] { js { … } }` + action `js{}` bodies — the JS escape hatch.         |
 | `routing.html`                      | Hash-based routing guide — always available at runtime.                                 |
 | `themes.html`                       | Built-in themes gallery, live picker, side-by-side compare, and the token customization studio. |
@@ -1098,7 +1132,7 @@ dist/system_prompt_chat.txt # Compact chat-focused prompt
 
 ### Publish to npm
 
-The package is published as `@aktion/runtime`. The `files` field
+The package is published as `aktion-runtime`. The `files` field
 restricts the tarball to `dist/` only, and `prepublishOnly` runs the
 full build, so a release is: