coralite 0.35.0 → 0.36.0

package/README.md

@@ -6,16 +6,18 @@
 
 ## Build for the Web, With the Web
 
-Coralite is a static site generator built around HTML modules and the Native Web.
-
-- **Build with HTML Modules**
-  Build your entire website with modular components using only native web technologies. This provides a simple, stable, and maintainable foundation.
-- **Accessibility and Security First**
-  By leveraging native HTML elements, sites inherit strong accessibility features out-of-the-box. A small footprint with no third-party library dependencies creates a more secure website. 
-- **Progressive Enhancement**
-  Ensures that all basic content and functionality are accessible, even on browsers without JavaScript. JavaScript is treated as an optional enhancement, not a requirement. 
-- **Powerful Plugin System**
-  Extend and customize the build process with a plugin API. Use hooks to manage content, create aggregations like blog posts with pagination, or transform final HTML and CSS output.
+Coralite is a **Native-First**, strictly Server-Side Rendered (SSR) framework for building fast, accessible, and future-proof websites.
+
+- **True Native Web Components with a "Flat" API**
+  No vanilla boilerplate. Use a clean `defineComponent` flat-options API (`attributes`, `data`, `getters`, `script`) to build powerful Custom Elements without the `class extends HTMLElement` friction.
+- **The "Smart State, Dumb Template" Paradigm**
+  Templates are strictly declarative and "dumb"—no logic loops or dot-notation in HTML. All logic lives in pure JavaScript `getters` which receive a safe, Read-Only Proxy.
+- **Scoped CSS without Shadow DOM**
+  Enjoy perfect style encapsulation using standard CSS. The Coralite compiler automatically injects unique instance identifiers and nests rules, avoiding the accessibility and global styling headaches of Shadow DOM.
+- **Native Async Race-Condition Immunity**
+  Coralite's reactive engine handles asynchronous `data()` and `getters` with built-in version locks, ensuring your DOM never renders stale data from out-of-order Promise resolutions.
+- **Isomorphic, Two-Phase Curried Plugins**
+  Extend the engine with a strict, typed boundary. Plugins use a two-phase currying pattern to inject heavy context during initialization, leaving you with a clean, scoped API at runtime.
 
 ---
 
@@ -113,82 +115,63 @@ Styles defined in the `<style>` block are automatically **scoped** to the compon
 
 ```html
 <template id="user-card">
-  <div class="card" ref="card">
-    <h2>{{ formatName }}</h2>
+  <div class="card">
+    <!-- Templates only render flat keys. Logic belongs in getters! -->
+    <h2 ref="title">{{ formatName }}</h2>
     <p>{{ userMeta }}</p>
-    <slot>
+    
+    <slot></slot>
+    
     <p class="stats">Logins: {{ loginCount }}</p>
   </div>
 </template>
 
 <style>
-  /* These styles are automatically scoped to this component */
+  /* These styles are automatically scoped to this component instance */
   .card {
     border: 1px solid #eaeaea;
     padding: 1.5rem;
     border-radius: 8px;
-    cursor: pointer;
-  }
-  h2 {
-    color: coral;
-  }
-  .stats {
-    font-size: 0.85em;
-    color: gray;
   }
+  h2 { color: coral; }
 </style>
 
 <script type="module">
   import { defineComponent } from 'coralite'
-  import db from 'database'
+  import { userService } from './services.js'
 
   export default defineComponent({
-    // INPUTS (Coerced from HTML string attributes)
+    // ATTRIBUTES: Coerced from HTML (String, Number, Boolean)
     attributes: {
-      firstName: { type: String, default: 'Unknown' },
-      lastName: { type: String, default: '' },
+      userId: { type: Number, default: 0 },
       role: { type: String, default: 'Guest' }
     },
 
-    // SERVER DATA (Async fetching, runs on build/server)
-    async data(context) {
-      // We can use the parsed attributes to fetch specific data
-      const stats = await db.fetchUserStats(context.attributes.firstName)
-      
+    // DATA: Async server-side fetching (Stripped from client bundle)
+    async data({ state }) {
+      const user = await userService.getById(state.userId)
       return {
-        // These will be merged into the base state
-        department: stats.department || 'General',
-        loginCount: stats.loginCount || 0
+        firstName: user.firstName,
+        lastName: user.lastName,
+        loginCount: user.loginCount
       }
     },
 
-    // DERIVED STATE (Sync, pure functions, Read-Only Proxy)
+    // GETTERS: Pure, sync derived state (Read-Only Proxy)
     getters: {
-      // state = attributes + data
       formatName: (state) => `${state.firstName} ${state.lastName}`.trim(),
-      userMeta: (state) => `Role: ${state.role} | Dept: ${state.department}`
+      userMeta: (state) => `Role: ${state.role} | ID: ${state.userId}`
     },
 
-    // Light DOM transformations
-    slots: {
-      default (nodes, context) {
-        return nodes.map(node => node)
-      }
-    },
+    // SCRIPT: Client-side controller (Read/Write Proxy)
+    script({ state, refs, signal }) {
+      // Use the 'refs' utility to get the unique DOM element
+      const titleEl = refs('title')
 
-    // CLIENT CONTROLLER (Mutations, Events, Read/Write Proxy, Teardown)
-    script({ state, refs, root, signal }) {
-      console.log(`Component mounted: ${state.formatName}`)
-      
-      // Use the refs dictionary provided by the core plugin to target the element
-      const cardEl = root.querySelector(`[ref="${refs.card}"]`)
-
-      cardEl.addEventListener('click', () => {
-        alert(`Hello from the browser, ${state.formatName}!`)
-        
-        // automatically updates the DOM, and re-runs any dependent getters.
-        state.loginCount++ 
-      }, { signal })
+      titleEl.addEventListener('click', () => {
+        // Mutations automatically trigger DOM updates & getter re-evaluations
+        state.loginCount++
+      }, { signal }) // Always use 'signal' for auto-cleanup!
     }
   })
 </script>
@@ -200,42 +183,33 @@ Styles defined in the `<style>` block are automatically **scoped** to the compon
 
 ## Extending the Engine (`definePlugin`)
 
-Coralite is built to be extended. The `definePlugin` API lets you tap directly into the framework's build lifecycle.
-
-Plugins in Coralite use a functional, immutable API. Instead of mutating shared state, your plugin hooks simply return the specific data patches or pages you want to add. Core utilities are available via `coralite/utils`, and global engine state is accessible through `this` binding.
+Coralite uses an isomorphic plugin architecture. A plugin is divided into `server` (Node.js) and `client` (Browser) blocks, using a **Two-Phase Curried** API to safely inject context.
 
 ```javascript
 import { definePlugin } from 'coralite'
