Coralite v0.32.0 Released

Thomas David - 17 Apr 26

Coralite v0.32.0 is now available, introducing key enhancements focused on test reliability, developer experience, and plugin development. This release improves the determinism of client-side hydration in development, introduces a dedicated testing plugin to streamline E2E workflows, optimizes context evaluation inside our development virtual machine (VM), and standardizes built-in page variables to use a consistent prefix.

In previous versions, client-side hydration for declarative components mapped over instances concurrently via Promise.all(). In development mode, network latency or execution races could cause component scripts to run out of order. This led to non-deterministic instantiation order, resulting in flaky test-id and index assignments during end-to-end (E2E) test runs.

To address this, Coralite v0.32.0 splits initialization into two phases: concurrently resolving and loading component dependencies, and then sequentially executing the component scripts in development mode inside a for...await loop. Production mode continues to execute everything concurrently to maximize rendering performance.

Additionally, this release introduces a testing plugin (activated when options.mode === 'development' or via a configuration flag) that replaces random UUIDs with deterministic, component-scoped integer counters. The plugin walks the component AST to duplicate references (ref) into namespaced data-testid attributes at build-time using the [componentId]__[refName]-[index] pattern.

  <button ref="submitButton">Submit</button>
  
  
  <button ref="submitButton">Submit</button>

When running components in development mode, Coralite evaluates server scripts inside a Node VM sandbox. To keep memory usage low and prevent cross-realm sandboxing issues, we now use AST parsing via acorn to inspect scripts and extract only the globals that are actually referenced. Fundamental built-in constructors (such as Object and Array) are excluded to avoid sandboxing conflicts. We have also added support for standard web globals, including setTimeout and URL, inside the VM sandbox context.

This release resolves Windows-specific path resolution issues within script-manager.js. When importing dom-serializer, backslashes in Windows file paths were previously interpreted as escape sequences by the JavaScript parser, corrupting the path. We now pass the path through JSON.stringify() to safely escape backslashes.

Furthermore, search and lookups in the script manager have been optimized. Redundant Object.keys().includes() calls have been replaced with Object.hasOwn() for O(1) lookups, and utility logic has been streamlined to reduce redundant object traversals.

Coralite v0.32.0 standardizes built-in page variables, renaming them to use a consistent page_* prefix. Ensure your templates and plugins are updated to reflect these updates:

• Property Renames: The following page context variables have been renamed to standardize on the page_* pattern:
  • $urlPathname → page_url_pathname (with $urlPathname temporarily retained as a deprecated fallback)
  • $urlDirname → page_url_dirname
  • $filePathname → page_pathname
  • $fileDirname → page_dirname
  • $filename → page_filename
  • $lang → page_lang
• Plugin Hook Payload Changes: The structure passed to the onPageUpdate plugin hook has been updated to match the onPageSet hook. Instead of receiving only CoraliteElement[], it now receives the full ParseHTMLResult (representing the entire parsed document tree), allowing plugins to safely traverse the entire page structure during updates.

To upgrade to the latest version, update your project dependencies:

  npm install coralite@0.32.0

  npm install coralite-scripts@0.32.0