@cesdk/node-native 1.77.0-nightly.20260610

package/LICENSE.md

@@ -0,0 +1,137 @@
+# Creative Editor Software Development Kit (SDK)
+
+## Terms of Service
+
+### 1. Subject Matter
+
+1.1 These Terms of Service (together with any applicable Order Form the "**Agreement**") govern all rights granted by Licensor to use and commercially exploit any of the IMG.LY SDKs (the "**Software**"), namely the CreativeEditor SDK and/or PhotoEditor SDK and/or VideoEditor SDK and/or imglyKit SDK.
+
+1.2 The Agreement is entered into by and between IMG.LY GmbH, Kortumstraße 19-21, 44787 Bochum, Germany (the "**Licensor**") and the entity identified in the Order Form (the "**Licensee**", together with Licensor the "**Parties**") as of the effective date the Order Form is last signed on.
+
+1.3 This Agreement shall govern the use of the Software for commercial purposes. To the extent the Software is intended to be used for non-commercial purposes only, an alternative licensing scheme may be available upon Licensor's discretion.
+
+### 2. Order Form
+
+2.1 An "**Order Form**" may either be executed (i) by the Parties upon individual negotiation or (ii) via an online order issued by Licensee via Licensor's website at img.ly (the "**Website**") that has been confirmed by Licensor. Online orders not confirmed within 14 days after issuance shall be considered denied.
+
+2.2 No rights shall be granted to Licensee by virtue of these Terms of Service alone as such grant requires the execution of an Order Form making reference to these Terms of Service.
+
+2.3 The Order Form shall specify the environment for the Software that shall be licensed by Licensee. The Software is currently available for integration in the following environments, but is not limited to: (i) Web, (ii) iOS, (iii) Android, and (iv) Node.js.
+
+2.4 The Order Form shall specify (i) the Subscription Term and (ii) the License Fees. Unless specified otherwise in the Order Form, the Subscription Term shall be based on monthly or annual periods for payment of the License Fees (the "**Payment Periods**").
+
+2.5 Licensor may choose to offer Licensee a trial period specified by Licensor to test the Software in a dedicated testing environment not subject to License Fees (the "**Trial Period**"). Licensor may also choose to offer Licensee extended trial periods subject to License Fees (“Extended Trial Period”). These Trial Periods and/or Extended Trial Periods will automatically end upon completion and do not require termination. Licensee acknowledges that converting from a Trial Period and/or Extended Trial Period to a regular Subscription Term may require additional steps, as outlined in the Order Form. Upon expiration of the Trial Period and/or Extended Trial Period, the right to test the Software shall cease without further notice. Licensee shall then be required to execute an Order Form to obtain a License for a Subscription Term in case the Software shall be further used.
+
+2.6 The Order Form can include usage-based pricing models based on factors such as monthly active users or number of exports. The pricing can also be based on Licensee’s company size. Licensee shall not make any false statements in regard to the eligibility thresholds stated on the Order Form or relevant for pricing. Further Licensee is solely responsible to keep Licensor informed about any changes on its part with respect to the eligibility thresholds or aspects relevant for pricing stated on the Order Form. 
+
+2.7 Licensee shall inform Licensor of any "**agency relationship”, if necessary under a Non-Disclosure Agreement, under which Licensee effectively shall not be the entity making use of the Software but intends to source the Software for use by a third party. In such case, Licensor shall be free to execute an Agreement with the entity effectively making use of the Software as Licensee only.  
+
+### 3. Grant of Rights
+
+3.1 Licensor shall grant to Licensee a worldwide, non-exclusive, non-transferable, non-sublicensable right to use the Software subject to the terms of this Agreement, in particular with the specifications as set out in the Order Form (the "**License**").
+
+3.2 The License shall pertain to the Software in object code format as well as to content data (fonts, stickers, stock images, etc.) included therein. In order to enable integration of the Software, parts of the Software may be provided in source code format if agreed upon in the Order Form individually or if offered by Licensor in its free discretion; in such case, the License shall also pertain to the Software in source code format.
+
+3.3 The License shall be limited to the right (i) to copy and – in case of disclosure in source code format – modify the Software solely for integration into one of Licensee's products (website or app) (the "**Licensee’s Product**") in accordance with the requirements of interfaces and implementation guidelines as issued by Licensor (the "**Integrated Software**") and (ii) to copy, distribute and make available the Integrated Software to Licensee's end customers in object code format (the License does not cover distribution, making available or disclosure of the Software or any part thereof in source code format).
+
+### 4. Obligations and Restrictions
+
+4.1 Licensee shall not reproduce, disassemble, or reverse assemble any portion of the Software or otherwise derive its source code, except to the extent that such activity is specifically permitted by this Agreement or by statutory law.
+
+4.2 Licensee shall not redistribute the Software or its modifications other than by integrating the Software into Licensee's Product. Use in context of more than one of Licensee's Products shall require multiple Licenses accordingly via respective Order Forms. Licensee's Product shall have a substantially different functionality than the Software (i.e. must not be described as a photo editor and/or video editor, respective development kit, library, or product commercially competing with the Software); otherwise, Licensor shall be entitled to terminate the Agreement and revoke the License at any time.
+
+4.3 Licensee shall not use the Software in connection with or to promote any products, services, or materials that constitute or promote spyware, adware, or other malicious programs or code, unsolicited mass distribution of email (spam), defamatory, pornographic, abusive or otherwise offensive content; otherwise, Licensor shall be entitled to terminate the Agreement and revoke the License at any time.
+
+4.4 Licensor shall be entitled to verify and validate Licensee's use of the Software in line with this Agreement via respective functionalities of the Software. In particular, Licensor is entitled to make access to the Software dependent from successful remote validation (via API) of a license key allocated to an active Subscription Term and covering the intended access and use.
+
+4.5 Licensor shall be entitled to use server-side monitoring tools to analyze use of the Software by users. Licensee shall safeguard that such monitoring by Licensor can be performed in accordance with applicable privacy and data protection law via respective notices and, if required, opt-in procedures. Licensor will support Licensee to the extent required by providing required information and instruction. 
+
+### 5. Proprietary Rights
+
+5.1 All rights not expressly granted to Licensee are reserved by Licensor. Licensee acknowledges and agrees that all rights to modifications of the source code made by Licensee to enable integration of the Software shall belong to the Licensor as part of the Software; the Licensee shall assign all respective rights to Licensor or, in case no assignment is feasible under applicable law, Licensee shall grant a worldwide, exclusive, transferable, sublicensable right to use such modifications without any restrictions. Licensee shall have no rights to use, copy, or reproduce the Software except as expressly set forth in this Agreement.
+
+5.2 No rights shall be granted with regard to trademarks, trade names, trade dress and trade secrets to Licensee except for the limited right of use provided under the License.
+
+### 6. Third Party Components
+
+6.1 The Software implements components licensed under open source licenses ("OSS Components**") and further software components and content data (fonts, stickers, stock images, etc.) provided by third parties under applicable licensing terms ("Third Party Components**"). The use of the OSS Components and the Third Party Components is subject to the applicable separate licensing terms. A list of the OSS Components and Third Party Components with reference to the applicable licensing terms is accessible online via https://img.ly/acknowledgements. Licensor does not act as sublicensor or agent in this regard and assumes or acknowledges no warranty or liability for the OSS Components and the Third Party Components.
+
+6.2 Licensee shall only use further third party software components or content data (fonts, stickers, stock images, etc.) with the Software to the extent that Licensee is entitled to such use. Licensor shall not be liable or responsible for any use of third party software components or content data by Licensee. Licensee shall indemnify and hold harmless Licensor from any third-party claims caused by Licensee's actions involving third party software components or content data.
+
+### 7. Payment
+
+7.1 The license fees as specified in the Order Form (the "**License Fees**") shall be due and payable in line with the Payment Periods. To the extent the due date is not specified in the Order Form, the License Fees shall be due upon the execution of the Order Form and then upon the commencement of each further Payment Period for all of the Subscription Term.
+
+7.2 Licensor shall invoice the License Fees to Licensee. Invoices are payable without deduction within 14 days of the date of the invoice and may be made by direct payment on the Website via credit card, if a respective option is provided by Licensor. If Licensee is in default of payment, the outstanding amount shall bear interest as applicable under statutory law. Licensor reserves all further rights resulting from default.
+
+7.3 Unless specified otherwise in the Order Form, the License Fees shall be paid in Euros. All amounts stated in the Order Form are excluding any applicable value added tax (VAT), unless explicitly specified otherwise. Licensee shall be responsible for any applicable sales, use, value added or similar taxes payable with respect to the licensing of the Software, or arising out of or in connection with this Agreement, other than taxes levied or imposed based upon Licensor's income or gross revenues. If Licensee has tax-exempt status, Licensee shall provide written evidence of such status to Licensor. Upon Licensor's request, Licensee shall provide its VAT identification number or other identification information required for invoicing purposes.
+
+7.4 The license fees specified in the Order Form (the "**License Fees**") are subject to price adjustments in accordance with changes in the Consumer Price Index ("CPI**") published by the European Central Bank (https://www.ecb.europa.eu/). Corresponding License Fee adjustments are made at renewal for annual Subscription Terms and after every 12 months for other Subscription Terms. 
+
+### 8. Delivery and Maintenance
+
+8.1 The Software shall be delivered via download from designated package repositories. The designated link for such download shall be provided in the Order Form. The use of the Software in a Subscription Term requires a key that shall be provided upon the initial payment of the License Fees, subject to the terms agreed upon in the Order Form. The key required for a Trial Period shall be provided upon commencement and deactivated upon expiration of the Trial Period.
+
+8.2 The Software and Documentation shall be provided in English language.
+
+8.3 Licensee shall be responsible for installing the Software and providing the system environment required to operate the Software in accordance with the requirements as set forth in the Documentation.
+
+8.4 Subject to any other specification in the Order Form, Licensor shall not provide any support and maintenance services other than the issuance of such updates, upgrades or patches for the Software as made available via the Website. Licensor shall have no obligation to provide support or maintenance for the Integrated Software or any modifications to the Software made by Licensee for integration into one of Licensee's Products.
+
+8.5 Licensor may choose to offer Licensee a separate Service Level Agreement detailing specific availability commitments against additional remuneration. Such availability commitments always exclude downtime due to planned maintenance and downtime outside Licensor’s control. In case of planned maintenance leading to downtime exceeding three hours, Licensor will notify Licensee via email.
+
+### 9. Term and Termination
+
+9.1 The term of the License shall be determined in the Order Form (the "**Subscription Term**"). The License shall commence upon initial payment of the License Fees and expire upon the end of the Subscription Term(s). Unless stated otherwise in the Order Form, the initial Subscription Term shall automatically be extended by further consecutive Subscription Terms unless either party notifies the other in writing of its intent not to extend the License prior to the end of the current Subscription Term. For monthly Subscription Terms, the notification must be given one week prior to the end of the then-current Subscription Term in order to be valid. For other Subscription Terms, the notification must be given one month prior to the end of the then-current Subscription Term in order to be valid. Upon expiration of the Subscription Term(s), the right to use the Software shall cease without further notice. To the extent the Subscription Term is not specified in the Order Form, Licensor shall be entitled to terminate the Agreement and revoke the License at any time.
+
+9.2 Either Party shall be entitled to immediately terminate this Agreement or suspend any rights granted hereunder upon notice to the other in the event that: (i) the other Party breaches any material term of this Agreement, Licensor may particularly revoke the License in case of default or other non-payment of License Fees or use of the Software in breach of Sections 3.3 or 5.1; or (ii) upon the other Party's dissolution, liquidation, or the appointment of a receiver, trustee, custodian, or similar agent for the Party's business or property. A change of control of Licensee, the sale of all or more than 50% of Licensee's assets, or a merger or reorganization of Licensee in which Licensee is not the surviving organization is considered dissolution of Licensee. In the event that Licensor terminates this Agreement for breach, all amounts due or to become due under this Agreement shall immediately become due and payable.
+
+9.3 Upon expiration of the Subscription Term or termination, each Party shall promptly remit to the other all unpaid monies due, or to become due, under this Agreement. Licensee shall return to Licensor or destroy all copies of the Software in its possession and provide written confirmation to that effect; this particularly applies to the Software in source code format in case such disclosure has occurred. In case of termination or revocation of the License, paid monies or due payments for any commenced Payment Periods shall not be refunded to Licensee.
+
+9.4 In addition to those provisions which by their nature are intended to survive any termination or expiration of this Agreement or any license granted hereunder, Sections 11, 12 and 13 of this Agreement shall specifically survive such expiration or termination.
+
+9.5 In the event of termination or expiration of the Subscription Term, the Licensee is obliged to promptly cease use of and remove the Software from all of its products. Until the Software is confirmed to be completely removed from all of the Licensee's products, Licensor reserves the right to continue to charge the Licensee the agreed License Fees. The Licensee must provide satisfactory evidence of the complete removal of the Software upon request of the Licensor.
+
+### 10. Warranty Claims
+
+10.1 Product descriptions shall not be deemed guaranteed unless separately agreed in writing.
+
+10.2 Rights in case of defects shall be excluded in case of minor or immaterial deviations from the characteristics of the Software or in the case of only slight impairment of use. Licensor shall further not be responsible for defects which are caused by improper use or operation. Licensor shall not be responsible for ensuring that any modifications made by Licensee to the Software for integration into one of Licensee's Products will work other versions of the Software.
+
+10.3 Any claims for damages are subject to the limitations set forth under Section 11 of this Agreement.
+
+### 11. Limitation of Liability
+
+11.1 Licensor shall be liable without restriction for damages caused intentionally or with gross negligence by Licensor, its legal representatives or assistants in performance. Licensor shall also be liable without restriction for death, personal injury or damage to health caused by Licensor, its legal representatives or assistants in performance. Furthermore, Licensor shall be liable without restriction for damages in accordance with the German Product Liability Act.
+
+11.2 Licensor shall be liable for damages caused by breach of its primary obligations under this Agreement by Licensor, its legal representatives or assistants in performance. Primary obligations are such duties that form the essence of the Agreement, which were decisive for the conclusion of the Agreement and on the performance of which Licensee may rely. If Licensor breaches its primary obligations with simple negligence, then its liability shall be limited to the amount which was foreseeable for Licensor at the time when the respective duty was performed. Any further liability of Licensor shall be excluded on the merits. In particular, any liability of Licensor for initial defects of the Software already present at the start of the Subscription Term shall be excluded. 
+
+11.3 The right to set off a claim shall be limited to such claims that are uncontested or have been finally established with legal effect.
+
+### 12. Confidentiality
+
+12.1 Each Party may be granted access to confidential information of the other Party during the term of this Agreement. Confidential information does not include information that: (i) is or becomes publicly available through no act or omission of the other party, (ii) is rightfully acquired by the recipient from a third party that was not under an obligation to hold the information in confidence, (iii) is independently developed by the recipient or, (iv) is previously known to the recipient without non-disclosure obligations. The terms of this Agreement and the source code to the Software shall constitute confidential information under this Agreement.
+
+12.2 Neither Party shall use any confidential information of the other Party other than for the purpose of exercising its rights or performing its obligations under this Agreement or disclose to any third party any confidential information of the other Party except as permitted under this Agreement. Disclosure of confidential information shall not be precluded if such disclosure is in response to a valid order of a court or other governmental body or is otherwise required by statutory law.
+
+12.3 Subject to the exceptions under Section 12.2., Licensee shall not disclose the terms of this Agreement to any third party.
+
+12.4 Non-disclosure agreements executed by the Parties independent from this Agreement shall remain in force.
+
+### 13. Final Provisions
+
+13.1 Licensor shall be entitled to identify Licensee as a customer and to refer to Licensee and its business by name, trademark and trade name, if applicable, on the Website and in Licensor's marketing materials.
+
+13.2 Licensor shall not accept, and this Agreement does not operate as an acceptance of, any different or additional terms and conditions, and this Agreement shall prevail over any such different or additional provisions, of any Licensee's order.
+
+13.3 All notices or reports shall be in writing or sent by email.
+
+13.4 Licensee may not assign this Agreement, in whole or in part to any third party without the prior written consent of Licensor.
+
+13.5 Amendments or additions to this Agreement must be made in writing to be effective. This shall also apply to amendments of this written form requirement.
+
+13.6 This Agreement shall be governed by the laws of the Federal Republic of Germany; the regulations of the UN Sales Convention shall be excluded.
+
+13.7 The courts for Licensor's registered office shall have exclusive jurisdiction over all disputes under and in connection with this Agreement.
+
+13.8 Should any provision of this Agreement be or become invalid, this shall not affect the validity of the remaining terms. In such event, the Parties shall be obliged to cooperate in the creation of terms which achieve such legally valid result as comes closest commercially to that of the invalid provision. The above shall apply accordingly to the closing of any gaps in the Agreement.

package/README.md

@@ -0,0 +1,474 @@
+![Hero image showing the configuration abilities of CE.SDK](https://img.ly/static/cesdk_release_header.png)
+
+# @cesdk/node-native
+
+Native Node.js bindings for the IMG.LY *Creative Engine*, the core of CE.SDK.
+A drop-in alternative to [`@cesdk/node`](https://www.npmjs.com/package/@cesdk/node)
+(WASM) that loads the engine as a platform-native N-API addon. The native
+build adds video and audio export, GPU-accelerated rendering, and removes the
+WASM 4 GB linear-memory ceiling.
+
+For full Creative Engine documentation see
+[https://img.ly/docs/cesdk/web/guides/headless/setup_node](https://img.ly/docs/cesdk/web/guides/headless/setup_node).
+
+## When to choose `@cesdk/node-native`
+
+Pick `@cesdk/node-native` if you need any of the following; otherwise stay on
+`@cesdk/node` (WASM), which has wider platform coverage:
+
+- **Video and audio export** (MP4 / H.264 via VideoToolbox on macOS, GStreamer
+  on Linux).
+- **Working memory above ~4 GB.** WASM linear memory is capped; native uses
+  the full process address space.
+- **Hardware-accelerated rendering** for image export on Metal (macOS) or EGL
+  (Linux). CPU fallback is automatic when no GPU is available.
+
+For raw call overhead the native addon also avoids the WASM↔JS boundary, but
+the practical impact is workload-dependent — measure on your own scenes
+before relying on a specific multiplier.
+
+## Supported platforms
+
+| OS    | Arch    | Node | Minimum OS                                       |
+| ----- | ------- | ---- | ------------------------------------------------ |
+| macOS | `arm64` | ≥ 20 | macOS 12 (Monterey)                              |
+| macOS | `x64`   | ≥ 20 | macOS 12 (Monterey)                              |
+| Linux | `x64`   | ≥ 20 | glibc ≥ 2.39 (Ubuntu 24.04, Debian 13, RHEL 10)  |
+
+**Not supported in this release:**
+
+- Windows
+- Linux `arm64`
+- musl-based distributions (Alpine, etc.)
+- AWS Lambda Node.js runtimes (AL2 / AL2023 ship glibc 2.26 / 2.34 — use
+  `@cesdk/node` for serverless until a manylinux build lands)
+
+`npm install @cesdk/node-native` succeeds on unsupported hosts (the main
+package itself has no platform filter), but the binary-carrying sibling is
+filtered out by npm's `os` / `cpu` / `libc` constraints and the first
+`require('@cesdk/node-native')` throws a clear error pointing at
+`@cesdk/node` (WASM). This is intentional so that conditional installs in
+Dockerfiles and CI don't fail at install time.
+
+## Installation
+
+```bash
+npm install @cesdk/node-native
+# or, to track nightly builds:
+npm install @cesdk/node-native@dev
+```
+
+## Usage
+
+ES Modules:
+
+```js
+import CreativeEngine from '@cesdk/node-native';
+
+const engine = await CreativeEngine.init({ license: 'YOUR_LICENSE_KEY' });
+const scene = engine.scene.create();
+const page = engine.block.create('page');
+engine.block.appendChild(scene, page);
+engine.block.setWidth(page, 1920);
+engine.block.setHeight(page, 1080);
+
+const png = await engine.block.export(page, 'image/png', {});
+// `png` is a Blob (same as @cesdk/node). Use `png.arrayBuffer()` to read.
+engine.dispose();
+```
+
+CommonJS:
+
+```js
+const CreativeEngine = require('@cesdk/node-native');
+
+CreativeEngine.init({ license: 'YOUR_LICENSE_KEY' }).then(async (engine) => {
+  // ... same API as above.
+  engine.dispose();
+});
+```
+
+> **Always call `engine.dispose()` when done.** The engine runs an internal
+> update timer (driving rendering and export), so until you dispose it the
+> Node.js event loop stays alive and the process will not exit on its own — a
+> short-lived script or a Lambda handler that skips `dispose()` will appear to
+> hang until timeout.
+
+## License & evaluation mode
+
+The CreativeEditor SDK is a commercial product. Purchase a license at
+<https://img.ly/pricing>.
+
+You can run the engine in **evaluation mode** by passing an empty string as
+the license key. In evaluation mode the engine prints an IMG.LY banner on
+stderr and watermarks output. There are three equivalent ways to enter it:
+
+```js
+// 1. Empty string at init.
+await CreativeEngine.init({ license: '' });
+
+// 2. Omit `license` entirely at init, then unlock later.
+const engine = await CreativeEngine.init();
+engine.editor.unlockWithLicense('');             // evaluation
+// engine.editor.unlockWithLicense('YOUR_KEY');  // upgrade in place
+
+// 3. Inspect the active key (empty string => evaluation mode).
+engine.editor.getActiveLicense();
+```
+
+## Linux runtime dependencies
+
+The Linux platform package statically links libc++ / libc++abi /
+libstdc++ into the addon, so a stock Ubuntu 24.04 / Debian 13 install
+needs only the engine's runtime dependencies. On `ubuntu:24.04` and
+`debian:13` the relevant packages are present by default; minimal base
+images (slim, distroless) need them installed explicitly.
+
+**Image / scene / archive workflows** depend on the standard graphics
+stack:
+
+```bash
+apt-get install -y \
+  libcurl4 \
+  libssl3 \
+  libfontconfig1 \
+  libfreetype6 \
+  libuuid1 \
+  libxcb1 \
+  libgl1 \
+  libegl1
+```
+
+**Video and audio export** additionally needs GStreamer 1.x plus the
+common plugin sets:
+
+```bash
+apt-get install -y \
+  libgstreamer1.0-0 \
+  gstreamer1.0-plugins-base \
+  gstreamer1.0-plugins-good \
+  gstreamer1.0-plugins-bad \
+  gstreamer1.0-plugins-ugly \
+  gstreamer1.0-libav \
+  gstreamer1.0-gl
+```
+
+A future release will offer a self-contained GStreamer bundle shipped
+inside the Linux platform package; until then, system GStreamer is
+required.
+
+### Supported Docker base images
+
+The Linux platform package ships with a **glibc ≥ 2.39 floor** (the
+`libc: ["glibc"]` npm filter blocks Alpine/musl at install time;
+older-glibc systems install successfully but fail at first
+`require('@cesdk/node-native')` with `version 'GLIBC_2.XX' not found`).
+
+| Base image | Works? | glibc | Notes |
+|---|---|---|---|
+| `ubuntu:24.04` (and `:24.04-slim`) | yes | 2.39 | Reference image |
+| `debian:13` (`trixie`, and `:13-slim`) | yes | 2.41 | |
+| `node:22-trixie` | yes | 2.41 | |
+| `gcr.io/distroless/nodejs22-debian13` | yes | 2.41 | Recommended distroless |
+| `node:22-alpine` | no | musl | Filtered at install |
+| `amazonlinux:2` / `:2023` | no | 2.26 / 2.34 | Below floor; also AWS Lambda base |
+| `public.ecr.aws/lambda/nodejs:22` | no | 2.34 | Below floor; see Lambda note below |
+
+Use `@cesdk/node` (WASM) on every "no" row above.
+
+### AWS Lambda
+
+The Linux platform package targets glibc 2.39+; AWS Lambda's Amazon Linux
+2 / 2023 base images ship glibc 2.26 / 2.34, both below the floor. A
+Lambda function that does `require('@cesdk/node-native')` will fail at
+load with `GLIBC_2.38 not found`. **Use `@cesdk/node` (WASM) on Lambda.**
+The `apps/cesdk_web_examples/cookbooks-aws-lambda/` cookbook documents
+the WASM-on-Lambda path.
+
+## Bundlers (webpack / esbuild / Next.js / Vite)
+
+`@cesdk/node-native` ships a native `.node` binary that bundlers cannot
+inline. Mark the package external and have the bundler emit the
+`.node` + the `assets/` resource bundle into the output as-is.
+
+### webpack / Next.js (server-side / API routes)
+
+```js
+// next.config.js — server side only, never the browser bundle
+module.exports = {
+  webpack(config, { isServer }) {
+    if (isServer) {
+      config.externals = [
+        ...(config.externals ?? []),
+        '@cesdk/node-native',
+        '@cesdk/node-native-darwin-arm64',
+        '@cesdk/node-native-darwin-x64',
+        '@cesdk/node-native-linux-x64',
+      ];
+    }
+    return config;
+  },
+  // Next.js 13+ App Router with server components:
+  experimental: {
+    serverComponentsExternalPackages: ['@cesdk/node-native'],
+  },
+};
+```
+
+### esbuild
+
+```js
+await esbuild.build({
+  // …
+  platform: 'node',
+  external: [
+    '@cesdk/node-native',
+    '@cesdk/node-native-darwin-arm64',
+    '@cesdk/node-native-darwin-x64',
+    '@cesdk/node-native-linux-x64',
+  ],
+});
+```
+
+### Vite (server / SSR)
+
+```js
+export default defineConfig({
+  ssr: {
+    external: ['@cesdk/node-native'],
+    noExternal: [],
+  },
+});
+```
+
+In every bundler the engine resource bundle (`@cesdk/node-native/assets/`)
+must reach the runtime layout intact. Either keep `node_modules/` next to
+the bundle output, or copy `node_modules/@cesdk/node-native/assets/`
+into the deploy artifact and point `CreativeEngine.init({ baseURL })` at
+that location explicitly.
+
+## Yarn Plug'n'Play
+
+Yarn PnP virtualises the `node_modules` graph through `.pnp.cjs`; the
+default mode keeps optional dependencies inside the zip cache, which
+breaks `dlopen` against the platform sibling package's `.node` because
+the dynamic linker cannot read into a zip filesystem. The fix is to opt
+the platform package out of PnP zipping by declaring it `unplugged`:
+
+```yaml
+# .yarnrc.yml
+nodeLinker: pnp
+pnpEnableInlining: false
+```
+
+```jsonc
+// package.json
+{
+  "dependencies": { "@cesdk/node-native": "^1.77.0-nightly.20260610" },
+  "dependenciesMeta": {
+    "@cesdk/node-native-darwin-arm64": { "unplugged": true },
+    "@cesdk/node-native-darwin-x64":   { "unplugged": true },
+    "@cesdk/node-native-linux-x64":    { "unplugged": true }
+  }
+}
+```
+
+The `unplugged` setting causes Yarn to extract the matching platform
+sibling into `.yarn/unplugged/`, where the `.node` resolves to a real
+filesystem path that `dlopen` can consume. The `nodeLinker: node-modules`
+mode (Yarn classic compatibility) doesn't need this — it materialises a
+real `node_modules/` tree on disk and works out of the box.
+
+## Migration from `@cesdk/node`
+
+The Block, Scene, Editor, Asset, Event, and Variable APIs are the same. For
+the vast majority of code paths, `@cesdk/node-native` is a drop-in
+replacement: change the import and run.
+
+```diff
+- import CreativeEngine from '@cesdk/node';
++ import CreativeEngine from '@cesdk/node-native';
+```
+
+Binary-returning methods (`block.export`, `block.exportVideo`,
+`block.exportAudio`, `block.saveToArchive`, `scene.saveToArchive`) return
+`Blob` on both packages. `block.export()` accepts both the WASM-shaped
+`(block, { mimeType, ... })` and the positional `(block, mimeType, options)`
+signatures, so existing call sites don't need rewriting.
+
+Default asset-source helpers (`engine.asset.addDefaultAssetSources`,
+`engine.asset.addDemoAssetSources`) are available with the same options
+(`baseURL`, `excludeAssetSourceIds`, `sceneMode`).
+
+### Intentional divergence
+
+- `engine.update()` is public on `@cesdk/node-native` (the wrapper pumps
+  frames internally during exports; you only need it if you're driving
+  frame-perfect work manually). On WASM it's private — the browser's
+  animation frame drives it.
+
+### Swapping in for tooling that pins `@cesdk/node`
+
+For test runs or third-party packages that import `@cesdk/node` by literal
+name (e.g. internal importers/exporters), point your bundler/test runner's
+module alias at `@cesdk/node-native` — its export shape matches `@cesdk/node`,
+so no call sites need to change:
+
+```js
+// e.g. in a vitest/vite config
+resolve: { alias: { '@cesdk/node': '@cesdk/node-native' } }
+```
+
+In application code, prefer importing `@cesdk/node-native` directly.
+
+## Video export
+
+`@cesdk/node-native` is the first IMG.LY-distributed Node binding to expose
+video export. The two known foot-guns:
+
+1. **`options.duration` defaults to `0`** for parity with the WASM
+   `@cesdk/node` package. The encoder treats `0` as "render a single frame",
+   which is rarely the intended outcome. Always pass an explicit duration:
+
+   ```js
+   await engine.block.exportVideo(page, 'video/mp4', onProgress, {
+     duration: 3.0,
+     framerate: 30,
+   });
+   ```
+
+2. **Scenes loaded from an archive must wait for AV resources** before
+   `exportVideo` can make progress; otherwise the encoder spins on resources
+   that haven't been fetched and the progress callback never fires. Pass
+   `waitForResources: true` when loading a video scene whose assets aren't
+   already in memory, or follow up with `engine.block.forceLoadAVResource`
+   (or `forceLoadResources`) on each video-fill block before calling
+   `exportVideo`:
+
+   ```js
+   const scene = await engine.scene.loadFromArchiveURL(file_url, {
+     waitForResources: true,
+   });
+   const [page] = engine.block.findByType('page');
+   const mp4 = await engine.block.exportVideo(page, 'video/mp4', onProgress, {
+     duration: engine.block.getTotalSceneDuration(scene),
+     framerate: 30,
+   });
+   ```
+
+The wrapper pumps `update()` internally during `init()`, so unlike
+`@cesdk/node` (WASM), **you do not need to drive a `setInterval` pump
+loop around `exportVideo`**. The export `await`s naturally. Only call
+`engine.update()` directly if you're driving frame-perfect work outside
+of the built-in export path.
+
+A runnable end-to-end example is in `examples/video-export-3s.js` of the
+source repository.
+
+## Cross-platform lockfiles (CI pitfalls)
+
+`@cesdk/node-native` ships a different `.node` per platform via npm's
+`optionalDependencies` (the same pattern as `esbuild`, `sharp`, etc.). One
+rough edge to call out:
+
+> `npm ci` on CI using a lockfile generated on a different architecture
+> succeeds at install but fails with `ERR_DLOPEN_FAILED` at runtime.
+
+Recommended mitigations (pick one):
+
+1. **`npm install --include=optional @cesdk/node-native` on CI.** Re-resolves
+   optional dependencies for the actual host. Slightly slower than `npm ci`,
+   robust.
+2. **Generate the lockfile on the same OS/arch as CI** (a `node:22` Docker
+   image for Linux consumers).
+3. **Per-platform lockfiles.** Over-engineering for most projects.
+
+Docker images that bake `@cesdk/node-native` into a final artifact should
+always install inside the target image, never copy `node_modules/` from a
+different-arch host.
+
+## Advanced: override the binary path
+
+For air-gapped builds or custom distributions, set
+`CESDK_NATIVE_BINARY_PATH` to an absolute path to the `.node` binary. The
+loader uses it directly, bypassing `require.resolve`:
+
+```bash
+CESDK_NATIVE_BINARY_PATH=/opt/cesdk/cesdk_native.node node app.js
+```
+
+Set `DEBUG=cesdk:native` (or `CESDK_DEBUG=1`) to log loader resolution steps
+when triaging install issues.
+
+### Skipping the integrity check (cold-start-sensitive deploys)
+
+On first `init()` the loader streams a SHA-256 over the ~32 MB `.node` and
+compares it to a checksum sidecar — a corruption/truncation guard (it is **not**
+anti-substitution; that's npm provenance). This adds a few tens of milliseconds
+to each cold start. For latency-sensitive serverless cold paths (e.g. AWS Lambda)
+where the artifact is already integrity-checked by the platform, you can skip it:
+
+```bash
+CESDK_SKIP_BINARY_VERIFY=1 node app.js
+```
+
+Leave verification on by default; only opt out when cold-start latency matters
+and the binary's integrity is guaranteed by other means.
+
+## Known limitations
+
+- **IMG.LY banner and engine diagnostics on stderr.** The native engine
+  prints a one-time license banner and occasional engine logs (e.g.
+  `EventSubscriptionService::initEventCallbacks errorStateChanged`) to
+  stderr. Capture or redirect stderr (`node app.js 2>/dev/null`,
+  `child_process.spawn(..., { stdio: ['inherit', 'inherit', 'ignore'] })`)
+  if it interferes with machine-readable output. A `setLogLevel` API is
+  tracked for a future release.
+- **macOS binaries are not code-signed.** Plain `node` doesn't enforce
+  signatures on `dlopen`, so the addon loads out of the box for normal
+  Node.js usage. Electron apps that notarize the containing app must sign
+  the nested `cesdk_native.node` with their own Developer ID in their
+  `afterSign` hook before notarization. Hosts that enforce strict library
+  validation (some Electron variants, hardened runtime CI runners) will
+  reject the unsigned binary; full Developer ID + notarization on our side
+  is tracked as a follow-up.
+- **Per-block error inspection.** The engine emits a `errorStateChanged`
+  log line when a block transitions to an error state (e.g. a video-fill
+  resource fails to load). Read the per-block state via
+  `engine.block.getState(blockId)` after `update()` to inspect the failure;
+  a top-level error subscriber is tracked as a follow-up.
+
+## Troubleshooting
+
+### `Failed to load the @cesdk/node-native addon for ...`
+
+Most commonly, npm skipped `optionalDependencies` during install. Reinstall:
+
+```bash
+npm install --include=optional @cesdk/node-native
+```
+
+For pnpm and Yarn, regenerate the lockfile on the target platform/arch
+(easiest via a Docker build), or use per-platform lockfiles. Neither
+package manager has a direct equivalent of npm's `--include=optional`.
+
+### Linux: `version 'GLIBC_2.XX' not found`
+
+This build targets glibc ≥ 2.39 — see "Supported platforms". Stay on
+`@cesdk/node` (WASM) for older systems until a manylinux build lands.
+
+### macOS: `library load disallowed by system policy`
+
+The published binary is not code-signed. `npm install` doesn't add the
+`com.apple.quarantine` xattr so this error doesn't show up there, but if
+you obtained the package via a browser download or a sideloaded zip, the
+quarantine flag will block `dlopen`. Strip it with:
+
+```bash
+xattr -d com.apple.quarantine node_modules/@cesdk/node-native-*/cesdk_native.node
+```
+
+## License
+
+The CreativeEditor SDK is a commercial product. Purchase a license at
+<https://img.ly/pricing>.