coralite 0.33.1 → 0.35.0

package/README.md

@@ -83,7 +83,7 @@ npx coralite --components src/components --pages src/pages --output dist
 Coralite uses a `coralite.config.js` file at the root of your project. We provide a `defineConfig` helper to give you full IDE autocomplete and type safety.
 
 ```javascript
-import { defineConfig } from 'coralite/plugins'
+import { defineConfig } from 'coralite'
 import myCustomPlugin from './plugins/my-plugin.js'
 
 export default defineConfig({
@@ -113,9 +113,11 @@ Styles defined in the `<style>` block are automatically **scoped** to the compon
 
 ```html
 <template id="user-card">
-  <div class="card">
+  <div class="card" ref="card">
     <h2>{{ formatName }}</h2>
-    <p>Role: {{ userRole }}</p>
+    <p>{{ userMeta }}</p>
+    <slot>
+    <p class="stats">Logins: {{ loginCount }}</p>
   </div>
 </template>
 
@@ -125,41 +127,67 @@ Styles defined in the `<style>` block are automatically **scoped** to the compon
     border: 1px solid #eaeaea;
     padding: 1.5rem;
     border-radius: 8px;
+    cursor: pointer;
   }
   h2 {
     color: coral;
   }
+  .stats {
+    font-size: 0.85em;
+    color: gray;
+  }
 </style>
 
 <script type="module">
