lithent 1.22.0 → 1.23.0

package/README.md

@@ -53,6 +53,8 @@ npm install lithent
 ```html
 <script src="https://cdn.jsdelivr.net/npm/lithent/dist/lithent.umd.js"></script>
 <script src="https://cdn.jsdelivr.net/npm/lithent/ftags/dist/lithentFTags.umd.js"></script>
+<!-- Custom Elements (optional) -->
+<script src="https://cdn.jsdelivr.net/npm/lithent/element/dist/lithentElement.umd.js"></script>
 ```
 
 > **[📦 View all available CDN URLs](https://superlucky84.github.io/lithent/#/guide/quick-start)**
@@ -103,6 +105,18 @@ const Counter = lmount(() => {
 - **store / lstore** — Global state
 - **context / lcontext** — Cross-component data sharing
 
+### Custom Elements (optional)
+- **lithent/element** — Register a component as a standard Custom Element and embed it in any page (plain HTML, server templates, React, Vue) with a script and a tag. Shadow DOM style isolation, attribute/property props, DOM events. Under 1KB on top of the core.
+
+```js
+import { defineElement, emit } from 'lithent/element';
+
+defineElement('pay-button', PayButton, { props: { amount: Number } });
+// <pay-button amount="1000"></pay-button>
+```
+
+> **[🧩 Custom Elements guide](https://superlucky84.github.io/lithent/#/guide/element)**
+
 ### Template options
 - **JSX** — Via Vite plugin
 - **FTags** — Function-style tags (no build step)
@@ -122,8 +136,18 @@ const Counter = lmount(() => {
 | [lithent/ssr](https://www.npmjs.com/package/lithent) | Server‑side rendering |
 | [lithent/ftags](https://www.npmjs.com/package/lithent) | Function‑style tag API |
 | [lithent/tag](https://www.npmjs.com/package/lithent) | HTM template support |
+| [lithent/element](./element/README.md) | Register components as Custom Elements, embeddable in any page ([guide](https://superlucky84.github.io/lithent/#/guide/element)) |
+| [lithent-concurrent](./lithentConcurrent/README.md) | Separate core with priority scheduling and interruptible low-priority builds |
+| [lithent-concurrent/helper](./lithentConcurrent/README.md#lithent-concurrenthelper) | Deferred state and component-local pending queries |
 | [create-lithent](https://www.npmjs.com/package/create-lithent) | Project scaffolding tool |
 
+For expensive component trees, select the concurrent core with an exact
+`/^lithent$/` bundler alias. `deferRender` defers rendering while state writes
+remain immediate; `whenIdle` waits for deferred work. Keep urgent input and
+heavy rendering in separate components. See the [concurrent rendering
+guide](https://superlucky84.github.io/lithent/#/guide/concurrent-rendering) and
+[release notes](./CHANGELOG.md).
+
 <br />
 
 ## License

package/dist/lithent-agent-addon.md

@@ -1,6 +1,6 @@
 # Lithent Agent Addon
 
-> Version: 1.22.0
+> Version: 1.23.0
 
 You are a coding agent with Lithent virtual DOM guidance enabled.
 
@@ -47,7 +47,7 @@ CODING GUIDELINES:
 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
+   - Use `mountReadyCallback` for logic right after the WDom is created (before DOM insertion)
    - Place hooks in mounter function, not in updater
 
 5. LIST RENDERING
@@ -82,13 +82,32 @@ CODING GUIDELINES:
     - Access children as third parameter in mounter function
     - Don't modify children directly, wrap or filter them
 
+11. CONCURRENT RENDERING (only when `lithent-concurrent` is installed or requested)
+    - Suggest it only for very large trees (thousands of rows); plain `lithent` otherwise
+    - Select the core with an exact `/^lithent$/` alias; never alias `lithent/*` subpaths
+    - Keep urgent input state and the heavy list in separate components
+    - `deferRender` runs its scope synchronously; only rendering is deferred
+    - `await nextTick()` covers sync commits; use `await whenIdle()` for deferred renders
+    - `hasPendingRender` is a query, not reactive; show pending from a sync parent
+    - No Suspense or `use()`; updateCallback's return value is not an unmount cleanup
+
+12. CUSTOM ELEMENTS (when the user embeds UI in pages they do not own)
+    - Suggest `lithent/element`: `defineElement('my-widget', Component, { props: { amount: Number } })`
+    - Declared props are optional in the component (Boolean props are boolean); never require them
+    - Objects, arrays, functions go through properties; attributes only carry strings
+    - Use `props.host` with `emit(host, name, detail)` for events out; `host` is reserved
+    - Default is an open shadow root; ship CSS with `styles`, theme via CSS variables and `::part()`
+    - Avoid native property names (`title`, `hidden`) as props
+
 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'`
+- Concurrent (optional): `import { deferRender, whenIdle } from 'lithent-concurrent'` and `import { deferred, ldeferred, hasPendingRender } from 'lithent-concurrent/helper'`
 - SSR: `import { renderToString, hydration } from 'lithent/ssr'`
+- Custom Elements: `import { defineElement, emit } from 'lithent/element'`
 - FTags: `import { fTags, fFragment, fMount } from 'lithent/ftags'`
 - HTM: `import { lTag } from 'lithent/tag'`
 
@@ -116,11 +135,15 @@ COMMON MISTAKES TO CATCH:
 - Missing `key` prop in list iterations
 - Calling hooks inside updater instead of mounter
 - Mutating state directly instead of using `.value`
+- Using `deferRender` while the urgent state and heavy list share one component
+- Aliasing `lithent` with a prefix match so `lithent/helper` is rewritten too
 
 REFERENCE MATERIALS (NOT PART OF BEHAVIORAL RULES):
 
 For detailed code examples and API usage, refer to:
 node_modules/lithent/dist/skills/lithent/SKILL.md
+(concurrent details: node_modules/lithent/dist/skills/lithent/reference/concurrent.md)
+(custom elements: node_modules/lithent/dist/skills/lithent/reference/element.md)
 
 This reference material provides comprehensive examples, patterns,
 and import references that complement the behavioral guidelines above.