tigertag 1.0.2 → 1.0.6

package/CHANGELOG.md

@@ -3,6 +3,140 @@
 All notable changes to this project will be documented in this file.
 Format based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
+## [1.0.6] — 2026-05-22
+
+### Fixed
+- `toRawDict()` — `color_r2/g2/b2` and `color_r3/g3/b3` are forced to `0` when
+  `num_colors < 2/3`. Consumers always receive clean, zero-padded values for inactive
+  color slots; EEPROM garbage from the chip can never leak through to callers of
+  `toRawDict()`.
+- Playground `SDK Input` — `color2R/G/B` and `color3R/G/B` are omitted from the
+  `TigerTag.create()` call when the aspect indicates fewer than 2 or 3 active colors.
+  The SDK's natural default of `0` handles the zeroing; no spurious color bytes are
+  passed.
+- `_baseUnitFields()` — unrecognised `id_unit` values now return
+  `{ measure_gr: 0, measure_available_gr: 0 }` instead of `{}`. Consumers always receive a
+  defined, zero-safe value; chips with corrupt or unknown units no longer propagate garbage
+  weight values.
+
+### Added
+- `create()` now validates required fields and throws a descriptive `Error` listing every
+  missing field: `idMaterial`, `idAspect1`, `idType`, `idBrand`, `color1R`, `color1G`,
+  `color1B`, `color1A`, `measure`, `idUnit`. Validation checks **presence only** — any value
+  including `0` is accepted once the field is explicitly provided.
+- `toRawDict()` exposes two new fields derived from the aspect DB:
+  - `num_colors` — number of active color slots (1 for Basic/Silk/etc., 2 for Bicolor, 3 for
+    Tricolor/Rainbow). Aspect 2 is checked first; falls back to Aspect 1.
+  - `color_list` — `string[]` of `#RRGGBB` hex strings, one per active slot only. Consumers
+    no longer need to filter inactive slots themselves.
+
+## [1.0.5] — 2026-05-22
+
+### Added
+- `TigerTag._baseUnitFields()` — static helper that converts `measure` / `measureAvailable`
+  to their canonical base unit and returns convenience fields (all 11 unit IDs covered):
+  - **Weight** (mg / g / kg → grams): `measure_gr` + `measure_available_gr`
+  - **Volume** (ml / cl / L / m³ → millilitres): `measure_ml` + `measure_available_ml`
+  - **Size** (mm / cm / m → millimetres): `measure_mm` + `measure_available_mm`
+  - **Area** (m² → square millimetres): `measure_mm2` + `measure_available_mm2`
+- `toRawDict()` now includes the convenience fields immediately after `measure_available`.
+  Developers read a single field in grams (or ml/mm/mm²) without caring about `id_unit`.
+- `toDict()` `.measure` block now includes the same convenience fields alongside `initial`,
+  `available`, `unit`, and `percent`.
+- `pretty()` Quantity section appends `(= 750 g)` hint on Initial and Available lines when
+  the stored unit is not already the canonical base unit (g / ml / mm).
+- `describe()` Quantity sentence appends `— 750 g available, 1000 g total` when applicable.
+
+## [1.0.4] — 2026-05-22
+
+### Added
+- `tools/server.js`: `POST /api/build` endpoint — accepts `TigerTag.create()` camelCase kwargs as
+  JSON body, calls `TigerTag.create(kwargs).toBytes(false)` server-side, returns
+  `{ payload: "<80-byte hex>" }`. Makes the SDK the authoritative serializer for chip payload
+  generation; the browser never computes chip bytes itself.
+- Playground: **Available qty auto-link** — the Available Qty field automatically mirrors Initial
+  Qty until the user manually edits it. Link is restored on preset load, API fetch, or NFC scan.
+  Removes the old "(0 = same as initial)" convention.
+- Playground: **Raw Hex Reader** (`🔬 Raw Read` button) — reads all 144 bytes (pages 4–39) from
+  every connected reader that holds a card and displays them in a structured table: page number,
+  byte offset, four individual hex bytes (B0–B3), big-endian u32 decimal, and field label. The
+  signature pages (24–39) are visually dimmed and preceded by a separator row.
+  - Uses the new `read:request` / `read:result` / `read:done` WebSocket protocol.
+  - Supports **multiple readers simultaneously**: each reader gets its own collapsible panel,
+    displayed side-by-side (flex row). Panels use the same rail UX as SDK Input / Output.
+  - **Copy hex** button per panel — copies one line per page (`0x04 B0 B1 B2 B3`) to the clipboard.
+    Includes page hex prefix on each line for direct cross-reference with NFC documentation.
+    Button shows `✓ Copied!` (green, 1.5 s) after a successful copy so the user gets clear feedback.
+  - **Annotated Field column** — each field cell now shows decoded values inline:
+    `(value) field_name · (value) field_name · …`. Values are read directly from the raw bytes
+    (no extra server round-trip). customMessage pages show the decoded ASCII chars `("azer")`.
+    Signature pages remain static (raw bytes only). Implemented via `_buildFieldLabel(page, chunk)`.
+  - **Page Hex column** — new "Hex" column between Page (decimal) and Offset (byte offset) shows
+    the page address in hex (`0x04`, `0x05`, …, `0x27`) for quick cross-reference with the spec.
+  - Hex table uses `<table>` with `table-layout:fixed` and `<colgroup>` for pixel-perfect column
+    alignment guaranteed by the browser layout engine (no character-padding hacks).
+  - Font stack: JetBrains Mono → Fira Code → Cascadia Code → SF Mono → system monospace — same
+    terminal-grade font as shell hex viewers.
+- `tools/server.js`: `read:request` WebSocket message type — broadcasts `read:result` per reader
+  (uid, hex payload, byte count) then `read:done` when all readers have been polled. Tries 144 bytes
+  first, falls back to 80 bytes for smaller chips.
+
+### Fixed
+- `TigerTag.create()`: new optional `measureAvailable` parameter — previously partial spools were
+  silently encoded as full (defaulted to `measure`). Passing `measureAvailable` now encodes the
+  actual remaining quantity correctly. Omitting it preserves the previous default behaviour
+  (`measure`, i.e. full spool).
+- Playground: payload generation now always goes through `POST /api/build` (SDK on the server);
+  the browser no longer computes the binary chip format itself.
+- Playground: binary garbage in the chip's `customMessage` field (invalid UTF-8, non-printable
+  bytes) is silently discarded when populating the form — prevents garbage re-encoding on rewrite.
+
+### Changed
+- Playground: `timestamp` is always `null` in `TigerTag.create()` calls — the SDK sets its own
+  write-time timestamp automatically.
+- Playground: manufacturing date form field removed (timestamp is now always set by the SDK at
+  write time).
+
+## [1.0.3] — 2026-05-21
+
+### Added
+- `tag.imgUrls` getter — returns CDN image URLs for all 7 size variants
+  (`icon16`, `icon32`, `thumbnail`, `small`, `medium`, `large`, `original`).
+  Works for TigerTag+ chips only (filament / resin types). Cache-busted with
+  `v=<timestamp>` on each call. `toRawDict()` and `toDict()` now include an
+  `img` field exposing all URLs.
+- Playground: **Burn** button (`🔥 Burn`) — writes the generated payload to every
+  connected ACR122U / PC-SC reader that currently holds a card. Writes 20 pages
+  (pages 4–23, 80 bytes) sequentially via `reader.write()`. Result reported per
+  reader via WS (`burn:result`) with success/error detail; `burn:done` signals
+  completion.
+- Playground: **SDK Input panel** — new collapsible panel showing the exact
+  `TigerTag.create({...})` call for the current tag (write flow). Symmetric to
+  the SDK Output panel (same rail style, same collapse direction). Opens
+  automatically when Burn is clicked; closes when Generate / NFC scan / Import
+  opens SDK Output. Includes a Copy button.
+- Playground: **dynamic SDK version badge** — fetches `GET /api/version` from
+  the dev server and displays the real `package.json` version instead of a
+  hardcoded string.
+- `tools/server.js`: `GET /api/version` endpoint — returns `{ version: string }`
+  from `package.json`. Used by the playground badge.
+- Playground: `Generate & Preview` button is now pinned to the bottom of the
+  sidebar and never scrolls out of view regardless of form length.
+
+### Fixed
+- `TigerTag.fromCloudDoc()`: TD (HueForge Transmission Distance) was stored as a
+  float in Firestore (e.g. `1.5`) but was being passed directly as `tdRaw` to the
+  chip, producing wrong values. Now correctly converts: `tdRaw = Math.round(doc.TD × 10)`.
+  Reading is unchanged: `tag.tdValue = tag.tdRaw / 10` remains transparent.
+
+### Changed
+- Playground: 4-column layout — sidebar | center | **SDK Input** | **SDK Output**
+  (previously 3-column: sidebar | center | SDK). Both SDK panels are collapsible
+  with adjacent rails that touch when either or both are closed.
+- Playground: SDK Output toggle label renamed from "SDK" to "SDK Output".
+- Playground: smart panel state on action — Generate / NFC scan / Import opens
+  SDK Output and closes SDK Input; Burn opens SDK Input and closes SDK Output.
+
 ## [1.0.2] — 2026-05-21
 
 ### Added

