@richardmcquiston01/unofficial-xcs-writer 0.2.0 → 0.3.1

package/CHANGELOG.md

@@ -0,0 +1,66 @@
+# Changelog
+
+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.3.1] - 2026-08-17
+
+### Changed
+
+- Replaced the ad-hoc PayPal "Support" section in the README with the standard
+  "Buy Me a Coffee" donation block (Stripe link plus a scannable QR code at
+  `donate.svg`), now the last section of the README.
+- `donate.svg` is included in the published tarball so the README's QR image
+  resolves for consumers reading it from the package.
+
+## [0.3.0] - 2026-07-14
+
+### Added
+
+- Root `LICENSE` file (MIT) — previously declared in `package.json` but not shipped.
+- `prepublishOnly` script that rebuilds and runs the test suite before every
+  `npm publish`, preventing stale-`dist/` releases.
+- This changelog.
+
+### Fixed
+
+- Republished the glyph outline extraction feature with a correct build. The
+  0.2.0 tarball on npm was packed from a stale `dist/` and does not actually
+  contain the glyph regeneration code its README describes — use 0.3.0 instead.
+
+## [0.2.0] - 2026-07-14
+
+> **Warning:** the npm tarball for this version was built from a stale `dist/`
+> and lacks the glyph extraction feature listed below. Use 0.3.0 or later.
+
+### Added
+
+- Real per-character glyph outline extraction (`src/glyphs.ts`, powered by
+  [opentype.js](https://github.com/opentypejs/opentype.js)). When
+  `renderXcsFile` changes a TEXT display's text, its `charJSONs` /
+  `fontData.glyphData` are regenerated with real glyph outlines so xTool
+  Studio renders the substituted text correctly.
+- Optional `fonts` parameter on `renderXcsFile` to supply real font bytes
+  (TTF/OTF/WOFF) keyed by `style.fontFamily`.
+- Bundled fallback font: Arimo v5.2.8 (Apache-2.0, metric-compatible with
+  Arial) for families not supplied via `fonts`.
+- Lower-level glyph primitives exported for direct use: `loadFont`,
+  `loadDefaultFont`, `layoutText`.
+
+### Known limitations
+
+- Curved-text layout (`style.curveX`/`curveY`) is not reproduced —
+  substituted text on a curved TEXT display gets correctly-shaped glyphs laid
+  out on a straight baseline.
+
+## [0.1.0] - 2026-05-19
+
+### Added
+
+- Initial release: read, validate, and apply `{{token}}` variable
+  substitution to xTool Creative Space `.xcs` files.
+- Core API: `assertXcsFormat`, `readXcsFile`, `extractXcsTokens`,
+  `renderXcsFile`, and the `XcsVariable` type.
+- Dual ESM + CJS build with TypeScript declarations via tsup.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Richard McQuiston
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,119 +1,135 @@
-# 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.
-
-## Support
-
-If this library saved you some reverse-engineering, consider [buying me a coffee](https://www.paypal.com/ncp/payment/VDTESHTRR7684). ☕
-
-## 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, fonts?): 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.
-
-Whenever a display's text actually changes, its glyph outline data (`charJSONs` / `fontData.glyphData`) is regenerated from a real font so xTool Studio renders the new text correctly — xTool Studio only trusts a TEXT display's stored glyph shapes; it does not re-shape text on its own unless you manually reselect the font inside the app. Displays whose text doesn't change are left completely untouched.
-
-Pass `fonts` to supply real font file bytes (TTF/OTF/WOFF) keyed by a display's `style.fontFamily`:
-
-```ts
-const arialBuffer = await fetch('/fonts/arial.ttf').then(r => r.arrayBuffer());
-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.
-
-### `XcsVariable`
-
-```ts
-interface XcsVariable {
-  token: string;        // token name without braces, e.g. "LastName"
-  defaultValue?: string;
-}
-```
-
-### `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.
-
-## 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. (`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.
-- 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`).
+# 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, fonts?): 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.
+
+Whenever a display's text actually changes, its glyph outline data (`charJSONs` / `fontData.glyphData`) is regenerated from a real font so xTool Studio renders the new text correctly — xTool Studio only trusts a TEXT display's stored glyph shapes; it does not re-shape text on its own unless you manually reselect the font inside the app. Displays whose text doesn't change are left completely untouched.
+
+Pass `fonts` to supply real font file bytes (TTF/OTF/WOFF) keyed by a display's `style.fontFamily`:
+
+```ts
+const arialBuffer = await fetch('/fonts/arial.ttf').then(r => r.arrayBuffer());
+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.
+
+### `XcsVariable`
+
+```ts
+interface XcsVariable {
+  token: string;        // token name without braces, e.g. "LastName"
+  defaultValue?: string;
+}
+```
+
+### `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.
+
+## 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 |
+
+### Releasing
+
+Publishing to npm is automated. Bump the version in `package.json`, add a
+`CHANGELOG.md` entry, then create a GitHub release tagged `vX.Y.Z` — the
+[publish workflow](.github/workflows/publish.yml) checks the tag against
+`package.json`, rebuilds, runs the tests, and publishes with provenance.
+It needs an `NPM_TOKEN` repository secret with publish rights.
+
+## Notes
+
+- 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.
+- 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
+
+[MIT](LICENSE). The bundled Arimo fallback font is separately licensed under Apache-2.0 (`third_party/arimo/LICENSE`).
+
+## Buy Me a Coffee
+
+If this app, code, or repository has helped you or someone you know, please consider donating. I appreciate any help to offset the costs of development and/or AI Credits.
+
+[**Donate via Stripe**](https://donate.stripe.com/00w5kD3Gj1Xo9v7gVOcs800), or scan:
+
+[![Donate via Stripe](./donate.svg)](https://donate.stripe.com/00w5kD3Gj1Xo9v7gVOcs800)