@geminilight/mindos-windows-arm64 1.0.6 → 1.0.7

package/_standalone/__node_modules/entities/src/internal/encode-shared.ts

@@ -0,0 +1,123 @@
+/**
+ * A node inside the encoding trie used by `encode.ts`.
+ *
+ * There are two physical shapes to minimize allocations and lookup cost:
+ *
+ * 1. Leaf node (string)
+ *    - A plain string (already in the form `"&name;"`).
+ *    - Represents a terminal match with no children.
+ *
+ * 2. Branch / value node (object)
+ */
+export type EncodeTrieNode =
+    | string
+    | {
+          /**
+           * Entity value for the current code point sequence (wrapped: `&...;`).
+           * Present when the path to this node itself is a valid named entity.
+           */
+          value: string | undefined;
+          /** If a number, the next code unit of the only next character. */
+          next: number | Map<number, EncodeTrieNode>;
+          /** If next is a number, `nextValue` contains the entity value. */
+          nextValue?: string;
+      };
+
+/**
+ * Parse a compact encode trie string into a Map structure used for encoding.
+ *
+ * Format per entry (ascending code points using delta encoding):
+ *   <diffBase36>[&name;][{<children>}]  -- diff omitted when 0
+ * Where diff = currentKey - previousKey - 1 (first entry stores absolute key).
+ * `&name;` is the entity value (already wrapped); a following `{` denotes children.
+ * @param serialized Serialized text fragment to encode.
+ */
+export function parseEncodeTrie(
+    serialized: string,
+): Map<number, EncodeTrieNode> {
+    const top = new Map<number, EncodeTrieNode>();
+    const totalLength = serialized.length;
+    let cursor = 0;
+    let lastTopKey = -1;
+
+    function readDiff(): number {
+        const start = cursor;
+        while (cursor < totalLength) {
+            const char = serialized.charAt(cursor);
+
+            if ((char < "0" || char > "9") && (char < "a" || char > "z")) {
+                break;
+            }
+            cursor++;
+        }
+        if (cursor === start) return 0;
+        return Number.parseInt(serialized.slice(start, cursor), 36);
+    }
+
+    function readEntity(): string {
+        if (serialized[cursor] !== "&") {
+            throw new Error(`Child entry missing value near index ${cursor}`);
+        }
+
+        // Cursor currently points at '&'
+        const start = cursor;
+        const end = serialized.indexOf(";", cursor + 1);
+        if (end === -1) {
+            throw new Error(`Unterminated entity starting at index ${start}`);
+        }
+        cursor = end + 1; // Move past ';'
+        return serialized.slice(start, cursor); // Includes & ... ;
+    }
+
+    while (cursor < totalLength) {
+        const keyDiff = readDiff();
+        const key = lastTopKey === -1 ? keyDiff : lastTopKey + keyDiff + 1;
+
+        let value: string | undefined;
+        if (serialized[cursor] === "&") value = readEntity();
+
+        if (serialized[cursor] === "{") {
+            cursor++; // Skip '{'
+            // Parse first child
+            let diff = readDiff();
+            let childKey = diff; // First key (lastChildKey = -1)
+            const firstValue = readEntity();
+            if (serialized[cursor] === "{") {
+                throw new Error("Unexpected nested '{' beyond depth 2");
+            }
+            // If end of block -> single child optimization
+            if (serialized[cursor] === "}") {
+                top.set(key, { value, next: childKey, nextValue: firstValue });
+                cursor++; // Skip '}'
+            } else {
+                const childMap = new Map<number, EncodeTrieNode>([
+                    [childKey, firstValue],
+                ]);
+                let lastChildKey = childKey;
+                while (cursor < totalLength && serialized[cursor] !== "}") {
+                    diff = readDiff();
+                    childKey = lastChildKey + diff + 1;
+                    const childValue = readEntity();
+                    if (serialized[cursor] === "{") {
+                        throw new Error("Unexpected nested '{' beyond depth 2");
+                    }
+                    childMap.set(childKey, childValue);
+                    lastChildKey = childKey;
+                }
+                if (serialized[cursor] !== "}") {
+                    throw new Error("Unterminated child block");
+                }
+                cursor++; // Skip '}'
+                top.set(key, { value, next: childMap });
+            }
+        } else if (value === undefined) {
+            throw new Error(
+                `Malformed encode trie: missing value at index ${cursor}`,
+            );
+        } else {
+            top.set(key, value);
+        }
+        lastTopKey = key;
+    }
+    return top;
+}

