@richardmcquiston01/unofficial-xcs-writer 0.3.1 → 0.5.0

package/CHANGELOG.md

@@ -5,6 +5,60 @@ 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
+
+- Version bump only — 0.4.0 itself was never published to npm (only consumed
+  ahead of release via a git dependency from `maker-toolkit`'s `apps/desktop`,
+  which pointed at this repo's `dist` branch as a workaround). No code changes
+  from 0.4.0; this is the first published release carrying the generation API
+  and curved-text layout described below.
+
+## [0.4.0] - 2026-09-19
+
+### Added
+
+- **Generation API** (`src/builder.ts`): `XCSGenerator`/`createXCS` build a `.xcs` project from
+  scratch — canvas, layers, and `TEXT`/`PATH`/`BITMAP` displays — ported from `maker-toolkit`'s
+  previously-duplicated hand-rolled generator. Chainable `.addText()`/`.addPath()`/
+  `.addBitmap()`/`.addLayer()`, then `.generate()`/`.toJSON()`/`.toBytes()`.
+- **Curved text layout** (`src/layout.ts`): `layoutCurvedGlyphText` lays a single line of text
+  out along a circular arc, baking each character's rotated position and glyph shape directly
+  (same approach `renderXcsFile` already uses for straight substituted text — xTool Studio only
+  trusts stored glyph shapes). Uses the same arc-geometry convention (chord width, sweep angle,
+  up/down sign, align-driven start offset) as SVG `<textPath>`/canvas curved-text editors, so a
+  document renders consistently across export formats. Not yet visually verified against real
+  xTool Studio output — see `CLAUDE.md`'s "Open Issues".
+- `layoutGlyphText`/`layoutMultilineGlyphText`/`translateGlyphLayout`/`fontSizePoints`
+  (`src/layout.ts`): the higher-level, real-world-scaled/positioned layout helpers built on
+  `glyphs.ts`'s `layoutText`, also ported from `maker-toolkit` (previously duplicated
+  consumer-side). `effectiveCurveDeg` clamps/normalizes a curve angle (±355°, treats <1° as
+  straight).
+
+### Changed
+
+- README's substitution "Known limitation" note narrowed to `renderXcsFile` specifically — it
+  still can't decode an existing curved display's `style.curveX`/`curveY`, but the new building
+  API doesn't have that problem (the caller supplies the angle directly).
+
 ## [0.3.1] - 2026-08-17
 
 ### Changed

package/README.md

@@ -1,14 +1,19 @@
 # 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.
+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 (`.xs` generation isn't supported yet — see `CLAUDE.md`'s "Open Issues")
 
 ## Installation
 
@@ -45,6 +50,53 @@ 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
+import {
+  createXCS,
+  loadDefaultFont,
+  layoutGlyphText,
+  layoutCurvedGlyphText,
+} from '@richardmcquiston01/unofficial-xcs-writer';
+
+const font = loadDefaultFont();
+
+const project = createXCS('P2S')
+  // Straight text needs a real glyph layout so xTool Studio renders
+  // actual outlines instead of placeholder blocks.
+  .addText('Hello', 10, 10, {
+    fontFamily: 'Arial',
+    fontSize: 24,
+    layout: layoutGlyphText(font, 'Hello', 8, 10, 10),
+  })
+  // Curved text: same idea, via layoutCurvedGlyphText -- the curve
+  // is baked into each character's own glyph shape and position, the
+  // way substituted text already bakes straight shapes.
+  .addText('Arch Text', 0, 40, {
+    fontFamily: 'Arial',
+    fontSize: 18,
+    layout: layoutCurvedGlyphText(font, 'Arch Text', 6, 90, 60, 20, 'center'),
+  })
+  .addPath('M0 0L10 0L10 10L0 10Z', 0, 60, 10, 10)
+  .toBytes(); // Uint8Array, ready to write to a .xcs file
+```
+
 ## API
 
 ### `assertXcsFormat(buffer: ArrayBuffer): void`
@@ -74,7 +126,7 @@ 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:** only straight horizontal-baseline layout is reproduced. xTool Studio's `style.curveX`/`curveY` curved-text layout formula is undocumented and isn't replicated — substituted text on a curved TEXT display gets correctly-shaped glyphs laid out on a straight line instead of the original curve.
+**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`
 
@@ -85,9 +137,46 @@ 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 `renderXcsFile` is built on, exported for direct use (e.g. building a `TEXT` display from scratch). See `src/glyphs.ts` for the exact xTool JSON conventions these were reverse-engineered against.
+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). |
+
+Then `.generate()` (the plain `XCSFile` object), `.toJSON()` (string), or `.toBytes()` (`Uint8Array`, matching `renderXcsFile`'s output type).
+
+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.
 
 ## Development
 
@@ -119,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