@alwatr/flux 9.16.0 → 9.18.0

package/README.md

@@ -52,7 +52,7 @@ No magic. No hidden re-renders. No performance cliffs.
 
 ### 3. **Absolute Type Safety**
 
-Through TypeScript's **Declaration Merging**, the entire action bus is fully typed:
+Through TypeScript's **Declaration Merging**, the entire action bus is fully typed. Every action is a single **`Action<K>`** object (Alwatr Flux Standard Action — AFSA) carrying `type`, `payload`, `context`, and `meta`:
 
 ```typescript
 // Define your actions once
@@ -64,14 +64,16 @@ declare module '@alwatr/flux' {
   }
 }
 
-// Get compile-time safety everywhere
-onAction('add_to_cart', (item) => {
-  // item is typed as {productId: number; qty: number}
-  cartService.add(item.productId, item.qty);
+// Get compile-time safety everywhere — handler receives the full Action object
+onAction('add_to_cart', (action) => {
+  // action.payload is typed as {productId: number; qty: number}
+  cartService.add(action.payload.productId, action.payload.qty);
+  // action.context is the nearest [action-context] ancestor value (or undefined)
+  console.log(action.context); // e.g. 'product-list'
 });
 
-dispatchAction('add_to_cart', {productId: 42, qty: 1}); // ✅
-dispatchAction('add_to_cart', 'wrong'); // ❌ Compile error
+dispatchAction({type: 'add_to_cart', payload: {productId: 42, qty: 1}}); // ✅
+dispatchAction({type: 'add_to_cart', payload: 'wrong'}); // ❌ Compile error
 ```
 
 ---
@@ -120,7 +122,7 @@ lastName.set('Smith'); // Only fullName and the effect re-run — nothing else
 
 ### 🧩 **Declarative HTML Syntax**
 
-Connect DOM events to typed actions without writing JavaScript:
+Connect DOM events to typed actions without writing JavaScript. Wrap elements in `[action-context]` to scope the same action type to different UI regions:
 
 ```html
 <!-- Simple action -->
@@ -153,6 +155,28 @@ Connect DOM events to typed actions without writing JavaScript:
 
 <!-- Fire once and remove -->
 <button on-click="track_impression:hero_banner; once">Learn More</button>
+
+<!-- Context scoping — same action type, different regions -->
+<section action-context="volume">
+  <input
+    type="range"
+    on-input="slider:change:$value"
+  />
+</section>
+<section action-context="brightness">
+  <input
+    type="range"
+    on-input="slider:change:$value"
+  />
+</section>
+```
+
+```typescript
+// Handler receives the full Action object — payload, context, and meta together
+onAction('slider:change', (action) => {
+  if (action.context === 'volume') audioService.setVolume(Number(action.payload));
+  if (action.context === 'brightness') displayService.setBrightness(Number(action.payload));
+});
 ```
 
 **Built-in modifiers:**