-  import { defineComponent } from 'coralite/plugins'
+  import { defineComponent } from 'coralite'
+  import db from 'database'
 
   export default defineComponent({
-    // Server-side state & data
-    properties(context) {
-      const { firstName, lastName, role } = context.properties
+    // INPUTS (Coerced from HTML string attributes)
+    attributes: {
+      firstName: { type: String, default: 'Unknown' },
+      lastName: { type: String, default: '' },
+      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)
+      
       return {
-        formatName: `${firstName} ${lastName}`,
-        userRole: role || 'Guest'
+        // These will be merged into the base state
+        department: stats.department || 'General',
+        loginCount: stats.loginCount || 0
       }
     },
 
+    // DERIVED STATE (Sync, pure functions, Read-Only Proxy)
+    getters: {
+      // state = attributes + data
+      formatName: (state) => `${state.firstName} ${state.lastName}`.trim(),
+      userMeta: (state) => `Role: ${state.role} | Dept: ${state.department}`
+    },
+
     // Light DOM transformations
     slots: {
-      content(nodes, context) {
-        return nodes.map(node => {
-          // Perform SSR transformations on slot content
-          return node
-        })
+      default (nodes, context) {
+        return nodes.map(node => node)
       }
     },
 
-    // Client-side behavior
-    script({ properties, refs, root, page, signal }) {
-      console.log(`Component mounted: ${properties.formatName}`)
+    // CLIENT CONTROLLER (Mutations, Events, Read/Write Proxy, Teardown)
+    script({ state, refs, root, signal }) {
+      console.log(`Component mounted: ${state.formatName}`)
       
-      refs.card.addEventListener('click', () => {
-        alert('Hello from the browser!')
+      // 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 })
     }
   })
@@ -177,7 +205,7 @@ Coralite is built to be extended. The `definePlugin` API lets you tap directly i
 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.
 
 ```javascript
-import { definePlugin } from 'coralite/plugins'
+import { definePlugin } from 'coralite'
 import { parseHTML } from 'coralite/utils'
 
 export default function seoPlugin(options = {}) {
@@ -185,10 +213,10 @@ export default function seoPlugin(options = {}) {
     name: 'coralite-seo-plugin',
 
     // State Reducers: Patch the page context before rendering
-    onBeforePageRender: async (context) => {
+    onBeforePageRender (context) {
       // Return a patch object; Coralite will safely deep-merge it for you!
       return {
-        properties: {
+        state: {
           siteTitle: options.title || 'My Coralite Site',
           metaDescription: 'Generated by Coralite'
         }
@@ -196,7 +224,7 @@ export default function seoPlugin(options = {}) {
     },
 
     // Data Aggregators: Generate entirely new pages during the build
-    onAfterPageRender: async (basePageResult) => {
+    onAfterPageRender (basePageResult) {
       // Access the engine instance via `this`
       // this.pages.getItem('/index.html')
 

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

@@ -9,10 +9,11 @@
  * @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 'production').
+ * @param {string} options.mode - Build mode ('development' or 'development').
+ * @param {Object} [options.renderContext] - Build-time render context.
  * @returns {string} The generated JavaScript runtime.
  */
-export function generateClientRuntime({ base, sharedChunkPath, chunkManifest, instances, mode }: {
+export function generateClientRuntime({ base, sharedChunkPath, chunkManifest, instances, mode, renderContext }: {
     base: string;
     sharedChunkPath: string;
     chunkManifest: any;
@@ -20,6 +21,7 @@ export function generateClientRuntime({ base, sharedChunkPath, chunkManifest, in
         [x: string]: InstanceContext;
     };
     mode: string;
+    renderContext?: any;
 }): 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;;;;;;;;;;GAUG;AACH,iGAPG;IAAwB,IAAI,EAApB,MAAM;IACU,eAAe,EAA/B,MAAM;IACU,aAAa;IACa,SAAS,EAAnD;YAAQ,MAAM,GAAE,eAAe;KAAC;IAChB,IAAI,EAApB,MAAM;CACd,GAAU,MAAM,CA8elB;qCA1fmC,mBAAmB"}
+{"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"}

package/dist/lib/coralite.d.ts

@@ -10,7 +10,6 @@
  *  CoraliteComponentRoot,
  *  CoraliteCollectionEventSet,
  *  CoraliteComponentResult,
- *  CoraliteProperties,
  *  InstanceContext,
  *  CoraliteConfig,
  *  CoraliteFilePath,
@@ -47,7 +46,6 @@ export class Coralite {
      *  CoraliteComponentRoot,
      *  CoraliteCollectionEventSet,
      *  CoraliteComponentResult,
-     *  CoraliteProperties,
      *  InstanceContext,
      *  CoraliteConfig,
      *  CoraliteFilePath,
@@ -144,11 +142,11 @@ export class Coralite {
      * @param {string} data.message
      * @param {Error} [data.error]
      */
-    _defaultOnError({ level, message, error }: {
+    readonly _defaultOnError: ({ level, message, error }: {
         level: "WARN" | "ERR" | "LOG";
         message: string;
         error?: Error;
-    }): void;
+    }) => void;
     /**
      * Internal error handler for the Coralite instance.
      * @internal
@@ -157,18 +155,29 @@ export class Coralite {
      * @param {string} data.message - The descriptive message to be logged or thrown.
      * @param {Error} [data.error] - An optional Error instance providing a stack trace.
      */
-    _handleError(data: {
+    readonly _handleError: (data: {
         level: "WARN" | "ERR" | "LOG";
         message: string;
         error?: Error;
-    }): void;
+    }) => void;
+    /**
+     * Helper to create CoraliteError during component execution
+     * @internal
+     * @param {Error} error - The caught error
+     * @param {CoraliteModule} module - The component module
+     * @param {CoraliteCollectionItem} moduleComponent - The parent module component
+     * @param {CoralitePage} page - The current page
+     * @param {string} instanceId - The unique instance id
+     * @returns {CoraliteError} The generated error object
+     */
+    readonly _createExecutionError: (error: Error, module: CoraliteModule, moduleComponent: CoraliteCollectionItem, page: CoralitePage, instanceId: string) => CoraliteError;
     /**
      * Creates a render context for the build process.
      * @internal
      * @param {string} [buildId] - The unique identifier for the build process.
      * @returns {Object}
      */
-    _createRenderContext(buildId?: string): any;
+    readonly _createRenderContext: (buildId?: string) => any;
     /**
      * Compiles specified page(s) by rendering their document content and measuring render time.
      * Processes pages based on provided path(s), replacing custom elements with components,
@@ -177,10 +186,25 @@ export class Coralite {
      * @internal
      *
      * @param {string | string[]} [path] - Path to a single page or array of page paths relative to the pages directory. If omitted, compiles all pages.
-     * @param {Object} [properties] - Properties to be passed to the page
+     * @param {Object} [state] - Properties to be passed to the page
      * @returns {AsyncGenerator<CoraliteResult>}
      */
-    _generatePages(path?: string | string[], properties?: any): AsyncGenerator<CoraliteResult>;
+    /**
+     * Processes custom elements found within a generated page context
+     * @internal
+     * @param {CoraliteComponent & CoraliteComponentResult} mappedComponent - The compiled component instance
+     * @param {CoraliteComponentResult} originalDocument - The original document mapping
+     * @param {Object} state - Local component state
+     * @param {Object} mappedRenderContextObject - Global rendering state
+     * @returns {Promise<void>} Resolves when the elements are processed
+     */
+    readonly _processCustomElementsInPage: (mappedComponent: CoraliteComponent & CoraliteComponentResult, originalDocument: CoraliteComponentResult, state: any, mappedRenderContextObject: any, pageContext: any) => Promise<void>;
+    readonly _generatePages: (path: any, state?: {}) => AsyncGenerator<{
+        type: string;
+        path: import("../types/core.js").CoralitePath & import("../types/core.js").CoraliteFilePath;
+        content: string;
+        duration: number;
+    }, void, unknown>;
     outputFiles: {};
     /**
      * Compiles pages and collects the results with controlled concurrency.
@@ -459,14 +483,14 @@ export class Coralite {
      * @param {Object} renderContext - The current build render context.
      * @param {CoralitePage} page - The global page object
      * @param {CoraliteComponentRoot} root - The root element of the component
-     * @param {Object} properties - The current token properties and state available
+     * @param {Object} state - The current token state and state available
      * @returns {Promise<void>}
      */
-    _processDependentComponents(componentIds: string[], renderContext: any, page: CoralitePage, root: CoraliteComponentRoot, properties?: any): Promise<void>;
+    readonly _processDependentComponents: (componentIds: string[], renderContext: any, page: CoralitePage, root: CoraliteComponentRoot, state?: any) => Promise<void>;
     /**
      * @param {Object} options
      * @param {string} options.id - id - Unique identifier for the component
-     * @param {CoraliteModuleDefinitions} [options.properties={}] - Token properties available for replacement
+     * @param {CoraliteModuleDefinitions} [options.state={}] - Token state available for replacement
      * @param {CoraliteElement} [options.element] - Mapping of component IDs to their module definitions
      * @param {CoralitePage} options.page - The global page object
      * @param {CoraliteComponentRoot} options.root - The root element of the component
@@ -476,9 +500,9 @@ export class Coralite {
      * @param {boolean} [head=true] - Indicates if the current function call is for the head of the recursion
      * @returns {Promise<CoraliteElement | void>}
      */
-    createComponentElement({ id, properties, element, page, root, contextId, index, renderContext }: {
+    createComponentElement({ id, state, element, page, root, contextId, index, renderContext }: {
         id: string;
-        properties?: CoraliteModuleDefinitions;
+        state?: CoraliteModuleDefinitions;
         element?: CoraliteElement;
         page: CoralitePage;
         root: CoraliteComponentRoot;
@@ -486,11 +510,26 @@ export class Coralite {
         index?: number;
         renderContext?: any;
     }, head?: boolean): Promise<CoraliteElement | void>;
+    /**
+     * Replaces slot elements in a component with provided content
+     * @internal
+     * @param {string} id - Component ID
+     * @param {CoraliteElement} element - The original Custom Element node
+     * @param {CoraliteModule} module - The component module configuration
+     * @param {string} contextId - Instance context ID
+     * @param {Object} state - The component state
+     * @param {CoralitePage} page - Active page object
+     * @param {CoraliteComponentRoot} root - The component root element
+     * @param {number} index - Index of element
+     * @param {Object} renderContext - Rendering state
+     * @returns {Promise<void>} Resolves when slots are successfully replaced
+     */
+    readonly _replaceSlots: (id: string, element: CoraliteElement, module: CoraliteModule, contextId: string, state: any, page: CoralitePage, root: CoraliteComponentRoot, index: number, renderContext: any) => Promise<void>;
     /**
      * Generates a custom module linker callback for the Node.js VM context.
      * This linker is responsible for resolving `import` statements inside evaluated
      * component scripts. It intercepts specific specifiers to provide synthetic modules
-     * for `coralite` and `coralite/plugins`, correctly resolves relative paths against
+     * for `coralite` and plugins, correctly resolves relative paths against
      * the component's directory, and safely bridges external Node.js modules into the VM sandbox.
      *
      * @internal
@@ -498,9 +537,9 @@ export class Coralite {
      * @param {Object.<string, any>} context - Contextual rendering data and state to be exposed when a script imports `'coralite'`.
      * @returns {(specifier: string, referencingModule: import('node:vm').Module, extra: { attributes: any }) => Promise<import('node:vm').Module>} The async linker function used by the VM module.
      */
-    _moduleLinker(path: CoraliteFilePath, context: {
+    readonly _moduleLinker: (path: CoraliteFilePath, context: {
         [x: string]: any;
-    }): (specifier: string, referencingModule: import("node:vm").Module, extra: {
+    }) => (specifier: string, referencingModule: import("node:vm").Module, extra: {
         attributes: any;
     }) => Promise<import("node:vm").Module>;
     /**
@@ -508,7 +547,7 @@ export class Coralite {
      *
      * @param {Object} data
      * @param {CoraliteModule} data.module - The Coralite module to parse
-     * @param {CoraliteModuleDefinitions} data.properties - Replacement tokens for the component
+     * @param {CoraliteModuleDefinitions} data.state - Replacement tokens for the component
      * @param {CoralitePage} data.page - The global page object
      * @param {CoraliteElement} data.root - The Coralite module to parse
      * @param {string} data.contextId - Context Id
@@ -516,21 +555,21 @@ export class Coralite {
      *
      * @returns {Promise<CoraliteModuleDefinitions>}
      */
-    _evaluateDevelopment({ module, properties, page, root, contextId, renderContext }: {
+    readonly _evaluateDevelopment: ({ module, state, page, root, contextId, renderContext }: {
         module: CoraliteModule;
-        properties: CoraliteModuleDefinitions;
+        state: CoraliteModuleDefinitions;
         page: CoralitePage;
         root: CoraliteElement;
         contextId: string;
         renderContext: any;
-    }): Promise<CoraliteModuleDefinitions>;
+    }) => Promise<CoraliteModuleDefinitions>;
     /**
      * Parses a Coralite module script and compiles it into JavaScript using esbuild.
      * Replaces node:vm SourceTextModule for better performance and memory management.
      *
      * @param {Object} data
      * @param {CoraliteModule} data.module - The Coralite module to parse
-     * @param {CoraliteModuleDefinitions} data.properties - Replacement tokens for the component
+     * @param {CoraliteModuleDefinitions} data.state - Replacement tokens for the component
      * @param {CoralitePage} data.page - The global page object
      * @param {CoraliteElement} data.root - The Coralite module to parse
      * @param {string} data.contextId - Context Id
@@ -538,21 +577,21 @@ export class Coralite {
      *
      * @returns {Promise<CoraliteModuleDefinitions>}
      */
-    _evaluateProduction({ module, properties, page, root, contextId, renderContext }: {
+    readonly _evaluateProduction: ({ module, state, page, root, contextId, renderContext }: {
         module: CoraliteModule;
-        properties: CoraliteModuleDefinitions;
+        state: CoraliteModuleDefinitions;
         page: CoralitePage;
         root: CoraliteElement;
         contextId: string;
         renderContext: any;
-    }): Promise<CoraliteModuleDefinitions>;
+    }) => Promise<CoraliteModuleDefinitions>;
     /**
      * Parses a Coralite module script and compiles it into JavaScript using esbuild.
      * Replaces node:vm SourceTextModule for better performance and memory management.
      *
      * @param {Object} data -
      * @param {CoraliteModule} data.module - The Coralite module to parse
-     * @param {CoraliteModuleDefinitions} data.properties - Replacement tokens for the component
+     * @param {CoraliteModuleDefinitions} data.state - Replacement tokens for the component
      * @param {CoralitePage} data.page - The global page object
      * @param {CoraliteElement} data.element - The Coralite module to parse
      * @param {string} data.contextId - Context Id
@@ -560,7 +599,7 @@ export class Coralite {
      *
      * @returns {Promise<CoraliteModuleDefinitions>}
      */
-    _evaluate(options: any): Promise<CoraliteModuleDefinitions>;
+    readonly _evaluate: (options: any) => Promise<CoraliteModuleDefinitions>;
     /**
      * Executes a collecting plugin hook where the results are aggregated.
      * Useful for hooks like `onAfterPageRender` that return new pages to be added to the build.
@@ -570,7 +609,15 @@ export class Coralite {
      * @param {any} contextData - Context to pass to the callbacks (not mutated by this function).
      * @returns {Promise<any[]>} A flattened array of all results returned by the plugins.
      */
-    _triggerPluginAggregateHook(name: string, contextData: any): Promise<any[]>;
+    readonly _triggerPluginAggregateHook: (name: string, contextData: any) => Promise<any[]>;
+    /**
+     * @internal Executes Phase 1 of plugin exports with the given context.
+     *
+     * @param {Object} plugins - The plugins object
+     * @param {Object} context - The context object to pass to Phase 1
+     * @returns {Object} The Phase 2 functions
+     */
+    readonly _bindPlugins: (plugins: any, context: any) => any;
     /**
      * @template T
      *
@@ -582,7 +629,7 @@ export class Coralite {
      * @param {T} initialData - Data to pass to each callback function.
      * @returns {Promise<T>} A promise that resolves to the merged data.
      */
-    _triggerPluginHook<T>(name: "onPageSet" | "onPageUpdate" | "onPageDelete" | "onComponentSet" | "onComponentUpdate" | "onComponentDelete" | "onBeforePageRender" | "onAfterPageRender" | "onBeforeBuild" | "onAfterBuild", initialData: T): Promise<T>;
+    readonly _triggerPluginHook: <T>(name: "onPageSet" | "onPageUpdate" | "onPageDelete" | "onComponentSet" | "onComponentUpdate" | "onComponentDelete" | "onBeforePageRender" | "onAfterPageRender" | "onBeforeBuild" | "onAfterBuild", initialData: T) => Promise<T>;
     /**
      * Registers a callback function under the specified hook name.
      *
@@ -591,7 +638,31 @@ export class Coralite {
      * @param {'onPageSet'|'onPageUpdate'|'onPageDelete'|'onComponentSet'|'onComponentUpdate'|'onComponentDelete'|'onBeforePageRender'|'onAfterPageRender'|'onBeforeBuild'|'onAfterBuild'} name - The name of the hook to register the callback with.
      * @param {Function} callback - The callback function to be executed when the hook is triggered.
      */
-    _addPluginHook(name: "onPageSet" | "onPageUpdate" | "onPageDelete" | "onComponentSet" | "onComponentUpdate" | "onComponentDelete" | "onBeforePageRender" | "onAfterPageRender" | "onBeforeBuild" | "onAfterBuild", callback: Function): void;
+    readonly _addPluginHook: (name: "onPageSet" | "onPageUpdate" | "onPageDelete" | "onComponentSet" | "onComponentUpdate" | "onComponentDelete" | "onBeforePageRender" | "onAfterPageRender" | "onBeforeBuild" | "onAfterBuild", callback: Function) => void;
+    /**
+     * Replaces a custom element with its template content.
+     * @internal
+     * @param {CoraliteElement} coraliteElement - The custom element to be replaced.
+     * @param {CoraliteElement} element - The target element to replace the tokens with.
+     */
+    readonly _replaceCustomElementWithTemplate: (coraliteElement: CoraliteElement, element: CoraliteElement) => void;
+    /**
+     * Process a token value - parse HTML strings and handle custom elements
+     * @internal
+     * @param {any} value - The value to process
+     * @param {Object} context - Processing context
+     * @returns {Promise<any>} - Processed value
+     */
+    readonly _processTokenValue: (value: any, context: any) => Promise<any>;
+    /**
+     * This function defines a component for the Coralite framework.
+     * It is used to register components with their associated state and scripts.
+     * @internal
+     * @param {Object} options - Configuration options for the component
+     * @param {Object} context - The evaluation context
+     * @returns {Promise<Object>} A promise resolving to the module state associated with this component.
+     */
+    readonly _defineComponent: (options: any, context: any) => Promise<any>;
 }
 export default Coralite;
 export type BuildPageHandler = (result: CoraliteResult) => Promise<any> | any;
@@ -605,10 +676,13 @@ import type { CoraliteComponentRoot } from '../types/index.js';
 import type { CoraliteAnyNode } from '../types/index.js';
 import type { DomSerializerOptions } from 'dom-serializer';
 import CoraliteCollection from './collection.js';
-import type { CoraliteResult } from '../types/index.js';
+import type { CoraliteModule } from '../types/index.js';
 import type { CoralitePage } from '../types/index.js';
+import { CoraliteError } from './errors.js';
+import type { CoraliteComponent } from '../types/index.js';
+import type { CoraliteComponentResult } from '../types/index.js';
+import type { CoraliteResult } from '../types/index.js';
 import type { CoraliteModuleDefinitions } from '../types/index.js';
 import type { CoraliteElement } from '../types/index.js';
 import type { CoraliteFilePath } from '../types/index.js';
-import type { CoraliteModule } from '../types/index.js';
 //# sourceMappingURL=coralite.d.ts.map

package/dist/lib/coralite.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"coralite.d.ts","sourceRoot":"","sources":["../../lib/coralite.js"],"names":[],"mappings":"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"}
+{"version":3,"file":"coralite.d.ts","sourceRoot":"","sources":["../../lib/coralite.js"],"names":[],"mappings":"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"}

package/dist/lib/errors.d.ts

@@ -0,0 +1,16 @@
+/**
+ *
+ */
+export class CoraliteError extends Error {
+    /**
+     *
+     */
+    constructor(message: any, options?: {});
+    isCoraliteError: boolean;
+    componentId: any;
+    filePath: any;
+    instanceId: any;
+    pagePath: any;
+    cause: any;
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/lib/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../lib/errors.js"],"names":[],"mappings":"AAAA;;GAEG;AACH;IACE;;OAEG;IACH,wCAaC;IAVC,yBAA2B;IAC3B,iBAAsC;IACtC,cAAgC;IAChC,gBAAoC;IACpC,cAAgC;IAI9B,WAA0B;CAG/B"}

package/dist/lib/html.d.ts

@@ -16,6 +16,7 @@
  * @param {CoraliteCollectionEventDelete} [options.onFileDelete]
  * @param {CoraliteCollection} [options.collection] - Optional collection instance to populate
  * @param {import('p-limit').LimitFunction} [options.limit] - Optional concurrency limiter
+ * @param {boolean} [options.discoverOnly=false] - Whether to skip reading file content and only discover paths
  * @returns {Promise<CoraliteCollection>} Array of HTML file data including parent path, name, and content
  *
  * @example
@@ -26,7 +27,7 @@
  *   exclude: ['index.html', 'subdir/file2.html']
  * })
  */
-export function getHtmlFiles({ path, type, recursive, exclude, onFileSet, onFileUpdate, onFileDelete, collection, limit }: {
+export function getHtmlFiles({ path, type, recursive, exclude, discoverOnly, onFileSet, onFileUpdate, onFileDelete, collection, limit }: {
     path: string;
     type: "page" | "component";
     recursive?: boolean;
@@ -36,7 +37,27 @@ export function getHtmlFiles({ path, type, recursive, exclude, onFileSet, onFile
     onFileDelete?: CoraliteCollectionEventDelete;
     collection?: CoraliteCollection;
     limit?: import("p-limit").LimitFunction;
+    discoverOnly?: boolean;
 }): Promise<CoraliteCollection>;
+/**
+ * Generator that yields HTML files found in a directory.
+ * Useful for lazy discovery and memory-efficient processing of many files.
+ *
+ * @param {Object} options - Options for searching HTML files
+ * @param {string} options.path - Path to the directory containing HTML files
+ * @param {'page' | 'component'} options.type - Document types
+ * @param {boolean} [options.recursive=false] - Whether to search recursively
+ * @param {string[]} [options.exclude=[]] - Files or directories to exclude
+ * @param {boolean} [options.discoverOnly=false] - Whether to skip reading file content
+ * @yields {Promise<{ type: 'page' | 'component', content: string | undefined, path: { pathname: string, filename: string, dirname: string } }>}
+ */
+export function discoverHtmlFiles({ path, type, recursive, exclude, discoverOnly }: {
+    path: string;
+    type: "page" | "component";
+    recursive?: boolean;
+    exclude?: string[];
+    discoverOnly?: boolean;
+}): any;
 /**
  * Reads an HTML file and returns its content as a string.
  * @param {string} pathname - The path to the HTML file.

package/dist/lib/html.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"html.d.ts","sourceRoot":"","sources":["../../lib/html.js"],"names":[],"mappings":"AAOA;;;;;GAKG;AAEH;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,2HAnBG;IAAwB,IAAI,EAApB,MAAM;IACwB,IAAI,EAAlC,MAAM,GAAG,WAAW;IACF,SAAS,GAA3B,OAAO;IACY,OAAO,GAA1B,MAAM,EAAE;IAC6B,SAAS,GAA9C,0BAA0B;IACc,YAAY,GAApD,6BAA6B;IACW,YAAY,GAApD,6BAA6B;IACA,UAAU,GAAvC,kBAAkB;IACwB,KAAK,GAA/C,OAAO,SAAS,EAAE,aAAa;CACvC,GAAU,OAAO,CAAC,kBAAkB,CAAC,CAgGvC;AAED;;;;GAIG;AACH,0CAHW,MAAM,UAehB;AAED;;;;GAIG;AACH,sCAHW,MAAM,mBAehB;gDArJwC,mBAAmB;mDAAnB,mBAAmB;mDAAnB,mBAAmB;+BAN7B,iBAAiB"}
+{"version":3,"file":"html.d.ts","sourceRoot":"","sources":["../../lib/html.js"],"names":[],"mappings":"AAOA;;;;;GAKG;AAEH;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,yIApBG;IAAwB,IAAI,EAApB,MAAM;IACwB,IAAI,EAAlC,MAAM,GAAG,WAAW;IACF,SAAS,GAA3B,OAAO;IACY,OAAO,GAA1B,MAAM,EAAE;IAC6B,SAAS,GAA9C,0BAA0B;IACc,YAAY,GAApD,6BAA6B;IACW,YAAY,GAApD,6BAA6B;IACA,UAAU,GAAvC,kBAAkB;IACwB,KAAK,GAA/C,OAAO,SAAS,EAAE,aAAa;IACb,YAAY,GAA9B,OAAO;CACf,GAAU,OAAO,CAAC,kBAAkB,CAAC,CAiGvC;AAED;;;;;;;;;;;GAWG;AACH,oFAPG;IAAwB,IAAI,EAApB,MAAM;IACwB,IAAI,EAAlC,MAAM,GAAG,WAAW;IACF,SAAS,GAA3B,OAAO;IACY,OAAO,GAA1B,MAAM,EAAE;IACU,YAAY,GAA9B,OAAO;CACf,OAwDF;AAED;;;;GAIG;AACH,0CAHW,MAAM,UAehB;AAED;;;;GAIG;AACH,sCAHW,MAAM,mBAehB;gDA3NwC,mBAAmB;mDAAnB,mBAAmB;mDAAnB,mBAAmB;+BAN7B,iBAAiB"}

package/dist/lib/index.d.ts

@@ -4,6 +4,7 @@ export * from "./utils.js";
 export * from "./plugin.js";
 export * from "./config.js";
 export * from "./type-helper.js";
+export * from "./errors.js";
 export * from "./script-manager.js";
 export * from "#plugins";
 export { Coralite };

package/dist/lib/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../lib/index.js"],"names":[],"mappings":";;;;;;;;;;qBAAqB,eAAe"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../lib/index.js"],"names":[],"mappings":";;;;;;;;;;;qBAAqB,eAAe"}