Debug/print flow

.changeset/sku-info-deci-mm.md

@@ -0,0 +1,21 @@
+---
+'@thermal-label/labelwriter-core': patch
+---
+
+Fix `ESC U` SKU geometry: the NFC tag reports deci-millimetres, not mm.
+
+`parseSkuInfo` read the label / marker / offset / liner geometry fields as
+whole millimetres, per the 550 reference table (`1...2^16 = length in mm`). An
+on-the-wire capture of an S0722540 (57×32 mm) roll disproves that — it reports
+571 / 317. All `*Mm` geometry fields are now converted from deci-mm, so
+`detectedMedia` reports 57.1 × 31.7 mm instead of 571 × 317. Counts
+(`totalLabelCount`, `counterMargin`) are left unscaled.
+
+The `MULTI_PURPOSE_MEDIUM` catalogue entry was stored transposed (32×57); it
+is corrected to 57×32 — `widthMm` is the across-head dimension and `heightMm`
+the feed length, matching the ESC U tag.
+
+`findMediaByDimensions` is now `@deprecated` — nothing maps `detectedMedia`
+onto a catalogue entry, and its exact dimension equality cannot match the
+deci-mm values `parseSkuInfo` now produces. Behaviour is unchanged; it is
+scheduled for removal in 0.7.0.

.github/workflows/release.yml

@@ -45,14 +45,32 @@ jobs:
           done
           echo "✅ All versions match tag $TAG"
 
+      - name: Determine release channel
+        id: channel
+        run: |
+          VERSION="${GITHUB_REF_NAME#v}"
+          if [[ "${{ github.event_name }}" == "push" && "$VERSION" == *-* ]]; then
+            # Prerelease tag (e.g. v0.6.3-debug.0): publish under the
+            # prerelease identifier as an npm dist-tag, never to `latest`.
+            NPM_TAG="${VERSION#*-}"
+            NPM_TAG="${NPM_TAG%%.*}"
+            echo "prerelease=true" >> "$GITHUB_OUTPUT"
+            echo "npm_tag=$NPM_TAG" >> "$GITHUB_OUTPUT"
+            echo "🔖 Prerelease $VERSION → npm dist-tag '$NPM_TAG'"
+          else
+            echo "prerelease=false" >> "$GITHUB_OUTPUT"
+            echo "npm_tag=latest" >> "$GITHUB_OUTPUT"
+            echo "🔖 Stable $VERSION → npm dist-tag 'latest'"
+          fi
+
       - name: Build
         run: pnpm build
 
       - name: Test
         run: pnpm test
 
       - name: Publish
-        run: pnpm publish -r --access public --no-git-checks --provenance
+        run: pnpm publish -r --access public --no-git-checks --provenance --tag ${{ steps.channel.outputs.npm_tag }}
         env:
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
 
@@ -61,4 +79,5 @@ jobs:
         uses: softprops/action-gh-release@v2
         with:
           generate_release_notes: true
-          make_latest: true
+          make_latest: ${{ steps.channel.outputs.prerelease == 'false' }}
+          prerelease: ${{ steps.channel.outputs.prerelease }}

DEBUG_RELEASE.md

@@ -0,0 +1,54 @@
+# Debug release — `0.6.3-debug.x`
+
+This branch (`debug/print-flow`) carries **temporary `console.debug` tracing
+through the print flow**. It exists only to publish an instrumented build to
+npm so a downstream CI can be debugged against a real package. It must never
+merge to `main`.
+
+## What's instrumented
+
+`console.debug` calls (one `dbg()` helper per package, grep-able) at the
+crucial print-flow points:
+
+- `packages/node/src/printer.ts` — `doPrint()`: start, 550 lock, media
+  resolved, rotation/bitmap, encoded bytes, write complete.
+- `packages/web/src/printer.ts` — same points in its `doPrint()`.
+- `packages/core/src/protocol.ts` — `encodeLabel()` entry + 450 byte count,
+  `encodeDuoTapeLabel()` entry.
+
+Log prefixes: `[lw-node]`, `[lw-web]`, `[lw-core]`.
+
+## How it reaches npm
+
+`.github/workflows/release.yml` on this branch detects a prerelease tag
+(a `-` in the version) and publishes under that identifier as an npm
+**dist-tag** instead of `latest` — so `latest` is untouched. This change
+lives only on this branch; `main`'s `release.yml` is unchanged.
+
+Publish:
+
+```sh
+git push origin debug/print-flow
+git tag v0.6.3-debug.0 && git push origin v0.6.3-debug.0
+```
+
+The Release workflow publishes all three packages at `0.6.3-debug.0` to the
+`debug` dist-tag.
+
+## How a consumer uses it
+
+```jsonc
+// CI / consumer package.json
+"@thermal-label/labelwriter-node": "debug"   // or pin "0.6.3-debug.0"
+```
+
+npm `^`/`~` ranges never resolve to a prerelease, and it is not on `latest`,
+so no other consumer picks it up by accident.
+
+## Teardown — there is no revert release
+
+1. Consumer drops the `@debug` pin, back to `^0.6.3` (or whatever stable).
+2. `npm dist-tag rm @thermal-label/labelwriter-core debug` (and `-node`, `-web`).
+3. Delete this branch.
+
+Iterating? Bump to `0.6.3-debug.1`, re-tag.