package/_standalone/__node_modules/escodegen/node_modules/.bin/esparse

@@ -10,9 +10,9 @@ case `uname` in
 esac
 
 if [ -z "$NODE_PATH" ]; then
-  export NODE_PATH="/home/runner/work/MindOS/MindOS/node_modules/.pnpm/esprima@4.0.1/node_modules/esprima/bin/node_modules:/home/runner/work/MindOS/MindOS/node_modules/.pnpm/esprima@4.0.1/node_modules/esprima/node_modules:/home/runner/work/MindOS/MindOS/node_modules/.pnpm/esprima@4.0.1/node_modules:/home/runner/work/MindOS/MindOS/node_modules/.pnpm/node_modules"
+  export NODE_PATH="/home/runner/work/mindos-dev/mindos-dev/node_modules/.pnpm/esprima@4.0.1/node_modules/esprima/bin/node_modules:/home/runner/work/mindos-dev/mindos-dev/node_modules/.pnpm/esprima@4.0.1/node_modules/esprima/node_modules:/home/runner/work/mindos-dev/mindos-dev/node_modules/.pnpm/esprima@4.0.1/node_modules:/home/runner/work/mindos-dev/mindos-dev/node_modules/.pnpm/node_modules"
 else
-  export NODE_PATH="/home/runner/work/MindOS/MindOS/node_modules/.pnpm/esprima@4.0.1/node_modules/esprima/bin/node_modules:/home/runner/work/MindOS/MindOS/node_modules/.pnpm/esprima@4.0.1/node_modules/esprima/node_modules:/home/runner/work/MindOS/MindOS/node_modules/.pnpm/esprima@4.0.1/node_modules:/home/runner/work/MindOS/MindOS/node_modules/.pnpm/node_modules:$NODE_PATH"
+  export NODE_PATH="/home/runner/work/mindos-dev/mindos-dev/node_modules/.pnpm/esprima@4.0.1/node_modules/esprima/bin/node_modules:/home/runner/work/mindos-dev/mindos-dev/node_modules/.pnpm/esprima@4.0.1/node_modules/esprima/node_modules:/home/runner/work/mindos-dev/mindos-dev/node_modules/.pnpm/esprima@4.0.1/node_modules:/home/runner/work/mindos-dev/mindos-dev/node_modules/.pnpm/node_modules:$NODE_PATH"
 fi
 if [ -x "$basedir/node" ]; then
   exec "$basedir/node"  "$basedir/../../../../../esprima@4.0.1/node_modules/esprima/bin/esparse.js" "$@"

package/_standalone/__node_modules/escodegen/node_modules/.bin/esvalidate

@@ -10,9 +10,9 @@ case `uname` in
 esac
 
 if [ -z "$NODE_PATH" ]; then
-  export NODE_PATH="/home/runner/work/MindOS/MindOS/node_modules/.pnpm/esprima@4.0.1/node_modules/esprima/bin/node_modules:/home/runner/work/MindOS/MindOS/node_modules/.pnpm/esprima@4.0.1/node_modules/esprima/node_modules:/home/runner/work/MindOS/MindOS/node_modules/.pnpm/esprima@4.0.1/node_modules:/home/runner/work/MindOS/MindOS/node_modules/.pnpm/node_modules"
+  export NODE_PATH="/home/runner/work/mindos-dev/mindos-dev/node_modules/.pnpm/esprima@4.0.1/node_modules/esprima/bin/node_modules:/home/runner/work/mindos-dev/mindos-dev/node_modules/.pnpm/esprima@4.0.1/node_modules/esprima/node_modules:/home/runner/work/mindos-dev/mindos-dev/node_modules/.pnpm/esprima@4.0.1/node_modules:/home/runner/work/mindos-dev/mindos-dev/node_modules/.pnpm/node_modules"
 else