@@ -308,55 +332,59 @@ createEffect({
 Flux implements a **strict layered architecture** where each layer has a single responsibility:
 
 ```
-┌─────────────────────────────────────────────────────────────┐
-│                         VIEW LAYER                          │
-│  (HTML templates, Directives, lit-html rendering)           │
-│                                                              │
-│  • Reads state from Signals                                 │
-│  • Dispatches Actions via on-<event> attributes            │
-│  • Never manipulates state directly                         │
-└──────────────────┬──────────────────────────────────────────┘
+┌───────────────────────────────────────────────────────────┐
+│                         VIEW LAYER                        │
+│  (HTML templates, Directives, lit-html rendering)         │
+│                                                           │
+│  • Reads state from Signals                               │
+│  • Dispatches Actions via on-<event> attributes           │
+│  • Never manipulates state directly                       │
+└──────────────────┬────────────────────────────────────────┘
                    │ on-click="add_to_cart:42"
                    ▼
-┌─────────────────────────────────────────────────────────────┐
-│                       ACTION LAYER                          │
-│  (@alwatr/action — Global Event Delegation)                 │
-│                                                              │
-│  • Captures DOM events via document.body listener           │
-│  • Parses on-<event> attributes                            │
-│  • Runs modifiers (prevent, validate, once)                 │
-│  • Resolves payload ($value, $formdata)                     │
-│  • Dispatches typed action to ChannelSignal                 │
-└──────────────────┬──────────────────────────────────────────┘
-                   │ dispatchAction('add_to_cart', 42)
+┌───────────────────────────────────────────────────────────┐
+│                       ACTION LAYER                        │
+│  (@alwatr/action — Global Event Delegation + AFSA)        │
+│                                                           │
+│  • Captures DOM events via document.body listener         │
+│  • Resolves [action-context] ancestor → action.context    │
+│  • Parses on-<event> attributes                           │
+│  • Runs modifiers (prevent, validate, once)               │
+│  • Modifiers may enrich action.meta                       │
+│  • Resolves payload ($value, $formdata)                   │
+│  • Dispatches full Action {type, payload, context, meta}  │
+└──────────────────┬────────────────────────────────────────┘
+                   │ dispatchAction({type: 'add_to_cart', payload: 42, context: 'cart'})
                    ▼
-┌─────────────────────────────────────────────────────────────┐
-│                     CONTROLLER LAYER                        │
-│  (Business Logic, Services, Use Cases)                      │
-│                                                              │
-│  • Subscribes to Actions via onAction()                     │
-│  • Executes business logic                                  │
-│  • Updates State via Signal.set()                           │
-│  • Never touches DOM directly                               │
-└──────────────────┬──────────────────────────────────────────┘
+┌───────────────────────────────────────────────────────────┐
+│                     CONTROLLER LAYER                      │
+│  (Business Logic, Services, Use Cases)                    │
+│                                                           │
+│  • Subscribes to Actions via onAction()                   │
+│  • Receives full Action object (type, payload, context,   │
+│    meta) — no need to pass context separately             │
+│  • Executes business logic                                │
+│  • Updates State via Signal.set()                         │
+│  • Never touches DOM directly                             │
+└──────────────────┬────────────────────────────────────────┘
                    │ cartSignal.set(newCart)
                    ▼
-┌─────────────────────────────────────────────────────────────┐
-│                        STATE LAYER                          │
-│  (@alwatr/signal — Reactive State Management)               │
-│                                                              │
-│  • StateSignal — mutable state                              │
-│  • ComputedSignal — derived state (memoized)                │
-│  • EffectSignal — side effects                              │
-│  • PersistentStateSignal — localStorage sync                │
-│  • SessionStateSignal — sessionStorage sync                 │
-└──────────────────┬──────────────────────────────────────────┘
+┌───────────────────────────────────────────────────────────┐
+│                        STATE LAYER                        │
+│  (@alwatr/signal — Reactive State Management)             │
+│                                                           │
+│  • StateSignal — mutable state                            │
+│  • ComputedSignal — derived state (memoized)              │
+│  • EffectSignal — side effects                            │
+│  • PersistentStateSignal — localStorage sync              │
+│  • SessionStateSignal — sessionStorage sync               │
+└──────────────────┬────────────────────────────────────────┘
                    │ signal.subscribe(render)
                    ▼
-┌─────────────────────────────────────────────────────────────┐
-│                         VIEW LAYER                          │
-│  (Re-render only affected DOM nodes)                        │
-└─────────────────────────────────────────────────────────────┘
+┌───────────────────────────────────────────────────────────┐
+│                         VIEW LAYER                        │
+│  (Re-render only affected DOM nodes)                      │
+└───────────────────────────────────────────────────────────┘
 ```
 
 **Key architectural benefits:**
@@ -369,6 +397,63 @@ Flux implements a **strict layered architecture** where each layer has a single
 
 ---
 
+## 🎯 The Action Object (AFSA)
+
+Every action flowing through the bus — whether triggered from HTML attributes or dispatched programmatically — is a single **`Action<K>`** object (Alwatr Flux Standard Action):
+
+```typescript
+interface Action<K extends keyof ActionRecord> {
+  /** Action identifier — must be a key of ActionRecord. */
+  type: K;
+
+  /**
+   * DOM context from the nearest [action-context] ancestor.
+   * undefined for programmatic dispatches or when no ancestor exists.
+   * Example: 'product-list', 'checkout-form', 'volume-slider'
+   */
+  context?: string;
+
+  /** Business payload — type is inferred from ActionRecord[K]. */
+  payload: ActionRecord[K];
+
+  /**
+   * Open-ended metadata bag for cross-cutting concerns.
+   * Modifiers in the delegation pipeline may write to this before
+   * the action reaches subscribers.
+   */
+  meta?: Record<string, unknown>;
+}
+```
+
+This unified structure replaces the previous two-argument `(id, payload)` API. Every handler now receives the full picture:
+
+```typescript
+onAction('add_to_cart', (action) => {
+  console.log(action.type); // 'add_to_cart'
+  console.log(action.payload); // {productId: 42, qty: 1} — fully typed
+  console.log(action.context); // 'product-list' — from [action-context] ancestor
+  console.log(action.meta); // {traceId: '…'} — set by modifiers, or undefined
+});
+```
+
+Modifiers can enrich `meta` before the action reaches subscribers:
+
+```typescript
+import {registerModifier} from '@alwatr/flux';
+
+registerModifier('trace', (_event, _element, action) => {
+  action.meta ??= {};
+  action.meta['traceId'] = crypto.randomUUID();
+  return true;
+});
+```
+
+```html
+<button on-click="submit_order:42; trace">Place Order</button>
+```
+
+---
+
 ## 📦 Installation
 
 ```bash
@@ -443,8 +528,9 @@ onAction('decrement', () => {
   counterSignal.update((count) => count - 1);
 });
 
-onAction('set_count', (value) => {
-  counterSignal.set(value);
+// Handler receives the full Action object — payload is typed from ActionRecord
+onAction('set_count', (action) => {
+  counterSignal.set(action.payload); // action.payload: number
 });
 ```
 
@@ -612,39 +698,56 @@ setupActionDelegation();
 setupActionDelegation([...DEFAULT_DELEGATED_EVENTS, 'keydown', 'focus']);
 ```
 
-#### `onAction<K>(actionId, handler)`
+#### `onAction<K>(type, handler)`
 
-Subscribes to a typed action.
+Subscribes to a typed action. The handler receives the full `Action<K>` object.
 
 ```typescript
-const sub = onAction('add_to_cart', (item) => {
-  cartService.add(item.productId, item.qty);
+const sub = onAction('add_to_cart', (action) => {
+  cartService.add(action.payload.productId, action.payload.qty);
+  console.log(action.context); // e.g. 'product-list' or undefined
+  console.log(action.meta); // any metadata set by modifiers
 });
 
 sub.unsubscribe(); // Clean up when done
 ```
 
-#### `dispatchAction<K>(actionId, payload?)`
+#### `dispatchAction<K>(action)`
 
-Dispatches a typed action programmatically.
+Dispatches a typed action programmatically. Takes a full `Action<K>` object.
 
 ```typescript
-dispatchAction('navigate', '/home');
-dispatchAction('logout'); // void payload
+dispatchAction({type: 'navigate', payload: '/home'});
+dispatchAction({type: 'logout', payload: undefined}); // void payload
+
+// With context and meta
+dispatchAction({
+  type: 'add_to_cart',
+  payload: {productId: 42, qty: 1},
+  context: 'product-list',
+  meta: {source: 'recommendation'},
+});
 ```
 
 #### `registerModifier(name, handler)`
 
-Adds a custom modifier for `on-<event>` attributes.
+Adds a custom modifier for `on-<event>` attributes. The handler receives the mutable `action` object and may write to `action.meta`.
 
 ```typescript
 registerModifier('confirm', () => {
   return window.confirm('Are you sure?');
 });
+
+// A modifier that stamps a trace ID into meta
+registerModifier('trace', (_event, _element, action) => {
+  action.meta ??= {};
+  action.meta['traceId'] = crypto.randomUUID();
+  return true;
+});
 ```
 
 ```html
-<button on-click="delete_item:42; confirm">Delete</button>
+<button on-click="delete_item:42; confirm,trace">Delete</button>
 ```
 
 #### `registerPayloadResolver(name, resolver)`
@@ -842,6 +945,123 @@ renderState(currentState, {
 
 ---
 
+### Template (lit-html)
+
+`@alwatr/flux` re-exports a curated subset of [`lit-html`](https://lit.dev/docs/libraries/standalone-templates/) so you can render efficient DOM templates without adding a separate dependency.
+
+#### `html`
+
+Tagged template literal that produces a `TemplateResult`. lit-html parses the template once and only updates the dynamic parts on subsequent renders.
+
+```typescript
+import {html} from '@alwatr/flux';
+
+const greeting = (name: string) => html`
+  <p>Hello, ${name}!</p>
+`;
+```
+
+#### `render(value, container)`
+
+Renders a `TemplateResult` (or any renderable value) into a DOM container. Subsequent calls efficiently patch only the changed parts.
+
+```typescript
+import {html, render} from '@alwatr/flux';
+
+render(
+  html`
+    <h1>Hello World</h1>
+  `,
+  document.getElementById('app')!,
+);
+```
+
+#### `noChange` / `nothing`
+
+Sentinels for fine-grained control over part updates:
+
+- **`noChange`** — leaves the current DOM value untouched (skips the update entirely)
+- **`nothing`** — removes the node or attribute from the DOM
+
+```typescript
+import {html, noChange, nothing} from '@alwatr/flux';
+
+const badge = (count: number | undefined) => html`
+  <span class="badge">
+    ${count === undefined ? nothing
+    : count === 0 ? noChange
+    : count}
+  </span>
+`;
+```
+
+#### `ifDefined(value)`
+
+Renders the attribute only when `value` is not `undefined`; removes the attribute otherwise.
+
+```typescript
+import {html, ifDefined} from '@alwatr/flux';
+
+const link = (href?: string) => html`
+  <a href=${ifDefined(href)}>Click</a>
+`;
+```
+
+#### `cache(value)`
+
+Caches rendered templates keyed by their `TemplateResult` identity. Avoids re-parsing the template string when switching between a fixed set of templates (e.g. tab panels).
+
+```typescript
+import {html, cache} from '@alwatr/flux';
+
+const panel = (tab: 'home' | 'settings') =>
+  cache(
+    tab === 'home' ?
+      html`
+        <home-panel></home-panel>
+      `
+    : html`
+        <settings-panel></settings-panel>
+      `,
+  );
+```
+
+#### `classMap(classInfo)`
+
+Efficiently toggles CSS classes from a `{[className]: boolean}` object. Only the classes present in the map are touched; others are left unchanged.
+
+```typescript
+import {html, classMap} from '@alwatr/flux';
+
+const button = (isActive: boolean, isDisabled: boolean) => html`
+  <button class=${classMap({active: isActive, disabled: isDisabled})}>Click</button>
+`;
+```
+
+#### `when(condition, trueCase, falseCase?)`
+
+Conditional rendering helper. Cleaner than ternary expressions for template branches.
+
+```typescript
+import {html, when} from '@alwatr/flux';
+
+const status = (isLoading: boolean) => html`
+  <div>
+    ${when(
+      isLoading,
+      () => html`
+        <spinner-element></spinner-element>
+      `,
+      () => html`
+        <content-element></content-element>
+      `,
+    )}
+  </div>
+`;
+```
+
+---
+
 ## 🆚 Why Choose Alwatr Flux?
 
 | Feature                | React + Redux            | Solid.js        | Svelte                   | **Alwatr Flux** 🌊                 |
@@ -889,23 +1109,23 @@ import {todosSignal} from './state.js';
 
 let nextId = 1;
 
-onAction('add_todo', (text) => {
+onAction('add_todo', (action) => {
   todosSignal.update((todos) => [
     ...todos,
-    {id: nextId++, text, done: false},
+    {id: nextId++, text: action.payload, done: false},
   ]);
 });
 
-onAction('toggle_todo', (id) => {
+onAction('toggle_todo', (action) => {
   todosSignal.update((todos) =>
     todos.map((todo) =>
-      todo.id === id ? {...todo, done: !todo.done} : todo
+      todo.id === action.payload ? {...todo, done: !todo.done} : todo
     )
   );
 });
 
-onAction('remove_todo', (id) => {
-  todosSignal.update((todos) => todos.filter((t) => t.id !== id));
+onAction('remove_todo', (action) => {
+  todosSignal.update((todos) => todos.filter((t) => t.id !== action.payload));
 });
 
 // view.html

package/dist/lit-html.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Curated re-exports from `lit-html` for use within `@alwatr/flux`.
+ *
+ * Only the subset of `lit-html` APIs that are commonly needed in a Flux-based
+ * application is exported here. This keeps the public surface minimal and
+ * avoids pulling in advanced directive utilities that most consumers never use.
+ *
+ * **Exported APIs:**
+ * - `html` — tagged template literal that produces a `TemplateResult`
+ * - `render` — renders a `TemplateResult` into a DOM container
+ * - `noChange` — sentinel that tells lit-html to leave the current part value unchanged
+ * - `nothing` — sentinel that renders nothing (removes the node/attribute)
+ * - `ifDefined` — renders a value only when it is not `undefined`
+ * - `cache` — caches rendered templates to avoid re-parsing on state changes
+ * - `classMap` — efficiently sets/removes CSS classes from an object map
+ * - `when` — conditional rendering helper (`when(condition, trueCase, falseCase)`)
+ *
+ * @example
+ * ```typescript
+ * import {html, render, classMap, when} from '@alwatr/flux';
+ *
+ * const template = (isActive: boolean) => html`
+ *   <div class=${classMap({active: isActive, hidden: !isActive})}>
+ *     ${when(isActive, () => html`<span>Active</span>`, () => html`<span>Inactive</span>`)}
+ *   </div>
+ * `;
+ *
+ * render(template(true), document.getElementById('app')!);
+ * ```
+ */
+export { html, render, noChange, nothing } from 'lit-html';
+export { ifDefined } from 'lit-html/directives/if-defined.js';
+export { cache } from 'lit-html/directives/cache.js';
+export { classMap } from 'lit-html/directives/class-map.js';
+export { when } from 'lit-html/directives/when.js';
+//# sourceMappingURL=lit-html.d.ts.map

package/dist/lit-html.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lit-html.d.ts","sourceRoot":"","sources":["../src/lit-html.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,OAAO,EAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAC,MAAM,UAAU,CAAC;AAIzD,OAAO,EAAC,SAAS,EAAC,MAAM,mCAAmC,CAAC;AAC5D,OAAO,EAAC,KAAK,EAAC,MAAM,8BAA8B,CAAC;AACnD,OAAO,EAAC,QAAQ,EAAC,MAAM,kCAAkC,CAAC;AAC1D,OAAO,EAAC,IAAI,EAAC,MAAM,6BAA6B,CAAC"}

package/dist/main.d.ts

@@ -5,5 +5,6 @@ export * from '@alwatr/render-state';
 export * from '@alwatr/local-storage';
 export * from '@alwatr/session-storage';
 export * from '@alwatr/page-ready';
+export * from './lit-html.js';
 export type * from '@alwatr/type-helper';
 //# sourceMappingURL=main.d.ts.map

package/dist/main.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../src/main.ts"],"names":[],"mappings":"AAGA,cAAc,gBAAgB,CAAC;AAC/B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAClC,cAAc,sBAAsB,CAAC;AACrC,cAAc,uBAAuB,CAAC;AACtC,cAAc,yBAAyB,CAAC;AACxC,cAAc,oBAAoB,CAAC;AACnC,mBAAmB,qBAAqB,CAAC"}
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../src/main.ts"],"names":[],"mappings":"AAGA,cAAc,gBAAgB,CAAC;AAC/B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAClC,cAAc,sBAAsB,CAAC;AACrC,cAAc,uBAAuB,CAAC;AACtC,cAAc,yBAAyB,CAAC;AACxC,cAAc,oBAAoB,CAAC;AACnC,cAAc,eAAe,CAAC;AAC9B,mBAAmB,qBAAqB,CAAC"}

package/dist/main.js

@@ -1,5 +1,5 @@
-/* 📦 @alwatr/flux v9.16.0 */
-export*from"@alwatr/signal";export*from"@alwatr/action";export*from"@alwatr/directive";export*from"@alwatr/render-state";export*from"@alwatr/local-storage";export*from"@alwatr/session-storage";export*from"@alwatr/page-ready";
+/* 📦 @alwatr/flux v9.18.0 */
+export*from"@alwatr/signal";export*from"@alwatr/action";export*from"@alwatr/directive";export*from"@alwatr/render-state";export*from"@alwatr/local-storage";export*from"@alwatr/session-storage";export*from"@alwatr/page-ready";import{html as o,render as a,noChange as t,nothing as p}from"lit-html";import{ifDefined as f}from"lit-html/directives/if-defined.js";import{cache as g}from"lit-html/directives/cache.js";import{classMap as i}from"lit-html/directives/class-map.js";import{when as s}from"lit-html/directives/when.js";export{s as when,a as render,p as nothing,t as noChange,f as ifDefined,o as html,i as classMap,g as cache};
 
-//# debugId=C06C2CEF2EC7ADAE64756E2164756E21
+//# debugId=432FAE968752561764756E2164756E21
 //# sourceMappingURL=main.js.map

package/dist/main.js.map

@@ -1,10 +1,11 @@
 {
   "version": 3,
-  "sources": ["../src/main.ts"],
+  "sources": ["../src/main.ts", "../src/lit-html.ts"],
   "sourcesContent": [
-    "// UI and reactive bundle — signals, actions, directives, and client-side storage.\n// This package aggregates all UI-layer nanolibs for convenient single-import usage.\n\nexport * from '@alwatr/signal';\nexport * from '@alwatr/action';\nexport * from '@alwatr/directive';\nexport * from '@alwatr/render-state';\nexport * from '@alwatr/local-storage';\nexport * from '@alwatr/session-storage';\nexport * from '@alwatr/page-ready';\nexport type * from '@alwatr/type-helper';\n"
+    "// UI and reactive bundle — signals, actions, directives, and client-side storage.\n// This package aggregates all UI-layer nanolibs for convenient single-import usage.\n\nexport * from '@alwatr/signal';\nexport * from '@alwatr/action';\nexport * from '@alwatr/directive';\nexport * from '@alwatr/render-state';\nexport * from '@alwatr/local-storage';\nexport * from '@alwatr/session-storage';\nexport * from '@alwatr/page-ready';\nexport * from './lit-html.js';\nexport type * from '@alwatr/type-helper';\n",
+    "/**\n * Curated re-exports from `lit-html` for use within `@alwatr/flux`.\n *\n * Only the subset of `lit-html` APIs that are commonly needed in a Flux-based\n * application is exported here. This keeps the public surface minimal and\n * avoids pulling in advanced directive utilities that most consumers never use.\n *\n * **Exported APIs:**\n * - `html` — tagged template literal that produces a `TemplateResult`\n * - `render` — renders a `TemplateResult` into a DOM container\n * - `noChange` — sentinel that tells lit-html to leave the current part value unchanged\n * - `nothing` — sentinel that renders nothing (removes the node/attribute)\n * - `ifDefined` — renders a value only when it is not `undefined`\n * - `cache` — caches rendered templates to avoid re-parsing on state changes\n * - `classMap` — efficiently sets/removes CSS classes from an object map\n * - `when` — conditional rendering helper (`when(condition, trueCase, falseCase)`)\n *\n * @example\n * ```typescript\n * import {html, render, classMap, when} from '@alwatr/flux';\n *\n * const template = (isActive: boolean) => html`\n *   <div class=${classMap({active: isActive, hidden: !isActive})}>\n *     ${when(isActive, () => html`<span>Active</span>`, () => html`<span>Inactive</span>`)}\n *   </div>\n * `;\n *\n * render(template(true), document.getElementById('app')!);\n * ```\n */\nexport {html, render, noChange, nothing} from 'lit-html';\n// export {Directive, PartType, directive} from 'lit-html/directive.js';\n// export {AsyncDirective} from 'lit-html/async-directive.js';\n// export {unsafeSVG} from 'lit-html/directives/unsafe-svg.js';\nexport {ifDefined} from 'lit-html/directives/if-defined.js';\nexport {cache} from 'lit-html/directives/cache.js';\nexport {classMap} from 'lit-html/directives/class-map.js';\nexport {when} from 'lit-html/directives/when.js';\n\n// export type {Part, PartInfo} from 'lit-html/directive.js';\n// export type {LitUnstable} from 'lit-html';\n"
   ],
-  "mappings": ";AAGA,4BACA,4BACA,+BACA,kCACA,mCACA,qCACA",
-  "debugId": "C06C2CEF2EC7ADAE64756E2164756E21",
+  "mappings": ";AAGA,4BACA,4BACA,+BACA,kCACA,mCACA,qCACA,gCCqBA,eAAQ,YAAM,cAAQ,aAAU,iBAIhC,oBAAQ,0CACR,gBAAQ,qCACR,mBAAQ,yCACR,eAAQ",
+  "debugId": "432FAE968752561764756E2164756E21",
   "names": []
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alwatr/flux",
-  "version": "9.16.0",
+  "version": "9.18.0",
   "description": "UI and reactive library bundle for ECMAScript (JavaScript/TypeScript) projects — signals, actions, directives, and storage.",
   "license": "MPL-2.0",
   "author": "S. Ali Mihandoost <ali.mihandoost@gmail.com> (https://ali.mihandoost.com)",
@@ -21,14 +21,15 @@
   },
   "sideEffects": false,
   "dependencies": {
-    "@alwatr/action": "9.16.0",
-    "@alwatr/directive": "9.16.0",
+    "@alwatr/action": "9.17.0",
+    "@alwatr/directive": "9.18.0",
     "@alwatr/local-storage": "9.16.0",
     "@alwatr/page-ready": "9.16.0",
     "@alwatr/render-state": "9.16.0",
     "@alwatr/session-storage": "9.16.0",
     "@alwatr/signal": "9.16.0",
-    "@alwatr/type-helper": "9.14.0"
+    "@alwatr/type-helper": "9.14.0",
+    "lit-html": "^3.3.2"
   },
   "devDependencies": {
     "@alwatr/nano-build": "9.14.0",
@@ -38,7 +39,7 @@
   "scripts": {
     "b": "bun run build",
     "build": "bun run build:ts && bun run build:es",
-    "build:es": "nano-build --preset=module src/*.ts",
+    "build:es": "nano-build --preset=module src/main.ts",
     "build:ts": "tsc --build",
     "cl": "bun run clean",
     "clean": "rm -rfv dist *.tsbuildinfo",
@@ -81,5 +82,5 @@
     "ui",
     "unidirectional-data-flow"
   ],
-  "gitHead": "c210044f6e8ab444ec2f9e600f095761cbd279bd"
+  "gitHead": "ae7aed95106fd2e6d3c14f0628fc12ae8a29ea15"
 }

package/src/lit-html.ts

@@ -0,0 +1,41 @@
+/**
+ * Curated re-exports from `lit-html` for use within `@alwatr/flux`.
+ *
+ * Only the subset of `lit-html` APIs that are commonly needed in a Flux-based
+ * application is exported here. This keeps the public surface minimal and
+ * avoids pulling in advanced directive utilities that most consumers never use.
+ *
+ * **Exported APIs:**
+ * - `html` — tagged template literal that produces a `TemplateResult`
+ * - `render` — renders a `TemplateResult` into a DOM container
+ * - `noChange` — sentinel that tells lit-html to leave the current part value unchanged
+ * - `nothing` — sentinel that renders nothing (removes the node/attribute)
+ * - `ifDefined` — renders a value only when it is not `undefined`
+ * - `cache` — caches rendered templates to avoid re-parsing on state changes
+ * - `classMap` — efficiently sets/removes CSS classes from an object map
+ * - `when` — conditional rendering helper (`when(condition, trueCase, falseCase)`)
+ *
+ * @example
+ * ```typescript
+ * import {html, render, classMap, when} from '@alwatr/flux';
+ *
+ * const template = (isActive: boolean) => html`
+ *   <div class=${classMap({active: isActive, hidden: !isActive})}>
+ *     ${when(isActive, () => html`<span>Active</span>`, () => html`<span>Inactive</span>`)}
+ *   </div>
+ * `;
+ *
+ * render(template(true), document.getElementById('app')!);
+ * ```
+ */
+export {html, render, noChange, nothing} from 'lit-html';
+// export {Directive, PartType, directive} from 'lit-html/directive.js';
+// export {AsyncDirective} from 'lit-html/async-directive.js';
+// export {unsafeSVG} from 'lit-html/directives/unsafe-svg.js';
+export {ifDefined} from 'lit-html/directives/if-defined.js';
+export {cache} from 'lit-html/directives/cache.js';
+export {classMap} from 'lit-html/directives/class-map.js';
+export {when} from 'lit-html/directives/when.js';
+
+// export type {Part, PartInfo} from 'lit-html/directive.js';
+// export type {LitUnstable} from 'lit-html';

package/src/main.ts

@@ -8,4 +8,5 @@ export * from '@alwatr/render-state';
 export * from '@alwatr/local-storage';
 export * from '@alwatr/session-storage';
 export * from '@alwatr/page-ready';
+export * from './lit-html.js';
 export type * from '@alwatr/type-helper';