@richardmcquiston01/unofficial-xcs-writer 0.6.0 → 0.8.0

package/CHANGELOG.md

@@ -5,6 +5,42 @@ 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.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
+
+- **`.xs` processing-profile support**: `.addText()`/`.addPath()`/`.addBitmap()` accept a new
+  `processing: { processingType, values }` option (`src/builder.ts`), which `.toXsBytes()`
+  (`src/xs.ts`'s `buildXsArchive`, now taking an optional `XsProcessingBinding[]`) turns into a
+  real `profiles.json` entry plus a matching `LASER_PLANE`-mode binding in
+  `devices/device-<id>.json`. Displays given identical `processingType`+`values` are merged into
+  one shared profile/binding, matching how real xTool Studio exports dedupe identical settings.
+  `.toBytes()` (`.xcs` output) ignores this option -- `.xcs`'s own per-display processing format
+  is structurally different and much less understood, so it isn't implemented (see `CLAUDE.md`'s
+  Open Issues).
+
 ## [0.6.0] - 2026-09-21
 
 ### Added

package/README.md

@@ -93,15 +93,46 @@ const project = createXCS('P2S')
     fontSize: 18,
     layout: layoutCurvedGlyphText(font, 'Arch Text', 6, 90, 60, 20, 'center'),
   })
