npm - liveinit - Versions diffs - 0.1.0 - Mend

liveinit 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (18) hide show

package/LICENSE +21 -0
package/README.md +113 -0
package/dist/liveinit.min.js +2 -0
package/docs/api.md +72 -0
package/docs/initCommands.md +111 -0
package/docs/initComponents.md +114 -0
package/docs/lazy.md +36 -0
package/docs/observer.md +65 -0
package/docs/parseConfig.md +39 -0
package/package.json +46 -0
package/src/auto.js +33 -0
package/src/index.js +15 -0
package/src/initCommands.js +86 -0
package/src/initComponents.js +156 -0
package/src/lazy.js +44 -0
package/src/observeOpenShadowRoots.js +47 -0
package/src/observer.js +121 -0
package/src/parseConfig.js +46 -0

package/LICENSE ADDED Viewed

@@ -0,0 +1,21 @@
+MIT License
+Copyright (c) 2026 Thomas Portelange
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md ADDED Viewed

@@ -0,0 +1,113 @@
+# liveinit
+A radically lean, ultra-fast, HTML-first application loader and DOM lifecycle observer.
+`liveinit` provides a robust architecture for initializing Javascript components and delegating stateless actions safely without memory leaks, massive framework overhead, or Virtual DOMs. It bridges the gap between server-rendered HTML and client-side interactivity by turning standard HTML data attributes into reactive lifecycle hooks and event delegations.
+It is heavily inspired by Stimulus, Alpine, and GitHub Catalyst, but stripped down to the absolute bare minimum (~150 lines of dependency-free modern Javascript).
+## Key Advantages
+- **Zero Global Listeners Overhead:** The declarative `data-command` engine uses a single, global event listener delegator that catches bubbling actions. No tracking individual buttons, no multiple active listeners—saving memory and CPU.
+- **GC & Memory Safe:** `initComponents` seamlessly constructs an `AbortController`. When DOM nodes are removed or replaced (e.g., via AJAX/HTMX), all associated event listeners are instantly aborted and garbage collected cleanly.
+- **O(1) Evaluation Pattern:** Instead of walking entire DOM trees upon mutations, the core observer relies on blazing-fast native `querySelectorAll` with pre-compiled CSS strings.
+- **Graceful Lazy-Loading:** Built-in `IntersectionObserver` optionally defers executing components until the user actually scrolls the element into view.
+- **HTML-first:** Maintain beautiful, standard HTML strings. The parser natively understands relaxed JSON configuration strings, requiring no compilation steps or esoteric syntax constraints inside your templates.
+## Quick Start
+**CDN / no-build (fastest setup):**
+```html
+<script src="https://cdn.jsdelivr.net/npm/liveinit@0.1.0/dist/liveinit.min.js" defer></script>
+```
+```html
+<div data-component="Counter" data-component-config="start: 10"></div>
+<button data-command="refresh" data-command-for="#my-table">Reload Data</button>
+<table id="my-table"></table>
+<script>
+  class Counter {
+    constructor(el, config) {
+      el.textContent = `Count: ${config.start || 0}`;
+    }
+  }
+  window.Counter = Counter; // default resolver reads from window
+  document.addEventListener("command:refresh", () => {
+    console.log("refresh table");
+  });
+</script>
+```
+**Everything is configurable** (custom attributes, event list, resolver, lifecycle hooks, lazy behavior).
+See [docs/initComponents.md](docs/initComponents.md) and [docs/initCommands.md](docs/initCommands.md) for full options.
+### Safe Script Loading
+`liveinit` is structurally immune to script load order issues because of its core architecture:
+1. **MutationObserver foundation**: Even if `liveinit` executes before your HTML finishes rendering, it will instantly catch and initialize elements as they stream into the `<body>`.
+2. **Global Delegation**: `initCommands()` attaches listeners to the document root, meaning it doesn't care if the target buttons exist yet or are added asynchronously later.
+To guarantee zero race-conditions and best performance, load the script high up in the document (like the `<head>`) with `defer`:
+```html
+<script src="..." defer></script>
+```
+**Bundler usage:**
+```javascript
+import { initComponents, initCommands } from "liveinit";
+initComponents({
+  dropdown: () => import("./components/dropdown.js"),
+  "heavy-map": () => import("./components/map.js"),
+});
+initCommands();
+```
+## Documentation
+The library consists of modular, standalone pieces you can use together or separately:
+1. **[API Contract](docs/api.md)** - Stable public exports and return shapes.
+2. **[Init Components Engine](docs/initComponents.md)** (`initComponents.js`) - The main application loader tying everything together.
+3. **[Command Engine](docs/initCommands.md)** (`initCommands.js`) - The global configurable event delegator for stateless HTML actions.
+4. **[Selector Observer](docs/observer.md)** (`observer.js`) - The ultra-fast MutationObserver wrapper.
+5. **[Lazy Init](docs/lazy.md)** (`lazy.js`) - The IntersectionObserver bindings for deferred loading.
+6. **[Data Config](docs/parseConfig.md)** (`parseConfig.js`) - A relaxed, HTML-friendly JSON parser.
+## Browser Support
+- `liveinit` targets browsers with native ES modules (`<script type="module">`) and modern DOM APIs.
+- `IntersectionObserver` is optional:
+  if unavailable, `lazy()` falls back to immediate initialization instead of throwing.
+- The table below reflects the baseline for the **full feature set** (`type="module"` + `AbortController` + core DOM APIs used by this library).
+| Browser | Minimum version | First stable release |
+|---------|-----------------|----------------------|
+| Chrome  | 66              | April 17, 2018       |
+| Firefox | 57              | November 14, 2017    |
+| Safari  | 12.1            | March 25, 2019       |
+| Edge    | 16              | October 17, 2017     |
+- `IntersectionObserver` remains optional (lazy init degrades to immediate init).
+- Quick checks on caniuse:
+  - ES modules: <https://caniuse.com/es6-module>
+  - IntersectionObserver: <https://caniuse.com/intersectionobserver>
+  - AbortController: <https://caniuse.com/abortcontroller>
+## Semver Policy
+- Patch releases (`x.y.z`) include bug fixes and internal changes only.
+- Minor releases (`x.y.0`) can add new features/options in backward-compatible ways.
+- Major releases (`x.0.0`) are used for breaking changes.
+Breaking changes include:
+- Renaming/removing public exports from `liveinit`.
+- Changing default attribute names or command event naming behavior.
+- Changing lifecycle contracts (for example return shapes from `initCommands()` or observer engine APIs).
+- Raising the documented browser support baseline.

