lithent 1.21.2 → 1.21.4

package/dist/lithent-agent-addon.md

@@ -0,0 +1,126 @@
+# Lithent Agent Addon
+
+> Version: 1.21.4
+
+You are a coding agent with Lithent virtual DOM guidance enabled.
+
+ACTIVATION CONDITIONS:
+
+These guidelines apply ONLY when Lithent is installed in the current project.
+
+Before suggesting Lithent patterns, verify Lithent availability:
+1. Check if `package.json` contains lithent in dependencies or devDependencies
+2. Check if `node_modules/lithent` directory exists
+3. Check if lithent imports are present in existing code
+
+If Lithent is NOT installed:
+- Do not enforce these guidelines
+- Use standard coding practices appropriate for the project
+- Never suggest installing lithent unless explicitly requested
+
+If Lithent IS installed:
+- Apply all guidelines below
+- Suggest Lithent patterns for UI component creation
+- Prioritize closure-based state management patterns
+
+CODING GUIDELINES:
+
+1. COMPONENT MODE SELECTION
+   - Use `mount` for explicit render control with `renew()`
+   - Use `lmount` for automatic reactivity with `lstate`/`lstore`
+   - Don't mix modes: use `state`/`store` with `mount`, use `lstate`/`lstore` with `lmount`
+   - Suggest `lmount` for simpler components, `mount` for fine-grained control
+
+2. COMPONENT STRUCTURE
+   - Outer function (mounter) runs once for initialization
+   - Inner function (updater) runs on every render
+   - Keep state setup in mounter, return JSX from updater
+   - Always return a function from mounter, never JSX directly
+
+3. STATE MANAGEMENT
+   - Use `state(initialValue, renew)` with `mount` components
+   - Use `lstate(initialValue)` with `lmount` components
+   - Access values via `.value` property
+   - For global state, use `store`/`lstore` instead of prop drilling
+   - Use `computed` for derived values, `effect` for side effects
+
+4. LIFECYCLE HOOKS
+   - Use `mountCallback` for setup after mount (return cleanup function)
+   - Use `updateCallback` for logic before each update
+   - Use `mountReadyCallback` for logic after initial render
+   - Place hooks in mounter function, not in updater
+
+5. LIST RENDERING
+   - Always use `key` prop for list items
+   - Keys must be unique and stable (prefer IDs over indices)
+   - Suggest adding keys when iterating over arrays without them
+
+6. PERFORMANCE OPTIMIZATION
+   - Suggest `cacheUpdate` when multiple state updates cause re-renders
+   - Suggest `nextTickRender` for deferring expensive renders
+   - Avoid creating new functions in updater when possible
+   - Move event handlers to mounter scope when they don't need updater closure
+
+7. SSR AND HYDRATION
+   - Use `renderToString` for server-side rendering
+   - Use `hydration` flag with `render` for client-side hydration
+   - Ensure component output is deterministic for hydration to work
+
+8. TEMPLATE ALTERNATIVES
+   - Prefer JSX for most cases
+   - Suggest `fTags` for no-build-step environments
+   - Suggest `lTag` (HTM) for template literal preference
+   - Don't mix template styles within a single component
+
+9. CONTEXT USAGE
+   - Use `createContext` with `mount`, `createLContext` with `lmount`
+   - Pass `renew` to `useContext()` in manual mode
+   - Suggest context over deep prop drilling (3+ levels)
+
+10. CHILDREN HANDLING
+    - Use `unwrapChildren` helper when manipulating children
+    - Access children as third parameter in mounter function
+    - Don't modify children directly, wrap or filter them
+
+IMPORT PATHS:
+- Core: `import { mount, lmount, render, h, Fragment, portal, ref, nextTick } from 'lithent'`
+- Lifecycle: `import { mountCallback, updateCallback, mountReadyCallback } from 'lithent'`
+- Helper (manual): `import { state, store, createContext, computed, effect } from 'lithent/helper'`
+- Helper (light): `import { lstate, lstore, createLContext } from 'lithent/helper'`
+- Helper (utils): `import { cacheUpdate, nextTickRender, unwrapChildren } from 'lithent/helper'`
+- SSR: `import { renderToString, hydration } from 'lithent/ssr'`
+- FTags: `import { fTags, fFragment, fMount } from 'lithent/ftags'`
+- HTM: `import { lTag } from 'lithent/tag'`
+
+GUIDANCE APPROACH:
+
+When user creates UI components:
+1. Suggest appropriate component mode (mount vs lmount)
+2. Ensure proper mounter/updater structure
+3. Add keys to list renderings if missing
+
+When reviewing existing Lithent code:
+1. Check for mode consistency (don't mix state/lstate)
+2. Suggest lifecycle hooks for side effects
+3. Recommend performance optimizations when applicable
+
+When user requests could benefit from Lithent patterns:
+1. Provide solution using Lithent idioms
+2. Explain the closure-based component model
+3. If user prefers different approach, respect their choice
+
+COMMON MISTAKES TO CATCH:
+- Returning JSX directly from mounter instead of returning a function
+- Using `state` without passing `renew` parameter
+- Using `lstate` with `mount` instead of `lmount`
+- Missing `key` prop in list iterations
+- Calling hooks inside updater instead of mounter
+- Mutating state directly instead of using `.value`
+
+REFERENCE MATERIALS (NOT PART OF BEHAVIORAL RULES):
+
+For detailed code examples and API usage, refer to:
+node_modules/lithent/dist/lithent-skills.md
+
+This reference material provides comprehensive examples, patterns,
+and import references that complement the behavioral guidelines above.

package/dist/lithent-skills.md

@@ -0,0 +1,365 @@
+# Lithent Agent Skills
+
+> Version: 1.21.4
+
+This file provides AI agent skills for working with the Lithent library.
+
+## Overview
+
+Lithent is a lightweight (~4KB) JSX-based virtual DOM library with closure-based state management. It offers two component modes:
+- **Manual Mode** (`mount`): Explicit control with `renew()` function
+- **Light API Mode** (`lmount`): Auto-reactive with `lstate`/`lstore`
+
+## Component Creation
+
+### Manual Mode (mount)
+
+```tsx
+import { mount, render } from 'lithent';
+import { state } from 'lithent/helper';
+
+const Counter = mount<{ initial?: number }>((renew, props) => {
+  const count = state(props.initial ?? 0, renew);
+
+  return () => (
+    <div>
+      <p>Count: {count.value}</p>
+      <button onClick={() => count.value++}>+1</button>
+    </div>
+  );
+});
+
+render(<Counter initial={10} />, document.getElementById('app')!);
+```
+
+### Light API Mode (lmount)
+
+```tsx
+import { lmount, render } from 'lithent';
+import { lstate } from 'lithent/helper';
+
+const Counter = lmount<{ initial?: number }>((props) => {
+  const count = lstate(props.initial ?? 0);
+
+  return () => (
+    <div>
+      <p>Count: {count.value}</p>
+      <button onClick={() => count.value++}>+1</button>
+    </div>
+  );
+});
+
+render(<Counter initial={10} />, document.getElementById('app')!);
+```
+
+## State Management
+
+### State (Manual Mode)
+
+```tsx
+import { mount } from 'lithent';
+import { state, computed, effect } from 'lithent/helper';
+
+const Component = mount((renew) => {
+  const firstName = state('John', renew);
+  const lastName = state('Doe', renew);
+
+  // Derived value
+  const fullName = computed(() => `${firstName.value} ${lastName.value}`);
+
+  // Side effect
+  effect(() => {
+    console.log('Name changed:', fullName.value);
+    return () => console.log('Cleanup');
+  });
+
+  return () => <p>{fullName.value}</p>;
+});
+```
+
+### State (Light API Mode)
+
+```tsx
+import { lmount } from 'lithent';
+import { lstate, computed, effect } from 'lithent/helper';
+
+const Component = lmount(() => {
+  const firstName = lstate('John');
+  const lastName = lstate('Doe');
+
+  const fullName = computed(() => `${firstName.value} ${lastName.value}`);
+
+  effect(() => {
+    console.log('Name changed:', fullName.value);
+  });
+
+  return () => <p>{fullName.value}</p>;
+});
+```
+
+### Global Store
+
+```tsx
+// Manual Mode
+import { store } from 'lithent/helper';
+const userStore = store({ name: '', loggedIn: false });
+
+const Component = mount((renew) => {
+  const user = userStore(renew);
+  return () => <p>{user.name}</p>;
+});
+
+// Light API Mode
+import { lstore } from 'lithent/helper';
+const userStore = lstore({ name: '', loggedIn: false });
+
+const Component = lmount(() => {
+  const user = userStore();
+  return () => <p>{user.name}</p>;
+});
+```
+
+## Lifecycle Hooks
+
+```tsx
+import { mount, mountCallback, updateCallback, mountReadyCallback } from 'lithent';
+
+const Component = mount((renew) => {
+  // After mount (return cleanup function for unmount)
+  mountCallback(() => {
+    console.log('Mounted');
+    return () => console.log('Unmounted');
+  });
+
+  // Before each update
+  updateCallback(() => {
+    console.log('Will update');
+  });
+
+  // After initial render complete
+  mountReadyCallback(() => {
+    console.log('Initial render done');
+  });
+
+  return () => <div>Hello</div>;
+});
+```
+
+## DOM References
+
+```tsx
+import { mount, ref } from 'lithent';
+
+const Component = mount((renew) => {
+  const inputRef = ref<HTMLInputElement>(null);
+
+  const focusInput = () => inputRef.value?.focus();
+
+  return () => (
+    <div>
+      <input ref={inputRef} type="text" />
+      <button onClick={focusInput}>Focus</button>
+    </div>
+  );
+});
+```
+
+## Context API
+
+```tsx
+// Manual Mode
+import { mount } from 'lithent';
+import { createContext } from 'lithent/helper';
+
+const ThemeContext = createContext<{ theme: string }>();
+
+const Provider = mount((renew, _props, children) => {
+  return () => (
+    <ThemeContext.Provider value={{ theme: 'dark' }}>
+      {children}
+    </ThemeContext.Provider>
+  );
+});
+
+const Consumer = mount((renew) => {
+  const { theme } = ThemeContext.useContext(renew);
+  return () => <p>{theme}</p>;
+});
+
+// Light API Mode
+import { lmount } from 'lithent';
+import { createLContext } from 'lithent/helper';
+
+const ThemeContext = createLContext<{ theme: string }>();
+
+const Consumer = lmount(() => {
+  const { theme } = ThemeContext.useContext();
+  return () => <p>{theme}</p>;
+});
+```
+
+## Portal
+
+```tsx
+import { mount, portal } from 'lithent';
+
+const Modal = mount((renew, props: { onClose: () => void }) => {
+  return () => portal(
+    <div class="modal-overlay" onClick={props.onClose}>
+      <div class="modal-content" onClick={(e) => e.stopPropagation()}>
+        <h2>Modal</h2>
+        <button onClick={props.onClose}>Close</button>
+      </div>
+    </div>,
+    document.body
+  );
+});
+```
+
+## List Rendering
+
+Always use `key` prop for lists:
+
+```tsx
+import { mount } from 'lithent';
+import { state } from 'lithent/helper';
+
+const TodoList = mount((renew) => {
+  const todos = state([
+    { id: 1, text: 'Learn Lithent', done: false },
+    { id: 2, text: 'Build app', done: false },
+  ], renew);
+
+  const toggle = (id: number) => {
+    todos.value = todos.value.map(t =>
+      t.id === id ? { ...t, done: !t.done } : t
+    );
+  };
+
+  return () => (
+    <ul>
+      {todos.value.map(todo => (
+        <li key={todo.id} onClick={() => toggle(todo.id)}>
+          {todo.text} {todo.done && '✓'}
+        </li>
+      ))}
+    </ul>
+  );
+});
+```
+
+## SSR and Hydration
+
+```tsx
+// Server
+import { renderToString } from 'lithent/ssr';
+const html = renderToString(<App />);
+
+// Client (hydrate existing DOM)
+import { render } from 'lithent';
+import { hydration } from 'lithent/ssr';
+render(<App />, document.getElementById('app')!, hydration);
+```
+
+## FTags (No JSX)
+
+```ts
+import { fTags, fMount } from 'lithent/ftags';
+import { state } from 'lithent/helper';
+
+const { div, button, p } = fTags;
+
+const Counter = fMount((renew) => {
+  const count = state(0, renew);
+  return () => div({},
+    p({}, `Count: ${count.value}`),
+    button({ onClick: () => count.value++ }, '+1')
+  );
+});
+```
+
+## HTM (Tagged Templates)
+
+```ts
+import { lTag } from 'lithent/tag';
+import { mount } from 'lithent';
+import { state } from 'lithent/helper';
+
+const html = lTag;
+
+const Counter = mount((renew) => {
+  const count = state(0, renew);
+  return () => html`
+    <div>
+      <p>Count: ${count.value}</p>
+      <button onClick=${() => count.value++}>+1</button>
+    </div>
+  `;
+});
+```
+
+## Performance
+
+```tsx
+import { cacheUpdate, nextTickRender } from 'lithent/helper';
+
+// Batch multiple state updates into single render
+cacheUpdate(() => {
+  a.value = 1;
+  b.value = 2;
+  c.value = 3;
+});
+
+// Defer render to next tick
+nextTickRender(() => {
+  items.value = [...items.value, ...newItems];
+});
+```
+
+## Children Handling
+
+```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>
+      <div class="card-body">{unwrapChildren(children)}</div>
+    </div>
+  );
+});
+
+// Usage
+<Card title="Title"><p>Content</p></Card>
+```
+
+## Import Reference
+
+```tsx
+// Core
+import {
+  mount, lmount, render, h, Fragment, portal,
+  ref, nextTick, mountCallback, updateCallback, mountReadyCallback
+} from 'lithent';
+
+// Helper
+import {
+  state, lstate,                    // Reactive state
+  computed, effect,                 // Derived values & side effects
+  store, lstore,                    // Global state
+  createContext, createLContext,   // Context API
+  cacheUpdate, nextTickRender,     // Performance
+  unwrapChildren                    // Utility
+} from 'lithent/helper';
+
+// SSR
+import { renderToString, hydration } from 'lithent/ssr';
+
+// FTags
+import { fTags, fFragment, fMount } from 'lithent/ftags';
+
+// HTM
+import { lTag } from 'lithent/tag';
+```