@richardmcquiston01/unofficial-xcs-writer 0.4.1 → 0.5.0

package/CHANGELOG.md

@@ -5,6 +5,23 @@ 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.5.0] - 2026-09-20
+
+### Added
+
+- **`.xs` (v2 workspace) format support** (`src/xs.ts`): `assertXsFormat`, `extractXsTokens`,
+  and `renderXsFile` read and apply `{{token}}` substitution to xTool Studio v1.7+'s new `.xs`
+  format — a ZIP archive of chunked per-canvas display files, unlike `.xcs`'s single plain-JSON
+  document. `.xcs` is now legacy as of xTool Studio v1.7 (still readable, no longer savable from
+  the app). The `TEXT` display schema itself (`text`/`style`/`fontData`/`charJSONs`) is
+  unchanged from `.xcs`, so token extraction and glyph regeneration share their implementation
+  with `renderXcsFile`/`extractXcsTokens` via a new `src/substitution.ts` module; only the
+  container format differs. Archives are read/written with [fflate](https://github.com/101arrowz/fflate)
+  (new runtime dependency); every entry other than the modified displays chunks round-trips
+  byte-for-byte unchanged, including large `PATH` displays' deduplicated `vectors/<bucketType>/`
+  vector store. `.xs` *generation* (building a new project from scratch) isn't implemented yet
+  — see `CLAUDE.md`'s "Open Issues".
+
 ## [0.4.1] - 2026-09-19
 
 ### Changed

package/README.md

@@ -1,15 +1,19 @@
 # unofficial-xcs-writer
 
-A framework-agnostic TypeScript library for reading, writing, building, and applying variable substitution to `.xcs` files produced by [xTool Creative Space](https://www.xtool.com/pages/software). Not affiliated with xTool.
+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.
 
-## What is an XCS file?
+## What is an XCS / XS file?
 
-An `.xcs` file is a plain UTF-8 JSON document exported by xTool Creative Space. It describes a laser project — canvas dimensions, design objects (shapes, text, images), layer assignments, and device parameters. This library lets you:
+An `.xcs` file is a plain UTF-8 JSON document exported by xTool Creative Space. It describes a laser project — canvas dimensions, design objects (shapes, text, images), layer assignments, and device parameters.
 
-- **Read** an XCS file and inspect its contents
+Starting with xTool Studio v1.7, new projects are saved as `.xs` instead — a ZIP archive of several JSON files (project metadata, per-canvas display chunks, processing profiles, device bindings, and binary resources as real files rather than inline base64). `.xcs` is now legacy: v1.7+ can still open `.xcs` files but can no longer save back to that format. See `src/xs.ts` for the full format writeup.
+
+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
+- **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")
 
 ## Installation
 
@@ -46,6 +50,21 @@ const values = { FirstName: 'Jane', LastName: 'Smith' };
 const output: Uint8Array = renderXcsFile(buffer, variables, values);
 ```
 
+### Working with `.xs` files
+
+Same shape, different functions — `.xs` is a ZIP archive, so there's no `readXsFile` equivalent to `readXcsFile` (there's no single JSON string to return), but token extraction and substitution work the same way:
+
+```ts
+import { assertXsFormat, extractXsTokens, renderXsFile } from '@richardmcquiston01/unofficial-xcs-writer';
+
+const buffer = await fetch('/templates/name-tag.xs').then(r => r.arrayBuffer());
+
+assertXsFormat(buffer); // throws if invalid
+const tokens = extractXsTokens(buffer); // e.g. ['FirstName', 'LastName']
+
+const output: Uint8Array = renderXsFile(buffer, variables, values);
+```
+
 ### Building a project from scratch
 
 ```ts
@@ -118,6 +137,20 @@ interface XcsVariable {
 }
 ```
 
+### `.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.
+
 ### `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.
@@ -175,7 +208,8 @@ It needs an `NPM_TOKEN` repository secret with publish rights.
 
 - 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.)
 - Only `TEXT` display objects are modified during substitution. Geometry, bitmaps, device configuration, and all other fields pass through unchanged.
-- This library targets the current xTool Creative Space JSON format. Older versions of the software may export a different structure.
+- This library targets the current xTool Creative Space JSON/`.xs` formats. Older versions of the software may export a different structure.
+- `.xs` archives are read and re-written with [fflate](https://github.com/101arrowz/fflate); large `PATH` displays' vector data may be deduplicated into a separate `vectors/<bucketType>/` store rather than inlined — this library never touches `PATH` displays, so that structure round-trips untouched.
 - Glyph outline extraction is powered by [opentype.js](https://github.com/opentypejs/opentype.js). The bundled fallback font is [Arimo](https://fonts.google.com/specimen/Arimo) v5.2.8 via [`@fontsource/arimo`](https://www.npmjs.com/package/@fontsource/arimo) (Apache License 2.0, see `third_party/arimo/LICENSE`).
 
 ## License

package/dist/index.cjs

@@ -32,9 +32,11 @@ var index_exports = {};
 __export(index_exports, {
   XCSGenerator: () => XCSGenerator,
   assertXcsFormat: () => assertXcsFormat,
+  assertXsFormat: () => assertXsFormat,
   createXCS: () => createXCS,
   effectiveCurveDeg: () => effectiveCurveDeg,
   extractXcsTokens: () => extractXcsTokens,
+  extractXsTokens: () => extractXsTokens,
   fontSizePoints: () => fontSizePoints,
   layoutCurvedGlyphText: () => layoutCurvedGlyphText,
   layoutGlyphText: () => layoutGlyphText,
@@ -44,6 +46,7 @@ __export(index_exports, {
   loadFont: () => loadFont,
   readXcsFile: () => readXcsFile,
   renderXcsFile: () => renderXcsFile,
+  renderXsFile: () => renderXsFile,
   translateGlyphLayout: () => translateGlyphLayout
 });
 module.exports = __toCommonJS(index_exports);
@@ -228,8 +231,56 @@ function layoutText(font, text, originX, originY) {
   };
 }
 
-// src/xcs.ts
+// src/substitution.ts
 var TOKEN_RE = /\{\{([^}]+)\}\}/g;
+function collectTextTokens(displays, seen) {
+  for (const display of displays) {
+    if (display.type === "TEXT" && typeof display.text === "string") {
+      for (const match of display.text.matchAll(TOKEN_RE)) {
+        seen.add(match[1]);
+      }
+    }
+  }
+}
+function resolveFont(fontFamily, fonts, cache) {
+  const key = fontFamily ?? "";
+  const cached = cache.get(key);
+  if (cached) return cached;
+  const suppliedBuffer = fontFamily ? fonts?.[fontFamily] : void 0;
+  const font = suppliedBuffer ? loadFont(suppliedBuffer) : loadDefaultFont();
+  cache.set(key, font);
+  return font;
+}
+function substituteTextDisplays(displays, variables, values, fonts, fontCache) {
+  for (const display of displays) {
+    if (display.type !== "TEXT" || typeof display.text !== "string") continue;
+    const originalText = display.text;
+    let text = originalText;
+    for (const variable of variables) {
+      const replacement = values[variable.token] ?? variable.defaultValue ?? "";
+      text = text.replaceAll(`{{${variable.token}}}`, replacement);
+    }
+    display.text = text;
+    if (text === originalText) continue;
+    const style = display.style;
+    const font = resolveFont(style?.fontFamily, fonts, fontCache);
+    const originX = typeof display.x === "number" ? display.x : 0;
+    const originY = typeof display.y === "number" ? display.y : 0;
+    const layout = layoutText(font, text, originX, originY);
+    display.fontData = layout.fontData;
+    display.charJSONs = layout.charJSONs;
+    if (layout.x !== null && layout.y !== null) {
+      display.x = layout.x;
+      display.y = layout.y;
+      display.offsetX = layout.x;
+      display.offsetY = layout.y;
+      display.width = layout.width;
+      display.height = layout.height;
+    }
+  }
+}
+
+// src/xcs.ts
 function assertXcsFormat(buffer) {
   let project;
   try {
@@ -248,60 +299,66 @@ function extractXcsTokens(buffer) {
   const project = JSON.parse(readXcsFile(buffer));
   const seen = /* @__PURE__ */ new Set();
   for (const canvas of project.canvas) {
-    for (const display of canvas.displays) {
-      if (display.type === "TEXT" && typeof display.text === "string") {
-        for (const match of display.text.matchAll(TOKEN_RE)) {
-          seen.add(match[1]);
-        }
-      }
-    }
+    collectTextTokens(canvas.displays, seen);
   }
   return Array.from(seen);
 }
-function resolveFont(fontFamily, fonts, cache) {
-  const key = fontFamily ?? "";
-  const cached = cache.get(key);
-  if (cached) return cached;
-  const suppliedBuffer = fontFamily ? fonts?.[fontFamily] : void 0;
-  const font = suppliedBuffer ? loadFont(suppliedBuffer) : loadDefaultFont();
-  cache.set(key, font);
-  return font;
-}
 function renderXcsFile(buffer, variables, values, fonts) {
   const project = JSON.parse(readXcsFile(buffer));
   const fontCache = /* @__PURE__ */ new Map();
   for (const canvas of project.canvas) {
-    for (const display of canvas.displays) {
-      if (display.type === "TEXT" && typeof display.text === "string") {
-        const originalText = display.text;
-        let text = originalText;
-        for (const variable of variables) {
-          const replacement = values[variable.token] ?? variable.defaultValue ?? "";
-          text = text.replaceAll(`{{${variable.token}}}`, replacement);
-        }
-        display.text = text;
-        if (text === originalText) continue;
-        const style = display.style;
-        const font = resolveFont(style?.fontFamily, fonts, fontCache);
-        const originX = typeof display.x === "number" ? display.x : 0;
-        const originY = typeof display.y === "number" ? display.y : 0;
-        const layout = layoutText(font, text, originX, originY);
-        display.fontData = layout.fontData;
-        display.charJSONs = layout.charJSONs;
-        if (layout.x !== null && layout.y !== null) {
-          display.x = layout.x;
-          display.y = layout.y;
-          display.offsetX = layout.x;
-          display.offsetY = layout.y;
-          display.width = layout.width;
-          display.height = layout.height;
-        }
-      }
-    }
+    substituteTextDisplays(canvas.displays, variables, values, fonts, fontCache);
   }
   return new TextEncoder().encode(JSON.stringify(project));
 }
 
+// src/xs.ts
+var import_fflate = require("fflate");
+var DISPLAYS_CHUNK_RE = /^canvases\/[^/]+\/displays-\d+\.json$/;
+function decodeJson(bytes) {
+  return JSON.parse(new TextDecoder().decode(bytes));
+}
+function assertXsFormat(buffer) {
+  let entries;
+  try {
+    entries = (0, import_fflate.unzipSync)(new Uint8Array(buffer));
+  } catch (err) {
+    throw new Error(`Not a valid .xs file: ${err.message}`);
+  }
+  const format = entries[".format"];
+  if (!format) {
+    throw new Error("Not a valid .xs file: missing .format entry.");
+  }
+  const formatVersion = new TextDecoder().decode(format).trim();
+  if (formatVersion !== "v2") {
+    throw new Error(`Unsupported .xs format version "${formatVersion}" (expected "v2").`);
+  }
+  if (!entries["project.json"]) {
+    throw new Error("Not a valid .xs file: missing project.json.");
+  }
+}
+function extractXsTokens(buffer) {
+  const entries = (0, import_fflate.unzipSync)(new Uint8Array(buffer));
+  const seen = /* @__PURE__ */ new Set();
+  for (const [path, data] of Object.entries(entries)) {
+    if (!DISPLAYS_CHUNK_RE.test(path)) continue;
+    const chunk = decodeJson(data);
+    collectTextTokens(chunk.displays, seen);
+  }
+  return Array.from(seen);
+}
+function renderXsFile(buffer, variables, values, fonts) {
+  const entries = (0, import_fflate.unzipSync)(new Uint8Array(buffer));
+  const fontCache = /* @__PURE__ */ new Map();
+  for (const [path, data] of Object.entries(entries)) {
+    if (!DISPLAYS_CHUNK_RE.test(path)) continue;
+    const chunk = decodeJson(data);
+    substituteTextDisplays(chunk.displays, variables, values, fonts, fontCache);
+    entries[path] = new TextEncoder().encode(JSON.stringify(chunk));
+  }
+  return (0, import_fflate.zipSync)(entries);
+}
+
 // src/layout.ts
 var LAYOUT_MM_PER_EM = 25.4;
 function fontSizePoints(emSizeMm) {
@@ -967,9 +1024,11 @@ function createXCS(deviceId = "P2S") {
 0 && (module.exports = {
   XCSGenerator,
   assertXcsFormat,
+  assertXsFormat,
   createXCS,
   effectiveCurveDeg,
   extractXcsTokens,
+  extractXsTokens,
   fontSizePoints,
   layoutCurvedGlyphText,
   layoutGlyphText,
@@ -979,6 +1038,7 @@ function createXCS(deviceId = "P2S") {
   loadFont,
   readXcsFile,
   renderXcsFile,
+  renderXsFile,
   translateGlyphLayout
 });
 //# sourceMappingURL=index.cjs.map