package/dist/liveinit.min.js ADDED Viewed

	@@ -0,0 +1,2 @@
1	+ /! liveinit \| https://github.com/lekoala/liveinit \| @license MIT /
2	+ (()=>{var{defineProperty:C,getOwnPropertyNames:S,getOwnPropertyDescriptor:y}=Object,p=Object.prototype.hasOwnProperty;var N=new WeakMap,b=(J)=>{var B=N.get(J),Q;if(B)return B;if(B=C({},"__esModule",{value:!0}),J&&typeof J==="object"\|\|typeof J==="function")S(J).map((W)=>!p.call(B,W)&&C(B,W,{get:()=>J[W],enumerable:!(Q=y(J,W))\|\|Q.enumerable}));return N.set(J,B),B};var h=(J,B)=>{for(var Q in B)C(J,Q,{get:B[Q],enumerable:!0,configurable:!0,set:(W)=>B[Q]=()=>W})};var u={};h(u,{default:()=>g});var w={};h(w,{parseConfig:()=>P,observer:()=>k,observeOpenShadowRoots:()=>j,lazy:()=>M,initComponents:()=>q,initCommands:()=>I});function P(J){if(typeof J!=="string")return{};let B=J.trim();if(B==="")return{};if(B=B.replace(/([a-zA-Z_$][\w$-])\s:\|'((?:\\'\|[^'])*)'/g,(Q,W,L)=>{if(W)return`"${W}":`;return`"${L.replace(/\\'/g,"'").replace(/"/g,"\\\"")}"`}),!B.startsWith("{"))B=`{${B}}`;try{return JSON.parse(B)}catch(Q){return console.error(`Failed to parse: ${J}`),{}}}function I(J={}){let B=J.attribute\|\|"data-command",Q=B.replace(/^data-/,""),W=`${B}-on`,L=`${B}-for`,K=`${B}-config`,D=J.events\|\|["click","change","input","submit","focusin","focusout"],O={handleEvent(G){let Z=G&&G.target;if(!Z\|\|typeof Z.closest!=="function")return;let U=Z.closest(`[${B}]`);if(!U)return;let H=U.getAttribute(W)\|\|"click",X=G.type;if(X!==H)return;if(X!=="focusin"&&X!=="focusout")G.preventDefault();let V=U.getAttribute(B),_=U.getAttribute(L),Y=U.getAttribute(K),$=P(Y?Y:"{}"),F=U;if(_)try{F=document.querySelector(_)}catch(T){return}if(F)F.dispatchEvent(new CustomEvent(`${Q}:${V}`,{detail:{originalEvent:G,config:$,trigger:U},bubbles:!0}))}};for(let G=0,Z=D.length;G<Z;G++)document.addEventListener(D[G],O);let x=!0;return{disconnect(){if(!x)return;x=!1;for(let G=0,Z=D.length;G<Z;G++)document.removeEventListener(D[G],O)}}}var E=new WeakMap,A;if(typeof window<"u"&&"IntersectionObserver"in window)A=new IntersectionObserver((J,B)=>{let Q=J.filter((W)=>W.isIntersecting);for(let W=0,L=Q.length;W<L;W++){let K=Q[W].target;B.unobserve(K);let D=E.get(K);if(E.delete(K),D)D(K)}});function M(J,B){if(!A)return B(J),()=>{};return E.set(J,B),A.observe(J),()=>{return E.delete(J),A.unobserve(J)}}function k(J,B,Q=document){let W=new WeakMap;if(!J\|\|!J.length)throw Error("observer requires an array of CSS selector queries.");let L=J.join(","),K=(G,Z)=>{if(!G.matches)return;let U=W.get(G);if(Z)for(let H=0,X=J.length;H<X;H++){let V=J[H];if(G.matches(V)){if(!U)U=new Set,W.set(G,U);if(!U.has(V))U.add(V),B(G,!0,V)}}else if(U)W.delete(G),U.forEach((H)=>{B(G,!1,H)})},D=(G,Z,U,H)=>{if(Z){if(!U.has(G))U.add(G),H.delete(G),K(G,!0)}else if(!H.has(G))H.add(G),U.delete(G),K(G,!1);let X=G.querySelectorAll(L);for(let V=0,_=X.length;V<_;V++){let Y=X[V];if(Z){if(!U.has(Y))U.add(Y),H.delete(Y),K(Y,!0)}else if(!H.has(Y))H.add(Y),U.delete(Y),K(Y,!1)}},O=new MutationObserver((G)=>{let Z=new Set,U=new Set;for(let H=0,X=G.length;H<X;H++){let{addedNodes:V,removedNodes:_}=G[H];for(let Y=0,$=_.length;Y<$;Y++){let F=_[Y];if(F.nodeType===1)D(F,!1,Z,U)}for(let Y=0,$=V.length;Y<$;Y++){let F=V[Y];if(F.nodeType===1)D(F,!0,Z,U)}}});O.observe(Q,{childList:!0,subtree:!0});let x=(G,Z=!0)=>{let U=G instanceof NodeList\|\|Array.isArray(G)?G:[G];for(let H=0,X=U.length;H<X;H++)if(U[H].nodeType===1)K(U[H],Z)};return x(Q.querySelectorAll(L),!0),{evaluate:x,forget:(G)=>W.delete(G),disconnect:()=>O.disconnect()}}function q(J=null,B={}){let Q=B.attribute\|\|"data-component",W=B.lazyAttribute\|\|"data-lazy",L=B.signalKey\|\|"signal",K=B.destroyMethod\|\|"destroy",D=new WeakMap,O=async(H)=>{if(J&&J[H]){let X=await J[H]();return X.default\|\|X}if(window[H])return window[H];return console.warn(`[liveinit] Module '${H}' not found in Registry or global scope.`),null},x=B.resolve\|\|O,G=k([`[${Q}]`],(H,X)=>{if(X){let V=H.getAttribute(`${Q}-config`),_=P(V),Y=H.getAttribute(Q),$={abortController:new AbortController,cancelLazy:null,appModule:null,failed:!1};D.set(H,$),_[L]=$.abortController.signal;let F=async()=>{try{let T=await x(Y);if(T&&!$.abortController.signal.aborted)$.appModule=new T(H,_),$.failed=!1;else if(!T)$.failed=!0}catch(T){$.failed=!0,console.error(T)}};if(H.hasAttribute(W))$.cancelLazy=M(H,F);else F()}else{let V=D.get(H);if(!V)return;if(V.abortController)V.abortController.abort();if(V.cancelLazy)V.cancelLazy();if(V.appModule&&typeof V.appModule[K]==="function")V.appModule[K]();D.delete(H)}}),Z=(H)=>{let X=[];if(!H)return X;if(typeof H.querySelectorAll==="function"){let V=H.querySelectorAll(`[${Q}]`);for(let _=0,Y=V.length;_<Y;_++)X.push(V[_])}if(typeof H.matches==="function"&&H.matches(`[${Q}]`))X.push(H);return X},U=(H=document)=>{let X=Z(H),V=0;for(let _=0,Y=X.length;_<Y;_++){let $=X[_],F=D.get($);if(!F\|\|!F.failed)continue;V++,G.forget($),G.evaluate($,!0)}return V};return{evaluate:G.evaluate,retryFailed:U,forget:G.forget,disconnect:G.disconnect}}var R=new Set,z=null;function j(J){if(typeof J!=="function")throw Error("observeOpenShadowRoots requires an observe callback.");if(typeof Element>"u"\|\|!Element.prototype.attachShadow)return()=>{};if(!z)z=Element.prototype.attachShadow,Element.prototype.attachShadow=function(Q){let W=z.call(this,Q);if(Q&&Q.mode==="open")R.forEach((L)=>{L(W)});return W};R.add(J);let B=!0;return()=>{if(!B)return;if(B=!1,R.delete(J),!R.size&&z)Element.prototype.attachShadow=z,z=null}}I();var f=q();if(typeof document<"u")document.addEventListener("liveinit:refresh",(J)=>{let B=J&&J.detail?J.detail:null,Q=B&&B.root?B.root:document;if(!Q\|\|typeof Q.querySelectorAll!=="function")return;if(f.evaluate(Q.querySelectorAll("[data-component]"),!0),Q.matches&&Q.matches("[data-component]"))f.evaluate(Q,!0);f.retryFailed(Q)});if(typeof window<"u")window.liveinit=w;var g=w;})();

package/docs/api.md ADDED Viewed

@@ -0,0 +1,72 @@
+# API Contract
+This document defines the public API exposed by `liveinit`.
+## Exports
+```javascript
+import {
+  initCommands,
+  initComponents,
+  lazy,
+  observeOpenShadowRoots,
+  observer,
+  parseConfig
+} from "liveinit";
+```
+## Functions
+### `initComponents(Registry?, options?)`
+Initializes component lifecycle handling for elements matching `data-component` (configurable).
+- Returns: `{ evaluate, retryFailed, forget, disconnect }` (observer engine handle)
+- Notes:
+  - supports global resolver fallback (`window[ComponentName]`) when no registry entry exists
+  - injects an `AbortSignal` into component config (default key: `signal`)
+  - supports optional lazy init via `data-lazy` (configurable)
+  - `retryFailed(root?)` retries components that previously failed to resolve
+### `initCommands(options?)`
+Initializes global command delegation for stateless event dispatching.
+- Returns: `{ disconnect }`
+- Notes:
+  - each call creates a new listener set
+  - call `disconnect()` before re-initializing in HMR/microfrontend contexts
+### `observer(queries, callback, root?)`
+MutationObserver wrapper for fixed selector matching.
+- Returns: `{ evaluate, forget, disconnect }`
+- Notes:
+  - safe by default: does not patch `Element.prototype.attachShadow`
+### `observeOpenShadowRoots(observe)`
+Opt-in bridge for future open shadow roots.
+- Returns: `() => void` (cleanup function)
+- Notes:
+  - subscribes to newly created open shadow roots only
+  - restores original `attachShadow` when last subscriber is removed
+### `lazy(el, cb)`
+Executes `cb` when `el` intersects viewport.
+- Returns: `() => void` (cleanup function)
+- Notes:
+  - degrades gracefully when `IntersectionObserver` is unavailable (runs immediately)
+### `parseConfig(str)`
+Parses relaxed HTML-friendly config strings into objects.
+- Returns: `object`
+- Notes:
+  - supports unquoted keys and single-quoted strings
+  - invalid input returns `{}` (does not throw)

package/docs/initCommands.md ADDED Viewed

@@ -0,0 +1,111 @@
+# Init Commands (`initCommands.js`)
+A global event delegation engine designed to handle stateless actions declaratively from HTML variables without writing repetitive event listeners.
+## Overview
+Instead of tracking every button's insertion and removal to attach/detach event listeners, the command engine uses a single, global event listener on the `document` that catches bubbling events and parses their custom target and actions. It then emits a standardized `CustomEvent` that your Javascript modules can listen for.
+### Relation to the Open UI Invokers API
+This engine takes heavy inspiration from the [Open UI Invokers API Explainer](https://open-ui.org/components/invokers.explainer/) (the native `command` and `commandfor` HTML attributes), but diverges to provide a generic, framework-like event bus.
+**How it's similar:**
+- It allows declarative, HTML-only event delegation without manual `addEventListener` scripts.
+- It relies on a source `trigger` pointing to a destination `target` using an ID or CSS selector.
+**How it's different & better for our needs:**
+1. **No Polyfill Overhead:** Native `command/commandfor` requires heavy polyfilling for general-purpose use, interfering with shadow DOMs and native prototypes. This engine is pure and lightweight.
+2. **Beyond Clicks:** The native spec is strictly tied to buttons and clicks. Our engine scales to `input`, `change`, `submit`, `focusin`, and `focusout` via the `data-command-on` attribute.
+3. **No `--custom` Syntax:** The native spec forces custom actions to use a CSS-variable-like syntax (e.g., `command="--my-action"`). We just use standard strings (`data-command="refresh"`).
+4. **Rich Configuration:** We built in native JSON configuration strings (`data-command-config`) via `parseConfig.js` to easily pass complex arguments to your controllers.
+## Usage
+Just import the initialization function into your main entry file to start tracking events:
+```javascript
+import { initCommands } from 'liveinit';
+// The engine binds to the document. Custom data attributes and events can be passed here.
+const commandEngine = initCommands({
+  attribute: "data-command", // Default
+  events: ["click", "change", "input", "submit", "focusin", "focusout"] // Default
+});
+// Later, cleanup listeners if needed (HMR, teardown, tests, microfrontends)
+commandEngine.disconnect();
+```
+`initCommands()` creates a new listener set on each call. In environments like HMR or microfrontends, keep the returned handle and call `disconnect()` before re-initializing to avoid duplicate command dispatches.
+### HTML Setup
+The engine relies on `[data-command]` (configurable) attributes to dispatch standard events.
+**Basic Click Example:**
+```html
+<!-- Clicking this dispatches a `command:refresh` event targeting the `#table` -->
+<button data-command="refresh" data-command-for="#table">Refresh</button>
+```
+**Custom Events:**
+By default, the engine listens for `click` events. To listen for other bubbling actions (`change`, `input`, `submit`, `focusin`, `focusout`), use the `data-command-on` attribute.
+```html
+<!-- Fires whenever the user types -->
+<input type="search" data-command="search" data-command-on="input" data-command-for="#table">
+<!-- Intercepts form submissions -->
+<form data-command="save" data-command-on="submit" data-command-for="#table">
+  ...
+</form>
+```
+**Custom Configurations:**
+To pass extra parameters to the command, use `data-command-config`.
+```html
+<button data-command="refresh" data-command-for="#table" data-command-config="silent: true">
+  Silent Refresh
+</button>
+```
+### Listening for Commands
+Inside your components or Javascript, you listen to the emitted `{prefix}:{action}` event on the target element.
+If your configured attribute is `data-command`, the prefix is `command`. If you configure it to `data-action`, the prefix becomes `action`.
+```javascript
+const table = document.querySelector("#table");
+// Assuming the default `data-command` attribute:
+table.addEventListener("command:refresh", (event) => {
+  // Extract custom configuration
+  const isSilent = event.detail.config.silent;
+  // See which element actually triggered the command
+  const buttonEl = event.detail.trigger;
+  // Access the original bubbling event (e.g. MouseEvent or SubmitEvent)
+  const originalEvent = event.detail.originalEvent;
+  console.log("Refreshing table...", isSilent);
+});
+```
+## Supported Events
+The global delegator currently listens for and supports intercepting:
+- `click` (default)
+- `change`
+- `input`
+- `submit`
+- `focusin`
+- `focusout`
+*(Note: The engine natively suppresses default browser behaviors like form submissions or hash link jumping automatically when catching these commands, except for focus events).*

package/docs/initComponents.md ADDED Viewed

@@ -0,0 +1,114 @@
+# Init Components Engine (`initComponents.js`)
+The high-level component initializer that wires together the `observer`, `lazy` intersection observations, and parsed `parseConfig` configuration.
+## Overview
+`initComponents` is designed to be the main entry point for HTML-first applications. It watches the DOM for specific attributes, parses configuration strings safely, and dynamically lazy-loads and instantiates classes when they enter the DOM.
+## Usage
+```javascript
+import { initComponents } from 'liveinit';
+// ---------- Method 1: Zero Setup (Global Scope) ----------
+// If a component is attached to the window (e.g., `window.Dropdown`)
+// this will automatically instantiate `<div data-component="Dropdown">`
+initComponents();
+// ---------- Method 2: Standard Registry (Code-Splitting) ----------
+// Dictionary mapping the module names (HTML attribute values)
+// to dynamic imports for lazy loading.
+const Registry = {
+  'datatable': () => import('./components/datatable.js'),
+  'heavy-map': () => import('./components/map.js')
+};
+initComponents(Registry);
+// ---------- Method 3: Advanced Options & Custom Resolvers ----------
+initComponents(null, {
+  attribute: 'data-widget',        // Default: data-component
+  lazyAttribute: 'data-defer',     // Default: data-lazy
+  signalKey: 'abortSignal',        // Default: signal
+  destroyMethod: 'dispose',        // Default: destroy
+  resolve: async (name) => {
+    // Write your own logic (e.g. Vite glob imports)
+    const modules = import.meta.glob('./widgets/*.js');
+    const imported = await modules[`./widgets/${name}.js`]();
+    return imported.default;
+  }
+});
+```
+### HTML Setup
+**Immediate Initialization:**
+When the HTML node enters the DOM, it immediately imports the datatable component and initializes it.
+```html
+<div data-component="datatable" data-component-config="pageLength: 25"></div>
+```
+**Lazy Initialization:**
+By adding the `data-lazy` attribute, the loader waits until the element is scrolled into view (using `IntersectionObserver`) before it downloads and executes the component code.
+```html
+<div data-component="heavy-map" data-component-config="lat: 50.85, lng: 4.35" data-lazy></div>
+```
+### Component Structure
+Your JavaScript component classes will receive two arguments upon instantiation: the DOM `Element`, and a `config` object containing the parsed dataset configurations.
+By default, an `AbortSignal` is automatically injected into the config as `config.signal` (configurable via `options.signalKey`) to elegantly handle event cleanup when DOM nodes are removed.
+```javascript
+export default class DataTable {
+  constructor(element, config) {
+    this.element = element;
+    // Config properties parsed from `data-component-config`
+    this.pageLength = config.pageLength || 10;
+    // Automatically cleaned up when the element leaves the DOM!
+    window.addEventListener("resize", this.handleResize, { signal: config.signal });
+  }
+  // Optional teardown triggered automatically if the node is removed from the DOM
+  // (Configurable via options.destroyMethod, defaults to "destroy")
+  destroy() {
+    console.log("Datatable unmounted safely.");
+  }
+}
+```
+## How It Works
+1. Uses `observer.js` to strictly track DOM insertion and removal.
+2. Uses `lazy.js` to optionally defer the initialization until the element is visible in the viewport.
+3. Automatically creates an `AbortController` and passes the `.signal` to the component to guarantee no orphaned event listeners cause memory leaks.
+4. Safely calls `.destroy()` on the class instance when the HTML node is removed (e.g., replaced during an AJAX/HTMX request).
+## AJAX / Load Order Notes
+`initComponents()` evaluates elements as soon as they enter the DOM.
+If an AJAX fragment is injected before its component class is registered on `window`, global fallback resolution can fail.
+Recommended for async/fragment-heavy apps:
+1. Prefer `options.resolve` with async imports so component loading is deterministic.
+2. Treat `window.ComponentName` fallback as a convenience path (best for simple pages).
+3. If your scripts register components later, retry previously failed nodes after registration (`engine.retryFailed(fragment)`), or inject scripts before inserting the fragment.
+If you use the CDN auto bundle (`dist/liveinit.min.js`), a convenience event is available:
+```javascript
+document.dispatchEvent(
+  new CustomEvent("liveinit:refresh", {
+    detail: { root: fragmentElement } // optional, defaults to document
+  })
+);
+```
+This re-scans `[data-component]` elements in the provided root and initializes any newly available components.
+It also retries nodes that previously failed to resolve.

package/docs/lazy.md ADDED Viewed

@@ -0,0 +1,36 @@
+# Lazy Intersection Observer (`lazy.js`)
+A simple utility that defers the initialization of DOM elements until they enter the user's viewport.
+## Overview
+By leveraging the natively performant `IntersectionObserver`, `lazy.js` prevents heavy external scripts—like maps, charts, or datatables—from unnecessarily slowing down Initial Page Load times.
+## Usage
+```javascript
+import { lazy } from 'liveinit';
+// Setup your heavy DOM initialization
+const initMyComponent = (element) => {
+  element.innerText = "Wow! I am finally loaded.";
+};
+// Start watching the element
+const cancelLazyObserver = lazy(myHeavyDiv, initMyComponent);
+```
+### Automatic Cleanup Strategy
+`lazy()` returns a cleanup function that cancels the observer entirely. This makes it perfect to cleanly tie to the teardown phase of a component lifecycle in case it drops from the page before it's ever scrolled to:
+```javascript
+// Disconnects element from IntersectionObserver
+cancelLazyObserver();
+```
+*(Note: Once the element actually enters the screen and executes `initMyComponent`, the internal observer automatically calls `.unobserve(el)` and destroys the internal WeakMap entry. The `cancelLazyObserver` function then becomes a harmless no-op string).*
+### Fallbacks
+If `IntersectionObserver` is completely unsupported by the browser, `lazy.js` will instantly fall back to executing the callback immediately to ensure core capabilities function without throwing an error natively.

package/docs/observer.md ADDED Viewed

@@ -0,0 +1,65 @@
+# Selector Observer (`observer.js`)
+The ultra-fast, pure JS core DOM lifecycle tracker for known, fixed CSS selectors. This module wraps `MutationObserver` directly.
+## Overview
+Unlike many mutation tracking libraries that suffer severe performance penalties by walking the entire DOM on every change, `observer.js` specifically looks for targeted, pre-computed CSS selector matches when nodes drop in and out of the DOM.
+## Features
+- Blazing fast CSS string compilation upfront.
+- Native evaluation for child element searches (`querySelectorAll`).
+- Auto-initialization for matched elements immediately on load.
+- Safe-by-default behavior with no global prototype patching.
+## Usage
+```javascript
+import { observer } from 'liveinit';
+// The engine takes an Array of specific CSS selectors it should look for
+const OBSERVED = ['[data-component]', '[data-custom-component]'];
+// Start observing mutations and immediately evaluate all current DOM
+const engine = observer(OBSERVED, (element, isConnected, selector) => {
+  if (isConnected) {
+    console.log(`Node ${element.tagName} attached! matched: ${selector}`);
+  } else {
+    console.log(`Node ${element.tagName} detached! matched: ${selector}`);
+  }
+});
+```
+### The Returned Instance
+The observer call returns the following API:
+```javascript
+const { evaluate, forget, disconnect } = engine;
+```
+- `evaluate(elements, isConnected = true)`: Manually trigger the engine on dynamically altered nodes. *Because `observer.js` intentionally ignores attribute changes (for performance), if you dynamically add a class or attribute later without re-appending the DOM node, call `evaluate(yourDiv)` to manually trigger the connection lifecycle.*
+- `forget(element)`: Strips an element entirely from the WeakMap memory tracker.
+- `disconnect()`: Unplugs the internal `MutationObserver`.
+## Shadow DOM (Opt-In)
+`observer.js` does not patch `Element.prototype` automatically. If you want to observe future **open** shadow roots, opt in explicitly:
+```javascript
+import { observer, observeOpenShadowRoots } from 'liveinit';
+const engine = observer(['[data-component]'], (el, isConnected) => {
+  // ...
+});
+// Observe all newly created open shadow roots.
+const stopShadowRootBridge = observeOpenShadowRoots((shadowRoot) => {
+  engine.evaluate(shadowRoot.querySelectorAll('[data-component]'), true);
+});
+// Later:
+stopShadowRootBridge();
+engine.disconnect();
+```

package/docs/parseConfig.md ADDED Viewed

@@ -0,0 +1,39 @@
+# Config Parser (`parseConfig.js`)
+A utility for parsing flexible HTML configuration strings securely into functional JavaScript Objects.
+## Overview
+Writing Strict JSON inside HTML properties is incredibly painful and prone to error:
+```html
+<div data-component-config='{"page": 2, "theme": "dark"}'> <!-- Annoying -->
+```
+`parseConfig` transforms the developer experience by explicitly supporting unquoted keys and single quotes, allowing for cleaner HTML:
+```html
+<div data-component-config="page: 2, theme: 'dark'"> <!-- Beautiful -->
+```
+## Usage
+```javascript
+import { parseConfig } from 'liveinit';
+// Pass relaxed strings:
+const parsed = parseConfig("delay: 50, silent: true");
+/* Result:
+{
+  "delay": 50,
+  "silent": true
+}
+*/
+```
+## Parsing Rules
+1. Single Quotes (`'value'`) are explicitly accepted as valid strings.
+2. Missing Key Quotes (`name: ...`) are wrapped with Double Quotes under-the-hood.
+3. If structural Regex rules completely fail, the function natively delegates down to `JSON.parse` or falls back to an empty object `{}` rather than throwing breaking errors up the chain.

package/package.json ADDED Viewed

@@ -0,0 +1,46 @@
+{
+  "name": "liveinit",
+  "version": "0.1.0",
+  "description": "Lean HTML-first component initializer and command delegator",
+  "license": "MIT",
+  "keywords": [
+    "dom",
+    "components",
+    "observer",
+    "events",
+    "html-first"
+  ],
+  "homepage": "https://github.com/lekoala/liveinit#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lekoala/liveinit.git"
+  },
+  "bugs": {
+    "url": "https://github.com/lekoala/liveinit/issues"
+  },
+  "type": "module",
+  "main": "./src/index.js",
+  "module": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "files": [
+    "src",
+    "dist",
+    "README.md",
+    "docs"
+  ],
+  "scripts": {
+    "test": "bun test",
+    "build": "bun build ./src/auto.js --outfile ./dist/liveinit.min.js --format=iife --minify --banner \"/*! liveinit | https://github.com/lekoala/liveinit | @license MIT */\"",
+    "demo": "bun ./demo.html"
+  },
+  "sideEffects": false,
+  "private": false,
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.4",
+    "@happy-dom/global-registrator": "^20.7.0",
+    "@types/bun": "latest",
+    "happy-dom": "^20.7.0"
+  }
+}

package/src/auto.js ADDED Viewed

@@ -0,0 +1,33 @@
+import * as liveinit from "./index.js";
+// Auto-initialize with default settings for immediate use via CDN script tag
+liveinit.initCommands();
+const componentEngine = liveinit.initComponents();
+// Convenience hook for AJAX/fragment flows in CDN mode.
+// Dispatch `liveinit:refresh` with an optional `detail.root` Element/Document.
+if (typeof document !== "undefined") {
+	document.addEventListener("liveinit:refresh", (event) => {
+		const detail = event && event.detail ? event.detail : null;
+		const root = detail && detail.root ? detail.root : document;
+		if (!root || typeof root.querySelectorAll !== "function") return;
+		// Evaluate children
+		componentEngine.evaluate(root.querySelectorAll("[data-component]"), true);
+		// Evaluate root itself if it is a component
+		if (root.matches && root.matches("[data-component]")) {
+			componentEngine.evaluate(root, true);
+		}
+		// Retry components that previously failed to resolve.
+		componentEngine.retryFailed(root);
+	});
+}
+// Expose the library to the global window object for programmatic access
+if (typeof window !== "undefined") {
+	window.liveinit = liveinit;
+}
+export default liveinit;

package/src/index.js ADDED Viewed

@@ -0,0 +1,15 @@
+import initCommands from "./initCommands.js";
+import initComponents from "./initComponents.js";
+import lazy from "./lazy.js";
+import observeOpenShadowRoots from "./observeOpenShadowRoots.js";
+import observer from "./observer.js";
+import parseConfig from "./parseConfig.js";
+export {
+	initCommands,
+	initComponents,
+	lazy,
+	observeOpenShadowRoots,
+	observer,
+	parseConfig,
+};

package/src/initCommands.js ADDED Viewed

@@ -0,0 +1,86 @@
+import parseConfig from "./parseConfig.js";
+/**
+ * Initializes the global command event delegator.
+ * @param {Object} [options={}]
+ * @param {string} [options.attribute="data-command"] - The HTML attribute used for the command action.
+ * @param {string[]} [options.events=["click", "change", "input", "submit", "focusin", "focusout"]] - The array of bubbling events to listen for.
+ * @returns {{ disconnect: () => void }} Disconnects all event listeners registered by this init call.
+ */
+export default function initCommands(options = {}) {
+	const attribute = options.attribute || "data-command";
+	const eventPrefix = attribute.replace(/^data-/, "");
+	const commandOnAttr = `${attribute}-on`;
+	const commandForAttr = `${attribute}-for`;
+	const commandConfigAttr = `${attribute}-config`;
+	const events = options.events || [
+		"click",
+		"change",
+		"input",
+		"submit",
+		"focusin",
+		"focusout",
+	];
+	const listener = {
+		// One stable listener object for all events:
+		// `handleEvent` keeps add/remove symmetric and avoids per-event bound closures.
+		handleEvent(event) {
+			const eventTarget = event && event.target;
+			if (!eventTarget || typeof eventTarget.closest !== "function") return;
+			// Find if the event originated from inside a [data-command] element
+			const trigger = eventTarget.closest(`[${attribute}]`);
+			if (!trigger) return;
+			// If the event type doesn't match the requested trigger, ignore it
+			const expectedEvent = trigger.getAttribute(commandOnAttr) || "click";
+			const type = event.type;
+			if (type !== expectedEvent) return;
+			if (type !== "focusin" && type !== "focusout") {
+				// Prevent Default handles submit, links, and changes correctly usually
+				event.preventDefault();
+			}
+			const action = trigger.getAttribute(attribute); // e.g., "refresh"
+			const targetSelector = trigger.getAttribute(commandForAttr);
+			const configString = trigger.getAttribute(commandConfigAttr);
+			const config = parseConfig(configString ? configString : "{}");
+			let target = trigger;
+			if (targetSelector) {
+				try {
+					target = document.querySelector(targetSelector);
+				} catch (_e) {
+					return;
+				}
+			}
+			if (target) {
+				target.dispatchEvent(
+					new CustomEvent(`${eventPrefix}:${action}`, {
+						detail: { originalEvent: event, config, trigger },
+						bubbles: true,
+					}),
+				);
+			}
+		},
+	};
+	for (let i = 0, len = events.length; i < len; i++) {
+		document.addEventListener(events[i], listener);
+	}
+	let connected = true;
+	return {
+		disconnect() {
+			if (!connected) return;
+			connected = false;
+			for (let i = 0, len = events.length; i < len; i++) {
+				document.removeEventListener(events[i], listener);
+			}
+		},
+	};
+}

package/src/initComponents.js ADDED Viewed

@@ -0,0 +1,156 @@
+import lazy from "./lazy.js";
+import observer from "./observer.js";
+import parseConfig from "./parseConfig.js";
+/**
+ * Initializes components dynamically based on HTML attributes.
+ *
+ * @param {Record<string, () => Promise<{ default: any }>>} [Registry] - Optional dictionary mapping module names to dynamic import functions.
+ * @param {Object} [options={}]
+ * @param {string} [options.attribute="data-component"] - The HTML attribute used for binding components.
+ * @param {string} [options.lazyAttribute="data-lazy"] - The HTML attribute indicating deferred loading.
+ * @param {string} [options.signalKey="signal"] - The key used to inject the AbortSignal into the component's config.
+ * @param {string} [options.destroyMethod="destroy"] - The method name called on the component instance during teardown.
+ * @param {Function} [options.resolve] - A custom async function `(moduleName) => ModuleClass` to override default resolution.
+ * @returns {Object} The observer instance { evaluate, retryFailed, forget, disconnect }.
+ */
+export default function initComponents(Registry = null, options = {}) {
+	const attribute = options.attribute || "data-component";
+	const lazyAttribute = options.lazyAttribute || "data-lazy";
+	const signalKey = options.signalKey || "signal";
+	const destroyMethod = options.destroyMethod || "destroy";
+	const componentState = new WeakMap();
+	// Default resolver: check explicit registry, fallback to global window object
+	const defaultResolver = async (moduleName) => {
+		if (Registry && Registry[moduleName]) {
+			const imported = await Registry[moduleName]();
+			// Handle both ES module default exports and CommonJS-style exports
+			return imported.default || imported;
+		}
+		if (window[moduleName]) {
+			return window[moduleName];
+		}
+		// Instead of throwing strongly, warn so that async component definitions
+		// (late init) do not throw unhandled runtime errors on the first pass.
+		// A warning is useful enough for developers to realize a typo or missing class.
+		console.warn(`[liveinit] Module '${moduleName}' not found in Registry or global scope.`);
+		return null;
+	};
+	const resolver = options.resolve || defaultResolver;
+	const engine = observer([`[${attribute}]`], (el, isConnected) => {
+		if (isConnected) {
+			// 1. Parse relaxed config string
+			const configString = el.getAttribute(`${attribute}-config`);
+			const config = parseConfig(configString);
+			const moduleName = el.getAttribute(attribute);
+			const state = {
+				abortController: new AbortController(),
+				cancelLazy: null,
+				appModule: null,
+				failed: false,
+			};
+			componentState.set(el, state);
+			config[signalKey] = state.abortController.signal;
+			// 2. Define the actual initialization logic
+			const initModule = async () => {
+				try {
+					const ModuleClass = await resolver(moduleName);
+					// Ensure element wasn't disconnected while we were resolving the module
+					// and ensure ModuleClass was actually resolved
+					if (ModuleClass && !state.abortController.signal.aborted) {
+						state.appModule = new ModuleClass(el, config);
+						state.failed = false;
+					} else if (!ModuleClass) {
+						// Keep state and mark as failed so retries can be targeted later.
+						state.failed = true;
+					}
+				} catch (err) {
+					state.failed = true;
+					console.error(err);
+				}
+			};
+			// 3. Check for Lazy Loading
+			if (el.hasAttribute(lazyAttribute)) {
+				state.cancelLazy = lazy(el, initModule);
+			} else {
+				initModule();
+			}
+		} else {
+			// --- TEARDOWN ---
+			const state = componentState.get(el);
+			if (!state) return;
+			// 1. Auto-cleanup all events bound with this signal
+			if (state.abortController) {
+				state.abortController.abort();
+			}
+			// 2. If it was removed before it ever scrolled into view, cancel the observer!
+			if (state.cancelLazy) {
+				state.cancelLazy();
+			}
+			// 3. If the module was actually initialized, destroy it safely.
+			if (
+				state.appModule &&
+				typeof state.appModule[destroyMethod] === "function"
+			) {
+				state.appModule[destroyMethod]();
+			}
+			componentState.delete(el);
+		}
+	});
+	const collectCandidates = (root) => {
+		const nodes = [];
+		if (!root) return nodes;
+		if (typeof root.querySelectorAll === "function") {
+			const descendants = root.querySelectorAll(`[${attribute}]`);
+			for (let i = 0, len = descendants.length; i < len; i++) {
+				nodes.push(descendants[i]);
+			}
+		}
+		if (
+			typeof root.matches === "function" &&
+			root.matches(`[${attribute}]`)
+		) {
+			nodes.push(root);
+		}
+		return nodes;
+	};
+	const retryFailed = (root = document) => {
+		const nodes = collectCandidates(root);
+		let retried = 0;
+		for (let i = 0, len = nodes.length; i < len; i++) {
+			const el = nodes[i];
+			const state = componentState.get(el);
+			if (!state || !state.failed) continue;
+			retried++;
+			engine.forget(el);
+			engine.evaluate(el, true);
+		}
+		return retried;
+	};
+	return {
+		evaluate: engine.evaluate,
+		retryFailed,
+		forget: engine.forget,
+		disconnect: engine.disconnect,
+	};
+}

package/src/lazy.js ADDED Viewed

@@ -0,0 +1,44 @@
+/**
+ * @type {WeakMap<Element,Function>}
+ */
+const map = new WeakMap();
+let observer;
+// Initialize IntersectionObserver for browsers that support it
+if (typeof window !== "undefined" && "IntersectionObserver" in window) {
+	observer = new IntersectionObserver((entries, obs) => {
+		const activeEntries = entries.filter((entry) => entry.isIntersecting);
+		for (let i = 0, len = activeEntries.length; i < len; i++) {
+			const t = activeEntries[i].target;
+			obs.unobserve(t);
+			// Run
+			const fn = map.get(t);
+			map.delete(t);
+			if (fn) {
+				fn(t);
+			}
+		}
+	});
+}
+/**
+ * Element will trigger callback when visible in intersection observer
+ * @param {Element} el
+ * @param {Function} cb An init callback that gets the element as the first argument
+ * @returns {Function} a callback to remove the observer
+ */
+export default function lazy(el, cb) {
+	// If IntersectionObserver is not supported, initialize immediately
+	if (!observer) {
+		cb(el);
+		// Dummy cleanup
+		return () => {};
+	}
+	map.set(el, cb);
+	observer.observe(el);
+	return () => {
+		map.delete(el);
+		return observer.unobserve(el);
+	};
+}

package/src/observeOpenShadowRoots.js ADDED Viewed

@@ -0,0 +1,47 @@
+const subscribers = new Set();
+let originalAttachShadow = null;
+/**
+ * Opt-in helper to observe mutations inside future open shadow roots.
+ * Returns a cleanup callback that removes the subscription and restores
+ * `Element.prototype.attachShadow` when no subscribers remain.
+ *
+ * @param {(shadowRoot: ShadowRoot) => void} observe
+ * @returns {() => void}
+ */
+export default function observeOpenShadowRoots(observe) {
+	if (typeof observe !== "function") {
+		throw new Error("observeOpenShadowRoots requires an observe callback.");
+	}
+	if (typeof Element === "undefined" || !Element.prototype.attachShadow) {
+		return () => {};
+	}
+	if (!originalAttachShadow) {
+		originalAttachShadow = Element.prototype.attachShadow;
+		Element.prototype.attachShadow = function (init) {
+			const shadowRoot = originalAttachShadow.call(this, init);
+			if (init && init.mode === "open") {
+				subscribers.forEach((subscriber) => {
+					subscriber(shadowRoot);
+				});
+			}
+			return shadowRoot;
+		};
+	}
+	subscribers.add(observe);
+	let active = true;
+	return () => {
+		if (!active) return;
+		active = false;
+		subscribers.delete(observe);
+		if (!subscribers.size && originalAttachShadow) {
+			Element.prototype.attachShadow = originalAttachShadow;
+			originalAttachShadow = null;
+		}
+	};
+}

package/src/observer.js ADDED Viewed

@@ -0,0 +1,121 @@
+/**
+ * Ultra-fast DOM lifecycle tracker for known, fixed CSS selectors.
+ *
+ * @param {string[]} queries Array of CSS selectors to observe
+ * @param {Function} callback Callback for matches: (element, connected, selector)
+ * @param {Document|Element} [root=document] The root element to observe
+ * @returns {object} The observer instance { evaluate, forget, disconnect }
+ */
+export default function observer(queries, callback, root = document) {
+	const liveElements = new WeakMap();
+	if (!queries || !queries.length) {
+		throw new Error("observer requires an array of CSS selector queries.");
+	}
+	// Compute the master selector string exactly once.
+	const selectorString = queries.join(",");
+	const notifyNode = (element, isConnected) => {
+		if (!element.matches) return;
+		let activeSelectors = liveElements.get(element);
+		if (isConnected) {
+			// Classic, blazing-fast 'for' loop instead of Set iteration
+			for (let i = 0, len = queries.length; i < len; i++) {
+				const selector = queries[i];
+				if (element.matches(selector)) {
+					if (!activeSelectors) {
+						activeSelectors = new Set();
+						liveElements.set(element, activeSelectors);
+					}
+					if (!activeSelectors.has(selector)) {
+						activeSelectors.add(selector);
+						callback(element, true, selector);
+					}
+				}
+			}
+		} else if (activeSelectors) {
+			liveElements.delete(element);
+			activeSelectors.forEach((selector) => {
+				callback(element, false, selector);
+			});
+		}
+	};
+	const processNode = (node, isConnected, added, removed) => {
+		if (isConnected) {
+			if (!added.has(node)) {
+				added.add(node);
+				removed.delete(node);
+				notifyNode(node, true);
+			}
+		} else {
+			if (!removed.has(node)) {
+				removed.add(node);
+				added.delete(node);
+				notifyNode(node, false);
+			}
+		}
+		// Uses the pre-computed string for immediate native C++ evaluation
+		const descendants = node.querySelectorAll(selectorString);
+		for (let i = 0, len = descendants.length; i < len; i++) {
+			const desc = descendants[i];
+			if (isConnected) {
+				if (!added.has(desc)) {
+					added.add(desc);
+					removed.delete(desc);
+					notifyNode(desc, true);
+				}
+			} else {
+				if (!removed.has(desc)) {
+					removed.add(desc);
+					added.delete(desc);
+					notifyNode(desc, false);
+				}
+			}
+		}
+	};
+	const observer = new MutationObserver((records) => {
+		const added = new Set();
+		const removed = new Set();
+		for (let i = 0, len = records.length; i < len; i++) {
+			const { addedNodes, removedNodes } = records[i];
+			for (let j = 0, rLen = removedNodes.length; j < rLen; j++) {
+				const node = removedNodes[j];
+				if (node.nodeType === 1) processNode(node, false, added, removed);
+			}
+			for (let j = 0, aLen = addedNodes.length; j < aLen; j++) {
+				const node = addedNodes[j];
+				if (node.nodeType === 1) processNode(node, true, added, removed);
+			}
+		}
+	});
+	observer.observe(root, { childList: true, subtree: true });
+	const evaluate = (elements, isConnected = true) => {
+		const nodes =
+			elements instanceof NodeList || Array.isArray(elements)
+				? elements
+				: [elements];
+		for (let i = 0, len = nodes.length; i < len; i++) {
+			if (nodes[i].nodeType === 1) notifyNode(nodes[i], isConnected);
+		}
+	};
+	// Automatically initialize everything currently in the DOM
+	evaluate(root.querySelectorAll(selectorString), true);
+	// Return the stripped-down public API
+	return {
+		evaluate,
+		forget: (el) => liveElements.delete(el),
+		disconnect: () => observer.disconnect(),
+	};
+}

package/src/parseConfig.js ADDED Viewed

@@ -0,0 +1,46 @@
+/**
+ * Parses a simplified, non-strict object string into a JavaScript object.
+ * Allows unquoted keys.
+ * Allows single-quoted strings.
+ * Assumes the root is an object.
+ * @param {string} str The configuration string.
+ * @returns {object} The parsed JavaScript object.
+ */
+export default function parseConfig(str) {
+	if (typeof str !== "string") return {};
+	let jsonString = str.trim();
+	// Empty returns an empty object
+	if (jsonString === "") return {};
+	// 1. ([a-zA-Z_$][\w$-]+)\s: matches an unquoted key followed by a colon.
+	// 2. '((?:\'|[^']))' matches a single-quoted string and its content.
+	jsonString = jsonString.replace(
+		/([a-zA-Z_$][\w$-]*)\s*:|'((?:\\'|[^'])*)'/g,
+		(_match, key, stringContent) => {
+			// Case 1: An unquoted key was matched (e.g., "key:").
+			if (key) {
+				// Return the key, now double-quoted, with the colon.
+				return `"${key}":`;
+			}
+			// Case 2: A single-quoted string was matched (e.g., "'value'").
+			// Note: The 'else' is implicit. `key` will be undefined if the second part of the regex matched.
+			// Un-escape any escaped single quotes within the content.
+			const unescaped = stringContent.replace(/\\'/g, "'");
+			// Escape any double quotes to create a valid JSON string.
+			const escaped = unescaped.replace(/"/g, '\\"');
+			// Return the content, now wrapped in double quotes.
+			return `"${escaped}"`;
+		},
+	);
+	// Ensure the string is wrapped in braces to be a valid JSON object.
+	if (!jsonString.startsWith("{")) {
+		jsonString = `{${jsonString}}`;
+	}
+	// Use the built-in JSON.parse.
+	try {
+		return JSON.parse(jsonString);
+	} catch (_e) {
+		console.error(`Failed to parse: ${str}`);
+		return {}; // Return an empty object on failure.
+	}
+}