@richardmcquiston01/unofficial-xcs-writer 0.7.0 → 0.8.1

package/API.md

@@ -0,0 +1,86 @@
+# API Reference
+
+## `assertXcsFormat(buffer: ArrayBuffer): void`
+
+Validates that `buffer` is a parseable XCS JSON file containing a `canvas` array. Throws a descriptive error if the file is invalid or unrecognized.
+
+## `readXcsFile(buffer: ArrayBuffer): string`
+
+Decodes the buffer and returns the raw JSON string. Useful for inspection or pass-through scenarios.
+
+## `extractXcsTokens(buffer: ArrayBuffer): string[]`
+
+Scans all `TEXT` display objects across all canvases and returns the unique token names found (without braces). For example, `{{LastName}}` in the file → `"LastName"` in the returned array.
+
+## `renderXcsFile(buffer, variables, values, fonts?): Uint8Array`
+
+Applies substitution to every `TEXT` display object and returns the modified file encoded as a UTF-8 `Uint8Array`. Tokens with no matching entry in `values` fall back to `variable.defaultValue`, or an empty string if no default is set.
+
+Whenever a display's text actually changes, its glyph outline data (`charJSONs` / `fontData.glyphData`) is regenerated from a real font so xTool Studio renders the new text correctly — xTool Studio only trusts a TEXT display's stored glyph shapes; it does not re-shape text on its own unless you manually reselect the font inside the app. Displays whose text doesn't change are left completely untouched.
+
+Pass `fonts` to supply real font file bytes (TTF/OTF/WOFF) keyed by a display's `style.fontFamily`:
+
+```ts
+const arialBuffer = await fetch('/fonts/arial.ttf').then(r => r.arrayBuffer());
+renderXcsFile(buffer, variables, values, { Arial: arialBuffer });
+```
+
+Any `fontFamily` not present in `fonts` falls back to a bundled default (Arimo, Apache-2.0, metric-compatible with Arial) — so the fix works out of the box with no font files required, just with shapes drawn from Arimo rather than the exact requested typeface.
+
+**Known limitation:** `renderXcsFile` only reproduces straight horizontal-baseline layout when substituting into an *existing* TEXT display. xTool Studio's `style.curveX`/`curveY` curved-text formula is undocumented and can't be reverse-decoded from a file alone, so a curved display's substituted text gets correctly-shaped glyphs laid out straight instead of on the original curve. This doesn't apply to the *building* API below — there, you supply the curve angle yourself (see `layoutCurvedGlyphText`), so there's nothing to decode.
+
+## `XcsVariable`
+
+```ts
+interface XcsVariable {
+  token: string;        // token name without braces, e.g. "LastName"
+  defaultValue?: string;
+}
+```
+
+## `.xs` (v2 workspace) format
+
+## `assertXsFormat(buffer: ArrayBuffer): void`
+
+Validates that `buffer` is a ZIP archive with a `.format` entry equal to `"v2"` and a `project.json` entry. Throws a descriptive error otherwise.
+
+## `extractXsTokens(buffer: ArrayBuffer): string[]`
+
+Same as `extractXcsTokens`, but scans every `canvases/<canvasId>/displays-<chunkIndex>.json` chunk across the archive instead of a single `canvas` array.
+
+## `renderXsFile(buffer, variables, values, fonts?): Uint8Array`
+
+Same substitution and glyph-regeneration behavior as `renderXcsFile` (see above — including the same `fonts` parameter and curved-text limitation), applied to every displays chunk. Returns a re-zipped `.xs` archive; every entry other than the modified displays chunks is passed through byte-for-byte unchanged.
+
+## `buildXsArchive(file: XCSFile): Uint8Array`
+
+Packages an already-`generate()`d project (see Building, below) into a `.xs` v2 ZIP archive. You won't normally call this directly — use `XCSGenerator.toXsBytes()` instead, which calls it for you.
+
+## `loadFont(buffer: ArrayBuffer)` / `loadDefaultFont()` / `layoutText(font, text, originX, originY)`
+
+Lower-level glyph-extraction primitives everything else in this library is built on, exported for direct use. See `src/glyphs.ts` for the exact xTool JSON conventions these were reverse-engineered against.
+
+## Building (`src/builder.ts`, `src/layout.ts`, `src/machines.ts`)
+
+`createXCS(deviceId?)` / `new XCSGenerator(options?)` — starts a new project (one canvas, one default layer). `deviceId` (and `options.deviceId`) accepts a `XTOOL_MACHINES` key, a `MachineProfile` object, or a raw device id string — see "Building a project from scratch" in the [README](./README.md). Chainable methods:
+
+| Method | Adds |
+|--------|------|
+| `.addText(text, x, y, options?)` | A `TEXT` display. Pass `options.layout` (see below) for real glyph outlines — without it, text renders as placeholder blocks in xTool Studio. |
+| `.addPath(pathData, x, y, width, height, options?)` | A `PATH` display from SVG path data. |
+| `.addBitmap(pngBase64, x, y, widthMm, heightMm, originWidthPx, originHeightPx, options?)` | An embedded PNG, physically sized in mm. |
+| `.addLayer(color, name, order)` | A named, colored layer (one `#00befe` "Cyan" layer exists by default). |
+
+`.addText()`/`.addPath()`/`.addBitmap()` all also accept a `processing: { processingType, values }` option — see "Building a project from scratch" in the [README](./README.md); it only affects `.toXsBytes()` output.
+
+Then `.generate()` (the plain `XCSFile` object), `.toJSON()` (string), `.toBytes()` (`Uint8Array`, matching `renderXcsFile`'s output type, as `.xcs`), or `.toXsBytes()` (`Uint8Array`, matching `renderXsFile`'s output type, as `.xs`).
+
+Text layout — build the `layout` option for `.addText()` with one of:
+
+| Function | Layout |
+|----------|--------|
+| `layoutGlyphText(font, text, emSizeMm, xMm, yMm, letterSpacingMm?)` | Single-line, straight, anchored so the ink box's top-left lands at `(xMm, yMm)`. |
+| `layoutMultilineGlyphText(font, text, emSizeMm, letterSpacingMm, lineHeightMult, align)` | Multi-line (`\n`-separated), straight, each line aligned and vertically stacked. |
+| `layoutCurvedGlyphText(font, text, emSizeMm, curveDeg, boxWidthMm, boxHeightMm, align?, letterSpacingMm?)` | Single-line, curved along an arc spanning `curveDeg` degrees across a `boxWidthMm`-wide box (positive arches the apex upward, negative bows it downward — same convention as SVG `<textPath>`/canvas curved-text editors). Multi-line curved text isn't supported (matches typical curved-text editors, which also flatten multi-line curved text to one line). **Not yet visually verified against real xTool Studio rendering** (there's no way to check outside the application itself) — the geometry is self-consistent and unit-tested, but treat curved output as best-effort until you've spot-checked it. |
+
+All three return `GlyphTextLayout | null` (`null` for empty/whitespace-only text). `translateGlyphLayout(layout, dxMm, dyMm)` cheaply shifts an already-built layout without relaying out the font.

