aktion-runtime 0.5.0 → 0.5.1

package/dist/system_prompt.txt

@@ -230,6 +230,48 @@ brackets doesn't matter.
 `effect { ... }` (no brackets) is equivalent to `effect [on:mount] { ... }` —
 both run the body once on mount.
 
+### Scope — top-level vs. component-local
+An effect can live at the program top level OR inside a
+`component Name() { … }` body. The syntax is identical; only the
+lifecycle differs:
+
+- **Top-level** — mounted once when the program parses, torn down on
+  `setResponse` / `clear()`. Use for global concerns (analytics,
+  app-wide shortcuts, hydration of shared atoms).
+- **Component-local** — mounted once per component instance on its
+  first render, torn down when the instance disappears from the tree.
+  Each instance gets its own timers, watched-atom subscriptions, and
+  `cleanup(fn)` registrations. Use for per-instance work (per-row
+  polling, modal focus management, observers attached to a widget).
+
+```
+_app_ = App()
+$value = 10
+
+# Top-level — one shared interval for the whole program.
+effect [on:every(1000)] {
+  $value = $value + 1
+}
+
+component App() {
+  return Box([Text("Value: " + $value)])
+}
+```
+
+```
+_app_ = App()
+$value = 10
+
+component App() {
+  # Component-local — interval starts on first render and is cleared
+  # automatically when the App instance leaves the tree.
+  effect [on:every(1000)] {
+    $value = $value + 1
+  }
+  return Box([Text("Value: " + $value)])
+}
+```
+
 ### Examples
 
 ```

package/dist/types/renderer/renderer.d.ts

@@ -1,4 +1,5 @@
 import { EvaluationContext } from '../runtime/evaluator.js';
+import { EffectDeclaration } from '../parser/types.js';
 import { StateStore } from '../runtime/state.js';
 import { Router } from '../runtime/router.js';
 import { ComponentLibrary } from '../library/types.js';
@@ -18,6 +19,20 @@ export interface RenderOptions {
      * render as `[unknown component: <Name>]` so the failure is visible.
      */
     evaluationContext?: () => EvaluationContext;
+    /**
+     * Mount `effect [ ...deps ] { … }` declarations discovered inside a
+     * `component { … }` body. Called by the renderer after every render of
+     * the instance; the implementation is expected to be idempotent so
+     * re-renders are no-ops once the effects are mounted. The host wires
+     * this to the same `EffectRunner` that handles top-level effects.
+     */
+    mountInstanceEffects?: (instanceKey: string, decls: ReadonlyArray<EffectDeclaration>, getCtx: () => EvaluationContext) => void;
+    /**
+     * Tear down every per-instance effect mounted under `instanceKey`.
+     * Invoked when the component instance disappears from the render tree
+     * (between two `beginRender`/`endRender` passes).
+     */
+    unmountInstanceEffects?: (instanceKey: string) => void;
 }
 export declare class Renderer {
     private options;
@@ -36,6 +51,13 @@ export declare class Renderer {
     private readonly instanceDisposers;
     /** Instance paths seen during the current render — used to GC stale state. */
     private aliveInstances;
+    /**
+     * User-declared component instances that currently hold per-instance
+     * effects (mounted via `mountInstanceEffects`). Tracked separately from
+     * `instanceStates` so the renderer can fire `unmountInstanceEffects` on
+     * GC even when an instance never registered `useInstanceState`.
+     */
+    private readonly instancesWithEffects;
     constructor(options: RenderOptions);
     /**
      * Swap the component library backing this renderer. Used when the host

package/dist/types/runtime/effects.d.ts

@@ -25,11 +25,30 @@ export declare class EffectRunner {
     /** Get any errors raised at mount-time (denied capabilities, parse issues). */
     getErrors(): ReadonlyArray<string>;
     /**
-     * Mount every effect declaration in `decls`. Idempotent: declarations
-     * that are already mounted under the same name are left alone, those
-     * that vanish from the new program are torn down.
+     * Mount every top-level effect declaration in `decls`. Idempotent:
+     * declarations that are already mounted under the same name are left
+     * alone, those that vanish from the new program are torn down.
+     *
+     * Only touches global (top-level) effects. Per-instance effects mounted
+     * inside `component { … }` bodies are managed via `syncInstanceEffects`
+     * / `unmountInstance` and are not affected by this call.
      */
     syncEffects(decls: ReadonlyArray<EffectDeclaration>, getCtx: () => EvaluationContext): void;
+    /**
+     * Mount per-instance effects discovered inside a `component { … }` body.
+     * Idempotent: re-rendering the same instance with the same effect set is
+     * a no-op; effects that vanished from the body since the last render are
+     * torn down. Effects belonging to other instances are untouched.
+     */
+    syncInstanceEffects(instanceKey: string, decls: ReadonlyArray<EffectDeclaration>, getCtx: () => EvaluationContext): void;
+    /**
+     * Tear down every effect that belongs to the given component instance
+     * (i.e. mounted via `syncInstanceEffects(instanceKey, …)`). Called by
+     * the renderer when an instance disappears from the tree so timers,
+     * interval handles, and state subscriptions don't outlive the
+     * component the user can see.
+     */
+    unmountInstance(instanceKey: string): void;
     reset(): void;
     private mount;
     private unmount;

package/dist/types/runtime/evaluator.d.ts

@@ -85,6 +85,17 @@ export interface EvaluationContext {
     componentDecls: Map<string, ComponentDeclaration>;
     /** Effect declarations (`effect [ ...deps ] { ... }`), keyed by auto-generated name. */
     effectDecls: Map<string, EffectDeclaration>;
+    /**
+     * Stack of per-component-invocation effect collection frames.
+     *
+     * When this stack is non-empty, an `EffectDeclaration` encountered while
+     * walking a block body is appended to the top frame instead of being
+     * registered globally on `effectDecls`. The renderer drains the frame
+     * immediately after `evaluateUserComponent` returns so it can mount the
+     * declarations on a per-instance scope (instead of globally, once per
+     * program).
+     */
+    componentEffectStack: EffectDeclaration[][];
     /** Action declarations (`action Foo() { ... }`). */
     actionDecls: Map<string, ActionDeclaration>;
     /** HTTP runtime (`http({...})` calls + interceptor configuration). */
@@ -135,6 +146,18 @@ export declare function resolveStateAlias(ctx: EvaluationContext, name: string):
  */
 export declare function planProgram(program: Program, ctx: EvaluationContext): void;
 export declare function evaluate(expr: Expression, ctx: EvaluationContext): unknown;
+/**
+ * Result of `evaluateUserComponent`. `value` is the body's last
+ * expression value (a `ComponentNode`, another `UserComponentNode`, or a
+ * primitive) that the renderer will materialise. `effects` is the list of
+ * `effect [ ...deps ] { … }` declarations discovered inside the body —
+ * the renderer hands them to the host's `EffectRunner` so they mount on
+ * a per-instance scope and tear down when the instance unmounts.
+ */
+export interface EvaluatedUserComponent {
+    value: unknown;
+    effects: ReadonlyArray<EffectDeclaration>;
+}
 /**
  * Evaluate a user-declared component body in a fresh per-instance scope.
  * Called by the renderer once the stable instance key is known so
@@ -146,6 +169,7 @@ export declare function evaluate(expr: Expression, ctx: EvaluationContext): unkn
  *
  * Returns the body's last-expression value (typically a `ComponentNode`
  * the renderer can hand to the library, or another `UserComponentNode`
- * to expand recursively).
+ * to expand recursively) plus any `effect [ ...deps ] { … }` declarations
+ * discovered inside the body that the renderer must mount per-instance.
  */
-export declare function evaluateUserComponent(node: UserComponentNode, ctx: EvaluationContext, instanceKey: string): unknown;
+export declare function evaluateUserComponent(node: UserComponentNode, ctx: EvaluationContext, instanceKey: string): EvaluatedUserComponent;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aktion-runtime",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "Aktion is a single web component that turns a compact, streaming-first DSL into a rich, interactive UI inside its shadow DOM. Works in React, Vue, Angular, Svelte, plain HTML — or no framework at all.",
   "type": "module",
   "main": "./dist/index.cjs",