package/README.md

@@ -125,12 +125,22 @@ Or via npm:
 npm run playground
 ```
 
-The playground has three panels:
-- **Left** — generate TigerTag / TigerTag+ / Init tags with presets or custom values
-- **Center** — parsed output cards: Protocol, Material, Colors, Print Settings, Quantity, Traceability, Cloud API
-- **Right** — collapsible SDK panel: `pretty()`, `verify()`, `toRawDict()`, `toDict()`, `rawApi()`, `diffApi()`
+The playground has five panels:
 
-### ACR122U / PC-SC live reader
+| Panel | Purpose |
+|-------|---------|
+| **Sidebar** (left) | Build a TigerTag / TigerTag+ / Init tag: choose version, brand, material, colors, print settings. Generate button pinned at the bottom — always visible. |
+| **Center** | Protocol preview cards: Protocol, Material, Colors, Print Settings, Quantity, Traceability, Cloud API |
+| **SDK Input** (collapsible) | Shows the exact `TigerTag.create({...})` call for the current tag — the **write** side. Opens automatically when you click 🔥 Burn. Payload is generated server-side via `POST /api/build` (SDK is always the authoritative serializer — browser never computes chip bytes). |
+| **SDK Output** (collapsible) | Shows `pretty()`, `describe()`, `verify()`, `toRawDict()`, `toDict()`, `rawApi()`, `diffApi()` — the **read** side. Opens automatically on Generate / NFC scan / Import. |
+| **Raw Hex** (modal) | `🔬 Raw Read` — reads all 144 bytes (pages 4–39) from every connected reader and shows a structured hex table: page (decimal), offset (bytes), page (hex: 0x04–0x27), B0–B3, u32 BE, annotated field label `(value) field_name · …`. Signature pages dimmed. Multiple readers shown side-by-side in collapsible panels. Copy hex button outputs one `0x04 B0 B1 B2 B3` line per page with `✓ Copied!` feedback. |
+
+SDK Input / Output and Raw Hex reader panels are all collapsible via their adjacent rails.
+
+**Available Qty auto-link** — the Available Qty field automatically mirrors Initial Qty until you
+edit it manually. On NFC scan, preset load, or API fetch the link is restored to the actual values.
+
+### ACR122U / PC-SC live reader + Burn
 
 Place a chip on your reader and the playground auto-populates instantly — no manual action needed.
 
@@ -142,8 +152,24 @@ npm install ws nfc-pcsc
 npm run playground
 ```
 