-  export NODE_PATH="/home/runner/work/MindOS/MindOS/node_modules/.pnpm/esprima@4.0.1/node_modules/esprima/bin/node_modules:/home/runner/work/MindOS/MindOS/node_modules/.pnpm/esprima@4.0.1/node_modules/esprima/node_modules:/home/runner/work/MindOS/MindOS/node_modules/.pnpm/esprima@4.0.1/node_modules:/home/runner/work/MindOS/MindOS/node_modules/.pnpm/node_modules:$NODE_PATH"
+  export NODE_PATH="/home/runner/work/mindos-dev/mindos-dev/node_modules/.pnpm/esprima@4.0.1/node_modules/esprima/bin/node_modules:/home/runner/work/mindos-dev/mindos-dev/node_modules/.pnpm/esprima@4.0.1/node_modules/esprima/node_modules:/home/runner/work/mindos-dev/mindos-dev/node_modules/.pnpm/esprima@4.0.1/node_modules:/home/runner/work/mindos-dev/mindos-dev/node_modules/.pnpm/node_modules:$NODE_PATH"
 fi
 if [ -x "$basedir/node" ]; then
   exec "$basedir/node"  "$basedir/../../../../../esprima@4.0.1/node_modules/esprima/bin/esvalidate.js" "$@"

package/_standalone/__node_modules/global-agent/node_modules/.bin/semver

@@ -10,9 +10,9 @@ case `uname` in
 esac
 
 if [ -z "$NODE_PATH" ]; then
-  export NODE_PATH="/home/runner/work/MindOS/MindOS/node_modules/.pnpm/semver@7.7.4/node_modules/semver/bin/node_modules:/home/runner/work/MindOS/MindOS/node_modules/.pnpm/semver@7.7.4/node_modules/semver/node_modules:/home/runner/work/MindOS/MindOS/node_modules/.pnpm/semver@7.7.4/node_modules:/home/runner/work/MindOS/MindOS/node_modules/.pnpm/node_modules"
+  export NODE_PATH="/home/runner/work/mindos-dev/mindos-dev/node_modules/.pnpm/semver@7.7.4/node_modules/semver/bin/node_modules:/home/runner/work/mindos-dev/mindos-dev/node_modules/.pnpm/semver@7.7.4/node_modules/semver/node_modules:/home/runner/work/mindos-dev/mindos-dev/node_modules/.pnpm/semver@7.7.4/node_modules:/home/runner/work/mindos-dev/mindos-dev/node_modules/.pnpm/node_modules"
 else
-  export NODE_PATH="/home/runner/work/MindOS/MindOS/node_modules/.pnpm/semver@7.7.4/node_modules/semver/bin/node_modules:/home/runner/work/MindOS/MindOS/node_modules/.pnpm/semver@7.7.4/node_modules/semver/node_modules:/home/runner/work/MindOS/MindOS/node_modules/.pnpm/semver@7.7.4/node_modules:/home/runner/work/MindOS/MindOS/node_modules/.pnpm/node_modules:$NODE_PATH"
+  export NODE_PATH="/home/runner/work/mindos-dev/mindos-dev/node_modules/.pnpm/semver@7.7.4/node_modules/semver/bin/node_modules:/home/runner/work/mindos-dev/mindos-dev/node_modules/.pnpm/semver@7.7.4/node_modules/semver/node_modules:/home/runner/work/mindos-dev/mindos-dev/node_modules/.pnpm/semver@7.7.4/node_modules:/home/runner/work/mindos-dev/mindos-dev/node_modules/.pnpm/node_modules:$NODE_PATH"
 fi
 if [ -x "$basedir/node" ]; then
   exec "$basedir/node"  "$basedir/../../../../../semver@7.7.4/node_modules/semver/bin/semver.js" "$@"

package/_standalone/__node_modules/has-flag/index.js

@@ -0,0 +1,8 @@
+'use strict';
+
+module.exports = (flag, argv = process.argv) => {
+	const prefix = flag.startsWith('-') ? '' : (flag.length === 1 ? '-' : '--');
+	const position = argv.indexOf(prefix + flag);
+	const terminatorPosition = argv.indexOf('--');
+	return position !== -1 && (terminatorPosition === -1 || position < terminatorPosition);
+};