package/CHANGELOG.md

@@ -5,6 +5,43 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+## [0.8.1] - 2026-09-21
+
+### Changed
+
+- **README restructure**: removed the "Releasing" subsection (internal maintainer process,
+  not user-facing); moved the full "API" section into a new `API.md` (added to `package.json`'s
+  `files` so it ships with the npm package), with the README's "API" section now just a link to
+  it; added a disclaimer blockquote under the title stating this is an unofficial,
+  community-built library not affiliated with xTool; removed the hyperlink on "xTool Creative
+  Space" in the intro paragraph (kept as plain text); moved "Buy Me a Coffee" up to sit directly
+  above the API section instead of at the very end.
+- **Copyright section**: added a note that xTool, xTool Studio, and xTool Creative Space are
+  registered trademarks of Makeblock Co., Ltd., and that this project isn't affiliated with,
+  endorsed by, or sponsored by Makeblock or xTool.
+
+## [0.8.0] - 2026-09-21
+
+### Added
+
+- **Machine catalog** (`src/machines.ts`): `XCSGeneratorOptions.deviceId`/`createXCS`'s argument
+  now accepts a `XTOOL_MACHINES` key -- currently 13 machines verified from real exports in this
+  repo (`P2S`, `F2 Ultra UV`, `S1`, `P3`, `M2`, `F2`, `F2 Ultra (Single)`, `F2 Ultra`, `M1 Ultra`,
+  `F1`, `F1 Lite`, `F1 Ultra`, `MetalFab`) -- and resolves that machine's real `extId`/`extName`/
+  `deviceCode` (`.xs` only)/default power, instead of reusing whatever string you pass for all of
+  them. A `MachineProfile` object can also be supplied directly for a machine not yet in the
+  catalog. Existing raw device id strings still behave exactly as before (unaffected, since they
+  simply don't match a catalog key).
+
+### Changed
+
+- `createXCS()`/`new XCSGenerator()` with no `deviceId` (defaulting to `"P2S"`) now embeds the
+  real `deviceCode: "ZY013"` in `.toXsBytes()` output, instead of the previous placeholder
+  (`file.device.id`, i.e. `"P2S"`). `.xcs` output (`.toBytes()`) is unaffected -- it has no
+  `deviceCode` field.
+
 ## [0.7.0] - 2026-09-21
 
 ### Added

package/README.md

@@ -1,6 +1,8 @@
 # unofficial-xcs-writer
 
-A framework-agnostic TypeScript library for reading, writing, building, and applying variable substitution to `.xcs` and `.xs` files produced by [xTool Creative Space](https://www.xtool.com/pages/software). Not affiliated with xTool.
+> **Disclaimer:** This is an unofficial, community-built library. It is not affiliated with, endorsed by, or sponsored by xTool in any way.
+
+A framework-agnostic TypeScript library for reading, writing, building, and applying variable substitution to `.xcs` and `.xs` files produced by xTool Creative Space.
 
 ## What is an XCS / XS file?
 
@@ -113,92 +115,38 @@ and undocumented beyond real exports — see `xs_samples/*.xs`'s `profiles.json`
 option behave as before: a generated `.xs` file's power/speed may need to be set manually in
 xTool Studio before cutting/engraving.
 
-## API
-
-### `assertXcsFormat(buffer: ArrayBuffer): void`
-
-Validates that `buffer` is a parseable XCS JSON file containing a `canvas` array. Throws a descriptive error if the file is invalid or unrecognized.
-
-### `readXcsFile(buffer: ArrayBuffer): string`
-
-Decodes the buffer and returns the raw JSON string. Useful for inspection or pass-through scenarios.
-
-### `extractXcsTokens(buffer: ArrayBuffer): string[]`
-
-Scans all `TEXT` display objects across all canvases and returns the unique token names found (without braces). For example, `{{LastName}}` in the file → `"LastName"` in the returned array.
-
-### `renderXcsFile(buffer, variables, values, fonts?): Uint8Array`
-
-Applies substitution to every `TEXT` display object and returns the modified file encoded as a UTF-8 `Uint8Array`. Tokens with no matching entry in `values` fall back to `variable.defaultValue`, or an empty string if no default is set.
-
-Whenever a display's text actually changes, its glyph outline data (`charJSONs` / `fontData.glyphData`) is regenerated from a real font so xTool Studio renders the new text correctly — xTool Studio only trusts a TEXT display's stored glyph shapes; it does not re-shape text on its own unless you manually reselect the font inside the app. Displays whose text doesn't change are left completely untouched.
-
-Pass `fonts` to supply real font file bytes (TTF/OTF/WOFF) keyed by a display's `style.fontFamily`:
+`createXCS('P2S')`'s argument (and `XCSGeneratorOptions.deviceId`) accepts a known machine name
+from `XTOOL_MACHINES` — currently 13 machines verified from real exports in this repo (`"P2S"`,
+`"F2 Ultra UV"`, `"S1"`, `"P3"`, `"M2"`, `"F2"`, `"F2 Ultra (Single)"`, `"F2 Ultra"`,
+`"M1 Ultra"`, `"F1"`, `"F1 Lite"`, `"F1 Ultra"`, `"MetalFab"`) — and resolves the real
+`extId`/`extName`/`deviceCode` (`.xs` only)/default power for that machine, instead of reusing
+whatever string you pass for all of them. Export the same design for multiple machines by
+building it once and calling `.toXsBytes()`/`.toBytes()` once per `createXCS(machineName)`:
 
 ```ts
-const arialBuffer = await fetch('/fonts/arial.ttf').then(r => r.arrayBuffer());
-renderXcsFile(buffer, variables, values, { Arial: arialBuffer });
-```
-
-Any `fontFamily` not present in `fonts` falls back to a bundled default (Arimo, Apache-2.0, metric-compatible with Arial) — so the fix works out of the box with no font files required, just with shapes drawn from Arimo rather than the exact requested typeface.
-
-**Known limitation:** `renderXcsFile` only reproduces straight horizontal-baseline layout when substituting into an *existing* TEXT display. xTool Studio's `style.curveX`/`curveY` curved-text formula is undocumented and can't be reverse-decoded from a file alone, so a curved display's substituted text gets correctly-shaped glyphs laid out straight instead of on the original curve. This doesn't apply to the *building* API below — there, you supply the curve angle yourself (see `layoutCurvedGlyphText`), so there's nothing to decode.
-
-### `XcsVariable`
+import { createXCS, XTOOL_MACHINES } from '@richardmcquiston01/unofficial-xcs-writer';
 
-```ts
-interface XcsVariable {
-  token: string;        // token name without braces, e.g. "LastName"
-  defaultValue?: string;
+for (const machine of Object.keys(XTOOL_MACHINES)) {
+  const bytes = createXCS(machine).addPath('M0 0L10 0L10 10L0 10Z', 0, 0, 10, 10).toXsBytes();
+  // write `bytes` to e.g. `design-${machine}.xs`
 }
 ```
 
-### `.xs` (v2 workspace) format
-
-### `assertXsFormat(buffer: ArrayBuffer): void`
-
-Validates that `buffer` is a ZIP archive with a `.format` entry equal to `"v2"` and a `project.json` entry. Throws a descriptive error otherwise.
-
-### `extractXsTokens(buffer: ArrayBuffer): string[]`
-
-Same as `extractXcsTokens`, but scans every `canvases/<canvasId>/displays-<chunkIndex>.json` chunk across the archive instead of a single `canvas` array.
+A device id not in the catalog still works exactly as before (no `.xs` `deviceCode`, `extId`/
+`extName`/`device.id` all set to that string, default power `55`); you can also pass a
+`MachineProfile` object directly for a machine not yet in the catalog.
 
-### `renderXsFile(buffer, variables, values, fonts?): Uint8Array`
-
-Same substitution and glyph-regeneration behavior as `renderXcsFile` (see above — including the same `fonts` parameter and curved-text limitation), applied to every displays chunk. Returns a re-zipped `.xs` archive; every entry other than the modified displays chunks is passed through byte-for-byte unchanged.
-
-### `buildXsArchive(file: XCSFile): Uint8Array`
-
-Packages an already-`generate()`d project (see Building, below) into a `.xs` v2 ZIP archive. You won't normally call this directly — use `XCSGenerator.toXsBytes()` instead, which calls it for you.
-
-### `loadFont(buffer: ArrayBuffer)` / `loadDefaultFont()` / `layoutText(font, text, originX, originY)`
-
-Lower-level glyph-extraction primitives everything else in this library is built on, exported for direct use. See `src/glyphs.ts` for the exact xTool JSON conventions these were reverse-engineered against.
-
-### Building (`src/builder.ts`, `src/layout.ts`)
-
-`createXCS(deviceId?)` / `new XCSGenerator(options?)` — starts a new project (one canvas, one default layer). Chainable methods:
-
-| Method | Adds |
-|--------|------|
-| `.addText(text, x, y, options?)` | A `TEXT` display. Pass `options.layout` (see below) for real glyph outlines — without it, text renders as placeholder blocks in xTool Studio. |
-| `.addPath(pathData, x, y, width, height, options?)` | A `PATH` display from SVG path data. |
-| `.addBitmap(pngBase64, x, y, widthMm, heightMm, originWidthPx, originHeightPx, options?)` | An embedded PNG, physically sized in mm. |
-| `.addLayer(color, name, order)` | A named, colored layer (one `#00befe` "Cyan" layer exists by default). |
+## Buy Me a Coffee
 
-`.addText()`/`.addPath()`/`.addBitmap()` all also accept a `processing: { processingType, values }` option — see "Building a project from scratch" above; it only affects `.toXsBytes()` output.
+If this app, code, or repository has helped you or someone you know, please consider donating. I appreciate any help to offset the costs of development and/or AI Credits.
 
-Then `.generate()` (the plain `XCSFile` object), `.toJSON()` (string), `.toBytes()` (`Uint8Array`, matching `renderXcsFile`'s output type, as `.xcs`), or `.toXsBytes()` (`Uint8Array`, matching `renderXsFile`'s output type, as `.xs`).
+[**Donate via Stripe**](https://donate.stripe.com/00w5kD3Gj1Xo9v7gVOcs800), or scan:
 
-Text layout — build the `layout` option for `.addText()` with one of:
+[![Donate via Stripe](./donate.svg)](https://donate.stripe.com/00w5kD3Gj1Xo9v7gVOcs800)
 
-| Function | Layout |
-|----------|--------|
-| `layoutGlyphText(font, text, emSizeMm, xMm, yMm, letterSpacingMm?)` | Single-line, straight, anchored so the ink box's top-left lands at `(xMm, yMm)`. |
-| `layoutMultilineGlyphText(font, text, emSizeMm, letterSpacingMm, lineHeightMult, align)` | Multi-line (`\n`-separated), straight, each line aligned and vertically stacked. |
-| `layoutCurvedGlyphText(font, text, emSizeMm, curveDeg, boxWidthMm, boxHeightMm, align?, letterSpacingMm?)` | Single-line, curved along an arc spanning `curveDeg` degrees across a `boxWidthMm`-wide box (positive arches the apex upward, negative bows it downward — same convention as SVG `<textPath>`/canvas curved-text editors). Multi-line curved text isn't supported (matches typical curved-text editors, which also flatten multi-line curved text to one line). **Not yet visually verified against real xTool Studio rendering** (there's no way to check outside the application itself) — the geometry is self-consistent and unit-tested, but treat curved output as best-effort until you've spot-checked it. |
+## API
 
-All three return `GlyphTextLayout | null` (`null` for empty/whitespace-only text). `translateGlyphLayout(layout, dxMm, dyMm)` cheaply shifts an already-built layout without relaying out the font.
+See [API.md](./API.md) for the full API reference — function signatures, options, types, and important behavior notes (glyph regeneration, curved-text limitations, machine catalog usage, etc.).
 
 ## Development
 
@@ -218,14 +166,6 @@ Output files after `pnpm build`:
 | `dist/index.cjs` | CommonJS |
 | `dist/index.d.ts` | TypeScript declarations |
 
-### Releasing
-
-Publishing to npm is automated. Bump the version in `package.json`, add a
-`CHANGELOG.md` entry, then create a GitHub release tagged `vX.Y.Z` — the
-[publish workflow](.github/workflows/publish.yml) checks the tag against
-`package.json`, rebuilds, runs the tests, and publishes with provenance.
-It needs an `NPM_TOKEN` repository secret with publish rights.
-
 ## Notes
 
 - All inputs and outputs use plain browser-compatible types (`ArrayBuffer`, `Uint8Array`, `string`) — no Node.js APIs, no DOM, no framework required. (`atob`/`crypto.randomUUID` are used for the bundled font and glyph IDs; both are available in browsers and Node ≥ 19.)
@@ -238,10 +178,8 @@ It needs an `NPM_TOKEN` repository secret with publish rights.
 
 [MIT](LICENSE). The bundled Arimo fallback font is separately licensed under Apache-2.0 (`third_party/arimo/LICENSE`).
 
-## Buy Me a Coffee
+## Copyright
 
-If this app, code, or repository has helped you or someone you know, please consider donating. I appreciate any help to offset the costs of development and/or AI Credits.
+(c)2026 Richard McQuiston
 
-[**Donate via Stripe**](https://donate.stripe.com/00w5kD3Gj1Xo9v7gVOcs800), or scan:
-
-[![Donate via Stripe](./donate.svg)](https://donate.stripe.com/00w5kD3Gj1Xo9v7gVOcs800)
+xTool, xTool Studio, and xTool Creative Space are registered trademarks of Makeblock Co., Ltd. This project is not affiliated with, endorsed by, or sponsored by Makeblock Co., Ltd. or xTool.

package/dist/index.cjs

@@ -31,6 +31,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   XCSGenerator: () => XCSGenerator,
+  XTOOL_MACHINES: () => XTOOL_MACHINES,
   assertXcsFormat: () => assertXcsFormat,
   assertXsFormat: () => assertXsFormat,
   buildXsArchive: () => buildXsArchive,
@@ -416,7 +417,7 @@ function coverResourceEntries(coverDataUrl) {
     })
   };
 }
-function buildXsArchive(file, processingBindings = []) {
+function buildXsArchive(file, processingBindings = [], deviceCode = file.device.id) {
   const canvas = file.canvas[0];
   if (!canvas) {
     throw new Error("Cannot build a .xs archive from a project with no canvas.");
@@ -478,7 +479,7 @@ function buildXsArchive(file, processingBindings = []) {
     }),
     [`devices/device-${file.device.id}.json`]: encodeJson({
       id: file.device.id,
-      deviceCode: file.device.id,
+      deviceCode,
       extId: file.extId,
       extName: file.extName,
       power: [file.device.power],
@@ -766,6 +767,101 @@ function layoutCurvedGlyphText(font, text, emSizeMm, curveDeg, boxWidthMm, boxHe
   };
 }
 
+// src/machines.ts
+var XTOOL_MACHINES = {
+  P2S: {
+    name: "P2S",
+    extId: "P2S",
+    extName: "P2S",
+    deviceCode: "ZY013",
+    defaultPower: 55
+  },
+  "F2 Ultra UV": {
+    name: "F2 Ultra UV",
+    extId: "GS009-CLASS-4",
+    extName: "F2 Ultra UV",
+    deviceCode: "GS009-CLASS-4",
+    defaultPower: 5
+  },
+  S1: {
+    name: "S1",
+    extId: "S1",
+    extName: "S1",
+    deviceCode: "MD2",
+    defaultPower: 40
+  },
+  P3: {
+    name: "P3",
+    extId: "P3",
+    extName: "P3",
+    deviceCode: "ZY015",
+    defaultPower: 80
+  },
+  M2: {
+    name: "M2",
+    extId: "JS002",
+    extName: "M2",
+    deviceCode: "JS002",
+    defaultPower: 10
+  },
+  F2: {
+    name: "F2",
+    extId: "GS006",
+    extName: "F2",
+    deviceCode: "GS006",
+    defaultPower: 5
+  },
+  "F2 Ultra (Single)": {
+    name: "F2 Ultra (Single)",
+    extId: "GS007-CLASS-4",
+    extName: "F2 Ultra (Single)",
+    deviceCode: "GS007-CLASS-4",
+    defaultPower: 60
+  },
+  "F2 Ultra": {
+    name: "F2 Ultra",
+    extId: "GS004-CLASS-4",
+    extName: "F2 Ultra",
+    deviceCode: "GS004-CLASS-4",
+    defaultPower: 60
+  },
+  "M1 Ultra": {
+    name: "M1 Ultra",
+    extId: "M1Ultra",
+    extName: "M1 Ultra",
+    deviceCode: "ZH009",
+    defaultPower: 20
+  },
+  F1: {
+    name: "F1",
+    extId: "F1",
+    extName: "F1",
+    deviceCode: "MF1",
+    defaultPower: 10
+  },
+  "F1 Lite": {
+    name: "F1 Lite",
+    extId: "GS005",
+    extName: "F1 Lite",
+    deviceCode: "GS005",
+    defaultPower: 10
+  },
+  "F1 Ultra": {
+    name: "F1 Ultra",
+    extId: "F1Ultra",
+    extName: "F1 Ultra",
+    deviceCode: "GS002",
+    defaultPower: 20
+  },
+  MetalFab: {
+    name: "MetalFab",
+    extId: "HJ003",
+    extName: "MetalFab CNC Cutter",
+    deviceCode: "HJ003",
+    defaultPower: 1200
+  }
+};
+
 // src/builder.ts
 var XCSGenerator = class {
   canvasId;
@@ -773,12 +869,20 @@ var XCSGenerator = class {
   displays = [];
   layers = /* @__PURE__ */ new Map();
   options;
+  /** From `XTOOL_MACHINES`/a supplied `MachineProfile`; `deviceId` itself when the machine isn't known. */
+  extName;
+  /** `.xs`-only; unset when the machine's real `deviceCode` isn't verified (see `src/machines.ts`). */
+  deviceCode;
   /** Keyed by `JSON.stringify([processingType, values])` to merge displays sharing identical settings into one profile. */
   processingBindings = /* @__PURE__ */ new Map();
   constructor(options = {}) {
+    const machine = this.resolveMachine(options.deviceId);
+    const deviceId = machine?.extId ?? (typeof options.deviceId === "string" ? options.deviceId : "P2S");
+    this.extName = machine?.extName ?? deviceId;
+    this.deviceCode = machine?.deviceCode;
     this.options = {
-      deviceId: options.deviceId || "P2S",
-      devicePower: options.devicePower || 55,
+      deviceId,
+      devicePower: options.devicePower || machine?.defaultPower || 55,
       canvasWidth: options.canvasWidth || 400,
       canvasHeight: options.canvasHeight || 400
     };
@@ -786,6 +890,11 @@ var XCSGenerator = class {
     this.canvas = this.createCanvas();
     this.addLayer("#00befe", "{Cyan}", 1);
   }
+  /** Looks `deviceId` up in `XTOOL_MACHINES` by name, passes a supplied `MachineProfile` through, or returns `undefined` for a raw/unknown device id (including the "no option given" default of `"P2S"`). */
+  resolveMachine(deviceId) {
+    if (typeof deviceId === "object") return deviceId;
+    return XTOOL_MACHINES[deviceId ?? "P2S"];
+  }
   /**
    * Add a text object to the canvas. Pass `layout` (built via
    * `layoutGlyphText`/`layoutMultilineGlyphText`/`layoutCurvedGlyphText`
@@ -914,7 +1023,7 @@ var XCSGenerator = class {
       canvasId: this.canvasId,
       canvas: [this.canvas],
       extId: this.options.deviceId,
-      extName: this.options.deviceId,
+      extName: this.extName,
       device: {
         id: this.options.deviceId,
         power: this.options.devicePower,
@@ -952,13 +1061,19 @@ var XCSGenerator = class {
   }
   /**
    * Export as a `.xs` (v2 workspace) ZIP archive instead of `.xcs` --
-   * see `buildXsArchive` in `src/xs.ts` for the container format and
-   * its limitations (no processing profiles/device bindings yet).
+   * see `buildXsArchive` in `src/xs.ts` for the container format.
    * Display objects themselves carry over unchanged; only the
-   * container differs from `toBytes()`.
+   * container differs from `toBytes()`. `deviceCode` comes from
+   * `XTOOL_MACHINES`/a supplied `MachineProfile` (see
+   * `XCSGeneratorOptions.deviceId`) when known, else `buildXsArchive`
+   * falls back to the device id itself, as before.
    */
   toXsBytes() {
-    return buildXsArchive(this.generate(), Array.from(this.processingBindings.values()));
+    return buildXsArchive(
+      this.generate(),
+      Array.from(this.processingBindings.values()),
+      this.deviceCode
+    );
   }
   /** Merges a display into an existing profile when another display already shares its exact `processing` settings, else starts a new one. */
   registerProcessing(displayId, processing) {
@@ -1208,6 +1323,7 @@ function createXCS(deviceId = "P2S") {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   XCSGenerator,
+  XTOOL_MACHINES,
   assertXcsFormat,
   assertXsFormat,
   buildXsArchive,