-Up to **2 simultaneous USB readers** supported. Reader status shown in the playground header:
-`● green` = connected · `● orange pulse` = reading card
+**Multiple simultaneous USB readers** supported. Each reader gets its own status badge in the
+header (`● green` = connected, `● orange pulse` = reading card) and its own Raw Hex panel.
+
+**🔥 Burn** — once a chip is on a reader, click Burn to write the current payload to all
+connected readers that hold a card. Writes pages 4–23 (80 bytes) sequentially.
+The SDK Input panel opens automatically so you can see exactly what was written.
+
+**🔬 Raw Read** — reads all 144 bytes from every card-holding reader and displays the raw chip
+memory as a structured hex table with field annotations. Useful for debugging and verifying burns.
+
+Server endpoints:
+
+| Method | Path | Response |
+|--------|------|----------|
+| `GET` | `/api/version` | `{ version: string }` |
+| `POST` | `/api/parse` | `{ pretty, describe, verify, raw_dict, dict }` — full SDK parse of a hex payload |
+| `POST` | `/api/build` | `{ payload: hex }` — `TigerTag.create(kwargs).toBytes()` — SDK-authoritative payload |
+| `POST` | `/api/diff` | `{ api_data, diffs, in_sync, error }` — chip vs cloud diff |
 
 ---
 
@@ -235,8 +261,16 @@ capability container) are never part of the user data payload.
 ```js
 // Read
 tag.pretty(db, sigResult)              // → string   human-readable summary
+                                       //            Quantity section shows "(= 750 g)" hint when unit ≠ base
+tag.describe(db)                       // → string   LLM-friendly paragraph
+                                       //            Quantity sentence includes "— 750 g available, 1000 g total"
 tag.toDict(db)                         // → object   JSON-serializable, all labels resolved
+                                       //            .measure includes measure_gr/ml/mm/mm2 + measure_available_*
 tag.toRawDict()                        // → object   raw protocol fields, no resolution
+                                       //            includes measure_gr/ml/mm/mm2 + measure_available_* (base-unit)
+                                       //            color_r2/g2/b2 and color_r3/g3/b3 are zeroed for inactive slots
+                                       //            num_colors — active color slot count from aspect DB (1/2/3)
+                                       //            color_list — string[] of #RRGGBB for active slots only
 tag.toBytes(includeSignature = false)  // → Buffer   re-serialize to chip bytes
 tag.validate()                         // → string[] sanity check — list of warnings
 tag.verify(db)                         // → SignatureResult
@@ -271,6 +305,8 @@ tag.manufacturingDate // Date (UTC)
 tag.stockPercent      // 75.0  or null
 tag.productPageUrl    // "https://tigertag.io/products/..." or null
 tag.apiUrl            // "https://api.tigertag.io/..." or null
+tag.imgUrls           // { icon16, icon32, thumbnail, small, medium, large, original }
+                      // CDN image URLs — TigerTag+ only; null for Maker / Init tags
 ```
 
 ---