package/_standalone/__node_modules/has-flag/license

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) Sindre Sorhus <sindresorhus@gmail.com> (sindresorhus.com)
+
+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/_standalone/__node_modules/has-flag/package.json

@@ -0,0 +1,46 @@
+{
+	"name": "has-flag",
+	"version": "4.0.0",
+	"description": "Check if argv has a specific flag",
+	"license": "MIT",
+	"repository": "sindresorhus/has-flag",
+	"author": {
+		"name": "Sindre Sorhus",
+		"email": "sindresorhus@gmail.com",
+		"url": "sindresorhus.com"
+	},
+	"engines": {
+		"node": ">=8"
+	},
+	"scripts": {
+		"test": "xo && ava && tsd"
+	},
+	"files": [
+		"index.js",
+		"index.d.ts"
+	],
+	"keywords": [
+		"has",
+		"check",
+		"detect",
+		"contains",
+		"find",
+		"flag",
+		"cli",
+		"command-line",
+		"argv",
+		"process",
+		"arg",
+		"args",
+		"argument",
+		"arguments",
+		"getopt",
+		"minimist",
+		"optimist"
+	],
+	"devDependencies": {
+		"ava": "^1.4.1",
+		"tsd": "^0.7.2",
+		"xo": "^0.24.0"
+	}
+}

package/_standalone/__node_modules/jsdom/node_modules/.bin/specificity

@@ -10,9 +10,9 @@ case `uname` in
 esac
 
 if [ -z "$NODE_PATH" ]; then
-  export NODE_PATH="/home/runner/work/MindOS/MindOS/node_modules/.pnpm/@bramus+specificity@2.4.2/node_modules/@bramus/specificity/bin/node_modules:/home/runner/work/MindOS/MindOS/node_modules/.pnpm/@bramus+specificity@2.4.2/node_modules/@bramus/specificity/node_modules:/home/runner/work/MindOS/MindOS/node_modules/.pnpm/@bramus+specificity@2.4.2/node_modules/@bramus/node_modules:/home/runner/work/MindOS/MindOS/node_modules/.pnpm/@bramus+specificity@2.4.2/node_modules:/home/runner/work/MindOS/MindOS/node_modules/.pnpm/node_modules"
+  export NODE_PATH="/home/runner/work/mindos-dev/mindos-dev/node_modules/.pnpm/@bramus+specificity@2.4.2/node_modules/@bramus/specificity/bin/node_modules:/home/runner/work/mindos-dev/mindos-dev/node_modules/.pnpm/@bramus+specificity@2.4.2/node_modules/@bramus/specificity/node_modules:/home/runner/work/mindos-dev/mindos-dev/node_modules/.pnpm/@bramus+specificity@2.4.2/node_modules/@bramus/node_modules:/home/runner/work/mindos-dev/mindos-dev/node_modules/.pnpm/@bramus+specificity@2.4.2/node_modules:/home/runner/work/mindos-dev/mindos-dev/node_modules/.pnpm/node_modules"
 else
-  export NODE_PATH="/home/runner/work/MindOS/MindOS/node_modules/.pnpm/@bramus+specificity@2.4.2/node_modules/@bramus/specificity/bin/node_modules:/home/runner/work/MindOS/MindOS/node_modules/.pnpm/@bramus+specificity@2.4.2/node_modules/@bramus/specificity/node_modules:/home/runner/work/MindOS/MindOS/node_modules/.pnpm/@bramus+specificity@2.4.2/node_modules/@bramus/node_modules:/home/runner/work/MindOS/MindOS/node_modules/.pnpm/@bramus+specificity@2.4.2/node_modules:/home/runner/work/MindOS/MindOS/node_modules/.pnpm/node_modules:$NODE_PATH"
+  export NODE_PATH="/home/runner/work/mindos-dev/mindos-dev/node_modules/.pnpm/@bramus+specificity@2.4.2/node_modules/@bramus/specificity/bin/node_modules:/home/runner/work/mindos-dev/mindos-dev/node_modules/.pnpm/@bramus+specificity@2.4.2/node_modules/@bramus/specificity/node_modules:/home/runner/work/mindos-dev/mindos-dev/node_modules/.pnpm/@bramus+specificity@2.4.2/node_modules/@bramus/node_modules:/home/runner/work/mindos-dev/mindos-dev/node_modules/.pnpm/@bramus+specificity@2.4.2/node_modules:/home/runner/work/mindos-dev/mindos-dev/node_modules/.pnpm/node_modules:$NODE_PATH"
 fi
 if [ -x "$basedir/node" ]; then
   exec "$basedir/node"  "$basedir/../../../../../@bramus+specificity@2.4.2/node_modules/@bramus/specificity/bin/cli.js" "$@"