-  .addPath('M0 0L10 0L10 10L0 10Z', 0, 60, 10, 10)
+  .addPath('M0 0L10 0L10 10L0 10Z', 0, 60, 10, 10, {
+    // Only affects .toXsBytes() output -- see below.
+    processing: { processingType: 'VECTOR_CUTTING', values: { power: 80, speed: 10 } },
+  })
   .toBytes(); // Uint8Array, ready to write to a .xcs file
 ```
 
 Call `.toXsBytes()` instead of `.toBytes()` to export the same project as a `.xs` (v2 workspace)
-archive — same chainable builder, same display objects, different container. Processing
-profiles/device bindings aren't populated (there's no `addProfile`-style API yet), so a
-generated `.xs` file's power/speed may need to be set manually in xTool Studio before
-cutting/engraving.
+archive — same chainable builder, same display objects, different container.
+
+Pass `processing: { processingType, values }` to `.addText()`/`.addPath()`/`.addBitmap()`'s
+options to set that display's power/speed/etc. in the exported `.xs` file's `profiles.json` +
+device bindings — `.xcs` output (`.toBytes()`) ignores this option; its own per-display
+processing format is different and not supported yet. Displays given identical settings share
+one profile/binding automatically. `processingType`/`values`' exact shape is xTool Studio's own
+and undocumented beyond real exports — see `xs_samples/*.xs`'s `profiles.json` for examples
+(`VECTOR_ENGRAVING`, `VECTOR_CUTTING`, `FILL_VECTOR_ENGRAVING`). Displays with no `processing`
+option behave as before: a generated `.xs` file's power/speed may need to be set manually in
+xTool Studio before cutting/engraving.
+
+`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
+import { createXCS, XTOOL_MACHINES } from '@richardmcquiston01/unofficial-xcs-writer';
+
+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`
+}
+```
+
+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.
 
 ## API
 
@@ -165,9 +196,9 @@ Packages an already-`generate()`d project (see Building, below) into a `.xs` v2
 
 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`)
+### Building (`src/builder.ts`, `src/layout.ts`, `src/machines.ts`)
 
-`createXCS(deviceId?)` / `new XCSGenerator(options?)` — starts a new project (one canvas, one default layer). Chainable methods:
+`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" above. Chainable methods:
 
 | Method | Adds |
 |--------|------|
@@ -176,7 +207,9 @@ Lower-level glyph-extraction primitives everything else in this library is built
 | `.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). |
 
-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` — see the note in "Building a project from scratch" above about unset processing profiles).
+`.addText()`/`.addPath()`/`.addBitmap()` all also accept a `processing: { processingType, values }` option — see "Building a project from scratch" above; 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:
 

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,
@@ -362,6 +363,36 @@ function renderXsFile(buffer, variables, values, fonts) {
 function encodeJson(value) {
   return new TextEncoder().encode(JSON.stringify(value));
 }
+function generateXsId(prefix) {
+  const uuid = typeof crypto !== "undefined" && crypto.randomUUID ? crypto.randomUUID() : "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, (c) => {
+    const r = Math.random() * 16 | 0;
+    const v = c === "x" ? r : r & 3 | 8;
+    return v.toString(16);
+  });
+  return `${prefix}:${uuid}`;
+}
+function buildProcessing(canvasId, bindings) {
+  const profiles = {};
+  const profileRefs = [];
+  const deviceBindings = [];
+  for (const binding of bindings) {
+    const profileId = generateXsId("profile");
+    profiles[profileId] = {
+      id: profileId,
+      processingType: binding.processingType,
+      values: binding.values
+    };
+    profileRefs.push(profileId);
+    deviceBindings.push({
+      bindingId: generateXsId("binding"),
+      canvasId,
+      mode: "LASER_PLANE",
+      baseProfileId: profileId,
+      displayIds: binding.displayIds
+    });
+  }
+  return { profiles, profileRefs, deviceBindings };
+}
 function decodeDataUrl(dataUrl) {
   const match = /^data:([^;]+);base64,(.*)$/.exec(dataUrl);
   if (!match) return null;
@@ -386,11 +417,15 @@ function coverResourceEntries(coverDataUrl) {
     })
   };
 }
-function buildXsArchive(file) {
+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.");
   }
+  const { profiles, profileRefs, deviceBindings } = buildProcessing(
+    canvas.id,
+    processingBindings
+  );
   return (0, import_fflate.zipSync)({
     ".format": new TextEncoder().encode("v2"),
     "meta/persistence-meta.json": encodeJson({
@@ -421,7 +456,7 @@ function buildXsArchive(file) {
       cover: "resources/project-cover.png",
       customProjectData: { projectTraceID: file.projectTraceID }
     }),
-    "profiles.json": encodeJson({ profiles: {} }),
+    "profiles.json": encodeJson({ profiles }),
     [`canvases/${canvas.id}.json`]: encodeJson({
       id: canvas.id,
       title: canvas.title,
@@ -444,7 +479,7 @@ function buildXsArchive(file) {
     }),
     [`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],
@@ -468,9 +503,9 @@ function buildXsArchive(file) {
                 focalLen: null,
                 focalLength: null
               },
-              profileRefs: [],
+              profileRefs,
               patches: {},
-              bindings: []
+              bindings: deviceBindings
             }
           }
         }
@@ -732,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;
@@ -739,10 +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
     };
@@ -750,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`
@@ -760,6 +905,7 @@ var XCSGenerator = class {
   addText(text, x, y, options = {}) {
     const textObj = this.createTextObject(text, x, y, options);
     this.displays.push(textObj);
+    this.registerProcessing(textObj.id, options.processing);
     return this;
   }
   /**
@@ -768,6 +914,7 @@ var XCSGenerator = class {
   addPath(pathData, x, y, width, height, options = {}) {
     const pathObj = this.createPathObject(pathData, x, y, width, height, options);
     this.displays.push(pathObj);
+    this.registerProcessing(pathObj.id, options.processing);
     return this;
   }
   /**
@@ -851,6 +998,7 @@ var XCSGenerator = class {
       opacity: 1
     };
     this.displays.push(bitmap);
+    this.registerProcessing(bitmap.id, options.processing);
     return this;
   }
   /**
@@ -875,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,
@@ -913,13 +1061,34 @@ 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());
+    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) {
+    if (!processing) return;
+    const key = JSON.stringify([processing.processingType, processing.values]);
+    const existing = this.processingBindings.get(key);
+    if (existing) {
+      existing.displayIds.push(displayId);
+      return;
+    }
+    this.processingBindings.set(key, {
+      processingType: processing.processingType,
+      values: processing.values,
+      displayIds: [displayId]
+    });
   }
   createCanvas() {
     return {
@@ -1154,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,