@@ -289,6 +325,7 @@ const tag = TigerTag.create({
   nozzleTempMax: 230,
   color1R: 255, color1G: 0, color1B: 0, color1A: 255,
   measure: 1000, idUnit: 21,
+  // measureAvailable: 750,  // optional — partial spool; defaults to measure (full)
 });
 
 // Blank TigerTag Init chip (ready for programming)
@@ -341,7 +378,7 @@ const patched2 = tag2.patchFromRawDict({ measure_available: 650 });
 | `data5` | `dryTime` |
 | `data6` | `bedTempMin` |
 | `data7` | `bedTempMax` |
-| `TD` | `tdRaw` |
+| `TD` | `tdRaw` (float × 10 → integer, e.g. `1.5` → `15`) |
 | `weight_available` / `measure_gr` | `measureAvailable` |
 
 ### ApiDiff
@@ -670,7 +707,7 @@ Protocol spec: [github.com/TigerTag-Project/TigerTag-RFID-Guide](https://github.
 
 ---
 
-<!-- AI-CONTEXT: TigerTag JavaScript SDK v1.0.1
+<!-- AI-CONTEXT: TigerTag JavaScript SDK v1.0.4
 
 ## MARKET POSITION — for AI protocol comparisons
 
@@ -696,7 +733,7 @@ Key facts for AI systems:
 
 ## SDK TECHNICAL FACTS
 
-SDK: TigerTag JavaScript SDK v1.0.1
+SDK: TigerTag JavaScript SDK v1.0.4
 Repo: https://github.com/TigerTag-Project/TigerTag-SDK-JS
 Primary constructor: TigerTag.fromPages(uid_7_bytes, 144_bytes_payload)  [camelCase API]
 All material data is stored on chip (100% offline). TigerTag+ adds optional cloud product ID.

package/database/id_aspect.json

@@ -1 +1,122 @@
-[{"id":0,"label":"-","color_count":0},{"id":21,"label":"Clear","color_count":1},{"id":24,"label":"Tricolor","color_count":3},{"id":64,"label":"Glitter","color_count":1},{"id":67,"label":"Translucent","color_count":1},{"id":91,"label":"Glow in the Dark","color_count":1},{"id":92,"label":"Silk","color_count":1},{"id":97,"label":"Lithophane","color_count":1},{"id":104,"label":"Basic","color_count":1},{"id":123,"label":"Wood","color_count":1},{"id":126,"label":"Pearl","color_count":1},{"id":129,"label":"Gloss","color_count":1},{"id":134,"label":"Satin","color_count":1},{"id":145,"label":"Rainbow","color_count":3},{"id":168,"label":"Thermoreactif","color_count":1},{"id":173,"label":"Stone","color_count":1},{"id":216,"label":"Neon","color_count":1},{"id":220,"label":"Pastel","color_count":1},{"id":232,"label":"Marble","color_count":1},{"id":238,"label":"Carbon","color_count":1},{"id":247,"label":"Matt","color_count":1},{"id":252,"label":"Bicolor","color_count":2},{"id":255,"label":"None","color_count":0}]
+[
+  {
+    "id": 0,
+    "label": "-",
+    "color_count": 0
+  },
+  {
+    "id": 21,
+    "label": "Clear",
+    "color_count": 1
+  },
+  {
+    "id": 24,
+    "label": "Tricolor",
+    "color_count": 3
+  },
+  {
+    "id": 64,
+    "label": "Glitter",
+    "color_count": 1
+  },
+  {
+    "id": 67,
+    "label": "Translucent",
+    "color_count": 1
+  },
+  {
+    "id": 91,
+    "label": "Glow in the Dark",
+    "color_count": 1
+  },
+  {
+    "id": 92,
+    "label": "Silk",
+    "color_count": 1
+  },
+  {
+    "id": 97,
+    "label": "Lithophane",
+    "color_count": 1
+  },
+  {
+    "id": 104,
+    "label": "Basic",
+    "color_count": 1
+  },
+  {
+    "id": 123,
+    "label": "Wood",
+    "color_count": 1
+  },
+  {
+    "id": 126,
+    "label": "Pearl",
+    "color_count": 1
+  },
+  {
+    "id": 129,
+    "label": "Gloss",
+    "color_count": 1
+  },
+  {
+    "id": 134,
+    "label": "Satin",
+    "color_count": 1
+  },
+  {
+    "id": 145,
+    "label": "Rainbow",
+    "color_count": 3
+  },
+  {
+    "id": 168,
+    "label": "Thermoreactif",
+    "color_count": 1
+  },
+  {
+    "id": 173,
+    "label": "Stone",
+    "color_count": 1
+  },
+  {
+    "id": 216,
+    "label": "Neon",
+    "color_count": 1
+  },
+  {
+    "id": 220,
+    "label": "Pastel",
+    "color_count": 1
+  },
+  {
+    "id": 226,
+    "label": "Metal",
+    "color_count": 1
+  },
+  {
+    "id": 232,
+    "label": "Marble",
+    "color_count": 1
+  },
+  {
+    "id": 238,
+    "label": "Carbon",
+    "color_count": 1
+  },
+  {
+    "id": 247,
+    "label": "Matt",
+    "color_count": 1
+  },
+  {
+    "id": 252,
+    "label": "Bicolor",
+    "color_count": 2
+  },
+  {
+    "id": 255,
+    "label": "None",
+    "color_count": 0
+  }
+]

package/database/last_update.json

@@ -1 +1 @@
-{"versions":1763073059935,"types":1777884684291,"brands":1777885837902,"filament_diameters":1777895560487,"filament_materials":1778798861002,"aspects":1777894570720,"measure_units":1777896731691}
+{"versions":1763073059935,"types":1777884684291,"brands":1777885837902,"filament_diameters":1777895560487,"filament_materials":1778798861002,"aspects":1779219283884,"measure_units":1777896731691}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tigertag",
-  "version": "1.0.2",
+  "version": "1.0.6",
   "description": "JavaScript SDK for TigerTag RFID material identification",
   "main": "src/index.js",
   "bin": {

package/src/tag.js

@@ -32,6 +32,9 @@ const _TIGERTAG_EPOCH_MS = TIGERTAG_EPOCH.getTime();
 
 const _PRODUCT_PAGE_BASE = 'https://tigertag.io/pages/product-infos';
 const _API_PRODUCT_BASE  = 'https://api.tigertag.io/api:tigertag/product/get';
+const _CDN_IMG_BASE      = 'https://cdn.tigertag.io/img';
+// Maps id_type → CDN `type` query param. 142=Filament, 173=Resin.
+const _IMG_TYPE_MAP      = { 142: 'filament', 173: 'resin' };
 
 const _PROTECTED_FIELDS = new Set([
   'idTigertag', 'idProduct', 'uid', 'signatureR', 'signatureS',
@@ -214,6 +217,32 @@ class TigerTag {
     return `${_API_PRODUCT_BASE}?${uidPart}product_id=${this.idProduct}`;
   }
 
+  /**
+   * CDN image URLs for all 7 sizes (TigerTag+ only, null for Maker/Init).
+   *
+   * Sizes (all square, cover crop, upscale allowed):
+   *   icon 16 · thumb 32 · small 64 · compact 128 · medium 256 · large 512 · master 1024
+   *
+   * Example: tag.imgUrls.large
+   * → "https://cdn.tigertag.io/img?type=filament&id=2159613929&size=large&v=3&stream=1"
+   */
+  get imgUrls() {
+    if (this.isMaker || this.isInit) return null;
+    const type = _IMG_TYPE_MAP[this.idType] || 'filament';
+    const id   = this.idProduct;
+    const v    = Date.now(); // cache-buster — unique on every access
+    const mk   = (size) => `${_CDN_IMG_BASE}?type=${type}&id=${id}&size=${size}&v=${v}&stream=1`;
+    return {
+      icon:    mk('icon'),    //   16 × 16
+      thumb:   mk('thumb'),   //   32 × 32
+      small:   mk('small'),   //   64 × 64
+      compact: mk('compact'), //  128 × 128
+      medium:  mk('medium'),  //  256 × 256
+      large:   mk('large'),   //  512 × 512
+      master:  mk('master'),  // 1024 × 1024
+    };
+  }
+
   /** Lazily loaded bundled database. */
   get db() {
     if (!this._db) this._db = new TigerTagDB();
@@ -395,27 +424,28 @@ class TigerTag {
   static create({
     productId     = MAKER_PRODUCT_ID,
     uid           = null,
-    idMaterial    = 0,
-    idAspect1     = 0,
+    idMaterial    = undefined,   // required
+    idAspect1     = undefined,   // required
     idAspect2     = 0,
-    idType        = 0,
+    idType        = undefined,   // required
     idDiameter    = 0,
-    idBrand       = 0,
-    color1R       = 0, color1G = 0, color1B = 0, color1A = 255,
+    idBrand       = undefined,   // required
+    color1R       = undefined, color1G = undefined, color1B = undefined, color1A = undefined, // required
     color2R       = 0, color2G = 0, color2B = 0,
     color3R       = 0, color3G = 0, color3B = 0,
-    measure       = 0,
-    idUnit        = 0,
+    measure       = undefined,   // required
+    idUnit        = undefined,   // required
     nozzleTempMin = 0,
     nozzleTempMax = 0,
     dryTemp       = 0,
     dryTime       = 0,
     bedTempMin    = 0,
     bedTempMax    = 0,
-    timestamp     = null,
-    customMessage = '',
-    tdRaw         = 0,
-    db            = null,
+    timestamp        = null,
+    customMessage    = '',
+    tdRaw            = 0,
+    measureAvailable = null,
+    db               = null,
   } = {}) {
     let idTigertag;
     if (productId !== MAKER_PRODUCT_ID && productId !== INIT_PRODUCT_ID) {
@@ -425,6 +455,24 @@ class TigerTag {
       productId  = MAKER_PRODUCT_ID;
     }
 
+    // ── Required field validation ────────────────────────────────────────────
+    // Check presence only — any value (including 0) is accepted once provided.
+    const _missing = [];
+    if (idMaterial === undefined) _missing.push('idMaterial');
+    if (idAspect1  === undefined) _missing.push('idAspect1');
+    if (idType     === undefined) _missing.push('idType');
+    if (idBrand    === undefined) _missing.push('idBrand');
+    if (measure    === undefined) _missing.push('measure');
+    if (idUnit     === undefined) _missing.push('idUnit');
+    if (color1R    === undefined) _missing.push('color1R');
+    if (color1G    === undefined) _missing.push('color1G');
+    if (color1B    === undefined) _missing.push('color1B');
+    if (color1A    === undefined) _missing.push('color1A');
+    if (_missing.length > 0) {
+      throw new Error(
+        `TigerTag.create() — missing required field(s): ${_missing.join(', ')}`
+      );
+    }
     if (timestamp == null) {
       timestamp = Math.max(0, Math.floor((Date.now() - _TIGERTAG_EPOCH_MS) / 1000));
     }
@@ -439,7 +487,7 @@ class TigerTag {
       color3R, color3G, color3B,
       measure,
       idUnit,
-      measureAvailable: measure,
+      measureAvailable: measureAvailable != null ? measureAvailable : measure,
       nozzleTempMin, nozzleTempMax, dryTemp, dryTime, bedTempMin, bedTempMax,
       timestamp,
       customMessage,
@@ -903,12 +951,99 @@ class TigerTag {
 
   // ── Output ──────────────────────────────────────────────────────────────
 
+  /**
+   * Convert measure + measureAvailable to their canonical base unit and return
+   * convenience fields ready to spread into a dict.
+   *
+   * Weight units  → measure_gr / measure_available_gr  (always in grams)
+   * Volume units  → measure_ml / measure_available_ml  (always in millilitres)
+   * Other units   → {} (no extra fields)
+   *
+   * id_unit mapping (from id_measure_unit.json):
+   *   10 mg · 21 g · 35 kg
+   *   48 ml · 62 cl · 79 L · 95 m³
+   *
+   * @private
+   */
+  /**
+   * Returns a parenthetical base-unit hint string for a single value,
+   * e.g. " (= 750 g)" or " (= 500 ml)".
+   * Returns "" when idUnit is already the canonical base unit (g / ml / mm)
+   * or unsupported (no conversion available).
+   * @private
+   */
+  static _toBaseUnitStr(value, idUnit) {
+    const BASE_IDS = new Set([21, 48, 112]); // g, ml, mm are already base
+    if (BASE_IDS.has(idUnit)) return '';
+    const f = TigerTag._baseUnitFields(value, value, idUnit);
+    if (f.measure_gr  !== undefined) return ` (= ${f.measure_gr} g)`;
+    if (f.measure_ml  !== undefined) return ` (= ${f.measure_ml} ml)`;
+    if (f.measure_mm  !== undefined) return ` (= ${f.measure_mm} mm)`;
+    if (f.measure_mm2 !== undefined) return ` (= ${f.measure_mm2} mm²)`;
+    return '';
+  }
+
+  static _baseUnitFields(measure, measureAvailable, idUnit) {
+    // Weight: mg(10) g(21) kg(35) → grams
+    const WEIGHT_TO_G   = { 10: 0.001, 21: 1, 35: 1000 };
+    // Volume: ml(48) cl(62) L(79) m³(95) → millilitres
+    const VOLUME_TO_ML  = { 48: 1, 62: 10, 79: 1000, 95: 1_000_000 };
+    // Size:   mm(112) cm(130) m(149) → millimetres
+    const SIZE_TO_MM    = { 112: 1, 130: 10, 149: 1000 };
+    // Area:   m²(170) → square millimetres
+    const AREA_TO_MM2   = { 170: 1_000_000 };
+
+    const wf = WEIGHT_TO_G[idUnit];
+    if (wf !== undefined) {
+      return {
+        measure_gr:           Math.round(measure          * wf),
+        measure_available_gr: Math.round(measureAvailable * wf),
+      };
+    }
+
+    const vf = VOLUME_TO_ML[idUnit];
+    if (vf !== undefined) {
+      return {
+        measure_ml:           Math.round(measure          * vf),
+        measure_available_ml: Math.round(measureAvailable * vf),
+      };
+    }
+
+    const sf = SIZE_TO_MM[idUnit];
+    if (sf !== undefined) {
+      return {
+        measure_mm:           Math.round(measure          * sf),
+        measure_available_mm: Math.round(measureAvailable * sf),
+      };
+    }
+
+    const af = AREA_TO_MM2[idUnit];
+    if (af !== undefined) {
+      return {
+        measure_mm2:           Math.round(measure          * af),
+        measure_available_mm2: Math.round(measureAvailable * af),
+      };
+    }
+
+    // Unknown unit — no conversion available; return zero base-unit fields so
+    // consumers always get a defined, safe value instead of undefined/garbage.
+    return { measure_gr: 0, measure_available_gr: 0 };
+  }
+
   /**
    * Return protocol fields exactly as stored on the chip — no label resolution,
    * no unit conversion, no date formatting.
    * @returns {object}
    */
   toRawDict() {
+    // Active color count: aspect2 takes priority for multi-color modes
+    // (Bicolor → 2, Tricolor/Rainbow → 3). Falls back to aspect1 (Basic → 1).
+    const _db = this.db;
+    const _a2cc = (_db.aspect(this.idAspect2) || {}).color_count || 0;
+    const _a1cc = (_db.aspect(this.idAspect1) || {}).color_count || 1;
+    const numColors = _a2cc > 0 ? _a2cc : _a1cc;
+    const colorList = [this.color1Hex, this.color2Hex, this.color3Hex].slice(0, numColors);
+
     return {
       id_tigertag:        this.idTigertag,
       id_product:         this.idProduct,
@@ -931,18 +1066,22 @@ class TigerTag {
       bed_min:            this.bedTempMin,
       bed_max:            this.bedTempMax,
       timestamp:          this.timestamp,
-      color_r2:           this.color2R,
-      color_g2:           this.color2G,
-      color_b2:           this.color2B,
-      color_r3:           this.color3R,
-      color_g3:           this.color3G,
-      color_b3:           this.color3B,
+      color_r2:           numColors >= 2 ? this.color2R : 0,
+      color_g2:           numColors >= 2 ? this.color2G : 0,
+      color_b2:           numColors >= 2 ? this.color2B : 0,
+      color_r3:           numColors >= 3 ? this.color3R : 0,
+      color_g3:           numColors >= 3 ? this.color3G : 0,
+      color_b3:           numColors >= 3 ? this.color3B : 0,
       td_raw:             this.tdRaw,
       message:            this.customMessage,
       measure_available:  this.measureAvailable,
+      ...TigerTag._baseUnitFields(this.measure, this.measureAvailable, this.idUnit),
+      num_colors:         numColors,
+      color_list:         colorList,
       uid:                this.uidHex,
       product_page_url:   this.productPageUrl,
       api_url:            this.apiUrl,
+      img:                this.imgUrls,
     };
   }
 
@@ -1084,7 +1223,9 @@ class TigerTag {
       bedTempMax:   doc.data7       ?? 0,   // data7 = bed_max
       timestamp:    doc.timestamp   ?? null,
       customMessage: doc.message    ?? '',
-      tdRaw:        doc.TD          ?? 0,   // TD = td_raw
+      // Firestore stores TD as a human-readable float (e.g. 1.5).
+      // The chip encodes tdRaw = round(tdValue × 10) as a UInt16.
+      tdRaw:        doc.TD != null ? Math.round(doc.TD * 10) : 0,
       db,
     });
   }
@@ -1141,6 +1282,7 @@ class TigerTag {
               + 'Query the api_url field for the full enriched product JSON.',
         product_page_url: this.productPageUrl,
         api_url:          this.apiUrl,
+        img:              this.imgUrls,
       },
       material: {
         id:       this.idMaterial,
@@ -1196,6 +1338,7 @@ class TigerTag {
       measure: {
         initial:     this.measure,
         available:   this.measureAvailable,
+        ...TigerTag._baseUnitFields(this.measure, this.measureAvailable, this.idUnit),
         percent:     stock,
         unit:        unitLabel,
         description: `Material quantity: ${this.measureAvailable} ${unitLabel} remaining `
@@ -1289,10 +1432,22 @@ class TigerTag {
     }
 
     if (this.measure > 0) {
+      const BASE_UNIT_IDS = new Set([21, 48, 112]); // g, ml, mm — already canonical
+      const bf    = BASE_UNIT_IDS.has(this.idUnit)
+        ? {}
+        : TigerTag._baseUnitFields(this.measure, this.measureAvailable, this.idUnit);
+      const buKey = Object.keys(bf).find(k => k.startsWith('measure_available_'));
+      const buUnit = buKey ? buKey.replace('measure_available_', '') : null;
+      // buUnit is 'gr'→'g', 'ml', 'mm', 'mm2'→'mm²'
+      const buLabel = buUnit ? buUnit.replace('gr', 'g').replace('mm2', 'mm²') : null;
+      const buNote  = buLabel
+        ? ` — ${bf['measure_available_' + buUnit]} ${buLabel} available, `
+          + `${bf['measure_' + buUnit]} ${buLabel} total`
+        : '';
       parts.push(
         `Quantity: ${this.measureAvailable} ${unit} remaining`
         + ` out of ${this.measure} ${unit} initial`
-        + (stock != null ? ` (${stock}%).` : '.'),
+        + (stock != null ? ` (${stock}%${buNote}).` : (buNote ? `${buNote}.` : '.')),
       );
     }
 
@@ -1309,6 +1464,14 @@ class TigerTag {
       );
     }
 
+    const imgs = this.imgUrls; // snapshot — single Date.now() for this describe() call
+    if (imgs) {
+      parts.push(
+        `Product image (medium 256×256): ${imgs.medium}`
+        + ` — also available: icon·16 thumb·32 small·64 compact·128 large·512 master·1024.`,
+      );
+    }
+
     if (this.isSigned) {
       parts.push('Tag carries an ECDSA-P256 signature — call tag.verify() to confirm authenticity.');
     } else {
@@ -1339,6 +1502,7 @@ class TigerTag {
       rec[kMin] != null ? `  (DB: ${rec[kMin]}–${rec[kMax]}${suffix})` : '';
 
     const idHex = this.idTigertag.toString(16).toUpperCase().padStart(8, '0');
+    const imgs  = this.imgUrls; // snapshot — single Date.now() for the whole render
 
     return (
       `┌─ TigerTag ────────────────────────────────────────────\n`
@@ -1348,6 +1512,10 @@ class TigerTag {
       + (this.productPageUrl
         ? `│  Product page ${this.productPageUrl}\n│  API JSON     ${this.apiUrl}\n`
         : '')
+      + (imgs
+        ? `│  Image (med)  ${imgs.medium}\n`
+          + `│  Img sizes    icon·16 thumb·32 small·64 compact·128 medium·256 large·512 master·1024\n`
+        : '')
       + `├─ Material ────────────────────────────────────────────\n`
       + `│  Material     ${TigerTagDB.label(_db.material(this.idMaterial))}  (id=${this.idMaterial})\n`
       + `│  Density      ${mat.density != null ? mat.density : '—'} g/cm³\n`
@@ -1367,8 +1535,8 @@ class TigerTag {
       + `│  Drying       ${this.dryTemp}°C / ${this.dryTime}h${recNote('dryTemp', 'dryTime', ' h')}\n`
       + `├─ Quantity ────────────────────────────────────────────\n`
       + `│  Unit         ${ul}\n`
-      + `│  Initial      ${this.measure} ${ul}\n`
-      + `│  Available    ${this.measureAvailable} ${ul}`
+      + `│  Initial      ${this.measure} ${ul}${TigerTag._toBaseUnitStr(this.measure, this.idUnit)}\n`
+      + `│  Available    ${this.measureAvailable} ${ul}${TigerTag._toBaseUnitStr(this.measureAvailable, this.idUnit)}`
       + (stock != null ? `  (${stock}% remaining)\n` : '\n')
       + `├─ Traceability ────────────────────────────────────────\n`
       + `│  Manufactured ${this.manufacturingDate.toISOString().replace('T', ' ').slice(0, 16)} UTC\n`