package/_standalone/__node_modules/koffi/doc/benchmarks.md

@@ -0,0 +1,126 @@
+# Overview
+
+Here is a quick overview of the execution time of Koffi calls on three benchmarks, where it is compared to a theoretical ideal FFI implementation (approximated with pre-compiled static N-API glue code):
+
+- The first benchmark is based on `rand()` calls
+- The second benchmark is based on `atoi()` calls
+- The third benchmark is based on [Raylib](https://www.raylib.com/)
+
+<p style="text-align: center;">
+    <a href="{{ ASSET static/perf_linux.png }}" target="_blank"><img src="{{ ASSET static/perf_linux.png }}" alt="Linux x86_64 performance" style="width: 350px;"/></a>
+    <a href="{{ ASSET static/perf_windows.png }}" target="_blank"><img src="{{ ASSET static/perf_windows.png }}" alt="Windows x86_64 performance" style="width: 350px;"/></a>
+</p>
+
+These results are detailed and explained below, and compared to node-ffi/node-ffi-napi.
+
+# Linux x86_64
+
+The results presented below were measured on my x86_64 Linux machine (AMD Ryzen™ 5 2600).
+
+## rand results
+
+This test is based around repeated calls to a simple standard C function `rand`, and has three implementations:
+
+- the first one is the reference, it calls rand through an N-API module, and is close to the theoretical limit of a perfect (no overhead) Node.js > C FFI implementation (pre-compiled static glue code)
+- the second one calls rand through Koffi
+- the third one uses the official Node.js FFI implementation, node-ffi-napi
+
+Benchmark     | Iteration time | Relative performance | Overhead
+------------- | -------------- | -------------------- | --------
+rand_napi     | 569 ns         | x1.00                | (ref)
+rand_koffi    | 855 ns         | x0.67                | +50%
+rand_node_ffi | 58730 ns       | x0.010               | +10228%
+
+Because rand is a pretty small function, the FFI overhead is clearly visible.
+
+## atoi results
+
+This test is similar to the rand one, but it is based on `atoi`, which takes a string parameter. Javascript (V8) to C string conversion is relatively slow and heavy.
+
+Benchmark     | Iteration time | Relative performance | Overhead
+------------- | -------------- | -------------------- | --------
+atoi_napi     | 1039 ns        | x1.00                | (ref)
+atoi_koffi    | 1642 ns        | x0.63                | +58%
+atoi_node_ffi | 164790 ns      | x0.006               | +15767%
+
+Because atoi is a pretty small function, the FFI overhead is clearly visible.
+
+## Raylib results
+
+This benchmark uses the CPU-based image drawing functions in Raylib. The calls are much heavier than in previous benchmarks, thus the FFI overhead is reduced. In this implementation, Koffi is compared to:
+
+- Baseline: Full C++ version of the code (no JS)
+- [node-raylib](https://github.com/RobLoach/node-raylib): This is a native wrapper implemented with N-API
+
+Benchmark          | Iteration time | Relative performance | Overhead
+------------------ | -------------- | -------------------- | --------
+raylib_cc          | 17.5 µs        | x1.34                | -25%
+raylib_node_raylib | 23.4 µs        | x1.00                | (ref)
+raylib_koffi       | 28.8 µs        | x0.81                | +23%
+raylib_node_ffi    | 103.9 µs       | x0.23                | +344%
+
+# Windows x86_64
+
+The results presented below were measured on my x86_64 Windows machine (Intel® Core™ i5-4460).
+
+## rand results
+
+This test is based around repeated calls to a simple standard C function `rand`, and has three implementations:
+
+- the first one is the reference, it calls rand through an N-API module, and is close to the theoretical limit of a perfect (no overhead) Node.js > C FFI implementation (pre-compiled static glue code)
+- the second one calls rand through Koffi
+- the third one uses the official Node.js FFI implementation, node-ffi-napi
+
+Benchmark     | Iteration time | Relative performance | Overhead
+------------- | -------------- | -------------------- | --------
+rand_napi     | 859 ns         | x1.00                | (ref)
+rand_koffi    | 1352 ns        | x0.64                | +57%
+rand_node_ffi | 35640 ns       | x0.02                | +4048%
+
+Because rand is a pretty small function, the FFI overhead is clearly visible.
+
+## atoi results
+
+This test is similar to the rand one, but it is based on `atoi`, which takes a string parameter. Javascript (V8) to C string conversion is relatively slow and heavy.
+
+The results below were measured on my x86_64 Windows machine (Intel® Core™ i5-4460):
+
+Benchmark     | Iteration time | Relative performance | Overhead
+------------- | -------------- | -------------------- | --------
+atoi_napi     | 1336 ns        | x1.00                | (ref)
+atoi_koffi    | 2440 ns        | x0.55                | +83%
+atoi_node_ffi | 136890 ns      | x0.010               | +10144%
+
+Because atoi is a pretty small function, the FFI overhead is clearly visible.
+
+## Raylib results
+
+This benchmark uses the CPU-based image drawing functions in Raylib. The calls are much heavier than in the atoi benchmark, thus the FFI overhead is reduced. In this implementation, Koffi is compared to:
+
+- [node-raylib](https://github.com/RobLoach/node-raylib) (baseline): This is a native wrapper implemented with N-API
+- raylib_cc: C++ implementation of the benchmark, without any Javascript
+
+Benchmark          | Iteration time | Relative performance | Overhead
+------------------ | -------------- | -------------------- | --------
+raylib_cc          | 18.2 µs        | x1.50                | -33%
+raylib_node_raylib | 27.3 µs        | x1.00                | (ref)
+raylib_koffi       | 29.8 µs        | x0.92                | +9%
+raylib_node_ffi    | 96.3 µs        | x0.28                | +253%
+
+# Running benchmarks
+
+Please note that all benchmark results on this page are made with Clang-built binaries.
+
+```sh
+cd koffi
+node ../../cnoke/cnoke.js --prefer-clang
+
+cd koffi/benchmark
+node ../../cnoke/cnoke.js --prefer-clang
+```
+
+Once everything is built and ready, run:
+
+```sh
+node benchmark.js
+```

package/_standalone/__node_modules/koffi/doc/callbacks.md

@@ -0,0 +1,210 @@
+# Callback types
+
+*Changed in Koffi 2.7*
+
+In order to pass a JS function to a C function expecting a callback, you must first create a callback type with the expected return type and parameters. The syntax is similar to the one used to load functions from a shared library.
+
+```js
+// ES6 syntax: import koffi from 'koffi';
+const koffi = require('koffi');
+
+// With the classic syntax, this callback expects an integer and returns nothing
+const ExampleCallback = koffi.proto('ExampleCallback', 'void', ['int']);
+
+// With the prototype parser, this callback expects a double and float, and returns the sum as a double
+const AddDoubleFloat = koffi.proto('double AddDoubleFloat(double d, float f)');
+```
+> [!NOTE]
+> The function `koffi.proto()` was introduced in Koffi 2.4, it was called `koffi.callback()` in earlier versions.
+
+For alternative [calling conventions](functions#calling-conventions) (such as `stdcall` on Windows x86 32-bit), you can specify as the first argument with the classic syntax, or after the return type in prototype strings, like this:
+
+```js
+const HANDLE = koffi.pointer('HANDLE', koffi.opaque());
+const HWND = koffi.alias('HWND', HANDLE);
+
+// These two declarations work the same, and use the __stdcall convention on Windows x86
+const EnumWindowsProc = koffi.proto('bool __stdcall EnumWindowsProc (HWND hwnd, long lParam)');
+const EnumWindowsProc = koffi.proto('__stdcall', 'EnumWindowsProc', 'bool', ['HWND', 'long']);
+```
+
+> [!WARNING]
+> You have to make sure you **get the calling convention right** (such as specifying __stdcall for a Windows API callback), or your code will crash on Windows 32-bit.
+>
+> Before Koffi 2.7, it was *impossible to use an alternative callback calling convention with the classic syntax*. Use a prototype string or *upgrade to Koffi 2.7* to solve this limitation.
+
+Once your callback type is declared, you can use a pointer to it in struct definitions, as function parameters and/or return types, or to call/decode function pointers.
+
+> [!NOTE]
+> Callbacks **have changed in version 2.0**.
+>
+> In Koffi 1.x, callbacks were defined in a way that made them usable directly as parameter and return types, obscuring the underlying pointer.
+>
+> Now, you must use them through a pointer: `void CallIt(CallbackType func)` in Koffi 1.x becomes `void CallIt(CallbackType *func)` in version 2.0 and newer.
+>
+> Consult the [migration guide](migration) for more information.
+
+# Transient and registered callbacks
+
+Koffi only uses predefined static trampolines, and does not need to generate code at runtime, which makes it compatible with platforms with hardened W^X migitations (such as PaX mprotect). However, this imposes some restrictions on the maximum number of callbacks, and their duration.
+
+Thus, Koffi distinguishes two callback modes:
+
+- [Transient callbacks](#transient-callbacks) can only be called while the C function they are passed to is running, and are invalidated when it returns. If the C function calls the callback later, the behavior is undefined, though Koffi tries to detect such cases. If it does, an exception will be thrown, but this is no guaranteed. However, they are simple to use, and don't require any special handling.
+- [Registered callbacks](#registered-callbacks) can be called at any time, but they must be manually registered and unregistered. A limited number of registered callbacks can exist at the same time.
+
+You need to specify the correct [calling convention](functions#calling-conventions) on x86 platforms, or the behavior is undefined (Node will probably crash). Only *cdecl* and *stdcall* callbacks are supported.
+
+## Transient callbacks
+
+Use transient callbacks when the native C function only needs to call them while it runs (e.g. qsort, progress callback, `sqlite3_exec`). Here is a small example with the C part and the JS part.
+
+```c
+#include <string.h>
+
+int TransferToJS(const char *name, int age, int (*cb)(const char *str, int age))
+{
+    char buf[64];
+    snprintf(buf, sizeof(buf), "Hello %s!", str);
+    return cb(buf, age);
+}
+```
+
+```js
+// ES6 syntax: import koffi from 'koffi';
+const koffi = require('koffi');
+
+const lib = koffi.load('./callbacks.so'); // Fake path
+
+const TransferCallback = koffi.proto('int TransferCallback(const char *str, int age)');
+
+const TransferToJS = lib.func('TransferToJS', 'int', ['str', 'int', koffi.pointer(TransferCallback)]);
+
+let ret = TransferToJS('Niels', 27, (str, age) => {
+    console.log(str);
+    console.log('Your age is:', age);
+    return 42;
+});
+console.log(ret);
+
+// This example prints:
+//   Hello Niels!
+//   Your age is: 27
+//   42
+```
+
+## Registered callbacks
+
+*New in Koffi 2.0 (explicit this binding in Koffi 2.2)*
+
+Use registered callbacks when the function needs to be called at a later time (e.g. log handler, event handler, `fopencookie/funopen`). Call `koffi.register(func, type)` to register a callback function, with two arguments: the JS function, and the callback type.
+
+When you are done, call `koffi.unregister()` (with the value returned by `koffi.register()`) to release the slot. A maximum of 8192 callbacks can exist at the same time. Failure to do so will leak the slot, and subsequent registrations may fail (with an exception) once all slots are used.
+
+The example below shows how to register and unregister delayed callbacks.
+
+```c
+static const char *(*g_cb1)(const char *name);
+static void (*g_cb2)(const char *str);
+
+void RegisterFunctions(const char *(*cb1)(const char *name), void (*cb2)(const char *str))
+{
+    g_cb1 = cb1;
+    g_cb2 = cb2;
+}
+
+void SayIt(const char *name)
+{
+    const char *str = g_cb1(name);
+    g_cb2(str);
+}
+```
+
+```js
+// ES6 syntax: import koffi from 'koffi';
+const koffi = require('koffi');
+
+const lib = koffi.load('./callbacks.so'); // Fake path
+
+const GetCallback = koffi.proto('const char *GetCallback(const char *name)');
+const PrintCallback = koffi.proto('void PrintCallback(const char *str)');
+
+const RegisterFunctions = lib.func('void RegisterFunctions(GetCallback *cb1, PrintCallback *cb2)');
+const SayIt = lib.func('void SayIt(const char *name)');
+
+let cb1 = koffi.register(name => 'Hello ' + name + '!', koffi.pointer(GetCallback));
+let cb2 = koffi.register(console.log, 'PrintCallback *');
+
+RegisterFunctions(cb1, cb2);
+SayIt('Kyoto'); // Prints Hello Kyoto!
+
+koffi.unregister(cb1);
+koffi.unregister(cb2);
+```
+
+Starting *with Koffi 2.2*, you can optionally specify the `this` value for the function as the first argument.
+
+```js
+class ValueStore {
+    constructor(value) { this.value = value; }
+    get() { return this.value; }
+}
+
+let store = new ValueStore(42);
+
+let cb1 = koffi.register(store.get, 'IntCallback *'); // If a C function calls cb1 it will fail because this will be undefined
+let cb2 = koffi.register(store, store.get, 'IntCallback *'); // However in this case, this will match the store object
+```
+
+# Special considerations
+
+## Decoding pointer arguments
+
+*New in Koffi 2.2, changed in Koffi 2.3*
+
+Koffi does not have enough information to convert callback pointer arguments to an appropriate JS value. In this case, your JS function will receive an opaque *External* object.
+
+You can pass this value through to another C function that expects a pointer of the same type, or you can use [koffi.decode()](variables#decode-to-js-values) function to decode pointer arguments.
+
+The following examples uses it to sort an array of strings in-place with the standard C function `qsort()`:
+
+```js
+// ES6 syntax: import koffi from 'koffi';
+const koffi = require('koffi');
+
+const lib = koffi.load('libc.so.6');
+
+const SortCallback = koffi.proto('int SortCallback(const void *first, const void *second)');
+const qsort = lib.func('void qsort(_Inout_ void *array, size_t count, size_t size, SortCallback *cb)');
+
+let array = ['foo', 'bar', '123', 'foobar'];
+
+qsort(koffi.as(array, 'char **'), array.length, koffi.sizeof('void *'), (ptr1, ptr2) => {
+    let str1 = koffi.decode(ptr1, 'char *');
+    let str2 = koffi.decode(ptr2, 'char *');
+
+    return str1.localeCompare(str2);
+});
+
+console.log(array); // Prints ['123', 'bar', 'foo', 'foobar']
+```
+
+## Asynchronous callbacks
+
+*New in Koffi 2.2.2*
+
+JS execution is inherently single-threaded, so JS callbacks must run on the main thread. There are two ways you may want to call a callback function from another thread:
+
+- Call the callback from an asynchronous FFI call (e.g. `waitpid.async`)
+- Inside a synchronous FFI call, pass the callback to another thread
+
+In both cases, Koffi will queue the call back to JS to run on the main thread, as soon as the JS event loop has a chance to run (for example when you await a promise).
+
+> [!WARNING]
+> Be careful, you can easily get into a deadlock situation if you call a callback from a secondary thread and your main thread never lets the JS event loop run (for example, if the main thread waits for the secondary thread to finish something itself).
+
+# Handling of exceptions
+
+If an exception happens inside the JS callback, the C API will receive 0 or NULL (depending on the return value type).
+
+Handle the exception yourself (with try/catch) if you need to handle exceptions differently.