@richardmcquiston01/unofficial-xcs-writer 0.1.0

package/README.md

@@ -0,0 +1,97 @@
+# unofficial-xcs-writer
+
+A framework-agnostic TypeScript library for reading, writing, and applying variable substitution to `.xcs` files produced by [xTool Creative Space](https://www.xtool.com/pages/software). Not affiliated with xTool.
+
+## What is an XCS 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:
+
+- **Read** an XCS file and inspect its contents
+- **Extract** `{{token}}` template placeholders from text objects
+- **Render** a filled-in copy by substituting values for those placeholders
+
+## Installation
+
+```bash
+npm install @richardmcquiston01/unofficial-xcs-writer
+# or
+pnpm add @richardmcquiston01/unofficial-xcs-writer
+```
+
+## Usage
+
+```ts
+import { assertXcsFormat, extractXcsTokens, renderXcsFile } from '@richardmcquiston01/unofficial-xcs-writer';
+import type { XcsVariable } from '@richardmcquiston01/unofficial-xcs-writer';
+
+// Load an .xcs file as an ArrayBuffer (browser or Node.js)
+const buffer = await fetch('/templates/name-tag.xcs').then(r => r.arrayBuffer());
+
+// Validate it's a real XCS file
+assertXcsFormat(buffer); // throws if invalid
+
+// Discover which {{token}} placeholders are in the file
+const tokens = extractXcsTokens(buffer);
+// e.g. ['FirstName', 'LastName']
+
+// Define variables and supply values
+const variables: XcsVariable[] = [
+  { token: 'FirstName', defaultValue: 'Guest' },
+  { token: 'LastName' },
+];
+const values = { FirstName: 'Jane', LastName: 'Smith' };
+
+// Produce a filled-in .xcs file ready for download
+const output: Uint8Array = renderXcsFile(buffer, variables, values);
+```
+
+## 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): 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.
+
+### `XcsVariable`
+
+```ts
+interface XcsVariable {
+  token: string;        // token name without braces, e.g. "LastName"
+  defaultValue?: string;
+}
+```
+
+## Development
+
+```bash
+pnpm install     # install dev dependencies
+pnpm build       # compile → dist/ (ESM + CJS + .d.ts)
+pnpm dev         # watch mode — rebuilds on save
+pnpm test        # run tests with vitest
+npx tsc --noEmit # type-check without emitting
+```
+
+Output files after `pnpm build`:
+
+| File | Format |
+|------|--------|
+| `dist/index.js` | ESM |
+| `dist/index.cjs` | CommonJS |
+| `dist/index.d.ts` | TypeScript declarations |
+
+## Notes
+
+- All inputs and outputs use plain browser-compatible types (`ArrayBuffer`, `Uint8Array`, `string`) — no Node.js APIs, no DOM, no framework required.
+- 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.

package/dist/index.cjs

@@ -0,0 +1,83 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  assertXcsFormat: () => assertXcsFormat,
+  extractXcsTokens: () => extractXcsTokens,
+  readXcsFile: () => readXcsFile,
+  renderXcsFile: () => renderXcsFile
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/xcs.ts
+var TOKEN_RE = /\{\{([^}]+)\}\}/g;
+function assertXcsFormat(buffer) {
+  let project;
+  try {
+    project = JSON.parse(new TextDecoder().decode(buffer));
+  } catch (err) {
+    throw new Error(`Not a valid .xcs file: ${err.message}`);
+  }
+  if (typeof project !== "object" || project === null || !Array.isArray(project.canvas)) {
+    throw new Error("Not a valid .xcs file: missing canvas array.");
+  }
+}
+function readXcsFile(buffer) {
+  return new TextDecoder().decode(buffer);
+}
+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]);
+        }
+      }
+    }
+  }
+  return Array.from(seen);
+}
+function renderXcsFile(buffer, variables, values) {
+  const project = JSON.parse(readXcsFile(buffer));
+  for (const canvas of project.canvas) {
+    for (const display of canvas.displays) {
+      if (display.type === "TEXT" && typeof display.text === "string") {
+        let text = display.text;
+        for (const variable of variables) {
+          const replacement = values[variable.token] ?? variable.defaultValue ?? "";
+          text = text.replaceAll(`{{${variable.token}}}`, replacement);
+        }
+        display.text = text;
+      }
+    }
+  }
+  return new TextEncoder().encode(JSON.stringify(project));
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  assertXcsFormat,
+  extractXcsTokens,
+  readXcsFile,
+  renderXcsFile
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/xcs.ts"],"sourcesContent":["export type { XcsVariable, XcsProject, XcsCanvas, XcsDisplay } from './types.js';\nexport { assertXcsFormat, readXcsFile, extractXcsTokens, renderXcsFile } from './xcs.js';\n","import type { XcsProject, XcsVariable } from './types.js';\n\nconst TOKEN_RE = /\\{\\{([^}]+)\\}\\}/g;\n\nexport function assertXcsFormat(buffer: ArrayBuffer): void {\n  let project: unknown;\n  try {\n    project = JSON.parse(new TextDecoder().decode(buffer));\n  } catch (err) {\n    throw new Error(`Not a valid .xcs file: ${(err as Error).message}`);\n  }\n  if (\n    typeof project !== 'object' ||\n    project === null ||\n    !Array.isArray((project as Record<string, unknown>).canvas)\n  ) {\n    throw new Error('Not a valid .xcs file: missing canvas array.');\n  }\n}\n\nexport function readXcsFile(buffer: ArrayBuffer): string {\n  return new TextDecoder().decode(buffer);\n}\n\nexport function extractXcsTokens(buffer: ArrayBuffer): string[] {\n  const project = JSON.parse(readXcsFile(buffer)) as XcsProject;\n  const seen = new Set<string>();\n\n  for (const canvas of project.canvas) {\n    for (const display of canvas.displays) {\n      if (display.type === 'TEXT' && typeof display.text === 'string') {\n        for (const match of display.text.matchAll(TOKEN_RE)) {\n          seen.add(match[1]);\n        }\n      }\n    }\n  }\n\n  return Array.from(seen);\n}\n\nexport function renderXcsFile(\n  buffer: ArrayBuffer,\n  variables: XcsVariable[],\n  values: Record<string, string>,\n): Uint8Array {\n  const project = JSON.parse(readXcsFile(buffer)) as XcsProject;\n\n  for (const canvas of project.canvas) {\n    for (const display of canvas.displays) {\n      if (display.type === 'TEXT' && typeof display.text === 'string') {\n        let text = display.text;\n        for (const variable of variables) {\n          const replacement = values[variable.token] ?? variable.defaultValue ?? '';\n          text = text.replaceAll(`{{${variable.token}}}`, replacement);\n        }\n        display.text = text;\n      }\n    }\n  }\n\n  return new TextEncoder().encode(JSON.stringify(project));\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACEA,IAAM,WAAW;AAEV,SAAS,gBAAgB,QAA2B;AACzD,MAAI;AACJ,MAAI;AACF,cAAU,KAAK,MAAM,IAAI,YAAY,EAAE,OAAO,MAAM,CAAC;AAAA,EACvD,SAAS,KAAK;AACZ,UAAM,IAAI,MAAM,0BAA2B,IAAc,OAAO,EAAE;AAAA,EACpE;AACA,MACE,OAAO,YAAY,YACnB,YAAY,QACZ,CAAC,MAAM,QAAS,QAAoC,MAAM,GAC1D;AACA,UAAM,IAAI,MAAM,8CAA8C;AAAA,EAChE;AACF;AAEO,SAAS,YAAY,QAA6B;AACvD,SAAO,IAAI,YAAY,EAAE,OAAO,MAAM;AACxC;AAEO,SAAS,iBAAiB,QAA+B;AAC9D,QAAM,UAAU,KAAK,MAAM,YAAY,MAAM,CAAC;AAC9C,QAAM,OAAO,oBAAI,IAAY;AAE7B,aAAW,UAAU,QAAQ,QAAQ;AACnC,eAAW,WAAW,OAAO,UAAU;AACrC,UAAI,QAAQ,SAAS,UAAU,OAAO,QAAQ,SAAS,UAAU;AAC/D,mBAAW,SAAS,QAAQ,KAAK,SAAS,QAAQ,GAAG;AACnD,eAAK,IAAI,MAAM,CAAC,CAAC;AAAA,QACnB;AAAA,MACF;AAAA,IACF;AAAA,EACF;AAEA,SAAO,MAAM,KAAK,IAAI;AACxB;AAEO,SAAS,cACd,QACA,WACA,QACY;AACZ,QAAM,UAAU,KAAK,MAAM,YAAY,MAAM,CAAC;AAE9C,aAAW,UAAU,QAAQ,QAAQ;AACnC,eAAW,WAAW,OAAO,UAAU;AACrC,UAAI,QAAQ,SAAS,UAAU,OAAO,QAAQ,SAAS,UAAU;AAC/D,YAAI,OAAO,QAAQ;AACnB,mBAAW,YAAY,WAAW;AAChC,gBAAM,cAAc,OAAO,SAAS,KAAK,KAAK,SAAS,gBAAgB;AACvE,iBAAO,KAAK,WAAW,KAAK,SAAS,KAAK,MAAM,WAAW;AAAA,QAC7D;AACA,gBAAQ,OAAO;AAAA,MACjB;AAAA,IACF;AAAA,EACF;AAEA,SAAO,IAAI,YAAY,EAAE,OAAO,KAAK,UAAU,OAAO,CAAC;AACzD;","names":[]}

package/dist/index.d.cts

@@ -0,0 +1,25 @@
+interface XcsVariable {
+    token: string;
+    defaultValue?: string;
+}
+interface XcsDisplay {
+    type: string;
+    text?: string;
+    [key: string]: unknown;
+}
+interface XcsCanvas {
+    displays: XcsDisplay[];
+    [key: string]: unknown;
+}
+interface XcsProject {
+    canvasId: string;
+    canvas: XcsCanvas[];
+    [key: string]: unknown;
+}
+
+declare function assertXcsFormat(buffer: ArrayBuffer): void;
+declare function readXcsFile(buffer: ArrayBuffer): string;
+declare function extractXcsTokens(buffer: ArrayBuffer): string[];
+declare function renderXcsFile(buffer: ArrayBuffer, variables: XcsVariable[], values: Record<string, string>): Uint8Array;
+
+export { type XcsCanvas, type XcsDisplay, type XcsProject, type XcsVariable, assertXcsFormat, extractXcsTokens, readXcsFile, renderXcsFile };

package/dist/index.d.ts

@@ -0,0 +1,25 @@
+interface XcsVariable {
+    token: string;
+    defaultValue?: string;
+}
+interface XcsDisplay {
+    type: string;
+    text?: string;
+    [key: string]: unknown;
+}
+interface XcsCanvas {
+    displays: XcsDisplay[];
+    [key: string]: unknown;
+}
+interface XcsProject {
+    canvasId: string;
+    canvas: XcsCanvas[];
+    [key: string]: unknown;
+}
+
+declare function assertXcsFormat(buffer: ArrayBuffer): void;
+declare function readXcsFile(buffer: ArrayBuffer): string;
+declare function extractXcsTokens(buffer: ArrayBuffer): string[];
+declare function renderXcsFile(buffer: ArrayBuffer, variables: XcsVariable[], values: Record<string, string>): Uint8Array;
+
+export { type XcsCanvas, type XcsDisplay, type XcsProject, type XcsVariable, assertXcsFormat, extractXcsTokens, readXcsFile, renderXcsFile };

package/dist/index.js

@@ -0,0 +1,53 @@
+// src/xcs.ts
+var TOKEN_RE = /\{\{([^}]+)\}\}/g;
+function assertXcsFormat(buffer) {
+  let project;
+  try {
+    project = JSON.parse(new TextDecoder().decode(buffer));
+  } catch (err) {
+    throw new Error(`Not a valid .xcs file: ${err.message}`);
+  }
+  if (typeof project !== "object" || project === null || !Array.isArray(project.canvas)) {
+    throw new Error("Not a valid .xcs file: missing canvas array.");
+  }
+}
+function readXcsFile(buffer) {
+  return new TextDecoder().decode(buffer);
+}
+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]);
+        }
+      }
+    }
+  }
+  return Array.from(seen);
+}
+function renderXcsFile(buffer, variables, values) {
+  const project = JSON.parse(readXcsFile(buffer));
+  for (const canvas of project.canvas) {
+    for (const display of canvas.displays) {
+      if (display.type === "TEXT" && typeof display.text === "string") {
+        let text = display.text;
+        for (const variable of variables) {
+          const replacement = values[variable.token] ?? variable.defaultValue ?? "";
+          text = text.replaceAll(`{{${variable.token}}}`, replacement);
+        }
+        display.text = text;
+      }
+    }
+  }
+  return new TextEncoder().encode(JSON.stringify(project));
+}
+export {
+  assertXcsFormat,
+  extractXcsTokens,
+  readXcsFile,
+  renderXcsFile
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/xcs.ts"],"sourcesContent":["import type { XcsProject, XcsVariable } from './types.js';\n\nconst TOKEN_RE = /\\{\\{([^}]+)\\}\\}/g;\n\nexport function assertXcsFormat(buffer: ArrayBuffer): void {\n  let project: unknown;\n  try {\n    project = JSON.parse(new TextDecoder().decode(buffer));\n  } catch (err) {\n    throw new Error(`Not a valid .xcs file: ${(err as Error).message}`);\n  }\n  if (\n    typeof project !== 'object' ||\n    project === null ||\n    !Array.isArray((project as Record<string, unknown>).canvas)\n  ) {\n    throw new Error('Not a valid .xcs file: missing canvas array.');\n  }\n}\n\nexport function readXcsFile(buffer: ArrayBuffer): string {\n  return new TextDecoder().decode(buffer);\n}\n\nexport function extractXcsTokens(buffer: ArrayBuffer): string[] {\n  const project = JSON.parse(readXcsFile(buffer)) as XcsProject;\n  const seen = new Set<string>();\n\n  for (const canvas of project.canvas) {\n    for (const display of canvas.displays) {\n      if (display.type === 'TEXT' && typeof display.text === 'string') {\n        for (const match of display.text.matchAll(TOKEN_RE)) {\n          seen.add(match[1]);\n        }\n      }\n    }\n  }\n\n  return Array.from(seen);\n}\n\nexport function renderXcsFile(\n  buffer: ArrayBuffer,\n  variables: XcsVariable[],\n  values: Record<string, string>,\n): Uint8Array {\n  const project = JSON.parse(readXcsFile(buffer)) as XcsProject;\n\n  for (const canvas of project.canvas) {\n    for (const display of canvas.displays) {\n      if (display.type === 'TEXT' && typeof display.text === 'string') {\n        let text = display.text;\n        for (const variable of variables) {\n          const replacement = values[variable.token] ?? variable.defaultValue ?? '';\n          text = text.replaceAll(`{{${variable.token}}}`, replacement);\n        }\n        display.text = text;\n      }\n    }\n  }\n\n  return new TextEncoder().encode(JSON.stringify(project));\n}\n"],"mappings":";AAEA,IAAM,WAAW;AAEV,SAAS,gBAAgB,QAA2B;AACzD,MAAI;AACJ,MAAI;AACF,cAAU,KAAK,MAAM,IAAI,YAAY,EAAE,OAAO,MAAM,CAAC;AAAA,EACvD,SAAS,KAAK;AACZ,UAAM,IAAI,MAAM,0BAA2B,IAAc,OAAO,EAAE;AAAA,EACpE;AACA,MACE,OAAO,YAAY,YACnB,YAAY,QACZ,CAAC,MAAM,QAAS,QAAoC,MAAM,GAC1D;AACA,UAAM,IAAI,MAAM,8CAA8C;AAAA,EAChE;AACF;AAEO,SAAS,YAAY,QAA6B;AACvD,SAAO,IAAI,YAAY,EAAE,OAAO,MAAM;AACxC;AAEO,SAAS,iBAAiB,QAA+B;AAC9D,QAAM,UAAU,KAAK,MAAM,YAAY,MAAM,CAAC;AAC9C,QAAM,OAAO,oBAAI,IAAY;AAE7B,aAAW,UAAU,QAAQ,QAAQ;AACnC,eAAW,WAAW,OAAO,UAAU;AACrC,UAAI,QAAQ,SAAS,UAAU,OAAO,QAAQ,SAAS,UAAU;AAC/D,mBAAW,SAAS,QAAQ,KAAK,SAAS,QAAQ,GAAG;AACnD,eAAK,IAAI,MAAM,CAAC,CAAC;AAAA,QACnB;AAAA,MACF;AAAA,IACF;AAAA,EACF;AAEA,SAAO,MAAM,KAAK,IAAI;AACxB;AAEO,SAAS,cACd,QACA,WACA,QACY;AACZ,QAAM,UAAU,KAAK,MAAM,YAAY,MAAM,CAAC;AAE9C,aAAW,UAAU,QAAQ,QAAQ;AACnC,eAAW,WAAW,OAAO,UAAU;AACrC,UAAI,QAAQ,SAAS,UAAU,OAAO,QAAQ,SAAS,UAAU;AAC/D,YAAI,OAAO,QAAQ;AACnB,mBAAW,YAAY,WAAW;AAChC,gBAAM,cAAc,OAAO,SAAS,KAAK,KAAK,SAAS,gBAAgB;AACvE,iBAAO,KAAK,WAAW,KAAK,SAAS,KAAK,MAAM,WAAW;AAAA,QAC7D;AACA,gBAAQ,OAAO;AAAA,MACjB;AAAA,IACF;AAAA,EACF;AAEA,SAAO,IAAI,YAAY,EAAE,OAAO,KAAK,UAAU,OAAO,CAAC;AACzD;","names":[]}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@richardmcquiston01/unofficial-xcs-writer",
+  "version": "0.1.0",
+  "description": "Read, write, and apply variable substitution to xTool Creative Space .xcs files",
+  "license": "MIT",
+  "author": "Richard McQuiston <richard.mcquiston01@gmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/RichardMcQuiston01/unofficial-xcs-writer.git"
+  },
+  "homepage": "https://github.com/RichardMcQuiston01/unofficial-xcs-writer#readme",
+  "bugs": "https://github.com/RichardMcQuiston01/unofficial-xcs-writer/issues",
+  "keywords": ["xtool", "xcs", "laser", "template", "variable-substitution"],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": ["dist"],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.4.0",
+    "vitest": "^1.6.0"
+  }
+}