@richardmcquiston01/unofficial-xcs-writer 0.5.0 → 0.7.0

package/CHANGELOG.md

@@ -5,6 +5,34 @@ 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).
 
+## [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
+
+- **`.xs` generation**: `XCSGenerator.toXsBytes()` (`src/xs.ts`'s new `buildXsArchive`) exports a
+  built project as a `.xs` v2 archive instead of `.xcs` -- the same chainable builder
+  (`.addText()`/`.addPath()`/`.addBitmap()`/`.addLayer()`), same display objects, different
+  container. `project.json`/`profiles.json`/`devices/`/`canvases/` metadata is synthesized
+  fresh, always as a single canvas in a single `displays-0.json` chunk, with the cover image
+  written as a real `resources/project-cover.png` file instead of inline base64. Processing
+  profiles and device bindings are left empty (no `addProfile`-style API exists yet) -- a
+  generated `.xs` file's power/speed settings may need to be configured manually in xTool
+  Studio before cutting/engraving.
+
 ## [0.5.0] - 2026-09-20
 
 ### Added

package/README.md

@@ -13,7 +13,7 @@ This library lets you, for both formats:
 - **Read** a file and inspect its contents
 - **Extract** `{{token}}` template placeholders from text objects
 - **Render** a filled-in copy by substituting values for those placeholders
-- **Build** a new `.xcs` project from scratch — text (straight, multi-line, or curved), paths, and embedded images (`.xs` generation isn't supported yet — see `CLAUDE.md`'s "Open Issues")
+- **Build** a new project from scratch — text (straight, multi-line, or curved), paths, and embedded images — and export it as either `.xcs` or `.xs`
 
 ## Installation
 
@@ -93,10 +93,26 @@ 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.
+
+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.
+
 ## API
 
 ### `assertXcsFormat(buffer: ArrayBuffer): void`
@@ -151,6 +167,10 @@ Same as `extractXcsTokens`, but scans every `canvases/<canvasId>/displays-<chunk
 
 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.
@@ -166,7 +186,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), or `.toBytes()` (`Uint8Array`, matching `renderXcsFile`'s output type).
+`.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

@@ -33,6 +33,7 @@ __export(index_exports, {
   XCSGenerator: () => XCSGenerator,
   assertXcsFormat: () => assertXcsFormat,
   assertXsFormat: () => assertXsFormat,
+  buildXsArchive: () => buildXsArchive,
   createXCS: () => createXCS,
   effectiveCurveDeg: () => effectiveCurveDeg,
   extractXcsTokens: () => extractXcsTokens,
@@ -358,6 +359,160 @@ function renderXsFile(buffer, variables, values, fonts) {
   }
   return (0, import_fflate.zipSync)(entries);
 }
+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;
+  const [, mimeType, base64] = match;
+  const binary = atob(base64);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
+  return { bytes, mimeType };
+}
+function coverResourceEntries(coverDataUrl) {
+  const cover = decodeDataUrl(coverDataUrl);
+  if (!cover) return {};
+  return {
+    "resources/project-cover.png": cover.bytes,
+    "resources/project-cover.png.meta.json": encodeJson({
+      ref: "resources/project-cover.png",
+      metadata: {
+        kind: "image",
+        source: { type: "workspace", value: "project-cover.png" },
+        mimeType: cover.mimeType
+      }
+    })
+  };
+}
+function buildXsArchive(file, processingBindings = []) {
+  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({
+      schemaVersion: "2.0.0",
+      protocol: "xcs-workspace-v2"
+    }),
+    "project.json": encodeJson({
+      __v2__: true,
+      version: "2.0.0",
+      schemaMeta: { schemaVersion: "2.1.0", format: "directory" },
+      projectId: file.projectTraceID,
+      projectTraceID: file.projectTraceID,
+      projectName: "Untitled",
+      activeCanvasId: canvas.id,
+      activeDeviceId: file.device.id,
+      versionInfo: {
+        source: "web",
+        appVersion: "",
+        savedAt: file.modify,
+        ua: file.ua,
+        minRequiredVersion: file.minRequiredVersion,
+        appMinRequiredVersion: file.appMinRequiredVersion,
+        webMinRequiredVersion: file.webMinRequiredVersion
+      },
+      created: file.created,
+      modify: file.modify,
+      modules: { canvases: [canvas.id], devices: [file.device.id] },
+      cover: "resources/project-cover.png",
+      customProjectData: { projectTraceID: file.projectTraceID }
+    }),
+    "profiles.json": encodeJson({ profiles }),
+    [`canvases/${canvas.id}.json`]: encodeJson({
+      id: canvas.id,
+      title: canvas.title,
+      hidden: false,
+      layerData: canvas.layerData,
+      groupData: canvas.groupData,
+      extendInfo: {
+        version: canvas.extendInfo.version,
+        minCanvasVersion: canvas.extendInfo.minCanvasVersion,
+        displayProcessConfigMap: {},
+        rulerPluginData: { rulerGuide: [] },
+        type: "2d"
+      },
+      chunkLayout: { displayCount: canvas.displays.length, chunkCount: 1, chunkIndexes: [0] }
+    }),
+    [`canvases/${canvas.id}/displays-0.json`]: encodeJson({
+      canvasId: canvas.id,
+      chunkIndex: 0,
+      displays: canvas.displays
+    }),
+    [`devices/device-${file.device.id}.json`]: encodeJson({
+      id: file.device.id,
+      deviceCode: file.device.id,
+      extId: file.extId,
+      extName: file.extName,
+      power: [file.device.power],
+      processing: {
+        [canvas.id]: {
+          id: canvas.id,
+          activeMode: "LASER_PLANE",
+          modes: {
+            LASER_PLANE: {
+              ignoredDisplayIds: [],
+              data: {
+                material: 0,
+                thickness: null,
+                perimeter: null,
+                diameter: null,
+                isProcessByLayer: false,
+                pathPlanning: "auto",
+                fillPlanning: "separate",
+                scanDirection: "topToBottom",
+                enableOddEvenKerf: true,
+                focalLen: null,
+                focalLength: null
+              },
+              profileRefs,
+              patches: {},
+              bindings: deviceBindings
+            }
+          }
+        }
+      }
+    }),
+    ...coverResourceEntries(file.cover)
+  });
+}
 
 // src/layout.ts
 var LAYOUT_MM_PER_EM = 25.4;