-import { parseHTML } from 'coralite/utils'
 
-export default function seoPlugin(options = {}) {
+export default function myPlugin(options = {}) {
   return definePlugin({
-    name: 'coralite-seo-plugin',
+    name: 'my-plugin',
 
-    // State Reducers: Patch the page context before rendering
-    onBeforePageRender (context) {
-      // Return a patch object; Coralite will safely deep-merge it for you!
-      return {
-        state: {
-          siteTitle: options.title || 'My Coralite Site',
-          metaDescription: 'Generated by Coralite'
+    server: {
+      // Phase 1: Global Context | Phase 2: Component Arguments
+      exports: {
+        getData: (context) => (query) => {
+          return { custom: 'data' }
         }
+      },
+      onBeforeComponentRender: ({ state }) => {
+        state.pluginAdded = true
       }
     },
 
-    // Data Aggregators: Generate entirely new pages during the build
-    onAfterPageRender (basePageResult) {
-      // Access the engine instance via `this`
-      // this.pages.getItem('/index.html')
-
-      // Return an array of new pages to append to the final build
-      if (basePageResult.path.filename === 'index.html') {
-        return [
-          {
-            path: { filename: 'sitemap.xml', pathname: '/sitemap.xml' },
-            content: '<xml>...</xml>'
-          }
-        ]
+    client: {
+      // Injects a utility directly into the component's 'script' context
+      context: {
+        myHelper: (globalCtx) => (instanceCtx) => () => {
+          console.log('Hello from component', instanceCtx.instanceId)
+        }
       }
     }
   })
@@ -261,6 +235,7 @@ Coralite plugins tap into specific hooks that execute strictly during the SSG bu
 ### Rendering Hooks
 - **`onBeforePageRender`**: A state-reducing hook to patch the page context just before HTML serialization.
 - **`onAfterPageRender`**: An aggregator hook that runs after a page is rendered, allowing plugins to append additional pages (e.g., RSS feeds, sitemaps) to the build output.
+- **`no-hydration`**: An attribute that can be added to any component tag to completely exclude it from client-side hydration while still rendering its content on the server.
 
 ---
 

package/dist/lib/client-runtime.d.ts

@@ -8,20 +8,13 @@
  * @param {string} options.base - The base URL for assets.
  * @param {string} options.sharedChunkPath - The filename of the shared chunk.
  * @param {Object} options.chunkManifest - Manifest mapping component IDs to their chunk filenames.
- * @param {Object.<string, InstanceContext>} options.instances - Map of instance data.
- * @param {string} options.mode - Build mode ('development' or 'development').
- * @param {Object} [options.renderContext] - Build-time render context.
+ * @param {string[]} [options.declarativeTags=[]] - The declarative tags used.
  * @returns {string} The generated JavaScript runtime.
  */
-export function generateClientRuntime({ base, sharedChunkPath, chunkManifest, instances, mode, renderContext }: {
+export function generateClientRuntime({ base, sharedChunkPath, chunkManifest, declarativeTags }: {
     base: string;
     sharedChunkPath: string;
     chunkManifest: any;
-    instances: {
-        [x: string]: InstanceContext;
-    };
-    mode: string;
-    renderContext?: any;
+    declarativeTags?: string[];
 }): string;
-import type { InstanceContext } from '../types/index.js';
 //# sourceMappingURL=client-runtime.d.ts.map

package/dist/lib/client-runtime.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client-runtime.d.ts","sourceRoot":"","sources":["../../lib/client-runtime.js"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;;;;;;;;;GAWG;AACH,gHARG;IAAwB,IAAI,EAApB,MAAM;IACU,eAAe,EAA/B,MAAM;IACU,aAAa;IACa,SAAS,EAAnD;YAAQ,MAAM,GAAE,eAAe;KAAC;IAChB,IAAI,EAApB,MAAM;IACW,aAAa;CACtC,GAAU,MAAM,CAmkBlB;qCAhlBmC,mBAAmB"}
+{"version":3,"file":"client-runtime.d.ts","sourceRoot":"","sources":["../../lib/client-runtime.js"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;;;;;;;GASG;AACH,iGANG;IAAwB,IAAI,EAApB,MAAM;IACU,eAAe,EAA/B,MAAM;IACU,aAAa;IACV,eAAe,GAAlC,MAAM,EAAE;CAChB,GAAU,MAAM,CA2DlB"}

package/dist/lib/client-runtime.js

@@ -0,0 +1,62 @@
+function generateClientRuntime({
+  base,
+  sharedChunkPath,
+  chunkManifest,
+  declarativeTags = []
+}) {
+  return `
+import { getClientContext, getSetups, createCoraliteClass, globalClientHooks } from '${base}assets/js/${sharedChunkPath}';
+
+(async () => {
+  if (!window.__coralite_ready__) {
+    window.__coralite_ready__ = new Promise(resolve => { window.__coralite_resolve_ready__ = resolve; });
+  }
+  globalThis.executableScripts = [];
+  globalThis.globalAbortController = new AbortController();
+
+  const componentManifest = ${JSON.stringify(chunkManifest)};
+  const loadCache = {};
+
+  const loadComponent = (componentId) => {
+    if (!componentManifest[componentId]) return Promise.resolve();
+    if (customElements.get(componentId)) return Promise.resolve();
+    if (loadCache[componentId]) return loadCache[componentId];
+
+    loadCache[componentId] = (async () => {
+      const module = await import('${base}assets/js/' + componentManifest[componentId]);
+      if (module.default && module.default.componentId) {
+        if (!customElements.get(module.default.componentId)) {
+          customElements.define(module.default.componentId, createCoraliteClass(module.default, getClientContext, globalClientHooks));
+        }
+      }
+    })();
+    return loadCache[componentId];
+  };
+
+  const declarativeTags = ${JSON.stringify(declarativeTags)};
+  const allTags = Object.keys(componentManifest);
+  const imperativeTags = allTags.filter(tag => !declarativeTags.includes(tag));
+
+  const loadPromises = declarativeTags.map(tagName => loadComponent(tagName));
+  await Promise.all(loadPromises);
+
+  if (typeof window.__coralite_resolve_ready__ === 'function') {
+    window.__coralite_resolve_ready__();
+  }
+
+  if (imperativeTags.length > 0) {
+    const lazyLoad = () => imperativeTags.forEach(tagName => loadComponent(tagName));
+    
+    if ('requestIdleCallback' in window) {
+      requestIdleCallback(lazyLoad, { timeout: 500 });
+    } else {
+      setTimeout(lazyLoad, 1);
+    }
+  }
+})();
+`.trim();
+}
+export {
+  generateClientRuntime
+};
+//# sourceMappingURL=client-runtime.js.map

package/dist/lib/client-runtime.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../lib/client-runtime.js"],
+  "sourcesContent": ["/**\n * @import { InstanceContext } from '../types/index.js'\n */\n\n/**\n * Generates the client-side runtime script for Coralite pages.\n *\n * @param {Object} options\n * @param {string} options.base - The base URL for assets.\n * @param {string} options.sharedChunkPath - The filename of the shared chunk.\n * @param {Object} options.chunkManifest - Manifest mapping component IDs to their chunk filenames.\n * @param {string[]} [options.declarativeTags=[]] - The declarative tags used.\n * @returns {string} The generated JavaScript runtime.\n */\nexport function generateClientRuntime ({\n  base,\n  sharedChunkPath,\n  chunkManifest,\n  declarativeTags = []\n}) {\n  return `\nimport { getClientContext, getSetups, createCoraliteClass, globalClientHooks } from '${base}assets/js/${sharedChunkPath}';\n\n(async () => {\n  if (!window.__coralite_ready__) {\n    window.__coralite_ready__ = new Promise(resolve => { window.__coralite_resolve_ready__ = resolve; });\n  }\n  globalThis.executableScripts = [];\n  globalThis.globalAbortController = new AbortController();\n\n  const componentManifest = ${JSON.stringify(chunkManifest)};\n  const loadCache = {};\n\n  const loadComponent = (componentId) => {\n    if (!componentManifest[componentId]) return Promise.resolve();\n    if (customElements.get(componentId)) return Promise.resolve();\n    if (loadCache[componentId]) return loadCache[componentId];\n\n    loadCache[componentId] = (async () => {\n      const module = await import('${base}assets/js/' + componentManifest[componentId]);\n      if (module.default && module.default.componentId) {\n        if (!customElements.get(module.default.componentId)) {\n          customElements.define(module.default.componentId, createCoraliteClass(module.default, getClientContext, globalClientHooks));\n        }\n      }\n    })();\n    return loadCache[componentId];\n  };\n\n  const declarativeTags = ${JSON.stringify(declarativeTags)};\n  const allTags = Object.keys(componentManifest);\n  const imperativeTags = allTags.filter(tag => !declarativeTags.includes(tag));\n\n  const loadPromises = declarativeTags.map(tagName => loadComponent(tagName));\n  await Promise.all(loadPromises);\n\n  if (typeof window.__coralite_resolve_ready__ === 'function') {\n    window.__coralite_resolve_ready__();\n  }\n\n  if (imperativeTags.length > 0) {\n    const lazyLoad = () => imperativeTags.forEach(tagName => loadComponent(tagName));\n    \n    if ('requestIdleCallback' in window) {\n      requestIdleCallback(lazyLoad, { timeout: 500 });\n    } else {\n      setTimeout(lazyLoad, 1);\n    }\n  }\n})();\n`.trim()\n}\n"],
+  "mappings": "AAcO,SAAS,sBAAuB;AAAA,EACrC;AAAA,EACA;AAAA,EACA;AAAA,EACA,kBAAkB,CAAC;AACrB,GAAG;AACD,SAAO;AAAA,uFAC8E,IAAI,aAAa,eAAe;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,8BASzF,KAAK,UAAU,aAAa,CAAC;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,qCAStB,IAAI;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,4BAUb,KAAK,UAAU,eAAe,CAAC;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAqBzD,KAAK;AACP;",
+  "names": []
+}

package/dist/lib/collection.js

@@ -0,0 +1,194 @@
+import path from "node:path";
+import { getHtmlFile } from "./html.js";
+import { access } from "node:fs/promises";
+import { existsSync } from "node:fs";
+function CoraliteCollection(options = { rootDir: "" }) {
+  this.rootDir = path.join(options.rootDir);
+  if (!existsSync(this.rootDir)) {
+    throw new Error("Root directory was not found: " + this.rootDir);
+  }
+  this.list = [];
+  this.listByPath = /* @__PURE__ */ Object.create(null);
+  this.collection = /* @__PURE__ */ Object.create(null);
+  this._onSet = options.onSet;
+  this._onUpdate = options.onUpdate;
+  this._onDelete = options.onDelete;
+}
+CoraliteCollection.prototype.setItem = async function(value) {
+  if (typeof value === "string") {
+    value = await this._loadByPath(value);
+  }
+  if (!value || !value.path) {
+    throw new Error("Valid HTMLData object must be provided");
+  }
+  const pathname = value.path.pathname;
+  const dirname = value.path.dirname;
+  const originalValue = this.collection[pathname];
+  const documentValue = value;
+  if (!originalValue) {
+    if (typeof this._onSet === "function") {
+      const result = await this._onSet(value);
+      if (!result) {
+        return;
+      }
+      documentValue.result = result.value;
+      if (result.state) {
+        documentValue.state = result.state;
+      }
+      if (result.type === "page" || result.type === "component") {
+        documentValue.type = result.type;
+      }
+      if (typeof result.id === "string" && result.id) {
+        this.collection[result.id] = documentValue;
+      }
+    }
+    this.collection[pathname] = documentValue;
+    if (!this.listByPath[dirname]) {
+      this.listByPath[dirname] = [];
+    }
+    if (!this.listByPath[dirname].includes(documentValue)) {
+      this.listByPath[dirname].push(documentValue);
+    }
+    if (!this.list.includes(documentValue)) {
+      this.list.push(documentValue);
+    }
+  } else {
+    return await this.updateItem(value);
+  }
+  return documentValue;
+};
+CoraliteCollection.prototype.deleteItem = async function(value) {
+  if (!value) {
+    throw new Error("Valid pathname must be provided");
+  }
+  let pathname;
+  let dirname;
+  let valuesByPath;
+  let originalValue;
+  if (typeof value !== "string" && value.path) {
+    pathname = value.path.pathname;
+    dirname = value.path.dirname;
+    valuesByPath = this.listByPath[dirname];
+    originalValue = value;
+  } else if (typeof value === "string") {
+    pathname = value;
+    dirname = path.dirname(pathname);
+    valuesByPath = this.listByPath[dirname];
+    originalValue = this.collection[pathname];
+  } else {
+    throw new Error("Valid pathname must be provided");
+  }
+  if (!originalValue) {
+    return;
+  }
+  if (!valuesByPath) {
+    for (const key in this.collection) {
+      if (this.collection[key] === originalValue) {
+        delete this.collection[key];
+      }
+    }
+    return;
+  }
+  if (typeof this._onDelete === "function") {
+    await this._onDelete(originalValue);
+  }
+  for (const key in this.collection) {
+    if (this.collection[key] === originalValue) {
+      delete this.collection[key];
+    }
+  }
+  const listIndex = this.list.indexOf(originalValue);
+  const pathIndex = valuesByPath.indexOf(originalValue);
+  if (listIndex !== -1) {
+    this.list.splice(listIndex, 1);
+  }
+  if (pathIndex !== -1) {
+    valuesByPath.splice(pathIndex, 1);
+  }
+  if (valuesByPath.length === 0) {
+    delete this.listByPath[dirname];
+  }
+};
+CoraliteCollection.prototype.updateItem = async function(value) {
+  if (typeof value === "string") {
+    value = await this._loadByPath(value);
+  }
+  if (!value || !value.path) {
+    throw new Error("Valid HTMLData object must be provided");
+  }
+  const pathname = value.path.pathname;
+  const originalValue = this.collection[pathname];
+  if (!originalValue) {
+    return await this.setItem(value);
+  }
+  if (typeof this._onUpdate === "function") {
+    const result = await this._onUpdate(value, originalValue);
+    if (!result) {
+      return originalValue;
+    }
+    if (result && typeof result === "object") {
+      if (result.value !== void 0) {
+        originalValue.result = result.value;
+      } else {
+        originalValue.result = result;
+      }
+      if (result.type === "page" || result.type === "component") {
+        originalValue.type = result.type;
+      }
+    } else {
+      originalValue.result = result;
+    }
+  }
+  if (value.content !== void 0) {
+    originalValue.content = value.content;
+  }
+  if (value.path && value.path !== originalValue.path) {
+    originalValue.path = value.path;
+  }
+  if (value.type) {
+    originalValue.type = value.type;
+  }
+  if (value.state !== void 0) {
+    originalValue.state = value.state;
+  }
+  return originalValue;
+};
+CoraliteCollection.prototype.getItem = function(id) {
+  if (!this.collection[id] && id.endsWith("html")) {
+    id = path.join(this.rootDir, id);
+  }
+  return this.collection[id];
+};
+CoraliteCollection.prototype.getListByPath = function(dirname) {
+  const list = this.listByPath[dirname];
+  if (list) {
+    return list.slice();
+  }
+};
+CoraliteCollection.prototype._loadByPath = async function(filepath) {
+  try {
+    await access(filepath);
+  } catch {
+    try {
+      filepath = path.join(this.rootDir, filepath);
+      await access(filepath);
+    } catch {
+      throw new Error("Could not find collection item: " + filepath);
+    }
+  }
+  const content = await getHtmlFile(filepath);
+  return {
+    type: "page",
+    content,
+    path: {
+      pathname: filepath,
+      dirname: path.dirname(filepath),
+      filename: path.basename(filepath)
+    }
+  };
+};
+var collection_default = CoraliteCollection;
+export {
+  collection_default as default
+};
+//# sourceMappingURL=collection.js.map

package/dist/lib/collection.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../lib/collection.js"],
+  "sourcesContent": ["import path from 'node:path'\nimport { getHtmlFile } from './html.js'\nimport { access } from 'node:fs/promises'\nimport { existsSync } from 'node:fs'\n\n/**\n * @import {\n *  CoraliteCollectionEventDelete,\n *  CoraliteCollectionEventSet,\n *  CoraliteCollectionEventUpdate,\n *  CoraliteCollectionItem,\n *  HTMLData } from '../types/index.js'\n */\n\n/**\n * Represents a collection of documents with methods to organize and retrieve them.\n * Maintains three views: flat list, path-based grouping, and ID lookup.\n * @class\n * @param {Object} [options={}] - Options for configuring the collection\n * @param {string} [options.rootDir=''] - The root directory path for the collection\n * @param {CoraliteCollectionEventSet} [options.onSet] - Event handler for when documents are set\n * @param {CoraliteCollectionEventUpdate} [options.onUpdate] - Event handler for when documents are updated\n * @param {CoraliteCollectionEventDelete} [options.onDelete] - Event handler for when documents are deleted\n */\nfunction CoraliteCollection (options = { rootDir: '' }) {\n  /**\n   * Root directory where collection items are located\n   */\n  this.rootDir = path.join(options.rootDir)\n\n  if (!existsSync(this.rootDir)) {\n    throw new Error('Root directory was not found: ' + this.rootDir)\n  }\n\n  /**\n   * An array of HTMLData objects representing the list of documents.\n   * @type {CoraliteCollectionItem[]}\n   */\n  this.list = []\n\n  /**\n   * An object mapping paths to arrays of HTMLData objects.\n   * Used for grouping documents by their file path.\n   * @type {Object.<string, CoraliteCollectionItem[]>}\n   */\n  this.listByPath = Object.create(null)\n\n  /**\n   * An object mapping unique identifiers to HTMLData objects.\n   * Used for quick lookup of documents by their identifier.\n   * @type {Object.<string, CoraliteCollectionItem>}\n   */\n  this.collection = Object.create(null)\n\n  /**\n   * Callback triggered when setting a new item\n   * @type {CoraliteCollectionEventSet | undefined}\n   */\n  this._onSet = options.onSet\n\n  /**\n   * Callback triggered when updating an existing item\n   * @type {CoraliteCollectionEventUpdate | undefined}\n   */\n  this._onUpdate = options.onUpdate\n\n  /**\n   * Callback triggered when deleting an item\n   * @type {CoraliteCollectionEventDelete | undefined}\n   */\n  this._onDelete = options.onDelete\n}\n\n/**\n * Adds or updates an HTMLData object in the collection and associated lists.\n * If the item already exists, it will be updated in all views.\n * @param {HTMLData|string} value - The HTMLData object to be added or updated.\n * @returns {Promise<CoraliteCollectionItem>} The modified document\n */\nCoraliteCollection.prototype.setItem = async function (value) {\n  if (typeof value === 'string') {\n    value = await this._loadByPath(value)\n  }\n\n  if (!value || !value.path) {\n    throw new Error('Valid HTMLData object must be provided')\n  }\n\n  const pathname = value.path.pathname\n  const dirname = value.path.dirname\n  const originalValue = this.collection[pathname]\n\n  /** @type {CoraliteCollectionItem} */\n  const documentValue = value\n\n  if (!originalValue) {\n    // handle pre-set hook if defined\n    if (typeof this._onSet === 'function') {\n      const result = await this._onSet(value)\n\n      // abort adding item\n      if (!result) {\n        return\n      }\n\n      documentValue.result = result.value\n\n      if (result.state) {\n        documentValue.state = result.state\n      }\n\n      if (result.type === 'page' || result.type === 'component') {\n        documentValue.type = result.type\n      }\n\n      // update collection using ID from hook result if available\n      if (typeof result.id === 'string' && result.id) {\n        this.collection[result.id] = documentValue\n      }\n    }\n\n    // always update the collection with current pathname\n    this.collection[pathname] = documentValue\n\n    // initialize directory list if it doesn't exist\n    if (!this.listByPath[dirname]) {\n      this.listByPath[dirname] = []\n    }\n\n    // add to both directory-specific and general lists\n    // check if already added to avoid duplicates\n    if (!this.listByPath[dirname].includes(documentValue)) {\n      this.listByPath[dirname].push(documentValue)\n    }\n    if (!this.list.includes(documentValue)) {\n      this.list.push(documentValue)\n    }\n  } else {\n    return await this.updateItem(value)\n  }\n\n  return documentValue\n}\n\n/**\n * Removes an HTMLData object from the collection and associated lists.\n * Accepts either an HTMLData object or a pathname string.\n * @param {HTMLData | string} value - The HTMLData object or a pathname to be removed.\n * @throws {Error} If invalid input is provided\n */\nCoraliteCollection.prototype.deleteItem = async function (value) {\n  if (!value) {\n    throw new Error('Valid pathname must be provided')\n  }\n\n  let pathname\n  let dirname\n  let valuesByPath\n  let originalValue\n\n  if (typeof value !== 'string' && value.path) {\n    // if the input is an HTMLData object, extract its pathname and directory name\n    pathname = value.path.pathname\n    dirname = value.path.dirname\n    valuesByPath = this.listByPath[dirname]\n    originalValue = value\n  } else if (typeof value === 'string') {\n    // if the input is a string, use it as the pathname and determine the directory name\n    pathname = value\n    dirname = path.dirname(pathname)\n    valuesByPath = this.listByPath[dirname]\n    originalValue = this.collection[pathname]\n  } else {\n    throw new Error('Valid pathname must be provided')\n  }\n\n  if (!originalValue) {\n    // item not found, nothing to delete\n    return\n  }\n\n  if (!valuesByPath) {\n    // directory list doesn't exist, but we still need to clean up collection\n    // This can happen if the item was stored under a different ID\n    for (const key in this.collection) {\n      if (this.collection[key] === originalValue) {\n        delete this.collection[key]\n      }\n    }\n    return\n  }\n\n  if (typeof this._onDelete === 'function') {\n    await this._onDelete(originalValue)\n  }\n\n  // remove the document from the collection\n  // also check if it's stored under a different ID (from hook result)\n  for (const key in this.collection) {\n    if (this.collection[key] === originalValue) {\n      delete this.collection[key]\n    }\n  }\n\n  // find and remove the document from the list and by-path grouping\n  const listIndex = this.list.indexOf(originalValue)\n  const pathIndex = valuesByPath.indexOf(originalValue)\n\n  if (listIndex !== -1) {\n    this.list.splice(listIndex, 1)\n  }\n  if (pathIndex !== -1) {\n    valuesByPath.splice(pathIndex, 1)\n  }\n\n  // clean up empty directory arrays\n  if (valuesByPath.length === 0) {\n    delete this.listByPath[dirname]\n  }\n}\n\n/**\n * Updates an existing HTMLData object in the collection.\n * If the document does not exist, it will be added using the set method.\n * @param {CoraliteCollectionItem|string} value - The HTMLData object to be updated or added.\n * @throws {Error} If invalid input is provided\n */\nCoraliteCollection.prototype.updateItem = async function (value) {\n  if (typeof value === 'string') {\n    value = await this._loadByPath(value)\n  }\n\n  if (!value || !value.path) {\n    throw new Error('Valid HTMLData object must be provided')\n  }\n\n  const pathname = value.path.pathname\n  const originalValue = this.collection[pathname]\n\n  if (!originalValue) {\n    // if the document does not exist, add it using the set method\n    return await this.setItem(value)\n  }\n\n  if (typeof this._onUpdate === 'function') {\n    const result = await this._onUpdate(value, originalValue)\n\n    // abort update\n    if (!result) {\n      return originalValue\n    }\n\n    // handle callback result\n    if (result && typeof result === 'object') {\n      // if result has a value property, use it\n      if (result.value !== undefined) {\n        originalValue.result = result.value\n      } else {\n        originalValue.result = result\n      }\n\n      // update type if provided\n      if (result.type === 'page' || result.type === 'component') {\n        originalValue.type = result.type\n      }\n    } else {\n      originalValue.result = result\n    }\n  }\n\n  // update core state\n  if (value.content !== undefined) {\n    originalValue.content = value.content\n  }\n\n  // update path information if it changed\n  if (value.path && value.path !== originalValue.path) {\n    originalValue.path = value.path\n  }\n\n  // update type if explicitly set\n  if (value.type) {\n    originalValue.type = value.type\n  }\n\n  // update any additional state\n  if (value.state !== undefined) {\n    originalValue.state = value.state\n  }\n\n  return originalValue\n}\n\n/**\n * Retrieves an item by its unique identifier\n * @param {string} id - Unique identifier of the item\n * @returns {CoraliteCollectionItem | undefined} The found item or undefined\n */\nCoraliteCollection.prototype.getItem = function (id) {\n  if (!this.collection[id] && id.endsWith('html')) {\n    id = path.join(this.rootDir, id)\n  }\n\n  return this.collection[id]\n}\n\n/**\n * Retrieves a list of items grouped by directory path\n * @param {string} dirname - Directory name to look up\n * @returns {CoraliteCollectionItem[] | undefined} A copy of the item list or undefined\n */\nCoraliteCollection.prototype.getListByPath = function (dirname) {\n  const list = this.listByPath[dirname]\n\n  if (list) {\n    return list.slice()\n  }\n}\n\n/**\n * Loads a collection item by its file path.\n *\n * @param {string} filepath - The path to the collection item file\n * @returns {Promise<HTMLData>} A promise that resolves to the loaded item object\n * @throws {Error} If the file cannot be found at either the provided path or within the root directory\n */\nCoraliteCollection.prototype._loadByPath = async function (filepath) {\n  try {\n    await access(filepath)\n  } catch {\n    try {\n      filepath = path.join(this.rootDir, filepath)\n\n      await access(filepath)\n    } catch {\n      throw new Error('Could not find collection item: ' + filepath)\n    }\n  }\n\n  const content = await getHtmlFile(filepath)\n\n  return {\n    type: 'page',\n    content,\n    path: {\n      pathname: filepath,\n      dirname: path.dirname(filepath),\n      filename: path.basename(filepath)\n    }\n  }\n}\n\nexport default CoraliteCollection\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/lib/config.js

@@ -0,0 +1,43 @@
+function defineConfig(options) {
+  if (!options || typeof options !== "object") {
+    throw new Error("Config must be an object");
+  }
+  const requiredProps = ["output", "components", "pages"];
+  for (const prop of requiredProps) {
+    if (!(prop in options)) {
+      throw new Error(`Missing required config property: "${prop}"`);
+    }
+    if (typeof options[prop] !== "string") {
+      throw new Error(
+        `Config property "${prop}" must be a string, received ${typeof options[prop]}`
+      );
+    }
+    if (options[prop].trim() === "") {
+      throw new Error(`Config property "${prop}" cannot be empty`);
+    }
+  }
+  if ("plugins" in options && options.plugins !== void 0) {
+    if (!Array.isArray(options.plugins)) {
+      throw new Error(
+        `Config property "plugins" must be an array, received ${typeof options.plugins}`
+      );
+    }
+    options.plugins.forEach((plugin, index) => {
+      if (typeof plugin !== "object" || plugin === null) {
+        throw new Error(
+          `Plugin at index ${index} must be an object, received ${typeof plugin}`
+        );
+      }
+      if (typeof plugin.name !== "string" || plugin.name.trim() === "") {
+        throw new Error(
+          `Plugin at index ${index} must have a valid "name" property (non-empty string)`
+        );
+      }
+    });
+  }
+  return options;
+}
+export {
+  defineConfig
+};
+//# sourceMappingURL=config.js.map

package/dist/lib/config.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../lib/config.js"],
+  "sourcesContent": ["/**\n * @import {CoraliteConfig} from '../types/index.js'\n */\n\n/**\n * Validates and defines a Coralite configuration object\n * @param {CoraliteConfig} options - The configuration options to validate and define\n * @returns {CoraliteConfig} The validated configuration object\n * @throws {Error} If the configuration is invalid\n */\nexport function defineConfig (options) {\n  // Validate that options is an object\n  if (!options || typeof options !== 'object') {\n    throw new Error('Config must be an object')\n  }\n\n  // Validate required string state\n  const requiredProps = ['output', 'components', 'pages']\n\n  for (const prop of requiredProps) {\n    // Check if property exists\n    if (!(prop in options)) {\n      throw new Error(`Missing required config property: \"${prop}\"`)\n    }\n\n    // Check if property is a string\n    if (typeof options[prop] !== 'string') {\n      throw new Error(\n        `Config property \"${prop}\" must be a string, received ${typeof options[prop]}`\n      )\n    }\n\n    // Check if property is not empty\n    if (options[prop].trim() === '') {\n      throw new Error(`Config property \"${prop}\" cannot be empty`)\n    }\n  }\n\n  // Validate optional plugins property\n  if ('plugins' in options && options.plugins !== undefined) {\n    if (!Array.isArray(options.plugins)) {\n      throw new Error(\n        `Config property \"plugins\" must be an array, received ${typeof options.plugins}`\n      )\n    }\n\n    // Validate each plugin in the array\n    options.plugins.forEach((plugin, index) => {\n      if (typeof plugin !== 'object' || plugin === null) {\n        throw new Error(\n          `Plugin at index ${index} must be an object, received ${typeof plugin}`\n        )\n      }\n\n      if (typeof plugin.name !== 'string' || plugin.name.trim() === '') {\n        throw new Error(\n          `Plugin at index ${index} must have a valid \"name\" property (non-empty string)`\n        )\n      }\n    })\n  }\n\n  return options\n}\n"],
+  "mappings": "AAUO,SAAS,aAAc,SAAS;AAErC,MAAI,CAAC,WAAW,OAAO,YAAY,UAAU;AAC3C,UAAM,IAAI,MAAM,0BAA0B;AAAA,EAC5C;AAGA,QAAM,gBAAgB,CAAC,UAAU,cAAc,OAAO;AAEtD,aAAW,QAAQ,eAAe;AAEhC,QAAI,EAAE,QAAQ,UAAU;AACtB,YAAM,IAAI,MAAM,sCAAsC,IAAI,GAAG;AAAA,IAC/D;AAGA,QAAI,OAAO,QAAQ,IAAI,MAAM,UAAU;AACrC,YAAM,IAAI;AAAA,QACR,oBAAoB,IAAI,gCAAgC,OAAO,QAAQ,IAAI,CAAC;AAAA,MAC9E;AAAA,IACF;AAGA,QAAI,QAAQ,IAAI,EAAE,KAAK,MAAM,IAAI;AAC/B,YAAM,IAAI,MAAM,oBAAoB,IAAI,mBAAmB;AAAA,IAC7D;AAAA,EACF;AAGA,MAAI,aAAa,WAAW,QAAQ,YAAY,QAAW;AACzD,QAAI,CAAC,MAAM,QAAQ,QAAQ,OAAO,GAAG;AACnC,YAAM,IAAI;AAAA,QACR,wDAAwD,OAAO,QAAQ,OAAO;AAAA,MAChF;AAAA,IACF;AAGA,YAAQ,QAAQ,QAAQ,CAAC,QAAQ,UAAU;AACzC,UAAI,OAAO,WAAW,YAAY,WAAW,MAAM;AACjD,cAAM,IAAI;AAAA,UACR,mBAAmB,KAAK,gCAAgC,OAAO,MAAM;AAAA,QACvE;AAAA,MACF;AAEA,UAAI,OAAO,OAAO,SAAS,YAAY,OAAO,KAAK,KAAK,MAAM,IAAI;AAChE,cAAM,IAAI;AAAA,UACR,mBAAmB,KAAK;AAAA,QAC1B;AAAA,MACF;AAAA,IACF,CAAC;AAAA,EACH;AAEA,SAAO;AACT;",
+  "names": []
+}