lithent 1.21.4 → 1.21.5

package/dist/lithent-agent-addon.md

@@ -1,6 +1,6 @@
 # Lithent Agent Addon
 
-> Version: 1.21.4
+> Version: 1.21.5
 
 You are a coding agent with Lithent virtual DOM guidance enabled.
 
@@ -120,7 +120,7 @@ COMMON MISTAKES TO CATCH:
 REFERENCE MATERIALS (NOT PART OF BEHAVIORAL RULES):
 
 For detailed code examples and API usage, refer to:
-node_modules/lithent/dist/lithent-skills.md
+node_modules/lithent/dist/skills/SKILL.md
 
 This reference material provides comprehensive examples, patterns,
 and import references that complement the behavioral guidelines above.

package/dist/{lithent-skills.md → skills/SKILL.md}

@@ -1,6 +1,17 @@
+---
+name: lithent
+title: Lithent Agent Skills
+version: 1.21.5
+description: AI agent skills for working with the Lithent library.
+additional_materials:
+  - constraints/
+  - reference/
+  - examples/
+---
+
 # Lithent Agent Skills
 
-> Version: 1.21.4
+> Version: 1.21.5
 
 This file provides AI agent skills for working with the Lithent library.
 
@@ -363,3 +374,9 @@ import { fTags, fFragment, fMount } from 'lithent/ftags';
 // HTM
 import { lTag } from 'lithent/tag';
 ```
+
+## Additional materials (optional)
+
+- `constraints/` (rules, mistakes, troubleshooting)
+- `reference/` (props types, children types, lstore inference)
+- `examples/` (quick examples)

package/dist/skills/constraints/mistakes.md

@@ -0,0 +1,15 @@
+---
+title: Common Mistakes
+category: constraints
+version: 1.21.5
+---
+
+# Common Mistakes
+
+- Destructuring props in the mounter and expecting primitive values to update.
+- Using `props.children` instead of the `children` argument.
+- Swapping argument order for `mount` or `lmount`.
+- Calling `state`/`lstate` outside the mounter (e.g., in updaters/handlers).
+- Using `state` with `lmount` or `lstate` with `mount`.
+- Creating `store`/`lstore` inside components (new store per render).
+- Mutating arrays or nested objects directly instead of replacing references.

package/dist/skills/constraints/rules.md

@@ -0,0 +1,16 @@
+---
+title: Rules
+category: constraints
+version: 1.21.5
+---
+
+# Rules
+
+- Use `state` with `mount` and pass `renew` as the second argument.
+- Use `lstate` with `lmount` (no `renew` argument is needed).
+- Call `state`/`lstate` only inside the mounter (not in updaters or handlers).
+- Use `store` with `mount`, `lstore` with `lmount`, and create stores outside components.
+- `store` is shallow‑reactive: replace first‑level properties or arrays to update.
+- Don’t rely on `props.children`; use the separate `children` argument.
+- Argument order is `mount(renew, props, children)` and `lmount(props, children)`.
+- Avoid destructuring props in the mounter if you need live updates.

package/dist/skills/constraints/troubleshooting.md

@@ -0,0 +1,13 @@
+---
+title: Troubleshooting
+category: constraints
+version: 1.21.5
+---
+
+# Troubleshooting
+
+- **Props look stale:** avoid destructuring props in the mounter; read `props.x` directly or use the updater’s props argument.
+- **Children missing:** use the `children` argument (not `props.children`); remember children are only passed to the mounter.
+- **Updates not rendering:** don’t mutate arrays/objects in place—assign a new array or replace first‑level properties.
+- **State doesn’t react:** `state` requires `mount` + `renew`; `lstate` requires `lmount` and is mounter‑only.
+- **Stores reset unexpectedly:** define `store`/`lstore` outside components and reuse them.

package/dist/skills/examples/quick-examples.md

@@ -0,0 +1,195 @@
+---
+title: Quick Examples
+category: examples
+version: 1.21.5
+---
+
+# Quick Examples
+
+## Manual Counter (mount + state)
+
+```tsx
+import { mount } from 'lithent';
+import { state } from 'lithent/helper';
+
+const Counter = mount((renew) => {
+  const count = state(0, renew);
+  return () => <button onClick={() => count.value++}>{count.value}</button>;
+});
+```
+
+## Light Counter (lmount + lstate)
+
+```tsx
+import { lmount } from 'lithent';
+import { lstate } from 'lithent/helper';
+
+const Counter = lmount(() => {
+  const count = lstate(0);
+  return () => <button onClick={() => count.value++}>{count.value}</button>;
+});
+```
+
+## Computed + Effect
+
+```tsx
+import { lmount } from 'lithent';
+import { lstate, computed, effect } from 'lithent/helper';
+
+const Profile = lmount(() => {
+  const first = lstate('Ada');
+  const last = lstate('Lovelace');
+  const full = computed(() => `${first.value} ${last.value}`);
+
+  effect(() => {
+    console.log('Name changed:', full.value);
+  });
+
+  return () => <p>{full.value}</p>;
+});
+```
+
+## Lifecycle Hooks (mount / update)
+
+```tsx
+import { mount, mountCallback, updateCallback, mountReadyCallback } from 'lithent';
+import { state } from 'lithent/helper';
+
+const Widget = mount((renew) => {
+  const count = state(0, renew);
+
+  // Runs after DOM mount
+  mountCallback(() => {
+    console.log('mounted');
+    return () => console.log('unmounted');
+  });
+
+  // Runs right after virtual DOM creation (before DOM mount)
+  mountReadyCallback(() => {
+    console.log('mountReady');
+  });
+
+  // Runs before every update; returned function runs after DOM update
+  updateCallback(() => {
+    console.log('before update');
+    return () => console.log('after update');
+  });
+
+  return () => (
+    <button onClick={() => count.value++}>
+      Count: {count.value}
+    </button>
+  );
+});
+```
+
+## Ref
+
+```tsx
+import { mount, ref } from 'lithent';
+
+const FocusInput = mount((renew) => {
+  const inputRef = ref<HTMLInputElement>(null);
+  return () => (
+    <div>
+      <input ref={inputRef} />
+      <button onClick={() => inputRef.value?.focus()}>Focus</button>
+    </div>
+  );
+});
+```
+
+## Portal
+
+```tsx
+import { mount, portal } from 'lithent';
+
+const Modal = mount((renew, props: { onClose: () => void }) => {
+  return () => portal(
+    <div class="modal" onClick={props.onClose}>Close</div>,
+    document.body
+  );
+});
+```
+
+## Context (mount + lmount)
+
+```tsx
+import { mount, lmount } from 'lithent';
+import { createContext, createLContext } from 'lithent/helper';
+
+const ThemeContext = createContext<{ theme: string }>();
+const LThemeContext = createLContext<{ theme: string }>();
+
+const ThemeProvider = mount((renew, _props, children) => {
+  return () => (
+    <ThemeContext.Provider value={{ theme: 'dark' }}>
+      {children}
+    </ThemeContext.Provider>
+  );
+});
+
+const LThemeProvider = lmount((_props, children) => {
+  return () => (
+    <LThemeContext.Provider value={{ theme: 'dark' }}>
+      {children}
+    </LThemeContext.Provider>
+  );
+});
+
+const Consumer = lmount(() => {
+  const { theme } = LThemeContext.useContext();
+  return () => <p>{theme}</p>;
+});
+```
+
+## Store (store + lstore)
+
+```tsx
+import { mount, lmount } from 'lithent';
+import { store, lstore } from 'lithent/helper';
+
+const userStore = store({ name: '', loggedIn: false });
+const userLStore = lstore({ name: '', loggedIn: false });
+
+const User = mount((renew) => {
+  const user = userStore(renew);
+  return () => <p>{user.name}</p>;
+});
+
+const UserLite = lmount(() => {
+  const user = userLStore();
+  return () => <p>{user.name}</p>;
+});
+```
+
+## Performance (cacheUpdate + nextTickRender)
+
+```ts
+import { cacheUpdate, nextTickRender } from 'lithent/helper';
+
+cacheUpdate(() => {
+  a.value = 1;
+  b.value = 2;
+});
+
+nextTickRender(() => {
+  items.value = [...items.value, ...more];
+});
+```
+
+## Children Helpers
+
+```tsx
+import { mount } from 'lithent';
+import { unwrapChildren } from 'lithent/helper';
+
+const Card = mount((renew, props: { title: string }, children) => {
+  return () => (
+    <div class="card">
+      <h3>{props.title}</h3>
+      {unwrapChildren(children)}
+    </div>
+  );
+});
+```

package/dist/skills/reference/children-type.md

@@ -0,0 +1,25 @@
+---
+title: Children Type
+category: reference
+version: 1.21.5
+---
+
+# Children Type
+
+- Lithent does **not** use `props.children`. Use the separate `children` argument.
+- Argument order: `mount(renew, props, children)` and `lmount(props, children)`.
+- Children are always `WDom[]`, even with a single child.
+- Children are only provided to the mounter; use closure inside the updater.
+
+```tsx
+import { mount, WDom } from 'lithent';
+
+const Panel = mount<{ title: string }>((renew, props, children: WDom[]) => {
+  return () => (
+    <section>
+      <h2>{props.title}</h2>
+      {children}
+    </section>
+  );
+});
+```

package/dist/skills/reference/lstore-inference.md

@@ -0,0 +1,19 @@
+---
+title: lstore Type Inference
+category: reference
+version: 1.21.5
+---
+
+# lstore Type Inference
+
+- Defining stores as **objects** is usually better than primitives.
+- Grouping related fields improves type inference and clarity.
+
+```tsx
+import { lstore } from 'lithent/helper';
+
+const userStore = lstore({
+  name: '',
+  loggedIn: false,
+});
+```

package/dist/skills/reference/props-types.md

@@ -0,0 +1,28 @@
+---
+title: Props Types
+category: reference
+version: 1.21.5
+---
+
+# Props Types
+
+- Props are the **second** argument to the mounter and the **first** argument to the updater.
+- The same props reference is preserved for the component’s lifetime.
+- For TypeScript, define the props type via a `mount`/`lmount` generic.
+- If you destructure props in the mounter, primitive values are copied and won’t update.
+  Prefer `props.property` or the updater’s props argument for fresh values.
+
+```tsx
+import { mount } from 'lithent';
+
+type Props = { count: number };
+
+const Counter = mount<Props>((renew, props) => {
+  return (updaterProps) => (
+    <div>
+      <p>props: {props.count}</p>
+      <p>updater: {updaterProps.count}</p>
+    </div>
+  );
+});
+```

package/package.json

@@ -1,7 +1,7 @@
 {
   "type": "module",
   "name": "lithent",
-  "version": "1.21.4",
+  "version": "1.21.5",
   "description": "An extensible virtual DOM library for lightweight use in a variety of environments.",
   "main": "./dist/lithent.umd.js",
   "module": "./dist/lithent.mjs",