v1.0.5 — base-unit convenience fields across all output methods

toRawDict(), toDict(), pretty() and describe() now expose canonical
base-unit fields so callers never need to handle unit conversion:
  weight  mg/g/kg    → measure_gr / measure_available_gr
  volume  ml/cl/L/m³ → measure_ml / measure_available_ml
  size    mm/cm/m    → measure_mm / measure_available_mm
  area    m²         → measure_mm2 / measure_available_mm2

Already-canonical units (g / ml / mm) produce no redundant field.
pretty() shows "(= 750 g)" inline; describe() appends
"— 750 g available, 1000 g total" to the Quantity sentence.
README and llms.txt updated accordingly.

Author: BenGlut

CHANGELOG.md

@@ -12,11 +12,13 @@ Format based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
   - **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 `measure_gr` / `measure_available_gr` (or `_ml` for liquids)
-  immediately after `measure_available`. Developers can read a single field in grams (or ml)
-  without caring about the unit stored on the chip.
+- `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
 

README.md

@@ -261,8 +261,13 @@ 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)
 tag.toBytes(includeSignature = false)  // → Buffer   re-serialize to chip bytes
 tag.validate()                         // → string[] sanity check — list of warnings
 tag.verify(db)                         // → SignatureResult

llms.txt

@@ -203,13 +203,21 @@ TigerTag.fromCloudDoc(doc, db?)
 
 tag.toBytes(includeSignature=false)     → Buffer(80 or 144)
 tag.toDict(db?)                         → resolved object (IDs → labels + metadata)
-tag.toRawDict()                         → raw protocol fields
+                                          .measure block always includes canonical base-unit fields:
+                                          measure_gr/measure_available_gr (weight), measure_ml/measure_available_ml
+                                          (volume), measure_mm/measure_available_mm (size),
+                                          measure_mm2/measure_available_mm2 (area).
+                                          Already-canonical units (g/ml/mm) produce no duplicate field.
+tag.toRawDict()                         → raw protocol fields (flat snake_case)
+                                          same base-unit convenience fields as toDict().measure (top-level).
 tag.patch({ ...fields })                → new TigerTag (immutable update, camelCase keys)
 tag.patchFromRawDict(raw)               → new TigerTag (immutable update, snake_case keys from toRawDict())
 tag.validate()                          → string[] warnings
 tag.verify(db?)                         → SignatureResult
 tag.pretty(db?, sigResult?)             → human-readable string
+                                          Quantity section: "1 kg (= 1000 g)" / "0.75 kg (= 750 g)  (75% remaining)"
 tag.describe(db?)                       → LLM-friendly natural language paragraph
+                                          Quantity sentence: "0.75 kg remaining out of 1 kg initial (75% — 750 g available, 1000 g total)"
 
 tag.rawApi(timeout=5000)                → Promise<object|null>
 tag.diffApi(apiData?, db?)              → Promise<ApiDiff[]>

src/tag.js

@@ -947,6 +947,24 @@ class TigerTag {
    *
    * @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 };
@@ -1384,10 +1402,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}.` : '.')),
       );
     }
 
@@ -1475,8 +1505,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`