cindel 1.0.2 → 1.0.4

package/README.md

@@ -5,6 +5,7 @@
 [![npm version](https://img.shields.io/npm/v/cindel.svg)](https://www.npmjs.com/package/cindel)
 [![npm bundle size](https://img.shields.io/bundlephobia/minzip/cindel?style=round-square)](https://bundlephobia.com/package/cindel@latest)
 [![license](https://img.shields.io/npm/l/cindel.svg)](LICENSE)
+
 ---
 
 ## Features
@@ -387,25 +388,26 @@ process.on("SIGINT", () => server.stop().then(() => process.exit(0)));
 - **`string`** treated as a full WebSocket URL
 - **`object`** full config, see below
 
-| Option              | Type                                 | Default                   | Description                                                                                      |
-| ------------------- | ------------------------------------ | ------------------------- | ------------------------------------------------------------------------------------------------ |
-| `port`              | `number`                             |                           | Port number                                                                                      |
-| `host`              | `string`                             | `'localhost'`             | Hostname                                                                                         |
-| `secure`            | `boolean`                            | `false`                   | Use `wss://` and `https://`                                                                      |
-| `wsUrl`             | `string`                             |                           | Explicit WebSocket URL, overrides host/port                                                      |
-| `httpUrl`           | `string`                             |                           | Explicit HTTP base URL for file fetching                                                         |
-| `wsPath`            | `string`                             | `'/hmr'`                  | WebSocket path                                                                                   |
-| `autoReconnect`     | `boolean`                            | `true`                    | Reconnect on disconnect with exponential backoff                                                 |
-| `reconnectDelay`    | `number`                             | `2000`                    | Base reconnect delay in ms                                                                       |
-| `maxReconnectDelay` | `number`                             | `30000`                   | Maximum reconnect delay cap in ms                                                                |
-| `skipOnReconnect`   | `boolean`                            | `true`                    | Skip files already loaded in the page when the server reconnects                                 |
-| `skip`              | `string[]`                           |                           | Glob patterns for files to never load                                                            |
-| `filterSkip`        | `(file, allFiles) => boolean`        |                           | Custom skip logic, OR'd with `skip`                                                              |
-| `cold`              | `string[]`                           |                           | Glob patterns that trigger a full page reload. Merged with the server's `cold` config on connect |
-| `filterCold`        | `(file) => boolean`                  |                           | Custom cold logic, OR'd with `cold`                                                              |
-| `getOverrideTarget` | `(file, allFiles) => string \| null` |                           | Map an override file to the original it replaces                                                 |
-| `onFileLoaded`      | `(file) => void`                     |                           | Called after each file is loaded or reloaded                                                     |
-| `sortFiles`         | `(files) => string[]`                | CSS before JS, cold first | Custom sort for the initial load order                                                           |
+| Option              | Type                                 | Default       | Description                                                       |
+| ------------------- | ------------------------------------ | ------------- | ----------------------------------------------------------------- |
+| `port`              | `number`                             |               | Port number                                                       |
+| `host`              | `string`                             | `'localhost'` | Hostname                                                          |
+| `secure`            | `boolean`                            | `false`       | Use `wss://` and `https://`                                       |
+| `wsUrl`             | `string`                             |               | Explicit WebSocket URL, overrides host/port                       |
+| `httpUrl`           | `string`                             |               | Explicit HTTP base URL for file fetching                          |
+| `wsPath`            | `string`                             | `'/hmr'`      | WebSocket path                                                    |
+| `autoReconnect`     | `boolean`                            | `true`        | Reconnect on disconnect with exponential backoff                  |
+| `reconnectDelay`    | `number`                             | `2000`        | Base reconnect delay in ms                                        |
+| `maxReconnectDelay` | `number`                             | `30000`       | Maximum reconnect delay cap in ms                                 |
+| `skipOnReconnect`   | `boolean`                            | `true`        | Skip files already loaded in the page when the server reconnects  |
+| `skip`              | `string[]`                           |               | Glob patterns for files to never load                             |
+| `filterSkip`        | `(file, allFiles) => boolean`        |               | Custom skip logic, OR'd with `skip`                               |
+| `cold`              | `string[]`                           |               | Glob patterns that emit a `cold` event instead of reloading       |
+| `filterCold`        | `(file) => boolean`                  |               | Custom cold logic, OR'd with `cold`                               |
+| `getOverrideTarget` | `(file, allFiles) => string \| null` |               | Map an override file to the original it replaces                  |
+| `onFileLoaded`      | `(file) => void`                     |               | Called after each file is loaded or reloaded                      |
+| `loadOrder`         | `Stage[]`                            |               | Extra stages prepended before the built-in sorting                |
+| `sortFiles`         | `(files) => string[]`                |               | Fully replaces the default sort. When set, `loadOrder` is ignored |
 
 ### Methods
 
@@ -470,7 +472,7 @@ client
 
 ### Skip and Cold Filters
 
-`skip` prevents files from ever being loaded by the client. `cold` marks files that need a full page reload rather than a hot swap. Both options accept glob patterns, a custom filter function, or both combined via OR logic.
+`skip` prevents files from ever being loaded by the client. `cold` marks files that emit a `cold` event instead of being hot-reloaded, what happens next is up to your `cold` event handler. Both options accept glob patterns, a custom filter function, or both combined via OR logic. Client and server `cold` patterns are merged on connect.
 
 > **Note:** Glob patterns are always relative to the project root, not the watched directory.
 
@@ -486,7 +488,7 @@ new HMRClient({
     return allFiles.includes(file.replace(".override.js", ".js"));
   },
 
-  // These files can't be hot-swapped, they need a full reload
+  // These files emit a cold event instead of being hot-reloaded
   cold: ["**/*.cold.js", "src/bootstrap.js"],
 
   // Custom cold logic
@@ -496,6 +498,60 @@ new HMRClient({
 
 ---
 
+### Load Order
+
+When the client receives the initial file list it sorts them before loading. The default order is:
+
+1. CSS before JS: stylesheets load first so scripts never run against an unstyled page
+2. Cold files first: files that require a full page reload are loaded before hot-swappable ones
+3. Alphabetical: stable tiebreaker within each group
+
+`loadOrder` lets you prepend extra stages to the pipeline without giving up the built-in sorting. Each stage is detected by how many arguments it takes:
+
+- **One argument** `f => boolean` return `true` to load that file earlier, `false` to leave it in its normal position
+- **Two arguments** `(a, b) => number` works exactly like a standard `Array.sort` callback
+
+The first stage to return a non-zero result wins; the built-in stages always follow as a fallback.
+
+```js
+new HMRClient({
+  port: 1338,
+
+  loadOrder: [
+    // Load the bootstrap file before everything else
+    (f) => f === "src/bootstrap.js",
+
+    // Load files in the core/ directory before others
+    (f) => f.startsWith("core/"),
+
+    // Higher-level files first (fewer path segments)
+    (a, b) => a.split("/").length - b.split("/").length,
+  ],
+});
+```
+
+Each stage is tried in order. The first one that produces a difference between two files decides which loads first. If a stage sees no difference, the next one is tried. The built-in stages (CSS-first, cold-first, alphabetical) always follow as a final fallback.
+
+When you need total control over the load order, pass `sortFiles` instead. It receives the full file list and must return a sorted copy. The built-in stages and any `loadOrder` are completely bypassed.
+
+```js
+new HMRClient({
+  port: 1338,
+
+  sortFiles: (files) => {
+    const order = ["src/reset.css", "src/theme.css", "src/bootstrap.js"];
+    return [
+      // Pinned files in explicit order
+      ...order.filter((f) => files.includes(f)),
+      // Everything else, alphabetical
+      ...files.filter((f) => !order.includes(f)).sort(),
+    ];
+  },
+});
+```
+
+---
+
 ### Override Detection
 
 Override detection lets you maintain a parallel directory of replacement files that shadow originals without modifying them. When an override changes, the client unloads the original before loading the override.

package/dist/client/hmr-client.d.ts

@@ -46,7 +46,8 @@ export class HMRClient {
      * @param {function(string): boolean} [options.filterCold] - Custom cold file logic. Receives `(filePath)`. Combined with `cold` via OR.
      * @param {function(string, string[]): string|null} [options.getOverrideTarget] - Given a changed file, return the path of the original it replaces, or `null`. Receives `(filePath, allFiles)`. When matched, the original is unloaded before the override loads.
      * @param {function(string): void} [options.onFileLoaded] - Called after each file loads or reloads. Receives `(filePath)`.
-     * @param {function(string[]): string[]} [options.sortFiles] - Custom sort for the initial file load order. Default sorts CSS before JS, cold files first.
+     * @param {function(string[]): string[]} [options.sortFiles] - Custom sort for the initial file load order. When provided, replaces `defaultSortFiles` entirely and `loadOrder` is ignored.
+     * @param {Array<Function>} [options.loadOrder] - Stages prepended before the built-in sort (CSS-first, cold-first, alphabetical). One argument: return true to load that file first. Two arguments: works like a normal sort callback.
      */
     constructor(options: {
         wsUrl?: string;
@@ -66,6 +67,7 @@ export class HMRClient {
         getOverrideTarget?: (arg0: string, arg1: string[]) => string | null;
         onFileLoaded?: (arg0: string) => void;
         sortFiles?: (arg0: string[]) => string[];
+        loadOrder?: Array<Function>;
     });
     wsUrl: any;
     httpUrl: any;
@@ -82,6 +84,7 @@ export class HMRClient {
     allFiles: any[];
     getOverrideTarget: (arg0: string, arg1: string[]) => string | null;
     onFileLoaded: (arg0: string) => void;
+    loadOrder: Function[];
     sortFiles: any;
     socket: WebSocket;
     reconnectAttempts: number;

package/dist/client/hmr-client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hmr-client.d.ts","sourceRoot":"","sources":["../../src/client/hmr-client.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH;IACE;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,qBAlBG;QAAyB,KAAK,GAAtB,MAAM;QACW,OAAO,GAAxB,MAAM;QACY,UAAU,GAA5B,OAAO;QACU,IAAI,GAArB,MAAM;QACW,IAAI,GAArB,MAAM;QACY,MAAM,GAAxB,OAAO;QACW,aAAa,GAA/B,OAAO;QACU,cAAc,GAA/B,MAAM;QACW,iBAAiB,GAAlC,MAAM;QACY,eAAe,GAAjC,OAAO;QACY,IAAI,GAAvB,MAAM,EAAE;QACsC,UAAU,GAAxD,CAAS,IAAM,EAAN,MAAM,EAAE,IAAQ,EAAR,MAAM,EAAE,KAAG,OAAO;QAChB,IAAI,GAAvB,MAAM,EAAE;QAC4B,UAAU,GAA9C,CAAS,IAAM,EAAN,MAAM,KAAG,OAAO;QACyB,iBAAiB,GAAnE,CAAS,IAAM,EAAN,MAAM,EAAE,IAAQ,EAAR,MAAM,EAAE,KAAG,MAAM,GAAC,IAAI;QACN,YAAY,GAA7C,CAAS,IAAM,EAAN,MAAM,KAAG,IAAI;QACiB,SAAS,GAAhD,CAAS,IAAQ,EAAR,MAAM,EAAE,KAAG,MAAM,EAAE;KACtC,EA+DA;IAxDC,WAAkB;IAClB,aAAsB;IACtB,oBAAsB;IAEtB,+BAAyD;IACzD,uBAA+C;IAC/C,uBAAiD;IACjD,0BAAwD;IACxD,yBAAqD;IAGrD,wBAAsC;IACtC,oBAvBkB,MAAM,KAAG,OAAO,CAuBQ;IAG1C,oBAAiF;IACjF,gBAAuE;IAGvE,gBAAkB;IAElB,0BA/BkB,MAAM,QAAE,MAAM,EAAE,KAAG,MAAM,GAAC,IAAI,CA+BO;IACvD,qBA/BkB,MAAM,KAAG,IAAI,CA+Bc;IAC7C,eAAmE;IAEnE,kBAAkB;IAClB,0BAA0B;IAC1B,qBAAwB;IACxB,6BAA8B;IAC9B,gCAA2B;IAI3B,qBAAuB;IACvB,6BAAgC;IAEhC,uBAA8C;IAE9C,wEAAwE;IACxE,aADW,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CACF;IAC5B,uFAAuF;IACvF,qBADW,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,CACC;IAEpC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;MAYC;IAGH,oCAmBC;IAED,8CAcC;IAED,mCAIC;IAED,sEAoDC;IAED,kCA0BC;IAED,4CAgDC;IAED,8EAkEC;IAED,2CA4CC;IAED,wCA6CC;IAED;;;;;OAKG;IACH,UAJW,MAAM,GAAC,QAAQ,GAAC,KAAK,GAAC,QAAQ,GAAC,MAAM,GAAC,SAAS,GAAC,YAAY,GAAC,OAAO,sBAElE,SAAS,CAQrB;IAED;;;;;OAKG;IACH,YAJW,MAAM,GAAC,QAAQ,GAAC,KAAK,GAAC,QAAQ,GAAC,MAAM,GAAC,SAAS,GAAC,YAAY,GAAC,OAAO,sBAElE,SAAS,CASrB;IAED;;;;;OAKG;IACH,WAJW,MAAM,GAAC,QAAQ,GAAC,KAAK,GAAC,QAAQ,GAAC,MAAM,GAAC,SAAS,GAAC,YAAY,GAAC,OAAO,sBAElE,SAAS,CAoBrB;IAED,uCAQC;IAMD,iCAGC;IAED,oCAWC;IAED;;;OAGG;IACH,WAFa,OAAO,CAAC,IAAI,CAAC,CAuFzB;IAED;;OAEG;IACH,mBAUC;CACF;2BAtoB0B,kBAAkB"}
+{"version":3,"file":"hmr-client.d.ts","sourceRoot":"","sources":["../../src/client/hmr-client.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH;IACE;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,qBAnBG;QAAyB,KAAK,GAAtB,MAAM;QACW,OAAO,GAAxB,MAAM;QACY,UAAU,GAA5B,OAAO;QACU,IAAI,GAArB,MAAM;QACW,IAAI,GAArB,MAAM;QACY,MAAM,GAAxB,OAAO;QACW,aAAa,GAA/B,OAAO;QACU,cAAc,GAA/B,MAAM;QACW,iBAAiB,GAAlC,MAAM;QACY,eAAe,GAAjC,OAAO;QACY,IAAI,GAAvB,MAAM,EAAE;QACsC,UAAU,GAAxD,CAAS,IAAM,EAAN,MAAM,EAAE,IAAQ,EAAR,MAAM,EAAE,KAAG,OAAO;QAChB,IAAI,GAAvB,MAAM,EAAE;QAC4B,UAAU,GAA9C,CAAS,IAAM,EAAN,MAAM,KAAG,OAAO;QACyB,iBAAiB,GAAnE,CAAS,IAAM,EAAN,MAAM,EAAE,IAAQ,EAAR,MAAM,EAAE,KAAG,MAAM,GAAC,IAAI;QACN,YAAY,GAA7C,CAAS,IAAM,EAAN,MAAM,KAAG,IAAI;QACiB,SAAS,GAAhD,CAAS,IAAQ,EAAR,MAAM,EAAE,KAAG,MAAM,EAAE;QACF,SAAS,GAAnC,KAAK,UAAU;KACzB,EAgEA;IAzDC,WAAkB;IAClB,aAAsB;IACtB,oBAAsB;IAEtB,+BAAyD;IACzD,uBAA+C;IAC/C,uBAAiD;IACjD,0BAAwD;IACxD,yBAAqD;IAGrD,wBAAsC;IACtC,oBAxBkB,MAAM,KAAG,OAAO,CAwBQ;IAG1C,oBAAiF;IACjF,gBAAuE;IAGvE,gBAAkB;IAElB,0BAhCkB,MAAM,QAAE,MAAM,EAAE,KAAG,MAAM,GAAC,IAAI,CAgCO;IACvD,qBAhCkB,MAAM,KAAG,IAAI,CAgCc;IAC7C,sBAAqC;IACrC,eAAmE;IAEnE,kBAAkB;IAClB,0BAA0B;IAC1B,qBAAwB;IACxB,6BAA8B;IAC9B,gCAA2B;IAI3B,qBAAuB;IACvB,6BAAgC;IAEhC,uBAA8C;IAE9C,wEAAwE;IACxE,aADW,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CACF;IAC5B,uFAAuF;IACvF,qBADW,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,CACC;IAEpC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;MAYC;IAGH,oCAkBC;IAED,8CAcC;IAED,mCAIC;IAED,sEAoDC;IAED,kCA0BC;IAED,4CAgDC;IAED,8EAkEC;IAED,2CA4CC;IAED,wCA6CC;IAED;;;;;OAKG;IACH,UAJW,MAAM,GAAC,QAAQ,GAAC,KAAK,GAAC,QAAQ,GAAC,MAAM,GAAC,SAAS,GAAC,YAAY,GAAC,OAAO,sBAElE,SAAS,CAQrB;IAED;;;;;OAKG;IACH,YAJW,MAAM,GAAC,QAAQ,GAAC,KAAK,GAAC,QAAQ,GAAC,MAAM,GAAC,SAAS,GAAC,YAAY,GAAC,OAAO,sBAElE,SAAS,CASrB;IAED;;;;;OAKG;IACH,WAJW,MAAM,GAAC,QAAQ,GAAC,KAAK,GAAC,QAAQ,GAAC,MAAM,GAAC,SAAS,GAAC,YAAY,GAAC,OAAO,sBAElE,SAAS,CAoBrB;IAED,uCAQC;IAMD,iCAGC;IAED,oCAWC;IAED;;;OAGG;IACH,WAFa,OAAO,CAAC,IAAI,CAAC,CAuFzB;IAED;;OAEG;IACH,mBAUC;CACF;2BAvoB0B,kBAAkB"}

package/dist/client.iife.js

@@ -1762,7 +1762,8 @@ var HMR = (() => {
      * @param {function(string): boolean} [options.filterCold] - Custom cold file logic. Receives `(filePath)`. Combined with `cold` via OR.
      * @param {function(string, string[]): string|null} [options.getOverrideTarget] - Given a changed file, return the path of the original it replaces, or `null`. Receives `(filePath, allFiles)`. When matched, the original is unloaded before the override loads.
      * @param {function(string): void} [options.onFileLoaded] - Called after each file loads or reloads. Receives `(filePath)`.
-     * @param {function(string[]): string[]} [options.sortFiles] - Custom sort for the initial file load order. Default sorts CSS before JS, cold files first.
+     * @param {function(string[]): string[]} [options.sortFiles] - Custom sort for the initial file load order. When provided, replaces `defaultSortFiles` entirely and `loadOrder` is ignored.
+     * @param {Array<Function>} [options.loadOrder] - Stages prepended before the built-in sort (CSS-first, cold-first, alphabetical). One argument: return true to load that file first. Two arguments: works like a normal sort callback.
      */
     constructor(options) {
       const opts = typeof options === "object" && !Array.isArray(options) ? options : {};
@@ -1783,6 +1784,7 @@ var HMR = (() => {
       this.allFiles = [];
       this.getOverrideTarget = opts.getOverrideTarget || null;
       this.onFileLoaded = opts.onFileLoaded || null;
+      this.loadOrder = opts.loadOrder || [];
       this.sortFiles = opts.sortFiles || this.defaultSortFiles.bind(this);
       this.socket = null;
       this.reconnectAttempts = 0;
@@ -1810,16 +1812,18 @@ var HMR = (() => {
     }
     defaultSortFiles(files) {
       const coldSet = new Set(files.filter((f) => this.isColdFile(f)));
+      const builtinStages = [
+        (f) => f.endsWith(".css"),
+        (f) => coldSet.has(f),
+        (a, b) => a.localeCompare(b)
+      ];
+      const stages = [...this.loadOrder, ...builtinStages];
       return [...files].sort((a, b) => {
-        const aIsCSS = a.endsWith(".css");
-        const bIsCSS = b.endsWith(".css");
-        if (aIsCSS && !bIsCSS) return -1;
-        if (!aIsCSS && bIsCSS) return 1;
-        const coldA = coldSet.has(a);
-        const coldB = coldSet.has(b);
-        if (coldA && !coldB) return -1;
-        if (!coldA && coldB) return 1;
-        return a.localeCompare(b);
+        for (const stage of stages) {
+          const result = stage.length === 2 ? stage(a, b) : stage(b) - stage(a);
+          if (result !== 0) return result;
+        }
+        return 0;
       });
     }
     makeFilter(patterns, callback) {