@inglorious/web 4.0.8 → 4.0.10

package/README.md

@@ -32,8 +32,8 @@ Unlike modern frameworks that invent their own languages or rely on signals, pro
 - **Zero Component State**  
   All state lives in the store — never inside components.
 
-- **No Signals, No Subscriptions, No Memory Leaks**  
-  Because every render is triggered by the store, and lit-html handles the rest.
+- **No Signals, No Subscriptions, No Framework-Level Memory Leaks**  
+  Because every render is triggered by the store, and lit-html handles the rest — no subscription cleanup needed.
 
 - **No compilation required**  
   Apps can run directly in the browser — no build/compile step is strictly necessary (though you may use bundlers or Vite for convenience in larger projects).
@@ -60,6 +60,8 @@ Use the scaffolder to create a starter app tailored to your workflow.
 
 ### ✨ **Inglorious Web re-renders the whole template tree on each state change.**
 
+**Important:** The DOM itself is not re-created. Only the template function reruns, and lit-html's efficient diffing updates just the changed DOM nodes.
+
 Thanks to lit-html's optimized diffing, this is fast, predictable, and surprisingly efficient.
 
 This means:
@@ -93,9 +95,16 @@ This framework is ideal for both small apps and large business UIs.
 
 ## When NOT to Use Inglorious Web
 
-- You need fine-grained reactivity for very large datasets (1000+ items per view)
-- You're building a library that needs to be framework-agnostic
-- Your team is already deeply invested in React/Vue/Angular
+- You're frequently mutating thousands of items without virtualization (though our `list` component handles this elegantly)
+- You need framework-agnostic components for users who might not use Inglorious (use Web Components instead)
+- Your team is already deeply invested in React/Vue/Angular and migration costs outweigh benefits
+
+## When Inglorious Web EXCELS
+
+- Building **internal component libraries** - Types are more customizable than React components
+- Creating **design systems** - Spread, override, and compose behaviors freely
+- Building **pattern libraries** - Ship pre-configured entity types that users can adapt
+- Apps where **predictable state flow** matters more than ecosystem size
 
 ---
 
@@ -141,7 +150,23 @@ This makes it especially suitable for:
 
 ## Comparison with Other Frameworks
 
-Here's how @inglorious/web compares to the major players:
+### TL;DR Quick Comparison
+
+| Framework      | Reactivity     | Build Transform  | Runtime Compiler | Component State | Bundle Size | Learning Curve |
+| -------------- | -------------- | ---------------- | ---------------- | --------------- | ----------- | -------------- |
+| Inglorious Web | Event-based    | None required    | No               | No (store only) | Tiny        | Very Low       |
+| React          | VDOM diffing   | JSX + optional\* | No               | Yes             | Large       | Medium/High    |
+| Vue            | Proxy-based    | SFC (optional)   | Available        | Yes             | Medium      | Medium         |
+| Svelte         | Compiler magic | Required         | No               | Yes             | Small       | Medium         |
+| SolidJS        | Fine signals   | JSX only         | No               | No (runs once)  | Tiny        | Medium/High    |
+| Qwik           | Resumable      | Required         | No               | Yes             | Small       | Very High      |
+
+\*React Compiler (stable 2024+) provides automatic memoization
+
+<details>
+<summary><strong>Click to expand detailed framework comparisons</strong></summary>
+
+Here's how @inglorious/web compares to the major players in detail:
 
 ---
 
@@ -220,6 +245,8 @@ Inglorious Web is minimal, predictable, and tiny.
 
 Inglorious Web is closer philosophically to **HTMX** and **vanilla JS**, but with a declarative rendering model and entity-based state.
 
+</details>
+
 ---
 
 ## Why Choose Inglorious Web
@@ -231,7 +258,7 @@ Inglorious Web is closer philosophically to **HTMX** and **vanilla JS**, but wit
 - One render path, no hidden rules
 - No reactivity graphs
 - No per-component subscriptions
-- No memory leaks
+- No framework-level memory leaks
 - No build step required (apps can run in the browser)
 - Works perfectly in hybrid UI/game engine contexts
 - Uses native ES modules and standards
@@ -1281,6 +1308,86 @@ See `src/list.js` in the package for the implementation details and the `example
 
 ---
 
+## Building Component Libraries with Inglorious Web
+
+**Inglorious types are uniquely suited for component libraries** because they're fully customizable through JavaScript's spread operator.
+
+### The Pattern
+
+**Library publishes types:**
+
+```javascript
+// @acme/design-system/table.js
+export const table = {
+  render(entity, api) {
+    const type = api.getType(entity.type)
+
+    return html`
+      <table>
+        ${entity.data.map((row) => type.renderRow(entity, row, api))}
+      </table>
+    `
+  },
+
+  renderRow(entity, row, api) {
+    return html`<tr>
+      ${row.name}
+    </tr>`
+  },
+
+  rowClick(entity, row) {
+    entity.selectedRow = row
+  },
+}
+```
+
+**Users customize freely:**
+
+```javascript
+import { table } from "@acme/design-system/table"
+
+// Use as-is
+const simpleTable = { ...table }
+
+// Override methods
+const customTable = {
+  ...table,
+  renderRow(entity, row, api) {
+    return html`<tr class="custom">
+      ${row.name} - ${row.email}
+    </tr>`
+  },
+}
+
+// Compose with behaviors
+import { sortable, exportable } from "@acme/design-system/behaviors"
+
+const advancedTable = [
+  table,
+  sortable,
+  exportable,
+  {
+    rowClick(entity, row) {
+      console.log("Custom click handler", row)
+    },
+  },
+]
+```
+
+### Why This Is Better Than React Components
+
+| Feature                    | React Components               | Inglorious Types                          |
+| -------------------------- | ------------------------------ | ----------------------------------------- |
+| Customize rendering        | Only if `render` prop exposed  | Override `render()` method directly       |
+| Customize behavior         | Only if callback props exposed | Override any method                       |
+| Compose multiple libraries | Wrapper hell / HOCs            | Array composition `[type1, type2, {...}]` |
+| Access internals           | Private - must fork            | Public - spread and override              |
+| Type safety                | Props interface                | Entity schema + method signatures         |
+
+**Users get complete control** without forking your library. They can override rendering, behavior, or both—down to individual methods.
+
+---
+
 ## Using Third-Party Web Components
 
 Inglorious Web works seamlessly with any Web Component library, such as Shoelace, Material Web Components, or Lion. Thanks to lit-html's efficient diffing algorithm, Web Components maintain their internal state even when the full tree re-renders - the component only updates when its properties change.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inglorious/web",
-  "version": "4.0.8",
+  "version": "4.0.10",
   "description": "A new web framework that leverages the power of the Inglorious Store combined with the performance and simplicity of lit-html.",
   "author": "IceOnFire <antony.mistretta@gmail.com> (https://ingloriouscoderz.it)",
   "license": "MIT",