@lumikmz/kmz-file 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zhaoyang Yuan
+
+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/README.md

@@ -0,0 +1,258 @@
+# @lumikmz/kmz-file
+
+Read and write DJI `.kmz` mission files in JavaScript. Wraps a Rust + WebAssembly core that handles ZIP packaging and XML serialization, surfacing only the typed `Template` / `Waylines` / resources shapes defined in [`@lumikmz/kmz`](../kmz/README.md).
+
+```sh
+npm install @lumikmz/kmz @lumikmz/kmz-file
+```
+
+## Table of contents
+
+- [What this package does](#what-this-package-does)
+- [Public API](#public-api)
+  - [`init(input?)`](#initinput--promiseinitoutput)
+  - [`initSync(input)`](#initsyncinput--initoutput)
+  - [`pack(template, waylines, resources?)`](#packtemplate-waylines-resources--uint8array)
+  - [`unpack(bytes)`](#unpackbytes--unpackresult)
+  - [Types](#types)
+- [Resource files](#resource-files)
+- [Bundler integration](#bundler-integration)
+- [Round-trip guarantees](#round-trip-guarantees)
+- [How it works](#how-it-works)
+
+## What this package does
+
+KMZ is a ZIP archive containing `wpmz/template.kml` (XML), `wpmz/waylines.wpml` (XML), and optional resource files (`res/audio/*.opus`, etc.). This package handles the full conversion:
+
+```
+.kmz bytes  ⇄  { template: Template, waylines: Waylines, resources: ResourceFile[] }
+```
+
+The Rust core (compiled to WASM) does ZIP + XML I/O. A TypeScript codec layer encodes/decodes between the on-wire XML JSON shape and the spec-aligned typed shape from `@lumikmz/kmz`. Consumers only see the typed shape.
+
+## Public API
+
+### `init(input?) → Promise<InitOutput>`
+
+Lazily initialize the WASM module. Idempotent — subsequent calls return the same in-flight promise. Must complete before calling `pack` / `unpack`.
+
+```ts
+import { init } from "@lumikmz/kmz-file";
+
+await init();              // default: fetches the wasm binary alongside the JS bundle
+```
+
+You can override the loader by passing an `InitInput` (URL, `Response`, `BufferSource`, or `WebAssembly.Module`), useful when your bundler needs explicit asset wiring:
+
+```ts
+import { init } from "@lumikmz/kmz-file";
+// Bundler-friendly explicit URL:
+import wasmUrl from "@lumikmz/kmz-file/wasm?url";
+
+await init(wasmUrl);
+```
+
+### `initSync(input) → InitOutput`
+
+Synchronous variant for when you already have the WASM bytes or a compiled `WebAssembly.Module`. Same idempotency rules don't apply — call this exactly once.
+
+```ts
+import { initSync } from "@lumikmz/kmz-file";
+
+const bytes = await (await fetch("/wasm_kmz_bg.wasm")).arrayBuffer();
+initSync({ module: bytes });
+```
+
+### `pack(template, waylines, resources?) → Uint8Array`
+
+Encode a `Template` + `Waylines` (plus optional resource files) into a `.kmz` byte stream. Pure synchronous after `init()`.
+
+```ts
+import { plan } from "@lumikmz/kmz";
+import { init, pack, type ResourceFile } from "@lumikmz/kmz-file";
+
+await init();
+
+const waylines = plan(template);
+const bytes: Uint8Array = pack(template, waylines);
+
+// With resources (e.g. a megaphone audio file referenced by an action):
+const resources: ResourceFile[] = [
+  { path: "wpmz/res/audio/announcement.opus", data: audioBytes },
+];
+const bytes2 = pack(template, waylines, resources);
+```
+
+**Signature:**
+
+```ts
+function pack(
+  template: Template,
+  waylines: Waylines,
+  resources?: ResourceFile[],
+): Uint8Array;
+
+interface ResourceFile {
+  path: string;        // path inside the KMZ archive, e.g. "wpmz/res/audio/<hash>.opus"
+  data: Uint8Array;
+}
+```
+
+### `unpack(bytes) → UnpackResult`
+
+Decode a `.kmz` byte stream into the typed shape. Pure synchronous after `init()`.
+
+```ts
+import { unpack } from "@lumikmz/kmz-file";
+
+const bytes = new Uint8Array(await file.arrayBuffer());
+const { template, waylines, resources } = unpack(bytes);
+//        ^Template   ^Waylines  ^ResourceFile[]
+```
+
+**Signature:**
+
+```ts
+function unpack(bytes: Uint8Array): UnpackResult;
+
+interface UnpackResult {
+  template: Template;
+  waylines: Waylines;
+  resources: ResourceFile[];
+}
+```
+
+### Types
+
+All types are re-exported alongside the functions. The main shapes — `Template`, `Waylines`, `MissionConfig`, `ActionGroup`, etc. — come from [`@lumikmz/kmz`](../kmz/README.md). This package adds:
+
+```ts
+interface ResourceFile {
+  path: string;
+  data: Uint8Array;
+}
+
+interface UnpackResult {
+  template: Template;
+  waylines: Waylines;
+  resources: ResourceFile[];
+}
+
+// WASM init types (passed through from wasm-bindgen):
+type InitInput     = RequestInfo | URL | Response | BufferSource | WebAssembly.Module;
+type SyncInitInput = BufferSource | WebAssembly.Module;
+interface InitOutput { /* the raw wasm-bindgen exports */ }
+```
+
+## Resource files
+
+`resources` is the array of non-XML files inside the KMZ archive. DJI uses these for:
+
+- **`/wpmz/res/audio/*.opus`** — Megaphone audio clips referenced by `megaphone` actions via `actionActuatorFuncParam.megaphoneOperateFilePath`
+- Anything else DJI ships inside the archive (currently rare)
+
+`path` is the in-archive path verbatim — usually rooted at `wpmz/`. When packing, pass exactly the paths your actions reference; when unpacking, you get every non-XML file the archive contained.
+
+## Bundler integration
+
+The package ships:
+
+```
+dist/index.mjs        # bundled JS, ESM
+dist/index.d.mts      # type declarations
+dist/wasm_kmz.js      # wasm-bindgen glue (loaded at runtime)
+dist/wasm_kmz.d.ts
+dist/wasm_kmz_bg.wasm # the WASM binary (~250 KB, ~127 KB gzipped)
+```
+
+`dist/index.mjs` imports `./wasm_kmz.js` at runtime, which in turn `fetch()`-loads `./wasm_kmz_bg.wasm` from the same directory. Modern bundlers (Vite, Webpack 5, Rollup with `@web/rollup-plugin-import-meta-assets`, etc.) resolve this automatically and emit the `.wasm` as a hashed asset.
+
+If your bundler doesn't handle wasm-bindgen's loader out of the box, pass an explicit URL to `init()`:
+
+```ts
+import { init } from "@lumikmz/kmz-file";
+
+await init(new URL("@lumikmz/kmz-file/wasm", import.meta.url));
+```
+
+The `./wasm` export in `package.json` maps to `dist/wasm_kmz_bg.wasm`.
+
+## Round-trip guarantees
+
+`pack` then `unpack` is shape-preserving for all spec-compliant fields:
+
+- All `wpml:` field names are mapped between camelCase (typed) and the XML-namespaced form.
+- Booleans round-trip via `"0"` / `"1"` strings.
+- Numbers, branded numbers, and unit strings round-trip via `toString()` / `parseFloat`.
+- `LngLat` ↔ KML `"lng,lat"` strings (longitude first).
+- `LngLatHeight` (for `takeOffRefPoint` / `waypointPoiPoint`) ↔ DJI `"lat,lng,height"` strings (**latitude first** — opposite order from KML, easy to swap by accident; the codec handles this).
+- Polygon `LinearRing.coordinates` and `LineString.coordinates` are passed through as the space-separated `"lng,lat,alt"` triples DJI expects.
+- Single-vs-array elements are normalized: a single `<Folder>` deserializes as one object, not a one-element array, and serializes back without becoming an array.
+- Spec misspellings (`visable`, `followBadArc`) are preserved verbatim — both directions.
+- Action-specific params live inside `actionActuatorFuncParam` and are demultiplexed by `actionActuatorFunc`.
+
+If a field is absent in the source it's absent in the output. The codec never invents defaults.
+
+## How it works
+
+```
+       ┌───────────────────────────────────────────────────┐
+       │                  @lumikmz/kmz-file                │
+       │                                                   │
+       │   ┌──────────────┐    ┌────────────────────────┐  │
+unpack │   │  TS codec    │ ←  │  Rust (WASM)           │  │ ← .kmz bytes
+       │   │  decode-*.ts │    │  - ZIP unpack          │  │
+       │   └──────┬───────┘    │  - XML → JSON (serde)  │  │
+       │          │            └────────────────────────┘  │
+       │          ↓                                        │
+       │     { Template, Waylines, resources }             │
+       │          ↑                                        │
+       │          │            ┌────────────────────────┐  │
+pack   │   ┌──────┴───────┐    │  Rust (WASM)           │  │ → .kmz bytes
+       │   │  TS codec    │ →  │  - JSON → XML          │  │
+       │   │  encode-*.ts │    │  - ZIP pack            │  │
+       │   └──────────────┘    └────────────────────────┘  │
+       └───────────────────────────────────────────────────┘
+```
+
+The Rust layer is intentionally dumb: it just shuffles bytes between ZIP entries and the `serde_json::Value` representation of the XML tree. All spec knowledge lives in TypeScript, where it can be evolved alongside the type definitions.
+
+### Source layout
+
+```
+packages/kmz-file/
+├── rust/                  # Rust crate compiled to WASM via wasm-bindgen
+│   ├── src/lib.rs         # wasm_bindgen entry points: kmzToJson, jsonToKmz, xmlToJson, jsonToXml
+│   ├── src/kmz/           # ZIP read/write
+│   └── src/xml/           # XML ↔ serde_json::Value
+├── src/                   # TypeScript layer
+│   ├── codec/             # XML JSON ↔ typed JSON (internal, not exported)
+│   │   ├── encode-*.ts
+│   │   ├── decode-*.ts
+│   │   └── xml-schema.ts
+│   ├── pack.ts            # public
+│   ├── unpack.ts          # public
+│   ├── init.ts            # public
+│   └── index.ts           # entry point
+├── scripts/build.js       # cargo build + wasm-bindgen + wasm-opt + vp pack
+└── dist/                  # publishable artifacts
+```
+
+### Build
+
+Rebuilding requires the Rust toolchain (only when the WASM core changes):
+
+```sh
+cd packages/kmz-file
+pnpm build                 # invokes scripts/build.js
+```
+
+Editing only the TypeScript codec (the common case) needs nothing beyond `vp pack`.
+
+## Compatibility
+
+[DJI WPML 1.0.2](https://developer.dji.com/doc/cloud-api-tutorial/en/feature-set/dji-wpml/template-kml.html). The XML namespaces and structure are pinned in [`src/codec/xml-schema.ts`](src/codec/xml-schema.ts).
+
+## License
+
+[MIT](../../LICENSE)

package/dist/index.d.mts

@@ -0,0 +1,48 @@
+import { InitInput, InitOutput, SyncInitInput } from "./wasm_kmz.js";
+import { Template, Waylines } from "@lumikmz/kmz";
+
+//#region src/init.d.ts
+/**
+ * Initialize the underlying WASM module. Idempotent — repeated calls return the
+ * original promise. Pass `input` to control how the module is loaded (e.g. a
+ * URL, fetch Response, or pre-fetched bytes). With no arguments,
+ * wasm-bindgen uses its default loader.
+ */
+declare function init(input?: InitInput | Promise<InitInput>): Promise<InitOutput>;
+/** Synchronous WASM init. Accepts pre-fetched bytes or a compiled module. */
+declare function initSync(input: {
+  module: SyncInitInput;
+} | SyncInitInput): InitOutput;
+//#endregion
+//#region src/pack.d.ts
+interface ResourceFile {
+  path: string;
+  data: Uint8Array;
+}
+/**
+ * Encode a Template + Waylines pair (plus optional resources) into a KMZ byte
+ * stream. `init()` must have completed before calling this.
+ */
+declare function pack(template: Template, waylines: Waylines, resources?: ResourceFile[]): Uint8Array;
+//#endregion
+//#region src/unpack.d.ts
+interface UnpackResult {
+  template: Template;
+  waylines: Waylines;
+  resources: ResourceFile[];
+}
+/**
+ * Decode a KMZ byte stream into typed Template + Waylines. `init()` must have
+ * completed before calling this.
+ */
+declare function unpack(bytes: Uint8Array): UnpackResult;
+//#endregion
+//#region src/index.d.ts
+declare const _default: {
+  pack: typeof pack;
+  unpack: typeof unpack;
+  init: typeof init;
+  initSync: typeof initSync;
+};
+//#endregion
+export { type InitInput, type InitOutput, type ResourceFile, type SyncInitInput, type UnpackResult, _default as default, init, initSync, pack, unpack };