@@ -618,6 +773,8 @@ var XCSGenerator = class {
   displays = [];
   layers = /* @__PURE__ */ new Map();
   options;
+  /** Keyed by `JSON.stringify([processingType, values])` to merge displays sharing identical settings into one profile. */
+  processingBindings = /* @__PURE__ */ new Map();
   constructor(options = {}) {
     this.options = {
       deviceId: options.deviceId || "P2S",
@@ -639,6 +796,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;
   }
   /**
@@ -647,6 +805,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;
   }
   /**
@@ -730,6 +889,7 @@ var XCSGenerator = class {
       opacity: 1
     };
     this.displays.push(bitmap);
+    this.registerProcessing(bitmap.id, options.processing);
     return this;
   }
   /**
@@ -790,6 +950,31 @@ var XCSGenerator = class {
   toBytes() {
     return new TextEncoder().encode(this.toJSON());
   }
+  /**
+   * 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).
+   * Display objects themselves carry over unchanged; only the
+   * container differs from `toBytes()`.
+   */
+  toXsBytes() {
+    return buildXsArchive(this.generate(), Array.from(this.processingBindings.values()));
+  }
+  /** 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 {
       id: this.canvasId,
@@ -1025,6 +1210,7 @@ function createXCS(deviceId = "P2S") {
   XCSGenerator,
   assertXcsFormat,
   assertXsFormat,
+  buildXsArchive,
   createXCS,
   effectiveCurveDeg,
   extractXcsTokens,